1<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 "http://www.w3.org/TR/html4/loose.dtd"> 3<html> <head> 4<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 5<link rel='stylesheet' type='text/css' href='postfix-doc.css'> 6<title> Postfix manual - postmap(1) </title> 7</head> <body> <pre> 8POSTMAP(1) POSTMAP(1) 9 10<b>NAME</b> 11 postmap - Postfix lookup table management 12 13<b>SYNOPSIS</b> 14 <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>] 15 [<i>file</i><b>_</b><i>type</i>:]<i>file</i><b>_</b><i>name</i> ... 16 17<b>DESCRIPTION</b> 18 The <a href="postmap.1.html"><b>postmap</b>(1)</a> command creates or queries one or more Postfix lookup 19 tables, or updates an existing one. 20 21 If the result files do not exist they will be created with the same 22 group and other read permissions as their source file. 23 24 While the table update is in progress, signal delivery is postponed, 25 and an exclusive, advisory, lock is placed on the entire table, in 26 order to avoid surprises in spectator processes. 27 28<b>INPUT FILE FORMAT</b> 29 The format of a lookup table input file is as follows: 30 31 <b>o</b> A table entry has the form 32 33 <i>key</i> whitespace <i>value</i> 34 35 <b>o</b> Empty lines and whitespace-only lines are ignored, as are lines 36 whose first non-whitespace character is a `#'. 37 38 <b>o</b> A logical line starts with non-whitespace text. A line that 39 starts with whitespace continues a logical line. 40 41 The <i>key</i> and <i>value</i> are processed as is, except that surrounding white 42 space is stripped off. Whitespace in lookup keys is supported in Post- 43 fix 3.2 and later, by surrounding the key with double quote characters 44 `"'. Within the double quotes, double quote `"' and backslash `\' char- 45 acters can be included by quoting them with a preceding backslash. 46 47 When the <b>-F</b> option is given, the <i>value</i> must specify one or more file- 48 names separated by comma and/or whitespace; <a href="postmap.1.html"><b>postmap</b>(1)</a> will concatenate 49 the file content (with a newline character inserted between files) and 50 will store the base64-encoded result instead of the <i>value</i>. 51 52 When the <i>key</i> specifies email address information, the localpart should 53 be enclosed with double quotes if required by <a href="https://tools.ietf.org/html/rfc5322">RFC 5322</a>. For example, an 54 address localpart that contains ";", or a localpart that starts or ends 55 with ".". 56 57 By default the lookup key is mapped to lowercase to make the lookups 58 case insensitive; as of Postfix 2.3 this case folding happens only with 59 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 60 <a href="DATABASE_README.html#types">hash</a>:. With earlier versions, the lookup key is folded even with tables 61 where a lookup field can match both upper and lower case text, such as 62 <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> 63 substitutions. 64 65<b>COMMAND-LINE ARGUMENTS</b> 66 <b>-b</b> Enable message body query mode. When reading lookup keys from 67 standard input with "<b>-q -</b>", process the input as if it is an 68 email message in <a href="https://tools.ietf.org/html/rfc5322">RFC 5322</a> format. Each line of body content 69 becomes one lookup key. 70 71 By default, the <b>-b</b> option starts generating lookup keys at the 72 first non-header line, and stops when the end of the message is 73 reached. To simulate <a href="header_checks.5.html"><b>body_checks</b>(5)</a> processing, enable MIME 74 parsing with <b>-m</b>. With this, the <b>-b</b> option generates no 75 body-style lookup keys for attachment MIME headers and for 76 attached message/* headers. 77 78 NOTE: with "<a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> = yes", the <b>-b</b> option disables UTF-8 79 syntax checks on query keys and lookup results. Specify the <b>-U</b> 80 option to force UTF-8 syntax checks anyway. 81 82 This feature is available in Postfix version 2.6 and later. 83 84 <b>-c</b> <i>config</i><b>_</b><i>dir</i> 85 Read the <a href="postconf.5.html"><b>main.cf</b></a> configuration file in the named directory 86 instead of the default configuration directory. 87 88 <b>-d</b> <i>key</i> Search the specified maps for <i>key</i> and remove one entry per map. 89 The exit status is zero when the requested information was 90 found. 91 92 If a key value of <b>-</b> is specified, the program reads key values 93 from the standard input stream. The exit status is zero when at 94 least one of the requested keys was found. 95 96 <b>-f</b> Do not fold the lookup key to lower case while creating or 97 querying a table. 98 99 With Postfix version 2.3 and later, this option has no effect 100 for regular expression tables. There, case folding is controlled 101 by appending a flag to a pattern. 102 103 <b>-F</b> When querying a map, or listing a map, base64-decode each value. 104 When creating a map from source file, process each value as a 105 list of filenames, concatenate the content of those files, and 106 store the base64-encoded result instead of the value (see INPUT 107 FILE FORMAT for details). 108 109 This feature is available in Postfix version 3.4 and later. 110 111 <b>-h</b> Enable message header query mode. When reading lookup keys from 112 standard input with "<b>-q -</b>", process the input as if it is an 113 email message in <a href="https://tools.ietf.org/html/rfc5322">RFC 5322</a> format. Each logical header line 114 becomes one lookup key. A multi-line header becomes one lookup 115 key with one or more embedded newline characters. 116 117 By default, the <b>-h</b> option generates lookup keys until the first 118 non-header line is reached. To simulate <a href="header_checks.5.html"><b>header_checks</b>(5)</a> pro- 119 cessing, enable MIME parsing with <b>-m</b>. With this, the <b>-h</b> option 120 also generates header-style lookup keys for attachment MIME 121 headers and for attached message/* headers. 122 123 NOTE: with "<a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> = yes", the <b>-b</b> option option dis- 124 ables UTF-8 syntax checks on query keys and lookup results. 125 Specify the <b>-U</b> option to force UTF-8 syntax checks anyway. 126 127 This feature is available in Postfix version 2.6 and later. 128 129 <b>-i</b> Incremental mode. Read entries from standard input and do not 130 truncate an existing database. By default, <a href="postmap.1.html"><b>postmap</b>(1)</a> creates a 131 new database from the entries in <b>file_name</b>. 132 133 <b>-m</b> Enable MIME parsing with "<b>-b</b>" and "<b>-h</b>". 134 135 This feature is available in Postfix version 2.6 and later. 136 137 <b>-N</b> Include the terminating null character that terminates lookup 138 keys and values. By default, <a href="postmap.1.html"><b>postmap</b>(1)</a> does whatever is the 139 default for the host operating system. 140 141 <b>-n</b> Don't include the terminating null character that terminates 142 lookup keys and values. By default, <a href="postmap.1.html"><b>postmap</b>(1)</a> does whatever is 143 the default for the host operating system. 144 145 <b>-o</b> Do not release root privileges when processing a non-root input 146 file. By default, <a href="postmap.1.html"><b>postmap</b>(1)</a> drops root privileges and runs as 147 the source file owner instead. 148 149 <b>-p</b> Do not inherit the file access permissions from the input file 150 when creating a new file. Instead, create a new file with 151 default access permissions (mode 0644). 152 153 <b>-q</b> <i>key</i> Search the specified maps for <i>key</i> and write the first value 154 found to the standard output stream. The exit status is zero 155 when the requested information was found. 156 157 Note: this performs a single query with the key as specified, 158 and does not make iterative queries with substrings of the key 159 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> 160 <a href="virtual.5.html">tual(5)</a> and other Postfix table-driven features. 161 162 If a key value of <b>-</b> is specified, the program reads key values 163 from the standard input stream and writes one line of <i>key value</i> 164 output for each key that was found. The exit status is zero when 165 at least one of the requested keys was found. 166 167 <b>-r</b> When updating a table, do not complain about attempts to update 168 existing entries, and make those updates anyway. 169 170 <b>-s</b> Retrieve all database elements, and write one line of <i>key value</i> 171 output for each element. The elements are printed in database 172 order, which is not necessarily the same as the original input 173 order. 174 175 This feature is available in Postfix version 2.2 and later, and 176 is not available for all database types. 177 178 <b>-u</b> Disable UTF-8 support. UTF-8 support is enabled by default when 179 "<a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> = yes". It requires that keys and values are 180 valid UTF-8 strings. 181 182 <b>-U</b> With "<a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> = yes", force UTF-8 syntax checks with the 183 <b>-b</b> and <b>-h</b> options. 184 185 <b>-v</b> Enable verbose logging for debugging purposes. Multiple <b>-v</b> 186 options make the software increasingly verbose. 187 188 <b>-w</b> When updating a table, do not complain about attempts to update 189 existing entries, and ignore those attempts. 190 191 Arguments: 192 193 <i>file</i><b>_</b><i>type</i> 194 The database type. To find out what types are supported, use the 195 "<b>postconf -m</b>" command. 196 197 The <a href="postmap.1.html"><b>postmap</b>(1)</a> command can query any supported file type, but it 198 can create only the following file types: 199 200 <b>btree</b> The output file is a btree file, named <i>file</i><b>_</b><i>name</i><b>.db</b>. 201 This is available on systems with support for <b>db</b> data- 202 bases. 203 204 <b>cdb</b> The output consists of one file, named <i>file</i><b>_</b><i>name</i><b>.cdb</b>. 205 This is available on systems with support for <b>cdb</b> data- 206 bases. 207 208 <b>dbm</b> The output consists of two files, named <i>file</i><b>_</b><i>name</i><b>.pag</b> and 209 <i>file</i><b>_</b><i>name</i><b>.dir</b>. This is available on systems with support 210 for <b>dbm</b> databases. 211 212 <b>fail</b> A table that reliably fails all requests. The lookup ta- 213 ble name is used for logging only. This table exists to 214 simplify Postfix error tests. 215 216 <b>hash</b> The output file is a hashed file, named <i>file</i><b>_</b><i>name</i><b>.db</b>. 217 This is available on systems with support for <b>db</b> data- 218 bases. 219 220 <b>lmdb</b> The output is a btree-based file, named <i>file</i><b>_</b><i>name</i><b>.lmdb</b>. 221 <b>lmdb</b> supports concurrent writes and reads from different 222 processes, unlike other supported file-based tables. 223 This is available on systems with support for <b>lmdb</b> data- 224 bases. 225 226 <b>sdbm</b> The output consists of two files, named <i>file</i><b>_</b><i>name</i><b>.pag</b> and 227 <i>file</i><b>_</b><i>name</i><b>.dir</b>. This is available on systems with support 228 for <b>sdbm</b> databases. 229 230 When no <i>file</i><b>_</b><i>type</i> is specified, the software uses the database 231 type specified via the <b><a href="postconf.5.html#default_database_type">default_database_type</a></b> configuration 232 parameter. 233 234 <i>file</i><b>_</b><i>name</i> 235 The name of the lookup table source file when rebuilding a data- 236 base. 237 238<b>DIAGNOSTICS</b> 239 Problems are logged to the standard error stream and to <b>syslogd</b>(8) or 240 <a href="postlogd.8.html"><b>postlogd</b>(8)</a>. No output means that no problems were detected. Duplicate 241 entries are skipped and are flagged with a warning. 242 243 <a href="postmap.1.html"><b>postmap</b>(1)</a> terminates with zero exit status in case of success (includ- 244 ing successful "<b>postmap -q</b>" lookup) and terminates with non-zero exit 245 status in case of failure. 246 247<b>ENVIRONMENT</b> 248 <b>MAIL_CONFIG</b> 249 Directory with Postfix configuration files. 250 251 <b>MAIL_VERBOSE</b> 252 Enable verbose logging for debugging purposes. 253 254<b>CONFIGURATION PARAMETERS</b> 255 The following <a href="postconf.5.html"><b>main.cf</b></a> parameters are especially relevant to this pro- 256 gram. The text below provides only a parameter summary. See <a href="postconf.5.html"><b>post-</b></a> 257 <a href="postconf.5.html"><b>conf</b>(5)</a> for more details including examples. 258 259 <b><a href="postconf.5.html#berkeley_db_create_buffer_size">berkeley_db_create_buffer_size</a> (16777216)</b> 260 The per-table I/O buffer size for programs that create Berkeley 261 DB hash or btree tables. 262 263 <b><a href="postconf.5.html#berkeley_db_read_buffer_size">berkeley_db_read_buffer_size</a> (131072)</b> 264 The per-table I/O buffer size for programs that read Berkeley DB 265 hash or btree tables. 266 267 <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b> 268 The default location of the Postfix <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> con- 269 figuration files. 270 271 <b><a href="postconf.5.html#default_database_type">default_database_type</a> (see 'postconf -d' output)</b> 272 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> 273 and <a href="postmap.1.html"><b>postmap</b>(1)</a> commands. 274 275 <b><a href="postconf.5.html#import_environment">import_environment</a> (see 'postconf -d' output)</b> 276 The list of environment variables that a privileged Postfix 277 process will import from a non-Postfix parent process, or 278 name=value environment overrides. 279 280 <b><a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> (yes)</b> 281 Enable preliminary SMTPUTF8 support for the protocols described 282 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>. 283 284 <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b> 285 The syslog facility of Postfix logging. 286 287 <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b> 288 A prefix that is prepended to the process name in syslog 289 records, so that, for example, "smtpd" becomes "prefix/smtpd". 290 291 Available in Postfix 2.11 and later: 292 293 <b><a href="postconf.5.html#lmdb_map_size">lmdb_map_size</a> (16777216)</b> 294 The initial OpenLDAP LMDB database size limit in bytes. 295 296<b>SEE ALSO</b> 297 <a href="postalias.1.html">postalias(1)</a>, create/update/query alias database 298 <a href="postconf.1.html">postconf(1)</a>, supported database types 299 <a href="postconf.5.html">postconf(5)</a>, configuration parameters 300 <a href="postlogd.8.html">postlogd(8)</a>, Postfix logging 301 syslogd(8), system logging 302 303<b>README FILES</b> 304 <a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview 305 306<b>LICENSE</b> 307 The Secure Mailer license must be distributed with this software. 308 309<b>AUTHOR(S)</b> 310 Wietse Venema 311 IBM T.J. Watson Research 312 P.O. Box 704 313 Yorktown Heights, NY 10598, USA 314 315 Wietse Venema 316 Google, Inc. 317 111 8th Avenue 318 New York, NY 10011, USA 319 320 POSTMAP(1) 321</pre> </body> </html> 322