mirror of
https://github.com/rsyslog/rsyslog.git
synced 2025-12-15 17:30:42 +01:00
doc: major restructure and content improvements
- Added "Getting Started" guide with modern examples and pipeline
integrations (e.g., Elasticsearch, Kafka).
- Rewrote community resources page:
* Added AI-based rsyslog assistant and GitHub Discussions as primary
support channels.
* Moved older resources to a new "Legacy Resources" section.
* Added note about Adiscon professional services.
- Reorganized configuration reference index with clearer structure,
modern examples, and compatibility note updates.
- Introduced a new "Documentation Style Guide" for consistent .rst
formatting and contributor guidance.
- Deleted outdated or unused content (old proposals, examples, and
legacy free_support page).
- Moved version compatibility notes to the historical section.
- Reworked main index page with a concise introduction, better
navigation, and updated community/sponsor references.
- Switched HTML theme to Furo and updated Sphinx requirements.
- Simplified and modernized footer with Apache License 2.0 reference.
This commit is contained in:
Rainer Gerhards
parent
572c6c0034
commit
3b0d6bfb2d
@ -1,3 +1,4 @@
|
||||
|
||||
# Need at least 1.5.1 due to some of the features we are using
|
||||
sphinx >=1.5.1
|
||||
furo
|
||||
|
||||
@ -1,37 +1,52 @@
|
||||
Community Resources
|
||||
===================
|
||||
|
||||
You can also browse the following online resources:
|
||||
The rsyslog project is supported by a vibrant community and official resources
|
||||
that help users learn, troubleshoot, and stay up to date.
|
||||
|
||||
- the `rsyslog wiki <http://wiki.rsyslog.com/>`_, a community resource
|
||||
which includes `rsyslog configuration
|
||||
examples <http://wiki.rsyslog.com/index.php/Configuration_Samples>`_
|
||||
- `rsyslog discussion forum - use this for technical
|
||||
support <http://kb.monitorware.com/rsyslog-f40.html>`_
|
||||
- `rsyslog video tutorials <http://www.rsyslog.com/Topic8.phtml>`_
|
||||
- `rsyslog FAQ <http://www.rsyslog.com/Topic3.phtml>`_
|
||||
- `syslog device configuration
|
||||
guide <http://www.monitorware.com/en/syslog-enabled-products/>`_
|
||||
(off-site)
|
||||
- `deutsches rsyslog
|
||||
forum <http://kb.monitorware.com/rsyslog-f49.html>`_ (forum in German
|
||||
language)
|
||||
Primary Resources
|
||||
-----------------
|
||||
|
||||
And don't forget about the `rsyslog mailing
|
||||
list <http://lists.adiscon.net/mailman/listinfo/rsyslog>`_. If you are
|
||||
interested in the "backstage", you may find
|
||||
`Rainer <https://rainer.gerhards.net/>`_'s
|
||||
`blog <https://rainer.gerhards.net/>`_ an interesting read (filter on
|
||||
syslog and rsyslog tags). Or meet `Rainer Gerhards at
|
||||
Facebook <https://www.facebook.com/rainer.gerhards.1/>`_.
|
||||
If you would like to use rsyslog source code inside your open source
|
||||
project, you can do that without any restriction as long as your license
|
||||
is GPLv3 compatible. If your license is incompatible to GPLv3, you may
|
||||
even be still permitted to use rsyslog source code. However, then you
|
||||
need to look at the way `rsyslog is licensed <licensing.html>`_.
|
||||
- `AI "rsyslog assistant" experiment <https://rsyslog.ai>`_
|
||||
An AI-powered assistant designed to help with configuration questions,
|
||||
troubleshooting, and learning rsyslog concepts.
|
||||
|
||||
Feedback is always welcome, but if you have a support question, please
|
||||
do not mail Rainer directly (`why not? <free_support.html>`_) - use the
|
||||
`rsyslog mailing
|
||||
list <http://lists.adiscon.net/mailman/listinfo/rsyslog>`_ or `github issue
|
||||
tracker <https://github.com/rsyslog/rsyslog/issues>`_ instead.
|
||||
- `GitHub Discussions <https://github.com/rsyslog/rsyslog/discussions>`_
|
||||
A community forum for questions, ideas, and feedback.
|
||||
|
||||
- `rsyslog mailing list <http://lists.adiscon.net/mailman/listinfo/rsyslog>`_
|
||||
A long-standing mailing list where the community exchanges knowledge and
|
||||
support.
|
||||
|
||||
- `Rainer Gerhards' blog <https://rainer.gerhards.net/>`_
|
||||
Insights and updates from the maintainer of rsyslog. Filter for *syslog*
|
||||
and *rsyslog* tags for relevant content.
|
||||
|
||||
Self-Help
|
||||
---------
|
||||
|
||||
For general support and troubleshooting, start with these resources:
|
||||
|
||||
- `AI "rsyslog assistant" <https://rsyslog.ai>`_
|
||||
- `GitHub Discussions <https://github.com/rsyslog/rsyslog/discussions>`_
|
||||
- `rsyslog mailing list <http://lists.adiscon.net/mailman/listinfo/rsyslog>`_
|
||||
- `GitHub issue tracker <https://github.com/rsyslog/rsyslog/issues>`_
|
||||
|
||||
Professional Support
|
||||
--------------------
|
||||
|
||||
For guaranteed response times, private consultations, or expert help, consider
|
||||
`Adiscon’s professional services <https://www.rsyslog.com/professional-services/>`_.
|
||||
Adiscon is the main sponsor of rsyslog, and using its services helps fund the
|
||||
continued development of the project.
|
||||
|
||||
Legacy Resources
|
||||
----------------
|
||||
|
||||
The following resources may still be helpful but are no longer actively updated.
|
||||
New users are encouraged to start with the **AI assistant** and **GitHub
|
||||
Discussions** listed above for the most current information.
|
||||
|
||||
- `rsyslog video tutorials <http://www.rsyslog.com/Topic8.phtml>`_
|
||||
These tutorials are slightly dated but still provide useful background on
|
||||
common rsyslog concepts and configurations.
|
||||
|
||||
@ -1,12 +0,0 @@
|
||||
Compatibility
|
||||
=============
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
|
||||
v8compatibility
|
||||
v7compatibility
|
||||
v6compatibility
|
||||
v5compatibility
|
||||
v4compatibility
|
||||
v3compatibility
|
||||
@ -310,11 +310,3 @@ By default, rulesets do **not** have their own queue. It must be
|
||||
activated via the
|
||||
:doc:`$RulesetCreateMainQueue <../configuration/ruleset/rsconf1_rulesetcreatemainqueue>`
|
||||
directive.
|
||||
|
||||
See Also
|
||||
--------
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
../historical/multi_ruleset_legacy_format_samples
|
||||
|
||||
|
||||
@ -229,7 +229,8 @@ suppress_warnings = ['epub.unknown_project_files']
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
html_theme = 'default'
|
||||
html_theme = 'furo'
|
||||
#html_theme = 'default'
|
||||
#html_theme = 'basic'
|
||||
#html_style = 'rsyslog.css'
|
||||
|
||||
|
||||
@ -1,27 +1,36 @@
|
||||
Configuration
|
||||
=============
|
||||
|
||||
**Rsyslog Configuration Reference Manual Introduction**
|
||||
This section is the **reference manual for configuring rsyslog**. It
|
||||
covers all major configuration concepts, modules, and directives needed
|
||||
to build robust logging infrastructures — from simple setups to complex
|
||||
log processing pipelines.
|
||||
|
||||
This document serves as a detailed guide to rsyslog configuration, offering extensive information on the setup and management of system logging using
|
||||
`rsyslog <https://www.rsyslog.com>`_
|
||||
It covers various aspects of rsyslog configuration, including constructs, statements, and key concepts, designed to assist users in customizing their logging infrastructure according to specific needs.
|
||||
rsyslog’s primary configuration file is located at:
|
||||
``/etc/rsyslog.conf``
|
||||
|
||||
The primary configuration file for rsyslog, located at `/etc/rsyslog.conf`, acts as the central point for establishing logging rules. This file is used to define input modules, filters, actions, and global directives, facilitating the processes of log collection, filtering, routing, and formatting.
|
||||
Additional configuration snippets are commonly placed in:
|
||||
``/etc/rsyslog.d/*.conf``
|
||||
|
||||
Please note that this documentation is currently in the process of being refined to improve its clarity, structure, and accessibility. We value your patience and understanding during this phase and are committed to delivering a comprehensive and easy-to-navigate guide to rsyslog.
|
||||
Within these files, you define:
|
||||
- **Input modules** (where logs come from)
|
||||
- **Filters and parsers** (how logs are processed)
|
||||
- **Actions** (where logs are sent)
|
||||
- **Global directives** (overall behavior and performance tuning)
|
||||
|
||||
For further exploration of rsyslog's configuration intricacies, please refer to the links provided below. This manual is designed to be a valuable resource for both experienced system administrators and those new to the field, aiming to fully leverage the capabilities of rsyslog.
|
||||
|
||||
Note that **configurations can be built interactively** via the online
|
||||
`rsyslog configuration builder <http://www.rsyslog.com/rsyslog-configuration-builder/>`_ tool.
|
||||
The topics listed below provide a complete guide to rsyslog
|
||||
configuration.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
conf_formats
|
||||
converting_to_new_format
|
||||
sysklogd_format
|
||||
modules/idx_output
|
||||
modules/idx_input
|
||||
modules/idx_parser
|
||||
modules/idx_messagemod
|
||||
modules/idx_stringgen
|
||||
modules/idx_library
|
||||
|
||||
basic_structure
|
||||
templates
|
||||
properties
|
||||
@ -44,20 +53,25 @@ Note that **configurations can be built interactively** via the online
|
||||
dyn_stats
|
||||
lookup_tables
|
||||
percentile_stats
|
||||
converting_to_new_format
|
||||
conf_formats
|
||||
sysklogd_format
|
||||
|
||||
`Configuration file examples can be found in the rsyslog
|
||||
wiki <http://wiki.rsyslog.com/index.php/Configuration_Samples>`_. Also
|
||||
keep the `rsyslog config
|
||||
snippets <http://www.rsyslog.com/config-snippets/>`_ on your mind. These
|
||||
are ready-to-use real building blocks for rsyslog configuration.
|
||||
Additional Resources
|
||||
--------------------
|
||||
|
||||
There is also one sample file provided together with the documentation
|
||||
set. If you do not like to read, be sure to have at least a quick look
|
||||
at :download:`rsyslog-example.conf <rsyslog-example.conf>`.
|
||||
- **Config snippets:** See `rsyslog config snippets
|
||||
<http://www.rsyslog.com/config-snippets/>`_ for ready-to-use building
|
||||
blocks.
|
||||
|
||||
While rsyslogd contains enhancements over standard syslogd, efforts have
|
||||
been made to keep the configuration file as compatible as possible.
|
||||
While, for obvious reasons, :doc:`enhanced features <../features>` require
|
||||
a different config file syntax, rsyslogd should be able to work with a
|
||||
standard syslog.conf file. This is especially useful while you are
|
||||
migrating from syslogd to rsyslogd.
|
||||
- **Example configuration:** Download a sample configuration file:
|
||||
:download:`rsyslog-example.conf <rsyslog-example.conf>`.
|
||||
|
||||
Compatibility Note
|
||||
------------------
|
||||
|
||||
rsyslog retains partial configuration compatibility with traditional
|
||||
BSD-style syslogd, which can be helpful when migrating from older
|
||||
implementations (e.g., on Solaris or AIX). On modern Linux systems,
|
||||
native rsyslog configuration formats (especially RainerScript) are
|
||||
recommended and provide access to all advanced features.
|
||||
|
||||
@ -24,10 +24,4 @@ There exist different classes of loadable modules:
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
idx_output
|
||||
idx_input
|
||||
idx_parser
|
||||
idx_messagemod
|
||||
idx_stringgen
|
||||
idx_library
|
||||
workflow
|
||||
|
||||
126
doc/source/development/doc_style_guide.rst
Normal file
126
doc/source/development/doc_style_guide.rst
Normal file
@ -0,0 +1,126 @@
|
||||
Documentation Style Guide
|
||||
=========================
|
||||
|
||||
This guide defines the standards for writing and maintaining rsyslog
|
||||
documentation. It ensures a consistent, professional style across all
|
||||
`.rst` files and helps contributors produce high-quality documentation.
|
||||
|
||||
General Principles
|
||||
------------------
|
||||
|
||||
- **Audience:** Primarily system administrators and developers. Content
|
||||
should also remain accessible to intermediate users.
|
||||
- **Tone:** Professional, clear, and concise. Avoid personal references
|
||||
or conversational language.
|
||||
- **Focus:** Prioritize actionable guidance (e.g., how to configure,
|
||||
troubleshoot, or understand rsyslog).
|
||||
- **Language:** Use plain English. Avoid jargon and colloquialisms.
|
||||
- **Consistency:** Every page should follow the same structure,
|
||||
terminology, and heading style.
|
||||
|
||||
File Structure and TOC
|
||||
----------------------
|
||||
|
||||
- **Master TOC:** The `index.rst` file is the single entry point. Avoid
|
||||
using filesystem order.
|
||||
- **Preferred Topic Order:**
|
||||
|
||||
1. Introduction / Quick Start
|
||||
2. Configuration Basics
|
||||
3. Modules & Advanced Topics
|
||||
4. Troubleshooting
|
||||
5. Reference & API
|
||||
6. Community & Support
|
||||
7. Legacy Resources
|
||||
|
||||
- Use explicit ordering in `.. toctree::` (avoid `:glob:`).
|
||||
|
||||
Headings
|
||||
--------
|
||||
|
||||
Use underline-only adornments (no overlines). Assign a character per
|
||||
level:
|
||||
|
||||
- `=` Level 1 (document title)
|
||||
- `-` Level 2
|
||||
- `~` Level 3
|
||||
- `^` Level 4
|
||||
- `"` Level 5
|
||||
- `+` Level 6
|
||||
|
||||
Keep titles concise (≤ 60 characters).
|
||||
|
||||
Text Formatting
|
||||
---------------
|
||||
|
||||
- **Line Length:** Wrap lines at **80 characters**.
|
||||
- **Code Blocks:** Use `::` or explicit code blocks (e.g.,
|
||||
`.. code-block:: bash`).
|
||||
- **Inline Code:** Use double backticks, e.g., ``rsyslog.conf``.
|
||||
- **Links:** Use inline links:
|
||||
`rsyslog mailing list <http://lists.adiscon.net/mailman/listinfo/rsyslog>`_ .
|
||||
- **Bold vs. Italic:**
|
||||
- **Bold:** For UI elements or emphasized terms.
|
||||
- *Italic:* For alternative terms or emphasis.
|
||||
|
||||
Cross-Referencing
|
||||
-----------------
|
||||
|
||||
- Use `:ref:` for internal cross-links, e.g.,
|
||||
``See :ref:`troubleshooting`.``.
|
||||
- Use consistent anchors, e.g.,
|
||||
``.. _troubleshooting:``.
|
||||
|
||||
Sections
|
||||
--------
|
||||
|
||||
**Introduction/Overview**
|
||||
- Describe what the feature/module is and why it is needed.
|
||||
- Include minimal examples.
|
||||
|
||||
**Configuration**
|
||||
|
||||
- Use rainerscript syntax for modern examples.
|
||||
- Comment key parameters.
|
||||
|
||||
**Support & Community**
|
||||
|
||||
- Recommend modern resources first: AI assistant, GitHub Discussions,
|
||||
mailing list.
|
||||
- Move outdated resources to *Legacy Resources*.
|
||||
|
||||
|
||||
Legacy Content
|
||||
--------------
|
||||
|
||||
- Archive outdated guides and tutorials in `legacy/`.
|
||||
- Use:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. note::
|
||||
This content is archived and may be outdated.
|
||||
|
||||
Licensing & Legal
|
||||
-----------------
|
||||
|
||||
- Keep licensing information in `licensing.rst`.
|
||||
- Use:
|
||||
``For license details, see :doc:`licensing`.``
|
||||
|
||||
Examples and Code
|
||||
-----------------
|
||||
|
||||
- Provide minimal, complete examples.
|
||||
- Always specify language:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo systemctl restart rsyslog
|
||||
|
||||
Maintenance
|
||||
-----------
|
||||
|
||||
- Review docs at every release for outdated content.
|
||||
- Check for deprecated parameters and move them to Legacy.
|
||||
- Run `make linkcheck` to verify links.
|
||||
@ -1,7 +0,0 @@
|
||||
Example Use Cases
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
high_performance
|
||||
@ -1,56 +0,0 @@
|
||||
Free Services for Rsyslog
|
||||
=========================
|
||||
|
||||
*A personal word from Rainer, the lead developer of rsyslog:*
|
||||
|
||||
**The rsyslog community provides ample free support resources. Please
|
||||
see our** `troubleshooting guide <troubleshooting/index.html>`_ **to get started.**
|
||||
|
||||
Every now and then I receive private mail with support questions. I
|
||||
appreciate any feedback, but I must limit my resources so that I can
|
||||
help drive a great logging system forward.
|
||||
|
||||
To do so, I have decided not to reply to unsolicited support emails, at
|
||||
least not with a solution (but rather a link to this page ;)). I hope
|
||||
this does not offend you. The reason is quite simple: If I do personal
|
||||
support, you gain some advantage without contributing something back.
|
||||
Think about it: if you ask your question on the public forum or mailing
|
||||
list, others with the same problem can help you and, most importantly, even
|
||||
years later find your post (and the answer) and get the problem solved.
|
||||
So by solving your issue in public, you help create a great community
|
||||
resource and also help your fellow users find solutions quicker. In
|
||||
the long term, this also contributes to improved code because the more
|
||||
questions users can find solutions to themselves, the fewer I need to
|
||||
look at.
|
||||
|
||||
But it becomes even better: the rsyslog community is much broader than
|
||||
Rainer ;) - there are other helpful members hanging around the public
|
||||
places. They often answer questions, so that I do not need to look at
|
||||
them (btw, once again a big "thank you", folks!). And, more important,
|
||||
those folks have a different background than me. So they often either know
|
||||
better how to solve your problem (e.g. because it is distro-specific) or
|
||||
they know how to better phrase it (after all, I like abstract terms and
|
||||
concepts ;)). So you do yourself a favor if you use the public places.
|
||||
|
||||
An excellent place to go to is the `rsyslog
|
||||
forum <http://kb.monitorware.com/rsyslog-f40.html>`_ inside the
|
||||
knowledge base (which in itself is a great place to visit!). For those
|
||||
used to mailing lists, the `rsyslog mailing
|
||||
list <http://lists.adiscon.net/mailman/listinfo/rsyslog>`_ also offers
|
||||
excellent advise.
|
||||
|
||||
**Don't like to post your question in a public place?** Well, then you
|
||||
should consider purchasing `rsyslog professional
|
||||
support <http://www.rsyslog.com/professional-services/>`_. The fees are very low and help
|
||||
fund the project. If you use rsyslog seriously inside a corporate
|
||||
environment, there is no excuse for not getting one of the support
|
||||
packages ;)
|
||||
|
||||
Of course, things are different when I ask you to mail me privately.
|
||||
I'll usually do that when I think it makes sense, for example when we
|
||||
exchange debug logs.
|
||||
|
||||
I hope you now understand the free support options and the reasoning for
|
||||
them. I hope I haven't offended you with my words - this is not my
|
||||
intention. I just needed to make clear why there are some limits on my
|
||||
responsiveness. Happy logging!
|
||||
117
doc/source/getting_started.rst
Normal file
117
doc/source/getting_started.rst
Normal file
@ -0,0 +1,117 @@
|
||||
Getting Started with rsyslog
|
||||
----------------------------
|
||||
|
||||
rsyslog is a modern, high-performance logging framework that extends
|
||||
traditional syslog functionality. It supports advanced features such as
|
||||
structured logging, high-throughput message processing, and integration
|
||||
with modern log pipelines (e.g., Elasticsearch, Kafka, cloud services).
|
||||
rsyslog is actively maintained and widely used as the default system
|
||||
logger on many Linux distributions.
|
||||
|
||||
Installation
|
||||
~~~~~~~~~~~~
|
||||
|
||||
### On Debian/Ubuntu
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo apt update
|
||||
sudo apt install rsyslog rsyslog-doc
|
||||
|
||||
### On RHEL/CentOS
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo yum install rsyslog rsyslog-doc
|
||||
|
||||
After installation, enable and start rsyslog:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo systemctl enable rsyslog
|
||||
sudo systemctl start rsyslog
|
||||
|
||||
Validating the Setup
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To verify your installation and configuration, run:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
rsyslogd -N1
|
||||
|
||||
This command checks configuration syntax without starting the daemon.
|
||||
|
||||
Basic Configuration
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The primary configuration file is:
|
||||
|
||||
``/etc/rsyslog.conf``
|
||||
|
||||
Additional configuration snippets are placed in:
|
||||
|
||||
``/etc/rsyslog.d/*.conf``
|
||||
|
||||
Minimal Example
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
A simple configuration that logs all messages to `/var/log/syslog`:
|
||||
|
||||
.. code-block:: rsyslog
|
||||
|
||||
module(load="imuxsock") # Unix socket for local system logging
|
||||
module(load="imklog") # Kernel logging support
|
||||
|
||||
*.* /var/log/syslog
|
||||
|
||||
Apply changes by restarting rsyslog:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo systemctl restart rsyslog
|
||||
|
||||
First Advanced Step: Forwarding Logs
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
rsyslog can forward logs to remote servers using TCP or TLS:
|
||||
|
||||
.. code-block:: rsyslog
|
||||
|
||||
action(
|
||||
type="omfwd"
|
||||
protocol="tcp"
|
||||
target="logs.example.com"
|
||||
port="514"
|
||||
)
|
||||
|
||||
This configuration forwards all log messages to `logs.example.com`.
|
||||
|
||||
Modern Pipeline Integration
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
rsyslog supports many modern systems and formats, including:
|
||||
|
||||
- Elasticsearch and OpenSearch via the `omelasticsearch` module
|
||||
- Kafka and other message brokers
|
||||
- Structured logging with JSON templates
|
||||
|
||||
For example, to send logs to Elasticsearch:
|
||||
|
||||
.. code-block:: rsyslog
|
||||
|
||||
module(load="omelasticsearch")
|
||||
|
||||
action(
|
||||
type="omelasticsearch"
|
||||
server="http://localhost:9200"
|
||||
searchIndex="rsyslog"
|
||||
)
|
||||
|
||||
Next Steps
|
||||
~---------
|
||||
|
||||
- Explore the :doc:`configuration/index` section for advanced settings
|
||||
and features.
|
||||
- Review :doc:`tutorials/index` for step-by-step guides.
|
||||
- For quick answers, try the `AI rsyslog assistant <https://rsyslog.ai>`_.
|
||||
@ -5,9 +5,15 @@ which are still of interest or may be useful in some more exotic
|
||||
environments.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:maxdepth: 1
|
||||
|
||||
php_syslog_ng
|
||||
stunnel
|
||||
multi_ruleset_legacy_format_samples
|
||||
module_devel
|
||||
high_performance
|
||||
v8compatibility
|
||||
v7compatibility
|
||||
v6compatibility
|
||||
v5compatibility
|
||||
v4compatibility
|
||||
v3compatibility
|
||||
|
||||
@ -1,277 +0,0 @@
|
||||
SSL Encrypting Syslog with Stunnel
|
||||
==================================
|
||||
|
||||
*Written by* `Rainer Gerhards <https://rainer.gerhards.net/>`_ *(2005-07-22)*
|
||||
|
||||
**HISTORICAL DOCUMENT**
|
||||
|
||||
**Note: this is an outdated HISTORICAL document.** A much better description on
|
||||
`securing syslog with TLS <http://www.rsyslog.com/doc/master/tutorials/tls_cert_summary.html>`_
|
||||
is available.
|
||||
|
||||
Abstract
|
||||
--------
|
||||
|
||||
**In this paper, I describe how to encrypt**
|
||||
`syslog <http://www.monitorware.com/en/topics/syslog/>`_ **messages on the
|
||||
network.** Encryption is vital to keep the confidential content of
|
||||
syslog messages secure. I describe the overall approach and provide a
|
||||
HOWTO with the help of `rsyslogd <http://www.rsyslog.com>`_ and
|
||||
`stunnel <http://www.stunnel.org>`_.*
|
||||
|
||||
Please note that starting with rsyslog 3.19.0, `rsyslog provides native
|
||||
TLS/SSL encryption <rsyslog_tls.html>`_ without the need of stunnel. I
|
||||
strongly recommend to use that feature instead of stunnel. The stunnel
|
||||
documentation here is mostly provided for backwards compatibility. New
|
||||
deployments are advised to use native TLS mode.\ **
|
||||
|
||||
Background
|
||||
----------
|
||||
|
||||
**Syslog is a clear-text protocol. That means anyone with a sniffer can
|
||||
have a peek at your data.** In some environments, this is no problem at
|
||||
all. In others, it is a huge setback, probably even preventing
|
||||
deployment of syslog solutions. Thankfully, there is an easy way to
|
||||
encrypt syslog communication. I will describe one approach in this
|
||||
paper.
|
||||
|
||||
The most straightforward solution would be that the syslogd itself
|
||||
encrypts messages. Unfortunately, encryption is only standardized in
|
||||
`RFC 3195 <http://www.monitorware.com/Common/en/glossary/rfc3195.php>`_.
|
||||
But there is currently no syslogd that implements RFC 3195's encryption
|
||||
features, so this route leads to nothing. Another approach would be to
|
||||
use vendor- or project-specific syslog extensions. There are a few
|
||||
around, but the problem here is that they have compatibility issues.
|
||||
However, there is one surprisingly easy and interoperable solution:
|
||||
though not standardized, many vendors and projects implement plain tcp
|
||||
syslog. In a nutshell, plain tcp syslog is a mode where standard syslog
|
||||
messages are transmitted via tcp and records are separated by newline
|
||||
characters. This mode is supported by all major syslogd's (both on
|
||||
Linux/Unix and Windows) as well as log sources (for example,
|
||||
`EventReporter <http://www.eventreporter.com/en/>`_ for Windows Event
|
||||
Log forwarding). Plain tcp syslog offers reliability, but it does not
|
||||
offer encryption in itself. However, since it operates on a tcp stream,
|
||||
it is now easy to add encryption. There are various ways to do that. In
|
||||
this paper, I will describe how it is done with stunnel (an other
|
||||
alternative would be `IPsec <https://en.wikipedia.org/wiki/IPsec>`_, for
|
||||
example).
|
||||
|
||||
Stunnel is open source and it is available both for Unix/Linux and
|
||||
Windows. It provides a way to use ssl communication for any non-ssl
|
||||
aware client and server - in this case, our syslogd.
|
||||
|
||||
Stunnel works much like a wrapper. Both on the client and on the server
|
||||
machine, tunnel portals are created. The non-ssl aware client and server
|
||||
software is configured to not directly talk to the remote partner, but
|
||||
to the local (s)tunnel portal instead. Stunnel, in turn, takes the data
|
||||
received from the client, encrypts it via ssl, sends it to the remote
|
||||
tunnel portal and that remote portal sends it to the recipient process
|
||||
on the remote machine. The transfer to the portals is done via
|
||||
unencrypted communication. As such, it is vital that the portal and the
|
||||
respective program that is talking to it are on the same machine,
|
||||
otherwise data would travel partly unencrypted. Tunneling, as done by
|
||||
stunnel, requires connection oriented communication. This is why you
|
||||
need to use tcp-based syslog. As a side-note, you can also encrypt a
|
||||
plain-text RFC 3195 session via stunnel, though this definitely is not
|
||||
what the protocol designers had on their mind ;)
|
||||
|
||||
In the rest of this document, I assume that you use rsyslog on both the
|
||||
client and the server. For the samples, I use
|
||||
`Debian <https://www.debian.org/>`_. Interestingly, there are some
|
||||
annoying differences between stunnel implementations. For example, on
|
||||
Debian a comment line starts with a semicolon (';'). On `Red
|
||||
Hat <https://www.redhat.com/en>`_, it starts with a hash sign ('#'). So you
|
||||
need to watch out for subtle issues when setting up your system.
|
||||
|
||||
Overall System Setup
|
||||
--------------------
|
||||
|
||||
In this paper, I assume two machines, one named "client" and the other
|
||||
named "server". It is obvious that, in practice, you will probably have
|
||||
multiple clients but only one server. Syslog traffic shall be
|
||||
transmitted via stunnel over the network. Port 60514 is to be used for
|
||||
that purpose. The machines are set up as follows:
|
||||
|
||||
**Client**
|
||||
|
||||
- rsyslog forwards message to stunnel local portal at port 61514
|
||||
- local stunnel forwards data via the network to port 60514 to its
|
||||
remote peer
|
||||
|
||||
**Server**
|
||||
|
||||
- stunnel listens on port 60514 to connections from its client peers
|
||||
- all connections are forwarded to the locally-running rsyslog
|
||||
listening at port 61514
|
||||
|
||||
Setting up the system
|
||||
---------------------
|
||||
|
||||
For Debian, you need the "stunnel4" package. The "stunnel" package is
|
||||
the older 3.x release, which will not support the configuration I
|
||||
describe below. Other distributions might have other names. For example,
|
||||
on Red Hat it is just "stunnel". Make sure that you install the
|
||||
appropriate package on both the client and the server. It is also a good
|
||||
idea to check if there are updates for either stunnel or openssl (which
|
||||
stunnel uses) - there are often security fixes available and often the
|
||||
latest fixes are not included in the default package.
|
||||
|
||||
In my sample setup, I use only the bare minimum of options. For example,
|
||||
I do not make the server check client certificates. Also, I do not talk
|
||||
much about certificates at all. If you intend to really secure your
|
||||
system, you should probably learn about certificates and how to manage
|
||||
and deploy them. This is beyond the scope of this paper. For additional
|
||||
information,
|
||||
`http://www.stunnel.org/faq/certs.html <http://www.stunnel.org/faq/certs.html>`_
|
||||
is a good starting point.
|
||||
|
||||
You also need to install rsyslogd on both machines. Do this before
|
||||
starting with the configuration. You should also familiarize yourself
|
||||
with its configuration file syntax, so that you know which actions you
|
||||
can trigger with it. Rsyslogd can work as a drop-in replacement for
|
||||
stock `sysklogd <http://www.infodrom.org/projects/sysklogd/>`_. So if
|
||||
you know the standard syslog.conf syntax, you do not need to learn any
|
||||
more to follow this paper.
|
||||
|
||||
Server Setup
|
||||
~~~~~~~~~~~~
|
||||
|
||||
At the server, you need to have a digital certificate. That certificate
|
||||
enables SSL operation, as it provides the necessary crypto keys being
|
||||
used to secure the connection. Many versions of stunnel come with a
|
||||
default certificate, often found in /etc/stunnel/stunnel.pem. If you
|
||||
have it, it is good for testing only. If you use it in production, it is
|
||||
very easy to break into your secure channel as everybody is able to get
|
||||
hold of your private key. I didn't find an stunnel.pem on my Debian
|
||||
machine. I guess the Debian folks removed it because of its insecurity.
|
||||
|
||||
You can create your own certificate with a simple openssl tool - you
|
||||
need to do it if you have none and I highly recommend to create one in
|
||||
any case. To create it, cd to /etc/stunnel and type:
|
||||
|
||||
``openssl req -new -x509 -days 3650 -nodes -out stunnel.pem -keyout stunnel.pem``
|
||||
|
||||
That command will ask you a number of questions. Provide some answer for
|
||||
them. If you are unsure, read
|
||||
`http://www.stunnel.org/faq/certs.html <http://www.stunnel.org/faq/certs.html>`_.
|
||||
After the command has finished, you should have a usable stunnel.pem in
|
||||
your working directory.
|
||||
|
||||
Next is to create a configuration file for stunnel. It will direct
|
||||
stunnel what to do. You can use the following basic file:
|
||||
|
||||
::
|
||||
|
||||
; Certificate/key is needed in server modecert = /etc/stunnel/stunnel.pem; Some debugging stuff useful for troubleshootingdebug = 7foreground=yes
|
||||
|
||||
[ssyslog]
|
||||
accept = 60514
|
||||
connect = 61514
|
||||
|
||||
Save this file to e.g. /etc/stunnel/syslog-server.conf. Please note that
|
||||
the settings in *italics* are for debugging only. They run stunnel with
|
||||
a lot of debug information in the foreground. This is very valuable
|
||||
while you setup the system - and very useless once everything works
|
||||
well. So be sure to remove these lines when going to production.
|
||||
|
||||
Finally, you need to start the stunnel daemon. Under Debian, this is
|
||||
done via "stunnel /etc/stunnel/syslog.server.conf". If you have enabled
|
||||
the debug settings, you will immediately see a lot of nice messages.
|
||||
|
||||
Now you have stunnel running, but it obviously unable to talk to rsyslog
|
||||
- because it is not yet running. If not already done, configure it so
|
||||
that it does everything you want. If in doubt, you can simply copy
|
||||
/etc/syslog.conf to /etc/rsyslog.conf and you probably have what you
|
||||
want. The really important thing in rsyslogd configuration is that you
|
||||
must make it listen to tcp port 61514 (remember: this is where stunnel
|
||||
send the messages to). Thankfully, this is easy to achieve: just add "-t
|
||||
61514" to the rsyslogd startup options in your system startup script.
|
||||
After done so, start (or restart) rsyslogd.
|
||||
|
||||
The server should now be fully operational.
|
||||
|
||||
Client Setup
|
||||
~~~~~~~~~~~~
|
||||
|
||||
The client setup is simpler. Most importantly, you do not need a
|
||||
certificate (of course, you can use one if you would like to
|
||||
authenticate the client, but this is beyond the scope of this paper). So
|
||||
the basic thing you need to do is create the stunnel configuration file.
|
||||
|
||||
::
|
||||
|
||||
; Some debugging stuff useful for troubleshootingdebug = 7foreground=yes
|
||||
|
||||
client=yes
|
||||
|
||||
[ssyslog]
|
||||
accept = 127.0.0.1:61514
|
||||
connect = 192.0.2.1:60514
|
||||
|
||||
Again, the text in *italics* is for debugging purposes only. I suggest
|
||||
you leave it in during your initial testing and then remove it. The most
|
||||
important difference to the server configuration outlined above is the
|
||||
"client=yes" directive. It is what makes this stunnel behave like a
|
||||
client. The accept directive binds stunnel only to the local host, so
|
||||
that it is protected from receiving messages from the network (somebody
|
||||
might fake to be the local sender). The address "192.0.2.1" is the
|
||||
address of the server machine. You must change it to match your
|
||||
configuration. Save this file to /etc/stunnel/syslog-client.conf.
|
||||
|
||||
Then, start stunnel via "stunnel4 /etc/stunnel/syslog-client.conf". Now
|
||||
you should see some startup messages. If no errors appear, you have a
|
||||
running client stunnel instance.
|
||||
|
||||
Finally, you need to tell rsyslogd to send data to the remote host. In
|
||||
stock syslogd, you do this via the "@host" forwarding directive. The
|
||||
same works with rsyslog, but it supports extensions to use tcp. Add the
|
||||
following line to your /etc/rsyslog.conf:
|
||||
|
||||
::
|
||||
|
||||
*.* @@127.0.0.1:61514
|
||||
|
||||
|
||||
|
||||
Please note the double at-sign (@@). This is no typo. It tells rsyslog
|
||||
to use tcp instead of udp delivery. In this sample, all messages are
|
||||
forwarded to the remote host. Obviously, you may want to limit this via
|
||||
the usual rsyslog.conf settings (if in doubt, use man rsyslog.con).
|
||||
|
||||
You do not need to add any special startup settings to rsyslog on the
|
||||
client. Start or restart rsyslog so that the new configuration setting
|
||||
takes place.
|
||||
|
||||
Done
|
||||
~~~~
|
||||
|
||||
After following these steps, you should have a working secure syslog
|
||||
forwarding system. To verify, you can type "logger test" or a similar
|
||||
smart command on the client. It should show up in the respective server
|
||||
log file. If you dig out you sniffer, you should see that the traffic on
|
||||
the wire is actually protected. In the configuration use above, the two
|
||||
stunnel endpoints should be quite chatty, so that you can follow the
|
||||
action going on on your system.
|
||||
|
||||
If you have only basic security needs, you can probably just remove the
|
||||
debug settings and take the rest of the configuration to production. If
|
||||
you are security-sensitive, you should have a look at the various stunnel
|
||||
settings that help you further secure the system.
|
||||
|
||||
Preventing Systems from talking directly to the rsyslog Server
|
||||
--------------------------------------------------------------
|
||||
|
||||
It is possible that remote systems (or attackers) talk to the rsyslog
|
||||
server by directly connecting to its port 61514. Currently (July of
|
||||
2005), rsyslog does not offer the ability to bind to the local host,
|
||||
only. This feature is planned, but as long as it is missing, rsyslog
|
||||
must be protected via a firewall. This can easily be done via e.g
|
||||
iptables. Just be sure not to forget it.
|
||||
|
||||
Conclusion
|
||||
----------
|
||||
|
||||
With minimal effort, you can set up a secure logging infrastructure
|
||||
employing ssl encrypted syslog message transmission. As a side note, you
|
||||
also have the benefit of reliable tcp delivery which is far less prone
|
||||
to message loss than udp.
|
||||
16
doc/source/idx_reference.rst
Normal file
16
doc/source/idx_reference.rst
Normal file
@ -0,0 +1,16 @@
|
||||
Reference
|
||||
---------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
containers/index
|
||||
installation/index
|
||||
historical/index
|
||||
history
|
||||
licensing
|
||||
how2help
|
||||
community
|
||||
features
|
||||
proposals/index
|
||||
whitepapers/index
|
||||
@ -1,18 +1,11 @@
|
||||
.. seealso::
|
||||
----
|
||||
|
||||
Help with configuring/using |PRODUCT|:
|
||||
**Support:** `rsyslog Assistant <https://rsyslog.ai>`_ |
|
||||
`GitHub Discussions <https://github.com/rsyslog/rsyslog/discussions>`_ |
|
||||
GitHub Issues: |GitHubSourceProject|_
|
||||
|
||||
- `rsyslog Assistant <https://rsyslog.ai>`_: official AI-powered support
|
||||
- `GitHub Discussions <https://github.com/rsyslog/rsyslog/discussions>`_
|
||||
- GitHub Issues: |GitHubSourceProject|_ – report suspected bugs
|
||||
|
||||
.. seealso::
|
||||
|
||||
Contributing to |PRODUCT|:
|
||||
|
||||
- Source & documentation are in the unified |GitHubSourceProject|_ repository
|
||||
|
||||
Copyright 2008-2025 `Rainer Gerhards <https://rainer.gerhards.net/>`__,
|
||||
(`Großrinderfeld <https://www.rainer-gerhards.de/grossrinderfeld/>`__),
|
||||
and others.
|
||||
**Contributing:** Source & docs: |GitHubSourceProject|_
|
||||
|
||||
© 2008–2025 `Rainer Gerhards <https://rainer.gerhards.net/>`_
|
||||
and others. Licensed under the `Apache License 2.0
|
||||
<https://www.apache.org/licenses/LICENSE-2.0>`_.
|
||||
|
||||
@ -1,78 +1,46 @@
|
||||
Welcome to Rsyslog
|
||||
==================
|
||||
rsyslog
|
||||
=======
|
||||
|
||||
`Rsyslog <http://www.rsyslog.com/>`_ is a **r**\ ocket-fast **sys**\ tem for **log** processing.
|
||||
It offers high-performance, great security features and a modular design.
|
||||
While it started as a regular syslogd, rsyslog has evolved into a kind of
|
||||
**swiss army knife of logging**, being able to
|
||||
**rsyslog** is a high-performance, modular logging framework designed for
|
||||
both traditional syslog workloads and modern log processing pipelines. It
|
||||
supports flexible routing, advanced filtering, structured logging, and
|
||||
integrations with modern observability tools such as **Elasticsearch,
|
||||
Kafka, and cloud-based systems**.
|
||||
|
||||
- accept inputs from a wide variety of sources,
|
||||
- transform them,
|
||||
- and output the results to diverse destinations.
|
||||
rsyslog is widely used as the default logging daemon on Linux systems and
|
||||
scales from embedded environments to large enterprise deployments. Its
|
||||
modular design enables you to collect, transform, and reliably deliver
|
||||
logs to a wide variety of destinations.
|
||||
|
||||
Rsyslog has a strong enterprise focus but also scales down to small
|
||||
systems.
|
||||
It supports, among others, :doc:`MariaDB/MySQL <tutorials/database>`,
|
||||
:doc:`PostgreSQL <tutorials/database>`,
|
||||
:doc:`failover log destinations <tutorials/failover_syslog_server>`,
|
||||
ElasticSearch, syslog/tcp transport, fine grain output format control,
|
||||
high precision timestamps,
|
||||
queued operations and the ability to filter on any message part.
|
||||
**Start Here:**
|
||||
- :doc:`Getting Started <getting_started>`
|
||||
- :doc:`Configuration Basics <configuration/index>`
|
||||
- :doc:`Troubleshooting <troubleshooting/index>`
|
||||
- :doc:`Tutorials <tutorials/index>`
|
||||
|
||||
Manual
|
||||
------
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
installation/index
|
||||
getting_started
|
||||
configuration/index
|
||||
containers/index
|
||||
troubleshooting/index
|
||||
faq/index
|
||||
concepts/index
|
||||
examples/index
|
||||
tutorials/index
|
||||
troubleshooting/index
|
||||
concepts/index
|
||||
development/index
|
||||
historical/index
|
||||
idx_reference
|
||||
|
||||
Reference
|
||||
---------
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
history
|
||||
licensing
|
||||
how2help
|
||||
community
|
||||
features
|
||||
proposals/index
|
||||
whitepapers/index
|
||||
free_support
|
||||
compatibility/index
|
||||
|
||||
Sponsors and Community
|
||||
Community and Sponsors
|
||||
----------------------
|
||||
|
||||
Please visit the rsyslog `Sponsor's Page`_ to honor the project sponsors or
|
||||
become one yourself! We are very grateful for any help towards the project
|
||||
goals.
|
||||
See the `Sponsor's Page <http://www.rsyslog.com/sponsors>`_ for details on
|
||||
project sponsors and how to support ongoing development.
|
||||
|
||||
If you like rsyslog, you might want to lend us a helping hand. It
|
||||
doesn't require a lot of time - even a single mouse click helps. Learn
|
||||
:doc:`how2help`.
|
||||
Want to help? See :doc:`how2help`.
|
||||
|
||||
.. _Sponsor's Page: http://www.rsyslog.com/sponsors
|
||||
Contributing to Documentation
|
||||
-----------------------------
|
||||
|
||||
Contributing to the docs
|
||||
------------------------
|
||||
|
||||
This documentation is hosted on `github
|
||||
<https://github.com/rsyslog/rsyslog/tree/main/doc>`_. If you find something to be
|
||||
improved, please feel free to fork and file a patch request with your
|
||||
improvements. There is also a Button 'Edit in GitHub' on every documentation
|
||||
page beginning with the main `docs page
|
||||
<https://www.rsyslog.com/doc/v8-stable/>`_ that allows easy access.
|
||||
|
||||
.. only:: dev
|
||||
|
||||
Built on |today| from branch |DOC_BRANCH|, commit |DOC_COMMIT|.
|
||||
This documentation is hosted on `GitHub
|
||||
<https://github.com/rsyslog/rsyslog/tree/main/doc>`_. Use the "Edit in
|
||||
GitHub" button on any page to suggest improvements.
|
||||
|
||||
@ -138,7 +138,7 @@ work.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:doc:`/compatibility/v3compatibility`
|
||||
:doc:`/historical/v3compatibility`
|
||||
|
||||
To load the most common plug-ins, add the following to the top of
|
||||
rsyslog.conf:
|
||||
|
||||
@ -1,9 +0,0 @@
|
||||
Extending rsyslog
|
||||
=================
|
||||
|
||||
Native plugins
|
||||
--------------
|
||||
|
||||
External plugins
|
||||
----------------
|
||||
|
||||
@ -1,6 +0,0 @@
|
||||
Create your first Rsyslog setup
|
||||
===============================
|
||||
|
||||
Teach how to get log messages from `logger` command and write to files conditionally.
|
||||
|
||||
|
||||
@ -1,14 +0,0 @@
|
||||
The Book
|
||||
========
|
||||
|
||||
.. toctree::
|
||||
|
||||
overview
|
||||
installing
|
||||
first_setup
|
||||
language
|
||||
input
|
||||
output
|
||||
queues
|
||||
security
|
||||
extending
|
||||
@ -1,3 +0,0 @@
|
||||
Input: from where come the logs
|
||||
===============================
|
||||
|
||||
@ -1,148 +0,0 @@
|
||||
Installing and configuring Rsyslog
|
||||
==================================
|
||||
|
||||
General procedures to install and configure.
|
||||
|
||||
|
||||
Installing from packages
|
||||
------------------------
|
||||
|
||||
How to install using apt-get, yum, etc.
|
||||
|
||||
|
||||
Installing from sources
|
||||
-----------------------
|
||||
|
||||
How to compile the sources into your system.
|
||||
|
||||
Testing configuration blocks
|
||||
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
#### MODULES ####
|
||||
|
||||
# Load (i)nput and (o)utput (m)odules
|
||||
module(load="imuxsock")
|
||||
module(load="imklog")
|
||||
module(load="imudp")
|
||||
module(load="imtcp")
|
||||
module(load="imrelp")
|
||||
module(load="omrelp")
|
||||
module(load="impstats" interval="3600" severity="7" log.syslog="off" log.file="/var/log/rsyslog-stats.log")
|
||||
|
||||
# Module parameters
|
||||
input(type="imrelp" port="1514" ruleset="remote")
|
||||
input(type="imtcp" port="514" ruleset="remote")
|
||||
input(type="imudp" port="514" ruleset="remote")
|
||||
|
||||
#### GLOBAL DIRECTIVES ####
|
||||
|
||||
# Use default timestamp format
|
||||
$ActionFileDefaultTemplate RSYSLOG_TraditionalFileFormat
|
||||
|
||||
# Spool files
|
||||
$WorkDirectory /var/spool/rsyslog
|
||||
|
||||
# Filter duplicate messages
|
||||
$RepeatedMsgReduction on
|
||||
|
||||
#### RULES ####
|
||||
|
||||
#...cut out standard log rules for brevity...#
|
||||
|
||||
ruleset(name="remote"){
|
||||
|
||||
action(Name="storage"
|
||||
Type="omrelp"
|
||||
Target="10.1.1.100"
|
||||
Port="514"
|
||||
Action.ExecOnlyWhenPreviousIsSuspended="on"
|
||||
queue.FileName="storage-buffer"
|
||||
queue.SaveOnShutdown="on"
|
||||
queue.Type="LinkedList"
|
||||
Action.ResumeInterval="30"
|
||||
Action.ResumeRetryCount="-1"
|
||||
Timeout="5")
|
||||
|
||||
action(Name="analysis"
|
||||
Type="omrelp"
|
||||
Target="10.1.1.101"
|
||||
Port="514"
|
||||
Action.ExecOnlyWhenPreviousIsSuspended="on"
|
||||
queue.FileName="analysis-buffer"
|
||||
queue.SaveOnShutdown="on"
|
||||
queue.Type="LinkedList"
|
||||
Action.ResumeInterval="30"
|
||||
Action.ResumeRetryCount="-1"
|
||||
Timeout="5")
|
||||
|
||||
action(Name="indexer"
|
||||
Type="omfwd"
|
||||
Target="10.1.1.102"
|
||||
Protocol="tcp"
|
||||
Port="514"
|
||||
Action.ExecOnlyWhenPreviousIsSuspended="on"
|
||||
queue.FileName="indexer-buffer"
|
||||
queue.SaveOnShutdown="on"
|
||||
queue.Type="LinkedList"
|
||||
Action.ResumeInterval="30"
|
||||
Action.ResumeRetryCount="-1"
|
||||
Timeout="5")
|
||||
}
|
||||
|
||||
#### INCLUDES ####
|
||||
|
||||
# Includes config files (Do these last)
|
||||
$IncludeConfig /etc/rsyslog.d/*.conf
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
You'll learn exactly how to load each file/format in the next section.
|
||||
|
||||
.. option:: dest_dir
|
||||
|
||||
Destination directory.
|
||||
|
||||
.. option:: -m <module>, --module <module>
|
||||
|
||||
Run a module as a script.
|
||||
|
||||
.. envvar:: nome_envvar
|
||||
|
||||
Descrevendo um programa.
|
||||
|
||||
.. program:: rm
|
||||
|
||||
.. option:: -r
|
||||
|
||||
Work recursively.
|
||||
|
||||
.. program:: svn
|
||||
|
||||
.. option:: -r revision
|
||||
|
||||
Specify the revision to work upon.
|
||||
|
||||
-------------------------------------------------
|
||||
|
||||
.. describe:: PAPER
|
||||
|
||||
You can set this variable to select a paper size.
|
||||
|
||||
-------------------------------------------------
|
||||
|
||||
todo::
|
||||
|
||||
Este item é do TO DO.
|
||||
|
||||
-------------------------------------------------
|
||||
|
||||
todolist::
|
||||
|
||||
none
|
||||
|
||||
-------------------------------------------------
|
||||
|
||||
FIM
|
||||
@ -1,29 +0,0 @@
|
||||
Configuration format
|
||||
====================
|
||||
|
||||
Currently there are two ways of creating your configuration
|
||||
script: RainerScript and the legacy format.
|
||||
|
||||
|
||||
RainerScript format
|
||||
-------------------
|
||||
|
||||
General guidelines.
|
||||
|
||||
|
||||
Legacy configuration format (deprecated)
|
||||
----------------------------------------
|
||||
|
||||
General guidelines.
|
||||
|
||||
|
||||
Why is there two different formats?
|
||||
-----------------------------------
|
||||
|
||||
Explain!
|
||||
|
||||
|
||||
todo::
|
||||
|
||||
Este item é do TO DO in language-rst.
|
||||
|
||||
@ -1,63 +0,0 @@
|
||||
Output
|
||||
======
|
||||
|
||||
What should be logged
|
||||
---------------------
|
||||
|
||||
Message properties
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
System properties
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
Variables
|
||||
^^^^^^^^^
|
||||
|
||||
|
||||
Functions
|
||||
^^^^^^^^^
|
||||
|
||||
|
||||
Transformation Modules
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
When should be logged
|
||||
---------------------
|
||||
|
||||
Filter Conditions
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
* “traditional” severity and facility based selectors
|
||||
* property-based filters
|
||||
* expression-based filters
|
||||
* BSD-style blocks (not upward compatible)
|
||||
|
||||
Rulesets
|
||||
^^^^^^^^
|
||||
|
||||
|
||||
How should be logged
|
||||
--------------------
|
||||
|
||||
|
||||
RainerScript templates
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
Legacy format templates
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
Properties in templates
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
Conditionally choosing a template
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
Where should be send: Output Modules
|
||||
------------------------------------
|
||||
@ -1,38 +0,0 @@
|
||||
Overview
|
||||
========
|
||||
|
||||
Write a bit about the logging challenge.
|
||||
|
||||
What is Rsyslog?
|
||||
----------------
|
||||
|
||||
`Rsyslog <http://www.rsyslog.com/>`_ is a **r**\ ocket-fast **sys**\ tem for **log** processing.
|
||||
It offers high-performance, great security features and a modular design.
|
||||
While it started as a regular syslogd, rsyslog has evolved into a kind of
|
||||
**swiss army knife of logging**, being able to
|
||||
|
||||
- accept inputs from a wide variety of sources,
|
||||
- transform them,
|
||||
- and output the results to diverse destinations.
|
||||
|
||||
Rsyslog has a strong enterprise focus but also scales down to small
|
||||
systems.
|
||||
|
||||
Message flow in rsyslog
|
||||
-----------------------
|
||||
|
||||
From where to where and when... describes the flow.
|
||||
|
||||
Input
|
||||
^^^^^
|
||||
|
||||
Message Transformation
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Output
|
||||
^^^^^^
|
||||
|
||||
Output format: Templates
|
||||
""""""""""""""""""""""""
|
||||
|
||||
|
||||
@ -1,23 +0,0 @@
|
||||
Queues: prepare for the worst
|
||||
=============================
|
||||
|
||||
|
||||
What are queues?
|
||||
----------------
|
||||
|
||||
In-memory queues
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
Disk queues
|
||||
^^^^^^^^^^^
|
||||
|
||||
Disk-assisted queues
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
Main message queue
|
||||
------------------
|
||||
|
||||
Action queues
|
||||
-------------
|
||||
|
||||
@ -1,9 +0,0 @@
|
||||
Security
|
||||
========
|
||||
|
||||
Securing your setup
|
||||
-------------------
|
||||
|
||||
Dropping privileges
|
||||
-------------------
|
||||
|
||||
@ -1,41 +0,0 @@
|
||||
Git
|
||||
===
|
||||
|
||||
This document explains some conventions and specificities in the way we manage
|
||||
the Rsyslog code with Git.
|
||||
|
||||
Pull Requests
|
||||
-------------
|
||||
|
||||
Whenever a pull request is merged, all the information contained in the pull
|
||||
request (including comments) is saved in the repository.
|
||||
|
||||
You can easily spot pull request merges as the commit message always follows
|
||||
this pattern:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
merged branch USER_NAME/BRANCH_NAME (PR #1111)
|
||||
|
||||
The PR reference allows you to have a look at the original pull request on
|
||||
GitHub: https://github.com/rsyslog/rsyslog/pull/1111. But all the information
|
||||
you can get on GitHub is also available from the repository itself.
|
||||
|
||||
The merge commit message contains the original message from the author of the
|
||||
changes. Often, this can help understand what the changes were about and the
|
||||
reasoning behind the changes.
|
||||
|
||||
Moreover, the full discussion that might have occurred back then is also
|
||||
stored as a Git note. To get access to these notes, add this line to
|
||||
your ``.git/config`` file:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
fetch = +refs/notes/*:refs/notes/*
|
||||
|
||||
After a fetch, getting the GitHub discussion for a commit is then a matter of
|
||||
adding ``--show-notes=github-comments`` to the ``git show`` command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ git show HEAD --show-notes=github-comments
|
||||
@ -1,8 +0,0 @@
|
||||
Contributing Code
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
standards
|
||||
git
|
||||
@ -1,10 +0,0 @@
|
||||
Coding Standards
|
||||
================
|
||||
|
||||
When contributing code to Rsyslog, you must follow its coding standards. To
|
||||
make a long story short, here is the golden rule: **Imitate the existing
|
||||
Rsyslog code**. Most open-source modules and libraries recommended by Rsyslog also
|
||||
follow the same guidelines, and you should too.
|
||||
|
||||
Remember that the main advantage of standards is that every piece of code
|
||||
looks and feels familiar, it's not about this or that being more readable.
|
||||
@ -1,8 +0,0 @@
|
||||
Community
|
||||
=========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
releases
|
||||
other
|
||||
@ -1,13 +0,0 @@
|
||||
Other Resources
|
||||
===============
|
||||
|
||||
In order to follow what is happening in the community you might find helpful
|
||||
these additional resources:
|
||||
|
||||
* List of open pull requests `pull requests`_
|
||||
* List of recent `commits`_
|
||||
* List of open bugs and enhancements `bugs and enhancements`_
|
||||
|
||||
.. _pull requests: https://github.com/rsyslog/rsyslog/pulls
|
||||
.. _commits: https://github.com/rsyslog/rsyslog/commits/master
|
||||
.. _bugs and enhancements: https://github.com/rsyslog/rsyslog/issues
|
||||
@ -1,43 +0,0 @@
|
||||
The Release Process
|
||||
===================
|
||||
|
||||
This document explains the Rsyslog release process (Rsyslog being the code
|
||||
hosted on the main ``rsyslog/rsyslog`` `Git repository`_).
|
||||
|
||||
Rsyslog manages its releases through a *time-based model*; a new Rsyslog minor
|
||||
version comes out every *six weeks*.
|
||||
|
||||
.. tip::
|
||||
|
||||
The meaning of "minor" comes from the `Semantic Versioning`_ strategy.
|
||||
|
||||
Each minor version sticks to the same very well-defined process where we start
|
||||
with a development period, followed by a maintenance period.
|
||||
|
||||
.. note::
|
||||
|
||||
This release process has been adopted as of Rsyslog 8.2, and all the
|
||||
"rules" explained in this document must be strictly followed as of Rsyslog
|
||||
8.3.
|
||||
|
||||
.. _contributing-release-development:
|
||||
|
||||
Development
|
||||
-----------
|
||||
|
||||
The full development period lasts six weeks and is divided into two phases:
|
||||
|
||||
* *Development*: *Four weeks* to add new features and to enhance existing
|
||||
ones;
|
||||
|
||||
* *Stabilisation*: *Two weeks* to fix bugs, prepare the release, and wait
|
||||
for the whole Rsyslog ecosystem (third-party libraries, bundles, and
|
||||
projects using Rsyslog) to catch up.
|
||||
|
||||
During the development phase, any new feature can be reverted if it won't be
|
||||
finished in time or if it won't be stable enough to be included in the current
|
||||
final release.
|
||||
|
||||
|
||||
.. _Semantic Versioning: https://semver.org/
|
||||
.. _Git repository: https://github.com/rsyslog/rsyslog
|
||||
@ -1,3 +0,0 @@
|
||||
How to contribute to the documentation
|
||||
======================================
|
||||
|
||||
@ -1,9 +0,0 @@
|
||||
Contributing
|
||||
============
|
||||
|
||||
.. toctree::
|
||||
|
||||
code/index
|
||||
documentation/index
|
||||
community/index
|
||||
|
||||
@ -1,7 +0,0 @@
|
||||
The Cookbook
|
||||
============
|
||||
|
||||
.. toctree::
|
||||
|
||||
templates/index
|
||||
setup/index
|
||||
@ -1,3 +0,0 @@
|
||||
Centralised logging with Logstash/ElasticSearch/Kibana
|
||||
======================================================
|
||||
|
||||
@ -1,7 +0,0 @@
|
||||
Setup Cookbooks
|
||||
===============
|
||||
|
||||
|
||||
.. toctree::
|
||||
|
||||
centralised_logging_logstash
|
||||
@ -1,8 +0,0 @@
|
||||
Templates
|
||||
=========
|
||||
|
||||
.. toctree::
|
||||
|
||||
rfc3164
|
||||
rfc5424
|
||||
|
||||
@ -1,3 +0,0 @@
|
||||
Configuring an RFC 3164 Template with Json message
|
||||
==================================================
|
||||
|
||||
@ -1,3 +0,0 @@
|
||||
Configuring an RFC 5424 Template with Json message
|
||||
==================================================
|
||||
|
||||
@ -1,82 +0,0 @@
|
||||
Rsyslog Documentation Review Proposal
|
||||
=====================================
|
||||
|
||||
Currently the Rsyslog documentation is spread over many places. It's not logical
|
||||
and well-organized as well. The objective of this proposal is to address those issues
|
||||
and establish a procedure for further development of the documentation.
|
||||
|
||||
.. note::
|
||||
|
||||
We SHOULD NOT write examples using mixed formats, RainerScripts and legacy. It confused
|
||||
the readers. We can provide them in both formats, but should not mix them.
|
||||
|
||||
|
||||
Compile information from current sources of information
|
||||
-------------------------------------------------------
|
||||
|
||||
Below are listed the official locations where documentation about Rsyslog can be found.
|
||||
|
||||
* Wiki: http://wiki.rsyslog.com/index.php/Main_Page
|
||||
* Rainer's blog: https://rainer.gerhards.net/2012/10/how-to-use-rsyslogs-ruleset-and-call.html
|
||||
* Issues: https://github.com/rsyslog/rsyslog
|
||||
* docs: https://github.com/rsyslog/rsyslog-doc
|
||||
* Forum: http://kb.monitorware.com/configuration-f36.html
|
||||
* https://www.youtube.com/user/rainergerhards
|
||||
|
||||
|
||||
Add a Cookbook Section
|
||||
----------------------
|
||||
|
||||
We should create some cookbooks to help people get started with Rsyslog.
|
||||
Some candidates to be a cookbook are below.
|
||||
|
||||
* http://sickbits.net/log-storage-and-analysis-infrastructure-reliable-logging-and-analysis-with-rsyslog-and-relp/
|
||||
* http://kb.monitorware.com/omfile-with-dynfile-syslogfacility-text-t12515.html
|
||||
* http://www.freeipa.org/page/Howto/Centralised_Logging_with_Logstash/ElasticSearch/Kibana
|
||||
|
||||
Add a subsection called "processing logs from". We'd place articles that'd would help people with specific
|
||||
common scenarios for a specific log sender application.
|
||||
|
||||
Add a Reference Section
|
||||
-----------------------
|
||||
|
||||
This section would have all the reference configuration of all possible tags, in both formats, RainerScript
|
||||
and legacy.
|
||||
|
||||
|
||||
Write articles that address common problems
|
||||
-------------------------------------------
|
||||
|
||||
Some of the common are following.
|
||||
|
||||
* https://github.com/rsyslog/rsyslog/issues/160
|
||||
* http://kb.monitorware.com/nginx-logging-rsyslog-t12359.html
|
||||
* http://trac.nginx.org/nginx/ticket/677
|
||||
|
||||
|
||||
Extra
|
||||
-----
|
||||
|
||||
Some resources worth taking a look.
|
||||
|
||||
* https://docs.redhat.com/en/documentation/Red_Hat_Enterprise_Linux/7/html/system_administrators_guide/ch-viewing_and_managing_log_files
|
||||
* https://www.usenix.org/system/files/login/articles/06_lang-online.pdf
|
||||
* http://download.rsyslog.com/rainerscript2_rsyslog.conf
|
||||
* https://people.redhat.com/pvrabec/rpms/rsyslog/rsyslog-example.conf
|
||||
* http://www.rsyslog.com/doc/syslog_parsing.html
|
||||
|
||||
|
||||
Initial Summary
|
||||
---------------
|
||||
|
||||
- Troubleshooting
|
||||
|
||||
* http://www.rsyslog.com/how-can-i-check-the-config/
|
||||
|
||||
Proposed Documentation Structure
|
||||
--------------------------------
|
||||
|
||||
toctree::
|
||||
|
||||
new_documentation/index
|
||||
|
||||
@ -1,15 +0,0 @@
|
||||
Rsyslog documentation
|
||||
=====================
|
||||
|
||||
Below is the proposed documentation structure. It's initial content is the
|
||||
current documentation available, just organized differently.
|
||||
|
||||
.. toctree::
|
||||
|
||||
book/index
|
||||
cookbook/index
|
||||
reference/index
|
||||
contributing/index
|
||||
documentation_review.rst
|
||||
|
||||
|
||||
@ -1,3 +0,0 @@
|
||||
Action Configuration Reference
|
||||
==============================
|
||||
|
||||
@ -1,3 +0,0 @@
|
||||
Global Configuration Reference
|
||||
==============================
|
||||
|
||||
@ -1,11 +0,0 @@
|
||||
Configuration Reference
|
||||
=======================
|
||||
|
||||
.. toctree::
|
||||
|
||||
module
|
||||
input
|
||||
action
|
||||
parser
|
||||
global
|
||||
timezone
|
||||
@ -1,3 +0,0 @@
|
||||
Input Configuration Reference
|
||||
=============================
|
||||
|
||||
@ -1,3 +0,0 @@
|
||||
Module Configuration Reference
|
||||
==============================
|
||||
|
||||
@ -1,3 +0,0 @@
|
||||
Parser Configuration Reference
|
||||
==============================
|
||||
|
||||
@ -1,3 +0,0 @@
|
||||
Timezone Configuration Reference
|
||||
================================
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 614 KiB |
@ -5,5 +5,3 @@ Proposals
|
||||
:maxdepth: 2
|
||||
|
||||
version_naming
|
||||
lookup_tables
|
||||
big_restructuring/index
|
||||
|
||||
@ -1,240 +0,0 @@
|
||||
Lookup Tables
|
||||
=============
|
||||
|
||||
**NOTE: this is proposed functionality, which is NOT YET IMPLEMENTED!**
|
||||
|
||||
**Lookup tables are a powerful construct to obtain "class" information
|
||||
based on message content (e.g. to build log file names for different
|
||||
server types, departments or remote offices).**
|
||||
|
||||
The base idea is to use a message variable as an index into a table
|
||||
which then returns another value. For example, $fromhost-ip could be
|
||||
used as an index, with the table value representing the type of server
|
||||
or the department or remote office it is located in. A main point with
|
||||
lookup tables is that the lookup is very fast. So while lookup tables
|
||||
can be emulated with if-elseif constructs, they are generally much
|
||||
faster. Also, it is possible to reload lookup tables during rsyslog
|
||||
runtime without the need for a full restart.
|
||||
|
||||
The lookup tables itself exists in a separate configuration file (one
|
||||
per table). This file is loaded on rsyslog startup and when a reload is
|
||||
requested.
|
||||
|
||||
There are different types of lookup tables:
|
||||
|
||||
- **string** - the value to be looked up is an arbitrary string. Only
|
||||
exact some strings match.
|
||||
- **array** - the value to be looked up is an integer number from a
|
||||
consecutive set. The set does not need to start at zero or one, but
|
||||
there must be no number missing. So, for example 5,6,7,8,9 would be a
|
||||
valid set of index values, while 1,2,4,5 would not be (due to missing
|
||||
2). A match happens if the requested number is present.
|
||||
- **sparseArray** - the value to be looked up is an integer value, but
|
||||
there may be gaps inside the set of values (usually there are large
|
||||
gaps). A typical use case would be the matching of IPv4 address
|
||||
information. A match happens on the first value that is less than or
|
||||
equal to the requested value.
|
||||
|
||||
Note that index integer numbers are represented by unsigned 32 bits.
|
||||
|
||||
Lookup tables can be access via the lookup() built-in function. The core
|
||||
idea is to set a local variable to the lookup result and later on use
|
||||
that local variable in templates.
|
||||
|
||||
More details on usage now follow.
|
||||
|
||||
Lookup Table File Format
|
||||
------------------------
|
||||
|
||||
Lookup table files contain a single JSON object. This object contains of
|
||||
a header and a table part.
|
||||
|
||||
Header
|
||||
~~~~~~
|
||||
|
||||
The header is the top-level json. It has parameters "version", "nomatch",
|
||||
and "type". The version parameter must be given and must always be one
|
||||
for this version of rsyslog. The nomatch parameter is optional. If
|
||||
specified, it contains the value to be used if lookup() is provided an
|
||||
index value for which no entry exists. The default for "nomatch" is the
|
||||
empty string. Type specifies the type of lookup to be done.
|
||||
|
||||
Table
|
||||
~~~~~
|
||||
|
||||
This must be an array of elements, even if only a single value exists
|
||||
(for obvious reasons, we do not expect this to occur often). Each array
|
||||
element must contain two fields "index" and "value".
|
||||
|
||||
Example
|
||||
~~~~~~~
|
||||
|
||||
This is a sample of how an ip-to-office mapping may look like:
|
||||
|
||||
::
|
||||
|
||||
{ "version":1, "nomatch":"unk", "type":"string",
|
||||
"table":[ {"index":"10.0.1.1", "value":"A" },
|
||||
{"index":"10.0.1.2", "value":"A" },
|
||||
{"index":"10.0.1.3", "value":"A" },
|
||||
{"index":"10.0.2.1", "value":"B" },
|
||||
{"index":"10.0.2.2", "value":"B" },
|
||||
{"index":"10.0.2.3", "value":"B" }
|
||||
]
|
||||
}
|
||||
|
||||
Note: if a different IP comes in, the value "unk" is returned thanks to
|
||||
the nomatch parameter in the first line.
|
||||
|
||||
RainerScript Statements
|
||||
-----------------------
|
||||
|
||||
lookup\_table() Object
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This statement defines and initially loads a lookup table. Its format is
|
||||
as follows:
|
||||
|
||||
::
|
||||
|
||||
lookup_table(name="name" file="/path/to/file" reloadOnHUP="on|off")
|
||||
|
||||
Parameters
|
||||
^^^^^^^^^^
|
||||
|
||||
- **name** (mandatory)
|
||||
|
||||
Defines the name of lookup table for further reference inside the
|
||||
configuration. Names must be unique. Note that it is possible, though
|
||||
not advisable, to have different names for the same file.
|
||||
- **file** (mandatory)
|
||||
|
||||
Specifies the full path for the lookup table file. This file must be
|
||||
readable for the user rsyslog is run under (important when dropping
|
||||
privileges). It must point to a valid lookup table file as described
|
||||
above.
|
||||
- **reloadOnHUP** (optional, default "on")
|
||||
|
||||
Specifies if the table shall automatically be reloaded as part of
|
||||
HUP processing. For static tables, the default is "off" and
|
||||
specifying "on" triggers an error message. Note that the default of
|
||||
"on" may be somewhat suboptimal performance-wise, but probably is
|
||||
what the user intuitively expects. Turn it off if you know that you
|
||||
do not need the automatic reload capability.
|
||||
|
||||
lookup() Function
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
This function is used to actually do the table lookup. Format:
|
||||
|
||||
::
|
||||
|
||||
lookup("name", indexvalue)
|
||||
|
||||
Parameters
|
||||
^^^^^^^^^^
|
||||
|
||||
- **return value**
|
||||
|
||||
The function returns the string that is associated with the given
|
||||
indexvalue. If the indexvalue is not present inside the lookup table,
|
||||
the "nomatch" string is returned (or an empty string if it is not
|
||||
defined).
|
||||
- **name** (constant string)
|
||||
|
||||
The lookup table to be used. Note that this must be specified as a
|
||||
constant. In theory, variable table names could be made possible, but
|
||||
their runtime behaviour is not as good as for static names, and we do
|
||||
not (yet) see good use cases where dynamic table names could be
|
||||
useful.
|
||||
- **indexvalue** (expression)
|
||||
|
||||
The value to be looked up. While this is an arbitrary RainerScript
|
||||
expression, it's final value is always converted to a string in order
|
||||
to conduct the lookup. For example, "lookup(table, 3+4)" would be
|
||||
exactly the same as "lookup(table, "7")". In most cases, indexvalue
|
||||
will probably be a single variable, but it could also be the result
|
||||
of all RainerScript-supported expression types (like string
|
||||
concatenation or substring extraction). Valid samples are
|
||||
"lookup(name, $fromhost-ip & $hostname)" or "lookup(name,
|
||||
substr($fromhost-ip, 0, 5))" as well as of course the usual
|
||||
"lookup(table, $fromhost-ip)".
|
||||
|
||||
load\_lookup\_table Statement
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
**Note: in the final implementation, this MAY be implemented as an
|
||||
action. This is a low-level decision that must be made during the detail
|
||||
development process. Parameters and semantics will remain the same of
|
||||
this happens.**
|
||||
|
||||
This statement is used to reload a lookup table. It will fail if the
|
||||
table is static. While this statement is executed, lookups to this table
|
||||
are temporarily blocked. So for large tables, there may be a slight
|
||||
performance hit during the load phase. It is assume that always a
|
||||
triggering condition is used to load the table.
|
||||
|
||||
::
|
||||
|
||||
load_lookup_table(name="name" errOnFail="on|off" valueOnFail="value")
|
||||
|
||||
Parameters
|
||||
^^^^^^^^^^
|
||||
|
||||
- **name** (string)
|
||||
|
||||
The lookup table to be used.
|
||||
- **errOnFail** (boolean, default "on")
|
||||
|
||||
Specifies whether or not an error message is to be emitted if there
|
||||
are any problems reloading the lookup table.
|
||||
- **valueOnFail** (optional, string)
|
||||
|
||||
This parameter affects processing if the lookup table cannot be
|
||||
loaded for some reason: If the parameter is not present, the previous
|
||||
table will be kept in use. If the parameter is given, the previous
|
||||
table will no longer be used, and instead an empty table be with
|
||||
nomath=valueOnFail be generated. In short, that means when the
|
||||
parameter is set and the reload fails, all matches will always return
|
||||
what is specified in valueOnFail.
|
||||
|
||||
Usage example
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
For clarity, we show only those parts of rsyslog.conf that affect lookup
|
||||
tables. We use the remote office example that an example lookup table
|
||||
file is given above for.
|
||||
|
||||
::
|
||||
|
||||
lookup_table(name="ip2office" file="/path/to/ipoffice.lu"
|
||||
reloadOnHUP="off")
|
||||
|
||||
|
||||
template(name="depfile" type="string"
|
||||
string="/var/log/%$usr.dep%/messages")
|
||||
|
||||
set $usr.dep = lookup("ip2office", $fromhost-ip);
|
||||
action(type="omfile" dynfile="depfile")
|
||||
|
||||
# support for reload "commands"
|
||||
if $fromhost-ip == "10.0.1.123"
|
||||
and $msg contains "reload office lookup table"
|
||||
then
|
||||
load_lookup_table(name="ip2office" errOnFail="on")
|
||||
|
||||
Note: for performance reasons, it makes sense to put the reload command
|
||||
into a dedicated ruleset, bound to a specific listener - which than
|
||||
should also be sufficiently secured, e.g. via TLS mutual auth.
|
||||
|
||||
Implementation Details
|
||||
----------------------
|
||||
|
||||
The lookup table functionality is implemented via highly efficient
|
||||
algorithms. The string lookup has O(log n) time complexity. The array
|
||||
lookup is O(1). In case of sparseArray, we have O(log n).
|
||||
|
||||
To preserve space and, more important, increase cache hit performance,
|
||||
equal data values are only stored once, no matter how often a lookup
|
||||
index points to them.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user