SCENARIO_GUIDE.rst 9.23 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11
Writing scenarios
=================



**Rewiev**

Scenario is a text file which must have the extension .rpl.
It consists of two sequential parts - configuration and scenario.
Configuration, which contains data with global scope, is always placed first.
Scenario follows Configuration. This part consists of sequence of datablocks
12
of two different types - **RANGE** and **STEP**. Generally **RANGE** datablock contains
13
data, used Python fake dns server to make answers to binary's under test
14
queries. And **STEP** datablock defines action will be taken - send next query 
15
to binary under test, send reply to binary under test, set faked system time, 
16 17 18 19
check the last answer. Each datablock must contain at least one **ENTRY** block 
and may contain some extra data. Each **ENTRY** block contains header data and 
at least one **SECTION** or **RAW** block. **SECTION** block contains Record Resource 
Sets like a dns message sections. **RAW** contains single-line data which will be
20 21 22 23 24 25 26
interpreted as raw dns message. Lines started with semicolon (;) are ignored 
and can be used as comments.

**Configuration**

Configuration part is a list of "key : value" pairs, one pair per line.
Configuration have no explicit start, it's assumed it starts immediately at
27
scenario file begin. It must be explicitly ended with **CONFIG_END** statement.
28 29
Next keys can be used

30
- **query-minimization** : on
31 32 33

  value "on" means query minimization algorithm will be used; any other value
  means query minimization algorithm will not be used.
34
- **stub-addr** : ipv4-addr
35

36 37 38
  address, which will be listened by Python fake dns server immediately after startup.
  When configuration files will be generated by Jinja2 engine, ``ROOT_ADDR`` template 
  variable will be replaced by this address.
Grigorii Demidov's avatar
Grigorii Demidov committed
39 40 41 42 43 44 45
- **thrust-anchor** : ``string value``

  Delegation Signer record, can be used for DNSSEC-related scenarios
- **val-override-date** : ``string value``

  POSIX timestamp; the system time will be reported to binary under the test

46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66
- **features** : jinja2_var1=v1;jinja2_var2=v2;...;jinja2_varN=vN

  semicolon-separated list of key=value pairs, all keys and values are strings;
  contains user-defined jinja2 template variables which can be used for improving
  flexibility of configuration generation process; when variable value is not needed,
  it can be omitted as well as equal sign; **features** configuration key can be
  repeated, so

  ::

      **features** : jinja2_var1=v1;jinja2_var2=v2;...;jinja2_varN=vN

  equal to

  ::

      **features** : jinja2_var1=v1
      **features** : jinja2_var2=v2
      ...
      **features** : jinja2_varN=vN

67 68 69

Example
::
70

71 72 73
    ; config options
	    query-minimization: on
	    stub-addr: 193.0.14.129 	# K.ROOT-SERVERS.NET.
Grigorii Demidov's avatar
Grigorii Demidov committed
74 75
	    trust-anchor: ". 3600 IN DS 17272 13 4 B87AD8C76DC2244E7AA57285057BF533F2E248CC8D7E1A071D8A3837A711A5EA705C4707E6E8911DA653BE1AE019927B"
	    val-override-date: "1442323400"
76 77
            features: dns64
            features: dns64_prefix = fe80::21b:aabb:0:0
78 79 80 81
    CONFIG_END

**Scenario**

82 83
Scenario part starts with **SCENARIO_BEGIN** and ends with **SCENARIO_END** statements.
**SCENARIO_BEGIN** can be followed by scenario description.
84 85 86

Example
::
87

88 89 90 91 92 93
    SCENARIO_BEGIN Test basic query minimization www.example.com.
    ...
    SCENARIO_END

**RANGE datablock**

94
**RANGE** datablock starts with **RANGE_BEGIN** and ends with **RANGE_END** statements.
95 96 97 98 99
This datablock contains data, used Python fake dns server to make answers to 
binary's under test queries. 

Format: 
::
100

101 102 103 104 105
    RANGE_BEGIN n1 n2
        ADDRESS addr
    ...
    RANGE_END

106
- **n1** and **n2** respectively minimal or maximal step ids (see below) to which this  
107
  range can be applied. 
108
- **addr** - IP address for which **RANGE** datablock is prepared; this statement can be omitted.
109 110 111 112 113 114 115 116 117 118

Datablock will be used for fetching reply to query only for these steps, whose identificators greater then or equal n1 and
lesser then or equal n2. Also one of the next condition must be met : 

- addr is not set
- addr is set, and query is directed to this addr
- address, to which query is directed, can not be found within the range addresses list for whole scenario

**STEP datablock**

119 120
**STEP** datablock starts with **STEP** statement and continues until to next **STEP**,
**RANGE** or **END_SCENARIO** statement. This datablock defines action will be taken by 
121 122 123 124 125
testing environment - send next query to binary under test, send reply to binary
under test, set faked system time or check the last answer. 

Format
::
126

127 128
   STEP id type [additional data]

129
- **id** - step identificator, positive integer value; all steps must have 
130
  different id's. This value used within RANGE datablock, see above.
131
- **type** - step type; can be **QUERY** | **REPLY** | **CHECK_ANSWER** | **TIME_PASSES ELAPSE** <**TIMESTAMP**>
132
  
