muscl/docs/administration.md

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:

sudo systemctl edit muscl.service

This will open an editor where you can add the following lines:

[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:

# Show only logs related to a specific user
journalctl -eu muscl F_USER="<username>"
journalctl -eu muscl F_USER=johndoe

# Show only logs for a specific command types
journalctl -eu muscl F_COMMAND="<operation>"
journalctl -eu muscl F_COMMAND=create-db

# Show logs emitted for a specific session id
journalctl -eu muscl F_SESSION_ID="<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) and 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.