From abaeed1a207ce6f28dbe18bfd2fa4eb631d7cd0b Mon Sep 17 00:00:00 2001
From: John Mulligan <jmulligan@redhat.com>
Date: Wed, 6 Sep 2023 16:56:40 -0400
Subject: [PATCH] doc/cephadm: document new cephadm logging destination
 settings

Add docs for setting the binary's log destination at cephadm bootstrap
or on a running cluster.

Signed-off-by: John Mulligan <jmulligan@redhat.com>
---
 doc/cephadm/operations.rst | 69 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/doc/cephadm/operations.rst b/doc/cephadm/operations.rst
index c59dce36a91c0..d6323c04e0c35 100644
--- a/doc/cephadm/operations.rst
+++ b/doc/cephadm/operations.rst
@@ -173,6 +173,75 @@ files.  You can configure the logging retention schedule by modifying
 ``/etc/logrotate.d/ceph.<cluster-fsid>``.
 
 
+Per-node cephadm logs
+=====================
+
+The cephadm executable, either run directly by a user or by the cephadm
+orchestration module, may also generate logs. It does so independently of
+the other Ceph components running in containers. By default, this executable
+logs to the file ``/var/log/ceph/cephadm.log``.
+
+This logging destination is configurable and you may choose to log to the
+file, to the syslog/journal, or to both.
+
+Setting a cephadm log destination during bootstrap
+--------------------------------------------------
+
+The ``cephadm`` command may be executed with the option ``--log-dest=file``
+or with ``--log-dest=syslog`` or both. These options control where cephadm
+will store persistent logs for each invocation. When these options are
+specified for the ``cephadm bootstrap`` command the system will automatically
+record these settings for future invocations of ``cephadm`` by the cephadm
+orchestration module.
+
+For example:
+
+.. prompt:: bash #
+
+  cephadm --log-dest=syslog bootstrap # ... other bootstrap arguments ...
+
+If you want to manually specify exactly what log destination to use
+during bootstrap, independent from the ``--log-dest`` options, you may add
+a configuration key ``mgr/cephadm/cephadm_log_destination`` to the
+initial configuration file, under the ``[mgr]`` section. Valid values for
+the key are: ``file``, ``syslog``, and ``file,syslog``.
+
+For example:
+
+.. prompt:: bash #
+
+  cat >/tmp/bootstrap.conf <<EOF
+  [mgr]
+  mgr/cephadm/cephadm_log_destination = syslog
+  EOF
+  cephadm bootstrap --config /tmp/bootstrap.conf # ... other bootstrap arguments ...
+
+Setting a cephadm log destination on an existing cluster
+--------------------------------------------------------
+
+An existing Ceph cluster can be configured to use a specific cephadm log
+destination by setting the ``mgr/cephadm/cephadm_log_destination``
+configuration value to one of ``file``, ``syslog``, or ``file,syslog``. This
+will cause the cephadm orchestration module to run ``cephadm`` so that logs go
+to ``/var/log/ceph/cephadm.log``, the syslog/journal, or both, respectively.
+
+For example:
+
+.. prompt:: bash #
+
+  # set the cephadm executable to log to syslog
+  ceph config set mgr mgr/cephadm/cephadm_log_destination syslog
+  # set the cephadm executable to log to both the log file and syslog
+  ceph config set mgr mgr/cephadm/cephadm_log_destination file,syslog
+  # set the cephadm executable to log to the log file
+  ceph config set mgr mgr/cephadm/cephadm_log_destination file
+
+.. note:: If you execute cephadm commands directly, such as cephadm shell,
+   this option will not apply. To have cephadm log to locations other than
+   the default log file When running cephadm commands directly use the
+   ``--log-dest`` options described in the bootstrap section above.
+
+
 Data location
 =============
 
-- 
2.39.5