diff options
Diffstat (limited to 'man/man1/postmap.1')
| -rw-r--r-- | man/man1/postmap.1 | 343 |
1 files changed, 343 insertions, 0 deletions
diff --git a/man/man1/postmap.1 b/man/man1/postmap.1 new file mode 100644 index 0000000..d2551e5 --- /dev/null +++ b/man/man1/postmap.1 @@ -0,0 +1,343 @@ +.TH POSTMAP 1 +.ad +.fi +.SH NAME +postmap +\- +Postfix lookup table management +.SH "SYNOPSIS" +.na +.nf +.fi +\fBpostmap\fR [\fB\-bfFhimnNoprsuUvw\fR] [\fB\-c \fIconfig_dir\fR] +[\fB\-d \fIkey\fR] [\fB\-q \fIkey\fR] + [\fIfile_type\fR:]\fIfile_name\fR ... +.SH DESCRIPTION +.ad +.fi +The \fBpostmap\fR(1) command creates or queries one or more Postfix +lookup tables, or updates an existing one. + +If the result files do not exist they will be created with the +same group and other read permissions as their source file. + +While the table update is in progress, signal delivery is +postponed, and an exclusive, advisory, lock is placed on the +entire table, in order to avoid surprises in spectator +processes. +.SH "INPUT FILE FORMAT" +.na +.nf +.ad +.fi +The format of a lookup table input file is as follows: +.IP \(bu +A table entry has the form +.sp +.nf + \fIkey\fR whitespace \fIvalue\fR +.fi +.IP \(bu +Empty lines and whitespace\-only lines are ignored, as +are lines whose first non\-whitespace character is a `#'. +.IP \(bu +A logical line starts with non\-whitespace text. A line that +starts with whitespace continues a logical line. +.PP +The \fIkey\fR and \fIvalue\fR are processed as is, except that +surrounding white space is stripped off. Whitespace in lookup +keys is supported in Postfix 3.2 and later, by surrounding the +key with double quote characters `"'. Within the double quotes, +double quote `"' and backslash `\\' characters can be included +by quoting them with a preceding backslash. + +When the \fB\-F\fR option is given, the \fIvalue\fR must +specify one or more filenames separated by comma and/or +whitespace; \fBpostmap\fR(1) will concatenate the file +content (with a newline character inserted between files) +and will store the base64\-encoded result instead of the +\fIvalue\fR. + +When the \fIkey\fR specifies email address information, the +localpart should be enclosed with double quotes if required +by RFC 5322. For example, an address localpart that contains +";", or a localpart that starts or ends with ".". + +By default the lookup key is mapped to lowercase to make +the lookups case insensitive; as of Postfix 2.3 this case +folding happens only with tables whose lookup keys are +fixed\-case strings such as btree:, dbm: or hash:. With +earlier versions, the lookup key is folded even with tables +where a lookup field can match both upper and lower case +text, such as regexp: and pcre:. This resulted in loss of +information with $\fInumber\fR substitutions. +.SH "COMMAND-LINE ARGUMENTS" +.na +.nf +.ad +.fi +.IP \fB\-b\fR +Enable message body query mode. When reading lookup keys +from standard input with "\fB\-q \-\fR", process the input +as if it is an email message in RFC 5322 format. Each line +of body content becomes one lookup key. +.sp +By default, the \fB\-b\fR option starts generating lookup +keys at the first non\-header line, and stops when the end +of the message is reached. +To simulate \fBbody_checks\fR(5) processing, enable MIME +parsing with \fB\-m\fR. With this, the \fB\-b\fR option +generates no body\-style lookup keys for attachment MIME +headers and for attached message/* headers. +.sp +NOTE: with "smtputf8_enable = yes", the \fB\-b\fR option +disables UTF\-8 syntax checks on query keys and lookup +results. Specify the \fB\-U\fR option to force UTF\-8 +syntax checks anyway. +.sp +This feature is available in Postfix version 2.6 and later. +.IP "\fB\-c \fIconfig_dir\fR" +Read the \fBmain.cf\fR configuration file in the named directory +instead of the default configuration directory. +.IP "\fB\-d \fIkey\fR" +Search the specified maps for \fIkey\fR and remove one entry per map. +The exit status is zero when the requested information was found. + +If a key value of \fB\-\fR is specified, the program reads key +values from the standard input stream. The exit status is zero +when at least one of the requested keys was found. +.IP \fB\-f\fR +Do not fold the lookup key to lower case while creating or querying +a table. + +With Postfix version 2.3 and later, this option has no +effect for regular expression tables. There, case folding +is controlled by appending a flag to a pattern. +.IP \fB\-F\fR +When querying a map, or listing a map, base64\-decode each +value. When creating a map from source file, process each +value as a list of filenames, concatenate the content of +those files, and store the base64\-encoded result instead +of the value (see INPUT FILE FORMAT for details). +.sp +This feature is available in Postfix version 3.4 and later. +.IP \fB\-h\fR +Enable message header query mode. When reading lookup keys +from standard input with "\fB\-q \-\fR", process the input +as if it is an email message in RFC 5322 format. Each +logical header line becomes one lookup key. A multi\-line +header becomes one lookup key with one or more embedded +newline characters. +.sp +By default, the \fB\-h\fR option generates lookup keys until +the first non\-header line is reached. +To simulate \fBheader_checks\fR(5) processing, enable MIME +parsing with \fB\-m\fR. With this, the \fB\-h\fR option also +generates header\-style lookup keys for attachment MIME +headers and for attached message/* headers. +.sp +NOTE: with "smtputf8_enable = yes", the \fB\-b\fR option +option disables UTF\-8 syntax checks on query keys and +lookup results. Specify the \fB\-U\fR option to force UTF\-8 +syntax checks anyway. +.sp +This feature is available in Postfix version 2.6 and later. +.IP \fB\-i\fR +Incremental mode. Read entries from standard input and do not +truncate an existing database. By default, \fBpostmap\fR(1) creates +a new database from the entries in \fBfile_name\fR. +.IP \fB\-m\fR +Enable MIME parsing with "\fB\-b\fR" and "\fB\-h\fR". +.sp +This feature is available in Postfix version 2.6 and later. +.IP \fB\-N\fR +Include the terminating null character that terminates lookup keys +and values. By default, \fBpostmap\fR(1) does whatever is +the default for +the host operating system. +.IP \fB\-n\fR +Don't include the terminating null character that terminates lookup +keys and values. By default, \fBpostmap\fR(1) does whatever +is the default for +the host operating system. +.IP \fB\-o\fR +Do not release root privileges when processing a non\-root +input file. By default, \fBpostmap\fR(1) drops root privileges +and runs as the source file owner instead. +.IP \fB\-p\fR +Do not inherit the file access permissions from the input file +when creating a new file. Instead, create a new file with default +access permissions (mode 0644). +.IP "\fB\-q \fIkey\fR" +Search the specified maps for \fIkey\fR and write the first value +found to the standard output stream. The exit status is zero +when the requested information was found. + +Note: this performs a single query with the key as specified, +and does not make iterative queries with substrings of the +key as described for access(5), canonical(5), transport(5), +virtual(5) and other Postfix table\-driven features. + +If a key value of \fB\-\fR is specified, the program reads key +values from the standard input stream and writes one line of +\fIkey value\fR output for each key that was found. The exit +status is zero when at least one of the requested keys was found. +.IP \fB\-r\fR +When updating a table, do not complain about attempts to update +existing entries, and make those updates anyway. +.IP \fB\-s\fR +Retrieve all database elements, and write one line of +\fIkey value\fR output for each element. The elements are +printed in database order, which is not necessarily the same +as the original input order. +.sp +This feature is available in Postfix version 2.2 and later, +and is not available for all database types. +.IP \fB\-u\fR +Disable UTF\-8 support. UTF\-8 support is enabled by default +when "smtputf8_enable = yes". It requires that keys and +values are valid UTF\-8 strings. +.IP \fB\-U\fR +With "smtputf8_enable = yes", force UTF\-8 syntax checks +with the \fB\-b\fR and \fB\-h\fR options. +.IP \fB\-v\fR +Enable verbose logging for debugging purposes. Multiple \fB\-v\fR +options make the software increasingly verbose. +.IP \fB\-w\fR +When updating a table, do not complain about attempts to update +existing entries, and ignore those attempts. +.PP +Arguments: +.IP \fIfile_type\fR +The database type. To find out what types are supported, use +the "\fBpostconf \-m\fR" command. + +The \fBpostmap\fR(1) command can query any supported file type, +but it can create only the following file types: +.RS +.IP \fBbtree\fR +The output file is a btree file, named \fIfile_name\fB.db\fR. +This is available on systems with support for \fBdb\fR databases. +.IP \fBcdb\fR +The output consists of one file, named \fIfile_name\fB.cdb\fR. +This is available on systems with support for \fBcdb\fR databases. +.IP \fBdbm\fR +The output consists of two files, named \fIfile_name\fB.pag\fR and +\fIfile_name\fB.dir\fR. +This is available on systems with support for \fBdbm\fR databases. +.IP \fBfail\fR +A table that reliably fails all requests. The lookup table +name is used for logging only. This table exists to simplify +Postfix error tests. +.IP \fBhash\fR +The output file is a hashed file, named \fIfile_name\fB.db\fR. +This is available on systems with support for \fBdb\fR databases. +.IP \fBlmdb\fR +The output is a btree\-based file, named \fIfile_name\fB.lmdb\fR. +\fBlmdb\fR supports concurrent writes and reads from different +processes, unlike other supported file\-based tables. +This is available on systems with support for \fBlmdb\fR databases. +.IP \fBsdbm\fR +The output consists of two files, named \fIfile_name\fB.pag\fR and +\fIfile_name\fB.dir\fR. +This is available on systems with support for \fBsdbm\fR databases. +.PP +When no \fIfile_type\fR is specified, the software uses the database +type specified via the \fBdefault_database_type\fR configuration +parameter. +.RE +.IP \fIfile_name\fR +The name of the lookup table source file when rebuilding a database. +.SH DIAGNOSTICS +.ad +.fi +Problems are logged to the standard error stream and to +\fBsyslogd\fR(8) or \fBpostlogd\fR(8). +No output means that no problems were detected. Duplicate entries are +skipped and are flagged with a warning. + +\fBpostmap\fR(1) terminates with zero exit status in case of success +(including successful "\fBpostmap \-q\fR" lookup) and terminates +with non\-zero exit status in case of failure. +.SH "ENVIRONMENT" +.na +.nf +.ad +.fi +.IP \fBMAIL_CONFIG\fR +Directory with Postfix configuration files. +.IP \fBMAIL_VERBOSE\fR +Enable verbose logging for debugging purposes. +.SH "CONFIGURATION PARAMETERS" +.na +.nf +.ad +.fi +The following \fBmain.cf\fR parameters are especially relevant to +this program. +The text below provides only a parameter summary. See +\fBpostconf\fR(5) for more details including examples. +.IP "\fBberkeley_db_create_buffer_size (16777216)\fR" +The per\-table I/O buffer size for programs that create Berkeley DB +hash or btree tables. +.IP "\fBberkeley_db_read_buffer_size (131072)\fR" +The per\-table I/O buffer size for programs that read Berkeley DB +hash or btree tables. +.IP "\fBconfig_directory (see 'postconf -d' output)\fR" +The default location of the Postfix main.cf and master.cf +configuration files. +.IP "\fBdefault_database_type (see 'postconf -d' output)\fR" +The default database type for use in \fBnewaliases\fR(1), \fBpostalias\fR(1) +and \fBpostmap\fR(1) commands. +.IP "\fBimport_environment (see 'postconf -d' output)\fR" +The list of environment variables that a privileged Postfix +process will import from a non\-Postfix parent process, or name=value +environment overrides. +.IP "\fBsmtputf8_enable (yes)\fR" +Enable preliminary SMTPUTF8 support for the protocols described +in RFC 6531, RFC 6532, and RFC 6533. +.IP "\fBsyslog_facility (mail)\fR" +The syslog facility of Postfix logging. +.IP "\fBsyslog_name (see 'postconf -d' output)\fR" +A prefix that is prepended to the process name in syslog +records, so that, for example, "smtpd" becomes "prefix/smtpd". +.PP +Available in Postfix 2.11 and later: +.IP "\fBlmdb_map_size (16777216)\fR" +The initial OpenLDAP LMDB database size limit in bytes. +.SH "SEE ALSO" +.na +.nf +postalias(1), create/update/query alias database +postconf(1), supported database types +postconf(5), configuration parameters +postlogd(8), Postfix logging +syslogd(8), system logging +.SH "README FILES" +.na +.nf +.ad +.fi +Use "\fBpostconf readme_directory\fR" or +"\fBpostconf html_directory\fR" to locate this information. +.na +.nf +DATABASE_README, Postfix lookup table overview +.SH "LICENSE" +.na +.nf +.ad +.fi +The Secure Mailer license must be distributed with this software. +.SH "AUTHOR(S)" +.na +.nf +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 |