FreeBSD Manual Pages
POUDRIERE-JAIL(8) System Manager's Manual POUDRIERE-JAIL(8) NAME poudriere jail -- manage jails used to build ports SYNOPSIS poudriere jail -c -j name [-bBDx] [-a architecture] [-f filesystem] [-J maxjobs] [-K kernelname] [-M mountpoint] [-m method] [-P patch] [-p portstree] [-S srcpath] [-z set] poudriere jail -d -j name [-y] [-C data] [-p portstree] [-z set] poudriere jail -i -j name [-z set] poudriere jail -k -j name [-z set] poudriere jail -l [nq] [-z set] poudriere jail -r name -j name [-z set] poudriere jail -s -j name [-z set] poudriere jail -u -j name [-X] [-J maxjobs] [-t version] [-z set] DESCRIPTION This command manages the poudriere jails which are used as different build- ing environments. SUBCOMMANDS -c Create a jail. See "CAVEATS" for restrictions on the names of jails. -d Delete a jail. If the stdin is a TTY then the command is going to ask for confir- mation, which defaults to "N" (for no). Othwerwise, the specified jail is deleted without confirmation. -i Show information about a jail. See also poudriere-status(8). -k Kill a jail (stop it). -l List all poudriere jails. -r name Rename a jail to name. -s Start a jail. -u Update a jail. OPTIONS Except for -l, all of the subcommands require the -j option (see below). -a architecture Specify the architecture to use in the jail (for example amd64). The default is the architecture of the host. -b By default, -m src=path will only install the source, not build it. Use -b to do a build too. Using -m git|svn will always build. -B Build the pkgbase set when creating the jail with -c. Should only be used with -b -m src=path, or -m git|svn. -C data Clean poudriere data directories when deleting a jail. Only used for -d option. Can be specified multiple times. The data parameter can be one of the following: all, cache, images, logs, packages, or wrkdirs. -D Clone the Git repository with the full history when creat- ing the jail from a Git checkout. The default behavior is to check out only the most recent commit (as if --depth=1 was specified to the Git command). -f filesystem Specify the filesystem name (${ZPOOL}/jails/filesystem). -J maxjobs Run maxjobs of make(1) jobs in parallel for buildworld. Defaults to the number of CPUs reported by nproc(1). -j name Specify the name of the jail. -K kernelname Install the jail with the specified kernel name. If the kernelname is an empty string then GENERIC will be used. If installing from FTP then the default kernel is in- stalled and the value of kernelname is ignored. -M mountpoint Use an alternative mountpoint when creating the jail. -m method Specify which method to use to create the jail. The de- fault is http. Pre-built distribution options: ftp Fetch from the host specified in the FREEBSD_HOST variable in poudriere.conf. ftp-archive Fetch from http://ftp-archive.freebsd.org. http See ftp. freebsdci Fetch from https://artifact.ci.freebsd.org. null This option can be used to import an existing directory that already contains an installed system. The path must be specified with -M path. It is expected that this directory be installed to with the following: # cd /usr/src # make installworld DESTDIR=PATH DB_FROM_SRC=1 # make distrib-dirs DESTDIR=PATH DB_FROM_SRC=1 # make distribution DESTDIR=PATH DB_FROM_SRC=1 It will not be copied at the time of running "poudriere jail". Deleting the jail will at- tempt to revert any files changed by poudriere. pkgbase[=repository_path] Install from the given pkgbase repository at path from the given -U url. If no path is specified, defaults to the official FreeBSD pkgbase server, in which case -U must not be provided. Note that building kernel module will not be possible as there is no package with the source code. src=path Install from the given directory at path. This directory will not be built unless -b is given. It is expected that it is already built and maps to a corresponding /usr/obj directory. tar=path Install from the tarball located at the given path. Note that if you plan to build any port con- taining kernel modules then the specified tarball has to contain the /usr/src files as well. url=url Fetch distribution tarballs (like base.txz) from the given url. Any URL supported by fetch(1) can be used. For example: "url=file:///mirror/10.0". Build from source options: git[+protocol] Use Git to download the sources. Sources will be cloned shallowly unless -D is specified. Output will mostly be hidden unless poudriere -v jail is used. Use the -v branch parameter to set the branch name when creating a jail. Use the -t branch parameter to switch the branch when updating a jail. The Git server address is derived from the GIT_BASEURL variable in poudriere.conf. -U url may be used to override that value. The following protocols are supported: git (default), +http, +https, +file, +ssh. src=path Copy the source tree from path into the jail, and build it. This option is meant to be used with the -b flag. svn[+protocol] Use SVN to download the sources. Output will mostly be hidden unless poudriere -v jail is used. Use the -v branch parameter to set the branch name. Use the -t branch parameter to switch the branch when updating a jail. The SVN host address is derived from the SVN_HOST variable in poudriere.conf. -U url may be used to override that value. The following protocols are supported: svn (default), +http, +https, +file, +ssh. -n When combined with -l, only display jail name. -P patch Apply the specified patch to the source tree before build- ing the jail. -p portstree Specify the ports tree to start/stop the jail with. (Default: "default") -q Remove the header when -l is the specified mandatory op- tion. Otherwise, it has no effect. -S srcpath Use the specified srcpath as the FreeBSD source tree mounted inside the jail or from the host for -m null. -t version Upgrade the jail to the specified version instead of up- grading to the latest security fix. -U url Specifies which url to checkout from when using the git or svn or pkgbase methods. -v version Specify the version of FreeBSD to use in the jail. For most methods, and by default if no -m is specified, version should in the form of "12.0-RELEASE". If you are using -m git, or -m svn, then the version should be in the form of Git or SVN branches, which is usually in the form of "stable/9" or "main" for CURRENT from git. Other meth- ods only use the version value for display. -X Do not build and setup native-xtools cross compile tools in jail when building for a different TARGET ARCH than the host. Only applies if TARGET_ARCH and HOST_ARCH are dif- ferent. -y Do not prompt for confirmation when deleting a jail. -z set This specifies which set to start/stop the jail with. FETCH_BIND_ADDRESS The bind address used by fetch(1). See fetch(3) for more details. HTTP_PROXY HTTP_* http_* FTP_PROXY FTP_* http_* SSL_* NO_PROXY no_proxy The proxy configuration for fetch(1). See fetch(3) for other supported proxy environment variables. MAKEOBJDIRPREFIX See build(7) and the implementation of the poudriere jail command for more details. TERM Passed through for interactive modes. EXAMPLES Example 1: Creating New Jail The following example creates a new amd64 jail called "120amd64", that is based on FreeBSD 12.0-RELEASE. # poudriere jail -c -j 120amd64 -v 12.0-RELEASE -a amd64 Example 2: Checking If a Jail Already Exists The following command returns success if a poudriere jail called "130i386" already exists. # poudriere jail -l -n -q | grep --quiet '^130i386$' SEE ALSO jail(8), poudriere(8), poudriere-bulk(8), poudriere-distclean(8), poudriere-image(8), poudriere-logclean(8), poudriere-options(8), poudriere- pkgclean(8), poudriere-ports(8), poudriere-queue(8), poudriere-status(8), poudriere-testport(8), poudriere-version(8) AUTHORS Baptiste Daroussin <bapt@FreeBSD.org> Bryan Drewery <bdrewery@FreeBSD.org> CAVEATS Jail Names The values set with the -j, -z, and -p flags are all used directly in the name of the jail created by poudriere. Be careful to respect the names supported by jail(8): This is an arbitrary string that identifies a jail (except it may not contain a '.'). FreeBSD ports 15.1 February 26, 2026 POUDRIERE-JAIL(8)
NAME | SYNOPSIS | DESCRIPTION | SUBCOMMANDS | OPTIONS | EXAMPLES | SEE ALSO | AUTHORS | CAVEATS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=poudriere-jail&sektion=8&manpath=FreeBSD+15.1-RELEASE+and+Ports>