Create a PostgreSQL jail in Freenas 11 using iocage

This tutorial covers creating a jail to run PostgreSQL in a jail using the iocage commands.

IX Systems  introduced the iocage jail management system to replace the warden based system. I’m running FreeNAS 11.1. which still has the Warden method in the web interface, however the iocage framework is available if you are prepared to use the command line.

Before starting, a couple of caveats:

  1. FreeNAS is a NAS, not a general purpose, or dedicated database server. I use this on a small system to support a couple of small apps which need a “proper” database back-end. It also gives a small personal database server to for small dev tasks.
  2. Follow these instructions at your own risk

Set up iocage

Before you can start using iocage, there are some simple housekeeping/initialisation steps to perform to prepare the system.

Decide on the volume you want to install the jails to.  I created a simple mirror set for the jails called (unimaginatively) jails.

The first command tells iocage where I want to place everything.

iocage set jail_zfs_dataset=jails/iocage

Replace jails with the name of your dataset. This will return to the prompt immediately.

Next step is to activate the jails environment and then fetch the jail images that will be used to create the jails.  The two commands needed are “activate” and “fetch”.

Fetch will also make a good choice for the release that you need (in this case 11.1, which matches the version of FreeNAS).

[root@freenas /mnt/Data]# iocage activate jails
ZFS pool 'jails' successfully activated.
[root@freenas /mnt/Data]# iocage fetch
[0] 9.3-RELEASE (EOL)
[1] 10.1-RELEASE (EOL)
[2] 10.2-RELEASE (EOL)
[3] 10.3-RELEASE (EOL)
[4] 10.4-RELEASE
[5] 11.0-RELEASE (EOL)
[6] 11.1-RELEASE
[7] 11.2-RELEASE

Type the number of the desired RELEASE
Press [Enter] to fetch the default selection: (11.1-RELEASE)
Type EXIT to quit: 
Fetching: 11.1-RELEASE

