Info: Version 1.8.x is available.

Japanese Page

Last modified: $Date: 2015-08-31 22:19:51 +0900 (Mon, 31 Aug 2015) $

The world of TOMOYO Linux
The second installment: "Let's experience access control."

Contents of this installment.

In the previous installment, I explained steps for installing TOMOYO Linux and steps for using automatic learning mode on files and steps for saving the learned result. In this installment, I explain enforcing mode and profiles in TOMOYO Linux and steps for restricting access using enforcing mode and profiles.

Access control modes and profiles

About access control modes

In the previous installment, /etc/ccs/profile.conf has contents listed in Fig. 1. In Fig.1, string specified in "mode=" parameter is called access control mode. Access control mode takes one of disabled / learning / permissive / enforcing , and their meaning is described in Fig. 2.

♦ Fig. 1  Profile used by previous installment
0-CONFIG::file={ mode=learning }
♦ Fig. 2  Access control modes
disabledWorks as if regular kernel.
learningAn access request is not rejected even if the request violates policy.
The permission to allow the request is automatically added to policy so that the same request no longer violates policy.
permissiveAn access request is not rejected even if the request violates policy.
enforcingAn access request is rejected if the request violates policy.

In the previous installment, TOMOYO Linux was running in learning mode because "learning" is specified. As a result, all accesses on files were granted and permissions were automatically appended to policy which was loaded upon boot.

The basic procedure of defining policy is shown below.

  1. Assign learning mode⋅⋅⋅Decide domains to restrict access. Generate policy by doing operations you want to allow.
  2. Assign permissive mode⋅⋅⋅Make sure that all permissions for doing operations you want to allow are included in policy. Tune policy as needed.
  3. Assign enforcing mode⋅⋅⋅Enable access restrictions.

In this installment, let's use permissive mode and enforcing mode in accordance with this procedure.

To change access control mode upon boot, edit /etc/ccs/profile.conf . To change access control mode after boot, use ccs-setlevel command or ccs-editpolicy command. For example, Fig. 3 changes to permissive mode, Fig. 4 changes to enforcing mode. (TOMOYO Linux's permissive mode corresponds with SELinux's permissive mode, TOMOYO Linux's enforcing mode corresponds with SELinux's enforcing mode.)

♦ Fig. 3  Changing to permissive mode
# /usr/sbin/ccs-setlevel '0-CONFIG::file={ mode=permissive }'
0-CONFIG::file={ mode=permissive grant_log=yes reject_log=yes }
♦ Fig. 4  Changing to enforcing mode
# /usr/sbin/ccs-setlevel '0-CONFIG::file={ mode=enforcing }'
0-CONFIG::file={ mode=enforcing grant_log=yes reject_log=yes }

TOMOYO Linux can perform access control on not only files but also networks and capabilities and more. You can know current coverage from /proc/ccs/profile . But enabling many access controls from the beginning would confuse you. Thus, I enable only access control on files in this installment. You can try enabling other access controls as you get understand how to use.

About profiles

In TOMOYO Linux, you can specify access control modes for per a domain basis. You can change access control modes of arbitrary domains independent of the rest of domains. To specify access control modes independently, TOMOYO Linux uses definition of access control modes called "profile" (Fig. 5) and assigns profiles using ccs-setprofile command or ccs-editpolicy command. (Fig. 6) I explain usage of ccs-setprofile command later.

♦ Fig. 5  Create profiles
♦ Fig. 6  Assign profiles to domains

♦Creating profiles

In this series, I use 4 profiles. Please overwrite /etc/ccs/profile.conf with the contents listed in Fig. 7.

♦ Fig. 7  Profiles used in this series
PREFERENCE::learning={ verbose=no }
PREFERENCE::permissive={ verbose=yes }
PREFERENCE::enforcing={ verbose=yes }
0-CONFIG::file={ mode=disabled }
1-CONFIG::file={ mode=learning }
2-CONFIG::file={ mode=permissive }
3-CONFIG::file={ mode=enforcing }

The leading integer is the profile number (which can take from 0 to 255) and lines with the same profile number belong to the same profile. The assignment of profile numbers is arbitrary. But to make it easier to associate access control modes with profile numbers, this series uses profile 0 as a profile with disabled mode, profile 1 as a profile with learning mode for appending permissions, profile 2 as a profile with permissive mode for verifying permissions, profile 3 as a profile with enforcing mode for access restriction.

Overwrite /etc/ccs/profile.conf with the contents listed in Fig. 7 and reboot the system with TOMOYO Linux kernel or run command in Fig. 8 in order to reflect profile changes.

