postfix-wrapper

package: postfix

title: postfix-wrapper(5)

text:
# postfix-wrapper(5)

## NAME
postfix-wrapper - Postfix multi-instance API

## DESCRIPTION

Support for managing multiple Postfix instances is available as of version 2.6. Instances share executable files and documentation, but have their own directories for configuration, queue and data files.

This document describes how the familiar "postfix start" etc. user interface can be used to manage one or multiple Postfix instances, and gives details of an API to coordinate activities between the postfix(1) command and a multi-instance manager program.

With multi-instance support, the default Postfix instance is always required. This instance is identified by the config_directory parameter's default value.

## GENERAL OPERATION

```

```

Multi-instance support is backwards compatible: when you run only one Postfix instance, commands such as "postfix start" will not change behavior at all.

Even with multiple Postfix instances, you can keep using the same postfix commands in boot scripts, upgrade procedures, and other places. The commands do more work, but humans are not forced to learn new tricks.

For example, to start all Postfix instances, use:

\# postfix start

Other postfix(1) commands also work as expected. For example, to find out what Postfix instances exist in a multi-instance configuration, use:

\# postfix status

This enumerates the status of all Postfix instances within a multi-instance configuration.

## MANAGING AN INDIVIDUAL POSTFIX INSTANCE

```

```

To manage a specific Postfix instance, specify its configuration directory on the postfix(1) command line:

\# postfix -c /path/to/config_directory command

Alternatively, the postfix(1) command accepts the instance's configuration directory via the MAIL_CONFIG environment variable (the -c command-line option has higher precedence).

Otherwise, the postfix(1) command will operate on all Postfix instances.

## ENABLING POSTFIX(1) MULTI-INSTANCE MODE

```

```

By default, the postfix(1) command operates in single-instance mode. In this mode the command invokes the postfix-script file directly (currently installed in the daemon directory). This file contains the commands that start or stop one Postfix instance, that upgrade the configuration of one Postfix instance, and so on.

When the postfix(1) command operates in multi-instance mode as discussed below, the command needs to execute start, stop, etc. commands for each Postfix instance. This multiplication of commands is handled by a multi-instance manager program.

Turning on postfix(1) multi-instance mode goes as follows: in the default Postfix instance's main.cf file, 1) specify the pathname of a multi-instance manager program with the multi_instance_wrapper parameter; 2) populate the multi_instance_directories parameter with the configuration directory pathnames of additional Postfix instances. For example:

```
/etc/postfix/main.cf:

    multi_instance_wrapper = $daemon_directory/postfix-wrapper

    multi_instance_directories = /etc/postfix-test
```

The $daemon_directory/postfix-wrapper file implements a simple manager and contains instructions for creating Postfix instances by hand. The postmulti(1) command provides a more extensive implementation including support for life-cycle management.

The multi_instance_directories and other main.cf parameters are listed below in the CONFIGURATION PARAMETERS section.

In multi-instance mode, the postfix(1) command invokes the $multi_instance_wrapper command instead of the postfix-script file. This multi-instance manager in turn executes the postfix(1) command in single-instance mode for each Postfix instance.

To illustrate the main ideas behind multi-instance operation, below is an example of a simple but useful multi-instance manager implementation:

```
#!/bin/sh
: ${command_directory?"do not invoke this command directly"}
POSTCONF=$command_directory/postconf
POSTFIX=$command_directory/postfix
instance_dirs=`$POSTCONF -h multi_instance_directories |

                sed 's/,/ /'` || exit 1
err=0
for dir in $config_directory $instance_dirs
do

    case "$1" in

    stop|abort|flush|reload|drain)

        test "`$POSTCONF -c $dir -h multi_instance_enable`" \

            = yes || continue;;

    start)

        test "`$POSTCONF -c $dir -h multi_instance_enable`" \

            = yes || {

            $POSTFIX -c $dir check || err=$?

            continue

        };;

    esac

    $POSTFIX -c $dir "$@" || err=$?
done
exit $err
```

## PER-INSTANCE MULTI-INSTANCE MANAGER CONTROLS

```

```

Each Postfix instance has its own main.cf file with parameters that control how the multi-instance manager operates on that instance. This section discusses the most important settings.

The setting "multi_instance_enable = yes" allows the multi-instance manager to start (stop, etc.) the corresponding Postfix instance. For safety reasons, this setting is not the default.

The default setting "multi_instance_enable = no" is useful for manual testing with "postfix -c /path/name start" etc. The multi-instance manager will not start such an instance, and it will skip commands such as "stop" or "flush" that require a running Postfix instance. The multi-instance manager will execute commands such as "check", "set-permissions" or "upgrade-configuration", and it will replace "start" by "check" so that problems will be reported even when the instance is disabled.

## MAINTAINING SHARED AND NON-SHARED FILES

```

```

Some files are shared between Postfix instances, such as executables and manpages, and some files are per-instance, such as configuration files, mail queue files, and data files. See the NON-SHARED FILES section below for a list of per-instance files.

Before Postfix multi-instance support was implemented, the executables, manpages, etc., have always been maintained as part of the default Postfix instance.

With multi-instance support, we simply continue to do this. Specifically, a Postfix instance will not check or update shared files when that instance's config_directory value is listed with the default main.cf file's multi_instance_directories parameter.

The consequence of this approach is that the default Postfix instance should be checked and updated before any other instances.

## MULTI-INSTANCE API SUMMARY

```

```

Only the multi-instance manager implements support for the multi_instance_enable configuration parameter. The multi-instance manager will start only Postfix instances whose main.cf file has "multi_instance_enable = yes". A setting of "no" allows a Postfix instance to be tested by hand.

The postfix(1) command operates on only one Postfix instance when the -c option is specified, or when MAIL_CONFIG is present in the process environment. This is necessary to terminate recursion.

Otherwise, when the multi_instance_directories parameter value is non-empty, the postfix(1) command executes the command specified with the multi_instance_wrapper parameter, instead of executing the commands in postfix-script.

The multi-instance manager skips commands such as "stop" or "reload" that require a running Postfix instance, when an instance does not have "multi_instance_enable = yes". This avoids false error messages.

The multi-instance manager replaces a "start" command by "check" when a Postfix instance's main.cf file does not have "multi_instance_enable = yes". This substitution ensures that problems will be reported even when the instance is disabled.

No Postfix command or script will update or check shared files when its config_directory value is listed in the default main.cf's multi_instance_directories parameter value. Therefore, the default instance should be checked and updated before any Postfix instances that depend on it.

Set-gid commands such as postdrop(1) and postqueue(1) effectively append the multi_instance_directories parameter value to the legacy alternate_config_directories parameter value. The commands use this information to determine whether a -c option or MAIL_CONFIG environment setting specifies a legitimate value.

The legacy alternate_config_directories parameter remains necessary for non-default Postfix instances that are running different versions of Postfix, or that are not managed together with the default Postfix instance.

## ENVIRONMENT VARIABLES

```

```

MAIL_CONFIG

When present, this forces the postfix(1) command to operate only on the specified Postfix instance. This environment variable is exported by the postfix(1) -c option, so that postfix(1) commands in descendant processes will work correctly.

## CONFIGURATION PARAMETERS

```

```

The text below provides only a parameter summary. See postconf(5) for more details.

multi_instance_directories (empty)

An optional list of non-default Postfix configuration directories; these directories belong to additional Postfix instances that share the Postfix executable files and documentation with the default Postfix instance, and that are started, stopped, etc., together with the default Postfix instance.

multi_instance_wrapper (empty)

The pathname of a multi-instance manager command that the postfix(1) command invokes when the multi_instance_directories parameter value is non-empty.

multi_instance_name (empty)

The optional instance name of this Postfix instance.

multi_instance_group (empty)

The optional instance group name of this Postfix instance.

multi_instance_enable (no)

Allow this Postfix instance to be started, stopped, etc., by a multi-instance manager.

## NON-SHARED FILES

```

```

config_directory (see 'postconf -d' output)

The default location of the Postfix main.cf and master.cf configuration files.

data_directory (see 'postconf -d' output)

The directory with Postfix-writable data files (for example: caches, pseudo-random numbers).

queue_directory (see 'postconf -d' output)

The location of the Postfix top-level queue directory.

## SEE ALSO

```
postfix(1) Postfix control program
postmulti(1) full-blown multi-instance manager
$daemon_directory/postfix-wrapper simple multi-instance manager
```

## LICENSE

```

```

The Secure Mailer license must be distributed with this software.

## AUTHOR(S)

```
Wietse Venema
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA
Wietse Venema
Google, Inc.
111 8th Avenue
New York, NY 10011, USA
```

branch: sisyphus


title: regexp_table(5)

text:
# regexp_table(5)

## NAME
regexp_table - format of Postfix regular expression tables

## SYNOPSIS

```
postmap -q "string" regexp:/etc/postfix/filename
postmap -q - regexp:/etc/postfix/filename <inputfile
```

## DESCRIPTION

The Postfix mail system uses optional tables for address rewriting, mail routing, or access control. These tables are usually in dbm or db format.

Alternatively, lookup tables can be specified in POSIX regular expression form. In this case, each input is compared against a list of patterns. When a match is found, the corresponding result is returned and the search is terminated.

To find out what types of lookup tables your Postfix system supports use the "postconf -m" command.

To test lookup tables, use the "postmap -q" command as described in the SYNOPSIS above. Use "postmap -hmq - <file" for header_checks(5) patterns, and "postmap -bmq - <file" for body_checks(5) (Postfix 2.6 and later).

## COMPATIBILITY

```

```

With Postfix version 2.2 and earlier specify "postmap -fq" to query a table that contains case sensitive patterns. Patterns are case insensitive by default.

## TABLE FORMAT

```

```

The general form of a Postfix regular expression table is:

/pattern/flags result

When pattern matches the input string, use the corresponding result value.

