The `queryprogram' router routes a domain by running an external command and acting on its output. This is an expensive way to route, and is intended mainly for use in lightly-loaded systems, or for performing experiments. However, if it is possible to use the `domains' generic option to skip this router for most addresses, then it could sensibly be used in special cases. There are two private options:
Option: command
Type: string
Default: unset
This option must be set, and must start with a slash character. It specifies the command that is to be run. It is expanded before use. Failure to expand causes the router to fail and the message to be frozen.
Option: current_directory
Type: string
Default: unset
This option specifies an absolute path which is made the current directory before running the command. If it is not set, `/' is used.
Option: group
Type: string
Default: unset
This option specifies a gid to be set when running the command. If it begins with a digit it is interpreted as the numerical value of the gid. Otherwise it is looked up using `getgrnam()'.
Option: timeout
Type: time
Default: 1h
If the command does not complete within the timeout period, its process is killed and the message gets frozen. A value of zero time specifies no timeout.
Option: user
Type: string
Default: unset
This option specifies the uid which is set when running the command. If it begins with a digit it is interpreted as the numerical value of the uid. Otherwise, it is looked up using `getpwnam()' to obtain a value for the uid and, if `group' is not set, a value for the gid also.
If `user' is not specified, the command is run as `nobody'. If the main configuration has not defined a user and group for `nobody', then it is looked up using `getpwnam()'. If this fails, the router fails and the message is frozen.
The standard output of the command is connected to a pipe, which is read when the command terminates. It should consist of a single line of output, containing up to five fields, separated by white space. The first field is one of the following words:
When the first word is not OK, the remainder of the line is an error message explaining what went wrong. For example:
FAIL queryprogram cannot route to unseen.discworld.fict.book
Otherwise, the line must be formatted as follows:
OK <transport name> <new domain> <option> <arbitrary text>
The second field is the name of a transport instance, or a plus character, which means that the transport specified for the router using the generic `transport' option is to be used, if set.
If the third field is not empty or a single plus character, it is a new domain name to replace the current one. If a transport is specified and the fourth field is not empty or a plus character, it specifies the method of looking up the new name. This can be one of the words `byname', `bydns', `bydns_a', or `bydns_mx'. For example,
OK smtp gate.star.fict.book bydns_a
causes the message to be sent using the `smtp' transport to the host `gate.star.fict.book', whose address is looked up as a DNS address record. If the host turns out to be the local host, what happens is controlled by the generic `self' option.
The fifth field, if present, is made available to the transport via the expansion variable `$route_option'. For example, a line such as
OK special + + /computed/filename
sends the message to the `special' transport, which can use `$route_option' in its configuration to access the text `/computed/filename'.
The fourth and fifth fields are ignored and the new domain name (if any) is passed to the next router if no transport is specified in the response line (that is, a plus character is given) and the generic `transport' option is also unset.
Go to the first, previous, next, last section, table of contents.