♦ Fig. 8  Reloading profiles
# /usr/sbin/ccs-loadpolicy p

Let's protect WWW services

I explain steps for creating policy for Apache as an example of mandatory access control. The pathname of Apache's main program depends on your distribution. For example, /usr/sbin/httpd for CentOS, /usr/sbin/apache2 for Debian.

Updating exception policy

Firstly, specify the pathname of Apache's main program using "initialize_domain" keyword. Run ccs-editpolicy with "e" option. (Fig. 9)

♦ Fig. 9  Executing policy editor
# /usr/sbin/ccs-editpolicy e

Then, you will see a screen titled "<<< Exception Policy Editor >>>". You will find lines starting with "initialize_domain" keyword by scrolling the screen. (Fig. 10. The contents depend on your environment.)

♦ Fig. 10  initialize_domain keyword in exception policy

If you have followed steps in the first installment, there should already be a line "initialize_domain /usr/sbin/httpd". But if you can't find the line, append by following steps.

First, press "A" key on the keyboard, and a prompt "Enter new entry>" is printed at the bottom line of the screen. Then, enter "initialize_domain /usr/sbin/httpd" and press "Enter" key, and the line you entered will be added. On the contrary, to delete this entry, move the cursor to "initialize_domain /usr/sbin/httpd" line by using up-arrow and down-arrow keys. Press "D" key on the keyboard, and a prompt "Delete selected entry? ('Y'es/'N'o)" is printed. Then press "Y" key to delete the line.

In TOMOYO Linux, different domains are assigned to the same program if the program was executed from different domains. This distinction is useful for giving different set of permissions depending on situation. But sometimes, like daemon processes, we want to give same set of permissions independent of situation. To be able to give same set of permissions independent of situation, TOMOYO Linux provides "initialize_domain" keyword.

To let a program run in the same domain no matter how the program is executed, specify the program using "initialize_domain" keyword. Programs specified using "initialize_domain" keyword runs in the child of "<kernel>" domain for both automatically executed upon startup scripts and manually restarted by administrator's login session. (Fig. 11)

♦ Fig. 11  The effect of initialize_domain keyword

Starting the program

First, create a domain for running Apache. (Fig. 12)

♦ Fig. 12  Starting Apache server
# service httpd restart

By executing Fig. 12, /etc/rc.d/init.d/httpd is executed and /usr/sbin/httpd is executed from /etc/rc.d/init.d/httpd . But if /usr/sbin/httpd is specified using "initialize_domain" keyword, "<kernel> /usr/sbin/httpd" domain is created. (If "initialize_domain /usr/sbin/httpd" is not specified in the exception policy, /usr/sbin/httpd will run in a child domain of program that executed /usr/sbin/httpd .)

Learning mode

Let's assign a profile for learning mode from profiles previously created. (Fig. 13) The "-r" option means apply recursively, which results in any domain which domainname starts with "<kernel> /usr/sbin/httpd" are assigned the specified profile. Be sure to quote appropriately when using ccs-setprofile command, or < and > will be interpreted as shell's redirection characters.

♦ Fig. 13  Assign profile for learning mode
# /usr/sbin/ccs-setprofile -r 1 '<kernel> /usr/sbin/httpd'
1 <kernel> /usr/sbin/httpd

Do operations you want to allow (such as browsing pages and using Wiki) after running the command in Fig. 13.

Permissive mode

When you have finished doing a series of operations you want to allow, assign a profile for permissive mode. (Fig. 14) Since the profile for permissive mode has a line "PREFERENCE::permissive={ verbose=yes }", warning messages starting with "WARNING:" are printed on the console whenever policy violation occurs. You can consider that all necessary permissions are appended into the policy if no warning messages are printed when you do operations you want to allow.

♦ Fig. 14  Assign profile for permissive mode
# /usr/sbin/ccs-setprofile -r 2 '<kernel> /usr/sbin/httpd'
2 <kernel> /usr/sbin/httpd

Also, tune policy at this stage. Steps for tuning policy are described later in this installment.

Enforcing mode

If you consider that creating policy is completed, assign a profile for enforcing mode. (Fig. 15)

♦ Fig. 15  Assign profile for enforcing mode
# /usr/sbin/ccs-setprofile -r 3 '<kernel> /usr/sbin/httpd'
3 <kernel> /usr/sbin/httpd

By doing Fig.15, mandatory access control is applied to domains which domainname starts with "<kernel> /usr/sbin/httpd".

To check status, you can use ccs-pstree command explained in the previous installment. The first column of each line by ccs-pstree command is the profile number. Make sure that profiles you intended are assigned to applications you want to protect using mandatory access control (in this example, /usr/sbin/httpd ).

