mariadbd Startup, Data Directory, Option Files, and Configuration Precedence

Learning outcomes

ServiceHub now has a compatibility-tested MariaDB lab, but an operator reports a classic production mystery: a value was added to /etc/mysql/my.cnf, the service was restarted, and MariaDB still shows the old value. A second engineer edits another file under mariadb.conf.d, and the setting suddenly changes. Both changes looked reasonable in isolation. The real problem is that a running server is the result of a configuration resolution process: program defaults, option-file search order, option groups, include files, packaging conventions, command-line arguments, and startup failures all participate.

This lesson makes mariadbd startup observable. Instead of memorizing one Linux path, you will ask the actual binary which files and groups it reads, identify the data directory and listener, trace effective options, and reproduce a harmless startup failure on a disposable instance. The goal is an operational habit: inspect the exact binary and package you run, then verify the server state after startup.

1. What starts when MariaDB starts?

mariadbd is the MariaDB Server daemon. On a package-managed Linux host, a service manager such as systemd normally launches it indirectly. On Windows, the installer commonly registers it as a Windows service. In a container, the image entrypoint prepares environment-dependent state and eventually executes the server process. These launchers matter because they may supply command-line arguments, environment variables, user identities, working directories, open-file limits, or additional configuration.

The server process must resolve its installation paths, find or receive a data directory, read options, initialize internal subsystems, load configured plugins, open InnoDB files, establish sockets/listeners, recover storage if needed, and finally accept client connections. A package being installed only proves files exist on disk. A successful service start plus a verified client query proves much more.

2. Ask the binary which defaults it reads

MariaDB option-file locations depend on platform, installation method, and build. The official option-file documentation therefore recommends asking the program. mariadbd --help --verbose prints the default option files read on that system and the option groups consumed by the server. This is stronger evidence than copying a path from a tutorial written for another distribution.

mariadbd --versionmariadbd --help --verbose# Print option values collected from the normal option-file search.mariadbd --print-defaults# Inspect server groups with the helper utility when installed.my_print_defaults --mariadbd

The special defaults options—such as --no-defaults, --defaults-file, --defaults-extra-file, and --print-defaults—must appear early where the program expects them. --defaults-file=/path/file.cnf tells the program to read only that option file rather than the normal search set; it is therefore excellent for disposable labs but dangerous if casually added to a production service because it can bypass package-provided settings.

3. Option groups and include order are part of the configuration API

An option file is divided into named groups. Client programs and the server read different groups, and server-oriented groups can include broad historical names and MariaDB-specific names. This lets a shared file contain settings for multiple programs, but it also means a correct-looking option under the wrong group can be silently irrelevant to mariadbd.

# servicehub-lab.cnf[client]port=3337socket=/tmp/servicehub-mariadb.sock[mariadb]port=3337socket=/tmp/servicehub-mariadb.sockdatadir=/tmp/servicehub-mariadb-datalog_error=/tmp/servicehub-mariadb.errskip_name_resolve=ON

MariaDB also supports !include and !includedir. Package layouts often use these to keep vendor defaults, distribution settings, and local overrides separate. Files in an included directory are processed in a defined filename order appropriate to the platform, so “last definition wins” can become operationally important. Do not hide ownership: keep a small local override file with an explicit naming convention rather than modifying package-managed files whenever your deployment model permits it.

Command-line options can override values read from files. A service unit or container entrypoint can therefore change an option even when every .cnf file looks correct. During incident response, capture the service definition or process command line in addition to the option files.

4. Verify the live server from inside the session

Once the server starts, SQL gives you the effective state. The @@ notation reads system variables. Query identity, paths, networking, and plugin directories together so that evidence is attributable to one server connection.

SELECT VERSION() AS server_version,       @@version_comment AS version_comment,       @@hostname AS hostname,       @@port AS port,       @@socket AS socket_path,       @@datadir AS data_directory,       @@basedir AS base_directory,       @@plugin_dir AS plugin_directory,       @@log_error AS error_log;SELECT CONNECTION_ID() AS connection_id,       USER() AS login_identity,       CURRENT_USER() AS privilege_identity;SHOW VARIABLES WHERE Variable_name IN (  'port','socket','datadir','basedir','plugin_dir','log_error',  'skip_name_resolve','max_connections');

These values are stronger evidence than file contents because they describe the running instance that answered your session. They still do not tell you which file supplied every value. MariaDB does not provide a direct equivalent of PostgreSQL’s per-setting source metadata. Operationally, you combine runtime values with --print-defaults, service definitions, package layout, and configuration management history.

5. The data directory is an ownership boundary, not a place for ad-hoc edits

The datadir contains system tables, InnoDB files, database directories or metadata, logs depending on configuration, and other files owned by the server. Treat it as server-managed state. Do not rename InnoDB files, delete redo/undo data, or copy a live data directory with ordinary filesystem tools and call it a backup. Later backup and recovery chapters explain consistent physical backup mechanisms.

