WIP

config/commands/debug.yaml

@@ -3,19 +3,29 @@ description: |
   Display help for debug commands and exit.
 include_options: [global/*]
 subcommands:
-  - name: diagnose
-    description: |
-      XXX
+  # - name: diagnose
+  #   description: |
+  #     XXX
   - name: dump
     links: [skupper/debug_dumps]
     description: |
-      Generate a debug dump file.
+      Generate a debug dump file.  Debug dumps collect the details of
+      a site so another party can identify and fix a problem.
     examples: |
-      # Generate a debug dump file
-      $ skupper debug dump ~/dump.tar.gz
-      Debug dump file generated at /home/fritz/dump.tar.gz.
+      # Generate a dump file
+      $ skupper debug dump
+      Debug dump file: /home/fritz/skupper-dump-west-2024-12-09.tar.gz
+
+      # Generate a dump file to a particular path
+      $ skupper debug dump /tmp/abc.tar.gz
+      Debug dump file: /tmp/abc.tar.gz
     include_options: [context/*, global/*]
     options:
       - name: file
         type: string
-        required: true
+        positional: true
+        default: "`skupper-dump-<site-name>-<date>.tar.gz`"
+        description: |
+          The name of the file to generate.
+
+          The command exits with an error if the file already exists.

input/commands/debug/dump.md

@@ -21,7 +21,8 @@ refdog_object_toc:
 
 <section>
 
-Generate a debug dump file.
+Generate a debug dump file.  Debug dumps collect the details of
+a site so another party can identify and fix a problem.
 
 <table class="fields"><tr><th>Platforms</th><td>Kubernetes, Docker, Podman, Linux</td></table>
 
@@ -32,7 +33,7 @@ Generate a debug dump file.
 ## Usage
 
 ~~~ shell
-skupper debug dump <file> [options]
+skupper debug dump [file] [options]
 ~~~
 
 </section>
@@ -42,9 +43,13 @@ skupper debug dump <file> [options]
 ## Examples
 
 ~~~ console
-# Generate a debug dump file
-$ skupper debug dump ~/dump.tar.gz
-Debug dump file generated at /home/fritz/dump.tar.gz.
+# Generate a dump file
+$ skupper debug dump
+Debug dump file: /home/fritz/skupper-dump-west-2024-12-09.tar.gz
+
+# Generate a dump file to a particular path
+$ skupper debug dump /tmp/abc.tar.gz
+Debug dump file: /tmp/abc.tar.gz
 ~~~
 
 </section>
@@ -55,13 +60,18 @@ Debug dump file generated at /home/fritz/dump.tar.gz.
 
 <div class="attribute">
 <div class="attribute-heading">
-<h3 id="option-file">&lt;file&gt;</h3>
+<h3 id="option-file">[file]</h3>
 <div class="attribute-type-info">string</div>
-<div class="attribute-flags">required</div>
+<div class="attribute-flags">optional</div>
 </div>
 <div class="attribute-body">
 
-<table class="fields"><tr><th>Platforms</th><td>Kubernetes, Docker, Podman, Linux</td></table>
+The name of the file to generate.
+
+The command exits with an error if the file already exists.
+
+<table class="fields"><tr><th>Default</th><td><p><code>skupper-dump-&lt;site-name&gt;-&lt;date&gt;.tar.gz</code></p>
+</td><tr><th>Platforms</th><td>Kubernetes, Docker, Podman, Linux</td></table>
 
 </div>
 </div>

input/commands/debug/index.md

@@ -38,8 +38,6 @@ skupper debug [subcommand] [options]
 ## Subcommands
 
 <table class="objects">
-<tr><th><a href="diagnose.html">Debug diagnose</a></th><td><p>XXX</p>
-</td></tr>
 <tr><th><a href="dump.html">Debug dump</a></th><td><p>Generate a debug dump file</p>
 </td></tr>
 </table>

input/commands/index.md

@@ -106,8 +106,6 @@ refdog_object_links:
 
 <table class="objects">
 <tr><th><a href="{{site_prefix}}/commands/debug/index.html">Debug</a></th><td>Overview of debug commands</td></tr>
-<tr><th><a href="{{site_prefix}}/commands/debug/diagnose.html">Debug diagnose</a></th><td><p>XXX</p>
-</td></tr>
 <tr><th><a href="{{site_prefix}}/commands/debug/dump.html">Debug dump</a></th><td><p>Generate a debug dump file</p>
 </td></tr>
 </table>

input/topics/debug-dumps.md

@@ -6,27 +6,36 @@
 - Key elements include site resources and status; component versions,
   config files, and logs; and info about the environment where Skupper
   is running.
-
 - Should we include workloads in the namespace?  Services, deployments, pods?
 - .txt file summaries for some things?
 - What details about the overall network should we get?
   - Links from other sites?
 
 ~~~
-versions.yaml  # Same as the output of 'skupper version --output yaml'
-platform.yaml  # Info about the platform and namespace hosting the site
-network.yaml   # ??
-components/
-  controller/
-    <config file>
-    controller.log
-  router/
-    <config file>
-    router.log
-    kube-adaptor.log
-  network-observer/
-    <config file>
-    network-observer.log
-resources/
-  <kind>-<name>.yaml for each Skupper resource
+# Same as the output of 'skupper version -o yaml'
+version.yaml
+
+# Same as the output of 'kubectl -n <site-namespace> get <kind>/<name> -o yaml'
+resources/<kind>-<name>.yaml
+
+# Same as the output of 'kubectl -n <skupper-namespace> get <kind>/<name> -o yaml'
+resources/<kind>-<name>.yaml
 ~~~
+
+<!-- components/controller/pods/<name>/log.txt -->
+<!-- components/controller/pods/<name>/log.txt -->
+<!-- components/router/log.txt -->
+
+<!-- platform.yaml  # Info about the platform and namespace hosting the site -->
+
+<!-- components/ -->
+<!--   controller/ -->
+<!--     <config file> -->
+<!--     controller.log -->
+<!--   router/ -->
+<!--     <config file> -->
+<!--     router.log -->
+<!--     kube-adaptor.log -->
+<!--   network-observer/ -->
+<!--     <config file> -->
+<!--     network-observer.log -->

input/topics/site-linking.md

@@ -2,6 +2,7 @@
 
 - Using tokens and the CLI
 - Using tokens and YAML
+- Token distribution methods
 - Using link generation
 - Using a network-scoped CA
 - Special concerns for non-Kube sites