5. Smapd Configuration File

The smapd configuration file consists, on a lexical level, of logical lines. A logical line is any sequence of characters between two unescaped newline characters. The word ‘unescaped’ means a newline character not preceded by a single backslash. Thus, escaped newlines allow to combine several physical lines into a single logical one.

Within a logical line, unescaped ‘#’ character introduces a comment. The character itself and the rest of characters after it up to the end of line are ignored.

Empty lines are ignored as well.

Each not empty line constitutes a configuration statement. Before further processing the statement is subject to the following expansions:

variable substitution

Variable substitution consists in replacing each sequence ‘$name’ or ‘${name}’ with the value of the variable name. Valid variable names begin with a letter of the Latin alphabet or underscore and consist of alphanumeric symbols and underscores. Variable names are case-sensitive. Variables are expanded in unquoted and doubly-quoted arguments. Variable expansion is suppressed within single-quoted strings (see below).

field splitting

A word is defined as any contiguous sequence of non-whitespace characters or any sequence of characters enclosed in double or single quotes. Standalone words and doubly-quoted strings are subject to variable substitution and escape expansion.

escape expansion

A backslash character introduces an escape sequence. The following escape sequences are expanded:

Sequence Replaced with
\a Audible bell character (ASCII 7)
\b Backspace character (ASCII 8)
\f Form-feed character (ASCII 12)
\n Newline character (ASCII 10)
\r Carriage return character (ASCII 13)
\t Horizontal tabulation character (ASCII 9)
\v Vertical tabulation character (ASCII 11)

Table 5.1: Escape sequences

A ‘\’ followed by any character not listed in the table above is replaced with that character alone. This allows, for example, to include double-quote characters in a doubly-quoted string.

quote removal

This stage consists in removing unescaped single and double quotes, which where not inserted due to variable expansion.

If, after expansion, the statement consists of a single word that begins with a valid variable name immediately followed by an equals sign, such statement is treated as a variable assignment. The string to the right of the equals sign is assigned to the variable named to the left of it.

Otherwise, if the statement has two or more words, the first word is treated as a keyword, which identifies a configuration statement, and the rest of words as its arguments.

The following configuration statements are understood.

Config: inetd-mode bool

If bool is ‘yes’, enable inet mode (see inetd-mode).

Config: pidfile filename

Write pidfile to the file filename.

Config: foreground bool

If bool is ‘yes’, run in foreground. This also means that log output goes to standard error, unless requested otherwise by ‘log-to-syslog’ statement or ‘--syslog’ command line option.

Config: idle-timeout number

Sets idle timeout to number seconds. A child process terminates if it has not received any request within this amount of time.

Config: log-to-stderr bool

If bool is ‘yes’ send log output to standard error.

Config: log-to-syslog bool

If bool is ‘yes’ send log output to syslog.

Config: log-tag string

Tag each log line in syslog with string. By default, the name of the program (‘smapd’) is used.

Config: log-facility fac

Write logs to the syslog facility fac. Valid values for fac are: ‘user’, ‘daemon’, ‘auth’, ‘authpriv’, ‘mail’, ‘cron’, and ‘local0’ through ‘local7’.

Default is ‘daemon’.

Config: debug dspec1 [dspec2...]

Enable debugging output according to the given specifications. See section Tracing and Debugging, for a description of specifications.

Config: trace bool

If bool is ‘yes’ enable query traces. See section Query traces.

Config: trace-pattern pat1 [pat2...]

Abridge query trace output to queries beginning with the given patterns. See trace-pattern.

Config: user name

After startup, switch to UID and GID of the user name.

Config: group name1 [name2 ...]

When switching to user privileges (see above), retain also these supplementary groups.

Config: allgroups bool

When switching to user privileges (see above), retain all supplementary groups the user is a member of.

Config: socket-mode mode

Set default file mode for creating UNIX sockets. The mode argument must be either in octal notation (e.g. ‘600’), or in chmod-style notation (e.g. ‘rw-------’).

Default mode is ‘600’.

Config: shutdown-timeout seconds

Sets the number of seconds to wait for all children to terminate before shutdown, after sending them the ‘SIGTERM’ signal. Any children remaining active after this timeout are terminated forcefully using ‘SIGKILL’.

Default value is 5 seconds.

Config: backlog number

Sets the maximum size of pending connections queue for sockets. If a connection request arrives when the queue is full, the client receives an error with an indication of ‘ECONNREFUSED’.

Default backlog is 8.

Config: reuseaddr bool

