path: root/src/man/poudriere-jail.8

.\" Copyright (c) 2012 Baptiste Daroussin <bapt@FreeBSD.org>
.\" Copyright (c) 2012-2014 Bryan Drewery <bdrewery@FreeBSD.org>
.\" Copyright (c) 2018 SRI International
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.\" Note: The date here should be updated whenever a non-trivial
.\" change is made to the manual page.
.Dd August 19, 2021
.Dt POUDRIERE-JAIL 8
.Os
.Sh NAME
.Nm "poudriere jail"
.Nd manage jails used to build ports
.Sh SYNOPSIS
.Nm
.Fl c
.Fl j Ar name
.Op Fl bDx
.Op Fl a Ar architecture
.Op Fl f Ar filesystem
.Op Fl J Ar maxjobs
.Op Fl K Ar kernelname
.Op Fl M Ar mountpoint
.Op Fl m Ar method
.Op Fl P Ar patch
.Op Fl p Ar portstree
.Op Fl S Ar srcpath
.Op Fl z Ar set
.Nm
.Fl d
.Fl j Ar name
.Op Fl y
.Op Fl C Ar data
.Op Fl p Ar portstree
.Op Fl z Ar set
.Nm
.Fl i
.Fl j Ar name
.Op Fl z Ar set
.Nm
.Fl k
.Fl j Ar name
.Op Fl z Ar set
.Nm
.Fl l
.Op Ar nq
.Op Fl z Ar set
.Nm
.Fl r Ar name
.Fl j Ar name
.Op Fl z Ar set
.Nm
.Fl s
.Fl j Ar name
.Op Fl z Ar set
.Nm
.Fl u
.Fl j Ar name
.Op Fl X
.Op Fl J Ar maxjobs
.Op Fl t Ar version
.Op Fl z Ar set
.Sh DESCRIPTION
This command manages the poudriere jails which are used as different building
environments.
.Sh SUBCOMMANDS
.Bl -tag -width "-r name"
.It Fl c
Create a jail.
See
.Sx CAVEATS
for restrictions on the names of jails.
.It Fl d
Delete a jail.
.Pp
If the stdin is a TTY then the command is going to ask for confirmation,
which defaults to
.Dq Ic N
.Pq for no .
Othwerwise, the specified jail is deleted without confirmation.
.It Fl i
Show information about a jail.
See also
.Xr poudriere-status 8 .
.It Fl k
Kill a jail (stop it).
.It Fl l
List all poudriere jails.
.It Fl r Ar name
Rename a jail to
.Ar name .
.It Fl s
Start a jail.
.It Fl u
Update a jail.
.El
.Sh OPTIONS
Except for
.Fl l ,
all of the subcommands require the
.Fl j
option (see below).
.Bl -tag -width "-a architecture"
.It Fl a Ar architecture
Specify the
.Ar architecture
to use in the jail
.Pq for example Cm amd64 .
The default is the architecture of the host.
.It Fl b
Build the source provided with the
.Fl m Cm src= Ns Ar path
option.
.It Fl C Ar data
Clean poudriere
.Ar data
folders when deleting a jail.
Only used for
.Fl d
option.
.Pp
The
.Pa data
parameter can be one of the following:
.Cm all , cache , logs , packages , No or Cm wkrdirs .
.It Fl D
Clone the Git repository with the full history when creating the jail from a
Git checkout.
The default behavior is to check out only the most recent commit
.Pq as if Fl -depth=1 No was specified to the Git command .
.It Fl f Ar filesystem
Specify the
.Ar filesystem
name
.Pq ${ Ns Va ZPOOL Ns } Ns Pa /jails/filesystem .
.It Fl J Ar maxjobs
Run
.Ar maxjobs
of
.Xr make 1
jobs in parallel for buildworld.
Defaults to the number of CPUs reported by:
.Dq Li sysctl hw.ncpu .
.It Fl j Ar name
Specify the
.Ar name
of the jail.
.It Fl K Ar kernelname
Install the jail with the specified kernel name.
If the
.Ar kernelname
is an empty string then GENERIC will be used.
If installing from FTP then the default kernel is installed and
the value of
.Ar kernelname
is ignored.
.It Fl M Ar mountpoint
Use an alternative
.Ar mountpoint
when creating the jail.
.It Fl m Ar method
Specify which
.Ar method
to use to create the jail.
The default is
.Cm http .
.Pp
Pre-built distribution options:
.Bl -tag -width "ftp-archive"
.It Cm allbsd
Fetch from
.Lk http://www.allbsd.org .
.It Cm ftp
Fetch from the host specified in the
.Va FREEBSD_HOST
variable in
.Pa poudriere.conf .
.It Cm ftp-archive
Fetch from
.Lk http://ftp-archive.freebsd.org .
.It Cm http
See
.Cm ftp .
.It Cm freebsdci
Fetch from
.Lk https://artifact.ci.freebsd.org .
.It Cm null
This option can be used to import an existing directory that already contains
an installed system.
The path must be specified with
.Fl M Ar path .
It is expected that this directory be installed to with the following:
.Bd -literal -offset 2n
.Ic # cd /usr/src
.Ic # Ic make installworld DESTDIR= Ns Ar PATH Ic DB_FROM_SRC=1
.Ic # make distrib-dirs DESTDIR= Ns Ar PATH Ic DB_FROM_SRC=1
.Ic # make distribution DESTDIR= Ns Ar PATH Ic DB_FROM_SRC=1
.Ed
.Pp
It will not be copied at the time of running
.Dq Li poudriere jail .
Deleting the jail will attempt to revert any files changed by poudriere.
.It Cm src= Ns Ar path
Install from the given directory at
.Ar path .
This directory will not be built unless
.Fl b
is given.
It is expected that it is already built and maps to a corresponding
.Pa /usr/obj
directory.
.It Cm tar= Ns Ar path
Install from the tarball located at the given
.Ar path .
.Pp
Note that if you plan to build any port containing kernel modules then the
specified tarball has to contain the
.Pa /usr/src
files as well.
.It Cm url= Ns Ar url
Fetch distribution tarballs
.Pq like Pa base.txz
from the given
.Ar url .
Any URL supported by
.Xr fetch 1
can be used.
For example:
.Dq Cm url=file:///mirror/10.0 .
.El
.Pp
Build from source options:
.Bl -tag -width "git[+protocol]"
.It Cm git Ns Op Cm + Ns Ar protocol
Use Git to download the sources.
.Pp
Sources will be cloned shallowly unless
.Fl D
is specified.
.Pp
Output will mostly be hidden unless
.Cm poudriere -v jail
is used.
.Pp
Use the
.Fl v Ar branch
parameter to set the branch name when creating a jail.
.Pp
Use the
.Fl t Ar branch
parameter to switch the branch when updating a jail.
.Pp
The Git server address is derived from the
.Va GIT_BASEURL
variable in
.Pa poudriere.conf .
.Fl U Ar url
may be used to override that value.
.Pp
The following protocols are supported:
.Cm git No (default), Cm +http Ns , Cm +https Ns , Cm +file Ns , Cm +ssh Ns .
.It Cm src= Ns Ar path
Copy the source tree from
.Ar path
into the jail,
and build it.
This option is meant to be used with the
.Fl b
flag.
.It Cm svn Ns Op Cm + Ns Ar protocol
Use SVN to download the sources.
.Pp
Output will mostly be hidden unless
.Cm poudriere -v jail
is used.
.Pp
Use the
.Fl v Ar branch
parameter to set the branch name.
.Pp
Use the
.Fl t Ar branch
parameter to switch the branch when updating a jail.
.Pp
The SVN host address is derived from the
.Va SVN_HOST
variable in
.Pa poudriere.conf .
.Fl U Ar url
may be used to override that value.
.Pp
The following protocols are supported:
.Cm svn No (default), Cm +http Ns , Cm +https Ns , Cm +file Ns , Cm +ssh Ns .
.El
.It Fl n
When combined with
.Fl l ,
only display jail name.
.It Fl P Ar patch
Apply the specified
.Ar patch
to the source tree before building the jail.
.It Fl p Ar portstree
Specify the ports tree to start/stop the jail with.
.Pq Default: Dq Li default
.It Fl q
Remove the header when
.Fl l
is the specified mandatory option.
Otherwise, it has no effect.
.It Fl S Ar srcpath
Use the specified
.Ar srcpath
as the
.Fx
source tree mounted inside the jail
or from the host for
.Fl m Cm null .
.It Fl t Ar version
Upgrade the jail to the specified
.Ar version
instead of upgrading to the latest security fix.
.It Fl U Ar url
Specifies which url to checkout from when using the
.Cm git
or
.Cm svn
methods.
.It Fl v Ar version
Specify the
.Ar version
of
.Fx
to use in the jail.
For most methods, and by default if no
.Fl m
is specified,
.Ar version
should in the form of
.Dq Cm 12.0-RELEASE .
If you are using
.Fl m Cm git ,
or
.Fl m Cm svn ,
then the
.Ar version
should be in the form of Git or SVN branches, which is usually
in the form of
.Dq Cm stable/9
or
.Dq Cm main
for CURRENT from git.
Other methods only use the
.Ar version
value for display.
.It Fl 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 different.
.It Fl y
Do not prompt for confirmation when deleting a jail.
.It Fl z Ar set
This specifies which set to start/stop the jail with.
.El
.Bl -tag -width FETCH_BIND_ADDRESS
.It Ev FETCH_BIND_ADDRESS
The bind address used by
.Xr fetch 1 .
See
.Xr fetch 3
for more details.
.It Ev HTTP_PROXY HTTP_* http_* FTP_PROXY FTP_* http_* SSL_* NO_PROXY no_proxy
The proxy configuration for
.Xr fetch 1 .
See
.Xr fetch 3
for other supported proxy environment variables.
.It Ev MAKEOBJDIRPREFIX
See
.Xr build 7
and the implementation of the
.Nm
command for more details.
.It Ev TERM
Passed through for interactive modes.
.El
.Sh EXAMPLES
.Bl -tag -width 0n
.It Sy Example 1\&: No Creating New Jail
.Pp
The following example creates a new amd64 jail called
.Dq 120amd64 ,
that is based on
.Fx 12.0-RELEASE .
.Bd -literal -offset 2n
.Li # Ic poudriere jail -c -j 120amd64 -v 12.0-RELEASE -a amd64
.Ed
.It Sy Example 2\&: No Checking If a Jail Already Exists
.Pp
The following command returns success if a poudriere jail called
.Dq 112i386
already exists.
.Bd -literal -offset 2n
.Li # Ic poudriere jail -l -n -q | grep --quiet '^112i386$'
.Ed
.El
.Sh SEE ALSO
.Xr jail 8 ,
.Xr poudriere 8 ,
.Xr poudriere-bulk 8 ,
.Xr poudriere-distclean 8 ,
.Xr poudriere-image 8 ,
.Xr poudriere-logclean 8 ,
.Xr poudriere-options 8 ,
.Xr poudriere-pkgclean 8 ,
.Xr poudriere-ports 8 ,
.Xr poudriere-queue 8 ,
.Xr poudriere-status 8 ,
.Xr poudriere-testport 8 ,
.Xr poudriere-version 8
.Sh AUTHORS
.An Baptiste Daroussin Aq bapt@FreeBSD.org
.An Bryan Drewery Aq bdrewery@FreeBSD.org
.Sh CAVEATS
.Ss Jail Names
The values set with the
.Fl j ,
.Fl z ,
and
.Fl p
flags
are all used directly in the name of the jail created by poudriere.
.Pp
Be careful to respect the names supported by jail(8):
.Bd -literal -offset indent
This is an arbitrary string that identifies a jail (except it
may not contain a '.').
.Ed