Downloading : MANIFEST [####################] 100% 
Downloading : base.txz [####################] 100% 
Downloading : lib32.txz [####################] 100% 
Downloading : doc.txz [####################] 100% 
Downloading : src.txz [####################] 100% 
Extracting: base.txz... 
Extracting: lib32.txz... 
Extracting: doc.txz... 
Extracting: src.txz... 
<snip ...... lots of output here> 
[root@freenas /mnt/Data]#

The fetching process may take a while depending on the speed of your connection.

Create the jail

Now create the basic part of the jail.

The things you will need to check are you IP address (please don’t blindly copy from the example). You will also need to use your Ethernet adapter name. Run the ifconfig command to find the name of the adapter.

This is all the information you need to create the basic jail.

[root@freenas /mnt/Data/home/tim]# iocage create -n database_02 ip4_addr="re0|" -r 11.1-RELEASE
database_02 successfully created!

Now let’s check  if it is there.

[root@freenas /mnt/Data/]# iocage list
| JID |  NAME       | STATE | RELEASE      | IP4           |
| -   | database_02 | down  | 11.1-RELEASE | |

The JID column is empty. When the jail is running this will have the jail ID (ie JID).

Now the moment of truth – Let’s start it up

[root@freenas /mnt/Data/]# iocage start da
* Starting database_02
+ Started OK
+ Starting services OK
[root@freenas /mnt/Data/]# iocage list
| JID | NAME        | STATE | RELEASE      | IP4          |
| 1   | database_02 | up    | 11.1-RELEASE | |

You’ll notice that rather than writing database, I just wrote da. One of the nice features of iocage is that you can abbreviate the jail names to the minimum unique start of the name. Provided I don’t create a called “database_03” etc, I’ll be able to use the very short version of the name.

To get into the jail, we start a console session.

root@freenas /mnt/Data/]# iocage console da
FreeBSD 11.1-STABLE (FreeNAS.amd64) #0 r321665+9902d126c39(freenas/11.1-stable): Tue Aug 21 12:24:37 EDT 2018

Welcome to FreeBSD!

Release Notes, Errata:
Security Advisories:
FreeBSD Handbook:
Questions List:
FreeBSD Forums:

Documents installed with the system are in the /usr/local/share/doc/freebsd/
directory, or can be installed later with: pkg install en-freebsd-doc
For other languages, replace "en" with a language code like de or fr.

Show the version of FreeBSD installed: freebsd-version ; uname -a
Please include that output and any error messages when posting questions.
Introduction to manual pages: man man
FreeBSD directory layout: man hier

Edit /etc/motd to change this login announcement
root@database_02:~ #

You are now in the jail.

You will see that there is a large MOTD (message of the day) message. This is the default message that’s written  when you create the jail. As you can see, the last line tells you which file to edit to change this. This is a simple text file. Probably the easiest and simplest replacement is a couple of lines saying the name of the jail, so you get a reminder when you connect to it.

Installing PostgreSQL

We’re going to use the package system to install the database. This is the easiest and quickest way to get the server installed. run the

root@database_02:~ # pkg update

command to bootstrap the package management. This will take a few minutes to download the latest details. You may also get a message say that you need to update the pkg command. If you get this, answer “Yes”.

Once the update has completed, have a look to see which versions of PostgreSQL are available using the search command.

root@database_02:~ # pkg search postgres

will show all the versions.  I needed 9.4 so I ran a search for this version.

root@database_02:~ # pkg search postgresql94
pgtcl-postgresql94-2.1.1 TCL extension for accessing a PostgreSQL server (PGTCL-NG)
postgresql94-client-9.4.18 PostgreSQL database (client)
postgresql94-contrib-9.4.18 The contrib utilities from the PostgreSQL distribution
postgresql94-docs-9.4.18 The PostgreSQL documentation set
postgresql94-plperl-9.4.18 Write SQL functions for PostgreSQL using Perl5
postgresql94-plpython-9.4.18 Module for using Python to write SQL functions
postgresql94-pltcl-9.4.18 Module for using Tcl to write SQL functions
postgresql94-server-9.4.18 PostgreSQL is the most advanced open-source database available anywhere

and this returned just the 9.4 packages.

To install the server, contrib and client packages, run the install command. Replace the 94 with the version that you want. If you need the various language support packages (plperl, plpython etc), you can add these as well.

The basic install looks like this

root@database_02:~ # pkg install postgresql94-server postgresql94-client postgresql94-contrib

or you can install all the packages

root@database_02:~ # pkg install postgresql94-server postgresql94-client postgresql94-contrib postgresql94-plperl postgresql94-plpython postgresql94-pltcl

All the required dependencies will be installed as well.

Once the packages are installed, initialise the database system and then make sure the database system starts when the jail starts

root@database_02:~ # usr/local/etc/rc.d/postgresql initdb
<lots of messages>
root@database_02:~ # sysrc postgresql_enable="YES"

(or you directly edit the /etc/rc.conf file yourself and add the line postgresql_enable=”YES”)

Log out of the jail by typing exit.

root@database_02:~ # exit

you will now be back at the freenas prompt, where you can stop and restart the jail

[root@freenas /mnt/Data]# iocage restart da
* Stopping database_02
+ Running prestop OK
+ Stopping services OK
+ Removing jail process OK
+ Running poststop OK
* Starting database_02
+ Started OK
+ Starting services OK
[root@freenas /mnt/Data]# iocage list
| JID | NAME        | STATE | RELEASE      | IP4          |
| 2   | database_02 | up    | 11.1-RELEASE | |

You can see that the jail id has increased by 1, but you can get into it by typing “iocage console da” again

go into the console to see if your database is up and running.

root@database_02:~ #su pgsql
$createdb pgsql

psql (9.4.18)
Type "help" for help.pgsql=# \l
List of databases
.... information about your databases shown ....
(4 rows)

you now have an up and running database

Tweaking your jail settings

There are number of useful settings you should consider applying to your jail. These are things like IP6 settings (if required), autostart, the priority and adding a useful comment.

From the Freenas root console (ie. not in the jail)  type

[root@freenas /mnt/Data/]# iocage get -a da
.......... lots of output .........
[root@freenas /mnt/Data/]#

These are all the settings.

The main items of interest are

  • boot: flag to automatically start the jail when FreeNAS starts
  • priority: control the order the the jails start
  • comment: add a descriptive title to the jail
  • domainname: domain name
  • defaultrouter: default route (also defaultrouter6 if you’re using ip6)

The priority is useful if you have a number of jails with dependencies. For example if you had another jail running a web-server that used this database jail to provide its database , you would assign the database jail a higher priority so that it would start before the web-server.

the set command is used to set the properties. The format is

iocage set <attribute name>=<new value> <jail name>

to set some things to finalise the jail we’ve just created you could enter the following.

root@database_02:~ #iocage set boot=on database_02
root@database_02:~ #iocage set priority=10 database_02
root@database_02:~ #iocage set host_domainname="" database_02
root@database_02:~ #iocage set comment="Postgres database server" database_02
root@database_02:~ #iocage set defaultrouter="" database_02

The manual pages provide details of all the other settings. If you need to change the ip address of the jail, this is also done using the set command.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.