diff --git a/docs/access/ssh.md b/docs/access/ssh.md index dd695db1..43b38345 100644 --- a/docs/access/ssh.md +++ b/docs/access/ssh.md @@ -3,7 +3,11 @@ Before accessing CSCS clusters using SSH, first ensure that you have [created a user account][account-management] that is part of a project that has access to the cluster, and have [multi factor authentification][mfa] configured. -It is not possible to authenticate with a username/password and user-created SSH keys: it is necessary to use a certified SSH key created using the CSCS SSHService, which is documented below. +[](){#sshservice} +## Generating Keys with SSHService + +It is not possible to authenticate with a username/password and user-created SSH keys. +Instead, it is necessary to use a certified SSH key created using the CSCS SSHService. !!! note Keys are valid for 24 hours, after which a new key must be generated. @@ -12,8 +16,6 @@ It is not possible to authenticate with a username/password and user-created SSH The number of certified SSH keys is limited to **five per day**. Once you have reached this number you will not be able to generate new keys until at least one of these key expires or keys are revoked. -## Generating Keys with SSHService - There are two methods for generating SSH keys using the SSHService, the [SSHService web app](https://sshservice.cscs.ch/) or by using a [command-line script](https://github.com/eth-cscs/sshservice-cli). ### Getting keys via the command line @@ -81,63 +83,93 @@ mv /download/location/cscs-key ~/.ssh/cscs-key chmod 0600 ~/.ssh/cscs-key ``` -## Logging in with the generated keys +### Adding a password to the key + +Once the key has been generated using either the CLI or web interface above, it is strongly reccomended that you add a password to the generated key using the [ssh-keygen](https://www.ssh.com/academy/ssh/keygen) tool. -Set up a passphrase on the private key: ``` ssh-keygen -f ~/.ssh/cscs-key -p ``` -Add the key to the SSH agent: +## Logging In + +To ensure secure access, CSCS requires users to connect through the designated jump host Ela (`ela.cscs.ch`) before accessing any cluster. + +Before trying to log into your target cluster, you can first check that the SSH key generated above can be used to access Ela: ``` -ssh-add -t 1d ~/.ssh/cscs-key +ssh -i ~/.ssh/cscs-key ela.cscs.ch ``` -??? warning "Could not open a connection to your authentification agent" - If you see this error message, the ssh agent is not running. - You can start it with the following command: - ``` - eval $(ssh-agent) - ``` - -Once the key has been configured, you can log in to CSCS' login system Ela: -```bash -# log in to ela.cscs.ch -> ssh -A cscs_username@ela.cscs.ch +To log into a target system at CSCS, you need to perform some additional setup to handle forwarding of SSH keys generated using the SSHService. +There are two alternatives detailed below. -# then jump to a cluster -> ssh clariden -``` +### Adding Ela as a jump host in SSH Configuration -### Set up SSH Config +This approach configures Ela as a jump host and creates aliases for the systems that you want to access in `~/.ssh/config` on your laptop or PC. +The benefit of this approach is that once the `~/.ssh/config` file has been configured, no additional steps are required between creating a new key using MFA, and logging in. -To simplify logging in, you can edit (or create) the SSH configuration file `$HOME/.ssh/config` on your laptop or PC. -A simple configuration for that simplifies logging into [Clariden][clariden] is: +Below is an example `~./.ssh/config` file that facilitates directly logging into the Daint, Santis and Clariden clusters using `ela.cscs.ch` as a Jump host: ``` Host ela HostName ela.cscs.ch - ForwardAgent yes - # replace with your CSCS username - User username + User cscsusername + IdentityFile ~/.ssh/cscs-key + +Host daint + HostName daint.alps.cscs.ch + User cscsusername + ProxyJump ela + IdentityFile ~/.ssh/cscs-key + IdentitiesOnly yes + +Host santis + HostName santis.alps.cscs.ch + ProxyJump ela + User cscsusername + IdentityFile ~/.ssh/cscs-key + IdentitiesOnly yes Host clariden HostName clariden.alps.cscs.ch ProxyJump ela - # replace with your CSCS username - User username + User cscsusername + IdentityFile ~/.ssh/cscs-key + IdentitiesOnly yes +``` -Host daint - HostName daint.alps.cscs.ch - ProxyJump ela - # replace with your CSCS username - User username +!!! note "" + :exclamation: Replace `cscsusername` with your CSCS username in the file above. + +After saving this file, one can directly log into `daint.alps.cscs.ch` from your local system using the alias `daint`: + +``` +ssh daint ``` -With this configuration, you can log into Clariden directly using the name clariden that was defined in `Host clariden`. +### Using SSH Agent + +Alternatively, the [SSH authentification agent](https://www.ssh.com/academy/ssh/add-command) can be configured to manage the keys. +Each time a new key is generated using the [SSHService][sshservice], add the key to the SSH agent: +``` +ssh-add -t 1d ~/.ssh/cscs-key +``` + +??? warning "Could not open a connection to your authentification agent" + If you see this error message, the ssh agent is not running. + You can start it with the following command: + ``` + eval $(ssh-agent) + ``` + +Once the key has been configured, log into Ela using the `-A` flag, and then jump to the target system: ```bash -ssh clariden +# log in to ela.cscs.ch +ssh -A cscsusername@ela.cscs.ch + +# then jump to a cluster +ssh daint.cscs.ch ``` ## Frequently encountered issues diff --git a/docs/faq/index.md b/docs/faq/index.md deleted file mode 100644 index 744ce857..00000000 --- a/docs/faq/index.md +++ /dev/null @@ -1,4 +0,0 @@ -# Frequently Asked Questions - -!!! todo - Much of the content that is in our current FAQ could go into proper documentation. diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index accae7ff..b333a92a 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -90,7 +90,7 @@ /* light mode: pale yellow background, solid black foreground */ [data-md-color-scheme="default"] { - --md-code-bg-color: #fcfafa; + --md-code-bg-color: #fdfdfd; --md-code-fg-color: #000000; } @@ -102,7 +102,7 @@ /* Light mode */ [data-md-color-scheme="default"] .md-typeset pre { - border: 2px solid #fcb8b8; + border: 2px solid #b4b4b4; border-radius: 2px; /* slight rounding to corners */ } diff --git a/mkdocs.yml b/mkdocs.yml index b51422e4..278696e1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -73,8 +73,6 @@ nav: - 'Data Transfer': storage/transfer.md - 'Long Term Storage': storage/longterm.md - 'Object Storage': storage/object.md - - 'Frequently asked questions': - - faq/index.md theme: name: material language: en