Go to file
2024-10-29 08:55:51 +02:00
src first commit 2024-10-26 09:08:11 +02:00
.gitignore first commit 2024-10-26 09:08:11 +02:00
LICENSE first commit 2024-10-26 09:08:11 +02:00
README.md Update the systemd details to avoid double monitoring. 2024-10-29 08:55:51 +02:00

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

  • 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

  1. Dependency Checks:

    • Ensures that jq, whiptail, and octosail are installed.
    • Prompts the user to install any missing dependencies.
  2. 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.
  3. 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

  1. 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
    
  2. 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:

  1. Run the Script:

    octokuma
    
  2. 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).

Manual Configuration

If you prefer to create or edit the configuration file manually, follow these steps:

  1. Create the Configuration Directory:

    mkdir -p $HOME/.config/octokuma
    
  2. Create the Configuration File:

    nano $HOME/.config/octokuma/config.json
    
  3. 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 and instance_name with your actual monitor IDs and corresponding Lightsail instance names.
  4. Save and Close the File:

    Press Ctrl+O to save and Ctrl+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

  1. Edit the service file by running:

    sudo systemctl edit --force --full octokuma.service
    
  2. 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
    
  3. Save and close the file.

    • User=ubuntu and Group=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

  1. Edit the timer file by running:

    sudo systemctl edit --force --full octokuma.timer
    
  2. 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
    
  3. 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

  1. Dependency Issues:

    • Install missing dependencies:

      sudo apt-get install jq whiptail
      
  2. Configuration Issues:

    • Validate the configuration file:

      jq '.' /path/to/config.json
      
  3. AWS CLI Configuration:

    • Configure AWS CLI with:

      
      

bash aws configure ```

  1. 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.