1 # CANONICAL(5) CANONICAL(5)
4 # canonical - Postfix canonical table format
7 # postmap /etc/postfix/canonical
9 # postmap -q "string" /etc/postfix/canonical
11 # postmap -q - /etc/postfix/canonical <inputfile
14 # The optional canonical(5) table specifies an address map-
15 # ping for local and non-local addresses. The mapping is
16 # used by the cleanup(8) daemon, before mail is stored into
17 # the queue. The address mapping is recursive.
19 # Normally, the canonical(5) table is specified as a text
20 # file that serves as input to the postmap(1) command. The
21 # result, an indexed file in dbm or db format, is used for
22 # fast searching by the mail system. Execute the command
23 # "postmap /etc/postfix/canonical" in order to rebuild the
24 # indexed file after changing the text file.
26 # When the table is provided via other means such as NIS,
27 # LDAP or SQL, the same lookups are done as for ordinary
30 # Alternatively, the table can be provided as a regular-
31 # expression map where patterns are given as regular expres-
32 # sions, or lookups can be directed to TCP-based server. In
33 # that case, the lookups are done in a slightly different
34 # way as described below under "REGULAR EXPRESSION TABLES"
35 # and "TCP-BASED TABLES".
37 # By default the canonical(5) mapping affects both message
38 # header addresses (i.e. addresses that appear inside mes-
39 # sages) and message envelope addresses (for example, the
40 # addresses that are used in SMTP protocol commands). Think
41 # Sendmail rule set S3, if you like. This is controlled
42 # with the canonical_classes parameter.
44 # NOTE: Postfix versions 2.2 and later rewrite message head-
45 # ers from remote SMTP clients only if the client matches
46 # the local_header_rewrite_clients parameter, or if the
47 # remote_header_rewrite_domain configuration parameter spec-
48 # ifies a non-empty value. To get the behavior before Post-
49 # fix 2.2, specify "local_header_rewrite_clients =
52 # Typically, one would use the canonical(5) table to replace
53 # login names by Firstname.Lastname, or to clean up
54 # addresses produced by legacy mail systems.
56 # The canonical(5) mapping is not to be confused with vir-
57 # tual domain support. Use the virtual(5) map for that pur-
60 # The canonical(5) mapping is not to be confused with local
61 # aliasing. Use the aliases(5) map for that purpose.
64 # The input format for the postmap(1) command is as follows:
67 # When pattern matches a mail address, replace it by
68 # the corresponding result.
70 # blank lines and comments
71 # Empty lines and whitespace-only lines are ignored,
72 # as are lines whose first non-whitespace character
76 # A logical line starts with non-whitespace text. A
77 # line that starts with whitespace continues a logi-
81 # With lookups from indexed files such as DB or DBM, or from
82 # networked tables such as NIS, LDAP or SQL, patterns are
83 # tried in the order as listed below:
86 # Replace user@domain by address. This form has the
89 # This is useful to clean up addresses produced by
90 # legacy mail systems. It can also be used to pro-
91 # duce Firstname.Lastname style addresses, but see
92 # below for a simpler solution.
95 # Replace user@site by address when site is equal to
96 # $myorigin, when site is listed in $mydestination,
97 # or when it is listed in $inet_interfaces or
100 # This form is useful for replacing login names by
101 # Firstname.Lastname.
104 # Replace other addresses in domain by address. This
105 # form has the lowest precedence.
107 # RESULT ADDRESS REWRITING
108 # The lookup result is subject to address rewriting:
110 # o When the result has the form @otherdomain, the
111 # result becomes the same user in otherdomain.
113 # o When "append_at_myorigin=yes", append "@$myorigin"
114 # to addresses without "@domain".
116 # o When "append_dot_mydomain=yes", append ".$mydomain"
117 # to addresses without ".domain".
120 # When a mail address localpart contains the optional recip-
121 # ient delimiter (e.g., user+foo@domain), the lookup order
122 # becomes: user+foo@domain, user@domain, user+foo, user, and
125 # The propagate_unmatched_extensions parameter controls
126 # whether an unmatched address extension (+foo) is propa-
127 # gated to the result of table lookup.
129 # REGULAR EXPRESSION TABLES
130 # This section describes how the table lookups change when
131 # the table is given in the form of regular expressions. For
132 # a description of regular expression lookup table syntax,
133 # see regexp_table(5) or pcre_table(5).
135 # Each pattern is a regular expression that is applied to
136 # the entire address being looked up. Thus, user@domain mail
137 # addresses are not broken up into their user and @domain
138 # constituent parts, nor is user+foo broken up into user and
141 # Patterns are applied in the order as specified in the ta-
142 # ble, until a pattern is found that matches the search
145 # Results are the same as with indexed file lookups, with
146 # the additional feature that parenthesized substrings from
147 # the pattern can be interpolated as $1, $2 and so on.
150 # This section describes how the table lookups change when
151 # lookups are directed to a TCP-based server. For a descrip-
152 # tion of the TCP client/server lookup protocol, see tcp_ta-
153 # ble(5). This feature is not available up to and including
154 # Postfix version 2.2.
156 # Each lookup operation uses the entire address once. Thus,
157 # user@domain mail addresses are not broken up into their
158 # user and @domain constituent parts, nor is user+foo broken
159 # up into user and foo.
161 # Results are the same as with indexed file lookups.
164 # The table format does not understand quoting conventions.
166 # CONFIGURATION PARAMETERS
167 # The following main.cf parameters are especially relevant.
168 # The text below provides only a parameter summary. See
169 # postconf(5) for more details including examples.
172 # What addresses are subject to canonical address
176 # List of canonical mapping tables.
178 # recipient_canonical_maps
179 # Address mapping lookup table for envelope and
180 # header recipient addresses.
182 # sender_canonical_maps
183 # Address mapping lookup table for envelope and
184 # header sender addresses.
186 # propagate_unmatched_extensions
187 # A list of address rewriting or forwarding mecha-
188 # nisms that propagate an address extension from the
189 # original address to the result. Specify zero or
190 # more of canonical, virtual, alias, forward,
191 # include, or generic.
193 # Other parameters of interest:
196 # The network interface addresses that this system
197 # receives mail on. You need to stop and start Post-
198 # fix when this parameter changes.
200 # local_header_rewrite_clients
201 # Rewrite message header addresses in mail from these
202 # clients and update incomplete addresses with the
203 # domain name in $myorigin or $mydomain; either don't
204 # rewrite message headers from other clients at all,
205 # or rewrite message headers and update incomplete
206 # addresses with the domain specified in the
207 # remote_header_rewrite_domain parameter.
210 # Other interfaces that this machine receives mail on
211 # by way of a proxy agent or network address transla-
215 # List of address classes subject to masquerading:
216 # zero or more of envelope_sender, envelope_recipi-
217 # ent, header_sender, header_recipient.
220 # List of domains that hide their subdomain struc-
223 # masquerade_exceptions
224 # List of user names that are not subject to address
228 # List of domains that this mail system considers
232 # The domain that is appended to locally-posted mail.
234 # owner_request_special
235 # Give special treatment to owner-xxx and xxx-request
238 # remote_header_rewrite_domain
239 # Don't rewrite message headers from remote clients
240 # at all when this parameter is empty; otherwise, re-
241 # write message headers and append the specified
242 # domain name to incomplete addresses.
245 # cleanup(8), canonicalize and enqueue mail
246 # postmap(1), Postfix lookup table manager
247 # postconf(5), configuration parameters
248 # virtual(5), virtual aliasing
251 # Use "postconf readme_directory" or "postconf html_direc-
252 # tory" to locate this information.
253 # DATABASE_README, Postfix lookup table overview
254 # ADDRESS_REWRITING_README, address rewriting guide
257 # The Secure Mailer license must be distributed with this
262 # IBM T.J. Watson Research
264 # Yorktown Heights, NY 10598, USA