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:
- 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.
- 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  9.3-RELEASE (EOL)  10.1-RELEASE (EOL)  10.2-RELEASE (EOL)  10.3-RELEASE (EOL)  10.4-RELEASE  11.0-RELEASE (EOL)  11.1-RELEASE  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> /usr/share/zoneinfo/Pacific/Tongatapu /usr/share/zoneinfo/zone.tab [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 192.168.1.52 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|192.168.1.52/24" -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 | 192.168.1.52 | +-----+-------------+-------+--------------+---------------+
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 | 192.168.1.52 | +-----+-------------+-------+--------------+--------------+
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: https://www.FreeBSD.org/releases/ Security Advisories: https://www.FreeBSD.org/security/ FreeBSD Handbook: https://www.FreeBSD.org/handbook/ FreeBSD FAQ: https://www.FreeBSD.org/faq/ Questions List: https://lists.FreeBSD.org/mailman/listinfo/freebsd-questions/ FreeBSD Forums: https://forums.FreeBSD.org/ 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.
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 logout
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 | 192.168.1.52 | +-----+-------------+-------+--------------+--------------+
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 psql (9.4.18) Type "help" for help.pgsql=# \l List of databases .... information about your databases shown .... (4 rows) \q
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 CONFIG_VERSION:11 allow_chflags:0 allow_mount:0 allow_mount_devfs:0 allow_mount_nullfs:0 allow_mount_procfs:0 allow_mount_tmpfs:0 allow_mount_zfs:0 allow_quotas:0 .......... lots of output ......... wallclock:off [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="example.com" database_02 root@database_02:~ #iocage set comment="Postgres database server" database_02 root@database_02:~ #iocage set defaultrouter="192.168.1.1" 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.