!/pattern/flags result

When pattern does not match the input string, use the corresponding result value.

if /pattern/flags

endif

If the input string matches /pattern/, then match that input string against the patterns between if and endif. The if..endif can nest. Note: do not prepend whitespace to patterns inside if..endif.

This feature is available in Postfix 2.1 and later.

if !/pattern/flags

endif

If the input string does not match /pattern/, then match that input string against the patterns between if and endif. The if..endif can nest. Note: do not prepend whitespace to patterns inside if..endif.

This feature is available in Postfix 2.1 and later.

blank lines and comments

Empty lines and whitespace-only lines are ignored, as are lines whose first non-whitespace character is a `#'.

multi-line text

A logical line starts with non-whitespace text. A line that starts with whitespace continues a logical line.

Each pattern is a POSIX regular expression enclosed by a pair of delimiters. The regular expression syntax is documented in re_format(7) with 4.4BSD, in regex(5) with Solaris, and in regex(7) with Linux. Other systems may use other document names.

The expression delimiter can be any non-alphanumerical character, except whitespace or characters that have special meaning (traditionally the forward slash is used). The regular expression can contain whitespace.

By default, matching is case-insensitive, and newlines are not treated as special characters. The behavior is controlled by flags, which are toggled by appending one or more of the following characters after the pattern:

i (default: on)

Toggles the case sensitivity flag. By default, matching is case insensitive.

m (default: off)

Toggle the multi-line mode flag. When this flag is on, the ^ and $ metacharacters match immediately after and immediately before a newline character, respectively, in addition to matching at the start and end of the input string.

x (default: on)

Toggles the extended expression syntax flag. By default, support for extended expression syntax is enabled.

## TABLE SEARCH ORDER

```

```

Patterns are applied in the order as specified in the table, until a pattern is found that matches the input string.

Each pattern is applied to the entire input string. Depending on the application, that string is an entire client hostname, an entire client IP address, or an entire mail address. Thus, no parent domain or parent network search is done, and user@domain mail addresses are not broken up into their user and domain constituent parts, nor is user+foo broken up into user and foo.

## TEXT SUBSTITUTION

```

```

Substitution of substrings (text that matches patterns inside "()") from the matched expression into the result string is requested with $1, $2, etc.; specify $$ to produce a $ character as output. The macros in the result string may need to be written as ${n} or $(n) if they aren't followed by whitespace.

Note: since negated patterns (those preceded by !) return a result when the expression does not match, substitutions are not available for negated patterns.

## INLINE SPECIFICATION

```

```

The contents of a table may be specified in the table name (Postfix 3.7 and later). The basic syntax is:

```
main.cf:

    parameter = .. regexp:{ { rule-1 }, { rule-2 } .. } ..
master.cf:

    .. -o { parameter = .. regexp:{ { rule-1 }, { rule-2 } .. } .. } ..
```

Postfix ignores whitespace after '{' and before '}', and writes each rule as one text line to an in-memory file:

```
in-memory file:

    rule-1

    rule-2

    ..
```

Postfix parses the result as if it is a file in /etc/postfix.

Note: if a rule contains $, specify $$ to keep Postfix from trying to do $name expansion as it evaluates a parameter value.

## EXAMPLE SMTPD ACCESS MAP

```
# Disallow sender-specified routing. This is a must if you relay mail
# for other domains.
/[%!@].*[%!@]/       550 Sender-specified routing rejected
# Postmaster is OK, that way they can talk to us about how to fix
# their problem.
/^postmaster@/       OK
# Protect your outgoing majordomo exploders
if !/^owner-/
/^(.*)-outgoing@(.*)$/  550 Use ${1}@${2} instead
endif
```

## EXAMPLE HEADER FILTER MAP

```
# These were once common in junk mail.
/^Subject: make money fast/     REJECT
/^To: friend@public\.com/       REJECT
```

## EXAMPLE BODY FILTER MAP

```
# First skip over base 64 encoded text to save CPU cycles.
~^[[:alnum:]+/]{60,}$~          OK
# Put your own body patterns here.
```

## SEE ALSO

```
postmap(1), Postfix lookup table manager
pcre_table(5), format of PCRE tables
cidr_table(5), format of CIDR tables
```

## README FILES

```

```

Use "postconf readme_directory" or "postconf html_directory" to locate this information.

```
DATABASE_README, Postfix lookup table overview
```

## AUTHOR(S)

```
The regexp table lookup code was originally written by:
LaMont Jones
lamont@hp.com
That code was based on the PCRE dictionary contributed by:
Andrew McNamara
andrewm@connect.com.au
connect.com.au Pty. Ltd.
Level 3, 213 Miller St
North Sydney, NSW, Australia
Adopted and adapted by:
Wietse Venema
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA
Wietse Venema
Google, Inc.
111 8th Avenue
New York, NY 10011, USA
```


relocated

title: relocated(5)

text:
# relocated(5)

## NAME
relocated - Postfix relocated table format

## SYNOPSIS

```
postmap /etc/postfix/relocated
```

## DESCRIPTION

The optional relocated(5) table provides the information that is used in "user has moved to new_location" bounce messages.

Normally, the relocated(5) table is specified as a text file that serves as input to the postmap(1) command. The result, an indexed file in dbm or db format, is used for fast searching by the mail system. Execute the command "postmap /etc/postfix/relocated" to rebuild an indexed file after changing the corresponding relocated table.

When the table is provided via other means such as NIS, LDAP or SQL, the same lookups are done as for ordinary indexed files.

Alternatively, the table can be provided as a regular-expression map where patterns are given as regular expressions, or lookups can be directed to a TCP-based server. In those case, the lookups are done in a slightly different way as described below under "REGULAR EXPRESSION TABLES" or "TCP-BASED TABLES".

Table lookups are case insensitive.

## CASE FOLDING

```

```

The search string is folded to lowercase before database lookup. As of Postfix 2.3, the search string is not case folded with database types such as regexp: or pcre: whose lookup fields can match both upper and lower case.

## TABLE FORMAT

```

```

The input format for the postmap(1) command is as follows:

- An entry has one of the following form:

```
     pattern      new_location
```

Where new_location specifies contact information such as an email address, or perhaps a street address or telephone number.

- Empty lines and whitespace-only lines are ignored, as are lines whose first non-whitespace character is a `#'.

- A logical line starts with non-whitespace text. A line that starts with whitespace continues a logical line.

## TABLE SEARCH ORDER

```

```

With lookups from indexed files such as DB or DBM, or from networked tables such as NIS, LDAP or SQL, patterns are tried in the order as listed below:

user@domain

Matches user@domain. This form has precedence over all other forms.

user

Matches user@site when site is $myorigin, when site is listed in $mydestination, or when site is listed in $inet_interfaces or $proxy_interfaces.

@domain

Matches other addresses in domain. This form has the lowest precedence.

## ADDRESS EXTENSION

```

```

When a mail address localpart contains the optional recipient delimiter (e.g., user+foo@domain), the lookup order becomes: user+foo@domain, user@domain, user+foo, user, and @domain.

## REGULAR EXPRESSION TABLES

```

```

This section describes how the table lookups change when the table is given in the form of regular expressions or when lookups are directed to a TCP-based server. For a description of regular expression lookup table syntax, see regexp_table(5) or pcre_table(5). For a description of the TCP client/server table lookup protocol, see tcp_table(5). This feature is available in Postfix 2.5 and later.

Each pattern is a regular expression that is applied to the entire address being looked up. Thus, user@domain mail addresses are not broken up into their user and @domain constituent parts, nor is user+foo broken up into user and foo.

Patterns are applied in the order as specified in the table, until a pattern is found that matches the search string.

Results are the same as with indexed file lookups, with the additional feature that parenthesized substrings from the pattern can be interpolated as $1, $2 and so on.

## TCP-BASED TABLES

```

```

This section describes how the table lookups change when lookups are directed to a TCP-based server. For a description of the TCP client/server lookup protocol, see tcp_table(5). This feature is available in Postfix 2.5 and later.

Each lookup operation uses the entire address once. Thus, user@domain mail addresses are not broken up into their user and @domain constituent parts, nor is user+foo broken up into user and foo.

Results are the same as with indexed file lookups.

## BUGS

The table format does not understand quoting conventions.

## CONFIGURATION PARAMETERS

```

```

The following main.cf parameters are especially relevant. The text below provides only a parameter summary. See postconf(5) for more details including examples.

relocated_maps (empty)

Optional lookup tables with new contact information for users or domains that no longer exist.

Other parameters of interest:

inet_interfaces (all)

The local network interface addresses that this mail system receives mail on.

mydestination ($myhostname, localhost.$mydomain, localhost, $config_directory/mydestination)

The list of domains that are delivered via the $local_transport mail delivery transport.

myorigin ($myhostname)

The domain name that locally-posted mail appears to come from, and that locally posted mail is delivered to.

proxy_interfaces (empty)

The remote network interface addresses that this mail system receives mail on by way of a proxy or network address translation unit.

## SEE ALSO

```
trivial-rewrite(8), address resolver
postmap(1), Postfix lookup table manager
postconf(5), configuration parameters
```

## README FILES

```

```

Use "postconf readme_directory" or "postconf html_directory" to locate this information.

```
DATABASE_README, Postfix lookup table overview
ADDRESS_REWRITING_README, address rewriting guide
```

## LICENSE

```

```

The Secure Mailer license must be distributed with this software.

## AUTHOR(S)

```
Wietse Venema
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA
Wietse Venema
Google, Inc.
111 8th Avenue
New York, NY 10011, USA
```


title: socketmap_table(5)

text:
# socketmap_table(5)

## NAME
socketmap_table - Postfix socketmap table lookup client

## SYNOPSIS

```
postmap -q "string" socketmap:inet:host:port:name

postmap -q "string" socketmap:unix:pathname:name
postmap -q - socketmap:inet:host:port:name <inputfile

postmap -q - socketmap:unix:pathname:name <inputfile
```

