Comments and line structure

and line structure for application developers for security researchers

How a profile file is divided. Rules end at a comma and not at the end of the line. Braces hold bodies. A hash starts a comment only where a new word could start and hash include is an include. The errors the parser prints for a missing comma or brace.

On the map: profile structure

▶ Watch this deck — 9 scenes, ~7 min

Worth seeing first

01 Where does a rule end?

LINE STRUCTURE # demo: a small network service profile demo /usr/bin/demo { include <abstractions/base> network inet stream, /etc/demo/** r, # configuration owner /var/lib/demo/** rwk, } network inet stream, /etc/demo/** r, owner /var/lib/demo/** rwk, , ends a rule profile demo /usr/bin/demo { } { } hold a body /etc/demo/** r, # # comment, to the end of the line no comma: not a rule one rule per line is a habit, not the grammar this deck: where a rule really ends, where # is not a comment, and what the parser says when the structure is broken
The demo profile, seven lines, with its structure characters marked one kind at a time: the commas that end rules, the braces that hold the body, the hashes that start comments, and the include line that takes no comma.

Rules end with ,. Bodies are in { }. # starts a comment to the end of the line. include lines and comments take no comma.

Look at demo's profile and ask a simple question: where does one rule end and the next begin? It looks like one rule per line, and that's how everyone writes it. But the parser doesn't read lines. It reads words, and three characters give those words structure. A comma ends a rule. Braces hold a body. A hash starts a comment that runs to the end of the line. And a few lines, like the include, take no comma at all. Most of the time the line picture and the real one agree. This deck is about the places where they don't, because that's where the confusing error messages come from.

Details and sources

Details

  • Three structural characters: , ends a rule, { and } hold a body, # starts a comment that runs to the end of the line.
  • apparmor.d(5), Comments: "Comments start with # and may begin at any place within a line. The comment ends when the line ends." (apparmor.d.pod:1173-1176).
  • The same page says "AppArmor configuration files are line-oriented" (apparmor.d.pod:98-101). For rules the parser is comma-oriented: only comments, include lines and variable assignments depend on line ends.
  • include <file> and the older #include <file> take no comma.
  • All of this is the parser's business only. Comments and line structure are gone before the policy is compiled; nothing of them reaches the kernel.
  • The profile for demo is invented for the map. Statements about the parser were checked with the parser built from the AppArmor tree at 836052d21 (-Q -K --skip-kernel-load --warn=all, nothing loaded into a kernel).

for AppArmor developers for security researchers

In the code

02 What ends with what

