Crate syslog_rs 

syslog-rs

An implementation of the syslog from glibc/libc like it was designed in in both system libraries. The API is almost compatible with what is in libc/glibc.

Also supports windows Event Log and/or remote syslog server.

Supports

• GNU/Linux RFC3164 (UTF-8 by default)
• *BSD and OSX RFC5424 (BOM UTF-8 by default) (including msgid and parametes).
• Windows Event Log via WindowsEvent provider and RFC3164/RFC5424 via network or file.
• Tokio async
• Smol async
• TLS over TCP syslog server connection
• TCP/UDP syslog server connection
• Local file writer
• Logger

Directories:

• a_sync - all async code
• formatters - syslog message formatter.
• sync - all sync code
• src - all common code for both sync and async.

Features:

• feature = build_with_thread_local enables the lockless syslog client for single threaded or thread_local instances.
• feature = “build_sync” a base feature which enables all SYNC code. Just enabling the use_sync would enable only basic SharedSyslog.
• feature = “build_async_tokio” a Tokio based async IO. Includes the tokio and tokio-rustls deps.
• feature = “build_async_smol” for synchronious with async processing (use syslog_rs::sy_async_queue::{Syslog};)
• feature = “build_async_interface” for asynchronious interface only without any realisations.
• feature = “build_with_queue” a Smol based async IO. Includes the smol and futures-rustls dep. moves the syslog client to separate thread and by default uses crossbeam-channel to receive messages. Depending on which async procvider is selected, the channel realization will be switched suring compilation. In this case, an async code can be attached to the sync queue which allows to write to the same syslog connection with the same setup.
• feature = “build_ext_net” adds the networking support! (TCP, UDP)
• feature = “build_ext_tls” adds the TLS support over network (TCP).
• feature = “build_ext_file” writing directly to file.
• feature = “build_with_logger” enables the ready to use logger. See below.
• feature = “logger_lazy” switches the mode to the lazy init which does not require to call init_* method from the code. However, it is not possible to attach the logging to the created instance outside of the crate.
• feature = “logger_lazy_silence_panic” changes the behaviour in case of error when the connection to the syslog server is established.

–

• feature = “udp_truncate_1024_bytes” - Forces truncation of the (whole) syslog message to 1024
• feature = udp_truncate_1440_bytes - Forces truncation of the (whole) syslog message to 1440
• feature = tcp_truncate_1024_bytes - Forces truncation of the (whole) syslog message to 1024
• feature = tcp_truncate_2048_bytes - Forces truncation of the (whole) syslog message to 2048
• feature = tcp_truncate_4096_bytes - Forces truncation of the (whole) syslog message to 4096
• feature = tcp_truncate_max_bytes - Forces truncation of the (whole) syslog message to 8192 (max)
• feature = dgram_sysctl_failure_panic - BSD only! By default, if crate fails to obtain a sysctl net.local.dgram.maxdgram, it returns a default value 2048. If this feature is enabled, then it will panic.

build_async_tokio and build_async_smol cannot be used together.

build_with_queue behaves differently if enabled ine of the async providers.

For mor info, please see README.md!

Usage Example

syslog-rs = {version = “7.0”, default-features = false, features = [“build_sync”, “truncate_default”, “build_with_logger”]}

By default, the following features are enabled: build_sync, truncate_default, build_with_logger

Examples

See the directory ./examples

build_with_logger

logger.rs

A logger can be controlled via environmental variables:

• SYSLOG_LOGGER_DST_URI - enables the logger and configures it.

• SYSLOG_LOGGER_LOG_FACILITY - optional, overrides the default which is LOG_DAEMON

• SYSLOG_LOGGER_LOG_FORMATTER - optional, overrides the default formatter dep on the OS.

• SYSLOG_LOGGER_LOG_IDENTITY - optional, if not set, will be determined automatically.

• SYSLOG_LOGGER_LOG_UPTO - optional, sets the LOGUPTO priority.

The vars can have suffix, for example XIO, so SYSLOG_LOGGER_DST_URI_XIO, SYSLOG_LOGGER_LOG_FACILITY_XIO, …

In the crate or executable, a logger should be initialized when using non-lazy mode. Below initializes the event log in shared mode.

    init_event_log(None).unwrap();

if suffix was used then it should be specified:

    init_event_log(Some("XIO")).unwrap();

Below initializes the event log in thread local mode:

    init_thread_local_event_log(None).unwrap();

In the lazy mode, it is not required to call init_*.

Below are the macroses and functions which can be used to send messages

    logger_dbg!("debug: test_logger_simple");
    logger_info!("info: test1test_logger_simple23");
    logger_error!("error: test_logger_simple");
    logger_warn!("warn: test_logger_simple");
    logger_emerg!("emerg: test_logger_simple");
    logger_custom!(Priority::LOG_EMERG, "custom");
    logger_log(Priority::LOG_EMERG, format!("abc"));

Also the logger can be attached to the existing syslog instance i.e in the larger work:

