Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

https://github.com/homeworkprod/syslog2irc

Forward syslog messages to IRC
https://github.com/homeworkprod/syslog2irc

irc irc-bot python sysadmin syslog

Last synced: about 6 hours ago
JSON representation

Forward syslog messages to IRC

Awesome Lists containing this project

README 

        
==========

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



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 .



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

:License: MIT, see LICENSE for details.