Control SAS Studio file system access in SAS Viya 3.5
SAS Viya 3.5 introduces new configuration options which improve the administrator's control over which parts of the server-side file system their users can access from both SAS Studio 5.2 (Enterprise) and SAS Studio 5.2 (Basic). The configuration settings are now similar across both flavours of SAS Studio.
The main configuration property is fileNavigationRoot, which specifies what sorts of directory are offered to the user at the top of their file navigation node in the Explorer tab in SAS Studio (both versions).
It has three possible values:
- USER (the default) gives users access to their own home directory on the server(s) hosting the SAS Studio web app.
- SYSTEM gives users access to both the system root directory AND their own home directory.
- CUSTOM gives users access to a path defined in fileNavigationCustomRootPath, and anything below it. Choosing this option does not allow the user access to their home directory.
There is also an option to disable access to the filesystem completely from within SAS Studio.
In this post I'll show you where to set these configuration properties in each flavour of SAS Studio, and we will look at the effect each of the possible values has in a little more detail.
Two SAS Studio flavors in SAS Viya 3.5
As the SAS Studio 5.2 product documentation explains:
The Configuration Properties > SAS Studio 5.2 (Enterprise) and 5.2 (Basic) Administration Differences section of SAS Viya 3.5 Administration expands on this slightly:
- SAS Studio 5.2 (Basic) the version that replaces SAS Studio 4.4, which was the version that was available since the first release of SAS Viya.
- SAS Studio 5.2 (Enterprise) the microservices-based version, with a different interface. Studio 5.2 (Enterprise) integrates with other SAS Viya components (such as SAS Drive, Launcher Server, and Compute Server).
That page in the Administration guide goes on to discuss other considerations about the different flavours, which are well worth reading if you are interested in deployment, authentication or other architectural differences between the two versions.
Since the filesystem access configuration is almost identical between the two SAS Studio flavours in this release, I will cover the three options in turn, each for both flavours.
The only real difference is where the configuration options are set, so let's look at that first.
SAS Studio 5.2 (Enterprise)
SAS Studio 5.2 (Enterprise) configuration is stored in the SAS Configuration Server. You can edit it in the Configuration page in SAS Environment Manager. Choose the All services view, and select the "SAS Studio Viya" service (not "SASStudio") on the left hand side of the app window. Use the filter to search for e.g. 'Studio' if that makes it easier to find.
Then edit the 'sas.studiov' configuration instance on the right hand side:
Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.
The Edit sas.studiov Configuration dialog has a warning at the top, saying "Modifying one of these property values requires you to restart one or more SAS Viya services". In my experience while writing this post, you can change the configuration properties discussed in this post for SAS Studio (Enterprise) without needing to restart the SAS Studio (Enterprise) service.
Note: There was one minor exception to this: unsetting the value for serverDisplayName. I will mention this again when we come to that setting again later.
However, I found that I often got the most reliable results after each change by signing out of SAS Studio (either version) and signing in again.
In the sas.studiov configuration instance, find the two configuration properties that control which parts of the server-side file system SAS Studio (Enterprise) users can access, named fileNavigationRoot and fileNavigationCustomRootPath.
We will look at the values of these properties in a moment, but first let's see where to manage the same configuration properties for SAS Studio (Basic).
SAS Studio 5.2 (Basic)
File system access in SAS Studio 5.2 (Basic) is not affected at all by the values in the sas.studiov configuration instance. This makes sense: SAS Studio Basic is included in programming-only deployments of SAS Viya, where there is no SAS Configuration Server.
Similarly, the configuration property settings for SAS Studio 5.2 (Basic) have no effect on SAS Studio 5.2 (Enterprise).
File system access for the SAS Studio 5.2 (Basic) is managed with property settings in the init_usermods.properties configuration file.
Note 1: At the time this post was published (23 March 2020), there was a documentation issue in which the table of SAS Studio: Configuration Properties in SAS Viya 3.5 Administration > Configuration Properties > Reference: Applications documentation for SAS Studio 5.2 (Basic) was also almost entirely incorrect.
Hopefully, by the time you read this, that documentation defect will have been fixed, but until then, read on...The correct property names for SAS Studio 5.2 (Basic) are sas.studio.fileNavigationRoot and sas.studio.fileNavigationCustomRootPath, which as you can see are very similar to the SAS Studio 5.2 (Enterprise) properties.
Creating and editing init_usermods.properties
Set these properties for SAS Studio 5.2 (Basic) in /opt/sas/viya/config/etc/sasstudio/default/init_usermods.properties (on Linux) or \ProgramData\SAS\Viya\etc\sasstudio\default\init_usermods.properties (on Windows). This file is much like the equivalent file in SAS Studio 4.4 at SAS Viya 3.4, but the properties are different.
Note 1: The init_usermods.properties file may not exist yet. If it has not been created by you or another administrator, create it on each of the hosts in the [programming] host group in your deployment's inventory.ini file. Make sure each new instance of this file is owned by the same user and group owner as the init_deployment.properties file in the same directory, usually sas:sas.
Note 2: You must restart SAS Studio 5.2 (Basic) (e.g. systemctl restart sas-viya-sasstudio-default) after modifying the init_usermods.properties file. It is only read during startup of the service.
Values for the fileNavigationRoot property
fileNavigationRoot = CUSTOM, fileNavigationCustomRootPath is set
When fileNavigationRoot = CUSTOM, you can set a file system path using fileNavigationCustomRootPath like this for SAS Studio 5.2 (Enterprise):
Or like this in init_usermods.properties for SAS Studio 5.2 (Basic):
sas.studio.fileNavigationCustomRootPath=/gelcontent sas.studio.fileNavigationRoot=CUSTOM
This is the setting we prefer for our GEL administration workshop environment, and I imagine it will be a popular choice for many customers. Here's what you get in SAS Studio (Enterprise) with those settings:
Notice that the Explorer pane in SAS Studio (Enterprise) offers the user a mixture of Viya Folders service folders (My Folders, SAS Content) and a server-side file system directory on the host where your SAS Studio session is running, here labelled the host's name intviya02.
The Enterprise version of SAS Studio 5.2 is deployed on hosts in the [StudioViya] host group in your deployment's inventory.ini file.
Here is SAS Studio (Basic) with the equivalent settings:
In both flavours of SAS Studio, under that host name in the Explorer pane, you see a Files folder, and then the contents of the file system directory path you set in fileNavigationCustomRootPath (/gelcontent in my examples above). On the collection I used while writing this post, that file system path contains a single subdirectory, called gelcorp, with subdirectories of its own as you see in the screenshots.
One potential drawback of choosing fileNavigationRoot = CUSTOM, that the user's home directory on the server is NOT displayed in the Explorer pane. I do not currently have a way to work around this, though I suspect is possible.
Either version of SAS Studio will access the server-side file system using a process running as the signed-in user, and the signed in user will normally be a member of several POSIX groups as determined by your LDAP and authentication configuration. Set access controls (permissions) on your chosen file system directories using those POSIX groups appropriately to ensure each user has read or write access to only the directories and files you intend. You may be able to achieve what you want with simple permission masks (the usual combination of user and group ownership and the drwxrwxrwx permissions set with chmod or equivalent), or you may have to use Access Control Lists (ACLs) to achieve the permissions design you require on your file system directories.
By the way, you can change the display name of the server to something other than its host name, using the sas.studiov serverDisplayName configuration property, like this in SAS Studio (Enterprise):
Or like this in init_usermods.properties for SAS Studio 5.2 (Basic):
sas.studio.serverDisplayName=SAS Studio Server
Setting or changing a value for serverDisplayName takes immediate effect for SAS Studio (Enterprise) users - you do not need to restart the SAS Studio (Enterprise) service(s):
However, you do need to restart the SAS Studio (Basic) service for the change to take effect in that flavour of the application (e.g. systemctl restart sas-viya-sasstudio-default).
However, if you wish to unset the serverDisplayName, by setting that property value to an empty string, you must then restart either the SAS Studio (Enterprise) service (i.e. systemctl restart sas-viya-studiov-default) or the SAS Studio (Basic) service (i.e. systemctl restart sas-viya-sasstudio-default) on each host where it runs, for the server's display name to revert to its host name.
The collection I used while writing this post had SAS Studio deployed on a single host (intviya02). But I think in a SAS Viya deployment where SAS Studio is deployed across several hosts across which share a file system directory path, and you provide users access to that path using fileNavigationRoot = CUSTOM and fileNavigationCustomRootPath, then this serverDisplayName configuration property is a nice way to 'hide' the differing hostnames from end users and give the appearance of a single named 'server'.
If users do not need to know which host their SAS Studio session is running on and might be concerned or confused when it changes between sessions, why present that information to them?
fileNavigationRoot = SYSTEM
Set fileNavigationRoot = SYSTEM like this for SAS Studio 5.2 (Enterprise):
Or like this in init_usermods.properties for SAS Studio 5.2 (Basic):
sas.studio.fileNavigationRoot=SYSTEM
This option is perhaps best for proof of concept (POC), lab or other similar non-production deployments.
When users sign in to SAS Studio (Enterprise), the Explorer tab will look something like this (two screenshots before and after scrolling down):
Similarly, SAS Studio (Basic) looks like this:
As you can see, this causes SAS Studio to display:
- The user's home directory (under the server), labelled as Home irrespective of its actual filesystem path, PLUS
- The file system root directory '/' under Files, plus
- In SAS Studio (Enterprise) only, the SAS Viya Folders service directories they would normally have access to.
On the deployment I was using to write this post, the Home directory for the signed-in user named Alex is actually /home/Alex, but home directory paths are configured in LDAP and/or as part of the authentication configuration, and could be something else on your host. They are most effective when they are a shared network directory that is common to all relevant hosts.
To learn more about the automatic creation of user home directories in SAS Viya 3.5, see Stuart Rogers' post SAS Viya 3.5 Automatic Home Directories.
So far as I am aware there is no way to change the 'root' (/) file system path displayed when fileNavigationRoot = SYSTEM, but I would not be too surprised to learn that there is a way to change this. Let me know if you find one and I'll update this post.
If you choose this option for fileNavigationRoot, you should think very carefully about the permissions on ALL of the directories at and beneath the file system root on the hosts where SAS Studio is deployed, so that users can only read or write to those directories and files that you intend. This is liable to be the least secure setting for the fileNavigationRoot property, but in a lab or POC environment where there are only a handful of users, no production requirements and no sensitive data, it may be the most convenient.
fileNavigationRoot = USER
This is the default value for fileNavigationRoot. Set fileNavigationRoot to USER when you only want to give users access to their own home directory on the host file system, plus the SAS Viya Folders service directories they would normally have access to, if they are using SAS Studio (Enterprise).
Set it like this for SAS Studio 5.2 (Enterprise):
Or like this in init_usermods.properties for SAS Studio 5.2 (Basic):
sas.studio.fileNavigationRoot=USER
Here's what you get in SAS Studio (Enterprise) with those settings:
And here is SAS Studio (Basic) with the equivalent settings:
As you can see, this causes SAS Studio to display:
- The user's home directory (under the server), labelled as Home irrespective of its actual filesystem path, PLUS
- In SAS Studio (Enterprise) only, the SAS Viya Folders service directories they would normally have access to.
No other file system paths are displayed.
Disable all file system access from within SAS Studio with showServerFiles=False
You can also prevent users from accessing the server file system at all. Set showServerFiles=False like this for SAS Studio 5.2 (Enterprise):
Or like this in init_usermods.properties for SAS Studio 5.2 (Basic):
sas.studio.showServerFiles=False
Here's what you get in SAS Studio (Enterprise) with those settings:
And here is SAS Studio (Basic) with the equivalent setting:
Conclusion
It's great that these configuration settings have been made so similar across the two flavours of SAS Studio. They also allow administrators a good level of control over user file system access from within both versions of SAS Studio in SAS Viya 3.5.
Don't neglect to also design and apply file system access controls on the directories and files that users can access, through SAS Studio and otherwise, to ensure that your user-created content, shared data, and application configurations are properly secured.
See you next time!
