Receive syslog messages via UDP and show them on IRC.
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
syslog2irc
tests
.gitignore
.travis.yml
AUTHORS.rst
CHANGES.rst
LICENSE
MANIFEST.in
README.rst
requirements.txt
setup.cfg
setup.py Support Python 3.5. Sep 26, 2015
start-syslog2irc.py
tox.ini Support Python 3.5. Sep 26, 2015

README.rst

syslog2IRC

Receive syslog messages via UDP and show them on IRC.

Requirements

Installation

The required packages can be installed via pip:

$ pip install -r requirements.txt

Tests

To run the tests:

$ python setup.py test

Configuration

Setup your syslog.conf or rsyslog.conf (commonly found in /etc) to send syslog messages to syslog2IRC on the default syslog port (514, UDP, as assigned by IANA):

*.*     @host-to-send-log-messages-to-and-this-script-runs-on

Or, when syslog2IRC listens on a non-default port (here: 11514):

*.*     @host-to-send-log-messages-to-and-this-script-runs-on:11514

To specify which IRC channels to join and forward syslog messages to, create Channel instances and reference them in the routes mapping.

A simple routing from the default syslog port, 514, to a single IRC channel without a password looks like this:

channel1 = Channel('#examplechannel1')

routes = {
    514: [channel1],
}

In a more complex setup, syslog messages could be received on two ports (514 and 55514), with those received on the first port being forwarded to two IRC channels, and those received on the letter port being forwarded exclusively to the second channel.

channel1 = Channel('#examplechannel1')
channel2 = Channel('#examplechannel2', password='zePassword')

routes = {
      514: [channel1, channel2],
    55514: [channel2],
}

For convenience, for example while testing, the bot can be configured to shut down if a certain text is sent to it as a private message. Just provide a callable that accepts nickmask and text as positional arguments and returns a boolean value.

def is_shutdown_requested(nickmask, text):
    """Determine if this is a valid shutdown request."""
    return text == 'shutdown!'

start_with_args(routes, shutdown_predicate=is_shutdown_requested)

Be aware that checking against nickmask and text is not very secure as they can be faked and guessed, respectively. You might not want to enable this in a production environment.

Usage

You might want to familiarize yourself with the available command line options first:

$ python start-syslog2irc.py -h

If no options are given, the IRC component will not be used. Instead, syslog messages will be written to STDOUT. This is helpful during setup of syslog message reception. Abort execution by pressing <Control-C>.

$ python start-syslog2irc.py

Send some messages to syslog2IRC using your system's syslog message sender tool (logger, in this example):

$ logger 'Hi there!'
$ logger -p kern.alert 'Whoa!'

Note that each message will appear twice on the console syslog2IRC was started because the handler itself will write it there anyway (so you have a log on what would be sent to IRC).

If receiving syslog messages works, connect to an IRC server:

$ python start-syslog2irc.py --irc-server irc.example.com

After a moment, you should see that syslog2IRC has connected to the server. The IRC bot should then enter the channel(s) you have configured (see Configuration).

To use another port on the IRC server than the default (6667), specify it like this (6669 in this case):

$ python start-syslog2irc.py --irc-server irc.example.com:6669

In order to shut down syslog2IRC, send a query message with the text "shutdown!" to the IRC bot. It should then quit, and syslog2IRC should exit.

Further Reading

For more information, see RFC 3164, "The BSD syslog Protocol".

Please note that there is RFC 5424, "The Syslog Protocol", which obsoletes RFC 3164. syslog2IRC, however, only implements the latter.

Copyright:2007-2015 Jochen Kupperschmidt
Date:09-Sep-2015
License:MIT, see LICENSE for details.
Version:0.9.2-dev