321 lines
18 KiB
HTML
321 lines
18 KiB
HTML
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
|
|
"https://www.w3.org/TR/html4/loose.dtd">
|
|
<html> <head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<link rel='stylesheet' type='text/css' href='postfix-doc.css'>
|
|
<title> Postfix manual - postmap(1) </title>
|
|
</head> <body> <pre>
|
|
POSTMAP(1) POSTMAP(1)
|
|
|
|
<b><a name="name">NAME</a></b>
|
|
postmap - Postfix lookup table management
|
|
|
|
<b><a name="synopsis">SYNOPSIS</a></b>
|
|
<b>postmap</b> [<b>-bfFhimnNoprsuUvw</b>] [<b>-c</b> <i>config</i><b>_</b><i>dir</i>] [<b>-d</b> <i>key</i>] [<b>-q</b> <i>key</i>]
|
|
[<i>file</i><b>_</b><i>type</i>:]<i>file</i><b>_</b><i>name</i> ...
|
|
|
|
<b><a name="description">DESCRIPTION</a></b>
|
|
The <a href="postmap.1.html"><b>postmap</b>(1)</a> 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.
|
|
|
|
<b><a name="input_file_format">INPUT FILE FORMAT</a></b>
|
|
The format of a lookup table input file is as follows:
|
|
|
|
<b>o</b> A table entry has the form
|
|
|
|
<i>key</i> whitespace <i>value</i>
|
|
|
|
<b>o</b> Empty lines and whitespace-only lines are ignored, as are lines
|
|
whose first non-whitespace character is a `#'.
|
|
|
|
<b>o</b> A logical line starts with non-whitespace text. A line that
|
|
starts with whitespace continues a logical line.
|
|
|
|
The <i>key</i> and <i>value</i> are processed as is, except that surrounding white
|
|
space is stripped off. Whitespace in lookup keys is supported in Post-
|
|
fix 3.2 and later, by surrounding the key with double quote characters
|
|
`"'. Within the double quotes, double quote `"' and backslash `\' char-
|
|
acters can be included by quoting them with a preceding backslash.
|
|
|
|
When the <b>-F</b> option is given, the <i>value</i> must specify one or more file-
|
|
names separated by comma and/or whitespace; <a href="postmap.1.html"><b>postmap</b>(1)</a> will concatenate
|
|
the file content (with a newline character inserted between files) and
|
|
will store the base64-encoded result instead of the <i>value</i>.
|
|
|
|
When the <i>key</i> specifies email address information, the localpart should
|
|
be enclosed with double quotes if required by <a href="https://tools.ietf.org/html/rfc5322">RFC 5322</a>. 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 <a href="DATABASE_README.html#types">btree</a>:, <a href="DATABASE_README.html#types">dbm</a>: or
|
|
<a href="DATABASE_README.html#types">hash</a>:. 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
|
|
<a href="regexp_table.5.html">regexp</a>: and <a href="pcre_table.5.html">pcre</a>:. This resulted in loss of information with $<i>number</i>
|
|
substitutions.
|
|
|
|
<b><a name="command-line_arguments">COMMAND-LINE ARGUMENTS</a></b>
|
|
<b>-b</b> Enable message body query mode. When reading lookup keys from
|
|
standard input with "<b>-q -</b>", process the input as if it is an
|
|
email message in <a href="https://tools.ietf.org/html/rfc5322">RFC 5322</a> format. Each line of body content
|
|
becomes one lookup key.
|
|
|
|
By default, the <b>-b</b> option starts generating lookup keys at the
|
|
first non-header line, and stops when the end of the message is
|
|
reached. To simulate <a href="header_checks.5.html"><b>body_checks</b>(5)</a> processing, enable MIME
|
|
parsing with <b>-m</b>. With this, the <b>-b</b> option generates no
|
|
body-style lookup keys for attachment MIME headers and for
|
|
attached message/* headers.
|
|
|
|
NOTE: with "<a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> = yes", the <b>-b</b> option disables UTF-8
|
|
syntax checks on query keys and lookup results. Specify the <b>-U</b>
|
|
option to force UTF-8 syntax checks anyway.
|
|
|
|
This feature is available in Postfix version 2.6 and later.
|
|
|
|
<b>-c</b> <i>config</i><b>_</b><i>dir</i>
|
|
Read the <a href="postconf.5.html"><b>main.cf</b></a> configuration file in the named directory
|
|
instead of the default configuration directory.
|
|
|
|
<b>-d</b> <i>key</i> Search the specified maps for <i>key</i> and remove one entry per map.
|
|
The exit status is zero when the requested information was
|
|
found.
|
|
|
|
If a key value of <b>-</b> 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.
|
|
|
|
<b>-f</b> 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.
|
|
|
|
<b>-F</b> 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).
|
|
|
|
This feature is available in Postfix version 3.4 and later.
|
|
|
|
<b>-h</b> Enable message header query mode. When reading lookup keys from
|
|
standard input with "<b>-q -</b>", process the input as if it is an
|
|
email message in <a href="https://tools.ietf.org/html/rfc5322">RFC 5322</a> format. Each logical header line
|
|
becomes one lookup key. A multi-line header becomes one lookup
|
|
key with one or more embedded newline characters.
|
|
|
|
By default, the <b>-h</b> option generates lookup keys until the first
|
|
non-header line is reached. To simulate <a href="header_checks.5.html"><b>header_checks</b>(5)</a> pro-
|
|
cessing, enable MIME parsing with <b>-m</b>. With this, the <b>-h</b> option
|
|
also generates header-style lookup keys for attachment MIME
|
|
headers and for attached message/* headers.
|
|
|
|
NOTE: with "<a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> = yes", the <b>-b</b> option option dis-
|
|
ables UTF-8 syntax checks on query keys and lookup results.
|
|
Specify the <b>-U</b> option to force UTF-8 syntax checks anyway.
|
|
|
|
This feature is available in Postfix version 2.6 and later.
|
|
|
|
<b>-i</b> Incremental mode. Read entries from standard input and do not
|
|
truncate an existing database. By default, <a href="postmap.1.html"><b>postmap</b>(1)</a> creates a
|
|
new database from the entries in <b>file_name</b>.
|
|
|
|
<b>-m</b> Enable MIME parsing with "<b>-b</b>" and "<b>-h</b>".
|
|
|
|
This feature is available in Postfix version 2.6 and later.
|
|
|
|
<b>-N</b> Include the terminating null character that terminates lookup
|
|
keys and values. By default, <a href="postmap.1.html"><b>postmap</b>(1)</a> does whatever is the
|
|
default for the host operating system.
|
|
|
|
<b>-n</b> Don't include the terminating null character that terminates
|
|
lookup keys and values. By default, <a href="postmap.1.html"><b>postmap</b>(1)</a> does whatever is
|
|
the default for the host operating system.
|
|
|
|
<b>-o</b> Do not release root privileges when processing a non-root input
|
|
file. By default, <a href="postmap.1.html"><b>postmap</b>(1)</a> drops root privileges and runs as
|
|
the source file owner instead.
|
|
|
|
<b>-p</b> 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).
|
|
|
|
<b>-q</b> <i>key</i> Search the specified maps for <i>key</i> 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 <a href="access.5.html">access(5)</a>, <a href="canonical.5.html">canonical(5)</a>, <a href="transport.5.html">transport(5)</a>, <a href="virtual.5.html">vir-</a>
|
|
<a href="virtual.5.html">tual(5)</a> and other Postfix table-driven features.
|
|
|
|
If a key value of <b>-</b> is specified, the program reads key values
|
|
from the standard input stream and writes one line of <i>key value</i>
|
|
output for each key that was found. The exit status is zero when
|
|
at least one of the requested keys was found.
|
|
|
|
<b>-r</b> When updating a table, do not complain about attempts to update
|
|
existing entries, and make those updates anyway.
|
|
|
|
<b>-s</b> Retrieve all database elements, and write one line of <i>key value</i>
|
|
output for each element. The elements are printed in database
|
|
order, which is not necessarily the same as the original input
|
|
order.
|
|
|
|
This feature is available in Postfix version 2.2 and later, and
|
|
is not available for all database types.
|
|
|
|
<b>-u</b> Disable UTF-8 support. UTF-8 support is enabled by default when
|
|
"<a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> = yes". It requires that keys and values are
|
|
valid UTF-8 strings.
|
|
|
|
<b>-U</b> With "<a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> = yes", force UTF-8 syntax checks with the
|
|
<b>-b</b> and <b>-h</b> options.
|
|
|
|
<b>-v</b> Enable verbose logging for debugging purposes. Multiple <b>-v</b>
|
|
options make the software increasingly verbose.
|
|
|
|
<b>-w</b> When updating a table, do not complain about attempts to update
|
|
existing entries, and ignore those attempts.
|
|
|
|
Arguments:
|
|
|
|
<i>file</i><b>_</b><i>type</i>
|
|
The database type. To find out what types are supported, use the
|
|
"<b>postconf -m</b>" command.
|
|
|
|
The <a href="postmap.1.html"><b>postmap</b>(1)</a> command can query any supported file type, but it
|
|
can create only the following file types:
|
|
|
|
<b>btree</b> The output file is a btree file, named <i>file</i><b>_</b><i>name</i><b>.db</b>.
|
|
This is available on systems with support for <b>db</b> data-
|
|
bases.
|
|
|
|
<b>cdb</b> The output consists of one file, named <i>file</i><b>_</b><i>name</i><b>.cdb</b>.
|
|
This is available on systems with support for <b>cdb</b> data-
|
|
bases.
|
|
|
|
<b>dbm</b> The output consists of two files, named <i>file</i><b>_</b><i>name</i><b>.pag</b> and
|
|
<i>file</i><b>_</b><i>name</i><b>.dir</b>. This is available on systems with support
|
|
for <b>dbm</b> databases.
|
|
|
|
<b>fail</b> A table that reliably fails all requests. The lookup ta-
|
|
ble name is used for logging only. This table exists to
|
|
simplify Postfix error tests.
|
|
|
|
<b>hash</b> The output file is a hashed file, named <i>file</i><b>_</b><i>name</i><b>.db</b>.
|
|
This is available on systems with support for <b>db</b> data-
|
|
bases.
|
|
|
|
<b>lmdb</b> The output is a btree-based file, named <i>file</i><b>_</b><i>name</i><b>.lmdb</b>.
|
|
<b>lmdb</b> supports concurrent writes and reads from different
|
|
processes, unlike other supported file-based tables.
|
|
This is available on systems with support for <b>lmdb</b> data-
|
|
bases.
|
|
|
|
<b>sdbm</b> The output consists of two files, named <i>file</i><b>_</b><i>name</i><b>.pag</b> and
|
|
<i>file</i><b>_</b><i>name</i><b>.dir</b>. This is available on systems with support
|
|
for <b>sdbm</b> databases.
|
|
|
|
When no <i>file</i><b>_</b><i>type</i> is specified, the software uses the database
|
|
type specified via the <b><a href="postconf.5.html#default_database_type">default_database_type</a></b> configuration
|
|
parameter.
|
|
|
|
<i>file</i><b>_</b><i>name</i>
|
|
The name of the lookup table source file when rebuilding a data-
|
|
base.
|
|
|
|
<b><a name="diagnostics">DIAGNOSTICS</a></b>
|
|
Problems are logged to the standard error stream and to <b>syslogd</b>(8) or
|
|
<a href="postlogd.8.html"><b>postlogd</b>(8)</a>. No output means that no problems were detected. Duplicate
|
|
entries are skipped and are flagged with a warning.
|
|
|
|
<a href="postmap.1.html"><b>postmap</b>(1)</a> terminates with zero exit status in case of success (includ-
|
|
ing successful "<b>postmap -q</b>" lookup) and terminates with non-zero exit
|
|
status in case of failure.
|
|
|
|
<b><a name="environment">ENVIRONMENT</a></b>
|
|
<b>MAIL_CONFIG</b>
|
|
Directory with Postfix configuration files.
|
|
|
|
<b>MAIL_VERBOSE</b>
|
|
Enable verbose logging for debugging purposes.
|
|
|
|
<b><a name="configuration_parameters">CONFIGURATION PARAMETERS</a></b>
|
|
The following <a href="postconf.5.html"><b>main.cf</b></a> parameters are especially relevant to this pro-
|
|
gram. The text below provides only a parameter summary. See <a href="postconf.5.html"><b>post-</b></a>
|
|
<a href="postconf.5.html"><b>conf</b>(5)</a> for more details including examples.
|
|
|
|
<b><a href="postconf.5.html#berkeley_db_create_buffer_size">berkeley_db_create_buffer_size</a> (16777216)</b>
|
|
The per-table I/O buffer size for programs that create Berkeley
|
|
DB hash or btree tables.
|
|
|
|
<b><a href="postconf.5.html#berkeley_db_read_buffer_size">berkeley_db_read_buffer_size</a> (131072)</b>
|
|
The per-table I/O buffer size for programs that read Berkeley DB
|
|
hash or btree tables.
|
|
|
|
<b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
|
|
The default location of the Postfix <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> con-
|
|
figuration files.
|
|
|
|
<b><a href="postconf.5.html#default_database_type">default_database_type</a> (see 'postconf -d' output)</b>
|
|
The default database type for use in <a href="newaliases.1.html"><b>newaliases</b>(1)</a>, <a href="postalias.1.html"><b>postalias</b>(1)</a>
|
|
and <a href="postmap.1.html"><b>postmap</b>(1)</a> commands.
|
|
|
|
<b><a href="postconf.5.html#import_environment">import_environment</a> (see 'postconf -d' output)</b>
|
|
The list of environment variables that a privileged Postfix
|
|
process will import from a non-Postfix parent process, or
|
|
name=value environment overrides.
|
|
|
|
<b><a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> (yes)</b>
|
|
Enable preliminary SMTPUTF8 support for the protocols described
|
|
in <a href="https://tools.ietf.org/html/rfc6531">RFC 6531</a>, <a href="https://tools.ietf.org/html/rfc6532">RFC 6532</a>, and <a href="https://tools.ietf.org/html/rfc6533">RFC 6533</a>.
|
|
|
|
<b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b>
|
|
The syslog facility of Postfix logging.
|
|
|
|
<b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b>
|
|
A prefix that is prepended to the process name in syslog
|
|
records, so that, for example, "smtpd" becomes "prefix/smtpd".
|
|
|
|
Available in Postfix 2.11 and later:
|
|
|
|
<b><a href="postconf.5.html#lmdb_map_size">lmdb_map_size</a> (16777216)</b>
|
|
The initial OpenLDAP LMDB database size limit in bytes.
|
|
|
|
<b><a name="see_also">SEE ALSO</a></b>
|
|
<a href="postalias.1.html">postalias(1)</a>, create/update/query alias database
|
|
<a href="postconf.1.html">postconf(1)</a>, supported database types
|
|
<a href="postconf.5.html">postconf(5)</a>, configuration parameters
|
|
<a href="postlogd.8.html">postlogd(8)</a>, Postfix logging
|
|
syslogd(8), system logging
|
|
|
|
<b><a name="readme_files">README FILES</a></b>
|
|
<a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview
|
|
|
|
<b><a name="license">LICENSE</a></b>
|
|
The Secure Mailer license must be distributed with this software.
|
|
|
|
<b>AUTHOR(S)</b>
|
|
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
|
|
|
|
POSTMAP(1)
|
|
</pre> </body> </html>
|