## DESCRIPTION

The Postfix mail system uses optional tables for address rewriting. mail routing or policy lookup.

The Postfix socketmap client expects TCP endpoint names of the form inet:host:port:name, or UNIX-domain endpoints of the form unix:pathname:name. In both cases, name specifies the name field in a socketmap client request (see "REQUEST FORMAT" below).

## PROTOCOL

```

```

Socketmaps use a simple protocol: the client sends one request, and the server sends one reply. Each request and each reply are sent as one netstring object.

## REQUEST FORMAT

```

```

The socketmap protocol supports only the lookup request. The request has the following form:

name <space> key

Search the named socketmap for the specified key.

Postfix will not generate partial search keys such as domain names without one or more subdomains, network addresses without one or more least-significant octets, or email addresses without the localpart, address extension or domain portion. This behavior is also found with cidr:, pcre:, and regexp: tables.

## REPLY FORMAT

```

```

The Postfix socketmap client requires that replies are not longer than 100000 characters (not including the netstring encapsulation). Replies must have the following form:

OK <space> data

The requested data was found.

NOTFOUND <space>

The requested data was not found.

TEMP <space> reason

TIMEOUT <space> reason

PERM <space> reason

The request failed. The reason, if non-empty, is descriptive text.

## SECURITY

```
This map cannot be used for security-sensitive information,
because neither the connection nor the server are authenticated.
```

## SEE ALSO

```
http://cr.yp.to/proto/netstrings.txt, netstring definition
postconf(1), Postfix supported lookup tables
postmap(1), Postfix lookup table manager
regexp_table(5), format of regular expression tables
pcre_table(5), format of PCRE tables
cidr_table(5), format of CIDR tables
```

## README FILES

```

```

Use "postconf readme_directory" or "postconf html_directory" to locate this information.

```
DATABASE_README, Postfix lookup table overview
```

## BUGS

The protocol limits are not yet configurable.

## LICENSE

```

```

The Secure Mailer license must be distributed with this software.

## HISTORY

Socketmap support was introduced with Postfix version 2.10.

## AUTHOR(S)

```
Wietse Venema
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA
Wietse Venema
Google, Inc.
111 8th Avenue
New York, NY 10011, USA
```


title: sqlite_table(5)

text:
# sqlite_table(5)

## NAME
sqlite_table - Postfix SQLite configuration

## SYNOPSIS

```
postmap -q "string" sqlite:/etc/postfix/filename
postmap -q - sqlite:/etc/postfix/filename <inputfile
```

## DESCRIPTION

The Postfix mail system uses optional tables for address rewriting or mail routing. These tables are usually in dbm or db format.

Alternatively, lookup tables can be specified as SQLite databases. In order to use SQLite lookups, define an SQLite source as a lookup table in main.cf, for example:

```
    alias_maps = sqlite:/etc/postfix/sqlite-aliases.cf
```

The file /etc/postfix/sqlite-aliases.cf has the same format as the Postfix main.cf file, and can specify the parameters described below.

## LIST MEMBERSHIP

```

```

When using SQL to store lists such as $mynetworks, $mydestination, $relay_domains, $local_recipient_maps, etc., it is important to understand that the table must store each list member as a separate key. The table lookup verifies the *existence* of the key. See "Postfix lists versus tables" in the DATABASE_README document for a discussion.

Do NOT create tables that return the full list of domains in $mydestination or $relay_domains etc., or IP addresses in $mynetworks.

DO create tables with each matching item as a key and with an arbitrary value. With SQL databases it is not uncommon to return the key itself or a constant value.

## SQLITE PARAMETERS

```

```

dbpath

The SQLite database file location. Example:

```
    dbpath = customer_database
```

query

The SQL query template used to search the database, where %s is a substitute for the address Postfix is trying to resolve, e.g.

```
    query = SELECT replacement FROM aliases WHERE mailbox = '%s'
```

This parameter supports the following '%' expansions:

%%

This is replaced by a literal '%' character.

%s

This is replaced by the input key. SQL quoting is used to make sure that the input key does not add unexpected metacharacters.

%u

When the input key is an address of the form user@domain, %u is replaced by the SQL quoted local part of the address. Otherwise, %u is replaced by the entire search string. If the localpart is empty, the query is suppressed and returns no results.

%d

When the input key is an address of the form user@domain, %d is replaced by the SQL quoted domain part of the address. Otherwise, the query is suppressed and returns no results.

%[SUD]

The upper-case equivalents of the above expansions behave in the query parameter identically to their lower-case counter-parts. With the result_format parameter (see below), they expand the input key rather than the result value.

%[1-9]

The patterns %1, %2, ... %9 are replaced by the corresponding most significant component of the input key's domain. If the input key is user@mail.example.com, then %1 is com, %2 is example and %3 is mail. If the input key is unqualified or does not have enough domain components to satisfy all the specified patterns, the query is suppressed and returns no results.

The domain parameter described below limits the input keys to addresses in matching domains. When the domain parameter is non-empty, SQL queries for unqualified addresses or addresses in non-matching domains are suppressed and return no results. This parameter is available with Postfix 2.2. In prior releases the SQL query was built from the separate parameters: select_field, table, where_field and additional_conditions. The mapping from the old parameters to the equivalent query is:

```
    SELECT [select_field]

    FROM [table]

    WHERE [where_field] = '%s'

          [additional_conditions]
```

The '%s' in the WHERE clause expands to the escaped search string. With Postfix 2.2 these legacy parameters are used if the query parameter is not specified.

NOTE: DO NOT put quotes around the query parameter.

result_format (default: %s)

Format template applied to result attributes. Most commonly used to append (or prepend) text to the result. This parameter supports the following '%' expansions:

%%

This is replaced by a literal '%' character.

%s

This is replaced by the value of the result attribute. When result is empty it is skipped.

%u

When the result attribute value is an address of the form user@domain, %u is replaced by the local part of the address. When the result has an empty localpart it is skipped.

%d

When a result attribute value is an address of the form user@domain, %d is replaced by the domain part of the attribute value. When the result is unqualified it is skipped.

%[SUD1-9]

The upper-case and decimal digit expansions interpolate the parts of the input key rather than the result. Their behavior is identical to that described with query, and in fact because the input key is known in advance, queries whose key does not contain all the information specified in the result template are suppressed and return no results.

For example, using "result_format = smtp:[%s]" allows one to use a mailHost attribute as the basis of a transport(5) table. After applying the result format, multiple values are concatenated as comma separated strings. The expansion_limit and parameter explained below allows one to restrict the number of values in the result, which is especially useful for maps that must return at most one value. The default value %s specifies that each result value should be used as is.

This parameter is available with Postfix 2.2 and later.

NOTE: DO NOT put quotes around the result format!

domain (default: no domain list)

This is a list of domain names, paths to files, or "type:table" databases. When specified, only fully qualified search keys with a *non-empty* localpart and a matching domain are eligible for lookup: 'user' lookups, bare domain lookups and "@domain" lookups are not performed. This can significantly reduce the query load on the SQLite server.

```
    domain = postfix.org, hash:/etc/postfix/searchdomains
```

It is best not to use SQL to store the domains eligible for SQL lookups.

This parameter is available with Postfix 2.2 and later.

NOTE: DO NOT define this parameter for local(8) aliases, because the input keys are always unqualified.

expansion_limit (default: 0)

A limit on the total number of result elements returned (as a comma separated list) by a lookup against the map. A setting of zero disables the limit. Lookups fail with a temporary error if the limit is exceeded. Setting the limit to 1 ensures that lookups do not return multiple values.

## OBSOLETE MAIN.CF PARAMETERS

```

```

For compatibility with other Postfix lookup tables, SQLite parameters can also be defined in main.cf. In order to do that, specify as SQLite source a name that doesn't begin with a slash or a dot. The SQLite parameters will then be accessible as the name you've given the source in its definition, an underscore, and the name of the parameter. For example, if the map is specified as "sqlite:sqlitename", the parameter "query" would be defined in main.cf as "sqlitename_query".

## OBSOLETE QUERY INTERFACE

```

```

This section describes an interface that is deprecated as of Postfix 2.2. It is replaced by the more general query interface described above. If the query parameter is defined, the legacy parameters described here ignored. Please migrate to the new interface as the legacy interface may be removed in a future release.

The following parameters can be used to fill in a SELECT template statement of the form:

```
    SELECT [select_field]

    FROM [table]

    WHERE [where_field] = '%s'

          [additional_conditions]
```

The specifier %s is replaced by the search string, and is escaped so if it contains single quotes or other odd characters, it will not cause a parse error, or worse, a security problem.

select_field

The SQL "select" parameter. Example:

```
    select_field = forw_addr
```

table

The SQL "select .. from" table name. Example:

```
    table = mxaliases
```

where_field

The SQL "select .. where" parameter. Example:

```
    where_field = alias
```

additional_conditions

Additional conditions to the SQL query. Example:

```
    additional_conditions = AND status = 'paid'
```

## SEE ALSO

```
postmap(1), Postfix lookup table maintenance
postconf(5), configuration parameters
ldap_table(5), LDAP lookup tables
mysql_table(5), MySQL lookup tables
pgsql_table(5), PostgreSQL lookup tables
```

## README FILES

```

```

Use "postconf readme_directory" or "postconf html_directory" to locate this information.

```
DATABASE_README, Postfix lookup table overview
SQLITE_README, Postfix SQLITE howto
```

## LICENSE

```

```

The Secure Mailer license must be distributed with this software.

## HISTORY

SQLite support was introduced with Postfix version 2.8.

## AUTHOR(S)

```
Original implementation by:
Axel Steiner
```


title: tcp_table(5)

text:
# tcp_table(5)

## NAME
tcp_table - Postfix client/server table lookup protocol

## SYNOPSIS

