From ef42272087deac5da12fbef3ed7ef88fa2e2535e Mon Sep 17 00:00:00 2001 From: h7x4 Date: Mon, 12 Jan 2026 15:15:50 +0900 Subject: [PATCH] docs: move admin docs to separate documents, expand some sections --- README.md | 3 +- docs/administration.md | 90 ++++++++++++++++++++++++++++++++++++++++++ docs/development.md | 8 ---- docs/installation.md | 26 ++---------- 4 files changed, 95 insertions(+), 32 deletions(-) create mode 100644 docs/administration.md diff --git a/README.md b/README.md index c7b195d..43c4a66 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,8 @@ over a IPC, which then performs the requested operations on behalf of the client ## Documentation -- [Installation and configuration](docs/installation.md) +- [Installation and initial configuration](docs/installation.md) +- [Administration and further configuration](docs/administration.md) - [Development and testing](docs/development.md) - [Compiling and packaging](docs/compiling.md) - [Compatibility mode with mysql-admutils](docs/mysql-admutils-compatibility.md) diff --git a/docs/administration.md b/docs/administration.md new file mode 100644 index 0000000..f0177cf --- /dev/null +++ b/docs/administration.md @@ -0,0 +1,90 @@ +# Administration and further configuration + +This page describes some additional configuration options and administration tasks for muscl. + +## Configuring group denylists + +In `/etc/muscl/muscl.conf`, you will find an option below `[authorization]` named `group_denylist_file`, +which points to `/etc/muscl/group_denylist.txt` by default. + +In this file, you can add unix group names or GIDs to disallow the groups from being used as prefixes. + +The deb package comes with a default denylist that disallows some common system groups. + +The format of the file is one group name or GID per line. Lines starting with `#` and empty lines are ignored. + +``` +# Disallow using the 'root' group as a prefix +gid:0 + +# Disallow using the 'adm' group as a prefix +group:adm +``` + +> [!NOTE] +> If a user is named the same as a disallowed group, that user will still be able to use their username as a prefix. + +## Configuring logging + +By default, muscl logs to the systemd journal when run as a systemd service, +and also limits the log level to `info`. You can request more verbose logging +by appending `-v` flags to the `ExecStart=` line in the systemd service file. + +To do this on a system where muscl was installed using a package, you can override +the service like this: + +```bash +sudo systemctl edit muscl.service +``` + +This will open an editor where you can add the following lines: + +```ini +[Service] +ExecStart= +ExecStart=/usr/bin/muscl-server -v ... +``` + +> [!NOTE] +> The first `ExecStart=` line is necessary to clear the previous value, as systemd +> interprets multiple `ExecStart=` lines as a list of commands to run in sequence. + +You set either `-v` or `-vv` for `debug` and `trace` logging, respectively. + +> [!WARNING] +> Be careful when enabling trace logging on production systems, as it might log +> passwords and credentials in plaintext. + +## Querying logs in the systemd journal + +Although invisible if you just run `journalctl -u muscl.service`, muscl adds a set of so-called +"fields" to its log entries to make it easier to filter and search them. + +Here are some examples of how you can filter logs using `journalctl`: + +```bash +# Show only logs related to a specific user +journalctl -eu muscl F_USER="" +journalctl -eu muscl F_USER=johndoe + +# Show only logs for a specific command types +journalctl -eu muscl F_COMMAND="" +journalctl -eu muscl F_COMMAND=create-db + +# Show logs emitted for a specific session id +journalctl -eu muscl F_SESSION_ID="" +journalctl -eu muscl F_SESSION_ID=123 + +# Show all of these fields together with the log message in a json format +journalctl --output json-pretty --output-fields MESSAGE,F_USER,F_COMMAND,F_SESSION_ID -eu muscl +``` + +See [`journalctl(1)`][journalctl_1] and [`systemd.journal-fields(7)`][systemd_journal-fields_7] for more information. + +> [!NOTE] +> Please note that the commands are not 1-1 mapped to muscl subcommands. +> Rather, they are the available requests in the protocol used between the muscl client and server. +> These requests will often have the same name as the subcommands, but this is not always the case. + +[journalctl_1]: https://man7.org/linux/man-pages/man1/journalctl.1.html +[systemd_journal-fields_7]: https://man7.org/linux/man-pages/man7/systemd.journal-fields.7.html diff --git a/docs/development.md b/docs/development.md index c03cc97..73c66ea 100644 --- a/docs/development.md +++ b/docs/development.md @@ -52,11 +52,3 @@ nix run .#vm-mysql # Start a NixOS VM in QEMU with muscl and MySQL installed ``` You can configure the vm in `flake.nix` - -## Filter logs by user with journalctl - -If you want to filter the server logs by user, you can use journalctl's built-in filtering capabilities. - -```bash -journalctl -eu muscl F_USER= -``` diff --git a/docs/installation.md b/docs/installation.md index 6c6f7b5..758a98d 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,9 +1,11 @@ -# Installation and configuration +# Installation and initial configuration This document contains instructions for the recommended way of installing and configuring muscl. Note that there are separate instructions for [installing on NixOS](nixos.md) and [installing with SUID/SGID mode](suid-sgid-mode.md). +After installation, you might want to look at the [Administration and further configuration](administration.md) page. + ## Installing with deb on Debian You can install muscl by adding the [PVV apt repository][pvv-apt-repository] and installing the package: @@ -103,28 +105,6 @@ If you are using systemd, you should also create an override to unset the `Impor ImportCredential= ``` -## Configuring group denylists - -In `/etc/muscl/muscl.conf`, you will find an option below `[authorization]` named `group_denylist_file`, -which points to `/etc/muscl/group_denylist.txt` by default. - -In this file, you can add unix group names or GIDs to disallow the groups from being used as prefixes. - -The deb package comes with a default denylist that disallows some common system groups. - -The format of the file is one group name or GID per line. Lines starting with `#` and empty lines are ignored. - -``` -# Disallow using the 'root' group as a prefix -gid:0 - -# Disallow using the 'adm' group as a prefix -group:adm -``` - -> [!NOTE] -> If a user is named the same as a disallowed group, that user will still be able to use their username as a prefix. - ## A note on minimum version requirements The muscl server will work with older versions of systemd, but the recommended version is 254 or newer.