From f55b2b19ea135c7f9a86157c1b99d9eeb62a3a8a Mon Sep 17 00:00:00 2001 From: rpaulo Date: Thu, 18 Aug 2005 21:00:20 +0000 Subject: Import Postfix-2.2.5. --- gnu/dist/postfix/html/pgsql_table.5.html | 306 +++++++++++++++++++++++-------- 1 file changed, 232 insertions(+), 74 deletions(-) (limited to 'gnu/dist/postfix/html/pgsql_table.5.html') diff --git a/gnu/dist/postfix/html/pgsql_table.5.html b/gnu/dist/postfix/html/pgsql_table.5.html index 02d71f97bff..13152c9a5e1 100644 --- a/gnu/dist/postfix/html/pgsql_table.5.html +++ b/gnu/dist/postfix/html/pgsql_table.5.html @@ -4,7 +4,7 @@ Postfix manual - pgsql_table(5)
-PGSQL_TABLE(5)                                     PGSQL_TABLE(5)
+PGSQL_TABLE(5)                                                  PGSQL_TABLE(5)
 
 NAME
        pgsql_table - Postfix PostgreSQL client configuration
@@ -29,7 +29,7 @@ PGSQL_TABLE(5)                                     PGSQL_TABLE(5)
        as  the  Postfix main.cf file, and can specify the parame-
        ters described below.
 
-ALTERNATIVE CONFIGURATION
+BACKWARDS COMPATIBILITY
        For compatibility with other Postfix lookup tables,  Post-
        greSQL  parameters  can  also  be  defined in main.cf.  In
        order to do that, specify as PostgreSQL source a name that
@@ -45,44 +45,72 @@ PGSQL_TABLE(5)                                     PGSQL_TABLE(5)
        readable.  Support for this form  will  be  removed  in  a
        future Postfix version.
 
+       Postfix  2.2  has  enhanced query interfaces for MySQL and
+       PostgreSQL, these include  features  previously  available
+       only  in the Postfix LDAP client. In the new interface the
+       SQL query  is  specified  via  a  single  query  parameter
+       (described  in  more  detail  below).   In Postfix 2.1 the
+       parameter  precedence  was,  from   highest   to   lowest,
+       select_function, query and finally select_field, ...
+
+       With  Postfix  2.2  the query parameter has highest prece-
+       dence, and is used in preference to the  still  supported,
+       but    slated   to   be   phased   out,   select_function,
+       select_field, table, where_field and additional_conditions
+       parameters. To migrate to the new interface set:
+
+           query = SELECT select_function('%s')
+
+       or  in the absence of selection_function, the lower prece-
+       dence:
+
+           query = SELECT select_field
+               FROM table
+               WHERE where_field = '%s'
+                   additional_conditions
+
+       Use the value, not the name,  of  each  legacy  parameter.
+       Note  that the additional_conditions parameter is optional
+       and if not empty, will always start with AND.
+
 LIST MEMBERSHIP
        When using SQL to store lists such as $mynetworks, $mydes-
-       tination, $relay_domains, $local_recipient_maps, etc.,  it
-       is  important to understand that the table must store each
-       list member as a separate key. The table  lookup  verifies
-       the  *existence*  of  the  key.  See "Postfix lists versus
-       tables" in the DATABASE_README document for a  discussion.
-
-       Do  NOT create tables that return the full list of domains
-       in $mydestination or $relay_domains etc., or IP  addresses
+       tination,  $relay_domains, $local_recipient_maps, etc., it
+       is important to understand that the table must store  each
+       list  member  as a separate key. The table lookup verifies
+       the *existence* of the  key.  See  "Postfix  lists  versus
+       tables"  in the DATABASE_README document for a discussion.
+
+       Do NOT create tables that return the full list of  domains
+       in  $mydestination or $relay_domains etc., or IP addresses
        in $mynetworks.
 
        DO create tables with each matching item as a key and with