```
postmap -q "string" tcp:host:port
postmap -q - tcp:host:port <inputfile
```

## DESCRIPTION

The Postfix mail system uses optional tables for address rewriting or mail routing. These tables are usually in dbm or db format. Alternatively, table lookups can be directed to a TCP server.

To find out what types of lookup tables your Postfix system supports use the "postconf -m" command.

To test lookup tables, use the "postmap -q" command as described in the SYNOPSIS above.

## PROTOCOL DESCRIPTION

```

```

The TCP map class implements a very simple protocol: the client sends a request, and the server sends one reply. Requests and replies are sent as one line of ASCII text, terminated by the ASCII newline character. Request and reply parameters (see below) are separated by whitespace.

Send and receive operations must complete in 100 seconds.

## REQUEST FORMAT

```

```

The tcp_table protocol supports only the lookup request. The request has the following form:

get SPACE key NEWLINE

Look up data under the specified key.

Postfix will not generate partial search keys such as domain names without one or more subdomains, network addresses without one or more least-significant octets, or email addresses without the localpart, address extension or domain portion. This behavior is also found with cidr:, pcre:, and regexp: tables.

## REPLY FORMAT

```

```

Each reply specifies a status code and text. Replies must be no longer than 4096 characters including the newline terminator.

500 SPACE text NEWLINE

In case of a lookup request, the requested data does not exist. The text describes the nature of the problem.

400 SPACE text NEWLINE

This indicates an error condition. The text describes the nature of the problem. The client should retry the request later.

200 SPACE text NEWLINE

The request was successful. In the case of a lookup request, the text contains an encoded version of the requested data.

## ENCODING

```

```

In request and reply parameters, the character %, each non-printing character, and each whitespace character must be replaced by %XX, where XX is the corresponding ASCII hexadecimal character value. The hexadecimal codes can be specified in any case (upper, lower, mixed).

The Postfix client always encodes a request. The server may omit the encoding as long as the reply is guaranteed to not contain the % or NEWLINE character.

## SECURITY

```

```

Do not use TCP lookup tables for security critical purposes. The client-server connection is not protected and the server is not authenticated.

## BUGS

Only the lookup method is currently implemented.

The client does not hang up when the connection is idle for a long time.

## SEE ALSO

```
postmap(1), Postfix lookup table manager
regexp_table(5), format of regular expression tables
pcre_table(5), format of PCRE tables
cidr_table(5), format of CIDR tables
```

## README FILES

```

```

Use "postconf readme_directory" or "postconf html_directory" to locate this information.

```
DATABASE_README, Postfix lookup table overview
```

## LICENSE

```

```

The Secure Mailer license must be distributed with this software.

## AUTHOR(S)

```
Wietse Venema
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA
Wietse Venema
Google, Inc.
111 8th Avenue
New York, NY 10011, USA
```


transport

title: transport(5)

text:
# transport(5)

## NAME
transport - Postfix transport table format

## SYNOPSIS

```
postmap /etc/postfix/transport
postmap -q "string" /etc/postfix/transport
postmap -q - /etc/postfix/transport <inputfile
```

## DESCRIPTION

The optional transport(5) table specifies a mapping from email addresses to message delivery transports and next-hop destinations. Message delivery transports such as local or smtp are defined in the master.cf file, and next-hop destinations are typically hosts or domain names. The table is searched by the trivial-rewrite(8) daemon.

This mapping overrides the default transport:nexthop selection that is built into Postfix:

local_transport (default: local:$myhostname)

This is the default for final delivery to domains listed with mydestination, and for [ipaddress] destinations that match $inet_interfaces or $proxy_interfaces. The default nexthop destination is the MTA hostname.

virtual_transport (default: virtual:)

This is the default for final delivery to domains listed with virtual_mailbox_domains. The default nexthop destination is the recipient domain.

relay_transport (default: relay:)

This is the default for remote delivery to domains listed with relay_domains. In order of decreasing precedence, the nexthop destination is taken from relay_transport, sender_dependent_relayhost_maps, relayhost, or from the recipient domain.

default_transport (default: smtp:)

This is the default for remote delivery to other destinations. In order of decreasing precedence, the nexthop destination is taken from sender_dependent_default_transport_maps, default_transport, sender_dependent_relayhost_maps, relayhost, or from the recipient domain.

Normally, the transport(5) table is specified as a text file that serves as input to the postmap(1) command. The result, an indexed file in dbm or db format, is used for fast searching by the mail system. Execute the command "postmap /etc/postfix/transport" to rebuild an indexed file after changing the corresponding transport table.

When the table is provided via other means such as NIS, LDAP or SQL, the same lookups are done as for ordinary indexed files.

Alternatively, the table can be provided as a regular-expression map where patterns are given as regular expressions, or lookups can be directed to a TCP-based server. In those case, the lookups are done in a slightly different way as described below under "REGULAR EXPRESSION TABLES" or "TCP-BASED TABLES".

## CASE FOLDING

```

```

The search string is folded to lowercase before database lookup. As of Postfix 2.3, the search string is not case folded with database types such as regexp: or pcre: whose lookup fields can match both upper and lower case.

## TABLE FORMAT

```

```

The input format for the postmap(1) command is as follows:

pattern result

When pattern matches the recipient address or domain, use the corresponding result.

blank lines and comments

Empty lines and whitespace-only lines are ignored, as are lines whose first non-whitespace character is a `#'.

multi-line text

A logical line starts with non-whitespace text. A line that starts with whitespace continues a logical line.

The pattern specifies an email address, a domain name, or a domain name hierarchy, as described in section "TABLE SEARCH ORDER".

The result is of the form transport:nexthop and specifies how or where to deliver mail. This is described in section "RESULT FORMAT".

## TABLE SEARCH ORDER

```

```

With lookups from indexed files such as DB or DBM, or from networked tables such as NIS, LDAP or SQL, patterns are tried in the order as listed below:

user+extension@domain transport:nexthop

Deliver mail for user+extension@domain through transport to nexthop.

user@domain transport:nexthop

Deliver mail for user@domain through transport to nexthop.

domain transport:nexthop

Deliver mail for domain through transport to nexthop.

.domain transport:nexthop

Deliver mail for any subdomain of domain through transport to nexthop. This applies only when the string transport_maps is not listed in the parent_domain_matches_subdomains configuration setting. Otherwise, a domain name matches itself and its subdomains.

* transport:nexthop

The special pattern * represents any address (i.e. it functions as the wild-card pattern, and is unique to Postfix transport tables).

Note 1: the null recipient address is looked up as $empty_address_recipient@$myhostname (default: mailer-daemon@hostname).

Note 2: user@domain or user+extension@domain lookup is available in Postfix 2.0 and later.

## RESULT FORMAT

```

```

The lookup result is of the form transport:nexthop. The transport field specifies a mail delivery transport such as smtp or local. The nexthop field specifies where and how to deliver mail.

The transport field specifies the name of a mail delivery transport (the first name of a mail delivery service entry in the Postfix master.cf file).

The nexthop field usually specifies one recipient domain or hostname. In the case of the Postfix SMTP/LMTP client, the nexthop field may contain a list of nexthop destinations separated by comma or whitespace (Postfix 3.5 and later).

The syntax of a nexthop destination is transport dependent. With SMTP, specify a service on a non-default port as host:service, and disable MX (mail exchanger) DNS lookups with [host] or [host]:port. The [] form is required when you specify an IP address instead of a hostname.

A null transport and null nexthop field means "do not change": use the delivery transport and nexthop information that would be used when the entire transport table did not exist.

A non-null transport field with a null nexthop field resets the nexthop information to the recipient domain.

A null transport field with non-null nexthop field does not modify the transport information.

## EXAMPLES

```

```

In order to deliver internal mail directly, while using a mail relay for all other mail, specify a null entry for internal destinations (do not change the delivery transport or the nexthop information) and specify a wildcard for all other destinations.

```
     my.domain    :

     .my.domain   :

     *            smtp:outbound-relay.my.domain
```

In order to send mail for example.com and its subdomains via the uucp transport to the UUCP host named example:

```
     example.com      uucp:example

     .example.com     uucp:example
```

When no nexthop host name is specified, the destination domain name is used instead. For example, the following directs mail for user@example.com via the slow transport to a mail exchanger for example.com. The slow transport could be configured to run at most one delivery process at a time:

```
     example.com      slow:
```

When no transport is specified, Postfix uses the transport that matches the address domain class (see DESCRIPTION above). The following sends all mail for example.com and its subdomains to host gateway.example.com:

```
     example.com      :[gateway.example.com]

     .example.com     :[gateway.example.com]
```

In the above example, the [] suppress MX lookups. This prevents mail routing loops when your machine is primary MX host for example.com.

In the case of delivery via SMTP or LMTP, one may specify host:service instead of just a host:

```
     example.com      smtp:bar.example:2025
```

This directs mail for user@example.com to host bar.example port 2025. Instead of a numerical port a symbolic name may be used. Specify [] around the hostname if MX lookups must be disabled.

Deliveries via SMTP or LMTP support multiple destinations (Postfix >= 3.5):

```
     example.com      smtp:bar.example, foo.example
```

This tries to deliver to bar.example before trying to deliver to foo.example.

The error mailer can be used to bounce mail:

```
     .example.com     error:mail for *.example.com is not deliverable
```

This causes all mail for user@anything.example.com to be bounced.

## REGULAR EXPRESSION TABLES

```

```

This section describes how the table lookups change when the table is given in the form of regular expressions. For a description of regular expression lookup table syntax, see regexp_table(5) or pcre_table(5).

Each pattern is a regular expression that is applied to the entire address being looked up. Thus, some.domain.hierarchy is not looked up via its parent domains, nor is user+foo@domain looked up as user@domain.

Patterns are applied in the order as specified in the table, until a pattern is found that matches the search string.

The trivial-rewrite(8) server disallows regular expression substitution of $1 etc. in regular expression lookup tables, because that could open a security hole (Postfix version 2.3 and later).

## TCP-BASED TABLES

```

