👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for apparmor.d (linux section 5)

APPARMOR.D(5)				     AppArmor				    APPARMOR.D(5)

NAME
       apparmor.d - syntax of security profiles for AppArmor.

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.

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; #
       introduces a comment, similar to shell scripting languages. The exception to this rule is
       that #include will include the contents of a file inline to the policy; this behaviour is
       modelled after cpp(1).

	   INCLUDE = '#include' ( ABS PATH | MAGIC PATH )

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

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

	   COMMENT = '#' TEXT

	   TEXT = any characters

	   PROFILE = [ COMMENT ... ] [ VARIABLE ASSIGNMENT ... ] ( '"' PROGRAM '"' | PROGRAM ) [
	   'flags=(complain)' ]'{' [ ( RESOURCE RULE | COMMENT | INCLUDE | SUBPROFILE |
	   'capability ' CAPABILITY | NETWORK RULE | 'change_profile -> ' PROGRAMCHILD ) ... ]
	   '}'

	   SUBPROFILE = [ COMMENT ... ] ( PROGRAMHAT | 'profile ' PROGRAMCHILD ) '{' [ ( FILE
	   RULE | COMMENT | INCLUDE ) ... ] '}'

	   CAPABILITY = (lowercase capability name without 'CAP_' prefix; see capabilities(7))

	   NETWORK RULE = 'network' [ [ DOMAIN ] [ TYPE ] [ I <PROTOCOL> ] ] ','

	   DOMAIN = ( 'inet' | 'ax25' | 'ipx' | 'appletalk' | 'netrom' | 'bridge' | 'atmpvc' |
	   'x25' | 'inet6' | 'rose' | 'netbeui' | 'security' | 'key' | 'packet' | 'ash' |
	   'econet' | 'atmsvc' | 'sna' | 'irda' | 'pppox' | 'wanpipe' | 'bluetooth' ) ','

	   TYPE = ( 'stream' | 'dgram' | 'seqpacket' |	'rdm' | 'raw' | 'packet' )

	   PROTOCOL = ( 'tcp' | 'udp' | 'icmp' )

	   PROGRAM = (non-whitespace characters except for '^', must start with '/'. Embedded
	   spaces or tabs must be quoted.)

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

	   PROGRAMCHILD = SUBPROFILE name

	   FILE RULE = RULE QUALIFIER ( '"' FILEGLOB '"' | FILEGLOB ) ACCESS ','

	   RULE QUALIFIER = [ 'audit' ] [ 'deny' ] [ 'owner' ]

	   FILEGLOB = (must start with '/' (after variable expansion), ?*[]{}^ have special
	   meanings; see below. May include VARIABLE. Rules with embedded spaces or tabs must be
	   quoted. Rules must end with '/' to apply to directories.)

	   ACCESS = ( 'r' | 'w' | 'l' | 'ix' | 'ux' | 'Ux' | 'px' | 'Px' | 'cx -> ' PROGRAMCHILD
	   | 'Cx -> ' PROGRAMCHILD | 'm' ) [ ACCESS ... ]  (not all combinations are allowed; see
	   below.)

	   VARIABLE = '@{' ALPHA [ ( ALPHANUMERIC | '_' ) ... ] '}'

	   VARIABLE ASSIGNMENT = VARIABLE ('=' | '+=') (space separated values)

	   ALIAS RULE = ABS PATH '->' REWRITTEN ABS PATH ','

	   ALPHA = ('a', 'b', 'c', ... 'z', 'A', 'B', ... 'Z')

	   ALPHANUMERIC = ('0', '1', '2', ... '9', 'a', 'b', 'c', ... 'z', 'A', 'B', ... 'Z')

       All resources and programs need a full path. There may be any number of subprofiles (aka
       child profiles) in a profile, limited only by kernel memory. Subprofile names are limited
       to 974 characters.  Child profiles can be used to confine an application in a special way,
       or when you want the child to be unconfined on the system, but confined when called from
       the parent.  Hats are a special child profile that can be used with the aa_change_hat(2)
       API call.  Applications written or modified to use aa_change_hat(2) can take advantage of
       subprofiles to run under different confinements, dependent on program logic. Several
       aa_change_hat(2)-aware applications exist, including an Apache module, mod_apparmor(5); a
       PAM module, pam_apparmor; and a Tomcat valve, tomcat_apparmor. Applications written or
       modified to use change_profile(2) transition permanently to the specified profile. libvirt
       is one such application.

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

       r    - read
       w    - write -- conflicts with append
       a    - append -- conflicts with write
       ux   - unconfined execute
       Ux   - unconfined execute -- scrub the environment
       px   - discrete profile execute
       Px   - discrete profile execute -- scrub the environment
       cx   - transition to subprofile on execute
       Cx   - transition to subprofile on execute -- scrub the environment
       ix   - inherit execute
       m    - allow PROT_EXEC with mmap(2) calls
       l    - link
       k    - lock

   Access Modes Details
       r - Read mode
	   Allows the program to have read access to the file or directory listing. Read access
	   is required for shell scripts and other interpreted content.

       w - Write mode
	   Allows the program to have write access to the file. Files and directories must have
	   this permission if they are to be unlinked (removed.)  Write mode is not required on a
	   directory to rename or create files within the directory.

	   This mode conflicts with append mode.

       a - Append mode
	   Allows the program to have a limited appending only write access to the file.  Append
	   mode will prevent an application from opening the file for write unless it passes the
	   O_APPEND parameter flag on open.

	   The mode conflicts with Write mode.

       ux - Unconfined execute mode
	   Allows the program to execute the program without any AppArmor profile being applied
	   to the program.

	   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 unconfined 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.

	   WARNING 'ux' should only be used in very special cases. It enables the designated
	   child processes to be run without any AppArmor protection.  'ux' does not scrub the
	   environment of variables such as LD_PRELOAD; as a result, the calling domain may have
	   an undue amount of influence over the callee.  Use this mode only if the child
	   absolutely must be run unconfined and LD_PRELOAD must be used. Any profile using this
	   mode provides negligible security. Use at your own risk.

	   Incompatible with 'Ux', 'px', 'Px', 'cx', 'Cx', 'ix'.

       Ux - unconfined execute -- scrub the environment
	   'Ux' allows the named program to run in 'ux' mode, but AppArmor will invoke the Linux
	   Kernel's unsafe_exec routines to scrub the environment, similar to setuid programs.
	   (See ld.so(8) for some information on setuid/setgid environment scrubbing.)

	   WARNING 'Ux' should only be used in very special cases. It enables the designated
	   child processes to be run without any AppArmor protection.  Use this mode only if the
	   child absolutely must be run unconfined. Use at your own risk.

	   Incompatible with 'ux', 'px', 'Px', 'cx', 'Cx', 'ix'.

       px - Discrete Profile execute mode
	   This mode requires that a discrete security profile is defined for a program executed
	   and forces an AppArmor domain transition. If there is no profile defined then the
	   access will be denied.

	   WARNING 'px' does not scrub the environment of variables such as LD_PRELOAD; as a
	   result, the calling domain may have an undue amount of influence over the callee.

	   Incompatible with 'Ux', 'ux', 'Px', 'cx', 'Cx', 'ix'.

       Px - Discrete Profile execute mode -- scrub the environment
	   'Px' allows the named program to run in 'px' mode, but AppArmor will invoke the Linux
	   Kernel's unsafe_exec routines to scrub the environment, similar to setuid programs.
	   (See ld.so(8) for some information on setuid/setgid environment scrubbing.)

	   Incompatible with 'Ux', 'ux', 'px', 'cx', 'Cx', 'ix'.

       cx - Transition to Subprofile execute mode
	   This mode requires that a local security profile is defined and forces an AppArmor
	   domain transition to the named profile. If there is no profile defined then the access
	   will be denied.

	   WARNING 'cx' does not scrub the environment of variables such as LD_PRELOAD; as a
	   result, the calling domain may have an undue amount of influence over the callee.

	   Incompatible with 'Ux', 'ux', 'px', 'Px', 'Cx', 'ix'.

       Cx - Transition to Subprofile execute mode -- scrub the environment
	   'Cx' allows the named program to run in 'cx' mode, but AppArmor will invoke the Linux
	   Kernel's unsafe_exec routines to scrub the environment, similar to setuid programs.
	   (See ld.so(8) for some information on setuid/setgid environment scrubbing.)

	   Incompatible with 'Ux', 'ux', 'px', 'Px', 'cx', 'ix'.

       ix - Inherit execute mode
	   Prevent the normal AppArmor domain transition on execve(2) when the profiled program
	   executes the named program. Instead, the executed resource will inherit the current
	   profile.

	   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. There is no version to scrub the environment because 'ix'
	   executions don't change privileges.

	   Incompatible with 'Ux', 'ux', 'Px', 'px', 'cx', 'Cx'. Implies 'm'.

       m - Allow executable mapping
	   This mode allows a file to be mapped into memory using mmap(2)'s PROT_EXEC flag. This
	   flag marks the pages executable; it is used on some architectures to provide non-
	   executable data pages, which can complicate exploit attempts. AppArmor uses this mode
	   to limit which files a well-behaved program (or all programs on architectures that
	   enforce non-executable memory access controls) may use as libraries, to limit the
	   effect of invalid -L flags given to ld(1) and LD_PRELOAD, LD_LIBRARY_PATH, given to
	   ld.so(8).

       l - Link mode
	   Allows the program to be able to create a link with this name.  When a link is
	   created, the new link MUST have a subset of permissions as the original file (with the
	   exception that the destination does not have to have link access.) If there is an 'x'
	   rule on the new link, it must match the original file exactly.

       k - lock mode
	   Allows the program to be able lock a file with this name.  This permission covers both
	   advisory and mandatory locking.

   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.

   Capabilities
       The only capabilities a confined process may use may be enumerated; for the complete list,
       please refer to capabilities(7). Note that granting some capabilities renders AppArmor
       confinement for that domain advisory; while open(2), read(2), write(2), etc., will still
       return error when access is not granted, some capabilities allow loading kernel modules,
       arbitrary access to IPC, ability to bypass discretionary access controls, and other
       operations that are typically reserved for the root user.

       The only operations that cannot be controlled in this manner are mount(2), umount(2), and
       loading new AppArmor policy into the kernel, which are always denied to confined
       processes.

   Network Rules
       AppArmor supports simple coarse grained network mediation.  The network rule restrict all
       socket(2) based operations.  The mediation done is a course grained check on whether a
       socket of a given type and family can be created, read, or written.  There is no mediation
       based of port number or protocol beyond tcp, udp, and raw.

       AppArmor network rules are accumulated so that the granted network permissions are the
       union of all the listed network rule permissions.

       AppArmor network rules are broad and general and become more restrictive as further
       information is specified.

       eg.

	network,	       #allow access to all networking
	network tcp,	       #allow access to tcp
	network inet tcp,      #allow access to tcp only for inet4 addresses
	network inet6 tcp,     #allow access to tcp only for inet6 addresses

   Variables
       AppArmor's policy language allows embedding variables into file rules to enable easier
       configuration for some common (and pervasive) setups.  Variables may have multiple values
       assigned, but any variable assignments must be made before the start of the profile.

       The parser will automatically expand variables to include all values that they have been
       assigned; it is an error to reference a variable without setting at least one value.

       At the time of this writing, only @{HOME} and @{HOMEDIRS} are defined in the AppArmor
       policy provided, in the /etc/apparmor.d/tunables/home file; these variables are used in
       many of the abstractions described later.  You may also add files in
       /etc/apparmor.d/tunables/home.d for site-specific customization of @{HOMEDIRS}.

   Alias rules
       AppArmor also provides alias rules for remapping paths for site-specific layouts. They are
       an alternative form of path rewriting to using variables, and are done after variable
       resolution. Alias rules must occur within the preamble of the profile. System-wide aliases
       are found in /etc/apparmor.d/tunables/alias, which is included by
       /etc/apparmor.d/tunables/global. /etc/apparmor.d/tunables/global is typically included at
       the beginning of an AppArmor profile.

   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).

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

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

       ?   can substitute for any single character excepting '/'

       [abc]
	   will substitute for the single character a, b, or c

       [a-c]
	   will substitute for the single character a, b, or c

       [^a-c]
	   will substitute for any single character not matching a, b or c

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

       When AppArmor looks up a directory the pathname being looked up will end with a slash
       (e.g., /var/tmp/); otherwise it will not end with a slash. Only rules that match a
       trailing slash will match directories. Some examples, none matching the /tmp/ directory
       itself, are:

       /tmp/*
	   Files directly in /tmp.

       /tmp/*/
	   Directories directly in /tmp.

       /tmp/**
	   Files and directories anywhere underneath /tmp.

       /tmp/**/
	   Directories anywhere underneath /tmp.

   Rule Qualifiers
       There are several rule qualifiers that can be applied to permission rules.  Rule
       qualifiers can modify the rule and/or permissions within the rule.

       audit
	   Specifies that permissions requests that match the rule should be recorded to the
	   audit log.

       deny
	   Specifies that permissions requests that match the rule should be denied without
	   logging. Can be combined with 'audit' to enable logging.

       owner
	   Specifies that the task must have the same euid/fsuid as the object being referenced
	   by the permission check.

   #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.  #include "/absolute/path"
       specifies that /absolute/path should be used.  #include "relative/path" specifies that
       relative/path should be used, where the path is relative to the current working directory.
       #include <magic/path> is the most common usage; it will load magic/path relative to a
       directory specified to apparmor_parser(8).  /etc/apparmor.d/ is the AppArmor default.

       The supplied AppArmor profiles follow several conventions; the abstractions stored in
       /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.

       abstractions/audio
	   Includes accesses to device files used for audio applications.

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

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

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

       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.

       abstractions/fonts
	   Includes access to fonts and the font libraries.

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

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

       abstractions/kerberosclient
	   Includes file access rules needed for common kerberos clients.

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

       abstractions/perl
	   Includes read access to perl modules.

       abstractions/user-download
       abstractions/user-mail
       abstractions/user-manpages
       abstractions/user-tmp
       abstractions/user-write
	   Some profiles for typical "user" programs will use these include files to describe
	   rights that users have in the system.

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

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

       The abstractions stored in /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
       /etc/apparmor.d/tunables/ directory. These variables are currently @{HOME} and
       @{HOMEDIRS}. Variables cannot be set in profile scope; they can only be set before the
       profile. Therefore, any profiles that use abstractions should either #include
       <tunables/global> or otherwise ensure that @{HOME} and @{HOMEDIRS} are set before starting
       the profile definition. The aa-autodep(8) and aa-genprof(8) utilities will automatically
       emit #include <tunables/global> in generated profiles.

EXAMPLE
       An example AppArmor profile:

	       # a variable definition in the preamble
	       @{HOME} = /home/*/ /root/

	       # 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*	     rmix,
		 /lib/lib*.so*	     r,
		 /proc/[0-9]**	     r,
		 /usr/lib/**	     r,
		 /tmp/foo.pid	     wr,
		 /tmp/foo.*	     lrw,
		 /@{HOME}/.foo_file  rw,
		 /usr/bin/baz	     Cx -> baz,

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

		 # a comment about foo's subprofile, baz.
		 profile baz {
		   #include <abstractions/bash>
		   owner /proc/[0-9]*/stat r,
		   /bin/bash ixr,
		   /var/lib/baz/ r,
		   owner /var/lib/baz/* rw,
		 }
	       }

FILES
       /etc/init.d/boot.apparmor
       /etc/apparmor.d/

SEE ALSO
       apparmor(7), apparmor_parser(8), aa-complain(1), aa-enforce(1), aa_change_hat(2),
       mod_apparmor(5), and <http://wiki.apparmor.net>.

AppArmor 2.7.0~beta1			    2011-04-01				    APPARMOR.D(5)


All times are GMT -4. The time now is 03:16 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password