.\" Copyright (C) 2009 Red Hat, Inc. All Rights Reserved. 
.\" Written by Ivana Varekova <varekova@redhat.com> 

.TH CGRULES.CONF  5 2009-03-10 "Linux" "libcgroup Manual"
.SH NAME
cgrules.conf \- libcgroup configuration file 
.SH DESCRIPTION
.B "cgrules.conf"
configuration file is used by
.B libcgroups
to define control groups to which a process belongs.


The file contains a list of rules which assign to a defined group/user a control
group in a subsystem (or control groups in subsystems).

Rules have two formats: 

.in +4n
.nf
<user>               	<controllers>		<destination>
.fi
.nf
<user>:<process name>	<controllers>		<destination>
.fi
.in

Where:

.I user
can be:
.nf
    - a user name
    - a group name with @group syntax
    - the wildcard '*', for any user or group
    - '%', which is equivalent to "ditto" (useful for 
      multi-line rules where different cgroups need to be 
      specified for various hierarchies for a single user)
.fi

.I process name
is optional and it can be:
.nf
    - a process name
    - a full command path of a process
.fi

.I controllers
can be:
.nf
    - comma separated controller names (no spaces) or 
    - * (for all mounted controllers)
.fi

.I destination
can be:
.nf
    - path relative to the controller hierarchy (ex. pgrp1/gid1/uid1)
    - following strings will get expanded

          %u     username, uid if name resolving fails
          %U     uid
          %g     group name, gid if name resolving fails
          %G     gid
          %p     process name, pid if name not available
          %P     pid

          '\\' can be used to escape '%'
.fi

First rule which matches the criteria will be executed.


Any text starting with '#' is considered as a start of comment line and is
ignored.


.SH EXAMPLES
.nf
student         devices         /usergroup/students
.fi
Student's processes in the 'devices' subsystem belong to the control
group /usergroup/students.

.nf
student:cp       devices         /usergroup/students/cp
.fi
When student executes 'cp' command, the processes in the 'devices' subsystem
belong to the control group /usergroup/students/cp.

.nf
@admin           *              admingroup/
.fi
Processes started by anybody from admin group no matter in what subsystem belong
to the control group admingroup/.

.nf
peter           cpu             test1/
%               memory          test2/
.fi
The first line says Peter's task for cpu controller belongs to test1 control
group. The second one says Peter's tasks for memory controller belong to test2/
control group.

.nf 
*               *               default/ 
.fi
All processes in any subsystem belong to the control group default/. Since
the earliest matched rule is applied, it makes sense to have this line
at the end of the list. It will put a task which was not mentioned in the
previous rules to default/ control group.



.SH FILES
.LP
.PD .1v
.TP 20
.B /etc/cgrules.conf
.TP
default libcgroup configuration file
.PD .


.SH SEE ALSO
cgconfig.conf (5), cgclassify (1), cgred.conf (5)

.SH BUGS