```

This section describes how the table lookups change when lookups are directed to a TCP-based server. For a description of the TCP client/server lookup protocol, see tcp_table(5). This feature is not available up to and including Postfix version 2.4.

Each lookup operation uses the entire recipient address once. Thus, some.domain.hierarchy is not looked up via its parent domains, nor is user+foo@domain looked up as user@domain.

Results are the same as with indexed file lookups.

## CONFIGURATION PARAMETERS

```

```

The following main.cf parameters are especially relevant. The text below provides only a parameter summary. See postconf(5) for more details including examples.

empty_address_recipient (MAILER-DAEMON)

The recipient of mail addressed to the null address.

parent_domain_matches_subdomains (see 'postconf -d' output)

A list of Postfix features where the pattern "example.com" also matches subdomains of example.com, instead of requiring an explicit ".example.com" pattern.

transport_maps (empty)

Optional lookup tables with mappings from recipient address to (message delivery transport, next-hop destination).

## SEE ALSO

```
trivial-rewrite(8), rewrite and resolve addresses
master(5), master.cf file format
postconf(5), configuration parameters
postmap(1), Postfix lookup table manager
```

## README FILES

```

```

Use "postconf readme_directory" or "postconf html_directory" to locate this information.

```
ADDRESS_REWRITING_README, address rewriting guide
DATABASE_README, Postfix lookup table overview
FILTER_README, external content filter
```

## LICENSE

```

```

The Secure Mailer license must be distributed with this software.

## AUTHOR(S)

```
Wietse Venema
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA
Wietse Venema
Google, Inc.
111 8th Avenue
New York, NY 10011, USA
```


virtual

title: virtual(5)

text:
# virtual(5)

## NAME
virtual - Postfix virtual alias table format

## SYNOPSIS

```
postmap /etc/postfix/virtual
postmap -q "string" /etc/postfix/virtual
postmap -q - /etc/postfix/virtual <inputfile
```

## DESCRIPTION

The optional virtual(5) alias table rewrites recipient addresses for all local, all virtual, and all remote mail destinations. This is unlike the aliases(5) table which is used only for local(8) delivery. This feature is implemented in the Postfix cleanup(8) daemon before mail is queued.

Virtual aliasing is recursive; to terminate recursion for a specific address, alias that address to itself.

The main applications of virtual aliasing are:

- To redirect mail for one address to one or more addresses.

- To implement virtual alias domains where all addresses are aliased to addresses in other domains. Virtual alias domains are not to be confused with the virtual mailbox domains that are implemented with the Postfix virtual(8) mail delivery agent. With virtual mailbox domains, each recipient address can have its own mailbox.

Virtual aliasing is applied only to recipient envelope addresses, and does not affect message headers. Use canonical(5) mapping to rewrite header and envelope addresses in general.

Normally, the virtual(5) alias table is specified as a text file that serves as input to the postmap(1) command. The result, an indexed file in dbm or db format, is used for fast searching by the mail system. Execute the command "postmap /etc/postfix/virtual" to rebuild an indexed file after changing the corresponding text file.

When the table is provided via other means such as NIS, LDAP or SQL, the same lookups are done as for ordinary indexed files.

Alternatively, the table can be provided as a regular-expression map where patterns are given as regular expressions, or lookups can be directed to a TCP-based server. In those case, the lookups are done in a slightly different way as described below under "REGULAR EXPRESSION TABLES" or "TCP-BASED TABLES".

## CASE FOLDING

```

```

The search string is folded to lowercase before database lookup. As of Postfix 2.3, the search string is not case folded with database types such as regexp: or pcre: whose lookup fields can match both upper and lower case.

## TABLE FORMAT

```

```

The input format for the postmap(1) command is as follows:

pattern address, address, ...

When pattern matches a mail address, replace it by the corresponding address.

blank lines and comments

Empty lines and whitespace-only lines are ignored, as are lines whose first non-whitespace character is a `#'.

multi-line text

A logical line starts with non-whitespace text. A line that starts with whitespace continues a logical line.

## TABLE SEARCH ORDER

```

```

With lookups from indexed files such as DB or DBM, or from networked tables such as NIS, LDAP or SQL, each user@domain query produces a sequence of query patterns as described below.

Each query pattern is sent to each specified lookup table before trying the next query pattern, until a match is found.

user@domain address, address, ...

Redirect mail for user@domain to address. This form has the highest precedence.

user address, address, ...

Redirect mail for user@site to address when site is equal to $myorigin, when site is listed in $mydestination, or when it is listed in $inet_interfaces or $proxy_interfaces. This functionality overlaps with the functionality of the local aliases(5) database. The difference is that virtual(5) mapping can be applied to non-local addresses.

@domain address, address, ...

Redirect mail for other users in domain to address. This form has the lowest precedence. Note: @domain is a wild-card. With this form, the Postfix SMTP server accepts mail for any recipient in domain, regardless of whether that recipient exists. This may turn your mail system into a backscatter source: Postfix first accepts mail for non-existent recipients and then tries to return that mail as "undeliverable" to the often forged sender address.

To avoid backscatter with mail for a wild-card domain, replace the wild-card mapping with explicit 1:1 mappings, or add a reject_unverified_recipient restriction for that domain:

```
    smtpd_recipient_restrictions =

        ...

        reject_unauth_destination

        check_recipient_access

            inline:{example.com=reject_unverified_recipient}

    unverified_recipient_reject_code = 550
```

In the above example, Postfix may contact a remote server if the recipient is aliased to a remote address.

## RESULT ADDRESS REWRITING

```

```

The lookup result is subject to address rewriting:

- When the result has the form @otherdomain, the result becomes the same user in otherdomain. This works only for the first address in a multi-address lookup result.

- When "append_at_myorigin=yes", append "@$myorigin" to addresses without "@domain".

- When "append_dot_mydomain=yes", append ".$mydomain" to addresses without ".domain".

## ADDRESS EXTENSION

```

```

When a mail address localpart contains the optional recipient delimiter (e.g., user+foo@domain), the lookup order becomes: user+foo@domain, user@domain, user+foo, user, and @domain.

The propagate_unmatched_extensions parameter controls whether an unmatched address extension (+foo) is propagated to the result of a table lookup.

## VIRTUAL ALIAS DOMAINS

```

```

Besides virtual aliases, the virtual alias table can also be used to implement virtual alias domains. With a virtual alias domain, all recipient addresses are aliased to addresses in other domains.

Virtual alias domains are not to be confused with the virtual mailbox domains that are implemented with the Postfix virtual(8) mail delivery agent. With virtual mailbox domains, each recipient address can have its own mailbox.

With a virtual alias domain, the virtual domain has its own user name space. Local (i.e. non-virtual) usernames are not visible in a virtual alias domain. In particular, local aliases(5) and local mailing lists are not visible as localname@virtual-alias.domain.

Support for a virtual alias domain looks like:

```
/etc/postfix/main.cf:

    virtual_alias_maps = hash:/etc/postfix/virtual
```

Note: some systems use dbm databases instead of hash. See the output from "postconf -m" for available database types.

```
/etc/postfix/virtual:

    virtual-alias.domain    anything (right-hand content does not matter)

    postmaster@virtual-alias.domain postmaster

    user1@virtual-alias.domain      address1

    user2@virtual-alias.domain      address2, address3
```

The virtual-alias.domain anything entry is required for a virtual alias domain. Without this entry, mail is rejected with "relay access denied", or bounces with "mail loops back to myself".

Do not specify virtual alias domain names in the main.cf mydestination or relay_domains configuration parameters.

With a virtual alias domain, the Postfix SMTP server accepts mail for known-user@virtual-alias.domain, and rejects mail for unknown-user@virtual-alias.domain as undeliverable.

Instead of specifying the virtual alias domain name via the virtual_alias_maps table, you may also specify it via the main.cf virtual_alias_domains configuration parameter. This latter parameter uses the same syntax as the main.cf mydestination configuration parameter.

## REGULAR EXPRESSION TABLES

```

```

This section describes how the table lookups change when the table is given in the form of regular expressions. For a description of regular expression lookup table syntax, see regexp_table(5) or pcre_table(5).

Each pattern is a regular expression that is applied to the entire address being looked up. Thus, user@domain mail addresses are not broken up into their user and @domain constituent parts, nor is user+foo broken up into user and foo.

Patterns are applied in the order as specified in the table, until a pattern is found that matches the search string.

Results are the same as with indexed file lookups, with the additional feature that parenthesized substrings from the pattern can be interpolated as $1, $2 and so on.

## TCP-BASED TABLES

```

```

This section describes how the table lookups change when lookups are directed to a TCP-based server. For a description of the TCP client/server lookup protocol, see tcp_table(5). This feature is available in Postfix 2.5 and later.

Each lookup operation uses the entire address once. Thus, user@domain mail addresses are not broken up into their user and @domain constituent parts, nor is user+foo broken up into user and foo.

Results are the same as with indexed file lookups.

## BUGS

The table format does not understand quoting conventions.

## CONFIGURATION PARAMETERS

```

```

The following main.cf parameters are especially relevant to this topic. See the Postfix main.cf file for syntax details and for default values. Use the "postfix reload" command after a configuration change.

virtual_alias_maps ($virtual_maps)

Optional lookup tables that alias specific mail addresses or domains to other local or remote addresses.

virtual_alias_domains ($virtual_alias_maps)

Postfix is the final destination for the specified list of virtual alias domains, that is, domains for which all addresses are aliased to addresses in other local or remote domains.

propagate_unmatched_extensions (canonical, virtual)

What address lookup tables copy an address extension from the lookup key to the lookup result.

Other parameters of interest:

inet_interfaces (all)

