network: Send messages to a remote log server using the RFC3164 protocol (network() driver)

The network() destination driver can send syslog messages conforming to RFC3164 from the network using the TCP, TLS, and UDP networking protocols.

• UDP is a simple datagram oriented protocol, which provides “best effort service” to transfer messages between hosts. It may lose messages, and no attempt is made to retransmit lost messages. The BSD-syslog protocol traditionally uses UDP.

  Use UDP only if you have no other choice.

• TCP provides connection-oriented service: the client and the server establish a connection, each message is acknowledged, and lost packets are resent. TCP can detect lost connections, and messages are lost, only if the TCP connection breaks. When a TCP connection is broken, messages that the client has sent but were not yet received on the server are lost.

• The AxoSyslog application supports TLS (Transport Layer Security, also known as SSL) over TCP. For details, see Encrypting log messages with TLS.

Declaration:

   network("<destination-address>" [options]);

The network() destination has a single required parameter that specifies the destination host address where messages should be sent. If name resolution is configured, you can use the hostname of the target server. By default, AxoSyslog sends messages using the TCP protocol to port 514.

Example: Using the network() driver

TCP destination that sends messages to 10.1.2.3, port 1999:

   destination d_tcp { network("10.1.2.3" port(1999)); };

If name resolution is configured, you can use the hostname of the target server as well.

   destination d_tcp { network("target_host" port(1999)); };

TCP destination that sends messages to the ::1 IPv6 address, port 2222.

   destination d_tcp6 {
        network(
            "::1"
            port(2222)
            transport(tcp)
            ip-protocol(6)
            );
    };

To send messages using the IETF-syslog message format without using the IETF-syslog protocol, enable the syslog-protocol flag. (For details on how to use the IETF-syslog protocol, see syslog() destination options.)

   destination d_tcp { network("10.1.2.3" port(1999) flags(syslog-protocol) ); };

Batching writes with flush-lines()

Available in AxoSyslog 4.26 and later.

When a network() or tcp() destination uses a TCP or TLS transport, AxoSyslog writes several messages to the transport with a single operation instead of one per message. It accumulates up to flush-lines() formatted messages and sends them together: over TCP as one writev() system call, and over TLS as few SSL_write() calls as fit into a TLS record. Fewer system calls per message reduces overhead and can increase throughput. As with flush-lines() on any destination, larger batches trade a small amount of latency for that throughput, because a message can wait for the batch to fill (or for the queue to empty) before it is sent.

This applies only to the stream-based transports. UDP destinations are unaffected, because each datagram already carries exactly one message, and the syslog() destination is unaffected as well, because it frames every message individually.

Controlling the behavior with the configuration version

The global default of flush-lines() is 100, so batching is enabled by default once your configuration declares @version: 4.26 (or later). Configurations that declare an older version keep the previous one-write-per-message behavior, so that upgrading AxoSyslog does not silently change how an existing configuration sends messages.

If your configuration declares a version older than 4.26 and does not set flush-lines() on the destination, AxoSyslog logs a warning once and keeps the pre-4.26 behavior. To adopt batching and stop the warning, either raise the configuration version to 4.26 or set flush-lines() explicitly on the destination. Setting flush-lines() explicitly always takes effect, regardless of the configuration version.

To keep (or restore) one write per message, set flush-lines(1):

   destination d_tcp { network("10.1.2.3" port(1999) flush-lines(1)); };