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 [-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-jail 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	wkrdirs.

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

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

				      Use the -v flag to set the branch	name.
				      The Git server address is	derived	from
				      the GIT_BASEURL variable in

				      The following protocols are supported:
				      git (default), http, https, and 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]  Will use SVN and the SVN_HOST variable
				      in poudriere.conf.  Use SVN to download
				      the sources.

				      The SVN host address is derived from the
				      SVN_HOST variable	in poudriere.conf.

				      The following protocols are supported:
				      svn (default), file, http, and https.

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

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

     -v	version	      Specify the version of FreeBSD to	use in the jail.  If
		      you are using -m ftp then	the version should in the form
		      of "12.0-RELEASE".  If you are using -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 just
		      "head" for CURRENT.  Other methods only use the version
		      value for	display.

     -x		      Build the	native-xtools target using the host's /usr/src
		      tree and copy this into the jail.	 The use of /usr/src
		      is due to	a bug in the native-xtools build which does
		      not allow	it to be built from the	jail's own source.
		      Used exclusively for cross building a ports set, typi-
		      cally via	the qemu-user tools.

     -z	set	      This specifies which set to start/stop the jail with.

     The jail subcommand may use the following environment variables:

     FETCH_BIND_ADDRESS	 The bind address used by fetch(1).  See fetch(3) for
			 more details.

     FTP_<*>		 The proxy configuration for fetch(1).	See fetch(3)
			 for other supported proxy environment variables.

     ftp_<*>		 See FTP_<*>.

     FTP_PROXY		 See FTP_<*>.

     HTTP_<*>		 See FTP_<*>.

     http_<*>		 See FTP_<*>.

     HTTP_PROXY		 See FTP_<*>.

     NO_PROXY		 See FTP_<*>.

     no_proxy		 See FTP_<*>.

     SSL_<*>		 See FTP_<*>.

     MAKEOBJDIRPREFIX	 Related to the	-x flag.  See build(7) and the imple-
			 mentation of the jail subcommand for more details.

     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
       "112i386" already exists.

	 # poudriere jail -l -n	-q | grep --quiet '^112i386$'

     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			 March 8, 2019			  FreeBSD 13.0


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

home | help