|
| 1 | +# zinit API Protocol |
| 2 | + |
| 3 | +This documents describes the wire protocol used by the zinit command line tool to talk to the running (zinit init) instance. Basically when you run `zinit init` as your init (normally PID 1) it also listens on a `unix` socket that is available by default under `/var/run/zinit.sock`. |
| 4 | + |
| 5 | +When you execute a command (for example `zinit list`) the tool will connect to the socket, send command to your running instance of `init` to read/write information. |
| 6 | + |
| 7 | +The protocol is a very simple line protocol. the process always like |
| 8 | + |
| 9 | +- connect(unix, /var/run/zinit.sock) |
| 10 | +- write(`<command>`), where command has to always end with a (newline) `\n` |
| 11 | +- read() read response of the operation |
| 12 | + |
| 13 | +after reading the response the connection is automatically closed from the server side (similar to HTTP 1). To do another operation you will need to open a new connection, send command and read the results. |
| 14 | + |
| 15 | +## Controlling zinit with `nc` |
| 16 | + |
| 17 | +Since zinit uses a simple line protocol you can very easily use `nc` tool to connect to zinit and control it. Once you have a working `zinit init` process running (preferably also running some processes) try the following |
| 18 | + |
| 19 | +```bash |
| 20 | +sudo nc -U /var/run/zinit.sock |
| 21 | +``` |
| 22 | + |
| 23 | +nc will now wait for you to send a `command` to zinit. |
| 24 | + |
| 25 | +Now type `list` then press enter, you should get output similar to |
| 26 | + |
| 27 | +```json |
| 28 | +{"state":"ok","body":{"redis":"Running"}} |
| 29 | +``` |
| 30 | + |
| 31 | +so seems `redis` is running. Now do |
| 32 | + |
| 33 | +```bash |
| 34 | +sudo nc -U /var/run/zinit.sock |
| 35 | +status redis |
| 36 | +``` |
| 37 | + |
| 38 | +It should print something like |
| 39 | + |
| 40 | +```json |
| 41 | +{"state":"ok","body":{"after":{"delay":"Success"},"name":"redis","pid":320996,"state":"Running","target":"Up"}} |
| 42 | +``` |
| 43 | + |
| 44 | +## Available commands |
| 45 | + |
| 46 | +- `list` |
| 47 | +- `status <serivce>` |
| 48 | +- `start <service>` |
| 49 | +- `stop <service>` |
| 50 | +- `forget <service>` |
| 51 | +- `monitor <service>` |
| 52 | +- `kill <service>` |
| 53 | +- `shutdown` |
| 54 | +- `reboot` |
| 55 | +- `log [snapshot]` |
| 56 | + |
| 57 | +> NOTE: the log command will return a stream of all logs in plain text format. if `log` has `snapshot` argument it will read all logs available in zinit ringbuffer, then exits (connection is closed from server side). If `log` without a snapshot, it will first print all logs from log ringbuffer, then will follow the logs forever (connection is kept open) and all new logs will appear on the stream as they happen. |
| 58 | +
|
| 59 | +For details and documentation of what the commands do please refer to docs of [commands](readme.md#controlling-commands) |
| 60 | + |
| 61 | +## Returned json schema |
| 62 | + |
| 63 | +All commands (except `log`) return a very json structure: |
| 64 | + |
| 65 | +```json |
| 66 | +{ |
| 67 | + "state": "ok|error", |
| 68 | + "body": <body> |
| 69 | +} |
| 70 | +``` |
| 71 | + |
| 72 | +In case of `state == error` body will be the error message. If `state == ok` then body is command specific data. |
| 73 | + |
| 74 | +> #TODO: document output for each command body |
0 commit comments