When the box breaks

First, breathe. BOA fixes most problems on its own, usually within a few minutes. Every single minute, in the background, it checks its own services and restarts anything that fell over. So a good chunk of the time, the honest advice is: wait five minutes and look again. The thing that was broken has often quietly fixed itself while you were reading this.

This page is your calm, in-order checklist for the moments when it hasn't. We go through the problems in the order they actually happen — the common, easy ones first — and for each one there's one thing to check and one thing to do. Work down the list. Don't skip ahead to drastic steps; nine times out of ten the fix is near the top.

If you only remember one rule: do the gentle thing first, and give BOA a few minutes to help before you reach for the big hammer.

Before anything: is it your box, or is it you?

The single most common "my box is down" panic is not the box at all — it's your own connection getting firewall-blocked. So the very first check is: can anyone else reach the box?

  • Pull out your phone, turn off wifi so it's on mobile data (a different internet connection), and open your site in the phone's browser.
  • If the site loads on your phone but not on your laptop, the box is fine — your home/office IP got blocked. Jump to 1. You can't reach the box at all.
  • If it's down from your phone too, the box itself has a problem — carry on down the list.

This 30-second test saves an enormous amount of needless worry. Do it first, every time.

1. You can't reach the box at all

SSH won't connect, the site won't load, everything times out. Before assuming the worst: BOA's firewall may have blocked your IP, not broken the box. This is by far the most common cause, and it's completely recoverable.

Why this happens

BOA runs a strict firewall (CSF) that automatically blocks IPs behaving like an attack: repeated wrong SSH passwords, port scanning, or hammering the site too fast. If you fat-fingered your SSH password a few times, or ran a script that knocked too hard, your own IP can get caught. The good news: most of these blocks are temporary and lift themselves after a while — often somewhere between about 15 minutes and an hour. The catch is that repeated offences (many failed logins in a row) can earn a longer, sometimes permanent block that will not expire on its own — so waiting isn't guaranteed to be enough, and the reliable fix below (get in another way and clear the block yourself) is the one to lean on.

Check it: reach the box from a different place

You need a way in that isn't your blocked IP. In rough order of ease:

  1. A second connection you already have — your phone on mobile data, a VPN, a different office, a jump host. If you can SSH in from there, you're set.
  2. Your provider's web console — nearly every VPS and dedicated-server provider has a "Console", "VNC", or "KVM" button in their control panel. That console reaches your box's terminal directly, completely bypassing the firewall. This always works even when SSH is fully blocked, so it's your reliable way back in. Log in there as root.

Fix it: was it your IP? Then unblock your IP

Once you're in (via any route above), as root, check whether your address is actually blocked. Replace YOUR.IP.HERE with your real public IP — if you don't know it, visit a "what is my IP" site from the machine that can't connect:

csf -g YOUR.IP.HERE

csf -g searches the firewall for that IP and tells you if (and why) it's blocked. If it shows a block, remove it and then allow your IP so it can't happen again:

csf -dr YOUR.IP.HERE        # remove the block on your IP
csf -a  YOUR.IP.HERE        # allow your IP going forward

To make that "allow" stick permanently (survive reboots and future blocks), add it to the allow list file and reload:

echo "YOUR.IP.HERE # my home" >> /etc/csf/csf.allow
csf -r

That's the whole fix. Reconnect over SSH from your now-allowed IP.

If you're truly locked out with no console

Worst case — no second connection and no provider console:

  1. Wait a while and try once. A temporary block often clears within about 15 minutes to an hour. Crucially, don't keep hammering the connection while you wait — repeated failed attempts can escalate a short block into a much longer or permanent one. Wait, then try a single time.
  2. Find your provider's console. This is the real answer, and it's worth hunting for — almost every provider has a "Console"/"VNC"/"KVM" button somewhere in their panel. It reaches the box directly, past the firewall, so it works even when a block won't expire on its own. Get in that way and clear your IP with the steps above.
  3. Restore from a snapshot (see the last-resort ladder) only if nothing else works.

A tip that prevents most of these lockouts: add your home, office, and VPN IPs to /etc/csf/csf.allow now, while everything is working — one IP per line, then csf -r. An allowed IP is much harder to lock yourself out from. It's five minutes of insurance against a very stressful afternoon.

2. The site is up but slow, or briefly "paused"

Sometimes the box is reachable but the site crawls, or for a minute or two it refuses connections and then recovers. Before you touch anything: this is often BOA protecting the box on purpose.

When traffic (or an attack) spikes hard enough to threaten the whole machine, BOA's load protection deliberately pauses the web server for a short spell to shed the load, rather than let the box fall over completely and take every site down with it. It's a safety valve. And critically — it lifts the pause by itself the moment the load drops back to normal. BOA re-measures the load every few seconds, so once the spike passes normal service resumes within about ten seconds — automatically, with nothing for you to do.

So the fix here is usually: wait a few minutes. A short slow patch or a one-minute pause under a load spike is BOA working correctly, not breaking. Don't restart anything — you'd just interrupt the recovery. Give it a little time and it comes back on its own.

If the slowness lasts much longer than a few minutes, or keeps recurring all day, that's beyond a quick self-heal and worth escalating — see Going further at the end.

3. A single service died (nginx, PHP, or the database)

The site throws an error, or one part misbehaves, but you can still SSH in. Maybe the web server, the PHP engine, or the database hiccupped.

