System Linux Core Documentation

Provides Linux-specific implementations for system process and service management.

This module is tailored for Linux environments and focuses on two main areas:

1. Systemd User Service Management: Functions for creating, enabling, disabling, and checking the existence of systemd user services. These are typically used to manage Bedrock servers as background daemons that can start on user login. Operations usually involve interaction with systemctl --user.

2. Foreground Process Management with FIFO IPC: Functions for starting a Bedrock server directly in the foreground, along with mechanisms for Inter-Process Communication (IPC) using a Unix named pipe (FIFO). This allows sending commands to the running foreground server.

Key Functionality Groups:

• Systemd User Service Utilities (Linux-specific):

  • get_systemd_user_service_file_path()

  • check_service_exists()

  • create_systemd_service_file()

  • enable_systemd_service()

  • disable_systemd_service()

• Foreground Server Management & IPC (Linux-specific):

  • _linux_start_server()

  • _linux_send_command()

  • _linux_stop_server()

  • Internal helpers for FIFO listener threads (_main_pipe_server_listener_thread()) and OS signal handling (_handle_os_signals()).

Constants:

• BEDROCK_EXECUTABLE_NAME: The typical name of the Bedrock server executable on Linux.

• PIPE_NAME_TEMPLATE: Template for FIFO paths used for IPC.

Global State:

• _foreground_server_shutdown_event: A threading event for managing the lifecycle of foreground server processes.

Note

Most functions in this module will perform a platform check and may return early or behave differently if not run on a Linux system.

bedrock_server_manager.core.system.linux.check_service_exists(service_name_full: str) → bool

Checks if a systemd user service file exists on Linux.

This function determines if a service is defined by checking for the presence of its service unit file in the standard systemd user directory (obtained via get_systemd_user_service_file_path()).

Parameters:

service_name_full (str) – The full name of the service unit to check (e.g., “my-app.service” or “my-app”).

Returns:

True if the service file exists, False otherwise. Returns False if the current operating system is not Linux.

Return type:

bool

Raises:

MissingArgumentError – If service_name_full is empty or not a string.

bedrock_server_manager.core.system.linux.create_systemd_service_file(service_name_full: str, description: str, working_directory: str, exec_start_command: str, exec_stop_command: str | None = None, exec_start_pre_command: str | None = None, service_type: str = 'forking', restart_policy: str = 'on-failure', restart_sec: int = 10, after_targets: str = 'network.target') → None

Creates or updates a systemd user service file on Linux and reloads the daemon.

This function generates a systemd service unit file with the specified parameters and places it in the user’s systemd directory (typically ~/.config/systemd/user/). After writing the file, it executes systemctl --user daemon-reload to ensure systemd recognizes any changes.

If the function is called on a non-Linux system, it logs a warning and returns.

Parameters:

• service_name_full (str) – The full name for the service unit file (e.g., “my-app.service” or “my-app”, “.service” suffix is optional).

• description (str) – A human-readable description for the service. Used for the Description= field in the unit file.

• working_directory (str) – The absolute path to the working directory for the service process. Used for WorkingDirectory=.

• exec_start_command (str) – The command (with arguments) to execute when the service starts. Used for ExecStart=.

• exec_stop_command (Optional[str], optional) – The command to execute when the service stops. Used for ExecStop=. Defaults to None.

• exec_start_pre_command (Optional[str], optional) – A command to execute before the main ExecStart command. Used for ExecStartPre=. Defaults to None.

• service_type (str, optional) – The systemd service type (e.g., “simple”, “forking”, “oneshot”). Used for Type=. Defaults to “forking”.

• restart_policy (str, optional) – The systemd Restart= policy (e.g., “no”, “on-success”, “on-failure”, “always”). Defaults to “on-failure”.

• restart_sec (int, optional) – Time in seconds to wait before restarting the service if restart_policy is active. Used for RestartSec=. Defaults to 10.

• after_targets (str, optional) – Specifies other systemd units that this service should start after. Used for After=. Defaults to “network.target”.

Raises:

• MissingArgumentError – If any of service_name_full, description, working_directory, or exec_start_command are empty or not strings.

• AppFileNotFoundError – If the specified working_directory does not exist or is not a directory.

• FileOperationError – If creating the systemd user directory or writing the service file fails (e.g., due to permissions).

• CommandNotFoundError – If the systemctl command is not found in the system’s PATH.

• SystemError – If systemctl --user daemon-reload fails.

bedrock_server_manager.core.system.linux.disable_systemd_service(service_name_full: str) → None

Disables a systemd user service on Linux from starting on user login.

This function uses systemctl --user disable <service_name> to disable the specified service. It first checks if the service file exists and if the service is already disabled (or not enabled) to avoid errors or redundant operations. Static or masked services cannot be disabled this way and will be logged accordingly.

If the function is called on a non-Linux system, it returns early.

Parameters:

service_name_full (str) – The full name of the service unit to disable (e.g., “my-app.service” or “my-app”).

Raises:

• MissingArgumentError – If service_name_full is empty or not a string.

• CommandNotFoundError – If the systemctl command is not found.

• SystemError – If the systemctl disable command fails for reasons other than the service being static or masked.

bedrock_server_manager.core.system.linux.enable_systemd_service(service_name_full: str) → None

Enables a systemd user service on Linux to start on user login.

This function uses systemctl --user enable <service_name> to enable the specified service. It first checks if the service file exists and if the service is already enabled to avoid redundant operations.

If the function is called on a non-Linux system, it returns early.

Parameters:

service_name_full (str) – The full name of the service unit to enable (e.g., “my-app.service” or “my-app”).

Raises:

• MissingArgumentError – If service_name_full is empty or not a string.

• CommandNotFoundError – If the systemctl command is not found.

• SystemError – If the service unit file (checked by check_service_exists()) does not exist, or if the systemctl enable command fails.

bedrock_server_manager.core.system.linux.get_systemd_user_service_file_path(service_name_full: str) → str

Generates the standard path for a systemd user service file on Linux.

Systemd user service files are typically located in the user’s ~/.config/systemd/user/ directory. This function constructs that path. If the provided service_name_full does not end with “.service”, the suffix is automatically appended.

Parameters:

service_name_full (str) – The full name of the service unit. It can be provided with or without the .service suffix (e.g., “my-app.service” or “my-app”).

Returns:

The absolute path to where the systemd user service file should be located (e.g., “/home/user/.config/systemd/user/my-app.service”).

Return type:

str

Raises:

MissingArgumentError – If service_name_full is empty or not a string.