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