[[Include(WikiToC)]]
=== Common SSH Tips and Info === #tips
==== If you deleted the "@internal1" key from your profile

As long as you have at least one public key configured in your profile, use your SSH client to connect to {{{gw.orbit-lab.org}}} and run the following commands there. You do not need to make a reservation in the scheduler for this.

{{{
rm ~/.ssh/id_rsa
rm ~/.ssh/id_rsa.pub
ssh-keygen -t rsa -C "@internal1"
}}}

Press 'Enter' at every prompt so that the default filename (id_rsa) and no password is used.

Then type the following command:

{{{
cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
}}}

The internal key should now be restored.

==== Prevent ```unknown host key``` error when connecting to node
Configure you ssh client not to use `strict host key checking`

For openssh, this is `-o StrictHostKeyChecking=no` or the same in the .config file


==== Using a .config file for SSH (Linux, Mac, and WSL ONLY) ==== #config

We'd like to do a few things for convenience:

1. log into nodes as root by default
1. allow forwarding of X11 applications
1. Suppress annoying host key warnings

First, log into any console, or gw.orbit-lab.org

After logging in, create or modify the file at {{{~/.ssh/config}}}

Add the following to the file

{{{
Host sdr?-md* sdr?-s?-lg* srv?-co* srv?-lg* node?-* node??-*
  User root
  UserKnownHostsFile /dev/null
  StrictHostKeyChecking no
  ForwardX11 yes
}}}

* Host: The Host line matches common naming conventions for nodes within the testbed
* User: root is set to match the common default for baseline
* !UserKnownHostsFile: is set to /dev/null to prevent saving new host keys for nodes
* !StrictHostKeyChecking: disables the warning message. SSH complains when host keys for a dns name change. This is a useful security feature, but is inconvenient within the testbed, where the operating system on a trusted machine changes frequently. Do not set it as a wildcard default for public endpoints, or you will be vulnerable to spoofing or man in the middle attacks.
* ForwardX11: allows the forwarding of graphical applications running the X11 protocol from a node back to your machine

=== Tips for working on a remote system

==== Handling sessions and disconnections

To avoid losing your place if disconnected, use something like [https://github.com/tmux/tmux/wiki Tmux]. This will allow you to have multiple tabs, or windows, with a single ssh connection. In addition, you'll be able to reconnect to this set-up if your connection drops.

Warning: On the consoles, when your reservation ends, all of your processes will be killed, including tmux sessions.

==== File management
To move files between your machine and the consoles, the simplest method is something like SCP.
For a graphical client, one example is !FileZilla, over scp or sftp.

To move files to a node, this is normally a two step process. Local -> Console, Console -> node.

By using a !ProxyJump directive in your local machine's `~/.ssh/config` file, you can do this in "1" step, but this is an advanced method. When accessing the node, your ssh client with automatically proxy the connection via the console.

An example file is:
{{{
Host node1.cosmos-lab.org
User root
ProxyJump console.cosmos-lab.org
}}}


For development on nodes, we recommend using git, and having both your local machine and the console or node pull from the repo.


=== Client Security Info
==== Allowed Key Types and security
SSH authentication has been configured following the security guidelines from [https://infosec.mozilla.org/guidelines/openssh.html#modern-openssh-67 Mozilla OpenSSH 6.7+]

Weak key types, algorithms, ciphers, and MACs are denied.

Specifically, the following types are allowed:
- rsa with key length >= 2048
- ecdsa
- ed25519

Any modern key should work, but if you have a very old key, it may be of an old type, or of insufficient length.

==== Key Generation
===== Passphrase
Most importantly, set a passphrase. Usage of this key both allows access, and identifies the user as you. If your key is lost or stolen, you may be responsible for actions taken.

===== Key types
We recommend ed25519 keys, mostly due to ease of use, as they can be both secure and quite short.

Using OpenSSH >= 6.7: `ssh-keygen -a 100 -t ed25519`

==== Key Installation

===== Linux
  The easiest way is to create a `~/.ssh/config` file, that looks like the following:
{{{
Host *.cosmos-lab.org
User USERNAME
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
}}}

Customize to your needs.
- Host specifies that this will be applied for anything in the cosmos-lab.org domain
- User is the username to use
- !IdentityFile specifies the path to the private key to use. It must have permissions 600.
- !IdentitiesOnly tells the client to only use the key specified. Our servers will deny access if too many different keys are attempted in one connection.

For convenience, you can use ssh-agent to automatically unlock and apply your key configuration based on your desktop login session. This may be done automatically on some distros, such as Ubuntu 18.04 Desktop

===== MacOS
You can follow the same steps as for linux, if using the built-in ssh client and terminal emulators.

You can configure your keyring to unlock your ssh keys, so again, please use keys with passphrases.

===== Windows

Common ssh clients for Windows:
- [https://docs.microsoft.com/en-us/windows/wsl/install-win10 WSL on Windows 10]: follow the steps for linux.
- [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html Putty] Very widely used. 
- [https://mobaxterm.mobatek.net/ MobaXterm] Has tabs, and a convenient Xserver for graphical forwards.
- [https://www.bitvise.com/ssh-client-download Bitvise] Has easy to use port forwarding config

For all of these, please make sure to generate or export your public key in "OpenSSH" format, as it will be applied on a Linux server.

==== Removing or changing keys
Once logged in, your allowed public keys are listed in the file `~/.ssh/authorized_keys`

The profile management page on the website reflects this file.

Please do not delete the first key on this list, as this allows moving between cosmos machines, such as console and gateway, but does not affect external access. If missing, it will be re-generated periodically.

If you remove ALL keys, you must upload a new one via the webUI, as you will have no other way to access the systems.