add ssh troubleshooting guide

capsulflask/landing.py

@@ -28,6 +28,10 @@ def faq():
 def about_ssh():
   return render_template("about-ssh.html")
 
+@bp.route("/troubleshooting-ssh")
+def troubleshooting_ssh():
+  return render_template("troubleshooting-ssh.html")
+
 @bp.route("/changelog")
 def changelog():
   return render_template("changelog.html")

capsulflask/templates/about-ssh.html

@@ -194,6 +194,13 @@
   <span class="code">/Users/username</span> on MacOS). 
 </p>
 
+<p> 
+  Also, note that as the <span class="code">.ssh</span> folder's name starts with a period, it is a "hidden" folder. 
+  This just means that your operating system's Graphical User Interface (GUI) will not display it by default.
+  All operating systems have a way to enable "Show Hidden Files" in the GUI, otherwise you can always access it via the
+  command line.
+</p>
+
 <p> 
   If the user asks the SSH client to connect to a server it has never seen before, 
   it will print a prompt like this to the terminal:

capsulflask/templates/capsul-detail.html

@@ -105,6 +105,9 @@
       </div>
       
     </div>
+    <div class="row">
+      <span>Can't log into your capsul? See <a href="/troubleshooting-ssh">Troubleshooting SSH</a></span>
+    </div>
     <div class="row center justify-start vm-actions">
       <label class="align" for="delete_action">Actions</label>
       <form id="delete_action" method="post">
@@ -202,8 +205,13 @@ SHA256:{{ key.sha256 }} ({{ key.key_type }}){% endfor %}</pre>
   </pre>
     </div>
     <div class="row">
-      <span>(What's this? see <a href="/about-ssh">Understanding the Secure Shell Protocol (SSH)</a>)</span>
+      <span>What's this? see <a href="/about-ssh">Understanding the Secure Shell Protocol (SSH)</a></span>
     </div>
+    <div class="row third-margin">
+      <span>Can't log into your capsul? See <a href="/troubleshooting-ssh">Troubleshooting SSH</a></span>
+    </div>
+
+    
   {% endif %}
 {% endif %}
 

capsulflask/templates/faq.html

@@ -19,13 +19,17 @@
      <p>f1-x: gitlab (wow such memory very devops)</p>
      <p>f1-xx: something gargantuan</p>
    </li>
-   <li>
+   <li  id="how-to-log-in">
      How do I log in?
      <p>ssh to the ip provided to you using the cyberian user.</p>
      <pre class='code'>$ ssh cyberian@1.2.3.4</pre>
      <p>For more information, see <a href="/about-ssh">Understanding the Secure Shell Protocol (SSH)</a>.</p>
    </li>
-   <li>
+   <li  id="help-ssh">
+     Help, I still can't log into my capsul!
+     <p>See <a href="/troubleshooting-ssh">Troubleshooting SSH</a>.</p>
+   </li>
+   <li  id="change-to-root-user">
      How do I change to the root user?
      <p>The cyberian user has passwordless sudo access by default. This should work:</p>
      <pre class='code'>

capsulflask/templates/troubleshooting-ssh.html

@@ -0,0 +1,110 @@
+{% extends 'base.html' %}
+
+{% block title %}SSH Troubleshooting{% endblock %}
+
+{% block content %}
+  <div class="row full-margin"><h1>Why can't I SSH to my capsul?</h1></div>
+{% endblock %}
+
+{% block subcontent %}
+<div class="long-form">
+
+  <p>
+    There are a few common reasons why your SSH command might not be working:
+  </p>
+
+  <ol>
+    <li>
+      The command wasn't quite formatted correctly or had a typo.
+      <ul>
+        <li>The correct format is: <span class="code">ssh cyberian@&lt;ip-address&gt;</span></li>
+
+        <li>Here's an example: <span class="code">ssh cyberian@69.61.2.166</span></li>
+      </ul>
+    </li>
+    <li>
+      The username or ip address wasn't right.
+      <ul>
+        <li>
+          Unless you set up a different user for yourself, 
+          the default username for logging into a capsul will always be <span class="code">cyberian</span>
+        </li>
+        <li>
+          Although we try our best to prevent this, in some situations the IP address of a capsul can change.
+          You can always get up-to-date IP address information for your capsuls at 
+          <a href="https://capsul.org/console">https://capsul.org/console</a>
+        </li>
+      </ul>
+    </li>
+    <li>
+      Your SSH key is not configured correctly, or the key(s) you have configured don't match
+      the one you uploaded to capsul.org and assigned to your capsul when you created it.
+      <ul>
+        <li>
+          The <span class="code">ssh</span> command line application (OpenSSH Client) looks for keys to use in 
+          <span class="code">~/.ssh</span>. 
+          It will try to use each key that it finds there until either one of them works, it runs out of keys to try,
+          or the server tells it "too many failed attempts" and closes the connection.
+          <br/>
+          <br/>
+          (the tilde <span class="code">~</span> here represents the user's home directory, 
+          <span class="code">/home/username</span> on linux, 
+          <span class="code">C:\Users\username</span> on Windows, and 
+          <span class="code">/Users/username</span> on MacOS).
+          <br/>
+          <br/>
+          Also, note that as the <span class="code">.ssh</span> folder's name starts with a period, it is a "hidden" folder. 
+  This just means that your operating system's Graphical User Interface (GUI) will not display it by default.
+  All operating systems have a way to enable "Show Hidden Files" in the GUI, otherwise you can always access it via the
+  command line.
+        </li>
+        <li>
+          You can also specify an additional key file for ssh to try using with the <span class="code">-i</span> flag.
+          For example: <span class="code">ssh -i /path/to/my/key_file cyberian@&lt;ip-address&gt;</span>
+        </li>
+        <li>
+          You may also use the <span class="code">ssh-keygen</span> command to generate a new key-pair, however this
+          won't help you if you are locked out of your existing capsul.
+        </li>
+        <li>
+          If you lost your SSH key permanently, sorry, but we cannot help you log into your capsul. Our policy is we
+          do not touch capsuls after they are created.
+        </li>
+      </ul>
+    </li>
+    <li>
+      You happen to have a lot of SSH keys, and you are being trolled by the SSH client.
+      <ul>
+        <li>
+          Like I mentioned, OpenSSH Client will try to use each key that it finds in <span class="code">~/.ssh</span>
+          until either one of them works, it runs out of keys to try, or the server tells it 
+          "too many failed attempts" and closes the connection.
+        </li>
+        <li>
+          If you specify an additional key file for ssh to try using with the <span class="code">-i</span> flag,
+          it won't try that one first. Personally I consider this to be extremely toxic behavior. It is what it is.
+        </li>
+        <li>
+          Here's the solution: <a href="https://superuser.com/questions/268776/how-do-i-configure-ssh-so-it-doesnt-try-all-the-identity-files-automatically">
+            superuser.com: how-do-i-configure-ssh-so-it-doesnt-try-all-the-identity-files-automatically
+          </a>
+          <br/>
+          <br/>
+          Add the <span class="code">-o IdentitiesOnly=yes</span> flag to tell it to only  
+          attempt the keys specified on the command line with <span class="code">-i</span>
+          <br/>
+          <br/>
+          Full example: <span class="code">ssh -o IdentitiesOnly=yes -i test_rsa_2 cyberian@&lt;ip-address&gt;</span>
+        </li>
+      </ul>
+    </li>
+  </ol>
+
+
+  
+
+</div>
+{% endblock %}
+
+{% block pagesource %}/templates/about-ssh.html{% endblock %}
+