    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 lmdb:, cdb:, hash:,  or  dbm:
           format.

           Alternatively, lookup tables can be specified as MongoDB databases.  To
           find out what types of lookup tables your Postfix system  supports  use
           the "postconf -m" command.

           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)