From PC-BSD Wiki
Revision as of 09:37, 9 April 2012 by Drulavigne (Talk | contribs)

Jump to: navigation, search

(Sorry for the inconvenience)

Warden® is an easy to use jail management program. Using Warden®, it is possible to create virtual environments which can be used to run services such as Apache, PHP, or MySQL in a secure manner. Each jail is considered to be a unique FreeBSD operating system and whatever happens in that jail will not effect your operating system or other jails running on the system.

Warden® has been redesigned for PC-BSD 9.1, and is now part of Control Panel. Some of the new features in Warden® include:

  • ability to create both traditional FreeBSD jails and (a less secure) ports jail which allows you to use FreeBSD ports/packages and run the resulting applications from your PC-BSD system


Creating a Jail using Warden®

The first time you start Warden®, you will be presented with the main window, een in Figure 7.10b. It will indicate that no jail is selected as none have been created yet.

Figure 7.10b: Initial Warden® Screen


To create your first jail, go to File ➜ New Jail. A jail creation wizard, seen in Figure 7.10c, will launch.

Figure 7.10c: Creating the New Jail


The first screen in the jail creation wizard will prompt you for the following information:

IP Address: this is the address you will use to ssh into the jail and access its contents. Choose an address that is not already in use on your network by another computer or jail. Use your arrow keys to move between the octets of the address as you type it in.

Hostname: you can change the default of "Jailbird" to another value. The hostname must be unique on your network.

Include system source: if you check this box, /usr/src/ will be populated with FreeBSD source. Source is needed if you wish to build world or recompile the kernel within this jail.

Include ports tree: if you check this box, the ports tree will be installed into /usr/ports/. This will allow you to compile FreeBSD ports within this jail.

Start jail at system bootup: if this box is checked, the jail will be started (become available) whenever you boot your main system. If the box is not checked, you can manually start the jail whenever you wish to access it using Warden®.

When you are finished, click the Create button. You will be prompted to set the root password and create a user account for this jail, as seen in Figure 7.10d. Since the jail will be accessible using ssh, both of the passwords should be secure.

Figure 7.10d: Setting the Login Information for the Jail


Once you click the Save button, Warden® will display status messages as it builds the new jail, as seen in Figure 7.10e. When it is finished, a Close button will appear that you can click on to return to the main screen.

Figure 7.10e: Warden® is Creating the New Jail


Once the jail is created, it will be listed in the main screen. In the example shown in Figure 7.10f, there is one jail with an IP address of and a hostname of Jailbird. This jail is currently stopped and it is not set to automatically start when the PC-BSD system boots.

Figure 7.10f: Viewing the Current Status of a Jail


To view the jail's configuration, highlight its entry then select Jails ➜ Configuration. Figure 7.10g shows an example of this jail's configuration:

Figure 7.10g: Viewing a Jail's Configuration


The following information is configurable:

Jail Network Interface: Warden® will automatically select the interface that is connected to the network containing the jail's IP address. In this example, the IP address is on an internal, private network attached to the re0 Ethernet address. Note: Modifications to the system network interface, such as to enable lagg0, may also affect access to the jail. In the case of enabled link aggregation, use lagg0 instead of an individual device (such as re0 for ethernet only).

Jail Directory: this is the directory on the PC-BSD system that contains the jail's filesystem. There will be a sub-directory for each jail with the same name as the jail's IP address. If you ever wish to backup your jail, this is the directory to backup.

Temp Directory this is the directory that will hold any temporary files created by the jail.

To start a jail, right-click its entry and select "Start this Jail" from the menu seen in Figure 7.10h. Once the jail has been started, you will be able to ssh to its IP address using the username and password you configured for the jail. Once you have logged into the jail, you can do anything that you could do on a FreeBSD system. This is a good way to learn how to use FreeBSD without affecting your PC-BSD desktop. The FreeBSD Handbook is a handy reference for learning how to perform almost any task on a FreeBSD system.

Figure 7.10h: Options Available For a Jail


A jail's right-click menu contains the following options:

Start this Jail: will change a jail's Status from Stopped to Running. You will not be able to SSH into a jail until it is Running.

Toggle Autostart: will toggle a jail's Autostart between Disabled (does not automatically start when the PC-BSD system is booted) and Enabled (will start the jail when the PC-BSD system is booted).

Install Inmate into jail: inmates are described in the next section.

View installed packages: will show the output of pkg_info to determine which software, if any, has been installed within the jail.

Export jail to .wdn file: this type of file is described in the Exporting/Importing Jails section.

Delete Jail: this will remove the jail and all of its contents from the PC-BSD system.

Installing Inmates

An inmate is a pre-configured software installation that allows you to quickly get a service up and running within a jail. This feature will be re-implented in 9.1 so that you can add inmates from within Warden®.

Exporting/Importing Jails

Exporting a jail allows you to save the jail (and all of its software, configuration, and files) as a .wdn file. This allows you to quickly clone a pre-configured jail to a new jail.

To create a .wdn file, right-click the jail and select "Export jail to a .wdn file". You will be prompted to choose the directory in which to store the backup. A progress bar will indicate that the backup is in progress. Creating the file may take some time, especially if you have installed src, ports, or software.

NOTE: you should not be logged into the jail while exporting it as Warden® will need to stop the jail in order to back it up. If your jail is running services (e.g. a webserver), you should select to export the jail at a time that will least impact network connections to the jail.

The exported jail will end with a .wdn extension and the filename will be the IP address of the jail.

