tomoyotitle.png

Chapter 3: How do I install TOMOYO Linux?

3.1. Install the kernel

3.1.1. Determine if your kernel has TOMOYO Linux enabled

TOMOYO Linux 2.5.x is integrated with the upstream kernel source, but is only enabled when certain kernel configuration options are set. You can determine if your kernel has TOMOYO Linux enabled by running the following command:

$ grep tomoyo_write_inet_network /proc/kallsyms
ffffffff8115e460 T tomoyo_write_inet_network

If the output of the above command includes a line with "tomoyo_write_inet_network", then the running kernel was built with TOMOYO Linux support and you can proceed to 3.2 Install the userspace tools.

If not, then the running kernel was not built with TOMOYO Linux support and you should follow the steps below.

If you wish to obtain the most functionality out of TOMOYO Linux, then you may wish to use either the 1.x branch (which requires you to build your own kernel), or AKARI (which is a module and does not require you to build your own kernel). AKARI module currently provides more functionality than the 2.x branch, but is missing a small number of features that the 1.x branch provides. It is easy to use with any kernel from Linux 2.6.0 and later, depending on how the kernel has been configured and the CPU architecture. This chart provides a detailed comparison between AKARI and both the 1.x and 2.x branches. If you would prefer to use this module, please visit the AKARI website.

3.1.2. Install dependencies

These packages are required for compiling the kernel and the userspace tools:

These can be installed with the following commands:

RedHat distributions

# yum -y install wget patch gcc make ncurses-devel

Debian distributions

# apt-get -y install wget patch gcc make libncurses-dev

SUSE distributions

# yast -i wget patch gcc make ncurses-devel

3.1.3. Download the kernel

Download the kernel source from "linux-3" or "linux-4" or "linux git tree".
Linux kernel 2.6.33 and later are supported.

Extract the kernel source and go to the extracted directory.

If you want to use TOMOYO 2.5 on Linux kernels between 2.6.33 and 3.4, download a backport patch that matches your kernel version from https://tomoyo.osdn.jp/2.5/patches/ and run the following commands. ("$KERNELVERSION" should for example be replaced with "2.6.33" if using Linux kernel 2.6.33):

$ wget https://www.kernel.org/pub/linux/kernel/v3.x/linux-3.5.tar.bz2
$ tar -jxf linux-3.5.tar.bz2 --strip 1 linux-3.5/security/tomoyo/
$ wget https://tomoyo.osdn.jp/2.5/patches/tomoyo-2.5-backport-for-$KERNELVERSION.patch
$ patch -p1 < tomoyo-2.5-backport-for-$KERNELVERSION.patch

3.1.4. Configure the kernel

$ make -s menuconfig

Choose the following options in the "Security options" section (although "Default security module" is optional):

[*] Enable different security models
-*- Enable the securityfs filesystem
-*- Security hooks for pathname based access control
[*] TOMOYO Linux Support
(2048) Default maximal count for learning mode
(1024) Default maximal count for audit log
[ ]   Activate without calling userspace policy loader.
(/sbin/tomoyo-init) Location of userspace policy loader
(/sbin/init) Trigger for calling userspace policy loader
    Default security module (TOMOYO)

There are two types of TOMOYO policy configuration. The former is embedded into the kernel and the latter is saved as files on the filesystem (e.g. /etc/tomoyo/ directory). You will need to rebuild the kernel whenever updating the former, but allows you to load policy without using userspace policy loader (e.g. /sbin/tomoyo-init ). The latter is loaded by executing userspace policy loader when the access control by TOMOYO is about to be activated (e.g. when /sbin/init starts). Activate without calling userspace policy loader. allows you to activate access control by TOMOYO as soon as the former is loaded. This option is useful when it is difficult to call policy loader (e.g. embedded systems).

Location of userspace policy loader is available only when Activate without calling userspace policy loader. is not selected. This option specifies the default pathname of the userspace policy loader. You can override this setting via the "TOMOYO_loader=" kernel command-line option.

Trigger for calling userspace policy loader is available only when Activate without calling userspace policy loader. is not selected. This option specifies the default pathname of the activation trigger. You can override this setting via the "TOMOYO_trigger=" kernel command-line option. For example, if you pass "init=/usr/lib/systemd/systemd" option, you may also want to pass "TOMOYO_trigger=/usr/lib/systemd/systemd" option.

3.1.5. Compile and install the kernel

Once the kernel has been configured, compile and install the kernel with the following commands:

$ make -s
$ su
# make -s modules_install install

Create initrd/initramfs if required.

3.2. Install the userspace tools

3.2.1. Determine if binary packages are provided

If your repository provides tomoyo-tools or tomoyotools package, and the package's version is 2.5, you can use that package. Install and proceed to 3.3. Initialize configuration.

