Info: Version 1.3 is available.

# TOMOYO Linux Install manual (Targeted version)

Last modified: $Date: 2011-11-20 09:56:56 +0900 (Sun, 20 Nov 2011) $

# Index

Preparation Install Kernel Install Tool Boot Test
Preparing Policy About Default Policy Defining Policy Managers Modifying Shutdown Procedure Creating Profiles Creating Exception Policy
Creating Policy Accept Mode and tuning Rerunning accept mode Permissive Mode
Production State Enforce mode

# Preparation

There are no limitations for distributions. But since it is impossible to cover all distributions, this manual covers "RedHat Linux 9", "Fedora Core 3" and "Debian Sarge".

The size of policy files gets smaller by uninstalling unnecessary applications. You should know what application you want to run on the system.

## Install Kernel

To compile kernel, see TOMOYO Linux kernel compilation.

## Install Tool

To compile tools, run the following commands.

cd /root/ # Download source of tools for TOMOYO Linux. wget -O ccs-tools-1.2-20060903.tar.gz 'http://sourceforge.jp/frs/redir.php?m=jaist&f=/tomoyo/21579/ccs-tools-1.2-20060903.tar.gz' # Extract. tar -zxf ccs-tools-1.2-20060903.tar.gz # Compile. make -sC ccstools/

## Boot Test

Boot with TOMOYO Linux kernel, and check the system works properly.

After you confirmed the system works properly, save the content of /proc/ccs/status as /root/security/status.txt . This file contains the topics controllable for this kernel. This file is used as a hint when creating profiles (described later).

mkdir -p /root/security cat /proc/ccs/status > /root/security/status.txt

# Preparing Policy

Please use normal kernel for operations in this chapter.
If you use TOMOYO Linux's kernel, /root/ccstools/savepolicy will be executed on shutdown and modifications you made on /root/security/exception_policy.txt will be lost.

## About Default Policy

TOMOYO Linux doesn't have default policy files distributed with softwares. Administrators need to create policy files using "accept mode".
The example policies are available to help your understanding. You may use these examples as a guide, but you MUST NOT use these examples as default policies.

## Defining Policy Managers

Create /root/security/manager.txt and list up programs that are allowed to update policies via /proc/ccs/ interface.
Specifically, "loadpolicy" that reloads policy, "editpolicy" that edits policy, "setlevel" that changes control level, "ld-watch" that updates globally readable files, "ccs-queryd" that grants access requests interactively.

cat > /root/security/manager.txt << EOF /root/ccstools/loadpolicy /root/ccstools/editpolicy /root/ccstools/setlevel /root/ccstools/ld-watch /root/ccstools/ccs-queryd EOF

## Modifying Shutdown Procedure

To save on-memory policies onto disk just before power off, modify the shutdown script to run /root/ccstools/savepolicy . Actual locations to modify depends on distributions. In many cases, since the final program invoked in the shutdown script under /etc/init.d/ directory is the program to power off, save on-memory policies just before the invocation of the program.

If you are using RedHat Linux 9 or Fedora Core 3, modify as follows.

/etc/rc.d/init.d/halt
Before | After
exec $command $HALTARGS | /root/ccstools/savepolicy exec $command $HALTARGS

If you are using Debian Sarge, modify as follows. To create and include domains for executing halt/reboot among the domain policy, run halt/reboot once before invoking savepolicy.

/etc/init.d/halt | /etc/init.d/reboot
Before | After | Before | After
halt -d -f -i $poweroff $hddown | halt --help 2> /dev/null /root/ccstools/savepolicy halt -d -f -i $poweroff $hddown | reboot -d -f -i | reboot --help 2> /dev/null /root/ccstools/savepolicy reboot -d -f -i

## Creating Profiles

TOMOYO Linux can perform several MACs besides MAC for files, but to reduce the load of policy managements, you can disable MACs you think unnecessary.

You can switch the MACs and their initial control status by creating several profiles and specifying the profile index number at kernel command line. Specifically, the parameter CCS=$INDEX (where $INDEX is an integer) given in the kernel command line corresponds to the profile /root/security/profile$INDEX.txt to use.

Refer the descriptions below and create profiles for "accept mode", "permissive mode", "enforce mode". Only topics included in /root/security/status.txt are configurable. The topics included in /root/security/status.txt vary depending on the kernel configuration.

