This page covers frequently asked questions about how to configure a running Mail-in-a-Box and how to keep it up to date. For help setting up a new box, see the setup guide.
Is something not working right? Start here. Please follow these steps before asking a question on the discussion forum:
https://box.yourdomain.com/admin. Everything should be green. Anything not green may help you diagnose the problem on your own.
sshcommand that you used during setup) and running
sudo mailinabox. Then check the System Status Checks page again.
sudo reboot. Once the box has started up, check the System Status Checks page again.
Please do these steps first. If you’ve done these steps, then head to the discussion forum to ask your question. In your post:
If you figure out the problem on your own, you are also welcome to write up your experience on the discussion forum so that it might help others.
Your box can host email and serve static websites for more than one domain name. To set up additional domain names, just follow three steps:
Mail-in-a-Box is based on a collection of other software packages provided by Ubuntu. We call these packages system software packages. These packages may have security or other functionality updates.
You should periodically update the system software on your box. The box will automatically install security updates as they are made available by Ubuntu, but your control panel will let you know if a reboot is needed or if non-security updates are available for you to install.
When indicated to do so, log into your machine with SSH (using the same
ssh command that you used during setup) and then type:
sudo apt-get update && sudo apt-get upgrade
If prompted to reboot, type:
You should move to the latest Mail-in-a-Box release as releases are posted, especially if an update addresses any security issues, although you do not necessarily need to do so. We will post release announcements to our twitter account @mailinabox, the announcements section of the discussion forum, and our Slack chat (see the homepage).
Check the release notes prior to updating to see what’s been changed in the latest version.
If you are upgrading from Mail-in-a-Box version v0.30 or earlier on Ubuntu 14.04 to version 0.40 or later on Ubuntu 18.04:
1. Follow the instructions in this section to uprade your existing Mail-in-a-Box to v0.30, the last version supporting Ubuntu 14.04.
2. After your existing box is up to date with v0.30, then proceed to the section below Moving to a New Box to migrate your system to a new machine running Ubuntu 18.04 and version 0.40 of Mail-in-a-Box.
To upgrade Mail-in-a-Box to the latest release, first log into your machine using
SSH in exactly the same manner as when you were setting up the box (see the setup guide section called Setting Up The Box for a reminder of what that looked like).
Then, once logged in, run:
curl -s https://mailinabox.email/setup.sh | sudo bash
This is actually the same command you ran when setting up the box. It does upgrades too.
If you want to move your Mail-in-a-Box installation to a new machine (e.g. you’re getting more memory, getting a new IP address, etc.), or if something is horribly wrong with your box, you can easily move all of your data to a new machine. This is also the process for upgrading a Mail-in-a-Box box from v0.30 or earlier on Ubuntu 14.04 to version 0.40 or later on Ubuntu 18.04.
Even if your box is working fine, it’s a good idea to test out this procedure from time to time so that you can verify that your backups are working and that you haven’t lost the backup secret key.
Moving your data to a new box is only supported if your existing Mail-in-a-Box box is up to date with the latest version of Mail-in-a-Box. So follow the steps in Upgrading Mail-in-a-Box above to upgrade to the latest version of Mail-in-a-Box before proceeding.
If you are upgrading from Mail-in-a-Box version v0.30 or earlier on Ubuntu 14.04 to version v0.40 or later on Ubuntu 18.04, you must follow the instructions in the previous section to uprade your existing Mail-in-a-Box to v0.30, the last version supporting Ubuntu 14.04, before proceeding. Complete instructions for updating to Ubuntu 18.04 and v0.40 are posted on the forum.
You will be performing a backup + restore to move your data to the new box. To ensure you have a final backup, first block access to your box to all services besides SSH so that no new emails are sent or received. Log into your old machine using SSH and run:
sudo ufw reset sudo ufw allow 22 # enable SSH access so you don't lock yourself out sudo ufw enable
Then perform a backup to ensure you have everything backed up since the last nightly backup run. Run:
cd mailinabox sudo management/backup.py
Start by creating a new Mail-in-a-Box machine: Spin up a new machine following the setup guide’s section The Machine. Use as many of the same settings as on your original box as makes sense. On Digital Ocean you will need to use the exact same name for your box as you did previously or reverse DNS won’t work.
Then follow the steps in the setup guide’s section Setting Up The Box. When you are prompted for the box’s hostname, you will need to use the hostname that you are currently using.
Next you’ll restore your mail data and other files to the new machine.
Your backups are encrypted, and you will need your backup secret key to restore from the backup.
You should have already stored the backup secret key in a safe place — like in your home — per the backup instructions in the control panel. If you haven’t done that yet... now is the time! The file is located on your old box at
/home/user-data/backup/secret_key.txt. Copy that file to a safe place now.
Copy that file onto your new box. Any SFTP program like FileZilla can help you with that. (SFTP is like SSH, so you will use the same login credentials as you use with SSH.)
If you are using the default backup method, which stores backups on the box itself, then hopefully you have figured out how to periodically copy those files somewhere else safe — otherwise what’s the point!
Using any SFTP program like FileZilla (or
scp if you know how) copy your backups from wherever you stored them to somewhere on your new machine. If your old box is still running, then just copy them from
/home/user-data/backup/encrypted on your old box.
Then restore the files:
export PASSPHRASE=$(cat your_backup_secret_key_file.txt) sudo -E duplicity restore --force file:///path/to/copied/files /home/user-data/
If your backups are stored in Amazon S3, get your account credentials handy and then run a duplicity restore:
export AWS_ACCESS_KEY_ID=paste your AWS access key ID here export AWS_SECRET_ACCESS_KEY=paste your AWS secret access key here export PASSPHRASE=$(cat your_backup_secret_key_file.txt) sudo -E duplicity restore --force s3://s3.amazonaws.com/your-bucket-name/your-backup-path /home/user-data/
You may have to adjust the S3 URL depending on what AWS region you use. You can find the AWS Regions and Endpoints here
Re-run Mail-in-a-Box setup now that your old files are back:
Your box should be functioning now. Log into the control panel on your new box to see if things look right.
Finally, update your domain name’s glue records to the new machine’s IP address (see the setup guide’s section on glue records.
DNS can take a few hours to update, so wait a while, and then see if the control panel’s status checks report any problems and that your devices are picking up mail on your new box.
(Skip this if you are just testing your backups.)