Guide: Debugging with Nebula SSH commands (#119)

Author: jasikpark

docs/guides/debug-ssh-commands/index.mdx

@@ -0,0 +1,97 @@
+---
+title: Debugging with Nebula SSH commands
+summary:
+  This guide describes useful commands built into the SSH server accessible over nebula, which can allow debugging
+  network connectivity for the nebula host.
+---
+
+# Debugging with Nebula SSH commands
+
+This guide describes useful commands built into the SSH server accessible over nebula, which can allow debugging network
+connectivity for the nebula host.
+
+First generate a new SSH key for the host you want to debug, via `ssh-keygen -t ed25519 -f ssh_host_ed25519_key`. You
+can set it to only accessible by `root` via `chown root:root ssh_host_ed25519_key`, which will ensure that regular users
+on that host cannot access the private key.
+
+Next configure the [`sshd`](https://nebula.defined.net/docs/config/sshd/) section on the host you want to debug.
+
+Example config:
+
+```yml
+sshd:
+  enabled: true
+  listen: 127.0.0.1:2222
+  host_key: /path/to/ssh_host_ed25519_key
+  authorized_users:
+    - user: steeeeve
+      keys:
+        - '[ssh public key string]'
+```
+
+In this case `steeeeve` and `[ssh public key string]` should be the values for the user you want to enable access for
+debugging. You must add the correct public ssh key for the users you wish to access the ssh server with. If you don't
+already have an SSH key for the host you want to access from, follow this guide by GitHub:
+[Generating a new SSH key and adding it to the ssh-agent](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
+
+Set the `listen` property to localhost for local debugging or to your nebula IP to enable access over the nebula overlay
+network.
+
+Next, either run `kill SIGHUP <nebula PID>` or restart nebula and ssh via `ssh 127.0.0.1 -p 2222` for example.
+
+Now you can debug your nebula installation, querying things like your hostmap:
+
+```ssh
+> list-hostmap
+10.128.1.1: [205.133.20.81:4242]
+10.128.1.2: [153.231.31.111:4242]
+```
+
+You should be able to run `help` once you're logged in.
+
+```ssh
+steeeeve@nebula > help
+Available commands:
+change-remote - Changes the remote address used in the tunnel for the provided vpn ip
+close-tunnel - Closes a tunnel for the provided vpn ip
+create-tunnel - Creates a tunnel for the provided vpn ip and address
+help - prints available commands or help <command> for specific usage info
+list-hostmap - List all known previously connected hosts
+list-lighthouse-addrmap - List all lighthouse map entries
+list-pending-hostmap - List all handshaking hosts
+log-format - Gets or sets the current log format
+log-level - Gets or sets the current log level
+logout - Ends the current session
+mutex-profile-fraction - Gets or sets runtime.SetMutexProfileFraction
+print-cert - Prints the current certificate being used or the certificate for the provided vpn ip
+print-relays - Prints json details about all relay info
+print-tunnel - Prints json details about a tunnel for the provided vpn ip
+query-lighthouse - Query the lighthouses for the provided vpn ip
+reload - Reloads configuration from disk, same as sending HUP to the process
+save-heap-profile - Saves a heap profile to the provided path
+save-mutex-profile - Saves a mutex profile to the provided path
+start-cpu-profile - Starts a cpu profile and write output to the provided file
+stop-cpu-profile - Stops a cpu profile and writes output to the previously provided file
+version - Prints the currently running version of nebula
+```
+
+You can discover additional information about each command by running `help <command>`.
+
+```ssh
+> help list-hostmap
+list-hostmap - List all known previously connected hosts
+  -by-index
+    	gets all hosts in the hostmap from the index table
+  -json
+    	outputs as json with more information
+  -pretty
+    	pretty prints json, assumes -json
+```
+
+## Notes about some commands
+
+`query-lighthouse <some-ip>` will return an empty result set initially if the host is not connected, but it will trigger
+a background request to the Lighthouse. Meaning, you need to run it twice to actually get a result.
+
+`change-remote` has only a temporary effect: after a period of time, Nebula will "revert" to its
+[preferred remote](https://nebula.defined.net/docs/config/preferred-ranges/#how-nebula-orders-underlay-ip-addresses-it-learns-about)

docs/guides/viewing-nebula-logs/index.mdx

@@ -57,9 +57,8 @@ On Intel processors, Homebrew uses `/usr/local` instead of `/opt/homebrew` as a
 sudo tail -f /opt/homebrew/var/log/nebula.*
 ```
 
-Another useful tool for viewing logs is the built-in
-[Console.app](<](https://support.apple.com/guide/console/welcome/mac)>). To access the logs, To access the logs, select
-`File -> Open` from the menu and then press
+Another useful tool for viewing logs is the built-in [Console.app](https://support.apple.com/guide/console/welcome/mac).
+To access the logs, To access the logs, select `File -> Open` from the menu and then press
 
 <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>G</kbd> in the file picker, which will allow you to enter `/opt/homebrew/var/log/nebula.log`
 into the textbox.