Mail-in-a-Box Setup Guide

indicates link to discussion.

indicates link to TLD registry requirements.

Next you will register your new domain name. It’s about $17/year, depending on the TLD. Buy basically anything you want, taking into account the TLD recommendations above. This will be the start of your new identity.

I recommend you use Gandi.net to register your domain name because I know it works well for Mail-in-a-Box. You can use other domain name registrars besides Gandi, but support for DNSSEC is not good everywhere. (DNSSEC is an optional security feature on Mail-in-a-Box. It’s nice to have but things will work just fine without it.)

Not all TLDs support DNSSEC either. If you will use Gandi, you should check their list of TLDs that support DNSSEC.

After you buy the domain name you’ll need to set it up, but that comes later so keep reading. Note that a Mail-in-a-Box box can handle the email for multiple domains names too — more on that later.

Your Box Has A Name

Every machine connected to the Internet has a name and an address.

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.

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.

For your Mail-in-a-Box, we recommend naming your box box + . + your domain name.

Josh’s Mail-in-a-Box is named box.occams.info. This is its hostname.

Your Mail-in-a-Box may handle the email for multiple domain names, but the box has a single name.

The Machine

Finding a cloud service provider

Now you will rent a machine, or a virtual part of a machine, somewhere in “the cloud.” We’ll call this machine your box. We recommend going over to Digital Ocean, Linode, 1&1, or Rimuhosting.com. (Most any cloud provider will do, but not Amazon Web Services because its network is often blocked to prevent users from sending spam.)

You must choose the Ubuntu 18.04 x64 (server edition) operating system and a machine with at least 512 MB of RAM. This setup currently costs around $5/month, depending on which provider you choose. We recommend you to use a box with 1 GB of RAM which costs around $10/month.

If you choose Digital Ocean, your machine is called a “droplet” and you must name your droplet the same as its hostname.

Josh’s droplet would be named box.occams.info (if Josh used Digital Ocean).

If you have a choice, choose a location for your machine that is near you — it’ll be faster! And if disabling IPv6 is an option, disable it.

Reverse DNS

Each cloud provider will have different instructions for setting up “reverse DNS.” You must follow your cloud provider’s instructions for setting the reverse DNS of your box to your box’s hostname.

If you are using Digital Ocean, your reverse DNS is already done. (They automatically set it to what you entered as your droplet’s name, which per the instructions above was your box’s hostname.) Linode’s instructions are here, but you may not be able to set the reverse DNS on Linode until after you have finished the rest of this guide (Linode only accepts reverse DNS changes once the forward DNS is working, which your box will handle by the end of this guide). 1&1’s instructions are here.

Josh’s box’s reverse DNS is set to the same as the box’s hostname: box.occams.info.

Locate the machine’s IP address

Your cloud provider will also now tell you the IP address of your machine. It looks like 123.123.123.123.

Josh’s box’s IP address is 94.76.202.152.

Sometimes you might be assigned an IP address that is on a spam block list. You may wish to use a tool such as MXToolbox to ensure your IP address is not on these block lists. If you find your assigned IP is on a blacklist, you might have luck requesting a "clean" IP from your provider, or creating a new host if you're using a VPS service.

Firewall settings

If your machine is behind a hardware firewall (or virtual equivalent, such as an AWS security group), ensure that the following ports are open: 22 (SSH), 25 (SMTP), 53 (DNS; must be open for both tcp & udp), 80 (HTTP), 443 (HTTPS), 587 (SMTP submission), 993 (IMAP), 995 (POP) and 4190 (Sieve). It doesn’t hurt to block other ports, but your box will take care of that itself by configuring a software firewall on the machine itself.

Domain Name Configuration — Glue Records

We’ll now go back to your domain name registrar to associate your domain name with your box’s IP address. This has two parts: glue records and nameservers.

Advanced Usage with External DNS: If you are using an external DNS provider, e.g. if you already have a website on your domain name, you may skip this section. However, we recommend that you continue and let your box take over your DNS so that it can set it up securely and correctly for email. If you choose to skip this section, pay special attention to “System status & DNS” toward the end.

Glue Records

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.

The way this works varies from registrar to registrar, but it goes something like this:

First, you’ll create two “glue records.” The purpose of glue records is to say that your box is becoming a part of the domain name system. These records go by different names at different registrars, so also look out for “hostnames” or “child nameservers.”. This will not be found in a DNS control panel. [Gandi instructions | GoDaddy instructions]

A glue record consists of a hostname and an IP address. You will need two: ns1. + your box’s hostname and ns2. + your box’s hostname. (They stand for “nameserver one” and “nameserver two”.) For the IP address, enter the IP address of your box.

Josh’s box’s hostname is box.occams.info. The two glue records are for ns1.box.occams.info and ns2.box.occams.info and list the box’s IP address of 94.76.202.152.

It looks something like what’s shown here:

Your registrar may ask you to enter these hostnames with the domain name part omitted, as mine did in this case. If so, enter the part of the hostname up to the domain name.

Josh’s domain name is occams.info. The two glue hostnames are ns1.box.occams.info and ns2.box.occams.info, but his registrar asks him to enter them with “.occams.info” omitted leaving just ns1.box and ns2.box.

If your Mail-in-a-Box is handling mail for multiple domains, you only do glue records once (for your first domain name). Additional domain names skip this step.

Some domain name TLDs and some registrars will require that you enter two glue records with different IP addresses. That won’t work for Mail-in-a-Box’s typical setup since your machine will only have one IP address. You can either set up secondary DNS servers to get around this limitation (it’s not hard, but it’s more work), or use a different domain name under a different TLD or a different registrar.

