Troubleshooting Torcx

Torcx generator runs early in the boot, when other system facilities are not yet set up and available for use. In case of errors, troubleshooting and debugging can be performed following the suggestions described here.

Checking for failures

In case of errors, Torcx stops before sealing the new system state. This means that in order to check for correct execution, it is sufficient to verify that the metadata file exists:

test -f /run/metadata/torcx || echo 'torcx failed'

On failures, the metadata seal file will not exist, and torcx failed will be printed. Verify failure at boot time using the torcx.target unit:

$ sudo systemctl start torcx.target ; sudo systemctl status torcx.target

Assertion failed on job for torcx.target.

* torcx.target - Verify torcx succeeded
   Loaded: loaded (/usr/lib/systemd/system/torcx.target; disabled; vendor preset: disabled)
   Active: inactive (dead) since [...]
   Assert: start assertion failed at [...]
           AssertPathExists=/run/metadata/torcx was not met

Gathering logs

The single most useful piece of information needed when troubleshooting failure is the log from torcx-generator. This binary does not run as a typical systemd service, thus log filtering must be done via its syslog identifier. With systemd-journald, this can be accomplished with the following command:

journalctl --boot 0 --identifier /usr/lib64/systemd/system-generators/torcx-generator

If this doesn’t yield results, run as root. There may be instances in which the journal isn’t owned by the systemd-journal group, or the current user is not part of that group.

Validating the configuration

One common cause for Torcx failure is a malformed configuration (such as a mis-assembled profile, or a syntax error). In other cases, the active profile might reference addon images which are no longer available on the system.