NAME

appjail-jail — Creates, removes, lists and configures jails

SYNOPSIS

appjail jail boot [off|on] jail

appjail jail clean

appjail jail create [-a architecture] [-I install-method] [-i initscript] [-r release] [-T type] [-t template] [-v version] jail

appjail jail destroy [-fR] jail

appjail jail get [-eHIpt] jail [keyword ...]

appjail jail list [-eHIpt] [-j jail] [keyword ...]

appjail jail mark [clean|dirty] jail

appjail jail mark [locked|unlocked] jail

appjail jail priority -p priority jail

appjail jail rename jail new-name

DESCRIPTION

The appjail jail utility creates, removes, lists, configures or basically can manage many things related to jails and their properties. appjail-quick(1) uses it to create, remove, and mark them as dirty.

The options are as follows:

boot [off|on] jail

Enable (on) or disable (off) the boot flag for jail. If the boot flag is enabled, appjail-startup(1) will start and/or stop jail, a process commonly performed by the rc(8) script.

clean

Remove dirty jails.

create [-a architecture] [-I install-method] [-i initscript] [-r release] [-T type] [-t template] [-v version] jail

Create a new jail. This subcommand only has the responsibility of creating a jail; It is highly recommended to use appjail-quick(1) unless you know what you are doing.

-a architecture: Specify the architecture to use in the jail. If this option is not set, the architecture specified by the FREEBSD_ARCH parameter is used.
-I install-method: Specify the installation method that affects the jail type and how you should use this subcommand. If this option is not set, the installation method specified by the DEFAULT_INSTALL_METHOD parameter is used.
See INSTALLATION METHODS for a list of available installation methods.
-i initscript: InitScript to make the jail interactive.
-r release: Specify the release to use in the jail. If this option is not set, the release specified by the DEFAULT_RELEASE parameter is used.
-T type: Type on which the jail is based. The default is thin.
-t template: Template file. If not specified, the template file specified by the DEFAULT_TEMPLATE parameter is used.
-v version: Specify the version of the operating system to use in the jail. If this option is not set, the version specified by the FREEBSD_VERSION parameter is used.

destroy [-fR] jail

Destroy jail.

If jail is a container, it will be destroyed before the files are removed.

-f: Forcibly unmount file system. Ignored when ZFS is not enabled.
-R: Recursively destroy all dependents, including cloned file systems outside the target hierarchy. Ignored when ZFS is not enabled.

get [-eHIpt] jail [keyword ...]

Get information about jail, that is, the keyword that represent the information to be obtained. Multiple keywords can be specified, which are displayed as a table-like interface in the order in which they are specified. If no keyword is specified, the defaults are status, name, type, version, ports and network_ip4.

See KEYWORDS for a list of available keywords.

-e: Not required when using -p. The \t character is used to delimit columns, so as not to show strange values, this option shows <TAB> instead of \t in the case that a value contains the latter.
-H: Shows the name of the columns.
-I: Include empty values. By default, a minus sign is displayed when a value is empty.
-p: Columnate the list.
-t: Tabulate columns and values.

list [-eHIpt] [-j jail] [keyword ...]

Similar to get but shows each keyword for each jail in a nice table.

-e, -H, -I, -p, -t: All of these options perform the opposite task of the options described in get.
-j jail: Only show information for jail.

mark [clean|dirty] jail

jail can be marked as dirty, which is something like an atomic operation. When a jail is marked dirty, appjail(1) and its subcommands are free to treat the target jail as incomplete and error-prone, so the behavior is typically to destroy it and start over, an operation commonly performed by appjail-jail(1), appjail-quick(1), the clean subcommand, and so on.

mark [locked|unlocked] jail

Used by appjail-start(1) to prevent another process from executing it (e.g.: the user spawns a new shell and executes appjail-start(1)) while the first one is still running.

Marking jail as locked locks it, but if you try to lock it again it fails unless it is marked as unlocked.

priority -p priority jail

Change the priority for jail.

rename jail new-name

Rename jail with a new name.

INSTALLATION METHODS

clone+jail="jail@snapshot"

Create a new jail by cloning a ZFS snapshot of jail.

Parameters:

jail: Jail to create a ZFS snapshot for cloning.
snapshot: ZFS snapshot name.

clone+release="snapshot"

Create a new jail by cloning a ZFS snapshot of a release.

With this option only the linux+debootstrap and thick jail types can be used.

Parameters:

snapshot: ZFS snapshot name.

copy="jail"

Create a new jail by copying another existing jail.

empty

Create an empty jail.

export+jail="output:outname [portable] [compress:algo]"

Export the jail directory to a tarball file.

Parameters:

output: Output name.
portable Ignored, but used by export+root.
compress: If specified, the file will be compressed.
See COMPRESSION ALGORITHMS for a list of available compression algorithms.

export+root="output:outname [portable] [compress:algo]"

Export the root directory of the jail to a tarball file.

Parameters:

