Chapter 4. The Jail Subsystem

In jail.c, the first thing I would note is the declaration of an important structure struct jail j; which was included from /usr/include/sys/jail.h.

The definition of the jail structure is:

As you can see, there is an entry for each of the arguments passed to the jail(8) program, and indeed, they are set during its execution.

One of the arguments passed to the jail(8) program is an IP address with which the jail can be accessed over the network. jail(8) translates the IP address given into host byte order and then stores it in j (the jail structure).

The inet_aton(3) function "interprets the specified character string as an Internet address, placing the address into the structure provided." The ip_number member in the jail structure is set only when the IP address placed onto the in structure by inet_aton(3) is translated into host byte order by ntohl(3).

Finally, the userland program jails the process. Jail now becomes an imprisoned process itself and then executes the command given using execv(3).

As you can see, the jail() function is called, and its argument is the jail structure which has been filled with the arguments given to the program. Finally, the program you specify is executed. I will now discuss how jail is implemented within the kernel.

In kern_jail.c, the following sysctls are defined:

Each of these sysctls can be accessed by the user through the sysctl(8) program. Throughout the kernel, these specific sysctls are recognized by their name. For example, the name of the first sysctl is security.jail.set_hostname_allowed.

Like all system calls, the jail(2) system call takes two arguments, struct thread *td and struct jail_args *uap. td is a pointer to the thread structure which describes the calling thread. In this context, uap is a pointer to the structure in which a pointer to the jail structure passed by the userland jail.c is contained. When I described the userland program before, you saw that the jail(2) system call was given a jail structure as its own argument.

Therefore, uap→jail can be used to access the jail structure which was passed to the system call. Next, the system call copies the jail structure into kernel space using the copyin(9) function. copyin(9) takes three arguments: the address of the data which is to be copied into kernel space, uap→jail, where to store it, j and the size of the storage. The jail structure pointed by uap→jail is copied into kernel space and is stored in another jail structure, j.

There is another important structure defined in jail.h. It is the prison structure. The prison structure is used exclusively within kernel space. Here is the definition of the prison structure.

The jail(2) system call then allocates memory for a prison structure and copies data between the jail and prison structure.

Next, we will discuss another important system call jail_attach(2), which implements the function to put a process into the jail.

This system call makes the changes that can distinguish a jailed process from those unjailed ones. To understand what jail_attach(2) does for us, certain background information is needed.

On FreeBSD, each kernel visible thread is identified by its thread structure, while the processes are described by their proc structures. You can find the definitions of the thread and proc structure in /usr/include/sys/proc.h. For example, the td argument in any system call is actually a pointer to the calling thread’s thread structure, as stated before. The td_proc member in the thread structure pointed by td is a pointer to the proc structure which represents the process that contains the thread represented by td. The proc structure contains members which can describe the owner’s identity(p_ucred), the process resource limits(p_limit), and so on. In the ucred structure pointed by p_ucred member in the proc structure, there is a pointer to the prison structure(cr_prison).

In kern_jail.c, the function jail() then calls function jail_attach() with a given jid. And jail_attach() calls function change_root() to change the root directory of the calling process. The jail_attach() then creates a new ucred structure, and attaches the newly created ucred structure to the calling process after it has successfully attached the prison structure to the ucred structure. From then on, the calling process is recognized as jailed. When the kernel routine jailed() is called in the kernel with the newly created ucred structure as its argument, it returns 1 to tell that the credential is connected with a jail. The public ancestor process of all the process forked within the jail, is the process which runs jail(8), as it calls the jail(2) system call. When a program is executed through execve(2), it inherits the jailed property of its parent’s ucred structure, therefore it has a jailed ucred structure.

When a process is forked from its parent process, the fork(2) system call uses crhold() to maintain the credential for the newly forked process. It inherently keep the newly forked child’s credential consistent with its parent, so the child process is also jailed.