pretty-svstat

Pretty Printer for runit-services
Log | Files | Refs | README | LICENSE

README.md (3486B)


      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 
     15 To compile the program, run the following command:
     16 
     17 ```sh
     18 $ make
     19 $ make PREFIX=$HOME/.local install
     20 ```
     21 
     22 ## Usage
     23 
     24 The `psvstat` program takes one or more arguments, each representing the path to a `runit` service directory. For example:
     25 
     26 ```sh
     27 psvstat /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 
     36 The program prints the status of each specified service in a formatted manner. The output contains the following columns:
     37 
     38 1. **Type**: Indicates if the service is a user service (`user`) or a system service (`sys`).
     39 2. **Name**: The name of the service.
     40 3. **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.
     44 4. **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.
     50 5. **Time Since Last Change**: The time elapsed since the last status change.
     51 6. **PID**: The process ID of the service if it is running.
     52 7. **Command**: The command name of the running process if available.
     53 
     54 ### Example Output
     55 
     56 ```sh
     57 sys   service1            = run   2 hours     1234   myservice
     58 sys   service2            ^ down  5 minutes   ---    ---
     59 ```
     60 
     61 In 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 
     67 The 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 
     84 This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
     85 
     86 ## Contributing
     87 
     88 Contributions are welcome! Please open an issue or submit a pull request on GitHub.
     89 
     90 ## Author
     91 
     92 Written by Friedel Schon.
     93 
     94 ## Acknowledgments
     95 
     96 Thanks to the developers and community of `runit` for their excellent software and documentation.