path: root/files/zh-tw/mozilla/thunderbird/autoconfiguration/index.html

---
title: Autoconfiguration in Thunderbird
slug: Mozilla/Thunderbird/Autoconfiguration
tags:
  - Administration
  - NeedsTranslation
  - TopicStub
  - enterprise
translation_of: Mozilla/Thunderbird/Autoconfiguration
---
<p>Author: Ben Bucksch<br>
  Please do not change this document without consulting the author</p>
<p>Thunderbird 3.1 and later (and 3.0 to some degree) includes mail account autoconfiguration functionality. The goal of autoconfiguration is to make it very easy for users to configure the connection of Thunderbird to their email servers. In many cases, people should be able to download and install Thunderbird, enter their real name, email address and password in the Account Setup Wizard and have a fully functioning mail client and get and send their mail as securely as possible.</p>
<p>See also:</p>
<ul>
  <li>the <a class="link-https" href="https://wiki.mozilla.org/Thunderbird:Autoconfiguration" title="https://wiki.mozilla.org/Thunderbird:Autoconfiguration">project page on the Mozilla wiki</a> for background, design, implementation and project details</li>
  <li>for instructions for users, see <a class="external" href="http://support.mozillamessaging.com/en-US/kb/Automatic+Account+Configuration" title="http://support.mozillamessaging.com/en-US/kb/Automatic+Account+Configuration">Automatic Account Configuration</a> on the Thunderbird Knowledge Base.</li>
  <li>the configuration file <a href="/en/Thunderbird/Autoconfiguration/FileFormat/HowTo" title="en/Thunderbird/Autoconfiguration/FileFormat/HowTo">description</a> and <a href="/en/Thunderbird/Autoconfiguration/FileFormat/Definition" title="en/Thunderbird/Autoconfiguration/FileFormat/Definition">definition</a></li>
</ul>
<p>This document describes how Autoconfiguration in Thunderbird works, and what to do to allow mail servers to be autoconfigured.</p>
<h1 id="Mechanisms">Mechanisms</h1>
<p>Thunderbird gets the server settings via different means, each of which is intended for different cases:</p>
<ul>
  <li>ISPDB<br>
    The ISPDB is a central database, currently hosted by Mozilla Messaging, but free to use for any client. It contains settings for the world's largest ISPs. We hope that the database will soon have enough information to autoconfigure approximately 50% of our user's email accounts.<br>
    It was added merely because we cannot assume that all big ISPs (including Microsoft) will immediately set up a configuration server for Thunderbird.</li>
  <li>Configuration server at ISP<br>
    ISPs have the option to provide their configuration information themselves directly to users, by setting up a web server at autoconfig.&lt;domain&gt;, which simply returns a static XML file with the configuration, as described below. For more complicated setups, for example when the login name does not appear in the the email address, the XML file can also be generated by the ISP. In such complicated cases, this is the only way to allow an automatic setup.</li>
  <li>Configuration file on harddisk<br>
    Administrators may place a configuration file in the Thunderbird installation folder. This is mainly intended for companies who install Thunderbird on their employees' computers and want to enable easy account setup without having to set up a configuration server. This method is not practical for other use cases, because it is difficult to update the configuration file. Therefore, public ISPs should use a configuration server.</li>
  <li>Guessing<br>
    If all other mechanisms failed, Thunderbird tries to guess the configuration, by trying common server names like imap.&lt;domain&gt;, smtp.&lt;domain&gt;, mail.&lt;domain&gt; etc., and, when a mail server answers, checking whether it supports SSL, STARTTLS and encrypted passwords (CRAM-MD5).</li>
  <li>Manual configuration<br>
    If guessing fails the user must manually enter the configuration information. Users can may also manually modify the account settings even if configuration information is successfully obtained by the methods described above.</li>
</ul>
<p>All the lookup mechanisms use the email address domain as base for the lookup. For example, for the email address <a class="moz-txt-link-abbreviated link-mailto" href="mailto:fred@example.com">fred@example.com</a> , the lookup is performed as (in this order):</p>
<ol>
  <li><em>tb-install-dir</em>/isp/example.com.xml on the harddisk</li>
  <li>check for autoconfig.example.com</li>
  <li>look up of "example.com" in the ISPDB</li>
  <li>look up "MX example.com" in DNS, and for mx1.mail.hoster.com, look up "hoster.com" in the ISPDB</li>
  <li>try to guess (imap.example.com, smtp.example.com etc.)</li>
