Add Uptime Kuma API management tooling
Implements programmatic monitor management via Socket.IO API: - manage_monitors.py: CLI script for CRUD operations on monitors - API.md: Comprehensive API usage documentation - SETUP.md: Step-by-step setup and verification guide Key features: - Supports API key and username/password authentication - List, add, update, delete monitors via CLI - SSL verification disabled for self-signed certificates - Monitor types: HTTP, TCP, ping, DNS, docker
This commit is contained in:
@@ -0,0 +1,217 @@
|
||||
# Uptime Kuma API Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
Uptime Kuma provides a Socket.IO-based API for programmatic monitor management. The REST API does **not** support monitor CRUD operations - you must use the Socket.IO API via the `uptime-kuma-api` Python package.
|
||||
|
||||
## Setup
|
||||
|
||||
### 1. Install Python Package
|
||||
|
||||
```bash
|
||||
pip3 install uptime-kuma-api
|
||||
```
|
||||
|
||||
**Requirements:** Python 3.7+
|
||||
|
||||
### 2. Create API Credentials
|
||||
|
||||
#### Option A: API Key (Recommended)
|
||||
|
||||
1. Access Uptime Kuma web UI: https://uptime.kolpacksoftware.com
|
||||
2. Navigate to **Settings → API Keys**
|
||||
3. Click **Generate** to create a new API key
|
||||
4. Set a descriptive name (e.g., "CLI Management")
|
||||
5. Set expiry (or "Never expire")
|
||||
6. **Copy the key immediately** (shown only once)
|
||||
7. Store securely in environment variable:
|
||||
|
||||
```bash
|
||||
export UPTIME_KUMA_API_KEY="uk1_your_api_key_here"
|
||||
```
|
||||
|
||||
**Important:** Once the first API key is created, basic authentication is permanently disabled for supported endpoints.
|
||||
|
||||
#### Option B: Username/Password
|
||||
|
||||
Use existing Uptime Kuma login credentials:
|
||||
|
||||
```bash
|
||||
export UPTIME_KUMA_USERNAME="your_username"
|
||||
export UPTIME_KUMA_PASSWORD="your_password"
|
||||
```
|
||||
|
||||
### 3. Make Script Executable
|
||||
|
||||
```bash
|
||||
chmod +x /home/poprhythm/docker-infrastructure/uptime-kuma/manage_monitors.py
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### List All Monitors
|
||||
|
||||
```bash
|
||||
./manage_monitors.py list
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
ID Name Type URL
|
||||
------------------------------------------------------------------------------------------------
|
||||
1 Example Service http https://example.com
|
||||
2 Database Health tcp 192.168.1.100:5432
|
||||
3 Gateway Ping ping 192.168.1.1
|
||||
```
|
||||
|
||||
### Add a Monitor
|
||||
|
||||
**HTTP/HTTPS Monitor:**
|
||||
```bash
|
||||
./manage_monitors.py add --name "My Service" --url "https://myservice.com" --type http
|
||||
```
|
||||
|
||||
**TCP Port Monitor:**
|
||||
```bash
|
||||
./manage_monitors.py add --name "PostgreSQL" --url "192.168.1.100:5432" --type tcp
|
||||
```
|
||||
|
||||
**Ping Monitor:**
|
||||
```bash
|
||||
./manage_monitors.py add --name "Router" --url "192.168.1.1" --type ping
|
||||
```
|
||||
|
||||
**Custom Interval (default is 60 seconds):**
|
||||
```bash
|
||||
./manage_monitors.py add --name "Critical Service" --url "https://critical.com" --interval 30
|
||||
```
|
||||
|
||||
### Update a Monitor
|
||||
|
||||
```bash
|
||||
# Update name
|
||||
./manage_monitors.py update --id 123 --name "New Name"
|
||||
|
||||
# Update URL
|
||||
./manage_monitors.py update --id 123 --url "https://newurl.com"
|
||||
|
||||
# Update interval
|
||||
./manage_monitors.py update --id 123 --interval 300
|
||||
|
||||
# Update multiple fields
|
||||
./manage_monitors.py update --id 123 --name "Updated" --url "https://updated.com" --interval 120
|
||||
```
|
||||
|
||||
### Delete a Monitor
|
||||
|
||||
```bash
|
||||
./manage_monitors.py delete --id 123
|
||||
```
|
||||
|
||||
## Monitor Types
|
||||
|
||||
| Type | Description | URL Format |
|
||||
|------|-------------|------------|
|
||||
| `http` | HTTP/HTTPS endpoint | `https://example.com` or `http://example.com` |
|
||||
| `tcp` | TCP port check | `hostname:port` or `ip:port` |
|
||||
| `ping` | ICMP ping | `hostname` or `ip` |
|
||||
| `dns` | DNS resolution | `example.com` |
|
||||
| `docker` | Docker container | Container name or ID |
|
||||
|
||||
## Authentication
|
||||
|
||||
The script checks for credentials in the following order:
|
||||
|
||||
1. `UPTIME_KUMA_API_KEY` environment variable (preferred)
|
||||
2. `UPTIME_KUMA_USERNAME` and `UPTIME_KUMA_PASSWORD` environment variables
|
||||
|
||||
To persist credentials, add to your shell profile (`~/.bashrc` or `~/.zshrc`):
|
||||
|
||||
```bash
|
||||
export UPTIME_KUMA_API_KEY="uk1_your_api_key_here"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "No credentials provided" Error
|
||||
|
||||
**Problem:** Script cannot find API credentials.
|
||||
|
||||
**Solution:** Set environment variables before running:
|
||||
```bash
|
||||
export UPTIME_KUMA_API_KEY="uk1_your_key"
|
||||
./manage_monitors.py list
|
||||
```
|
||||
|
||||
### Connection Refused
|
||||
|
||||
**Problem:** Cannot connect to Uptime Kuma instance.
|
||||
|
||||
**Solution:**
|
||||
1. Verify service is running: `docker ps | grep uptime-kuma`
|
||||
2. Check URL in script matches web UI access
|
||||
3. Ensure SSL certificate is valid (or use `verify=False` in script for self-signed)
|
||||
|
||||
### "Monitor not found" Error
|
||||
|
||||
**Problem:** Monitor ID doesn't exist.
|
||||
|
||||
**Solution:** Run `./manage_monitors.py list` to see all valid monitor IDs.
|
||||
|
||||
### Import Error: uptime_kuma_api
|
||||
|
||||
**Problem:** Python package not installed.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
pip3 install uptime-kuma-api
|
||||
# Or with sudo if needed:
|
||||
sudo pip3 install uptime-kuma-api
|
||||
```
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Using as a Python Module
|
||||
|
||||
```python
|
||||
from uptime_kuma_api import UptimeKumaApi, MonitorType
|
||||
|
||||
# Connect
|
||||
api = UptimeKumaApi("https://uptime.kolpacksoftware.com")
|
||||
api.login_by_token("uk1_your_api_key")
|
||||
|
||||
# Get all monitors
|
||||
monitors = api.get_monitors()
|
||||
|
||||
# Add monitor
|
||||
api.add_monitor(
|
||||
type=MonitorType.HTTP,
|
||||
name="My Service",
|
||||
url="https://example.com",
|
||||
interval=60
|
||||
)
|
||||
|
||||
# Edit monitor
|
||||
monitor = api.get_monitor(1)
|
||||
monitor['name'] = "Updated Name"
|
||||
api.edit_monitor(1, **monitor)
|
||||
|
||||
# Delete monitor
|
||||
api.delete_monitor(1)
|
||||
|
||||
# Always disconnect
|
||||
api.disconnect()
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [Uptime Kuma API Keys Documentation](https://github.com/louislam/uptime-kuma/wiki/API-Keys)
|
||||
- [Uptime Kuma API Documentation](https://github.com/louislam/uptime-kuma/wiki/API-Documentation)
|
||||
- [uptime-kuma-api Python Package](https://github.com/lucasheld/uptime-kuma-api)
|
||||
- [uptime-kuma-api Documentation](https://uptime-kuma-api.readthedocs.io/)
|
||||
|
||||
## Web UI Access
|
||||
|
||||
- **URL:** https://uptime.kolpacksoftware.com
|
||||
- **Settings:** Click gear icon → API Keys
|
||||
- **Monitor Management:** Dashboard → Add/Edit monitors via UI
|
||||
@@ -0,0 +1,189 @@
|
||||
# Uptime Kuma API Setup Guide
|
||||
|
||||
## Prerequisites Installation
|
||||
|
||||
The management script requires Python 3.7+ and the `uptime-kuma-api` package.
|
||||
|
||||
### Step 1: Install pip (if not already installed)
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install python3-pip -y
|
||||
```
|
||||
|
||||
### Step 2: Install uptime-kuma-api Package
|
||||
|
||||
```bash
|
||||
pip3 install uptime-kuma-api
|
||||
# Or if pip3 is not in PATH:
|
||||
python3 -m pip install uptime-kuma-api
|
||||
```
|
||||
|
||||
**Verify installation:**
|
||||
```bash
|
||||
python3 -c "import uptime_kuma_api; print('Package installed successfully')"
|
||||
```
|
||||
|
||||
## Authentication Setup
|
||||
|
||||
You must configure API credentials before using the management script.
|
||||
|
||||
### Option A: API Key (Recommended)
|
||||
|
||||
1. **Access Uptime Kuma web UI:**
|
||||
- URL: https://uptime.kolpacksoftware.com
|
||||
- Log in with your credentials
|
||||
|
||||
2. **Generate API Key:**
|
||||
- Click the gear icon (Settings)
|
||||
- Navigate to **API Keys** section
|
||||
- Click **Generate**
|
||||
- Set a descriptive name (e.g., "CLI Management")
|
||||
- Set expiry (or "Never expire")
|
||||
- **IMPORTANT:** Copy the key immediately - it's only shown once!
|
||||
|
||||
3. **Configure Environment Variable:**
|
||||
|
||||
Add to `~/.bashrc` or `~/.zshrc`:
|
||||
```bash
|
||||
export UPTIME_KUMA_API_KEY="uk1_your_api_key_here"
|
||||
```
|
||||
|
||||
Or set temporarily:
|
||||
```bash
|
||||
export UPTIME_KUMA_API_KEY="uk1_your_api_key_here"
|
||||
```
|
||||
|
||||
Apply changes:
|
||||
```bash
|
||||
source ~/.bashrc # or source ~/.zshrc
|
||||
```
|
||||
|
||||
### Option B: Username/Password
|
||||
|
||||
```bash
|
||||
export UPTIME_KUMA_USERNAME="your_username"
|
||||
export UPTIME_KUMA_PASSWORD="your_password"
|
||||
```
|
||||
|
||||
**Note:** Once you create the first API key, username/password authentication is permanently disabled for API endpoints. API keys are more secure and recommended.
|
||||
|
||||
## Verification
|
||||
|
||||
### Test 1: Check Script is Executable
|
||||
|
||||
```bash
|
||||
cd /home/poprhythm/docker-infrastructure
|
||||
ls -l uptime-kuma/manage_monitors.py
|
||||
# Should show -rwxr-xr-x (executable permissions)
|
||||
```
|
||||
|
||||
### Test 2: List Existing Monitors
|
||||
|
||||
```bash
|
||||
cd /home/poprhythm/docker-infrastructure
|
||||
./uptime-kuma/manage_monitors.py list
|
||||
```
|
||||
|
||||
**Expected output:**
|
||||
```
|
||||
ID Name Type URL
|
||||
------------------------------------------------------------------------------------------------
|
||||
1 Example Service http https://example.com
|
||||
...
|
||||
```
|
||||
|
||||
### Test 3: Add a Test Monitor
|
||||
|
||||
```bash
|
||||
./uptime-kuma/manage_monitors.py add --name "Test Monitor" --url "https://httpbin.org/status/200" --type http --interval 300
|
||||
```
|
||||
|
||||
### Test 4: Delete the Test Monitor
|
||||
|
||||
```bash
|
||||
# Find the ID from the list command
|
||||
./uptime-kuma/manage_monitors.py list
|
||||
|
||||
# Delete it (replace 999 with actual ID)
|
||||
./uptime-kuma/manage_monitors.py delete --id 999
|
||||
```
|
||||
|
||||
### Test 5: Verify in Web UI
|
||||
|
||||
1. Access https://uptime.kolpacksoftware.com
|
||||
2. Check that the test monitor was created and deleted
|
||||
3. Verify existing monitors match the CLI list output
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "No credentials provided" Error
|
||||
|
||||
**Cause:** Environment variables not set.
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
# Check current environment
|
||||
echo $UPTIME_KUMA_API_KEY
|
||||
|
||||
# If empty, set it:
|
||||
export UPTIME_KUMA_API_KEY="uk1_your_key"
|
||||
```
|
||||
|
||||
### "ModuleNotFoundError: No module named 'uptime_kuma_api'"
|
||||
|
||||
**Cause:** Package not installed or installed for wrong Python version.
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
# Install for your Python 3
|
||||
python3 -m pip install --user uptime-kuma-api
|
||||
|
||||
# Or system-wide (requires sudo)
|
||||
sudo python3 -m pip install uptime-kuma-api
|
||||
```
|
||||
|
||||
### Connection Errors
|
||||
|
||||
**Cause:** Uptime Kuma service not running or URL incorrect.
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
# Check service is running
|
||||
docker ps | grep uptime-kuma
|
||||
|
||||
# Test web UI access
|
||||
curl -k https://uptime.kolpacksoftware.com
|
||||
|
||||
# If needed, start the service
|
||||
cd /home/poprhythm/docker-infrastructure/uptime-kuma
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### SSL Certificate Errors
|
||||
|
||||
**Cause:** Self-signed certificate or certificate validation issues.
|
||||
|
||||
**Fix:** If using self-signed certificates, you may need to modify the script to disable SSL verification (not recommended for production).
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. ✅ Install prerequisites (`python3-pip`, `uptime-kuma-api`)
|
||||
2. ✅ Create API key in web UI
|
||||
3. ✅ Set environment variable
|
||||
4. ✅ Test with `./manage_monitors.py list`
|
||||
5. 📖 Read [API.md](API.md) for full usage documentation
|
||||
|
||||
## Quick Reference
|
||||
|
||||
```bash
|
||||
# Set credentials (add to ~/.bashrc for persistence)
|
||||
export UPTIME_KUMA_API_KEY="uk1_your_api_key"
|
||||
|
||||
# Common commands
|
||||
cd /home/poprhythm/docker-infrastructure
|
||||
./uptime-kuma/manage_monitors.py list
|
||||
./uptime-kuma/manage_monitors.py add --name "Service" --url "https://example.com"
|
||||
./uptime-kuma/manage_monitors.py update --id 123 --interval 120
|
||||
./uptime-kuma/manage_monitors.py delete --id 123
|
||||
```
|
||||
Executable
+156
@@ -0,0 +1,156 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Uptime Kuma Monitor Management Script
|
||||
Usage examples:
|
||||
./manage_monitors.py list
|
||||
./manage_monitors.py add --name "My Service" --url "https://example.com" --type http
|
||||
./manage_monitors.py delete --id 123
|
||||
./manage_monitors.py update --id 123 --name "Updated Name"
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import sys
|
||||
import os
|
||||
from uptime_kuma_api import UptimeKumaApi, MonitorType
|
||||
|
||||
# Configuration
|
||||
UPTIME_KUMA_URL = "https://uptime.kolpacksoftware.com"
|
||||
# Set one of these (or use environment variables):
|
||||
API_KEY = os.getenv('UPTIME_KUMA_API_KEY') # Set via UPTIME_KUMA_API_KEY env var
|
||||
USERNAME = os.getenv('UPTIME_KUMA_USERNAME') # Or use UPTIME_KUMA_USERNAME
|
||||
PASSWORD = os.getenv('UPTIME_KUMA_PASSWORD') # And UPTIME_KUMA_PASSWORD
|
||||
|
||||
def connect():
|
||||
"""Connect to Uptime Kuma API"""
|
||||
# Disable SSL verification for self-signed certificates
|
||||
api = UptimeKumaApi(UPTIME_KUMA_URL, ssl_verify=False)
|
||||
|
||||
if API_KEY:
|
||||
# API key authentication (preferred)
|
||||
api.login_by_token(API_KEY)
|
||||
elif USERNAME and PASSWORD:
|
||||
# Username/password authentication
|
||||
api.login(USERNAME, PASSWORD)
|
||||
else:
|
||||
print("Error: No credentials provided. Set UPTIME_KUMA_API_KEY or UPTIME_KUMA_USERNAME/PASSWORD environment variables.")
|
||||
sys.exit(1)
|
||||
|
||||
return api
|
||||
|
||||
def list_monitors(api):
|
||||
"""List all monitors"""
|
||||
monitors = api.get_monitors()
|
||||
if not monitors:
|
||||
print("No monitors found")
|
||||
return
|
||||
|
||||
print(f"{'ID':<6} {'Name':<30} {'Type':<10} {'URL/Hostname':<50}")
|
||||
print("-" * 96)
|
||||
for monitor in monitors:
|
||||
url = monitor.get('url') or monitor.get('hostname', 'N/A')
|
||||
if url is None:
|
||||
url = 'N/A'
|
||||
print(f"{monitor['id']:<6} {monitor['name']:<30} {str(monitor['type']):<10} {url:<50}")
|
||||
|
||||
def add_monitor(api, name, url, monitor_type='http', interval=60, ignore_tls=False):
|
||||
"""Add a new monitor"""
|
||||
type_map = {
|
||||
'http': MonitorType.HTTP,
|
||||
'https': MonitorType.HTTP,
|
||||
'tcp': MonitorType.PORT,
|
||||
'ping': MonitorType.PING,
|
||||
'dns': MonitorType.DNS,
|
||||
'docker': MonitorType.DOCKER,
|
||||
}
|
||||
|
||||
monitor_type_value = type_map.get(monitor_type.lower(), MonitorType.HTTP)
|
||||
|
||||
# Different monitor types use different parameters
|
||||
if monitor_type.lower() == 'ping':
|
||||
result = api.add_monitor(
|
||||
type=monitor_type_value,
|
||||
name=name,
|
||||
hostname=url,
|
||||
interval=interval
|
||||
)
|
||||
else:
|
||||
kwargs = {
|
||||
'type': monitor_type_value,
|
||||
'name': name,
|
||||
'url': url,
|
||||
'interval': interval
|
||||
}
|
||||
# Add SSL ignore for HTTPS URLs
|
||||
if ignore_tls or (url.startswith('https://') and monitor_type.lower() in ['http', 'https']):
|
||||
kwargs['ignoreTls'] = True
|
||||
result = api.add_monitor(**kwargs)
|
||||
print(f"Monitor added successfully: ID {result['monitorID']}")
|
||||
|
||||
def delete_monitor(api, monitor_id):
|
||||
"""Delete a monitor"""
|
||||
api.delete_monitor(monitor_id)
|
||||
print(f"Monitor {monitor_id} deleted successfully")
|
||||
|
||||
def update_monitor(api, monitor_id, **kwargs):
|
||||
"""Update a monitor"""
|
||||
# Get existing monitor
|
||||
monitor = api.get_monitor(monitor_id)
|
||||
|
||||
# Update fields
|
||||
for key, value in kwargs.items():
|
||||
if value is not None:
|
||||
monitor[key] = value
|
||||
|
||||
api.edit_monitor(monitor_id, **monitor)
|
||||
print(f"Monitor {monitor_id} updated successfully")
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description='Manage Uptime Kuma monitors')
|
||||
subparsers = parser.add_subparsers(dest='command', help='Commands')
|
||||
|
||||
# List command
|
||||
subparsers.add_parser('list', help='List all monitors')
|
||||
|
||||
# Add command
|
||||
add_parser = subparsers.add_parser('add', help='Add a monitor')
|
||||
add_parser.add_argument('--name', required=True, help='Monitor name')
|
||||
add_parser.add_argument('--url', required=True, help='URL to monitor')
|
||||
add_parser.add_argument('--type', default='http', help='Monitor type (http, tcp, ping, dns, docker)')
|
||||
add_parser.add_argument('--interval', type=int, default=60, help='Check interval in seconds')
|
||||
add_parser.add_argument('--ignore-tls', action='store_true', help='Ignore TLS/SSL certificate errors')
|
||||
|
||||
# Delete command
|
||||
delete_parser = subparsers.add_parser('delete', help='Delete a monitor')
|
||||
delete_parser.add_argument('--id', type=int, required=True, help='Monitor ID')
|
||||
|
||||
# Update command
|
||||
update_parser = subparsers.add_parser('update', help='Update a monitor')
|
||||
update_parser.add_argument('--id', type=int, required=True, help='Monitor ID')
|
||||
update_parser.add_argument('--name', help='New name')
|
||||
update_parser.add_argument('--url', help='New URL')
|
||||
update_parser.add_argument('--interval', type=int, help='New interval')
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
if not args.command:
|
||||
parser.print_help()
|
||||
sys.exit(1)
|
||||
|
||||
# Connect to API
|
||||
api = connect()
|
||||
|
||||
try:
|
||||
if args.command == 'list':
|
||||
list_monitors(api)
|
||||
elif args.command == 'add':
|
||||
ignore_tls = getattr(args, 'ignore_tls', False)
|
||||
add_monitor(api, args.name, args.url, args.type, args.interval, ignore_tls)
|
||||
elif args.command == 'delete':
|
||||
delete_monitor(api, args.id)
|
||||
elif args.command == 'update':
|
||||
update_monitor(api, args.id, name=args.name, url=args.url, interval=args.interval)
|
||||
finally:
|
||||
api.disconnect()
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
Reference in New Issue
Block a user