mirror of
https://github.com/troglobit/finit.git
synced 2026-11-20 19:41:51 +00:00
initctl -j status had the state of a service but little of how it is
set up. A program reading it could not tell how the service is
stopped, what scripts it runs, or how it signals readiness.
Add the settings: stop, reload, notify, remain, scripts, directories,
cgroup-config, rlimits, log or tty, provides, conflicts, if, groups,
capabilities, pam, name, id, protected, and nowarn. The restart
object also gets sec, respawn, and oncrash, and the state Finit keeps
for its own use goes in internal:
"stop": {
"signal": "SIGTERM",
"timeout": 3,
"scope": "pgroup"
},
"scripts": {
"exec-stop-post": { "command": "/bin/true", "timeout": 7 }
},
initctl reads the status over D-Bus first, so each setting is also a
property of org.finit.Service1. The new test checks that the JSON is
the same over D-Bus as over the initctl socket.
Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
280 lines
10 KiB
Markdown
280 lines
10 KiB
Markdown
Commands & Status
|
|
=================
|
|
|
|
Finit also implements a modern API to query status, and start/stop
|
|
services, called `initctl`. Unlike `telinit` the `initctl` tool does
|
|
not return until the given command has fully completed.
|
|
|
|
Since Finit v5, `initctl` talks to Finit over the built-in
|
|
[D-Bus API](dbus.md) when the bus socket is available, falling back
|
|
to the legacy `INIT_SOCKET` transport. The `monitor` command streams
|
|
the `org.finit` signals until interrupted.
|
|
|
|
```
|
|
Usage: initctl [OPTIONS] [COMMAND]
|
|
|
|
Options:
|
|
-b, --batch Batch mode, no screen size probing
|
|
-c, --create Create missing paths (and files) as needed
|
|
-f, --force Ignore missing files and arguments, never prompt
|
|
-h, --help This help text
|
|
-j, --json JSON output in 'status' and 'cond' commands
|
|
-n, --noerr Ignore error, e.g., already started/enabled/...
|
|
-1, --once Only one lap in commands like 'top'
|
|
-p, --plain Use plain table headings, no ctrl chars
|
|
-q, --quiet Silent, only return status of command
|
|
-t, --no-heading Skip table headings
|
|
-v, --verbose Verbose output
|
|
-V, --version Show program version
|
|
|
|
Commands:
|
|
debug Toggle Finit (daemon) debug
|
|
help This help text
|
|
version Show program version
|
|
|
|
show Show /etc/finit.conf
|
|
reload Reload /etc/finit.conf (activate changes)
|
|
|
|
cond set <COND> Set (assert) user-defined conditions +usr/COND
|
|
cond get <COND> Get status of user-defined condition, see $? and -v
|
|
cond clear <COND> Clear (deassert) user-defined conditions -usr/COND
|
|
cond status Show condition status, default cond command
|
|
cond dump [TYPE] Dump all, or a type of, conditions and their status
|
|
|
|
log [NAME] Show ten last Finit, or NAME, messages from syslog
|
|
start <NAME>[:ID] Start service by name, with optional ID
|
|
stop <NAME>[:ID] Stop/Pause a running service by name
|
|
reload <NAME>[:ID] Reload service as if .conf changed (SIGHUP or restart)
|
|
This allows restart of run/tasks that have already run
|
|
Note: Finit .conf file(s) are *not* reloaded!
|
|
restart <NAME>[:ID] Restart (stop/start) service by name
|
|
kill <NAME>[:ID] <S> Send signal S to service by name, with optional ID
|
|
monitor Stream D-Bus signals (service state, conditions) until ^C
|
|
ident [NAME] Show matching identities for NAME, or all
|
|
status <NAME>[:ID] Show service status, by name
|
|
status Show status of services, default command
|
|
|
|
cgroup List cgroup config overview
|
|
ps List processes based on cgroups
|
|
top Show top-like listing based on cgroups
|
|
|
|
plugins List installed plugins
|
|
|
|
runlevel [0-9] Show or set runlevel: 0 halt, 6 reboot
|
|
reboot Reboot system
|
|
halt Halt system
|
|
poweroff Halt and power off system
|
|
suspend Suspend system
|
|
switch-root ROOT [INIT] Switch to new root filesystem (initramfs)
|
|
|
|
utmp show Raw dump of UTMP/WTMP db
|
|
|
|
```
|
|
|
|
For services *not* supporting `SIGHUP` the `<!>` notation in the .conf
|
|
file must be used to tell Finit to stop and start it on `reload` and
|
|
`runlevel` changes. If `<>` holds more [conditions](conditions.md),
|
|
these will also affect how a service is maintained.
|
|
|
|
> [!NOTE]
|
|
> Even though it is possible to start services not belonging in the
|
|
> current runlevel these services will not be respawned automatically by
|
|
> Finit if they exit (crash). Hence, if the runlevel is 2, the below
|
|
> Dropbear SSH service will not be restarted if it is killed or exits.
|
|
|
|
The `status` command is the default, it displays a quick overview of all
|
|
monitored run/task/services. Here we call `initctl -p`, suitable for
|
|
scripting and documentation:
|
|
|
|
```
|
|
alpine:~# initctl -p
|
|
PID IDENT STATUS RUNLEVELS DESCRIPTION
|
|
======================================================================
|
|
1506 acpid running [---2345----] ACPI daemon
|
|
1509 crond running [---2345----] Cron daemon
|
|
1489 dropbear running [---2345----] Dropbear SSH daemon
|
|
1511 klogd running [S-12345----] Kernel log daemon
|
|
1512 ntpd running [---2345----] NTP daemon
|
|
1473 syslogd running [S-12345----] Syslog daemon
|
|
|
|
alpine:~# initctl -pv
|
|
PID IDENT STATUS RUNLEVELS COMMAND
|
|
======================================================================
|
|
1506 acpid running [---2345----] acpid -f
|
|
1509 crond running [---2345----] crond -f -S $CRON_OPTS
|
|
1489 dropbear running [---2345----] dropbear -R -F $DROPBEAR_OPTS
|
|
1511 klogd running [S-12345----] klogd -n $KLOGD_OPTS
|
|
1512 ntpd running [---2345----] ntpd -n $NTPD_OPTS
|
|
1473 syslogd running [S-12345----] syslogd -n
|
|
```
|
|
|
|
The environment variables to each of the services above are read from,
|
|
in the case of Alpine Linux, `/etc/conf.d/`. Other distributions may
|
|
have other directories, e.g., Debian use `/etc/default/`.
|
|
|
|
The `status` command takes an optional `NAME:ID` argument. Here we
|
|
check the status of `dropbear`, which only has one instance in this
|
|
system:
|
|
|
|
```
|
|
alpine:~# initctl -p status dropbear
|
|
Status : running
|
|
Identity : dropbear
|
|
Description : Dropbear SSH daemon
|
|
Origin : /etc/finit.d/enabled/dropbear.conf
|
|
Environment : -/etc/conf.d/dropbear
|
|
Condition(s):
|
|
Command : dropbear -R -F $DROPBEAR_OPTS
|
|
PID file : !/run/dropbear.pid
|
|
PID : 1485
|
|
User : root
|
|
Group : root
|
|
Uptime : 2 hour 46 min 56 sec
|
|
Runlevels : [---2345----]
|
|
Memory : 1.2M
|
|
CGroup : /system/dropbear cpu 0 [100, max] mem [--.--, max]
|
|
|- 1485 dropbear -R -F
|
|
|- 2634 dropbear -R -F
|
|
|- 2635 ash
|
|
`- 2652 initctl -p status dropbear
|
|
|
|
Apr 8 12:19:49 alpine authpriv.info dropbear[1485]: Not backgrounding
|
|
Apr 8 12:37:45 alpine authpriv.info dropbear[2300]: Child connection from 192.168.121.1:47834
|
|
Apr 8 12:37:46 alpine authpriv.notice dropbear[2300]: Password auth succeeded for 'root' from 192.168.121.1:47834
|
|
Apr 8 12:37:46 alpine authpriv.info dropbear[2300]: Exit (root) from <192.168.121.1:47834>: Disconnect received
|
|
Apr 8 15:02:11 alpine authpriv.info dropbear[2634]: Child connection from 192.168.121.1:48576
|
|
Apr 8 15:02:12 alpine authpriv.notice dropbear[2634]: Password auth succeeded for 'root' from 192.168.121.1:48576
|
|
```
|
|
|
|
With `-j` the same command gives JSON, for scripts and other programs.
|
|
The view above is kept short for reading, the JSON also has the
|
|
settings of the service:
|
|
|
|
```
|
|
alpine:~# initctl -j status dialer
|
|
{
|
|
"identity": "dialer",
|
|
"description": "Modem dialer",
|
|
"type": "service",
|
|
"forking": false,
|
|
"status": "restart",
|
|
"exit": { "code": 1 },
|
|
"origin": "/etc/finit.d/enabled/dialer.conf",
|
|
"command": "dialer",
|
|
"manual": false,
|
|
"started": false,
|
|
"starts": 0,
|
|
"restarts": 7,
|
|
"restart": {
|
|
"count": 4,
|
|
"max": -1,
|
|
"sec": 10,
|
|
"delay": 160,
|
|
"limit": 300,
|
|
"respawn": false,
|
|
"oncrash": "ignore"
|
|
},
|
|
"name": "dialer",
|
|
"id": "",
|
|
"internal": {
|
|
"job": 12,
|
|
"oldpid": 1234,
|
|
"starting": false,
|
|
"dirty": false,
|
|
"removed": false
|
|
},
|
|
"protected": false,
|
|
"nowarn": false,
|
|
"notify": "none",
|
|
"remain": false,
|
|
"stop": {
|
|
"signal": "SIGTERM",
|
|
"timeout": 3,
|
|
"scope": "pgroup"
|
|
},
|
|
"reload": {
|
|
"signal": "SIGHUP",
|
|
"propagate": false
|
|
},
|
|
"scripts": {
|
|
"exec-stop-post": { "command": "/usr/libexec/dialer-down", "timeout": 3 }
|
|
},
|
|
"directories": {
|
|
"runtime": { "name": "dialer", "mode": "0755" },
|
|
"preserve": "no"
|
|
},
|
|
"cgroup-config": {
|
|
"group": "",
|
|
"config": "",
|
|
"delegate": false
|
|
},
|
|
"rlimits": {
|
|
"core": { "soft": 0, "hard": "unlimited" },
|
|
"nofile": { "soft": 1024, "hard": 4096 },
|
|
...
|
|
},
|
|
"log": {
|
|
"enabled": true,
|
|
"null": false,
|
|
"console": false,
|
|
"file": "",
|
|
"priority": "",
|
|
"identity": "dialer"
|
|
},
|
|
"pidfile": "none",
|
|
"pid": 0,
|
|
"user": "root",
|
|
"group": "root",
|
|
"uptime": 0,
|
|
"runlevels": [ 2, 3, 4, 5 ]
|
|
}
|
|
```
|
|
|
|
In `restart`, `count` is the restart counter that `restart-max`, here
|
|
`max`, is compared to, -1 for `restart = "always"`. The total since
|
|
boot is in `restarts`. `delay` is the number of seconds before the
|
|
next restart, should the service crash, `sec` is `restart-sec`, and
|
|
`limit` is `restart-max-sec`, both 0 when not set. All times are in
|
|
seconds.
|
|
|
|
The settings use the names from the [configuration](config/service-opts.md):
|
|
`scripts` has the `exec-*` scripts that are set, each with its timeout,
|
|
`directories` the `runtime`, `state`, `cache`, `logs`, and `config`
|
|
directories that are set, and `preserve`. `cgroup-config` is the
|
|
`cgroup` setting of the service, where `cgroup` is the control group
|
|
it runs in right now. `rlimits` has every resource limit, the ones
|
|
from `rlimit` and the ones the service inherits. A `tty` has a `tty`
|
|
object with its device and flags where other types have `log`.
|
|
`internal` is state Finit keeps for its own use, it may change between
|
|
releases.
|
|
|
|
Left out when they do not apply are `environment`, `condition`, `exit`,
|
|
`if`, `provides`, `conflicts`, `groups`, `capabilities`, `pam`, and the
|
|
cgroup members `cgroup`, `memory`, `cpu`, and `limits`.
|
|
|
|
```
|
|
alpine:~# initctl -j status dialer | jq .restart.delay
|
|
160
|
|
```
|
|
|
|
|
|
Switch Root
|
|
-----------
|
|
|
|
The `switch-root` command is used when running Finit in an initramfs to
|
|
transition to the real root filesystem. This is similar to the standalone
|
|
`switch_root(8)` utility but integrated into Finit.
|
|
|
|
```
|
|
initctl switch-root /mnt/root [/sbin/init]
|
|
```
|
|
|
|
Requirements:
|
|
|
|
- Must be run during runlevel S (bootstrap) or runlevel 1
|
|
- The new root must be a mount point (different device than /)
|
|
- Can only be used when Finit is running as PID 1 in an initramfs
|
|
|
|
For complete documentation and usage examples, see the dedicated
|
|
[Switch Root](switchroot.md) section.
|