1@(#) README 1.3 2001/07/25 10:15:32 2 3chrootuid - run command in restricted environment 4 5Description 6=========== 7 8Chrootuid makes it easy to run a network service at low privilege 9level and with restricted file system access. In the past I used 10this program to run the gopher and www (world-wide web) network 11daemons in a restricted environment: the daemons have access only 12to their own directory tree, and run under a low-privileged userid. 13Nowadays I also use it for proxy servers. The arrangement greatly 14reduces the impact of possible loopholes in network software. 15 16Note: for security reasons, chrootuid uses the passwd and group 17files from *outside* the chroot area. This idea was suggested by 18Douglas Schales of Texas A&M University, now with IBM Research. 19 20This software was initially released in 1993. However, chrootuid 21is still being used after all those years, so I have released a 22slightly updated version with a BSD-style license. The examples 23below are still the original ones. Although the systems don't exist 24anymore, the same ideas still apply. 25 26 Wietse Venema 27 wietse@porcupine.org 28 IBM T.J. Watson Research Center 29 Hawthorne, USA 30 31Installation 32============ 33 34The source of the chrootuid program is small and easy to verify. In 35order to build the program, run "make". If it compiles OK, edit the 36destination pathnames in the Makefile and do a "make install". 37 38Important: chrootuid should *not* be installed set-uid. 39 40Using the chrootuid program 41=========================== 42 43The use of the chrootuid program will be illustrated with the gopher 44service. The examples are easily adapted to www (world-wide web) or any 45other network service. 46 47In the inetd.conf file, make a gopher entry like this: 48 49 gopher stream tcp nowait root /usr/local/lib/gopherd gopherd 50 51If you like to run the daemon under control of my tcp/ip daemon 52wrapper, use the following entry: 53 54 gopher stream tcp nowait root /some/where/tcpd /usr/local/lib/gopherd 55 56On some systems you will have to omit the "root" field, because all 57daemons are executed as root by default. 58 59The file /usr/local/lib/gopherd should be a shell script that is 60maintained by the superuser, because inetd runs the script with root 61privilege. It is this script that runs the real gopher daemon, as an 62unprivileged process, in a restricted environment. Of course you can 63specify any other pathname for the script, as long as it is fully 64controlled by the superuser. 65 66 #!/bin/sh 67 68 exec /usr/local/bin/chrootuid /some/where/gopher nobody \ 69 /bin/gopherd -I -l /tmp/gopher.log \ 70 -o /bin/gopherd.conf \ 71 -c -C /gopherdata 70 72 73I'll describe the contents of this script in some detail: 74 75- Instead of /usr/local/bin/chrootuid, specify the absolute path to the 76installed chrootuid executable. The program is executed by root so the 77path should be fully controlled by the super user. 78 79- Instead of /some/where/gopher, specify the absolute path to your 80gopher directory tree. The gopher daemon will have access only to files 81within this subtree. This arrangement is similar to anonymous FTP. 82 83- The gopher daemon will be executed with the privileges of the "nobody" 84account. You can specify any unprivileged account, as long as it does 85not own any files etc. within the gopher directory tree. The account 86info will be extracted from the regular password database, so there is 87no need for passwd or group files below the gopher directory tree. 88 89- "/bin/gopherd -I -l ..." is the command that will be executed, after 90access to the file system has been restricted to the gopher directory 91tree, and after privileges have been reduced to those of "nobody" (or 92whatever account name you choose). All path names should be absolute 93with respect to the root of the gopher directory tree. Thus, 94/bin/gopherd corresponds to /some/where/gopher/bin/gopherd. 95 96On systems with shared libraries it will be necessary to set up the 97appropriate files in the gopher directory tree. The appendix below 98shows [a slightly edited version of] what we have. It is very similar 99to what one has to set up for anonymous FTP, except that no passwd or 100group files are needed. 101 102Finally, chrootuid reports all problems to the syslog daemon. Have a 103look at your syslog.conf file if you don't know where the errors are 104logged. 105 106Appendix: sample restricted gopher subtree 107========================================== 108 109This example is a slightly edited version of own gopher subtree. Some 110details (shared libs, DNS, and timezone stuff) are specific to SunOS; 111hints are given for Ultrix 4.x. 112 113The restricted gopher subtree is very similar to the tree used for 114anonymous ftp, except that no passwd or group files are needed. The 115example assumes that the tree is located at /some/where/gopher, which 116will sometimes be referred to as ~gopher for brevity. 117 118SunOS notes: the shared libraries in this example are specific to 119SunOS 4.1.1. What you will need depends on the OS release and on the 120compiler used to build the gopher executable (do `ldd gopherd' to find 121out; you'll always need the ld.so runtime linker, though). The example 122assumes that you are running DNS on top of NIS. Otherwise, you will 123need a ~gopher/etc/resolv.conf file. 124 125Ultrix notes: you will need the following files in ~gopher/etc: hosts, 126resolv.conf, svc.conf, svcorder. Just copy them from a DNS client host. 127 128Other systems: it may be necessary to install a ~gopher/etc/resolv.conf 129file so that gopherd can find the domain name server (DNS). 130 131It is convenient to have a symlink ~gopher/some/where/gopher -> ../.. 132so that old pathnames keep working after the installation of chrootuid. 133 134Important: make sure that no files etc. are owned by the unprivileged 135account ("nobody" or whatever you chose). The only exception that we 136permit is the gopherd logfile, because no program depends on it. 137 138~gopher: 139drwxr-sr-x 2 exp 512 Aug 12 13:33 bin 140dr-xr-sr-x 2 exp 512 Oct 12 1992 dev 141drwxr-sr-x 9 exp 512 Aug 9 12:35 gopherdata 142dr-xr-sr-x 2 exp 512 Apr 22 14:24 some 143drwxrwsrwt 2 exp 512 Aug 12 13:48 tmp 144dr-xr-sr-x 4 exp 512 Jan 25 1993 usr 145 146~gopher/bin: 147-rwx--x--x 1 exp 409600 Aug 12 13:39 gopherd 148-rw-r--r-- 1 exp 2299 Jun 15 10:12 gopherd.conf 149 150~gopher/dev: 151crw-rw-rw- 1 exp 3, 12 Oct 12 1992 zero 152 153~gopher/gopherdata: 154<our information data base omitted for brevity> 155 156~gopher/some: 157dr-xr-xr-x 2 exp 512 Apr 22 14:24 where 158 159~gopher/some/where: 160lrwxrwxrwx 1 exp 6 Apr 22 14:24 gopher -> ../../ 161 162~gopher/tmp: 163-rw-r--r-- 1 nobody 220563 Aug 12 14:46 gopher.log 164 165~gopher/usr: 166dr-xr-xr-x 2 exp 512 Oct 12 1992 lib 167dr-xr-xr-x 3 exp 512 Jan 21 1993 share 168 169~gopher/usr/lib: 170-r-xr-xr-x 1 exp 40960 Oct 11 1990 ld.so 171-r-xr-xr-x 1 exp 516096 Oct 12 1990 libc.so.1.6 172 173~gopher/usr/share: 174dr-xr-xr-x 3 exp 512 Jan 21 1993 lib 175 176~gopher/usr/share/lib: 177dr-xr-xr-x 2 exp 512 Jan 21 1993 zoneinfo 178 179~gopher/usr/share/lib/zoneinfo: 180-r--r--r-- 1 exp 590 Oct 11 1990 MET 181-r--r--r-- 1 exp 590 Oct 11 1990 localtime 182