# syslog

![](https://1982584918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LR7OsqPORtP86IQxs6E-694727794%2Fuploads%2Fgit-blob-15307d6422903c5057657bcae4ecf8e128b1b0f6%2Fsyslog.png?alt=media)

The `in_syslog` Input plugin enables Fluentd to retrieve records via the syslog protocol on UDP or TCP.

It is included in Fluentd's core.

## Example Configuration

```
<source>
  @type syslog
  port 5140
  bind 0.0.0.0
  tag system
</source>
```

This tells Fluentd to create a socket listening on port 5140. You need to set up your `syslog` daemon to send messages to the socket. For example, if you're using `rsyslogd`, add the following lines to `/etc/rsyslog.conf`:

```
# Send log messages to Fluentd
*.* @127.0.0.1:5140
```

### Example Usage

The retrieved data is organized as follows. Fluentd's tag is generated by the `tag` parameter (tag prefix), [facility level](http://en.wikipedia.org/wiki/Syslog#Facility_Levels), and [priority](http://en.wikipedia.org/wiki/Syslog#Severity_levels). The record is parsed by the `regexp` [here](https://github.com/fluent/fluentd/blob/master/lib/fluent/plugin/parser_syslog.rb#L23).

```
tag = "#{@tag}.#{facility}.#{priority}"
time = 1353436518,
record = {
  "host": "host",
  "ident": "ident",
  "pid": "12345",
  "message": "text"
}
```

If you want to keep facility and priority in the record, set related parameters.

## Plugin Helpers

* [`parser`](https://docs.fluentd.org/plugin-helper-overview/api-plugin-helper-parser)
* [`compat_parameters`](https://docs.fluentd.org/plugin-helper-overview/api-plugin-helper-compat_parameters)
* [`server`](https://docs.fluentd.org/plugin-helper-overview/api-plugin-helper-server)

## Parameters

See [Common Parameters](https://docs.fluentd.org/configuration/plugin-common-parameters).

### `@type` (required)

The value must be `syslog`.

### `tag` (required)

The prefix of the tag. The tag itself is generated by the tag prefix, [facility level](http://en.wikipedia.org/wiki/Syslog#Facility_Levels), and [priority](http://en.wikipedia.org/wiki/Syslog#Severity_levels).

### `port`

| type    | default | version |
| ------- | ------- | ------- |
| integer | 5140    | 0.14.0  |

The port to listen to.

### `bind`

| type   | default                 | version |
| ------ | ----------------------- | ------- |
| string | 0.0.0.0 (all addresses) | 0.14.0  |

The bind address to listen to.

### `protocol_type`

| type | default | available values | version |
| ---- | ------- | ---------------- | ------- |
| enum | udp     | udp/tcp          | 0.14.0  |

The transport protocol used to receive logs. `udp` and `tcp` are supported.

This parameter is deprecated since v1.5. Use `<transport>` instead.

### `<transport>` Section

| type | default | available values | version |
| ---- | ------- | ---------------- | ------- |
| enum | udp     | udp/tcp/tls      | 1.5.0   |

The protocol of the `syslog` transport.

```
<source>
  @type syslog
  tag system
  <transport tcp>
  </transport>
  # other parameters
</source>
```

This section is for setting TLS transport or some general transport configurations. See **How to Enable TLS Encryption** section for how to use and see [Configuration Example](https://docs.fluentd.org/plugin-helper-overview/api-plugin-helper-server#configuration-example) and [Config: Transport Section](https://docs.fluentd.org/configuration/transport-section) for all supported parameters.

### `message_length_limit`

| type | default | version |
| ---- | ------- | ------- |
| size | 2048    | 0.14.2  |

The maximum length of a syslog message in bytes. If you send a larger message, change this parameter.

### `frame_type`

| type |   default   | available values         | version |
| :--: | :---------: | ------------------------ | ------- |
| enum | traditional | traditional/octet\_count | 1.3.0   |

Specifies the framing type in TCP protocol.

* `traditional`

Messages are delimited by newline(`\n`):

```
<6>Sep 10 00:00:00 localhost logger: hello!\n
```

* `octet_count`

Message has the message size prefix to delimit:

```
43 <6>Sep 10 00:00:00 localhost logger: hello!
```

See also [RFC 6587](https://tools.ietf.org/html/rfc6587#section-3.4).

### `format`

Deprecated parameter. Use `<parse>` instead.

### `<parse>` Directive

The format of the log. This option is used to parse non-standard syslog formats using [parser plugins](https://docs.fluentd.org/parser).

```
<source>
  @type syslog
  tag system
  <parse>
    @type FORMAT_PARAMETER
  </parse>
</source>
```

Your `<parse>` regexp should not consider the 'priority' prefix of the log. For example, if `in_syslog` receives the log below:

```
<1>Feb 20 00:00:00 192.168.0.1 fluentd[11111]: [error] hogehoge
```

Then, the format parser receives the following log:

```
Feb 20 00:00:00 192.168.0.1 fluentd[11111]: [error] hogehoge
```

If the `<parse>/@type` parameter is missing, the log data is assumed to have the canonical `syslog` format. It is same with the following configuration:

```
<parse>
  @type syslog
  with_priority true
</parse>
```

### `message_format`

| type | default | available values     | version |
| ---- | ------- | -------------------- | ------- |
| enum | rfc3164 | rfc3164/rfc5424/auto | 0.14.14 |

This parameter is used inside `<parse>` directive. The default is `rfc3164`.

```
<source>
  @type syslog
  tag system
  <parse>
    message_format rfc5424
  </parse>
</source>
```

Specifies the protocol format. Supported values are `rfc3164`, `rfc5424` and `auto`. If your syslog uses `rfc5424`, use `rfc5424` instead. Here is an example of message:

```
# rfc3164
<6>Feb 28 12:00:00 192.168.0.1 fluentd[11111]: [error] Hello!
# rfc5424
<16>1 2017-02-28T12:00:00.009Z 192.168.0.1 fluentd - - - Hello!
```

`auto` is useful when `in_syslog` receives both `rfc3164` and `rfc5424` message per source. `in_syslog` detects message format by using message prefix and parses it.

### `with_priority`

| type | default | version |
| ---- | ------- | ------- |
| bool | true    | 0.14.0  |

This parameter is used inside `<parse>` directive.

```
<source>
  @type syslog
  tag system
  <parse>
    with_priority false
  </parse>
</source>
```

If `with_priority` is `true`, then syslog messages are assumed to be prefixed with a priority tag like `<3>`. This option exists since some syslog daemons output logs without the priority tag preceding the message body.

If you wish to parse syslog messages of arbitrary formats, [`in_tcp`](https://docs.fluentd.org/input/tcp) or [`in_udp`](https://docs.fluentd.org/input/udp) are recommended.

### `emit_unmatched_lines`

| type | default | version |
| ---- | ------- | ------- |
| bool | false   | 1.6.3   |

Emits unmatched lines when `<parse>` format is not matched for incoming logs.

Emitted record is `{"unmatched_line" : "incoming line"}` with `${tag parameter}.unmatched` tag.

### `resolve_hostname`

| type | default | version |
| ---- | ------- | ------- |
| bool | nil     | 0.14.19 |

Tries to resolve hostname from IP addresses or not. Cannot set `false` when `source_hostname_key` is set.

### `send_keepalive_packet`

| type | default | version |
| ---- | ------- | ------- |
| bool | false   | 1.14.0  |

Enables the TCP keepalive for sockets. See [socket article](https://docs.fluentd.org/plugin-helper-overview/api-plugin-helper-socket#send_keepalive_packet-use-case) for more details.

### `source_hostname_key`

| type   | default         | version |
| ------ | --------------- | ------- |
| string | nil (no assign) | 0.14.0  |

The field name of the client's hostname. If set, the client's hostname will be set to its key.

### `source_address_key`

| type   | default         | version |
| ------ | --------------- | ------- |
| string | nil (no assign) | 0.14.0  |

The field name of the client's address. If set, the client's address will be set to its key.

### `severity_key`

| type   | default         | version |
| ------ | --------------- | ------- |
| string | nil (no assign) | 1.7.3   |

The field name of the severity. If set, the severity will be set to its key.

If you set `severity_key severity` and got `<6>` started syslog message, `severity` field is `info`.

### `priority_key`

| type   | default         | version |
| ------ | --------------- | ------- |
| string | nil (no assign) | 0.14.10 |

This parameter is deprecated due to a misleading name. This sets severity, not priority.

This parameter will be removed in fluentd v2. Use `severity_key` instead.

### `facility_key`

| type   | default         | version |
| ------ | --------------- | ------- |
| string | nil (no assign) | 0.14.10 |

The field name of the facility. If set, the facility will be set to its key.

If you set `facility_key facility` and got `<6>` started syslog message, `facility` field is `kern`.

#### `@log_level`

The `@log_level` option allows the user to set different levels of logging for each plugin. The supported log levels are: `fatal`, `error`, `warn`, `info`, `debug`, and `trace`.

Please see the [logging article](https://docs.fluentd.org/deployment/logging) for further details.

## TCP Protocol and Message Delimiter

This plugin assumes `\n` for delimiter character between syslog messages in one TCP connection by default. If you use syslog library in your application with `<transport tcp>`, add `\n` to your syslog message. See also [rfc6587](https://tools.ietf.org/html/rfc6587#section-3.4.2).

If your syslog uses octet counting mode, set `frame_type octet_count` in `in_syslog` configuration. See also `frame_type` parameter.

## Tips

### How to Enable TLS Encryption

Since v1.5.0, `in_syslog` support TLS transport. Here is the configuration example with `rsyslog`:

* `in_syslog`

```
<source>
  @type syslog
  port 5140
  bind 0.0.0.0
  <transport tls>
    ca_path /etc/pki/ca.pem
    cert_path /etc/pki/cert.pem
    private_key_path /etc/pki/key.pem
    private_key_passphrase PASSPHRASE
  </transport>
  tag system
</source>
```

* `rsyslog`

```
$DefaultNetstreamDriverCAFile /etc/pki/ca.pem
$DefaultNetstreamDriver gtls
$ActionSendStreamDriverMode 1
$ActionSendStreamDriverAuthMode anon
*.* @@127.0.0.1:5140
```

### Multi-process Environment

If you use this plugin under the multi-process environment, the port will be shared.

```
<system>
  workers 3
</system>

<source>
  @type syslog
  port 5140
</source>
```

With this configuration, 3 workers share 5140 port. No need of an additional port. The incoming data will be routed to the three (3) workers automatically.

## FAQ

### Our system sends RFC3164/RFC5424 message but parse failure happens

First, check your message format follows RFC3164/RFC5424 or not. Some systems say RFC3164/RFC5424 but it sends non-RFC3164/RFC5424 message, e.g. invalid priority, different timestamp, lack/add fields.

If only timestamp is different, configure `time_format` in `<parse>` may help.

If other parts are different, the `syslog` parser cannot parse your message. To resolve the problem, there are several approaches:

* Use `regex` parser or write your parser
* Use `in_udp`/`in_tcp` with other parsers

## Learn More

* [Input Plugin Overview](https://docs.fluentd.org/input)

If this article is incorrect or outdated, or omits critical information, please [let us know](https://github.com/fluent/fluentd-docs-gitbook/issues?state=open). [Fluentd](http://www.fluentd.org/) is an open-source project under [Cloud Native Computing Foundation (CNCF)](https://cncf.io/). All components are available under the Apache 2 License.