Systemd Can’t Find the Unit File Although It Exists

1. Overview

Systemd is the standard service manager on most Linux systems, responsible for starting and stopping services. However, a problem that commonly occurs is when systemd fails to recognize a unit file, even if it exists in the correct location.

In this tutorial, we explore the reasons behind the issue and provide a step-by-step troubleshooting guide to help resolve it.

2. Understanding Systemd Unit Files

Before we begin troubleshooting the issue, let’s first understand what systemd unit files are and how they function. In essence, unit files are the configuration files that systemd uses to manage various resources on our system, including services, devices, and mount points.

They serve as blueprints, providing the system with the necessary instructions to start, stop, and monitor these resources effectively.

Each unit file contains directives that define a resource’s behavior. For instance, a service unit file specifies how a service should start, stop, and reload. It also defines the executable to run and any dependencies it might have.

2.1. Advantages of Unit Files

By using unit files, we gain several advantages:

• Automated service management: We can automate the starting and stopping of services based on specific events or conditions.
• Defined startup order: We can control the order in which services start during the boot process, ensuring that dependencies are met.
• Dependency management: We can explicitly specify which services depend on others, ensuring that services start in the correct order and function correctly.

2.2. Where Systemd Searches for Unit Files

Now, where do we typically find these unit files? Systemd looks for these files in specific directories:

• /usr/lib/systemd/system/ (or /lib/systemd/system/): This directory contains the default unit files provided by the system and software packages. Generally, we avoid modifying these files directly. For instance, the unit file for the SSH service might be located at /usr/lib/systemd/system/sshd.service.
• /etc/systemd/system/: This is where we place our custom or modified unit files. Any unit files placed here override the default ones located in /usr/lib/systemd/system/. For example, if we create a custom unit file for our web server, we would save it as /etc/systemd/system/my-webserver.service.
• /run/systemd/system/: This directory holds unit files generated at runtime. We usually don’t place files here manually.

2.3. Unit Types Systemd Supports

Moreover, systemd supports various unit types, each designed for a specific purpose:

• Service units (.service): These manage system services, such as a web server (nginx.service) or a database (mysql.service).
• Target units (.target): These group units together to bring the system to a specific state. For example, multi-user.target represents a system state corresponding to a non-graphical multi-user environment.
• Mount units (.mount): These control filesystem mount points, such as mounting a partition, /home.mount.
• Timer units (.timer): These schedule tasks to run at specific times or intervals, like a cron job (backup.timer).
• Socket units (.socket): These manage network sockets and inter-process communication.

With this knowledge of systemd unit files, we’re now better prepared to troubleshoot the “missing” unit file problem.

3. Common Causes of the Issue

Now that we have a good grasp of systemd unit files, let’s explore the common reasons why systemd might fail to recognize them. These can range from simple oversights to more subtle configuration issues.

3.1. Incorrect File Permissions

One common reason systemd might not recognize our unit file is due to incorrect file permissions, notably in the context of user-specific services. When we run services under our user account with systemctl –user, systemd operates without full root privileges for those units.

If our user account can’t read the unit file, systemd’s user instance will ignore it, leading to errors claiming the unit file doesn’t exist.

For example, let’s say we place a user-specific service in ~/.config/systemd/user/our-app.service. We’ll assume we made a mistake and set the file’s permissions so that no one can read it:

$ ls -l ~/.config/systemd/user/our-app.service
---------- 1 bluecrane bluecrane 202 Dec 15 17:57 /home/bluecrane/.config/systemd/user/our-app.service

In this scenario, the permission bits show all dashes, meaning no read, write, or execute permissions for anyone. This includes the file owner, the user group, and others. If we run services using systemctl –user, without elevated privileges, systemd can’t bypass standard UNIX file permissions.

Therefore, with no read bit set, systemd can’t access the file content at all.

If we now try to start the service with the –user flag, we might see something like:

$ systemctl --user start our-app.service
Failed to start our-app.service: Unit our-app.service not found.

Systemd reports that the unit file doesn’t exist from its perspective because it can’t read it. To fix this, we need to grant read permissions so that our user — and by extension, systemd — can load the service definition:

$ sudo chmod 644 ~/.config/systemd/user/our-app.service
$ ls -l ~/.config/systemd/user/our-app.service
-rw-r--r-- 1 bluecrane bluecrane 202 Dec 15 17:57 /home/bluecrane/.config/systemd/user/our-app.service

Now, let’s reload the user manager configuration and attempt to start the service again:

$ systemctl --user daemon-reload
$ systemctl --user start our-app.service

This time, systemd should successfully find and start the service, as our user’s systemd instance can now read the unit file.

3.2. SELinux Context Issues

Security-Enhanced Linux (SELinux) can sometimes interfere with systemd’s ability to recognize unit files. If the unit file has the wrong SELinux security context, systemd may ignore it, even if it’s in the correct location with the right permissions.

First, let’s see how to verify whether SELinux is active on our system:

