========== syslog2IRC

.. image:: https://raw.githubusercontent.com/homeworkprod/syslog2irc/main/assets/syslog2irc_logo.svg :alt: syslog2IRC logo :height: 80 :width: 310

Forward syslog messages to IRC

For a more generic forwarder to IRC, check out Weitersager <https://homework.nwsnet.de/releases/1cda/#weitersager>_.

Code Status

|badge_travis-ci_build| |badge_scrutinizer-ci_coverage| |badge_scrutinizer-ci_quality-score| |badge_code-climate_maintainability|

.. |badge_travis-ci_build| image:: https://travis-ci.org/homeworkprod/syslog2irc.svg?branch=main :alt: Build Status :target: https://travis-ci.org/homeworkprod/syslog2irc

.. |badge_scrutinizer-ci_coverage| image:: https://scrutinizer-ci.com/g/homeworkprod/syslog2irc/badges/coverage.png?b=main :alt: Scrutinizer Code Coverage :target: https://scrutinizer-ci.com/g/homeworkprod/syslog2irc/?branch=main

.. |badge_scrutinizer-ci_quality-score| image:: https://scrutinizer-ci.com/g/homeworkprod/syslog2irc/badges/quality-score.png?b=main :alt: Scrutinizer Code Quality :target: https://scrutinizer-ci.com/g/homeworkprod/syslog2irc/?branch=main

.. |badge_code-climate_maintainability| image:: https://api.codeclimate.com/v1/badges/7fc3553f7a7cf6502560/maintainability :alt: Code Climate :target: https://codeclimate.com/github/homeworkprod/syslog2irc

Requirements

• Python 3.7+
• Dependencies: blinker_, irc_, rtoml_, syslogmp_

.. _blinker: https://pythonhosted.org/blinker/ .. _irc: https://bitbucket.org/jaraco/irc .. _rtoml: https://github.com/samuelcolvin/rtoml .. _syslogmp: https://homework.nwsnet.de/releases/76d6/#syslogmp

Installation

syslog2IRC and its dependencies can be installed via pip_:

.. code:: sh

$ pip install syslog2irc

To update an installed copy of syslog2IRC to the most recent release:

.. code:: sh

$ pip install -U syslog2irc

.. _pip: http://www.pip-installer.org/

Configuration

syslog

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

.. _IANA: https://www.iana.org/

syslog2IRC

Configuration is done as a file in TOML_ format.

A simple configuration to route from the default syslog port, 514, to a single IRC channel looks like this:

.. code:: toml

[irc.server]
host = "irc.server.example"

[irc.bot]
nickname = "syslog"

[irc]
channels = [
  { name = "#syslog" },
]

[routes]
"514/udp" = [ '#syslog' ]

In a more complex setup, syslog messages could be received on multiple ports (514/UDP and 55514/TCP in this example), with those received on the first port being forwarded to two IRC channels, and those received on the latter port being forwarded exclusively to the second channel.

Here is a full example of an advanced configuration with all optional properties being specified:

.. code:: toml

log_level = "warning"        # optional

[irc.server]
host = "irc.server.example"  # optional
port = 6667                  # optional
ssl = false                  # optional
password = "t0ps3cr3t"       # optional
rate_limit = 0.5             # optional; limit of messages per second

[irc.bot]
nickname = "syslog"
realname = "syslog"          # optional

[irc]
commands = [                 # optional
  "MODE syslog +i",
]
channels = [
  { name = "#examplechannel1" },
  { name = "#examplechannel2", password = "zePassword" },
]

[routes]
# routing for syslog messages from the ports on which they are
# received to the IRC channels they should be announced on
"514/udp" = [ '#examplechannel1', '#examplechannel2' ]
"55514/tcp" = [ '#examplechannel2' ]

.. _TOML: https://toml.io/

IRC Dummy Mode

If no value for irc.server.host is set (the property is missing or commented out), syslog2IRC will not attempt to connect to an IRC server and start in IRC dummy mode.

In this mode, it will still receive syslog messages, but it will write them to STDOUT. This can be helpful during setup of syslog message reception.

Abort execution by pressing <Control-C>.

Usage

Start syslog2IRC with a configuration file:

.. code:: sh

$ syslog2irc config.toml

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

.. code:: sh

$ 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 and you have been using IRC dummy mode so far, specify an IRC server in the configuration file, then start as above:

.. code:: sh

$ syslog2irc config.toml

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

Custom Message Format

The application's entry point is prepared to accept a custom callable to format messages.

Arguably the easiest way to make use of this without fiddling inside of the installed package's sources:

• Copy the Python code from src/syslog2irc/formatting.py to a new file outside of the package path, e.g. syslog2irc-custom.py.

• Adjust the copy of the function format_message as desired.

• Import the entry point function into the new file, then call it while passing the adjusted formatter function to it:

  .. code:: python

  from syslog2irc.main import main
  
  if __name__ == '__main__':
      main(custom_format_message=format_message)
  

• Run the new file in the shell:

  .. code:: sh

  $ python syslog2irc-custom.py config.toml
  

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.

.. _RFC 3164: https://tools.ietf.org/html/rfc3164 .. _RFC 5424: https://tools.ietf.org/html/rfc5424

:Copyright: 2007-2021 Jochen Kupperschmidt <https://homework.nwsnet.de/>_ :License: MIT, see LICENSE for details.