Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
jailkit(8)			    jailkit			    jailkit(8)

       jailkit - utilities for jailing a user or process

       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

       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 in-
       stall  a	copy of	scp in the jail	along with just	enough support to exe-
       cute 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 di-
       rectory 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 "/".

       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  di-
       rectory), 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 ex-

       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.

       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 di-
       rectories 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	prede-
       fined 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  sym-
       links) 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  im-
       plemented  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 con-
       figuration file:	/etc/jailkit/jk_socketd.ini

       jk_chrootlaunch is a utility to start a daemon that  cannot  do	a  ch-
       root(2)	call itself in a jail. It can change the user and group	id af-
       ter 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.

       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

       # 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
       # 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

       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.

       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 (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 no-
       tice and	this notice are	preserved.

JAILKIT				  07-02-2010			    jailkit(8)


Want to link to this manual page? Use this URL:

home | help