The iocage program is a python 3 piece created to manage FreeBSD Jails leveraging the underpinning ZFS file system on FreeBSD. As already explained on previous articles the FreeBSD operating system offers an OS-level virtualization system called Jails. And as described on past articles it can benefit administrators and developers alike. This is a simple guide on how to install the tool.
If you find the articles in Adminbyaccident.com useful to you, please consider making a donation.
As a pre-requisite the disks on which the Jails will sit have to be formatted using the ZFS file system.
Let’s look for the program.
albert@Jails:~ % pkg search iocage
py36-iocage-0.9.10 FreeBSD jail manager written in Python3
py36-iocage-devel-1.0.0.20181219,1 FreeBSD jail manager written in Python3
py36-libiocage-0.3.1 Library to manage jails with iocage
albert@Jails:~ %
Let’s make the install.
albert@Jails:~ % sudo pkg install py36-iocage-0.9.10
Updating FreeBSD repository catalogue...
FreeBSD repository is up to date.
All repositories are up to date.
The following 26 package(s) will be affected (of 0 checked):
New packages to be INSTALLED:
py36-iocage: 0.9.10
py36-requests: 2.18.4_1
py36-chardet: 3.0.4
python36: 3.6.7
readline: 7.0.5
libffi: 3.2.1_3
py36-setuptools: 40.6.2
py36-certifi: 2018.11.29
py36-urllib3: 1.22,1
py36-openssl: 18.0.0
py36-cryptography: 2.3
py36-idna: 2.7
py36-six: 1.12.0
py36-cffi: 1.11.5
py36-pycparser: 2.18
py36-asn1crypto: 0.22.0
py36-pysocks: 1.6.8
py36-texttable: 1.5.0
ca_root_nss: 3.41
py36-tqdm: 4.28.1
py36-pytest-runner: 2.11.1
py36-libzfs: 1.0.20181212
py36-coloredlogs: 10.0
py36-humanfriendly: 4.16.1
py36-click: 6.7_1
py36-dulwich: 0.18.6
Number of packages to be installed: 26
The process will require 132 MiB more space.
19 MiB to be downloaded.
Proceed with this action? [y/N]: y
Once it is installed it has to be presented, so to speak, to the file system where it will operate. We do that by activating the install referencing on what ZFS pool we want to work on. For further detail refer to the original iocage documentation.
albert@Jails:~ % sudo iocage activate zroot
ZFS pool 'zroot' successfully activated.
albert@Jails:~ %
If you prettend yo use Jails regularly you must edit the /etc/fstab file and add the fdescfs path.
albert@Jails:~ % sudo vi /etc/fstab
# Device Mountpoint FStype Options Dump Pass#
/dev/ada0p2 none swap sw 0 0
fdescfs /dev/fd fdescfs rw 0 0
albert@Jails:~ %
If you just want to do this temporary just mount it manually for the actual log in session.
albert@Jails:~ % sudo mount -t fdescfs null /dev/fd
albert@Jails:~ %
It is now time to fetch a release which will create a base jail. This takes some time the first time since it has to download some sources. After the creation of this base jail, creating new jails takes just a matter of seconds. Plus one can choose different FreeBSD versions to play with.
albert@Jails:~ % sudo 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 (EOL)
[5] 11.0-RELEASE (EOL)
[6] 11.1-RELEASE (EOL)
[7] 11.2-RELEASE
[8] 12.0-RELEASE
Type the number of the desired RELEASE
Press [Enter] to fetch the default selection: (12.0)
Type EXIT to quit:
If you are using a later version of iocage, for example py36-iocage-1.1 you may encounter the following error when fetching the base jail.
$ sudo iocage fetch
Please set a mountpoint on zroot/iocage
$
To correct this situation we’ll create a mounting point directory, will set it as the mountpoint and everything will work as expected.
We first create the directory
$ sudo mkdir /zroot
Now we set the mountpoint for zroot/iocage using the following command:
$ sudo zfs set mountpoint=/zroot zroot/iocage
Once this is done, if we have had the error we sould issue the following command with no hassle.
$ sudo iocage fetch
I am choosing the 11.2-RELEASE so I can play with another system I have the same release already on. I will update later.
Type EXIT to quit: 7
Fetching: 11.2-RELEASE
Downloading : MANIFEST [####################] 100% 0Mbit/s
Downloading : base.txz [####################] 100% 25.2Mbit/ss
Downloading : lib32.txz [####################] 100% 24.08Mbit/s
Downloading : doc.txz [####################] 100% 18.27Mbit/s
Downloading : src.txz [####################] 100% 26.66Mbit/s
26.66Mbit/sExtracting: base.txz...
Extracting: lib32.txz...
Extracting: doc.txz...
Extracting: src.txz...
* Updating 11.2-RELEASE to the latest patch level...
src component not installed, skipped
Looking up update.FreeBSD.org mirrors... 3 mirrors found.
Fetching public key from update1.freebsd.org... done.
Fetching metadata signature for 11.2-RELEASE from update1.freebsd.org... done.
Fetching metadata index... done.
Fetching 2 metadata files... done.
Inspecting system... done.
Preparing to download files... done.
Fetching 31 patches.....10....20....30 done.
Applying patches... done.
Installing updates... done.
albert@Jails:~ %
So now a base jail is installed and you can start creating jails and managing them. For the sake of completion we’ll see now how to create one and log into it.
We will now create a ‘Test’ jail.
albert@Jails:~ % sudo iocage create -r 11.2-RELEASE -n Test ip4_addr="em0|192.168.1.150/24"
Test successfully created!
albert@Jails:~ %
The -r flag lets us specify what release we want to choose from. We can have several base jails from different FreeBSD versions. At creation time we have to specify which.
The -n flag allows us to give the jail a proper understandable name. If we don’t do this iocage will give the jail a name made of numbers and letters which will be completely impossible to pronounce, not even remember.
The ip4_addr directive allows us to set the ip networking property to the jail.
Let’s list the jail so we check it has been effectively created.
albert@Jails:~ % sudo iocage list
+-----+------+-------+--------------+---------------+
| JID | NAME | STATE | RELEASE | IP4 |
+=====+======+=======+==============+===============+
| - | Test | down | 11.2-RELEASE | 192.168.1.150 |
+-----+------+-------+--------------+---------------+
albert@Jails:~ %
We can now start up the jail.
albert@Jails:~ % sudo iocage start Test
* Starting Test
+ Started OK
+ Starting services OK
albert@Jails:~ %
To log into the jail just type:
albert@Jails:~ % sudo iocage console Test
FreeBSD 12.0-RELEASE r341666 GENERIC
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@Test:~ #
So you are now in. Although it says it’s FreeBSD 12, that is the kernel you are dealing with, however the userland is 11.2’s version.
Once in it works as a regular FreeBSD box.
root@Test:~ # whoami
root
root@Test:~ # id
uid=0(root) gid=0(wheel) groups=0(wheel),5(operator)
root@Test:~ #
To get out just type exit.
root@Test:~ # exit
logout
albert@Jails:~ %
Let’s stop the jail.
albert@Jails:~ % sudo iocage stop Test
* Stopping Test
+ Running prestop OK
+ Stopping services OK
+ Removing jail process OK
+ Running poststop OK
albert@Jails:~ %
This is all on this how to install iocage to manage FreeBSD Jails. Enjoy your cell!
Use this link to get 100 $ credit at DOcean and support Adminbyaccident.com hosting costs.