Introduction: systemd on Custom Android and the Challenge of Complex Dependencies

Integrating systemd into custom Android builds offers significant advantages over traditional init.rc scripts for managing system services. Its robust dependency management, sophisticated logging, and powerful process supervision make it ideal for complex, custom hardware platforms and specialized Android distributions. However, this power comes with a learning curve, particularly when dealing with systemd unit failures, especially those stemming from intricate dependency graphs.

A unit failure typically manifests as a service failing to start, terminating unexpectedly, or operating incorrectly due to its environment not being fully prepared. Debugging these issues requires a systematic approach, understanding how systemd orchestrates services, and proficient use of its diagnostic tools. This article will guide you through advanced troubleshooting techniques for systemd unit failures on custom Android, focusing on complex dependency scenarios.

Understanding systemd Unit Files and Dependency Directives

At the core of systemd are unit files, which describe services, mount points, devices, sockets, and targets. For services, the critical sections are [Unit], [Service], and [Install]. Understanding their directives is paramount for effective debugging.

Key Dependency Directives:

• Requires= / Wants=: Specifies units that must be started alongside or before this unit. Requires implies a hard dependency (if the required unit fails, this unit will be stopped), while Wants is a weaker, non-critical dependency.
• After= / Before=: Defines the ordering of units. After means this unit starts only after the specified units are started. Before means this unit starts before the specified units. These do not imply a dependency failure, only order.
• PartOf=: Makes this unit part of another unit. If the other unit is stopped, started, or reloaded, this unit will be too.
• BindsTo=: Similar to Requires, but if the bound unit stops, this unit will also be stopped.
• Conflicts=: Specifies units that cannot run concurrently with this unit.
• Requisite=: A stronger version of Requires. If the requisite unit is not started, this unit will not be started.
• OnFailure=: Specifies units to activate if this unit enters the ‘failed’ state.

Diagnostic Tools for systemd Failures

Effective debugging starts with the right tools:

• systemctl --failed: Lists all failed units. A quick first check.
• systemctl status <unit_name>: Provides a concise overview of a unit’s current state, including its active status, PID, and a snippet of recent logs.
• journalctl -u <unit_name>: Displays logs specifically for a given unit. Use -xe for detailed output showing explanations and journal context.
• systemctl list-dependencies <unit_name> --all: Shows the full dependency tree, including both `Requires` and `Wants` dependencies, and ordering information. This is crucial for understanding complex graphs.
• systemctl cat <unit_name>: Prints the full contents of the unit file, including any overrides.
• strace: For deeper insights into what a process is doing (system calls, signals). Attach to a running process via strace -p <pid> or run the service’s executable directly with strace <command>.

Common Failure Scenarios in Complex Dependencies

1. Service Starts Before Its Dependency Is Truly Ready: A common pitfall. After=network.target might mean the network stack is up, but not necessarily that a specific Wi-Fi interface has an IP address or that DNS is fully operational.
2. Circular Dependencies: Two or more units requiring each other, leading to a deadlock or start-up timeout.
3. Resource Contention or Permission Issues: A service attempts to access a file, device, or port that is not yet available, or it lacks the necessary permissions, often silently failing or exiting with a non-zero status.
4. Incorrect Executable Path or Arguments: The ExecStart command points to a non-existent binary, or the arguments passed are invalid, causing the service to immediately exit.
5. Service Crashing Internally: The application itself has a bug that causes it to crash shortly after startup, appearing as a systemd failure.

Step-by-Step Debugging Methodology

Let’s walk through a methodical approach to debug a failing systemd unit.

1. Identify the Failing Unit and Initial Symptoms

   Start by identifying the problematic unit:

   systemctl --failedjournalctl -xe

   Note the unit name and any immediately obvious error messages in the journal.

2. Examine the Unit File and Its Environment

   Display the unit file and pay close attention to ExecStart, Type, User, Group, WorkingDirectory, Environment, and particularly the dependency directives in the [Unit] section.

   systemctl cat <failing_unit>

   Verify that ExecStart points to the correct, executable binary. Check if the specified User and Group have the necessary permissions for the service’s operations.

3. Trace Dependencies and Ordering

   This is crucial for complex dependency issues. Understand what your failing unit expects to be ready.

   systemctl list-dependencies <failing_unit> --all

   Examine the output. Are there critical services that your unit Requires or Wants that might be failing or starting too late? Pay attention to After= and Before= directives; ensure the logical flow is correct.

4. Review Detailed Logs

   Dive deep into the logs. Filter by the unit and boot session:

   journalctl -u <failing_unit> -b -o cat

   Look for:

   • Error messages (e.g.,
     
     Android Mobile Specs & Compare Directory

     Are you researching mobile hardware properties, processor SoCs, GPU chipsets, or RAM configurations? Access our complete specs catalog to compare up to 5 devices side-by-side!

     Compare Devices Specs →