-       an arbitrary value. With SQL databases it is not  uncommon
+       an  arbitrary value. With SQL databases it is not uncommon
        to return the key itself or a constant value.
 
 PGSQL PARAMETERS
-       hosts  The  hosts  that Postfix will try to connect to and
+       hosts  The hosts that Postfix will try to connect  to  and
               query from.  Specify unix: for UNIX-domain sockets,
               inet: for TCP connections (default).  Example:
                   hosts = host1.some.domain host2.some.domain
                   hosts = unix:/file/name
 
-              The  hosts are tried in random order, with all con-
+              The hosts are tried in random order, with all  con-
               nections  over  UNIX  domain  sockets  being  tried
-              before  those  over TCP.  The connections are auto-
-              matically closed  after  being  idle  for  about  1
+              before those over TCP.  The connections  are  auto-
+              matically  closed  after  being  idle  for  about 1
               minute, and are re-opened as necessary.
 
               NOTE: the unix: and inet: prefixes are accepted for
-              backwards compatibility reasons, but  are  actually
+              backwards  compatibility  reasons, but are actually
               ignored.  The PostgreSQL client library will always
               try to connect to an UNIX socket if the name starts
-              with  a slash, and will try a TCP connection other-
+              with a slash, and will try a TCP connection  other-
               wise.
 
        user, password
-              The user name and password to log  into  the  pgsql
+              The  user  name  and password to log into the pgsql
               server.  Example:
                   user = someone
                   password = some_password
@@ -90,58 +118,155 @@ PGSQL_TABLE(5)                                     PGSQL_TABLE(5)
        dbname The database name on the servers. Example:
                   dbname = customer_database
 
-       The  following  parameters can be used to fill in a SELECT
-       template statement of the form:
-           select [select_field] from [table] where
-               [where_field] = '$lookup' [additional_conditions]
-
-       $lookup contains the search string, and is escaped  so  if
-       it contains single quotes or other odd characters, it will
-       not cause a parse error, or worse, a security problem.
-
-       select_field
-              The SQL "select" parameter. Example:
-                  select_field = forw_addr
-
-       table  The SQL "select .. from" table name. Example:
-                  table = mxaliases
-
-       where_field
-              The SQL "select .. where" parameter. Example:
-                  where_field = alias
-
-       additional_conditions
-              Additional conditions to the SQL query. Example:
-                  additional_conditions = and status = 'paid'
-
-       The following parameters  provide  ways  to  override  the
-       default  SELECT  statement.   Setting  them  will instruct
-       Postfix  to  ignore   the   above   table,   select_field,
-       where_field and additional_conditions parameters:
+       query  The SQL query template used to search the database,
+              where %s is a substitute for the address Postfix is
+              trying to resolve, e.g.
+                  query = SELECT replacement FROM  aliases  WHERE
+              mailbox = '%s'
 
-       query  This  parameter  specifies  a  complete  SQL query.
-              Example:
-                  query = select forw_addr from mxaliases where
-                      alias = '%s' and status = 'paid'
-
-              This parameter supports the  following  '%'  expan-
+              This  parameter  supports  the following '%' expan-
               sions:
 
-              %s     This  is  replaced by the input key. Quoting
-                     is used to make sure that the input key does
-                     not add unexpected metacharacters.
+              %%     This is replaced by a literal '%' character.
+                     (Postfix 2.2 and later)
+
+              %s     This  is  replaced  by  the  input key.  SQL
+                     quoting is used to make sure that the  input
+                     key  does not add unexpected metacharacters.
 
               %u     When the input key is an address of the form
-                     user@domain, %u is replaced  by  the  quoted
-                     local  part of the address.  If no domain is
-                     specified, %u  is  replaced  by  the  entire
-                     search string.
+                     user@domain,  %u  is  replaced  by  the  SQL
+                     quoted local part of  the  address.   Other-
+                     wise,  %u  is  replaced by the entire search
+                     string.  If  the  localpart  is  empty,  the
+                     query  is suppressed and returns no results.
 
               %d     When the input key is an address of the form
