    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)