Ubuntu Manpage: jailkit - utilities for jailing a user or process

name
description
security considerations
contents
example
files
see also
copyright

NAME

       jailkit - utilities for jailing a user or process

DESCRIPTION

Jailkit is a set of utilities that can limit user accounts to a specific 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 directory. 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
reference 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
       privileges.

       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 processes 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.

This section gives summary sketches of the various programs that comprise 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
executable, 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
execute 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 limited
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 executed 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 specifying it as the shell in the passwd file located inside the
JAIL directory: JAIL/etc/passwd, in which case it reads its configuration from within the JAIL:
JAIL/etc/jailkit/jk_lsh.ini. The latter is the recommended 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 configuration 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 execute 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
       # Move the account into the jail
       jk_jailuser -j /home/sftproot -s /usr/bin/jk_lsh -m 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
       # or if you use systemd
       journalctl --since=-1h

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.

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.