1<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 "https://www.w3.org/TR/html4/loose.dtd"> 3<html> <head> 4<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 5<link rel='stylesheet' type='text/css' href='postfix-doc.css'> 6<title> Postfix manual - mongodb_table(5) </title> 7</head> <body> <pre> 8MONGODB_TABLE(5) MONGODB_TABLE(5) 9 10<b><a name="name">NAME</a></b> 11 mongodb_table - Postfix MongoDB client configuration 12 13<b><a name="synopsis">SYNOPSIS</a></b> 14 <b>postmap -q "</b><i>string</i><b>" <a href="mongodb_table.5.html">mongodb</a>:/etc/postfix/</b><i>filename</i> 15 16 <b>postmap -q - <a href="mongodb_table.5.html">mongodb</a>:/etc/postfix/</b><i>filename</i> <<i>inputfile</i> 17 18<b><a name="description">DESCRIPTION</a></b> 19 The Postfix mail system uses optional tables for address rewriting or 20 mail routing. These tables are usually in <b>dbm</b> or <b>db</b> format. 21 22 Alternatively, lookup tables can be specified as MongoDB databases. In 23 order to use MongoDB lookups, define a MongoDB source as a lookup table 24 in <a href="postconf.5.html">main.cf</a>, for example: 25 <a href="postconf.5.html#alias_maps">alias_maps</a> = <a href="mongodb_table.5.html">mongodb</a>:/etc/postfix/mongodb-aliases.cf 26 27 In this example, the file /etc/postfix/mongodb-aliases.cf has the same 28 format as the Postfix <a href="postconf.5.html">main.cf</a> file, and can specify the parameters 29 described below. It is also possible to have the configuration in 30 <a href="postconf.5.html">main.cf</a>; see "OBSOLETE MAIN.CF PARAMETERS" below. 31 32 It is strongly recommended to use <a href="proxymap.8.html">proxy</a>:mongodb, in order to reduce the 33 number of database connections. For example: 34 <a href="postconf.5.html#alias_maps">alias_maps</a> = <a href="proxymap.8.html">proxy</a>:<a href="mongodb_table.5.html">mongodb</a>:/etc/postfix/mongodb-aliases.cf 35 36 Note: when using <a href="proxymap.8.html">proxy</a>:<a href="mongodb_table.5.html">mongodb</a>:/<i>file</i>, the file must be readable by the 37 unprivileged postfix user (specified with the Postfix <a href="postconf.5.html#mail_owner">mail_owner</a> con- 38 figuration parameter). 39 40<b><a name="mongodb_parameters">MONGODB PARAMETERS</a></b> 41 <b>uri</b> The URI of mongo server/cluster that Postfix will try to connect 42 to and query from. Please see 43 <a href="https://www.mongodb.com/docs/manual/reference/connection-string/">https://www.mongodb.com/docs/manual/reference/connection-string/</a> 44 45 Example: 46 uri = mongodb+srv://user:pass@loclhost:27017/mail 47 48 <b>dbname</b> Name of the database to read the information from. Example: 49 dbname = mail 50 51 <b>collection</b> 52 Name of the collection (table) to read the information from. 53 Example: 54 collection = mailbox 55 56 <b>query_filter</b> 57 The MongoDB query template used to search the database, where <b>%s</b> 58 is a substitute for the email address that Postfix is trying to 59 resolve. Please see: 60 <a href="https://www.mongodb.com/docs/manual/tutorial/query-documents/">https://www.mongodb.com/docs/manual/tutorial/query-documents/</a> 61 62 Example: 63 query_filter = {"$or": [{"username": "%s"}, {"alias.address": "%s"}], "active": 1} 64 65 This parameter supports the following '%' expansions: 66 67 <b>%%</b> This is replaced by a literal '%' character. 68 69 <b>%s</b> This is replaced by the input key. The %s must appear in 70 quotes, because all Postfix queries are strings contain- 71 ing (parts from) a domain or email address. Postfix makes 72 no numerical queries. 73 74 <b>%u</b> When the input key is an address of the form user@domain, 75 <b>%u</b> is replaced by the local part of the address. Other- 76 wise, <b>%u</b> is replaced by the entire search string. 77 78 <b>%d</b> When the input key is an address of the form user@domain, 79 <b>%d</b> is replaced by the domain part of the address. 80 81 <b>%[1-9]</b> The patterns %1, %2, ... %9 are replaced by the corre- 82 sponding most significant component of the input key's 83 domain. If the input key is <i>user@mail.example.com</i>, then 84 %1 is <b>com</b>, %2 is <b>example</b> and %3 is <b>mail</b>. 85 86 In the above substitutions, characters will be quoted as 87 required by <a href="https://tools.ietf.org/html/rfc4627">RFC 4627</a>. For example, each double quote or back- 88 slash character will be escaped with a backslash characacter. 89 90 <b>projection</b> 91 Advanced MongoDB query projections. Please see: 92 <a href="https://www.mongodb.com/docs/manual/tutorial/project-fields-from-query-results/">https://www.mongodb.com/docs/manual/tutorial/project-fields-from-query-results/</a> 93 94 <b>o</b> If <b>projection</b> is non-empty, then <b>result_attribute</b> must be 95 empty. 96 97 <b>o</b> This implementation can extract information only from 98 result fields that have type <b>string</b> (UTF8), <b>integer</b> 99 (int32, int64) and <b>array</b>. Other result fields will be 100 ignored with a warning. Please see: 101 <a href="https://mongoc.org/libbson/current/bson_type_t.html">https://mongoc.org/libbson/current/bson_type_t.html</a> 102 103 <b>o</b> As with <b>result_attribute</b>, the top-level _id field (type 104 OID) is automatically removed from projection results. 105 106 <b>result_attribute</b> 107 Comma or whitespace separated list with the names of fields to 108 be returned in a lookup result. 109 110 <b>o</b> If <b>result_attribute</b> is non-empty, then <b>projection</b> must be 111 empty. 112 113 <b>o</b> As with <b>projection</b>, the top-level _id field (type OID) is 114 automatically removed from lookup results. 115 116 <b>result_format (default: %s</b>) 117 Format template applied to the result from <b>projection</b> or 118 <b>result_attribute</b>. Most commonly used to append (or prepend) text 119 to the result. This parameter supports the following '%' expan- 120 sions: 121 122 <b>%%</b> This is replaced by a literal '%' character. 123 124 <b>%s</b> This is replaced by the value of the result attribute. 125 When result is empty it is skipped. 126 127 <b>%u</b> When the result attribute value is an address of the form 128 user@domain, <b>%u</b> is replaced by the local part of the 129 address. When the result has an empty localpart it is 130 skipped. 131 132 <b>%d</b> When a result attribute value is an address of the form 133 user@domain, <b>%d</b> is replaced by the domain part of the 134 attribute value. When the result is unqualified it is 135 skipped. 136 137 <b>%[SUD1-9]</b> 138 The upper-case and decimal digit expansions interpolate 139 the parts of the input key rather than the result. Their 140 behavior is identical to that described with <b>query_fil-</b> 141 <b>ter</b>, and in fact because the input key is known in 142 advance, lookups whose key does not contain all the 143 information specified in the result template are sup- 144 pressed and return no results. 145 146 For example, using "result_format = <a href="smtp.8.html">smtp</a>:[%s]" allows one to use 147 a mailHost attribute as the basis of a <a href="transport.5.html">transport(5)</a> table. After 148 applying the result format, multiple values are concatenated as 149 comma separated strings. The expansion_limit parameter explained 150 below allows one to restrict the number of values in the result, 151 which is especially useful for maps that should return a single 152 value. 153 154 The default value <b>%s</b> specifies that each attribute value should 155 be used as is. 156 157 NOTE: DO NOT put quotes around the result format! The result is 158 not a JSON string. 159 160 <b>domain (default: no domain list)</b> 161 This is a list of domain names, paths to files, or "<a href="DATABASE_README.html">type:table</a>" 162 databases. When specified, only fully qualified search keys with 163 a *non-empty* localpart and a matching domain are eligible for 164 lookup: 'user' lookups, bare domain lookups and "@domain" 165 lookups are not performed. This can significantly reduce the 166 query load on the backend database. Example: 167 domain = postfix.org, <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/searchdomains 168 169 <b>expansion_limit (default: 0)</b> 170 A limit on the total number of result elements returned (as a 171 comma separated list) by a lookup against the map. A setting of 172 zero disables the limit. Lookups fail with a temporary error if 173 the limit is exceeded. Setting the limit to 1 ensures that 174 lookups do not return multiple values. 175 176<b>OBSOLETE MAIN.CF PARAMETERS</b> 177 MongoDB parameters can also be defined in <a href="postconf.5.html">main.cf</a>. Specify as MongoDB 178 source a name that doesn't begin with a slash or a dot. The MongoDB 179 parameters will then be accessible as the name you've given the source 180 in its definition, an underscore, and the name of the parameter. For 181 example, if a map is specified as "<a href="mongodb_table.5.html">mongodb</a>:<i>mongodb</i><b>_</b><i>source</i>", the "uri" 182 parameter would be defined in <a href="postconf.5.html">main.cf</a> as "<i>mongodb</i><b>_</b><i>source</i>_uri". 183 184 Note: with this form, passwords are written in <a href="postconf.5.html">main.cf</a>, which is nor- 185 mally world-readable, and '$' in a mongodb parameter setting needs to 186 be written as '$$'. 187 188<b><a name="see_also">SEE ALSO</a></b> 189 <a href="postmap.1.html">postmap(1)</a>, Postfix lookup table maintenance 190 <a href="postconf.5.html">postconf(5)</a>, configuration parameters 191 192<b><a name="readme_files">README FILES</a></b> 193 <a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview 194 <a href="MONGODB_README.html">MONGODB_README</a>, Postfix MONGODB client guide 195 196<b><a name="license">LICENSE</a></b> 197 The Secure Mailer license must be distributed with this software. 198 199<b><a name="history">HISTORY</a></b> 200 MongoDB support was introduced with Postfix version 3.9. 201 202<b>AUTHOR(S)</b> 203 Hamid Maadani (hamid@dexo.tech) 204 Dextrous Technologies, LLC 205 206 Edited by: 207 Wietse Venema 208 porcupine.org 209 210 Based on prior work by: 211 Stephan Ferraro 212 Aionda GmbH 213 214 MONGODB_TABLE(5) 215</pre> </body> </html> 216