← Back to branch summary

~ubuntu-branches/ubuntu/saucy/postfix/saucy

« back to all changes in this revision

Viewing changes to html/pgsql_table.5.html

  • Committer: Bazaar Package Importer
  • Author(s): LaMont Jones
  • Date: 2011-02-22 11:20:43 UTC
  • mfrom: (1.1.27 upstream)
  • Revision ID: james.westby@ubuntu.com-20110222112043-c34ht219w3ybrilr
Tags: 2.8.0-2
* a little more lintian cleanup
* Fix missing format strings in smtp-sink.c

Show diffs side-by-side

added added

removed removed

Lines of Context:
html/pgsql_table.5.html
45
45
       readable.  Support for this form  will  be  removed  in  a
46
46
       future Postfix version.
47
47
 
48
 
       Postfix  2.2  has  enhanced query interfaces for MySQL and
49
 
       PostgreSQL, these include  features  previously  available
50
 
       only  in the Postfix LDAP client. In the new interface the
51
 
       SQL query  is  specified  via  a  single  <b>query</b>  parameter
52
 
       (described  in  more  detail  below).   In Postfix 2.1 the
53
 
       parameter  precedence  was,  from   highest   to   lowest,
54
 
       <b>select_function</b>, <b>query</b> and finally <b>select_field</b>, ...
55
 
 
56
 
       With  Postfix  2.2  the <b>query</b> parameter has highest prece-
57
 
       dence, and is used in preference to the  still  supported,
58
 
       but    slated   to   be   phased   out,   <b>select_function</b>,
59
 
       <b>select_field</b>, <b>table</b>, <b>where_field</b> and <b>additional_conditions</b>
60
 
       parameters. To migrate to the new interface set:
 
48
       Normally,  the  SQL  query is specified via a single <b>query</b>
 
49
       parameter (described in more  detail  below).   When  this
 
50
       parameter  is not specified in the map definition, Postfix
 
51
       reverts to an older interface, with the  SQL   query  con-
 
52
       structed   from  the <b>select_function</b>, <b>select_field</b>, <b>table</b>,
 
53
       <b>where_field</b> and <b>additional_conditions</b> parameters.  The old
 
54
       interface  will be gradually phased out. To migrate to the
 
55
       new interface set:
61
56
 
62
57
           <b>query</b> = SELECT <i>select</i><b>_</b><i>function</i>('%s')
63
58
 
64
 
       or  in  the  absence  of <b>select_function</b>, the lower prece-
 
59
       or in the absence of  <b>select_function</b>,  the  lower  prece-
65
60
       dence:
66
61
 
67
62
           <b>query</b> = SELECT <i>select</i><b>_</b><i>field</i>
69
64
               WHERE <i>where</i><b>_</b><i>field</i> = '%s'
70
65
                   <i>additional</i><b>_</b><i>conditions</i>
71
66
 
72
 
       Use the value, not the name,  of  each  legacy  parameter.
73
 
       Note  that the <b>additional_conditions</b> parameter is optional
 
67
       Use  the  value,  not  the name, of each legacy parameter.
 
68
       Note that the <b>additional_conditions</b> parameter is  optional
74
69
       and if not empty, will always start with <b>AND</b>.
75
70
 
76
71
<b>LIST MEMBERSHIP</b>
77
72
       When using SQL to store lists such as $<a href="postconf.5.html#mynetworks">mynetworks</a>, $<a href="postconf.5.html#mydestination">mydes</a>-
78
 
       <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
79
 
       is important to understand that the table must store  each
80
 
       list  member  as a separate key. The table lookup verifies
81
 
       the *existence* of the  key.  See  "Postfix  lists  versus
82
 
       tables"  in the <a href="DATABASE_README.html">DATABASE_README</a> document for a discussion.
 
73
       <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
 
74
       is  important to understand that the table must store each
 
75
       list member as a separate key. The table  lookup  verifies
 
76
       the  *existence*  of  the  key.  See "Postfix lists versus
 
77
       tables" in the <a href="DATABASE_README.html">DATABASE_README</a> document for a  discussion.
83
78
 
84
 
       Do NOT create tables that return the full list of  domains
85
 
       in  $<a href="postconf.5.html#mydestination">mydestination</a> or $<a href="postconf.5.html#relay_domains">relay_domains</a> etc., or IP addresses
 