$ sestatus
SELinux status:                 enabled
SELinuxfs mount:                /sys/fs/selinux
SELinux root directory:         /etc/selinux
Loaded policy name:             targeted
Current mode:                   enforcing
Mode from config file:          enforcing
Policy MLS status:              enabled
Policy deny_unknown status:     allowed
Max kernel policy version:      31

If SELinux is active, we need to verify the security context of our unit file. We can use the ls -Z command to display SELinux contexts:

$ ls -Z /etc/systemd/system/<our-service>.service

We should see a similar output:

-rw-r--r--. root root unconfined_u:object_r:systemd_unit_file_t:s0 /etc/systemd/system/<our-service>.service

The important part is systemd_unit_file_t. This context tells SELinux that the file is a systemd unit file. If our file has a different context, systemd may not recognize it.

To fix the SELinux context, we can run:

$ sudo restorecon /etc/systemd/system/<our-service>.service

This command restores the default SELinux context for the file. After that, we can use ls -Z to confirm the context is now correct.

Finally, let’s reload systemd to pick up the changes:

$ sudo systemctl daemon-reload

With the correct SELinux context, systemd can now recognize the unit file and manage it properly.

3.3. Wrong File Location

Often, systemd fails to locate our unit file due to its placement in the incorrect directory. Systemd looks for unit files in specific locations, and it won’t detect our file if it’s not in one of them.

For system-wide services, we have to place our unit files in:

• /etc/systemd/system/ for custom unit files
• /usr/lib/systemd/system/ or /lib/systemd/system/ for system-installed unit files (typically managed by package managers)

If we accidentally place our unit file in a different directory, systemd won’t find it. For example, placing it in our home directory won’t work:

$ sudo systemctl enable ~/uuidd.service
Failed to enable unit: Unit file /home/bluecrane/uuidd.service does not exist.

Let’s move our unit file to the correct location:

$ sudo mv ~/uuidd.service /usr/lib/systemd/system/

For user-specific services (running under our user account), we need to place unit files in ~/.config/systemd/user/.

To use user-specific units, we need to specify the –user flag with systemctl. For example:

$ systemctl --user start <our-service>.service

Therefore, by placing our unit file in the right location, we ensure systemd can find and manage it.

3.4. Missing daemon-reload

After adding or modifying a unit file, we need to inform systemd about the changes. Systemd reads unit files into memory, and it won’t notice new or changed files until we reload the systemd manager configuration.

To reload systemd’s configuration, we need to run:

$ sudo systemctl daemon-reload

This command tells systemd to reload all unit files, adding any changes we’ve made. Without running daemon-reload, systemd will continue to use its cached version of the configuration.

Internally, daemon-reload rescans all unit files, recreates the dependency tree, and updates the internal state. It doesn’t start or stop any services. Instead, it just refreshes systemd’s view of the available units.

3.5. Incorrect File Naming

Systemd relies on specific naming conventions for unit files. For service units, the file must have a .service extension. If our unit file doesn’t follow this convention, systemd won’t recognize it.

For instance, if we name our unit file uuidd.serivce (notice the typo), systemd won’t find it because it expects the extension to be .service:

$ sudo systemctl enable /usr/lib/systemd/system/uuidd.serivce
Failed to enable unit: File /usr/lib/systemd/system/uuidd.serivce: Invalid argument

To check our unit file’s name, we can list the files in the unit directory:

$ ls -l /usr/lib/systemd/system/

Then, we can check if our unit file has the correct name. If we find a typo or incorrect extension, we can rename the file. After correcting the file name, we need to reload systemd.

Hence, by adhering to the correct naming convention, we can help systemd locate and manage our unit files without issues.

3.6. Syntax Errors in the Unit File

Even if our unit file is in the right place with the right permissions, syntax errors within the file can prevent systemd from loading it. Mistyped directives, missing sections, or incorrect formatting can cause systemd to ignore the unit file.

To check for syntax errors, we can use the systemd-analyze verify command:

$ sudo systemd-analyze verify /usr/lib/systemd/system/open-vm-tools.service
/usr/lib/systemd/system/open-vm-tools.service:13: Unknown key name 'ExectStart' in section 'Service', ignoring.
open-vm-tools.service: Service has no ExecStart=, ExecStop=, or SuccessAction=. Refusing.
Unit open-vm-tools.service has a bad unit file setting.

In the above example, ExectStart is misspelled — it should be ExecStart. To fix this error, let’s open our unit file:

$ sudo vim /usr/lib/systemd/system/open-vm-tools.service

We’ll fix the typo, save the file, and execute the verification command once more to guarantee the resolution of all errors.

After fixing any syntax error, we need to reload systemd:

$ sudo systemctl daemon-reload

Now that we’ve fixed the syntax errors in our unit file, systemd can parse and load it correctly.

4. Conclusion

In this article, we explored the common reasons why systemd might fail to recognize a unit file, even when it seemingly exists in the correct location.

We examined various factors, including file permissions, SELinux contexts, file locations, naming conventions, and syntax errors, that can contribute to the issue.

By focusing on these details, we can ensure that systemd doesn’t overlook our unit files. This proactive approach not only solves the immediate issue but enhances our overall system administration skills.