MONGODB_TABLE(5)                                              MONGODB_TABLE(5)

NAME
       mongodb_table - Postfix MongoDB client configuration

SYNOPSIS
       postmap -q "string" mongodb:/etc/postfix/filename

       postmap -q - mongodb:/etc/postfix/filename <inputfile

DESCRIPTION
       The  Postfix  mail system uses optional tables for address rewriting or
       mail routing. These tables are usually in dbm or db format.

       Alternatively, lookup tables can be specified as MongoDB databases.  In
       order to use MongoDB lookups, define a MongoDB source as a lookup table
       in main.cf, for example:
           alias_maps = mongodb:/etc/postfix/mongodb-aliases.cf

       In this example, the file /etc/postfix/mongodb-aliases.cf has the  same
       format  as  the  Postfix  main.cf  file, and can specify the parameters
       described below. It is also  possible  to  have  the  configuration  in
       main.cf; see "OBSOLETE MAIN.CF PARAMETERS" below.

       It is strongly recommended to use proxy:mongodb, in order to reduce the
       number of database connections. For example:
           alias_maps = proxy:mongodb:/etc/postfix/mongodb-aliases.cf

       Note: when using proxy:mongodb:/file, the file must be readable by  the
       unprivileged  postfix  user (specified with the Postfix mail_owner con-
       figuration parameter).

MONGODB PARAMETERS
       uri    The URI of mongo server/cluster that Postfix will try to connect
              to and query from. Please see
              https://www.mongodb.com/docs/manual/reference/connection-string/

              Example:
                  uri = mongodb+srv://user:pass@loclhost:27017/mail

       dbname Name of the database to read the information from.  Example:
                  dbname = mail

       collection
              Name  of  the  collection  (table) to read the information from.
              Example:
                  collection = mailbox

       query_filter
              The MongoDB query template used to search the database, where %s
              is  a substitute for the email address that Postfix is trying to
              resolve. Please see:
              https://www.mongodb.com/docs/manual/tutorial/query-documents/

              Example:
                  query_filter = {"$or": [{"username": "%s"}, {"alias.address": "%s"}], "active": 1}

              This parameter supports the following '%' expansions:

              %%     This is replaced by a literal '%' character.

              %s     This is replaced by the input key. The %s must appear  in
                     quotes,  because all Postfix queries are strings contain-
                     ing (parts from) a domain or email address. Postfix makes
                     no numerical queries.

              %u     When the input key is an address of the form user@domain,
                     %u is replaced by the local part of the address.   Other-
                     wise, %u is replaced by the entire search string.

              %d     When the input key is an address of the form user@domain,
                     %d is replaced by the domain part of the address.

              %[1-9] The patterns %1, %2, ... %9 are replaced  by  the  corre-
                     sponding  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.

              In  the  above  substitutions,  characters  will  be  quoted  as
              required by RFC 4627. For example, each double  quote  or  back-
              slash character will be escaped with a backslash characacter.

       projection
              Advanced MongoDB query projections. Please see:
              https://www.mongodb.com/docs/manual/tutorial/project-fields-from-query-results/

              o      If projection is non-empty, then result_attribute must be
                     empty.

              o      This implementation can  extract  information  only  from
                     result  fields  that  have  type  string  (UTF8), integer
                     (int32, int64) and array. Other  result  fields  will  be
                     ignored with a warning. Please see:
                     https://mongoc.org/libbson/current/bson_type_t.html

              o      As  with  result_attribute, the top-level _id field (type
                     OID) is automatically removed from projection results.

       result_attribute
              Comma or whitespace separated list with the names of  fields  to
              be returned in a lookup result.

              o      If result_attribute is non-empty, then projection must be
                     empty.

              o      As with projection, the top-level _id field (type OID) is
                     automatically removed from lookup results.

       result_format (default: %s)
              Format  template  applied  to  the  result  from  projection  or
              result_attribute. Most commonly used to append (or prepend) text
              to  the result. This parameter supports the following '%' expan-
              sions:

              %%     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_fil-
                     ter, and in fact  because  the  input  key  is  known  in
                     advance,  lookups  whose  key  does  not  contain all the
                     information specified in the  result  template  are  sup-
                     pressed 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 parameter explained
              below allows one to restrict the number of values in the result,
              which is especially useful for maps that should return a  single
              value.

              The  default value %s specifies that each attribute value should
              be used as is.

              NOTE: DO NOT put quotes around the result format! The result  is
              not a JSON string.

       domain (default: no domain list)
              This  is a list of domain names, paths to files, or "type:table"
              databases. 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 backend database. Example:
                  domain = postfix.org, hash:/etc/postfix/searchdomains

       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.

OBSOLETE MAIN.CF PARAMETERS
       MongoDB parameters can also be defined in main.cf. Specify  as  MongoDB
       source  a  name  that  doesn't begin with a slash or a dot. The MongoDB
       parameters will then be accessible as the name you've given the  source
       in  its  definition,  an underscore, and the name of the parameter. For
       example, if a map is specified as "mongodb:mongodb_source",  the  "uri"
       parameter would be defined in main.cf as "mongodb_source_uri".

       Note:  with  this form, passwords are written in main.cf, which is nor-
       mally world-readable, and '$' in a mongodb parameter setting  needs  to
       be written as '$$'.

SEE ALSO
       postmap(1), Postfix lookup table maintenance
       postconf(5), configuration parameters

README FILES
       DATABASE_README, Postfix lookup table overview
       MONGODB_README, Postfix MONGODB client guide

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

HISTORY
       MongoDB support was introduced with Postfix version 3.9.

AUTHOR(S)
       Hamid Maadani (hamid@dexo.tech)
       Dextrous Technologies, LLC

       Edited by:
       Wietse Venema
       porcupine.org

       Based on prior work by:
       Stephan Ferraro
       Aionda GmbH

                                                              MONGODB_TABLE(5)