Systemd Service Generation
Relevant source files
The following files were used as context for generating this wiki page:
Systemd Service Generation is a core component of the Teleport Ansible role responsible for managing the lifecycle, persistence, and execution environment of the Teleport daemon on Linux systems. This system ensures that Teleport is correctly registered as a background service, configured with appropriate permissions, and integrated with the host's init system for automatic startup and recovery.
The process primarily focuses on modern systemd-based distributions but maintains conditional logic to handle containerized environments and legacy init systems. It automates the creation of the service unit file from templates, manages ownership and permissions, and coordinates service reloads or restarts through dedicated handlers when configuration or binaries change.
Sources: tasks/service/systemd.yml:1-33, tasks/main.yml:61-68, README.md:143-150
Service Lifecycle Flow
The service generation and management follow a structured sequence starting from environment validation to final service activation.
The workflow ensures that the role does not attempt to manage systemd units in environments where systemd is absent or non-functional, such as certain Docker containers.
Sources: tasks/service/systemd.yml:3-33, tasks/service/daemon_management.yml:5-29, tasks/preflight/check.yml:11-13
Configuration and Templates
The systemd service is driven by variables defined in the role's defaults. These variables control the template used, the user account under which the service runs, and whether the role should manage the service at all.
Key Service Variables
| Variable | Default Value | Description |
|---|---|---|
teleport_control_systemd | yes | Global toggle to enable/disable service management. |
teleport_service_template | teleport.service.j2 | The Jinja2 template used to generate the unit file. |
teleport_service_user | teleport | The system user assigned to the Teleport service. |
teleport_system_group | teleport | The system group assigned to the Teleport service. |
Sources: defaults/main.yml:25-29
Service Unit Deployment
The unit file is deployed to /etc/systemd/system/teleport.service with a specific security posture. It is configured with 0640 permissions and owned by root:root.
- name: Create systemd service unit
ansible.builtin.template:
src: "{{ teleport_service_template }}"
dest: "/etc/systemd/system/teleport.service"
mode: "0640"
notify:
- Reload systemd daemon
- Restart Teleport service
Sources: tasks/service/systemd.yml:10-25
Handlers and State Management
The role utilizes Ansible handlers to ensure that changes to the service unit or the Teleport configuration file are applied safely without unnecessary service interruptions.
Handler Logic Flow
- Reload systemd daemon: Triggered whenever the
.serviceunit file is modified. It executesdaemon-reloadto inform systemd of the changes. - Reload Teleport service: Performed when the Teleport configuration (
/etc/teleport.yaml) changes. This uses thereloadedstate, which typically sends aSIGHUPto the process rather than a full restart. - Restart Teleport service: Used during initial installation or binary updates to ensure the new version is running.
Sources: handlers/main.yml:3-20, tasks/config/main.yml:65-68
Validation and Verification
The system includes verification steps to ensure the service is correctly generated and running. In testing environments (Molecule), the presence and attributes of the service file are asserted.
- File Existence: Checks that
/etc/systemd/system/teleport.serviceexists and is not empty. - Permissions: Validates that the file has a mode of
0644(or0640as per task definition) and is owned byroot. - Process Check: Verifies that the
teleportprocess is running under therootuser (or the configured service user).
Sources: molecule/default/verify.yml:45-66
Summary
The Systemd Service Generation module provides a robust mechanism for ensuring Teleport's operational stability. By combining template-based unit generation, strict permission management, and intelligent handlers for reloads and restarts, it allows for seamless configuration updates and reliable service persistence across system reboots. It maintains environment awareness by skipping systemd operations in containers and providing fallback mechanisms for legacy systems.