Torcx metadata and systemd target

    In many cases, it is desirable to inspect the state of a system booted with Torcx and to verify the details of the configuration that has been applied. For this purpose, Torcx comes with additional facilities to integrate with systemd-based workflows: a custom target and a metadata file containing environment flags.

    Metadata entries and environment flags

    In order to signal a successful run, Torcx writes a metadata file at most once per boot. The format of this file is suitable for consumption by the systemd EnvironmentFile= directive and can be used to introspect the booted configuration at runtime.

    The metadata file is written to /run/metadata/torcx and contains a list of key-value pairs:

    $ cat /run/metadata/torcx
    
    TORCX_LOWER_PROFILES="vendor"
    TORCX_UPPER_PROFILE="custom-demo"
    TORCX_PROFILE_PATH="/run/torcx/profile.json"
    TORCX_BINDIR="/run/torcx/bin"
    TORCX_UNPACKDIR="/run/torcx/unpack"
    

    These values can be used to detect where assets have been unpacked and propagated (shown above as “unpack” and “bin” entries), which profiles have been sourced (both vendor- and user-provided), and what is the resulting profile that has been applied.

    Finally, the runtime profile can be inspected to detect which addons (and versions) are currently applied:

    $ cat /run/torcx/profile.json
    
    {
      "kind": "profile-manifest-v0",
      "value": {
        "images": []
      }
    }
    

    Torcx target unit

    System services may depend on successful execution of Torcx generator. As such, torcx.target is provided as a target unit which is only reachable if the generator successfully ran and sealed the system.

    This target is not enabled by default, but can be referenced as a dependency by other units who want to introspect system status:

    $ sudo systemctl cat torcx-echo.service
    
    [Unit]
    Description=Sample unit relying on torcx run
    After=torcx.target
    Requires=torcx.target
    
    [Service]
    EnvironmentFile=/run/metadata/torcx
    Type=oneshot
    ExecStart=/usr/bin/echo "torcx: applied ${TORCX_UPPER_PROFILE}"
    
    [Install]
    WantedBy=multi-user.target
    
    $ sudo systemctl status torcx.target
    
    ● torcx.target - Verify torcx succeeded
       Loaded: loaded (/usr/lib/systemd/system/torcx.target; disabled; vendor preset: disabled)
       Active: active since [...]
    
    $ sudo journalctl -u torcx-echo.service
    
    localhost systemd[1]: Starting Sample unit relying on torcx run...
    localhost echo[756]: torcx: applied custom-demo
    localhost systemd[1]: Started Sample unit relying on torcx run.