diff options
Diffstat (limited to 'source/proposals/big_restructuring')
34 files changed, 635 insertions, 0 deletions
diff --git a/source/proposals/big_restructuring/book/extending.rst b/source/proposals/big_restructuring/book/extending.rst new file mode 100644 index 0000000..0797206 --- /dev/null +++ b/source/proposals/big_restructuring/book/extending.rst @@ -0,0 +1,9 @@ +Extending rsyslog +================= + +Native plugins +-------------- + +External plugins +---------------- + diff --git a/source/proposals/big_restructuring/book/first_setup.rst b/source/proposals/big_restructuring/book/first_setup.rst new file mode 100644 index 0000000..9102c66 --- /dev/null +++ b/source/proposals/big_restructuring/book/first_setup.rst @@ -0,0 +1,6 @@ +Create your first Rsyslog setup +=============================== + +Teach how to get log messages from `logger` command and write to files conditionally. + + diff --git a/source/proposals/big_restructuring/book/index.rst b/source/proposals/big_restructuring/book/index.rst new file mode 100644 index 0000000..5b5260f --- /dev/null +++ b/source/proposals/big_restructuring/book/index.rst @@ -0,0 +1,14 @@ +The Book +======== + +.. toctree:: + + overview + installing + first_setup + language + input + output + queues + security + extending diff --git a/source/proposals/big_restructuring/book/input.rst b/source/proposals/big_restructuring/book/input.rst new file mode 100644 index 0000000..3938971 --- /dev/null +++ b/source/proposals/big_restructuring/book/input.rst @@ -0,0 +1,3 @@ +Input: from where come the logs +=============================== + diff --git a/source/proposals/big_restructuring/book/installing.rst b/source/proposals/big_restructuring/book/installing.rst new file mode 100644 index 0000000..9f1c6e8 --- /dev/null +++ b/source/proposals/big_restructuring/book/installing.rst @@ -0,0 +1,148 @@ +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 diff --git a/source/proposals/big_restructuring/book/language.rst b/source/proposals/big_restructuring/book/language.rst new file mode 100644 index 0000000..c75a42f --- /dev/null +++ b/source/proposals/big_restructuring/book/language.rst @@ -0,0 +1,29 @@ +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. + diff --git a/source/proposals/big_restructuring/book/output.rst b/source/proposals/big_restructuring/book/output.rst new file mode 100644 index 0000000..45fcc50 --- /dev/null +++ b/source/proposals/big_restructuring/book/output.rst @@ -0,0 +1,63 @@ +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 +------------------------------------ diff --git a/source/proposals/big_restructuring/book/overview.rst b/source/proposals/big_restructuring/book/overview.rst new file mode 100644 index 0000000..44c47d8 --- /dev/null +++ b/source/proposals/big_restructuring/book/overview.rst @@ -0,0 +1,38 @@ +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 +"""""""""""""""""""""""" + + diff --git a/source/proposals/big_restructuring/book/queues.rst b/source/proposals/big_restructuring/book/queues.rst new file mode 100644 index 0000000..cb35d74 --- /dev/null +++ b/source/proposals/big_restructuring/book/queues.rst @@ -0,0 +1,23 @@ +Queues: prepare for the worst +============================= + + +What are queues? +---------------- + +In-memory queues +^^^^^^^^^^^^^^^^ + +Disk queues +^^^^^^^^^^^ + +Disk-assisted queues +^^^^^^^^^^^^^^^^^^^^ + + +Main message queue +------------------ + +Action queues +------------- + diff --git a/source/proposals/big_restructuring/book/security.rst b/source/proposals/big_restructuring/book/security.rst new file mode 100644 index 0000000..573086e --- /dev/null +++ b/source/proposals/big_restructuring/book/security.rst @@ -0,0 +1,9 @@ +Security +======== + +Securing your setup +------------------- + +Dropping privileges +------------------- + diff --git a/source/proposals/big_restructuring/contributing/code/git.rst b/source/proposals/big_restructuring/contributing/code/git.rst new file mode 100644 index 0000000..e2a7176 --- /dev/null +++ b/source/proposals/big_restructuring/contributing/code/git.rst @@ -0,0 +1,41 @@ +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 diff --git a/source/proposals/big_restructuring/contributing/code/index.rst b/source/proposals/big_restructuring/contributing/code/index.rst new file mode 100644 index 0000000..734fa33 --- /dev/null +++ b/source/proposals/big_restructuring/contributing/code/index.rst @@ -0,0 +1,8 @@ +Contributing Code +================= + +.. toctree:: + :maxdepth: 2 + + standards + git diff --git a/source/proposals/big_restructuring/contributing/code/standards.rst b/source/proposals/big_restructuring/contributing/code/standards.rst new file mode 100644 index 0000000..5528af0 --- /dev/null +++ b/source/proposals/big_restructuring/contributing/code/standards.rst @@ -0,0 +1,10 @@ +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. diff --git a/source/proposals/big_restructuring/contributing/community/index.rst b/source/proposals/big_restructuring/contributing/community/index.rst new file mode 100644 index 0000000..43b7b52 --- /dev/null +++ b/source/proposals/big_restructuring/contributing/community/index.rst @@ -0,0 +1,8 @@ +Community +========= + +.. toctree:: + :maxdepth: 2 + + releases + other diff --git a/source/proposals/big_restructuring/contributing/community/other.rst b/source/proposals/big_restructuring/contributing/community/other.rst new file mode 100644 index 0000000..26b2cce --- /dev/null +++ b/source/proposals/big_restructuring/contributing/community/other.rst @@ -0,0 +1,13 @@ +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 diff --git a/source/proposals/big_restructuring/contributing/community/releases.rst b/source/proposals/big_restructuring/contributing/community/releases.rst new file mode 100644 index 0000000..2486eda --- /dev/null +++ b/source/proposals/big_restructuring/contributing/community/releases.rst @@ -0,0 +1,43 @@ +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: http://semver.org/ +.. _Git repository: https://github.com/rsyslog/rsyslog diff --git a/source/proposals/big_restructuring/contributing/documentation/index.rst b/source/proposals/big_restructuring/contributing/documentation/index.rst new file mode 100644 index 0000000..e684599 --- /dev/null +++ b/source/proposals/big_restructuring/contributing/documentation/index.rst @@ -0,0 +1,3 @@ +How to contribute to the documentation +====================================== + diff --git a/source/proposals/big_restructuring/contributing/index.rst b/source/proposals/big_restructuring/contributing/index.rst new file mode 100644 index 0000000..d4d99b5 --- /dev/null +++ b/source/proposals/big_restructuring/contributing/index.rst @@ -0,0 +1,9 @@ +Contributing +============ + +.. toctree:: + + code/index + documentation/index + community/index + diff --git a/source/proposals/big_restructuring/cookbook/index.rst b/source/proposals/big_restructuring/cookbook/index.rst new file mode 100644 index 0000000..8291e44 --- /dev/null +++ b/source/proposals/big_restructuring/cookbook/index.rst @@ -0,0 +1,7 @@ +The Cookbook +============ + +.. toctree:: + + templates/index + setup/index diff --git a/source/proposals/big_restructuring/cookbook/setup/centralised_logging_logstash.rst b/source/proposals/big_restructuring/cookbook/setup/centralised_logging_logstash.rst new file mode 100644 index 0000000..b33e9e8 --- /dev/null +++ b/source/proposals/big_restructuring/cookbook/setup/centralised_logging_logstash.rst @@ -0,0 +1,3 @@ +Centralised logging with Logstash/ElasticSearch/Kibana +====================================================== + diff --git a/source/proposals/big_restructuring/cookbook/setup/index.rst b/source/proposals/big_restructuring/cookbook/setup/index.rst new file mode 100644 index 0000000..def615e --- /dev/null +++ b/source/proposals/big_restructuring/cookbook/setup/index.rst @@ -0,0 +1,7 @@ +Setup Cookbooks +=============== + + +.. toctree:: + + centralised_logging_logstash diff --git a/source/proposals/big_restructuring/cookbook/templates/index.rst b/source/proposals/big_restructuring/cookbook/templates/index.rst new file mode 100644 index 0000000..1b3e14e --- /dev/null +++ b/source/proposals/big_restructuring/cookbook/templates/index.rst @@ -0,0 +1,8 @@ +Templates +========= + +.. toctree:: + + rfc3164 + rfc5424 + diff --git a/source/proposals/big_restructuring/cookbook/templates/rfc3164.rst b/source/proposals/big_restructuring/cookbook/templates/rfc3164.rst new file mode 100644 index 0000000..7045fb1 --- /dev/null +++ b/source/proposals/big_restructuring/cookbook/templates/rfc3164.rst @@ -0,0 +1,3 @@ +Configuring an RFC 3164 Template with Json message +================================================== + diff --git a/source/proposals/big_restructuring/cookbook/templates/rfc5424.rst b/source/proposals/big_restructuring/cookbook/templates/rfc5424.rst new file mode 100644 index 0000000..1b60645 --- /dev/null +++ b/source/proposals/big_restructuring/cookbook/templates/rfc5424.rst @@ -0,0 +1,3 @@ +Configuring an RFC 5424 Template with Json message +================================================== + diff --git a/source/proposals/big_restructuring/documentation_review.rst b/source/proposals/big_restructuring/documentation_review.rst new file mode 100644 index 0000000..b257bfd --- /dev/null +++ b/source/proposals/big_restructuring/documentation_review.rst @@ -0,0 +1,83 @@ +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://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/System_Administrators_Guide/ch-Viewing_and_Managing_Log_Files.html + * https://www.usenix.org/system/files/login/articles/06_lang-online.pdf + * https://media.readthedocs.org/pdf/rsyslog/latest/rsyslog.pdf + * http://download.rsyslog.com/rainerscript2_rsyslog.conf + * http://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 + diff --git a/source/proposals/big_restructuring/index.rst b/source/proposals/big_restructuring/index.rst new file mode 100644 index 0000000..a75c9f5 --- /dev/null +++ b/source/proposals/big_restructuring/index.rst @@ -0,0 +1,15 @@ +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 + + diff --git a/source/proposals/big_restructuring/reference/action.rst b/source/proposals/big_restructuring/reference/action.rst new file mode 100644 index 0000000..7ad1aaf --- /dev/null +++ b/source/proposals/big_restructuring/reference/action.rst @@ -0,0 +1,3 @@ +Action Configuration Reference +============================== + diff --git a/source/proposals/big_restructuring/reference/global.rst b/source/proposals/big_restructuring/reference/global.rst new file mode 100644 index 0000000..cc464fd --- /dev/null +++ b/source/proposals/big_restructuring/reference/global.rst @@ -0,0 +1,3 @@ +Global Configuration Reference +============================== + diff --git a/source/proposals/big_restructuring/reference/index.rst b/source/proposals/big_restructuring/reference/index.rst new file mode 100644 index 0000000..4583a93 --- /dev/null +++ b/source/proposals/big_restructuring/reference/index.rst @@ -0,0 +1,11 @@ +Configuration Reference +======================= + +.. toctree:: + + module + input + action + parser + global + timezone diff --git a/source/proposals/big_restructuring/reference/input.rst b/source/proposals/big_restructuring/reference/input.rst new file mode 100644 index 0000000..f1dd84d --- /dev/null +++ b/source/proposals/big_restructuring/reference/input.rst @@ -0,0 +1,3 @@ +Input Configuration Reference +============================= + diff --git a/source/proposals/big_restructuring/reference/module.rst b/source/proposals/big_restructuring/reference/module.rst new file mode 100644 index 0000000..3876f37 --- /dev/null +++ b/source/proposals/big_restructuring/reference/module.rst @@ -0,0 +1,3 @@ +Module Configuration Reference +============================== + diff --git a/source/proposals/big_restructuring/reference/parser.rst b/source/proposals/big_restructuring/reference/parser.rst new file mode 100644 index 0000000..c9e6dc6 --- /dev/null +++ b/source/proposals/big_restructuring/reference/parser.rst @@ -0,0 +1,3 @@ +Parser Configuration Reference +============================== + diff --git a/source/proposals/big_restructuring/reference/timezone.rst b/source/proposals/big_restructuring/reference/timezone.rst new file mode 100644 index 0000000..34db014 --- /dev/null +++ b/source/proposals/big_restructuring/reference/timezone.rst @@ -0,0 +1,3 @@ +Timezone Configuration Reference +================================ + diff --git a/source/proposals/big_restructuring/toc_screenshot.png b/source/proposals/big_restructuring/toc_screenshot.png Binary files differnew file mode 100644 index 0000000..b474c49 --- /dev/null +++ b/source/proposals/big_restructuring/toc_screenshot.png |
