ryansteffan/simply_syslog repository overview

⁠simply_syslog

A dead simple open source syslog server written in Python.

The server is intended to be used with docker to provide a syslog server that is easy to configure, deploy, and scale.

⁠How to Use:

⁠Table of Contents:

• simply_syslog⁠
• How to Use:⁠
  • Table of Contents:⁠
  • Features:⁠
  • Upcoming features:⁠
  • Quick Start Guide (Docker):⁠
  • Quick Start Guide (Bare-Metal):⁠
  • Config settings guide:⁠
    • Some setting details:⁠
  • Reporting Vulnerabilities:⁠

⁠Features:

• UDP syslog support
• Supports docker.
• Highly configurable
• Able to handle large numbers of requests

⁠Upcoming features:

• Support for TCP
• Support for encryption.

⁠Quick Start Guide (Docker):

This is the recommended method for setting up the server.

To Deploy a very simple configuration with the default values, this command can be used:

Pull the image:

docker pull ryansteffan/simply_syslog

And then run the container:

docker run -d --name simply_syslog --restart always -p 514:514/udp -v /var/lib/docker/volume/simply_syslog:/var/log/simply_syslog/ ryansteffan/simply_syslog

All other configuration of the server is done by passing environment variables to the container with the -e flag. Such as, -e DEBUG_MESSAGES=False, which would disable the debug logging for the server.

A full command with that example would look like:

docker run -d --name simply_syslog --restart always -p 514:514/udp -e DEBUG_MESSAGES=False -v /var/lib/docker/volume/simply_syslog:/var/log/simply_syslog/ ryansteffan/simply_syslog

For a full list of the settings that can be configured, refer to this part of the README⁠.

⁠Quick Start Guide (Bare-Metal):

While docker is the main focus of simply_syslog, bare-metal is also an option for deploying the server.

Do note though, in the current state the server does not ship with an installation script to make it use systemd or any init system. Making it run in the background will need to be setup by you.

To get started running on bare-metal:

1. Make sure that you have python3 installed on your server. The sever was built for python 3.12, though it may work older 3.x versions.

   :warning: Issues that arise from using any version of python older than 3.12 will not be addressed.:warning:

2. cd into the directory that you will store the git repo in.

3. Run git clone https://github.com/TheTurnnip/simply_syslog.git to clone the repo.

4. cd into the server directory.

5. To make changes to the configuration, you can use your preferred text editor. Refer to this part of the README⁠ for details on the configuration.

6. To run the server use python ./main.py on windows or on linux/mac python3 ./main.py

⁠Config settings guide:

When editing the config for the docker container, all of these settings can be edited as environment variables.

When editing the config on bare-metal you can edit the config file directly. It can be found at dir_you_copied_repo_to/simply_syslog/config/config.json

This is a quick reference guide to the configurations:

⁠Some setting details:

• The sever expects that the file it needs to log to is made already. Ensure that not only the directory specified not only exists, but has a file called syslog.log in it.
• When changing the BUFFER_LIFESPAN value, be careful. If it is set to high it can lead to the buffer holding syslog messages for a long time. This means they will not display in the file, and also it is dangerous in the event of power loss and can lead to loss of data. A good rule of thumb is to keep the buffer timeout as low as possible. I would not set it higher than 5 seconds max, unless there is some special case where it is needed.
• The BUFFER_LENGTH needs to be balanced, while a larger buffer will allow for more requests to be taken in before a disk write is done, this leads to the trade-off of having a longer disk write that needs to be done later. I would recommend not set values any higher than 256, unless there are lots of machines on the network, or you have a use case that demands it.

⁠Reporting Vulnerabilities:

If you find any vulnerabilities with this code please report the issue using the security section of the GitHub repo (https://github.com/TheTurnnip/simply_syslog⁠).