From d4a70647e6b8de2cb81cbea3c53d08c299b65cc5 Mon Sep 17 00:00:00 2001 From: Nathan Skrzypczak Date: Fri, 8 Oct 2021 14:01:27 +0200 Subject: docs: convert vpp doc md->rst Type: improvement Change-Id: If453321785b04f9c16e8cea36fb1910efaeb2c59 Signed-off-by: Nathan Skrzypczak --- src/vnet/syslog/sylog_doc.md | 65 ---------------------------------------- src/vnet/syslog/sylog_doc.rst | 70 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+), 65 deletions(-) delete mode 100644 src/vnet/syslog/sylog_doc.md create mode 100644 src/vnet/syslog/sylog_doc.rst (limited to 'src/vnet/syslog') diff --git a/src/vnet/syslog/sylog_doc.md b/src/vnet/syslog/sylog_doc.md deleted file mode 100644 index 0b48d4db573..00000000000 --- a/src/vnet/syslog/sylog_doc.md +++ /dev/null @@ -1,65 +0,0 @@ -# Syslog protocol support {#syslog_doc} - -VPP provides [RFC5424](https://tools.ietf.org/html/rfc5424) syslog protocol -logging, which is used to transport event messages across network. VPP -currently suports UDP transport based on -[RFC5426](https://tools.ietf.org/html/rfc5426). - -The syslog message has the following format: -* header -* structured data -* free-form message - -The header contains, priority, version, timestamp, hostname, application, -process id and message id. It is followed by structured data, which provides -a mechanism to express event data in easily parsable format. Structured data -can contain zero, one or multiple structured data elements. Structured data -element contains name-value pairs. Structured data can by followed by free-form -message. - -Following example explains how to use the internal APIs to genrate syslog -message: -```{.c} - #include - - ... - - syslog_msg_t syslog_msg; - - /* Check if syslog logging is enabled */ - if (!syslog_is_enabled ()) - return; - - /* Severity filer test */ - if (syslog_severity_filter_block (severity)) - return; - - /* Initialize syslog message header */ - syslog_msg_init (&syslog_msg, facility, severity, "NAT", "SADD"); - - /* Create structured data element */ - syslog_msg_sd_init (&syslog_msg, "nsess"); - /* Add structured data element parameters (name-value pairs) */ - syslog_msg_add_sd_param (&syslog_msg, "SSUBIX", "%d", ssubix); - syslog_msg_add_sd_param (&syslog_msg, "SVLAN", "%d", svlan); - syslog_msg_add_sd_param (&syslog_msg, "IATYP", "IPv4"); - syslog_msg_add_sd_param (&syslog_msg, "ISADDR", "%U", - format_ip4_address, isaddr); - syslog_msg_add_sd_param (&syslog_msg, "ISPORT", "%d", isport); - syslog_msg_add_sd_param (&syslog_msg, "XATYP", "IPv4"); - syslog_msg_add_sd_param (&syslog_msg, "XSADDR", "%U", - format_ip4_address, xsaddr); - syslog_msg_add_sd_param (&syslog_msg, "XSPORT", "%d", xsport); - syslog_msg_add_sd_param (&syslog_msg, "PROTO", "%d", proto); - - /* Send syslog message */ - syslog_msg_send (&syslog_msg); -``` - -Example above produces following syslog message: - <134>1 2018-11-12T11:25:30.252715Z 172.16.4.1 NAT 5901 SADD [nsess SSUBIX="0" SVLAN="0" IATYP="IPv4" ISADDR="172.16.1.2" ISPORT="6303" XATYP="IPv4" XSADDR="10.0.0.3" XSPORT="16253" PROTO="6"] - -To add free-form message use: -```{.c} - syslog_msg_add_msg (&syslog_msg, "event log entry"); -``` diff --git a/src/vnet/syslog/sylog_doc.rst b/src/vnet/syslog/sylog_doc.rst new file mode 100644 index 00000000000..f39c9c490dc --- /dev/null +++ b/src/vnet/syslog/sylog_doc.rst @@ -0,0 +1,70 @@ +.. _syslog_doc: + +Syslog protocol support +======================= + +VPP provides `RFC5424 `__ syslog +protocol logging, which is used to transport event messages across +network. VPP currently supports UDP transport based on +`RFC5426 `__. + +The syslog message has the following format: \* header \* structured +data \* free-form message + +The header contains, priority, version, timestamp, hostname, +application, process id and message id. It is followed by structured +data, which provides a mechanism to express event data in easily +parsable format. Structured data can contain zero, one or multiple +structured data elements. Structured data element contains name-value +pairs. Structured data can by followed by free-form message. + +Following example explains how to use the internal APIs to generate +syslog message: + +.. code:: c + + #include + + ... + + syslog_msg_t syslog_msg; + + /* Check if syslog logging is enabled */ + if (!syslog_is_enabled ()) + return; + + /* Severity filer test */ + if (syslog_severity_filter_block (severity)) + return; + + /* Initialize syslog message header */ + syslog_msg_init (&syslog_msg, facility, severity, "NAT", "SADD"); + + /* Create structured data element */ + syslog_msg_sd_init (&syslog_msg, "nsess"); + /* Add structured data element parameters (name-value pairs) */ + syslog_msg_add_sd_param (&syslog_msg, "SSUBIX", "%d", ssubix); + syslog_msg_add_sd_param (&syslog_msg, "SVLAN", "%d", svlan); + syslog_msg_add_sd_param (&syslog_msg, "IATYP", "IPv4"); + syslog_msg_add_sd_param (&syslog_msg, "ISADDR", "%U", + format_ip4_address, isaddr); + syslog_msg_add_sd_param (&syslog_msg, "ISPORT", "%d", isport); + syslog_msg_add_sd_param (&syslog_msg, "XATYP", "IPv4"); + syslog_msg_add_sd_param (&syslog_msg, "XSADDR", "%U", + format_ip4_address, xsaddr); + syslog_msg_add_sd_param (&syslog_msg, "XSPORT", "%d", xsport); + syslog_msg_add_sd_param (&syslog_msg, "PROTO", "%d", proto); + + /* Send syslog message */ + syslog_msg_send (&syslog_msg); + +Example above produces following syslog message: <134>1 +2018-11-12T11:25:30.252715Z 172.16.4.1 NAT 5901 SADD [nsess SSUBIX=“0” +SVLAN=“0” IATYP=“IPv4” ISADDR=“172.16.1.2” ISPORT=“6303” XATYP=“IPv4” +XSADDR=“10.0.0.3” XSPORT=“16253” PROTO=“6”] + +To add free-form message use: + +.. code:: c + + syslog_msg_add_msg (&syslog_msg, "event log entry"); -- cgit 1.2.3-korg