Name | Control | Accept mode supported
MAC_FOR_FILE | File Access | Yes
MAX_ACCEPT_FILES | Limits the max number of file ACL entries that are automatically appended during accept mode | -
MAX_GRANT_LOG | Limits the max number of grant logs that the kernel can hold | -
MAX_REJECT_LOG | Limits the max number of reject logs that the kernel can hold | -
TOMOYO_VERBOSE | Dump domain policy violation messages to syslog | -
MAX_ENFORCE_GRACE | Wait before rejecting access request when the request violates policy in enforce mode | -

You can give the following values for MAX_ACCEPT_FILES

Value | Meaning
any integer | The max number of file ACL entries that are automatically appended during accept mode. The default is given at the kernel compilation time.

You can give the following values for MAX_GRANT_LOG and MAX_REJECT_LOG

Value | Meaning
any integer | The max number of logs that the kernel can hold. The default is given at the kernel compilation time. You may give 0 if you don't need logs.

You can give the following values for TOMOYO_VERBOSE

Value | Meaning
0 | Don't dump domain policy violation messages.
1 | Dump domain policy violation messages.

You can give the following values for MAX_ENFORCE_GRACE

Value | Meaning
any integer | The max grace time in seconds. If the administrator tells the kernel not to reject the request that violated policy in enforce mode, the request will be granted.

You can give the following values for all but listed above.

Value | Meaning
0 | Disabled. Works as if regular kernel.
1 | Accept mode. Not rejected if the request violates policy. Automatically appended to policy.
2 | Permissive mode. Not rejected if the request violates policy. Not appended to policy automatically.
3 | Enforce mode. Rejected if the request violates policy.

## Creating Exception Policy

Register pathnames with patterns that likely exists on all Linux systems.
Register pathnames with patterns using the "file_pattern" directive in /root/security/exception_policy.txt .
When a file operation are performed and the requested pathname matches to a patterned pathname registered with "file_pattern" directive, policy is generated using patterned pathnames.
The following is the guideline.

- Files under /proc/PID/ directory.
- Files under /sys/ directory. (Applicable to 2.6 kernels only)
- Some files under /dev/ directory.
- Policy files under /root/security/ directory.
- Manual pages.
- Spool directories.
- Temporary files used for sending and receiving mails.
- Temporary files used by man command.
- Temporary files used by mount command.

TOMOYO Linux needs more patterned pathnames depending on the applications installed and their configurations. You can add missing patterned pathnames after running the system.

Register files that are allowed to be read by all programs.
Register pathnames using the "allow_read" directive in /root/security/exception_policy.txt . No patterns allowed.
When a read access is requested and the requested pathname matches to a pathname registered with "allow_read" directive, the read access is granted without checking domain policy.
The following is the guideline.

- Dynamically-linked library files that are registered with ldconfig.
- Some files under /proc/ directory.
- Some locale data under /usr/share/locale/ directory.

A shell script is included that performs the operations described above. Run as the following.

/root/ccstools/make_targeted_exception.sh | sort | uniq > /root/security/exception_policy.txt

Next, specify programs you want to apply MAC protection. Some candidates are shown by running the following command.

/root/ccstools/make_exception.sh | grep '^initializer' | sort | uniq

For example, if you want to enable Mandatory Access Controls on /usr/sbin/httpd and programs invoked by /usr/sbin/httpd , add the following line.

initializer /usr/sbin/httpd

By these steps, /usr/sbin/httpd and programs invoked by /usr/sbin/httpd run in the "<kernel> /usr/sbin/httpd" domain and its child domains and are protected by Mandatory Access Controls.

For example, if you want to enable Mandatory Access Controls on /usr/sbin/sshd and programs invoked by /usr/sbin/sshd , add the following line.

initializer /usr/sbin/sshd

By these steps, /usr/sbin/sshd and programs invoked by /usr/sbin/sshd run in the "<kernel> /usr/sbin/sshd" domain and its child domains and are protected by Mandatory Access Controls.

# Creating Policy

## Accept Mode and tuning

### Boot options

