diff options
| author | rpaulo <rpaulo@NetBSD.org> | 2005-08-18 21:00:20 +0000 |
|---|---|---|
| committer | rpaulo <rpaulo@NetBSD.org> | 2005-08-18 21:00:20 +0000 |
| commit | f55b2b19ea135c7f9a86157c1b99d9eeb62a3a8a (patch) | |
| tree | 7c1bf3caff811fdce228cb8327ab5cc13fb5be93 /gnu/dist/postfix/html/pgsql_table.5.html | |
| parent | 4851927311343a38254555c132386dc235c24d68 (diff) | |
Import Postfix-2.2.5.
Diffstat (limited to 'gnu/dist/postfix/html/pgsql_table.5.html')
| -rw-r--r-- | gnu/dist/postfix/html/pgsql_table.5.html | 306 |
1 files changed, 232 insertions, 74 deletions
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 @@ <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <title> Postfix manual - pgsql_table(5) </title> </head> <body> <pre> -PGSQL_TABLE(5) PGSQL_TABLE(5) +PGSQL_TABLE(5) PGSQL_TABLE(5) <b>NAME</b> 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. -<b>ALTERNATIVE CONFIGURATION</b> +<b>BACKWARDS COMPATIBILITY</b> 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 <b>query</b> parameter + (described in more detail below). In Postfix 2.1 the + parameter precedence was, from highest to lowest, + <b>select_function</b>, <b>query</b> and finally <b>select_field</b>, ... + + With Postfix 2.2 the <b>query</b> parameter has highest prece- + dence, and is used in preference to the still supported, + but slated to be phased out, <b>select_function</b>, + <b>select_field</b>, <b>table</b>, <b>where_field</b> and <b>additional_conditions</b> + parameters. To migrate to the new interface set: + + <b>query</b> = SELECT <i>select</i><b>_</b><i>function</i>('%s') + + or in the absence of <b>selection_function</b>, the lower prece- + dence: + + <b>query</b> = SELECT <i>select</i><b>_</b><i>field</i> + FROM <i>table</i> + WHERE <i>where</i><b>_</b><i>field</i> = '%s' + <i>additional</i><b>_</b><i>conditions</i> + + Use the value, not the name, of each legacy parameter. + Note that the <b>additional_conditions</b> parameter is optional + and if not empty, will always start with <b>AND</b>. + <b>LIST MEMBERSHIP</b> When using SQL to store lists such as $<a href="postconf.5.html#mynetworks">mynetworks</a>, $<a href="postconf.5.html#mydestination">mydes</a>- - <a href="postconf.5.html#mydestination">tination</a>, $<a href="postconf.5.html#relay_domains">relay_domains</a>, $<a href="postconf.5.html#local_recipient_maps">local_recipient_maps</a>, 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 <a href="DATABASE_README.html">DATABASE_README</a> document for a discussion. - - Do NOT create tables that return the full list of domains - in $<a href="postconf.5.html#mydestination">mydestination</a> or $<a href="postconf.5.html#relay_domains">relay_domains</a> etc., or IP addresses + <a href="postconf.5.html#mydestination">tination</a>, $<a href="postconf.5.html#relay_domains">relay_domains</a>, $<a href="postconf.5.html#local_recipient_maps">local_recipient_maps</a>, 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 <a href="DATABASE_README.html">DATABASE_README</a> document for a discussion. + + Do NOT create tables that return the full list of domains + in $<a href="postconf.5.html#mydestination">mydestination</a> or $<a href="postconf.5.html#relay_domains">relay_domains</a> etc., or IP addresses in $<a href="postconf.5.html#mynetworks">mynetworks</a>. 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. <b>PGSQL PARAMETERS</b> - <b>hosts</b> The hosts that Postfix will try to connect to and + <b>hosts</b> The hosts that Postfix will try to connect to and query from. Specify <i>unix:</i> for UNIX-domain sockets, <i>inet:</i> 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 <i>unix:</i> and <i>inet:</i> 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. <b>user, password</b> - 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) <b>dbname</b> 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 [<b>select_field</b>] from [<b>table</b>] where - [<b>where_field</b>] = '$lookup' [<b>additional_conditions</b>] - - $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. - - <b>select_field</b> - The SQL "select" parameter. Example: - select_field = forw_addr - - <b>table</b> The SQL "select .. from" table name. Example: - table = mxaliases - - <b>where_field</b> - The SQL "select .. where" parameter. Example: - where_field = alias - - <b>additional_conditions</b> - 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 <b>table</b>, <b>select_field</b>, - <b>where_field</b> and <b>additional_conditions</b> parameters: + <b>query</b> The SQL query template used to search the database, + where <b>%s</b> is a substitute for the address Postfix is + trying to resolve, e.g. + query = SELECT replacement FROM aliases WHERE + mailbox = '%s' - <b>query</b> 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: - <b>%s</b> This is replaced by the input key. Quoting - is used to make sure that the input key does - not add unexpected metacharacters. + <b>%%</b> This is replaced by a literal '%' character. + (Postfix 2.2 and later) + + <b>%s</b> This is replaced by the input key. SQL + quoting is used to make sure that the input + key does not add unexpected metacharacters. <b>%u</b> When the input key is an address of the form - user@domain, <b>%u</b> is replaced by the quoted - local part of the address. If no domain is - specified, <b>%u</b> is replaced by the entire - search string. + user@domain, <b>%u</b> is replaced by the SQL + quoted local part of the address. Other- + wise, <b>%u</b> is replaced by the entire search + string. If the localpart is empty, the + query is suppressed and returns no results. <b>%d</b> When the input key is an address of the form - user@domain, <b>%d</b> is replaced by the quoted - domain part of the address. When the input - key has no domain qualifier, <b>%d</b> is replaced - by the entire search string. + user@domain, <b>%d</b> is replaced by the SQL + quoted domain part of the address. Other- + wise, the query is suppressed and returns no + results. + + <b>%[SUD]</b> The upper-case equivalents of the above + expansions behave in the <b>query</b> parameter + identically to their lower-case counter- + parts. With the <b>result_format</b> 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 + + <b>%[1-9]</b> The patterns %1, %2, ... %9 are replaced by + the corresponding most significant component + of the input key's domain. If the input key + is <i>user@mail.example.com</i>, then %1 is <b>com</b>, %2 + is <b>example</b> and %3 is <b>mail</b>. 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 <b>domain</b> parameter described below limits the + input keys to addresses in matching domains. When + the <b>domain</b> 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, <b>select_function</b>, <b>query</b>, + <b>select_field</b>, ... + + With Postfix 2.2 the <b>query</b> parameter has highest + precedence, see COMPATIBILITY above. + + NOTE: DO NOT put quotes around the <b>query</b> parameter. + + <b>result_format (default: %s</b>) + Format template applied to result attributes. Most + commonly used to append (or prepend) text to the + result. This parameter supports the following '%' + expansions: + + <b>%%</b> This is replaced by a literal '%' character. + + <b>%s</b> This is replaced by the value of the result + attribute. When result is empty it is + skipped. + + <b>%u</b> When the result attribute value is an + address of the form user@domain, <b>%u</b> is + replaced by the local part of the address. + When the result has an empty localpart it is + skipped. + + <b>%d</b> When a result attribute value is an address + of the form user@domain, <b>%d</b> is replaced by + the domain part of the attribute value. When + the result is unqualified it is skipped. + + <b>%[SUD1-9]</b> + 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 <b>query</b>, 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 = <a href="smtp.8.html">smtp</a>:[%s]" + allows one to use a mailHost attribute as the basis + of a <a href="transport.5.html">transport(5)</a> 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 <b>%s</b> 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! + + <b>domain (default: no domain list)</b> + 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 <a href="local.8.html">local(8)</a> + aliases, because the input keys are always unquali- + fied. + + <b>expansion_limit (default: 0)</b> + 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: <b>select_function</b> 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 <b>query</b> parame- + ter. Starting with Postfix 2.2, the <b>query</b> parameter + has highest precedence, and this parameter is dep- + recated. Please migrate to the new <b>query</b> interface + as this interface is slated to be phased out. + + The following parameters (with lower precedence than the + <b>select_function</b> interface described above) can be used to + build the SQL select statement as follows: + + SELECT [<b>select_field</b>] + FROM [<b>table</b>] + WHERE [<b>where_field</b>] = '%s' + [<b>additional_conditions</b>] + + 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 <b>query</b> interface described above. If + higher precedence the <b>query</b> or <b>select_function</b> parameters + described above are defined, these parameters are ignored. + Please migrate to the new <b>query</b> interface as this inter- + face is slated to be phased out. - and overrides both the <b>query</b> parameter and the - table-related fields above. + <b>select_field</b> + The SQL "select" parameter. Example: + <b>select_field</b> = 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. + <b>table</b> The SQL "select .. from" table name. Example: + <b>table</b> = mxaliases - Future versions will allow functions to return - result sets. + <b>where_field</b> + The SQL "select .. where" parameter. Example: + <b>where_field</b> = alias + + <b>additional_conditions</b> + Additional conditions to the SQL query. Example: + <b>additional_conditions</b> = AND status = 'paid' <b>SEE ALSO</b> <a href="postmap.1.html">postmap(1)</a>, Postfix lookup table manager @@ -173,7 +331,7 @@ PGSQL_TABLE(5) PGSQL_TABLE(5) <a href="PGSQL_README.html">PGSQL_README</a>, Postfix PostgreSQL client guide <b>LICENSE</b> - The Secure Mailer license must be distributed with this + The Secure Mailer license must be distributed with this software. <b>HISTORY</b> @@ -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) </pre> </body> </html> |