79
       Do  NOT create tables that return the full list of domains
 
80
       in $<a href="postconf.5.html#mydestination">mydestination</a> or $<a href="postconf.5.html#relay_domains">relay_domains</a> etc., or IP  addresses
86
81
       in $<a href="postconf.5.html#mynetworks">mynetworks</a>.
87
82
 
88
83
       DO create tables with each matching item as a key and with
89
 
       an  arbitrary value. With SQL databases it is not uncommon
 
84
       an arbitrary value. With SQL databases it is not  uncommon
90
85
       to return the key itself or a constant value.
91
86
 
92
87
<b>PGSQL PARAMETERS</b>
93
 
       <b>hosts</b>  The hosts that Postfix will try to connect  to  and
 
88
       <b>hosts</b>  The  hosts  that Postfix will try to connect to and
94
89
              query from.  Specify <i>unix:</i> for UNIX-domain sockets,
95
90
              <i>inet:</i> for TCP connections (default).  Example:
96
91
                  hosts = host1.some.domain host2.some.domain
97
92
                  hosts = unix:/file/name
98
93
 
99
 
              The hosts are tried in random order, with all  con-
 
94
              The  hosts are tried in random order, with all con-
100
95
              nections  over  UNIX  domain  sockets  being  tried
101
 
              before those over TCP.  The connections  are  auto-
102
 
              matically  closed  after  being  idle  for  about 1
 
96
              before  those  over TCP.  The connections are auto-
 
97
              matically closed  after  being  idle  for  about  1
103
98
              minute, and are re-opened as necessary.
104
99
 
105
100
              NOTE: the <i>unix:</i> and <i>inet:</i> prefixes are accepted for
106
 
              backwards  compatibility  reasons, but are actually
 
101
              backwards compatibility reasons, but  are  actually
107
102
              ignored.  The PostgreSQL client library will always
108
103
              try to connect to an UNIX socket if the name starts
109
 
              with a slash, and will try a TCP connection  other-
 
104
              with  a slash, and will try a TCP connection other-
110
105
              wise.
111
106
 
112
107
       <b>user, password</b>
113
 
              The  user  name  and password to log into the pgsql
 
108
              The user name and password to log  into  the  pgsql
114
109
              server.  Example:
115
110
                  user = someone
116
111
                  password = some_password
123
118
              trying to resolve, e.g.
124
119
                  query = SELECT replacement FROM aliases WHERE mailbox = '%s'
125
120
 
126
 
              This parameter supports the  following  '%'  expan-
 
121
              This  parameter  supports  the following '%' expan-
127
122
              sions:
128
123
 
129
124
              <b>%%</b>     This is replaced by a literal '%' character.
130
125
                     (Postfix 2.2 and later)
131
126
 
132
 
              <b>%s</b>     This is replaced  by  the  input  key.   SQL
133
 
                     quoting  is used to make sure that the input
134
 
                     key does not add unexpected  metacharacters.
 
127
              <b>%s</b>     This  is  replaced  by  the  input key.  SQL
 
128
                     quoting is used to make sure that the  input
 
129
                     key  does not add unexpected metacharacters.
135
130
 
136
131
              <b>%u</b>     When the input key is an address of the form
137
132
                     user@domain,  <b>%u</b>  is  replaced  by  the  SQL
138
 
                     quoted  local  part  of the address.  Other-
139
 
                     wise, <b>%u</b> is replaced by  the  entire  search
140
 
                     string.   If  the  localpart  is  empty, the
141
 
                     query is suppressed and returns no  results.
 
133
                     quoted local part of  the  address.   Other-
 
134
                     wise,  <b>%u</b>  is  replaced by the entire search
 
135
                     string.  If  the  localpart  is  empty,  the
 
136
                     query  is suppressed and returns no results.
142
137
 
143
138
              <b>%d</b>     When the input key is an address of the form
144
139
                     user@domain,  <b>%d</b>  is  replaced  by  the  SQL
145
 
                     quoted  domain  part of the address.  Other-
 
140
                     quoted domain part of the  address.   Other-
146
141
                     wise, the query is suppressed and returns no
147
142
                     results.
148
143
 
149
144
              <b>%[SUD]</b> The  upper-case  equivalents  of  the  above
150
 
                     expansions behave  in  the  <b>query</b>  parameter
 
