# 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 `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):

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

    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:

    # 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 `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:

    #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 `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 `syslog_ng.set_config_file` function to set the location of the configuration file.

## Examples

### Simple source

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

    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

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

OR

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

### Complex source

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

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

### Filter

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

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

### Template

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

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

### Rewrite

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

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

### Global options

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

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

### Log

    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)
      );
     };
    };

    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