</ol>
<p>We may in the future add DNS SRV records as supported mechanism in the future, but we currently do not.</p>
<h1 id="How_to_add_support_for_your_domain">How to add support for your domain</h1>
<h2 id="Classification">Classification</h2>
<p>If you are a big ISP (&gt; 100,000 users) providing email addresses solely under a few domains like "example.com" and "example.de", you may either submit the configuration to the ISPDB or set up a configuration server.<br>
  <br>
  If you support email aliases and the user's login name is not part of the email address (for example, users may have <a class="moz-txt-link-rfc2396E link-mailto" href="mailto:hero@example.com">"hero@example.com"</a> as email address, but the IMAP/POP/SMTP login name is neither "hero" nor <a class="moz-txt-link-rfc2396E link-mailto" href="mailto:hero@example.com">"hero@example.com"</a>, but "u67578"), you need to set up a configuration server, which does the email address -&gt; login name lookup.<br>
  <br>
  If you host customer domains, i.e. you are "hoster.com", but your customers have <a class="moz-txt-link-rfc2396E link-mailto" href="mailto:fred@flintstone.com">"fred@flintstone.com"</a> and <a class="moz-txt-link-rfc2396E link-mailto" href="mailto:louis@kent.com">"louis@kent.com"</a> as domains, with only a few users per domain, you need to set up a configuration server (or rely on DNS MX).<br>
  <br>
  If you are a small company installing Thunderbird on your employees' desktops, you can place a configuration file in the Thunderbird installation folder.</p>
<h2 id="ISPDB">ISPDB</h2>
<p>Database URL is <a class="moz-txt-link-rfc2396E link-https" href="https://live.mozillamessaging.com/autoconfig/v1.1/" title="https://live.mozillamessaging.com/autoconfig/v1.1/">&lt;https://live.mozillamessaging.com/autoconfig/v1.1/&gt;</a>, append domain name, e.g. <a class="moz-txt-link-rfc2396E link-https" href="https://live.mozillamessaging.com/autoconfig/v1.1/freenet.de" title="https://live.mozillamessaging.com/autoconfig/v1.1/freenet.de">&lt;https://live.mozillamessaging.com/autoconfig/v1.1/freenet.de&gt;</a>.<br>
  <br>
  Current process: File a bug in <a class="link-https" href="https://bugzilla.mozilla.org/enter_bug.cgi?product=Webtools&amp;component=ISPDB%20Database%20Entries&amp;op_sys=All&amp;rep_platform=All">Bugzilla</a>, Product "Webtools", Component "ISPDB Database Entries", with a configuration file that matches the requirements described below. Request review from bwinton, gozer or ben.bucksch.<br>
  <br>
  Future: add the configuration to the <a class="link-https" href="https://ispdb.mozillamessaging.com">ISPDB server app</a>.</p>
