modernize sshaccess

Signed-off-by: Kevin Fenzi <kevin@scrye.com>

modules/sysadmin_guide/pages/sshaccess.adoc

@@ -16,7 +16,7 @@ Owner::
 Contact::
   #fedora-admin or admin@fedoraproject.org
 Location::
-  IAD2
+  All
 Servers::
   All IAD2 and VPN Fedora machines
 Purpose::
@@ -24,69 +24,68 @@ Purpose::
 
 == Introduction
 
-This page will contain some useful instructions about how you can safely
+This SOP contains information on how to setup access to
-login into Fedora IAD2 machines successfully using a public key
+fedoraproject.org servers via ssh from your client machines.
-authentication. As of 2011-05-27, all machines require a SSH key to
+
-access. Password authentication will no longer work. Note that this SOP
+All access requires ssh (secure shell), using keys.
-has nothing to do with actually gaining access to specific machines. For
+See
-that you MUST be in the correct group for shell access to that machine.
+https://docs.fedoraproject.org/en-US/fedora/latest/system-administrators-guide/infrastructure-services/OpenSSH/
-This SOP simply describes the process once you do have valid and
+for more detailed information on OpenSSH.
-appropriate shell access to a machine.
+
+Note that this SOP has nothing to do with actually gaining access
+to specific machines. For that you MUST be in the correct group
+for shell access to that machine. This SOP simply describes the
+process once you do have valid and appropriate shell access to a machine.
 
 == SSH configuration
 
-First of all: (on your local machine):
+1. Generate a ssh keypair on your local machine if you don't already have one.
+run: 'ssh-keygen -t ed25519'
+Make sure you enter a strong passphrase you can remember or have stored in a password manager.
+
+2. Setup your local client ssh config
 
 ....
 vi ~/.ssh/config
 ....
 
+(Or use any text editor you are comfortable with)
+
 [NOTE]
 ====
-This file, and any keys, need to be chmod 600, or you will get a "Bad
+This file, and any keys, need to be mode 600, or you will get a "Bad
 owner or permissions" error. The .ssh directory must be mode 700.
 ====
 
-then, add the following:
+then, add the following contents to that text file:
 
 ....
 Host bastion.fedoraproject.org
-  HostName bastion-iad01.fedoraproject.org
+  HostName bastion.fedoraproject.org
   User FAS_USERNAME (all lowercase)
   ProxyCommand none
   ForwardAgent no
 Host *.iad2.fedoraproject.org *.qa.fedoraproject.org 10.3.160.* 10.3.161.* 10.3.163.* 10.3.165.* 10.3.167.* *.vpn.fedoraproject.org batcave01
-  User FAS_USERNAME (all lowercase)
   ProxyCommand ssh -W %h:%p bastion.fedoraproject.org
 ....
 
-How ProxyCommand works?
+Note that there are 2 bastion servers: bastion01.fedoraproject.org
+and bastion02.fedoraproject.org. The 'bastion.fedoraproject.org' name
+should match whichever one is primary at any time. If for some reason
+you get connection refused or unreachable messages from it, you can manually
+change the above to specifically point to bastion01 or bastion02.
+Normally this should not be needed.
 
-A connection is established to the bastion host:
+3. Setup the fedora infrastructure ssh hostkey certificate authority:
 
-....
+download https://admin.fedoraproject.org/ssh_known_hosts
-+-------+            +--------------+
+and add it to (or create if it does not yet exist) a
-|  you  | ---ssh---> | bastion host |
+~/.ssh/known_hosts file.
-+-------+            +--------------+
-....
 
-Bastion host establish a connction to the target server:
+This tells OpenSSH to trust any host keys that are signed with
-
+the fedora infrastructure ssh certificate authority. This allows
-....
+you to know when you login to a machine that it's not been
-+--------------+          +--------+
+replaced or tampered with.
-| bastion host | -------> | server |
-+--------------+          +--------+
-....
-
-Your client then connects through the Bastion and reaches the target
-server:
-
-....
-+-----+                  +--------------+                +--------+
-| you |                  | bastion host |                | server |
-|     | ===ssh=over=bastion============================> |        |
-+-----+                  +--------------+                +--------+
-....
 
 == PuTTY SSH configuration
 
@@ -108,6 +107,16 @@ ____
 . In Connection:SSH:Auth remember to insert the same key file for
 authentication you have used on FAS profile
 
+== Using OpenSSH
+
+You can use openssh from any terminal to access machines you are granted access to:
+
+'ssh batcave01.iad2.fedoraproject.org'
+
+It's important to use the fully qualified domain name of the host you are trying
+to access so that the certificate matches correctly. Otherwise you may get a
+notice that the ssh host key is unknown.
+
 == SSH Agent forwarding
 
 You should normally have:
@@ -142,8 +151,7 @@ using your local username, thus it will fail.
 * `ssh -vv` is very handy for debugging what sections are matching and
 what are not.
 * If you get access denied several times in a row, please consult with
-#fedora-admin. If you try too many times with an invalid config your
+#fedora-admin.
-IP could be added to denyhosts.
 * If you are running an OpenSSH version less than 5.4, then the -W
 option is not available. In that case, use the following ProxyCommand
 line instead:
@@ -151,3 +159,35 @@ line instead:
 ....
 ProxyCommand ssh -q bastion.fedoraproject.org exec nc %h %p
 ....
+
+== How does ssh ProxyCommand work?
+
+ProxyCommand configures OpenSSH to use your fas username to access
+bastion.fedoraproject.org directly, and then in turn to use
+bastion.fedoraproject.org as a proxy to all the other listed
+hosts.
+
+A connection is established to the bastion host:
+
+....
++-------+            +--------------+
+|  you  | ---ssh---> | bastion host |
++-------+            +--------------+
+....
+
+Your client runs the proxy command on the bastion server to connect to the target:
+
+....
++--------------+          +--------+
+| bastion host | -------> | server |
++--------------+          +--------+
+....
+
+Your client then connects through the Bastion and reaches the target server:
+
+....
++-----+                  +--------------+                +--------+
+| you |                  | bastion host |                | server |
+|     | ===ssh=over=bastion============================> |        |
++-----+                  +--------------+                +--------+
+....