How to Use the Command 'systemd-run' (with Examples)

The systemd-run command is a versatile utility that leverages the features of systemd, the system and service manager for Linux, to run programs as transient scope units or service units. It enables users to manage and execute tasks with various configurations and properties efficiently and innovatively. The command is suitable for creating timed tasks, managing resource usage, and executing tasks with specific environments, all as part of a systemd unit without having to create predefined unit files. Below, we explore different use cases of systemd-run with examples to illustrate its diverse applications.

Use Case 1: Start a Transient Service

Code:

sudo systemd-run command argument1 argument2 ...

Motivation:

This use case is valuable when you intend to launch a service temporarily without a permanent service unit file. It allows for ad-hoc executions while leveraging the benefits of systemd’s supervision and resource management features.

Explanation:

• sudo: Required to run the command as a superuser since managing units typically needs elevated privileges.
• systemd-run: The primary command to invoke the process as a systemd unit.
• command: The actual program you want to execute.
• argument1 argument2 ...: Any arguments that the command may need for execution.

Example Output:

Upon executing the above command, systemd will output a unit identifier like Started <generated unit name> indicating the successfully started transient service.

Use Case 2: Start a Transient Service Under the Service Manager of the Current User (No Privileges)

Code:

systemd-run --user command argument1 argument2 ...

Motivation:

This scenario is perfect when you want limited user-level isolation and management of a service, without requiring root privileges. It allows users to manage their processes as units within their own session scopes.

Explanation:

• systemd-run: Initiates the command as a transient unit.
• --user: Runs the command under the user’s service manager scope rather than the system-wide scope.
• command, argument1, argument2 ...: Specifies the command and its arguments.

Example Output:

The output will indicate the creation and status of the transient service under the user’s control, such as Started <user-specific unit name>.

Use Case 3: Start a Transient Service with a Custom Unit Name and Description

Code:

sudo systemd-run --unit=name --description=string command argument1 argument2 ...

Motivation:

Naming and describing your units provide clarity and easier management, especially when multiple transient services exist or when you have to troubleshoot or document system operations.

Explanation:

• --unit=name: Sets a user-defined name for the transient unit, allowing for better identification.
• --description=string: Provides a brief overview or purpose of the service, useful for automatic documentation or clarity on service intent.
• command, arguments: The operation to perform.

Example Output:

The output will offer feedback similar to Started <name>, along with the description given, aiding in understanding immediately what the service does.

Use Case 4: Start a Transient Service That Does Not Get Cleaned Up After It Terminates with a Custom Environment Variable

Code:

sudo systemd-run --remain-after-exit --set-env=name=value command argument1 argument2 ...

Motivation:

Keeping the service state post-execution can be pivotal for audit trails or debugging purposes. This also allows setting environment variables crucial for the service configuration at runtime.

Explanation:

• --remain-after-exit: Ensures the unit remains in the service manager’s list post-exit, maintaining its final state for inspection.
• --set-env=name=value: Sets an environment variable for the unit, essential for configuring or customizing the environment in which the command runs.
• command, arguments: Specifies the program and its runtime parameters.

Example Output:

Messages like Running as unit <name> with environment variable <name=value> set followed by task completion status are expected.

Use Case 5: Start a Transient Timer That Periodically Runs Its Transient Service

Code:

sudo systemd-run --on-calendar=calendar_event command argument1 argument2 ...

Motivation:

This approach helps automate tasks based on calendar-driven triggers, akin to cron jobs but with the rich context and management capabilities of systemd.

Explanation:

• --on-calendar=calendar_event: Sets a calendar-based trigger for the service execution, allowing it to run at specified intervals.
• command, arguments: The operation scheduled to occur periodically.

Example Output:

Feedback like Started <timed unit name> scheduled for <next occurrence> will confirm success.

Use Case 6: Share the Terminal with the Program and Ensure Execution Details Remain After the Program Exits

Code:

systemd-run --remain-after-exit --pty command

Motivation:

When interacting with a command requires real-time input, this use case facilitates shared terminal access while keeping the command’s state data post-execution for inspection.

Explanation:

• --remain-after-exit: Keeps the unit data in the systemd manager beyond its execution.
• --pty: Allocates a pseudo-terminal for the command, supporting full terminal I/O.
• command: Execution target with potential interactive requirements.

Example Output:

A terminal emulator message confirms successful invocation and post-termination status information remains accessible.

Use Case 7: Set Properties of the Process and Wait Until It Exits

Code:

systemd-run --property MemoryMax=memory_in_bytes --property CPUQuota=percentage_of_CPU_time% --wait command

Motivation:

Resource-constrained environments benefit greatly from running services with explicit limits on memory and CPU usage, ensuring fair use and system stability.

Explanation:

• --property MemoryMax=memory_in_bytes: Caps the memory usage of the process to avoid over-allocation.
• --property CPUQuota=percentage_of_CPU_time%: Limits CPU time to prevent overuse.
• --wait: Ensures the command completes before systemd-run itself exits.

Example Output:

Output shows unit creation followed by resource usage statistics until command completion.

Use Case 8: Use the Program in a Shell Pipeline

Code:

command1 | systemd-run --pipe command2 | command3

Motivation:

Embedding processes in pipelines allow data transformations and streamlined executions leveraging inter-process communication, enhancing workflow automation.

Explanation:

• |: A pipe operator that directs output from one command into another.
• --pipe: Directs pipelined input/output, incorporating unit management directly into shell pipelines.
• command sequences: Series of commands executed in the pipeline.

Example Output:

Intermediate outputs, such as logs or transformed data, appear in a seamless workflow, providing utility across shell-based operations.

Conclusion:

The systemd-run command equips users with the power of systemd for temporary, straightforward process launches with flexible configurations. Its integration into routine tasks allows optimal resource utilization, operational transparency, and enhanced process control across individual sessions or system-wide environments. Understanding these use cases enables leveraging systemd-run for improved system operations and management.