diff --git a/src/stelline/README.md b/src/stelline/README.md
index fe949176..b60f5225 100644
--- a/src/stelline/README.md
+++ b/src/stelline/README.md
@@ -19,3 +19,117 @@ In both cases real `net::client` instances handle interaction with the server.
 When using a mock server the replay file should define both test requests and test responses and the mock server replies with the test responses.
 
 When using a real server the replay file defines DNS requests and server configuration and real `net::server` instances reply based on their configuration.
+
+## Syntax of an `.rpl` file
+
+
+The replay format used by Stelline is a line based configuration. The format supports line comments starting with `;`.
+
+The format contains two sections `CONFIG` and `SCENARIO`. The format of the `CONFIG` section depends on how Stelline is used (e.g. as a client or as a server). The `CONFIG` section extends from the start of the file until the line containing the `CONFIG_END` option.
+
+The `SCENARIO` section contains the steps to perform in the test. It starts with `SCENARIO_BEGIN` and ends with `SCENARIO_END`. Note that all `.rpl` files must end with `SCENARIO_END`.
+
+### Steps
+A scenario consists of steps. Each step is something that is executed in the test. A step can be one of the following types:
+
+- `QUERY`
+- `CHECK_ANSWER`
+- `TIME_PASSES`
+- `TRAFFIC` (TODO)
+- `CHECK_TEMP_FILE` (TODO)
+- `ASSIGN` (TODO)
+
+In general, the syntax looks like:
+
+```
+STEP id type data
+```
+
+where `id` is a positive integer, `type` on of the step types mentioned above, and `data` is the data for the step.
+
+Steps of types `QUERY` and `CHECK_ANSWER` have entries associated with them, which are textual representations of DNS messages. These entries are simply put aafter the `STEP` declaration.
+
+A `QUERY` step sends a query to the tested program. It can optionally have data declaring its `ADDRESS` and `KEY`:
+
+```
+STEP 1 QUERY
+STEP 1 QUERY ADDRESS <ip_address> KEY <key_name>  
+```
+
+A `CHECK_ANSWER` step checks an incoming answer. It has no data, only entries.
+
+```
+STEP 1 CHECK_ANSWER
+```
+
+A `TIME_PASSES` step increments the fake system clock by the specified number of seconds. The time is given after the `ELAPSE` token.
+
+```
+STEP 1 TIME_PASSES ELAPSE
+```
+
+### Entries
+
+An entry represents a DNS message (or an expected DNS message). It starts with `ENTRY_BEGIN` and ends with `ENTRY_END`. There are several parts to an entry, which depend on the use of the entry. The simplest form is the form used the `QUERY` step:
+
+```
+ENTRY_BEGIN
+REPLY <opcode> <rcode> <flags>
+SECTION <section_type>
+  ...
+SECTION <section_type>
+  ...
+...
+ENTRY_END
+```
+
+The `REPLY` part specifies the header information of the outgoing message. The supported values are:
+
+ - RCODES: `NOERROR`, `FORMERR`, `SERVFAIL`, `NXDOMAIN`, `NOTIMP`, `REFUSED`, `YXDOMAIN`, `YXRRSET`, `NXRRSET`, `NOTAUTH`, `NOTZONE`, `BADVERS`, `BADCOOKIE`.
+ - Flags: `AA`, `AD`, `CD`, `DO`, `QR`, `RA`, `RD`, `TC`, `NOTIFY`.
+
+The `SECTION` directives specify which sections to fill with each section with. The content of a section is exactly like a zonefile, except for the question section, which does not require rdata.
+
+There are two other sections in an entry, which are only relevant to ranges (see below), which are `MATCH` and `ADJUST`. The `MATCH` directive specifies which parts of the incoming message must match the reply to match the entry. The following values are allowed:
+
+- `all`: same as `opcode qtype qname rcode flags answer authority additional`
+- `opcode`
+- `qname`
+- `rcode`
+- Flags: `AD`, `CD`, `DO`, `RD`, `flags`
+- `question`: same as `qtype qname`
+- Sections: `answer`, `authority`, `additional`
+- `subdomain`
+- `ttl`
+- Protocol: `TCP`, `UDP`
+- `server_cookie`
+- `ednsdata`
+- `MOCK_CLIENT`
+- `CONNECTION_CLOSED`
+- `EXTRA_PACKETS`
+- `ANY_ANSWER`
+
+The `ADJUST` directive specifies which parts of the incoming message should be changed before sending. The possible values are `copy_id` and `copy_query`.
+
+### Ranges
+
+Mock responses from are defined by a `RANGE`, which specifies the reponses that are given to a "range" of queries. A range is delimited by the `RANGE_BEGIN` and `RANGE_END` tokens.
+
+The `RANGE_BEGIN` directive takes two positive integers: a start and end value. A `QUERY` step with an id within that range can match this range.
+
+After the numeric range, a range has a list of addresses that match on this range, with each address on its own line prefixed with `ADDRESS`.
+
+Lastly, a range contains a list of entries, following the syntax described above.
+
+```
+RANGE_BEGIN 0 100 ; begin and end of the range
+  ADDRESS 1.1.1.1 ; an address to match
+  ADDRESS 2.2.2.2 ; a second address, any number of address is allowed
+
+ENTRY_BEGIN
+; ... 
+ENTRY_END
+
+; more entries may be added
+RANGE_END
+```