If bool is ‘yes’ reuse existing socket addresses (both INET and UNIX). This is the default.

Config: max-children number

Maximum number of children processes allowed to run simultaneously. When the actual number of children reaches number, the server stops refusing further connections until any of them terminates. The value of ‘0’ means ‘unlimited’.

The default limit is ‘128’.

Config: single-process bool

Operate in single-process mode. This option may be necessary only when debugging smapd. Never use it in production environment!

Config: server name address [block]

Configure a server. The name argument gives its symbolic name, which will be used in logs to identify it. The address argument specifies network address to listen on. As of version 1.1 two kind of addresses are recognized:

inet://ip:port

Listen on the IPv4 address ip, on the given port. IP address may be given either in “dotted-quad” form or as a hostname. Port may be specified either as a port number, or as a name of a service from ‘/etc/services’.

unix://pathname

Listen on the UNIX socket pathname. Notice that the name of the socket must be absolute, so you would usually have three slashes together. For example, the following statement will listen on a socket named ‘/var/run/smap.sock’:

 
server main unix:///var/run/smap.sock

Optional block is a block statement consisting of the word ‘begin’ followed by a newline, one or more configuration statements and the word ‘end’ alone on a line. For example:

 
server main unix:///var/run/smap.sock begin
  user smap
  allgroups yes
end

The statements within block apply only to that particular server. That is, in the example above, the connections requested on the server main will be handled by a subprocess with privileges of the user smap, retaining all the supplementary groups of this user. The following statements are allowed for use in the block statement:

Their meaning is the same as of the corresponding statements in global scope (see above), but applies to that particular server only.

Config: load-path path

Add path to the current set of directories searched for module files. Path is a list of directory names separated by colons.

Config: module modname libname [args...]

Declare new module. Arguments are:

modname

A name which uniquely identifies this module in the configuration. It will be used to associate databases with this module.

libname

Name of the shared library file (without suffix) to load.

args...

Arguments to the module initialization function.

Config: database dbname modname [args...]

Define a database dbname and associate it with the module modname, which must be loaded by a prior module statement. Optional args are passed to the database initialization function verbatim.

Config: dispatch cond target

Dispatch incoming queries.

Cond is a list of conditions that must be satisfied in order to dispatch this query to target. Conditions are separated by any amount of whitespace. They are evaluated from left to right and are joined using boolean ‘AND’ so that cond yields ‘True’ only if all conditions evaluate to ‘True’. Supported conditions are:

Condition: from ipaddr

Returns ‘True’ if the IP address of the client equals ipaddr. The latter may be given either as an IP address or as a host name, in which case it will be resolved and the first of its IP addresses will be used.

Condition: from ipaddr/netmask

Returns ‘True’ if the result of logical ‘AND’ between the client IP address and netmask equals to ipaddr. The network mask must be specified in “dotted quad” form, e.g.:

 
from 10.1.10.1/255.255.255.224
Condition: from ipaddr/netlen

Returns ‘True’ if first netlen bits from the client IP address equal to ipaddr. The network mask length, netlen must be an integer number in the range from 0 to 32. The address part, ipaddr, is as described above. For example:

 
from 10.1.10.1/27
Condition: server name

True’ if this query is being served by server name (see name).

Condition: map op string

True’ if the map name part of the query (see section map) matches string. The op part specifies the comparison algorithm:

eq
is

Literal equality. Map name must be exactly the same as string.

like
fnmatch

Match using shell wildcard patterns (see Globbing patterns: (glob(7))glob section `glob' in Glob(7) man page).

regexp

Match using regular expressions. String must have the following form:

 
/expr/flags

The slashes may be uniformly replaced with any other punctuation character. The expr must constitute a valid regular expression. The flags are optional. When given, they allow to control the type of the regular expression:

Flag Meaning
i Use case-insensitive matching
x expr is an extended regular expression. This is the default setting.
b expr is a basic regular expression.

See Extended regular expressions: (sed)Extended regexps section `Extended regular expressions' in GNU sed, for a description of Extended regular expressions.

Condition: key op string

True’ if the key value (see section key) matches string. The op argument has the same meaning as for map above.

Condition: not cond

Reverts the value returned by cond, which is one of the conditions described above. For example:

 
not map like "local*"
Condition: default

Always ‘True’. This must be the only condition in cond. It is useful to declare default query destination.

The target instructs the server to direct this query to a particular database. The syntax is:

Target: database dbname

Pass this query to the database dbname (see dbname).