Documentation

Secure File Transport Protocol (SFTP)

This is a basic method / protocol for transferring data based on the ancient and insecure File Transfer Protocol (FTP), only updated to be more secure. The internal system used by Rockstor is that included as a subsystem within the openssh server.

Unlike other file sharing systems like Samba/CIFS or Apple Filing Protocol (AFP) sftp has no built in discovery or service publishing components. This makes it a simpler system but one that requires a little more effort to connect with. Most notably is it required that you manually enter the Rockstor’s hostname or ip address on the clients that wish to connect.

The Rockstor SFTP System

By default no user other than root are allowed to login via ssh or use SFTP. This restriction improves security but means there are certain conditions that must be met to gain sftp access to a Rockstor share.

  • the SFTP user must be a Rockstor user
  • the SFTP user must also be the owner of an exported SFTP share

These restrictions make Rockstor’s SFTP implimentation more suited for individual storage needs as opposed to a shared storage area accessed by multiple users. In the following example we will setup a secure share for use by a single user, ie for secure file access / storage across client platforms.

Note also that the share or shares owned by the SFTP user will be mounted within a chroot environment, internally this is located at /mnt3/<username>/<sharename>.

Creating a SFTP Share

In order to establish a SFTP share it is first necessary to have a pre-configured storage pool, a share of this pool or part there of, and a Rockstor user to authenticate against this share. Finally the share must be exported via the SFTP method. The following list details a suggested order and gives links to the documentation on each of these steps.

The following sections illustrate examples of the last 3 items in the above.

The SFTP Pool

The following example shows a general purpose rock-pool has been created.

../_images/rock_pool.png

A Raid1 pool of 2 drives

The SFTP Share

Here a Share has been created on the above rock-pool disk set.

../_images/sftp_share.png

A 20GB share of the rock-pool resource.

Note the required setting of owner is set here to the intended user, this page appears when the share name is clicked on and the Access control tab is selected. An Edit button brings up the following display.

../_images/sftp_perms.png

Please note the required setting of owner has to be non root. If not then when a SFTP export is attempted a warning will be given.

Add SFTP Export

Finally export the Share via the SFTP entry in File Sharing. This menu entry is available in the Storage section. Note that the SFTP Service must be ON, the default, for the configured shares to be available to SFTP clients.

../_images/add_sftp_export.png

Note the Writable or Read only settings for this export option.

The resulting SFTP export is then displayed in summary form:

../_images/sftp_export_summary.png

N.B even if a share is writable by the user the export “read only” option will take precedence.

Accessing a SFTP Share

Depending on your chosen operating system your options to access a SFTP Share differ.

SFTP Access from Linux

Most Linux desktop systems have SFTP capability built into their file managers. This is usually accessed either via a url entry such as in Nautilus, the gnome file manager, or by way of a form entry system such as in KDE. The typical URL that can be used in both desktop environments is as follows:-

  • sftp://username@rockstor-ip-or-name

so to access the above example share the url would be:-

  • sftp://philip@rockstord.lan

The following shows this url having been entered via the Other Locations option in Nautilus. This is akin to Ubuntu’s Unity Connect to Server. A similar facility is possible via KDE’s dolphin file manager.

../_images/gnome_sftp.png

And the consequent connection along with the associated eject icon.

../_images/gnome_sftp_connected.png

Here we see the minimal content associated with a chroot environment and the share or shares owned by this use; in this case the philip-sftp-share.

Once connected the resource is available to other GUI programs via their respective open / save dialogs and the connection can be bookmarked to ease future access.

SFTP Access From OSX

A popular SFTP client program on OSX is Cyberduck. This is a particularly feature full client available directly from the link given or if preferred via a paid version on the Mac App Store where updates will then be automated. Cyberduck is licenced under GNUv2 and is available for OSX 10.7 (Lion) or later. Source code and issue tracking are available at trac.cyberduck.io.

A partner project by the same founding author of Cyberduck is Mountain Duck which allows for drive mappings to be made in the Finder over a variety of protocols including SFTP.

Here we see the dialog resulting from the Open Connection button filled out with the example used in this guide. Note the generated url in blue from the information entered. The 22 at the end of the url is required by some clients and is the default port used by ssh /sftp.

../_images/cyberduck_sftp.png

The display once the above connection is made is shown below; note the eject icon to disconnect.

../_images/cyberduck_sftp_connected.png

Finally we see Cyberduck used to transfer the OSX screen shots used in this document via the example Rockstor share. A testfiles directory is also visible.

../_images/cyberduck_sftp_share.png

Note that Cyberduck supports drag and drop from the OSX Finder app.

SFTP Access from Windows

Most versions of MS Windows do not have a build in ability to access a SFTP resource. To partially get around this limitation one can install an explorer extension such as Swish which is Licenced under GPLv2 with source code available on their Swish GitHub page. Note also that Swish has been translated to over 20 languages via their Transifex account.

An important aspect to the use of Swish is that it is an explorer extension only and does not map a drive in the traditional Windows way so does not make the SFTP resource available to other programs. Ie it is not a filesystem driver.

Also note that Cyberduck, as referenced in the SFTP Access From OSX section above, is also available for various versions of windows.

A dedicated SFTP client application that has found favour in our forum is WinSCP which is GPLv3 Licenced.