Notifiers

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                 = '[email protected]'
  mail.to                   = '[email protected]'
  mail.address              = 'smtp.gmail.com'
  mail.port                 = 587
  mail.domain               = 'your.host.name'
  mail.user_name            = '[email protected]'
  mail.password             = 'my_password'
  mail.authentication       = 'plain'
  mail.enable_starttls_auto = true
end

This will make [email protected] send an email to [email protected] 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.

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.

• To use Mail::Sendmail, use the following:

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

  mail.delivery_method      = :sendmail
  mail.from                 = '[email protected]'
  mail.to                   = '[email protected]'
 
  # 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.

• To use Mail::Exim, use the following:

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

  mail.delivery_method      = :exim
  mail.from                 = '[email protected]'
  mail.to                   = '[email protected]'

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

• To use Mail::FileDelivery, use the following:

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

  mail.delivery_method      = :file
  mail.from                 = '[email protected]'
  mail.to                   = '[email protected]'
  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 and should be an array
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.

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 targetting 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                 = '[email protected]'
  mail.to                   = '[email protected]'
  mail.address              = 'smtp.gmail.com'
  mail.port                 = 587
  mail.domain               = 'your.host.name'
  mail.user_name            = '[email protected]'
  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