Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
BECTL(8)		FreeBSD	System Manager's Manual		      BECTL(8)

     bectl -- Utility to manage	boot environments on ZFS

     bectl activate [-t	| -T] beName
     bectl check
     bectl create [-r] [-e {nonActiveBe	| beName@snapshot}] newBeName
     bectl create [-r] beName@snapshot
     bectl destroy [-Fo] beName[@snapshot]
     bectl export sourceBe
     bectl import targetBe
     bectl jail	[-bU] [{-o key=value | -u key}]... beName
	   [utility [argument ...]]
     bectl list	[-aDHs]	[-c property] [-C property] [{-c property | -C
     bectl mount beName	[mountpoint]
     bectl rename origBeName newBeName
     bectl {ujail | unjail} {jailId | jailName | beName}
     bectl {umount | unmount} [-f] beName

     bectl [-h?]

     The bectl command is used to setup	and interact with ZFS boot environ-
     ments, which are bootable clones of datasets.

     Boot environments allow the system	to be upgraded,	while preserving the
     old system	environment in a separate ZFS dataset.

     The following commands are	supported by bectl:

     activate [-t | -T]	beName
	       Activate	the given beName as the	default	boot filesystem.  If
	       the -t flag is given, this takes	effect only for	the next boot.
	       Flag -T removes temporary boot once configuration.  Without
	       temporary configuration,	the next boot will use zfs dataset
	       specified in boot pool bootfs property.

     check     Performs	a silent sanity	check on the current system.  If boot
	       environments are	supported and used, bectl will exit with a
	       status code of 0.  Any other status code	is not currently de-
	       fined and may, in the future, grow special meaning for differ-
	       ent degrees of sanity check failures.

     create [-r] [-e {nonActiveBe | beName@snapshot}] newBeName
	       Create a	new boot environment named newBeName.

	       If the -r flag is given,	a recursive boot environment will be
	       made.  See Boot Environment Structures for a discussion on dif-
	       ferent layouts.

	       If the -e flag is specified, the	new environment	will be	cloned
	       from the	given nonActiveBe or beName@snapshot.  Otherwise, the
	       new environment will be created from the	currently booted envi-

	       If bectl	is creating from another boot environment, a snapshot
	       of that boot environment	will be	created	to clone from.

     create [-r] beName@snapshot
	       Create a	snapshot of the	boot environment named beName.

	       If the -r flag is given,	a recursive snapshot of	the boot envi-
	       ronment will be created.	 A snapshot is created for each	de-
	       scendant	dataset	of the boot environment.  See Boot Environment
	       Structures for a	discussion on different	layouts.

	       No new boot environment is created with this command.

     destroy [-Fo] beName[@snapshot]
	       Destroy the given beName	boot environment or beName@snapshot
	       snapshot	without	confirmation, unlike in	beadm(1).  Specifying
	       -F will automatically unmount without confirmation.

	       By default, bectl will warn that	it is not destroying the ori-
	       gin of beName.  The -o flag may be specified to destroy the
	       origin as well.

     export sourceBe
	       Export sourceBe to stdout(4).  stdout(4)	must be	piped or redi-
	       rected to a file.

     import targetBe
	       Import targetBe from stdin(4).

     jail [-bU]	[{-o key=value | -u key}]... beName [utility [argument ...]]
	       Create a	jail of	the given boot environment.  Multiple -o and
	       -u arguments may	be specified.  -o will set a jail parameter,
	       and -u will unset a jail	parameter.

	       By default, jails are created in	interactive mode and /bin/sh
	       is executed within the jail.  If	utility	is specified, it will
	       be executed instead of /bin/sh.	The jail will be destroyed and
	       the boot	environment unmounted when the command finishes	exe-
	       cuting, unless the -U argument is specified.

	       The -b argument enables batch mode, thereby disabling interac-
	       tive mode.  The -U argument will	be ignored in batch mode.

	       The name, host.hostname,	and path must be set, the default val-
	       ues are specified below.

	       All key=value pairs are interpreted as jail parameters as de-
	       scribed in jail(8).  The	following default parameters are pro-

	       allow.mount	    true
	       allow.mount.devfs    true
	       enforce_statfs	    1
	       name		    Set	to jail	ID.
	       host.hostname	    bootenv
	       path		    Set	to a path in /tmp generated by

	       All default parameters may be overwritten.

     list [-aDHs] [{-c property	| -C property}]

	       Display all boot	environments.  The Active field	indicates
	       whether the boot	environment is active now (N); active on re-
	       boot (R); is used on next boot once (T);	or combination of

	       -a      Display all datasets.

	       -D      Display the full	space usage for	each boot environment,
		       assuming	all other boot environments were destroyed.

	       -H      Used for	scripting.  Do not print headers and separate
		       fields by a single tab instead of arbitrary white

	       -s      Display all snapshots as	well.

	       -c property
		       Sort boot environments by given property	name.  The
		       following properties are	supported:

			     name (default output)

	       -C property
		       Same as the -c option, but displays in descending or-

	       The -D option is	ignored	when either the	-s or -a option	is

     mount beName [mountpoint]
	       Temporarily mount the boot environment.	Mount at the specified
	       mountpoint if provided.

     rename origBeName newBeName
	       Rename the given	origBeName to the given	newBeName.  The	boot
	       environment will	not be unmounted in order for this rename to

     ujail {jailId | jailName |	beName}

     unjail {jailId | jailName | beName}
	       Destroy the jail	created	from the given boot environment.

     umount [-f] beName

     unmount [-f] beName
	       Unmount the given boot environment, if it is mounted.  Specify-
	       ing -f will force the unmount if	busy.

     bectl prints usage	information if -h or -?	is specified.

   Boot	Environment Structures
     The traditional FreeBSD boot environment layout, as created by the	Auto
     ZFS option	to bsdinstall(8), is a "shallow" boot environment structure,
     where boot	environment datasets do	not have any directly subordinate
     datasets.	Instead, they're organized off in zroot/ROOT, and they rely on
     datasets elsewhere	in the pool having canmount set	to off.	 For instance,
     a simplified pool may be laid out as such:

	   % zfs list -o name,canmount,mountpoint
	   zroot/ROOT		   noauto	   none
	   zroot/ROOT/default	   noauto	   none
	   zroot/usr		   off		   /usr
	   zroot/usr/home	   on		   /usr/home
	   zroot/var		   on		   /var

     In	that example, zroot/usr	has canmount set to off, thus files in /usr
     typically fall into the boot environment because this dataset is not
     mounted.  zroot/usr/home is mounted, thus files in	/usr/home are not in
     the boot environment.

     The other style of	boot environments in use, frequently called "deep boot
     environments", organizes some or all of the boot environment as subordi-
     nate to the boot environment dataset.  For	example:

	   % zfs list -o name,canmount,mountpoint
	   zroot/ROOT			   noauto	   none
	   zroot/ROOT/default		   noauto	   none
	   zroot/ROOT/default/usr	   noauto	   /usr
	   zroot/ROOT/default/usr/local	   noauto	   /usr/local
	   zroot/var			   on		   /var

     Note that the subordinate datasets	now have canmount set to noauto.
     These are more obviously a	part of	the boot environment, as indicated by
     their positioning in the layout.  These subordinate datasets will be
     mounted by	the zfsbe rc(8)	script at boot time.  In this example, /var is
     excluded from the boot environment.

     bectl commands that have their own	-r operate on this second, "deep"
     style of boot environment,	when the -r flag is set.  A future version of
     bectl may default to handling both	styles and deprecate the various -r

     libbe(3),,	jail(8), zfs(8), zpool(8)

     bectl is based on beadm(1)	and was	implemented as a project for the 2017
     Summer of Code, along with	libbe(3).

     bectl was written by Kyle Kneitinger (kneitinger) <>.

     beadm(1) was written and is maintained by
     Slawomir Wojciech Wojtczak	(vermaden) <>.

     Bryan Drewery (bdrewery) <> wrote the original beadm(1)
     manual page that this one is derived from.

FreeBSD	13.0			March 31, 2022			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help