1# CANONICAL(5) CANONICAL(5) 2# 3# NAME 4# canonical - Postfix canonical table format 5# 6# SYNOPSIS 7# postmap /etc/postfix/canonical 8# 9# postmap -q "string" /etc/postfix/canonical 10# 11# postmap -q - /etc/postfix/canonical <inputfile 12# 13# DESCRIPTION 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. 18# 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" to rebuild an indexed 24# file after changing the corresponding text file. 25# 26# When the table is provided via other means such as NIS, 27# LDAP or SQL, the same lookups are done as for ordinary 28# indexed files. 29# 30# Alternatively, the table can be provided as a regu- 31# lar-expression map where patterns are given as regular 32# expressions, or lookups can be directed to a TCP-based 33# server. In those cases, the lookups are done in a slightly 34# different way as described below under "REGULAR EXPRESSION 35# TABLES" or "TCP-BASED TABLES". 36# 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). This 41# is controlled with the canonical_classes parameter. 42# 43# NOTE: Postfix versions 2.2 and later rewrite message head- 44# ers from remote SMTP clients only if the client matches 45# the local_header_rewrite_clients parameter, or if the 46# remote_header_rewrite_domain configuration parameter spec- 47# ifies a non-empty value. To get the behavior before Post- 48# fix 2.2, specify "local_header_rewrite_clients = 49# static:all". 50# 51# Typically, one would use the canonical(5) table to replace 52# login names by Firstname.Lastname, or to clean up 53# addresses produced by legacy mail systems. 54# 55# The canonical(5) mapping is not to be confused with vir- 56# tual alias support or with local aliasing. To change the 57# destination but not the headers, use the virtual(5) or 58# aliases(5) map instead. 59# 60# CASE FOLDING 61# The search string is folded to lowercase before database 62# lookup. As of Postfix 2.3, the search string is not case 63# folded with database types such as regexp: or pcre: whose 64# lookup fields can match both upper and lower case. 65# 66# TABLE FORMAT 67# The input format for the postmap(1) command is as follows: 68# 69# pattern address 70# When pattern matches a mail address, replace it by 71# the corresponding address. 72# 73# blank lines and comments 74# Empty lines and whitespace-only lines are ignored, 75# as are lines whose first non-whitespace character 76# is a `#'. 77# 78# multi-line text 79# A logical line starts with non-whitespace text. A 80# line that starts with whitespace continues a logi- 81# cal line. 82# 83# TABLE SEARCH ORDER 84# With lookups from indexed files such as DB or DBM, or from 85# networked tables such as NIS, LDAP or SQL, each 86# user@domain query produces a sequence of query patterns as 87# described below. 88# 89# Each query pattern is sent to each specified lookup table 90# before trying the next query pattern, until a match is 91# found. 92# 93# user@domain address 94# Replace user@domain by address. This form has the 95# highest precedence. 96# 97# This is useful to clean up addresses produced by 98# legacy mail systems. It can also be used to pro- 99# duce Firstname.Lastname style addresses, but see 100# below for a simpler solution. 101# 102# user address 103# Replace user@site by address when site is equal to 104# $myorigin, when site is listed in $mydestination, 105# or when it is listed in $inet_interfaces or 106# $proxy_interfaces. 107# 108# This form is useful for replacing login names by 109# Firstname.Lastname. 110# 111# @domain address 112# Replace other addresses in domain by address. This 113# form has the lowest precedence. 114# 115# Note: @domain is a wild-card. When this form is 116# applied to recipient addresses, the Postfix SMTP 117# server accepts mail for any recipient in domain, 118# regardless of whether that recipient exists. This 119# may turn your mail system into a backscatter 120# source: Postfix first accepts mail for non-existent 121# recipients and then tries to return that mail as 122# "undeliverable" to the often forged sender address. 123# 124# To avoid backscatter with mail for a wild-card 125# domain, replace the wild-card mapping with explicit 126# 1:1 mappings, or add a reject_unverified_recipient 127# restriction for that domain: 128# 129# smtpd_recipient_restrictions = 130# ... 131# reject_unauth_destination 132# check_recipient_access 133# inline:{example.com=reject_unverified_recipient} 134# unverified_recipient_reject_code = 550 135# 136# In the above example, Postfix may contact a remote 137# server if the recipient is rewritten to a remote 138# address. 139# 140# RESULT ADDRESS REWRITING 141# The lookup result is subject to address rewriting: 142# 143# o When the result has the form @otherdomain, the 144# result becomes the same user in otherdomain. 145# 146# o When "append_at_myorigin=yes", append "@$myorigin" 147# to addresses without "@domain". 148# 149# o When "append_dot_mydomain=yes", append ".$mydomain" 150# to addresses without ".domain". 151# 152# ADDRESS EXTENSION 153# When a mail address localpart contains the optional recip- 154# ient delimiter (e.g., user+foo@domain), the lookup order 155# becomes: user+foo@domain, user@domain, user+foo, user, and 156# @domain. 157# 158# The propagate_unmatched_extensions parameter controls 159# whether an unmatched address extension (+foo) is propa- 160# gated to the result of table lookup. 161# 162# REGULAR EXPRESSION TABLES 163# This section describes how the table lookups change when 164# the table is given in the form of regular expressions. For 165# a description of regular expression lookup table syntax, 166# see regexp_table(5) or pcre_table(5). 167# 168# Each pattern is a regular expression that is applied to 169# the entire address being looked up. Thus, user@domain mail 170# addresses are not broken up into their user and @domain 171# constituent parts, nor is user+foo broken up into user and 172# foo. 173# 174# Patterns are applied in the order as specified in the ta- 175# ble, until a pattern is found that matches the search 176# string. 177# 178# Results are the same as with indexed file lookups, with 179# the additional feature that parenthesized substrings from 180# the pattern can be interpolated as $1, $2 and so on. 181# 182# TCP-BASED TABLES 183# This section describes how the table lookups change when 184# lookups are directed to a TCP-based server. For a descrip- 185# tion of the TCP client/server lookup protocol, see tcp_ta- 186# ble(5). This feature is not available up to and including 187# Postfix version 2.4. 188# 189# Each lookup operation uses the entire address once. Thus, 190# user@domain mail addresses are not broken up into their 191# user and @domain constituent parts, nor is user+foo broken 192# up into user and foo. 193# 194# Results are the same as with indexed file lookups. 195# 196# BUGS 197# The table format does not understand quoting conventions. 198# 199# CONFIGURATION PARAMETERS 200# The following main.cf parameters are especially relevant. 201# The text below provides only a parameter summary. See 202# postconf(5) for more details including examples. 203# 204# canonical_classes (envelope_sender, envelope_recipient, 205# header_sender, header_recipient) 206# What addresses are subject to canonical_maps 207# address mapping. 208# 209# canonical_maps (empty) 210# Optional address mapping lookup tables for message 211# headers and envelopes. 212# 213# recipient_canonical_maps (empty) 214# Optional address mapping lookup tables for envelope 215# and header recipient addresses. 216# 217# sender_canonical_maps (empty) 218# Optional address mapping lookup tables for envelope 219# and header sender addresses. 220# 221# propagate_unmatched_extensions (canonical, virtual) 222# What address lookup tables copy an address exten- 223# sion from the lookup key to the lookup result. 224# 225# Other parameters of interest: 226# 227# inet_interfaces (all) 228# The network interface addresses that this mail sys- 229# tem receives mail on. 230# 231# local_header_rewrite_clients (permit_inet_interfaces) 232# Rewrite message header addresses in mail from these 233# clients and update incomplete addresses with the 234# domain name in $myorigin or $mydomain; either don't 235# rewrite message headers from other clients at all, 236# or rewrite message headers and update incomplete 237# addresses with the domain specified in the 238# remote_header_rewrite_domain parameter. 239# 240# proxy_interfaces (empty) 241# The network interface addresses that this mail sys- 242# tem receives mail on by way of a proxy or network 243# address translation unit. 244# 245# masquerade_classes (envelope_sender, header_sender, 246# header_recipient) 247# What addresses are subject to address masquerading. 248# 249# masquerade_domains (empty) 250# Optional list of domains whose subdomain structure 251# will be stripped off in email addresses. 252# 253# masquerade_exceptions (empty) 254# Optional list of user names that are not subjected 255# to address masquerading, even when their addresses 256# match $masquerade_domains. 257# 258# mydestination ($myhostname, localhost.$mydomain, local- 259# host) 260# The list of domains that are delivered via the 261# $local_transport mail delivery transport. 262# 263# myorigin ($myhostname) 264# The domain name that locally-posted mail appears to 265# come from, and that locally posted mail is deliv- 266# ered to. 267# 268# owner_request_special (yes) 269# Enable special treatment for owner-listname entries 270# in the aliases(5) file, and don't split owner-list- 271# name and listname-request address localparts when 272# the recipient_delimiter is set to "-". 273# 274# remote_header_rewrite_domain (empty) 275# Don't rewrite message headers from remote clients 276# at all when this parameter is empty; otherwise, re- 277# write message headers and append the specified 278# domain name to incomplete addresses. 279# 280# SEE ALSO 281# cleanup(8), canonicalize and enqueue mail 282# postmap(1), Postfix lookup table manager 283# postconf(5), configuration parameters 284# virtual(5), virtual aliasing 285# 286# README FILES 287# Use "postconf readme_directory" or "postconf html_direc- 288# tory" to locate this information. 289# DATABASE_README, Postfix lookup table overview 290# ADDRESS_REWRITING_README, address rewriting guide 291# 292# LICENSE 293# The Secure Mailer license must be distributed with this 294# software. 295# 296# AUTHOR(S) 297# Wietse Venema 298# IBM T.J. Watson Research 299# P.O. Box 704 300# Yorktown Heights, NY 10598, USA 301# 302# Wietse Venema 303# Google, Inc. 304# 111 8th Avenue 305# New York, NY 10011, USA 306# 307# CANONICAL(5) 308