syslog_rs/

lib.rs

/*-
 * syslog-rs - a syslog client translated from libc to rust
 * 
 * Copyright 2025(c) Aleksandr Morozov
 * 
 * The syslog-rs crate can be redistributed and/or modified
 * under the terms of either of the following licenses:
 *
 *   1. the Mozilla Public License Version 2.0 (the “MPL”) OR
 *
 *   2. The MIT License (MIT)
 *                     
 *   3. EUROPEAN UNION PUBLIC LICENCE v. 1.2 EUPL © the European Union 2007, 2016
 */

//! syslog-rs
//! 
//!  <img src="https://cdn.4neko.org/syslog_logo.webp" width="220"/> <img src="https://cdn.4neko.org/source_avail.webp" width="220"/> <img src="https://cdn.4neko.org/mit_mpl_eupl_2.webp" width="220"/>
//!  <br/>
//!  <a href = "https://codeberg.org/4neko/syslog-rs/actions"><img src="https://codeberg.org/4neko/syslog-rs/badges/workflows/linux-os.yml/badge.svg" /></a>
//!  <a href = "https://codeberg.org/4neko/syslog-rs/actions"><img src="https://codeberg.org/4neko/syslog-rs/badges/workflows/freebsd-os.yml/badge.svg" /></a>
//!  <a href = "https://codeberg.org/4neko/syslog-rs/actions"><img src="https://codeberg.org/4neko/syslog-rs/badges/workflows/openbsd-os.yml/badge.svg" /></a>
//!  <a href = "https://codeberg.org/4neko/syslog-rs/actions"><img src="https://codeberg.org/4neko/syslog-rs/badges/workflows/netbsd-os.yml/badge.svg" /></a>
//!  <a href = "https://codeberg.org/4neko/syslog-rs/actions"><img src="https://codeberg.org/4neko/syslog-rs/badges/workflows/linux-os-arm.yml/badge.svg" /></a>
//! 
//! 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.
//! 
//! ```ignore
//!     init_event_log(None).unwrap();
//! ```
//! 
//! if `suffix` was used then it should be specified:
//! 
//! ```ignore
//!     init_event_log(Some("XIO")).unwrap();
//! ```
//! 
//! Below initializes the event log in thread local mode:
//! 
//! ```ignore
//!     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
//! 
//! ```ignore
//!     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:
//! ```ignore
//!     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: 
//! 
//! ```text
//! 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:
//! 
//! ```text
//! 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:
//! 
//! ```text
//! 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:
//! 
//! ```text
//! SYSLOG_LOGGER_DST_URI="file#/tmp/file1.txt"
//! ```
//! 
//! ### SYSLOG_LOGGER_LOG_FACILITY
//! 
//! Default: LOG_DAEMON
//! 
//! ```text
//! 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
//! 
//! ```text
//! RFC3146, RFC5424, FILE
//! ```
//! 
//! ! Don't use `FILE` with syslog server, this is for local file only.
//! 
//! ### SYSLOG_LOGGER_LOG_UPTO
//! 
//! ```text
//! LOG_ALERT, LOG_CRIT, LOG_DEBUG, LOG_EMERG, LOG_ERR, LOG_INFO, LOG_NOTICE, LOG_WARNING
//! ```
//! 

// make sure that the smol and tokio are not used together.
#[cfg(all(feature = "build_async_tokio", feature = "build_async_smol"))]
compile_error!("use_async_tokio and use_async_smol can not be used at the same time");

// make sure that the build_async_interface and either async_embedded are not used together.
#[cfg(all(feature = "build_async_interface", feature = "async_embedded"))]
compile_error!("build_async_interface and either tokio/smol can not be used at the same time");

//-- REEXPORT --
#[macro_use] 
extern crate bitflags;
pub extern crate chrono;
extern crate socket2;


#[cfg(target_family = "unix")]
pub extern crate nix;

/// winDAws crp...
#[cfg(target_family = "windows")]
pub extern crate windows;


// -- TLS --

#[cfg(all(feature = "build_sync", feature = "build_ext_tls"))]
extern crate rustls;

#[cfg(all(feature = "build_async_tokio", feature = "build_ext_tls"))]
extern crate tokio_rustls;

