Help:Access to Toolforge instances with PuTTY and WinSCP

From Wikitech
Jump to navigation Jump to search

This page documents Single-click solutions for accessing your Toolforge instances using PuTTY and WinSCP. For other Cloud VPS project than Tools, instructions differ.

With the correct settings, a single click shell connection or file transfer is possible, and no command line input trouble is needed.



  • USERNAME: your username on wikitech and Toolforge
  • PATH-TO-YOUR-PRIVATE-KEY: the path and name of your private key file on your local system


  • PuTTY
  • WinSCP
  • plink.exe (part of PuTTY suite)
  • Pageant (PuTTY authentication agent, part of both the PuTTY and WinSCP suites)

How to set up PuTTY for direct access to your Toolforge account

You are likely going to set up connections to each of the login servers:

20130526 1941 Putty Login Session tools-dev.png 20130526 1941 Putty Login Session tools-login.png

The remaining configuration options are identical for all login servers. Of course, you may prefer screen and scroll buffer sizes of your choice:

20130526 1941 Putty Login Window.png 20130526 1941 Putty Login Translation.png

Adding a keep-alive time will prevent your connection from dropping when inactive.

20130526 1941 Putty Login Connection.png 20130526 1941 Putty Login Connection Data.png 20130526 2133 Putty Login Connection SSH Auth.png

How to set up WinSCP for direct access to your Toolforge account

With WinSCP you must setup a site pointing to the adequate hostname and change the advanced settings to use your private key file on the authentication tab.

WINSCP screen 2.png WINSCP screen advanced settings.png WINSCP screen advanced settings authentication.png

After connecting to your Toolforge account with WinSCP, you may then wish to connect to a particular TOOL account directory (e.g. foobot, or my-tool, etc). Following are instructions (using WinSCP v5.5.0).

  • Access the root directory by clicking the root directory icon. (A folder icon with a backwards slash in the right/remote pane of WinSCP) You will now be in /<root>.
  • Scroll down to the the data directory and double click to access.
  • Next double-click on the project directory. (accessing some of these directories may take several seconds, so be patient)
  • Scroll down to the tool of your choice and double-click. You are now in your chosen TOOL directory.

To get back to your Toolforge account directory click the root directory icon again, then home, then scroll down to your username directory and double-click.

Troubleshooting permissions errors

Sometimes the file system permissions on the tool's directory (/data/project/$TOOL) can get messed up and be missing the group write permission. You can check the current permissions by logging into a bastion and showing the directory:

$ ssh
$ ls -ld /data/project/bd808-test
drwxrwsr-x 7 tools.bd808-test tools.bd808-test 4096 Jul 19 15:07 /data/project/bd808-test/

The "drwxrwsr-x" section in the output above is the directory permissions. Each letter tells you something about the permissions mask on the file system:

  • "d" - this is a directory.
  • "rwx" - These are the permissions for the directory's owning user. "r" - read, "w" - write, "x" - eXecute.
  • "rws" - These are the permissions for the directory's owning group. "r" - read, "w" - write, "s" - sticky. Sticky implies execute and also attempts to set the same group ownership on all new files and directories created inside the directory.
  • "r-x" - These are the permissions for "other" users (users who are not the owner or in the owning group). The "-" means that other users cannot write to this directory.

Your user should be a member of the owning group for the directory. When you cannot upload files the problem is often that the "w" write permission is missing for the group on either the tool's directory itself or on a subdirectory or file that you are trying to change. Fixing that is as easy as logging into a bastion, becoming the tool, and changing the permissions:

$ ssh
$ become $MY_TOOL
$ chmod -R g+w /data/project/$MY_TOOL
# Recusively grant write permission to the group on all files and directories.