﻿`runwisp import systemd` converts `.service` and `.timer` units into
`runwisp.toml`. A `Type=oneshot` unit becomes a [task](/configuration/tasks/)
that runs when the daemon starts. Any other unit becomes a
[service](/configuration/services/). A timer and the service it starts become
one scheduled task, see [Timers](#timers).

## Convert a unit

```bash
runwisp import systemd /etc/systemd/system/myapp.service -o runwisp.toml
runwisp validate
```

A bare unit name such as `myapp.service` also works: it is looked up where
systemd keeps units.

Drop-ins are applied the way systemd applies them: every `NAME.service.d/*.conf`
next to the unit and in `/etc/systemd/system`, `/run/systemd/system` and
`/usr/lib/systemd/system`. That includes the overrides `systemctl edit` writes.

Given `tempoledger.service`:

```ini
[Unit]
Description=Tempo Ledger API

[Service]
Type=simple
ExecStart=/usr/local/bin/bun run start
WorkingDirectory=/srv/tempoledger
User=deploy
Group=deploy
Environment=NODE_ENV=production
Environment=PORT=3000
Restart=always
TimeoutStopSec=30
KillSignal=SIGTERM

[Install]
WantedBy=multi-user.target
```

you get:

```toml title="runwisp.toml"
[services.tempoledger]
description = "Tempo Ledger API"
run = "/usr/local/bin/bun run start"
working_dir = "/srv/tempoledger"
graceful_stop = "30s"
stop_signal = "SIGTERM"
user = "deploy:deploy"

[services.tempoledger.env]
NODE_ENV = "production"
PORT = "3000"
```

The name comes from the file name. A piped-in unit has no file name, so it
gets a placeholder name and a note to rename it. A summary on stderr lists
every unit and anything that needs a look.

If you already have a `runwisp.toml`, use `--write` instead of `-o`; see
[Staging and promoting](/coming-from/cron/#staging-and-promoting). All flags are
in the [CLI reference](/reference/cli/#runwisp-import).

## Disable the unit

The import doesn't stop or disable anything. If systemd and RunWisp both run
the same process, you get two copies fighting over ports or queues. The summary
ends with the command that disables the units you imported. Run it before
RunWisp starts them:

```bash
sudo systemctl disable --now myapp.service
```

`--now` stops it immediately; `disable` keeps it from starting on boot. You can
move a few units at a time, but never leave one enabled in both.
`runwisp service install` lists units that are still enabled under the name of
a task. There is no `takeover` for systemd units.

To go back, re-enable the units with `sudo systemctl enable --now NAME`, delete
their blocks from `runwisp.d/imported.toml` (or `runwisp.toml`, once promoted),
and run `runwisp reload`.

## How the pieces map

| systemd              | runwisp.toml                                                                      | Notes                                                                                                                    |
| -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `Type=oneshot`       | `[tasks.NAME]` with [`run_on_start = "boot"`](/configuration/tasks/#run_on_start) | Runs once per boot.                                                                                                      |
| any other `Type`     | `[services.NAME]`                                                                 | See `Restart=` below.                                                                                                    |
| `ExecStart`          | [`run`](/configuration/services/#run)                                             | One command. `@ - + !` prefixes are removed, with a note. Arguments with shell characters such as `*` or `;` are quoted. |
| `WorkingDirectory`   | [`working_dir`](/configuration/services/#working_dir)                             |                                                                                                                          |
| `User` (+ `Group`)   | [`user`](/configuration/services/#user)                                           | Combined as `user:group`. The daemon must run as root to switch users.                                                   |
| `Environment`        | [`env`](/configuration/services/#env)                                             | Every line is kept.                                                                                                      |
| `EnvironmentFile`    | [`env_file`](/configuration/services/#env_file)                                   | Only the first file. A `-` file that doesn't exist is left out.                                                          |
| `TimeoutStopSec`     | [`graceful_stop`](/configuration/services/#graceful_stop)                         | `0` (no timeout) is left out with a note.                                                                                |
| `TimeoutStartSec`    | [`timeout`](/configuration/tasks/#timeout)                                        | `Type=oneshot` only. On other types it only bounds startup and is dropped.                                               |
| `StandardOutput`     | _(not needed)_                                                                    | Output goes to the run's log. A `file:` or `append:` target gets a note.                                                 |
| `Restart`            | [`restart`](/configuration/services/#restart)                                     | See below.                                                                                                               |
| `KillSignal`         | [`stop_signal`](/configuration/services/#stop_signal)                             |                                                                                                                          |
| `[Unit] Description` | [`description`](/configuration/services/#description)                             |                                                                                                                          |
| `[Install]`          | _(not needed)_                                                                    | Services start with the daemon. See below.                                                                               |

RunWisp starts services when the daemon starts. To keep one stopped at boot,
set [`autostart = false`](/configuration/services/#autostart). For start order,
use [`depends_on`](/configuration/services/#depends_on).

## Timers

**since**: `1.8`

Pass the `.timer` file. The import reads the service it starts from the timer's
`Unit=`, or else `NAME.service` next to it, and writes one task named after the
timer:

```bash
runwisp import systemd /etc/systemd/system/backup.timer -o runwisp.toml
```

Given `backup.timer` and `backup.service`:

```ini
# backup.timer
[Timer]
OnCalendar=Mon..Fri *-*-* 03:30:00
Persistent=true

# backup.service
[Service]
Type=oneshot
ExecStart=/usr/local/bin/backup --all
```

you get:

```toml title="runwisp.toml"
[tasks.backup]
run = "/usr/local/bin/backup --all"
cron = "30 3 * * 1-5"
```

If you also pass the service, it isn't imported a second time. Disable the
timer, not the service: `sudo systemctl disable --now backup.timer`.

| systemd                                  | runwisp.toml                                                  | Notes                                                                                     |
| ---------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `OnCalendar`                             | [`cron`](/configuration/tasks/#cron)                          | `weekly` is Monday. A trailing zone becomes [`timezone`](/configuration/tasks/#timezone). |
| `OnUnitActiveSec`, `OnUnitInactiveSec`   | `cron = "@every …"`                                           | Counted from the last scheduled run, not from when the unit ran. `1d` becomes `24h`.      |
| `OnBootSec`, `OnStartupSec`              | [`run_on_start = "boot"`](/configuration/tasks/#run_on_start) | The delay is dropped.                                                                     |
| `Persistent=true`                        | _(default)_                                                   | Without it, the import sets [`catch_up = 0`](/configuration/tasks/#catch_up).             |
| `RandomizedDelaySec`                     | [`jitter`](/configuration/tasks/#jitter)                      | The closest match, with a note.                                                           |
| `OnActiveSec`, `OnClockChange`           | _(dropped)_                                                   | With a note.                                                                              |
| `AccuracySec`, `WakeSystem`, `[Install]` | _(not needed)_                                                |                                                                                           |

A timer-run service becomes a task whatever its `Type=`, and `Restart=` is
ignored, as systemd ignores it. These need a human:

- **A year or a weekday plus a date.** `OnCalendar=2027-*-* 00:00` and
  `Mon *-*-01..07` have no cron form. The value is kept under a `# TODO`.
- **More than one `OnCalendar`.** Only the first is imported. Add a task for
  each other schedule.
- **A missing service.** The task gets an empty `run` and a `# TODO`. A timer
  piped on stdin has no folder to look in, so it always gets one.

## What needs a human

Anything that can't be mapped gets a `# TODO` in the TOML and a note on the
unit's row.

- **`Restart=`.** `always` is RunWisp's default
  [`restart`](/configuration/services/#restart). `on-failure` becomes
  `restart = "on_failure"`, and `no` (or none) becomes `restart = "never"`.
  `on-success`, `on-abnormal`, `on-abort`, and `on-watchdog` have no exact
  equal, so they land on the closest value with a note.
- **More than one command.** RunWisp runs one [`run`](/configuration/tasks/#run) command. Only the first
  `ExecStart` is imported; other `ExecStart`, `ExecStartPre`, `ExecStartPost`,
  and `ExecStop` lines are flagged. Put them into the `run` script, or setup
  steps into a separate task.
- **`Type=notify` and `Type=forking`.** RunWisp watches the process it starts
  and treats it as up at once. Run the program in the foreground if you can.
- **Sandboxing.** `ProtectSystem`, `PrivateTmp`, `NoNewPrivileges`,
  `CapabilityBoundingSet`, and similar directives are dropped. The process gets
  more access than the unit allowed. If that matters, use a container or a
  restricted user.
- **Socket activation.** Not supported. The program must open its own port.
- **Template units.** `%i`, `%I`, `%n`, `%T`, and similar are not filled in.
  Replace them in the `run` line.
- **A service a timer starts.** Import the `.timer`. The `.service` on its own
  runs once per boot, or all the time, instead of on the timer's schedule.
- **`OnFailure=` and `Condition…=`.** Dropped with a note. Use a
  [notification route](/notifications/) to hear about failures, and put a
  condition into the `run` line.

## Learn more

- [`[services.*]`](/configuration/services/)
- [Tasks vs services](/concepts/tasks-vs-services/)
- [Autostart](/operations/autostart/), to run RunWisp itself under systemd
- [From cron](/coming-from/cron/), for cron jobs
