.. syslog_ng-sate-usage:

Syslog-ng usage
===============

The syslog\_ng state modul is to generate syslog-ng
configurations. You can do the following things:

-  generate syslog-ng configuration from YAML,
-  use non-YAML configuration,
-  start, stop or reload syslog-ng.

There is also an execution module, which can check the syntax of the
configuration, get the version and other information about syslog-ng.

Configuration
-------------

The following configuration is an example, how a complete syslog-ng
state configuration looks like:

.. code-block:: yaml

    # Set the location of the configuration file
    "/home/tibi/install/syslog-ng/etc/syslog-ng.conf":
      syslog_ng.set_config_file

    # The syslog-ng and syslog-ng-ctl binaries are here. You needn't use 
    # this method if these binaries can be found in a directory in your PATH.
    "/home/tibi/install/syslog-ng/sbin":
      syslog_ng.set_binary_path

    # Writes the first lines into the config file, also erases its previous
    # content
    "3.6":
      syslog_ng.write_version

    # Some global options
    global_options:
      syslog_ng.config:
        - config:
            options:
              - time_reap: 30
              - mark_freq: 10
              - keep_hostname: "yes"

    s_localhost:
      syslog_ng.config:
        - config:
            source:
              - tcp:
                - ip: "127.0.0.1"
                - port: 1233

    d_log_server:
      syslog_ng.config:
        - config:
            destination:
              - tcp:
                - "127.0.0.1"
                - port: 1234

    l_log_to_central_server:
      syslog_ng.config:
        - config:
            log:
              - source: s_localhost
              - destination: d_log_server

    some_comment:
      syslog_ng.write_config:
        - config: |
            # Multi line
            # comment

    auto_start_or_reload:
      {% set pids = salt["ps.pgrep"]("syslog-ng") %}
      {% if pids == None or pids|length == 0 %}
      syslog_ng.started:
        - user: tibi
      {% else %}
      syslog_ng.reloaded
      {% endif %}

    #auto_stop:
    #  syslog_ng.stopped

The ``3.6``, ``s_devlog``, ``d_log_server``, etc. are identifiers. The
second lines in each block are functions and their first parameter is
their id. The ``- config`` is the second named parameter of the
``syslog_ng.config`` function. This function can generate the syslog-ng
configuration from YAML. If the statement (source, destination, parser,
etc.) has a name, this function uses the id as the name, otherwise (log
statement) it's purpose is like a mandatory comment.

You can use ``set_binary_path`` to set the directory which contains the
syslog-ng and syslog-ng-ctl binaries. If this directory is in your PATH,
you don't need to use this function.

Under ``auto_start_or_reload`` you can see a Jinja template. If
syslog-ng isn't running it will start it, otherwise reload it. It uses
the process name ``syslog-ng`` to determine its running state. I suggest
that you use ``service`` state if it's available on your system.

After execution this example the syslog\_ng state will generate this
file:

.. code-block:: text

    #Generated by Salt on 2014-06-19 16:53:11
    @version: 3.6

    options {
       time_reap(30);
       mark_freq(10);
       keep_hostname(yes);
    };

    source s_localhost {
       tcp(
             ip("127.0.0.1"),
             port(1233)
       );
    };

    destination d_log_server {
       tcp(
             "127.0.0.1",
             port(1234)
       );
    };

    log {
       source(s_localhost);
       destination(d_log_server);
    };

    # Multi line
    # comment

Users can include arbitrary texts in the generated configuration with
using the ``write_config`` function.

Examples
--------

Simple source
~~~~~~~~~~~~~

.. code-block:: text

    source s_tail {
     file(
       "/var/log/apache/access.log",
       follow_freq(1),
       flags(no-parse, validate-utf8)
     );
    };

.. code-block:: yaml

    s_tail:
      # Salt will call the source function of syslog_ng module
      syslog_ng.config:
        - config:
            source:
              - file:
                - file: "/var/log/apache/access.log"
                - follow_freq : 1
                - flags:
                  - no-parse
                  - validate-utf8

OR

.. code-block:: yaml

    s_tail:
      syslog_ng.config:
        - config:
            source:
                - file:
                  - "/var/log/apache/access.log"
                  - follow_freq : 1
                  - flags:
                    - no-parse
                    - validate-utf8

Complex source
~~~~~~~~~~~~~~

.. code-block:: text

    source s_gsoc2014 {
     tcp(
       ip("0.0.0.0"),
       port(1234),
       flags(no-parse)
     );
    };

.. code-block:: yaml

    s_gsoc2014:
      syslog_ng.config:
        - config:
            source:
              - tcp:
                - ip: 0.0.0.0
                - port: 1234
                - flags: no-parse

Filter
~~~~~~

.. code-block:: text

    filter f_json {
     match(
       "@json:"
     );
    };

.. code-block:: yaml

    f_json:
      syslog_ng.config:
        - config:
            filter:
              - match:
                - "@json:"

Template
~~~~~~~~

.. code-block:: text

    template t_demo_filetemplate {
     template(
       "$ISODATE $HOST $MSG "
     );
     template_escape(
       no
     );
    };

.. code-block:: yaml

    t_demo_filetemplate:
      syslog_ng.config:
        -config:
            template:
              - template:
                - "$ISODATE $HOST $MSG\n"
              - template_escape:
                - "no"

Rewrite
~~~~~~~

.. code-block:: text

    rewrite r_set_message_to_MESSAGE {
     set(
       "${.json.message}",
       value("$MESSAGE")
     );
    };

.. code-block:: yaml

    r_set_message_to_MESSAGE:
      syslog_ng.config:
        - config:
            rewrite:
              - set:
                - "${.json.message}"
                - value : "$MESSAGE"

Global options
~~~~~~~~~~~~~~

.. code-block:: text

    options {
       time_reap(30);
       mark_freq(10);
       keep_hostname(yes);
    };

.. code-block:: yaml

    global_options:
      syslog_ng.config:
        - config:
            options:
              - time_reap: 30
              - mark_freq: 10
              - keep_hostname: "yes"

Log
~~~

.. code-block:: text

    log {
     source(s_gsoc2014);
     junction {
      channel {
       filter(f_json);
       parser(p_json);
       rewrite(r_set_json_tag);
       rewrite(r_set_message_to_MESSAGE);
       destination {
        file(
          "/tmp/json-input.log",
          template(t_gsoc2014)
        );
       };
       flags(final);
      };
      channel {
       filter(f_not_json);
       parser {
        syslog-parser(

        );
       };
       rewrite(r_set_syslog_tag);
       flags(final);
      };
     };
     destination {
      file(
        "/tmp/all.log",
        template(t_gsoc2014)
      );
     };
    };

.. code-block:: yaml

    l_gsoc2014:
      syslog_ng.config:
        - config:
            log:
              - source: s_gsoc2014
              - junction:
                - channel:
                  - filter: f_json
                  - parser: p_json
                  - rewrite: r_set_json_tag
                  - rewrite: r_set_message_to_MESSAGE
                  - destination:
                    - file:
                      - "/tmp/json-input.log"
                      - template: t_gsoc2014
                  - flags: final
                - channel:
                  - filter: f_not_json
                  - parser:
                    - syslog-parser: []
                  - rewrite: r_set_syslog_tag
                  - flags: final
              - destination:
                - file:
                  - "/tmp/all.log"
                  - template: t_gsoc2014