initial commit

g3proxy/doc/configuration/log/driver/fluentd.rst

@@ -0,0 +1,140 @@
+.. _configuration_log_driver_fluentd:
+
+fluentd
+=======
+
+.. versionadded:: 1.5.0
+
+The fluentd driver config is is map format.
+
+We can set it to send logs to fluentd / fluent-bit by using it's `Forward Protocol`_.
+
+.. _Forward Protocol: https://github.com/fluent/fluentd/wiki/Forward-Protocol-Specification-v1
+
+The tags in the fluentd event message will be g3proxy.Task / g3proxy.Escape / g3proxy.Resolve for the corresponding logs.
+
+The keys are described below.
+
+address
+-------
+
+**optional**, **type**: :ref:`sockaddr str <conf_value_sockaddr_str>`
+
+Set the tcp address of the fluentd server.
+
+**default**: 127.0.0.1:24224
+
+bind_ip
+-------
+
+**optional**, **type**: :ref:`ip addr str <conf_value_ip_addr_str>`
+
+Set the ip address to bind to for the local socket.
+
+**default**: not set
+
+shared_key
+----------
+
+**optional**, **type**: str
+
+Set the shared key if authentication is required.
+
+The handshake stage will be skipped if shared key is not set.
+
+**default**: not set
+
+username
+--------
+
+**optional**, **type**: str
+
+Set the username if authorization is required.
+
+This will only be used if authorization is required by the server.
+
+**default**: not set
+
+password
+--------
+
+**optional**, **type**: str
+
+Set the password if authorization is required.
+
+This will only be used if authorization is required by the server.
+
+**default**: not set
+
+hostname
+--------
+
+**optional**, **type**: str
+
+Set a custom hostname.
+
+**default**: local hostname
+
+tcp_keepalive
+-------------
+
+**optional**, **type**: :ref:`tcp keepalive <conf_value_tcp_keepalive>`
+
+Set the tcp keepalive config for the connection to fluentd server.
+
+**default**: enabled with system default values
+
+tls_client
+----------
+
+**optional**, **type**: :ref:`openssl tls client config <conf_value_openssl_tls_client_config>`
+
+Enable tls and set the config.
+
+**default**: not set
+
+connect_timeout
+---------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the timeout value for the connection to fluentd server, including tcp connect, tls handshake, fluentd handshake.
+
+**default**: 10s
+
+connect_delay
+-------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the delay time if the connect to fluentd server failed. All messages received will be dropped during this stage.
+
+**default**: 10s
+
+write_timeout
+-------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the write timeout for each message. The message will be dropped if timeout.
+
+default: 1s
+
+flush_interval
+--------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the flush interval for the connection to fluentd server.
+
+**default**: 100ms
+
+retry_queue_len
+---------------
+
+**optional**, **type**: usize
+
+Set how many events will be queued up to retry when connect or write failed.
+Note the write timeout events will be dropped directly.
+
+**default**: 10

g3proxy/doc/configuration/log/driver/index.rst

@@ -0,0 +1,20 @@
+.. _configuration_log_driver:
+
+**********
+Log Driver
+**********
+
+We support the following log drivers:
+
+* journald
+
+* syslog
+
+* fluentd
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Details:
+
+   syslog
+   fluentd

g3proxy/doc/configuration/log/driver/syslog.rst

@@ -0,0 +1,159 @@
+.. _configuration_log_driver_syslog:
+
+syslog
+======
+
+The syslog driver config is is map format.
+
+We can set it to send logs to syslogd, which can be listening on
+
+ * unix socket, which is default
+ * udp socket
+
+The message format can be
+
+ * rfc3164, which is default
+ * rfc5424
+
+The keys are described below.
+
+target_unix
+-----------
+
+**optional**, **type**: mix
+
+You can set this if you want to send syslog to a custom unix socket path.
+
+The value can be a map, with the following keys:
+
+* path
+
+  **required**, **type**: :ref:`absolute path <conf_value_absolute_path>`
+
+  The syslogd daemon listen socket path.
+
+If the value type is str, the value should be the same as the value as *path* above.
+
+**default**: not set
+
+target_udp
+----------
+
+**optional**, **type**: mix
+
+You can set this if you want to send syslog to a remote syslogd which listening on a udp socket.
+
+The value can be a map, with the following keys:
+
+* address
+
+  **required**, **type**: :ref:`sockaddr str <conf_value_sockaddr_str>`
+
+  Set the remote socket address.
+
+* bind_ip
+
+  **optional**, **type**: :ref:`ip addr str <conf_value_ip_addr_str>`
+
+  Set the ip address to bind to for the local socket.
+
+  **default**: not set
+
+If the value type is str, the value should be the same as the value as *address* above.
+
+**default**: not set
+
+target
+------
+
+**optional**, **type**: map
+
+This is just another form to set syslog target address.
+
+The key *udp* is just handled as *target_udp* as above.
+
+The key *unix* is just handled as *target_unix* as above.
+
+.. versionadded:: 1.3.5
+
+format_rfc5424
+--------------
+
+**optional**, **type**: mix
+
+Set this to use rfc5424 message format.
+
+The value can be a map, with the following keys:
+
+* enterprise_id
+
+  **optional**, **type**: int
+
+  Set the enterprise id value as described in `rfc5424`_.
+
+  See `PRIVATE ENTERPRISE NUMBERS`_ for IANA allocated numbers.
+
+  **default**: 0, which is reserved
+
+  .. _rfc5424: https://tools.ietf.org/html/rfc5424
+  .. _PRIVATE ENTERPRISE NUMBERS: https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers
+
+* message_id
+
+  **optional**, **type**: str
+
+  Set the message id.
+
+  **default**: not set
+
+If the value type is int, the value should be the same as the value as *enterprise_id* above.
+If the value type is str, the value should be the same as the value as *message_id* above.
+
+**default**: not set
+
+use_cee_log_syntax
+------------------
+
+**optional**, **type**: bool
+
+Set if we should use `CEE Log Syntax`_.
+
+Enable this option if you need to use rsyslog `mmjsonparse`_ module.
+
+**default**: not set
+
+.. _mmjsonparse: https://www.rsyslog.com/files/temp/doc-indent/configuration/modules/mmjsonparse.html
+.. _CEE Log Syntax: https://cee.mitre.org/language/1.0-beta1/cls.html
+
+cee_event_flag
+--------------
+
+**optional**, **type**: ascii string
+
+Set a custom CEE event flag value. Only meaningful if *use_cee_log_syntax* is set.
+
+The one defined by `CLT`_ is *@cee:*, you can override it by using this option.
+
+**default**: @cee:
+
+.. _CLT: https://cee.mitre.org/language/1.0-beta1/clt.html
+
+emit_hostname
+-------------
+
+**optional**, **type**: bool
+
+Set if we should set hostname in the syslog message header.
+
+**default**: false
+
+.. versionadded:: 1.5.4
+
+append_report_ts
+----------------
+
+**optional**, **type**: bool
+
+Set if we should add :ref:`report_ts <log_shared_keys_report_ts>` to logs.
+
+**default**: false