# $Id$
# This publication is intellectual property of Novell Inc. Its contents
# can be duplicated, either in part or in whole, provided that a copyright
# label is visibly located on each copy.
# 
# All information found in this book has been compiled with utmost
# attention to detail. However, this does not guarantee complete accuracy.
# Neither SUSE LINUX GmbH, the authors, nor the translators shall be held
# liable for possible errors or the consequences thereof.
# 
# Many of the software and hardware descriptions cited in this book
# are registered trademarks. All trade names are subject to copyright
# restrictions and may be registered trade marks. SUSE LINUX GmbH
# essentially adheres to the manufacturer's spelling.
# 
# Names of products and trademarks appearing in this book (with or without
# specific notation) are likewise subject to trademark and trade protection
# laws and may thus fall under copyright restrictions.
# 
# Please direct suggestions and comments to apparmor-general@forge.novell.com.


=pod

=head1 NAME

apparmor.d - syntax of security profiles for AppArmor.

=head1 DESCRIPTION

AppArmor profiles describe mandatory access rights granted to given
programs and are fed to the AppArmor policy enforcement module using
apparmor_parser(8). This man page describes the format of the AppArmor
configuration files; see apparmor(7) for an overview of AppArmor.

=head1 FORMAT

The following is a BNF-style description of AppArmor policy
configuration files; see below for an example AppArmor policy file.
AppArmor configuration files are line-oriented; B<#> introduces a
comment, similar to shell scripting languages. The exception to this
rule is that B<#include> will I<include> the contents of a file inline
to the policy; this behaviour is modelled after cpp(1).

=over 4

B<INCLUDE> = '#include' ( I<ABS PATH> | I<MAGIC PATH> )

B<ABS PATH> = '"' path '"' (the path is passed to open(2))

B<MAGIC PATH> = '<' relative path '>' (the path is relative to F</etc/apparmor.d/>)

B<COMMENT> = '#' I<TEXT>

B<TEXT> = any characters

B<PROFILE> = [ I<COMMENT> ... ] I<PROGRAM> [ I<flags=(complain)> ]'{' [ ( I<RESOURCE RULE> | I<COMMENT> | I<INCLUDE> | I<SUBPROFILE> ) ... ] '}'

B<SUBPROFILE> = [ I<COMMENT> ... ] I<PROGRAMHAT> '{' [ ( I<FILE RULE> | I<COMMENT> | I<INCLUDE> ) ... ] '}'

B<PROGRAM> = (non-whitespace characters except for B<^>, must start with '/')

B<PROGRAMHAT> = '^'  (non-whitespace characters; see change_hat(2) for a description of how this "hat" is used.)

B<RESOURCE RULE> = ( I<FILE RULE> | I<NETWORK RULE> ) ','

B<FILE RULE> = ( I<FILENAME> | I<FILEGLOB> ) I<ACCESS> 

B<FILENAME> = (non-whitespace characters except for B<?*[]{}^>, must start with '/')

B<FILEGLOB> = (non-whitespace characters, must start with '/', B<?*[]{}^> have special meanings; see below.)

B<ACCESS> = ( 'r' | 'w' | 'l' | 'ix' | 'ux' | 'px' ) I<ACCESS>  (not all combinations are allowed; see below.)

=back

All resources and programs need a full path. There may be any number
of subprofiles ("hats") in a profile, limited only by kernel memory.
Subprofile names are limited to 974 characters.
Not all profiles benefit from subprofiles
--- applications must either be written or modified to use change_hat(2)
to take advantage of subprofiles. (An Apache module, mod_apparmor(5)
has been provided to use change_hat(2).)

=head2 Access Modes

File permission access modes consists of combinations of the following
modes:

=over 8

=item B<r> 	- read

=item B<w> 	- write

=item B<px> 	- discrete profile execute 

=item B<ux> 	- unconstrained execute 

=item B<ix>	- inherit execute 

=item B<l> 	- link

=back

=head2 Access Modes Details

=over 4

=item B<Read mode>

Allows the program to have read access to the resource. Read access is
required for shell scripts and other interpreted content, and determines
if an executing process can core dump or be attached to with ptrace(2).
(ptrace(2) is used by utilities such as strace(1), ltrace(1), and
gdb(1).)

=item B<Write mode>

Allows the program to have write access to the resource. Files must have
this permission if they are to be unlinked (removed.)


=item B<Unconstrained execute mode>

Allows the program to execute the resource without any AppArmor profile
being applied to the executed resource. Requires listing execute mode
as well. Incompatible with Inherit and Discrete Profile execute entries.

This mode is useful when a confined program needs to be able to perform
a privileged operation, such as rebooting the machine. By placing the
privileged section in another executable and granting unconstrained
execution rights, it is possible to bypass the mandatory constraints
imposed on all confined processes. For more information on what is
constrained, see the apparmor(7) man page.

B<WARNING> this should only be used in very special cases. It enables the
designated child processes to be run without any AppArmor protection.
Use at your own risk.

=item B<Inherit execute mode>

Prevent the normal AppArmor domain transition on execve(2) when the
profiled program executes the resource. Instead, the executed resource
will inherit the current profile. Incompatible with Unconstrained and
Discrete Profile execute entries.

This mode is useful when a confined program needs to call another
confined program without gaining the permissions of the target's
profile, or losing the permissions of the current profile.

=item B<Discrete Profile execute mode>

This mode requires that a discrete security profile is defined for
a resource executed at a AppArmor domain transition.  If there is no
profile defined then the access will be denied.  Incompatible with
Inherit and Unconstrained execute entries.

