src/vnet/syslog/sylog_doc.rst

   1 .. _syslog_doc:
   2
   3 Syslog protocol support
   4 =======================
   5
   6 VPP provides `RFC5424 <https://tools.ietf.org/html/rfc5424>`__ syslog
   7 protocol logging, which is used to transport event messages across
   8 network. VPP currently supports UDP transport based on
   9 `RFC5426 <https://tools.ietf.org/html/rfc5426>`__.
  10
  11 The syslog message has the following format: \* header \* structured
  12 data \* free-form message
  13
  14 The header contains, priority, version, timestamp, hostname,
  15 application, process id and message id. It is followed by structured
  16 data, which provides a mechanism to express event data in easily
  17 parsable format. Structured data can contain zero, one or multiple
  18 structured data elements. Structured data element contains name-value
  19 pairs. Structured data can by followed by free-form message.
  20
  21 Following example explains how to use the internal APIs to generate
  22 syslog message:
  23
  24 .. code:: c
  25
  26       #include <vnet/syslog/syslog.h>
  27
  28       ...
  29
  30       syslog_msg_t syslog_msg;
  31
  32       /* Check if syslog logging is enabled */
  33       if (!syslog_is_enabled ())
  34         return;
  35
  36       /* Severity filer test */
  37       if (syslog_severity_filter_block (severity))
  38         return;
  39
  40       /* Initialize syslog message header */
  41       syslog_msg_init (&syslog_msg, facility, severity, "NAT", "SADD");
  42
  43       /* Create structured data element */
  44       syslog_msg_sd_init (&syslog_msg, "nsess");
  45       /* Add structured data element parameters (name-value pairs) */
  46       syslog_msg_add_sd_param (&syslog_msg, "SSUBIX", "%d", ssubix);
  47       syslog_msg_add_sd_param (&syslog_msg, "SVLAN", "%d", svlan);
  48       syslog_msg_add_sd_param (&syslog_msg, "IATYP", "IPv4");
  49       syslog_msg_add_sd_param (&syslog_msg, "ISADDR", "%U",
  50                                format_ip4_address, isaddr);
  51       syslog_msg_add_sd_param (&syslog_msg, "ISPORT", "%d", isport);
  52       syslog_msg_add_sd_param (&syslog_msg, "XATYP", "IPv4");
  53       syslog_msg_add_sd_param (&syslog_msg, "XSADDR", "%U",
  54                                format_ip4_address, xsaddr);
  55       syslog_msg_add_sd_param (&syslog_msg, "XSPORT", "%d", xsport);
  56       syslog_msg_add_sd_param (&syslog_msg, "PROTO", "%d", proto);
  57
  58       /* Send syslog message */
  59       syslog_msg_send (&syslog_msg);
  60
  61 Example above produces following syslog message: <134>1
  62 2018-11-12T11:25:30.252715Z 172.16.4.1 NAT 5901 SADD [nsess SSUBIX=“0”
  63 SVLAN=“0” IATYP=“IPv4” ISADDR=“172.16.1.2” ISPORT=“6303” XATYP=“IPv4”
  64 XSADDR=“10.0.0.3” XSPORT=“16253” PROTO=“6”]
  65
  66 To add free-form message use:
  67
  68 .. code:: c
  69
  70       syslog_msg_add_msg (&syslog_msg, "event log entry");