JAILADM(8) FreeBSD System Manager's Manual JAILADM(8)
NAME
jailadm - administer jails
SYNOPSIS
jailadm -j jailname [-u uuid-match] subcommand
[subcommand_options]
jailadm [-R root] [-j jailname] [-u uuid-match] list
[list_options]
jailadm [-R root] -j jailname [-u uuid-match] mark incomplete
DESCRIPTION
The jailadm utility is used to administer jails. A jail is an
application container that is maintained by the operating system
runtime.
SECURITY
Once a process has been placed in a jail, the process or any of its
children cannot change jails.
OPTIONS
The following options are supported:
-R root
Specify an alternate root (boot environment). This option can only
be used in conjunction with the "list" and "mark" subcommands.
-u uuid-match
Unique identifier for a jail, as assigned by libuuid(3LIB). If this
option is present and the argument is a non-empty string, then the
jail matching the UUID is selected instead of the one named by the
-j option, if such a jail is present.
-j jailname
String identifier for a jail.
SUBCOMMANDS
Subcommands which can result in destructive actions or loss of work
have a -F flag to force the action. If input is from a terminal device,
the user is prompted if such a command is given without the -F flag;
otherwise, if such a command is given without the -F flag, the action
is disallowed, with a diagnostic message written to standard error. If
a jail installation or uninstallation is interrupted, the jail is left
in the incomplete state. Use uninstall to reset such a jail back to the
configured state.
The following subcommands are supported:
attach [-F] [-n path] [brand-specific options]
The attach subcommand takes a jail that has been detached from one
system and attaches the jail onto a new system. Therefore, it is
advised (though not required) that the detach subcommand should be
run before the "attach" takes place. Once you have the new jail in
the configured state, use the attach subcommand to set up the jail
root instead of installing the jail as a new jail.
The -F option can be used to force the jail into the "installed"
state with no validation. This option should be used with care
since it can leave the jail in an unsupportable state if it was
moved from a source system to a target system that is unable to
properly host the jail. The -n option can be used to run the attach
subcommand, without executing the command. It uses the output of
the "detach -n" subcommand as input and is useful to identify any
conflicting issues, such as the network device being incompatible,
and can also determine whether the host is capable of supporting
the jail. The path can be "-", to read the input from standard
input.
The jail's brand may include additional options that govern how the
jail will be attached. See brands(5) for specific brand
information.
The jail being attached must first be configured using the jailcfg
(see jailcfg(1M)) command. This does not apply when running "attach
-n".
Use the following command to attach a jail:
# jailadm -j my-jail attach
boot [-- boot_options]
Boot (or activate) the specified jails.
The following boot_options are supported:
-i altinit
Select an alternative executable to be the primordial Process.
altinit is a valid path to an executable. The default
primordial process is init(1M).
clone [-m copy] [-s zfs_snapshot] source_jail
Install a jail by copying an existing installed jail. This
subcommand is an alternative way to install the jail.
-m copy
Force the clone to be a copy, even if a "ZFS clone" is
possible.
-s zfs_snapshot
Specify the name of a ZFS snapshot to use as the source of the
clone. The snapshot must be a snapshot of the source jail taken
from a previous "jailadm clone" installation.
The source jail must be halted before this subcommand can be used.
detach [-n]
Detach the specified jail. Detaching a jail is the first step in
moving a jail from one system to another. The full procedure to
migrate a jail is that the jail is detached, the jailpath directory
is moved to the new host, and then the jail is attached on the new
host. Once the jail is detached, it is left in the configured
state. If you try to install or clone to a configured jail that has
been detached, you will receive an error message and the install or
clone subcommand will not be allowed to proceed. The -n option can
be used to run the detach subcommand, without executing the
command. This generates the information needed for running the
"attach -n" subcommand, which is useful to identify any conflicting
issues, such as the network device being incompatible or if the
host is capable of supporting the jail. The information is sent to
standard output and can be saved to a file or piped to the "attach
-n" subcommand.
Use the following command to detach a jail:
# jailadm -j my-jail detach
The source jail must be halted before this subcommand can be used.
halt
Halt the specified jails. halt bypasses running the shutdown
scripts inside the jail. It also removes run time resources of the
jail.
help [subcommand]
Display general help. If you specify subcommand, displays help on
subcommand.
install [-x nodataset] [brand-specific options]
Install the specified jail on the system. This subcommand
automatically attempts to verify first, most verification errors
are fatal. See the verify subcommand.
-x nodataset
Do not create a ZFS file system.
The jail's brand may include additional options that govern how the
software will be installed in the jail. See brands(5) for specific
brand information.
list [list_options]
Display the name of the current jails, or the specified jail if
indicated.
By default, all running jails are listed. If you use this
subcommand with the jailadm -j jailname option, it lists only the
specified jail, regardless of its state. In this case, the -i and
-c options are disallowed.
If neither the -i or -c options are given, all running jails are
listed.
The following list_options are supported:
-c
Display all configured jails. This option overides the -i
option.
-i
Expand the display to all installed jails.
-p
Request machine parsable output. The output format is a list of
lines, one per jail, with colon- delimited fields. These fields
are:
jailid:jailname:state:jailpath:uuid:brand:ip-type
If the jailpath contains embedded colons, they can be escaped
by a backslash (""), which is parsable by using the shell
read(1) function with the environmental variable IFS. The uuid
value is assigned by libuuid(3LIB) when the jail is installed,
and is useful for identifying the same jail when present (or
renamed) on alternate boot environments. Any software that
parses the output of the "jailadm list -p" command must be able
to handle any fields that may be added in the future.
The -v and -p options are mutually exclusive. If neither -v nor
-p is used, just the jail name is listed.
-v
Display verbose information, including jail name, id, current
state, root directory, brand type, ip-type, and options.
The -v and -p options are mutually exclusive. If neither -v nor
-p is used, just the jail name is listed.
mark incomplete
Change the state of an installed jail to "incomplete." This command
may be useful in cases where administrative changes on the system
have rendered a jail unusable or inconsistent. This change cannot
be undone (except by uninstalling the jail).
move new_jailpath
Move the jailpath to new_jailpath. The jail must be halted before
this subcommand can be used. The new_jailpath must be a local file
system and normal restrictions for jailpath apply.
ready
Prepares a jail for running applications but does not start any
user processes in the jail.
reboot[-- boot_options]]
Restart the jails. This is equivalent to a halt boot sequence. This
subcommand fails if the specified jails are not active. See boot
subcommand for the boot options.
shutdown [-r [-- boot_options]]
Gracefully shutdown the specified jail. This subcommand waits for
all jail processes to finish; the default timeout is
SCF_PROPERTY_TIMEOUT value from the SMF service system/jails. If
the -r option is specified, reboot the jail. See boot subcommand
for the boot options.
uninstall [-F]
Uninstall the specified jail from the system. Use this subcommand
with caution. It removes all of the files under the jailpath of
the jail in question. You can use the -F flag to force the action.
verify
Check to make sure the configuration of the specified jail can
safely be installed on the machine. Following is a break-down of
the checks by resource/property type:
jailpath
jailpath and its parent directory exist and are owned by root
with appropriate modes . The appropriate modes are that
jailpath is 700, its parent is not group or world-writable and
so forth. jailpath is not over an NFS mount. A sub-directory
of the jailpath named "root" does not exist.
If jailpath does not exist, the verify does not fail, but
merely warns that a subsequent install will attempt to create
it with proper permissions. A verify subsequent to that might
fail should anything go wrong.
jailpath cannot be a symbolic link.
fs
Any fs resources have their type value checked. An error is
reported if the value is one of proc, mntfs, autofs, or nfs or
the filesystem does not have an associated mount binary at
/usr/lib/fs/<fstype>/mount.
It is an error for the directory to be a relative path.
It is an error for the path specified by raw to be a relative
path or if there is no fsck binary for a given filesystem type
at /usr/lib/fs/<fstype>/fsck. It is also an error if a
corresponding fsck binary exists but a raw path is not
specified.
net
All physical network interfaces exist. All network address
resources are one of:
o a valid IPv4 address, optionally followed by "/" and
a prefix length;
o a valid IPv6 address, which must be followed by "/"
and a prefix length;
o a host name which resolves to an IPv4 address.
Note that hostnames that resolve to IPv6 addresses are not
supported.
The physical interface name is the network interface name.
A jail can be configured to be either exclusive-IP or shared-
IP. For a shared-IP jail, both the physical and address
properties must be set. For an exclusive-IP jail, the physical
property must be set and the address property cannot be set.
rctl
It also verifies that any defined resource control values are
valid on the current machine. This means that the privilege
level is privileged, the limit is lower than the currently
defined system value, and that the defined action agrees with
the actions that are valid for the given resource control.
EXAMPLES
Example 1 Using the -m Option
The following command illustrates the use of the -m option.
# jailadm boot -- -m verbose
Example 2 Using the -i Option
The following command illustrates the use of the -i option.
# jailadm boot -- -i /sbin/init
Example 3 Using the -s Option
The following command illustrates the use of the -s option.
# jailadm boot -- -s
EXIT STATUS
The following exit values are returned:
0
Successful completion.
1
An error occurred.
2
Invalid usage.
SEE ALSO
read(1), svcs(1), zlogin(1), jailname(1), init(1M), kernel(1M),
svcadm(1M), svc.startd(1M), svc.startd(1M), jailcfg(1M), libuuid(3LIB),
attributes(5), brands(5), native(5), smf(5), jails(5)
STANDARDS
The jailadm(8) command is specific to FreeBSD and does not conform to
any published standards.
HISTORY
The jailadm(8) command is based on the zoneadm(1M) command that first
appeared in Sun Solaris version 10 .
September 8, 2015 JAILADM(8)