README.md (3486B) download
1# psvstat - Pretty Service Status
2
3`psvstat` is a command-line utility for checking and printing the status of `runit` services. This tool reads the service status from the `supervise/status` file of each specified `runit` service and displays relevant information in a user-friendly format.
4
5## Features
6
7- Displays whether the service is a user service or a system service.
8- Shows the service name, desired state, and current state.
9- Indicates if the service is paused, down, running, or finished.
10- Provides the time elapsed since the last status change.
11- Displays the process ID and command name of the running service.
12
13## Compilation
14
15To compile the program, run the following command:
16
17```sh
18$ make
19$ make PREFIX=$HOME/.local install
20```
21
22## Usage
23
24The `psvstat` program takes one or more arguments, each representing the path to a `runit` service directory. For example:
25
26```sh
27psvstat /etc/service/service1 /etc/service/service2
28```
29
30### Arguments
31
32- **service_path**: The path to the `runit` service directory. The program expects the status file to be located at `service_path/supervise/status`.
33
34## Output
35
36The program prints the status of each specified service in a formatted manner. The output contains the following columns:
37
381. **Type**: Indicates if the service is a user service (`user`) or a system service (`sys`).
392. **Name**: The name of the service.
403. **Desired State**: Indicates if the service's desired state matches its current state.
41 - `=`: The service's desired state matches its current state.
42 - `v`: The service is up but should be down.
43 - `^`: The service is down but should be up.
444. **Current State**: The current state of the service.
45 - `paus`: The service is paused.
46 - `down`: The service is down.
47 - `run`: The service is running.
48 - `fin`: The service has finished.
49 - `???`: Unknown state.
505. **Time Since Last Change**: The time elapsed since the last status change.
516. **PID**: The process ID of the service if it is running.
527. **Command**: The command name of the running process if available.
53
54### Example Output
55
56```sh
57sys service1 = run 2 hours 1234 myservice
58sys service2 ^ down 5 minutes --- ---
59```
60
61In this example:
62- `service1` is a system service (`sys`), its desired state matches its current state (`=`), it is currently running (`run`), the status changed 2 hours ago, its PID is 1234, and the command name is `myservice`.
63- `service2` is a system service (`sys`), its desired state does not match its current state (`v`), it should be down but is up, the status changed 5 minutes ago, it is not running (`---`), and no command name is available (`---`).
64
65## Error Handling
66
67The program handles several error conditions and prints appropriate messages to `stderr`:
68
69- If it is unable to open the `supervise/status` file, it prints:
70 ```
71 <service_path>: unable to open supervise/status
72 ```
73- If it is unable to read the `supervise/status` file, it prints:
74 ```
75 <service_path>: unable to read status
76 ```
77
78## Environment Variables
79
80- **HOME**: Used to determine if a service is a user service.
81
82## License
83
84This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
85
86## Contributing
87
88Contributions are welcome! Please open an issue or submit a pull request on GitHub.
89
90## Author
91
92Written by Friedel Schon.
93
94## Acknowledgments
95
96Thanks to the developers and community of `runit` for their excellent software and documentation.