145
                     expansions  behave  in  the  <b>query</b> parameter
151
146
                     identically  to  their  lower-case  counter-
152
147
                     parts.   With  the  <b>result_format</b>  parameter
153
148
                     (see  below),  they  expand  the  input  key
154
149
                     rather than the result value.
155
150
 
156
 
                     The above  %S,  %U  and  %D  expansions  are
 
151
                     The  above  %S,  %U  and  %D  expansions are
157
152
                     available with Postfix 2.2 and later
158
153
 
159
 
              <b>%[1-9]</b> The  patterns %1, %2, ... %9 are replaced by
 
154
              <b>%[1-9]</b> The patterns %1, %2, ... %9 are replaced  by
160
155
                     the corresponding most significant component
161
 
                     of  the input key's domain. If the input key
 
156
                     of the input key's domain. If the input  key
162
157
                     is <i>user@mail.example.com</i>, then %1 is <b>com</b>, %2
163
 
                     is  <b>example</b> and %3 is <b>mail</b>. If the input key
 
158
                     is <b>example</b> and %3 is <b>mail</b>. If the input  key
164
159
                     is  unqualified  or  does  not  have  enough
165
 
                     domain  components to satisfy all the speci-
166
 
                     fied patterns, the query is  suppressed  and
 
160
                     domain components to satisfy all the  speci-
 
161
                     fied  patterns,  the query is suppressed and
167
162
                     returns no results.
168
163
 
169
 
                     The  above  %1, ... %9 expansions are avail-
 
164
                     The above %1, ... %9 expansions  are  avail-
170
165
                     able with Postfix 2.2 and later
171
166
 
172
 
              The <b>domain</b> parameter  described  below  limits  the
173
 
              input  keys  to addresses in matching domains. When
174
 
              the <b>domain</b> parameter is non-empty, SQL queries  for
175
 
              unqualified  addresses or addresses in non-matching
 
167
              The  <b>domain</b>  parameter  described  below limits the
 
168
              input keys to addresses in matching  domains.  When
 
169
              the  <b>domain</b> parameter is non-empty, SQL queries for
 
170
              unqualified addresses or addresses in  non-matching
176
171
              domains are suppressed and return no results.
177
172
 
178
 
              The precedence of this parameter has  changed  with
179
 
              Postfix  2.2, in prior releases the precedence was,
180
 
              from highest  to  lowest,  <b>select_function</b>,  <b>query</b>,
 
173
              The  precedence  of this parameter has changed with
 
174
              Postfix 2.2, in prior releases the precedence  was,
 
175
              from  highest  to  lowest,  <b>select_function</b>, <b>query</b>,
181
176
              <b>select_field</b>, ...
182
177
 
183
 
              With  Postfix  2.2  the <b>query</b> parameter has highest
 
178
              With Postfix 2.2 the <b>query</b>  parameter  has  highest
184
179
              precedence, see COMPATIBILITY above.
185
180
 
186
181
              NOTE: DO NOT put quotes around the <b>query</b> parameter.
187
182
 
188
183
       <b>result_format (default: %s</b>)
189
 
              Format  template applied to result attributes. Most
190
 
              commonly used to append (or prepend)  text  to  the
191
 
              result.  This  parameter supports the following '%'
 
184
              Format template applied to result attributes.  Most
 
185
              commonly  used  to  append (or prepend) text to the
 
186
              result. This parameter supports the  following  '%'
192
187
              expansions:
193
188
 
194
189
              <b>%%</b>     This is replaced by a literal '%' character.
195
190
 
196
 
              <b>%s</b>     This  is replaced by the value of the result
197
 
                     attribute.  When  result  is  empty  it   is
 
191
              <b>%s</b>     This is replaced by the value of the  result
 
192
                     attribute.   When  result  is  empty  it  is
198
193
                     skipped.
199
194
 
200
 
              <b>%u</b>     When   the  result  attribute  value  is  an
 
195
              <b>%u</b>     When  the  result  attribute  value  is   an
201
196
                     address  of  the  form  user@domain,  <b>%u</b>  is
202
 
                     replaced  by  the local part of the address.
 
197
                     replaced by the local part of  the  address.
203
198
                     When the result has an empty localpart it is
204
199
                     skipped.
205
200
 