-                     user@domain, %d is replaced  by  the  quoted
-                     domain  part of the address.  When the input
-                     key has no domain qualifier, %d is  replaced
-                     by the entire search string.
+                     user@domain,  %d  is  replaced  by  the  SQL
+                     quoted domain part of the  address.   Other-
+                     wise, the query is suppressed and returns no
+                     results.
+
+              %[SUD] The  upper-case  equivalents  of  the  above
+                     expansions  behave  in  the  query parameter
+                     identically  to  their  lower-case  counter-
+                     parts.   With  the  result_format  parameter
+                     (see  below),  they  expand  the  input  key
+                     rather than the result value.
+
+                     The  above  %S,  %U  and  %D  expansions are
+                     available with Postfix 2.2 and later
+
+              %[1-9] The patterns %1, %2, ... %9 are replaced  by
+                     the corresponding most significant component
+                     of the input key's domain. If the input  key
+                     is user@mail.example.com, then %1 is com, %2
+                     is example and %3 is mail. If the input  key
+                     is  unqualified  or  does  not  have  enough
+                     domain components to satisfy all the  speci-
+                     fied  patterns,  the query is suppressed and
+                     returns no results.
+
+                     The above %1, ... %9 expansions  are  avail-
+                     able with Postfix 2.2 and later
+
+              The  domain  parameter  described  below limits the
+              input keys to addresses in matching  domains.  When
+              the  domain parameter is non-empty, SQL queries for
+              unqualified addresses or addresses in  non-matching
+              domains are suppressed and return no results.
+
+              The  precedence  of this parameter has changed with
+              Postfix 2.2, in prior releases the precedence  was,
+              from  highest  to  lowest,  select_function, query,
+              select_field, ...
+
+              With Postfix 2.2 the query  parameter  has  highest
+              precedence, see COMPATIBILITY above.
+
+              NOTE: DO NOT put quotes around the query parameter.
+
+       result_format (default: %s)
+              Format template applied to result attributes.  Most
+              commonly  used  to  append (or prepend) text to the
+              result. This parameter supports the  following  '%'
+              expansions:
+
+              %%     This is replaced by a literal '%' character.
+
+              %s     This is replaced by the value of the  result
+                     attribute.   When  result  is  empty  it  is
+                     skipped.
+
+              %u     When  the  result  attribute  value  is   an
+                     address  of  the  form  user@domain,  %u  is
+                     replaced by the local part of  the  address.
+                     When the result has an empty localpart it is
+                     skipped.
+
+              %d     When a result attribute value is an  address
+                     of  the  form user@domain, %d is replaced by
+                     the domain part of the attribute value. When
+                     the result is unqualified it is skipped.
+
+              %[SUD1-9]
+                     The  upper-case and decimal digit expansions
+                     interpolate  the  parts  of  the  input  key
+                     rather  than  the  result. Their behavior is
+                     identical to that described with query,  and
+                     in  fact  because  the input key is known in
+                     advance, queries whose key does not  contain
+                     all  the information specified in the result
+                     template  are  suppressed  and   return   no
+                     results.
+
+              For  example,  using  "result_format  =  smtp:[%s]"
+              allows one to use a mailHost attribute as the basis
+              of  a transport(5) table. After applying the result
+              format, multiple values are concatenated  as  comma
+              separated  strings. The expansion_limit and parame-
+              ter explained below allows one to restrict the num-
+              ber  of  values  in the result, which is especially
+              useful for maps that must return at most one value.
+
+              The  default  value  %s  specifies that each result
+              value should be used as is.
+
+              This parameter is available with  Postfix  2.2  and
+              later.
+
+              NOTE: DO NOT put quotes around the result format!
+
+       domain (default: no domain list)
+              This  is a list of domain names, paths to files, or
+              dictionaries. When specified, only fully  qualified
+              search  keys  with  a  *non-empty*  localpart and a
+              matching domain are  eligible  for  lookup:  'user'
+              lookups,  bare domain lookups and "@domain" lookups
+              are not performed. This  can  significantly  reduce
+              the query load on the PostgreSQL server.
+                  domain = postfix.org, hash:/etc/postfix/search-
+              domains
+
+              It is best not to use SQL to store the domains eli-
+              gible for SQL lookups.
+
+              This  parameter  is  available with Postfix 2.2 and
+              later.
+
+              NOTE: DO NOT define  this  parameter  for  local(8)
+              aliases, because the input keys are always unquali-
+              fied.
+
+       expansion_limit (default: 0)
+              A limit on the  total  number  of  result  elements
+              returned  (as  a  comma separated list) by a lookup
+              against the map.  A setting of  zero  disables  the
+              limit.  Lookups  fail with a temporary error if the
+              limit is exceeded.  Setting the limit to 1  ensures
+              that lookups do not return multiple values.
+
+       Pre-Postfix 2.2 legacy interfaces:
 
        select_function
               This  parameter specifies a database function name.