GRAMMAR ends with a comma rule , /etc/demo/** r, network inet stream, abi <abi/5.0>, alias /usr/ -> /opt/demo/usr/, ends with a closing brace head { rules } profile demo /usr/bin/demo { } ^admin { } deny { } if ${DEMO_DEBUG} { } no comma after } ends with the line text new line # a comment include <abstractions/base> @{APP_DATA} = /var/lib/demo /srv/demo the only line-oriented parts of the language everywhere else a new line is just white space
Three groups of constructs by what ends them: rules, abi and alias end with a comma; profile, hat, qualifier block and if block bodies end with a closing brace; comments, include lines and variable assignments end with the line.

Comma: every rule, abi, alias. Closing brace: profile, hat, child, qualifier block, if block. End of line: comments, include, variable assignments.

Here's the whole structure in three groups. Rules end with a comma: file rules, network rules, every rule keyword, and also the two preamble lines, abi and alias. Bodies end with a closing brace: profiles, hats, child profiles, qualifier blocks and if blocks, and no comma follows the brace. And three things end with the line itself: comments, include lines, and variable assignments. Those are the only parts of the language that care about line ends. Everywhere else, a new line is white space, no different from a blank.

Details and sources

Details

  • Ends with a comma: every rule (file, network, capability, mount, signal, change_profile and the others), and in the preamble abi <...>, and alias A -> B,.
  • Ends with } and no comma: a profile, a hat, a child profile, a qualifier block (deny { }, audit { }) and an if block.
  • Ends with the line: a comment; include and #include; a variable assignment @{X} = ... and a boolean assignment ${X} = .... A backslash directly before the new line continues an assignment.
  • A comma after an assignment is refused: Variable declarations do not accept trailing commas.
  • A comma after an include is a syntax error: include if exists <x>, gives syntax error, unexpected TOK_END_OF_RULE (run with the released parser 5.0.2).
  • \r\n is accepted wherever \n is: dos_line_endings.sd.
  • A bare { } block with no qualifier is accepted, and blocks nest: audit { deny { /x w, } } (5.0.2).

Read more

for AppArmor developers for security researchers

In the code

03 The comma ends the rule, not the line

COMMAS /etc/demo/** r , /var/lib/demo/** rw , /etc/demo/** r accepted: two rules /etc/demo/** r , /var/lib/demo/** rw , /proc/sys/** w, /sys/** w, two rules on one line /etc/demo/a,b r, glued to the next character: part of the word one rule, for the path /etc/demo/a,b a comma followed by a space, a new line or another comma ends the rule so: a space or a new line after every comma that ends a rule
Three fragments: two rules spread over four lines and accepted as two rules; two rules on one line; and a path with a comma inside it, where only the last comma ends the rule.

New lines are white space inside and between rules. /etc/demo/a,b r, names the path /etc/demo/a,b: a comma followed directly by a word character is part of the word.

To see that lines don't matter, break one. Put the path on one line, the permission on the next, the comma on a third, and start the next rule right after that comma. The parser accepts it: two rules. The other way works too, and you'll see it in real profiles: two short rules on one line. Then the fine print. A comma only ends a rule when something other than a word character follows it. A comma glued to the next letter is part of the word, so a path may contain one. It's rare, and it's why you put a space or a new line after every comma that ends a rule.

Details and sources

Details

  • A rule may span lines, and several rules may share a line: new lines are white space inside and between rules (parser built from the AppArmor tree at 836052d21, -Q -K --skip-kernel-load --warn=all).
  • A comma ends a rule when a blank, a new line or another comma follows. A comma followed directly by a word character is part of the word.
  • /foo,bar r, is one rule for the path /foo,bar: ok_comma_1.sd, expected result PASS.
  • /foobar, r, fails: bad_comma_1.sd, expected result FAIL. The message is syntax error, unexpected TOK_END_OF_RULE, expecting TOK_MODE.
  • A path that ends in a comma has to be quoted, "/foobar," r,: ok_comma_2.sd.
  • A doubled comma, /etc/demo/** r,,, gives syntax error, unexpected TOK_END_OF_RULE, expecting TOK_ID or TOK_MODE or TOK_SET_VAR.
  • The permission string of a file rule must be followed by white space or a comma (read from the source).

Read more

for AppArmor developers for security researchers

In the code

04 Where a hash is a comment

COMMENTS # demo: a small network service comment /etc/demo/** r, # configuration comment after the comma: always safe capability # why we need it chown, comment between the words of a plain rule /etc/demo/a#b r, not a comment the path is /etc/demo/a#b profile demo /usr/bin/demo flags=(complain # for now Invalid profile flag: #. inside ( ) the hash is a value also not a comment: inside signal, network, mount or dbus rules, before their comma safe habit: comments on their own line, or after the comma
Five places where a hash is written, each with a verdict: at the start of a line, after a rule's comma and between the words of a capability rule it is a comment; inside a path it is part of the path; inside a flags list the parser reports an invalid profile flag.

# begins a comment at the start of a line, after a rule's comma and between the words of file and capability rules. It is not a comment inside a word (/a#b), inside ( ) lists, or inside rules such as signal, network, mount, dbus before their comma.

A hash starts a comment, and the comment runs to the end of the line. But only where the parser could start a new word. At the start of a line, yes. After a rule's comma, yes. Even between the words of a file rule or a capability rule. Inside a word it's just a character: a#b is a file name. And inside a parenthesised list, such as the flags, the parser takes the hash as a value: invalid profile flag, hash. The same goes for the insides of some keyword rules, signal and network for example. So the safe habit is simple: comments on their own line, or after the comma.

Details and sources

Details

Run with the parser built from the AppArmor tree at 836052d21 (-Q -K --skip-kernel-load --warn=all, nothing loaded into a kernel):

  • Comment: at the start of a line; after a rule's comma (/etc/demo/** r, # configuration); between the words of a file rule or a capability rule.
  • Not a comment: inside a word. /etc/demo/a#b r, names the path /etc/demo/a#b.
  • Not a comment: inside a ( ) list. flags=(complain # for now gives Invalid profile flag: #.
  • Not a comment: inside a keyword rule before its comma. signal send # why gives syntax error, unexpected TOK_ID, expecting TOK_CONDID or TOK_END_OF_RULE. The rules affected are network, signal, ptrace, dbus, unix, mount, change_profile, rlimit, mqueue, userns and abi.
  • Not a comment: directly after profile, hat, ^ or ->. profile #demo { } defines a profile named #demo.
  • After a variable assignment a # is a comment and also ends the assignment: @{X} = /a /b # tail (run with the released parser 5.0.2).
  • A comment on the last line of a file needs its final new line; without it: Lexer found unexpected character: '#' (0x23) in state: INITIAL.
  • apparmor_parser -p (--preprocess, "Dump preprocessed profile") echoes comments to its output (parser_main.c:262, read from the source).

for AppArmor developers for security researchers

In the code

05 Hash include is not a comment

THE #INCLUDE EXCEPTION include <abstractions/base> include #include <abstractions/base> include, old spelling a hash in front does not switch it off # include <abstractions/base> comment ##include <abstractions/base> comment to switch an include off, put a space after the hash $ apparmor_parser --warn=pound-include ... deprecated use of '#include' a warning, off by default
Four spellings of an include line with a verdict each: include and hash include are both includes; hash, space, include and two hashes before include are comments. Below, the parser's optional warning about the old spelling.

#include <file> is an include (deprecated spelling; warning class pound-include, off by default). # include <file> and ##include <file> are comments.

One exception to remember. In old profiles, includes were written with a hash in front: #include, like in C. The parser still accepts that. So a line that starts with #include isn't a comment, it's an include. That bites when you try to disable an include by putting a hash in front of it: nothing changes, the file is still pulled in. Put a space between the hash and the word, or use two hashes, and it really is a comment. The parser can tell you about the old spelling, deprecated use of #include, but only if you turn that warning on.

Details and sources

Details

  • #include <file>, with no blank after the hash, is an include. # include <file> and ##include <file> are comments (parser built from the AppArmor tree at 836052d21).
  • apparmor.d(5): "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)" (apparmor.d.pod:98-101).
  • The old spelling is deprecated. The warning is Warning from FILE (FILE line N): deprecated use of '#include'.
  • Its warning class is pound-include, "warn when #include is used" (parser_main.c:295). Turn it on with --warn=pound-include or --warn=all; it is not in the default set (parser.h:77-78). apparmor_parser --help=warn lists the classes.
  • The pattern is not tied to the start of a line: /a r, #include <x> performs the include after the rule (run with the released parser 5.0.2).
  • A comment may follow the file name on the same line: ok_27.sd.
  • There is no word boundary after #include: a comment that begins #included by hand is read as an include of the file d and fails with Could not open 'd' (tree parser).
  • Old-style includes in the parser's own tests: new_style1.sd.

for AppArmor developers for security researchers

In the code

  • The four patterns, in order: #include if exists, include if exists, #include, include; the two with a hash call pwarn(WARN_INCLUDE, ...) (parser_lex.l:781-809). They precede the comment rule (parser_lex.l:815-818) and match the same length, so flex takes the earlier rule.
  • The file name is read in the INCLUDE and INCLUDE_EXISTS states (parser_lex.l:376-397).

06 Braces open bodies, unless they are inside a word

BRACES profile demo /usr/bin/demo { deny { /proc/sys/** w, /sys/** w, } ^admin { /etc/demo/admin.conf rw, } owner @{APP_DATA}/{cache,state}/** rwk, } profile demo /usr/bin/demo { deny { /proc/sys/** w, /sys/** w, } ^admin { /etc/demo/admin.conf rw, } } alone: a body profile, qualifier block, hat bodies nest; no comma after } owner @{APP_DATA}/{cache,state} inside a word: a pattern cache or state; these commas do not end the rule profile demo{ /etc/demo/** r, syntax error, unexpected TOK_MODE, expecting TOK_OPEN at line 2: the brace was read as part of the name leave a space before an opening brace; it may also sit on the next line
A profile with a deny block, a hat and a path containing braces: the braces that stand alone delimit bodies, the braces inside the path are a pattern. Below, profile demo with the brace glued to the name and the syntax error it causes.

A { or } that stands alone delimits a body; bodies nest and take no trailing comma. Inside a word, {a,b} is a pattern. profile demo{ fails because the brace is read as part of the name.

Braces do two unrelated jobs, and the parser tells them apart by one thing: is the brace a word by itself, or is it inside a word? Standing alone, it opens or closes a body. The profile, a qualifier block like deny, a hat. Bodies nest, and no comma follows the closing brace. Inside a word, as in the path with {cache,state}, braces are a pattern: either of these. The commas in there don't end the rule either. This is why you need a space before an opening brace. Write profile demo and the brace with no space, and the brace becomes part of the name.

Details and sources

Details

  • A { or } that stands alone opens or closes a body. Bodies nest. No comma follows the closing brace.
  • Inside a word, {a,b} is a pattern of alternatives, and its commas do not end the rule: /var/lib/demo/{cache,state}/** rw,.
  • profile demo{ fails with syntax error, unexpected TOK_MODE, expecting TOK_OPEN: without a blank the brace is read as part of the name (parser built from the AppArmor tree at 836052d21, -Q -K --skip-kernel-load --warn=all).
  • The opening brace may sit on a later line than its head: new_style3.sd has ^HAT2 on one line and { /var/log/HAT2 rwl, } on the next.
  • A missing } gives syntax error, unexpected end of file, expecting TOK_ID or TOK_MODE or TOK_SET_VAR; one too many gives syntax error, unexpected TOK_CLOSE, expecting end of file.
  • A qualifier block may carry audit, deny and owner but not a priority: priority=1 { /a r, } gives priority is not allowed on rule blocks (block.h:46-52).
  • Known discrepancy: the word open is accepted in place of {, as in profile demo /usr/bin/demo open (tree parser). There is no closing counterpart and no diagnostic.

for AppArmor developers for security researchers

In the code

07 The scanner states behind the structure for AppArmor developers for security researchers

SCANNER INITIAL parser_lex.l #include/.*\r?\n -> INCLUDE 781-802 #.*\r?\n comment, dropped 815-818 {END_OF_RULE} -> TOK_END_OF_RULE 911-917 \r?\n current_lineno++ 919-924 ASSIGN_MODE, ASSIGN_EXPR_MODE same comment rule, plus POP() 576-580, 735-739 same match length: the earlier rule wins, so #include is not a comment SIGNAL_MODE, NETWORK_MODE, ... no comment rule pushed by the keyword 856-908 POP at {END_OF_RULE} 911-917 SUB_ID 456-461 no comment rule no white-space or new-line rule LIST_VAL_MODE no comment rule inside ( ... ) known discrepancy keyword_table: "open" -> TOK_OPEN, the token of { parser_misc.c:131, parser_lex.l:834 added for mqueue rules; in INITIAL the word open is accepted where { is expected
The scanner's INITIAL state with its include, comment, end of rule and new line rules; the assignment states that share the comment rule; SUB_ID, LIST_VAL_MODE and the rule states that have no comment rule; the pop back to INITIAL at the comma; and the keyword table entry that maps open to TOK_OPEN.

Comment rule #.*\r?\n in INITIAL, ASSIGN_MODE, ASSIGN_EXPR_MODE only. #include rules precede it. {END_OF_RULE} pops rule-specific states. Known discrepancy: open yields TOK_OPEN, the token of {.

A comment is a pattern, hash to the end of the line, and it exists in three start conditions only: initial and the two assignment states. The #include patterns sit before it and match the same length, so flex picks them first. Rule keywords push their own states, which have no comment rule, and pop back to initial at the comma. The state SUB_ID, entered after profile, hat and caret, has neither a comment rule nor a white space rule. One oddity: the keyword table maps the word open to the same token as an opening brace, so in the initial state the word open acts as a brace.

Details and sources

for AppArmor developers for security researchers

Details

Read more

08 What a missing comma looks like

COMMON MISTAKES /etc/demo/** r /usr/bin/[a-z]* ix, line 3: missing an end of line character? (entry: /etc/demo/**) "end of line character" means the comma; seen at the next rule /etc/demo/** r } syntax error, unexpected TOK_CLOSE, expecting TOK_END_OF_RULE the last rule needs its comma too @{APP_DATA} = /var/lib/demo /srv/demo, Variable declarations do not accept trailing commas an assignment ends with the line /etc/demo/** r, (the file ends here, no }) syntax error, unexpected end of file, expecting TOK_ID or TOK_MODE or TOK_SET_VAR } } syntax error, unexpected TOK_CLOSE, expecting end of file one brace too many TOK_END_OF_RULE is the comma; TOK_OPEN and TOK_CLOSE are the braces
Five broken fragments with the parser's message: a missing comma between two file rules, a missing comma on the last rule, a comma after a variable assignment, a missing closing brace and an extra closing brace.

"missing an end of line character? (entry: PATH)" is a missing comma after the rule for PATH, reported at the next rule. In syntax errors TOK_END_OF_RULE is the comma, TOK_OPEN and TOK_CLOSE are braces.

Finally, what broken structure looks like. Forget the comma between two file rules and the parser asks, in its own words, whether you're missing an end of line character. It means the comma, and it reports the line of the next rule, because that's where it noticed. Forget the comma on the last rule and you get a plain syntax error at the closing brace instead. A comma after a variable assignment is refused by name. A missing closing brace is unexpected end of file. One brace too many is unexpected TOK_CLOSE, expecting end of file. Read TOK_END_OF_RULE as comma, TOK_OPEN and TOK_CLOSE as braces, and these messages become readable.

Details and sources

Details

Messages from the parser built from the AppArmor tree at 836052d21 (-Q -K --skip-kernel-load --warn=all). The full form is AppArmor parser error for FILE in profile FILE at line N: MESSAGE.

  • Missing comma between two file rules: missing an end of line character? (entry: PATH). PATH is the rule that lacks the comma; the line is that of the next rule. File rules only: other rule classes give a generic syntax error.
  • Missing comma on the last rule of a body: syntax error, unexpected TOK_CLOSE, expecting TOK_END_OF_RULE.
  • Comma after an assignment, @{X} = /a,: Variable declarations do not accept trailing commas.
  • Missing }: syntax error, unexpected end of file, expecting TOK_ID or TOK_MODE or TOK_SET_VAR. Fixture: simple_bad_no_close_brace1.sd.
  • One } too many: syntax error, unexpected TOK_CLOSE, expecting end of file.
  • Missing {: fixture simple_bad_no_opening_brace1.sd, expected result FAIL.
  • Token names in these messages: TOK_END_OF_RULE is the comma, TOK_OPEN is {, TOK_CLOSE is }.
  • A body cannot be closed and continued later: a second top-level profile of the same name gives Multiple definitions for profile NAME exist,bailing out. (parser_policy.c:60-66).

for AppArmor developers for security researchers

In the code

  • The message is an error production: file_rule_tail: opt_exec_mode id_or_var file_perms id_or_var calls yyerror(_("missing an end of line character? (entry: %s)"), $2) (parser_yacc.y:1132-1139).
  • The trailing comma error for assignments is in the scanner (parser_lex.l:570-574); the unexpected character message at parser_lex.l:930.

09 Around line structure

ROADS , { } # syn-globbing commas inside {a,b} syn-globbing braces inside a path syn-quoting a path that ends in a comma syn-qualifier-blocks braces after a qualifier syn-hats bodies inside bodies syn-include the line after the hash syn-variables ended by the line fe-lexer the scanner states adm-parser the --warn options syntax-map the three habits
Roads from the three structure characters: the comma leads to syn-globbing and syn-quoting, the braces to syn-globbing, syn-qualifier-blocks and syn-hats, the hash to syn-include; below, syn-variables, fe-lexer, adm-parser and syntax-map.

Inside words: syn-globbing, syn-quoting. Blocks: syn-qualifier-blocks, syn-hats. Includes: syn-include. Assignments: syn-variables. The scanner: fe-lexer.

Each of these three characters has a second life. Commas and braces inside a path are pattern syntax, in the globbing deck. A path that needs a real comma, a space or a quote is the quoting deck, right next door. Braces after a qualifier are qualifier blocks, and bodies inside bodies are hats. The include line has its own deck too. Variable assignments, the other line-ended construct, have theirs. And if the scanner states made you curious, the lexer deck walks through them.

Details and sources

Details

  • , ends a rule, { } hold a body, # starts a comment to the end of the line.
  • Only comments, include lines and variable assignments end with the line.
  • #include with no blank after the hash is an include, not a comment.
  • None of this reaches the kernel: it is handled by apparmor_parser before compilation.
  • Commit read for this deck: AppArmor 836052d21 (6.0.0~alpha2).

Read more

Basis of the statements on this page: "tree" means the parser built from the AppArmor commit above was run on the fragment (-Q -K --skip-kernel-load --warn=all, nothing loaded into a kernel); "5.0.2" means the released parser 5.0.2 was run; "code" means the parser source was read, not run. Comments and line structure exist only in the parser: nothing of them reaches the kernel.

Structure

FILE:     { PREAMBLE-LINE | PROFILE | COMMENT }
PROFILE:  HEAD '{' BODY '}'
BODY:     { RULE ',' | BLOCK | PROFILE | HAT | INCLUDE | COMMENT }
BLOCK:    [ QUALIFIERS ] '{' BODY '}'
COMMENT:  '#' text to the end of the line
ConstructEnds with
every rule (file, network, capability, mount, signal, change_profile and the others),
abi <...>, and alias A -> B, in the preamble,
a profile, a hat, a child profile} with no comma after it
a qualifier block (deny { }, audit { }) and an if block} with no comma after it
a commentthe end of the line
include and #includethe end of the line; no comma
a variable assignment @{X} = ... and a boolean assignment ${X} = ...the end of the line; a backslash directly before the new line continues it
  • Outside the last three rows a new line is white space. One rule may span several lines and several rules may share a line (tree).
  • A bare { } block with no qualifier is accepted, and blocks nest: audit { deny { /x w, } } (tree).
  • An opening brace may sit on a later line than its head (parser/tst/simple_tests/change_hat/new_style3.sd).
  • The include line: syn-include. Assignments: syn-variables. Qualifier blocks: syn-qualifier-blocks. Hats: syn-hats.

Characters

CharacterWhere it is structureWhere it is part of a word
,ends a rule when a blank, a new line or another , followswhen a word character follows directly: /etc/demo/a,b r, is one rule for the path /etc/demo/a,b (tree); inside {a,b} it separates alternatives; inside a quoted string ("/foobar," r,)
{ }standing alone: open and close a bodyinside a word: a pattern of alternatives, see syn-globbing; profile demo{ reads the brace as part of the name
#starts a comment in ordinary rule text and in assignmentsinside a word (/etc/demo/a#b); directly after profile, hat, ^ or ->; inside ( ) lists; inside the keyword rules listed under Comments
new lineends a comment, an include line and an assignmentwhite space everywhere else; not accepted directly after profile, hat or ^
  • \r\n is accepted wherever \n is (parser/tst/simple_tests/file/dos_line_endings.sd). A carriage return that is not followed by a line feed is a lexer error (5.0.2).
  • The permission string of a file rule must be followed by white space or a comma (code).
  • A path that needs a comma at its end, a blank or a quote: syn-quoting.

Comments

A # is a comment where the parser could start a new word:

PlaceExampleResultBasis
the start of a line# demo: a small network servicecommenttree
after a rule's comma/etc/demo/** r, # configurationcommenttree
between the words of a file rule or a capability rulecapability # why then chown, on the next linecommenttree
after a variable assignment@{X} = /a /b # tailcomment; it also ends the assignmenttree
inside a word/etc/demo/a#b r,the path /etc/demo/a#btree
inside a ( ) listflags=(complain # for nowInvalid profile flag: #.tree
inside a keyword rule, before its commasignal send # whysyntax errortree
directly after profile, hat, ^, ->profile #demo { }a profile named #demo; known discrepancy, see belowtree
  • The keyword rules whose inside is not comment-safe: network, signal, ptrace, dbus, unix, mount, change_profile, rlimit, mqueue, userns, abi. A comment after the comma of such a rule is fine.
  • The safe habit: a comment on its own line, or after a rule's comma.
  • apparmor_parser -p (preprocess) echoes comments to its output (code).
  • The parser gives no meaning to the text of a comment. The metadata that tools and the test harness keep there (# Last Modified:, #=DESCRIPTION, #=EXRESULT) is a plain comment to it.

#include

The scanner tries these four patterns, in this order, before the comment pattern:

PatternMeaning
#include if exists FILEinclude, old spelling
include if exists FILEinclude
#include FILEinclude, old spelling
include FILEinclude
  • #include with no blank after the hash is an include, not a comment. Putting one hash in front of an include line does not switch it off.
  • # include <file> and ##include <file> are comments (tree).
  • The old spelling is deprecated. The warning is Warning from FILE (FILE line N): deprecated use of '#include'. Its class is pound-include: turn it on with --warn=pound-include or --warn=all. It is not in the default set, and warnings are not printed with -N or -q.
  • The pattern is not anchored to the start of a line: /a r, #include <x> performs the include after the rule (tree).
  • A comment may follow the file name on the same line (parser/tst/simple_tests/include_tests/ok_27.sd).
  • No comma follows an include: include if exists <x>, is a syntax error (tree).
  • Search path, directories and if exists: syn-include. The warning options: adm-parser.

Errors and warnings

Errors are printed as AppArmor parser error for FILE in profile FILE at line N: MESSAGE (tree). The line is where the parser noticed the problem, often one line after the mistake.

MessageCause
missing an end of line character? (entry: PATH)a missing comma between two file rules; PATH is the rule that lacks it; reported at the line of the next rule. File rules only: other rule classes give a generic syntax error
syntax error, unexpected TOK_CLOSE, expecting TOK_END_OF_RULEa missing comma on the last rule of a body
syntax error, unexpected TOK_END_OF_RULE, expecting TOK_ID or TOK_MODE or TOK_SET_VARa doubled comma: /etc/demo/** r,,
syntax error, unexpected TOK_END_OF_RULE, expecting TOK_MODEa comma right after a path: /etc/demo/c, r, (parser/tst/simple_tests/file/bad_comma_1.sd)
syntax error, unexpected TOK_END_OF_RULEa comma after an include line (5.0.2)
Variable declarations do not accept trailing commas@{X} = /a,
syntax error, unexpected end of file, expecting TOK_ID or TOK_MODE or TOK_SET_VARa missing }
syntax error, unexpected TOK_CLOSE, expecting end of fileone } too many
syntax error, unexpected TOK_MODE, expecting TOK_OPENno blank before {: profile demo{
Invalid profile flag: #.a comment inside a flags=( ) list
syntax error, unexpected TOK_ID, expecting TOK_CONDID or TOK_END_OF_RULEa comment inside a signal rule
Lexer found unexpected character: 'C' (0xNN) in state: STATEa # on a last line that has no final new line; a new line directly after profile; a carriage return without a line feed
priority is not allowed on rule blockspriority=1 { /a r, }
Multiple definitions for profile NAME exist,bailing out.a second top-level profile of the same name; a body cannot be closed and continued later
Could not open 'FILE'an include, also one written as #include, names a file that is not found
warning: deprecated use of '#include'the old spelling, with --warn=pound-include

In syntax errors TOK_END_OF_RULE is the comma, TOK_OPEN is { and TOK_CLOSE is }.

Known discrepancies

These are things the parser does that do not look like intended design. They are described as behaviour, not as features to rely on.

  • The word open is accepted in place of {: profile demo /usr/bin/demo open, a rule and } is accepted (tree). There is no closing counterpart, and no diagnostic. No valid profile changes meaning.
  • #include has no word boundary: a comment that begins #included by hand is read as an include of the file d and fails with Could not open 'd' (tree).
  • A comment on the last line of a file needs its final new line; without it the parser stops with Lexer found unexpected character: '#' (0x23) in state: INITIAL (tree). By the pattern the same holds for a #include line (code).
  • A name may begin with # after profile, hat, ^ and ->: profile #demo { } defines a profile named #demo (tree).
  • apparmor.d(5) says "AppArmor configuration files are line-oriented". For rules the parser is comma-oriented; only comments, include lines and assignments depend on line ends.
  • Line numbers in error messages are too low after a quoted string that contains a new line: see syn-quoting.

for AppArmor developers for security researchers

Code map

WhatWhere
OPEN_BRACE, CLOSE_BRACE, END_OF_RULE definitionsparser/parser_lex.l:249-254
ID_CHARS, ID, IDS: a word excludes blank, tab, CR, LF, ", ! and ,; , followed by a word character is part of the wordparser/parser_lex.l:262-267
white space skipped, per start condition (SUB_ID is not in the list)parser/parser_lex.l:372-373
INCLUDE, INCLUDE_EXISTS: the file nameparser/parser_lex.l:376-397
SUB_ID, SUB_ID_WS: the name after profile, hat, ^, ->parser/parser_lex.l:456-461
ASSIGN_MODE: trailing comma error, comment with POP(), backslash continuation, new line with POP()parser/parser_lex.l:570-588
EXPR_MODE: { after ifparser/parser_lex.l:725-727
ASSIGN_EXPR_MODE: comment, continuation, new lineparser/parser_lex.l:735-747
the four include patterns, with pwarn(WARN_INCLUDE, ...)parser/parser_lex.l:781-809
the comment rule #.*\r?\n in INITIALparser/parser_lex.l:815-818
{ and } return TOK_OPEN and TOK_CLOSEparser/parser_lex.l:834-836
keyword lookup; rule keywords push their own start conditionparser/parser_lex.l:856-909
{END_OF_RULE} returns TOK_END_OF_RULE and pops a rule stateparser/parser_lex.l:911-917
new lines countedparser/parser_lex.l:919-924
Lexer found unexpected characterparser/parser_lex.l:930
keyword_table, with "open" mapped to TOK_OPENparser/parser_misc.c:81-138 (131)
profile_base: TOK_OPEN rules TOK_CLOSE; the include cache is saved at { and restored at }parser/parser_yacc.y:391-399, 453-455
block: TOK_OPEN rules TOK_CLOSE and its use with qualifiersparser/parser_yacc.y:738-759
file_rule_tail: the "missing an end of line character?" productionparser/parser_yacc.y:1132-1139
Invalid profile flagparser/profile.h:261
priority is not allowed on rule blocksparser/block.h:46-52
Multiple definitions for profileparser/parser_policy.c:60-66
warning class pound-include; the default warning setparser/parser_main.c:295; parser/parser.h:77-78
  • flex takes the longest match and, for equal length, the earlier rule. The #include patterns and the comment pattern both run to the end of the line, so the earlier #include rules win.
  • The comment rule exists in INITIAL, ASSIGN_MODE and ASSIGN_EXPR_MODE only. LIST_VAL_MODE, SUB_ID and the rule states (NETWORK_MODE, SIGNAL_MODE and the others) have none.
  • ID_FIRST_CHARS (parser/parser_lex.l:262) excludes # but no other definition uses it; ID_FIRST is built from ID_CHARS. This is why a name may begin with #.
  • TOK_OPEN is also the open permission of mqueue rules (parser/parser_yacc.y:1566); in MQUEUE_MODE the scanner has its own rule for the word, so the keyword_table entry only has an effect in INITIAL.
  • The scanner as a whole: fe-lexer.

Roads from here

START HERE

FILE ACCESS

PREAMBLE AND REUSE

  • include — the include lines that take no comma
  • Variables — assignments that end at the line end

QUALIFIERS

PROFILE STRUCTURE

RUNNING THE PARSER

INSIDE THE PARSER

  • The lexer — the scanner states behind these rules