tomoyotitle.png

Chapter 3: How do I install TOMOYO Linux?

3.1. Are binary packages available for my distribution?

TOMOYO Linux requires the installation of a separate Linux kernel from the one provided by your distribution. This can be done in one of two ways. A binary package can be installed, or the kernel can be compiled from source and manually patched. If your distribution is listed below, then you can install the binary package very easily without having to do any compilation.

The distributions that we provide binary packages for are:

If your distribution was listed above then continue to section 3.2. Installing binary packages, otherwise you will need to compile your own kernel. If this is the case then proceed to section 3.3. Installing from source

3.2. Installing binary packages

If your distribution uses RPM packages, import the GPG key with these commands:

# wget https://tomoyo.osdn.jp/kumaneko-key
# rpm --import kumaneko-key

If your distribution uses DEB packages, import the GPG key with these commands:

# wget https://tomoyo.osdn.jp/kumaneko-key
# apt-key add kumaneko-key

The binary packages provided by this project can be manually downloaded from this SourceForge page. A package for the kernel and a package for the userspace tools are required. Alternatively, packages can be installed very easily straight from the repository using the following commands:

CentOS 6 (686 flavour)

# wget -O /etc/yum.repos.d/ccs.repo http://tomoyo.osdn.jp/repos-1.8/CentOS6/ccs.repo
# yum install ccs-kernel ccs-tools

CentOS 5 (686 flavour)

# wget -O /etc/yum.repos.d/ccs.repo http://tomoyo.osdn.jp/repos-1.8/CentOS5/ccs.repo
# yum install ccs-kernel ccs-tools

CentOS 4 (686 flavour)

# wget -O /etc/yum.repos.d/ccs.repo http://tomoyo.osdn.jp/repos-1.8/CentOS4/ccs.repo
# yum install ccs-kernel-smp ccs-tools

CentOS 3 (686 flavour)

# wget -O - http://tomoyo.osdn.jp/repos-1.8/CentOS3/ccs.repo >> /etc/yum.conf
# yum install ccs-kernel-smp ccs-tools

Asianux 3 (686 flavour)

# wget -O /etc/yum.repos.d/ccs.repo http://tomoyo.osdn.jp/repos-1.8/Asianux3/ccs.repo
# yum install ccs-kernel ccs-tools

Vine Linux 6 (686-pae flavour)

# echo "repomd http://tomoyo.osdn.jp/repos-1.8/VineLinux6/ ./" >> /etc/apt/sources.list
# apt-get update
# apt-get install ccs-kernel-pae ccs-tools

Debian Squeeze (686 flavour)

# echo 'deb http://tomoyo.osdn.jp/repos-1.8/DebianSqueeze/ ./' >> /etc/apt/sources.list
# apt-get update
# apt-get install linux-image-2.6-686-ccs ccs-tools

Debian Wheezy (686-pae flavour)

# echo 'deb http://tomoyo.osdn.jp/repos-1.8/DebianWheezy/ ./' >> /etc/apt/sources.list
# apt-get update
# apt-get install linux-image-3.2.0-4-686-pae-ccs ccs-tools

Ubuntu 12.04 (generic-pae flavour)

# echo 'deb http://tomoyo.osdn.jp/repos-1.8/Ubuntu12.04/ ./' >> /etc/apt/sources.list
# apt-get update
# apt-get install linux-generic-pae-ccs ccs-tools

Ubuntu 10.04 (generic-pae flavour)

# echo 'deb http://tomoyo.osdn.jp/repos-1.8/Ubuntu10.04/ ./' >> /etc/apt/sources.list
# apt-get update
# apt-get install linux-generic-pae-ccs ccs-tools

You can now proceed to section 3.4. Initializing configuration.

3.3. Installing from source

If we do not provide binary packages for your distribution, then you will have to compile your own kernel.

If you wish to obtain the most functionality out of TOMOYO Linux possible but do not wish to compile a kernel, the AKARI module can be used. This module provides more functionality that 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.3.1. 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.3.2. Download and patch the kernel

Download the kernel source from linux-2.4 or linux-2.6 or linux-3 or linux-4.
Linux kernel 2.4.37 is supported from the linux-2.4 tree.
Linux kernel 2.6.27 and later are supported from the linux-2.6 tree.
Linux kernel 3.0 and later are supported from the linux-3 tree.
Linux kernel 4.0 and later are supported from the linux-4 tree.

Extract the kernel source and go to the extracted directory.
In the operations below, "$VERSION.$PATCHLEVEL.diff" should for example be replaced with "4.18.diff" if using Linux kernel 4.18.5 :

$ wget -O ccs-patch-1.8.5-20180827.tar.gz 'http://osdn.jp/frs/redir.php?m=jaist&f=/tomoyo/49684/ccs-patch-1.8.5-20180827.tar.gz'
$ wget -O ccs-patch-1.8.5-20180827.tar.gz.asc 'http://osdn.jp/frs/redir.php?m=jaist&f=/tomoyo/49684/ccs-patch-1.8.5-20180827.tar.gz.asc'
$ gpg ccs-patch-1.8.5-20180827.tar.gz.asc
$ tar -zxf ccs-patch-1.8.5-20180827.tar.gz
$ patch -sp1 < patches/ccs-patch-$VERSION.$PATCHLEVEL.diff

