Skip to content

Notifiers

Jump to bottom Edit New page
Brian D. Burns edited this page Mar 25, 2013 · 17 revisions

Notifiers

Currently supported notifiers:

  • Mail
  • Twitter
  • Campfire
  • Prowl
  • Hipchat
  • Pushover

Examples

The following examples should be placed in your Backup configuration file.

Backup::Model.new(:my_backup, 'My Backup') do
  # examples go here...
end

Mail

notify_by Mail do |mail|
  mail.on_success           = true
  mail.on_warning           = true
  mail.on_failure           = true

  mail.from                 = 'sender@email.com'
  mail.to                   = 'receiver@email.com'
  mail.address              = 'smtp.gmail.com'
  mail.port                 = 587
  mail.domain               = 'your.host.name'
  mail.user_name            = 'sender@email.com'
  mail.password             = 'my_password'
  mail.authentication       = 'plain'
  mail.encryption           = :starttls
end

This will make sender@email.com send an email to receiver@email.com every time a Backup process ends.

To receive an email only if a problem occurs, use:

  mail.on_success           = false
  mail.on_warning           = true
  mail.on_failure           = true

on_warning notifications are sent when warnings occur, but the backup process was still successful. on_success implies on_warning. If on_success is true, then warning notifications will be sent regardless of the setting of on_warning.

To ignore warnings and only receive an email if the backup process fails, use:

  mail.on_success           = false
  mail.on_warning           = false
  mail.on_failure           = true

on_warning and on_failure notifications, the email sent will have a copy of the backup log attached, which will show all messages/warnings/errors logged during the backup process. The backup log is not attached to on_success emails.

SMTP Connection Security

mail.encryption may be set to :starttls to use STARTTLS to upgrade the initial connection to SSL/TLS.
It may also be set to :ssl (or :tls) to initiate a direct SSL/TLS connection.
For no encryption (default), set to :none.

Other Delivery Methods

The Mail Notifier uses the Mail library. Mail notifications are sent using Mail::SMTP by default, but the Mail::Sendmail, Mail::Exim and Mail::FileDelivery delivery methods are also supported.

notify_by Mail do |mail|
  mail.on_success           = true
  mail.on_warning           = true
  mail.on_failure           = true

  mail.delivery_method      = :sendmail
  mail.from                 = 'sender@email.com'
  mail.to                   = 'receiver@email.com'

  # optional settings:
  mail.sendmail             # the full path to the `sendmail` program
  mail.sendmail_args        # string of arguments to to pass to `sendmail`
end

Note: sendmail_args will override the defaults set by Mail::Sendmail. See the source for Mail::Sendmail:initialize for details.

notify_by Mail do |mail|
  mail.on_success           = true
  mail.on_warning           = true
  mail.on_failure           = true

  mail.delivery_method      = :exim
  mail.from                 = 'sender@email.com'
  mail.to                   = 'receiver@email.com'

  # optional settings:
  mail.exim                 # the full path to the `exim` program
  mail.exim_args            # string of arguments to to pass to `exim`
end

Note: exim_args will override the defaults set by Mail::Exim. See the source for Mail::Sendmail:initialize for details, as Mail::Exim inherits it's constructor from Mail::Sendmail.

notify_by Mail do |mail|
  mail.on_success           = true
  mail.on_warning           = true
  mail.on_failure           = true

  mail.delivery_method      = :file
  mail.from                 = 'sender@email.com'
  mail.to                   = 'receiver@email.com'
  mail.mail_folder          = '/path/to/store/emails' # default: ~/Backup/emails
end

Twitter

notify_by Twitter do |tweet|
  tweet.on_success = true
  tweet.on_warning = true
  tweet.on_failure = true

  tweet.consumer_key       = 'my_consumer_key'
  tweet.consumer_secret    = 'my_consumer_secret'
  tweet.oauth_token        = 'my_oauth_token'
  tweet.oauth_token_secret = 'my_oauth_token_secret'
end

In order to use Twitter as a notifier you will need a Twitter account. Once you create a Twitter account for the notifier, you need to register a new application for your Twitter account. After registering an application you will acquire the following credentials:

  • consumer_key
  • my_consumer_secret
  • my_oauth_token
  • my_oauth_token_secret

You can find these credentials on your application's pages.

Campfire

notify_by Campfire do |campfire|
  campfire.on_success = true
  campfire.on_warning = true
  campfire.on_failure = true

  campfire.api_token = 'my_token'
  campfire.subdomain = 'my_subdomain'
  campfire.room_id   = 'the_room_id'
end

