1#++ 2# NAME 3# canonical 5 4# SUMMARY 5# Postfix canonical table format 6# SYNOPSIS 7# \fBpostmap /etc/postfix/canonical\fR 8# 9# \fBpostmap -q "\fIstring\fB" /etc/postfix/canonical\fR 10# 11# \fBpostmap -q - /etc/postfix/canonical <\fIinputfile\fR 12# DESCRIPTION 13# The optional \fBcanonical\fR(5) table specifies an address mapping for 14# local and non-local addresses. The mapping is used by the 15# \fBcleanup\fR(8) daemon, before mail is stored into the 16# queue. The address mapping is recursive. 17# 18# Normally, the \fBcanonical\fR(5) table is specified as a text file 19# that serves as input to the \fBpostmap\fR(1) command. 20# The result, an indexed file in \fBdbm\fR or \fBdb\fR format, 21# is used for fast searching by the mail system. Execute the command 22# "\fBpostmap /etc/postfix/canonical\fR" to rebuild an indexed 23# file after changing the corresponding text file. 24# 25# When the table is provided via other means such as NIS, LDAP 26# or SQL, the same lookups are done as for ordinary indexed files. 27# 28# Alternatively, the table can be provided as a regular-expression 29# map where patterns are given as regular expressions, or lookups 30# can be directed to TCP-based server. In those cases, the lookups 31# are done in a slightly different way as described below under 32# "REGULAR EXPRESSION TABLES" or "TCP-BASED TABLES". 33# 34# By default the \fBcanonical\fR(5) mapping affects both message 35# header addresses (i.e. addresses that appear inside messages) 36# and message envelope addresses (for example, the addresses 37# that are used in SMTP protocol commands). This is controlled with 38# the \fBcanonical_classes\fR parameter. 39# 40# NOTE: Postfix versions 2.2 and later rewrite message headers 41# from remote SMTP clients only if the client matches the 42# local_header_rewrite_clients parameter, or if the 43# remote_header_rewrite_domain configuration parameter specifies 44# a non-empty value. To get the behavior before Postfix 2.2, 45# specify "local_header_rewrite_clients = static:all". 46# 47# Typically, one would use the \fBcanonical\fR(5) table to replace login 48# names by \fIFirstname.Lastname\fR, or to clean up addresses produced 49# by legacy mail systems. 50# 51# The \fBcanonical\fR(5) mapping is not to be confused with \fIvirtual 52# alias\fR support or with local aliasing. To change the destination 53# but not the headers, use the \fBvirtual\fR(5) or \fBaliases\fR(5) 54# map instead. 55# CASE FOLDING 56# .ad 57# .fi 58# The search string is folded to lowercase before database 59# lookup. As of Postfix 2.3, the search string is not case 60# folded with database types such as regexp: or pcre: whose 61# lookup fields can match both upper and lower case. 62# TABLE FORMAT 63# .ad 64# .fi 65# The input format for the \fBpostmap\fR(1) command is as follows: 66# .IP "\fIpattern result\fR" 67# When \fIpattern\fR matches a mail address, replace it by the 68# corresponding \fIresult\fR. 69# .IP "blank lines and comments" 70# Empty lines and whitespace-only lines are ignored, as 71# are lines whose first non-whitespace character is a `#'. 72# .IP "multi-line text" 73# A logical line starts with non-whitespace text. A line that 74# starts with whitespace continues a logical line. 75# TABLE SEARCH ORDER 76# .ad 77# .fi 78# With lookups from indexed files such as DB or DBM, or from networked 79# tables such as NIS, LDAP or SQL, patterns are tried in the order as 80# listed below: 81# .IP "\fIuser\fR@\fIdomain address\fR" 82# Replace \fIuser\fR@\fIdomain\fR by \fIaddress\fR. This form 83# has the highest precedence. 84# .sp 85# This is useful to clean up addresses produced by legacy mail systems. 86# It can also be used to produce \fIFirstname.Lastname\fR style 87# addresses, but see below for a simpler solution. 88# .IP "\fIuser address\fR" 89# Replace \fIuser\fR@\fIsite\fR by \fIaddress\fR when \fIsite\fR is 90# equal to $\fBmyorigin\fR, when \fIsite\fR is listed in 91# $\fBmydestination\fR, or when it is listed in $\fBinet_interfaces\fR 92# or $\fBproxy_interfaces\fR. 93# .sp 94# This form is useful for replacing login names by 95# \fIFirstname.Lastname\fR. 96# .IP "@\fIdomain address\fR" 97# Replace other addresses in \fIdomain\fR by \fIaddress\fR. 98# This form has the lowest precedence. 99# .sp 100# Note: @\fIdomain\fR is a wild-card. When this form is applied 101# to recipient addresses, the Postfix SMTP server accepts 102# mail for any recipient in \fIdomain\fR, regardless of whether 103# that recipient exists. This may turn your mail system into 104# a backscatter source: Postfix first accepts mail for 105# non-existent recipients and then tries to return that mail 106# as "undeliverable" to the often forged sender address. 107# RESULT ADDRESS REWRITING 108# .ad 109# .fi 110# The lookup result is subject to address rewriting: 111# .IP \(bu 112# When the result has the form @\fIotherdomain\fR, the 113# result becomes the same \fIuser\fR in \fIotherdomain\fR. 114# .IP \(bu 115# When "\fBappend_at_myorigin=yes\fR", append "\fB@$myorigin\fR" 116# to addresses without "@domain". 117# .IP \(bu 118# When "\fBappend_dot_mydomain=yes\fR", append 119# "\fB.$mydomain\fR" to addresses without ".domain". 120# ADDRESS EXTENSION 121# .fi 122# .ad 123# When a mail address localpart contains the optional recipient delimiter 124# (e.g., \fIuser+foo\fR@\fIdomain\fR), the lookup order becomes: 125# \fIuser+foo\fR@\fIdomain\fR, \fIuser\fR@\fIdomain\fR, \fIuser+foo\fR, 126# \fIuser\fR, and @\fIdomain\fR. 127# 128# The \fBpropagate_unmatched_extensions\fR parameter controls whether 129# an unmatched address extension (\fI+foo\fR) is propagated to the 130# result of table lookup. 131# REGULAR EXPRESSION TABLES 132# .ad 133# .fi 134# This section describes how the table lookups change when the table 135# is given in the form of regular expressions. For a description of 136# regular expression lookup table syntax, see \fBregexp_table\fR(5) 137# or \fBpcre_table\fR(5). 138# 139# Each pattern is a regular expression that is applied to the entire 140# address being looked up. Thus, \fIuser@domain\fR mail addresses are not 141# broken up into their \fIuser\fR and \fI@domain\fR constituent parts, 142# nor is \fIuser+foo\fR broken up into \fIuser\fR and \fIfoo\fR. 143# 144# Patterns are applied in the order as specified in the table, until a 145# pattern is found that matches the search string. 146# 147# Results are the same as with indexed file lookups, with 148# the additional feature that parenthesized substrings from the 149# pattern can be interpolated as \fB$1\fR, \fB$2\fR and so on. 150# TCP-BASED TABLES 151# .ad 152# .fi 153# This section describes how the table lookups change when lookups 154# are directed to a TCP-based server. For a description of the TCP 155# client/server lookup protocol, see \fBtcp_table\fR(5). 156# This feature is not available up to and including Postfix version 2.4. 157# 158# Each lookup operation uses the entire address once. Thus, 159# \fIuser@domain\fR mail addresses are not broken up into their 160# \fIuser\fR and \fI@domain\fR constituent parts, nor is 161# \fIuser+foo\fR broken up into \fIuser\fR and \fIfoo\fR. 162# 163# Results are the same as with indexed file lookups. 164# BUGS 165# The table format does not understand quoting conventions. 166# CONFIGURATION PARAMETERS 167# .ad 168# .fi 169# The following \fBmain.cf\fR parameters are especially relevant. 170# The text below provides only a parameter summary. See 171# \fBpostconf\fR(5) for more details including examples. 172# .IP \fBcanonical_classes\fR 173# What addresses are subject to canonical address mapping. 174# .IP \fBcanonical_maps\fR 175# List of canonical mapping tables. 176# .IP \fBrecipient_canonical_maps\fR 177# Address mapping lookup table for envelope and header recipient 178# addresses. 179# .IP \fBsender_canonical_maps\fR 180# Address mapping lookup table for envelope and header sender 181# addresses. 182# .IP \fBpropagate_unmatched_extensions\fR 183# A list of address rewriting or forwarding mechanisms that propagate 184# an address extension from the original address to the result. 185# Specify zero or more of \fBcanonical\fR, \fBvirtual\fR, \fBalias\fR, 186# \fBforward\fR, \fBinclude\fR, or \fBgeneric\fR. 187# .PP 188# Other parameters of interest: 189# .IP \fBinet_interfaces\fR 190# The network interface addresses that this system receives mail on. 191# You need to stop and start Postfix when this parameter changes. 192# .IP \fBlocal_header_rewrite_clients\fR 193# Rewrite message header addresses in mail from these clients 194# and update incomplete addresses with the domain name in 195# $myorigin or $mydomain; either don't rewrite message headers 196# from other clients at all, or rewrite message headers and 197# update incomplete addresses with the domain specified in 198# the remote_header_rewrite_domain parameter. 199# .IP \fBproxy_interfaces\fR 200# Other interfaces that this machine receives mail on by way of a 201# proxy agent or network address translator. 202# .IP \fBmasquerade_classes\fR 203# List of address classes subject to masquerading: zero or more of 204# \fBenvelope_sender\fR, \fBenvelope_recipient\fR, \fBheader_sender\fR, 205# \fBheader_recipient\fR. 206# .IP \fBmasquerade_domains\fR 207# List of domains that hide their subdomain structure. 208# .IP \fBmasquerade_exceptions\fR 209# List of user names that are not subject to address masquerading. 210# .IP \fBmydestination\fR 211# List of domains that this mail system considers local. 212# .IP \fBmyorigin\fR 213# The domain that is appended to locally-posted mail. 214# .IP \fBowner_request_special\fR 215# Give special treatment to \fBowner-\fIxxx\fR and \fIxxx\fB-request\fR 216# addresses. 217# .IP \fBremote_header_rewrite_domain\fR 218# Don't rewrite message headers from remote clients at all 219# when this parameter is empty; otherwise, rewrite message 220# headers and append the specified domain name to incomplete 221# addresses. 222# SEE ALSO 223# cleanup(8), canonicalize and enqueue mail 224# postmap(1), Postfix lookup table manager 225# postconf(5), configuration parameters 226# virtual(5), virtual aliasing 227# README FILES 228# .ad 229# .fi 230# Use "\fBpostconf readme_directory\fR" or 231# "\fBpostconf html_directory\fR" to locate this information. 232# .na 233# .nf 234# DATABASE_README, Postfix lookup table overview 235# ADDRESS_REWRITING_README, address rewriting guide 236# LICENSE 237# .ad 238# .fi 239# The Secure Mailer license must be distributed with this software. 240# AUTHOR(S) 241# Wietse Venema 242# IBM T.J. Watson Research 243# P.O. Box 704 244# Yorktown Heights, NY 10598, USA 245#-- 246