src | ||
.gitignore | ||
LICENSE | ||
README.md |
Octokuma - Easy Monitor and Reboot Lightsail Instances
octokuma is a script designed to monitor specific Uptime Kuma monitors and automatically reboot corresponding Amazon Lightsail instances if any of them go down. It leverages the octosail
script to manage the Lightsail instances and can be scheduled to run at regular intervals using systemd timers.
Table of Contents
- Features
- How It Works
- Prerequisites
- Installation
- Configuration
- Running the Script
- Setting Up Systemd Timer
- Logging
- Troubleshooting
- Additional Notes
- License
Features
- Monitors specified Uptime Kuma monitors.
- Automatically reboots corresponding Amazon Lightsail instances if a monitor is down.
- Interactive configuration setup using
whiptail
. - Dependency checks and automatic installation prompts.
- Designed to run as a systemd service for regular monitoring.
- Runs as the current user to access user-specific configurations.
- Logs are stored in
~/.local/log/
to keep your home directory organized.
How It Works
-
Dependency Checks:
- Ensures that
jq
,whiptail
, andoctosail
are installed. - Prompts the user to install any missing dependencies.
- Ensures that
-
Configuration Loading:
- Reads configuration from a JSON file located in the user's home directory.
- If the configuration file is not found, prompts the user to create it interactively.
-
Monitoring Logic:
- Iterates over each monitor specified in the configuration.
- Checks the status of each monitor via Uptime Kuma's API.
- If a monitor is down, uses
octosail
to reboot the associated Lightsail instance.
Prerequisites
- AWS CLI: The script requires the AWS Command Line Interface (CLI) to interact with your AWS account.
- AWS Credentials: You need to have your AWS credentials configured. The
octosail
script will help you set this up if not already configured. - Dependencies:
jq
: For JSON parsing.whiptail
: For interactive prompts.octosail
: Script to manage Lightsail instances.
Installation
-
Download the Script:
sudo curl -L "https://git.vdm.dev/api/v1/repos/octoleo/octokuma/raw/src/octokuma" -o /usr/local/bin/octokuma sudo chmod +x /usr/local/bin/octokuma
-
Ensure Dependencies are Installed:
The script will check for dependencies and prompt you to install any that are missing when you run it for the first time.
Configuration
The script uses a JSON configuration file to store settings, including the Uptime Kuma URL and the list of monitors to check.
Automatic Configuration
When you run the script for the first time, it will check for the configuration file. If not found, it will prompt you to create it interactively using whiptail
.
Steps:
-
Run the Script:
octokuma
-
Follow the Prompts:
- Uptime Kuma URL:
- You will be asked to enter your Uptime Kuma URL.
- Add Monitors:
- The script will ask if you want to add a monitor.
- If you select "Yes," you will be prompted to enter the Monitor ID and the corresponding Lightsail Instance Name.
- Repeat the process to add multiple monitors.
- Save Configuration:
- Once you have added all monitors, the configuration will be saved to the default path (
$HOME/.config/octokuma/config.json
).
- Once you have added all monitors, the configuration will be saved to the default path (
- Uptime Kuma URL:
Manual Configuration
If you prefer to create or edit the configuration file manually, follow these steps:
-
Create the Configuration Directory:
mkdir -p $HOME/.config/octokuma
-
Create the Configuration File:
nano $HOME/.config/octokuma/config.json
-
Add the Following Content:
{ "uptime_kuma_url": "https://your-uptime-kuma-url", "monitors": [ { "monitor_id": 24, "instance_name": "YourInstanceName1" }, { "monitor_id": 25, "instance_name": "YourInstanceName2" } ] }
- Replace
"https://your-uptime-kuma-url"
with your actual Uptime Kuma URL. - Replace
monitor_id
andinstance_name
with your actual monitor IDs and corresponding Lightsail instance names.
- Replace
-
Save and Close the File:
Press
Ctrl+O
to save andCtrl+X
to exit.
Note: You can also specify a custom configuration file path using the --config
option:
octokuma --config /path/to/your/config.json
Running the Script
To run the script manually, simply execute:
octokuma
-
If you have specified a custom configuration file, use:
octokuma --config /path/to/your/config.json
Setting Up Systemd Timer
To automate octokuma
execution at regular intervals, configure a systemd service and timer with sudo systemctl edit --force --full
.
Create and Configure the Service File
-
Edit the service file by running:
sudo systemctl edit --force --full octokuma.service
-
Enter the following content for the service configuration:
[Unit] Description=OctoKuma Monitoring Service [Service] Type=oneshot User=ubuntu Group=ubuntu ExecStart=/usr/local/bin/octokuma ExecStartPre=/bin/sh -c 'if [ -e /var/lock/octokuma-monitoring.lock ]; then echo "Monitoring already in progress."; exit 1; else touch /var/lock/octokuma-monitoring.lock; fi' ExecStartPost=/bin/rm -f /var/lock/octokuma-monitoring.lock StandardOutput=append:/home/ubuntu/.local/log/octokuma.log StandardError=append:/home/ubuntu/.local/log/octokuma.log
-
Save and close the file.
User=ubuntu
andGroup=ubuntu
ensure that the service runs with appropriate permissions.- Change
ubuntu
to your relevant user name and group name. - Logs are directed to
/home/ubuntu/.local/log/octokuma.log
.
Create and Configure the Timer File
-
Edit the timer file by running:
sudo systemctl edit --force --full octokuma.timer
-
Enter the following configuration for the timer:
[Unit] Description=Run OctoKuma Monitoring Service every 5 minutes [Timer] OnCalendar=*:0/5 Persistent=true [Install] WantedBy=timers.target
-
Save and close the file.
OnBootSec=1min
triggers the service 1 minute after system boot.OnUnitActiveSec=5min
schedules it to run every 5 minutes thereafter.
Enable and Start the Timer
To activate the timer:
sudo systemctl enable octokuma.timer
sudo systemctl start octokuma.timer
Verifying the Service and Timer
-
Service Status:
sudo systemctl status octokuma.service
-
Timer Status:
sudo systemctl status octokuma.timer
Logging
- Log File Location: The log file is located at
/home/ubuntu/.local/log/octokuma.log
.
Ensure the log directory exists:
mkdir -p /home/ubuntu/.local/log
Troubleshooting
-
Dependency Issues:
-
Install missing dependencies:
sudo apt-get install jq whiptail
-
-
Configuration Issues:
-
Validate the configuration file:
jq '.' /path/to/config.json
-
-
AWS CLI Configuration:
-
Configure AWS CLI with:
-
bash aws configure ```
- Permissions Issues:
-
Ensure
octosail
is executable:sudo chmod +x /usr/local/bin/octosail
-
Additional Notes
-
Environment Variables: Adjust
PATH
if necessary. -
Testing the Setup: Test
octokuma
manually to verify functionality:octokuma
-
Stopping the Timer: Disable with:
sudo systemctl disable --now octokuma.timer
Free Software License
@copyright Copyright (C) 2021 Llewellyn van der Merwe. All rights reserved.
@license GNU General Public License version 2; see LICENSE
Disclaimer: Be cautious when using scripts that can reboot servers. Ensure you have proper access controls and safeguards in place to prevent unintended actions. Test the script thoroughly in a safe environment before deploying it to production.