syslog2irc 0.13
Forward syslog messages to IRC
License: MIT
Requires Python: >=3.7
Keywords: irc,syslog

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


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

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

Changelog
=========


Version 0.13
------------

Released 2021-05-07

- Changed log level of message for failed IRC channel join due to bad
  key to "warning". This keeps it visible if one decides logging on
  level "info" is too noisy in production.

- Simplified implementation of ``format_message``. As it is suggested to
  be copied and adjusted by users, this change should make that easier.

- Corrected Weitersager version in ``Dockerfile``.


Version 0.12
------------

Released 2021-05-05

- Switched to using Python's logging mechanism directly, with different
  log levels. Removed function ``util.log``.

- Made the application's log level configurable.

- Introduced an internal queue to decouple syslog message reception from
  message formatting and posting to IRC.

- Added TCP support for syslog message receiving. Adjusted routes
  configuration format to support it.

- Added support for custom IRC commands to send after connecting
  (authentication, cloaking, flood protection, etc.) (idea and essential
  patch provided by Jonas Alexandersson).

- Prevent enabling of a joined IRC channel to receive messages if no
  ports are routed to it.

- Remove leading and trailing newlines from message text to prevent
  additional lines on IRC (patch provided by Jonas Alexandersson).

- Provided and documented an easier way to customize message formatting.


Version 0.11
------------

Released 2021-04-21

- Introduced configuration file. Removed the CLI arguments that have
  been replaced by it.

- Moved configuration of IRC channels to join and ports-to-channels
  routes to configuration file.

- Provided an actual ``syslog2irc`` command.

- Published the package to the Python Package Index to allow installing
  from there.

- Added support for IRC server password.

- Added support for a rate limit for the IRC connection, i.e. the
  maximum number of messages per second to send. This can prevent the
  bot from getting kicked (or even banned) from a channel because of
  flooding.

- Added ``Dockerfile``.

- Added command line option ``--version`` to show syslog2IRC's version.


Version 0.10
------------

Released 2021-04-20

- Removed support for unsupported Python versions 2.7, 3.3, 3.4, and
  3.5.

- Added support for Python 3.7, 3.8, and 3.9.

- Split the single module into several modules inside a namespace
  package and a start script. Refactored a lot.

- Added type hints.

- Expect channels in routing configuration to be in sets, not lists.

- A custom formatter for syslog messages can be specified.

- Made bot properly disconnect from IRC with a quit message on shutdown.

- Removed handler to request shutdown via IRC private message.

- Require blinker version 1.4.

- Require irc version 19.0.1.

- Require syslogmp version 0.4.


Version 0.9.1
-------------

Released 2015-09-09

- Exposed programmatic entry point to pass arguments from Python code
  rather than the command line.

- Introduced signal to indicate an approved message. Decoupled processor
  and announcer.

- Wrapped ``print`` calls in a slightly higher-level, timestamped
  logging function.

- Added and improved tests.

- Created manifest template to package all files relevant for
  distribution.


Version 0.9
-----------

Released 2015-09-08

- Adapted to version 0.2 of syslogmp.

- Spread tests to separate modules.

- Added support to connect to IRC servers via SSL (suggested by Jonas
  Alexandersson).


Version 0.8
-----------

Released 2015-08-10

- Dropped support for Python 3.2.

- The syslog message parser was moved into the new 'syslogmp' package.


Version 0.7
-----------

Released 2014-05-19


Version 0.6
-----------

Released 2014-05-15


Version 0.5
-----------

Released 2013-07-22


Version 0.2–0.4
---------------

unknown


Version 0.1
-----------

Released 2007-04-12