In order to use Campfire as a notifier you will need a Campfire account. Once you create a Campfire account for the notifier, you need to create a room and take note of its id (room_id) (https://.campfirenow.com/room/<room_id>), get your api authentication token from the "My info" page, and take note of your subdomain (https://.campfirenow.com/).

Long story short, this is the information you will need:

  • api authentication token
  • subdomain
  • room id

Prowl

notify_by Prowl do |prowl|
  prowl.on_success = true
  prowl.on_warning = true
  prowl.on_failure = true

  prowl.application = 'my_application'  # Example: Server Backup
  prowl.api_key     = 'my_api_key'
end

Prowl is an iOS push notification gateway. Backup can connect to Prowl and deliver success and/or failure notifications directly to your iOS device. All you need is a Prowl account. Go to the API keys tab after registration, generate a key and copy/paste it into your notifier configuration.

Hipchat

notify_by Hipchat do |hipchat|
  hipchat.on_success = true
  hipchat.on_warning = true
  hipchat.on_failure = true

  hipchat.success_color = 'green'
  hipchat.warning_color = 'yellow'
  hipchat.failure_color = 'red'

  hipchat.token = 'hipchat api token' # required
  hipchat.from = 'DB Backup' # required
  hipchat.rooms_notified = ['activity'] # required
end

Hipchat is a hosted private chat service. Backup can connect to Hipchat to post notices in room via the API. To get an API token, you must be logged in as an admin. Click the Group Admin tab at the top, then click API and then create a new token for backup. A "notification" key type is sufficient.

The Hipchat notifier can notify on multiple rooms that you specify by name. rooms_notified may be set using a single room name (hipchat.rooms_notified = 'my_room'), a comma-delimited list of names (hipchat.rooms_notified = 'my_room, another room'), or an Array of names (as shown above).

Please see the Hipchat API documents for a list of available colors.

Pushover

notify_by Pushover do |pushover|
  pushover.on_success = true
  pushover.on_warning = true
  pushover.on_failure = true

  pushover.user = 'USER_KEY' # required
  pushover.token = 'API_KEY' # required
  pushover.title = 'The message title' # optional
  pushover.device = 'The device identifier' # optional
  pushover.priority = '1' # optional
end

Pushover is a platform for sending and receiving push notifications to Android and iOS devices. Authentication requires the supply of two keys; an Application (API) token and a user token. Every connected device will require a device name which can then be used for targeting push notifications.

Messages sent through this notifier are restricted to 512 characters including the supplied title. Applications can send a maximum of 7,500 messages per month per application (API) key.

Please read the Pushover API documentation for further details of the configuration parameters. Registration is free, but you do need to purchase the device clients.

Default Configuration

If you are planning to set up a Mail notifier for multiple Backup processes, it'll become quite verbose and redundant, very quickly. Consider setting up some default configuration. For example, if in most cases you want to use the same "sender" to send email notifications, you could set up a default Mail configuration, like so:

Backup::Notifier::Mail.defaults do |mail|
  mail.from                 = 'sender@email.com'
  mail.to                   = 'receiver@email.com'
  mail.address              = 'smtp.gmail.com'
  mail.port                 = 587
  mail.domain               = 'your.host.name'
  mail.user_name            = 'sender@email.com'
  mail.password             = 'my_password'
  mail.authentication       = 'plain'
  mail.enable_starttls_auto = true
end

So now, every time you wish to setup Mail notifications for a Backup process, you only have to define the following inside the Backup::Model block:

notify_by Mail

Then you won't have to specify all the SMTP configuration, sender, receiver, credentials, etc. It will always use the defaults unless you explicitly overwrite them within the notify_by block.

For example, the on_success, on_warning and on_failure notifications are always true by default. To turn off on_success notifications, use:

notify_by Mail do |mail|
  mail.on_success = false
end

Notifier Failures

Notifiers are processed after all other procedures in the backup process, and are called in the order they are defined in your backup model. If a Notifier fails, this will cause Backup to consider the job as having failed - even if all other procedures succeeded.

In this case, if multiple Notifiers are configured to send on_success or on_warning notifications, those configured after the failed Notifier will not be called. However, when the backup job fails, all Notifiers configured to send on_failure notifications are called. If any Notifier fails while attempting to send a on_failure notification, the error that caused the failure will be logged and the next Notifier will be called.

What does this mean?

Say you have two Notifiers configured to send on_success and on_failure notifications. All backup procedures complete successfully, but the second Notifier fails. The first notifier will send a on_success notification, then it will send an on_failure notification. The second notifier in this case will actually be attempted twice. So, if the second notifier succeeds on the second attempt, you'll get a on_failure notification from it as well.

Say you only have one Notifier configured, and only setup to send on_failure notifications. If your backup job fails and that Notifier fails, you will never receive any notifications. This could happen if your backup job fails due to a network failure. It's a good idea to have at least one Notifier configured to send on_success notifications.

Add a custom footer
Add a custom sidebar

Clone this wiki locally