.. _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 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