=item B<Link mode>

Allows the program to be able to create a link with this name.
When a link is created, the file that is being
linked to B<MUST> have the same access permissions as the link being
created (with the exception that the destination does not have to have
link access.)

=back

=head2 Comments

Comments start with # and may begin at any place within a line. The
comment ends when the line ends. This is the same comment style as
shell scripts.

=head2 Globbing

File resources may be specified with a globbing syntax similar to that
used by popular shells, such as csh(1), bash(1), zsh(1).

=over 4

=item B<*>

can substitute for any number of characters, excepting '/'

=item B<**>

can substitute for any number of characters, including '/'

=item B<?>

can substitute for any single character excepting '/'

=item B<[abc]>

will substitute for the single character a, b, or c

=item B<[a-c]>

will substitute for the single character a, b, or c

=item B<{ab,cd}>

will expand to one rule to match ab, one rule to match cd

=back

=head2 #include mechanism

AppArmor provides an easy abstraction mechanism to group common file
access requirements; this abstraction is an extremely flexible way to
grant site-specific rights and makes writing new AppArmor profiles very
simple by assembling the needed building blocks for any given program.

The use of '#include' is modelled directly after cpp(1); its use will
replace the '#include' statement with the specified file's contents.
B<#include "/absolute/path"> specifies that F</absolute/path> should be
used.  B<#include "relative/path"> specifies that F<relative/path> should
be used, where the path is relative to the current working directory.
B<#include E<lt>magic/pathE<gt>> is the most common usage; it will load
F<magic/path> relative to a directory specified to apparmor_parser(8).
F</etc/apparmor.d/> is the AppArmor default.

The supplied AppArmor profiles follow several conventions; the
abstractions stored in F</etc/apparmor.d/abstractions/> are some
large clusters that are used in most profiles. What follows are short
descriptions of how some of the abstractions are used.

=over 4


=item F<abstractions/audio>

Includes accesses to device files used for audio applications.

=item F<abstractions/authentication>

Includes access to files and services typically necessary for services
that perform user authentication.

=item F<abstractions/base>

Includes files that should be readable and writable in all profiles.

=item F<abstractions/bash>

Includes many files used by bash; useful for interactive shells and
programs that call system(3).

=item F<abstractions/consoles>

Includes read and write access to the device files controlling the
virtual console, sshd(8), xterm(1), etc. This abstraction is needed for
many programs that interact with users.

=item F<abstractions/fonts>

Includes access to fonts and the font libraries.

=item F<abstractions/gnome>

Includes read and write access to GNOME configuration files, as well as
read access to GNOME libraries.

=item F<abstractions/kde>

Includes read and write access to KDE configuration files, as well as
read access to KDE libraries.

=item F<abstractions/kerberosclient>

Includes file access rules needed for common kerberos clients.

=item F<abstractions/nameservice>

Includes file rules to allow DNS, LDAP, NIS, SMB, user and group password
databases, services, and protocols lookups.

=item F<abstractions/perl>

Includes read access to perl modules.

=item F<abstractions/user-download>

=item F<abstractions/user-mail>

=item F<abstractions/user-manpages>

=item F<abstractions/user-tmp>

=item F<abstractions/user-write>

Some profiles for typical "user" programs will use these include files
to describe rights that users have in the system.

=item F<abstractions/wutmp>

Includes write access to files used to maintain wtmp(5) and utmp(5)
databases, used with the w(1) and associated commands.

=item F<abstractions/X>

Includes read access to libraries, configuration files, X authentication
files, and the X socket.

=back

The abstractions stored in F</etc/apparmor.d/program-chunks/> are
intended for use by specific program suites, and are not generally
useful.

Some of the abstractions rely on variables that are set in files in the
F</etc/apparmor.d/tunables/> directory. These variables are currently
B<@{HOME}> and B<@{HOMEDIR}>. Variables cannot be set in profile scope;
they can only be set before the profile. Therefore, any profiles that
use abstractions should either B<#include E<lt>tunables/globalE<gt>> or
otherwise ensure that B<@{HOME}> and B<@{HOMEDIR}> are set before
starting the profile definition. The autodep(8) and genprof(8) utilities
will automatically emit B<#include E<lt>tunables/globalE<gt>> in
generated profiles.

=head1 EXAMPLE

An example AppArmor profile:

	# a comment about foo.
	/usr/bin/foo {
	  /bin/mount          ux,
  	  /dev/{,u}random     r,
  	  /etc/ld.so.cache    r,
  	  /etc/foo.conf       r,
  	  /etc/foo/*          r,
  	  /lib/ld-*.so*       x,
  	  /lib/lib*.so*       r,
  	  /proc/[0-9]**       r,
  	  /usr/lib/**         r,
  	  /tmp/foo.pid        wr,
  	  /tmp/foo.*          lrw,

	  # a comment about foo's subprofile, bar.
  	  ^bar {
  	    /lib/ld-*.so*       x,
  	    /usr/bin/bar        x,
  	    /var/spool/*        rwl,
  	  }
  	}

=head1 FILES

=over 4

=item F</etc/init.d/boot.apparmor>

=item F</etc/apparmor.d/>

=back

=head1 SEE ALSO

apparmor(7), apparmor_parser(8), complain(1),
enforce(1), change_hat(2), mod_apparmor(5), and
L<http://forge.novell.com/modules/xfmod/project/?apparmor>.

=cut