To create a new jail using the .wdn backup, select File ➜ Import Jail. You will be prompted to browse to the location of the .wdn file. Once selected, you will be prompted whether or not to use the same IP address for the new jail. If you are creating a new jail on the same system that still has the original jail installed, select No and input the IP address for the new jail. However, if you have deleted the original jail or need to restore that same jail on another computer (for example, there was a hardware failure on the system containing the original jail), you can choose to use the same IP address. You will then be prompted whether or not to use the same hostname. Again, only say Yes if that hostname is no longer in use; otherwise, select No and input a unique hostname for the jail. Warden® will then recreate the jail with all of the original settings. Whether or not those settings include the original IP address and hostname depends upon your selections.

Moving a Jail/Changing the IP

One method is to export your jail to a .wdn file as described above, then import this jail but when asked whether to use the same IP (as the filename of the .wdn file, select No and input your new IP address for the jail. The old jail and .wdn file can then be deleted.

A second method is speedier but offers no safety net. As with previous changes to a jail, it must not be running and should not have autostart enabled. As root:

cd /usr/local/warden/jails/
mv your.jail.ip.number/ new.jail.ip.number/

Next (still as root) edit the hosts file inside /usr/local/warden/jails/new.jail.ip.number/etc/ to reflect the change. Modify the line below the name of your jail, from your.jail.ip.number to new.jail.ip.number and resave the file.

Using Warden® from the ncurses Menu

Currently before invoking the warden menu command as root from the shell prompt, if installed from ports there are further steps to prepare for this. Of course these commands assume root (you can su to root to satisfy). Prior to the buildworld command mentioned above (in the other instructions), the defaultworld directory must exist, so create it and any intermediate paths:

mkdir -p /usr/local/warden/worlds/defaultworld/ 

After the buildworld and installworld have completed, additional directories and files are needed:

cp /etc/rc /usr/local/warden/worlds/defaultworld/etc/ 
cp /etc/shells /usr/local/warden/worlds/defaultworld/etc/
cp /etc/rc /usr/local/warden/worlds/defaultworld/etc/
cp /etc/rc.subr /usr/local/warden/worlds/defaultworld/etc/
cp /etc/master.passwd /usr/local/warden/worlds/defaultworld/etc/

If any alternative shells are desired from /usr/local/bin, such as zsh those will need to be copied:

cp /usr/local/bin/zsh /usr/local/warden/worlds/defaultworld/usr/local/bin/

By using the vipw command, it will automatically create two necessary files, pwd.db and spwd.db. Using your existing master.passwd file is a faster way to set things up, but some edits are suggested to avoid possible difficulties (including security issues).

Values are seperated by colon (:) as below:


The line with the root password could look like this:

root:$2a$04$PHzr/Z4FCxL4I.CsIIG6uuJmQIJ7mMe6gnZXO4cYN.dOjXRSu34VW:0:0::0:0:Charlie &:/root:/bin/sh

The line with your username might look like this:


The root password may be removed but not the whole line; remove the entire line with your username during the following edit session:

vipw -d /usr/local/warden/worlds/defaultworld/etc/

One way to have a group file is to copy the existing one from your system, but it may be best to modify it after.

cp /etc/group /usr/local/warden/worlds/defaultworld/etc/

Edit the group file to remove your username from groups wheel and operator, and remove the group named for your username:

vi /usr/local/warden/worlds/defaultworld/etc/group

These preparations help to setup the default world which will be used each time a jail is created, Warden® will copy this default world into the directory named for the IP you choose later. You can add the account you create to the wheel or other groups during account creation steps.

Creating a new jail

The output on your screen should be:

Building new Jail... Please wait...
Installing world...
Installing source...
Installing ports...
Success! Jail created at /usr/local/warden/jails/

Then you should see this message (very briefly) but currently there doesn't seem to be any modifications made to the root password, nor actual entry of a replacement.

Changing local password for root

Which results in this output on your screen:

Username: particleman
Full name: Particle Man
Uid (Leave empty for default): 1001
Login group [particleman]: 
Login group is particleman. Invite particleman into other groups? []: wheel
Login class [default]: 
Shell (sh csh tcsh bash rbash nologin) [sh]: 
Home directory [/home/particleman]: 
Home directory permissions (Leave empty for default): 
Use password-based authentication? [yes]:
Use an empty password? (yes/no) [no]: 
Use a random password? (yes/no) [no]: 
Enter password: 
Enter password again: 
Lock out the account after creation? [no]: 
Username   : particleman
Password   : *****
Full Name  : Particle Man
Uid        : 1001
Class      : 
Groups     : particleman wheel
Home       : /home/particleman
Home Mode  : 
Shell      : /bin/sh
Locked     : no
OK? (yes/no): yes
adduser: INFO: Successfully added (particleman) to the user database.
Add another user? (yes/no): no
Press ENTER to continue

Managing a Jail

Note: If something such as perl will be used/installed within the jail, a proper /dev/null will need to be created. Currently, for this to occur, the jail must be started, but this also may cause the side-effect of incomplete removal of the jail if desired later. Once the jail has been started, the files in /dev will exist and access via ssh or shell session are possible. It appears that the jail must be started prior to every shell access to be sure of /dev/null viability.

Removing a Jail

When deleting a jail, some directories may not be removed as they are protected by the system immutable flag. To remove these, first unset the flag on the affected directory:

chflags -R noschg <directory>

After using that command, the directory can be removed with rm -rf.

Personal tools