postfix-master/postmap.1.html

   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>
   7 POSTMAP(1)                                                          POSTMAP(1)
   8
   9 <b>NAME</b>
  10        postmap - Postfix lookup table management
  11
  12 <b>SYNOPSIS</b>
  13        <b>postmap</b> [<b>-Nbfhimnoprsvw</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
  18        Postfix  lookup  tables,  or  updates an existing one. The
  19        input and output file formats are expected to be  compati-
  20        ble with:
  21
  22            <b>makemap</b> <i>file</i><b>_</b><i>type file</i><b>_</b><i>name</i> &lt; <i>file</i><b>_</b><i>name</i>
  23
  24        If the result files do not exist they will be created with
  25        the same group and other read permissions as their  source
  26        file.
  27
  28        While  the table update is in progress, signal delivery is
  29        postponed, and an exclusive, advisory, lock is  placed  on
  30        the entire table, in order to avoid surprises in spectator
  31        processes.
  32
  33 <b>INPUT FILE FORMAT</b>
  34        The format of a lookup table input file is as follows:
  35
  36        <b>o</b>      A table entry has the form
  37
  38                    <i>key</i> whitespace <i>value</i>
  39
  40        <b>o</b>      Empty lines and whitespace-only lines are  ignored,
  41               as  are  lines whose first non-whitespace character
  42               is a `#'.
  43
  44        <b>o</b>      A logical line starts with non-whitespace  text.  A
  45               line  that starts with whitespace continues a logi-
  46               cal line.
  47
  48        The <i>key</i> and <i>value</i> are processed as is,  except  that  sur-
  49        rounding  white space is stripped off. Unlike with Postfix
  50        alias databases, quotes cannot be used to  protect  lookup
  51        keys that contain special characters such as `#' or white-
  52        space.
  53
  54        By default the lookup key is mapped to lowercase  to  make
  55        the  lookups case insensitive; as of Postfix 2.3 this case
  56        folding happens only with tables  whose  lookup  keys  are
  57        fixed-case  strings  such  as  btree:, dbm: or hash:. With
  58        earlier versions, the  lookup  key  is  folded  even  with
  59        tables where a lookup field can match both upper and lower
  60        case text, such as <a href="regexp_table.5.html">regexp</a>: and  <a href="pcre_table.5.html">pcre</a>:.  This  resulted  in
  61        loss of information with $<i>number</i> substitutions.
  62
  63 <b>COMMAND-LINE ARGUMENTS</b>
  64        <b>-b</b>     Enable message body query mode. When reading lookup
  65               keys from standard input with "<b>-q -</b>",  process  the
  66               input as if it is an email message in <a href="http://tools.ietf.org/html/rfc2822">RFC 2822</a> for-
  67               mat.  Each line of body content becomes one  lookup
  68               key.
  69
  70               By  default, the <b>-b</b> option starts generating lookup
  71               keys at the first non-header line, and  stops  when
  72               the  end  of  the  message is reached.  To simulate
  73               <a href="header_checks.5.html"><b>body_checks</b>(5)</a> processing, enable MIME parsing with
  74               <b>-m</b>.  With  this,  the  <b>-b</b> option generates no body-
  75               style lookup keys for attachment MIME  headers  and
  76               for attached message/* headers.
  77
  78               This  feature  is  available in Postfix version 2.6
  79               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
  83               directory  instead  of  the  default  configuration
  84               directory.
  85
  86        <b>-d</b> <i>key</i> Search the specified maps for <i>key</i>  and  remove  one
  87               entry  per  map.   The exit status is zero when the
  88               requested information was found.
  89
  90               If a key value of <b>-</b> is specified, the program reads
  91               key values from the standard input stream. The exit
  92               status is zero when at least one of  the  requested
  93               keys was found.
  94
  95        <b>-f</b>     Do not fold the lookup key to lower case while cre-
  96               ating or querying a table.
  97
  98               With Postfix version 2.3 and later, this option has
  99               no  effect  for  regular  expression tables. There,
 100               case folding is controlled by appending a flag to a
 101               pattern.
 102
 103        <b>-h</b>     Enable  message  header  query  mode.  When reading
 104               lookup  keys  from  standard  input  with  "<b>-q  -</b>",
 105               process  the  input as if it is an email message in
 106               <a href="http://tools.ietf.org/html/rfc2822">RFC 2822</a> format.  Each logical header line  becomes
 107               one  lookup  key.  A  multi-line header becomes one
 108               lookup key with one or more embedded newline  char-
 109               acters.
 110
 111               By  default,  the  <b>-h</b>  option generates lookup keys
 112               until the first non-header  line  is  reached.   To
 113               simulate  <a href="header_checks.5.html"><b>header_checks</b>(5)</a>  processing, enable MIME
 114               parsing with <b>-m</b>. With this, the <b>-h</b> option also gen-
 115               erates header-style lookup keys for attachment MIME
 116               headers and for attached message/* headers.
 117
 118               This feature is available in  Postfix  version  2.6
 119               and later.
 120
 121        <b>-i</b>     Incremental  mode. Read entries from standard input
 122               and  do  not  truncate  an  existing  database.  By
 123               default, <a href="postmap.1.html"><b>postmap</b>(1)</a> creates a new database from the
 124               entries in <b>file_name</b>.
 125
 126        <b>-m</b>     Enable MIME parsing with "<b>-b</b>" and "<b>-h</b>".
 127
 128               This feature is available in  Postfix  version  2.6
 129               and later.
 130
 131        <b>-N</b>     Include  the terminating null character that termi-
 132               nates  lookup  keys   and   values.   By   default,
 133               <a href="postmap.1.html"><b>postmap</b>(1)</a>  does  whatever  is  the default for the
 134               host operating system.
 135
 136        <b>-n</b>     Don't include the terminating null  character  that
 137               terminates  lookup  keys  and  values.  By default,
 138               <a href="postmap.1.html"><b>postmap</b>(1)</a> does whatever is  the  default  for  the
 139               host operating system.
 140
 141        <b>-o</b>     Do  not  release  root privileges when processing a
 142               non-root input file. By default,  <a href="postmap.1.html"><b>postmap</b>(1)</a>  drops
 143               root  privileges  and runs as the source file owner
 144               instead.
 145
 146        <b>-p</b>     Do not inherit the file access permissions from the
 147               input file when creating a new file.  Instead, cre-
 148               ate a new  file  with  default  access  permissions
 149               (mode 0644).
 150
 151        <b>-q</b> <i>key</i> Search  the  specified  maps  for <i>key</i> and write the
 152               first value found to the  standard  output  stream.
 153               The exit status is zero when the requested informa-
 154               tion was found.
 155
 156               If a key value of <b>-</b> is specified, the program reads
 157               key  values  from  the  standard  input  stream and
 158               writes one line of <i>key value</i> output  for  each  key
 159               that  was  found.  The  exit status is zero when at
 160               least one of the requested keys was found.
 161
 162        <b>-r</b>     When  updating  a  table,  do  not  complain  about
 163               attempts to update existing entries, and make those
 164               updates anyway.
 165
 166        <b>-s</b>     Retrieve all database elements, and write one  line
 167               of  <i>key value</i> output for each element. The elements
 168               are printed in database order, which is not  neces-
 169               sarily the same as the original input order.
 170
 171               This  feature  is  available in Postfix version 2.2
 172               and later, and is not available  for  all  database
 173               types.
 174
 175        <b>-v</b>     Enable verbose logging for debugging purposes. Mul-
 176               tiple <b>-v</b> options  make  the  software  increasingly
 177               verbose.
 178
 179        <b>-w</b>     When  updating  a  table,  do  not  complain  about
 180               attempts to update  existing  entries,  and  ignore
 181               those attempts.
 182
 183        Arguments:
 184
 185        <i>file</i><b>_</b><i>type</i>
 186               The  database type. To find out what types are sup-
 187               ported, use the "<b>postconf -m</b>" command.
 188
 189               The <a href="postmap.1.html"><b>postmap</b>(1)</a> command can query any supported file
 190               type,  but  it  can  create only the following file
 191               types:
 192
 193               <b>btree</b>  The output  file  is  a  btree  file,  named
 194                      <i>file</i><b>_</b><i>name</i><b>.db</b>.   This is available on systems
 195                      with support for <b>db</b> databases.
 196
 197               <b>cdb</b>    The  output  consists  of  one  file,  named
 198                      <i>file</i><b>_</b><i>name</i><b>.cdb</b>.  This is available on systems
 199                      with support for <b>cdb</b> databases.
 200
 201               <b>dbm</b>    The output  consists  of  two  files,  named
 202                      <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
 203                      available on systems with  support  for  <b>dbm</b>
 204                      databases.
 205
 206               <b>hash</b>   The  output  file  is  a  hashed file, named
 207                      <i>file</i><b>_</b><i>name</i><b>.db</b>.  This is available on  systems
 208                      with support for <b>db</b> databases.
 209
 210               <b>sdbm</b>   The  output  consists  of  two  files, named
 211                      <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
 212                      available  on  systems with support for <b>sdbm</b>
 213                      databases.
 214
 215               When no <i>file</i><b>_</b><i>type</i> is specified, the  software  uses
 216               the  database  type specified via the <b><a href="postconf.5.html#default_database_type">default_data</a>-</b>
 217               <b><a href="postconf.5.html#default_database_type">base_type</a></b> configuration parameter.
 218
 219        <i>file</i><b>_</b><i>name</i>
 220               The name of  the  lookup  table  source  file  when
 221               rebuilding a database.
 222
 223 <b>DIAGNOSTICS</b>
 224        Problems  are  logged  to the standard error stream and to
 225        <b>syslogd</b>(8).   No  output  means  that  no  problems   were
 226        detected.  Duplicate  entries  are skipped and are flagged
 227        with a warning.
 228
 229        <a href="postmap.1.html"><b>postmap</b>(1)</a> terminates with zero exit  status  in  case  of
 230        success  (including  successful  "<b>postmap  -q</b>" lookup) and
 231        terminates with non-zero exit status in case of failure.
 232
 233 <b>ENVIRONMENT</b>
 234        <b>MAIL_CONFIG</b>
 235               Directory with Postfix configuration files.
 236
 237        <b>MAIL_VERBOSE</b>
 238               Enable verbose logging for debugging purposes.
 239
 240 <b>CONFIGURATION PARAMETERS</b>
 241        The following <a href="postconf.5.html"><b>main.cf</b></a> parameters are  especially  relevant
 242        to this program.  The text below provides only a parameter
 243        summary. See <a href="postconf.5.html"><b>postconf</b>(5)</a> for more details including  exam-
 244        ples.
 245
 246        <b><a href="postconf.5.html#berkeley_db_create_buffer_size">berkeley_db_create_buffer_size</a> (16777216)</b>
 247               The  per-table  I/O  buffer  size for programs that
 248               create Berkeley DB hash or btree tables.
 249
 250        <b><a href="postconf.5.html#berkeley_db_read_buffer_size">berkeley_db_read_buffer_size</a> (131072)</b>
 251               The per-table I/O buffer  size  for  programs  that
 252               read Berkeley DB hash or btree tables.
 253
 254        <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
 255               The  default  location  of  the Postfix <a href="postconf.5.html">main.cf</a> and
 256               <a href="master.5.html">master.cf</a> configuration files.
 257
 258        <b><a href="postconf.5.html#default_database_type">default_database_type</a> (see 'postconf -d' output)</b>
 259               The default database type for use in <a href="newaliases.1.html"><b>newaliases</b>(1)</a>,
 260               <a href="postalias.1.html"><b>postalias</b>(1)</a> and <a href="postmap.1.html"><b>postmap</b>(1)</a> commands.
 261
 262        <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b>
 263               The syslog facility of Postfix logging.
 264
 265        <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b>
 266               The  mail  system  name  that  is  prepended to the
 267               process name in syslog  records,  so  that  "smtpd"
 268               becomes, for example, "postfix/smtpd".
 269
 270 <b>SEE ALSO</b>
 271        <a href="postalias.1.html">postalias(1)</a>, create/update/query alias database
 272        <a href="postconf.1.html">postconf(1)</a>, supported database types
 273        <a href="postconf.5.html">postconf(5)</a>, configuration parameters
 274        syslogd(8), system logging
 275
 276 <b>README FILES</b>
 277        <a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview
 278
 279 <b>LICENSE</b>
 280        The Secure Mailer license must be  distributed  with  this
 281        software.
 282
 283 <b>AUTHOR(S)</b>
 284        Wietse Venema
 285        IBM T.J. Watson Research
 286        P.O. Box 704
 287        Yorktown Heights, NY 10598, USA
 288
 289                                                                     POSTMAP(1)
 290 </pre> </body> </html>