10.10. File system access¶
This page describes how SFTPPlus handles native file system access on both Unix-like and Windows platforms for the server-side operations. While running on a specific operating system, it provides the extra features provided by that operating system.
When accounts are authenticated as operating systems accounts (local, domain, or remote), they will observe the same file system permissions as those defined in the local file system. In other words, the file system access will be granted according to user permissions for the local file system. This way, you can have multiple accounts accessing the same file or folder, each account having its own permissions. The permissions that are set is completely dependent on each use case. For example, you may only want to set read-only permission if you only want users to have read-only permission.
For accounts authenticated as server application accounts, all accounts are mapped to the same OS account and they will have the same permissions.
For application accounts, all file system activity will be executed under the account specified by the [server] account configuration option. Application accounts are locked into their home directories.
The client would need close to full control with permissions.
Windows administrators can further allocate advanced permission settings. In this case, they can also choose to exclude the following permissions - Read Permissions, Change Permissions, Take Ownership, and Write Extended Attributes.
Files on Windows having the read-only attribute set are removed, renamed, moved, and copied without getting an access denied error.
Read-only files cannot be modified, but they can be copied, moved, renamed, or deleted. It is possible that moving, renaming, or deleting a read-only file can cause a program that relies on that file to stop working properly.
Lock access is specified by lock_in_home_folder in the account's settings.
In locked accounts, the account is locked inside the home folder path and access to files and folders outside the home folder path will be denied.
Application accounts are always inside their home folder and will not have access to files outside the home folder.
Operating System accounts have further configuration options:
Deny access to files and folders outside the home folder.
Inherit the account’s group configuration.
If an account is locked and the home folder is set to
/home/user1/, the user is locked inside the home folder. The home folder path is now the root folder visible to the client. When a client lists the folder contents of ‘/upload’, the request is mapped in accordance to the home folder. Therefore it is mapped to
/home/user1/uploadon the local file system.
If an account is not locked inside the home folder, a request to list the relative file path
/upload/folder will be mapped to the
/uploadfolder on the local file system.
You can use absolute or relative file paths when specifying a home folder to lock an account to.
Absolute and relative file paths when used in locked_in_home folder accounts differ to the paths used inside the configuration file as mentioned in the section on absolute and relative paths.
To avoid potentially creating ambiguous behaviour in setting lock access, opt to specify an absolute file path instead of a relative file path.
When a locked account specifies an absolute file path outside the home folder, they will not be able to access that folder. For example, an account with a home folder of
/home/user1/and states an absolute file path to navigate to
/home/user2/uploadwill be unable to access the folder.
When a client navigates to a folder via relative file path, like
/upload/, they will be able to access that folder.
When an account that is not locked to the home folder specifies an absolute file path to a destination outside that folder, it is able to access that folder. For example, if an account with a home folder of
/home/user1navigates to a file path outside its home folder to
/home/user2/uploadit will be able to access that folder. This is also dependent on the account having privileges on the OS to access that particular folder.
Similar to the scenario of a locked home folder account, when a user navigates to a folder via relative file paths, they will also be able to access that folder.
Virtual folders are directories which can be accessed outside of the account's locked home folder, but available as paths inside the user's home folder.
Virtual folders act as symbolic links.
As for real folders, permissions for virtual folders can be defined at the account configuration level or inherited from group configuration.
Virtual folders and their parents in the path cannot be changed through file transfer operations. That is, an account cannot delete, rename, set attributes, or change the root virtual folder, or its parent or grandparents. Even if SFTPPlus permissions allow for deleting a folder, the operation of deleting the root virtual folder will fail.
Accounts can still modify or delete files and folders which are inside the virtual folders, as per the current permissions set in SFTPPlus.
Virtual folders are mapped starting from the root folder.
The following is a scenario for a user,
JohnD requiring access to
C:\Users\JohnD as the home folder path,
and access to these folders:
In SFTPPlus, this user is associated with the following group and account
Notice that virtual_folders are listed in the
JohnD, is not only a part of this group but it is also
inheriting the group's configuration settings:
[groups/d32e-653a-98da] name = Sales virtual_folders = /virtual-in-root, C:\Storage\base /read-only-reports, C:\Storage\reports /upload/team/emea, C:\Storage\teams\sales permissions = allow-full-control /read-only-reports/*, allow-list, allow-read [accounts/7521-bb32-6cce] name = JohnD group = d32e-653a-98da home_folder_path = C:\Users\JohnD permissions = inherit
When a file transfer session is commenced, the session will make available to the user the following list of folder structure to file transfer clients:
/ -> C:\Users\JohnD /download -> C:\Users\JohnD\download /upload -> Virtual folder with 'team' as single member /upload/team -> Virtual folder with 'sales' as single member /upload/team/emea -> C:\Storage\teams\sales /upload/team/emea/jobs -> C:\Storage\teams\sales\jobs /virtual-in-root -> C:\Storage\base /virtual-in-root/vid -> C:\Storage\base\vid /read-only-reports -> C:\Storage\reports /read-only-reports/us -> C:\Storage\reports\us
In addition, the following permissions are also applied to these folders:
/ -> Full control /download -> Full control, including ability to remove the folder. /upload -> Only list, since this is a virtual folder. /upload/team -> Only list, since this is a virtual folder. /upload/team/sales -> Full control, but cannot delete the folder since it is a virtual folder. /upload/team/emea/jobs -> Full control, but cannot delete the folder itself. /virtual-in-root -> Full control, but cannot delete the folder itself. /virtual-in-root/vid -> Full control, can also delete the `vid` folder. /read-only-reports -> Only allow reading files and listing folders. /read-only-reports/us -> Only allow reading files and listing folders.
With the configurations above, the file transfer administrator can be assured
JohnD has access to the appropriate virtual folders with the right
On Linux, virtual folders are case-sensitive. On Windows and macOS, virtual folders are case-insensitive and are always represented in lowercase.
You cannot have a virtual folder sharing the same name as a real folder or file that already exists at the same path that is represented by the virtual folder.
When an account is member of multiple groups, it will get access to all the virtual folders defined for the associated groups.
For example, based on the configuration from below, user JohnD will have access to both /sales-emea and /sales-uk virtual folders:
[groups/d32e-653a-98da] name = Sales EMEA enabled = yes virtual_folders = /sales-emea, C:\Storage\sales\EMEA [groups/2a2e-823a-76de] name = Sales UK enabled = yes virtual_folders = /sales-uk, C:\Storage\sales\UK [accounts/7521-bb32-6cce] name = JohnD group = d32e-653a-98da, 2a2e-823a-76de home_folder_path = C:\Users\JohnD permissions = inherit
During the authentication process, SFTPPlus will check that no real path exists with the same name as one of the configured virtual paths. If these paths are found, the authentication fails and the connection is rejected.
For example, if there is a user with
C:\Users\JohnD as the home folder
path and the following folders:
And they have the following virtual folder configured:
virtual_folders = /upload/team/sales, C:\Storage\teams\sales
The user will fail to authenticate since the real path
C:\Users\JohnD\upload is accessible inside the user's home folder as
When this occurs, a conflict is detected with the virtual path
/upload/team/sales and the authentication will fail.
Administrators can mitigate this issue by ensuring that no real path exists with the same name as one of the configured virtual paths.
Folder / file names that contain only space characters are fully supported on Unix-like systems: Linux and macOS. Names containing leading or trailing spaces are preserved as is.
Names can contain ASCII characters or Unicode names encoded using UTF-8. Other character encoding schemes are not supported yet.
If you require to handle names using a character encoding scheme other than UTF-8, please contact us.
On Windows, leading and trailing spaces from file names are stripped by the operating system. Due to this, names with only space characters are converted into names with no characters, invalidating them.
ASCII and Unicode characters are supported.