.. _syslog-ng-sate-usage:

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

Overview
--------

Syslog\_ng state module is for generating 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
-------------

Users can create syslog-ng configuration statements with the
:py:func:`syslog_ng.config <salt.states.syslog_ng.config>` function. It requires
a `name` and a `config` parameter. The `name` parameter determines the name of
the generated statement and the `config` parameter holds a parsed YAML structure.

A statement can be declared in the following forms (both are equivalent):

.. code-block:: yaml

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

.. code-block:: yaml

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

The first one is called short form, because it needs less typing. Users can use lists
and dictionaries to specify their configuration. The format is quite self describing and
there are more examples [at the end](#examples) of this document.

Quotation
---------

The quotation can be tricky sometimes but here are some rules to follow:
 * when a string meant to be ``"string"`` in the generated configuration, it should be like ``'"string"'`` in the YAML document
 * similarly, users should write ``"'string'"`` to get ``'string'`` in the generated configuration

Full example
------------

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

.. code-block:: yaml

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

    # 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.
    set_bin_path:
      module.run:
        - name: syslog_ng.set_binary_path
        - m_name: "/home/tibi/install/syslog-ng/sbin"

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

    # There is a shorter form to set the above variables
    set_variables:
      module.run:
        - name: syslog_ng.set_parameters
        - version: "3.6"
        - binary_path: "/home/tibi/install/syslog-ng/sbin"
        - config_file: "/home/tibi/install/syslog-ng/etc/syslog-ng.conf"


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

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

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

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

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

    # Another mode to use comments or existing configuration snippets
    config.other_comment_form:
      syslog_ng.config:
        - config: |
            # Multi line
            # comment



The :py:func:`syslog_ng.reloaded <salt.states.syslog_ng.reloaded>` function can generate 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) its purpose is like a mandatory comment.

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

.. code-block:: text

  #Generated by Salt on 2014-08-18 00:11: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


  # Multi line
  # comment


Users can include arbitrary texts in the generated configuration with
using the ``config`` statement (see the example above).

Syslog_ng module functions
--------------------------

You can use :py:func:`syslog_ng.set_binary_path <salt.modules.syslog_ng.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. There is also a  :py:func:`syslog_ng.set_config_file <salt.modules.syslog_ng.set_config_file>`
function to set the location of the configuration file.

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

OR

.. code-block:: yaml

    source.s_tail:
      syslog_ng.config:
        - config:
            - 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