NAME

rgrowl -- Send and receive Growl notifications from remote machines.

SYNOPSIS

rgrowl [-hsw] [--amazon-access-key key] [--amazon-region region] [--amazon-secret-key key] [-a appname] [-d identifier] [-H host] [-i extension] [-I filepath] [--image filepath] [-m message] [-n name] [-P password] [-p priority] [--sqs-queue queuename] [-t] [title]

rgrowl --daemon [--amazon-access-key key] [--amazon-region region] [--amazon-secret-key key] [--poll-interval interval] [--sqs-queue queuename]

rgrowl --man

Options:

--amazon-access-key Your AWS Access Key ID.
--amazon-region     The AWS region in which to store the notifications.
--amazon-secret-key Your AWS Secret Key.
--appIcon,-a        The application to use for the icon.
--daemon            Run in receiving rather than sending mode.
--help,-h           Display a short help message.
--host,-H           The hostname or IP for a remote Growl notification.
--icon,-i           The filetype or extension to take the icon from.
--iconpath,-I       A file whose icon should be the notification icon.
--identifier,-d     An identifier to help coalesce notifications.
--image             An image to use as the icon for the notification.
--man               Display a man page for rgrowl.
--message,-m        The text of the notification.
--name,-n           The name of the app sending the notification.
--password,-P       The password to authenticate a remote notification.
--poll-interval     The time to sleep between polling in daemon mode.
--priority,-p       Set the urgency of the notification.
--sqs-queue         The name of the SQS queue used for storage.
--sticky,-s         Require the notification to be dismissed manually.
--title,-t          Here for compatibility with growlnotify.
--wait,-w           Ignored. Here for compatibility with growlnotify.

DESCRIPTION

Growl natively has the ability to receive and display notifications but it requires Growl to be reachable by the remote sender. On many networks your machine may be behind a firewall or NAT which makes it difficult to reach.

rgrowl uses Amazon SQS as a "mailbox" for Growl notifications. Any app wishing to send a growl notification simply runs rgrowl with the same arguments as Growl's growlnotify command line program. On the receiving machine, rgrowl runs as a daemon and polls the SQS mailbox for notifications and displays them as appropriate. As soon as the message is received, it is deleted from the mailbox.

To set rgrowl up, see the instructions in "INSTALLATION" below.

The following options are available:

--amazon-access-key

The Access Key ID for your Amazon Web Services account.

--amazon-region

The region where you wish to keep your SQS queue. By default, it's kept in us-east-1 but you may wish to change this to a region closer to you.

--amazon-secret-key

The Secret Key matching your Access Key ID above.

--appIcon, -a

Either the name of an application or the full path to the .app directory for that application. The icon for this application will be used as the icon for the notification or as part of the icon for the notification depending on the values of --icon, --iconpath, --image and the Growl display style used.

--daemon

Run rgrowl in the background collecting and triggering Growl notifications. You should never need to specify this manually, if you've installed rgrowl according to the instructions below it should be set up automatically for you.

--help, -h

Display a short summary of the available command line options.

--host, -H

The host to send the Growl notification to. Note, this is not required unless you've installed the rgrowl daemon in order to relay the notifications to another machine.

--icon, -i

Provide a file extension and the icon for the notification will be the icon for that file type.

--iconpath, -I

Provide a path to a file and the appropriate icon for that file will be used as the icon for the notification.

--identifier, -d

If several notifications are sent with the same identifier the notifications will be coalesced into one on display. Only some displays support coalescing.

--image

Use this to specify the image to be used as the icon for the notification.

--man

Display a man page for rgrowl.

--message, -m

The message portion of the notification.

--name, -n

Set the name of the application which is sending the notification.

--password, -P

Provide a password for notifications sent to remote hosts. Ignored unless --host is used.

--poll-interval

Set the amount of time (in seconds) to sleep between polling for new messages. The lower you make this, the more "instant" the notifications you feel. On the other hand, it will cost you more money in AWS fees.

--priority, -p

Set the priority of the notification. Valid values are:

Very Low

Moderate

Normal

High

Emergency

-2

-1

0

1

2

Not all display methods respect priority.

--sqs-queue

The name of the SQS queue in which to store the notifications while they're in transit.

--sticky, -s

Make the notification sticky, i.e. require user interaction to dismiss the notification.

--title, -t

Set the title of the notification. If this is not provided, the remaining non-option command line arguments are used as the title. If both this option and extra items are used, the extra arguments are concatenated onto this argument.

--wait, -w

Wait until the notification has been dismissed before returning. Due to the way rgrowl is constructed this is not possible so this argument is ignored.

INSTALLATION

Before installing rgrowl, you should sign up for Amazon Web Services. Then log into the AWS Console and create an SQS queue called "GrowlNotifications".

On all machines using rgrowl

1. Install rgrowl's dependencies

In addition to Getopt::Long and Pod::Usage, rgrowl also requires Amazon::SQS::Simple and JSON. If your chosen operating system does not already have a package for these modules you can install them using CPAN with the following two commands:

$

sudo perl -MCPAN install Amazon::SQS::Simple

$

sudo perl -MCPAN install JSON

2. Install rgrowl

Copy rgrowl to a directory in your path and make it executable. For example, to install it system-wide run the following:

$

sudo cp rgrowl /usr/bin/rgrowl

$

sudo chmod 555 /usr/bin/rgrowl

3. Configure rgrowl

Create a configuration file with the following contents:

amazon-access-key = 'AAAAAAAAAAAAAAAAAAAA'
amazon-secret-key = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
amazon-region = 'us-east-1'

Replace the values with the appropriate ones found in your Amazon Web Services Console. Any command line option is allowed (minus the -- prefix) but the above is the recommended minimum.

Install the configuration file in any one of the following locations (this is the order in which configuration files are searched for, later files override earlier ones).

/opt/local/etc/rgrowlrc

/usr/local/etc/rgrowlrc

/etc/rgrowlrc

$HOME/.rgrowlrc

On the machine displaying Growl notifications

On the machine where you want your Growl notifications to display, you need to do the following additional steps.

1. Install Growl

If you haven't done it already, install Growl.

2. Install growlnotify

If you are running a version of Growl earlier than version 1.3, growlnotify is available inside the DMG file you downloaded. For Growl 1.3 and later you need to download it separately from http://growl.info/extras.php#growlnotify.

3. Arrange for rgrowl to be run in daemon mode.

Run the following commands in a terminal:

$ launchctl submit -l com.mcdermottroe.rgrowl -- \
      /usr/bin/perl -T /usr/bin/rgrowl --daemon
$ launchctl start com.mcdermottroe.rgrowl

DIAGNOSTICS

The rgrowl utility exits 0 on success, and >0 if an error occurs.

ENVIRONMENT

The following environment variables affect the execution of rgrowl:

PATH

The PATH is used to search for growlnotify(1) and osascript(1). The former is required and the latter is desirable when running in daemon mode.

LICENSE

Copyright (c) 2012, Conor McDermottroe All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

-

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

-

Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

SEE ALSO

growlnotify(1)

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 160:

Expected text after =item, not a number

Around line 162:

Expected text after =item, not a number

Around line 164:

Expected text after =item, not a number