Search documentation of jhn_stdlib

# jhn_syslog (jhn_stdlib v5.10.3)

View Source

A Syslog library based on: The Syslog Protocol (rfc5424) Transport Layer Security (TLS) Transport Mapping for Syslog (rfc5425) Transmission of Syslog Messages over UDP (rfc5426) Textual Conventions for Syslog Management (rfc5427) Transmission of Syslog Messages over TCP (rfc6587) Datagram Transport Layer Security (DTLS) Transport Mapping for Syslog (rfc6012)

SYSLOG line is represented as follows:

line : #{header => Header, structured => Structured, msg => Message }

Header : #{facility => Facility, severity => Severity, version => Version, time_stamp => TimeStamp, fraction => integer(), offset_sign => '+' | '-' | 'Z', offset => {Hour, Minute}, host_name => iodata(), app_name => iodata(), proc_id => iodata(), msg_id => iodata() }

Facility : kern | user | mail | daemon | auth | syslog | lpr | news | uucp | cron | authpriv | ftp | ntp | audit | console | cron2 | local0 | local1 | local2 | local3 | local4 | local5 | local6 | local7 default: user Severity : emerg | alert | crit | err | warning | notice | info | debug default: info Version : integer() default: 1 TimeStamp : binary() | {{Year, Month, Day}, {Hour, Minute, Second}} | #{year => Year, month => Month, day => Day, hour =>Hour, minute => Minute, second => Second} Year, Month, Day, Hour, Minute, Second : integer()

Structured : [{Id, [{Key, Value}]}] Id, Key, Value : iodata()

Message : #{type => utf8 | any, content => iodata() }

All part of the map are optional. All iodata is in fact a binary when a line is decoded. All header values that can be represented by the nil element "-" has that as default and when decoded omitted from the returned map.

N.B. TCP only supports Octet counting framing. The TLS transport requires the ssl OTP lib which is not included in the application resource file. The DTLS transport requires the ssl OTP lib which is not included in the application resource file.

# Summary

## Types

line/0
listen_type/0
opt/0
socket_options/0
transport/0
type/0

## Functions

accept(Transport)

Accepts an incoming connection request on an opened server transport for the TCP and TLS, it returns a connected transport. Equivalent to accept(Transport, []).

accept(Transport, Opts)

Accepts an incoming connection request on an opened server transport for the TCP and TLS, it returns a connected transport.

close(Transport)

Closes an already established transport.

controlling_process(Transport, Pid)

Assigns a new controlling process Pid to the Transport socket.

decode(Binary)

Decodes the binary into a structured Erlang term. Equivalent to decode(Binary, [])

decode(Binary, Opts)

Decodes the binary into a structured Erlang. Decode will give an exception if the binary is not well formed Syslog line.

encode(Line)

Encodes the structured Erlang term as an iolist. Equivalent to encode(Line, []).

encode(Line, Opts)

Encodes the structured Erlang term as an iolist or binary. Encode will give an exception if the erlang term is not well formed. Options are: seconds (default) -> second precision milli -> milli second precision micro -> micro second precision binary -> a binary is returned iolist -> a iolist is returned

frame(_, Data)

Encloses an encoded line in an octet counting frame.

open()

Opens an UDP client or server transport. Equivalent to open([]).

open(Opts)

Opens a Transport returning a connected client connection or a listen port for DTLS/TCP/TLS for the server, UDP the difference is quite moot.

recv(Transport)

Receives a packet from a Transport socket in passive mode. A closed socket is indicated by a return value {error, closed}. Equivalent to recv(Line, []).

recv(Transport, Opts)

Receives a packet from a Transport socket in passive mode. A closed socket is indicated by a return value {error, closed}.

send(Transport, Line)

Sends a message over the transport. Equivalent to Send(Transport, Line).

send(Transport, Line, Opts)

Sends a message over the transport.

setopts(Transport, Options)

Sets one or more options for a transport socket according to the transport.

unframe(_, Data)

Extracts the line from an octet counting frame.

# Types

