Variable assignment

=, +=, ?=, := for application developers

Four operators assign a variable in the preamble. The equals sign declares a new variable and fails if the name exists. Plus equals adds values to an existing set. Question mark equals declares only if the name is free. Colon equals replaces. Boolean variables take all but plus equals.

On the map: preamble and reuse

▶ Watch this deck — 8 scenes, ~5 min

Worth seeing first

  • Variables — set variables and their values, before the four operators

01 The variable already has a value

ASSIGNMENT tunables/home, included by tunables/global @{HOMEDIRS}=/home/ demo's preamble include <tunables/global> @{HOMEDIRS} = /srv/nfs/home/ variable @{HOMEDIRS} was previously declared exit status 1 add a value set it only if nobody did replace it += ?= := = is for a name that is new
The shipped file tunables/home declares @{HOMEDIRS}=/home/. Demo's preamble includes tunables/global and then assigns @{HOMEDIRS} = /srv/nfs/home/ with a plain equals sign. The parser answers: variable @{HOMEDIRS} was previously declared, exit status 1. Three intentions, add a value, set it only if nobody did, replace it, each get an operator: +=, ?= and :=.

= declares a new variable and is an error for an existing one. +=, ?= and := say what to do with an existing name.

Most variables you use were declared by somebody else, in a tunables file. So when you write an assignment in your own preamble, the name often already exists. Try the plain equals sign on the @{HOMEDIRS} variable, and the parser refuses: the variable was previously declared. That makes you say what you mean. Do you want to add a value, give a default in case nobody set it, or throw the old value away? There's an operator for each. The plain equals sign is kept for names that are new.

Details and sources

Details

  • = creates the variable and is an error if the name exists.
  • The slide's case was run with the tree's parser for this deck: include <tunables/global> on line 1 and @{HOMEDIRS} = /srv/nfs/home/ on line 2. Output: '@{HOMEDIRS}' is already defined, then AppArmor parser error for /work/va-home.sd in profile /work/va-home.sd at line 3: variable @{HOMEDIRS} was previously declared, exit status 1.
  • The assignment is on line 2 and the message says line 3: the line reported is that of the next token.
  • The same with demo's own variable (@{APP_DATA} = /var/lib/demo, then @{APP_DATA} = /srv/demo) prints '@{APP_DATA}' is already defined and variable @{APP_DATA} was previously declared, exit status 1 (run with the tree's parser for this deck).
  • The shipped declaration is @{HOMEDIRS}=/home/ in home, which tunables/global includes. The shipped tunables files use only =.
  • The parser's own test: @{FOO}=foo then @{FOO}=bar (vars_reassignment_1.sd, expected to fail).

for AppArmor developers for security researchers

In the code

  • global_symtab.add_var(); on failure yyerror("variable %s was previously declared") (parser_yacc.y:539-545).
  • The first line of output, '%s' is already defined, is printed by add_var itself (symtab.cc:30-36).

02 A variable, one of four operators, the rest of the line

GRAMMAR @{NAME} ${NAME} = += ?= := values expression then the end of the line @{APP_DATA} = /var/lib/demo /srv/demo line 3 of demo's file declare add declare unless declared replace for a set variable for a boolean ${NAME} += a boolean has nothing to add to preamble only; no comma
Syntax diagram of an assignment: a set variable @{NAME} or a boolean variable ${NAME}, then one of the four operators =, +=, ?= and :=, labelled declare, add, declare unless declared and replace, then values for a set variable or an expression for a boolean, up to the end of the line. Demo's line 3 is the example. ${NAME} += is struck out.

VARIABLE ( = | += | ?= | := ) ... to the end of the line. Booleans take =, ?= and :=.

An assignment has three parts: the variable, an operator and the rest of the line. There are four operators, and they stand in the same spot. On screen, top to bottom: declare, add, declare unless declared, and replace. What follows the operator differs by kind: a set variable takes values, a boolean takes an expression. The same four work for both kinds of variable, with one exception: you can't add to a boolean. Like every assignment, this lives in the preamble and ends with the line.

Details and sources