<h2 id="Configuration_server_at_ISP">Configuration server at ISP</h2>
<p>Given the email address <a class="moz-txt-link-rfc2396E link-mailto" href="mailto:fred@example.com">"fred@example.com"</a>, Thunderbird first checks &lt;<span class="external free"><a class="moz-txt-link-freetext external" href="http://autoconfig.example.com/mail/config-v1.xml?emailaddress=fred@example.com">http://autoconfig.example.com/mail/config-v1.1.xml?emailaddress=fred@example.com</a></span>&gt; and then <a class="moz-txt-link-rfc2396E external" href="http://example.com/.well-known/autoconfig/mail/config-v1.1.xml" title="http://example.com/.well-known/autoconfig/mail/config-v1.1.xml">&lt;http://example.com/.well-known/autoconfig/mail/config-v1.1.xml&gt;</a>.</p>
<h3 id="Small_company">Small company</h3>
<p>If you are a small company, you can put the XML configuration file on your web server, at URL <a class="moz-txt-link-rfc2396E external" href="http://example.com/.well-known/autoconfig/mail/config-v1.1.xml">&lt;http://example.com/.well-known/autoconfig/mail/config-v1.1.xml&gt;</a>. (This is not yet finalized and subject to change.)</p>
<h3 id="Domain_hoster">Domain hoster</h3>
<p>If you are an ISP that hosts domains for your customers - for example, you are hoster.com and your customer registers fancy.com or example.com, and your servers accept and serve the mail for example.com -, you should set up an autoconfig server.</p>
<h4 id="DNS">DNS</h4>
<p>For each customer domain, you add a DNS record (in addition to the existing MX, A www etc. DNS records):<br>
  <code>autoconfig IN A 10.2.3.4</code><br>
  or<br>
  <code>autoconfig IN CNAME autoconfig.hoster.com</code>.<br>
  ... where 10.2.3.4 and autoconfig.hoster.com are IP addresses / hostnames you own.<br>
  This allows Thunderbird to find you as hoster.</p>
<p>To make the Version without an autoconfig DNS Entry work you have to make sure that example.com points to the Webserver you will place the config-v1.1.xml on.</p>
<p>Example: <span style="font-family: 'Courier New', 'Andale Mono', monospace; line-height: normal;">example.com A 10.2.3.4</span></p>
<h4 id="Web_server">Web server</h4>
<p>You set up a web server bound to a physical IP address. This may be on the same machine as other web servers, but the web server must be configured to the content to any requested domain.<br>
  <br>
  You must use an virtual host that match all autoconfig.* domains of your customers. In Apache terms, you can use a "ip-based virtual host". In the Apache configuration files, that means something like: Listen 10.2.3.4:80 (of course, you use a public IP address that you own)</p>
<pre>&lt;VirtualHost 10.2.3.4:80&gt; #Must be the first and only virtual host with this ip!
    DocumentRoot /var/www/autoconfig/
    ServerName autoconfig.hoster.com
    &lt;Directory /var/www/autoconfig&gt;
	Order allow,deny
	allow from all
    &lt;/Directory&gt;
&lt;/VirtualHost&gt;</pre>
<p>Place the configuration file at the URL /mail/config-v1.1.xml on that host.</p>
<p>All config files must be served as <code>Content-Type: text/xml</code> (or <code>application/xml</code>), otherwise the file will be ignored. Also, they must use charset UTF-8 (esp. if there are any non-ASCII-characters).</p>
<p>If you like to use name-based virtual hosts. You probably don't want to setup the autoconfig subdomain for every domain of your customers.<br>
  You can add a Rewriterule in the default virtual host (on debian /etc/apache2/sites-enabled/000-default)  to match all autoconfig.* subdomains:</p>
<pre>&lt;VirtualHost *:80&gt; #Must be the first Virtual host
	ServerAdmin webmaster@hoster.com
	ServerName www
	DocumentRoot /var/www
	RewriteEngine On
	RewriteCond %{HTTP_HOST} ^autoconfig\. [NC]
	RewriteRule ^/(.*)	http://autoconfig.hoster.com/$1 [L,R=301,NE]
        #...
&lt;/VirtualHost&gt;
&lt;VirtualHost *:80&gt;
    DocumentRoot /var/www/autoconfig/
    ServerName autoconfig.hoster.com
    &lt;Directory /var/www/autoconfig&gt;
 	Order allow,deny
	allow from all
    &lt;/Directory&gt;
&lt;/VirtualHost&gt;
</pre>
<p> </p>
<p> </p>
<h2 id="Configuration_file">Configuration file</h2>
<p>This is described at <a href="/en/Thunderbird/Autoconfiguration/FileFormat/HowTo" title="en/Thunderbird/Autoconfiguration/FileFormat/HowTo">How to create a configuration file</a> and <a href="/en/Thunderbird/Autoconfiguration/FileFormat/Definition" title="en/Thunderbird/Autoconfiguration/FileFormat/Definition">defined</a> on the sub-pages.</p>
<p>{{ languages( { "ja": "ja/Thunderbird/Autoconfiguration" } ) }}</p>