206
 
              <b>%d</b>     When  a result attribute value is an address
207
 
                     of the form user@domain, <b>%d</b> is  replaced  by
 
201
              <b>%d</b>     When a result attribute value is an  address
 
202
                     of  the  form user@domain, <b>%d</b> is replaced by
208
203
                     the domain part of the attribute value. When
209
204
                     the result is unqualified it is skipped.
210
205
 
211
206
              <b>%[SUD1-9]</b>
212
 
                     The upper-case and decimal digit  expansions
 
207
                     The  upper-case and decimal digit expansions
213
208
                     interpolate  the  parts  of  the  input  key
214
 
                     rather than the result.  Their  behavior  is
215
 
                     identical  to that described with <b>query</b>, and
216
 
                     in fact because the input key  is  known  in
217
 
                     advance,  queries whose key does not contain
218
 
                     all the information specified in the  result
219
 
                     template   are   suppressed  and  return  no
 
209
                     rather  than  the  result. Their behavior is
 
210
                     identical to that described with <b>query</b>,  and
 
211
                     in  fact  because  the input key is known in
 
212
                     advance, queries whose key does not  contain
 
213
                     all  the information specified in the result
 
214
                     template  are  suppressed  and   return   no
220
215
                     results.
221
216
 
222
217
              For  example,  using  "result_format  =  <a href="smtp.8.html">smtp</a>:[%s]"
223
218
              allows one to use a mailHost attribute as the basis
224
 
              of a <a href="transport.5.html">transport(5)</a> table. After applying the  result
225
 
              format,  multiple  values are concatenated as comma
226
 
              separated strings. The expansion_limit and  parame-
 
219
              of  a <a href="transport.5.html">transport(5)</a> table. After applying the result
 
220
              format, multiple values are concatenated  as  comma
 
221
              separated  strings. The expansion_limit and parame-
227
222
              ter explained below allows one to restrict the num-
228
 
              ber of values in the result,  which  is  especially
 
223
              ber  of  values  in the result, which is especially
229
224
              useful for maps that must return at most one value.
230
225
 
231
 
              The default value <b>%s</b>  specifies  that  each  result
 
226
              The  default  value  <b>%s</b>  specifies that each result
232
227
              value should be used as is.
233
228
 
234
 
              This  parameter  is  available with Postfix 2.2 and
 
229
              This parameter is available with  Postfix  2.2  and
235
230
              later.
236
231
 
237
232
              NOTE: DO NOT put quotes around the result format!
238
233
 
239
234
       <b>domain (default: no domain list)</b>
240
 
              This is a list of domain names, paths to files,  or
241
 
              dictionaries.  When specified, only fully qualified
242
 
              search keys with  a  *non-empty*  localpart  and  a
243
 
              matching  domain  are  eligible  for lookup: 'user'
244
 
              lookups, bare domain lookups and "@domain"  lookups
245
 
              are  not  performed.  This can significantly reduce
 
235
              This  is a list of domain names, paths to files, or
 
236
              dictionaries. When specified, only fully  qualified
 
237
              search  keys  with  a  *non-empty*  localpart and a
 
238
              matching domain are  eligible  for  lookup:  'user'
 
239
              lookups,  bare domain lookups and "@domain" lookups
 
240
              are not performed. This  can  significantly  reduce
246
241
              the query load on the PostgreSQL server.
247
242
                  domain = postfix.org, hash:/etc/postfix/searchdomains
248
243
 
249
244
              It is best not to use SQL to store the domains eli-
250
245
              gible for SQL lookups.
251
246
 
252
 
              This  parameter  is  available with Postfix 2.2 and
 
247
              This parameter is available with  Postfix  2.2  and
253
248
              later.
254
249
 
255
 
              NOTE: DO NOT define  this  parameter  for  <a href="local.8.html">local(8)</a>
 
250
              NOTE:  DO  NOT  define  this parameter for <a href="local.8.html">local(8)</a>
256
251
              aliases, because the input keys are always unquali-
257
252
              fied.
258
253
 
259
254
       <b>expansion_limit (default: 0)</b>
260
 
              A limit on the  total  number  of  result  elements
261
 
              returned  (as  a  comma separated list) by a lookup
262
 
              against the map.  A setting of  zero  disables  the
263
 
              limit.  Lookups  fail with a temporary error if the
