← Back to branch summary

~ubuntu-branches/ubuntu/precise/apparmor/precise-security

« back to all changes in this revision

Viewing changes to parser/apparmor.d.pod

  • Committer: Package Import Robot
  • Author(s): Steve Beattie, Jamie Strandboge, Serge Hallyn, Steve Beattie
  • Date: 2012-04-12 06:17:42 UTC
  • Revision ID: package-import@ubuntu.com-20120412061742-9v75hjko2mjtbewv
Tags: 2.7.102-0ubuntu3
https://launchpad.net/bugs/974089
https://launchpad.net/bugs/978297
https://launchpad.net/bugs/963756
https://launchpad.net/bugs/959560
https://launchpad.net/bugs/872446
https://launchpad.net/bugs/978584
https://launchpad.net/bugs/800826
https://launchpad.net/bugs/979095
https://launchpad.net/bugs/963756
https://launchpad.net/bugs/978038
https://launchpad.net/bugs/968956
https://launchpad.net/bugs/979135
[ Jamie Strandboge ]
* debian/patches/0007-ubuntu-manpage-updates.patch: update apparmor(5)
  to describe Ubuntu's two-stage policy load and how to add utilize it
  when developing policy (LP: #974089)

[ Serge Hallyn ]
* debian/apparmor.init: do nothing in a container.  This can be
  removed once stacked profiles are supported and used by lxc.
  (LP: #978297)

[ Steve Beattie ]
* debian/patches/0008-apparmor-lp963756.patch: Fix permission mapping
  for change_profile onexec (LP: #963756)
* debian/patches/0009-apparmor-lp959560-part1.patch,
  debian/patches/0010-apparmor-lp959560-part2.patch: Update the parser
  to support the 'in' keyword for value lists, and make mount
  operations aware of 'in' keyword so they can affect the flags build
  list (LP: #959560)
* debian/patches/0011-apparmor-lp872446.patch: fix logprof missing
  exec events in complain mode (LP: #872446)
* debian/patches/0012-apparmor-lp978584.patch: allow inet6 access in
  dovecot imap-login profile (LP: #978584)
* debian/patches/0013-apparmor-lp800826.patch: fix libapparmor
  log parsing library from dropping apparmor network events that
  contain ip addresses or ports in them (LP: #800826)
* debian/patches/0014-apparmor-lp979095.patch: document new mount rule
  syntax and usage in apparmor.d(5) manpage (LP: #979095)
* debian/patches/0015-apparmor-lp963756.patch: Fix change_onexec
  for profiles without attachment specification (LP: #963756,
  LP: #978038)
* debian/patches/0016-apparmor-lp968956.patch: Fix protocol error when
  loading policy to kernels without compat patches (LP: #968956)
* debian/patches/0017-apparmor-lp979135.patch: Fix change_profile to
  grant access to /proc/attr api (LP: #979135)

Show diffs side-by-side

added added

removed removed

Lines of Context:
parser/apparmor.d.pod
54
54
 
55
55
B<TEXT> = any characters
56
56
 
57
 
B<PROFILE> = [ I<COMMENT> ... ] [ I<VARIABLE ASSIGNMENT> ... ] ( '"' I<PROGRAM> '"' | I<PROGRAM> ) [ 'flags=(complain)' ]'{' [ ( I<RESOURCE RULE> | I<COMMENT> | I<INCLUDE> | I<SUBPROFILE> | 'capability ' I<CAPABILITY> | I<NETWORK RULE> | 'change_profile -> ' I<PROGRAMCHILD> ) ... ] '}'
 
57
B<PROFILE> = [ I<COMMENT> ... ] [ I<VARIABLE ASSIGNMENT> ... ] ( '"' I<PROGRAM> '"' | I<PROGRAM> ) [ 'flags=(complain)' ]'{' [ ( I<RESOURCE RULE> | I<COMMENT> | I<INCLUDE> | I<SUBPROFILE> | 'capability ' I<CAPABILITY> | I<NETWORK RULE> | I<MOUNT RULE> | I<FILE RULE> | 'change_profile -> ' I<PROGRAMCHILD> ) ... ] '}'
58
58
 
59
59
B<SUBPROFILE> = [ I<COMMENT> ... ] ( I<PROGRAMHAT> | 'profile ' I<PROGRAMCHILD> ) '{' [ ( I<FILE RULE> | I<COMMENT> | I<INCLUDE> ) ... ] '}'
60
60
 
75
75
 
76
76
B<PROGRAMCHILD> = I<SUBPROFILE> name
77
77
 
 
78
B<MOUNT RULE> = ( I<MOUNT> | I<REMOUNT> | I<UMOUNT> | I<PIVOT ROOT> )
 
79
 
 
80
B<MOUNT> = [ 'audit' ] [ 'deny' ] 'mount' [ I<MOUNT CONDITIONS> ] [ I<SOURCE FILEGLOB> ] [ -> [ I<MOUNTPOINT FILEGLOB> ]
 
81
 
 
82
B<REMOUNT> = [ 'audit' ] [ 'deny' ] 'remount' [ I<MOUNT CONDITIONS> ] I<MOUNTPOINT FILEGLOB>
 
83
 
 
84
B<UMOUNT> = [ 'audit' ] [ 'deny' ] 'umount' [ I<MOUNT CONDITIONS> ] I<MOUNTPOINT FILEGLOB>
 
85
 
 
86
B<PIVOT ROOT> = [ 'audit' ] [ 'deny' ] pivot_root [ I<OLD ABS PATH> ] [ I<MOUNTPOINT ABS PATH> ] [ -> I<PROGRAMCHILD> ]
 
87
 
 
88
B<MOUNT CONDITIONS> = [ ( 'fstype' | 'vfstype' ) ( '=' | 'in' ) I<MOUNT FSTYPE EXPRESSION> ] [ 'options' ( '=' | 'in' ) I<MOUNT FLAGS EXPRESSION> ]
 
89
 
 
90
B<MOUNT FSTYPE EXPRESSION> = ( I<MOUNT FSTYPE LIST> | I<MOUNT EXPRESSION> )
 
91
 
 
92
B<MOUNT FSTYPE LIST> = Comma separated list of valid filesystem and virtual filesystem types (eg ext4, debugfs, devfs, etc)
 
93
 
 
94
B<MOUNT FLAGS EXPRESSION> = ( I<MOUNT FLAGS LIST> | I<MOUNT EXPRESSION> )
 
95
 
 
96
B<MOUNT FLAGS LIST> = Comma separated list of I<MOUNT FLAGS>.
 
97
 
 
98
B<MOUNT FLAGS> = ( 'ro' | 'rw' | 'nosuid' | 'suid' | 'nodev' | 'dev' | 'noexec' | 'exec' | 'sync' | 'async' | 'remount' | 'mand' | 'nomand' | 'dirsync' | 'nodirsync' | 'noatime' | 'atime' | 'nodiratime' | 'diratime' | 'bind' | 'move' | 'rec' | 'verbose' | 'silent' | 'load' | 'acl' | 'noacl' | 'unbindable' | 'private' | 'slave' | 'shared' | 'relative' | 'norelative' | 'iversion' | 'noiversion' | 'strictatime' | 'nouser' | 'user' )
 
99
 
 
100
B<MOUNT EXPRESSION> = ( I<ALPHANUMERIC> | I<AARE> ) ...
 
101
 
 
102
B<AARE> = B<?*[]{}^> (see below for meanings)
 
103
 
78
104
B<FILE RULE> = I<RULE QUALIFIER> ( '"' I<FILEGLOB> '"' | I<FILEGLOB> ) I<ACCESS> ','
79
105
 
80
106
B<RULE QUALIFIER> = [ 'audit' ] [ 'deny' ] [ 'owner' ]
81
107
 
82
 
B<FILEGLOB> = (must start with '/' (after variable expansion), B<?*[]{}^> have special meanings; see below. May include I<VARIABLE>. Rules with embedded spaces or tabs must be quoted. Rules must end with '/' to apply to directories.)
 
108
B<FILEGLOB> = (must start with '/' (after variable expansion), B<AARE> have special meanings; see below. May include I<VARIABLE>. Rules with embedded spaces or tabs must be quoted. Rules must end with '/' to apply to directories.)
83
109
 
84
110
B<ACCESS> = ( 'r' | 'w' | 'l' | 'ix' | 'ux' | 'Ux' | 'px' | 'Px' | 'cx -> ' I<PROGRAMCHILD> | 'Cx -> ' I<PROGRAMCHILD> | 'm' ) [ I<ACCESS> ... ]  (not all combinations are allowed; see below.)
85
111
 
303
329
arbitrary access to IPC, ability to bypass discretionary access controls,
304
330
and other operations that are typically reserved for the root user.
305
331
 
306
 
The only operations that cannot be controlled in this manner are mount(2),
307
 
umount(2), and loading new AppArmor policy into the kernel, which are
308
 
always denied to confined processes.
309
 
 
310
332
=head2 Network Rules
311
333
 
312
334
AppArmor supports simple coarse grained network mediation.  The network
328
350
 network inet tcp,      #allow access to tcp only for inet4 addresses
329
351
 network inet6 tcp,     #allow access to tcp only for inet6 addresses
330
352
 
 
353
=head2 Mount Rules
 
354
 
 
355
AppArmor supports mount mediation and allows specifying filesystem types and
 
356
mount flags. The syntax of mount rules in AppArmor is based on the mount(8)
 
357
command syntax. Mount rules must contain one of the mount, remount, umount or
 
358
pivot_root keywords, but all mount conditions are optional. Unspecified
 
359
optional conditionals are assumed to match all entries (eg, not specifying
 
360
fstype means all fstypes are matched). Due to the complexity of the mount
 
361
command and how options may be specified, AppArmor allows specifying
 
362
conditionals three different ways:
 
363
 
 
364
=over 4
 
365
 
 
366
=item 1.
 
367
 
 
368
If a conditional is specified using '=', then the rule only grants permission
 
369
for mounts matching the exactly specified options. For example, an AppArmor
 
370
policy with the following rule:
 
371
 
 
372
=over 4
 
373
 
 
374
mount options=ro /dev/foo -> /mnt/,
 
375
 
 
376
=back
 
377
 
 
378
Would match:
 
379
 
 
380
=over 4
 
381
 
 
382
$ mount -o ro /dev/foo /mnt
 
383
 
 
384
=back
 
385
 
 
386
but not either of these:
 
387
 
 
388
=over 4
 
389
 
 
390
$ mount -o ro,atime /dev/foo /mnt
 
391
 
 
392
$ mount -o rw /dev/foo /mnt
 
393
 
 
394
=back
 
395
 
 
396
=item 2.
 
397
 
 
398
If a conditional is specified using 'in', then the rule grants permission for
 
399
mounts matching any combination of the specified options. For example, if an
 
400
AppArmor policy has the following rule:
 
401
 
 
402
=over 4
 
403
 
 
404
mount options in (ro,atime) /dev/foo -> /mnt/,
 
405
 
 
406
=back
 
407
 
 
408
all of these mount commands will match:
 
409
 
 
410
=over 4
 
411
 
 
412
$ mount -o ro /dev/foo /mnt
 
413
 
 
414
$ mount -o ro,atime /dev/foo /mnt
 
415
 
 
416
$ mount -o atime /dev/foo /mnt
 
417
 
 
418
=back
 
419
 
 
420
but none of these will:
 
421
 
 
422
=over 4
 
423
 
 
424
$ mount -o ro,sync /dev/foo /mnt
 
425
 
 
426
$ mount -o ro,atime,sync /dev/foo /mnt
 
427
 
 
428
$ mount -o rw /dev/foo /mnt
 
429
 
 
430
$ mount -o rw,noatime /dev/foo /mnt
 
431
 
 
432
$ mount /dev/foo /mnt
 
433
 
 
434
=back
 
435
 
 
436
=item 3.
 
437
 
 
438
If multiple conditionals are specified in a single mount rule, then the rule
 
439
grants permission for each set of options. This provides a shorthand when
 
440
writing mount rules which might help to logically break up a conditional. For
 
441
example, if an AppArmor policy has the following rule:
 
442
 
 
443
=over 4
 
444
 
 
445
mount options=ro options=atime
 
446
 
 
447
=back
 
448
 
 
449
both of these mount commands will match:
 
450
 
 
451
=over 4
 
452
 
 
453
$ mount -o ro /dev/foo /mnt
 
454
 
 
455
$ mount -o atime /dev/foo /mnt
 
456
 
 
457
=back
 
458
 
 
459
but this one will not:
 
460
 
 
461
=over 4
 
462
 
 
463
$ mount -o ro,atime /dev/foo /mnt
 
464
 
 
465
=back
 
466
 
 
467
=back
 
468
 
 
469
Note that separate mount rules are distinct and the options do not accumulate.
 
470
For example, these AppArmor mount rules:
 
471
 
 
472
=over 4
 
473
 
 
474
mount options=ro,
 
475
mount options=atime,
 
476
 
 
477
=back
 
478
 
 
479
are not equivalent to either of these mount rules:
 
480
 
 
481
=over 4
 
482
 
 
483
mount options=(ro,atime),
 
484
 
 
485
mount options in (ro,atime),
 
486
 
 
487
=back
 
488
 
 
489
To help clarify the flexibility and complexity of mount rules, here are some
 
490
example rules with accompanying matching commands:
 
491
 
 
492
=over 4
 
493
 
 
494
=item B<mount,>
 
495
 
 
496
the 'mount' rule without any conditionals is the most generic and allows any
 
497
mount. Equivalent to 'mount fstype=** options=** ** -> /**'.
 
498
 
 
499
=item B<mount /dev/foo,>
 
500
 
 
501
allow mounting of /dev/foo anywhere with any options. Some matching mount
 
502
commands:
 
503
 
 
504
=over 4
 
505
 
 
506
$ mount /dev/foo /mnt
 
507
 
 
508
$ mount -t ext3 /dev/foo /mnt
 
509
 
 
510
$ mount -t vfat /dev/foo /mnt
 
511
 
 
512
$ mount -o ro,atime,noexec,nodiratime /dev/foo /srv/some/mountpoint
 
513
 
 
514
=back
 
515
 
 
516
=item B<mount options=ro /dev/foo,>
 
517
 
 
518
allow mounting of /dev/foo anywhere, as read only. Some matching mount
 
519
commands:
 
520
 
 
521
=over 4
 
522
 
 
523
$ mount -o ro /dev/foo /mnt
 
524
 
 
525
$ mount -o ro /dev/foo /some/where/else
 
526
 
 
527
=back
 
528
 
 
529
=item B<mount options=(ro,atime) /dev/foo,>
 
530
 
 
531
allow mount of /dev/foo anywhere, as read only and using inode access times.
 
532
Some matching mount commands:
 
533
 
 
534
=over 4
 
535
 
 
536
$ mount -o ro,atime /dev/foo /mnt
 
537
 
 
538
$ mount -o ro,atime /dev/foo /some/where/else
 
539
 
 
540
=back
 
541
 
 
542
=item B<mount options in (ro,atime) /dev/foo,>
 
543
 
 
544
allow mount of /dev/foo anywhere using some combination of 'ro' and 'atime'
 
545
(see above). Some matching mount commands:
 
546
 
 
547
=over 4
 
548
 
 
549
$ mount -o ro /dev/foo /mnt
 
550
 
 
551
$ mount -o atime /dev/foo /some/where/else
 
552
 
 
553
$ mount -o ro,atime /dev/foo /some/other/place
 
554
 
 
555
=back
 
556
 
 
557
=item B<mount options=ro /dev/foo, mount options=atime /dev/foo,>
 
558
 
 
559
allow mount of /dev/foo anywhere as read only, and allow mount of /dev/foo
 
560
anywhere using inode access times. Note this is expressed as two different
 
561
rules. Matches:
 
562
 
 
563
=over 4
 
564
 
 
565
$ mount -o ro /dev/foo /mnt/1
 
566
 
 
567
$ mount -o atime /dev/foo /mnt/2
 
568
 
 
569
=back
 
570
 
 
571
=item B<< mount -> /mnt/**, >>
 
572
 
 
573
allow mounting anything under a directory in /mnt/**. Some matching mount
 
574
commands:
 
575
 
 
576
=over 4
 
577
 
 
578
$ mount /dev/foo1 /mnt/1
 
579
 
 
580
$ mount -o ro,atime,noexec,nodiratime /dev/foo2 /mnt/deep/path/foo2
 
581
 
 
582
=back
 
583
 
 
584
=item B<< mount options=ro -> /mnt/**, >>
 
585
 
 
586
allow mounting anything under /mnt/**, as read only. Some matching mount
 
587
commands:
 
588
 
 
589
=over 4
 
590
 
 
591
$ mount -o ro /dev/foo1 /mnt/1
 
592
 
 
593
$ mount -o ro /dev/foo2 /mnt/deep/path/foo2
 
594
 
 
595
=back
 
596
 
 
597
=item B<< mount fstype=ext3 options=(rw,atime) /dev/sdb1 -> /mnt/stick/, >>
 
598
 
 
599
allow mounting an ext3 filesystem in /dev/sdb1 on /mnt/stick as read/write and
 
600
using inode access times. Matches only:
 
601
 
 
602
=over 4
 
603
 
 
604
$ mount -o rw,atime /dev/sdb1 /mnt/stick
 
605
 
 
606
=back
 
607
 
 
608
=item B<< mount options=(ro, atime) options in (nodev, user) /dev/foo -> /mnt/, >>
 
609
 
 
610
allow mounting /dev/foo on /mmt/ read only and using inode access times or
 
611
allow mounting /dev/foo on /mnt/ with some combination of 'nodev' and 'user'.
 
612
Matches only:
 
613
 
 
614
=over 4
 
615
 
 
616
$ mount -o ro,atime /dev/foo /mnt
 
617
 
 
618
$ mount -o nodev /dev/foo /mnt
 
619
 
 
620
$ mount -o user /dev/foo /mnt
 
621
 
 
622
$ mount -o nodev,user /dev/foo /mnt
 
623
 
 
624
=back
 
625
 
 
626
=back
 
627
 
331
628
=head2 Variables
332
629
 
333
630
AppArmor's policy language allows embedding variables into file rules
605
902
 
606
903
=back
607
904
 
 
905
=head1 KNOWN BUGS
 
906
 
 
907
=over 4
 
908
 
 
909
Mount options support the use of pattern matching but mount flags are not
 
910
correctly intersected against specified patterns. Eg, 'mount options=**,'
 
911
should be equivalent to 'mount,', but it is not. (LP: #965690)
 
912
 
 
913
The fstype may not be matched against when certain mount command flags are
 
914
used. Specifically fstype matching currently only works when creating a new
 
915
mount and not remount, bind, etc.
 
916
 
 
917
Mount rules with multiple 'options' conditionals are not applied as documented
 
918
but instead merged such that 'options in (ro,nodev) options in (atime)' is
 
919
equivalent to 'options in (ro,nodev,atime)'.
 
920
 
 
921
When specifying mount options with the 'in' conditional, both the positive and
 
922
negative values match when specifying one or the other. Eg, 'rw' matches when
 
923
'ro' is specified and 'dev' matches when 'nodev' is specified such that
 
924
'options in (ro,nodev)' is equivalent to 'options in (rw,dev)'.
 
925
 
 
926
=back
 
927
 
608
928
=head1 SEE ALSO
609
929
 
610
930
apparmor(7), apparmor_parser(8), aa-complain(1),