Boot with TOMOYO Linux kernel with the profile number for accept mode to CCS= parameter. Give the parameter "TOMOYO_NOLOAD" to the kernel command line for the first time to skip reading domain policy. If the parameter "TOMOYO_NOLOAD" is given, the domain policy file (domain_policy.txt) won't get loaded. (Therefore, choose TOMOYO Linux kernel with TOMOYO_NOLOAD parameter and the profile number for accept mode to CCS= parameter.)

### Confirming processes to be protected

If you run the following command, the process IDs of the programs on which MAC aren't applied are shown.

cat /proc/ccs/info/trusted_pids

Make sure that the process IDs of the programs you want to protect aren't shown. If shown, do the following operation.

* Run "/root/ccstools/editpolicy e". * Move cursors using UP/DOWN arrow keys and make sure that the line "initializer program_to_protect" doesn't exist. For example, if you want to protect "/usr/sbin/squid", make sure the line "initializer /usr/sbin/squid" doesn't exist. * When you press "a" key, a prompt "Enter new entry>" will appear, then input "initializer program_to_protect" and press "Enter" key. * Move cursors using UP/DOWN arrow keys and make sure that the line "initializer program_to_protect" exists. * Press "q" key to quit the editor. * Restart the program you want to protect. * Examine the contents of /proc/ccs/info/trusted_pids and make sure that the process IDs of the programs you want to protect aren't shown.

### Examining behavior

Do a series of operations you want to allow.

Repeat several times, for all access patterns may not be recorded by single operations.
Also, there are operations that are done only startup and shutdown, repeat reboot for several times.

When you are running with accept mode, you may find messages in the following format.

TOMOYO-WARNING: Domain '<kernel> ...' has so many ACLs to hold. Stopped auto-append mode.

This message tells you that the safeguard for this program is activated to prevent memory consumption and dull response since this program accessed so many files. When the safeguard is activated, file ACLs for that domain are no longer appended automatically.

To deal with this message, you need to edit ACLs manually.
For example, if the following message appeared, you need to reduce the number of file ACLs for <kernel> /usr/sbin/hald using appropriate pathname patterns.

TOMOYO-WARNING: Domain '<kernel> /usr/sbin/hald' has so many ACLs to hold. Stopped auto-append mode.

### Patterning pathnames

Run the following command to find pathnames that are likely temporary.

/root/ccstools/findtemp < /proc/ccs/policy/domain_policy | sort | uniq

Make patterns appropriately and do the following operation.

* Run "/root/ccstools/editpolicy e". * Move cursors using UP/DOWN arrow keys and make sure that the line "file_pattern patterned_pathname" doesn't exist. For example, if you want to add pattern "/tmp/sh-thd-\$", make sure the line "file_pattern /tmp/sh-thd-\$" doesn't exist. * When you press "a" key, a prompt "Enter new entry>" will appear, then input "file_pattern patterned_pathname" and press "Enter" key. * Move cursors using UP/DOWN arrow keys and make sure that the line "file_pattern patterned_pathname" exists. * Press "q" key to quit the editor.

Guidelines for temporary pathnames are "Multiple pathnames that differs only last 6 letters", "Multiple pathnames that differs only numerical part" and so on.
An example of patterned pathnames is shown below. These patterned pathnames may not exist or exist in other location depending on the applications installed and their configurations.

- file_pattern /etc/.fstab.hal.\?
- file_pattern /etc/blkid.tab-\?\?\?\?\?\?
- file_pattern /etc/mrtg/mrtg.cfg_l_\$
- file_pattern /root/.emacs.d/auto-save-list/.saves-\$-\*
- file_pattern /root/Mail/inbox/\$
- file_pattern /tmp/auto\?\?\?\?\?\?/
- file_pattern /tmp/autofs.\?\?\?\?\?\?
- file_pattern /tmp/logrotate.\?\?\?\?\?\?
- file_pattern /tmp/logwatch.\*/
- file_pattern /tmp/logwatch.\*/\*
- file_pattern /tmp/makewhatis\?\?\?\?\?\?/
- file_pattern /tmp/makewhatis\?\?\?\?\?\?/w
- file_pattern /tmp/sh-thd-\$
- file_pattern /tmp/spamassassin-\$/
- file_pattern /tmp/spamassassin-\$/.spamassassin/
- file_pattern /tmp/spamassassin-\$/.spamassassin/auto-whitelist\*
- file_pattern /tmp/whatis.\?\?\?\?\?\?
- file_pattern /var/lib/dhcp/dhcpd.leases.\$
- file_pattern /var/lock/autofs.\$
- file_pattern /var/lock/mrtg/mrtg_l_\$
- file_pattern /var/log/ksymoops/\*
- file_pattern /var/log/sa/sa\*
- file_pattern /var/mailman/locks/gate_news.lock.\*
- file_pattern /var/run/gpm\?\?\?\?\?\?

