Essential settings

Good news first: BOA ships tuned for you. Almost every setting on your server already has a sensible default, chosen so a one-box self-hoster gets a fast, secure site without touching anything. You do not need to read a giant list of options and decide what each one does. For day-to-day running, there are only a handful of settings worth knowing about, and this page walks you through them gently.

If you just installed BOA and everything is working, you can skim this page, change the one email address below, and get on with your life. The rest is here for the day you actually need it.

The two files you might ever touch

BOA keeps its settings in plain-text files under /root. There are two you might open, and no others you need to think about:

  • /root/.barracuda.cnf — the host-wide file. Settings here apply to the whole box: your admin email, the auto-update switch, and so on. There is exactly one of these.
  • /root/.<user>.octopus.cnf — the per-instance file. BOA calls each hosting instance an Octopus instance, and each one gets its own file named after the instance's system user (for example /root/.o1.octopus.cnf). If you only run one instance, you have one of these; most beginners never need to open it.

Both are ordinary text files. Each meaningful line is one setting written as _NAME=value — one setting per line, nothing fancy.

How to edit them safely

The golden rule: change one line, save, and leave the rest alone. These files are long and full of settings you should never touch. You are looking for a single named line, changing its value, and saving.

  1. Open the file in a plain-text editor as root, for example nano /root/.barracuda.cnf.
  2. Find the line for the setting you want (each has a _NAME= at the start of the line).
  3. Change only the value to the right of the =. Keep the same shape — if the default wraps the value in quotes, keep the quotes.
  4. Do not delete other lines, and do not add stray spaces around the =.
  5. Save and close.

Most settings take effect on the next BOA run (an upgrade or the nightly maintenance pass). A few — like your admin email — are read whenever BOA next needs them. You do not need to restart anything by hand.

You have a safety net

You might worry: what if BOA overwrites my file? It does rewrite /root/.barracuda.cnf during installs and upgrades — that is how new settings get added and old ones kept current — but it never does so blindly. Before it rewrites that file, BOA snapshots your host-wide config first, automatically. It copies /root/.barracuda.cnf into a timestamped folder:

/var/backups/dragon/config/YYYY-MM-DD_HH-MM-SS/

Everything snapshotted during a single run lands in the same timestamped folder, so a complete "before" set stays together. This archive is kept permanently — BOA's normal housekeeping never purges it — and is locked down to root-only access. So if an upgrade ever changes something you did not expect, your previous version of /root/.barracuda.cnf is sitting right there, dated, ready to compare or copy back. You do not have to set this up; it just happens.

The short list worth knowing

Out of the hundreds of settings in /root/.barracuda.cnf, here are the few a self-hoster actually benefits from knowing. Everything else is safe to leave at its default.

_MY_EMAIL — your admin address (change this one)

This is the one setting you really should change. It is the email address BOA uses for you, the server admin — health alerts, upgrade notices, and reports all go here. Out of the box it is set to a placeholder:

_MY_EMAIL="notify@omega8.cc"

Change it to a real inbox you actually read, keeping the quotes:

_MY_EMAIL="you@example.com"

If you leave the placeholder in place, you simply won't receive the alerts BOA tries to send you — nothing breaks, but you'll be flying blind.

_SKYNET_MODE — the auto-update switch (leave it on)

BOA keeps itself current automatically: it updates its own tools, applies security fixes, and repairs the stack on its own. That behaviour is on by default — you will not even find a _SKYNET_MODE line in a fresh config, and that absence means it is active.

The only reason this setting exists is to switch auto-updates off, by adding this line:

_SKYNET_MODE=OFF

Our advice for a self-hoster: never add that line. Turning auto-updates off means you take on the job of keeping BOA secure and current by hand, which is exactly the work BOA is designed to do for you. If you ever see _SKYNET_MODE=OFF in your file and don't remember adding it, removing that line turns automatic updates back on.

For the wider picture of how BOA keeps itself current, see Keeping current.

_LE_CLIENT_NOTIFY — HTTPS-renewal notices (optional opt-out)

Your sites get free HTTPS certificates from Let's Encrypt, and BOA renews them automatically. When a renewal fails — almost always because a domain stopped pointing at your server or its DNS went missing — BOA can email the affected site's contact a plain-language heads-up so it can be fixed. These per-site notices are throttled to at most once every seven days, so nobody gets spammed. This is on by default:

_LE_CLIENT_NOTIFY=YES

If you are the only person using your box and you'd rather not send these client notices at all, opt out by setting it to NO:

_LE_CLIENT_NOTIFY=NO

Turning it off only silences the notice sent to the site's contact. You, as the server admin (_MY_EMAIL above), still get the full renewal-failure report either way — so you never lose visibility into a broken certificate.

Everything else: trust the defaults

That really is the short list. The remaining settings in /root/.barracuda.cnf control memory tuning, cache behaviour, database limits, firewall knobs, and dozens of other internals — all pre-tuned for a single self-hosted box. As a beginner root, you do not need to change any of them to run a healthy site. If a page or guide here doesn't tell you to change a specific setting, the safe move is to leave it alone.

Two habits will keep you out of trouble:

  • Change a setting only when a specific instruction (in these docs) tells you to, and only the setting it names.
  • After any change, remember the dated snapshot under /var/backups/dragon/config/ is your undo button.

Going further

Ready to look deeper, or need a setting that isn't on the short list above? The full catalogue of control files and every variable BOA understands lives in the Operating area — it assumes more comfort with the stack than this page does, so treat it as the next step up.

Advanced (root required): Operating → Control files overview — how all the BOA control files fit together.

Advanced (root required): Operating → The barracuda.cnf file — the complete host-wide settings reference.