From bd9f53be5432d8ea3f49eefbfce398940cf44275 Mon Sep 17 00:00:00 2001
From: Sylvia Crowe <software@oneirocosm.com>
Date: Wed, 27 Dec 2023 22:24:15 -0800
Subject: [PATCH] create user instructions for ssh-config imports

The SSH config import feature has a few default behaviors that some
users may want to overwrite. The procedures to do so are provided here
along with some limitations of the feature.
---
 features/sshconfig-imports.mdx | 47 ++++++++++++++++++++++++++++++++++
 mint.json                      |  1 +
 2 files changed, 48 insertions(+)
 create mode 100644 features/sshconfig-imports.mdx

diff --git a/features/sshconfig-imports.mdx b/features/sshconfig-imports.mdx
new file mode 100644
index 0000000..0db6a0b
--- /dev/null
+++ b/features/sshconfig-imports.mdx
@@ -0,0 +1,47 @@
+---
+title: 'SSH Config Imports'
+description: 'Import your local SSH Configuration'
+icon: 'file-import'
+---
+
+## How To Use
+You have the ability to import your SSH Configuration in two ways.
+- The `remote:parse` command which takes no arguments
+- The **Import** Button on the **Connections** page
+
+## Limitations
+- Remotes that have previously been created and not been deleted cannot be overwritten by an import with the same canonical name or alias. Any conflicts will be skipped when attempting an import. If you wish to replace the manually entered version, you may do so by deleting the existing remote and importing your config file afterward.
+- Imported Remotes cannot be edited in the app. To edit these, you must edit the config file and import it again.
+- You can only have one identity file per remote.
+- Imported Remotes can be deleted in the app, but they will come back upon importing again. They will stay removed if you follow the [procedure below](#waveoptions-keyword).
+- Imported Remotes will default to the **Auto Connect Mode** if an identity file is provided. This can be overwritten to **Manual Connect Mode** if you follow the [procedure below](#waveoptions-keyword).
+
+## WaveOptions Keyword
+Waveterm allows a special keyword to be used in your ssh config to override the default behavior. In order to use this, you first must add the following at the top of your ssh config file (~/.ssh/config):
+```
+Host *
+    IgnoreUnknown WaveOptions
+```
+This will allow you to use the `WaveOptions` keyword for all of your hosts without ssh complaining about a keyword it doesn't understand. This alone will not do anything, but it gives you the option to use the features below.
+
+#### Ignore
+`Ignore` allows you to completely skip a host in your SSH config file. Upon import, waveterm will delete any previously imported remote with that name and will not create a new one. It is used as follows:
+```
+Host <host.com>
+    User <user>
+    IdentityFile <file>
+    ...
+    WaveOptions Ignore
+```
+Note that this requires the use of `IgnoreUnknown` described above. Once this has been added to your SSH config file, you must import again for it to take effect.
+
+#### ConnectMode
+By default, Waveterm will set up auto connection for an imported remote if an identity file is provided. This behavior can be overwritten to force manual connect mode with the following entry:
+```
+Host <host.com>
+    User <user>
+    IdentityFile <file>
+    ...
+    WaveOptions ConnectMode=manual
+```
+Note that this requires the use of `IgnoreUnknown` described above. Once this has been added to your SSH config file, you must import again for it to take effect.
\ No newline at end of file
diff --git a/mint.json b/mint.json
index 5592351..c8a81e0 100644
--- a/mint.json
+++ b/mint.json
@@ -56,6 +56,7 @@
         "features/history",
         "features/images",
         "features/markdown",
+        "features/sshconfig-imports",
 	"features/chatGPT"
       ]
     },