Skip to content

Commit c09f662

Browse files
SebastianPrehnSebastianPrehn
committed
Add SSHFS guide for SIF #13 
1 parent 93c2045 commit c09f662

File tree

4 files changed

+250
-1
lines changed

4 files changed

+250
-1
lines changed

‎docs/sections/sif/networkdrive/sshfs/index.rst

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,35 @@
11
SSHFS
22
=====
33

4-
WIP
4+
SSHFS is a kind of network drive which is supported on Microsoft Windows, MacOS and Linux. SSHFS uses SSH/SFTP connections underneath, so it inherits a number of the advantages like efficiency plus network robustness from there, and is supported directly with SIF SFTP.
5+
6+
Below, you can find user guides on how to setup SSHFS with SFTP for Windows, MacOS or Linux.
7+
8+
Before you proceed to set it up for your system, you first need to setup SSHFS with SFTP on SIF, which you can read about below.
9+
10+
11+
Setup SSHFS/SFTP
12+
----------------
13+
14+
To setup SSHFS with SFTP, go onto the SIF web page, and click on *Setup*.
15+
16+
Click on the "SFTP" tab, and either create a new, separate password for your SFTP access in the field under "Password" or add your public key if you prefer that way. If you choose the password route, the password must consist of at least 8 characters and contain a combination of lowercase and uppercase letters, numbers, and special characters (at least three out of the four types mentioned).
17+
18+
After you have concluded this step, click on "Save SFTP Settings".
19+
20+
21+
⏩️ :doc:`Setup SSHFS with SFTP on Windows </sections/sif/networkdrive/sshfs/windows>`
22+
23+
⏩️ :doc:`Setup SSHFS with SFTP on MacOS </sections/sif/networkdrive/sshfs/macos>`
24+
25+
⏩️ :doc:`Setup SSHFS with SFTP on Linux </sections/sif/networkdrive/sshfs/linux>`
26+
27+
28+
.. toctree::
29+
:maxdepth: 1
30+
:hidden:
31+
32+
Windows </sections/sif/networkdrive/sshfs/windows>
33+
MacOS </sections/sif/networkdrive/sshfs/macos>
34+
Linux </sections/sif/networkdrive/sshfs/linux>
35+

‎docs/sections/sif/networkdrive/sshfs/linux.rst

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
.. _sif-networkdrive-lsftp:
2+
3+
Setup SSHFS with SFTP on Linux
4+
==============================
5+
6+
Some Linux distributions natively integrate SFTP drive access in their file manager, so that one can connect SIF without installing anything.
7+
In the file manager you can *Open Location* or similar (Ctrl+L), insert ``sftp://sif-io.erda.dk`` in the address field and enter your username and chosen password when prompted for login.
8+
9+
10+
SSHFS Drive Linux/UN*X
11+
----------------------
12+
13+
On Linux/UN*X it is also generally possible to install and use the low-level sshfs program to mount SIF as a network drive.
14+
Install `SSHFS <https://github.com/libfuse/sshfs#sshfs>`_ including the FUSE and OpenSSH dependencies using your preferred package manager or via downloading them online.
15+
Save something like the following lines in your local ``~/.ssh/config``::
16+
17+
Host sif-io.erda.dk sif
18+
Hostname sif-io.erda.dk
19+
VerifyHostKeyDNS yes
20+
User <sif_mail>@<project>
21+
Port 22
22+
# Uncomment next line to use your private key in ~/.ssh/id_rsa
23+
# IdentityFile ~/.ssh/id_rsa
24+
25+
replacing <sif_mail> with your SIF-associated mail and <project> with the project name. You can find this information in the Setup tab on SFTP under "SSHFS/SFTP Network Drive" fold-out menu.
26+
Afterwards, you can mount with the SSHFS command to access your SIF home::
27+
28+
mkdir -p sif-home && \
29+
sshfs sif-io.erda.dk: sif-home -o idmap=user -o reconnect

