CANONICAL(5) CANONICAL(5)

NAME
       canonical - format of Postfix canonical table

SYNOPSIS
       ppoossttmmaapp //eettcc//ppoossttffiixx//ccaannoonniiccaall

       ppoossttmmaapp -qq ""string"" //eettcc//ppoossttffiixx//ccaannoonniiccaall

       ppoossttmmaapp -qq - //eettcc//ppoossttffiixx//ccaannoonniiccaall <
DESCRIPTION
       The optional ccaannoonniiccaall table specifies an address mapping for local and
       non-local addresses. The mapping is used by the cclleeaannuupp(8) daemon.  The
       address mapping is recursive.

       Normally,  the  ccaannoonniiccaall table is specified as a text file that serves
       as input to the ppoossttmmaapp(1) command.  The result, an indexed file in ddbbmm
       or  ddbb  format,  is used for fast searching by the mail system. Execute
       the command ppoossttmmaapp //eettcc//ppoossttffiixx//ccaannoonniiccaall  in  order  to  rebuild  the
       indexed file after changing the text file.

       When  the  table  is provided via other means such as NIS, LDAP or SQL,
       the same lookups are done as for ordinary indexed files.

       Alternatively, the table can be provided as  a  regular-expression  map
       where  patterns  are  given  as  regular expressions, or lookups can be
       directed to TCP-based server. In that case, the lookups are done  in  a
       slightly  different  way  as  described below under "REGULAR EXPRESSION
       TABLES" and "TCP-BASED TABLES".

       The ccaannoonniiccaall mapping  affects  both  message  header  addresses  (i.e.
       addresses  that  appear inside messages) and message envelope addresses
       (for example, the addresses that are used in SMTP  protocol  commands).
       Think Sendmail rule set SS33, if you like.

       Typically,  one would use the ccaannoonniiccaall table to replace login names by
       Firstname.Lastname, or to clean up addresses produced  by  legacy  mail
       systems.

       The  ccaannoonniiccaall  mapping  is not to be confused with virtual domain sup-
       port. Use the vviirrttuuaall(5) map for that purpose.

       The ccaannoonniiccaall mapping is not to be confused with local  aliasing.   Use
       the aalliiaasseess(5) map for that purpose.