### Add conditions to ACLs

TOMOYO Linux 1.2 supports conditional ACLs. By using this feature, you can control system's user ID based access control.

If you want to protect non-anonymous FTP service, by adding conditions in the following manner, you can forbid access to directories outside the user's home directory. To reduce damages when it is cracked, it is recommended that you should expose directories only under specific (such as "ftp") directory rather than exposing whole of home directories. If you use vsftpd, you can give like the following way.

Before
<kernel> /usr/sbin/vsftpd 6 /home/\*/ftp/\* 6 /home/\*/ftp/\*/\* 6 /home/\*/ftp/\*/\*/\* 6 /home/\*/ftp/\*/\*/\*/\* allow_mkdir /home/\*/ftp/\*/ allow_mkdir /home/\*/ftp/\*/\*/ allow_mkdir /home/\*/ftp/\*/\*/\*/ allow_rmdir /home/\*/ftp/\*/ allow_rmdir /home/\*/ftp/\*/\*/ allow_rmdir /home/\*/ftp/\*/\*/\*/ allow_create /home/\*/ftp/\* allow_create /home/\*/ftp/\*/\* allow_create /home/\*/ftp/\*/\*/\* allow_create /home/\*/ftp/\*/\*/\*/\* allow_truncate /home/\*/ftp/\* allow_truncate /home/\*/ftp/\*/\* allow_truncate /home/\*/ftp/\*/\*/\* allow_truncate /home/\*/ftp/\*/\*/\*/\* allow_unlink /home/\*/ftp/\* allow_unlink /home/\*/ftp/\*/\* allow_unlink /home/\*/ftp/\*/\*/\* allow_unlink /home/\*/ftp/\*/\*/\*/\* allow_rename /home/\*/ftp/\* /home/\*/ftp/\* allow_rename /home/\*/ftp/\*/\* /home/\*/ftp/\*/\* allow_rename /home/\*/ftp/\*/\*/\* /home/\*/ftp/\*/\*/\* allow_rename /home/\*/ftp/\*/\*/\*/\* /home/\*/ftp/\*/\*/\*/\* allow_rename /home/\*/ftp/\*/ /home/\*/ftp/\*/ allow_rename /home/\*/ftp/\*/\*/ /home/\*/ftp/\*/\*/ allow_rename /home/\*/ftp/\*/\*/\*/ /home/\*/ftp/\*/\*/\*/

