GEREAL-GENERATOR(8)

NAME
gereal-generator - systemd generator for gereal serial console sessions

SYNOPSIS
gereal-generator unitdir runtime-dir sysconf-dir

DESCRIPTION
gereal-generator is a systemd generator used by gereal(8) to dynamically generate systemd service units for serial console sessions defined in gereal.conf(5). The generator is invoked automatically by systemd at boot time and whenever systemctl daemon-reload is executed. It is not intended to be run manually by users. For each configured session, the generator creates a corresponding systemd service unit that starts and supervises a detached GNU screen session.

gereal-generator implements systemd.generator(7).

OPERATION
On invocation, gereal-generator reads the configuration file /etc/gereal/gereal.conf. For each session defined in the configuration, a systemd service unit named:
    gereal-session.service
is generated in the generator output directory. If a session has enable: true set in the configuration, the generator also creates the necessary symlink so the unit is started automatically as part of multi-user.target.

GENERATED UNITS
The generated units have the following properties:

•   They are system-level services.

•   They run screen in detached mode, creating a screen session named gereal:session.

•   They run under the configured User and Group .

•   They are restarted automatically if the screen process exits.

•   They log session start events via logger(1).

VALIDATION
The generator performs basic validation before generating units. Units are not generated if:

•   The configuration file cannot be read or parsed.

•   Required session fields are missing.

•   The configured user or group does not exist on the system.

In these cases, an error is written to standard error and the generator exits with status 0, as required for systemd generators.

SCREEN CONFIGURATION
By default, screen is started using:
    /etc/gereal/screenrc
If a file named:
    /etc/gereal/screenrc-<session>
exists, it is used instead for that session.

ENVIRONMENT

SYSTEMD_GENERATOR_OUTPUT
    If set, specifies the directory into which generated units are written. Otherwise, the default systemd generator directory is used.

DEBUG
    If set to any value, enables debug output from the generator.

EXIT STATUS
The generator always exits with status 0 unless invoked incorrectly. This ensures that system boot is not interrupted.

SECURITY CONSIDERATIONS
The generator creates services that run serial consoles under specified users and groups. Access to serial devices often implies privileged access to connected hardware. Administrators should ensure that device permissions, users, and groups are configured appropriately. Enabling multiuser access or setuid root on screen has additional security implications and should be carefully reviewed.

SEE ALSO
gereal.conf(5), gerealctl(1), screen(1), systemd.generator(7), systemctl(1)

AUTHOR
Marc Haber <mh+debian-packages@zugschlus.de>