3.3.3. Configure the kernel

$ make -s menuconfig

Choose the following options in "Security options" section:

"Compile as loadable kernel module" is useful when there is a file size limitation for vmlinux (e.g. embedded systems).

"Disable by default" will enable TOMOYO Linux only when "ccsecurity=on" is passed to the kernel's command line options. If this option is not selected, "ccsecurity=off" will disable TOMOYO Linux.

"Do not modify 'struct task_struct' in order to keep KABI" is available to 2.6 and later kernels only. This option will manage "struct task_struct" variables outside "struct task_struct" in order to avoid Kernel Application Binary Interface (KABI) breakage. Choose this option if wanting to patch against distributor's kernels without breaking KABI. However, since "struct ccsecurity_operations" must be exported to loadable kernel modules (LKMs) in order to allow them to call TOMOYO's functions, build scripts may still print warning messages.

There are two types of TOMOYO's policy configuration. The former is embedded into the kernel and the latter is saved as files on the filesystems (e.g. /etc/ccs/ 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/ccs-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 "CCS_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 "CCS_trigger=" kernel command-line option. For example, if you pass "init=/usr/lib/systemd/systemd" option, you may also want to pass "CCS_trigger=/usr/lib/systemd/systemd" option.

3.3.4. Compile and install the kernel

The policy configuration which will be embedded into the kernel needs to be exist as domain_policy.conf, exception_policy.conf, manager.conf, profile.conf and stat.conf under security/ccsecurity/policy/ directory. But you can proceed without creating files under security/ccsecurity/policy/ directory because you don't have the policy configuration to embed as of this step. (You may come back here after you developed policy configuration to embed.)

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

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

Create initrd/initramfs if required.

3.3.5. Install the userspace tools

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

$ wget -O ccs-tools-1.8.5-20170102.tar.gz 'http://osdn.jp/frs/redir.php?m=jaist&f=/tomoyo/49693/ccs-tools-1.8.5-20170102.tar.gz'
$ wget -O ccs-tools-1.8.5-20170102.tar.gz.asc 'http://osdn.jp/frs/redir.php?m=jaist&f=/tomoyo/49693/ccs-tools-1.8.5-20170102.tar.gz.asc'
$ gpg ccs-tools-1.8.5-20170102.tar.gz.asc
$ tar -zxf ccs-tools-1.8.5-20170102.tar.gz
$ cd ccs-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.


You can now proceed to section 3.4. Initializing configuration

3.4. Initializing 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/ccs/" directory.

One of two commands can be used to initialize configuration. The command you use depends on what operations you wish to analyze or restrict.

Some users may wish to restrict only file-related operations, such as read, write and execute. This is suitable for users wanting to keep policy simpler or do not require the full functionality of TOMOYO Linux. If you chose to restrict only file-related operations, then you may ignore parts of this guide that are not relevant, such as network operations. In this case, policy can be initialized using this command:

# /usr/lib/ccs/init_policy --file-only-profile

Other users may wish to make use of all the restrictive capabilities of TOMOYO Linux, and may want to analyze or restrict all possible operations (e.g. files, networks, capabilities, environment variables, signal transmissions). This is suitable for users wanting to secure their system as much as possible. This is also what this guide generally assumes the reader has chosen. In this case, run the following command:

# /usr/lib/ccs/init_policy

After running one of the above commands, you should see the following output:

# /usr/lib/ccs/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 module loader... OK
Creating configuration file for ccs-editpolicy ... OK
Creating configuration file for ccs-auditd ... OK
Creating configuration file for ccs-patternize ... OK
Creating configuration file for ccs-notifyd ... OK

3.5. Configuring your bootloader

Now edit your bootloader (e.g. GRUB) to include the kernel you have just compiled. If the "Disable by default" option was selected during kernel configuration, remember to include "ccsecurity=on" in the kernel boot options. Consult the documentation for your distribution and bootloader to find out how to boot your TOMOYO Linux kernel.

TOMOYO Linux 1.8.2 and later support "CCS_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 "CCS_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 CCS_trigger=/usr/lib/systemd/systemd"

3.6. 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

If something went wrong, the system may halt by kernel panic. Below screenshot is an example of rebooting Ubuntu 11.04 without creating initramfs after Compile and install the kernel:

missing-initramfs.png

3.7. 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 "ccsecurity=off" at the kernel command-line parameters.

TOMOYO Linux fortunately does not require the modification of any existing Linux binaries, libraries or applications. Thus, uninstalling TOMOYO Linux is very easy. It is simply a matter of uninstalling the kernel and userspace tools that you installed above using your package manager (e.g. rpm or apt). You can reboot with the kernel provided by your distribution and then remove the entry from your bootloader.