From 847b2c9596ec4df06be35bddfa9ad74d0513b88a Mon Sep 17 00:00:00 2001
From: Akemi Izuko <akemi@noway.moe>
Date: Sun, 26 May 2024 18:32:39 -0600
Subject: [PATCH] Readme: init

---
 README.md | 204 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 204 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9728343
--- /dev/null
+++ b/README.md
@@ -0,0 +1,204 @@
+# SSH config+
+
+Streamline repetitive ssh config files with trait-style property inheritance!
+
+ssh_config+ is meant for users with very large and repetitive ssh configs. This
+includes templating, an inheretence-style way of copying fields, and for loops
+to reduce repetitive lines.
+
+See the `example/` directory for an idea of capabilities, but here's a snippet:
+
+```yaml
+__preamble:
+  ssh_props:
+    Port: 22
+    IdentitiesOnly: yes
+    ForwardX11: no
+
+__uni_template:
+  template: __preamble
+  ssh_props:
+    IdentityFile: ~/.ssh/computer_labs_key
+    User: emiliko
+
+undergrad:
+  template: __uni_template
+  ssh_props:
+    Hostname: ug22.cs.ualberta.ca
+
+ohaton:
+  template: __uni_template
+  ssh_props:
+    Hostname: ohaton.cs.ualberta.ca
+
+coronation:
+  template: __uni_template
+  ssh_props:
+    Hostname: coronation.cs.ualberta.ca
+```
+
+## Rules
+
+The `src/ssh_config_to_yaml.py` script will assist in quickly migrating your
+existing config.
+
+#### SSH Properties
+
+Standard SSH config properties go under the `ssh_props` heading for every host.
+For example:
+
+```sshconfig
+Host github.com
+    Hostname github.com
+    IdentityFile ~/.ssh/github_main
+    LocalForward 3306 localhost:3306
+    LocalForward 3302 localhost:3302
+    LocalForward 3000 localhost:3000
+```
+
+Becomes:
+
+```yaml
+github.com:
+  ssh_props:
+    Hostname: github.com
+    IdentityFile: ~/.ssh/github_main
+    LocalForward:
+      - 3306 localhost:3306
+      - 3302 localhost:3302
+      - 3000 localhost:3000
+```
+
+Note that yaml does not support duplicate keys, so keys can take a list of
+properties instead to mimic repeated keys, as seen above.
+
+#### Templates
+
+Templates are "default" properties inherited from another host. Templates must
+be declared above the host that uses it. You can make a template-only host by
+declaring it with `__` at the start of the name. You can also use another host
+as a template.
+
+```yaml
+__preamble:
+  ssh_props:
+    Port: 22
+    IdentitiesOnly: yes
+    ForwardX11: no
+
+#############################################################################
+# Uni Computers
+#############################################################################
+__uni_template:
+  template: __preamble
+  ssh_props:
+    IdentityFile: ~/.ssh/id_ed25519
+    User: emiliko
+
+ohaton:
+  template: __uni_template
+  ssh_props:
+    Hostname: ohaton.cs.ualberta.ca
+
+coronation:
+  # Using __uni_template here would make more sense outside an example
+  template: ohaton
+  ssh_props:
+    Hostname: coronation.cs.ualberta.ca
+```
+
+Will generate:
+
+```sshconfig
+Host ohaton:
+    ForwardX11 no
+    Hostname ohaton.cs.ualberta.ca
+    IdentitiesOnly yes
+    IdentityFile ~/.ssh/id_ed25519
+    Port 22
+    User emiliko
+
+Host coronation:
+    ForwardX11 no
+    Hostname coronation.cs.ualberta.ca
+    IdentitiesOnly yes
+    IdentityFile ~/.ssh/id_ed25519
+    Port: 22
+    User emiliko
+```
+
+As a note, properties inherited from templates will be overwritten entirely,
+even if they're multi-valued. For example:
+
+```
+__uni:
+  ssh_props:
+   LocalForward:
+    - 3306 localhost:3306
+    - 3302 localhost:3302
+    - 3000 localhost:3000
+
+ohaton:
+  template: __uni
+  ssh_props:
+      LocalForward:
+       - 9000 localhost:9000
+```
+
+Will overwrite all the `LocalForward` properties provided by the `__uni`
+template, generating:
+
+```sshconfig
+Host ohaton
+    LocalForward 9000 localhost:9000
+```
+
+#### For loops
+
+For loops allow simple substitution of a single variable over a range or set of
+values. Ranges must be numerical, but sets can be any arbitrary string. Multiple
+different for loops can be declared under the `for` section.
+
+```yaml
+orca:
+  ssh_props:
+    Hostname: 10.42.43.1
+    User emiliko
+  for:
+    - variable: port
+      range:
+        from: 9026
+        to: 9042
+      template: LocalForward ${port} localhost:${port}
+    - variable: env
+      range: ["FOO=bar", "BAR=foo"]
+      template: SendEnv ${env}
+```
+
+Expands to:
+
+```sshconfig
+Host orca
+    Hostname 10.42.43.1
+    LocalForward 9026 localhost:9026
+    LocalForward 9027 localhost:9027
+    LocalForward 9028 localhost:9028
+    LocalForward 9029 localhost:9029
+    LocalForward 9030 localhost:9030
+    LocalForward 9031 localhost:9031
+    LocalForward 9032 localhost:9032
+    LocalForward 9033 localhost:9033
+    LocalForward 9034 localhost:9034
+    LocalForward 9035 localhost:9035
+    LocalForward 9036 localhost:9036
+    LocalForward 9037 localhost:9037
+    LocalForward 9038 localhost:9038
+    LocalForward 9039 localhost:9039
+    LocalForward 9040 localhost:9040
+    LocalForward 9041 localhost:9041
+    SendEnv FOO=bar
+    SendEnv BAR=foo
+    User emiliko
+```
+
+For loops can be part of templates