akarititle.png

<Prev> <Index> <Next>

Chapter 3: How do I install AKARI?

3.1. Installing dependencies

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

These can be installed with the following commands:

RedHat distributions

# yum -y install wget gcc make ncurses-devel

Debian distributions

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

SUSE distributions

# yast -i wget gcc make ncurses-devel

3.2. Building the kernel module

3.2.1. Installing the kernel development package

Install the kernel development package and go to the directory that it has installed into:

RedHat distributions

# VERSION=$(uname -r)
# yum -y install kernel-devel-${VERSION}
# cd /usr/src/kernels/${VERSION}*/

Debian distributions

# VERSION=$(uname -r)
# apt-get -y install linux-headers-${VERSION}
# cd /usr/src/linux-headers-${VERSION}/

SUSE distributions

# VERSION=$(uname -r)
# yast -i kernel-devel
# cd /lib/modules/${VERSION}/build/

3.2.2. Building and installing the AKARI module

Run the following commands in order to extract source code of AKARI:

# wget https://sourceforge.net/projects/tomoyo/files/akari-patch/akari-1.0.54-20250205.tar.gz
# wget https://sourceforge.net/projects/tomoyo/files/akari-patch/akari-1.0.54-20250205.tar.gz.asc
# wget https://tomoyo.sourceforge.net/kumaneko-key
# gpg --import kumaneko-key
# gpg akari-1.0.54-20250205.tar.gz.asc
# tar -zxf akari-1.0.54-20250205.tar.gz

On systemd environments, /usr/lib/systemd/systemd will be executed rather than /sbin/init. If your system is using systemd, please edit CONFIG_CCSECURITY_ACTIVATION_TRIGGER line in akari/config.h like below:

Before:

#define CONFIG_CCSECURITY_ACTIVATION_TRIGGER "/sbin/init"

After:

#define CONFIG_CCSECURITY_ACTIVATION_TRIGGER "/usr/lib/systemd/systemd"

If you want to activate AKARI as soon as the kernel module is loaded, you can define CONFIG_CCSECURITY_OMIT_USERSPACE_LOADER line in akari/config.h like below. (But be sure to supply built-in policy configuration located at akari/policy/ directory if you define CONFIG_CCSECURITY_OMIT_USERSPACE_LOADER, or the system will panic as soon as the kernel module is loaded.):

Before:

//#define CONFIG_CCSECURITY_OMIT_USERSPACE_LOADER

After:

#define CONFIG_CCSECURITY_OMIT_USERSPACE_LOADER

Run the following commands in order to build and install AKARI:

# make SUBDIRS=$PWD/akari modules
# make SUBDIRS=$PWD/akari modules_install
# depmod ${VERSION}

If you encountered one of errors listed below, you cannot use AKARI for your kernel. You may instead wish to try TOMOYO Linux. For other errors, please contact the author ( penguin-kernel@I-love.SAKURA.ne.jp ).

This module supports only 2.6.0 and later kernels.
You must choose CONFIG_SECURITY=y for building this module.
You must choose CONFIG_KALLSYMS=y for building this module.
You must choose CONFIG_PROC_FS=y for building this module.
You must choose CONFIG_MODULES=y for building this module.

If you are interested in what functionality and syntax are supported for your kernel, see AKARI / TOMOYO functionality comparison table.

3.2.3. Check whether AKARI kernel module can be loaded or not (Optional)

Since registering AKARI module depends on your environment, you might encounter problems. Therefore, I recommend you to confirm that AKARI module can be loaded at this step.

Run the following commands in order to try to load akari_test.ko module:

# dmesg -c > /dev/null
# modprobe akari_test
# dmesg

akari_test: module verification failed: signature and/or required key missing - tainting kernel
security_ops=ffffffff81df6c80
find_task_by_vpid=ffffffff810821a0
find_task_by_pid_ns=ffffffff81082170
d_absolute_path=ffffffff811c8f10
All dependent symbols have been guessed.
Please verify these addresses using System.map for this kernel (e.g. /boot/System.map-`uname -r` ).
If these addresses are correct, you can try loading AKARI module on this kernel.

If akari_test.ko was loaded successfully, guessed addresses like above are printed. Therefore, please compare guessed addresses from akari_test.ko and actual addresses from System.map file. (Number of symbols and addresses printed depends on your environment.):

# for i in ffffffff81df6c80 ffffffff810821a0 ffffffff81082170 ffffffff811c8f10; do grep $i /boot/System.map-${VERSION}; done

ffffffff81df6c80 b security_ops
ffffffff810821a0 T find_task_by_vpid
ffffffff81082170 T find_task_by_pid_ns
ffffffff811c8f10 T d_absolute_path

Please proceed if these addresses are correct.

You might find some gap between guessed addresses from akari_test.ko and actual addresses from System.map file (like some examples shown below) if your kernel configuration uses CONFIG_RANDOMIZE_BASE=y. In this case, although guessed addresses will randomly change for every reboot, please proceed as long as the gap between guessed address and actual address is same for all guessed symbols. Otherwise, please contact the author since AKARI module will not work even if you continue.

If akari_test.ko was not loaded successfully, error messages like below are printed. In this case, please contact the author since AKARI module will not work even if you continue:

# dmesg -c > /dev/null
# modprobe akari_test

FATAL: Error inserting akari_test (/lib/modules/2.6.32/extra/akari_test.ko): Invalid argument

# dmesg

Sorry, I couldn't guess dependent symbols.
I need some changes for supporting your environment.
Please contact the author.

