1.\" Copyright (c) 1999 Poul-Henning Kamp. 2.\" All rights reserved. |
3.\"
|
2.\" ----------------------------------------------------------------------------
3.\" "THE BEER-WARE LICENSE" (Revision 42):
4.\" <phk@FreeBSD.ORG> wrote this file. As long as you retain this notice you
5.\" can do whatever you want with this stuff. If we meet some day, and you think
6.\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp
7.\" ----------------------------------------------------------------------------
|
4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. |
12.\"
|
9.\" $FreeBSD: head/lib/libc/sys/jail.2 186834 2009-01-06 18:10:17Z bz $
|
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. |
24.\"
|
25.\" $FreeBSD: head/lib/libc/sys/jail.2 191668 2009-04-29 16:02:52Z jamie $ 26.\" |
27.Dd January 6, 2009 28.Dt JAIL 2 29.Os 30.Sh NAME 31.Nm jail , jail_attach 32.Nd imprison current process and future descendants 33.Sh LIBRARY 34.Lb libc 35.Sh SYNOPSIS 36.In sys/param.h 37.In sys/jail.h 38.Ft int 39.Fn jail "struct jail *jail" 40.Ft int 41.Fn jail_attach "int jid" 42.Sh DESCRIPTION 43The 44.Fn jail 45system call sets up a jail and locks the current process in it. 46.Pp 47The argument is a pointer to a structure describing the prison: 48.Bd -literal -offset indent 49struct jail { 50 u_int32_t version; 51 char *path; 52 char *hostname; 53 char *jailname; 54 unsigned int ip4s; 55 unsigned int ip6s; 56 struct in_addr *ip4; 57 struct in6_addr *ip6; 58}; 59.Ed 60.Pp 61.Dq Li version 62defines the version of the API in use. 63.Dv JAIL_API_VERSION 64is defined for the current version. 65.Pp 66The 67.Dq Li path 68pointer should be set to the directory which is to be the root of the 69prison. 70.Pp 71The 72.Dq Li hostname 73pointer can be set to the hostname of the prison. 74This can be changed 75from the inside of the prison. 76.Pp 77The 78.Dq Li jailname 79pointer is an optional name that can be assigned to the jail 80for example for managment purposes. 81.Pp 82The 83.Dq Li ip4s 84and 85.Dq Li ip6s 86give the numbers of IPv4 and IPv6 addresses that will be passed 87via their respective pointers. 88.Pp 89The 90.Dq Li ip4 91and 92.Dq Li ip6 93pointers can be set to an arrays of IPv4 and IPv6 addresses to be assigned to 94the prison, or NULL if none. 95IPv4 addresses must be in network byte order. 96.Pp 97The 98.Fn jail_attach 99system call attaches the current process to an existing jail, 100identified by 101.Fa jid . 102.Sh RETURN VALUES 103If successful, 104.Fn jail 105returns a non-negative integer, termed the jail identifier (JID). 106It returns \-1 on failure, and sets 107.Va errno 108to indicate the error. 109.Pp 110.Rv -std jail_attach 111.Sh PRISON? 112Once a process has been put in a prison, it and its descendants cannot escape 113the prison. 114.Pp 115Inside the prison, the concept of 116.Dq superuser 117is very diluted. 118In general, 119it can be assumed that nothing can be mangled from inside a prison which 120does not exist entirely inside that prison. 121For instance the directory 122tree below 123.Dq Li path 124can be manipulated all the ways a root can normally do it, including 125.Dq Li "rm -rf /*" 126but new device special nodes cannot be created because they reference 127shared resources (the device drivers in the kernel). 128The effective 129.Dq securelevel 130for a process is the greater of the global 131.Dq securelevel 132or, if present, the per-jail 133.Dq securelevel . 134.Pp 135All IP activity will be forced to happen to/from the IP number specified, 136which should be an alias on one of the network interfaces. 137All connections to/from the loopback address 138.Pf ( Li 127.0.0.1 139for IPv4, 140.Li ::1 141for IPv6) will be changed to be to/from the primary address 142of the jail for the given address family. 143.Pp 144It is possible to identify a process as jailed by examining 145.Dq Li /proc/<pid>/status : 146it will show a field near the end of the line, either as 147a single hyphen for a process at large, or the hostname currently 148set for the prison for jailed processes. 149.Sh ERRORS 150The 151.Fn jail 152system call 153will fail if: 154.Bl -tag -width Er 155.It Bq Er EINVAL 156The version number of the argument is not correct. 157.It Bq Er EAGAIN 158No free JID could be found. 159.El 160.Pp 161Further 162.Fn jail 163calls 164.Xr chroot 2 165internally, so it can fail for all the same reasons. 166Please consult the 167.Xr chroot 2 168manual page for details. 169.Sh SEE ALSO 170.Xr chdir 2 , 171.Xr chroot 2 172.Sh HISTORY 173The 174.Fn jail 175system call appeared in 176.Fx 4.0 . 177The 178.Fn jail_attach 179system call appeared in 180.Fx 5.1 . 181.Sh AUTHORS 182The jail feature was written by 183.An Poul-Henning Kamp 184for R&D Associates 185.Dq Li http://www.rndassociates.com/ 186who contributed it to 187.Fx .
|