doc: document new --output-file switch

Signed-off-by: Patrick Donnelly <pdonnell@redhat.com>

PendingReleaseNotes

@@ -1,5 +1,12 @@
 >=19.0.0
 
+* ceph: a new --daemon-output-file switch is available for `ceph tell` commands
+  to dump output to a file local to the daemon. For commands which produce
+  large amounts of output, this avoids a potential spike in memory usage on the
+  daemon, allows for faster streaming writes to a file local to the daemon, and
+  reduces time holding any locks required to execute the command. For analysis,
+  it is necessary to retrieve the file from the host running the daemon
+  manually. Currently, only --format=json|json-pretty are supported.
 * RGW: GetObject and HeadObject requests now return a x-rgw-replicated-at
   header for replicated objects. This timestamp can be compared against the
   Last-Modified header to determine how long the object took to replicate.

doc/man/8/ceph.rst

@@ -1724,7 +1724,25 @@ Options
 
 .. option:: -f {json,json-pretty,xml,xml-pretty,plain,yaml}, --format
 
-	Format of output. Note: yaml is only valid for orch commands. 
+	Format of output.
+
+    Note: yaml is only valid for orch commands.
+
+.. option:: --daemon-output-file OUTPUT_FILE
+
+    When using --format=json|json-pretty, you may specify a file name on the
+    host running the daemon to stream output to. Be mindful this is probably
+    not the same machine running the ceph command. So to analyze the output, it
+    will be necessary to fetch the file once the command completes.
+
+    OUTPUT_FILE may also be ``:tmp:``, indicating that the daemon should create
+    a temporary file (subject to configurations tmp_dir and tmp_file_template).
+
+    The ``tell`` command will output json with the path to the output file
+    written to, the size of the file, the result code of the command, and any
+    output produced by the command.
+
+    Note: this option is only used for ``ceph tell`` commands.
 
 .. option:: --connect-timeout CLUSTER_TIMEOUT
 

doc/rados/configuration/common.rst

@@ -44,6 +44,27 @@ For more about configuring a network for use with Ceph, see the `Network
 Configuration Reference`_ .
 
 
+Temporary Directory
+===================
+
+Some operations will cause a daemon to write to a temporary file. These files
+are located according to the ``tmp_dir`` config.
+
+.. confval:: tmp_dir
+
+The ``$TMPDIR`` environment variable is used to initialize the config, if
+present, but may be overriden on the command-line. A default may also
+be set for the cluster using the usual ``ceph config`` API.
+
+The template for the temporary files created by daemons is controlled
+by the ``tmp_file_template`` config.
+
+.. confval:: tmp_file_template
+
+One example where temporary files are created by daemons is the use of the
+``--daemon-output-file=:tmp:`` argument to the ``ceph tell`` command.
+
+
 Monitors
 ========