If your kernel has /proc/sys/kernel/kptr_restrict sysctl parameter set to 2, loading of akari_test.ko will fail. In this case, please set /proc/sys/kernel/kptr_restrict to 0 before loading and restore /proc/sys/kernel/kptr_restrict to 2 after loading.

# dmesg -c > /dev/null
# echo 0 > /proc/sys/kernel/kptr_restrict
# modprobe akari_test
# echo 2 > /proc/sys/kernel/kptr_restrict

3.3. Install the userspace tools

Make sure the dependencies described above have been installed. Compile and install the tools with the following commands. (Please use USRLIBDIR=/usr/lib or USRLIBDIR=/usr/lib32 if needed):

$ wget https://sourceforge.net/projects/tomoyo/files/ccs-tools/1.8/ccs-tools-1.8.12-20241111.tar.gz
$ wget https://sourceforge.net/projects/tomoyo/files/ccs-tools/1.8/ccs-tools-1.8.12-20241111.tar.gz.asc
$ gpg ccs-tools-1.8.12-20241111.tar.gz.asc
$ tar -zxf ccs-tools-1.8.12-20241111.tar.gz
$ cd ccs-tools/
$ make -s USRLIBDIR=/usr/lib64
$ su
# make -s USRLIBDIR=/usr/lib64 install

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 AKARI, 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 AKARI. 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/lib64/ccs/init_policy --file-only-profile --module_name=akari

Other users may wish to make use of all the restrictive capabilities of AKARI, and may want to analyze or restrict all possible operations (e.g. files, networks, environment variables). 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/lib64/ccs/init_policy --module_name=akari

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

# /usr/lib64/ccs/init_policy --module_name=akari

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

On systems where use of init= kernel boot option causes boot failures (e.g. RHEL 7), you need to choose Loading AKARI's module from initramfs. On systems where it does not cause boot failures (e.g. RHEL 6), you can choose Loading AKARI's module from the init process.

3.5.1. Loading AKARI's module from initramfs

If your system is using dracut, create /etc/dracut.conf.d/akari.conf like below and rebuild the initramfs:

# echo 'add_drivers+=" akari "' > /etc/dracut.conf.d/akari.conf
# dracut -f --kver ${VERSION}

Now edit your bootloader (e.g. GRUB) to add "rd.driver.pre=akari" to the kernel boot options. An example is shown below:

Before:

linux16 /boot/vmlinuz-3.10.0-957.1.3.el7.x86_64 ro root=LABEL=/

After:

linux16 /boot/vmlinuz-3.10.0-957.1.3.el7.x86_64 ro root=LABEL=/ rd.driver.pre=akari

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:

Before:

GRUB_CMDLINE_LINUX="vconsole.keymap=us crashkernel=auto  vconsole.font=latarcyrheb-sun16 rhgb quiet"

After:

GRUB_CMDLINE_LINUX="vconsole.keymap=us crashkernel=auto  vconsole.font=latarcyrheb-sun16 rhgb quiet rd.driver.pre=akari"

3.5.2. Loading AKARI's module from the init process

Create /sbin/akari-init like below. (Please use /bin/modprobe if modprobe in your system is located at /bin rather than /sbin.):

# echo '#! /bin/sh' > /sbin/akari-init
# echo '/sbin/modprobe akari && exec /sbin/init "$@"' >> /sbin/akari-init
# chmod 755 /sbin/akari-init

Please create /sbin/akari-init like below if your system is using /usr/lib/systemd/systemd rather than /sbin/init:

# echo '#! /bin/sh' > /sbin/akari-init
# echo '/sbin/modprobe akari && exec /usr/lib/systemd/systemd "$@"' >> /sbin/akari-init
# chmod 755 /sbin/akari-init

Now edit your bootloader (e.g. GRUB) to add "init=/sbin/akari-init" to the kernel boot options. An example is shown below:

Before:

kernel /boot/vmlinuz-2.6.32-754.9.1.el6.x86_64 ro root=LABEL=/

After:

kernel /boot/vmlinuz-2.6.32-754.9.1.el6.x86_64 ro root=LABEL=/ init=/sbin/akari-init

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 AKARI kernel at the GRUB screen, or at whatever other bootloader you have installed.

You will find messages like below when /usr/lib/systemd/systemd or /sbin/init starts. (The content of messages depends on your environment.):

AKARI: 1.0.54   2025/02/05
Access Keeping And Regulating Instrument registered.
Calling /sbin/ccs-init to load policy. Please wait.
CCSecurity: 1.8.14   2025/02/05
Mandatory Access Control activated.

Note that you won't be able to see AKARI's messages if you are using "quiet" or "rhgb" kernel boot option because these options prevent most of kernel messages from being printed.

Depending on kernel configuration and/or kernel boot options, above messages might not be printed. In this case, please check whether /proc/ccs/ directory exists. If /proc/ccs/ directory exists, AKARI module is registered successfully.

Although AKARI is a LSM module, AKARI can coexist with other LSM modules. However, you need to also add "selinux=0" to the kernel boot options if you disable SELinux by specifying SELINUX=disabled in /etc/selinux/config . This is because the init process unregisters LSM hooks which AKARI module depends on if SELINUX=disabled is specified in /etc/selinux/config .

3.7. How can I disable/uninstall AKARI?

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 AKARI. If this is the case, it is possible that the kernel can still be booted by disabling AKARI. This can be done by removing "rd.driver.pre=akari" or "init=/sbin/akari-init" at the kernel command-line parameters.