#[cfg(all(feature = "build_async_smol", feature = "build_ext_tls"))]
extern crate futures_rustls;

// -- ASYNC --

#[cfg(feature = "build_async_tokio")]
extern crate tokio;

#[cfg(feature = "build_async_smol")]
extern crate smol;

// -- SYNC --
#[cfg(feature = "build_with_queue")]
extern crate crossbeam_channel;

#[cfg(feature = "build_sync")]
extern crate crossbeam_utils;

/// A sync syslog realization including shared and queued syslog client.
#[cfg(feature = "build_sync")]
pub mod sync;

/// An async interface and/or realisations. The main async syslog struct is located there.
#[cfg(feature = "async_enabled")]
pub mod a_sync;

/// A message formatters i.e RFC5424 and other. Also a message formatter interface.
pub mod formatters;

pub mod syslog_provider;

/// A syslog destnation. i.e local, remote, remote TLS, local file. Needed to initialize the 
/// (both sync and async) instances.
pub use syslog_provider::*;

/// A common things for the sockets managment.
pub mod socket;

/// A logger which can be setup from env.
#[cfg(all(unix, feature = "build_with_logger"))]
pub mod logger;

/// A common code which holds all flags and macroses.
#[macro_use] 
pub mod common;

/// Unified error interface.
#[macro_use] 
pub mod error;


//-- NON EXPORT
/// A portable code which is different for different OSes.
mod portable;

/// Public use of the type of the tap.
pub use socket::TapType;

/// A streamable sync instance (both).
#[cfg(feature = "build_sync")]
pub use sync::{syslog_sync::{Syslog, SyShared, DynSyslog}, SyStreamPriWarning, SyStreamPriNotice, SyStreamPriInfo,
    SyStreamPriEmerg, SyStreamPriCrit, SyStreamPriAlert, SyStreamPriDebug, SyStreamPriErr,
    DefaultLocalSyslogDestination};

#[cfg(feature = "build_with_logger")]
pub use logger::{logger_log};

#[cfg(all(feature = "build_with_logger", not(feature = "logger_lazy")))]
pub use logger::init_event_log;

#[cfg(all(feature = "build_with_logger", not(feature = "logger_lazy")))]
pub use logger::attach_event_log_shared;

#[cfg(all(feature = "build_with_logger", feature = "build_with_queue", not(feature = "logger_lazy")))]
pub use logger::attach_event_log_queued;

#[cfg(all(feature = "build_with_logger", feature = "build_with_thread_local", not(feature = "logger_lazy")))]
pub use logger::init_thread_local_event_log;

/// A `sy_async` is a shortcut to the file `syslog_async.rs` in dir `a_sync`.
#[cfg(feature = "async_enabled")]
pub use a_sync::syslog_async as sy_async;

/// A main async syslog instance.
#[cfg(feature = "async_enabled")]
pub use sy_async::AsyncSyslog;

/// A shortcut for the internals of the `async_syslog` and IO for user implementation.
#[cfg(feature = "build_async_interface")]
pub use a_sync::syslog_async_internal::{AsyncSyslogInternal, AsyncSyslogInternalIO};

/// A shortcut to the trait `AsyncMutex` which unifies the mutex realiztion of different 
/// exec environments.
#[cfg(feature = "build_async_interface")]
pub use a_sync::syslog_async_internal::AsyncMutex;

/// Use this trait to access queue interface for async code.
#[cfg(all(feature = "async_enabled", feature = "build_with_queue"))]
pub use a_sync::syslog_trait::AsyncSyslogQueueApi;


/// A shortcut to the file `syslog_sync_queue.rs` in dir `sync`.
#[cfg(feature = "build_with_queue")]
pub use sync::syslog_sync_queue as sy_sync_queue;

/// A (previosuly SyslogQueue) queued sync type of the syslog client. Also async queue.
#[cfg(feature = "build_with_queue")]
pub use sync::syslog_sync::SyQueued;

#[cfg(feature = "build_with_thread_local")]
pub use sync::syslog_sync::{SyThreadLocal, MutDynSyslog};

/// A shortcut use of all in the `common.rs`.
pub use common::*;