Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/conormcd/rgrowl

Send and receive Growl notifications from remote machines.
https://github.com/conormcd/rgrowl

Last synced: 2 days ago
JSON representation

Send and receive Growl notifications from remote machines.

Awesome Lists containing this project

README 

        
=head1 NAME



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



=head1 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.



=head1 DESCRIPTION



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



B uses L as a "mailbox" for Growl

notifications. Any app wishing to send a growl notification simply runs

B with the same arguments as Growl's L command line

program.  On the receiving machine, B 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 B up, see the instructions in L below.



The following options are available:



=over 21



=item B<--amazon-access-key>



The Access Key ID for your Amazon Web Services account.



=item B<--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.



=item B<--amazon-secret-key>



The Secret Key matching your Access Key ID above.



=item B<--appIcon>, B<-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 I as part of the icon for the notification depending on

the values of B<--icon>, B<--iconpath>, B<--image> and the Growl display style

used.



=item B<--daemon>



Run B in the background collecting and triggering Growl notifications.

You should never need to specify this manually, if you've installed B

according to the instructions below it should be set up automatically for you.



=item B<--help>, B<-h>



Display a short summary of the available command line options.



=item B<--host>, B<-H>



The host to send the Growl notification to. Note, this is not required unless

you've installed the B daemon in order to relay the notifications to

another machine.



=item B<--icon>, B<-i>



Provide a file extension and the icon for the notification will be the icon for

that file type.



=item B<--iconpath>, B<-I>



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

the icon for the notification.



=item B<--identifier>, B<-d>



If several notifications are sent with the same identifier the notifications

will be coalesced into one on display. Only some displays support coalescing.



=item B<--image>



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



=item B<--man>



Display a man page for B.



=item B<--message>, B<-m>



The message portion of the notification.



=item B<--name>, B<-n>



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



=item B<--password>, B<-P>



Provide a password for notifications sent to remote hosts. Ignored unless

B<--host> is used.



=item B<--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.



=item B<--priority>, B<-p>



Set the priority of the notification. Valid values are:



=over



=item Very Low



=item Moderate



=item Normal



=item High



=item Emergency



=item -2



=item -1



=item 0



=item 1



=item 2



=back



Not all display methods respect priority.



=item B<--sqs-queue>



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

transit.



=item B<--sticky>, B<-s>



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

notification.



=item B<--title>, B<-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.



=item B<--wait>, B<-w>



Wait until the notification has been dismissed before returning. Due to the way

B is constructed this is not possible so this argument is ignored.



=back



=head1 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". 



=head2 On all machines using rgrowl



=over



=item 1. Install rgrowl's dependencies



In addition to L and L, rgrowl also requires

L and L. 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:



=over 2



=item $



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



=item $



sudo perl -MCPAN install JSON



=back



=item 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:



=over 2



=item $



sudo cp rgrowl /usr/bin/rgrowl



=item $



sudo chmod 555 /usr/bin/rgrowl



=back



=item 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).



=over



=item /opt/local/etc/rgrowlrc



=item /usr/local/etc/rgrowlrc



=item /etc/rgrowlrc



=item $HOME/.rgrowlrc



=back



=back



=head2 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.



=over



=item 1. Install Growl



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



=item 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 L.



=item 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



=back



=head1 DIAGNOSTICS



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



=head1 ENVIRONMENT



The following environment variables affect the execution of B:



=over 6



=item PATH



The PATH is used to search for L and L. The

former is required and the latter is desirable when running in daemon mode. 



=back



=head1 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:



=over 2



=item -



Redistributions of source code must retain the above copyright notice, this

list of conditions and the following disclaimer.



=item -



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.



=back



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.



=cut



=head1 SEE ALSO



L