The local network interface addresses that this mail system receives mail on.

mydestination ($myhostname, localhost.$mydomain, localhost, $config_directory/mydestination)

The list of domains that are delivered via the $local_transport mail delivery transport.

myorigin ($myhostname)

The domain name that locally-posted mail appears to come from, and that locally posted mail is delivered to.

owner_request_special (yes)

Enable special treatment for owner-listname entries in the aliases(5) file, and don't split owner-listname and listname-request address localparts when the recipient_delimiter is set to "-".

proxy_interfaces (empty)

The remote network interface addresses that this mail system receives mail on by way of a proxy or network address translation unit.

## SEE ALSO

```
cleanup(8), canonicalize and enqueue mail
postmap(1), Postfix lookup table manager
postconf(5), configuration parameters
canonical(5), canonical address mapping
```

## README FILES

```

```

Use "postconf readme_directory" or "postconf html_directory" to locate this information.

```
ADDRESS_REWRITING_README, address rewriting guide
DATABASE_README, Postfix lookup table overview
VIRTUAL_README, domain hosting guide
```

## LICENSE

```

```

The Secure Mailer license must be distributed with this software.

## AUTHOR(S)

```
Wietse Venema
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA
Wietse Venema
Google, Inc.
111 8th Avenue
New York, NY 10011, USA
```


poundctl.tmpl

package: pound

title: poundctl.tmpl(5)

summary: templates for poundctl.

text:
# poundctl.tmpl(5)

## NAME
poundctl.tmpl - templates for poundctl.