@@ -149,18 +274,51 @@ PGSQL_TABLE(5)                                     PGSQL_TABLE(5)
                   select_function = my_lookup_user_alias
 
               This is equivalent to:
-                  query = select my_lookup_user_alias('%s')
+                  query = SELECT my_lookup_user_alias('%s')
+
+              This parameter overrides the  legacy  table-related
+              fields  (described  below).  With  Postfix versions
+              prior to 2.2, it also overrides the  query  parame-
+              ter. Starting with Postfix 2.2, the query parameter
+              has highest precedence, and this parameter is  dep-
+              recated.  Please migrate to the new query interface
+              as this interface is slated to be phased out.
+
+       The following parameters (with lower precedence  than  the
+       select_function  interface described above) can be used to
+       build the SQL select statement as follows:
+
+           SELECT [select_field]
+           FROM [table]
+           WHERE [where_field] = '%s'
+                 [additional_conditions]
+
+       The specifier %s is  replaced  with  each  lookup  by  the
+       lookup  key and is escaped so if it contains single quotes
+       or other odd characters, it will not cause a parse  error,
+       or worse, a security problem.
+
+       Starting  with Postfix 2.2, this interface is obsoleted by
+       the more  general  query  interface  described  above.  If
+       higher  precedence the query or select_function parameters
+       described above are defined, these parameters are ignored.
+       Please  migrate  to the new query interface as this inter-
+       face is slated to be phased out.
 
-              and overrides both  the  query  parameter  and  the
-              table-related fields above.
+       select_field
+              The SQL "select" parameter. Example:
+                  select_field = forw_addr
 
-              As  of  June 2002, if the function returns a single
-              row and a single column AND  that  value  is  NULL,
-              then  the  result will be treated as if the key was
-              not in the dictionary.
+       table  The SQL "select .. from" table name. Example:
+                  table = mxaliases
 
-              Future versions  will  allow  functions  to  return
-              result sets.
+       where_field
+              The SQL "select .. where" parameter. Example:
+                  where_field = alias
+
+       additional_conditions
+              Additional conditions to the SQL query. Example:
+                  additional_conditions = AND status = 'paid'
 
 SEE ALSO
        postmap(1), Postfix lookup table manager
@@ -173,7 +331,7 @@ PGSQL_TABLE(5)                                     PGSQL_TABLE(5)
        PGSQL_README, Postfix PostgreSQL client guide
 
 LICENSE
-       The Secure Mailer license must be  distributed  with  this
+       The  Secure  Mailer  license must be distributed with this
        software.
 
 HISTORY
@@ -193,5 +351,5 @@ PGSQL_TABLE(5)                                     PGSQL_TABLE(5)
        P.O. BOX 1-764
        RO-014700 Bucharest, ROMANIA
 
-                                                   PGSQL_TABLE(5)
+                                                                PGSQL_TABLE(5)
 
-- cgit