Example:

    attach_event_log_shared(&syslog).unwrap()

attaches the crate’s syslog to the created one in a larger program. But the crate which uses logger must provide a function which would call this routine internally! It is not possible when crate is compiled in the lazy mode.

There are two attach methods:

• attach_event_log_shared - for a SyShared instance

• attach_event_log_queued - for a [SyQueue] instance

SYSLOG_LOGGER_DST_URI

Local

• local# - for default

• local#/var/run/syslogcustom - for custom path

Example:

SYSLOG_LOGGER_DST_URI="local#"
SYSLOG_LOGGER_DST_URI="local#/var/run/log"

UDP/TCP

• udp#127.0.0.1:80 - for IPv4 + port

• udp#[fe00:::0]:80 - for IPv6 + port

• udp#www.mydomain.tdl:80 - for hostname + port

• tcp#127.0.0.1:80 - for IPv4 + port

Example:

SYSLOG_LOGGER_DST_URI="udp#127.0.0.1:80"

TLS

• tls#127.0.0.1:80#servername#root_cert_path - for IPv4 + port

• tls#[fe00:::0]:80#servername#root_cert_path - for IPv6 + port

• tls#www.mydomain.tdl:80#servername#root_cert_path - for hostname + port

Example:

SYSLOG_LOGGER_DST_URI="tls#127.0.0.1:80#prod0.syslogse.tld#/etc/ssl/rootcerts.crt"

FILE

• file#/tmp/file1.txt - for file append mode

Example:

SYSLOG_LOGGER_DST_URI="file#/tmp/file1.txt"

SYSLOG_LOGGER_LOG_FACILITY

Default: LOG_DAEMON

LOG_KERN, LOG_USER, LOG_MAIL, LOG_DAEMON, LOG_AUTH, LOG_SYSLOG, LOG_LPR, LOG_NEWS,
LOG_UUCP, LOG_LOCAL0, LOG_LOCAL1, LOG_LOCAL2, LOG_LOCAL3, LOG_LOCAL4, LOG_LOCAL5,
LOG_LOCAL6, LOG_LOCAL7

SYSLOG_LOGGER_LOG_FORMATTER

Default: autoselected

RFC3146, RFC5424, FILE

! Don’t use FILE with syslog server, this is for local file only.

SYSLOG_LOGGER_LOG_UPTO

LOG_ALERT, LOG_CRIT, LOG_DEBUG, LOG_EMERG, LOG_ERR, LOG_INFO, LOG_NOTICE, LOG_WARNING

Re-exports

pub extern crate chrono;

pub extern crate nix;

Re-exports

pub use socket::TapType;

pub use sync::syslog_sync::Syslog;

pub use sync::syslog_sync::SyShared;

pub use sync::syslog_sync::DynSyslog;

pub use sync::SyStreamPriWarning;

pub use sync::SyStreamPriNotice;

pub use sync::SyStreamPriInfo;

pub use sync::SyStreamPriEmerg;

pub use sync::SyStreamPriCrit;

pub use sync::SyStreamPriAlert;

pub use sync::SyStreamPriDebug;

pub use sync::SyStreamPriErr;

pub use sync::DefaultLocalSyslogDestination;

pub use logger::logger_log;

pub use logger::init_event_log;

pub use logger::attach_event_log_shared;

pub use logger::attach_event_log_queued;

pub use logger::init_thread_local_event_log;

pub use a_sync::syslog_async as sy_async;

pub use sy_async::AsyncSyslog;

pub use a_sync::syslog_trait::AsyncSyslogQueueApi;

pub use sync::syslog_sync_queue as sy_sync_queue;

pub use sync::syslog_sync::SyQueued;

pub use sync::syslog_sync::SyThreadLocal;

pub use sync::syslog_sync::MutDynSyslog;

pub use syslog_provider::*;

pub use common::*;

Modules

a_sync

An async interface and/or realisations. The main async syslog struct is located there.

common

A common code which holds all flags and macroses.

error

Unified error interface.

formatters

A message formatters i.e RFC5424 and other. Also a message formatter interface.

logger

A logger which can be setup from env.

socket

A common things for the sockets managment.

sync

A sync syslog realization including shared and queued syslog client.

syslog_provider

Macros

LOG_MASK

LOG_MASK is used to create the priority mask in setlogmask. For a single Priority mask used with Priority can be used with | & ! bit operations LOG_MASK()

LOG_UPTO

LOG_MASK is used to create the priority mask in setlogmask For a mask UPTO specified used with Priority

logger_custom

Sends a message with the user defined priority.

logger_dbg

Sends a message with the Priority::LOG_DEBUG.

logger_emerg

Sends a message with the Priority::LOG_EMERG.

logger_error

Sends a message with the Priority::LOG_ERR.

logger_info

Sends a message with the Priority::LOG_INFO.

logger_warn

Sends a message with the Priority::LOG_WARNING.

map_error

map_error_code

map_error_os

throw_error

throw_error_code

throw_error_errno

throw_error_os