## DESCRIPTION
The syntax of poundctl templates is modelled after and mostly conforming to the specifications of the golang template module (https://pkg.go.dev/text/template).

Templates are executed by applying them to a JSON object. Annotations in a template refer to attributes of the object to control execution and derive values to be displayed. Execution of the template walks the structure and sets the cursor, represented by a period (called dot), to the value at the current location in the object as execution proceeds.

The input text for a template is as ASCII text is arbitrary format. Actions -- data evaluations or control structures -- are delimited by {{ and }}; all text outside actions is copied to the output verbatim.

To aid in formatting template source code, if {{ is followed immediately by a minus sign and white space, all trailing white space is trimmed from the immediately preceding text. Similarly, if }} is preceded by white space and a minus sign, all leading white space is trimmed from the immediately following text. Notice that the presence of the whitespace in these trim markers is mandatory: "{{- 3}}" trims the immediately preceding text and outputs "3", while "{{-3}}" parses as an action containing the number -3.

### Actions
Here is the list of actions. Arguments and pipelines are evaluations of data, defined in detail in the corresponding sections that follow.

{{ }}

Empty action is discarded. It may be useful to trim the preceding or following whitespace, as in {{- -}} .

{{/* a comment */}}

Comments are discarded. They may span multiple lines of text. Comments do not nest and must start immediately after the opening delimiter (with optional dash and whitespace in between). A comment may be followed by any action described below.

Comments may be used to control trailing and leading whitespace as well:

```
{{- a comment trimming the surrounding whitespace -}}

```

{{pipeline}}

Pipeline is evaluated, and the default textual representation of its value is copied to the output.

{{if pipeline}} T1 {{end}}

If the value of the pipeline is empty, no output is generated; otherwise, T1 is executed. The empty values are null, false, numeric 0, null, empty string (""), array ([]), or object ({}). Dot is unaffected.

{{if pipeline}} T1 {{else}} T0 {{end}}

If the value of the pipeline is empty, T0 is executed; otherwise, T1 is executed. Dot is unaffected.

{{if pipeline}} T1 {{else if pipeline}} T2 {{else}} T0 {{end}}

A shortcut to simplify writing the if-else chains. Equivalent to (newlines added for readability):

```
{{if pipeline }}

  T1
{{else -}}

 {{if pipeline }}

   T2

 {{else}}

   T0

 {{end}}
{{end}}

```

{{range pipeline}} T1 {{end}}

The value of pipeline must be an object or array. If it is of length zero, nothing is output. Otherwise, dot is set to the successive elements of the array or object and T1 is executed. For objects, the elements will be visited in sorted key order.

{{range pipeline}} T1 {{else}} T0 {{end}}

Same as above, except that if the value of the pipeline is of length zero, T0 is executed with dot unaffected.

Within the {{range}} action, the following two keywords may appear:

{{break}}

The innermost {{range pipeline}} loop is ended early, stopping the current iteration and bypassing all remaining iterations.

{{continue}}

The current iteration of the innermost {{range pipeline}} loop is stopped, and the loop starts the next iteration.

{{define "name"}} text {{end}}

The text is collected and stored for the further use as template with the given name. It can be invoked using the {{template}} action (see below).

{{template "name"}}

The template with the specified name (see the {{define}} above) is executed with dot set to null.

{{template "name" value}}

The template with the specified name (see the {{define}} above) is executed with dot set to value.

{{block "name" pipeline}} T1 {{end}}

A block is shorthand for defining a template

```
{{define "name"}} T1 {{end}}

```

and then executing it in place

```
{{template "name" pipeline}}

```

{{with pipeline}} T1 {{end}}

If the value of the pipeline is empty, no output is generated; otherwise, dot is set to the value of the pipeline and T1 is executed.

{{with pipeline}} T1 {{else}} T0 {{end}}

Same as above, but if the value of the pipeline is empty, T0 is executed with dot unchanged.

### Arguments
An argument is a simple value, i.e. any of the following:

Numeric value (integer or floating point)

Boolean value: true or false.

Quoted string.

A dot (.)

This represents the cursor value.

Attribute: .Attr

This is the value of the attribute Attr in the current value (dot).

Attribute references can be nested, as in .Attr.Xattr.Yattr.

A variable reference: $var.

Here, var is the name of the variable defined in the range action. See the subsection Variables, below.

Function call in parentheses, for grouping.

### Pipelines
A pipeline is a series of one or more commands delimited by pipe sign (|). Each command is either an argument or a function call, in form:

```
func arg1 arg2...
```

where func is the name of one of the built-in functions discussed below.

Pipelines are executed from left to right, with the result of the previous command implicitly added to the list of argument of each subsequent command. For example, the pipeline

```
.attr | eq $x
```

is equivalent to

```
eq $x .attr
```

i.e. it calls the built-in function eq with two arguments: the value of the variable x and attribute attr of the cursor value.

The following built-in functions are defined:

and A1 A2

Evaluates to true if pipelines A1 and A2 both evaluate to true. Notice, that there is no boolean shortcut evaluation: both pipelines are evaluated prior to calling and.

or A1 A2

Evaluates to true if at least one of the pipelines A1 and A2 evaluates to true. Notice, that there is no boolean shortcut evaluation: both pipelines are evaluated prior to calling and.

index A1 A2...

Returns the result of indexing its first argument by the following arguments. Thus, if . is an array, then:

```
index . 5

```

evaluates to its fifth element (.[5]).

len A1

Returns the integer length of its argument.

not A1

Returns true if its argument evaluates to false.

eq A1 A2

Returns true if both its arguments are equal. This applies only if both A1 and A2 are numeric or if they both are strings.

ne A1 A2

Returns true if its arguments (both must be numeric or strings) are not strings.

lt A1 A2

Returns true if A1 is numerically less than A2.

le A1 A2

Returns true if A1 is numerically less than or equal to A2.

gt A1 A2

Returns true if A1 is numerically greater than A2.

ge A1 A2

Returns true if A1 is numerically greater than or equal to A2.

even A1

Returns true if A1, which must evaluate to an integer value, is divisible by 2.

printf FMT A1...

Implements the printf(3) function. FMT must evaluate to a string. Rest of arguments is interpreted according to the conversion specifications in FMT. The result is a formatted string.

In addition to the standard conversion specifications described in printf(3), the "%v" specifier is implemented: it formats its argument in the best way, depending on its actual type.

typeof A1

Evaluates to the type of its argument, one of: null, bool, number, integer, string, array, object.

exists A1 A2

A1 must evaluate to an object and A2 to string. The function evaluates to true if the attribute A2 is present in A1.

add A1 A2...

Returns the sum of its arguments.

sub A1 A2

Returns the difference A1 - A2.

mul A1 A2

Multiplies A1 by A2.

div A1 A2

Divides A1 by A2.

### Variables
Variables (referred to as $name) can be defined in range and with actions. For range, the syntax is:

```
{{range $index, $element = pipeline}} T1 {{end}}
```

where index and element are arbitrary variable names. When executing this action, during each iteration $index and $element are set to the index (attribute name) and value of each successive element. Dot remains unaffected.

For with, the syntax is:

```
{{with $var = pipeline}} T1 {{end}}
```

Pipeline is evaluated, its result is assigned to $var and the T1 block is executed with dot unchanged.

A variable's scope extends to the end action of the control structure (with or range) in which it is declared. This includes any nested statements that may appear in between.

## INPUT OBJECT
Depending on the request issued by poundctl, the invoked template can receive as its argument (dot) an object of the following types: full listing, listener, service, or backend.

Since there is no explicit indication of the object type being passed, templates normally use heuristics based on the presence or absence of certain attribute to deduce the object type in question. The recommended approach is described in the following pseudo-code fragment:

```
{{if exists . "listeners" }}

  {{/* This is a full listing, as requested by poundctl list. */}}

  ...
{{else if exists . "services"}}

  {{/* Single listener, as requested by poundctl list /L.

       Notice that this attribute is present in the full listing as

       well, so presence of "listeners" should be checked first. */}}

  ...
{{else if exists . "backends"}}

  {{/* Single service, as requested by poundctl list /L/S. */}}

  ...
{{else}}

  {{/* Backend listing (poundctl list /L/S/B) */}}

  ...
{{end}}
```

Structures of each object are discussed in subsections that follow.

### Full listing
A full listing contains the following attributes:

listeners

An array of listener objects. See below for a description.

services

An array of services objects, representing services defined in the global scope of the pound configuration file.

pid

PID of the running pound daemon.

version

Pound version number (string).

workers

Workers statistics. This is a JSON object with the following attributes:

active

Number of active threads.

count

Number of threads currently running.

max

Maximum number of threads.

min

Minimum number of threads.

timeout

Thread idle timeout.

queue_len

Number of incoming HTTP requests in the queue (integer).

timestamp

Current time on the server, formatted as ISO 8601 date-time with microsecond precision, e.g.: "2023-01-05T22:43:18.071559".

### Listener
A listener object represents a single HTTP or HTTPS listener in pound configuration. It has the following attributes:

address

String. Address of this listener. A string formatted as "IP:PORT" for IPv4 and IPv6 addresses or containing socket file name, for UNIX sockets.

protocol

String. Protocol used: either http or https.

services

Array of service objects representing services defined in this listener. See below for a definition of service object.

enabled

Boolean. Whether this listener is enabled or not.

nohttps11

Integer. Value of the NoHTTPS11 configuration statement for this listener. One of: 0, 1, 2.

### Service
A service object describes a single service.

name

String. Symbolic name of this service.

enabled

Boolean. Whether this service is enabled or not.

tot_pri

Integer. Sum of priority values of active backends in this service.

abs_pri

Integer. Sum of priority values of all defined backends in this service.

session_type

String. Name of the session handling algorithm for this service. One of: IP, BASIC, URL, PARM, COOKIE, HEADER.

sessions

List of active sessions in this service. Each session is represented as object with the following attributes:

key

String. Session key.

backend

Integer. Number of the backend assigned to handle requests with this session.

expire

Timestamp. Expiration time of this session, with microsecond precision.

backends

List of backends defined for this service.

emergency

Emergency backend object, or null if no such backend is defined.

### Backend
The following attributes are always present in each backend object:

alive

Boolean. Whether or not this backend is alive.

conn_to

Integer. Connection timeout for this backend (seconds).

enabled

Boolean. Whether or not this backend is enabled.

io_to

Integer. I/O timeout for this backend (seconds).

priority

Integer in range 0-9. Priority value assigned to this backend.

protocol

String. Protocol used by this backend: either http or https.

type

String. Backend type. One of: acme, backend, control, redirect.

ws_to

Integer Websocket timeout (seconds).

Depending on the backend type, the following attributes may be present:

acme

path

String. Directory where ACME challenges are stored.

backend

address

String. Backend address.

redirect

url

String. URL to redirect to.

code

Integer. HTTP code for redirection responses. One of: 301, 302, 307.

redir_req

Boolean. Whether to append the original request path to the resulting location.

If backend statistics is enabled (see BackendStats in pound(8)), the stats object will be present, with the following attributes:

request_count

Total number of requests processed by this backend.

request_time_avg

Average time per request, in nanoseconds.

request_time_stddev

Standard deviation of the above.

## SEE ALSO
pound(8), poundctl(8).

## REPORTING BUGS
Report bugs to <gray@gnu.org>. You may also use github issue tracker at https://github.com/graygnuorg/pound/issues.

## COPYRIGHT
Copyright © 2023 Sergey Poznyakoff

License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.


pptpd.conf

package: pptpd

title: pptpd.conf(5)

text:
# pptpd.conf(5)

## NAME
pptpd.conf - PPTP VPN daemon configuration

## DESCRIPTION
pptpd(8) reads options from this file, usually /etc/pptpd.conf. Most options can be overridden by the command line. The local and remote IP addresses for clients must come from the configuration file or from pppd(8) configuration files.

## OPTIONS
option option-file

the name of an option file to be passed to pppd(8) in place of the default /etc/ppp/options so that PPTP specific options can be given. Equivalent to the command line --option option.

stimeout seconds

number of seconds to wait for a PPTP packet before forking the pptpctrl(8) program to handle the client. The default is 10 seconds. This is a denial of service protection feature. Equivalent to the command line --stimeout option.

logwtmp

update wtmp(5) as users connect and disconnect. See wtmp(1).

debug

turns on debugging mode, sending debugging information to syslog(3). Has no effect on pppd(8) debugging. Equivalent to the command line --debug option.

bcrelay internal-interface

turns on broadcast relay mode, sending all broadcasts received on the server's internal interface to the clients. Equivalent to the command line --bcrelay option.

connections n

limits the number of client connections that may be accepted. If pptpd is allocating IP addresses (e.g. delegate is not used) then the number of connections is also limited by the remoteip option. The default is 100.

delegate

delegates the allocation of client IP addresses to pppd(8). Without this option, which is the default, pptpd manages the list of IP addresses for clients and passes the next free address to pppd. With this option, pptpd does not pass an address, and so pppd may use radius or chap-secrets to allocate an address.

localip ip-specification

one or many IP addresses to be used at the local end of the tunnelled PPP links between the server and the client. If one address only is given, this address is used for all clients. Otherwise, one address per client must be given, and if there are no free addresses then any new clients will be refused. localip will be ignored if the delegate option is used.

remoteip ip-specification

a list of IP addresses to assign to remote PPTP clients. Each connected client must have a different address, so there must be at least as many addresses as you have simultaneous clients, and preferably some spare, since you cannot change this list without restarting pptpd. A warning will be sent to syslog(3) when the IP address pool is exhausted. remoteip will be ignored if the delegate option is used.

noipparam

by default, the original client IP address is given to ip-up scripts using the pppd(8) option ipparam. The noipparam option prevents this. Equivalent to the command line --noipparam option.

listen ip-address

the local interface IP address to listen on for incoming PPTP connections (TCP port 1723). Equivalent to the command line --listen option.

vrf vrf-name

VRF to use for the TCP listening socket as well as the GRE packets. Equivalent to the command line --vrf option.

pidfile pid-file

specifies an alternate location to store the process ID file (default /run/pptpd.pid). Equivalent to the command line --pidfile option.

speed speed

specifies a speed (in bits per second) to pass to the PPP daemon as the interface speed for the tty/pty pair. This is ignored by some PPP daemons, such as Linux's pppd(8). The default is 115200 bytes per second, which some implementations interpret as meaning "no limit". Equivalent to the command line --speed option.

## NOTES
An ip-specification above (for the localip and remoteip tags) may be a list of IP addresses (for example 192.168.0.2,192.168.0.3), a range (for example 192.168.0.1-254 or 192.168.0-255.2) or some combination (for example 192.168.0.2,192.168.0.5-8). For some valid pairs might be (depending on use of the VPN):

localip 192.168.0.1

remoteip 192.168.0.2-254

or

localip 192.168.1.2-254

remoteip 192.168.0.2-254

## ROUTING CHECKLIST - PROXYARP
Allocate a section of your LAN addresses for use by clients.

In /etc/ppp/options.pptpd. set the proxyarp option. In pptpd.conf do not set localip option, but set remoteip to the allocated address range. Enable kernel forwarding of packets, (e.g. using /proc/sys/net/ipv4/ip_forward ).

The server will advertise the clients to the LAN using ARP, providing it's own ethernet address. bcrelay(8) should not be required.

## ROUTING CHECKLIST - FORWARDING
Allocate a subnet for the clients that is routable from your LAN, but is not part of your LAN.

In pptpd.conf set localip to a single address or range in the allocated subnet, set remoteip to a range in the allocated subnet. Enable kernel forwarding of packets, (e.g. using /proc/sys/net/ipv4/ip_forward ). The LAN must have a route to the clients using the server as gateway.

The server will forward the packets unchanged between the clients and the LAN. bcrelay(8) will be required to support broadcast protocols such as NETBIOS.

## ROUTING CHECKLIST - MASQUERADE
Allocate a subnet for the clients that is not routable from your LAN, and not otherwise routable from the server (e.g. 10.0.0.0/24).

Set localip to a single address in the subnet (e.g. 10.0.0.1), set remoteip to a range for the rest of the subnet, (e.g. 10.0.0.2-200). Enable kernel forwarding of packets, (e.g. using /proc/sys/net/ipv4/ip_forward ). Enable masquerading on eth0 (e.g. iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE ).

The server will translate the packets between the clients and the LAN. The clients will appear to the LAN as having the address corresponding to the server. The LAN need not have an explicit route to the clients. bcrelay(8) will be required to support broadcast protocols such as NETBIOS.

## FIREWALL RULES
pptpd(8) accepts control connections on TCP port 1723, and then uses GRE (protocol 47) to exchange data packets. Add these rules to your iptables(8) configuration, or use them as the basis for your own rules:

iptables --append INPUT --protocol 47 --jump ACCEPT

```
iptables --append INPUT --protocol tcp --match tcp \

         --destination-port 1723 --jump ACCEPT
```

## SEE ALSO
pppd(8), pptpd(8), pptpd.conf(5).


boom.cfg

package: prboom

title: boom.cfg(5)

text:
# boom.cfg(5)

## NAME
boom.cfg, glboom.cfg - Configuration file for PrBoom v2.1.0 onwards

## USAGE
When a version of PrBoom is run, it searches for this configuration file to modify its default settings. Every time PrBoom exits, it rewrites the configuration file, updating any settings that have been changed using the in-game menus.

PrBoom expects the config file to be ~/.prboom/boom.cfg, or ~/.prboom/glboom.cfg if compiled with GL support. Alternatively, it can be made to look elsewhere by using a command-line parameter:

{prboom,glboom} [-config myconf]

## FORMAT
boom.cfg consists of a number of variables and values. Each line is of the following format:

[ { {{#,;,[} comment_text , variable {decimal_integer, 0x hex_integer, "string_text"}}]

Any line beginning with a non-alphabetic character is treated as a comment and ignored; for future compatibility you should start comments with a #, ; or [. Note however that when PrBoom rewrites boom.cfg it does not preserve user added comments.

Any line beginning with an alphabetic character is treated as a variable-value pair. The first word (sequence of non-whitespace characters) is the variable name, and everything after the following block of whitespace is taken to be the value assigned to the variable.

Variables not recognised by PrBoom, or which are given an invalid value or a value of an inappropriate type, are ignored. Warning messages are given where relevant.

The variables recognised by PrBoom are described per-section in the following sections. The sections are informal however; when PrBoom rewrites the config file it writes in section headings and puts variables into the relevant sections, but when reading these are ignored.

## MISC SETTINGS
compatibility_level

PrBoom is capable of behaving in a way compatible with earlier versions of Doom and Boom/PrBoom. The value given here selects the version to be compatible with when doing new games/demos. See README.compat for details.

realtic_clock_rate

Selects the speed that PrBoom runs at, as a percentage of normal game speed. Leave at 0 unless you want to experiment. Note that it is considered `cheating' to use this at any setting below 0 (or above?).

max_player_corpse

Sets the maximum number of player corpses to leave lying around. If this limit would be exceeded, an old corpse is removed. Useful for big/long Deathmatch games, where the sheer number of corpses could slow the game down.

flashing_hom

Flag indicating whether a flashing red background is drawn to highlight HOM errors in levels (for level developers)

demo_insurance

Selects a method of protecting demos against `going out of sync' (where the player seems to lose control and behave madly, but in fact the players original instructions as stored in the demo have got out of sync with the game he was playing). 0=No protection, 1=Full protection, 2=Only while recording demos. Safest when left set to 2.

endoom_mode

This parameter specifies options controlling the display of the credits screen when Doom exits. Currently it is the sum of 3 options: add 1 for colours, 2 for non-ASCII characters to be displayed, and 4 for the last line to be skipped so the top line doesn't scroll off screen.

level_precache

If set, when loading a new level PrBoom precaches all the graphics the level is likely to need in memory. This makes it much slower to load the level, but reduces disk activity and slowdowns reading data during play. Most systems are fast enough that precaching is not needed.

## FILES SETTINGS
wadfile_1, wadfile_2

The names of 2 .wad files to be automatically loaded when PrBoom is started. A blank string means unused.

dehfile_1, dehfile_2

The names of 2 patch files (.deh or .bex) to be automatically loaded when PrBoom is started (empty string for none).

## GAME SETTINGS
default_skill

The default skill level when starting a new game.

weapon_recoil

Enables recoil from weapon fire.

doom_weapon_toggles

Flag indicating whether pressing 3 or 1 when that weapon is already selected causes the selected shotgun or fist/chainsaw to be toggled, as in original Doom. Some people prefer to use a number for each weapon alone.

player_bobbing

Enables player bobbing (view randomly moving up/down slightly as the player runs).

monsters_remember

Makes monsters remember their previous enemy after killing their current target.

monster_infighting

Whether monsters will fight each other when they injure each other accidentally.

monster_backing

Whether monsters without close combat weapons will back away from close combat (unlike original Doom).

monster_avoid_hazards

Whether monsters avoid crushing ceilings.

monkeys

Whether monsters will climb steep stairs.

monster_friction

Whether monsters are affected by changed floor friction (they should be, but weren't in Boom)

help_friends

Whether monsters will help out injured monsters by aiding them against their attacker.

player_helpers

The number of helper dogs to spawn.

friend_distance

Distance within which friends will generally stay.

dog_jumping

Whether dogs will jump.

sts_always_red

PrBoom can make the colour of the text displays on the status bar reflect your current status (red=low, yellow=average, green=good, blue=super-charged). This option if set selects the traditional Doom behavior of always-red status bar display; set to 0 to allow the coloured display.

sts_pct_always_gray

See above, this makes just the percent signs always gray, instead of changing colour.

sts_traditional_keys

Doom and PrBoom have two types of keys; PrBoom will normally display both keys of a given colour if you have both. This option, if enabled, instead makes PrBoom only ever display one key of each colour, in the same way Doom did.

traditional_menu

Changes PrBoom's menu ordering to be the same as original Doom if enabled.

show_messages

When enabled, text messages are displayed in the top left corner of the screen describing events in the game. Can be toggled in the game, this is just to preserve the setting.

autorun

Makes the player always run, without having to hold down a run key. Can be toggled in the game, this just preserves the setting.

## SOUND SETTINGS
sound_card

Selects whether sound effects are enabled (non-zero enables). For compatibility reasons with Boom, a range of values are accepted.

music_card

Selects whether in-game music is enabled (non-zero enables). For compatibility reasons a range of values are accepted.

pitched_sounds

If enabled by this variable, this enables `pitching' (making pitch adjustments to the playing sounds) for 16 bit sound cards.

samplerate

The samplerate for soundmixing and timidity. The sound quality is much better at higher samplerates, but if you use timidity then higher samplerates need much more CPU power. Useful values are 11025, 22050, 44100 and 48000.

sfx_volume

Sound effects volume. This is best adjusted in the game.

music_volume

Music volume. This is best adjusted in the game.

mus_pause_opt

Selects what PrBoom does to the music when a games is paused. 0=stop the music, 1=pause the music (stop it playing, but when resumed resume it at the same place - not implemented), 2=continue playing.

sounddev, snd_channels, soundsrv, musicsrv

These variables are no longer used by PrBoom, but are kept for compatibility reasons.

## COMPATIBILITY SETTINGS
These are settings that let you choose whether the normal game mechanics are used, or whether various quirks, bugs and limitations of the original Doom game are emulated.

## VIDEO SETTINGS
screen_width, screen_height

For versions of PrBoom which support high-res, these specify the default screen or window size for PrBoom. These settings are ignored and preserved by versions of PrBoom which do not do high-res (they assume 320x200).

use_fullscreen

If set, this causes PrBoom to try to go full screen. Depending on your video driver and mode, this may include changing screen resolution to better match the game's screen resolution.

use_doublebuffer

Use double buffering to reduce tearing. On some machines this is even faster than the normal method, but on others this makes problems, so you have to try out which setting works best.

translucency

Causes PrBoom to display certain objects as translucent.

tran_filter_pct

Selects how translucent objects are when they are translucent. Play with this and see for yourself.

screenblocks

Selects a reduced screen size inside the PrBoom window (the player's view is surrounded by a border). Normally this is undesirable, but it can help speed up the game. Can be changed in the game with the +/- keys, this variable is just to preserve that setting.

usegamma

Selects a level of gamma correction (extra screen brightening) to correct for a dark monitor or light surroundings. Can be selected in the game with the F11 key, this config entry preserves that setting.

## OPENGL SETTINGS
If you are knowledgeable about OpenGL, you can tweak various aspects of the GL rendering engine.

gl_nearclip

The near clipping plane *100.

gl_colorbuffer_bits

The bit depth for the framebuffer. (16, 24 or 32 bits)

gl_depthbuffer_bits

The bit depth for the z-buffer. (16, 24 or 32 bits)

gl_tex_filter_string

A string, one of the following: GL_NEAREST or GL_LINEAR (no mipmapping), or one of GL_NEAREST_MIPMAP_NEAREST, GL_NEAREST_MIPMAP_LINEAR, GL_LINEAR_MIPMAP_NEAREST, GL_LINEAR_MIPMAP_LINEAR with mipmapping.

gl_tex_format_string

One of the following strings: GL_RGBA - means format selected by driver (not so good), GL_RGBA2 - means 2 bits for each component (bad), GL_RGBA4 - means 4 bits for each component (like GL_RGBA on most cards), GL_RGB5_A1 - means 5 bits for each color component 1 bit for the alpha channel (default), GL_RGBA8 - means 8 bits for each component (best quality, but only a little bit better than GL_RGB5_A1 and slower on most cards)

gl_drawskys

If 0, disables drawing skies, which may be needed with some problematic 3D cards.

gl_sortsprites

Experimental option, possibly faster but less reliable.

## MOUSE SETTINGS
This section specifies settings for using a mouse with PrBoom. There are several settings that control button bindings (what action each button causes in the game); these are easiest set from the in-game menus, these config entries are to preserve the settings between games.

use_mouse

Enable or disable the use of a mouse with PrBoom.

mouse_sensitivity_horiz, mouse_sensitivity_vert

Sets the sensitivity of the mouse in PrBoom. Easier set from the in-game menus.

## KEY BINDINGS
These specify the keys that trigger various actions in PrBoom. The codes used for keys are internal to PrBoom, though many keys are represented by their ASCII codes. It is easiest to modify these via the in-game menus (OPTIONS->SETUP->KEY BINDINGS). These config file entries preserve the settings from this menu between game sessions.

## JOYSTICK SETTINGS
There are the trigger variables here, which are calculated during joystick calibration (the values received from the kernel driver outside of which movement is caused in the game). Also there are the button-bindings, again best adjusted using the in-game menus.

use_joystick

This selects the number of the joystick to use, or 0 selects no joystick. You have to have the relevant device files (/dev/js0 etc) and the kernel driver loaded.

## CHAT MACROS
These are pre-written text strings for quick transmission to players in a network game (consult your Doom documentation). Easiest set via the in-game menus (OPTIONS->SETUP->CHAT MACROS).

## AUTOMAP SETTINGS
These are settings related to the automap. These are easiest set from within the game.

## HEADS_UP DISPLAY SETTINGS
These are settings related to the heads-up display, that is messages received while playing and the heads-up display of your current status obtained by pressing + while the view is full-screen in PrBoom. See the Boom documentation for details. All controlled best from within the game.

## WEAPON PREFERENCES
Here are the settings from the Weapons menu in the game (OPTIONS->SETUP->WEAPONS).

## ALSO SEE
prboom(6), PrBoom's documentation (including the Boom and MBF documentation) and your Doom documentation.

## AUTHOR
See the file AUTHORS included with PrBoom for a list of contributors to PrBoom. This config file reference written by Colin Phipps (cph@moria.org.uk).