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

FreeBSD Manual Pages


home | help
POUDRIERE-JAIL(8)	FreeBSD	System Manager's Manual	     POUDRIERE-JAIL(8)

     poudriere jail -- manage jails used to build ports

     poudriere jail -c -j name [-bDx] [-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]

     This command manages the poudriere	jails which are	used as	different
     building environments.

     -c	      Create a jail.  See CAVEATS for restrictions on the names	of

     -d	      Delete a jail.

	      If the stdin is a	TTY then the command is	going to ask for con-
	      firmation, 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.

     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		      Build the	source provided	with the -m src=path option.

     -C	data	      Clean poudriere data folders when	deleting a jail.  Only
		      used for -d option.

		      The data parameter can be	one of the following: all,
		      cache, logs, packages, or	wrkdirs.

     -D		      Clone the	Git repository with the	full history when cre-
		      ating the	jail from a Git	checkout.  The default behav-
		      ior 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: "sysctl

     -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:

		      allbsd	   Fetch from

		      ftp	   Fetch from the host specified in the
				   FREEBSD_HOST	variable in poudriere.conf.

		      ftp-archive  Fetch from

		      http	   See ftp.

		      freebsdci	   Fetch from

		      null	   This	option can be used to import an	exist-
				   ing directory that already contains an in-
				   stalled system.  The	path must be specified
				   with	-M path.  It is	expected that this di-
				   rectory 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	run-
				   ning	"poudriere jail".  Deleting the	jail
				   will	attempt	to revert any files changed by

		      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	al-
				   ready 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
				   containing kernel modules then the speci-
				   fied	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:

		      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,

		      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,

     -n		      When combined with -l, only display jail name.

     -P	patch	      Apply the	specified patch	to the source tree before
		      building 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 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 methods 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

     -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.

     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$'

     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)

     Baptiste Daroussin	<>
     Bryan Drewery <>

   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	13.0			 June 17, 2022			  FreeBSD 13.0


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

home | help