| Overview |  |
Copyright © (C) 2016-2020, Jan Henry Nystrom <JanHenryNystrom@gmail.com> -------------------------------------------------------------------
Authors: Jan Henry Nystrom (JanHenryNystrom@gmail.com).
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)
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. Only supports R18 and later.line() = map()
opt() = term()
socket_options() = gen_udp:option() | gen_tcp:option() | ssl:option()
transport() = #transport{type = type() | tcp_listen | tls_listen, role = client | server, port = inet:port(), ipv = ipv4 | ipv6, dest = inet:ip_address() | inet:hostname(), dest_port = inet:port(), socket = gen_udp:socket() | gen_tcp:socket() | ssl:socket(), listen_socket = gen_tcp:socket() | ssl:socket(), buf = binary()}
type() = udp | tcp | tls
| accept/1 | Accepts an incoming connection request on an opened server transport for the TCP and TLS, it returns a connected transport. |
| accept/2 | Accepts an incoming connection request on an opened server transport for the TCP and TLS, it returns a connected transport. |
| close/1 | Closes an already established transport. |
| controlling_process/2 | Assigns a new controlling process Pid to the Transport socket. |
| decode/1 | Decodes the binary into a structured Erlang term. |
| decode/2 | Decodes the binary into a structured Erlang. |
| encode/1 | Encodes the structured Erlang term as an iolist. |
| encode/2 | Encodes the structured Erlang term as an iolist or binary. |
| frame/2 | Encloses an encoded line in an octet counting frame. |
| open/0 | Opens an UDP client or server transport. |
| open/1 | Opens a Transport returning a connected client connection or a listen port for TCP and TLS for the server, UDP the difference is quite moot. |
| recv/1 | Receives a packet from a Transport socket in passive mode. |
| recv/2 | Receives a packet from a Transport socket in passive mode. |
| send/2 | Sends a message over the transport. |
| send/3 | Sends a message over the transport. |
| setopts/2 | Sets one or more options for a transport socket according to the transport. |
| unframe/2 | Extracts the line from an octet counting frame. |
accept(Transport::transport()) -> transport() | {error, term()}
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::transport(), Opts::[opt()]) -> transport() | {error, term()}
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 completeclose(Transport::transport()) -> ok | {error, term()}
Closes an already established transport.
controlling_process(Transport::transport(), Pid::pid()) -> ok | {error, term()}
Assigns a new controlling process Pid to the Transport socket.
decode(Binary::binary()) -> line()
Decodes the binary into a structured Erlang term. Equivalent to decode(Binary, [])
decode(Binary::binary(), Opts::[opt()] | #opts{type = type(), role = client | server, port = integer(), opts = [{atom(), term()}], ipv = ipv4 | ipv6, dest = inet:ip_address() | inet:hostname(), dest_port = inet:port(), precision = seconds | milli | micro, timeout = integer(), 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::line()) -> iolist()
Encodes the structured Erlang term as an iolist. Equivalent to encode(Line, []).
encode(Line::line(), Opts::[opt()] | #opts{type = type(), role = client | server, port = integer(), opts = [{atom(), term()}], ipv = ipv4 | ipv6, dest = inet:ip_address() | inet:hostname(), dest_port = inet:port(), precision = seconds | milli | micro, timeout = integer(), 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(X1::type(), Data::iodata()) -> iodata()
Encloses an encoded line in an octet counting frame.
open() -> transport() | {error, term()}
Opens an UDP client or server transport. Equivalent to open([]).
open(Opts::[opt()] | #opts{type = type(), role = client | server, port = integer(), opts = [{atom(), term()}], ipv = ipv4 | ipv6, dest = inet:ip_address() | inet:hostname(), dest_port = inet:port(), precision = seconds | milli | micro, timeout = integer(), return_type = iolist | binary}) -> transport() | {error, term()}
Opens a Transport returning a connected client connection or a listen port for TCP and 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) tcp -> uses the TCP protocol tls -> uses TLS v1.2 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, 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 case destination_port -> the port of the server to connect to in the case TCP and TLS and the default server for the UDP case opts -> options to the transport's UDP, TCP, or TLS, see the documentation of gen_udp, gen_tcp, ssl respectively timeout -> the time in milliseconds the request is allowed to completerecv(Transport::transport()) -> {ok, line()} | {ok, line(), transport()} | {error, term()}
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::transport(), Opts::[opt()] | #opts{type = type(), role = client | server, port = integer(), opts = [{atom(), term()}], ipv = ipv4 | ipv6, dest = inet:ip_address() | inet:hostname(), dest_port = inet:port(), precision = seconds | milli | micro, timeout = integer(), return_type = iolist | binary}) -> {ok, line()} | {ok, line(), transport()} | {error, term()}
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 completesend(Transport::transport(), Line::line()) -> ok | {error, term()}
Sends a message over the transport. Equivalent to Send(Transport, Line).
send(Transport::transport(), Line::line(), Opts::[opt()] | #opts{type = type(), role = client | server, port = integer(), opts = [{atom(), term()}], ipv = ipv4 | ipv6, dest = inet:ip_address() | inet:hostname(), dest_port = inet:port(), precision = seconds | milli | micro, timeout = integer(), return_type = iolist | binary}) -> ok | {error, term()}
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 casesetopts(Transport::transport(), Options::socket_options()) -> ok | {error, term()}
Sets one or more options for a transport socket according to the transport.
unframe(X1::type(), Data::iodata()) -> iodata()
Extracts the line from an octet counting frame.
Generated by EDoc