‎docs/sections/sif/networkdrive/sshfs/macos.rst

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
.. _sif-networkdrive-msftp:
2+
3+
Setup SSHFS with SFTP on macOS
4+
==============================
5+
6+
.. _sif-networkdrive-applesilicon:
7+
8+
Macs with Apple Silicon
9+
^^^^^^^^^^^^^^^^^^^^^^^
10+
11+
With the new Apple Silicon, Mac introduced more security and therefore restrictions to their computers. In order to use the program that SSHFS relies on, you will need to allow it to access the kernel extensions.
12+
13+
You can follow the below guidelines to activate the kernel extensions for 3rd party programs, or contact your local IT department for assistance.
14+
15+
First of all, make sure that this guide is handy, as you will have to restart your computer. Turn off your Mac and wait for it to turn off completely. A mac is completely shut down when the screen is black and all light (including Touch Bar) is turned off.
16+
17+
After that, press the power button and hold it down until the "Loading setup options" text is shown. Click on "Options", then on "Continue". Select your user if you are asked to do so, and click "next". Input your computer's password when prompted.
18+
19+
After getting into the menu, click on the "Utilities" button up on the top or similar button, before clicking on the "Startup Security Utility" button. Select your main system if you have several, and click "Unlock..." if prompted. Then. click on "Security Policy...". In this menu, you have to tick the "Reduced Security" rather than "Full Security", and tick the "Allow user management of kernel extensions from identified developers", click OK afterwards.
20+
21+
You have now enabled kernel extensions, and can proceed with the main guide. Click on the Apple logo in the top-left to restart your computer.
22+
23+
24+
.. _sif-networkdrive-msftpsetup:
25+
26+
Setup SSHFS
27+
-----------
28+
29+
Log onto `SIF <https://sif.ku.dk/>`_ and click "Setup".
30+
31+
Click on the SFTP tab, and create a password for your SFTP access in the field under "Password" or add a public SSH key. We recommend that you select a separate password than your main one for SIF. Click on "Save SFTP Settings" once done.
32+
33+
.. TIP::
34+
The password need to follow the University of Copenhagen's guidelines in terms of passwords, and be at least 12 symbols.
35+
36+
37+
.. _sif-networkdrive-msftpinstall:
38+
39+
Install MacFUSE and SSHFS
40+
^^^^^^^^^^^^^^^^^^^^^^^^^
41+
42+
With SSHFS set up on the SIF side, you now need to install the SSHFS client, which connects a SFTP-service as a network drive on your computer.
43+
44+
You need to install SSHFS by downloading and running two programs: MacFUSE and SSHFS
45+
46+
You can download the two programs from `this website <https://osxfuse.github.io/>`_.
47+
48+
Open the programs, and follow the installation wizard for each program.
49+
50+
Once you have installed both programs, you can finally connect SIF as a network drive.
51+
52+
.. IMPORTANT::
53+
If you have a newer Mac with Apple Silicon, then at the end of the installation you will be prompted to activate the kernel extension. A window will pop up, where you will be asked to open System Settings. Do so and click on the button that has appeared mentioning the program or an extension by "Benjamin Fleischer". After clicking this and being prompted your password, you will need to restart your computer once more to allow the kernel extension to load up as a starting process.
54+
55+
56+
.. _sif-networkdrive-msftpconnectnetwork:
57+
58+
Connect Nerwork Drive
59+
^^^^^^^^^^^^^^^^^^^^^
60+
61+
Open an editor on your computer. (A free and easy tool for mac users is TextEdit, even if it is a rich text editor)
62+
63+
Navigate to the Setup page once more for SFTP, and click on the fold-out menu "SSHFS/SFTP Network Drive", and copy the configuration in the box under "SSHFS Drive on Mac OSX". Insert the text into your editor of choice. If you chose a rich text editor such as TextEdit, then go into "Format" and click ""Make Plain Text". Save this configuration as "config" and make sure that it does not use .txt or similar extension after the file name, and save it as a Unicode file if you are prompted to select which type of file. You can save it on your Desktop for now.
64+
65+
Afterwards, you need to open the terminal on your computer, which you can find via Spotlight search as "Terminal".
66+
67+
.. TIP::
68+
If a warning message pops up, simply click "OK" to allow "Terminal" to have access to the files.
69+
70+
71+
To create the folder ".ssh" in your "~" folder, which should be the location your terminal opened in, insert the command ``mkdir -p ~/.ssh`` before pressing Enter. Then, you want to insert the command ``touch ~/.ssh/config`` and press Enter to either create or update the timestamp on your config file.
72+
73+
Now you can copy the contents from the file you created earlier into this config file by inserting the command ``cat ~/Desktop/config >> ~/.ssh/config`` into the Terminal before pressing Enter.
74+
This has the added bonus that even if ``config`` already exists, it will simply append the setup you've done onto it.
75+
76+
After this is done, you need to mount with SSHFS, where one option is to use the following command::
77+
78+
mkdir -p sif-home && \
79+
sshfs sif-io.erda.dk: sif-home -o idmap=user -o reconnect \
80+
-o iosize=262144
81+
82+
Press Enter after inserting it into your terminal. First time you try to connect SIF with SFTP / SSHFS, you will be asked to verify the service's fingerprint. Here, you can check if the fingerprint in the terminal corresponds with the one on the SIF Setup page under "Login Details". Note that the fingerprint can have been updated since this guide was created, and feel free to contact our Support if that is the case.
83+
84+
If it is the same fingerprint, then write ``yes`` and press Enter. You will then be prompted to write a password, and this will be the one you set up in the beginning of this guide. As a security measure, it will not be shown in the terminal, so simply type it and press Enter once done.
85+
86+
SIF is now connected as a network drive and will be visible on the computer's desktop. You will now have access to all your data in SIF via your computer and if you are online, then you can work in the files in the same manner as your other local files, and when you save, those changes will be directly transmitted onto the files in SIF.
87+
88+
89+
.. _sif-networkdrive-msftperror:
90+
91+
Error in the setup
92+
^^^^^^^^^^^^^^^^^^
93+
94+
In case of error in the setup, the SSHFS command will give you the message "remote host has disconnected" in the terminal. If this happens, you can try to test the setup by inserting the command ``sftp sif-io.erda.dk`` and press Enter. If you can log in after that, the setup is correct.
95+
96+
If you still cannot log in, then you need to follow the terminal steps in this guide again, and if you continue to get errors, then you can write to our support at [email protected].
97+
98+
Before doing so, please run the command ``sftp -vvv sif-io.erda.dk`` and insert the result in the mail for us to troubleshoot.
99+
100+
101+
.. _sif-networkdrive-msftpdisconnect:
102+
103+
Disconnect Network Drive
104+
------------------------
105+
106+
You can disconnect SIF as a network drive, and we recommend doing this if you share the computer with others.
107+
108+
Right-click on the drive on the Desktop, and click "Push 'macFUSE Volume 0 (sshfs) out".
109+
110+
111+
.. _sif-networkdrive-msftpreconnect:
112+
113+
Reconnect to the Network Drive
114+
------------------------------
115+
116+
When your computer has been turned off, you need to connect the network drive again. You do that by opening the terminal and running the sshfs command::
117+
118+
mkdir -p sif-home && \
119+
sshfs sif-io.erda.dk: ucph-sif-home -o idmap=user -o reconnect \
120+
-o iosize=262144
121+
122+
If you are experiencing problems in connection the network drive, then it may be because the network drive is connected but not visible. You can try to unmount the network drive by inserting the command ``diskutil unmount force ~/sif-home`` in the terminal and press Enter. After, you can try to connect the network drive again by running the sshfs command.
123+
124+
125+
WIP We are currently working on automating this step for our less technical users.

