mirror of
https://github.com/mail-in-a-box/mailinabox.git
synced 2025-04-30 04:27:01 +00:00
391 lines
20 KiB
HTML
391 lines
20 KiB
HTML
<!DOCTYPE html>
|
|
<html class="no-js">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
|
|
<meta name="viewport" content="width=device-width">
|
|
<title>Mail-in-a-Box Setup Guide</title>
|
|
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" />
|
|
<style>
|
|
@import url(https://fonts.googleapis.com/css?family=Iceland);
|
|
@import url(https://fonts.googleapis.com/css?family=Raleway:400,700);
|
|
@import url(https://fonts.googleapis.com/css?family=Ubuntu:300);
|
|
|
|
|
|
body {
|
|
font-family: Raleway, sans-serif;
|
|
font-size: 16px;
|
|
color: #555;
|
|
}
|
|
|
|
h1 {
|
|
font-family: 'Iceland', sans-serif;
|
|
font-size: 50px;
|
|
}
|
|
|
|
h2 {
|
|
margin-top: 1.75em;
|
|
font-family: Ubuntu, Arial, sans-serif;
|
|
font-weight: 300;
|
|
font-size: 20px;
|
|
padding-bottom: .25em;
|
|
border-bottom: 1px solid #DDD;
|
|
margin-bottom: 1em;
|
|
}
|
|
|
|
h3 {
|
|
margin-top: 1.5em;
|
|
margin-bottom: .75em;
|
|
font-family: Ubuntu, Arial, sans-serif;
|
|
font-weight: 300;
|
|
font-size: 18px;
|
|
font-style: italic;
|
|
color: #777;
|
|
}
|
|
|
|
a {
|
|
color: #24A;
|
|
text-decoration: underline;
|
|
}
|
|
|
|
#back {
|
|
background-color: #EEE;
|
|
font-size: 90%;
|
|
padding: .5em;
|
|
}
|
|
#back a { text-decoration: none; }
|
|
#back a:hover { text-decoration: underline; }
|
|
|
|
p {
|
|
margin-bottom: 1.25em; /* see .example, .figure, pre */
|
|
}
|
|
|
|
p.pros {
|
|
font-size: 12px;
|
|
font-family: Ubuntu;
|
|
margin: 11px 0 22px -6px;
|
|
padding: 6px;
|
|
background-color: #F8F8F8;
|
|
color: #666;
|
|
}
|
|
p.pros:before {
|
|
content: "Expert summary: ";
|
|
font-weight: bold;
|
|
color: #777;
|
|
}
|
|
|
|
.example {
|
|
margin: 1em 1em 1.3em 1.5em; /* bottom must match p */
|
|
border: 1px solid #EEF;
|
|
padding: .5em;
|
|
background-color: #FAFAFF;
|
|
}
|
|
|
|
.figure {
|
|
margin: 1.25em auto; /* bottom must match p */
|
|
}
|
|
|
|
pre {
|
|
margin-bottom: 1.25em; /* bottom must match p */
|
|
}
|
|
|
|
#nav {
|
|
margin-top: 2em;
|
|
}
|
|
#nav a { color: #E64; text-decoration: none; }
|
|
#nav li.active { background-color: #D55; }
|
|
#nav li.active a { color: white; }
|
|
#nav li.active a:hover { color: #E64; }
|
|
|
|
</style>
|
|
</head>
|
|
<body data-spy="scroll" data-target="#nav">
|
|
<a href="https://github.com/joshdata/mailinabox/tree/website" class="visible-md visible-lg"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://camo.githubusercontent.com/365986a132ccd6a44c23a9169022c0b5c890c387/68747470733a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f7265645f6161303030302e706e67" alt="Fork me on GitHub" data-canonical-src="https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png"></a>
|
|
|
|
<div id="back">
|
|
<div class="container">
|
|
<a href="/">
|
|
< Back to Mail-in-a-Box
|
|
</a>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="container">
|
|
<div class="row">
|
|
<div id="sidebar" class="col-sm-4 col-md-3">
|
|
<div id="nav" class="small">
|
|
<p style="margin: 0 0 1em 14px; border-bottom: 1px solid #CCC; color: #888;">Table of Contents</p>
|
|
<ul class="nav nav-list">
|
|
<li><a href="#cost">Cost</a></li>
|
|
<li><a href="#domain-name-registration">Getting a Domain Name</a></li>
|
|
<li><a href="#hostname">The Box’s Hostname</a></li>
|
|
<li><a href="#machine">The Machine</a></li>
|
|
<li><a href="#domain-name-configuration">Domain Name Configuration</a></li>
|
|
<li><a href="#setup">Machine Setup</a></li>
|
|
<li><a href="#mail">Checking/Sending Mail</a></li>
|
|
<li><a href="#mail-users">Adding Email Addresses</a></li>
|
|
<li><a href="#ssl">SSL Certificate</a></li>
|
|
<li><a href="#dnssec">DNSSEC</a></li>
|
|
<li><a href="#other">Other</a></li>
|
|
<li><a href="#checks">Systems Checks</a></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="col-sm-8 col-md-9">
|
|
|
|
<div style="padding-left: 1em; max-width: 55em">
|
|
<h1>Mail-in-a-Box Setup Guide</h1>
|
|
|
|
<h2 id="cost">How much will this cost?</h2>
|
|
|
|
<p>About $15/month. You’re going to become your own Internet service provider — an ISP. It’s going to cost a little bit of money to do so, but not much and you can divide it among friends and share your Mail-in-a-Box if you’d like to split it up. Most of the cost is in having a (virtual) machine connected to the Internet 24/7.</p>
|
|
|
|
<p>There’s also your time. Once a Mail-in-a-Box is set up, we hope it “ just works” but when you are your own systems administrator you must be prepared to resolve issues as they arise.</p>
|
|
|
|
|
|
<h2 id="domain-name-registration">Your Domain Name</h2>
|
|
|
|
<p class="pros">Register a new domain name, or have a domain name that you can have your Mail-in-a-Box completely take over.</p>
|
|
|
|
<p>The first step in setting up a Mail-in-a-Box is to pick your new email address. An email address has two parts. The part after the @-sign is the “domain name.” Each domain name is owned by someone, and you are going to be the owner of your own.</p>
|
|
|
|
<p class="example">Josh’s email address is <code><script>document.write("tj".split("").reverse().join(""));</script>@occams.info</code>. His domain name is <code>occams.info</code>.</p>
|
|
|
|
<p>Besides using the domain name for email, you’ll also be able to put a simple website at the domain.</p>
|
|
|
|
<p>Go over to <a href="http://www.gandi.net/domain">Gandi.net</a>, a domain name registrar, and buy a new domain name. It’s about $17/year, but the price varies by which “top-level domain” (TLD) you use, whether it’s <code>.com</code>, <code>.me</code>, <code>.info</code>, and so on.</p>
|
|
|
|
<p>Buy anything you want. This is your new identity.</p>
|
|
|
|
<p>After you buy the name you’ll need to set it up, but that comes later so keep reading. Note that a Mail-in-a-Box can handle the email for multiple domains names too — more on that later.</p>
|
|
|
|
<h2 id="hostname">Your Box Has A Name</h2>
|
|
|
|
<p class="pros">Your box’s hostname should be <tt>box.yourdomain.com</tt>.</p>
|
|
|
|
<p>Every machine connected to the Internet has a name and an address.</p>
|
|
|
|
<p>The address, an IP address, is like a telephone number. It’s made up of numbers and is assigned to you by whoever provides Internet access to you.</p>
|
|
|
|
<p>The name — called a “hostname” — is something you decide. It can be a domain name you own or any “subdomain” of a domain you own.</p>
|
|
|
|
<p>For your Mail-in-a-Box, we recommend naming your box <code>box</code> + <code>.</code> + your domain name.</p>
|
|
|
|
<p class="example">Josh’s Mail-in-a-Box is named <code>box.occams.info</code>. This is its hostname.</p>
|
|
|
|
<p>Your Mail-in-a-Box may handle the email for multiple domain names, but the box has a single name.</p>
|
|
|
|
|
|
<h2 id="machine">The Machine</h2>
|
|
|
|
<p class="pros">Spin up an Ubuntu 14.04 x64 machine with about 1 GB memory and 12 GB disk, and then set the machine’s <u>reverse DNS</u>.</p>
|
|
|
|
<p>Now you will rent a machine, or a virtual part of a machine, somewhere in “the cloud.” We’ll call this machine your box.</p>
|
|
|
|
<p>We recommend going over to <a href="https://www.digitalocean.com/">Digital Ocean</a>. You must choose the Ubuntu 14.04 x64 operating system. We recommend using a machine with 1 GB of RAM and a 30 GB disk. At Digital Ocean this setup costs $10/month.</p>
|
|
|
|
<p>At Digital Ocean, your machine is called a “droplet” and you <strong>must</strong> name your droplet the same as its hostname.</p>
|
|
|
|
<p class="example">Josh’s droplet would be named <code>box.occams.info</code> (if Josh used Digital Ocean).</p>
|
|
|
|
<p>I've been a long-time customer of <a href="http://rimuhosting.com/order/v2orderstart.jsp">Rimuhosting.com</a> which also provides cheap virtual machines, which they call “VPS”s, at several locations around the world. Choose a location near you — it’ll be faster!</p>
|
|
|
|
<p>Wherever you rent your box, you must choose the Ubuntu 14.04 x64 operating system. Most any cloud provider will do, but not Amazon Web Services because its network is often blocked to prevent users from sending spam.</p>
|
|
|
|
<p>Each cloud provider will have different instructions for setting up “reverse DNS.” As described above, Digital Ocean's method is to give your droplet the same name as your hostname, but other providers may use differentmethods. You <strong>must</strong> follow your cloud provider’s instructions for setting the reverse DNS of your box to your box’s hostname.</p>
|
|
|
|
<p class="example">Josh’s box’s reverse DNS is set to the same as the box’s hostname: <code>box.occams.info</code>.</p>
|
|
|
|
<p>Your cloud provider will also now tell you the IP address of your machine. It looks like 123.123.123.123.</p>
|
|
|
|
<p class="example">Josh’s box’s IP address is <code>94.76.202.152</code>.</p>
|
|
|
|
|
|
<h2 id="domain-name-configuration">Configuring Your Domain Name</h2>
|
|
|
|
<p class="pros">At your registrar, create hostname records for <code>ns1.box.yourdomain.com</code> and <code>ns2.box.yourdomain.com</code> providing your box’s IP address, and then set your domain name’s nameservers to these two hostnames.</p>
|
|
|
|
<p>We’ll now go back to your domain name registrar to associate your domain name with your box’s IP address.</p>
|
|
|
|
<p>The association between your domain name and IP address is . . . complicated. The domain name system (DNS) is a global, distributed network of machines that turn domain names into IP addresses. Your registrar and your box play a role in the domain name system.</p>
|
|
|
|
<p>The way this works varies from registrar to registrar, but it goes something like this:</p>
|
|
|
|
<h3>Hostnames</h3>
|
|
|
|
<p>First, you’ll associate two new hostnames with your IP address. The purpose of this step is to say that your box is becoming a part of the domain name system. For historical reasons we need two fake hostnames for this purpose.</p>
|
|
|
|
<p>The two fake hostnames will be <code>ns1</code> + <code>.</code> + your box’s actual hostname and <code>ns2</code> + <code>.</code> + your box’s actual hostname. (These stand for “nameserver one” and “nameserver two”.)</p>
|
|
|
|
<p class="example">Josh’s box’s hostname is <code>box.occams.info</code>. The two fake hostnames are <code>ns1.box.occams.info</code> and <code>ns2.box.occams.info</code>.</p>
|
|
|
|
<p>It looks something like what’s shown in the next image.</p>
|
|
|
|
<img src="static/domain_hostnames.png" title="Hostname Configuration at Your Domain Registrar" class="img-responsive figure"/>
|
|
|
|
<p>Your registrar may ask you to enter these hostnames with the domain name part omitted, as mine did in this case. What you enter is the part of the fake hostname before the domain name.</p>
|
|
|
|
<p class="example">Josh’s domain name is <code>occams.info</code>. The two fake hostnames are <code>ns1.box.occams.info</code> and <code>ns2.box.occams.info</code>, but his registrar asks him to enter them with “.occams.info” omitted leaving just <code>ns1.box</code> and <code>ns2.box</code>.</p>
|
|
|
|
<p>If your Mail-in-a-Box is handling mail for multiple domains, you will still only set these hostnames once.</p>
|
|
|
|
<h3>Nameservers</h3>
|
|
|
|
<p>Second, you’ll tell your domain registrar that your domain name’s nameservers are <code>ns1</code> + <code>.</code> + your box’s hostname and <code>ns2</code> + <code>.</code> + your box’s hostname.</p>
|
|
|
|
<p>You will usually be turning off the registrar’s provided nameservers and turning on custom servers. This is usually <i>not</i> found in the domain name’s DNS control panel. You will be disabling that control panel.</p>
|
|
|
|
<p>Here’s what that looks like in my registrar:</p>
|
|
|
|
<img src="static/domain_nameservers.png" title="Nameserver Configuration at Your Domain Registrar" class="img-responsive figure"/>
|
|
|
|
<p>Don’t worry if you are confused about what this all means. It is complicated — we all get confused at this point.</p>
|
|
|
|
<h3>DNSSEC</h3>
|
|
|
|
<p>The domain name system is not very secure. Enabling DNSSEC provides a layer of cryptographic security on top of the domain name system in a similar way to how HTTPS web addresses add a layer of security to the web.</p>
|
|
|
|
<p>DNSSEC is configured at your domain name registrar as well but you can’t do it until after we set up the box, so we will come back to it below.</p>
|
|
|
|
|
|
<h2 id="setup">Setting Up The Box</h2>
|
|
|
|
<p class="pros">Clone our github repo <a href="https://github.com/JoshData/mailinabox">https://github.com/JoshData/mailinabox</a>, cd to the directory, and run <code>setup/start.sh</code>.</p>
|
|
|
|
<p>You will now have to log into your running box using SSH. Your cloud provider will probably give you some instructions on how to do that. If your personal computer has a command line, you'll be doing something like this:</p>
|
|
|
|
<pre>ssh -i yourkey.pem ubuntu@10.20.30.40</pre>
|
|
|
|
<p>Once inside, you will now get the Mail-in-a-Box code onto your box. Type:</p>
|
|
|
|
<pre>sudo apt-get install -y git
|
|
git clone https://github.com/joshdata/mailinabox
|
|
cd mailinabox</pre>
|
|
|
|
<p>And then start the setup process:</p>
|
|
|
|
<pre>sudo setup/start.sh</pre>
|
|
|
|
<p>You will be asked to enter the email address you want and a few other configuration questions. At the end you will be asked for a password for your email address.</p>
|
|
|
|
<p>This password will be used to login to webmail, and to authorize sending and receiving mail through SMTP and IMAP. It will <strong>not</strong> be used to log onto your Mail-in-a-Box server.</p>
|
|
|
|
<p>When the setup script is done running, you have a working mail server. But first check that everything is correct so far by typing:</p>
|
|
|
|
<pre>sudo management/whats_next.py</pre>
|
|
|
|
<p>This script reports configuration problems and next steps.</p>
|
|
|
|
<p>Things related to the domain name system sometimes take several minutes, or much longer, to update. This is called DNS propagation. If you get domain name resolving problems, you may need to wait a bit for your registrar and your home ISP’s name servers to update. If the problem persists, there is a configuration problem either at your domain name registrar or on the box.</p>
|
|
|
|
<p>Also right now your SSL certificates won’t be signed. This does not prevent you from sending or receiving email, though, so we will come back to this below.</p>
|
|
|
|
|
|
<h2 id="mail">Checking and Sending Mail</h2>
|
|
|
|
<p class="pros">You have webmail at <code>https://hostname/mail</code>. IMAP with SSL is on port 993 and SMTP with STARTTLS is on port 587. Your username is your email address.</p>
|
|
|
|
<h3>Webmail</h3>
|
|
|
|
<p>You can access your email at <code>https://hostname/mail</code>, where hostname is your box’s hostname.</p>
|
|
|
|
<p class="example">Josh goes to <a href="https://box.occams.info/mail">https://box.occams.info/mail</a> to check and send email using webmail.</p>
|
|
|
|
<p>When you visit this page you will see a warning about the site’s SSL certificate being invalid. Right now you are using a self-signed certificate. If it is unlikely that anyone is running an active network attack on you right now, just permanently confirm the security exception and you will be good to go.</p>
|
|
|
|
<p>(Otherwise, check that the SSL fingerprint show to you matches the SSL fingerprint printed toward the top of the long output of the setup script. You may run <code>sudo setup/start.sh</code> again if you missed it.)</p>
|
|
|
|
<p>Your username is the <u>email address</u> you entered when you ran the setup program above.</p>
|
|
|
|
<p><strong>Try to send some mail now!</strong></p>
|
|
|
|
<h3>Mobile and other mail clients</h3>
|
|
|
|
<p>On mobile devices you might need to install a “mail client” app. We recommend <a href="https://play.google.com/store/apps/details?id=com.fsck.k9">K-9 Mail</a>, which is developed by Google. On a desktop you could try <a href="https://www.mozilla.org/en-US/thunderbird/">Mozilla Thunderbird</a>.</p>
|
|
|
|
<p>When configuring these applications you will need to provide them with IMAP and SMTP settings. Your IMAP and SMTP server is the box’s hostname. For IMAP, you must choose SSL and port 993. For SMTP, you must choose STARTTLS and port 587.</p>
|
|
|
|
<p class="example">Josh’s IMAP and SMTP server are <code>box.occams.info</code>. (You can’t use mine!)</p>
|
|
|
|
<p>Your username for IMAP and SMTP is the <u>email address</u> you entered when you ran the setup program above, the same as with webmail.</p>
|
|
|
|
<p>Note: Mail-in-a-Box uses <a href="http://en.wikipedia.org/wiki/Greylisting">greylisting</a> to cut down on spam. The first time you receive an email from a recipient, it may be delayed for ten minutes.</p>
|
|
|
|
|
|
<h2 id="mail-users">Adding More Email Addresses</h2>
|
|
|
|
<p class="pros">Use <code>tools/mail.py</code> to manage email addresses and aliases.</p>
|
|
|
|
<p>Your box may manage the email for multiple email addresses. While logged in with SSH (see above), run:</p>
|
|
|
|
<pre>tools/mail.py</pre>
|
|
|
|
<p>This command will help you add and remove email accounts and email aliases (forwarders).</p>
|
|
|
|
<p>You may add email addresses on other domain names. If you do, you will need to set the nameservers for those domains in the domain name registrar configuration too, as described above.</p>
|
|
|
|
|
|
<h2 id="ssl">Getting a Signed Certificate</h2>
|
|
|
|
<p>To configure a real signed SSL certificate, run the <code>whats_next</code> script and follow the instructions:</p>
|
|
|
|
<pre>sudo management/whats_next.py</pre>
|
|
|
|
<p>The script will give you the CSR (which you give to your registrar or other SSL provider).</p>
|
|
|
|
<p>When you purchase an SSL certificate you will receive a certificate in PEM format and possibly a file containing “intermediate certificates” in PEM format. If you receive intermediate certificates, use a text editor like Notepad or Gedit and paste <em>your</em> certificate on top and <em>then</em> the intermediate certificates below it. Save the file and place this <em>combined</em> file onto your box in the location indicated by the <code>whats_next</code> script.</p>
|
|
|
|
|
|
<h2 id="dnssec">Configuring DNSSEC</h2>
|
|
|
|
<p>Optionally, to activate DNSSEC (see above), you'll need to get a DS record from the box. While logged in on the box, run:</p>
|
|
|
|
<pre>sudo bash -c 'curl --user $(</var/lib/mailinabox/api.key): http://localhost:10222/dns/ds'</pre>
|
|
|
|
<p>Sorry that is a long one! This will print DS records for the domain name(s) managed by your box.</p>
|
|
|
|
<p>Copy the DS record(s) and follow the DS record instructions provided by your domain name registrar.</p>
|
|
|
|
|
|
<h2 id="other">To-be-written</h2>
|
|
|
|
<p>It is also possible to...</p>
|
|
|
|
<ul>
|
|
<li>Host a static website on the box.</li>
|
|
<li>Add custom DNS records.</li>
|
|
<li>Backup your mail.</li>
|
|
</ul>
|
|
|
|
<h2 id="checks">Systems Checks</h2>
|
|
|
|
<p>If you want to double-check that your system is configured correctly, here are some tools:</p>
|
|
|
|
<ul>
|
|
<li>DNS: <a href="http://pingability.com/zoneinfo.jsp">pingability.com/zoneinfo</a></li>
|
|
<li>DKIM and SPF: <a href="http://www.brandonchecketts.com/emailtest.php">brandonchecketts.com/emailtest</a></li>
|
|
<li>SSL: <a href="https://www.ssllabs.com/ssltest/analyze.html">ssllabs.com</a></li>
|
|
</ul>
|
|
|
|
<p>There are also Python scripts in the <a href="https://github.com/JoshData/mailinabox/tree/master/tests"><code>tests/</code></a> directory on GitHub for automated testing.</p>
|
|
|
|
<div class="hidden-xs" style="height: 200px"> </div>
|
|
|
|
</div>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<script src="https://code.jquery.com/jquery-2.1.1.min.js"> </script>
|
|
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js"></script>
|
|
<script>
|
|
if ($(window).width() >= 768) {
|
|
// scroll spy with a fixed TOC doesn't work on small screens
|
|
$('#nav').attr('data-spy', 'affix');
|
|
$('body').scrollspy()
|
|
}
|
|
</script>
|
|
</body>
|
|
</html>
|