Page MenuHomePhabricator

Improve SSH access information in onboarding documentation
Closed, ResolvedPublic

Description

It seems that folks have trouble with gaining SSH access and would appreciate improved documentation. Some notes taken that show examples of this trouble:

Notes from Zareen, found at https://wikitech.wikimedia.org/wiki/Production_shell_access#Other_tips:

(Note from Dan: this seems quite painful, we should see if there are any unnecessary steps).

  1. Follow Request Access steps: https://wikitech.wikimedia.org/wiki/Production_shell_access#Requesting_access
  2. Once the ticket has been resolved, create a config file under ~/.ssh on your laptop (if it doesn’t exist already)
  3. Copy and paste this into config file (edit User and IdentityFile - only provide path to private key, don’t actually paste private key) and save
Host bast1001.wikimedia.org
    # Direct connection for the bastion host
    ProxyCommand none
    ControlMaster auto

Host *.wikimedia.org *.wmnet !gerrit.wikimedia.org !git-ssh.wikimedia.org
    User your_username_here
    # Everything else goes via bastion acting as a proxy
    ProxyCommand ssh -a -W %h:%p bast1001.wikimedia.org
    # Do not offer other identities loaded in ssh-agent
    IdentitiesOnly yes
    IdentityFile ~/.ssh/your_production_ssh_key
  1. https://wikitech.wikimedia.org/wiki/Production_shell_access#SSH_configuration
  2. ssh bast1001.wikimedia.org into terminal
  3. You will be prompted to enter your ssh password (if there is one)
  4. Now you are in the bastion server, but still need to connect to the access groups
  5. Exit bastion
  6. Go back to config file on your laptop and copy and paste (edit User and IdentityFile) and save (this may be different for different access groups, for example stat1002.eqiad.wmnet needs the Host *.eqiad.wmnet configurations but another access group may require different host configurations) :
## Internal Zones
Host *.wmnet
    User your_username_here
    IdentitiesOnly yes
    IdentityFile ~/.ssh/your_production_ssh_key

Event Timeline

Nuria added subscribers: Zareenf, mpopov, Nuria.

Can we be specific as to what needs improvements to help ops document what is needed? cc @Zareenf, @Tbayer @mpopov who had had trouble with this in the past

Can we be specific as to what needs improvements to help ops document what is needed? cc @Zareenf, @Tbayer @mpopov who had had trouble with this in the past

Have you already had a look at the notes mentioned in the task description?

This task will be seen by the ops on cleaning duty next week. It will help to have a list of issues so they can know what problems the documentation needs to address.

@Tbayer, I copied Zareen's notes in the description, please add anything else that you think is painful about SSH access.

MoritzMuehlenhoff triaged this task as Medium priority.

I'll take care of that.

@Tbayer, I copied Zareen's notes in the description, please add anything else that you think is painful about SSH access.

I'll take care of that.

Thanks Dan and Moritz! Yes, I think vetting and - if appropriate - merging these nine steps is likely to advance progress on this task. Overall, it seems that identifying the precise list of things that need to be fixed is the main task here. And considering that for users, SSH onboarding is a one-off activity which often involves having to become more familiar with SSH generally at the same time, they are not in the best position to do this work. I would suggest doing the following (after processing Zareen's notes):

  1. Have an expert about our current setup do a thorough read through the existing documentation and either confirm that, from their perspective, it should all work as intended, or list parts that need to be updated or fixed.
  2. Test the existing documentation by creating a new (dummy) account from scratch following the prescribed steps exactly.

Once that is done, we could go back and ask users for any remaining pain points.

The version history of the documentation ( https://wikitech.wikimedia.org/w/index.php?title=Production_shell_access&action=history https://wikitech.wikimedia.org/w/index.php?title=SSH_access&action=history ) shows edits by several non-experts who apparently recorded insights from their own trial-and-error there (including e.g. @JKatzWMF and @Neil_P._Quinn_WMF). That clearly isn't the most efficient way to write good documentation, as much as I appreciate that it consists of wiki pages that allow anyone contribute their knowledge (as I frequently do myself).

PS: Perhaps (I haven't checked in detail) there are also things that could be adapted from the SSH documentation changes @Cdentinger recently made to the Fundraising part of that page ("geared toward less technical users").

CCing @diego and @RobH who (judging from IRC scrollback) grappled quite a bit too with the existing onboarding process the other day. Just in case they have useful input from recent memory on the shortcomings of the current documentation.

This task has been assigned to the same task owner for more than two years. Resetting task assignee due to inactivity, to decrease task cookie-licking and to get a slightly more realistic overview of plans. Please feel free to assign this task to yourself again if you still realistically work or plan to work on this task - it would be welcome!

For tips how to manage individual work in Phabricator (noisy notifications, lists of task, etc.), see https://phabricator.wikimedia.org/T228575#6237124 for available options.
(For the records, two emails were sent to assignee addresses before resetting assignees. See T228575 for more info and for potential feedback. Thanks!)