After
<kernel> /usr/sbin/vsftpd 6 /home/\*/ftp/\* if task.uid=path1.uid 6 /home/\*/ftp/\*/\* if task.uid=path1.uid 6 /home/\*/ftp/\*/\*/\* if task.uid=path1.uid 6 /home/\*/ftp/\*/\*/\*/\* if task.uid=path1.uid allow_mkdir /home/\*/ftp/\*/ if task.uid=path1.parent.uid allow_mkdir /home/\*/ftp/\*/\*/ if task.uid=path1.parent.uid allow_mkdir /home/\*/ftp/\*/\*/\*/ if task.uid=path1.parent.uid allow_rmdir /home/\*/ftp/\*/ if task.uid=path1.uid allow_rmdir /home/\*/ftp/\*/\*/ if task.uid=path1.uid allow_rmdir /home/\*/ftp/\*/\*/\*/ if task.uid=path1.uid allow_create /home/\*/ftp/\* if task.uid=path1.parent.uid allow_create /home/\*/ftp/\*/\* if task.uid=path1.parent.uid allow_create /home/\*/ftp/\*/\*/\* if task.uid=path1.parent.uid allow_create /home/\*/ftp/\*/\*/\*/\* if task.uid=path1.parent.uid allow_truncate /home/\*/ftp/\* if task.uid=path1.uid allow_truncate /home/\*/ftp/\*/\* if task.uid=path1.uid allow_truncate /home/\*/ftp/\*/\*/\* if task.uid=path1.uid allow_truncate /home/\*/ftp/\*/\*/\*/\* if task.uid=path1.uid allow_unlink /home/\*/ftp/\* if task.uid=path1.uid allow_unlink /home/\*/ftp/\*/\* if task.uid=path1.uid allow_unlink /home/\*/ftp/\*/\*/\* if task.uid=path1.uid allow_unlink /home/\*/ftp/\*/\*/\*/\* if task.uid=path1.uid allow_rename /home/\*/ftp/\* /home/\*/ftp/\* if task.uid=path1.parent.uid task.uid=path2.parent.uid allow_rename /home/\*/ftp/\*/\* /home/\*/ftp/\*/\* if task.uid=path1.parent.uid task.uid=path2.parent.uid allow_rename /home/\*/ftp/\*/\*/\* /home/\*/ftp/\*/\*/\* if task.uid=path1.parent.uid task.uid=path2.parent.uid allow_rename /home/\*/ftp/\*/\*/\*/\* /home/\*/ftp/\*/\*/\*/\* if task.uid=path1.parent.uid task.uid=path2.parent.uid allow_rename /home/\*/ftp/\*/ /home/\*/ftp/\*/ if task.uid=path1.parent.uid task.uid=path2.parent.uid allow_rename /home/\*/ftp/\*/\*/ /home/\*/ftp/\*/\*/ if task.uid=path1.parent.uid task.uid=path2.parent.uid allow_rename /home/\*/ftp/\*/\*/\*/ /home/\*/ftp/\*/\*/\*/ if task.uid=path1.parent.uid task.uid=path2.parent.uid

If you want to protect Samba service, by adding conditions in the following manner, you can forbid access to directories outside the user's home directory. To reduce damages when it is cracked, it is recommended that you should expose directories only under specific (such as "samba") directory rather than exposing whole of home directories.

Before
<kernel> /usr/sbin/smbd 6 /home/\*/samba/\* 6 /home/\*/samba/\*/\* 6 /home/\*/samba/\*/\*/\* 6 /home/\*/samba/\*/\*/\*/\* allow_mkdir /home/\*/samba/\*/ allow_mkdir /home/\*/samba/\*/\*/ allow_mkdir /home/\*/samba/\*/\*/\*/ allow_rmdir /home/\*/samba/\*/ allow_rmdir /home/\*/samba/\*/\*/ allow_rmdir /home/\*/samba/\*/\*/\*/ allow_create /home/\*/samba/\* allow_create /home/\*/samba/\*/\* allow_create /home/\*/samba/\*/\*/\* allow_create /home/\*/samba/\*/\*/\*/\* allow_truncate /home/\*/samba/\* allow_truncate /home/\*/samba/\*/\* allow_truncate /home/\*/samba/\*/\*/\* allow_truncate /home/\*/samba/\*/\*/\*/\* allow_unlink /home/\*/samba/\* allow_unlink /home/\*/samba/\*/\* allow_unlink /home/\*/samba/\*/\*/\* allow_unlink /home/\*/samba/\*/\*/\*/\* allow_rename /home/\*/samba/\* /home/\*/samba/\* allow_rename /home/\*/samba/\*/\* /home/\*/samba/\*/\* allow_rename /home/\*/samba/\*/\*/\* /home/\*/samba/\*/\*/\* allow_rename /home/\*/samba/\*/\*/\*/\* /home/\*/samba/\*/\*/\*/\* allow_rename /home/\*/samba/\*/ /home/\*/samba/\*/ allow_rename /home/\*/samba/\*/\*/ /home/\*/samba/\*/\*/ allow_rename /home/\*/samba/\*/\*/\*/ /home/\*/samba/\*/\*/\*/