output: Output name.
portable Include only portable files, that is, the jail directory, the InitScript, the configuration file that describes the jail, and the specifications of volumes used by the jail. This is used by appjail-image(1).
compress: If specified, the file will be compressed.
See COMPRESSION ALGORITHMS for a list of available compression algorithms.

import+jail="input:file [portable] [compress:algo]"

Create a new jail by importing a tarball file into the jail directory.

Parameters:

input: Tarball file.
portable: Ignored, but used by import+root.
compress: Ignored, but used by zfs+import+jail and zfs+import+root.

import+root="input:file [portable] [compress:algo]"

Create a new jail by importing a tarball file into the root directory of the jail.

Parameters:

input: Tarball file.
portable: Include only portable files, that is, the jail directory, the InitScript, the configuration file that describes the jail, and the specifications of volumes used by the jail. This is used by appjail-image(1).
compress: Ignored, but used by zfs+import+root and zfs+import+root.

standard

Create a thin, thick or linux+debootstrap jail.

tiny+export="files:file output:outname [compress:algo]"

Export a jail directory with only the files needed to run a program.

Parameters:

files: A file that contains a list of files to export.
output: Output name.
compress: If specified, the file will be compressed.
See COMPRESSION ALGORITHMS for a list of available compression algorithms.

tiny+import="file"

Create a new jail by importing a TinyJail.

zfs+export+jail="output:outname [portable] [compress:algo]"

Recursively export the jail dataset to a ZFS image file.

output: Output name.
portable: Ignored, but used by export+root.
compress: If specified, the file will be compressed.
See COMPRESSION ALGORITHMS for a list of available compression algorithms.

zfs+export+root="output:outname [portable] [compress:algo]"

Recursively export the root jail dataset to a ZFS image file.

output: Output name.
portable: Ignored, but used by export+root.
compress: If specified, the file will be compressed.
See COMPRESSION ALGORITHMS for a list of available compression algorithms.

zfs+import+jail="input:file [portable] [compress:algo]"

Create a new jail by importing a ZFS image into the jail directory.

Parameters:

input: ZFS image.
portable: Ignored, but used by import+root.
compress: Change the compression algorithm. Automatic detection of the algorithm used by the ZFS image is performed, but if it fails or you need to change for some reason, you do so using this subparameter.

zfs+import+root="input:file [portable] [compress:algo]"

Create a new jail by importing a ZFS image into the root directory of the jail.

Parameters:

input: ZFS image.
portable: Ignored, but used by import+root.
compress: Change the compression algorithm. Automatic detection of the algorithm used by the ZFS image is performed, but if it fails or you need to change for some reason, you do so using this subparameter.

KEYWORDS

alt_name: Displays the alternate DNS name.
See also appjail-network(1).
appjail_version: AppJail version that was used to first create the jail.
arch: Architecture that was used at the creation time.
boot: Shows 1 if the boot flag is enabled, 0 if it is not.
container: Displays the name of the container.
container_boot: Displays 1 if the program defined in the OCI image is to be executed by appjail-start(1), 0 otherwise.
container_image: Displays the OCI image used to create the container.
container_pid: Displays the PID of the program defined in the OCI image running in the background if it is running.
created: Creation date. The CREATED_FORMAT parameter specifies the format to display this value.
devfs_ruleset: Shows the ruleset assigned by appjail-devfs(1).
dirty: Shows 1 if the jail is dirty, 0 if it is not.
hostname: Shows the hostname assigned by the host.hostname parameter in a template.
inet: Shows all IPv4 addresses reported by ifconfig(8). If the jail is not running, IPv4 addresses cannot be retrieved.
inet6: Same as inet but for IPv6.
ip4: Shows the IPv4 addresses assigned by the ip4.addr parameter in a template.
ip6: Same as ip4 but for IPv6.
is_container: Displays 1 if the jail is a container, 0 otherwise.
locked: Shows 1 if the jail is locked, 0 if it is not.
name: Shows the jail name.
network_ip4: Shows all current IPv4 addresses assigned to the jail for all virtual networks it is on.
networks: Shows all virtual networks the jail is on.
path: Jail directory.
priority: Jail priority.
ports: Exposed ports. Note that this does not mean that port forwarding is performed, it only shows the ports that are marked to be exposed and may or may not be currently forwarded.
release_name: Release that was or is currently being used by the jail.
status: Shows UP if the jail is currently started, DOWN if not.
type: Jail type.
version: Operating system version that was used at the creation time.
version_extra: String commonly used when the jail was created using a build from the FreeBSD source tree.

COMPRESSION ALGORITHMS

bzip
gzip
lrzip: Requires archivers/lrzip.
lz4
lzma
lzop: Requires archivers/lzop.
xz
zstd

EXIT STATUS

The appjail jail utility exits 0 on success, and >0 if an error occurs.

AUTHORS

Jesús Daniel Colmenares Oviedo <DtxdF@disroot.org>