Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
POSTMAP(1)		    General Commands Manual		    POSTMAP(1)

NAME
       postmap - Postfix lookup	table management

SYNOPSIS
       postmap [-bfFhimnNoprsuUvw] [-c config_dir] [-d key] [-q	key]
	       [file_type:]file_name ...

DESCRIPTION
       The  postmap(1)	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  or-
       der to avoid surprises in spectator processes.

INPUT FILE FORMAT
       The format of a lookup table input file is as follows:

       o      A	table entry has	the form

		   key whitespace value

       o      Empty  lines and whitespace-only lines are ignored, as are lines
	      whose first non-whitespace character is a	`#'.

       o      A	logical	line starts with  non-whitespace  text.	 A  line  that
	      starts with whitespace continues a logical line.

       The  key	 and  value are	processed as is, except	that surrounding white
       space is	stripped off. Whitespace in lookup keys	 is  supported	as  of
       Postfix 3.2.

       When  the  -F option is given, the value	must specify one or more file-
       names separated by comma	and/or whitespace; postmap(1) will concatenate
       the  file content (with a newline character inserted between files) and
       will store the base64-encoded result instead of the value.

       When the	key specifies email address information, the localpart	should
       be enclosed with	double quotes if required by RFC 5322. 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 btree:, dbm: or
       hash:. 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
       regexp: and pcre:. This resulted	in loss	of  information	 with  $number
       substitutions.

COMMAND-LINE ARGUMENTS
       -b     Enable  message  body  query mode. When reading lookup keys from
	      standard input with "-q -", process the input as	if  it	is  an
	      email message in RFC 5322	format.	 Each line of body content be-
	      comes one	lookup key.

	      By default, the -b option	starts generating lookup keys  at  the
	      first  non-header	line, and stops	when the end of	the message is
	      reached.	To simulate  body_checks(5)  processing,  enable  MIME
	      parsing	with  -m.  With	 this,	the  -b	 option	 generates  no
	      body-style lookup	keys for attachment MIME headers and  for  at-
	      tached message/* headers.

	      NOTE:  with  "smtputf8_enable  = yes", the -b option option dis-
	      ables UTF-8 syntax checks	on  query  keys	 and  lookup  results.
	      Specify the -U option to force UTF-8 syntax checks anyway.

	      This feature is available	in Postfix version 2.6 and later.

       -c config_dir
	      Read  the	 main.cf configuration file in the named directory in-
	      stead of the default configuration directory.

       -d key Search the specified maps	for key	and remove one entry per  map.
	      The  exit	 status	 is  zero  when	 the requested information was
	      found.

	      If a key value of	- 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.

       -f     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.

       -F     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
	      FORMAT for details).

       -h     Enable  message header query mode. When reading lookup keys from
	      standard input with "-q -", process the input as	if  it	is  an
	      email  message in	RFC 5322 format.  Each logical header line be-
	      comes one	lookup key. A multi-line header	becomes	one lookup key
	      with one or more embedded	newline	characters.

	      By  default, the -h option generates lookup keys until the first
	      non-header line is reached.  To simulate	header_checks(5)  pro-
	      cessing,	enable	MIME parsing with -m. With this, the -h	option
	      also generates header-style  lookup  keys	 for  attachment  MIME
	      headers and for attached message/* headers.

	      NOTE:  with  "smtputf8_enable  = yes", the -b option option dis-
	      ables UTF-8 syntax checks	on  query  keys	 and  lookup  results.
	      Specify the -U option to force UTF-8 syntax checks anyway.

	      This feature is available	in Postfix version 2.6 and later.

       -i     Incremental  mode.  Read	entries	from standard input and	do not
	      truncate an existing database. By	default, postmap(1) creates  a
	      new database from	the entries in file_name.

       -m     Enable MIME parsing with "-b" and	"-h".

	      This feature is available	in Postfix version 2.6 and later.

       -N     Include  the  terminating	 null character	that terminates	lookup
	      keys and values. By default, postmap(1) does whatever is the de-
	      fault for	the host operating system.

       -n     Don't  include  the  terminating	null character that terminates
	      lookup keys and values. By default, postmap(1) does whatever  is
	      the default for the host operating system.

       -o     Do  not release root privileges when processing a	non-root input
	      file. By default,	postmap(1) drops root privileges and  runs  as
	      the source file owner instead.

       -p     Do  not  inherit the file	access permissions from	the input file
	      when creating a new file.	 Instead, create a new file  with  de-
	      fault access permissions (mode 0644).

       -q key Search  the  specified  maps  for	 key 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  access(5),  canonical(5), transport(5), vir-
	      tual(5) and other	Postfix	table-driven features.

	      If a key value of	- is specified,	the program reads  key	values
	      from  the	standard input stream and writes one line of key value
	      output for each key that was found. The exit status is zero when
	      at least one of the requested keys was found.

       -r     When  updating a table, do not complain about attempts to	update
	      existing entries,	and make those updates anyway.

       -s     Retrieve all database elements, and write	one line of key	 value
	      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.

       -u     Disable UTF-8 support. UTF-8 support is enabled by default  when
	      "smtputf8_enable	=  yes".  It requires that keys	and values are
	      valid UTF-8 strings.

       -U     With "smtputf8_enable = yes", force UTF-8	syntax checks with the
	      -b and -h	options.

       -v     Enable  verbose  logging for debugging purposes. Multiple	-v op-
	      tions make the software increasingly verbose.

       -w     When updating a table, do	not complain about attempts to	update
	      existing entries,	and ignore those attempts.

       Arguments:

       file_type
	      The database type. To find out what types	are supported, use the
	      "postconf	-m" command.

	      The postmap(1) command can query any supported file type,	but it
	      can create only the following file types:

	      btree  The  output  file	is  a  btree file, named file_name.db.
		     This is available on systems with support	for  db	 data-
		     bases.

	      cdb    The  output  consists  of	one file, named	file_name.cdb.
		     This is available on systems with support for  cdb	 data-
		     bases.

	      dbm    The output	consists of two	files, named file_name.pag and
		     file_name.dir.  This is available on systems with support
		     for dbm databases.

	      hash   The  output  file	is  a hashed file, named file_name.db.
		     This is available on systems with support	for  db	 data-
		     bases.

	      fail   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.

	      sdbm   The output	consists of two	files, named file_name.pag and
		     file_name.dir.  This is available on systems with support
		     for sdbm databases.

	      When  no	file_type is specified,	the software uses the database
	      type specified via the default_database_type  configuration  pa-
	      rameter.

       file_name
	      The name of the lookup table source file when rebuilding a data-
	      base.

DIAGNOSTICS
       Problems	are logged to the standard error stream	and to	syslogd(8)  or
       postlogd(8).  No	output means that no problems were detected. Duplicate
       entries are skipped and are flagged with	a warning.

       postmap(1) terminates with zero exit status in case of success (includ-
       ing  successful	"postmap -q" lookup) and terminates with non-zero exit
       status in case of failure.

ENVIRONMENT
       MAIL_CONFIG
	      Directory	with Postfix configuration files.

       MAIL_VERBOSE
	      Enable verbose logging for debugging purposes.

CONFIGURATION PARAMETERS
       The following main.cf parameters	are especially relevant	to  this  pro-
       gram.   The  text  below	 provides  only	a parameter summary. See post-
       conf(5) for more	details	including examples.

       berkeley_db_create_buffer_size (16777216)
	      The per-table I/O	buffer size for	programs that create  Berkeley
	      DB hash or btree tables.

       berkeley_db_read_buffer_size (131072)
	      The per-table I/O	buffer size for	programs that read Berkeley DB
	      hash or btree tables.

       config_directory	(see 'postconf -d' output)
	      The default location of the Postfix main.cf and  master.cf  con-
	      figuration files.

       default_database_type (see 'postconf -d'	output)
	      The default database type	for use	in newaliases(1), postalias(1)
	      and postmap(1) commands.

       import_environment (see 'postconf -d' output)
	      The list of environment parameters  that	a  privileged  Postfix
	      process  will  import  from  a  non-Postfix  parent  process, or
	      name=value environment overrides.

       smtputf8_enable (yes)
	      Enable preliminary SMTPUTF8 support for the protocols  described
	      in RFC 6531..6533.

       syslog_facility (mail)
	      The syslog facility of Postfix logging.

       syslog_name (see	'postconf -d' output)
	      A	 prefix	 that  is  prepended  to  the  process	name in	syslog
	      records, so that,	for example, "smtpd" becomes "prefix/smtpd".

SEE ALSO
       postalias(1), create/update/query alias database
       postconf(1), supported database types
       postconf(5), configuration parameters
       postlogd(8), Postfix logging
       syslogd(8), system logging

README FILES
       Use "postconf readme_directory" or "postconf html_directory" to	locate
       this information.
       DATABASE_README,	Postfix	lookup table overview

LICENSE
       The Secure Mailer license must be distributed with this software.

AUTHOR(S)
       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)

NAME | SYNOPSIS | DESCRIPTION | INPUT FILE FORMAT | COMMAND-LINE ARGUMENTS | DIAGNOSTICS | ENVIRONMENT | CONFIGURATION PARAMETERS | SEE ALSO | README FILES | LICENSE | AUTHOR(S)

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=postmap&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help