Bug #2380

Fix bugs in Windows SSH instructions, and split off to a separate page (use template includes to show identical workbench-side content on both).

Added by Tom Clegg over 5 years ago. Updated about 5 years ago.

Status:
Resolved
Priority:
Normal
Assigned To:
Radhika Chippada
Category:
-
Target version:
Start date:
06/30/2014
Due date:
% Done:

100%

Estimated time:
(Total: 10.00 h)
Story points:
1.0

Description

Known bugs:

Proxy doesn't work (just hangs forever) until you add switchyard's public key to your cache. See #2381.

Instructions for getting into the Control Panel are missing some steps. Control Panel has various ways of presenting itself to make it harder to find what you need. Microsoft says the way to change your environment variables (at least in XP) is
  1. Click Start menu
  2. Right-click My Computer
  3. Click Properties
  4. Click Advanced tab
  5. Click Environment Variables
  6. In the "system variables" section, .... (our instructions are fine once you get here)

Subtasks

Task #2658: Split Windows and Unix instructions into separate pagesResolvedRadhika Chippada

Task #2657: Fix up instructions for setting environment variablesResolvedRadhika Chippada

Task #2381: Putty setup instructions must include a step for adding switchyard's server key to the cache. Otherwise, proxy setup just hangs forever with no feedback.ResolvedRadhika Chippada

Task #3143: Review branch 2380-ssh-docResolvedRadhika Chippada


Related issues

Related to Arvados - Feature #2505: Recurring: Update doc site to ensure it is internally consistent and accurately reflects the current behavior of the software.Resolved12/02/2013

Associated revisions

Revision 0f8504de
Added by Radhika Chippada about 5 years ago

closes #2380
Merge branch '2380-ssh-doc'

Revision 4b2ab09e
Added by Radhika Chippada about 5 years ago

refs #2380 Needed to updated all docs referencing to SSH documentation.
Merge branch '2380-ssh-doc'

History

#1 Updated by Tom Clegg over 5 years ago

  • Subject changed from Split Unix and Windows SSH instructions into separate pages (use template includes to show identical workbench-side content on both). to Fix bugs in Windows SSH instructions, and split off to a separate page (use template includes to show identical workbench-side content on both).
  • Description updated (diff)

#2 Updated by Tom Clegg over 5 years ago

  • Target version set to 2014-05-07 Storing and Organizing Data

#3 Updated by Tom Clegg over 5 years ago

  • Tracker changed from Story to Bug

#4 Updated by Tom Clegg over 5 years ago

  • Assigned To set to Tom Clegg

#5 Updated by Tom Clegg over 5 years ago

  • Target version changed from 2014-05-07 Storing and Organizing Data to 2014-05-28 Pipeline Factory

#6 Updated by Tom Clegg over 5 years ago

  • Target version deleted (2014-05-28 Pipeline Factory)
  • Release deleted (4)

#7 Updated by Tom Clegg about 5 years ago

  • Target version set to 2014-07-16 Sprint

#8 Updated by Tom Clegg about 5 years ago

  • Assigned To deleted (Tom Clegg)

#9 Updated by Radhika Chippada about 5 years ago

  • Assigned To set to Radhika Chippada

#10 Updated by Radhika Chippada about 5 years ago

  • Status changed from New to In Progress

#11 Updated by Peter Amstutz about 5 years ago

Is bug #2377 a duplicate of this?

#12 Updated by Bryan Cosca about 5 years ago

Under Logging in using PuTTY (Windows)
Initial Configuration

Step 6.5: In cmd enter: plink -P 2222 %host"

#13 Updated by Radhika Chippada about 5 years ago

Ready for review. Below is the list of what has been updated:

- Windows environment related instructions are moved into a separate page

- Cleaned up the original documentation, which is now the unix only version, to remove the moved out windows instructions.

- Update the windows instructions to ensure that they are now working

- Removed "make sure to include semicolon and quotation marks" since the path did not work with this.

- Update the ssh-adding-public-key.png image and corresponding text changes.

#14 Updated by Brett Smith about 5 years ago

Reviewing 060faf2

  • Please consistently capitalize the following names: "SSH" (except when referring to the literal ssh command), "Unix," "Windows"
  • In page titles and links, "Accessing Arvados VM" would be better as "Accessing an Arvados VM," since the user may have access to several of them.
  • Now that the different platforms have separate pages, I think it would be cleaner to remove the subheads that refer specifically to the platform again (e.g., under "Getting your SSH key" on either page).
  • Instructions that refer to the Workbench interface are generally out-of-date with its recent changes. In particular, please double-check "Alternate way to add SSH keys" and "Using SSH to log into an Arvados VM."
  • please visit the Accessing Arvados VM with SSH - Unix/Windows Environments - this sentence seems to be missing a word and punctuation.

