-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #316 from Exabyte-io/docs/SOF-7548
SOF-7548: update ssh instructions for windows
- Loading branch information
Showing
5 changed files
with
129 additions
and
48 deletions.
There are no files selected for viewing
Git LFS file not shown
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
25 changes: 18 additions & 7 deletions
25
lang/en/docs/remote-connection/actions/transfer-files-scp.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,30 +1,41 @@ | ||
| # Transfer Files via SCP | ||
|
|
||
| [SCP file transfers](../../remote-connection/ssh.md#transfer-files-with-scp) can be performed directly via any terminal instance opened in a local user machine running a Unix-based operating system, through the following commands (the user should replace the text inside braces below with the corresponding names/paths). | ||
| [SCP file transfers](../../remote-connection/ssh.md#transfer-files-with-scp) can | ||
| be performed directly via any terminal instance opened in a local user machine | ||
| with OpenSSH client installed, through the following commands (the user should | ||
| replace the text inside braces below with the corresponding names/paths). | ||
|
|
||
| 1. To transfer local files **to** exabyte.io remote server (called "bohr"): | ||
| 1. To transfer local files **to** mat3ra.com remote server (called "bohr"): | ||
|
|
||
| ```bash | ||
| scp -i <path to private_key> <path to local file> <username>@login.mat3ra.com:<path inside login home> | ||
| ``` | ||
|
|
||
| 2. To transfer remote files **from** exabyte.io server to local machine: | ||
| 2. To transfer remote files **from** mat3ra.com server to local machine: | ||
|
|
||
| ``` | ||
| scp -i <path to private_key> <username>@login.mat3ra.com:<path inside login home> <path to local file> | ||
| ``` | ||
|
|
||
| ## Examples | ||
|
|
||
| For example, let us assume that user `steve` would like to transfer a text file called `example.txt` under his local home directory to the remote "bohr" server, where the final destination is his personal `data` folder in the [Cluster Home](../../infrastructure/clusters/directories.md) directory for "cluster-001". | ||
|
|
||
| The command that he needs to enter to perform this file transfer, after opening a terminal instance on his own local machine, would be the following (assuming his private [ssh key](../ssh.md) file is stored locally under his home folder). | ||
| For example, let us assume that user `steve` would like to transfer a text file | ||
| called `example.txt` under his local home directory to the remote "bohr" server, | ||
| where the final destination is his personal `data` folder in the | ||
| [Cluster Home](../../infrastructure/clusters/directories.md) directory for | ||
| "cluster-001". | ||
|
|
||
| The command that he needs to enter to perform this file transfer, after opening | ||
| a terminal instance on his own local machine, would be the following (assuming | ||
| his private [ssh key](../ssh.md) file is stored locally under his home folder). | ||
|
|
||
| ```bash | ||
| scp -i ~/ssh_key ~/example.txt [email protected]:cluster-001/data | ||
| ``` | ||
|
|
||
| The converse operation, to retrieve the remotely stored `example.txt` file and re-copy it under his local home directory, would consist in the following command. | ||
| The converse operation, to retrieve the remotely stored `example.txt` file and | ||
| re-copy it under his local home directory, would consist in the following | ||
| command. | ||
|
|
||
| ``` | ||
| scp -i ~/ssh_key [email protected]:cluster-001/data/example.txt ~/ | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,43 +1,96 @@ | ||
| # Command Line Interface via SSH | ||
|
|
||
| The user can connect to the [Command Line Interface](../cli/overview.md) (CLI) of our platform using an **external SSH terminal client** under any Operating System (OS), as an alternative to the [Web Terminal](web-terminal.md). | ||
|
|
||
| We use **SSH keys** [^1] as a way to identify users and trusted computers during command line sessions. Keys provide improved security, however they need to be set properly before use. The steps included in the present page will guide the user through generating SSH keys and adding them to the account being employed. | ||
|
|
||
| Experienced users who are already familiar with how SSH clients operate under their preferred Operating System can navigate directly to the [Upload SSH key](#upload-ssh-key) section of the present page. | ||
|
|
||
| ## OS-specific SSH Clients | ||
|
|
||
| We particularly recommend the following SSH clients for each OS. | ||
|
|
||
| - **Putty** [^2], a widespread SSH client for Windows. | ||
| - **OpenSSH** [^3], the standard protocol in Unix-based OSs (both Linux and Mac OS distributions) for connecting through SSH via the terminal. | ||
| Users can connect to the [Command Line Interface](../cli/overview.md) (CLI) | ||
| of our platform using an **SSH terminal client** under any Operating System | ||
| (OS), as an alternative to the [Web Terminal](web-terminal.md). | ||
|
|
||
| We use **SSH keys** [^1] to identify users and trusted computers during command | ||
| line sessions. Keys provide improved security, but they must be properly set up | ||
| before use. The steps on this page will guide you through generating SSH keys | ||
| and adding them to your account. | ||
|
|
||
| Experienced users who are already familiar with how SSH clients operate under | ||
| their preferred Operating System can navigate directly to the | ||
| [Upload SSH key](#upload-ssh-key) section below. | ||
|
|
||
| ## SSH Client | ||
|
|
||
| Make sure you have a SSH client installed in your computer. We particularly | ||
| recommend the following SSH clients. | ||
|
|
||
| - **OpenSSH**[^2]: the standard protocol in Unix-based OSs (both Linux and | ||
| macOS distributions) for connecting through SSH via the terminal. <br/>Starting | ||
| from Windows version 10, OpenSSH client is included as a Windows Feature. Please | ||
| expand below section if OpenSSH is not enabled on your Windows computer. Once | ||
| enabled, both `ssh` and `scp` commands should be available via both | ||
| **PowerShell** and **Command Prompt**. | ||
| <details markdown="1"> | ||
| <summary> | ||
| How to enable OpenSSH on Windows 10? | ||
| </summary> | ||
| 1. Click on the Windows **Start menu** and search for **Apps and Features**. | ||
| Click on **Apps and Features** on the sidebar, then click **Optional | ||
| Features**. | ||
|  | ||
| 2. Scroll down the list to check if **OpenSSH Client** is listed. Otherwise, | ||
| click the plus sign next to **Add a feature**, select **OpenSSH Client**, | ||
| and click **Install**. | ||
| {:style="max-width: 400px !important;"} | ||
| </details> | ||
|
|
||
| - **Putty**[^3]: a widespread SSH client for Windows users, can be used as an | ||
| alternative to OpenSSH. | ||
|
|
||
| ## Generate SSH Keys | ||
|
|
||
| As introduced previously, SSH keys are necessary to connect to the CLI using the credentials for the account under consideration. | ||
| As introduced previously, SSH keys are necessary to connect to the CLI using the | ||
| credentials for the account under consideration. You can create a RSA key of | ||
| size 4096 bits with the following command: | ||
|
|
||
| External tutorials are available on how to generate such keys for each of the Putty [^4] and OpenSSH [^5] clients. | ||
| ```bash | ||
| ssh-keygen -t rsa -b 4096 -C "[email protected]" | ||
| ``` | ||
| where `-C` flag refers to comment, which could be any identifier. You will be | ||
| prompted to specify a file to save the key. Press Enter to accept the default | ||
| location. When prompted, enter a secure passphrase for your key. This step is | ||
| optional but recommended for added security. After keys are generated, there | ||
| will be two files `id_rsa` and `id_rsa.pub`. Please upload the public key file | ||
| `id_rsa.pub` as described below. | ||
|
|
||
| Please refer to the external tutorials on the advanced usage of OpenSSH [^4] and | ||
| Putty [^5] clients. | ||
|
|
||
| ## Upload SSH Key | ||
|
|
||
| After generating the keys, they need to be uploaded to our platform and associated with the user's account. This effectively establishes a **secure link** between the external SSH client and the corresponding Exabyte account. | ||
| After generating the keys, the public key need to be uploaded to our platform | ||
| and associated with the user's account. This effectively establishes a | ||
| **secure link** between the external SSH client and the corresponding Mat3ra | ||
| account. | ||
|
|
||
| We explain how to upload the SSH keys to our platform in a | ||
| [separate section](../accounts/ui/preferences/ssh.md) of the documentation. | ||
|
|
||
| We explain how to upload the SSH keys to our platform in a [separate section](../accounts/ui/preferences/ssh.md) of the documentation. | ||
|
|
||
| !!!warning "Privacy of SSH keys" | ||
| SSH keys are **private** and are meant to be used to identify exclusively the user with our platform. Any other user logged in with such private keys would automatically have access to the account's data and allocation, and because of this they should not be shared with anyone else. | ||
| SSH keys are **private** and are meant to be used to identify exclusively | ||
| the user with our platform. Any other user logged in with such private keys | ||
| would automatically have access to the account's data and allocation, and | ||
| because of this they should not be shared with anyone else. | ||
|
|
||
| ## Connect to Server | ||
| ## Connecting to Mat3ra Server | ||
|
|
||
| Once the secure SSH link is established via the SSH keys, the remote Exabyte server can be accessed as follows (the user should replace the text inside braces below with the corresponding names/paths). | ||
| Once the secure SSH link is established via the SSH keys, the remote Mat3ra | ||
| server can be accessed as follows (the user should replace the text inside | ||
| braces below with the corresponding names/paths). | ||
|
|
||
| !!!info "Name of remote server" | ||
| Our Exabyte server for accepting remote connections is referred to under the alias of **"bohr"**, and is accessible via the corresponding address `login.mat3ra.com`. | ||
| Our Mat3ra server for accepting remote connections is referred to under the | ||
| alias of **"bohr"**, and is accessible via the corresponding address | ||
| `login.mat3ra.com`. | ||
|
|
||
| ### OpenSSH for Unix | ||
| ### SSH using OpenSSH | ||
|
|
||
| 1. The user should first change the permissions on the private key to be accessible to him/her only. | ||
| 1. The user should first change the permissions on the private key to be | ||
| accessible to him/her only. | ||
|
|
||
| ``` | ||
| chmod 400 {path/to/your/private_key} | ||
|
|
@@ -46,46 +99,57 @@ Once the secure SSH link is established via the SSH keys, the remote Exabyte ser | |
| 2. At the command prompt, the user should then enter the following command. | ||
|
|
||
| ``` | ||
| ssh -i {path/to/your/private_key} {exabyte.io_username}@login.mat3ra.com | ||
| ssh -i {path/to/your/private_key} {mat3ra.com_username}@login.mat3ra.com | ||
| ``` | ||
| ### Putty for Windows | ||
| Instructions on how to operate Putty to connect to our remote server can be found in Ref. [^6]. The name of the server to be used in this case is the same as before, namely `login.mat3ra.com`. | ||
| Instructions on how to operate Putty to connect to our remote server can be | ||
| found in Ref. [^6]. The name of the server to be used in this case is the same | ||
| as before, namely `login.mat3ra.com`. | ||
| ### Enter the CLI | ||
| Following successful SSH connection, the user is presented with the [CLI of our platform](../cli/overview.md). | ||
| Following successful SSH connection, the user is presented with the | ||
| [CLI of our platform](../cli/overview.md). | ||
| Some useful instructions are already contained in the CLI **splash welcome screen** greeting the user at the moment of login. A copy of this welcome screen is reproduced below. | ||
| Some useful instructions are already contained in the CLI | ||
| **splash welcome screen** greeting the user at the moment of login. A copy of | ||
| this welcome screen is reproduced below. | ||
|  | ||
| ## Transfer Files with SCP | ||
| The user can also transfer files back and forth from his/her local hard drives to the folders on the remote Exabyte server. For this purpose, we recommend the **SCP file transfer protocol** [^7], which is also based on SSH. | ||
| The user can also transfer files back and forth from his/her local hard drives | ||
| to the folders on the remote Exabyte server. For this purpose, we recommend the | ||
| **SCP file transfer protocol** [^7], which is also based on SSH. Detailed | ||
| instructions on how to transfer files using `scp` is available | ||
| [in a separate page](actions/transfer-files-scp.md). | ||
| ### Windows Instructions | ||
| On Windows, we recommend the **WinSCP** graphical user interface program [^8]. A tutorial demonstrating how to operate it can be retrieved in Ref. [^9]. | ||
| Once OpenSSH client is enabled on [Windows](#ssh-client), | ||
| [scp](#transfer-files-with-scp) command should be available via Windows | ||
| **PowerShell** and **Command Prompt** terminals. | ||
| When using WinSCP, one would need to load the private key through its interface before connecting. Explanations on how to do so can be found in Ref. [^10]. | ||
| ### Unix Instructions | ||
| Alternatively, you may use **WinSCP** graphical user interface program [^8]. A | ||
| tutorial demonstrating how to operate it can be retrieved in Ref. [^9]. | ||
| The instructions for Unix-based operating systems can be found [in a separate page](actions/transfer-files-scp.md). | ||
| When using WinSCP, one would need to load the private key through its interface | ||
| before connecting. Explanations on how to do so can be found in Ref. [^10]. | ||
| ## Links to Clients Documentation | ||
| [^1]: [SSH keys, Website](https://wiki.archlinux.org/index.php/SSH_keys) | ||
| [^2]: [Putty Homepage, Website](https://www.putty.org/) | ||
| [^2]: [OpenSSH Homepage, Website](https://www.openssh.com/) | ||
| [^3]: [OpenSSH Homepage, Website](https://www.openssh.com/) | ||
| [^3]: [Putty Homepage, Website](https://www.putty.org/) | ||
| [^4]: [Puttygen - Key Generator for Putty on Windows, Website](https://www.ssh.com/ssh/putty/windows/puttygen) | ||
| [^4]: [SSH-keygen - Generate a New SSH Key, Website](https://www.ssh.com/ssh/keygen/) | ||
| [^5]: [SSH-keygen - Generate a New SSH Key, Website](https://www.ssh.com/ssh/keygen/) | ||
| [^5]: [Puttygen - Key Generator for Putty on Windows, Website](https://www.ssh.com/ssh/putty/windows/puttygen) | ||
| [^6]: [How to Use Putty on Windows, Website](https://www.ssh.com/ssh/putty/windows/) | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters