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