====== SSH ======

SSH is the //Secure Shell//, a powerful encrypted communication tool. This page contains some basic information about the use of SSH.


======  SSH Software  ======

SSH client and server programs are included with almost all Linux distributions, Mac OS, and recent versions of Windows (later updates of 10 as well as 11). You can obtain SSH client and server software for most other platforms, including Android.

Here are some SSH clients (there are many others available):
^Platform^Software^Comments^
|Linux|OpenSSH|Included in almost all Linux distributions|
|OSX|OpenSSH|Included with OSX|
|ChromeOS (Chromebook)|Terminal|The terminal provided with current versions of Chrome provides ssh capabilities. Use the 'Linux' menu option but instead of starting a local Linux vm/container, create a remote ssh session.|
|Android|JuiceSSH|Free and premium versions available in the Google Play store.|
|Windows|OpenSSH|Included with Windows 10 onward; may not be installed automatically on Windows 10.|

======  Using SSH for a Text-Based Connection  ======

The most basic use of SSH is for a text-based connection used to enter commands and view command output, or execute a text-based application such a menu-driven system.

Some SSH clients have a graphical interface. For OpenSSH and others used from the command line, the most basic form of invocation is:

<code>
 ssh [[OPTIONS]] [user@]host command</code>

Note that the ssh command name may vary, depending on the software used.

Where:
  *  //user// is the name of the user account on the remote computer (optional, if the user account name is the same on both systems)
  *  //host// is the name or IP address of the remote computer
  *  //command// is the command to be executed on the remote computer (optional - the default is to open whatever shell or application is the default for the specified user)


Useful options include:
^Option^Description^Example^
|-C|Enable compression (gzip) to enhance performance|ssh -C //user//@//host//|
|-X or -Y|Turn on X11 forwarding (it is recommended that -C also be used) - See X11 Tunnelling, below|ssh -X -C //user//@//host//|
|-L or -R|Turns on tunnelling|(See Tunnelling section)|
|-i //identityfile//|Specifies the private key file to be used (default: all private keys in ~/.ssh)|ssh -i ~/.ssh/id_dsa //user//@//host//|
|-p //portnumber//|Connect to the TCP/IP port //portnumber// rather than the default SSH port 22.|ssh -p 2200 //user//@//host//|


=====  Examples  =====
  * Connect to a shell for account 'kim' on the computer 'winter': ''ssh kim@winter''
  * Like above, with compression: ''ssh -C kim@winter''
  * Run ''df -h'' on the remote system, and display the graphics on the local computer: ''ssh -XC kim@winter firefox''

=====  Simplified SSH Access  =====

If you're using OpenSSH (the ssh client used on most Linux systems and other platforms), you can simplify ssh command lines by placing host connection details in the file ''~/.ssh/config'' (or on Windows, ''%HOME%\.ssh\config''), like this: 

<code>
 Host "matrix"
         hostname "matrix.senecapolytechnic.ca"
         user "YourUserID"</code>

Once you have added these lines (inserting your user ID where appropriate) and set the permission on that file (on Linux, ''chmod 0600 ~/.ssh/config'') you can use this simplified command to access the server:

<code>
 ssh matrix</code>

You can similarly configure simplified access in most other SSH client programs.

======  Using SSH for File Transfer  ======

SSH provides two mechanisms for file transfer: //scp// and //sftp//. You can use these from the command line using the OpenSSH software (installed by default in most MacOS, Windows, and Linux systems) or you can use a graphical tool that uses these protocols.

=====  scp - Secure Copy  =====

The ''scp'' command, which is included as part of the OpenSSH software, functions like the normal Unix/Linux copy (cp) command, but accepts a hostname (and optional user ID) prepended to a filename for copying to/from remote systems:

<code>
  scp user@host:sourcefilename destinationfilename</code>
  
or

<code>
  scp sourcefilename user@host:destinationfilename</code>
  
