# sys-systemctl

Utility role to reset/clean up **systemd** units for a given software stack.  
It can install a unit-file remover tool, delete units that match a configured suffix, and reload the systemd daemon. The role is designed to run **once per play** and is commonly included by other roles (e.g., timer/service roles) to ensure a clean state before (re)deployment.

## Overview

When `MODE_RESET` is enabled, the role will:

1. Install the configured remover tool/package (via `pkgmgr-install`).
2. Remove all unit files that match the configured suffix for the current software.
3. Reload the systemd daemon to apply changes.

A run-once guard (`run_once_sys_systemctl`) prevents repeated execution within the same play run.

## Features

- **Idempotent cleanup** of systemd unit files based on a suffix.
- **Pluggable remover tool** via `UNIT_SUFFIX_REMOVER_PACKAGE`.
- **Daemon reload** to immediately apply changes.
- **Run-once safety** across the play to avoid redundant work.

## Variables

| Variable                     | Type    | Default     | Description                                                                                 |
|-----------------------------|---------|-------------|---------------------------------------------------------------------------------------------|
| `MODE_RESET`                | bool    | `false`     | If `true`, executes the reset/cleanup tasks.                                                |
| `SYS_SERVICE_SUFFIX`        | string  | *required*  | Suffix used to identify unit files belonging to the software stack (e.g., `.infinito.nexus`). |
| `SOFTWARE_NAME`             | string  | *required*  | Logical software identifier passed to the remover tool.                                      |
| `UNIT_SUFFIX_REMOVER_PACKAGE` | string| `"unsure"`  | Package/command used to remove the unit files. Must provide a CLI compatible with `-s`.     |

> **Note:** The role expects the remover tool to support a command pattern like:
> ```
> <UNIT_SUFFIX_REMOVER_PACKAGE> -s '<SOFTWARE_NAME>'
> ```
> Replace `UNIT_SUFFIX_REMOVER_PACKAGE` with your actual utility (or wrapper script) that removes all matching unit files.

## Tasks Flow

- `tasks/main.yml`
  - Includes `tasks/01_reset.yml` **only when** `MODE_RESET` is `true`.
  - Loads `utils/run_once.yml` once to set `run_once_sys_systemctl`.

- `tasks/01_reset.yml`
  - Installs `UNIT_SUFFIX_REMOVER_PACKAGE` via `pkgmgr-install`.
  - Executes the remover command to purge unit files for `SOFTWARE_NAME` / `SYS_SERVICE_SUFFIX`.
  - Runs `systemctl daemon-reload`.

## Dependencies

- `pkgmgr-install` (role): used to install `UNIT_SUFFIX_REMOVER_PACKAGE`.