jailkit(8)jailkitjailkit(8)NAMEjailkit - utilities for jailing a user or process
DESCRIPTION
Jailkit is a set of utilities that can limit user accounts to a spe‐
cific directory tree and to specific commands. Setting up a jail is
much easier using the jailkit utilities that doing so 'by hand'. A jail
is a directory tree that you create within your file system; the user
cannot see any directories or files that are outside the jail direc‐
tory. The user is jailed in that directory and it subdirectories. The
chroot(2) system call is used by jailkit to put the user inside the
jail.
If you want the user to be able to do just one thing, you can set up
the jail so that the user is able to do exactly and only that one
thing. For example, if you want the user to be able to run scp, you
install a copy of scp in the jail along with just enough support to
execute it (e.g., using a limited shell). As you can understand, the
fewer executables you have in a jail (and the more their capabilities
are limited such as using strict configurations), the more work a
hacker needs to break out of it. It is important to note that a chroot
jail can be easily escaped if the user is able to elevate to the root
level, so it's very important to prevent the user from doing so.
In this summary, the top-level directory of the jail is referred to as
JAIL. You can configure the JAIL to be any suitable directory (e.g.,
your JAIL may be /usr/local/chrootjail or /home/chroot). The JAIL
directory should obviously be chosen so as not collide or interfere
with other standard directories (e.g., it's probably a bad idea to use
/home/chroot as the JAIL and also create a user named 'chroot'). A ref‐
erence to JAIL/etc means "the etc/ subdirectory in your top-level jail
directory". From the jailed user's point of view, the top-level jail
directory is "/".
SECURITY CONSIDERATIONS
A badly configured jail is a security risk!
If a jailed user or a jailed process can modify files in (for example)
the JAIL/lib/ or JAIL/etc/ directory (i.e., those within the jail
directory), the user can bypass security checks and gain root privi‐
leges.
No directory inside the jail except for the user's home directory or
tmp should be writable by the user. Especially the root of the jail
should not be writable by the user. Jailkit utilities can be used to
perform some basic checks to verify that a jail is secure and abort if
a jail is not secure. Check your logfiles if things don't work as
expected.
The super user (root), or any process running with root privileges, can
always break out of a jail. It is therefore important that the pro‐
cesses inside the jail do not have root privileges, nor have the means
to receive those privileges. Avoid setuid (+s) executables inside the
jail. If the jail is on a separate filesystem, the jail filesystem can
mounted with the nosuid flag.
CONTENTS
This section gives summary sketches of the various programs that com‐
prise jailkit. For details on how a program operates and is configured,
read the reference pages of each program.
jk_init can be used to quickly create a jail with several files or
directories needed for a specific task or profile. Creating the same
jail over and over again is easily automated with jk_init. There are
many tasks in /etc/jailkit/jk_init.ini predefined that work on Debian
or Ubuntu systems. For other platforms you might need to update the
predefined configuration. For example, you can use jk_init to quickly
set up a limited shell, a jail to run apache, or a jail for just sftp
and scp. It will copy the binaries, the required libraries (and related
symlinks) as well as other files such as /etc/passwd. These are all
copied into the jail directory so that a jailed process can run them.
jk_cp can be used to copy a file or device into a jail. Each file or
device is copied with the same permissions with the exception that any
setuid or setgid permissions are removed. If the file is a binary exe‐
cutable, the libraries required to execute it (as reported by ldd) are
copied as well.
jk_chrootsh is a shell that jails a user in a specific directory,
called the JAIL. It does this using the chroot(2) (change root) system
call. This makes the filesystem 'above' the JAIL directory inaccessible
to the user. Because the user can no longer access directories such as
/usr/bin that are accessible to a 'non-jailed' user, the JAIL directory
must recreate enough of a file system to allow the jailed user to exe‐
cute programs. For example, the JAIL directory typically contains a
lib/ directory to contain shared libraries, and it normally has a etc/
directory to contain a minimal set of files such as etc/passwd (though
this passwd file contains only a few key entries, not all those of the
'real' /etc/passwd). The jk_chrootsh program is normally installed as
the user's shell (replacing /bin/bash) in the 'real' /etc/passwd file.
When the user logs in, jk_chrootsh is executed as the user's shell. The
jk_chrootsh enacts the chroot into the JAIL directory. It then reads
the passwd file found within the JAIL (i.e., JAIL/etc/passwd ), obtains
the program to be run as the user's shell (typically jk_lsh, the lim‐
ited shell), and executes it within the jail. This combination limits
the user's file system access to the JAIL directory (implemented by
jk_chrootsh) and limits which programs the user is allowed to execute
(implemented by jk_lsh).
jk_lsh is a limited shell that allows only those commands to be exe‐
cuted as specified in its configuration file. /etc/jailkit/jk_lsh.ini.
It is typically started in one of two ways, by specifying it as the
user's shell or by using the jk_chrootsh program. The first way is
implemented by specifying jk_lsh as the shell in the user's entry in
the 'real' /etc/passwd file. In this case, it executes in the normal
file system and reads its configuration from /etc/jailkit/jk_lsh.ini.
In the second way, jk_lsh is started from within jk_chrootsh by speci‐
fying it as the shell in the passwd file located inside the JAIL direc‐
tory: JAIL/etc/passwd, in which case it reads its configuration from
within the JAIL: JAIL/etc/jailkit/jk_lsh.ini. The latter is the recom‐
mended approach for highest security. Use this program if you want to
deny regular shell access (e.g. logins) but you want to allow execution
of only one or a few commands such sftp, scp, rsync, or cvs.
jk_uchroot is a utility to give regular users access to the chroot(2)
(change root) system call in a safe way. Which users are allowed in
which jails is controlled from /etc/jailkit/jk_uchroot.ini Use this
utility for users that can run processes both inside a jail and outside
a jail.
jk_socketd is a daemon that allows logging safely to syslog from within
a jail. It limits the logging rate based on parameters set in its con‐
figuration file: /etc/jailkit/jk_socketd.ini
jk_chrootlaunch is a utility to start a daemon that cannot do a
chroot(2) call itself in a jail. It can change the user and group id
after jailing the process, and before executing the daemon.
jk_jailuser is a tool to move an existing user account into a jail.
This moves the user's entire home directory (and subdirectories) into
the appropriate place in the JAIL directory (e.g., JAIL/home/someuser).
jk_check is a jail integrity checker. It checks a jail for some of the
potential security problems. (Obviously it does not check all possible
weaknesses.) It reports any setuid and setgid programs, checks for any
modified programs, checks for world writable directories, and more. It
is configured by /etc/jailkit/jk_check.ini
jk_list lists all jailed processes on a system, showing the PID, UID,
and the jail directory.
jk_procmailwrapper is a wrapper for procmail. For regular users, it
runs procmail and allows access to their normal .procmailrc file. For
jailed users, it runs procmail and allows access only to the jailed
.procmailrc (e.g., JAIL/home/someuser/.procmailrc). In the latter case,
procmail must be available inside the jail.
jk_update is a tool to update files inside a jail according to updates
on the real system.
EXAMPLE
Suppose you wish to create an account 'test' that is permitted to exe‐
cute only sftp and scp. Assume you also want it contained in a jail
called /home/sftproot, in which it has a home directory /home/test (as
seen by processes run by user 'test'; the actual directory will be
JAIL/home/test).
# Initialise the jail
mkdir /home/sftproot
chown root:root /home/sftproot
chmod 0755 /home/sftproot
jk_init -j /home/sftproot jk_lsh
jk_init -j /home/sftproot sftp
jk_init -j /home/sftproot scp
# Create the account
jk_addjailuser -j /home/sftproot test
# Edit the jk_lsh configfile in the jail; see man jk_lsh.
# You can use every editor you want; I choose 'joe'
joe /home/sftproot/etc/jailkit/jk_lsh.ini
# Restart jk_socketd so that log messages are transferred
killall jk_socketd
jk_socketd
# Test the account
sftp test@localhost
# Check the logs to see if everything is correct
tail /var/log/daemon.log /var/log/auth.log
FILES
The jailkit configuration files are located in /etc/jailkit/ Note that
in some cases the configuration files must be replicated into the
JAIL/etc/jailkit directory and edited appropriately. A jk program that
is run within the jail directory is able to read its configuration from
only the jailed etc/jailkit directory.
SEE ALSOjk_check(8)jk_chrootlaunch(8)jk_chrootsh(8)jk_cp(8)jk_init(8)jk_jailuser(8)jk_list(8)jk_lsh(8)jk_procmailwrapper(8)jk_socketd(8)jk_uchroot(8)jk_update(8)chroot(2)COPYRIGHT
Copyright (C) 2003, 2004, 2005, 2006, 2007, 2009 Olivier Sessink
Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.
JAILKIT 07-02-2010 jailkit(8)
