summaryrefslogtreecommitdiffstats
path: root/source/proposals
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--source/proposals/big_restructuring/book/extending.rst9
-rw-r--r--source/proposals/big_restructuring/book/first_setup.rst6
-rw-r--r--source/proposals/big_restructuring/book/index.rst14
-rw-r--r--source/proposals/big_restructuring/book/input.rst3
-rw-r--r--source/proposals/big_restructuring/book/installing.rst148
-rw-r--r--source/proposals/big_restructuring/book/language.rst29
-rw-r--r--source/proposals/big_restructuring/book/output.rst63
-rw-r--r--source/proposals/big_restructuring/book/overview.rst38
-rw-r--r--source/proposals/big_restructuring/book/queues.rst23
-rw-r--r--source/proposals/big_restructuring/book/security.rst9
-rw-r--r--source/proposals/big_restructuring/contributing/code/git.rst41
-rw-r--r--source/proposals/big_restructuring/contributing/code/index.rst8
-rw-r--r--source/proposals/big_restructuring/contributing/code/standards.rst10
-rw-r--r--source/proposals/big_restructuring/contributing/community/index.rst8
-rw-r--r--source/proposals/big_restructuring/contributing/community/other.rst13
-rw-r--r--source/proposals/big_restructuring/contributing/community/releases.rst43
-rw-r--r--source/proposals/big_restructuring/contributing/documentation/index.rst3
-rw-r--r--source/proposals/big_restructuring/contributing/index.rst9
-rw-r--r--source/proposals/big_restructuring/cookbook/index.rst7
-rw-r--r--source/proposals/big_restructuring/cookbook/setup/centralised_logging_logstash.rst3
-rw-r--r--source/proposals/big_restructuring/cookbook/setup/index.rst7
-rw-r--r--source/proposals/big_restructuring/cookbook/templates/index.rst8
-rw-r--r--source/proposals/big_restructuring/cookbook/templates/rfc3164.rst3
-rw-r--r--source/proposals/big_restructuring/cookbook/templates/rfc5424.rst3
-rw-r--r--source/proposals/big_restructuring/documentation_review.rst83
-rw-r--r--source/proposals/big_restructuring/index.rst15
-rw-r--r--source/proposals/big_restructuring/reference/action.rst3
-rw-r--r--source/proposals/big_restructuring/reference/global.rst3
-rw-r--r--source/proposals/big_restructuring/reference/index.rst11
-rw-r--r--source/proposals/big_restructuring/reference/input.rst3
-rw-r--r--source/proposals/big_restructuring/reference/module.rst3
-rw-r--r--source/proposals/big_restructuring/reference/parser.rst3
-rw-r--r--source/proposals/big_restructuring/reference/timezone.rst3
-rw-r--r--source/proposals/big_restructuring/toc_screenshot.pngbin0 -> 629287 bytes
-rw-r--r--source/proposals/index.rst9
-rw-r--r--source/proposals/lookup_tables.rst240
-rw-r--r--source/proposals/version_naming.rst150
37 files changed, 1034 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
new file mode 100644
index 0000000..b474c49
--- /dev/null
+++ b/source/proposals/big_restructuring/toc_screenshot.png
Binary files differ
diff --git a/source/proposals/index.rst b/source/proposals/index.rst
new file mode 100644
index 0000000..41c106a
--- /dev/null
+++ b/source/proposals/index.rst
@@ -0,0 +1,9 @@
+Proposals
+=========
+
+.. toctree::
+ :maxdepth: 2
+
+ version_naming
+ lookup_tables
+ big_restructuring/index
diff --git a/source/proposals/lookup_tables.rst b/source/proposals/lookup_tables.rst
new file mode 100644
index 0000000..f61d673
--- /dev/null
+++ b/source/proposals/lookup_tables.rst
@@ -0,0 +1,240 @@
+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 advisible, 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 decesion 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.
+
diff --git a/source/proposals/version_naming.rst b/source/proposals/version_naming.rst
new file mode 100644
index 0000000..7a0e7f2
--- /dev/null
+++ b/source/proposals/version_naming.rst
@@ -0,0 +1,150 @@
+Version Naming
+==============
+
+This is the proposal on how versions should be named in the future:
+
+Rsyslog version naming has undergone a number of changes in the past.
+Our sincere hopes is that the scheme outlined here will serve us well
+for the future. In general, a three-number versioning scheme with a
+potential development state indication is used. It follows this pattern:
+
+major.minor.patchlevel[-devstate]
+
+where devstate has some further structure:
+-<releaseReason><releaseNumber>
+
+All stable builds come without the devstate part. All unstable
+development version come with it.
+
+The major version is incremented whenever something really important
+happens. A single new feature, even if important, does not justify an
+increase in the major version. There is no hard rule when the major
+version needs an increment. It mostly is a soft factor, when the
+developers and/or the community think there has been sufficient change
+to justify that. Major version increments are expected to happen quite
+infrequently, maybe around once a year. A major version increment has
+important implications from the support side: without support contracts,
+the current major version's last stable release and the last stable
+release of the version immediately below it are supported (Adiscon, the
+rsyslog sponsor, offers `support contracts <http://www.rsyslog.com/professional-services/>`_
+covering all other versions).
+
+The minor version is incremented whenever a non-trivial new feature is
+planned to be added. Triviality of a feature is simply determined by
+time estimated to implement a feature. If that's more than a few days,
+it is considered a non-trivial feature. Whenever a new minor version is
+begun, the desired feature is identified and will be the primary focus
+of that major.minor version. Trivial features may justify a new minor
+version if they either do not look trivial from the user's point of view
+or change something quite considerable (so we need to alert users). A
+minor version increment may also be done for some other good reasons
+that the developers have.
+
+The patchlevel is incremented whenever there is a bugfix or very minor
+feature added to a (stable or development) release.
+
+The devstate is important during development of a feature. It helps the
+developers to release versions with new features to the general public
+and in the hope that this will result in some testing. To understand how
+it works, we need to look at the release cycle: As already said, at the
+start of a new minor version, a new non-trivial feature to be
+implemented in that version is selected. Development on this feature
+begins. At the current pace of development, getting initial support for
+such a non-trivial feature typically takes between two and four weeks.
+During this time, new feature requests come in. Also, we may find out
+that it may be just the right time to implement some not yet targeted
+feature requests. A reason for this is that the minor release's feature
+focus is easier to implement if the other feature is implemented first.
+This is a quite common thing to happen. So development on the primary
+focus may hold for a short period while we implement something else.
+Even unrelated, but very trivial feature requests (maybe an hour's worth
+of time to implement), may be done in between. Once we have implemented
+these things, we would like to release as quickly as possible (even more
+if someone has asked for the feature). So we do not like to wait for the
+original focus feature to be ready (what could take maybe three more
+weeks). As a result, we release the new features. But that version will
+also include partial code of the focus feature. Typically this doesn't
+hurt as long as noone tries to use it (what of course would miserably
+fail). But still, part of the new code is already in it. When we release
+such a "minor-feature enhanced" but "focus-feature not yet completed"
+version, we need a way to flag it. In current thinking, that is using a
+"-mf<version>" devstate in the version number ("mf" stands for "minor
+feature"). Version numbers for -mf releases start at 0 for the first
+release and are monotonically incremented. Once the focus feature has
+been fully implemented, a new version now actually supporting that
+feature will be released. Now, the release reason is changed to the
+well-know "-rc<version>" where "rc" stands for release candidate. For
+the first release candidate, the version starts at 0 again and is
+incremented monotonically for each subsequent release. Please note that
+a -rc0 may only have bare functionality but later -rc's have a richer
+one. If new minor features are implemented and released once we have
+reached rc stage, still a new rc version is issued. The difference
+between "mf" and "rc" is simply the presence of the desired feature. No
+support is provided for -mf versions once the first -rc version has been
+released. And only the most current -rc version is supported.
+
+The -rc is removed and the version declared stable when we think it has
+undergone sufficient testing and look sufficiently well. Then, it'll
+turn into a stable release. Stable minor releases never receive
+non-trivial new features. There may be more than one -rc releases
+without a stable release present at the same time. In fact, most often
+we will work on the next minor development version while the previous
+minor version is still a -rc because it is not yet considered
+sufficiently stable.
+
+Note: the absence of the -devstate part indicates that a release is
+stable. Following the same logic, any release with a -devstate part is
+unstable.
+
+A quick sample: 
+
+4.0.0 is the stable release. We begin to implement relp, moving to
+major.minor to 4.1. While we develop it, someone requests a trivial
+feature, which we implement. We need to release, so we will have
+4.1.0-mf0. Another new feature is requested, move to 4.1.0-mf2. A first
+version of RELP is implemented: 4.1.0-rc0. A new trivial feature is
+implemented: 4.1.0-rc1. Relp is being enhanced: 4.1.0-rc2. We now feel
+RELP is good enough for the time being and begin to implement TLS on
+plain /Tcp syslog: logical increment to 4.2. Now another new feature in
+that tree: 4.2.0-mf0. Note that we now have 4.0.0 (stable) and 4.1.0-rc2
+and 4.1.0-mf0 (both devel). We find a big bug in RELP coding. Two new
+releases: 4.1.0-rc3, 4.2.0-mf1 (the bug fix acts like a non-focus
+feature change). We release TLS: 4.2.0-rc0. Another RELP bug fix
+4.1.0-rc4, 4.2.0-rc1. After a while, RELP is matured: 4.1.0 (stable).
+Now support for 4.0.x stable ends. It, however, is still provided for
+3.x.x (in the actual case 2.x.x, because v3 was under the old naming
+scheme and now stable v3 was ever released).
+
+This is how it is done so far:
+
+This document briefly outlines the strategy for naming versions. It
+applies to versions 1.0.0 and above. Versions below that are all
+unstable and have a different naming schema.
+
+**Please note that version naming is currently being changed. There is a
+`blog post about future rsyslog
+versions <https://rainer.gerhards.net/2007/08/on-rsyslog-versions.html>`_.**
+
+The major version is incremented whenever a considerate, major features
+have been added. This is expected to happen quite infrequently.
+
+The minor version number is incremented whenever there is "sufficient
+need" (at the discretion of the developers). There is a notable
+difference between stable and unstable branches. The **stable branch**
+always has a minor version number in the range from 0 to 9. It is
+expected that the stable branch will receive bug and security fixes
+only. So the range of minor version numbers should be quite sufficient.
+
+For the **unstable branch**, minor version numbers always start at 10
+and are incremented as needed (again, at the discretion of the
+developers). Here, new minor versions include both fixes as well as new
+features (hopefully most of the time). They are expected to be released
+quite often.
+
+The patch level (third number) is incremented whenever a really minor
+thing must be added to an existing version. This is expected to happen
+quite infrequently.
+
+In general, the unstable branch carries all new development. Once it
+concludes with a sufficiently-enhanced, quite stable version, a new
+major stable version is assigned.