usr.sbin/chroot/chroot.8

   1 .\" Copyright (c) 1988, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   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 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)chroot.8    8.1 (Berkeley) 6/9/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd July 20, 2021
  32 .Dt CHROOT 8
  33 .Os
  34 .Sh NAME
  35 .Nm chroot
  36 .Nd change root directory
  37 .Sh SYNOPSIS
  38 .Nm
  39 .Op Fl G Ar group Ns Op Cm \&, Ns Ar group  ...
  40 .Op Fl g Ar group
  41 .Op Fl u Ar user
  42 .Op Fl n
  43 .Ar newroot
  44 .Op Ar command Op Ar arg ...
  45 .Sh DESCRIPTION
  46 The
  47 .Nm
  48 utility changes its current and root directories to the supplied directory
  49 .Ar newroot
  50 and then exec's
  51 .Ar command
  52 with provided arguments, if supplied,
  53 or an interactive copy of the user's login shell.
  54 .Pp
  55 The options are as follows:
  56 .Bl -tag -width "-G group[,group ...]"
  57 .It Fl G Ar group Ns Op Cm \&, Ns Ar group  ...
  58 Run the command with the permissions of the specified groups.
  59 .It Fl g Ar group
  60 Run the command with the permissions of the specified
  61 .Ar group .
  62 .It Fl u Ar user
  63 Run the command as the
  64 .Ar user .
  65 .It Fl n
  66 Use the
  67 .Dv PROC_NO_NEW_PRIVS_CTL
  68 .Xr procctl 2
  69 command before chrooting, effectively disabling SUID/SGID bits
  70 for the calling process and its descendants.
  71 If
  72 .Dv security.bsd.unprivileged_chroot
  73 sysctl is set to 1, it will make it possible to chroot without
  74 superuser privileges.
  75 .El
  76 .Sh ENVIRONMENT
  77 The following environment variable is referenced by
  78 .Nm :
  79 .Bl -tag -width "SHELL"
  80 .It Ev SHELL
  81 If set,
  82 the string specified by
  83 .Ev SHELL
  84 is interpreted as the name of
  85 the shell to exec.
  86 If the variable
  87 .Ev SHELL
  88 is not set,
  89 .Pa /bin/sh
  90 is used.
  91 .El
  92 .Sh EXAMPLES
  93 .Bl -tag -width 0n
  94 .It Sy Example 1\&: No Chrooting into a New Root Directory
  95 .Pp
  96 The following command opens the
  97 .Xr csh 1
  98 shell after chrooting to the standard root directory.
  99 .Bd -literal -offset 2n
 100 .Li # Ic chroot / /bin/csh
 101 .Ed
 102 .It Sy Example 2\&: No Execution of a Command with a Changed Root Directory
 103 .Pp
 104 The following command changes a root directory with
 105 .Nm
 106 and then runs
 107 .Xr ls 1
 108 to list the contents of
 109 .Pa /sbin .
 110 .Bd -literal -offset 2n
 111 .Li # Ic chroot /tmp/testroot ls /sbin
 112 .Ed
 113 .El
 114 .Sh SEE ALSO
 115 .Xr chdir 2 ,
 116 .Xr chroot 2 ,
 117 .Xr setgid 2 ,
 118 .Xr setgroups 2 ,
 119 .Xr setuid 2 ,
 120 .Xr getgrnam 3 ,
 121 .Xr environ 7 ,
 122 .Xr jail 8
 123 .Sh HISTORY
 124 The
 125 .Nm
 126 utility first appeared in
 127 .At III
 128 and
 129 .Bx 4.3 Reno .