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 regular- 31# expression map where patterns are given as regular expres- 32# sions, or lookups can be directed to TCP-based server. In 33# those cases, the lookups are done in a slightly different 34# way as described below under "REGULAR EXPRESSION TABLES" 35# 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 result 70# When pattern matches a mail address, replace it by 71# the corresponding result. 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, patterns are 86# tried in the order as listed below: 87# 88# user@domain address 89# Replace user@domain by address. This form has the 90# highest precedence. 91# 92# This is useful to clean up addresses produced by 93# legacy mail systems. It can also be used to pro- 94# duce Firstname.Lastname style addresses, but see 95# below for a simpler solution. 96# 97# user address 98# Replace user@site by address when site is equal to 99# $myorigin, when site is listed in $mydestination, 100# or when it is listed in $inet_interfaces or 101# $proxy_interfaces. 102# 103# This form is useful for replacing login names by 104# Firstname.Lastname. 105# 106# @domain address 107# Replace other addresses in domain by address. This 108# form has the lowest precedence. 109# 110# Note: @domain is a wild-card. When this form is 111# applied to recipient addresses, the Postfix SMTP 112# server accepts mail for any recipient in domain, 113# regardless of whether that recipient exists. This 114# may turn your mail system into a backscatter 115# source: Postfix first accepts mail for non-existent 116# recipients and then tries to return that mail as 117# "undeliverable" to the often forged sender address. 118# 119# RESULT ADDRESS REWRITING 120# The lookup result is subject to address rewriting: 121# 122# o When the result has the form @otherdomain, the 123# result becomes the same user in otherdomain. 124# 125# o When "append_at_myorigin=yes", append "@$myorigin" 126# to addresses without "@domain". 127# 128# o When "append_dot_mydomain=yes", append ".$mydomain" 129# to addresses without ".domain". 130# 131# ADDRESS EXTENSION 132# When a mail address localpart contains the optional recip- 133# ient delimiter (e.g., user+foo@domain), the lookup order 134# becomes: user+foo@domain, user@domain, user+foo, user, and 135# @domain. 136# 137# The propagate_unmatched_extensions parameter controls 138# whether an unmatched address extension (+foo) is propa- 139# gated to the result of table lookup. 140# 141# REGULAR EXPRESSION TABLES 142# This section describes how the table lookups change when 143# the table is given in the form of regular expressions. For 144# a description of regular expression lookup table syntax, 145# see regexp_table(5) or pcre_table(5). 146# 147# Each pattern is a regular expression that is applied to 148# the entire address being looked up. Thus, user@domain mail 149# addresses are not broken up into their user and @domain 150# constituent parts, nor is user+foo broken up into user and 151# foo. 152# 153# Patterns are applied in the order as specified in the ta- 154# ble, until a pattern is found that matches the search 155# string. 156# 157# Results are the same as with indexed file lookups, with 158# the additional feature that parenthesized substrings from 159# the pattern can be interpolated as $1, $2 and so on. 160# 161# TCP-BASED TABLES 162# This section describes how the table lookups change when 163# lookups are directed to a TCP-based server. For a descrip- 164# tion of the TCP client/server lookup protocol, see tcp_ta- 165# ble(5). This feature is not available up to and including 166# Postfix version 2.4. 167# 168# Each lookup operation uses the entire address once. Thus, 169# user@domain mail addresses are not broken up into their 170# user and @domain constituent parts, nor is user+foo broken 171# up into user and foo. 172# 173# Results are the same as with indexed file lookups. 174# 175# BUGS 176# The table format does not understand quoting conventions. 177# 178# CONFIGURATION PARAMETERS 179# The following main.cf parameters are especially relevant. 180# The text below provides only a parameter summary. See 181# postconf(5) for more details including examples. 182# 183# canonical_classes 184# What addresses are subject to canonical address 185# mapping. 186# 187# canonical_maps 188# List of canonical mapping tables. 189# 190# recipient_canonical_maps 191# Address mapping lookup table for envelope and 192# header recipient addresses. 193# 194# sender_canonical_maps 195# Address mapping lookup table for envelope and 196# header sender addresses. 197# 198# propagate_unmatched_extensions 199# A list of address rewriting or forwarding mecha- 200# nisms that propagate an address extension from the 201# original address to the result. Specify zero or 202# more of canonical, virtual, alias, forward, 203# include, or generic. 204# 205# Other parameters of interest: 206# 207# inet_interfaces 208# The network interface addresses that this system 209# receives mail on. You need to stop and start Post- 210# fix when this parameter changes. 211# 212# local_header_rewrite_clients 213# Rewrite message header addresses in mail from these 214# clients and update incomplete addresses with the 215# domain name in $myorigin or $mydomain; either don't 216# rewrite message headers from other clients at all, 217# or rewrite message headers and update incomplete 218# addresses with the domain specified in the 219# remote_header_rewrite_domain parameter. 220# 221# proxy_interfaces 222# Other interfaces that this machine receives mail on 223# by way of a proxy agent or network address transla- 224# tor. 225# 226# masquerade_classes 227# List of address classes subject to masquerading: 228# zero or more of envelope_sender, envelope_recipi- 229# ent, header_sender, header_recipient. 230# 231# masquerade_domains 232# List of domains that hide their subdomain struc- 233# ture. 234# 235# masquerade_exceptions 236# List of user names that are not subject to address 237# masquerading. 238# 239# mydestination 240# List of domains that this mail system considers 241# local. 242# 243# myorigin 244# The domain that is appended to locally-posted mail. 245# 246# owner_request_special 247# Give special treatment to owner-xxx and xxx-request 248# addresses. 249# 250# remote_header_rewrite_domain 251# Don't rewrite message headers from remote clients 252# at all when this parameter is empty; otherwise, re- 253# write message headers and append the specified 254# domain name to incomplete addresses. 255# 256# SEE ALSO 257# cleanup(8), canonicalize and enqueue mail 258# postmap(1), Postfix lookup table manager 259# postconf(5), configuration parameters 260# virtual(5), virtual aliasing 261# 262# README FILES 263# Use "postconf readme_directory" or "postconf html_direc- 264# tory" to locate this information. 265# DATABASE_README, Postfix lookup table overview 266# ADDRESS_REWRITING_README, address rewriting guide 267# 268# LICENSE 269# The Secure Mailer license must be distributed with this 270# software. 271# 272# AUTHOR(S) 273# Wietse Venema 274# IBM T.J. Watson Research 275# P.O. Box 704 276# Yorktown Heights, NY 10598, USA 277# 278# CANONICAL(5) 279