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

FreeBSD Manual Pages


home | help
BECTL(8)		  BSD 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

	       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.

	       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.

     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.

BSD				January	6, 2021				   BSD


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

home | help