serverherald 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

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

serverherald 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/serverherald

serverherald 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 File

This script will create a `~/.serverherald/servers.json` cache file to recordthe results from the previous execution.