xref: /freebsd/sbin/bectl/bectl.8 (revision 52c2bb75163559a6e2866ad374a7de67a4ea1273)
1.\"
2.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
3.\"
4.\" Copyright (c) 2017 Kyle J. Kneitinger <kyle@kneit.in>
5.\" All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\"
16.\"
17.\"     @(#)be.1
18.\"
19.\" $FreeBSD$
20.\"
21.Dd April 3, 2019
22.Dt BECTL 8
23.Os
24.Sh NAME
25.Nm bectl
26.Nd Utility to manage boot environments on ZFS
27.Sh SYNOPSIS
28.Nm
29.Cm activate
30.Op Fl t
31.Ar beName
32.Nm
33.Cm create
34.Op Fl r
35.Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot
36.Ar newBeName
37.Nm
38.Cm destroy
39.Op Fl \&Fo
40.Ar beName Ns Op Cm @ Ns Ar snapshot
41.Nm
42.Cm export
43.Ar sourceBe
44.Nm
45.Cm import
46.Ar targetBe
47.Nm
48.Cm jail
49.Op Fl bU
50.Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ...
51.Ar beName
52.Op Ar utility Op Ar argument ...
53.Nm
54.Cm list
55.Op Fl aDHs
56.Nm
57.Cm mount
58.Ar beName
59.Op Ar mountpoint
60.Nm
61.Cm rename
62.Ar origBeName
63.Ar newBeName
64.Nm
65.Brq Cm ujail | unjail
66.Brq Ar jailId | jailName
67.Ar beName
68.Nm
69.Brq Cm umount | unmount
70.Op Fl f
71.Ar beName
72.Pp
73.Nm
74.Op Fl h\&?
75.Sh DESCRIPTION
76The
77.Nm
78command is used to setup and interact with ZFS boot environments, which are
79bootable clones of datasets.
80.Pp
81Boot environments
82allow the system to be upgraded, while preserving the old system environment in
83a separate ZFS dataset.
84.Pp
85The following commands are supported by
86.Nm :
87.Bl -tag -width activate
88.It Xo
89.Cm activate
90.Op Fl t
91.Ar beName
92.Xc
93Activate the given
94.Ar beName
95as the default boot filesystem.
96If the
97.Op Fl t
98flag is given, this takes effect only for the next boot.
99.It Xo
100.Cm create
101.Op Fl r
102.Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot
103.Ar newBeName
104.Xc
105Create a new boot environment named
106.Ar newBeName .
107.Pp
108If the
109.Fl r
110flag is given, a recursive boot environment will be made.
111.Pp
112If the
113.Fl e
114flag is specified, the new environment will be cloned from the given
115.Ar nonActiveBe
116or
117.Ar beName Ns Cm @ Ns Ar snapshot .
118Otherwise, the new environment will be created from the currently booted environment.
119.Pp
120If
121.Nm
122is creating from another boot environment, a snapshot of that boot environment will be created to clone from.
123.It Xo
124.Cm destroy
125.Op Fl \&Fo
126.Ar beName Ns Op Cm @ Ns Ar snapshot
127.Xc
128Destroy the given
129.Ar beName
130boot environment or
131.Ar beName Ns Cm @ Ns Ar snapshot
132snapshot without confirmation, unlike in
133.Xr beadm 1 .
134Specifying
135.Fl F
136will automatically unmount without confirmation.
137.Pp
138By default,
139.Nm
140will warn that it is not destroying the origin of
141.Ar beName .
142The
143.Fl o
144flag may be specified to destroy the origin as well.
145.It Cm export Ar sourceBe
146Export
147.Ar sourceBe
148to
149.Xr stdout 4 .
150.Xr stdout 4
151must be piped or redirected to a file.
152.It Cm import Ar targetBe
153Import
154.Ar targetBe
155from
156.Xr stdin 4 .
157.It Xo
158.Cm jail
159.Op Fl bU
160.Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ...
161.Ar beName
162.Op Ar utility Op Ar argument ...
163.Xc
164Create a jail of the given boot environment.
165Multiple
166.Fl o
167and
168.Fl u
169arguments may be specified.
170.Fl o
171will set a jail parameter, and
172.Fl u
173will unset a jail parameter.
174.Pp
175By default, jails are created in interactive mode and
176.Pa /bin/sh
177is
178executed within the jail.
179If
180.Ar utility
181is specified, it will be executed instead of
182.Pa /bin/sh .
183The jail will be destroyed and the boot environment unmounted when the command
184finishes executing, unless the
185.Fl U
186argument is specified.
187.Pp
188The
189.Fl b
190argument enables batch mode, thereby disabling interactive mode.
191The
192.Fl U
193argument will be ignored in batch mode.
194.Pp
195The
196.Va name ,
197.Va host.hostname ,
198and
199.Va path
200must be set, the default values are specified below.
201.Pp
202All
203.Ar key Ns Cm = Ns Ar value
204pairs are interpreted as jail parameters as described in
205.Xr jail 8 .
206The following default parameters are provided:
207.Bl -column "allow.mount.devfs" ""
208.It Va allow.mount Ta Cm true
209.It Va allow.mount.devfs Ta Cm true
210.It Va enforce_statfs Ta Cm 1
211.It Va name Ta Set to jail ID.
212.It Va host.hostname Ta Va bootenv
213.It Va path Ta Set to a path in Pa /tmp
214generated by
215.Xr libbe 3 .
216.El
217.Pp
218All default parameters may be overwritten.
219.It Cm list Op Fl aDHs
220Display all boot environments.
221The
222.Em Active
223field indicates whether the boot environment is active now
224.Pq Em \&N ;
225active on reboot
226.Pq Em \&R ;
227or both
228.Pq Em \&NR .
229.Pp
230If
231.Fl a
232is used, display all datasets.
233If
234.Fl D
235is used, display the full space usage for each boot environment, assuming all
236other boot environments were destroyed.
237The
238.Fl H
239option is used for scripting.
240It does not print headers and separate fields by a single tab instead of
241arbitrary white space.
242If
243.Fl s
244is used, display all snapshots as well.
245.It Cm mount Ar beName Op Ar mountpoint
246Temporarily mount the boot environment.
247Mount at the specified
248.Ar mountpoint
249if provided.
250.It Cm rename Ar origBeName newBeName
251Rename the given
252.Ar origBeName
253to the given
254.Ar newBeName .
255The boot environment will not be unmounted in order for this rename to occur.
256.It Cm ujail Bro Ar jailId | jailName Brc Ar beName
257.It Cm unjail Bro Ar jailId | jailName Brc Ar beName
258Destroy the jail created from the given boot environment.
259.It Xo
260.Cm umount
261.Op Fl f
262.Ar beName
263.Xc
264.It Xo
265.Cm unmount
266.Op Fl f
267.Ar beName
268.Xc
269Unmount the given boot environment, if it is mounted.
270Specifying
271.Fl f
272will force the unmount if busy.
273.El
274.Pp
275.Nm
276prints usage information if
277.Fl h
278or
279.Fl \&?
280is specified.
281.Sh EXAMPLES
282.Bl -bullet
283.It
284To fill in with jail upgrade example when behavior is firm.
285.El
286.Sh SEE ALSO
287.Xr beinstall.sh 1 ,
288.Xr libbe 3 ,
289.Xr jail 8 ,
290.Xr zfs 8 ,
291.Xr zpool 8
292.Sh HISTORY
293.Nm
294is based on
295.Xr beadm 1
296and was implemented as a project for the 2017 Summer of Code, along with
297.Xr libbe 3 .
298.Sh AUTHORS
299.Nm
300was written by
301.An Kyle Kneitinger (kneitinger) Aq Mt kyle@kneit.in .
302.Pp
303.Xr beadm 1
304was written and is maintained by
305.An Slawomir Wojciech Wojtczak (vermaden) Aq Mt vermaden@interia.pl .
306.Pp
307.An Bryan Drewery (bdrewery) Aq Mt bryan@shatow.net
308wrote the original
309.Xr beadm 1
310manual page that this one is derived from.
311