Debian to Devuan (autoinit)

BOA runs best on Devuan — a Debian-based system without systemd. Devuan is what BOA is built and tested on, so it's the OS you want under a BOA server.

Sometimes you don't get a choice at install time. Many hosting providers only offer Debian images, not Devuan. That's fine: BOA ships a tool called autoinit that turns a fresh Debian box into a Devuan box for you, ready for the BOA install. You run it once, wait, and check a log. That's the whole task.

Do you even need this?

You need autoinit only if your box is running Debian right now.

• Your provider gave you a Debian image → yes, do this page first.
• Your provider offered Devuan and you picked it → you're already set; skip straight to installing BOA.

Not sure which you have? Run this:

cat /etc/devuan_version

If that prints a version (for example daedalus or a number), you're on Devuan already — nothing to do here, go install BOA. If it says No such file or directory, you're on Debian, and this page is for you.

The easy way: let BOA do it for you

You don't have to run autoinit as a separate step at all. If you start the BOA install on a Debian box, BOA notices and handles the conversion for you — it runs autoinit, reboots as needed, and then automatically runs your original install command once the box is on Devuan. One command in, a working BOA out.

This is the path we recommend for a beginner, because there's nothing to remember: you just start the install and walk away.

So the simplest thing you can do is skip ahead to Install BOA and run the install command there. When BOA sees it's on Debian, it will print a message like "we will run the autoinit for you first", kick off the conversion, and email you when the whole thing — conversion and BOA install — is finished. Expect to wait roughly 30 to 40 minutes before that email arrives. Log out, grab a coffee, and check back.

If you'd rather watch the conversion happen on its own first — or your provider's image is unusual and you want to confirm it worked before installing anything — run autoinit by hand using the steps below.

The hands-on way: run autoinit yourself

Log in as root and run two commands.

Step 1 — fetch BOA's tools (this gives you autoinit and the boa command):

wget -qO- https://files.boa.io/BOA.sh.txt | bash

Step 2 — start the conversion:

autoinit

That's it. autoinit now takes over. It will churn through a series of package upgrades and reboot the box one or more times on its own. This is normal and expected — do not reboot the server yourself while it's working, and don't panic when your SSH connection drops during a reboot.

How many hops that takes depends on where you start: autoinit advances one codename per pass and picks each hop from your current release — a Debian Trixie box converts straight to Devuan Excalibur, while older releases walk the chain one release at a time toward Daedalus (the full codename ladder is in the OS-upgrade map). Mind the database consequence of the starting image: a Trixie start lands on Excalibur, which runs only Percona 8.4 — fine for a fresh install, but worth knowing before you pick the newest image just because it is newest.

Advanced — two optional markers before the first run (root): touch /root/.autoinit-early-upgrade.cnf makes the very first pass fully upgrade the existing Debian system before the conversion machinery starts — worth it on a stale vendor image (it only works before the first run, never after). And on a routed IP block whose gateway lives outside your interface's subnet, write that gateway's address as the single line of /root/.net_gateway.cnf so networking survives the conversion reboots — on a normally-routed box, skip this; BOA maintains the file by itself.

What you'll see, and when

• The screen will show a lot of package activity, then the connection may close as the box reboots. That's the tool doing its job.
• There are long quiet stretches while big upgrades run. Silence is not a failure — leave it alone.
• Wait about 10 minutes, then log back in as root and check the log (below). If it's still going, wait a little longer and check again.

If the box must not reboot on its own. Some providers want reboots done from their own control panel, and some operators simply prefer to watch each stage. Create the brake file before you start:

touch /root/.manual-autoinit-reboot.cnf

At every point where autoinit would reboot, it now stops the cron service, waits 90 seconds and exits instead. The box stays up and restarting it is yours to do; because cron is stopped, the minutely job that resumes the conversion is parked too, so nothing moves until you restart the box. BOA never creates or removes this file, so it keeps working at every stage until you delete it. It does not remove the reboots — the conversion cannot finish without them, they are just yours to trigger.

Confirm it worked

Two quick checks tell you the conversion finished cleanly.

Check the log. autoinit writes its progress to /root/.autoinit.log:

cat /root/.autoinit.log

Near the bottom you're looking for this line:

[init] cycl ==> The system is now ready for boa install

In the log that line carries an AutoInit v.<version> [<time>] ==> stamp in front of it, so match the part shown above and ignore the stamp. If it's there, you're done — on a run BOA started for you, one further line follows it, naming the install command BOA then launched.

Check the OS identity. The clinching proof is that Devuan's release file now exists:

cat /etc/devuan_version

If that prints a version (no "No such file" error), the box is Devuan. You've converted successfully.

If something looks stuck or incomplete, there's a second, much more detailed log you (or support) can read to see exactly where it stopped:

cat /root/.autoinit-verbose.log

If the verbose log mentions GRUB

Once in a while that verbose log ends with a warning that the boot loader package grub-pc could not be configured. If you see it, finish GRUB by hand before you install BOA. Run:

DEBIAN_FRONTEND=dialog dpkg --configure grub-pc
dpkg --configure -a

When the dialogue asks which device to install the boot loader on, choose your boot disk (usually /dev/sda). Once it completes without errors, carry on with the BOA install.

Advanced: GRUB and network interface naming

