canonical revision 1.1.1.4
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 address\fR" 67# When \fIpattern\fR matches a mail address, replace it by the 68# corresponding \fIaddress\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, each \fIuser\fR@\fIdomain\fR 80# query produces a sequence of query patterns as described below. 81# 82# Each query pattern is sent to each specified lookup table 83# before trying the next query pattern, until a match is 84# found. 85# .IP "\fIuser\fR@\fIdomain address\fR" 86# Replace \fIuser\fR@\fIdomain\fR by \fIaddress\fR. This form 87# has the highest precedence. 88# .sp 89# This is useful to clean up addresses produced by legacy mail systems. 90# It can also be used to produce \fIFirstname.Lastname\fR style 91# addresses, but see below for a simpler solution. 92# .IP "\fIuser address\fR" 93# Replace \fIuser\fR@\fIsite\fR by \fIaddress\fR when \fIsite\fR is 94# equal to $\fBmyorigin\fR, when \fIsite\fR is listed in 95# $\fBmydestination\fR, or when it is listed in $\fBinet_interfaces\fR 96# or $\fBproxy_interfaces\fR. 97# .sp 98# This form is useful for replacing login names by 99# \fIFirstname.Lastname\fR. 100# .IP "@\fIdomain address\fR" 101# Replace other addresses in \fIdomain\fR by \fIaddress\fR. 102# This form has the lowest precedence. 103# .sp 104# Note: @\fIdomain\fR is a wild-card. When this form is applied 105# to recipient addresses, the Postfix SMTP server accepts 106# mail for any recipient in \fIdomain\fR, regardless of whether 107# that recipient exists. This may turn your mail system into 108# a backscatter source: Postfix first accepts mail for 109# non-existent recipients and then tries to return that mail 110# as "undeliverable" to the often forged sender address. 111# .sp 112# To avoid backscatter with mail for a wild-card domain, 113# replace the wild-card mapping with explicit 1:1 mappings, 114# or add a reject_unverified_recipient restriction for that 115# domain: 116# 117# .nf 118# smtpd_recipient_restrictions = 119# ... 120# reject_unauth_destination 121# check_recipient_access 122# inline:{example.com=reject_unverified_recipient} 123# unverified_recipient_reject_code = 550 124# .fi 125# 126# In the above example, Postfix may contact a remote server 127# if the recipient is rewritten to a remote address. 128# RESULT ADDRESS REWRITING 129# .ad 130# .fi 131# The lookup result is subject to address rewriting: 132# .IP \(bu 133# When the result has the form @\fIotherdomain\fR, the 134# result becomes the same \fIuser\fR in \fIotherdomain\fR. 135# .IP \(bu 136# When "\fBappend_at_myorigin=yes\fR", append "\fB@$myorigin\fR" 137# to addresses without "@domain". 138# .IP \(bu 139# When "\fBappend_dot_mydomain=yes\fR", append 140# "\fB.$mydomain\fR" to addresses without ".domain". 141# ADDRESS EXTENSION 142# .fi 143# .ad 144# When a mail address localpart contains the optional recipient delimiter 145# (e.g., \fIuser+foo\fR@\fIdomain\fR), the lookup order becomes: 146# \fIuser+foo\fR@\fIdomain\fR, \fIuser\fR@\fIdomain\fR, \fIuser+foo\fR, 147# \fIuser\fR, and @\fIdomain\fR. 148# 149# The \fBpropagate_unmatched_extensions\fR parameter controls whether 150# an unmatched address extension (\fI+foo\fR) is propagated to the 151# result of table lookup. 152# REGULAR EXPRESSION TABLES 153# .ad 154# .fi 155# This section describes how the table lookups change when the table 156# is given in the form of regular expressions. For a description of 157# regular expression lookup table syntax, see \fBregexp_table\fR(5) 158# or \fBpcre_table\fR(5). 159# 160# Each pattern is a regular expression that is applied to the entire 161# address being looked up. Thus, \fIuser@domain\fR mail addresses are not 162# broken up into their \fIuser\fR and \fI@domain\fR constituent parts, 163# nor is \fIuser+foo\fR broken up into \fIuser\fR and \fIfoo\fR. 164# 165# Patterns are applied in the order as specified in the table, until a 166# pattern is found that matches the search string. 167# 168# Results are the same as with indexed file lookups, with 169# the additional feature that parenthesized substrings from the 170# pattern can be interpolated as \fB$1\fR, \fB$2\fR and so on. 171# TCP-BASED TABLES 172# .ad 173# .fi 174# This section describes how the table lookups change when lookups 175# are directed to a TCP-based server. For a description of the TCP 176# client/server lookup protocol, see \fBtcp_table\fR(5). 177# This feature is not available up to and including Postfix version 2.4. 178# 179# Each lookup operation uses the entire address once. Thus, 180# \fIuser@domain\fR mail addresses are not broken up into their 181# \fIuser\fR and \fI@domain\fR constituent parts, nor is 182# \fIuser+foo\fR broken up into \fIuser\fR and \fIfoo\fR. 183# 184# Results are the same as with indexed file lookups. 185# BUGS 186# The table format does not understand quoting conventions. 187# CONFIGURATION PARAMETERS 188# .ad 189# .fi 190# The following \fBmain.cf\fR parameters are especially relevant. 191# The text below provides only a parameter summary. See 192# \fBpostconf\fR(5) for more details including examples. 193# .IP "\fBcanonical_classes (envelope_sender, envelope_recipient, header_sender, header_recipient)\fR" 194# What addresses are subject to canonical_maps address mapping. 195# .IP "\fBcanonical_maps (empty)\fR" 196# Optional address mapping lookup tables for message headers and 197# envelopes. 198# .IP "\fBrecipient_canonical_maps (empty)\fR" 199# Optional address mapping lookup tables for envelope and header 200# recipient addresses. 201# .IP "\fBsender_canonical_maps (empty)\fR" 202# Optional address mapping lookup tables for envelope and header 203# sender addresses. 204# .IP "\fBpropagate_unmatched_extensions (canonical, virtual)\fR" 205# What address lookup tables copy an address extension from the lookup 206# key to the lookup result. 207# .PP 208# Other parameters of interest: 209# .IP "\fBinet_interfaces (all)\fR" 210# The network interface addresses that this mail system receives 211# mail on. 212# .IP "\fBlocal_header_rewrite_clients (permit_inet_interfaces)\fR" 213# Rewrite message header addresses in mail from these clients and 214# update incomplete addresses with the domain name in $myorigin or 215# $mydomain; either don't rewrite message headers from other clients 216# at all, or rewrite message headers and update incomplete addresses 217# with the domain specified in the remote_header_rewrite_domain 218# parameter. 219# .IP "\fBproxy_interfaces (empty)\fR" 220# The network interface addresses that this mail system receives mail 221# on by way of a proxy or network address translation unit. 222# .IP "\fBmasquerade_classes (envelope_sender, header_sender, header_recipient)\fR" 223# What addresses are subject to address masquerading. 224# .IP "\fBmasquerade_domains (empty)\fR" 225# Optional list of domains whose subdomain structure will be stripped 226# off in email addresses. 227# .IP "\fBmasquerade_exceptions (empty)\fR" 228# Optional list of user names that are not subjected to address 229# masquerading, even when their address matches $masquerade_domains. 230# .IP "\fBmydestination ($myhostname, localhost.$mydomain, localhost)\fR" 231# The list of domains that are delivered via the $local_transport 232# mail delivery transport. 233# .IP "\fBmyorigin ($myhostname)\fR" 234# The domain name that locally-posted mail appears to come 235# from, and that locally posted mail is delivered to. 236# .IP "\fBowner_request_special (yes)\fR" 237# Enable special treatment for owner-\fIlistname\fR entries in the 238# \fBaliases\fR(5) file, and don't split owner-\fIlistname\fR and 239# \fIlistname\fR-request address localparts when the recipient_delimiter 240# is set to "-". 241# .IP "\fBremote_header_rewrite_domain (empty)\fR" 242# Don't rewrite message headers from remote clients at all when 243# this parameter is empty; otherwise, rewrite message headers and 244# append the specified domain name to incomplete addresses. 245# SEE ALSO 246# cleanup(8), canonicalize and enqueue mail 247# postmap(1), Postfix lookup table manager 248# postconf(5), configuration parameters 249# virtual(5), virtual aliasing 250# README FILES 251# .ad 252# .fi 253# Use "\fBpostconf readme_directory\fR" or 254# "\fBpostconf html_directory\fR" to locate this information. 255# .na 256# .nf 257# DATABASE_README, Postfix lookup table overview 258# ADDRESS_REWRITING_README, address rewriting guide 259# LICENSE 260# .ad 261# .fi 262# The Secure Mailer license must be distributed with this software. 263# AUTHOR(S) 264# Wietse Venema 265# IBM T.J. Watson Research 266# P.O. Box 704 267# Yorktown Heights, NY 10598, USA 268# 269# Wietse Venema 270# Google, Inc. 271# 111 8th Avenue 272# New York, NY 10011, USA 273#-- 274