lib/libc/sys/jail.2

   1 .\"
   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 .\"----------------------------------------------------------------------------
   8 .\"
   9 .\"$FreeBSD: src/lib/libc/sys/jail.2,v 1.10.2.10 2002/12/12 05:26:38 trhodes Exp $
  10 .\"$DragonFly: src/lib/libc/sys/jail.2,v 1.11 2007/11/21 19:12:40 swildner Exp $
  11 .\"
  12 .Dd April 28, 1999
  13 .Dt JAIL 2
  14 .Os
  15 .Sh NAME
  16 .Nm jail
  17 .Nd imprison current process and future descendants
  18 .Sh LIBRARY
  19 .Lb libc
  20 .Sh SYNOPSIS
  21 .In sys/types.h
  22 .In sys/jail.h
  23 .Ft int
  24 .Fn jail "struct jail *jail"
  25 .Sh DESCRIPTION
  26 The
  27 .Nm
  28 system call sets up a jail and locks the current process in it.
  29 .Pp
  30 The argument is a pointer to a structure describing the prison:
  31 .Bd -literal -offset indent
  32 struct jail {
  33         uint32_t        version;
  34         char            *path;
  35         char            *hostname;
  36         uint32_t        n_ips;
  37         struct sockaddr_storage *ips;
  38 };
  39 .Ed
  40 .Pp
  41 .Dq Li version
  42 defines the version of the API in use.  It should be set to 1 at this time.
  43 .Pp
  44 The
  45 .Dq Li path
  46 pointer should be set to the directory which is to be the root of the
  47 prison.
  48 .Pp
  49 The
  50 .Dq Li hostname
  51 pointer can be set to the hostname of the prison.  This can be changed
  52 from the inside of the prison.
  53 .Pp
  54 .Dq Li n_ips
  55 is the number of IP addresses that are on ips.
  56 .Pp
  57 The
  58 .Dq ips
  59 pointer contains the IP addresses assigned to the jail.
  60 .Sh PRISON
  61 Once a process has been put in a prison, it and its descendants cannot escape
  62 the prison.
  63 A process can be attached to a prison by calling
  64 .Xr jail_attach 2 .
  65 .Pp
  66 Inside the prison, the concept of "superuser" is very diluted.  In general,
  67 it can be assumed that nothing can be mangled from inside a prison which
  68 does not exist entirely inside that prison.  For instance the directory
  69 tree below
  70 .Dq Li path
  71 can be manipulated all the ways a root can normally do it, including
  72 .Dq Li "rm -rf /*"
  73 but new device special nodes cannot be created because they reference
  74 shared resources (the device drivers in the kernel).
  75 .Pp
  76 All IP activity will be forced to happen to/from the IP numbers specified,
  77 which should be an alias on one or more of the network interfaces.
  78 .Pp
  79 It is possible to identify a process as jailed by examining
  80 .Dq Li /proc/<pid>/status :
  81 it will show a field near the end of the line, either as
  82 a single hyphen for a process at large, or the hostname currently
  83 set for the prison for jailed processes.
  84 .Pp
  85 The program
  86 .Xr jls 8
  87 ca be used to identify all active jails.
  88 .Sh RETURN VALUES
  89 If successful, jail() returns a non-negative integer, termed the jail
  90 identifier (JID). It returns -1 on failure, and sets
  91 .Va errno
  92 to indicate the error.
  93 .Sh ERRORS
  94 The
  95 .Fn jail
  96 system call will fail if:
  97 .Bl -tag -width Er
  98 .It Bq Er EINVAL
  99 The version number of the argument is not correct.
 100 .El
 101 .Pp
 102 Further
 103 .Fn jail
 104 calls
 105 .Xr chroot 2
 106 internally, so it can fail for all the same reasons.
 107 Please consult the
 108 .Xr chroot 2
 109 manual page for details.
 110 .Sh SEE ALSO
 111 .Xr chdir 2 ,
 112 .Xr chroot 2 ,
 113 .Xr jail_attach 2 ,
 114 .Xr jail 8 ,
 115 .Xr jexec 8 ,
 116 .Xr jls 8
 117 .Sh HISTORY
 118 The
 119 .Fn jail
 120 function call appeared in
 121 .Fx 4.0 .
 122 .Sh AUTHORS
 123 The jail feature was written by
 124 .An Poul-Henning Kamp
 125 for R&D Associates
 126 .Dq Pa http://www.rndassociates.com/
 127 who contributed it to
 128 .Fx .