Command Line – systemctl

Systemd has replaced init in most distributions for several years. Yet for many users, it remains mostly unknown. One reason for this obscurity is that, to avoid confusion, distributions hide systemd with aliases to traditional commands. It is only when you look into the intricacies of systemctl, a systemd command that views and manages a system, that you begin to appreciate how far-reaching systemd actually is.

Like other init systems, systemd's main purpose is to start and control services that must be started after the kernel – those that run in userland, as it is sometimes expressed. The difference is that systemctl's controls extend to other parts of a system as well and are far more extensive than init's or Upstart's controls. systemctl carries out these tasks by acting upon systemd's units. Units are often described – not very usefully – as objects that systemd knows how to manage. A more revealing explanation is by example. You can get a general overview from the different types of units, each identified by a suffix: .service, .socket, .device, .mount, and so on. For a more detailed example, enter:

systemctl list-unit-files

and you will see that not only system calls but everything from Bluetooth and CUPS to Plymouth and Apache have systemd units, configured in a corresponding unit file (Figure 1). Notice, too, that units can define both software and hardware attached to the system. You can also write your own unit files for such tasks as mounting a filesystem or running a script at startup.

Figure 1: The start of a list of unit files on a typical workstation.

Unit files have multiple sections that can be in any order, since systemd reads them all before acting on them. However, for the convenience of humans, the tradition is to start each unit file with the Unit section, whose properties name the unit, specify the path to documentation, and list any dependencies. Where relevant, the next section is Install, which defines elements like aliases and reverse dependencies – system elements that depend on the unit. It is usually followed by a section relevant to the type of unit and any other relevant part of the system. Nothing is arcane about unit files – they are basically configuration files, with one property defined per line, most of which have self-explanatory names. If you have any experience with pre-systemd administration, you can soon understand them. The trouble is, there are dozens, and just to summarize all possible entries would take several thousand words. However, you can explore an individual unit file with the command structure:

systemctl cat UNIT

Figure 2 shows the unit file for atd, the job queue. As you can see, it consists of a general description, followed by the Service section, which sets how atd runs, and the Install section, which defines atd's relationship to other applications. As unit files go, atd's is a simple one, but it gives you some idea of what to expect in other unit files.

Figure 2: The atd scheduler is a simple example of a unit file.

As you explore, you will soon find that every major aspect of a system that runs in userland can be controlled by systemctl, making it a powerful command indeed. Unit files for the entire system are stored in /lib/systemd/system, but are over-ridden by unit files in /etc/systemd/system.

systemctl operates by issuing commands to units, sometimes modified by command options. The basic structure is:

systemctl COMMAND OPTION

The unit may be specified with its suffix, or without, since the command issued will often be unique to a particular unit (Figure 3). But what commands might you want to issue? The majority fall into one of two categories: controlling services and gathering information about units.

Figure 3: A systemctl command to display the unit file for Bluetooth.

Controlling Services

If you have encountered systemctl previously, probably it is as a means of managing services. You can check the status of a unit using the status command (Figure 4) and use the start and stop commands to toggle a unit. However, you may be better off using the reload or restart commands, or, if you are not sure which to use, reload-or-restart, since they will work regardless unit's state. All these commands apply in the current session. However, if you want to make a permanent change to the system and have the service start during bootup, use enable or disable (Figure 5). Both enable or disable create a symbolic link from the copy of the unit in /lib/systemd/system to the one in /etc/systemd/system, where systemd looks for units to start automatically. Remember, though, neither enable or disable take effect until the next system boot.

Figure 4: The current status for Bluetooth. Note the color coding.

Figure 5: Use enable to automatically start a service during bootup.

If you are troubleshooting, you might start a service using isolate. To use this function, a unit must have enabled AllowIsolate=. The function runs the unit and its dependencies and stops all others – including, possibly, the desktop environment or command prompt, so be warned. The man page likens isolate to changing the runlevel in init. More details are available in the systemd.unit(5) man page. Rescue offers a similar function, except that it includes the option of sending a message to logged in users.

In addition, systemctl has several functions that are aliased to standard Unix commands for root users, like kill, halt, poweroff, reboot, suspend, and hibernate. Mostly, these commands are like the standard Unix ones and include some obvious synonyms. One exception is that halt, poweroff, and reboot have the built in option --message STRING, which broadcasts a message to users before the function is activated. Prior to the adoption of systemd, of course, the separate wall command was needed for such messages.

Gathering Information

To learn any unit's current state, you can use the status command, either to see a tree view of all units or the status of a named unit. To get more specific results, you can use is-active, is-enabled, and is-failed.

For broader views of the system, the command is list-units. It returns results that include each unit that is loaded, active or running, as well as a short description. list-units can be filtered by a number of options. For example, followed by -all (-a), it lists all units, regardless of their state. Followed by --type TYPE (-t TYPE), it lists only the type of unit named, such as service or mount. Similarly, --state can be followed by a comma-separated list of LOAD, SUB, ACTIVE, FAILED, or help. Alternatively, you may prefer to use the list-units, list-sockets, or list-timer commands as a filter.

The show command zeroes in on the properties of one or more units or jobs, or, if neither is specified, systemd itself. For even more of a close-up view, you can add --property (-p) to search for unit files that contain a specific property or --recursive (-r) to include units in a container in search results. Once you have located a unit, you can learn more about it with list-dependencies or, in some cases, list-jobs.

With most of these commands and options, you have some control over how the output displays. When you are new to systemd, you may want to use --full (-l) to display property names and statuses spelled out in full. Later, when you have learned enough of systemd and how it displays information, you may be content with --values and not bother to display the property names.

Keeping systemctl on Your Side

This is only an overview of an extremely lengthy subject. You do not need to study systemctl for long before you can understand why critics of systemd complain that systemd violates the unofficial Unix philosophy of one simple command to accomplish one simple task. In contrast to that philosophy, systemctl can potentially affect everything on a system. However, the obverse of that philosophy is that systemd creates a consistent administrative layer, that, once learned, can be applied elsewhere. In that sense, systemd is simple as well, although its simplicity is of a different nature than a simple shell script or a command with limited philosophy.

However, it hardly needs to be said that with systemctl's great power comes the potential for great harm. Especially as you learn systemctl, be careful to double-check your command structure and make sure that you understand exactly what various functions and options do. Otherwise, systemctl, which is a benefit to administration, could quickly make life complicated.