-
Notifications
You must be signed in to change notification settings - Fork 46
/
maintenance.html
252 lines (162 loc) · 16.5 KB
/
maintenance.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
<!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 Maintenance Guide</title>
<meta name="description" content="Maintenance instructions for Mail-in-a-Box. Take back control of your email with this easy-to-deploy mail server in a box." />
<meta property="og:site_name" content="Mail-in-a-Box">
<meta name="twitter:creator" content="@joshdata" />
<meta name="twitter:creator:id" content="352686442" />
<meta name="twitter:site" content="@mailinabox" />
<meta name="twitter:site:id" content="2612357965" />
<meta name="og:image" content="https://mailinabox.email/static/logo.png" />
<link rel="vcs-git" href="https://github.com/mail-in-a-box/mailinabox.email" title="code for Mail-in-a-Box website" />
<link rel="icon" type="image/png" href="/static/logo_small.png">
<link rel="apple-touch-icon" type="image/png" href="/static/logo_small.png">
<link rel="stylesheet" href="static/vendor/bootstrap/css/bootstrap.min.css" />
<link rel="stylesheet" href="guides.css" />
<style>
</style>
</head>
<body data-spy="scroll" data-target="#nav">
<a href="https://github.com/mail-in-a-box/mailinabox.email/blob/main/maintenance.html" 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 sticky-top">
<p style="margin: 0 0 .5em 14px; border-bottom: 1px solid #CCC; color: #888;">Table of Contents</p>
<ul class="nav flex-column">
<li class="nav-item"><a class="nav-link" href="#something-went-wrong">Something Went Wrong</a></li>
<li class="nav-item"><a class="nav-link" href="#multiple-domains">Multiple Domains</a></li>
<li class="nav-item"><a class="nav-link" href="#updating-software">Updating System Software</a></li>
<li class="nav-item"><a class="nav-link" href="#upgrade">Upgrading Mail-in-a-Box</a></li>
<li class="nav-item"><a class="nav-link" href="#moving-boxes">Moving to a New Box</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 Maintenance Guide</h1>
<p>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 <a href="guide.html">setup guide</a>.</p>
<h2 id="something-went-wrong">Something Went Wrong!</h2>
<p>Is something not working right? Start here. Please follow these steps before asking a question on the discussion forum:</p>
<ol>
<li>Check your System Status Checks page in the control panel at <code>https://box.yourdomain.com/admin</code>. Everything should be green. Anything not green may help you diagnose the problem on your own.</li>
<li>Re-run the setup by logging into your box (using the same <code>ssh</code> command that you used <a href="guide.html#setup">during setup</a>) and running <code>sudo mailinabox</code>. Then check the System Status Checks page again.</li>
<li>Restart your box by logging in with SSH and then typing <code>sudo reboot</code>. Once the box has started up, check the System Status Checks page again.</li>
</ol>
<p>Please do these steps first. If you’ve done these steps, then head to the <a href="https://discourse.mailinabox.email">discussion forum</a> to ask your question. In your post:</p>
<ol>
<li>Describe the problem you are having. Instead of saying “it doesn’t work”, write the error message you see, post a screenshot, or describe what you are seeing that you don’t want to be seeing.</li>
<li>Mention that you “checked the status page, re-ran setup, and rebooted the box”, per the steps above, so that anyone answering knows what you have tried so far. If you don’t mention this, someone may ask you to do it before providing other assistance.</li>
<li>If everything in the System Status Checks is green, mention that by saying “all checks are green”. If something isn’t green, mention it.</li>
</ol>
<p>If you figure out the problem on your own, you are also welcome to write up your experience on the <a href="https://discourse.mailinabox.email">discussion forum</a> so that it might help others.</p>
<h2 id="multiple-domains">Multiple Domain Names</h2>
<p>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:</p>
<ol>
<li>Buy an additional domain name if you don’t yet own it. See the <a href="guide.html#domain-name-registration">Your Domain Name</a> section of the setup guide for tips.</li>
<li>Configure its nameservers to be the same nameservers on your first domain name. Follow the <a href="guide.html#domain-name-nameservers">Domain Name Configuration — Nameservers</a> section of the setup guide for instructions.</li>
<li>Add an email account (user) or alias on your box for the new domain name using the control panel. If you only plan to serve a website, still add an email address or alias — that’s how the box knows to handle that domain name.</li>
</ol>
<h2 id="updating-software">Updating System Software</h2>
<p>Mail-in-a-Box is based on a collection of other software packages provided by <a href="https://www.ubuntu.com/">Ubuntu</a>. We call these packages system software packages. These packages may have security or other functionality updates.</p>
<p>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.</p>
<p>When indicated to do so, log into your machine with SSH (using the same <code>ssh</code> command that you used <a href="guide.html#setup">during setup</a>) and then type:</p>
<pre>sudo apt-get update && sudo apt-get upgrade</pre>
<p>If prompted to reboot, type:</p>
<pre>sudo reboot</pre>
<p>We will post security advisories to our twitter account <a href="https://twitter.com/mailinabox">@mailinabox</a>, the <a href="https://discourse.mailinabox.email/c/announcements">announcements section of the discussion forum</a>, and our Slack chat (see the homepage).</p>
<h2 id="upgrade">Upgrading Mail-in-a-Box</h2>
<p>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 <a href="https://twitter.com/mailinabox">@mailinabox</a>, the <a href="https://discourse.mailinabox.email/c/announcements">announcements section of the discussion forum</a>, and our Slack chat (see the homepage).</p>
<p>Check the <a href="https://github.com/mail-in-a-box/mailinabox/blob/main/CHANGELOG.md">release notes</a> prior to updating to see what’s been changed in the latest version.</p>
<div class="alert alert-warning" role="alert">
<p>If you are upgrading from Mail-in-a-Box version 5x or earlier on <strong>Ubuntu 18.04</strong> to version 60 or later on <strong>Ubuntu 22.04</strong>:</p>
<p>1. Follow the instructions in this section to upgrade your <em>existing</em> Mail-in-a-Box box (running Ubuntu 18.04) to the latest version of Mail-in-a-Box supporting that version of Ubuntu.</p>
<p>2. After your existing box is up to date with the latest version of Mail-in-a-Box supporting Ubuntu 18.04, then proceed to the section below <strong>Moving to a New Box</strong> to migrate your system to a new machine running Ubuntu 22.04 and version 60 (or later) of Mail-in-a-Box.</p>
</div>
<p>To upgrade Mail-in-a-Box to the latest release, first close any web browser pages related to your instance of Mail-in-a-Box, then log into your machine using <code>SSH</code> in exactly the same manner as when you were setting up the box (see the setup guide section called <a href="guide.html#setup">Setting Up The Box</a> for a reminder of what that looked like).</p>
<p>Then, once logged in, run:</p>
<pre>curl -s https://mailinabox.email/setup.sh | sudo bash</pre>
<p>This is actually the same command you ran when setting up the box. It does upgrades too.</p>
<div class="alert alert-warning" role="alert">
<p>If you see an error message similar to:</p>
<p>Could not get lock /var/lib/dpkg/lock-frontend - open (11: Resource temporarily unavailable)</p>
<p>Unable to acquire the dpkg frontend lock (/var/lib/dpkg/lock-frontend), is another process using it?</p>
<p>then be sure that you have closed any browser pages for your Mail-in-a-Box instance and run the above command again.</p>
</div>
<h2 id="moving-boxes">Moving to a New Box / Testing Backups</h2>
<p>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. <strong>This is also the process for upgrading a Mail-in-a-Box box from version 5x or earlier on Ubuntu 18.04 to version 60 or later on Ubuntu 22.04</strong> (<a href="https://discourse.mailinabox.email/t/version-60-for-ubuntu-22-04-is-released/9558">see the release announcement for details</a>).</p>
<div class="alert alert-success" role="alert">
<p>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.</p>
</div>
<h3>Upgrade your old box first!</h3>
<p>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 <i>Upgrading Mail-in-a-Box</i> above to upgrade to the latest version of Mail-in-a-Box before proceeding.</p>
<div class="alert alert-warning" role="alert">
If you are upgrading from Mail-in-a-Box version v0.50 or earlier on <strong>Ubuntu 18.04</strong> to version 60 or later on <strong>Ubuntu 22.04</strong>, you must follow the instructions in the previous section to upgrade your existing Mail-in-a-Box to v0.51 or a later "5x" version first.
</div>
<h3>Perform one last backup on the old machine</h3>
<p>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:</p>
<pre>sudo ufw reset
sudo ufw allow 22 # enable SSH access so you don't lock yourself out
sudo ufw enable</pre>
<p>Then perform a backup to ensure you have everything backed up since the last nightly backup run. Run:</p>
<pre>cd mailinabox
sudo management/backup.py</pre>
<h3>Create a new box</h3>
<p>Start by creating a new Mail-in-a-Box machine: Spin up a new machine following the setup guide’s section <a href="guide.html#machine">The Machine</a>. <em>Use as many of the same settings as on your original box as makes sense.</em> 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.</p>
<p>Then follow the steps in the setup guide’s section <a href="guide.html#setup">Setting Up The Box</a>. When you are prompted for the box’s hostname, you will need to use the hostname that you are currently using.</p>
<h3>Clean up SSL files</h3>
<p>When you set up a new machine, a self-signed SSL certificate will be generated. The presence of this data will cause nginx to not restart properly, so let's delete this data. Run:</p>
<pre> sudo rm -rf /home/user-data/ssl/* </pre>
<h3>Restore your mail data (and other files)</h3>
<p>Next you’ll restore your mail data and other files to the new machine.</p>
<h4>Locating your backup secret key</h4>
<p>Your backups are encrypted, and you will need your backup secret key to restore from the backup.</p>
<p>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 <code>/home/user-data/backup/secret_key.txt</code>. Copy that file to a safe place now.</p>
<p>Copy that file onto your new box. Any SFTP program like <a href="https://filezilla-project.org/">FileZilla</a> can help you with that. (SFTP is like SSH, so you will use the same login credentials as you use with SSH.)</p>
<h4>Restoring backup files</h4>
<h5>Local backups</h5>
<p>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!</p>
<p>Using any SFTP program like <a href="https://filezilla-project.org/">FileZilla</a> (or <code>scp</code> 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 <code>/home/user-data/backup/encrypted</code> on your old box.</p>
<p>Then restore the files:</p>
<pre>export PASSPHRASE=$(cat your_backup_secret_key_file.txt)
sudo -E duplicity restore --force file:///path/to/copied/files /home/user-data/</pre>
<h5>Amazon S3 backups</h5>
<p>If your backups are stored in Amazon S3, get your account credentials handy and then run a duplicity restore:</p>
<pre>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/</pre>
<p>You may have to adjust the S3 URL depending on what AWS region you use. You can find the AWS Regions and Endpoints <a href="https://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region">here</a></p>
<h5>S3 compatible backups</h5>
<p>If your backups are stored in an S3 compatible storage which is not amazon, you have to set the s3 endpoint url:</p>
<pre>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://your-bucket-name/your-backup-path /home/user-data/ --s3-endpoint-url=https://host</pre>
<h3>Re-configure the box</h3>
<p>Re-run Mail-in-a-Box setup now that your old files are back:</p>
<pre>sudo mailinabox</pre>
<p>Your box should be functioning now. Log into the control panel on your new box to see if things look right.</p>
<h3>Update your DNS</h3>
<p>Finally, update your domain name’s glue records to the new machine’s IP address (see the setup guide’s section on <a href="guide.html#machine">glue records</a>.</p>
<p>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.</p>
<p>(Skip this if you are just testing your backups.)</p>
<div class="hidden-xs" style="height: 200px"> </div>
</div>
</div>
</div>
<script src="static/vendor/jquery.js"> </script>
<script src="static/vendor/bootstrap/js/bootstrap.min.js"></script>
</body>
</html>