‎docs/sections/sif/networkdrive/sshfs/windows.rst

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
.. _sif-networkdrive-wsftp:
2+
3+
Setup SSHFS with SFTP on Windows
4+
================================
5+
6+
.. _sif-networkdrive-wsftpinstall:
7+
8+
Install WinFsp and SSHFS-Win
9+
----------------------------
10+
11+
On Windows, our recommended way of working with SFTP is through the `SSHFS client <https://github.com/winfsp/sshfs-win#----sshfs-win--sshfs-for-windows>`_.
12+
13+
Thus, you need to go to the linked GitHub page and install the two programs, either by following their installation guide in the GitHub, or by reading on here.
14+
15+
To install without Winget, you first click on the `WinFsp <https://github.com/winfsp/winfsp/releases/tag/v2.0>`_ link, and then click "DOWNLOAD WINFSP". Follow their installation guide, before returning back to the sshfs-win GitHub page.
16+
17+
Click on either of the two buttons under Download, or click the link under the installation section, and pick either the x64 or x86 depending on your computer's architecture.
18+
19+
If you are unsure about your computer's architecture, you can find it under Start -> Settings -> System -> About
20+
21+
.. image:: /images/networkdrive/networkdrive-about.png
22+
23+
When you are done installing both programs, you can connect a network drive.
24+
25+
26+
Tips for installing on a UCPH computer
27+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
28+
29+
On a standard UCPH computer (B machine), you have access to installing programs by clicking "Request administrator access" in the bottom right corner.
30+
31+
.. image:: /images/networkdrive/networkdrive-ucphcomp.png
32+
33+
If you have a special, secure UCPH computer (A machine), you need to contact UCPH IT to install the two programs.
34+
35+
36+
.. _sif-networkdrive-wsftpmapdrive:
37+
38+
Map Network Drive
39+
-----------------
40+
41+
Click on the File Explorer icon on your computer and click on "This PC" on the side. On top, click on the "Computer" tab and click on the "Map network drive" at the top of the screen.
42+
43+
.. image:: /images/networkdrive/networkdrive-mapbutton.png
44+
45+
Next to "Folder", paste the path from SIF Setup page under "SSHFS/SFTP Network Drive", where it follows the format "\\sshfs\<your-unique-identifier>". Click on "Finish" once you are done.
46+
47+
This will open a login dialogue prompt if you chose password, and you will have to enter your UCPH name, and the password you chose for your SFTP access. Tick "Remember me" if you are using your own personal computer for ease of use, and click "OK".
48+
49+
.. image:: /images/networkdrive/networkdrive-loginprompt.png
50+
51+
SIF is now connected as a network drive with a chosen drive name, and you now have access to all your data in SIF via your computer's programs and file management! When you are online, you can work in the files in the same way as with your other local files, and any changes you make will be applied directly to the files in SIF.
52+
53+
.. TIP::
54+
Every time you log into your computer, you need to click on the network drive to connect if you have previously ticked "Remember me", and if not, you will need to enter your previously chosen password before it reconnects.
55+
56+
57+
.. _sif-networkdrive-wsftpdisconnect:
58+
59+
Disconnect Network Drive
60+
------------------------
61+
62+
You can disconnect SIF as a network drive, and we recommend you do this if you share a computer with others.
63+
64+
Right click on the drive and click "Disconnect".

0 commit comments

Comments
 (0)