Details

  • The four operators stand in the same place: = declares, += adds values to an existing set, ?= declares unless the name is declared, := replaces.
  • A set variable takes a list of values, a boolean variable takes an expression: see variables and boolean variables.
  • A boolean takes =, ?= and :=. ${NAME} += ... is the error Invalid assignment += not allowed with boolean variables.
  • The man page says "AppArmor provides 3 different assignment operators" and then describes four (apparmor.d.pod:2375-2389). The deck follows the code.
  • Known discrepancy: apparmor.d(5): the grammar summary and text disagree with the parser in several places.

for AppArmor developers for security researchers

In the code

03 Four operators, watched in the table

THE TABLE the preamble @{APP_DATA} = /var/lib/demo variables, after each line @APP_DATA = "/var/lib/demo" created @{APP_DATA} += /srv/demo @APP_DATA = "/srv/demo" "/var/lib/demo" added @{CACHE} ?= /var/cache/demo @CACHE = "/var/cache/demo" free: created @{LOGS} = /var/log/demo @{LOGS} := /srv/log/demo @LOGS = "/var/log/demo" @LOGS = "/srv/log/demo" replaced $ apparmor_parser -Q -D variables demo prints the rows that are not struck out owner @{APP_DATA}/** rw, compiles to {/srv/demo,/var/lib/demo}/**
Five assignment lines on the left and the table of variables on the right, one state per line. @{APP_DATA} = /var/lib/demo creates the row. += /srv/demo replaces it by a row with two values. @{CACHE} ?= /var/cache/demo creates a row. @{LOGS} = /var/log/demo creates a row and := /srv/log/demo replaces it. The dump of variables prints the rows that are left, and the rule owner @{APP_DATA}/** rw compiles to {/srv/demo,/var/lib/demo}/**.

= creates, += adds to the set, ?= creates if the name is free, := replaces.

Watch the table while five lines go by. The first declares the @{APP_DATA} variable with one value. The second adds a value, so the set now has two. The third uses ?= on a name nobody has used: it's created, just as the plain operator would have done. The fourth and fifth declare a variable for logs and then replace it: the old value is gone, not added to. Print the table and you get precisely the rows that are left. And the rule in the profile sees the final state: both data directories.

Details and sources

Details

  • The five lines are the first five lines of a side profile written for this deck. Every state on the slide was run with the tree's parser for this deck, by compiling the first one, two, three, four and five lines with -D variables:
  • after line 1: @APP_DATA = "/var/lib/demo";
  • after line 2: @APP_DATA = "/srv/demo" "/var/lib/demo";
  • after line 3: that row and @CACHE = "/var/cache/demo";
  • after line 4: those rows and @LOGS = "/var/log/demo";
  • after line 5: @LOGS = "/srv/log/demo", @CACHE = "/var/cache/demo", @APP_DATA = "/srv/demo" "/var/lib/demo".
  • The whole profile also assigns ${DEMO_DEBUG} = false and ${DEMO_DEBUG} := true; its dump has the three rows above and $DEMO_DEBUG = true, exit status 0, nothing on standard error.
  • Its rule owner @{APP_DATA}/** rw, prints aare: {/srv/demo,/var/lib/demo}/** with -D rule-exprs (run with the tree's parser for this deck).
  • The dump prints the table in its own order, not in the order of the lines. The slide orders the rows by line.
  • Recorded in the research notes: @{A} = /a /b then @{A} += /c gives @A = "/a" "/b" "/c" and the rule {/a,/b,/c}/x; @{C} = /c1 then @{C} := /c2 /c3 gives @C = "/c2" "/c3".
  • The parser's own tests: ?= then += (vars_simple_assignment_combination_1.sd, expected to pass); = then := (vars_simple_assignment_20.sd, expected to pass).

for AppArmor developers for security researchers

In the code

04 Which operator for which file

WHO WRITES WHAT met in this order tunables/home @{HOMEDIRS}=/home/ the owner declares tunables/home.d/site.local @{HOMEDIRS} += /srv/nfs/home/ a site file adds @{HOME}/.ssh/** is then {/home/*,/root,/srv/nfs/home/*}/.ssh/** demo's preamble @{CACHE} ?= /var/cache/demo a default, unless set above @{LOGS} := /srv/log/demo replace: what was set above is gone each line acts on the table as it is when the line is reached
Three files met in order. The shipped tunables/home declares @{HOMEDIRS}=/home/. The administrator's tunables/home.d/site.local adds a value with @{HOMEDIRS} += /srv/nfs/home/, and the home rule then also covers /srv/nfs/home/*. Demo's preamble gives a default with @{CACHE} ?= /var/cache/demo and replaces a value with @{LOGS} := /srv/log/demo.

The owner uses =, a site file +=, a default ?=, an override :=. Order matters.

In practice the four operators belong to different people. The shipped file that owns a variable declares it with the plain equals sign. The administrator's site file, included right after, adds to it with +=, which only works because the declaration came first. Your own preamble can offer a default with ?=: it takes effect only if nothing above has set that name. And := is the blunt one: it replaces whatever was there. In every case the line acts on the table as it stands at that moment, so the order of includes and lines matters.

Details and sources

Details

  • The first box is the shipped file home.
  • The second box is the shipped file site.local with its commented example made active. As shipped, the line reads #@{HOMEDIRS}+=/srv/nfs/home/ /mnt/home/.
  • The effect shown under it was run with the tree's parser for this deck. The image's tree cannot be changed, so the line @{HOMEDIRS} += /srv/nfs/home/ was put in a file of its own and included with include if exists after tunables/global; it stands in for a file in tunables/home.d/. The rule audit deny @{HOME}/.ssh/** rw, then prints aare: {/home/*,/root,/srv/nfs/home/*}/.ssh/**, exit status 0.
  • The two lines of the third box are from the side profile of the scene "Four operators, watched in the table".
  • ?= on a name that is declared leaves the value alone: @{FOO}=foo then @{FOO} ?=bar (vars_simple_assignment_16.sd, expected to pass). Recorded in the research notes: @{B} ?= /first then @{B} ?= /second leaves @B = "/first", exit status 0.
  • Known discrepancy: ?= on a declared variable prints '@{NAME}' is already defined.
  • ?= must come after the assignment it yields to. A = after ?= or := has created the variable is the "previously declared" error (vars_bad_assign_after_cond_1.sd, vars_bad_assign_after_over_1.sd, both expected to fail).
  • Recorded in the research notes: := also changes the kind of a variable. ${A} = true then @{A} := /a prints @A = "/a". Whether that is intended was not determined.
  • Known discrepancy: The files of an included directory are compiled in reverse alphabetical order, and an error in one is reported with a neighbour's file name. It decides whether a = in one site file is met before a += in another, so do not make two files of one directory depend on each other.

05 Booleans: three of the four

BOOLEANS ${DEMO_DEBUG} = false variables $DEMO_DEBUG = false ${DEMO_DEBUG} := true $DEMO_DEBUG = true replaced, as for a set ${DEMO_DEBUG} += true Invalid assignment += not allowed with boolean variables ${DEBUG} = true @{DEBUG} = /var/log/debug variable @{DEBUG} was previously declared one table for both kinds: a name is a set or a boolean, not both
${DEMO_DEBUG} = false creates the table row $DEMO_DEBUG = false, and ${DEMO_DEBUG} := true replaces it by $DEMO_DEBUG = true. ${DEMO_DEBUG} += true is refused: Invalid assignment += not allowed with boolean variables. A boolean ${DEBUG} followed by a set variable @{DEBUG} is refused: variable @{DEBUG} was previously declared.

Booleans take =, ?= and :=. += is Invalid assignment += not allowed with boolean variables.

Boolean variables, the ones with a dollar sign, use the same operators. Declare the debug switch as false, replace it with true further down, and the table shows true. ?= works too, as a default. The one that doesn't is +=: a boolean is a single truth value, there's nothing to add to, and the parser says exactly that. And since both kinds live in one table, a name can only be one of them. Declare a boolean called debug and a set called debug, and the second line is refused as previously declared. One name, one kind.

Details and sources

Details

  • The first two lines are lines 6 and 7 of the side profile of the scene "Four operators, watched in the table". Its -D variables dump prints $DEMO_DEBUG = true (run with the tree's parser for this deck). With ${DEMO_DEBUG} = false alone the dump prints $DEMO_DEBUG = false.
  • ${DEMO_DEBUG} += true in full, run with the tree's parser for this deck: AppArmor parser error for /work/va-boolplus.sd in profile /work/va-boolplus.sd at line 3: Invalid assignment += not allowed with boolean variables, exit status 1. The assignment is on line 2.
  • ${DEBUG} = true then @{DEBUG} = /var/log/debug, run with the tree's parser for this deck: '@{DEBUG}' is already defined, then ... at line 3: variable @{DEBUG} was previously declared, exit status 1.
  • The parser's own tests: $VAR = True then $VAR ?= False (boolean_cond_2.sd, expected to pass); $VAR := False (boolean_over_1.sd, expected to pass).
  • Known discrepancy: += on a boolean reports that the variable was not declared. This is the set-variable form: ${A} = true then @{A} += /a prints Variable A is not a set variable and then variable @{A} was not previously declared, but is being assigned additional values (recorded in the research notes).

for AppArmor developers for security researchers

In the code

06 One grammar rule, three calls on the symbol table for AppArmor developers for security researchers

IN THE PARSER varassign: TOK_SET_VAR assign_op valuelist assign_op: TOK_EQUALS | TOK_ADD_ASSIGN | TOK_COND_ASSIGN | TOK_OVERRIDE_ASSIGN global_symtab = add_var(name, values) fails: "variable %s was previously declared" += add_set_value(name, values) fails: "variable %s was not previously declared, but is being assigned additional values" ?= add_var(name, values) the same call as =; the failure is ignored := delete_var(name) then add_var(name, values) varassign: TOK_BOOL_VAR assign_op expr the same switch; += is refused before any call; the expression is evaluated at once
The production varassign: TOK_SET_VAR assign_op valuelist and the rule assign_op with its four tokens. Four lanes lead to the symbol table global_symtab: = calls add_var and reports "was previously declared" on failure; += calls add_set_value and reports "was not previously declared, but is being assigned additional values"; ?= calls add_var and ignores the failure; := calls delete_var and then add_var. The boolean production uses the same switch.

parser_yacc.y:519-570: = and ?= call add_var, += calls add_set_value, := calls delete_var then add_var.

In the grammar there's one rule for the operator and one production each for the two kinds of variable. The action switches on the operator. Plain equals calls add_var on the global symbol table and turns a failure into the previously declared error. += calls add_set_value, and a failure there becomes the not previously declared error. ?= makes the same add_var call and simply ignores the failure. := deletes the name and adds it again. The boolean production runs the same switch, refuses += up front, and stores the result of its expression straight away.

Details and sources

for AppArmor developers for security researchers

Details

  • assign_op yields one of four token values (parser_yacc.y:519-522). The action of varassign: TOK_SET_VAR assign_op valuelist switches on it (parser_yacc.y:524-548); the boolean production is at parser_yacc.y:550-570.
  • add_var prints '%s' is already defined itself, whatever the caller (symtab.cc:30-36).
  • add_set_value (symtab.cc:90-101) prints Failed to find declaration for: NAME for an unknown name.
  • delete_var: symtab.cc:103-112.
  • The line number of an error is that of the token after the assignment, because the action runs when the next token has been read. Run with the tree's parser for this deck: line 3 is reported for an assignment on line 2.
  • Known discrepancy: ?= on a declared variable prints '@{NAME}' is already defined.
  • Known discrepancy: += on a boolean reports that the variable was not declared.

for security researchers

Attack surface

  • += and := let any later preamble text change what every rule written with a shipped variable means.
  • The later text can come from a .d directory: see include if exists.
  • Review the final table with -D variables, not the shipped assignment.

07 The operator did not fit the table

MISTAKES 1 @{APP_DATA} = /var/lib/demo 2 @{APP_DATA} = /srv/demo variable @{APP_DATA} was previously declared use += or := 1 @{APP_DATA} += /srv/demo nothing has declared it yet variable @{APP_DATA} was not previously declared, but is being assigned additional values 1 @{CACHE} ?= /var/cache/demo 2 @{CACHE} = /tmp/demo variable @{CACHE} was previously declared ?= created it the message says line 3 the message says line 2 the message says line 3 the line number in the message is one too high in all three: the parser reports the mistake when it reaches the next line
Three wrong assignments and the parser's messages. A second = on @{APP_DATA}, on line 2: was previously declared, reported at line 3. += on a name that does not exist, on line 1: was not previously declared, but is being assigned additional values, reported at line 2. = after ?= created the variable, on line 2: was previously declared, reported at line 3. The line number in the message is one too high in each.

= needs a free name, += needs an existing set. The reported line can be the one after the assignment.

Every error here means the same thing: the table wasn't in the state your operator needs. Equals on a name that exists. += on a name that doesn't, usually because the include that declares it is missing or comes later. A plain equals after a ?= has already created the variable. One practical hint: the parser reports each of these when it reaches the next line, so the line number in the message can be one higher than the line you need to fix.

Details and sources

Details

  • All three rows were run with the tree's parser for this deck; each ends with exit status 1. The muted numbers on the slide are line numbers of the file.
  • Row 1: '@{APP_DATA}' is already defined, then ... at line 3: variable @{APP_DATA} was previously declared. The second assignment is on line 2.
  • Row 2: Failed to find declaration for: APP_DATA, then ... at line 2: variable @{APP_DATA} was not previously declared, but is being assigned additional values. The assignment is on line 1.
  • Row 3: '@{CACHE}' is already defined, then ... at line 3: variable @{CACHE} was previously declared. The second assignment is on line 2. The parser's own test of this case is vars_bad_assign_after_cond_1.sd.
  • The three messages come from the grammar and name the line of the next token, which is why they are one too high here; with blank lines or comments after the assignment the distance grows.
  • Not on this slide: += on a boolean, ... at line 3: Invalid assignment += not allowed with boolean variables for an assignment on line 2 (run with the tree's parser for this deck; see the scene "Booleans: three of the four").
  • Not on this slide: a trailing comma, ... at line 2: Variable declarations do not accept trailing commas, for a += line on line 2 (run with the tree's parser for this deck). This message comes from the scanner and names the line itself; it is shown in variables.

08 What the values become

ROADS = += ?= := declare · add · declare unless declared · replace syn-variables sets and their expansion syn-boolean-variables the right-hand side of a boolean syn-include-if-exists site files syn-abstractions-tunables who declares what syn-preamble where an assignment stands fe-grammar one grammar rule syntax-map every kind of line also: syn-boolean-conditionals
The four operators =, +=, ?= and := in the middle, with roads to the decks syn-variables, syn-boolean-variables, syn-include-if-exists, syn-abstractions-tunables, syn-preamble, fe-grammar and syntax-map.

Assignment fills the table of variables; expansion and conditional blocks use it.

Four operators, one table. What a set variable turns into inside a rule is the variables deck, and what you can write on the right of a boolean assignment is the boolean variables deck. The place where += earns its keep, the site file in a .d directory, is the deck on include if exists. The tunables deck shows who declares what. And the preamble deck says where an assignment may stand.

Details and sources

Details

  • = declares and fails if the name exists. += adds to an existing set. ?= declares unless the name is declared. := replaces.
  • Boolean variables take =, ?= and :=.
  • Set and boolean variables share one table: a name is one or the other.
  • -D variables prints the final table.
  • Commit read for this deck: AppArmor 836052d21 (6.0.0~alpha2). Assignments have no kernel side.

Read more

Basis of the statements on this page: "tree" means the parser built from the AppArmor commit 836052d21 (6.0.0~alpha2) was run on the fragment (-Q -K --skip-kernel-load, with the tree's abi/5.0 as kernel feature set and the dump option named), with nothing loaded into a kernel; "code" means the parser source was read and not run; "derived" means the result was reasoned from that code. Nothing here was observed on a running kernel.

Grammar

assignment:  VARIABLE OP REST            up to the end of the line, no comma
VARIABLE:    @{NAME} | ${NAME}
OP:          =  |  +=  |  ?=  |  :=
REST:        VALUE ...                   for @{NAME}
             EXPRESSION                  for ${NAME}
OperatorTokenMeaning
=TOK_EQUALSdeclare: create the variable; an error if the name exists
+=TOK_ADD_ASSIGNadd: add values to a set that exists; an error if it does not
?=TOK_COND_ASSIGNdeclare unless declared: assign only if the name is free
:=TOK_OVERRIDE_ASSIGNreplace: assign, replacing any variable of that name

Operator against the state of the name

OperatorThe name is freeThe name is a setThe name is a boolean
@{N} = vcreated (tree)variable @{N} was previously declared (tree)variable @{N} was previously declared (tree)
@{N} += vvariable @{N} was not previously declared, but is being assigned additional values (tree)the values are added (tree)see the known discrepancies
@{N} ?= vcreated (tree)the value is kept (tree)not run
@{N} := vcreated (code)replaced (tree)replaced by a set (tree; intent not determined)
${N} = ecreated (tree)not runvariable %s was previously declared (code)
${N} += eInvalid assignment += not allowed with boolean variables (code)the same message (code)the same message (tree)
${N} ?= ecreated (code)not runthe value is kept (tree)
${N} := ecreated (code)replaced by a boolean (tree; intent not determined)replaced (tree)

Worked sequence

@{APP_DATA} = /var/lib/demo
@{APP_DATA} += /srv/demo
@{CACHE} ?= /var/cache/demo
@{LOGS} = /var/log/demo
@{LOGS} := /srv/log/demo
${DEMO_DEBUG} = false
${DEMO_DEBUG} := true
profile demo /usr/bin/demo {
  owner @{APP_DATA}/** rw,
}
  • -D variables prints $DEMO_DEBUG = true, @LOGS = "/srv/log/demo", @CACHE = "/var/cache/demo", @APP_DATA = "/srv/demo" "/var/lib/demo"; exit status 0; nothing on standard error (tree).
  • -D rule-exprs prints aare: {/srv/demo,/var/lib/demo}/** for the rule (tree).

Roles

WhoOperatorExample
the file that owns the variable=@{HOMEDIRS}=/home/ in tunables/home
a site file+=@{HOMEDIRS} += /srv/nfs/home/ in tunables/home.d/site.local
a profile that offers a default?=@{CACHE} ?= /var/cache/demo
a profile that overrides:=@{LOGS} := /srv/log/demo
  • Each line acts on the table as it is when the line is reached, so the order of includes and of lines decides the result (code).
  • += works only after the declaration. ?= is a default only if it comes after the assignment it yields to (code).
  • With the site line included after tunables/global, @{HOME}/.ssh/** compiles as {/home/*,/root,/srv/nfs/home/*}/.ssh/** (tree; the line was included through an include if exists of its own, standing in for a file in tunables/home.d/).

Errors

MessageFirst line printed before itCauseReported lineBasis
variable @{N} was previously declared'@{N}' is already defined= on a name that exists, also after ?= or := created itthe line of the next tokentree
variable @{N} was not previously declared, but is being assigned additional valuesFailed to find declaration for: N+= on a name that does not existthe line of the next tokentree
Invalid assignment += not allowed with boolean variablesnone+= on ${N}the line of the next tokentree
Variable declarations do not accept trailing commasnonea comma at the end of the linethe line itselftree
  • Exit status 1 for each.

The man page

  • apparmor.d(5) says "AppArmor provides 3 different assignment operators" and then describes four (apparmor.d.pod:2375-2389). This page follows the code.

for security researchers

Attack surface

  • += and := let any later preamble text change what every rule written with a shipped variable means. The later text can come from a .d directory: see include if exists.
  • -D variables prints the final table.

for AppArmor developers for security researchers

In the code

for AppArmor developers for security researchers

Known discrepancies

  • The files of an included directory are compiled in reverse alphabetical order, and an error in one is reported with a neighbour's file name. For assignments it decides whether a = in one site file is met before a += in another.
  • ?= on a declared variable prints '@{NAME}' is already defined. Run: @{B} ?= /first then @{B} ?= /second leaves @B = "/first", prints '@{B}' is already defined, exit status 0.
  • += on a boolean reports that the variable was not declared. Run: ${A} = true then @{A} += /a prints Variable A is not a set variable and then ... at line 3: variable @{A} was not previously declared, but is being assigned additional values.
  • apparmor.d(5): the grammar summary and text disagree with the parser in several places (the count of operators above).
  • Not determined: whether := changing the kind of a variable is intended. Run: ${A} = true then @{A} := /a prints @A = "/a"; @{S} = /s then ${S} := false prints $S = false.

Roads from here

START HERE

PREAMBLE AND REUSE

INSIDE THE PARSER

  • The grammar — the one grammar rule behind the four operators