Most people can skip this. On an ordinary box with a public IP address, autoinit does not rewrite the kernel command line in /etc/default/grub at all, and everything above is all you need. It does still write a separate GRUB file as part of the AppArmor teardown, covered below.

autoinit records the interface naming convention it will use in a marker file under /root/, created on its first run and locked with chattr +i:

To choose, create the marker yourself before the first autoinit run. autoinit resolves the convention from the markers present in the fixed precedence classic, predictable, vanilla, auto — first match wins — and creates the marker for the result, which is vanilla when none exists. Because the file is immutable you need chattr -i before you can remove or replace it. Only one should exist: the GRUB check itself is evaluated the other way round, so a vanilla marker always wins there and cancels the rewrite whichever other marker is present. Clear the old marker rather than adding a second one.

Whichever marker is in force, a live rewrite always adds memhp_default_state=online, copies the old file to /etc/default/grub.bak, runs update-grub, then reboots into the next stage — and it stamps /root/.ninc.grub.updated.cnf so this happens once and later runs skip it.

Rewriting GRUB on a virtual machine you have no console access to is risky, so BOA asks for the decision twice: the rewrite happens only when a classic, predictable or auto marker is present and /root/.ignore.ifnames.cnf does not exist. With either condition unmet nothing is written and nothing is logged: when /root/.ignore.ifnames.cnf or the once-only stamp /root/.ninc.grub.updated.cnf is present, or the resolved convention is vanilla or none at all, the check simply returns.

So touch /root/.ignore.ifnames.cnf is the way to say "never rewrite my kernel command line". It governs the interface-naming rewrite in /etc/default/grub and nothing else — the AppArmor drop-in below is not gated by it, nor by the .ninc.selected.* markers. It is honoured by autoinit before installation and by boa, barracuda and cluster afterwards, and nothing in BOA ever creates it. One exception is worth knowing: on a NAT or cloud box — every non-loopback IPv4 address private — and where a classic marker is not already in place, autoinit forces classic eth0 naming. It creates and locks .ninc.selected.classic.cnf and deletes your .ignore.ifnames.cnf, clearing the immutable flag first, so the GRUB rewrite can go ahead. That is deliberate: an interface name that changes when systemd is removed is the classic way to lose networking on such a box.

After BOA is installed, boa in-* and barracuda up-* run the same check on every pass and honour the same two markers, but there they pin whichever naming the box already reports in ip a rather than the convention the marker names; the marker only decides whether the rewrite is live.

A default run does write to GRUB, for an unrelated reason. Unless /root/.keep_apparmor_on.cnf exists, autoinit tears AppArmor down on any box where it is active — which is the Debian default — and the last step of that teardown writes /etc/default/grub.d/apparmor.cfg, appending apparmor=0 to GRUB_CMDLINE_LINUX_DEFAULT, then runs update-grub. That happens on the ordinary public-IP run where no interface-naming rewrite is pending, and neither .ignore.ifnames.cnf nor any .ninc.selected.* marker gates it. touch /root/.keep_apparmor_on.cnf before the first run is what suppresses it — it is the same master switch the AppArmor page covers.

A related marker: the run mode. autoinit always records /root/.mode.selected.minimal.cnf, created with chattr +i — minimal is the only mode it can resolve to. full mode is entered solely by creating /root/.mode.selected.full.cnf by hand: that file is the one the later readers test, so simply add it alongside the immutable minimal marker, with no chattr -i needed. With it in place, autoinit and the automated codename drivers remove the cloud-utils, cloud-init and cloud-image-utils packages and move /etc/cloud into /var/backups. The minimal marker has no reader anywhere and simply records the choice.

What actually changed on your box

You don't need to do anything with this — it's just so nothing surprises you. In one pass, autoinit swaps your system's package sources from Debian to Devuan, removes systemd and puts Devuan's traditional init system in its place, walks the box up to the current Devuan release, and pins your network card's name so networking still comes up after the switch. It reboots between the big steps. When it's finished, you have a clean, current Devuan system with no BOA installed yet — exactly the starting point the BOA installer wants.

The one thing worth knowing: your network interface may be renamed as part of this (for example from a systemd-style name to plain eth0). autoinit handles that for you so the box doesn't lose its network — it writes a udev rule pinning the card's current MAC address to eth0 and updates /etc/network/interfaces to match, so you don't have to touch either yourself.

On a box behind NAT, or on a cloud network where every address is private, it goes one step further and pins the name in the boot loader too. That is the only case where a default autoinit run rewrites the kernel command line in /etc/default/grub. If you would rather it never touched your boot loader, or you want to pick the naming convention yourself, see Advanced: GRUB and network interface naming above.

Next step

Once /etc/devuan_version exists and the log says the system is ready, you're done here. Continue with Install BOA. If you took the easy way and let BOA drive the conversion, the install has already run itself — just wait for the completion email.

After installation, keep the box healthy with Keeping BOA current — BOA updates its own tools automatically, and that page walks you through the rest.

Going further

Advanced (root required): Operating → Major OS upgrade — for a box that already runs BOA and needs a later OS release, or for the codename-by-codename upgrade map. That path assumes Ægir and Linux comfort; autoinit on this page is only for the one-time Debian-to-Devuan step before BOA is installed.