133 134 135
  - **QUERY** - at this step new query must be sent
  - **REPLY** - send answer to last query; steps of this type fired when eligible 
    **RANGE** datablock can not be found
136 137
  - **CHECK_ANSWER** - last received answer must be checked; this step can have additional fields **RETRY** = `integer value` **PAUSE** = `float value` **NEXT** = `integer value`. This additional values are intended to ensure error recovery possibility. When answer checking failed, is possible to take    step with predefined step id. For example, **STEP CHECK_ANSWER RETRY** = `3` **PAUSE** = `0.5` **NEXT** = `10` means that when current step fails, then step with id = 10 must be taken after pause. Pause duration is 0.5 seconds. Maximal number of retries is 3. When maximal number of retries is reached, scenario fails.
  - **TIME_PASSES ELAPSE** - new time must be set for binary under test; **TIMESTAMP** - POSIX timemestamp, it will be added to current system time.
138 139 140 141


**ENTRY**

142
**ENTRY** is an basic informational block, it has a DNS-message based structure. 
143
It contains all necessary data to perform action for which it was intended.
144
Block starts with **ENTRY_BEGIN** and ends with **ENTRY_END** statements.
145 146 147

Format
::
148

149 150 151 152 153 154 155 156 157 158
    ENTRY_BEGIN
    MATCH <field list>
    ADJUST <field list>
    REPLY <flags>
    SECTION <type>
       ...
    RAW
       ...
    ENTRY_END

159
- **MATCH** <field list> - space-separated list of **ENTRY** block elements to be compared
160 161 162 163
  with elements of incoming query (answer); when all elements matches, this entry 
  block will be used, otherwise next entry will be analyzed.
  <field list> can contain values :
  
164 165 166 167 168 169 170 171 172 173
  - **opcode**     - check if the incominq query is a standard query (**OPCODE** is 0) 
  - **qtype**      - check if **QTYPE** fields of both question sections are equal
  - **qname**      - check if domain name (**QNAME**) fields of question sections are equal
  - **subdomain**  - check if domain from question section of incoming query (answer) 
    is a subdomain of domain from question section of this **ENTRY** block.
  - **flags**      - check if set of dns flags (**QR** **AA** **TC** **RD** **RA**) is equal
  - **question**,
  - **answer**,
  - **authority**,
  - **additional** - check if lists of RR sets for question,answer,authority and 
174
    additional section respectively is equal
175
  - **all**        - check if set of dns flags is equal and all sections presented 
176 177 178
    in entry are equal to ones in incoming query (answer); incoming query 
    (answer) can contain some extra sections which will not be compared
    
179
- **ADJUST** <field list> - when **ENTRY** block is used as a pattern to prepare answer
180 181 182
  to incoming query, it must be preprocessed; values in <field list> defines
  actions will be taken:

183
  - **copy_id**    - query id and domain name (question section QNAME field) only 
184
    will be copied from incoming message
185
  - **copy_query** - whole question section will be copied from incoming message
186

187
- **REPLY** <flags> - space-separated list of flags will be set in reply values
188 189
  can be used:

190 191 192 193
  - **QR**, **AA**, **TC**, **RD**, **RA** - i.e. standard dns flags
  - **NOERROR**, **FORMERR**, **SERVFAIL**, **NXDOMAIN**, **NOTIMP**, **REFUSED**, **YXDOMAIN**, **YXRRSET**, 
    **NXRRSET**, **NOTAUTH**, **NOTZONE**, **BADVERS** - standard rcodes
  - **DO** - enable 'DNSSEC desired' flag
194
              
195 196
- **SECTION** <type> - defines section of dns message, so <type> can be equal to 
  **QUESTION**, **ANSWER**, **AUTHORITY** or **ADDITIONAL** each section contains rr sets like 
197
  standard dns message
198

199 200
Example
::
201

202 203 204 205 206 207 208 209 210
  SECTION QUESTION
  www.example.com.	IN A
  SECTION ANSWER
  www.example.com.	IN A	10.20.30.40
  SECTION AUTHORITY
  example.com.	IN NS	ns.example.com.
  SECTION ADDITIONAL
  ns.example.com.	IN A	1.2.3.4

211
- **RAW** - section used to sending raw dns messages. Contains a single-line data 
212 213 214 215 216
  interpreted as hexadecimal string. This string will be sent to binary under 
  test without any changes. Raw messages used to sending badly formed queries
  to binary under test. Queries assumed not be answered, so no waiting for answer
  is performed.Main goal of this behavior is to check if binary under test is 
  able to serve valid queries after getting of series badly formed packets. 
217 218 219 220
  So using **RAW** section in conjunction of other sections  is meaningless. 
  All sections other than **RAW** will be ignored. Also, **ENTRY** datablock can contain 
  only one **RAW** section.

221 222
Example
::
223

224 225 226 227 228 229 230
  RAW
      b5c9ca3d50104320f4120000000000000000

`SCRIPT EXAMPLE`_

.. _`SCRIPT EXAMPLE`: https://gitlab.labs.nic.cz/knot/deckard/blob/master/SCENARIO_EXAMPLE.rst