This is an automated email from the ASF dual-hosted git repository.
xiaoxiang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit a5f43aa8e864d4f449b2f93a095dcf468dd7e206
Author: Matteo Golin <matteo.go...@gmail.com>
AuthorDate: Sun Jun 8 13:46:33 2025 -0400
docs/syslog: Add documentation for RFC 5424 support
Introduces two documentation additions. First, the RFC 5424 support is
documented on the main syslog documentation page, with information about
how to use it effectively. Second is the application documentation for
the `syslogd` application addition, which enables easy use of the new
RFC 5424 support.
Signed-off-by: Matteo Golin <matteo.go...@gmail.com>
---
.../applications/system/syslogd/index.rst | 35 ++++++++++++++++++++++
.../components/drivers/special/syslog.rst | 33 ++++++++++++++++++++
2 files changed, 68 insertions(+)
diff --git a/Documentation/applications/system/syslogd/index.rst
b/Documentation/applications/system/syslogd/index.rst
new file mode 100644
index 0000000000..13021897dc
--- /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 <https://www.rfc-editor.org/rfc/rfc5424>`_ compatible syslog
+messages: ``CONFIG_SYSLOG_RFC5424``.
+
+Options are similar to the Linux `syslogd
+<https://linux.die.net/man/8/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 48149fca06..914b7db7d4 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 <https://www.rfc-editor.org/rfc/rfc5424>`_ 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 </applications/system/syslogd/index>`, 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 <https://www.wireshark.org/>`_ to
+view and parse ``syslog`` entries in your packet captures.