# line/0

    -type line() :: map().

# listen_type/0

    -type listen_type() :: dtls_listen | tcp_listen | tls_listen.

# opt/0

    -type opt() :: _.

# socket_options/0

    -type socket_options() :: gen_udp:option() | gen_tcp:option() | ssl:socket_option() | ssl:tls_option().

# transport/0

    -type transport() ::
              #transport{type :: type() | listen_type(),
                         role :: client | server,
                         port :: inet:port_number() | undefined,
                         ipv :: ipv4 | ipv6 | undefined,
                         dest :: inet:ip_address() | inet:hostname(),
                         dest_port :: inet:port_number() | undefined,
                         socket :: gen_udp:socket() | gen_tcp:socket() | ssl:sslsocket() | undefined,
                         listen_socket :: gen_tcp:socket() | ssl:sslsocket() | undefined,
                         buf :: binary()}.

# type/0

    -type type() :: udp | dtls | tcp | tls.

# Functions

# accept(Transport)

    -spec accept(transport()) -> transport() | {error, _}.

Accepts an incoming connection request on an opened server transport for the TCP and TLS, it returns a connected transport. Equivalent to accept(Transport, []).

# accept(Transport, Opts)

    -spec accept(transport(), [opt()]) -> transport() | {error, _}.

Accepts an incoming connection request on an opened server transport for the TCP and TLS, it returns a connected transport.

Options are: timeout -> the time in milliseconds the request is allowed to complete

# close(Transport)

    -spec close(transport()) -> ok | {error, _}.

Closes an already established transport.

# controlling_process(Transport, Pid)

    -spec controlling_process(transport(), pid()) -> ok | {error, _}.

Assigns a new controlling process Pid to the Transport socket.

# decode(Binary)

    -spec decode(binary()) -> line().

Decodes the binary into a structured Erlang term. Equivalent to decode(Binary, [])

# decode(Binary, Opts)

    -spec decode(binary(),
                 [opt()] |
                 #opts{type :: type(),
                       role :: client | server,
                       port :: integer() | undefined,
                       opts :: [{atom(), _}],
                       ipv :: ipv4 | ipv6,
                       dest :: inet:ip_address() | inet:hostname(),
                       dest_port :: inet:port_number() | undefined,
                       precision :: seconds | milli | micro,
                       timeout :: integer() | undefined,
                       version :: 'tlsv1.2' | 'tlsv1.3',
                       return_type :: iolist | binary}) ->
                    line().

Decodes the binary into a structured Erlang. Decode will give an exception if the binary is not well formed Syslog line.

Options are: currently none N.B. the timestamp is decode into a date time tuple.

# encode(Line)

    -spec encode(line()) -> iolist().

Encodes the structured Erlang term as an iolist. Equivalent to encode(Line, []).

# encode(Line, Opts)

    -spec encode(line(),
                 [opt()] |
                 #opts{type :: type(),
                       role :: client | server,
                       port :: integer() | undefined,
                       opts :: [{atom(), _}],
                       ipv :: ipv4 | ipv6,
                       dest :: inet:ip_address() | inet:hostname(),
                       dest_port :: inet:port_number() | undefined,
                       precision :: seconds | milli | micro,
                       timeout :: integer() | undefined,
                       version :: 'tlsv1.2' | 'tlsv1.3',
                       return_type :: iolist | binary}) ->
                    iolist() | binary().

Encodes the structured Erlang term as an iolist or binary. Encode will give an exception if the erlang term is not well formed. Options are: seconds (default) -> second precision milli -> milli second precision micro -> micro second precision binary -> a binary is returned iolist -> a iolist is returned

# frame(_, Data)

    -spec frame(type(), iodata()) -> iodata().

Encloses an encoded line in an octet counting frame.

# open()

    -spec open() -> transport() | {error, _}.

Opens an UDP client or server transport. Equivalent to open([]).

