diff --git a/Documentation/applications/system/syslogd/index.rst b/Documentation/applications/system/syslogd/index.rst new file mode 100644 index 00000000000..13021897dcb --- /dev/null +++ b/Documentation/applications/system/syslogd/index.rst @@ -0,0 +1,35 @@ +=========== +``syslogd`` +=========== + +.. tags:: experimental + +The ``syslogd`` command is used as a "syslog daemon". It sends syslog entries +over the network using UDP so that they can be consumed by a central logging +server. This is achieved by reading the newline separated long entries from the +``syslog`` device specified by ``CONFIG_SYSLOG_DEVPATH`` (similar to how +``dmesg`` works) and sending them as UDP packets to the configured host. + +If the ``syslog`` device being read is non-blocking, ``syslogd`` will terminate +with a successful error code once all logs have been read. It is suggested to +use a blocking device so that ``syslogd`` will continuously send logs when they +are generated. + +In order to use this command, you must have a UDP capable platform and have +enabled `RFC 5424 `_ compatible syslog +messages: ``CONFIG_SYSLOG_RFC5424``. + +Options are similar to the Linux `syslogd +`_ utility, however not all options are +implemented since NuttX does not immediately support the more complex features +(i.e. the ``-l`` option). The application can only act as an originator, it does +not receive or forward logs. + +.. warning:: + + The daemon is currently runs itself in the background using ``fork()``. On + architectures where ``fork()`` is not implemented, the daemon must be + "backgrounded" by using the trailing ``&`` in NSH at the moment. It is also + possible to us ``posix_spawn()`` from a parent program. + +Read more about ``syslog`` on NuttX: :doc:`/components/drivers/special/syslog` diff --git a/Documentation/components/drivers/special/syslog.rst b/Documentation/components/drivers/special/syslog.rst index 48149fca063..914b7db7d42 100644 --- a/Documentation/components/drivers/special/syslog.rst +++ b/Documentation/components/drivers/special/syslog.rst @@ -518,3 +518,36 @@ Other miscellaneous settings - ``CONFIG_RAMLOG_NPOLLWAITERS``: The maximum number of threads that may be waiting on the poll method. + +SYSLOG Protocol (RFC 5424) +========================== + +`RFC 5424 `_ is a protocol defined for +syslog messages which makes provisions to have logs created by "originators" to +be saved on "collectors" (log servers). + +NuttX is capable of generating RFC 5424 compatible ``syslog`` entries with the +option ``CONFIG_SYSLOG_RFC5424``. Not all features of RFC 5424 are currently +implemented, such as the ``HOSTNAME`` field or ``MSGID`` fields. However, the +majority of the RFC 5424 functionality is in place and allows for a NuttX device +to become a RFC 5424 originator. + +Syslog over the network +----------------------- + +Using RFC 5424, network capable NuttX devices can become originators and +transmit ``syslog`` entries to a collector (log server). This is currently +possible using the basic UDP implementation with +:doc:`/applications/system/syslogd/index`. + +If using ``syslogd``, it is recommended to use the ``RAMLOG`` device as the +syslog sink. This allows very fast recording of logs, which unlocks the +ability to record logs from interrupt contexts or time-sensitive code. The +``syslogd`` daemon can then transmit these later from user space. As stated +in :doc:`the syslogd documentation `, it is +recommended to configure ``RAMLOG`` in blocking mode. + +Once messages are set up for transmission with ``syslogd``, you can consume them +on another network capable host device using one of the RFC 5424 compatible log +servers. You're even able to use `WireShark `_ to +view and parse ``syslog`` entries in your packet captures.