Package: serverherald
# serverheraldserverherald announces when a new Rackspace OpenStack Cloud Server becomesACTIVE by polling the API. It supports multiple notification methods, withemail being the most popular.## UsageFor your first run, enable the silent switch so that serverherald can learnabout your existing servers:$ serverherald --silentAll future runs can drop the silent option so that notifications are sent fornew servers.$ serverherald## Notification Methodsserverherald has a pluggable notification system that currently supports thefollowing methods:* Email (SMTP, [Mailgun](http://www.mailgun.com/), or [Sendgrid](http://sendgrid.com))* SMS ([Twilio](http://www.twilio.com/) or [Nexmo](http://nexmo.com/))* Mobile notification apps ([Prowl](http://www.prowlapp.com/) or [Pushover](https://pushover.net/))* [PagerDuty](http://www.pagerduty.com/) event trigger* Custom HTTP(S) webhookThe `method` directive in the configuration file determines how serverheraldsends notifications.## Installationserverherald is written in Python. It requires Python 2.6 or Python 2.7 andmultiple dependencies. It is recommended to install this inside of a Pythonvirtual environment.### Red Hat / CentOSInstall python-virtualenv:# rpm -ivh http://dl.fedoraproject.org/pub/epel/6/i386/epel-release-6-8.noarch.rpm# yum install python-virtualenv### Ubuntu / DebianInstall python-virtualenv:$ sudo apt-get install python-virtualenv### serverherald Installation$ git clone git+https://github.com/rackerlabs/serverherald.git$ virtualenv ~/venv$ source ~/venv/bin/activate$ python setup.py install## Configuration Fileserverherald requires a configuration file in[YAML format](http://yaml.org/spec/1.1/#id857168). You can specify the filelocation at runtime with the `--config` option. Otherwise serverherald willsearch these locations and select the first file that exists:* serverherald.yaml (in the current directory)* ~/.serverherald/serverherald.yaml* /etc/serverherald.yaml* /etc/serverherald/serverherald.yaml### Example ConfigurationsEmail notifications via a local SMTP server:method: smtpemail:to:- you@yourcompany.com- list@yourcompany.comfrom: Server Herald <noreply@yourcompany.com>accounts:myclouduser1:apikey: db2132af5dc3125f9c688661fefab621endpoint: USmyclouduser2:apikey: cef58b947cd85a4fd772fe37c9408ffaendpoint: USmyclouduser3:apikey: 6d708e45a377d3f4421542217c282a22endpoint: LONEmail notifications via Mailgun:method: mailgunmailgun:domain: mydomain.mailgun.orgapikey: key-3ax6xnjp29jd6fds4gc373sgvjxteol0email:to:- you@yourcompany.comfrom: Server Herald <postmaster@mydomain.mailgun.org>accounts:myclouduser1:apikey: db2132af5dc3125f9c688661fefab621Email notifications via Sendgrid:method: sendgridsendgrid:apikey: 1234567890apiuser: myusernameemail:to:- you@yourcompany.comfrom: noreply@yourcompany.comaccounts:myclouduser1:apikey: db2132af5dc3125f9c688661fefab621SMS notifications via Twilio:method: twiliotwilio:accountsid: 6d708e45a377d3f4421542217c282a22token: cef58b947cd85a4fd772fe37c9408ffafrom: "+15551234567"to: "+15557654321"accounts:myclouduser1:apikey: db2132af5dc3125f9c688661fefab621SMS notifications via Nexmo:method: nexmonexmo:apikey: 12345678apisecret: 87654321from: 15551234567to: 155577654321accounts:myclouduser1:apikey: db2132af5dc3125f9c688661fefab621iOS push notifications via Prowl:method: prowlprowl:apikey: 6d708e45a377d3f4421542217c282a55accounts:myclouduser1:apikey: db2132af5dc3125f9c688661fefab621Android or iOS push notifications via Pushover:method: pushoverpushover:apikey: 6d708e45a377d3f4421542217c282a55accounts:myclouduser1:apikey: db2132af5dc3125f9c688661fefab621PagerDuty event trigger:method: pagerdutypagerduty:apikey: 6d708e45a377d3f4421542217c282a55accounts:myclouduser1:apikey: db2132af5dc3125f9c688661fefab621Custom HTTP or HTTPS webhook notifications:method: webhookwebhook:url: http://example.com/notify-meaccounts:myclouduser1:apikey: db2132af5dc3125f9c688661fefab621### Securing Sensitive Data in Configuration Filesserverherald supports storing and retrieving sensitive values from keyringsso that they do not have to be stored in a human-readable text file. They keyword `USE_KEYRING` will signal serverherald that it needs to lookup the value.If the secret has not been stored, serverherald will prompt the user for theinitial value.Here's an example configuration that protects the Prowl API key:method: prowlprowl:apikey: USE_KEYRINGaccounts:myclouduser1:apikey: db2132af5dc3125f9c688661fefab621## Deploymentserverherald should be used to poll the Rackspace Cloud Servers API ona regular interval so that it can detect changes and then announce them.A 5 minute cron job is recommended:*/5 * * * * /path/to/serverheraldserverherald uses lockfiles to prevent overlapping runs.## FAQ### Do I have to use Python virtualenv?No, there is no requirement to use Python virtualenv. Python virtualenvenables us to keep the global Python packages clean and to prevent conflictsbetween required versions of Python modules between different Pythonapplications.If you decide to go this route, there is a python-yaml in Ubuntu and a PyYAMLpackage in Red Hat/CentOS.Many of the other Python modules will still need to be installed viapip/easy_install as there are no packages provided by your distribution'ssoftware repository.## Additional Notes### Server Cache FileThis script will create a `~/.serverherald/servers.json` cache file to recordthe results from the previous execution.## Developers1. [Matt Martz](https://github.com/sivel) - Primary Developer1. [Caleb Groom](https://github.com/calebgroom)