# open(Opts)

    -spec open([opt()] |
               #opts{type :: type(),
                     role :: client | server,
                     port :: integer() | undefined,
                     opts :: [{atom(), _}],
                     ipv :: ipv4 | ipv6,
                     dest :: inet:ip_address() | inet:hostname(),
                     dest_port :: inet:port_number() | undefined,
                     precision :: seconds | milli | micro,
                     timeout :: integer() | undefined,
                     version :: 'tlsv1.2' | 'tlsv1.3',
                     return_type :: iolist | binary}) ->
                  transport() | {error, _}.

Opens a Transport returning a connected client connection or a listen port for DTLS/TCP/TLS for the server, UDP the difference is quite moot.

Options are: client -> opens a client transport (default) server -> open a server transport udp -> uses the UDP protocol (default) dtls -> uses the DTLS v1.2 over UDP tcp -> uses the TCP protocol tls -> uses TLS v1.2(default) or TLS v1.3 over TCP ipv4 -> IPv4 addresses are used (default) ipv6 -> IPv6 addresses are used port -> The port used by client or server with the default in the client case is 0 (the underlying OS assigns an available port number) for the server the default ports are as follows: UDP/514, UDP/6514, TCP/601, TLS/6514 destination -> the IP address or hostname of the server to connect to in the case TCP and TLS and the default server for the UDP/DTLS case destination_port -> the port of the server to connect to in the case TCP/TLS and the default server for the UDP/DTLS case version -> the version used for TLS, v1.2(default) or v1.3. opts -> options to the transport's UDP, DTLS, TCP, or TLS, see the documentation of gen_udp, gen_tcp, ssl respectively timeout -> the time in milliseconds the request is allowed to complete

# recv(Transport)

    -spec recv(transport()) -> {ok, line()} | {ok, line(), transport()} | {error, _}.

Receives a packet from a Transport socket in passive mode. A closed socket is indicated by a return value {error, closed}. Equivalent to recv(Line, []).

# recv(Transport, Opts)

    -spec recv(transport(),
               [opt()] |
               #opts{type :: type(),
                     role :: client | server,
                     port :: integer() | undefined,
                     opts :: [{atom(), _}],
                     ipv :: ipv4 | ipv6,
                     dest :: inet:ip_address() | inet:hostname(),
                     dest_port :: inet:port_number() | undefined,
                     precision :: seconds | milli | micro,
                     timeout :: integer() | undefined,
                     version :: 'tlsv1.2' | 'tlsv1.3',
                     return_type :: iolist | binary}) ->
                  {ok, line()} | {ok, line(), transport()} | {error, _}.

Receives a packet from a Transport socket in passive mode. A closed socket is indicated by a return value {error, closed}.

Options are: timeout -> the time in milliseconds the request is allowed to complete

# send(Transport, Line)

    -spec send(transport(), line()) -> ok | {error, _}.

Sends a message over the transport. Equivalent to Send(Transport, Line).

# send(Transport, Line, Opts)

    -spec send(transport(),
               line(),
               [opt()] |
               #opts{type :: type(),
                     role :: client | server,
                     port :: integer() | undefined,
                     opts :: [{atom(), _}],
                     ipv :: ipv4 | ipv6,
                     dest :: inet:ip_address() | inet:hostname(),
                     dest_port :: inet:port_number() | undefined,
                     precision :: seconds | milli | micro,
                     timeout :: integer() | undefined,
                     version :: 'tlsv1.2' | 'tlsv1.3',
                     return_type :: iolist | binary}) ->
                  ok | {error, _}.

Sends a message over the transport.

Options are: seconds (default) -> second precision milli -> milli second precision micro -> micro second precision destination -> the IP address or hostname of the peer to send to in the UDP case, otherwise the default provided in open is used destination_port -> the port of the peer in the UDP case

# setopts(Transport, Options)

    -spec setopts(transport(), socket_options()) -> ok | {error, _}.

Sets one or more options for a transport socket according to the transport.

# unframe(_, Data)

    -spec unframe(type(), binary()) -> {binary(), iodata()} | {more, integer()}.

Extracts the line from an octet counting frame.