GoAdmio

autodiscover

Write the Outlook Autodiscover file for every hosted domain

On this page: Overview · Quick start · Syntax · Output · Examples · Troubleshooting · Details · See also


Overview

Autodiscover lets a mail app set up an email account from the address alone, without the user typing server names and ports. /go/autodiscover writes the file that Outlook-style mail apps read. For every hosted domain, it:

Mail apps that support Autodiscover look for the file at addresses such as https://<domain>/autodiscover/autodiscover.xml.

The command only writes the files. It does not change DNS or the web server configuration.


Quick start

# Write the Autodiscover file for every hosted domain
/go/autodiscover

Syntax

/go/autodiscover

The command takes no arguments or options. If you are not root, it re-runs itself with sudo. It always processes every domain, so you cannot run it for one domain alone.


Output

The command prints nothing. To check the result, look at the file or request it:

cat /home/example.com/www/autodiscover/autodiscover.xml
curl https://example.com/autodiscover/autodiscover.xml

Examples

# Write or refresh the files for all domains
/go/autodiscover
# Check one domain's file
cat /home/example.com/www/autodiscover/autodiscover.xml
# Review the log of past runs
tail -n 20 /var/log/go/autodiscover.log

Troubleshooting

Symptom Likely cause Fix
A domain has no autodiscover folder The domain has no /home/<domain>/www folder. Check the account with ls /home.
The mail app does not find the settings The site has no working HTTPS, or the app looks at an address that does not reach this file. Check that https://<domain>/autodiscover/autodiscover.xml opens in a browser. See ssl.
The file names the server hostname, not smtp.<domain> or imap.<domain> No certificate exists for that name, or (for SMTP) Postfix is not version 3. Install the certificates with mailssl, then run the command again.
POP3 shows the SMTP server name The file uses the SMTP server name for POP3. See Servers. None. Use IMAP, or enter the POP3 server by hand.
The app cannot log in The file requires the full email address as the user name. Enter the whole address, such as info@example.com.
Connection fails on port 993, 995, or 465 The port is closed in the firewall. Open it with allow, and check with checkfirewall.
Your edits to the file are gone The command rewrites the file on every run. Make lasting changes in the script, not in the file.

Details

Servers

The file lists three protocols. All use SSL and require authentication.

Protocol Server Port
IMAP The IMAP server name 993
POP3 The SMTP server name 995
SMTP The SMTP server name 465

The SMTP settings also turn on UsePOPAuth and leave SMTPLast off.

How the server names are chosen

Name Default Replaced when
IMAP server The contents of /etc/imap if that file exists, otherwise the server's hostname A certificate exists at /etc/letsencrypt/live/imap.<domain>/fullchain.pem. The name becomes imap.<domain>.
SMTP server The server's hostname A certificate exists at /etc/letsencrypt/live/smtp.<domain>/fullchain.pem and Postfix is version 3.x. The name becomes smtp.<domain>.

What the file contains

The file uses Microsoft's Autodiscover response format, as read by Outlook-style mail apps. It is the same for every user of the domain. It does not insert the user's address, so each user types the full email address as the login name (DomainRequired is on).

Files and folders

Item Detail
Folder /home/<domain>/www/autodiscover, created if missing.
File autodiscover.xml, overwritten on every run.
Owner root, because the command writes the file as root.

Entries in /home without a www folder are skipped.

Logging

Every run appends a timestamp to /var/log/go/autodiscover.log.

What a run does

flowchart TD
    A["autodiscover"] --> B["Read the Postfix version"]
    B --> C["For each entry in /home"]
    C --> D{"Has a www folder?"}
    D -- "No" --> X["Skip"]
    D -- "Yes" --> E["Choose the IMAP and SMTP server names"]
    E --> F["Write www/autodiscover/autodiscover.xml"]

See also

Command Description
mailssl Install SSL certificates for SMTP and IMAP
outlook Send IMAP/SMTP configuration to email accounts
checkimap Check the IMAP port and SSL certificate
checksmtp Check the SMTP port and SSL certificate
installmail Install and configure webmail services (Postfix and Dovecot)
allow Open a TCP port in the server firewall