====  Examples  ====

  * Copy the file ''/etc/hosts'' from this computer to the ''/tmp'' directory on the computer //ireland//: ''scp /etc/hosts ireland:/tmp''
  * Copy the file ''test.tar'' from the home directory of the user //chris// on the computer //ireland// to the current directory: ''scp chris@ireland:~/test.tar .''

=====  Graphical File Management over SSH  =====

Many graphical file managers, such as the GNOME //Nautilus// and KDE //Konqueror// programs (both on Linux) or graphical file managers (on many operating system platforms), know how to manage files remotely using the ssh/scp/sftp protocols.

For example, on GNOME, you can select the menu option Places>Connect to Server, enter the connection details, and view a file management window on a remote server. You can then rename, copy, move, and delete files using drag-and-drop operations (for example, you can copy a file by dragging it from your desktop to the remote window). You can also create bookmarks for rapid access to remote filesystems at a later date.

======  Using SSH with Public-Key Authentication  ======

Although SSH can be used with passwords, a sysadmin may need to initiate hundreds of SSH connections a day, and typing passwords that often is tedious. SSH therefore permits authentication using public and private keys.

=====  Background: Public Key Cryptography  =====

See [[Public Key Cryptography]] for an overview of how this technology works.

=====  Using Public Keys with SSH  =====

====  Creating a Public/Private Key Pair  ====

These instructions assume a Linux or Mac OS/X system running OpenSSH. Using OpenSSH on Windows will be similar except for file paths. Other SSH clients will have different procedures, and you'll need to check that the key produced is in OpenSSH format (you can convert key types using the ''ssh-keygen'' command on a Linux system such as Matrix if needed).

  -  Enter this command: ''ssh-keygen -ted25519''
    *  Answer the questions asked by ssh-keygen. Use default values for most questions. The use of a passphrase is **strongly** recommended. Avoid changing the filename from the default (unless there is a really good reason), because the location, name, and permission of keys is critical.
    *  ssh-keygen will produce two files:
      - ''~/.ssh/id_ed25519'' - your private key
      - ''~/.ssh/id_ed25519.pub'' - your public key

A note on key type and length: ssh-keygen can generate multiple types of keys, including rsa, dsa, ecdsa, and ed25519. Any of these types serves the same purpose, and rsa/dsa can be generated with varying key lengths. The longer the key, the more difficult it is to break the key by guessing it (trying successive values until the right key is found) - each bit added to the key doubles the number of possible key values. Key lengths of 1024-4096 bits are considered reasonably secure; as computers become faster, key lengths should be increased. Better yet, use the ed25519 eliptic curve option, which is considered the most secure format supported by the current OpenSSH implementation (8.4 as of the time of writing).

====  Sending the Public Key to a Remote System Administrator  ====
  -  Upload or email (or otherwise send) the ''~/.ssh/id_rsa.pub'' file to the remote system administrator. **Do NOT send your private key!**

====  Setting up Public Key Authentication on Two Machines  ====

Automatically (preferred approach):
  -  Run the command: ''ssh-copy-id //user@host//''

Manually:
  -  Copy the public key to the remote system you wish to access.
  -  Create the ''~/.ssh'' directory if it does not exist.
    *  Set the permission on ''~/.ssh'' to 0700
  -  Append the public key to the file ''~/authorized_keys''
    *  Set the permission on ''~/authorized_keys'' to 0600


======  Disconnecting from and Reconnecting to a Login Session  ======

The [[Screen Tutorial|GNU screen]] utility permits you to start a session, disconnect from it (accidentally or intentionally), and then reconnect from the same or another network connection. This is useful when you're using an unstable WiFi connection (e.g., in a coffee shop or mobile link) or want to start a long operation (such as a build or a test suite run) on campus, commute home while it's running, and then check on its status. Other tools such as tmux provide similar capabilities.

Note that this approach does not work with graphical applications (ssh -X), although software such as VNC can be used to provide disconnect/reconnect ability for graphical sessions.