After
<kernel> /usr/sbin/smbd 6 /home/\*/samba/\* if task.euid=path1.uid 6 /home/\*/samba/\*/\* if task.euid=path1.uid 6 /home/\*/samba/\*/\*/\* if task.euid=path1.uid 6 /home/\*/samba/\*/\*/\*/\* if task.euid=path1.uid allow_mkdir /home/\*/samba/\*/ if task.euid=path1.parent.uid allow_mkdir /home/\*/samba/\*/\*/ if task.euid=path1.parent.uid allow_mkdir /home/\*/samba/\*/\*/\*/ if task.euid=path1.parent.uid allow_rmdir /home/\*/samba/\*/ if task.euid=path1.uid allow_rmdir /home/\*/samba/\*/\*/ if task.euid=path1.uid allow_rmdir /home/\*/samba/\*/\*/\*/ if task.euid=path1.uid allow_create /home/\*/samba/\* if task.euid=path1.parent.uid allow_create /home/\*/samba/\*/\* if task.euid=path1.parent.uid allow_create /home/\*/samba/\*/\*/\* if task.euid=path1.parent.uid allow_create /home/\*/samba/\*/\*/\*/\* if task.euid=path1.parent.uid allow_truncate /home/\*/samba/\* if task.euid=path1.uid allow_truncate /home/\*/samba/\*/\* if task.euid=path1.uid allow_truncate /home/\*/samba/\*/\*/\* if task.euid=path1.uid allow_truncate /home/\*/samba/\*/\*/\*/\* if task.euid=path1.uid allow_unlink /home/\*/samba/\* if task.euid=path1.uid allow_unlink /home/\*/samba/\*/\* if task.euid=path1.uid allow_unlink /home/\*/samba/\*/\*/\* if task.euid=path1.uid allow_unlink /home/\*/samba/\*/\*/\*/\* if task.euid=path1.uid allow_rename /home/\*/samba/\* /home/\*/samba/\* if task.euid=path1.parent.uid task.euid=path2.parent.uid allow_rename /home/\*/samba/\*/\* /home/\*/samba/\*/\* if task.euid=path1.parent.uid task.euid=path2.parent.uid allow_rename /home/\*/samba/\*/\*/\* /home/\*/samba/\*/\*/\* if task.euid=path1.parent.uid task.euid=path2.parent.uid allow_rename /home/\*/samba/\*/\*/\*/\* /home/\*/samba/\*/\*/\*/\* if task.euid=path1.parent.uid task.euid=path2.parent.uid allow_rename /home/\*/samba/\*/ /home/\*/samba/\*/ if task.euid=path1.parent.uid task.euid=path2.parent.uid allow_rename /home/\*/samba/\*/\*/ /home/\*/samba/\*/\*/ if task.euid=path1.parent.uid task.euid=path2.parent.uid allow_rename /home/\*/samba/\*/\*/\*/ /home/\*/samba/\*/\*/\*/ if task.euid=path1.parent.uid task.euid=path2.parent.uid

If you want to protect SSH service, by adding conditions in the following manner, you can forbid login as user "root".

Before | After
<kernel> /usr/sbin/sshd 1 /bin/bash | <kernel> /usr/sbin/sshd 1 /bin/bash if task.uid!=0 task.euid!=0

See Conditional permission for available conditions.

### Patterning File Access Permissions

Append access permissions for files that are not necessarily accessed in the accept mode such as WWW contents for WWW service to /root/security/domain_policy.txt .
The following example allows /usr/sbin/httpd to read files in the /var/www/html/ directory.

<kernel> /usr/sbin/httpd 4 /var/www/html/\* 4 /var/www/html/\*/\* 4 /var/www/html/\*/\*/\* 4 /var/www/html/\*/\*/\*/\* 4 /var/www/html/\*/\*/\*/\*/\*

In the same way, modify access permissions for files using patterns that should be grouped. The following example shows /usr/sbin/smbd should handle all log files equally.

Before | After
<kernel> /usr/sbin/smbd 2 /var/log/samba/host1.log 2 /var/log/samba/host2.log 2 /var/log/samba/host3.log 2 /var/log/samba/host4.log 2 /var/log/samba/host5.log | <kernel> /usr/sbin/smbd 2 /var/log/samba/\*.log

## Rerunning accept mode

If you are sure you found all patterns, recreate the domain policy from the beginning. Give the parameter "TOMOYO_NOLOAD" to the kernel command line for the first time to skip reading domain policy.

## Permissive Mode

Boot with TOMOYO Linux kernel with the profile number for permissive mode to CCS= parameter.

Check that error messages don't appear when you operate you want to allow.

If the system works properly, the installation of TOMOYO Linux is done.

# Production State

## Enforce mode

Boot with TOMOYO Linux kernel with the profile number for enforce mode to CCS= parameter.