ssh-access-windows.html.textile.liquid

  • The Unix instructions refer to the site.arvados_api_host variable to avoid hardcoding references to qr1hi. Please do the same here.
  • if you are using the SSH client that comes with Cygwin you should follow the Unix - this sentence seems to be missing a word. Punctuation should go inside the parentheses.
  • There's trailing whitespace after the first bullet point under "Step 1 - Adding PuTTY to the PATH"
  • Click to save the Public Key. - might read better as Click the _Save public key_ button. Same comment about the private key below.
  • the Arvados Workbench page _Settings %(rarr)→% Virtual machines_ page. - You can trim one of the "page"s here.
  • If you see a hung terminal window with no futher action: open a new terminal window - "further" has a typo. Please provide instructions for how I open a new terminal window, and add a note that "shell" should be replaced with the name of the virtual machine the user wants to log in to. I wonder if these instructions should be moved up? Right now we believe that every user will have to do this before their first login, so it seems like it would be helpful to have the instructions before the first login, in case they stop reading when they get the hung terminal (I almost did myself).

#15 Updated by Brett Smith about 5 years ago

Reviewing a24c2a7a

  • This sentence (on both pages) still has operating system capitalization issues: "This document is for windows environments. If you are using a unix environment (Linux, OS X, Cygwin), please visit the [other page]."
  • "if you are using the SSH client that comes with Cygwin you should follow the Unix" - this sentence (still) seems to be missing a word. Punctuation should go inside the parentheses.
  • The new header "Generate key using ssh-keygen" needs some change to make it grammatical—e.g., "Generate a key…"
  • I'm concerned that the instructions to open a new terminal "from the Start menu" aren't specific enough. I'm not sure that many Windows users will realize this refers to what Windows calls the Command Prompt. Is it possible to be more specific?
  • Did you make a specific decision to leave the terminal plink instructions where they are, rather than moving them up? I think I'm fine with it if there's a reason; just want to double-check that the comment wasn't overlooked (since it went on for a while).

Thanks.

#16 Updated by Radhika Chippada about 5 years ago

Brett: updated as per your feedback.

I was actually looking at a different Cygwin location and missed the line you were actually referring to. It is now updated and I also corrected the unix url link in the Windows page, which was not working.

Used "Command Prompt" in place of "terminal".

I left the last plink instruction (in the hung command prompt window section) as is. I think it flows better with the sequence of instructions and moving it up would cause confusion.

Thanks.

#17 Updated by Brett Smith about 5 years ago

Reviewing 7410cd97

  • I'm not sure we should refer to the hung PuTTY window as a Command Prompt. I think we should only use that name to refer to the specific DOS-like CLI launched from the Windows Start menu, and call the hung PuTTY window something else. Calling PuTTY's window a terminal, as before, would be okay by me.
  • On the Unix SSH page, "This document is for unix environments" is missing capitalization for Unix.

#18 Updated by Brett Smith about 5 years ago

Reviewing 0456c653, and there's just one thing: the section "Alternate way to add SSH keys" still refers to an older version of the Workbench interface. For example, it talks about clicking the "user icon" instead of the user's e-mail address.

This ticket's title talks about using a template to hold these Workbench instructions and help keep them consistent. Would that help keep this sort of thing in sync?

#19 Updated by Radhika Chippada about 5 years ago

Brett, thanks for catching the user icon issue. I updated it to say email address.

I am not sure how hard /easy it is to introduce a template for the common stuff. Unless it is very easy, I think we should merge this into master at this time so that the documentation is at least functional and usable. If we want the template, do let me know if there is a sample implementation.

Thanks.

#20 Updated by Brett Smith about 5 years ago

Radhika Chippada wrote:

Brett, thanks for catching the user icon issue. I updated it to say email address.

Unfortunately, the section needs other updates related to Workbench interface changes. At least on our development environment right now, clicking the button to add a key no longer dynamically adds a row to the keys table. Instead, it takes you to a page to fill out the key's metadata, where every attribute is a separate row.

I am not sure how hard /easy it is to introduce a template for the common stuff. Unless it is very easy, I think we should merge this into master at this time so that the documentation is at least functional and usable. If we want the template, do let me know if there is a sample implementation.

Understood. Thanks.

#21 Updated by Radhika Chippada about 5 years ago

Brett, ah the evil cycle of ongoing updates and review process got me!

I updated the add key section and image. I also extracted the common ssh items into include files and reuse among the two files. Tested thoroughly by clicking on the links several times.

Please take one more look. I am hopeful I'm almost done bothering you with this. Thanks.

#22 Updated by Brett Smith about 5 years ago

ebd7d571 looks good to merge to me. Thank you.

#23 Updated by Radhika Chippada about 5 years ago

  • Status changed from In Progress to Resolved

Applied in changeset arvados|commit:0f8504de1ab3a0ff2e33d23cc421a150cacf5d86.

Also available in: Atom PDF