New doc: iredmail-easy.autoconfig.autodiscover.html.
This commit is contained in:
Zhang Huangbin
parent
19aa1ae77f
commit
c93efe6090
|
|
@ -0,0 +1,159 @@
|
|||
# How to setup DNS records for autoconfig and autodiscover
|
||||
|
||||
[TOC]
|
||||
|
||||
[iRedMail Easy](https://www.iredmail.org/easy.html) offers component
|
||||
`Autoconfig and Autodiscover` to help end users
|
||||
setup their MUA like Thunderbird and Outlook which supports autoconfig and
|
||||
autodiscover protocol.
|
||||
|
||||
This tutorial explains how autoconfig and autodiscover works, and how to
|
||||
setup required DNS records to get them working. In this tutorial, we use:
|
||||
|
||||
* `customer.com` is your customer's mail domain name.
|
||||
* `mail.host.com` is the hostname of your mail server deployed with iRedMail
|
||||
Easy platform, it's public IPv4 address is `a.b.c.d`. IP can be either IPv4
|
||||
or IPv6, we use IPv4 for example in this tutorial.
|
||||
|
||||
It's ok to use a separated DNS name like `autoconfig.host.com` for
|
||||
autoconfig and autodiscover service, don't forget to setup https for it
|
||||
with a valid ssl cert (it's required by autodiscover).
|
||||
|
||||
## How autoconfig works in Thunderbird
|
||||
|
||||
To setup email account `user@customer.com`, Thunderbird performs the
|
||||
lookups below in particular order to get pre-defined server settings:
|
||||
|
||||
1. It checks `http://autoconfig.customer.com/mail/config-v1.1.xml?emailaddress=user@customer.com`
|
||||
1. if failed, checks `http://customer.com/.well-known/autoconfig/mail/config-v1.1.xml?emailaddress=user@customer.com`
|
||||
1. If failed, try to find the config of mail domain at the Mozilla ISP database (ISPDB).
|
||||
|
||||
For more details about ISPDB, or you're a big ISP and want to add your
|
||||
domain in ISPDB, please read [this tutorial](https://developer.mozilla.org/en-US/docs/Mozilla/Thunderbird/Autoconfiguration#ISPDB).
|
||||
|
||||
1. Look up DNS MX record of `customer.com`. If the server specified in
|
||||
DNS MX record is `mx1.mail.host.com`, look up `host.com` in the ISPDB.
|
||||
1. If all mechanisms failed, Thunderbird tries to guess the server
|
||||
address, by trying common server names like `imap.customer.com`,
|
||||
`smtp.customer.com`, `mail.customer.com`, etc. and, when a mail server
|
||||
answers, checking whether it supports SSL, STARTTLS and encrypted passwords
|
||||
(CRAM-MD5).
|
||||
|
||||
We don't control Mozilla ISPDB, and most times web site is hosted on another
|
||||
server, so the ideal solution is setting DNS record `autoconfig.customer.com`
|
||||
and pointed to your mail server. We will show you how to setup this DNS record
|
||||
later.
|
||||
|
||||
The autoconfig component configured by iRedMail Easy supports URLs:
|
||||
|
||||
- `https://mail.host.com/mail/config-v1.1.xml`
|
||||
- `https://mail.host.com/.well-known/autoconfig/mail/config-v1.1.xml`
|
||||
- `https://autoconfig.host.com/mail/config-v1.1.xml` (DNS A record of `autoconfig.host.com` must be pointed to IP of your mail server `a.b.c.d`.)
|
||||
- `https://autoconfig.host.com/.well-known/autoconfig/mail/config-v1.1.xml` (DNS A record of `autoconfig.host.com` must be pointed to IP of your mail server `a.b.c.d`.)
|
||||
|
||||
## How auto-discover works in Microsoft Outlook
|
||||
|
||||
!!! warning
|
||||
|
||||
Outlook requires a valid ssl cert, a self-signed ssl cert may fail.
|
||||
|
||||
Without Microsoft Exchange, the order of logic that Outlook 2007 and newer
|
||||
releases use when trying to figure out where to get server settings is as
|
||||
follows:
|
||||
|
||||
1. HTTPS root domain query. Outlook uses the domain part of user email address
|
||||
to do this query, so it's `https://customer.com/autodiscover/autodiscover.xml`.
|
||||
1. If above failed, try HTTPS autodiscover domain:
|
||||
`https://autodiscover.customer.com/autodiscover/autodiscover.xml`.
|
||||
1. If above failed, try same URL but HTTP instead:
|
||||
`http://autodiscover.customer.com/autodiscover/autodiscover.xml`
|
||||
1. If all failed, try DNS SRV record: `_autodiscover._tcp.customer.com`. If it
|
||||
returns a web host name and port number, for example, `mail.host.com` and
|
||||
port number 443, then try
|
||||
`https://mail.host.com:443/autodiscover/autodiscover.xml`
|
||||
|
||||
The ideal solution is setting DNS SRV record `_autodiscover._tcp.customer.com`
|
||||
and point to your server `mail.host.com`.
|
||||
|
||||
The autodiscover component configured by iRedMail Easy supports URLs:
|
||||
|
||||
- `https://mail.host.com/autodiscover/autodiscover.xml`
|
||||
- `https://autodiscover.host.com/autodiscover/autodiscover.xml` (DNS A record of `autodiscover.host.com` must be pointed to IP of your mail server `a.b.c.d`.)
|
||||
|
||||
## Setup DNS record for autoconfig
|
||||
|
||||
Please create either a DNS A or CNAME record `autoconfig.customer.com` for
|
||||
your customer's domain name:
|
||||
|
||||
* For DNS A record, please point to your mail server IP address `a.b.c.d`.
|
||||
* For DNS CNAME record, please point to your mail server hostname `mail.host.com`.
|
||||
|
||||
After created, you may need to wait for 2 or more hours until your DNS vendor
|
||||
flush the DNS cache. Then you can test the autoconfig with curl commands below:
|
||||
|
||||
```
|
||||
curl -k http://autoconfig.customer.com/.well-known/autoconfig/mail/config-v1.1.xml?emailaddress=user@customer.com
|
||||
curl -k http://mail.host.com/mail/config-v1.1.xml?emailaddress=user@customer.com
|
||||
curl -k http://mail.host.com/.well-known/autoconfig/mail/config-v1.1.xml?emailaddress=user@customer.com
|
||||
```
|
||||
|
||||
It should print a XML format content on console.
|
||||
|
||||
## Setup DNS record for autodiscover
|
||||
|
||||
Please create a DNS SRV record for your customer's domain name `customer.com`:
|
||||
|
||||
- `Service`: _autodiscover
|
||||
- `Protocol`: _tcp
|
||||
- `Port Number`: 443
|
||||
- `Host`: mail.host.com
|
||||
|
||||
Outlook will query DNS SRV record `_autodiscover._tcp.customer.com` first, then
|
||||
fetch pre-defined server settings from URL
|
||||
`https://mail.host.com/autodiscover/autodiscover.xml`.
|
||||
|
||||
After created, you may need to wait for 2 or more hours until your DNS vendor
|
||||
flush the DNS cache. Then try to query it with `dig` command like below:
|
||||
|
||||
```
|
||||
# dig +short -t srv _autodiscover._tcp.customer.com
|
||||
1 1 443 mail.host.com.
|
||||
```
|
||||
|
||||
Create temporary text file `/tmp/outlook.xml` with content below:
|
||||
|
||||
```
|
||||
<?xml version="1.0" encoding="utf-8" ?>
|
||||
<Autodiscover xmlns="http://schemas.microsoft.com/exchange/autodiscover/outlook/requestschema/2006">
|
||||
<Request>
|
||||
<AcceptableResponseSchema>http://schemas.microsoft.com/exchange/autodiscover/outlook/responseschema/2006a</AcceptableResponseSchema>
|
||||
|
||||
<!-- EMailAddress: indicates the user's email address. OPTIONAL -->
|
||||
<EMailAddress>user@customer.com</EMailAddress>
|
||||
</Request>
|
||||
</Autodiscover>
|
||||
```
|
||||
|
||||
Create temporary text file `/tmp/eas.xml` with content below:
|
||||
|
||||
```
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<Autodiscover xmlns="http://schemas.microsoft.com/exchange/autodiscover/mobilesync/requestschema/2006">
|
||||
<Request>
|
||||
<EMailAddress>user@customer.com</EMailAddress>
|
||||
<AcceptableResponseSchema>http://schemas.microsoft.com/exchange/autodiscover/mobilesync/responseschema/2006</AcceptableResponseSchema>
|
||||
</Request>
|
||||
</Autodiscover>
|
||||
```
|
||||
|
||||
Now run `curl` commands to verify it:
|
||||
|
||||
```
|
||||
curl -k -X POST -d @/tmp/outlook.xml https://autodiscover.customer.com/autodiscover/autodiscover.xml
|
||||
curl -k -X POST -d @/tmp/eas.xml https://autodiscover.customer.com/autodiscover/autodiscover.xml
|
||||
|
||||
curl -k -X POST -d @/tmp/outlook.xml https://mail.host.com/autodiscover/autodiscover.xml
|
||||
curl -k -X POST -d @/tmp/eas.xml https://mail.host.com/autodiscover/autodiscover.xml
|
||||
```
|
||||
|
||||
It should print XML format content on console.
|
||||
|
|
@ -80,6 +80,7 @@
|
|||
<li><a href="iredmail-easy.best.practice.html">Best Practice</a></li>
|
||||
<li><a href="iredmail-easy.release.notes.html">Release Notes</a></li>
|
||||
<li><a href="iredmail-easy.unsubscribe.html">How to cancel your subscription</a></li>
|
||||
<li><a href="iredmail-easy.autoconfig.autodiscover.html">How to setup DNS records for autoconfig and autodiscover</a></li>
|
||||
<li><a href="iredmail-easy.setup-sudo.html">Setup sudo for deployment with iRedMail Easy</a></li>
|
||||
<li><a href="iredmail-easy.what.is.ssh.jump.server.html">What is SSH jump server</a></li>
|
||||
</ul>
|
||||
|
|
|
|||
|
|
@ -0,0 +1,180 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||||
<title>How to setup DNS records for autoconfig and autodiscover</title>
|
||||
<link rel="stylesheet" type="text/css" href="./css/markdown.css" />
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<div id="navigation">
|
||||
<a href="https://www.iredmail.org" target="_blank">
|
||||
<img alt="iRedMail web site"
|
||||
src="./images/logo-iredmail.png"
|
||||
style="vertical-align: middle; height: 30px;"
|
||||
/>
|
||||
<span>iRedMail</span>
|
||||
</a>
|
||||
// <a href="./index.html">Document Index</a></div><h1 id="how-to-setup-dns-records-for-autoconfig-and-autodiscover">How to setup DNS records for autoconfig and autodiscover</h1>
|
||||
<div class="toc">
|
||||
<ul>
|
||||
<li><a href="#how-to-setup-dns-records-for-autoconfig-and-autodiscover">How to setup DNS records for autoconfig and autodiscover</a><ul>
|
||||
<li><a href="#how-autoconfig-works-in-thunderbird">How autoconfig works in Thunderbird</a></li>
|
||||
<li><a href="#how-auto-discover-works-in-microsoft-outlook">How auto-discover works in Microsoft Outlook</a></li>
|
||||
<li><a href="#setup-dns-record-for-autoconfig">Setup DNS record for autoconfig</a></li>
|
||||
<li><a href="#setup-dns-record-for-autodiscover">Setup DNS record for autodiscover</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<p><a href="https://www.iredmail.org/easy.html">iRedMail Easy</a> offers component
|
||||
<code>Autoconfig and Autodiscover</code> to help end users
|
||||
setup their MUA like Thunderbird and Outlook which supports autoconfig and
|
||||
autodiscover protocol.</p>
|
||||
<p>This tutorial explains how autoconfig and autodiscover works, and how to
|
||||
setup required DNS records to get them working. In this tutorial, we use:</p>
|
||||
<ul>
|
||||
<li><code>customer.com</code> is your customer's mail domain name.</li>
|
||||
<li>
|
||||
<p><code>mail.host.com</code> is the hostname of your mail server deployed with iRedMail
|
||||
Easy platform, it's public IPv4 address is <code>a.b.c.d</code>. IP can be either IPv4
|
||||
or IPv6, we use IPv4 for example in this tutorial.</p>
|
||||
<p>It's ok to use a separated DNS name like <code>autoconfig.host.com</code> for
|
||||
autoconfig and autodiscover service, don't forget to setup https for it
|
||||
with a valid ssl cert (it's required by autodiscover).</p>
|
||||
</li>
|
||||
</ul>
|
||||
<h2 id="how-autoconfig-works-in-thunderbird">How autoconfig works in Thunderbird</h2>
|
||||
<p>To setup email account <code>user@customer.com</code>, Thunderbird performs the
|
||||
lookups below in particular order to get pre-defined server settings:</p>
|
||||
<ol>
|
||||
<li>It checks <code>http://autoconfig.customer.com/mail/config-v1.1.xml?emailaddress=user@customer.com</code></li>
|
||||
<li>if failed, checks <code>http://customer.com/.well-known/autoconfig/mail/config-v1.1.xml?emailaddress=user@customer.com</code></li>
|
||||
<li>
|
||||
<p>If failed, try to find the config of mail domain at the Mozilla ISP database (ISPDB).</p>
|
||||
<p>For more details about ISPDB, or you're a big ISP and want to add your
|
||||
domain in ISPDB, please read <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Thunderbird/Autoconfiguration#ISPDB">this tutorial</a>.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Look up DNS MX record of <code>customer.com</code>. If the server specified in
|
||||
DNS MX record is <code>mx1.mail.host.com</code>, look up <code>host.com</code> in the ISPDB.</p>
|
||||
</li>
|
||||
<li>If all mechanisms failed, Thunderbird tries to guess the server
|
||||
address, by trying common server names like <code>imap.customer.com</code>,
|
||||
<code>smtp.customer.com</code>, <code>mail.customer.com</code>, etc. and, when a mail server
|
||||
answers, checking whether it supports SSL, STARTTLS and encrypted passwords
|
||||
(CRAM-MD5).</li>
|
||||
</ol>
|
||||
<p>We don't control Mozilla ISPDB, and most times web site is hosted on another
|
||||
server, so the ideal solution is setting DNS record <code>autoconfig.customer.com</code>
|
||||
and pointed to your mail server. We will show you how to setup this DNS record
|
||||
later.</p>
|
||||
<p>The autoconfig component configured by iRedMail Easy supports URLs:</p>
|
||||
<ul>
|
||||
<li><code>https://mail.host.com/mail/config-v1.1.xml</code></li>
|
||||
<li><code>https://mail.host.com/.well-known/autoconfig/mail/config-v1.1.xml</code></li>
|
||||
<li><code>https://autoconfig.host.com/mail/config-v1.1.xml</code> (DNS A record of <code>autoconfig.host.com</code> must be pointed to IP of your mail server <code>a.b.c.d</code>.)</li>
|
||||
<li><code>https://autoconfig.host.com/.well-known/autoconfig/mail/config-v1.1.xml</code> (DNS A record of <code>autoconfig.host.com</code> must be pointed to IP of your mail server <code>a.b.c.d</code>.)</li>
|
||||
</ul>
|
||||
<h2 id="how-auto-discover-works-in-microsoft-outlook">How auto-discover works in Microsoft Outlook</h2>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<p>Outlook requires a valid ssl cert, a self-signed ssl cert may fail.</p>
|
||||
</div>
|
||||
<p>Without Microsoft Exchange, the order of logic that Outlook 2007 and newer
|
||||
releases use when trying to figure out where to get server settings is as
|
||||
follows:</p>
|
||||
<ol>
|
||||
<li>HTTPS root domain query. Outlook uses the domain part of user email address
|
||||
to do this query, so it's <code>https://customer.com/autodiscover/autodiscover.xml</code>.</li>
|
||||
<li>If above failed, try HTTPS autodiscover domain:
|
||||
<code>https://autodiscover.customer.com/autodiscover/autodiscover.xml</code>.</li>
|
||||
<li>If above failed, try same URL but HTTP instead:
|
||||
<code>http://autodiscover.customer.com/autodiscover/autodiscover.xml</code></li>
|
||||
<li>If all failed, try DNS SRV record: <code>_autodiscover._tcp.customer.com</code>. If it
|
||||
returns a web host name and port number, for example, <code>mail.host.com</code> and
|
||||
port number 443, then try
|
||||
<code>https://mail.host.com:443/autodiscover/autodiscover.xml</code></li>
|
||||
</ol>
|
||||
<p>The ideal solution is setting DNS SRV record <code>_autodiscover._tcp.customer.com</code>
|
||||
and point to your server <code>mail.host.com</code>.</p>
|
||||
<p>The autodiscover component configured by iRedMail Easy supports URLs:</p>
|
||||
<ul>
|
||||
<li><code>https://mail.host.com/autodiscover/autodiscover.xml</code></li>
|
||||
<li><code>https://autodiscover.host.com/autodiscover/autodiscover.xml</code> (DNS A record of <code>autodiscover.host.com</code> must be pointed to IP of your mail server <code>a.b.c.d</code>.)</li>
|
||||
</ul>
|
||||
<h2 id="setup-dns-record-for-autoconfig">Setup DNS record for autoconfig</h2>
|
||||
<p>Please create either a DNS A or CNAME record <code>autoconfig.customer.com</code> for
|
||||
your customer's domain name:</p>
|
||||
<ul>
|
||||
<li>For DNS A record, please point to your mail server IP address <code>a.b.c.d</code>.</li>
|
||||
<li>For DNS CNAME record, please point to your mail server hostname <code>mail.host.com</code>.</li>
|
||||
</ul>
|
||||
<p>After created, you may need to wait for 2 or more hours until your DNS vendor
|
||||
flush the DNS cache. Then you can test the autoconfig with curl commands below:</p>
|
||||
<pre><code>curl -k http://autoconfig.customer.com/.well-known/autoconfig/mail/config-v1.1.xml?emailaddress=user@customer.com
|
||||
curl -k http://mail.host.com/mail/config-v1.1.xml?emailaddress=user@customer.com
|
||||
curl -k http://mail.host.com/.well-known/autoconfig/mail/config-v1.1.xml?emailaddress=user@customer.com
|
||||
</code></pre>
|
||||
|
||||
<p>It should print a XML format content on console.</p>
|
||||
<h2 id="setup-dns-record-for-autodiscover">Setup DNS record for autodiscover</h2>
|
||||
<p>Please create a DNS SRV record for your customer's domain name <code>customer.com</code>:</p>
|
||||
<ul>
|
||||
<li><code>Service</code>: _autodiscover</li>
|
||||
<li><code>Protocol</code>: _tcp</li>
|
||||
<li><code>Port Number</code>: 443</li>
|
||||
<li><code>Host</code>: mail.host.com</li>
|
||||
</ul>
|
||||
<p>Outlook will query DNS SRV record <code>_autodiscover._tcp.customer.com</code> first, then
|
||||
fetch pre-defined server settings from URL
|
||||
<code>https://mail.host.com/autodiscover/autodiscover.xml</code>.</p>
|
||||
<p>After created, you may need to wait for 2 or more hours until your DNS vendor
|
||||
flush the DNS cache. Then try to query it with <code>dig</code> command like below:</p>
|
||||
<pre><code># dig +short -t srv _autodiscover._tcp.customer.com
|
||||
1 1 443 mail.host.com.
|
||||
</code></pre>
|
||||
|
||||
<p>Create temporary text file <code>/tmp/outlook.xml</code> with content below:</p>
|
||||
<pre><code><?xml version="1.0" encoding="utf-8" ?>
|
||||
<Autodiscover xmlns="http://schemas.microsoft.com/exchange/autodiscover/outlook/requestschema/2006">
|
||||
<Request>
|
||||
<AcceptableResponseSchema>http://schemas.microsoft.com/exchange/autodiscover/outlook/responseschema/2006a</AcceptableResponseSchema>
|
||||
|
||||
<!-- EMailAddress: indicates the user's email address. OPTIONAL -->
|
||||
<EMailAddress>user@customer.com</EMailAddress>
|
||||
</Request>
|
||||
</Autodiscover>
|
||||
</code></pre>
|
||||
|
||||
<p>Create temporary text file <code>/tmp/eas.xml</code> with content below:</p>
|
||||
<pre><code><?xml version="1.0" encoding="utf-8"?>
|
||||
<Autodiscover xmlns="http://schemas.microsoft.com/exchange/autodiscover/mobilesync/requestschema/2006">
|
||||
<Request>
|
||||
<EMailAddress>user@customer.com</EMailAddress>
|
||||
<AcceptableResponseSchema>http://schemas.microsoft.com/exchange/autodiscover/mobilesync/responseschema/2006</AcceptableResponseSchema>
|
||||
</Request>
|
||||
</Autodiscover>
|
||||
</code></pre>
|
||||
|
||||
<p>Now run <code>curl</code> commands to verify it:</p>
|
||||
<pre><code>curl -k -X POST -d @/tmp/outlook.xml https://autodiscover.customer.com/autodiscover/autodiscover.xml
|
||||
curl -k -X POST -d @/tmp/eas.xml https://autodiscover.customer.com/autodiscover/autodiscover.xml
|
||||
|
||||
curl -k -X POST -d @/tmp/outlook.xml https://mail.host.com/autodiscover/autodiscover.xml
|
||||
curl -k -X POST -d @/tmp/eas.xml https://mail.host.com/autodiscover/autodiscover.xml
|
||||
</code></pre>
|
||||
|
||||
<p>It should print XML format content on console.</p><div class="footer">
|
||||
<p style="text-align: center; color: grey;">All documents are available in <a href="https://bitbucket.org/zhb/iredmail-docs/src">BitBucket repository</a>, and published under <a href="http://creativecommons.org/licenses/by-nd/3.0/us/" target="_blank">Creative Commons</a> license. You can <a href="https://bitbucket.org/zhb/iredmail-docs/get/tip.tar.bz2">download the latest version</a> for offline reading. If you found something wrong, please do <a href="https://www.iredmail.org/contact.html">contact us</a> to fix it.</p>
|
||||
</div>
|
||||
<!-- Global site tag (gtag.js) - Google Analytics -->
|
||||
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-3293801-21"></script>
|
||||
<script>
|
||||
window.dataLayer = window.dataLayer || [];
|
||||
function gtag(){dataLayer.push(arguments);}
|
||||
gtag('js', new Date());
|
||||
|
||||
gtag('config', 'UA-3293801-21');
|
||||
</script>
|
||||
</body></html>
|
||||
Loading…
Reference in New Issue