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
= 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, thenAppArmor 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 definedandvariable @{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, whichtunables/globalincludes. The shipped tunables files use only=. - The parser's own test:
@{FOO}=foothen@{FOO}=bar(vars_reassignment_1.sd, expected to fail).
for AppArmor developers for security researchers
In the code
global_symtab.add_var(); on failureyyerror("variable %s was previously declared")(parser_yacc.y:539-545).- The first line of output,
'%s' is already defined, is printed byadd_varitself (symtab.cc:30-36).
02 A variable, one of four operators, the rest of the line
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 errorInvalid 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.
Read more
for AppArmor developers for security researchers
In the code
assign_op(parser_yacc.y:519-522).- Tokens
TOK_EQUALS,TOK_ADD_ASSIGN(\+=),TOK_COND_ASSIGN(\?=),TOK_OVERRIDE_ASSIGN(:=) (parser_lex.l:308-310, parser_lex.l:824-832). varassign: TOK_SET_VAR assign_op valuelist(parser_yacc.y:524-548) andvarassign: TOK_BOOL_VAR assign_op expr(parser_yacc.y:550-570).
03 Four operators, watched in the table
= 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} = falseand${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,printsaare: {/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 /bthen@{A} += /cgives@A = "/a" "/b" "/c"and the rule{/a,/b,/c}/x;@{C} = /c1then@{C} := /c2 /c3gives@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
add_var(),add_set_value(), anddelete_var()followed byadd_var()(parser_yacc.y:527-545, symtab.cc:25-112).
04 Which operator for which file
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 withinclude if existsaftertunables/global; it stands in for a file intunables/home.d/. The ruleaudit deny @{HOME}/.ssh/** rw,then printsaare: {/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}=foothen@{FOO} ?=bar(vars_simple_assignment_16.sd, expected to pass). Recorded in the research notes:@{B} ?= /firstthen@{B} ?= /secondleaves@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} = truethen@{A} := /aprints@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.
Read more
05 Booleans: three of the four
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 variablesdump prints$DEMO_DEBUG = true(run with the tree's parser for this deck). With${DEMO_DEBUG} = falsealone the dump prints$DEMO_DEBUG = false. ${DEMO_DEBUG} += truein 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} = truethen@{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 = Truethen$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} = truethen@{A} += /aprintsVariable A is not a set variableand thenvariable @{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
- The boolean production and its refusal of
+=: parser_yacc.y:553-567. add_varfor a boolean: symtab.cc:42-45.
06 One grammar rule, three calls on the symbol table for AppArmor developers for security researchers
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_opyields one of four token values (parser_yacc.y:519-522). The action ofvarassign: TOK_SET_VAR assign_op valuelistswitches on it (parser_yacc.y:524-548); the boolean production is at parser_yacc.y:550-570.add_varprints'%s' is already defineditself, whatever the caller (symtab.cc:30-36).add_set_value(symtab.cc:90-101) printsFailed to find declaration for: NAMEfor 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
.ddirectory: see include if exists. - Review the final table with
-D variables, not the shipped assignment.
Read more
07 The operator did not fit the table
= 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 isvars_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 variablesfor 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
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 variablesprints 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}
| Operator | Token | Meaning |
|---|---|---|
= | TOK_EQUALS | declare: create the variable; an error if the name exists |
+= | TOK_ADD_ASSIGN | add: add values to a set that exists; an error if it does not |
?= | TOK_COND_ASSIGN | declare unless declared: assign only if the name is free |
:= | TOK_OVERRIDE_ASSIGN | replace: assign, replacing any variable of that name |
- Assignments stand in the preamble only: see the preamble (code).
- The values of a set variable: see variables. The expression of a boolean: see boolean variables.
Operator against the state of the name
| Operator | The name is free | The name is a set | The name is a boolean |
|---|---|---|---|
@{N} = v | created (tree) | variable @{N} was previously declared (tree) | variable @{N} was previously declared (tree) |
@{N} += v | variable @{N} was not previously declared, but is being assigned additional values (tree) | the values are added (tree) | see the known discrepancies |
@{N} ?= v | created (tree) | the value is kept (tree) | not run |
@{N} := v | created (code) | replaced (tree) | replaced by a set (tree; intent not determined) |
${N} = e | created (tree) | not run | variable %s was previously declared (code) |
${N} += e | Invalid assignment += not allowed with boolean variables (code) | the same message (code) | the same message (tree) |
${N} ?= e | created (code) | not run | the value is kept (tree) |
${N} := e | created (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 variablesprints$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-exprsprintsaare: {/srv/demo,/var/lib/demo}/**for the rule (tree).
Roles
| Who | Operator | Example |
|---|---|---|
| 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 aninclude if existsof its own, standing in for a file intunables/home.d/).
Errors
| Message | First line printed before it | Cause | Reported line | Basis |
|---|---|---|---|---|
variable @{N} was previously declared | '@{N}' is already defined | = on a name that exists, also after ?= or := created it | the line of the next token | tree |
variable @{N} was not previously declared, but is being assigned additional values | Failed to find declaration for: N | += on a name that does not exist | the line of the next token | tree |
Invalid assignment += not allowed with boolean variables | none | += on ${N} | the line of the next token | tree |
Variable declarations do not accept trailing commas | none | a comma at the end of the line | the line itself | tree |
- 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.ddirectory: see include if exists.-D variablesprints the final table.
for AppArmor developers for security researchers
In the code
assign_op(parser_yacc.y:519-522); the scanner rules (parser_lex.l:308-310, parser_lex.l:824-832).varassign: TOK_SET_VAR assign_op valuelist(parser_yacc.y:524-548);varassign: TOK_BOOL_VAR assign_op expr(parser_yacc.y:550-570).add_var(symtab.cc:25-76),add_set_value(symtab.cc:90-101),delete_var(symtab.cc:103-112).
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} ?= /firstthen@{B} ?= /secondleaves@B = "/first", prints'@{B}' is already defined, exit status 0.+=on a boolean reports that the variable was not declared. Run:${A} = truethen@{A} += /aprintsVariable A is not a set variableand 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} = truethen@{A} := /aprints@A = "/a";@{S} = /sthen${S} := falseprints$S = false.
Roads from here
START HERE
- The profile language at a glance — every kind of line on one page
PREAMBLE AND REUSE
- Variables — what a set variable is and how it expands
- Boolean variables — the variables that take an expression
- include if exists — the site files where plus equals is used
- Abstractions and tunables — the shipped files that declare the variables you extend
- The preamble — the only place an assignment may stand
- Conditional blocks — the expressions on the right of a boolean assignment
INSIDE THE PARSER
- The grammar — the one grammar rule behind the four operators