====== Using 'PuTTY' on Windows to Work On a Remote Linux Machine ====== Here are some hints how to login from a Windows machine to a Linux machine via SSH, e.g. to work natively with a ''git'' repo that is stored on the Linux machine. :!: Please note a user name has to be specified when logging in to the remote machine, so first an appropriate user has to be created on the remote machine. \\ ===== Download and Install 'PuTTY' ===== **''PuTTY''** is a terminal program that also supports SSH to log in to a remote machine over a network. It can be downloaded here: * [[https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html]] The best approach is to select and download the ''.msi'' installer that is a appropriate for your Windows version, i.e. the 32 bit or 64 bit version, so ''PuTTY'' can be run from the Windows start menu. The installation program includes a few utilities that are installed beside the ''PuTTY'' program itself. \\ ===== Using 'PuTTY' ===== When accessing a remote machine via SSH, the **host name** of the remote machine, the **name of a user** known on the remote machine and the **password of that user** have to be known to be able to log in. If the remote machine is accessed frequently, typing the password every time is a pain, so there is a possibility to create an **SSH key pair** on a local machine and transfer the public key to the remote machine, so it's no more required to enter a password. ''PuTTY'' can [[#Using SSH Keys with PuTTY|create and use an SSH key]] to support this, and it can save several profiles with different settings for several remote machines. \\ ===== Using SSH Keys with PuTTY ===== Run the PuTTY key Generator program **''PuTTYgen''** from the Windows start menu to create or manage one or more SSH keys that can be used to connect to a remote machine without having to enter a password. ==== Loading or Generating a Key ==== === Loading an Existing 'OpenSSH' Key === If an OpenSSH key pair has already been created, e.g. by running ''ssh-keygen'' on a Linux machine, the private key file (e.g. ''id_rsa'') and associated public key file (e.g. ''id_rsa.pub'') are usually located in the ''~/.ssh/'' directory on the Linux machine. The private key file can be imported via the ''Conversions''-->''Import Key'' menu and selecting the file, \\ === Generating a New Key === A new key pair can be generated by clicking the ''Generate'' button. \\ === Loading an Existing 'PuTTY' Key === An existing key can be loaded by clicking the ''Load'' button. \\ ==== Exporting the Public Key for OpenSSH on Linux ==== To be able to use the SSH key to login to a Linux machine, the //public// part of the SSH key pair has to be transferred to the Linux machine. Once a key has been loaded or generated, the associated public key in a format appropriate for OpenSSH on a Linux machine is displayed in the field labelled ''Public key for pasting into OpenSSH authorized_keys file:''. The text should start with something like ''SSH-RSA'', and it is a very long, single line of text that is wrapped into several lines in the ''PuTTYgen'' dialog. As the label suggests, this long line can be copied and pasted into the file ''~/.ssh/authorized_keys'' on the Linux machine. \\ ==== Saving the 'PuTTY' Key File ==== Once a SSH key has been loaded or generated, it has to be saved as ''PuTTY'' key file with extension ''.ppk'', which can later be used to specify a particular key for ''PuTTY''. When the file is saved, ''PuTTY'' may ask if you really want to save the file without password. If you specify a password, you will have to enter the password once before the key can be used, but it protects the key from being used by someone else, and thus increases security. \\ ===== Configuring 'PuTTY' ===== Run the **''PuTTY''** program from the Windows start menu and enter some information. ==== The 'Session' Tab ==== If a remote session has already been saved, a session can be selected and loaded here. If the settings are appropriate, you can click on the ''Open'' button to start the session. Otherwise the host name or IP address of the remote machine has to be entered in the ''Host Name'' field. The **''Port'' '22'** and **''Connection Type'' 'SSH'** should be selected by default, and this is usually OK. \\ ==== The 'Connection' Tab ==== There is a checkbox labelled ''Enable TCP keepalives'' which can be ticked to keep an SSH session alive even though there is no user interaction for some time. Without this option the remote SSH server might terminate the connection after some time without interaction. \\ === The 'Data' Section of the 'Connection' Tab === There is a field ''Auto-login username'' where you can enter the name of the user to log in at the remote system. \\ === The 'SSH' Section of the 'Connection' Tab === There is a field where you can specify a command to be executed on the remote machine. For example, you could enter cd /var/www/htdocs; /bin/bash ~~codedoc:clean:--~~login to immediately change to the specified directory when logging in to the remote machine. \\ === The 'SSH-->Auth' Section of the 'Connection' Tab === In the **''Auth''** part of the ''SSH'' section there is a field labelled **''Private key file for authentication''** where you can enter the name of a key file you have created before. If a valid private key file has been specified and the associated public key [[#Exporting the Public Key for OpenSSH on Linux|has been added to the 'authorized_keys' file]] on the remote Linux machine, you will be able to establish the remote connection without having to enter a password. \\ === The 'X11' Section of the 'Connection' Tab === If you want to run graphical programs on the remote machine, you have to make sure the checkbox labelled ''Enable X11 forwarding'' in this secrtion is ticked, and [[#Download and Install the X Server 'VcXserv'|an X server is running on the local machine]]. \\ ==== Other Settings ==== Of course there are many more settings in the remaining sections, but the default values are normally OK for most use cases, and you should only make changes if you know what you're doing. \\ ==== Saving the Session Profile ==== If you want to save the settings you've made as profile for later sessions, don't forget to go back to the [[#The 'Session' Tab|session tab]], make sure an appropriate name has been entered in the ''Saved Sessions'' field, and click on the ''Save'' button. This allows to quickly reload the set of sessions when connecting to the same remote machine next time. Finally click on the ''Open'' button to start the session. \\ ===== Download and Install the X Server 'VcXserv' ===== Programs with a graphic user interface (e.g. ''gitk'') running on a Linux/Unix machine require a so-called X server to display graphic dialogs and windows of the program. If working on a remote Linux/Unix machine, the graphic output can be forwarded via the network to an X server running on the local machine to display the graphic output, which looks exactly as if the program was running on the local machine. Most Unix-like operating systems run an X server anyway by default, but Windows doesn't, so on Windows, an X server must be explicitly installed and run to display the output of a graphics program that is running on a remote Linux machine. **''VcXserv''** is a nice, open source X Server implementation for Windows that can be downloaded here: * [[https://sourceforge.net/projects/vcxsrv/files/vcxsrv/]] From the Link above, select the version to download (the latest one should be good, e.g. 1.20.6.0), download the 32 bit version (e.g. vcxsrv.1.20.6.0.installer.exe) or 64 bit version (e.g. vcxsrv-64.1.20.6.0.installer.exe) of the installer, as appropriate for your Windows version. Then install and run the program, accepting all default settings. :!: Please note that **//X11 forwarding//** [[#The 'X11' Section of the 'Connection' Tab|has to be enabled]] for the SSH session that runs the program on the remote Linux machine. ---- --- //Martin Burnicki [[martin.burnicki@burnicki.net]] 2020-02-18//