Updated by Linode
Use promo code DOCS10 for $10 credit on a new account.
What is systemctl?
systemctl is a controlling interface and inspection tool for the widely-adopted init system and service manager systemd. This guide will cover how to use
systemctl to manage systemd services, work with systemd Targets and extract meaningful information about your system’s overall state.
NoteThis guide is written for a non-root user. Commands that require elevated privileges are prefixed with
sudo. If you’re not familiar with the
sudocommand, see the Users and Groups guide.
systemd initializes user space components that run after the Linux kernel has booted, as well as continuously maintaining those components throughout a system’s lifecycle. These tasks are known as units, and each unit has a corresponding unit file. Units might concern mounting storage devices (.mount), configuring hardware (.device), sockets (.socket), or, as will be covered in this guide, managing services (.service).
Starting and Stopping a Service
To start a
systemd service in the current session, issue the
sudo systemctl start apache2.service
Conversely, to stop a
systemd service, issue the
sudo systemctl stop apache2.service
In the above example we started and then stopped the Apache service. It is important to note that
systemctl does not require the
.service extension when working with service units. The following is just as acceptable:
sudo systemctl start apache2
If the service needs to be restarted, such as to reload a configuration file, you can issue the
sudo systemctl restart apache2
Similarly, if a service does not need to restart to reload it’s configuration, you can issue the
sudo systemctl reload apache2
Finally, you can use the
reload-or-restart command if you are unsure about whether your application needs to be restarted or just reloaded.
sudo systemctl reload-or-restart apache2
Enabling a Service at Boot
The above commands are good for managing a service in a single session, but many services are also required to start at boot. To enable a service at boot:
sudo systemctl enable nginx
To disable the service from starting at boot, issue the
sudo systemctl disable nginx
enablecommand does not start the service in the current session, nor does
disablestop the service in the current session. To enable/disable and start/stop a service simultaneously, combine the command with the
sudo systemctl enable nginx --now
If the service unit file is not located within one of the known
systemd file paths, you can provide a file path to the service unit file you wish to enable:
sudo systemctl enable /path/to/myservice.service
However, this file needs to be accessible by
systemd at startup. For example, this means files underneath
/var are not allowed, unless those directories are located on the root file system.
Checking a Service’s Status
systemctl allows us to check on the status of individual services:
systemctl status mysql
This will result in a message similar to the output below:
● mysql.service - MySQL Community Server Loaded: loaded (/lib/systemd/system/mysql.service; enabled; vendor preset: enabled) Active: active (running) since Thu 2018-08-30 09:15:35 EDT; 1 day 5h ago Main PID: 711 (mysqld) Tasks: 31 (limit: 2319) CGroup: /system.slice/mysql.service └─711 /usr/sbin/mysqld --daemonize --pid-file=/run/mysqld/mysqld.pid
You can also use
is-failed to monitor a service’s status:
systemctl is-enabled mysql
To view which
systemd service units are currently active on your system, issue the following
list-units command and filter by the service type:
systemctl list-units --type=service
list-unitsis the default action for the
systemctlcommand, so you can simply enter
systemctlto retrieve a list of units.
The generated list includes all currently active service units, service units that have jobs pending, and service units that were active and have failed:
UNIT LOAD ACTIVE SUB DESCRIPTION accounts-daemon.service loaded active running Accounts Service apparmor.service loaded active exited AppArmor initialization apport.service loaded active exited LSB: automatic crash report generation atd.service loaded active running Deferred execution scheduler blk-availability.service loaded active exited Availability of block devices console-setup.service loaded active exited Set console font and keymap cron.service loaded active running Regular background program processing daemon dbus.service loaded active running D-Bus System Message Bus ebtables.service loaded active exited ebtables ruleset management ...
The output provides five pieces of data:
- UNIT: The name of the unit.
- LOAD: Was the unit properly loaded?
- ACTIVE: The general activation state, i.e. a generalization of SUB.
- SUB: The low-level unit activation state, with values dependent on unit type.
- DESCRIPTION: The unit’s description.
To list all units, including inactive units, append the
systemctl list-units --type=service --all
You can filter the list of units by state. Supply a comma-separated list of unit states to output as the value for the
systemctl list-units --type=service --all --state=exited,inactive
To retrieve a list of failed units, enter the
list-units command with the
systemctl list-units --failed
Working with Unit Files
Each unit has a corresponding unit file. These unit files are usually located in the following directories:
/lib/systemd/systemdirectory holds unit files that are provided by the system or are supplied by installed packages.
/etc/systemd/systemdirectory stores unit files that are user-provided.
Listing Installed Unit Files
Not all unit files are active on a system at any given time. To view all
systemd service unit files installed on a system, use the
list-unit-files command with the optional
systemctl list-unit-files --type=service
The generated list has two columns, UNIT FILE and STATE:
UNIT FILE STATE accounts-daemon.service enabled acpid.service disabled apparmor.service enabled apport-forward@.service static apt-daily-upgrade.service static apt-daily.service static ...
A unit’s STATE can be either enabled, disabled, static, masked, or generated. Unit files with a static state do not contain an Install section and are either meant to be run once or they are a dependency of another unit file and should not be run alone. For more on masking, see Masking a Unit File.
Viewing a Unit File
To view the contents of a unit file, run the
systemctl cat cron
# /lib/systemd/system/cron.service [Unit] Description=Regular background program processing daemon Documentation=man:cron(8) [Service] EnvironmentFile=-/etc/default/cron ExecStart=/usr/sbin/cron -f $EXTRA_OPTS IgnoreSIGPIPE=false KillMode=process [Install] WantedBy=multi-user.target
If there are recent changes to the unit file that have not yet been loaded into systemd, the output of the
systemctl cat command may be an older version of the service.
For a low-level view of a unit file, issue the
systemctl show cron
This will generate a list of property key=value pairs for all non-empty properties defined in the unit file:
Type=simple Restart=no NotifyAccess=none RestartUSec=100ms TimeoutStartUSec=1min 30s TimeoutStopUSec=1min 30s RuntimeMaxUSec=infinity ...
To show empty property values, supply the
To filter the key=value pairs by property, use the
systemctl show cron -p Names
Note that the property name must be capitalized.
Viewing a Unit File’s Dependencies
To display a list of a unit file’s dependencies, use the
systemctl list-dependencies cron
The generated output will show a tree of unit dependencies that must run before the service in question runs.
cron.service ● ├─system.slice ● └─sysinit.target ● ├─apparmor.service ● ├─blk-availability.service ● ├─dev-hugepages.mount ● ├─dev-mqueue.mount ● ├─friendly-recovery.service ...
Recursive dependencies are only listed for
.target files. To list all recursive dependencies, pass in the
To check which unit files depend on a service unit file, you can run the
list-dependencies command with the
systemctl list-dependencies cron --reverse
Editing a Unit File
NoteWhile the particulars of unit file contents are beyond the scope of this article, there are a number of good resources online that describe them, such as the RedHat Customer Portal page on Creating and Modifying systemd Unit Files.
There are two ways to edit a unit file using
editcommand opens up a blank drop-in snippet file in the system’s default text editor:
sudo systemctl edit ssh
When the file is saved,
systemctlwill create a file called
override.confunder a directory at
yourserviceis the name of the service you chose to edit. This command is useful for changing a few properties of the unit file.
The second way is to use the
editcommand with the
sudo systemctl edit ssh --full
This command opens a full copy of whatever unit file you chose to edit in a text editor. When the file is saved,
systemctlwill create a file at
/etc/systemd/system/yourservice.service. This is useful if you need to make many changes to an existing unit file.
In general, any unit file in
/etc/systemd/system will override the corresponding file in
Creating a Unit File
systemctl will throw an error if you try to open a unit file that does not exist, you can force
systemctl to create a new unit file using the
sudo systemctl edit yourservice.service --force
When the file is saved,
systemctl will create an
override.conf file in the
/etc/systemd/system/yourservice.service.d directory, where ‘yourservice’ is the name of the service you chose to create. To create a full unit file instead of just a snippet, use
--force in tandem with
sudo systemctl edit yourservice.service --force --full
Masking a Unit File
To prevent a service from ever starting, either manually or automatically, use the
mask command to symlink a service to
sudo systemctl mask mysql
Similar to disabling a service, the
mask command will not prevent a service from continuing to run. To mask a service and stop the service at the same time, use the
sudo systemctl mask mysql --now
To unmask a service, use the
sudo systemctl unmask mysql
Removing a Unit File
To remove a unit file snippet that was created with the
edit command, remove the directory
yourservice.service.d (where ‘yourservice’ is the service you would like to delete), and the
override.conf file inside of the directory:
sudo rm -r /etc/systemd/system/yourservice.service.d
To remove a full unit file, run the following command:
sudo rm /etc/systemd/system/yourservice.service
After you issue these commands, reload the
systemd daemon so that it no longer tries to reference the deleted service:
sudo systemctl daemon-reload
Working with systemd Targets
Like other init system’s run levels,
systemd’s targets help it determine which unit files are necessary to produce a certain system state.
systemd targets are represented by target units. Target units end with the
.target file extension and their only purpose is to group together other systemd units through a chain of dependencies.
For instance, there is a
graphical.target that denotes when the system’s graphical session is ready. Units that are required to start in order to achieve the necessary state have
graphical.target in their configuration. Units that depend on
graphical.target can include
After= in their configuration to make themselves available at the correct time.
A target can have a corresponding directory whose name has the syntax
graphical.target.wants), located in
/etc/systemd/system. When a symlink to a service file is added to this directory, that service becomes a dependency of the target.
When you enable a service (using
systemctl enable), symlinks to the service are created inside the
.target.wants directory for each target listed in that service’s
WantedBy= configuration. This is actually how the
WantedBy= option is implemented.
Getting and Setting the Default Target
To get the default target for your system –the end goal of the chain of dependencies– issue the
If you would like to change the default target for your system, issue the
sudo systemctl set-default multi-user.target
To retrieve a list of available targets, use the
list-unit-files command and filter by target:
systemctl list-unit-files --type=target
To list all currently active targets, use the
list-units command and filter by target:
systemctl list-units --type=target
Changing the Active Target
To change the current active target, issue the
isolate command. This command starts the isolated target with all dependent units and shuts down all others. For instance, if you wanted to move to a multi-user command line interface and stop the graphical shell, use the following command:
sudo systemctl isolate multi-user.target
However, it is a good idea to first check on the dependencies of the target you wish to isolate so you do not stop anything important. To do this, issue the
systemctl list-dependencies multi-user.target
When a situation arises where you are unable to proceed with a normal boot, you can place your system in rescue mode. Rescue mode provides a single-user interface used to repair your system. To place your system in rescue mode, enter the following command:
sudo systemctl rescue
This command is similar to
systemctl isolate rescue, but will also issue a notice to all other users that the system is entering rescue mode. To prevent this message from being sent, apply the
sudo systemctl rescue --no-wall
Emergency mode offers the user the most minimal environment possible to salvage a system in need of repair, and is useful if the system cannot enter rescue mode. For a full explanation of emergency mode, refer to the RedHat Customer Portal page. To enter emergency mode, enter the following command:
sudo systemctl emergency
This command is similar to
systemctl isolate emergency, but will also issue a notice to all other users that the system is entering emergency mode. To prevent this message, apply the
sudo systemctl emergency --no-wall
systemctl allows users the ability to halt, shutdown and reboot a system.
To halt a system, issue the following command:
sudo systemctl halt
To shutdown a system, use:
sudo systemctl shutdown
Finally, to reboot a system, enter the following command:
sudo systemctl reboot
Similar to the
rescue commands, these commands will issue a notice to all users that the system state is changing.
You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.
Join our Community
Find answers, ask questions, and help others.
This guide is published under a CC BY-ND 4.0 license.