autodiscover

Name

Autodiscover HTTP Service Protocol handler (AutoDiscover responder)

Description

Autodiscover clients can locate the Autodiscover server for a given domain example.com by attempting to resolve the _autodiscover._tcp.example.com IN SRV record from DNS, and otherwise fall back to autodiscover.example.com.

To force using a particular Autodiscover server, such as when Gromox is run in a development environment with a fake domain, c:windowssystem32driversetchosts can be populated with a static entry for autodiscover.example.com to get that particular scenario working.

An Autodiscover client would make a “POST /Autodiscover/Autodiscover.xml” request to the autodiscover server that was determined moments ago. The mailbox credentials are presented using HTTP authentication.

In a Gromox minimal setup, http(8gx) will receive this POST request and, in conjunction with the built-in defaults of mod_rewrite(4gx) and mod_fastcgi(4gx), is forwarded to a php-fpm instance, since the Autodiscover handler is coded in PHP. Alternative setups where, for example, an nginx frontend is used, nginx can also be the server that passes the request to a PHP executor.

The Autodiscover response contains a HTTP server (generally the HTTP home server) and the designated choice for protocol framing. A client uses this to set up the EMSMDB MAPI service within a MAPI profile. Because the HTTP home server is then known, Autodiscover is not used again when making a connection to the message store service. However, the Address Book always issues Autodiscover requests. (In other words, removing the DNS entry for the Autodiscover server after a profile is set up would break the address book, but not the message store.)

Configuration directives

At first, /etc/gromox/mysql_adaptor.cfg is read for the connection parameters to the user database. See gromox(7) for a description of the format. See mysql_adaptor(4gx) for details about the available configuration directives. In the file’s absence, built-in defaults as documented are applied, in other words, root@localhost/email. Note that this cfg file is read using an ini parser, which is not technically correct and has the caveat that it is not possible to use any of these characters in values: ;

Note that PHP is dumb and the program cannot distinguish between file absence and file presence but missing permissions.

Second, /etc/gromox/autodiscover.ini is read. In the file’s absence, built-in defaults, tuned for the minimal Gromox installation, are used. A few ini sections and keys are recognized.

[database]

This section can be used to override the parameters previously sourced from mysql_adaptor.cfg (or built-in defaults thereto).

host
Host and optionally port to pass to php-mysqli.
Default: inherit from mysql_adaptor, localhost.
username
User for the SQL connection.
Default: inherit, root.
password
Password for the same.
Default: inherit, (empty string).
dbname
Database name.
Default: inherit, email.

[exchange]

advertise_mh
This setting controls whether the AutoDiscover response should include a EXHTTP Protocol section. Possible values: yes, no, not_old_mso, only_new_mso. The latter two values can be used to finely control emission in case of clients other than Outlook.
Default: yes
advertise_rpch
This setting controls whether the AutoDiscover response should include EXCH/EXPR Protocol sections. Possible values: yes, no, only_old_mso, not_new_mso. The latter two values can be used to finely control emission in case of clients other than Outlook.
Default: yes
hostname
The globally valid hostname of this server for the purpose of AutoDisocvery referring to itself and other RPC and EWS endpoints. (The OXDSCLI protocol requires URLs and Outlook would not do anything if we snuck in relative paths in violation of the spec.)
Default: (system hostname).

[default]

timezone
Default: (unspecified)

[system]

freebusy
Program location of the freebusy binary.
Default: /usr/libexec/gromox/freebusy

[http-proxy]

This section contains the emsmdb multiserver map. This conveys the public-facing HTTP server name(s) for homedir prefix(es), and Outlook and other clients will connect to these servers. Whether prefixes end in a slash or not is of no consequence, their right will always be treated as a word boundary so that “/var/lib/gromox/user” will not be a match to a userdir “/var/lib/gromox/users/x/y” (but will be for “/var/lib/gromox/user/x/y”).

Default:

/var/lib/gromox/user/ = (system hostname)
/var/lib/gromox/domain/ = (system hostname)

If no prefix yields a match for a given mailbox directory, the value from the exchange.hostname setting is used as a response.

Outlook notes

When Outlook is active, it is possible to Ctrl-MouseBtn3 (right click) on the status tray icon to call up a context menu, from which “Test Email Autoconfiguration…” can be selected to debug AutoDiscover requests and responses from the Windows side.

Normative references

  • MS-OXDISCO: Autodiscover HTTP Service Protocol
  • MS-OXDSCLI: Autodiscover Publishing and Lookup Protocol

See also

gromox(7)