my.cnf lifecycle + mycnfup

/etc/mysql/my.cnf is BOA-deployed and BOA-maintained. It is not hand-assembled per host: BOA ships a single template (aegir/conf/var/my.cnf.txt), re-deploys it verbatim, then sed-patches a handful of directives to match the target Percona series. This page covers who writes it, when it is rewritten, how to protect a custom config across upgrades, and what mycnfup actually does (it is not the version migrator).

What lives where

/etc/mysql/my.cnf          BOA-deployed main config (from var/my.cnf.txt)
/etc/mysql/conf.d/         drop-in directory; the only !includedir BOA ships

BOA's deployed my.cnf ends with a single include line:

!includedir /etc/mysql/conf.d/

That is the whole BOA include chain. BOA does not add /etc/mysql/mysql.conf.d/ or /etc/mysql/percona-server.conf.d/ to its config — those exist only on some non-BOA / distro-default layouts. (The xmass migration tool detects them, preferring percona-server.conf.d, then conf.d, then mysql.conf.d as a last-resort fallback when migrating from a non-BOA host — but that detection is for the migrator, not part of BOA's own include chain.)

For drop-in fragments the read order is my.cnf first, then conf.d/*.cnf; later fragments override earlier ones.

Deploy and per-version patch

There is no per-host generation step and no marker stamped into the file. The mechanism is two stages, both in lib/functions/sql.sh.inc:

1. Deploy the template verbatim. On a fresh DB install the package's own my.cnf is moved aside to /var/backups/package.my.cnf and BOA copies aegir/conf/var/my.cnf.txt over /etc/mysql/my.cnf. On a config-update pass BOA re-deploys the same template (unless custom-config protection is on — see below).
2. Sed-patch per Percona version. BOA comments/uncomments the version-specific directives so the file is valid for the target Percona series (_DB_SERIES, e.g. 5.7, 8.0, 8.4).

The template carries every version's logging block commented out, and BOA enables exactly the set the target version understands:

Critically, every config pass resets logging first — it comments out log_syslog, log_error, syseventlog and mysqlx before re-enabling the target-version set. This is what makes a 5.7 → 8.0 upgrade start cleanly: a stale log_syslog left over from 5.7 makes 8.x abort on the unknown variable. The reset is idempotent (a leading # is collapsed, never doubled). The same pass also resets slow_query_log / long_query_time / slow_query_log_file (commented out) and re-disables performance_schema on 5.7 / re-enables it on 8.x.

Hardened template defaults

The shipped my.cnf.txt carries these defaults:

Leave secure_file_priv and local_infile as shipped unless a specific workload requires otherwise — they are deliberate anti-exfiltration defaults.

Protecting a custom config: _CUSTOM_CONFIG_SQL

BOA has no marker-diff override-detection. If you hand-edit /etc/mysql/my.cnf and leave the defaults alone, BOA re-deploys the template over your changes on the next config pass. To keep a fully custom my.cnf, set the protection toggle in /root/.barracuda.cnf:

_CUSTOM_CONFIG_SQL=YES   # protects custom SQL config when YES

When _CUSTOM_CONFIG_SQL=YES, BOA does nothing to my.cnf — no re-deploy (_tune_sql_memory_limits skips the template copy), no version sed-patching or logging reset (_sql_conf_update bails to _DO_NOTHING), and no binary-log toggling. The protection holds on every host, including BOA-managed ones (_hostedSys=YES): on a managed host the version-sync block is entered, but the very first test inside it still short-circuits to _DO_NOTHING when the toggle is YES. You own the file end to end, including keeping it valid across Percona upgrades.

The lower-risk pattern, if you only need additions, is to leave _CUSTOM_CONFIG_SQL=NO and drop fragments into /etc/mysql/conf.d/zz-operator-*.cnf. The zz- prefix sorts last, so those fragments override BOA's template directives, and they survive every re-deploy because BOA never touches conf.d/.

mycnfup — memory tuner + mysqld controller (not a migrator)

Despite the name, aegir/tools/bin/mycnfup is not the my.cnf version migrator — the version migration is in sql.sh.inc as described above. mycnfup is a memory tuner plus a mysqld start/stop/restart orchestrator, a positional-verb dispatcher (case "$1" in …):

It is normally invoked by BOA tooling — e.g. cluster runs mycnfup check, mycnfup tune, mycnfup init and mycnfup stop over SSH on DB nodes. There are no --target-version, --dry-run, --include or --target flags — those do not exist. Run a bare mycnfup (or mycnfup tune) to re-tune memory limits after a RAM change.

Backups taken during an upgrade

Before re-deploying the template, the upgrade path copies the current my.cnf aside for diffing/rollback — to <vault>/dragon/t/my.cnf-pre-<serial>-<version>-<timestamp>, not to a /etc/mysql/my.cnf.backup-<timestamp> next to the live file. On a fresh DB install the distro package's my.cnf is preserved at /var/backups/package.my.cnf.

For your own hand-edits, take your own backup first:

cp /etc/mysql/my.cnf /etc/mysql/my.cnf.$(date +%Y%m%d-%H%M%S).bak

Diagnosing my.cnf issues

# Current Percona version + active InnoDB variables
mysql -e "SELECT VERSION();"
mysql -e "SHOW VARIABLES LIKE 'innodb_%';" | head

# Validate my.cnf syntax without restarting
mysqld --validate-config

# Which file each variable came from (Percona 8.0+)
mysql -e "SELECT * FROM performance_schema.variables_info \
  WHERE variable_source IN ('GLOBAL','COMMAND_LINE')" | head -50

The variables_info view in Percona 8.0+ tells you whether a variable came from my.cnf, a conf.d/*.cnf drop-in, the command line, or a runtime SET.

When operator overrides break upgrades

With _CUSTOM_CONFIG_SQL=NO (default), BOA re-deploys its template each pass, so stale operator directives in the main file are simply overwritten. The failure mode to watch for is a protected custom config (_CUSTOM_CONFIG_SQL=YES) carrying directives the new Percona major rejects — BOA will not fix those for you:

• Custom InnoDB tuning invalid in the new major (e.g. an explicit innodb_log_file_size value 8.0+ refuses).
• A sql_mode the new Percona rejects (e.g. NO_AUTO_CREATE_USER, gone in 8.0+).
• Plugin loads for plugins that do not exist in the new version.
• Logging directives from the previous Percona series — exactly what BOA's reset pass removes automatically when protection is off.

If a protected config blocks an upgrade: restore from the pre-upgrade copy under <vault>/dragon/t/, remove or update the conflicting directive, and re-run the upgrade.

Related

• Percona install + tuning — install, the staged upgrade, and the upgrade-time memory tuner (mycnfup tune re-sizes the buffers in my.cnf).
• Dumps with mydumper — dumps run against this Percona instance.
• Control files & INI — _DB_SERIES, _DB_SERVER, _DB_BINARY_LOG, _CUSTOM_CONFIG_SQL, _CUSTOM_COLLATION_SQL, _USE_MYSQLTUNER at the barracuda.cnf level.
• Reference appendix — the consolidated _VAR table.