For experiments, create a disposable data directory that is clearly separate from any production instance. On Unix-like systems, initialize it with mariadb-install-db using the account that will own the files. In containers, a disposable volume provides a clean equivalent. On Windows, a separate service/data-directory workflow can be used, but the exact initialization command and service registration should follow the installed package documentation.

rm -rf /tmp/servicehub-mariadb-datamkdir -p /tmp/servicehub-mariadb-data# Run as an appropriate local lab user; package-specific options may differ.mariadb-install-db   --datadir=/tmp/servicehub-mariadb-data   --auth-root-authentication-method=normal

6. Deliberately break startup—without touching the normal service

The failure drill uses the disposable data directory, alternate port 3337, and alternate socket. Introduce an unknown option into the isolated configuration. The typo is realistic because startup-only failures often come from renamed, removed, or misspelled variables after an upgrade.

# servicehub-bad.cnf[mariadb]datadir=/tmp/servicehub-mariadb-dataport=3337socket=/tmp/servicehub-mariadb.socklog_error=/tmp/servicehub-mariadb.errmax_conections=25   # INTENTIONALLY MISSPELLED

mariadbd --defaults-file=/tmp/servicehub-bad.cnf --console# In another terminal, inspect the isolated error log if created.tail -n 80 /tmp/servicehub-mariadb.err

A current server should reject the unknown max_conections option and abort rather than start with a guessed meaning. The exact message and startup prefix vary by build, platform, and logging destination, so teach the pattern rather than memorizing one line: identify the first actionable [ERROR], tie it to the option name/source, correct the configuration, and retry the isolated instance.

# Fix the spelling in the disposable file:# max_connections=25mariadbd --defaults-file=/tmp/servicehub-good.cnf --console# Verify from another shell.mariadb --protocol=TCP --host=127.0.0.1 --port=3337   -e "SELECT VERSION(), @@port, @@datadir, @@max_connections;"

Stop the disposable server cleanly using mariadb-admin with the explicit alternate connection parameters, then remove only the disposable files after confirming the paths. This drill proves that a startup failure can be reproduced and diagnosed without taking the normal Chapter 01 server offline.

7. Preview-only configuration validation is not the stable baseline

MariaDB 13.1 Preview introduces mariadbd --validate-config, which can parse and validate server configuration without continuing to normal service startup. That is operationally attractive, but it is not part of the MariaDB 12.3.2 stable lab baseline used in this chapter. Do not write a production runbook that assumes a preview feature exists on an older LTS deployment.

For the stable baseline, use layered checks: inspect option-file discovery; print parsed defaults; test changes against a disposable instance when a restart-level option is involved; capture the error log; then verify effective variables after the real controlled restart. If a future production series includes --validate-config, add it as an extra preflight—not as a substitute for post-start verification.

8. A startup evidence bundle for change review

Before approving a restart-level change, collect enough evidence that another operator can reproduce your reasoning. A useful bundle includes exact server binary/version, package/container identity, option-file list, local override diff, service/entrypoint arguments, current effective values, restart plan, error-log location, verification query, and rollback file. This turns “I changed my.cnf” into a controlled change.

9. Hands-on lab and verification checklist

Complete the following on a disposable local environment. If your operating system packages MariaDB differently, substitute its documented paths while preserving the evidence goals.

1. Record mariadbd --version and mariadb --version.
2. Run mariadbd --help --verbose and save the option-file search list.
3. Run mariadbd --print-defaults and my_print_defaults --mariadbd if available.
4. From the Chapter 01 server, query @@datadir, @@port, @@socket, @@plugin_dir, and @@log_error.
5. Initialize a disposable alternate data directory.
6. Attempt startup with the intentionally misspelled option and capture the error.
7. Fix the option, start on port 3337, connect explicitly, and verify the effective state.
8. Stop the alternate instance cleanly and delete only the disposable files.

Verification checklist

• You can name the exact option files searched by your binary.
• You can distinguish parsed defaults from live effective values.
• No production/default service was stopped or reconfigured for the failure drill.
• The failed startup produced evidence that identifies the invalid option.
• The repaired alternate instance accepted a client query on the intended port/socket.
• Cleanup removed only the explicit disposable directory/socket/log.

10. Summary and bridge

A MariaDB instance is not configured by one magic file. Startup resolves executable defaults, searched option files, groups and includes, service/entrypoint arguments, and server-managed state. The reliable workflow is discover → change one controlled source → start safely → inspect logs → verify live variables. You also practiced a real startup failure without risking the normal server.

The next lesson follows a client after startup. You will trace connections, server threads, session state, max_connections, idle timeouts, per-account limits, and MariaDB’s adaptive thread-pool option—while learning why “2,000 connected sessions” is not the same statement as “2,000 useful concurrent queries.”