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