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,
  90 .Fn jail
  91 returns a non-negative integer, termed the jail identifier (JID).
  92 It returns -1 on failure, and sets
  93 .Va errno
  94 to indicate the error.
  95 .Sh ERRORS
  96 The
  97 .Fn jail
  98 system call will fail if:
  99 .Bl -tag -width Er
 100 .It Bq Er EINVAL
 101 The version number of the argument is not correct.
 102 .El
 103 .Pp
 104 Further
 105 .Fn jail
 106 calls
 107 .Xr chroot 2
 108 internally, so it can fail for all the same reasons.
 109 Please consult the
 110 .Xr chroot 2
 111 manual page for details.
 112 .Sh SEE ALSO
 113 .Xr chdir 2 ,
 114 .Xr chroot 2 ,
 115 .Xr jail_attach 2 ,
 116 .Xr jail 8 ,
 117 .Xr jexec 8 ,
 118 .Xr jls 8
 119 .Sh HISTORY
 120 The
 121 .Fn jail
 122 function call appeared in
 123 .Fx 4.0 .
 124 .Sh AUTHORS
 125 The jail feature was written by
 126 .An Poul-Henning Kamp
 127 for R&D Associates
 128 .Dq Pa http://www.rndassociates.com/
 129 who contributed it to
 130 .Fx .