3.2.2. Install tools from source

Make sure the dependencies described above have been installed. Compile and install the tools with the following commands:

$ wget -O tomoyo-tools-2.5.0-20170102.tar.gz 'http://osdn.jp/frs/redir.php?m=jaist&f=/tomoyo/53357/tomoyo-tools-2.5.0-20170102.tar.gz'
$ wget -O tomoyo-tools-2.5.0-20170102.tar.gz.asc 'http://osdn.jp/frs/redir.php?m=jaist&f=/tomoyo/53357/tomoyo-tools-2.5.0-20170102.tar.gz.asc'
$ wget https://tomoyo.osdn.jp/kumaneko-key
$ gpg --import kumaneko-key
$ gpg tomoyo-tools-2.5.0-20170102.tar.gz.asc
$ tar -zxf tomoyo-tools-2.5.0-20170102.tar.gz
$ cd tomoyo-tools/
$ make -s USRLIBDIR=/usr/lib
$ su
# make -s USRLIBDIR=/usr/lib install

Please change USRLIBDIR=/usr/lib to USRLIBDIR=/usr/lib64 (for 64bits userspace) or USRLIBDIR=/usr/lib32 (for 32bits userspace) if needed.

3.3. Initialize configuration

You will probably want to add the location of the userspace tools (/usr/sbin) to your PATH so that the commands can be run easily. If you are using bash, append the following line to ~/.bashrc:

export PATH=$PATH:/usr/sbin

Before you can make use of TOMOYO Linux, an initialization procedure must take place. This prepares the files in which policy information will be stored. All policy files are stored in the "/etc/tomoyo/" directory.

You should see the following output by executing /usr/lib/tomoyo/init_policy:

# /usr/lib/tomoyo/init_policy
Creating policy directory... OK
Creating configuration directory... OK
Creating exception policy... OK
Creating domain policy... OK
Creating manager policy... OK
Creating default profile... OK
Creating stat policy... OK
Creating configuration file for tomoyo-editpolicy ... OK
Creating configuration file for tomoyo-auditd ... OK
Creating configuration file for tomoyo-patternize ... OK
Creating configuration file for tomoyo-notifyd ... OK

Note that the policy configuration is not compatible between TOMOYO 2.3 and TOMOYO 2.5. If policy has been developed for TOMOYO 2.3 then the "/etc/tomoyo/" directory needs to be deleted or renamed, otherwise there will be a kernel panic on the next boot.

3.4. Configure bootloader

Now edit your bootloader (e.g. GRUB) to include the kernel you have just compiled. If your kernel config does not contain "CONFIG_DEFAULT_SECURITY_TOMOYO=y", then edit your bootloader to include "security=tomoyo" in the kernel boot options. Depending on your distribution, the bootloader configuration file will probably be one of "/boot/grub/grub.conf" or "/boot/grub/menu.lst" (for GRUB version 1) or "/boot/grub/grub.cfg" or "/boot/grub2/grub.cfg" (for GRUB version 2). Consult your distribution documentation for information on how to configure the bootloader.

TOMOYO Linux supports "TOMOYO_trigger" kernel boot option. This option is useful for systems that run a program other than /sbin/init on startup. For example, RHEL 7 is using systemd which runs /usr/lib/systemd/systemd on startup. In this case, you need to include "TOMOYO_trigger=/usr/lib/systemd/systemd" in the kernel boot options unless you specified /usr/lib/systemd/systemd at 3.3.3. Configure the kernel.

You may directly edit /boot/grub2/grub.cfg file. But it is recommended that you also edit GRUB_CMDLINE_LINUX line in /etc/default/grub file like below in case you update kernel packages in the future:

GRUB_CMDLINE_LINUX="vconsole.keymap=us crashkernel=auto  vconsole.font=latarcyrheb-sun16 rhgb quiet security=tomoyo TOMOYO_trigger=/usr/lib/systemd/systemd"

3.5. Rebooting your system

Now you have finished all preparation. You can't wait any more? Now it's time to make use of your newly installed kernel. Reboot your system and choose the entry with TOMOYO Linux kernel at the GRUB screen, or at whatever other bootloader you have installed:

grub-screen.png

If everything was installed properly and the bootloader was correctly configured, the kernel should boot as normal and TOMOYO Linux should be activated:

tomoyo-activated.png

3.6. How can I disable/uninstall TOMOYO Linux?

If your system becomes unable to boot during the course of this guide or any time in the future, it may be due to policy configuration or something related to TOMOYO Linux. If this is the case, it is possible that the kernel can still be booted by disabling TOMOYO Linux. This can be done by appending "security=none" at the kernel command-line parameters.