www.uptimerobot.com is an excellent service which provides monitoring of up to 50 websites for free. The developers of this service have also created an API allowing for programmatically creating and modifying the data in one's account. Here is a command line tool which allows to create new monitors from the Linux command line or a shell script which is very useful if one is hosting many websites at once.
Requirements
The command line utility is a python script and therefore should run on any Linux system. It was tested on Debian.
Download
The software is currently available as a source code package only, but it can easily be build and installed from the source. See below.
Download the source code from https://github.com/uptimerobot/uptimerobot-cli/archive/master.zip.
Installation
As root, install the required python packages (the statements below will work with Debian, Ubuntu and other Debian-based distributions).
# apt-get install python-pip python-yaml python-argparse Reading package lists... Done Building dependency tree Reading state information... Done ... # |
Download and unpack the source code.
# wget https://github.com/uptimerobot/cli/archive/master.zip ... Saving to: "master.zip" # unzip master.zip Archive: master.zip 2cfe94fe18d8be088ab4ce0b9404550a44075b41 creating: cli-master/ extracting: cli-master/.gitignore inflating: cli-master/.uptimerobot.yml inflating: cli-master/LICENSE ... # |
After that create a package from the source code and install it:
# cd cli-master/
# python build.py release
running sdist
running egg_info
creating uptimerobot.egg-info
writing requirements to uptimerobot.egg-info/requires.txt
...
Distribution package created in dist/
# pip install dist/uptimerobot-1.0.0.tar.gz
Unpacking ./dist/uptimerobot-1.0.0.tar.gz
Running setup.py egg_info for package from file:///home/u00/cli-master/dist/uptimerobot-1.0.0.tar.gz
Downloading/unpacking requests>=1.2.0 (from uptimerobot)
...
Running setup.py install for uptimerobot
Installing uptimerobot script to /usr/local/bin
Successfully installed pyyaml requests termcolor uptimerobot
Cleaning up...
# |
The uptimerobot command is now available.
Tutorial
First, create a free account at www.uptimerobot.com, select "My Settings"
and enable the API access by clicking the "API Information (show details)" link in your profile. Note the API key - we need it for every access to the uptimerobot site.
You should also add one or two monitors manually so that you can list and modify them using the uptimerobot command.
Working with contacts
First, let's list all alert contacts. These are the email addresses that will receive a notification email if there is a problem with a monitored site:
$ uptimerobot get-alerts --api-key u83645-0123 email: arne@schirmacher.de [Active] #083645 $ |
This command should return the email address of your uptimerobot account, and all additional email addresses that you have registered. Note the alert contact id for each alert contact, it is needed to reference a contact when administrating a website monitor.
Add a new alert contact:
$ uptimerobot new-alert admin@schirmacher.de --api-key u83645-0123 Created alert contact with id: 1350251 $ uptimerobot get-alerts --api-key u83645-0123 email: arne@schirmacher.de [Active] #083645 email: admin@schirmacher.de [Active] #1350251 $ |
The new alert contact is created on the uptimerobot site, and an activation email is sent to that email address. Similarly, it is also possible to delete an entry by referencing it by its id or email-address:
$ uptimerobot delete-alert admin@schirmacher.de --api-key u83645-0123 Deleted alert contact with id: 1350251 $ |
Working with monitors
Now let's list the existing monitors (this should return the entry that you have created manually):
$ uptimerobot get-monitors --api-key u83645-0123 schirmacher [Up] #775795065 URL: http://www.schirmacher.de Type: http(s) All Time Uptime Ratio: 100.00% -------------------- $ |
Add a new monitor by entering its URL and the corresponding alert id:
$ uptimerobot new-monitor Google http://www.google.de --alerts 083645 1350251 --api-key u83645-0123 Created monitor with id: 775795516 $ uptimerobot get-monitors --api-key u83645-0123 schirmacher [Up] #775795065 URL: http://www.schirmacher.de Type: http(s) All Time Uptime Ratio: 100.00% -------------------- Google [Up] #775795516 URL: http://www.google.de Type: http(s) All Time Uptime Ratio: 100.00% -------------------- $ |
You can of course also delete the monitor by referencing it by name or monitor id.
$ uptimerobot delete-monitor Google --api-key u83645-0123 Deleted monitor with id: 775795516 $ |
Using defaults
It is annoying to have to add the api key to every single uptimerobot command line. Therefore it is possible to store it into a defaults file.
Copy the file cli-master/uptimerobot/.uptimerobot.yml to your home directory and edit it accordingly. It is also possible to copy it to the current directory. uptimerobot will look in the current directory first, then in the users's home directory. A command line setting will always override the default settings.
---
# UptimeRobot API key MUST BE SET BY THE USER (in config or on the command line).
api_key: u83645-0123
# Only optional parameters are defaulted here.
# Remember that alerts and monitors are STRINGS, not numbers.
get_monitors:
monitors: null # e.g ['012', 'my monitor', '1451']
show_alerts: False
show_log: False
log_alerts: False
log_timezone: False
uptime: null # e.g [1, 5, 10]
new_monitor:
type: 1 # http(s)
subtype: null
port: null
keyword_type: null
keyword: null
username: null
password: null
alerts: null # e.g. ['12315', 'my alert']
edit_monitor:
# Probably not a good idea to default any of these.
name: null
status: null
url: null
type: null
subtype: null
port: null
keyword_type: null
keyword: null
username: null
password: null
alerts: null # e.g. ['12315', 'my alert']
get_alerts:
alerts: null # e.g. ['12315', 'my alert']
new_alert:
type: 2 # Default to email |
Help
The uptimerobot command comes with a builtin help. Just run uptimerobot -h or uptimerobot SUBCOMMAND -h to learn about all options of the program. There are many more options and features available, which are not mentioned in this tutorial.
During development we stumbled upon a few minor bugs in the uptimerobot API. If things do not work even if they should, you may have found a new bug.
Documentation
get-monitors: Get information about some or all monitors
Synopsis
uptimerobot get-monitors [OPTION] ...
-h, --help
show this help message and exit.
--api-key STR
Your uptimerobot.com api-key (for account or individual monitor).
--monitors MONITOR [MONITOR ...]
IDs or names of monitors.
--uptime NUM-HOURS [NUM-HOURS ...]
Show custom uptime ratios, for one or more periods (in hours).
--show-log
Show logs associated with this monitor.
--log-alerts
Show logs with their associated alert contacts (ignored without --show-log).
--show-alerts
shows alert contacts associated with this monitor.
--log-timezone
shows timezone for the logs (ignored without --show-log).
new-monitor: create a new monitor
Synopsis
uptimerobot new-monitor NAME URL [OPTION] ...
positional arguments:
NAME
Friendly name for new monitor
URL
URL for new monitor
optional arguments:
-h, --help
show this help message and exit
--api-key STR
Your uptimerobot.com api-key (for account or individual monitor).
--type N
Monitor type. The parameter is one of these integer values:
1: http(s)
2: keyword
3: ping
4: port
--subtype N
Monitor subtype. The parameter is one of these integer values:
1: http
2: https
3: ftp
4: smtp
5: pop3
6: imap
99: custom
--port N
Port to monitor
--keyword-type N
When monitoring for keywords (parameter "--type 2"), this integer selects the monitoring type.
1: exists
2: not exists
--keyword STR
Keyword to monitor
--username STR
HTTP username to use for private site
--password STR
HTTP password to use for private site
--alerts ID [ID ...]
IDs of alert contacts to use
edit-monitor: Edit an existing monitor
Synopsis
uptimerobot edit-monitor ID [OPTION] ...
positional arguments:
ID
ID of monitor to edit
optional arguments:
-h, --help
show this help message and exit
--api-key STR
Your uptimerobot.com api-key (for account or individual monitor).
--name STR
Friendly name of monitor
--status N
Status to set the monitor to: one of
0: paused
1: running
--url STR
URL to monitor
--type N
Monitor type. The parameter is one of these integer values:
1: http(s)
2: keyword
3: ping
4: port
--subtype N
Monitor subtype. The parameter is one of these integer values:
1: http
2: https
3: ftp
4: smtp
5: pop3
6: imap
99: custom
--port N
Port to monitor
--keyword-type N
When monitoring for keywords (parameter "--type 2"), this integer selects the monitoring type.
1: exists
2: not exists
--keyword STR
Keyword to monitor
--username STR
HTTP username to use for private site
--password STR
HTTP password to use for private site
--alerts ID [ID ...]
IDs of alert contacts to use