Here's the reassuring part: you very likely don't need to do anything. BOA runs a health check on all of these every single minute, around the clock. If it finds the web server, the PHP engine, or the database stopped or wedged, it restarts it for you automatically — no login, no command from you.

So the right first move is patience, not typing:

  1. Wait a minute or two. BOA's next check runs within 60 seconds and will very likely bring the service back.
  2. Reload your site. If it's back, you're done — BOA handled it.

A reasonable wait before you get involved is about five minutes (that's several of BOA's automatic check-and-restart cycles). If a service is still down after five quiet minutes, then it's not a simple hiccup BOA can shrug off, and it's time to gather a little information (see How to ask for help) rather than guess.

Resist the urge to start manually restarting things in the first minute — you'll often just collide with BOA's own restart that was about to happen anyway.

4. The disk filled up

A full disk causes weird, misleading breakage — sites error out, uploads fail, the database gets unhappy — because nothing on the box has room to write. It's worth an explicit check because the symptoms rarely say "disk full" out loud.

Check it

As root:

df -h

Read the Use% column. Anything at 100% (or a nervous 95%+) on the main partition is your culprit.

Free up space safely

Two safe, beginner-friendly things you can do:

  • Old backups pile up. BOA keeps per-site backups, and on a small disk they add up fast. It's safe to delete the oldest backup archives once you're sure you have a recent good one elsewhere. Don't blow away all backups — keep at least the most recent.
  • Old logs. Log files grow over time; the very old, already-rotated ones (names ending in .gz or with old dates) are safe to remove.

Clear a few gigabytes, then re-run df -h to confirm you've got breathing room, and reload your site.

If it keeps filling up

If the disk is simply too small for what you're hosting, the real fix is a bigger disk — you ask your provider to grow the VM's disk, and then, because the box doesn't notice the extra space on its own, you grow the partition and filesystem to match. There's a dedicated step-by-step for exactly that: Resizing the root disk walks you through it safely. Take a snapshot before you start, as that page reminds you.

5. The last-resort ladder

You've worked down the list, given BOA its few minutes to self-heal, and the box is still genuinely broken. Now — and only now — climb this ladder, one rung at a time, least drastic first. Do not jump to the bottom rung.

Rung 1 — a clean reboot

A surprising number of stubborn states clear with a restart. BOA has its own tidy reboot command that shuts things down in the right order:

boa reboot

Your SSH session will drop; wait a minute or two, reconnect, and check the site. If a new kernel was waiting, this also switches you onto it. A single clean reboot fixes a lot — try this before anything more drastic.

Rung 2 — restore from a snapshot

The true last resort. If the box is unrecoverable — you can't reach it at all, even a reboot didn't help — restore the whole VM from a snapshot taken before things went wrong, using your provider's control panel.

This is exactly why the snapshot advice keeps coming up: a recent snapshot is your ultimate undo button. If you take nothing else from this page, take this — snapshot your box on a schedule (most providers can do it automatically), and especially right before any big change. A restore rewinds the whole machine to a known-good moment. It's the safety net under every other step here.

How to ask for help, the right way

If you're stuck and reaching out for help — the community, a support channel, a knowledgeable friend — you'll get a good answer far faster if you bring the right information up front. Two things do most of the work.

1. The output of boa info. As root, run:

boa info

It prints a tidy summary of your box in one place: BOA and system versions, the database engine, uptime and current load, current and pending kernel, CPU, RAM, disk usage per partition, and which key services are up or down. Copy that whole block into your help request — it answers half the questions someone would otherwise have to ask you.

2. The relevant log. Include the log for whatever broke — don't paste everything, just the fitting one:

  • An upgrade went wrong: /var/log/barracuda_log.txt
  • A service kept dying: the matching incident log under /var/log/boa/ — nginx.incident.log, php.incident.log, or mysql.incident.log. These record what BOA saw and every restart it attempted, which is exactly what a helper needs.
  • Load / pause trouble: /var/log/boa/high.load.incident.log and /var/log/boa/load_guard.log.

Grab the last chunk of the relevant file, for example:

tail -n 100 /var/log/boa/nginx.incident.log

With boa info plus the right log, you've handed over almost everything anyone needs to help you — and you'll usually get a real answer instead of a string of "what does X say?" questions.

Going further

You've now got the beginner playbook: check if it's your own IP, give BOA a few minutes to self-heal, watch the disk, and use the reboot-then-restore ladder as a last resort. That covers the large majority of "my box broke" moments. The topics below go deeper — they assume you're comfortable on the command line and root on the box.

  • Advanced (root required): Operating → Auto-healing — exactly which services BOA watches, how it decides something is wedged, and every restart it performs on its own.
  • Advanced (root required): Operating → Load control — the full load-pause mechanism: what trips it, how it sheds load, and when it lifts.
  • Advanced (root required): Operating → IP-blocked recovery — the complete firewall-block toolkit, including web-abuse bans and the CSF-to-Nginx ban lifecycle.
  • Advanced (root required): Operating → 502 Bad Gateway — diagnosing a web/PHP gateway error that outlasts a self-heal.
  • Advanced (root required): Operating → Task failures — when an Aegir task itself is stuck or failing, not the box.

Related

  • Keeping current — the day-to-day upkeep (SKYNET, running an upgrade) that prevents a lot of breakage in the first place.
  • Resizing the root disk — the full, safe walk-through for when a full disk means you've genuinely outgrown it and need a bigger one.
  • Essential settings — where the admin email lives, so BOA's incident and completion notices actually reach you.
  • Discontinued features — recovery tricks in older BOA guides that no longer apply.