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.
137 lines
4.5 KiB
Markdown
137 lines
4.5 KiB
Markdown
# PSwatch README
|
|
|
|
This is a program that allows you to watch system processes and run custom
|
|
commands when specific patterns are matched. It's written in Rust for better
|
|
performance and safety. This README will guide you through the usage of the
|
|
program, as well as provide examples of using multiple watches within the same
|
|
configuration file.
|
|
|
|
## Table of Contents
|
|
|
|
1. [Installation](#installation)
|
|
2. [Usage](#usage)
|
|
3. [Configuration File](#configuration-file)
|
|
4. [Examples with Multiple Watches](#examples-with-multiple-watches)
|
|
5. [Troubleshooting](#troubleshooting)
|
|
6. [Contributing](#contributing)
|
|
7. [License](#license)
|
|
|
|
## 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
|
|
|
|
To use pswatch, provide the path to a configuration file as an argument:
|
|
|
|
```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 MIT License. See [LICENSE](LICENSE) for more
|
|
details.
|
|
|
|
|