jailkit(8)                                                    jailkit                                                    jailkit(8)

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  direc‐
       tory". 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  impor‐
       tant  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.

CONTENTS
       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. Creat‐
       ing  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 ex‐
       ception that any setuid or setgid permissions are removed. If the file is a binary executable, the libraries required to ex‐
       ecute 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_ch‐
       rootsh 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  ac‐
       cess  to  the  JAIL  directory (implemented by jk_chrootsh) and limits which programs the user is allowed to execute (imple‐
       mented 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  parame‐
       ters 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  subdi‐
       rectories) 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 .proc‐
       mailrc  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 con‐
       tained 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 repli‐
       cated 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 ALSO
       jk_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)