Jails

Jails

Manifest support

This page describes keys within a manifest that pertain to FreeBSD jails. The keys can be at one of the following scopes:

• Global, i.e. top-level keys
• Jail scope, i.e. keys within a 'Jail' dictionary
• CreateDataset scope -- keys to create a ZFS dataset for the jail
• NetworkInterface scope -- keys for creating network interfaces
• MountFilesystem scope -- keys for mounting filesystems into the jail

Global scope

The following keys are defined at top-scope within the manifest:

Key	Datatype	Default	Description
Transient	Boolean	False	If true, the jail will be destroyed when the job is terminated
Packages	List of strings	none	Packages to be installed in the jail via pkg(8)
ChrootDirectory	Pathname	none	If the Jail key is present, the value of ChrootDirectory is used for the root directory of the jail.
ChrootPopulate	Array of pathnames	none	The chroot for the jail will be populated by extracting files from a list of pathnames. The tar(1) command is used to extract files. The ordering of pathnames in the array is important, and will be preserved when extracting files. This allows you to extract the FreeBSD "base.txz", and then extract additional files over-top of the base system.

CreateDataset scope

The following keys are defined with the scope of a top-level CreateDataset key that is a dictionary.

Key	Datatype	Default	Description
Pool	String	none	The pool to create the dataset within
Name	String	none	The name of the dataset, including any parents
Origin	String	none	If this field is non-empty, the dataset will be cloned from an origin. The origin dataset must already exist.
Quota	String	none	The quota to be applied to the dataset; see zfs(8) for the syntax

NetworkInterface scope

The following keys are defined with the scope of a top-level NetworkInterface key that is a dictionary.

Key	Datatype	Default	Description
Driver	String	none	The type of interface to create. Examples: tap, epair, lo
Instance	Integer	automatically determined based on the next available instance number	(Optional) The instance number of the interface. This usually starts with zero and increments.
AddToBridge	String	none	(Optional) Name of the bridge to add the interface to after it is created.
Description	String	none	(Optional) A user-visible description to assign to the interface.

MountFilesystem scope

The following keys are defined with the scope of a top-level MountFilesystem key that is a dictionary.

Key	Datatype	Default	Description
Device	string	none	TODO
MountPoint	string	none	TODO
Type	string	none	TODO
Options	string	none	TODO

Jail scope

The following keys are defined with the scope of a top-level Jail key that is a dictionary.

Key	Datatype	Default	Description
Hostname	String	Shortened version of the label	The hostname of the jail
Name	String	Shortened version of the label	The name of the jail

Example

The following is an example of a manifest that constructs a jail to run a "hello world" process. When the process exits, the jail will be destroyed. The process output will be saved under /tmp/hello-world/hello.log.

{
"Label": "hello.world",
"ProgramArguments": [ "/bin/echo", "Hello world!" ],
"StandardOutPath": "/tmp/hello.log",
"Transient": true,
"ChrootDirectory": "/jails/hello_world",
"ChrootPopulate": [
  "/var/tmp/base.txz",
  "/var/tmp/my_custom_files.tar.gz",
],
"CreateDataset": {
  "Pool": "zroot",
  "Name": "jails/hello_world",
  "Quota": "20G",
},
"NetworkInterface": {
  "AddToBridge": "br0",
  "Driver": "epair",
  "Instance": "0",
  "Description": "automatically created by launchd(8) for the hello-world jail",
},
"MountFilesystem": [
    {
    "Device": "/tmp/hello-world",
    "MountPoint": "/jails/hello_world/tmp",
    "Type": "nullfs",
    "Options": "rw,noexec,nosuid",
    },
  ],
"Jail": {
  "Hostname": "hello-world",
  },
}