Domain Name Configuration — Nameservers

Advanced Usage with External DNS: If you skipped the previous section, you will skip this one too and follow your external DNS provider’s instructions instead. If you skip this section, pay special attention to “System status & DNS” toward the end.

Nameservers

Now you’ll tell your domain registrar that your domain name’s nameservers are ns1. + your box’s hostname and ns2. + your box’s hostname.

You will usually be turning off the registrar’s provided nameservers and turning on custom servers. This is usually not found in the domain name’s DNS control panel. You will be disabling that control panel.

Here’s what that looks like in my registrar:

Don’t worry if you are confused about what this all means. It is complicated — we all get confused at this point.

If you add another domain name to your box later, this section is repeated for each domain name you associate with your box. All domain names on the box will use the exact same two nameservers. So if you used ns1.yourdomain.com for your first domain, use exactly the same thing for your second domain name. (You do NOT use ns1.yourseconddomain.com, etc.)

DNSSEC DS Record

DNSSEC adds a security layer on top of DNS, in the same way that HTTPS adds a security layer to HTTP. It is not necessary, but it is recommended. When enabled, mail between Mail-in-a-Boxes will always be encrypted.

Your box’s control panel will tell you to come back to your domain name registrar at the end to configure the DNSSEC DS record. It’s not something the box can set up on its own, but you also can’t configure it until after the box itself is set up — so you will come back to this.

Setting Up The Box

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:

ssh -i yourkey.pem ubuntu@10.20.30.40

Once inside, you will now get the Mail-in-a-Box code onto your box and start its setup. Copy and paste this into your terminal and hit enter:

curl -s https://mailinabox.email/setup.sh | sudo -E bash

Advanced: To change the default location where Mail-in-a-Box stores all of its data, you can set an environment variable named 'STORAGE_ROOT' before running the setup script.


export STORAGE_ROOT=/your/desired/path

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.

This password will be used to login to webmail, the administrative interface, and on your devices. It will not be used to log onto your Mail-in-a-Box server using SSH (that’s what you did above).

It is always safe to re-run the setup, either because something went wrong or you just want to see it again. You can do so by following two the steps above again or just running sudo mailinabox from the command line.

When it comes time to update to a newer release of Mail-in-a-Box, you’ll literally just run the above two commands again (ssh ... and then curl ..., as above) on your existing machine.

The Administrative Interface

Connecting for the First Time

When the setup script is done running, you’ll been given instructions on how to access your box’s web-based administrative control panel:

Your Mail-in-a-Box is running. Please log in to the control panel for further instructions at:     https://94.76.202.152/admin You will be alerted that the website has an invalid certificate. Check that the certificate fingerprint matches: C0:9B:FF:04:2B:2D:8F:47:5A:8B:D5:88:B7:05:D3:4B:6C:22:80:5F

Your SSL certificate is not yet signed so you will get a security warning when you visit the administrative URL. There is a way to proceed securely if you use Mozilla Firefox.

  1. Open the URL in Firefox. Firefox will say This Connection is Untrusted.
  2. Click on I Understand the Risks.
  3. Click on Add Exception.
  4. Click on View.
  5. Compare the SHA1 Fingerprint in Firefox to the fingerpint reported by Mail-in-a-Box’s setup script in your SSH connection (see the example above). If they match, it is safe to continue.
  6. Click on Close.
  7. Click on Confirm Security Exception. It is safe (and convenient!) to permanently store the exception.

The page will then load securely.

You can also get a signed SSL certificate later (see below) so you don’t have to go through these steps.

System status & DNS

Log in to the administrative control panel with the email address and password that you provided during Mail-in-a-Box’s setup. Proceed to the System Status Checks.

These checks will guide you toward finishing your setup:

The control panel will check if your DNS is set up correctly. Things related to the domain name system sometimes take several minutes, or much longer, to update. This is called DNS propagation. Wait for the control panel to report no DNS problems — reload the page every 15 minutes or so. If problems persist, something went wrong.

DNSSEC is an optional step that adds additional security to DNS. The control panel will walk you through setting up DNSSEC as well. You will need to go back to your domain name registrar and enter additional information.

If you skipped the DNS settings earlier, you should now go to the DNS (Custom/External) > External DNS section of the control panel and copy the DNS records into your own DNS control panel.

Getting a signed TLS (SSL) certificate

Use the TLS Certificates page of the control panel to provision a free TLS (SSL) certificate from Let’s Encrypt. If you don't want to use Let's Encrypt, you can also add any other certificate and import it in the box. The box will help you by generating a private key. Just follow the instructions given in the control panel.

Checking your email

The administrative control panel will provide instructions for how to check your email with webmail, IMAP/SMTP, or Exchange/ActiveSync.

You can also add or remove additional email accounts and mail aliases (forwarders).

Advanced tools

The administrative control panel also helps you with...

Keeping Your Box Humming

Follow @Mailinabox on Twitter so you know when we post any updates to Mail-in-a-Box.

Check your box’s control panel periodically to see that the System Status Checks report everything is OK. Your box will also automatically email you whenever anything changes in the status checks.

Remember that it is always safe to re-run the setup script by typing sudo mailinabox at the SSH terminal prompt.

Finally, consult the Maintenance Guide for further questions.

Systems Checks

If you want to double-check that your system is configured correctly, here are some tools:

https://mailinabox.email/guide.html