From 97820029c9c16cf7670080d9ad23035c58d5cdc7 Mon Sep 17 00:00:00 2001 From: beaini Date: Sun, 23 Jul 2023 19:00:48 -0400 Subject: [PATCH] Updated the Readme --- README.md | 47 +++++++++++++++++++++++++++++++---------------- 1 file changed, 31 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 6e72687..341755a 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,42 @@ -# MullvadServerAlert +MullvadServerAlert +================== -MullvadServerAlert is a tool that uses GitHub Actions to monitor the status of Mullvad VPN servers and sends alerts to a specified Discord channel when a server is detected as down. It uses the OpenAPI endpoint to fetch the status of each server and verifies their status. +MullvadServerAlert is a tool that uses GitHub Actions to monitor the status of Mullvad VPN servers. It sends alerts via multiple notification services when a server is detected as down. The tool uses the Mullvad API to fetch the status of each server, verifies their status, and sends notifications using [Apprise](https://github.com/caronc/apprise), a universal notification service. -## Setup +Features +-------- -1. **Clone this repository:** Use the "Use this template" button to create a new repository from this template. +- Monitors the status of Mullvad VPN servers at specified intervals +- Sends notifications via multiple services (Discord, Slack, etc.) when a server is detected as down +- Uses GitHub Actions for scheduling and running the checks +- Configurable list of servers to monitor +- Configurable list of Apprise URLs for notifications -2. **Modify the config file:** Edit the `config.json` file in your new repository to include the hostnames of the Mullvad servers you want to monitor. +Setup +----- -3. **Set up the Discord webhook:** - - In your Discord server, create a new webhook (Server Settings > Integrations > New Webhook). - - Copy the webhook URL. +1. Click on the "Use this template" button to create a new repository from this template. -4. **Add the Discord Webhook URL as a GitHub Secret:** - - In your cloned GitHub repository, go to Settings > Secrets > New repository secret. - - Create a new secret named `DISCORD_WEBHOOK` and paste the webhook URL as the value. +2. Navigate to the 'Settings' tab of your new repository and click on 'Secrets' in the left sidebar. -5. **Monitor your Mullvad servers:** The GitHub Action is scheduled to run once an hour and will send a message to your Discord server if any of the specified Mullvad servers are detected as down. +3. Click on the 'New repository secret' button. -## License +4. Create two new secrets: -MullvadServerAlert is released under the MIT License. See the LICENSE file for more details. + - `HOSTNAMES`: A JSON-formatted string of the hostnames you want to monitor. For example: `["server1","server2","server3"]`. + - `APPRISE_URLS`: A JSON-formatted string of the Apprise URLs for the services where you want to receive notifications. For example: `["url1","url2","url3"]`. +5. Save the secrets. GitHub Actions will now have access to these secrets and will use them when running the workflow. -## Contributions +6. The GitHub Actions workflow is already set up in the `.github/workflows` directory in the file `hostname_check.yml`. By default, the workflow is scheduled to run every 5 minutes. If you want to change this, open `hostname_check.yml` and modify the `cron` line under `schedule`. The syntax for this line is the same as for cron jobs. -Contributions are welcome! Please feel free to submit a pull request. +Usage +----- + +After setting up, the GitHub Actions workflow will automatically run at the specified intervals. If a server is detected as down, the tool will send notifications to the configured services. + +You can also run the tool locally by running `python main.py`. Make sure to set the `HOSTNAMES` and `APPRISE_URLS` environment variables if you are not using the `config.json` file. + +Contributing +------------ + +Contributions are welcome! Please open an issue if you encounter any problems or have suggestions for improvements. \ No newline at end of file