264
 
              limit is exceeded.  Setting the limit to 1  ensures
 
255
              A  limit  on  the  total  number of result elements
 
256
              returned (as a comma separated list)  by  a  lookup
 
257
              against  the  map.   A setting of zero disables the
 
258
              limit. Lookups fail with a temporary error  if  the
 
259
              limit  is exceeded.  Setting the limit to 1 ensures
265
260
              that lookups do not return multiple values.
266
261
 
267
262
<b>OBSOLETE QUERY INTERFACES</b>
268
 
       This  section  describes  query interfaces that are depre-
269
 
       cated as of Postfix 2.2.  Please migrate to the new  <b>query</b>
270
 
       interface  as  the  old interfaces are slated to be phased
 
263
       This section describes query interfaces  that  are  depre-
 
264
       cated  as of Postfix 2.2.  Please migrate to the new <b>query</b>
 
265
       interface as the old interfaces are slated  to  be  phased
271
266
       out.
272
267
 
273
268
       <b>select_function</b>
274
 
              This parameter specifies a database function  name.
 
269
              This  parameter specifies a database function name.
275
270
              Example:
276
271
                  select_function = my_lookup_user_alias
277
272
 
278
273
              This is equivalent to:
279
274
                  query = SELECT my_lookup_user_alias('%s')
280
275
 
281
 
              This  parameter  overrides the legacy table-related
282
 
              fields (described  below).  With  Postfix  versions
283
 
              prior  to  2.2, it also overrides the <b>query</b> parame-
 
276
              This parameter overrides the  legacy  table-related
 
277
              fields  (described  below).  With  Postfix versions
 
278
              prior to 2.2, it also overrides the  <b>query</b>  parame-
284
279
              ter. Starting with Postfix 2.2, the <b>query</b> parameter
285
 
              has  highest  precedence,  and  the <b>select_function</b>
 
280
              has highest  precedence,  and  the  <b>select_function</b>
286
281
              parameter is deprecated.
287
282
 
288
 
       The following parameters (with lower precedence  than  the
289
 
       <b>select_function</b>  interface described above) can be used to
 
283
       The  following  parameters (with lower precedence than the
 
284
       <b>select_function</b> interface described above) can be used  to
290
285
       build the SQL select statement as follows:
291
286
 
292
287
           SELECT [<b>select_field</b>]
294
289
           WHERE [<b>where_field</b>] = '%s'
295
290
                 [<b>additional_conditions</b>]
296
291
 
297
 
       The specifier %s is  replaced  with  each  lookup  by  the
298
 
       lookup  key and is escaped so if it contains single quotes
299
 
       or other odd characters, it will not cause a parse  error,
 
292
       The  specifier  %s  is  replaced  with  each lookup by the
 
293
       lookup key and is escaped so if it contains single  quotes
 
294
       or  other odd characters, it will not cause a parse error,
300
295
       or worse, a security problem.
301
296
 
302
 
       Starting  with Postfix 2.2, this interface is obsoleted by
303
 
       the more  general  <b>query</b>  interface  described  above.  If
304
 
       higher  precedence the <b>query</b> or <b>select_function</b> parameters
 
297
       Starting with Postfix 2.2, this interface is obsoleted  by
 
298
       the  more  general  <b>query</b>  interface  described  above. If
 
299
       higher precedence the <b>query</b> or <b>select_function</b>  parameters
305
300
       described above are defined, the parameters described here
306
301
       are ignored.
307
302
 
325
320
       <a href="postconf.5.html">postconf(5)</a>, configuration parameters
326
321
       <a href="ldap_table.5.html">ldap_table(5)</a>, LDAP lookup tables
327
322
       <a href="mysql_table.5.html">mysql_table(5)</a>, MySQL lookup tables
 
323
       <a href="sqlite_table.5.html">sqlite_table(5)</a>, SQLite lookup tables
328
324
 
329
325
<b>README FILES</b>
330
326
       <a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview
331
327
       <a href="PGSQL_README.html">PGSQL_README</a>, Postfix PostgreSQL client guide
332
328
 
333
329
<b>LICENSE</b>
334
 
       The Secure Mailer license must be  distributed  with  this
 
330
       The  Secure  Mailer  license must be distributed with this
335
331
       software.
336
332
 
337
333
<b>HISTORY</b>