You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
132 lines
4.4 KiB
Markdown
132 lines
4.4 KiB
Markdown
# PSWatch
|
|
|
|
pswatch is a minimalist process monitoring and task scheduler that allows you to
|
|
watch system processes and run custom commands when specific conditions or
|
|
patterns are matched. It also implements the `notify` signal with systemd.
|
|
|
|
**Features**
|
|
- match running processes by pattern in: name, exe path or the entire command line.
|
|
- Define multiple conditions and actions.
|
|
- Execute actions when conditions are met on the matched processes.
|
|
|
|
## Installation
|
|
|
|
To install pswatch, clone the repository from GitHub and build it using
|
|
Cargo:
|
|
|
|
```sh
|
|
git clone https://github.com/your-username/pswatch.git
|
|
cd pswatch
|
|
cargo build --release
|
|
```
|
|
|
|
The binary will be located in `target/release/pswatch`.
|
|
|
|
## Usage
|
|
|
|
Pswatch requires a `TOML` based configuration file. By default it uses the
|
|
config file under $XDG_CONFIG_DIR/pswatch/config.toml or the one provided as
|
|
parameter.
|
|
|
|
```sh
|
|
./pswatch -c /path/to/config.toml
|
|
```
|
|
|
|
The program will watch system processes and execute commands based on the
|
|
patterns defined in the configuration file.
|
|
|
|
## Configuration File
|
|
|
|
pswatch's behavior is configured using a TOML-formatted configuration file.
|
|
The file should contain a list of `watches`, each containing a `pattern` (the
|
|
process name to match), a `regex` flag (set to `true` if the pattern is a
|
|
regular expression), and a list of `commands`.
|
|
|
|
Each command contains a condition (either `seen` or `not_seen` with a duration)
|
|
and an array of shell commands (`exec`) to execute when the condition is met. An
|
|
optional `run_once` flag can be set to run the command only once per process
|
|
detection.
|
|
|
|
Here's an example configuration file:
|
|
|
|
```toml
|
|
[[watches]]
|
|
pattern = "foo"
|
|
regex = false
|
|
|
|
[[watches.commands]]
|
|
condition = {seen = "5s"}
|
|
exec = ["sh", "-c", "notify-end action!"]
|
|
# run_once = false # uncomment to run the command only once per process
|
|
detection
|
|
```
|
|
|
|
## Examples with Multiple Watches
|
|
|
|
You can use multiple watches within a single configuration file to monitor
|
|
different processes and execute commands based on their patterns. Here's an
|
|
example configuration that uses two watches:
|
|
|
|
```toml
|
|
[[watches]]
|
|
pattern = "bar"
|
|
regex = false
|
|
|
|
[[watches.commands]]
|
|
condition = {not_seen = "5s"}
|
|
exec = ["sh", "-c", "echo not seen!"]
|
|
|
|
[[watches]]
|
|
pattern = "baz"
|
|
regex = true
|
|
|
|
[[watches.commands]]
|
|
condition = {seen = "10s"}
|
|
exec = ["sh", "-c", "say 'baz detected!'"]
|
|
run_once = true # run the command only once per process detection
|
|
```
|
|
|
|
In this example, pswatch will watch for two processes: "bar" and "baz". When
|
|
"bar" is not seen for 5 seconds, it will execute `echo not seen!`. When "baz" (a
|
|
regular expression) is detected, it will execute `say 'baz detected!'` after a
|
|
delay of 10 seconds. The command for "baz" will be run only once per process
|
|
detection.
|
|
|
|
## Example Scenarios
|
|
|
|
1. **Execute a command when a specific process is seen for a certain duration**
|
|
- Define a watch with the desired process name and use `{seen = "duration"}` to specify that the command should be executed when the process has been running for a specified duration (e.g., "5s").
|
|
|
|
2. **Execute a command when a specific process is not seen for a certain duration**
|
|
- Define a watch with the desired process name and use `{not_seen = "duration"}` to specify that the command should be executed when the process has been absent for a specified duration (e.g., "5s").
|
|
|
|
3. **Execute multiple commands based on different conditions**
|
|
- Define multiple watch configurations in the same TOML file and specify separate `condition` and `exec` settings for each. pswatch will monitor all configured watches and execute their respective commands when appropriate.
|
|
|
|
## Troubleshooting
|
|
|
|
If you encounter any issues while using pswatch, please refer to the
|
|
[TROUBLESHOOTING.md](TROUBLESHOOTING.md) file in this repository for
|
|
troubleshooting tips and solutions.
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! If you'd like to contribute to pswatch, please
|
|
follow these steps:
|
|
|
|
1. Fork the repository on GitHub.
|
|
2. Clone your fork to your local machine: `git clone
|
|
https://github.com/your-username/pswatch.git`.
|
|
3. Create a new branch for your changes: `git checkout -b my-feature`.
|
|
4. Make your changes and commit them with descriptive messages: `git commit
|
|
-am 'Add some feature'`.
|
|
5. Push your branch to your GitHub fork: `git push origin my-feature`.
|
|
6. Submit a pull request from your GitHub fork to the main repository.
|
|
|
|
## License
|
|
|
|
pswatch is licensed under the AGPLv3 License. See [LICENSE](LICENSE) for more
|
|
details.
|
|
|
|
|