# service

control a systemd unit

With running: false, a missing unit file is ok, with the note \<unit\> does not exist. A service step with confirm\_access: true runs the access check after the step, and rolls back when it fails. Run winch doc step.confirm\_access. In a handler, restarted and reloaded check as ok when a service step of the run started the unit after the handler's last notify, no earlier step of the handler changed anything, and the step has no confirm\_access.

A unit of type simple, exec, forking, or idle does not report readiness. After its start or restart, apply watches it for 2 seconds. A reload of such a unit without ExecReload is a restart, and gets the watch. The step fails when the unit is not running then, or when systemd restarted it in that time. A unit that crashes after the 2 seconds passes. A reload ends when ExecReload ends: one that only sends a signal is confirmed as sent, and the unit can still end after it. A health gate checks that a service works. Run winch doc pipeline.health.

## Keys

| Key | Type | Default | Meaning |
| --- | --- | --- | --- |
| [`name`](#service.name) | string | required | unit, with or without .service |
| [`running`](#service.running) | boolean | - | start or stop; unset leaves it |
| [`enabled`](#service.enabled) | boolean | - | start at boot; unset leaves it |
| [`reloaded`](#service.reloaded) | boolean | false | reload, in handlers and winch run only |
| [`restarted`](#service.restarted) | boolean | false | restart, in handlers and winch run only |

### `service.name` {#service.name}

string, required

Unit, with or without .service, such as nginx or certbot.timer.

### `service.running` {#service.running}

boolean

Start or stop; unset leaves it. Without running, the step does not start or stop the unit.

### `service.enabled` {#service.enabled}

boolean

Start at boot; unset leaves it. Without enabled, the step does not change it.

### `service.reloaded` {#service.reloaded}

boolean, default false

Reload, in handlers and winch run only. A unit that cannot reload restarts.

### `service.restarted` {#service.restarted}

boolean, default false

Restart, in handlers and winch run only. A stopped unit stays stopped.

## Example

```yaml
- service:
    name: nginx
    running: true
    enabled: true
```