TTAABBLLEE FFOORRMMAATT
       The input format for the ppoossttmmaapp(1) command is as follows:

       pattern result
              When  pattern  matches  a mail address, replace it by the corre-
              sponding result.

       blank lines and comments
              Empty lines and whitespace-only lines are ignored, as are  lines
              whose first non-whitespace character is a `#'.

       multi-line text
              A  logical  line  starts  with  non-whitespace text. A line that
              starts with whitespace continues a logical line.

       With lookups from indexed files such as DB or DBM,  or  from  networked
       tables  such  as  NIS,  LDAP or SQL, patterns are tried in the order as
       listed below:

       user@domain address
              user@domain is replaced by address. This form  has  the  highest
              precedence.

              This  is  useful  to  clean up addresses produced by legacy mail
              systems.  It can also  be  used  to  produce  Firstname.Lastname
              style addresses, but see below for a simpler solution.

       user address
              user@site  is  replaced by address when site is equal to $mmyyoorrii-
              ggiinn, when site is listed in $mmyyddeessttiinnaattiioonn, or when it is listed
              in $iinneettiinntteerrffaacceess or $pprrooxxyyiinntteerrffaacceess.

              This form is useful for replacing login names by Firstname.Last-
              name.

       @domain address
              Every address in domain is replaced by address.  This  form  has
              the lowest precedence.

       In  all  the  above  forms, when address has the form @otherdomain, the
       result is the same user in otherdomain.

AADDDDRREESSSS EEXXTTEENNSSIIOONN
       When a mail address localpart contains the optional recipient delimiter
       (e.g.,  user+foo@domain),  the  lookup  order becomes: user+foo@domain,
       user@domain, user+foo, user, and @domain.

       The  pprrooppaaggaatteeuunnmmaattcchheeddeexxtteennssiioonnss  parameter  controls   whether   an
       unmatched address extension (+foo) is propagated to the result of table
       lookup.

RREEGGUULLAARR EEXXPPRREESSSSIIOONN TTAABBLLEESS
       This section describes how the table lookups change when the  table  is
       given  in the form of regular expressions. For a description of regular
       expression lookup table syntax, see rreeggeexxppttaabbllee(5) or ppccrreettaabbllee(5).

       Each pattern is a regular expression that  is  applied  to  the  entire
       address  being looked up. Thus, user@domain mail addresses are not bro-
       ken up into their user and @domain constituent parts, nor  is  user+foo
       broken up into user and foo.

       Patterns  are  applied  in the order as specified in the table, until a
       pattern is found that matches the search string.

       Results are the same as with indexed file lookups, with the  additional
       feature  that parenthesized substrings from the pattern can be interpo-
       lated as $$11, $$22 and so on.

TTCCPP-BBAASSEEDD TTAABBLLEESS
       This section describes how the table lookups change  when  lookups  are
       directed   to  a  TCP-based  server.  For  a  description  of  the  TCP
       client/server lookup protocol, see ttccppttaabbllee(5).  This feature  is  not
       available in Postfix version 2.1.

       Each  lookup operation uses the entire address once.  Thus, user@domain
       mail addresses are not broken up  into  their  user  and  @domain  con-
       stituent parts, nor is user+foo broken up into user and foo.

       Results are the same as with indexed file lookups.

BUGS
       The table format does not understand quoting conventions.

CCOONNFFIIGGUURRAATTIIOONN PPAARRAAMMEETTEERRSS
       The  following  mmaaiinn..ccff  parameters  are especially relevant.  The text
       below provides only a  parameter  summary.  See  postconf(5)  for  more
       details including examples.

       ccaannoonniiccaallmmaappss
              List of canonical mapping tables.

       rreecciippiieennttccaannoonniiccaallmmaappss
              Address  mapping  lookup table for envelope and header recipient
              addresses.

       sseennddeerrccaannoonniiccaallmmaappss
              Address mapping lookup table  for  envelope  and  header  sender
              addresses.

       pprrooppaaggaatteeuunnmmaattcchheeddeexxtteennssiioonnss
              A list of address rewriting or forwarding mechanisms that propa-
              gate an address extension  from  the  original  address  to  the
              result.  Specify zero or more of ccaannoonniiccaall, vviirrttuuaall, aalliiaass, ffoorr-
              wwaarrdd, or iinncclluuddee.

       Other parameters of interest:

       iinneettiinntteerrffaacceess
              The network interface addresses that this system  receives  mail
              on.   You  need  to  stop  and start Postfix when this parameter
              changes.

       pprrooxxyyiinntteerrffaacceess
              Other interfaces that this machine receives mail on by way of  a
              proxy agent or network address translator.

       mmaassqquueerraaddeeccllaasssseess
              List of address classes subject to masquerading: zero or more of
              eennvveellooppeesseennddeerr,       eennvveellooppeerreecciippiieenntt,        hheeaaddeerrsseennddeerr,
              hheeaaddeerrrreecciippiieenntt.

       mmaassqquueerraaddeeddoommaaiinnss
              List of domains that hide their subdomain structure.

       mmaassqquueerraaddeeeexxcceeppttiioonnss
              List of user names that are not subject to address masquerading.

       mmyyddeessttiinnaattiioonn
              List of domains that this mail system considers local.

       mmyyoorriiggiinn
              The domain that is appended to locally-posted mail.

       oowwnneerrrreeqquueessttssppeecciiaall
              Give special treatment to oowwnneerr-xxx and xxx-rreeqquueesstt addresses.

SEE ALSO
       cleanup(8), canonicalize and enqueue mail
       postmap(1), Postfix lookup table manager
       postconf(5), configuration parameters
       virtual(5), virtual aliasing

README FILES       Use "ppoossttccoonnff rreeaaddmmeeddiirreeccttoorryy" or "ppoossttccoonnff hhttmmllddiirreeccttoorryy" to  locate
       this information.
       DATABASEREADME, Postfix lookup table overview
       ADDRESSREWRITINGREADME, address rewriting guide

LLIICCEENNSSEE
       The Secure Mailer license must be distributed with this software.

AUTHOR(S)       Wietse Venema
       IBM T.J. Watson Research
       P.O. Box 704
       Yorktown Heights, NY 10598, USA



                                                                  CANONICAL(5)