Window of a terminal emulator

Use qnan.org: terminal

Background

SSH, or Secure Shell, is a protocol that allows a user to communicate information between the user and the server. This information includes files (SFTP) and commands (shell).

There are two common ways of authenticating a user to the server: using a password and using an SSH keypair. This server uses the latter. This means that instead of presenting the server your username and password, you present your username and proof that you have a private key associated with your SSH account.

Quick summary for using qnan.org's terminal

  1. Make an SSH keypair on your computer
  2. Email Philip the public key
  3. Wait for Philip to add your key to your shell account
  4. Configure your SSH client (if applicable)
  5. Log in!

First-time setup

On Linux, Unix, or MacOS X

  1. If you do not yet have an SSH keypair or don't know what one is:
    1. Open a terminal application. (On MacOS X it's called "Terminal"; on Unix, you surely know of, and have a favorite, terminal application.)
    2. Type ssh-keygen -b 2048
    3. Wait for your computer to generate the keypair
    4. Enter a passphrase when prompted, unless you feel that your computer is very secure. This passphrase protects your private key.
    5. Email the file ~/.ssh/id_rsa.pub to Philip
    Now you have an SSH keypair.
  2. Because Linux distributions, Unix distributions, and MacOS X typically come with an SSH client, no further setup should be necessary. For convenience, consider using an SSH key agent such as SSHKeychain for MacOS X or one of many graphical SSH key agents for Linux.

On Windows

  1. Download PuTTY and Pageant from the same site. If you do not have an SSH keypair or don't know what one is, also download PuTTYgen from the same site.
  2. If you downloaded PuTTYgen:
    1. Execute PuTTYgen
    2. Generate a key by clicking "Generate"
    3. Enter a key passphrase
    4. Click "Save private key" and save the key to a convenient place, such as a portable flash drive
    5. Repeat the step above for the public key
    6. Copy the already-highlighted public key text out of the program window and paste it into an email to Philip
    7. Exit PuTTYgen
    8. Delete PuTTYgen
    Now you have an SSH keypair.
  3. For convenience, configure Pageant to start automatically upon a user login by placing the executable (or a shortcut thereto) into Start -> Programs -> Startup
  4. Execute Pageant
  5. Right-click the Pageant icon in your taskbar, select "Add key", and point the file dialog at your SSH key
  6. Enter your SSH key's passphrase if prompted
  7. Execute PuTTY
  8. Configure a new session in PuTTY:
    1. In Session, enter "qnan.org" for Host Name
    2. In Session, enter "qnan.org" (or another identifying name, if you prefer) for Saved Sessions
    3. In Window -> Translation, select "UTF-8" from the character set dropdown
    4. In Connection -> Data, specify your username
    5. If you are behind a proxy, change the category Connection -> Proxy appropriately
    6. In Connection -> SSH, set the preferred SSH protocol option to "2 only"
    7. If you plan to run X programs from qnan.org, consider checking "Enable compression". Leave this unchecked otherwise, as it will increase latency.
    8. In Connection -> SSH -> Auth, uncheck the option "Attempt 'keyboard-interactive' auth (SSH-2)"
    9. If you have an X server locally and want to run X programs from qnan.org, enable X11 forwarding in the category Connection -> SSH -> X11
    10. In Session, click "Save"
    This process made a registry entry for this server on your computer. Consider exporting HKEY_CURRENT_USER\Software\SimonTatham\PuTTY\Sessions onto a portable flash drive to save time on other computers.

Day-to-day use

You will not be able to log in until Philip adds your public SSH key to your shell account's list of authorized keys. Please wait for notification that this took place before continuing.

On Linux, Unix, or MacOS X

  1. Open a terminal application.
  2. Type ssh [username]@qnan.org, where "[username]" is the username given to you by Philip. You can omit "[username]@" if your current username matches your username on qnan.org.
  3. If you are prompted with the message "The authenticity of host ... can't be established", do continue connecting. If instead you are prompted with any other scary-looking message, do not continue.
  4. If your private key is protected with a passphrase, you should be prompted for the passphrase now; enter it.
  5. At this point you should be logged in and at the shell prompt
  6. When you are finished using the terminal on qnan.org, return to the shell and press Ctrl-D to log off

On Windows

  1. If Pageant is not running, execute it
  2. If you have not yet added your SSH private key to Pageant's cache, right-click the Pageant icon in your taskbar, select "Add key", and point the file dialog at your SSH key.
  3. Execute PuTTY
  4. Double-click the "qnan.org" entry
  5. If you are prompted with the message "The server's host key is not cached in the registry", do continue connecting. If instead you are prompted with any other scary-looking message, do not continue.
  6. At this point you should be logged in and at the shell prompt
  7. When you are finished using the terminal on qnan.org, return to the shell and press Ctrl-D to log off

Manipulating your SSH keys

One advantage of using SSH keypairs for authentication is that you can have several keypairs: one for your laptop, one for your USB drive, one for your desktop, etc. Having one private key fall into the wrong hands does not mean that your account is compromised (unless you did not set a passphrase); like with credit card numbers, you would simply disassociate that keypair's public key from your account as soon as you become aware of a potential compromise.

Of course, you can only manipulate your SSH keys when you are able to log in to your account. The list of public SSH keys that are associated with your account is located in ~/.ssh/authorized_keys, with one key per line. The sshd daemon consults that file when someone attempts to log in with your username. You can manually add to and delete from there using any text editor.

If you lost your SSH private key and need help replacing the public key in ~/.ssh/authorized_keys, contact Philip. Include a new public key if you want the old one to be replaced with the new one.