maddy

  1# Configuration files syntax
  2
  3**Note:** This file is a technical document describing how
  4maddy parses configuration files.
  5
  6Configuration consists of newline-delimited "directives". Each directive can
  7have zero or more arguments.
  8
  9```
 10directive0
 11directive1 arg0 arg1
 12```
 13
 14Any line starting with # is ignored. Empty lines are ignored too.
 15
 16## Quoting
 17
 18Strings with whitespace should be wrapped into double quotes to make sure they
 19will be interpreted as a single argument.
 20
 21```
 22directive0 two arguments
 23directive1 "one argument"
 24```
 25
 26String wrapped in quotes may contain newlines and they will not be interpreted
 27as a directive separator.
 28
 29```
 30directive0 "one long big
 31argument for directive0"
 32```
 33
 34Quotes and only quotes can be escaped inside literals: \\"
 35
 36Backslash can be used at the end of line to continue the directve on the next
 37line.
 38
 39## Blocks
 40
 41A directive may have several subdirectives. They are written in a {-enclosed
 42block like this:
 43```
 44directive0 arg0 arg1 {
 45    subdirective0 arg0 arg1
 46    subdirective1 etc
 47}
 48```
 49
 50Subdirectives can have blocks too.
 51
 52```
 53directive0 {
 54    subdirective0 {
 55        subdirective2 {
 56            a
 57            b
 58            c
 59        }
 60    }
 61    subdirective1 { }
 62}
 63```
 64
 65Level of nesting is limited, but you should never hit the limit with correct
 66configuration.
 67
 68In most cases, an empty block is equivalent to no block:
 69```
 70directive { }
 71directive2 # same as above
 72```
 73
 74## Environment variables
 75
 76Environment variables can be referenced in the configuration using either
 77{env:VARIABLENAME} syntax.
 78
 79Non-existent variables are expanded to empty strings and not removed from
 80the arguments list.  In the following example, directive0 will have one argument
 81independently of whether VAR is defined.
 82
 83```
 84directive0 {env:VAR}
 85```
 86
 87Parse is forgiving and incomplete variable placeholder (e.g. '{env:VAR') will
 88be left as-is. Variables are expanded inside quotes too.
 89
 90## Snippets & imports
 91
 92You can reuse blocks of configuration by defining them as "snippets". Snippet
 93is just a directive with a block, declared tp top level (not inside any blocks)
 94and with a directive name wrapped in curly braces.
 95
 96```
 97(snippetname) {
 98    a
 99    b
100    c
101}
102```
103
104The snippet can then be referenced using 'import' meta-directive.
105
106```
107unrelated0
108unrelated1
109import snippetname
110```
111
112The above example will be expanded into the following configuration:
113
114```
115unrelated0
116unrelated1
117a
118b
119c
120```
121
122Import statement also can be used to include content from other files. It works
123exactly the same way as with snippets but the file path should be used instead.
124The path can be either relative to the location of the currently processed
125configuration file or absolute. If there are both snippet and file with the
126same name - snippet will be used.
127
128```
129# /etc/maddy/tls.conf
130tls long_path_to_certificate long_path_to_private_key
131
132# /etc/maddy/maddy.conf
133smtp tcp://0.0.0.0:25 {
134    import tls.conf
135}
136```
137
138```
139# Expanded into:
140smtp tcp://0.0.0.0:25 {
141    tls long_path_to_certificate long_path_to_private_key
142}
143```
144
145The imported file can introduce new snippets and they can be referenced in any
146processed configuration file.
147
148## Duration values
149
150Directives that accept duration use the following format: A sequence of decimal
151digits with an optional fraction and unit suffix (zero can be specified without
152a suffix). If multiple values are specified, they will be added.
153
154Valid unit suffixes: "h" (hours), "m" (minutes), "s" (seconds), "ms" (milliseconds).
155Implementation also accepts us and ns for microseconds and nanoseconds, but these
156values are useless in practice.
157
158Examples:
159```
1601h
1611h 5m
1621h5m
1630
164```
165
166## Data size values
167
168Similar to duration values, but fractions are not allowed and suffixes are different.
169
170Valid unit suffixes: "G" (gibibyte, 1024^3 bytes), "M" (mebibyte, 1024^2 bytes),
171"K" (kibibyte, 1024 bytes), "B" or "b" (byte).
172
173Examples:
174```
17532M
1763M 5K
1775b
178```
179
180Also note that the following is not valid, unlike Duration values syntax:
181```
18232M5K
183```
184
185## Address Definitions
186
187Maddy configuration uses URL-like syntax to specify network addresses.
188
189- `unix://file_path` – Unix domain socket. Relative paths are relative to runtime directory (`/run/maddy`).
190- `tcp://ADDRESS:PORT` – TCP/IP socket.
191- `tls://ADDRESS:PORT` – TCP/IP socket using TLS.
192
193## Dummy Module
194
195No-op module. It doesn't need to be configured explicitly and can be referenced
196using "dummy" name. It can act as a delivery target or auth.
197provider. In the latter case, it will accept any credentials, allowing any
198client to authenticate using any username and password (use with care!).
199
200