From e66d8d6fca0f6ade76aaab82957eb5a9448c31fb Mon Sep 17 00:00:00 2001 From: Pranab Das <31024886+pranabdas@users.noreply.github.com> Date: Thu, 16 Jan 2025 22:11:51 +0800 Subject: [PATCH 1/3] SOF-7548: update ssh instructions for windows --- images/remote-connection/win10apps.webp | 3 + images/remote-connection/win10features.png | 3 + .../actions/transfer-files-scp.md | 25 ++- lang/en/docs/remote-connection/ssh.md | 144 +++++++++++++----- 4 files changed, 128 insertions(+), 47 deletions(-) create mode 100644 images/remote-connection/win10apps.webp create mode 100644 images/remote-connection/win10features.png diff --git a/images/remote-connection/win10apps.webp b/images/remote-connection/win10apps.webp new file mode 100644 index 000000000..c7e5a2777 --- /dev/null +++ b/images/remote-connection/win10apps.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:dcbd567eb297b95511727be62d32660383e77009e7703b8a52bd22d5237e7a6e +size 22612 diff --git a/images/remote-connection/win10features.png b/images/remote-connection/win10features.png new file mode 100644 index 000000000..9a4543ab5 --- /dev/null +++ b/images/remote-connection/win10features.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:bf7e296ea0d500916dfb2957d1bfd9202e65a4a6d983fe92814d056b137aeb71 +size 11201 diff --git a/lang/en/docs/remote-connection/actions/transfer-files-scp.md b/lang/en/docs/remote-connection/actions/transfer-files-scp.md index 3a9121a96..6fc93c51a 100644 --- a/lang/en/docs/remote-connection/actions/transfer-files-scp.md +++ b/lang/en/docs/remote-connection/actions/transfer-files-scp.md @@ -1,14 +1,17 @@ # 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 @login.mat3ra.com: ``` -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 @login.mat3ra.com: @@ -16,15 +19,23 @@ scp -i @login.mat3ra.com: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**. +
+ + How to enable OpenSSH on Windows 10? + + 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**. + ![Windows 10 Apps and Features](../images/remote-connection/win10apps.webp) + 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**. + ![Windows 10 Apps and Features](../images/remote-connection/win10features.png) +
+ +- **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@example.com" +``` +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. ![CLI Welcome Screen](../images/remote-connection/CLI-Welcome-Screen.png "CLI Welcome Screen") ## 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/) From 589fe70142869ae0ed99f9fcd83fd7e97db1e99a Mon Sep 17 00:00:00 2001 From: Pranab Das <31024886+pranabdas@users.noreply.github.com> Date: Tue, 21 Jan 2025 19:46:44 +0800 Subject: [PATCH 2/3] SOF-7548: set max-width for narrow screenshot --- lang/en/docs/remote-connection/ssh.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lang/en/docs/remote-connection/ssh.md b/lang/en/docs/remote-connection/ssh.md index b4f4762d8..6a9b3e7d1 100644 --- a/lang/en/docs/remote-connection/ssh.md +++ b/lang/en/docs/remote-connection/ssh.md @@ -35,7 +35,7 @@ enabled, both `ssh` and `scp` commands should be available via both 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**. - ![Windows 10 Apps and Features](../images/remote-connection/win10features.png) + ![Windows 10 Apps and Features](../images/remote-connection/win10features.png){:style="max-width: 400px !important;"} - **Putty**[^3]: a widespread SSH client for Windows users, can be used as an From 73c91ba98eb2fe986ca667a899185ca20175cf7c Mon Sep 17 00:00:00 2001 From: Pranab Das <31024886+pranabdas@users.noreply.github.com> Date: Tue, 28 Jan 2025 10:15:34 +0800 Subject: [PATCH 3/3] chore: bump platform version --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index f7b49dbf1..5fd292822 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -30,7 +30,7 @@ extra_javascript: copyright: Exabyte Inc. All rights reserved. | Back to platform extra: - version: "2024.12.19" + version: "2025.1.23" preload_javascript: - /extra/js/preload_hotjar.js - /extra/js/preload.js