Note that the system is protected by mandatory access control only if you assigned profile for enforcing mode.

Since the profile for enforcing mode has a line "PREFERENCE::enforcing={ verbose=yes }", warning messages starting with "ERROR:" are printed on the console whenever policy violation occurs.

Tuning policy

Patternizing pathnames

You need to specify all pathnames which applications can access, but some programs create files dynamically under /tmp/ directory with random alphabets and process ID numbers in their filenames. Such programs won't work with pathnames appended by learning mode only.

In TOMOYO Linux, some wildcards are defined for handling dynamically created files. (Fig. 16) By using wildcards appropriately, you can reduce number of entries in policy and save memory usage.

♦ Fig. 16  Wildcard expressions in TOMOYO Linux
\*Zero or more repetitions of characters other than '/'.
\@Zero or more repetitions of characters other than '/' or '.'.
\?1 byte character other than '/'.
\$One or more repetitions of decimal digits.
\+1 decimal digit.
\XOne or more repetitions of hexadecimal digits.
\x1 hexadecimal digit.
\AOne or more repetitions of alphabet characters.
\a1 alphabet character.
\-Pathname subtraction operator.
/\{dir\}/Recursive directory matching operator which matches '/' + one or more repetitions of 'dir/'.

Since '\' is used for escape character for representing wildcard, use '\\' for representing '\' itself. Also, use '\ooo' style octal representation for non-printable characters (e.g. ASCII's control codes and Japanese characters).

Let's patternize pathnames

You can patternize pathnames from policy editor. When you start ccs-editpolicy , a screen titled "<<< Domain Transition Editor >>>" will appear. Then, find "<kernel> /usr/sbin/httpd" domain. You will see a screen titled "<<< Domain Policy Editor >>>" (Fig. 17. The entries depends on your environment) by pressing "Enter" key after moving cursor to "<kernel> /usr/sbin/httpd" domain.

♦ Fig. 17  Policy for Apache

WWW servers access files under /var/www/ directory. Thus, specify like Fig. 18 for granting read access on files under /var/www/html/ directory. For each line in Fig. 18, press "A" key and enter the line and press "Enter" key. (Fig. 19)

♦ Fig. 18  An example for allowing reading under /var/www/html/ directory.
allow_read /var/www/html/\*
allow_read /var/www/html/\{\*\}/\*
♦ Fig. 19  Allow Apache to read under /var/www/html/ directory.

Some applications use temporary files. For example, if entries listed in Fig. 20 exist, these are likely temporary files created in /tmp/phpXXXXXX pattern. Therefore, you need to replace these entries using /tmp/php\?\?\?\?\?\? (this is TOMOYO Linux's wildcard representation for /tmp/phpXXXXXX pattern). Steps are shown below.

♦ Fig. 20  Temporary files
allow_read/write /tmp/phpAb9fD1
allow_read/write /tmp/phpkzqf5p
allow_read/write /tmp/php3lo7ab

First, press "A" key on the keyboard, and enter "allow_read/write /tmp/php\?\?\?\?\?\?" (this is a patternized entry for entries in Fig. 20). Next, move the cursor to the "allow_read/write /tmp/php\?\?\?\?\?\?" line and press "O" key, and you will see entries included in "allow_read/write /tmp/php\?\?\?\?\?\?" entry are marked with "&". Verify that entries listed in Fig. 20 are marked with "&" and press "D" key on the keyboard, and a prompt "Delete selected entries? ('Y'es/'N'o)" is printed, and press "Y" key on the keyboard.

Continue policy tuning using permissive mode until all necessary permissions are given.

How to save policy?

Upon boot, /sbin/ccs-init automatically loads policy from files on disk to kernel memory. But upon shutdown, nothing automatically saves policy from kernel memory to files on disk. Therefore, be sure to run ccs-savepolicy command before shutdown if you modified policy or changed profile assignment.

How to recreate policy from scratch?

The learning mode automatically appends entries to existing policy. But if you want to restart learning mode from the scratch rather than starting from existing policy, reboot the system after deleting a symbolic link named /etc/ccs/domain_policy.conf .


In this installment, I explained steps for actually performing access control and steps for protecting WWW services. All basic operations for TOMOYO Linux were explained in previous installment and this installment. Thus, you can say "I can use TOMOYO Linux" if you understood steps written in this installment.

In the next installment, I explain TOMOYO Linux's domain transitions. Don't miss it!

Go back to the first installment.  Proceed to the third installment.

Return to index page.