6 files changed, 425 insertions, 0 deletions
diff --git a/source/installation/.install_from_source.rst.swp b/source/installation/.install_from_source.rst.swp
new file mode 100644
index 0000000..df6ea0c
--- /dev/null
+++ b/source/installation/.install_from_source.rst.swp
diff --git a/source/installation/build_from_repo.rst b/source/installation/build_from_repo.rst
new file mode 100644
index 0000000..d948626
--- /dev/null
+++ b/source/installation/build_from_repo.rst
@@ -0,0 +1,73 @@
+Installing rsyslog from the source repository
+=============================================
+
+In most cases, people install rsyslog either via a package or use an
+"official" distribution tarball to generate it. But there may be
+situations where it is desirable to build directly from the source
+repository. This is useful for people who would like to participate in
+development or who would like to use the latest, not-yet-released code.
+The later may especially be the case if you are asked to try out an
+experimental version.
+
+Building from the repository is not much different than building from the
+source tarball, but some files are missing because they are output files
+and thus do not belong into the repository.
+
+Obtaining the Source
+--------------------
+
+First of all, you need to download the sources. Rsyslog is kept in git.
+The "`Where to find the rsyslog source
+code <http://www.rsyslog.com/where-to-find-the-rsyslog-source-code/>`_\ "
+page on the project site will point you to the current repository
+location.
+
+After you have cloned the repository, you are in the master branch by
+default. This is where we keep the devel branch. If you need any other
+branch, you need to do a "git checkout --track -b branch origin/branch".
+For example, the command to check out the beta branch is "git checkout
+--track -b beta origin/beta".
+
+Prequisites
+-----------
+
+.. include:: /includes/container_dev_env.inc.rst
+
+To build the compilation system, you need
+
+* GNU autotools (autoconf, automake, ...)
+* libtool
+* pkg-config
+
+Unfortunately, the actual package names vary between distributions. Doing
+a search for the names above inside the packaging system should lead to
+the right path, though.
+
+If some of these tools are missing, you will see errors like this one:
+
+::
+
+    checking for SYSLOG_UNIXAF support... yes
+    checking for FSSTND support... yes
+    ./configure: line 25895: syntax error near unexpected token `RELP,'
+    ./configure: line 25895: ` PKG_CHECK_MODULES(RELP, relp >= 0.1.1)'
+
+The actual error message will vary. In the case shown here, pkg-config
+was missing.
+
+**Important:** the build dependencies must be present **before** creating
+the build environment is begun. Otherwise, some hard to interpret errors may
+occur. For example, the error above will also occur if you install
+pkg-config, but *after* you have run *autoreconf*. So be sure everything
+is in place *before* you create the build environment.
+
+Creating the Build Environment
+------------------------------
+
+This is fairly easy: just issue "**autoreconf -fvi**\ ", which should do
+everything you need. Once this is done, you can follow the usual
+./configure steps just like when you downloaded an official distribution
+tarball (see the `rsyslog install guide <install.html>`_, starting at
+step 2, for further details about that).
+
+
diff --git a/source/installation/index.rst b/source/installation/index.rst
new file mode 100644
index 0000000..8cd4d64
--- /dev/null
+++ b/source/installation/index.rst
@@ -0,0 +1,26 @@
+Installation
+============
+
+Installation is usually as simple as typing
+
+|  ``$ sudo yum install rsyslog``,
+|  ``$ sudo apt-get install rsyslog``, or
+|  ``$ sudo apk add rsyslog``
+
+Unfortunately distributions usually provide rather old versions of
+rsyslog, and so there are chances you want to have something
+newer. To do this easily, we provide :doc:`packages <packages>`
+and :doc:`Docker containers <rsyslog_docker>`.
+
+Alternatively you can build directly from source. That provides most
+flexibility and control over the resulting binaries, but obviously also
+requires most work. Some prior knowledge with building software on
+your system is recommended.
+
+.. toctree::
+   :maxdepth: 2
+
+   packages
+   rsyslog_docker
+   install_from_source
+   build_from_repo
diff --git a/source/installation/install_from_source.rst b/source/installation/install_from_source.rst
new file mode 100644
index 0000000..282e3b2
--- /dev/null
+++ b/source/installation/install_from_source.rst
@@ -0,0 +1,238 @@
+Installing rsyslog from Source
+==============================
+
+*Written by* `Rainer Gerhards <https://rainer.gerhards.net>`_
+
+**In this paper, I describe how to install**
+`rsyslog <http://www.rsyslog.com/>`_. It is intentionally a brief
+step-by-step guide, targeted to those who want to quickly get it up and
+running. For more elaborate information, please consult the rest of the
+:doc:`manual set <../index>`.
+
+How to make your life easier...
+-------------------------------
+
+In addition to building from source, you can also install |PRODUCT|
+using packages. If you use them, you can spare yourself many of the steps
+below. This is highly recommended if there is a package for your
+distribution available. See :doc:`packages` for instructions.
+
+Steps To Do
+-----------
+
+Step 1 - Download Software
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For obvious reasons, you need to download rsyslog. Here, I assume that
+you use a distribution tarball. If you would like to use a version
+directly from the repository, see :doc:`build_from_repo` instead.
+
+Load the most recent build from
+`http://www.rsyslog.com/downloads <http://www.rsyslog.com/downloads>`_.
+Extract the software with "tar xzf -nameOfDownloadSet-". This will
+create a new subdirectory rsyslog-version in the current working
+directory. cd into that.
+
+Depending on your system configuration, you also need to install some
+build tools, most importantly make, the gcc compiler and the MySQL
+development system (if you intend to use MySQL - the package is often
+named "mysql-dev"). On many systems, these things should already be
+present. If you don't know exactly, simply skip this step for now and
+see if nice error messages pop up during the compile process. If they
+do, you can still install the missing build environment tools. So this
+is nothing that you need to look at very carefully.
+
+
+Build Requirements
+~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/container_dev_env.inc.rst
+
+At a minimum, the following development tools must be present on the
+system:
+
+* C compiler (usually gcc)
+* make
+* libtool
+* rst2man (part of Python docutils) if you want to generate the man files
+* Bison and Flex (preferably, otherwise yacc and lex)
+* zlib development package (usually *libz-dev*)
+* json-c (usually named *libjson0-dev* or similar)
+* libuuid (usually *uuid-dev*, if not present use --disable-uuid)
+* libgcrypt (usually *libgcrypt-dev*)
+
+Also, development versions of the following supporting libraries
+that the rsyslog project provides are necessary:
+
+* liblogging (only stdlog component is hard requirement)
+* libfastjson
+* libestr
+
+In contrast to the other dependencies, recent versions of rsyslog may
+require recent versions of these libraries as well, so there is a chance
+that they must be built from source, too.
+
+Depending on which plugins are enabled, additional dependencies exist.
+These are reported during the ./configure run.
+
+**Important**: you need the **development** version of the packages in
+question. That is the version which is used by developers to build software
+that uses the respective package. Usually, they are separate from the
+regular user package. So if you just install the regular package but not
+the development one, ./configure will fail.
+
+As a concrete example, you may want to build ommysql. It obviously requires
+a package like *mysql-client*, but that is just the regular package and not
+sufficient to build rsyslog successfully. To do so, you need to also install
+something named like *mysql-client-dev*.
+
+Usually, the regular package is
+automatically installed, when you select the development package, but not
+vice versa. The exact behaviour and names depend on the distribution you use.
+It is quite common to name development packages something along the line of
+*pkgname-dev* or *pkgname-devel* where *pkgname* is the regular package name
+(like *mysql-client* in the above example).
+
+
+Step 2 - Run ./configure
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Run ./configure to adopt rsyslog to your environment. While doing so,
+you can also enable options. Configure will display selected options
+when it is finished. For example, to enable MySQL support, run::
+
+ ./configure --enable-mysql
+
+Please note that MySQL support by default is NOT disabled.
+
+To learn which ./configure options are available and what their
+default values are, use
+
+``./configure --help``
+
+
+Step 3 - Compile
+~~~~~~~~~~~~~~~~
+
+That is easy. Just type "make" and let the compiler work. On any recent
+system, that should be a very quick task, on many systems just a matter
+of a few seconds. If an error message comes up, most probably a part of
+your build environment is not installed. Check with step 1 in those
+cases.
+
+Step 4 - Install
+~~~~~~~~~~~~~~~~
+
+Again, that is quite easy. All it takes is a "sudo make install". That will
+copy the rsyslogd and the man pages to the relevant directories.
+
+Step 5 - Configure rsyslogd
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In this step, you tell rsyslogd what to do with received messages. If
+you are upgrading from stock syslogd, /etc/syslog.conf is probably a
+good starting point. Rsyslogd understands stock syslogd syntax, so you
+can simply copy over /etc/syslog.conf to /etc/rsyslog.conf. Note since
+version 3 rsyslog requires to load plug-in modules to perform useful
+work.
+
+.. seealso::
+
+   :doc:`/compatibility/v3compatibility`
+
+To load the most common plug-ins, add the following to the top of
+rsyslog.conf:
+
+::
+
+  $ModLoad immark # provides --MARK-- message capability
+  $ModLoad imudp # provides UDP syslog reception
+  $ModLoad imtcp # provides TCP syslog reception
+  $ModLoad imuxsock # provides support for local system logging
+  $ModLoad imklog # provides kernel logging support
+
+Change rsyslog.conf for any further enhancements you would like to see.
+For example, you can add database writing as outlined in the paper
+:doc:`/tutorials/database` (remember you need to enable MySQL
+support during step 2 if you want to do that!).
+
+Step 6 - Disable stock syslogd
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**You can skip this and the following steps if rsyslog was already
+installed as the stock
+syslogd on your system (e.g. via a distribution default or package).**
+In this case, you are finished.
+
+If another syslogd is installed, it must be disabled and rsyslog set
+to become the default. This is because
+both it and rsyslogd listen to the same sockets, they can NOT be run
+concurrently. So you need to disable the stock syslogd. To do this, you
+typically must change your rc.d startup scripts.
+
+For example, under `Debian <http://www.debian.org/>`_ this must be done
+as follows: The default runlevel is 2. We modify the init scripts for
+runlevel 2 - in practice, you need to do this for all run levels you
+will ever use (which probably means all). Under /etc/rc2.d there is a
+S10sysklogd script (actually a symlink). Change the name to
+\_S10sysklogd (this keeps the symlink in place, but will prevent further
+execution - effectively disabling it).
+
+Step 7 - Enable rsyslogd Autostart
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This step is very close to step 3. Now, we want to enable rsyslogd to
+start automatically. The rsyslog package contains a (currently small)
+number of startup scripts. They are inside the distro-specific directory
+(e.g. debian). If there is nothing for your operating system, you can
+simply copy the stock syslogd startup script and make the minor
+modifications to run rsyslogd (the samples should be of help if you
+intend to do this).
+
+In our Debian example, the actual scripts are stored in /etc/init.d.
+Copy the standard script to that location. Then, you need to add a
+symlink to it in the respective rc.d directory. In our sample, we modify
+rc2.d, and can do this via the command "ln -s ../init.d/rsyslogd
+S10rsyslogd". Please note that the S10 prefix tells the system to start
+rsyslogd at the same time stock sysklogd was started.
+
+**Important:** if you use the database functionality, you should make
+sure that MySQL starts before rsyslogd. If it starts later, you will
+receive an error message during each restart (this might be acceptable
+to you). To do so, either move MySQL's start order before rsyslogd or
+rsyslogd's after MySQL.
+
+Step 8 - Check daily cron scripts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Most distributions come pre-configured with some daily scripts for log
+rotation. As long as you use the same log file names, the log rotation
+scripts will probably work quite well. There is one caveat, though. The
+scripts need to tell syslogd that the files have been rotated. To do
+this, they typically have a part using syslogd's init script to do that.
+Obviously, scripts for other default daemons do not know about rsyslogd, so they
+manipulate the other one. If that happens, in most cases an additional
+instance of that daemon is started.  It also means that rsyslogd
+is not properly told about the log rotation, which will lead it to
+continue to write to the now-rotated files.
+
+So you need to fix these scripts. See your distro-specific documentation
+how they are located.
+
+Done
+~~~~
+
+This concludes the steps necessary to install rsyslog. Of course, it is
+always a good idea to test everything thoroughly. At a minimalist level,
+you should do a reboot and after that check if everything has come up
+correctly. Pay attention not only to running processes, but also check
+if the log files (or the database) are correctly being populated.
+
+If rsyslogd encounters any serious errors during startup, you should be
+able to see them at least on the system console. They might not be in
+log file, as errors might occur before the log file rules are in place.
+So it is always a good idea to check system console output when things
+don't go smooth. In some rare cases, enabling debug logging (-d option)
+in rsyslogd can be helpful. If all fails, go to
+`www.rsyslog.com <http://www.rsyslog.com>`_ and check the forum or
+mailing list for help with your issue.
diff --git a/source/installation/packages.rst b/source/installation/packages.rst
new file mode 100644
index 0000000..2373f2a
--- /dev/null
+++ b/source/installation/packages.rst
@@ -0,0 +1,65 @@
+Installing rsyslog from Package
+===============================
+Installing from package is usually the most convenient way to install
+rsyslog. Usually, the regular package manager can be used.
+
+Package Availability
+--------------------
+
+**Rsyslog is included in all major distributions.** So you do not
+necessarily need to take care of where packages can be found - they
+are "just there". Unfortunately, the distros provide often rather old
+versions. This is especially the case for so-called enterprise
+distributions.
+
+As long as you do not run into trouble with one of these old versions, using
+the distribution-provided packages is easy and a good idea. If you need
+new features, better performance and sometimes even a fix for a bug that
+the distro did not backport, you can use alternative packages. Please note
+that the project team does not support outdated versions. While we probably
+can help with simple config questions, for anything else we concentrate on
+current versions.
+
+The rsyslog project offers current packages for a number of major distributions.
+More information about these can be found at the |RsyslogPackageDownloads|_
+page.
+
+If you do not find a suitable package for your distribution, there is no
+reason to panic. You can use official rsyslog docker containers or
+install rsyslog from the source tarball.
+
+.. seealso::
+
+   - :doc:`rsyslog_docker`
+   - :doc:`install_from_source`
+
+Package Structure
+-----------------
+Almost all distributions package rsyslog in multiple packages. This is also
+the way Adiscon packages are created. The reason is that rsyslog has so many
+input and output plugins that enable it to connect to different systems
+like MariaDB/mysql, Kafka, ElasticSearch and so on. If everything were provided in a
+single gigantic package, you would need to install all of these dependencies,
+even though they are mostly not needed.
+
+For that reason, rsyslog comes with multiple packages:
+
+* *core package* (usually just called "rsyslog") - this contains core
+  technology that is required as a base for all other packages. It also
+  contains modules like the file writer or syslog forwarder that is extremely
+  often used and has little dependencies.
+* *feature package* (usually called "rsyslog-feature") - there are
+  multiple of these packages. What exactly is available and how it is
+  named depends on the distro. This unfortunately is a bit inconsistent.
+  Usually, it is a good guess that the package is intuitively named,
+  e.g. "rsyslog-mysql" for the MySQL component and "rsyslog-elasticsearch"
+  for ElasticSearch support. If in doubt, it is suggested to use the
+  distro's package manager and search for "rsyslog*".
+
+Contributing
+------------
+**Packaging is a community effort.** If you would like to see support for an
+additional distribution and know how to build packages, please consider
+contributing to the project and joining the packaging team. Also, rsyslog's
+presence on github also contains the sources for the currently
+maintained packages. They can be found at the |GitHubSourceProject|_.
diff --git a/source/installation/rsyslog_docker.rst b/source/installation/rsyslog_docker.rst
new file mode 100644
index 0000000..d80987e
--- /dev/null
+++ b/source/installation/rsyslog_docker.rst
@@ -0,0 +1,23 @@
+Using Rsyslog Docker Containers
+===============================
+
+The rsyslog project provides a ready-to-run "syslog appliance" which provides
+all rsyslog features in an easy to use way. To run it, simply do
+
+|DockerApplianceAlpineRun|
+
+Up-to-date information on how to use this container can be found at the
+|DockerApplianceAlpineDockerHubRepo|_.
+
+.. warning::
+
+   The docker containers are currently (early 2018) under development
+   and must be used with some care.
+
+Further Information
+-------------------
+The rsyslog project also provides a number of additional containers for
+different needs (end users, developers, package builders, ...). A full
+overview of what is currently available can be found at the |RsyslogDockerHub|_.
+Source code for the docker containers is kept in Github at
+|GitHubDockerProject|_.