SAS Viya Command-Line Interface for Administration (update)

2 Likes

SAS Viya includes a set of command-line interfaces that Viya administrators will find extremely useful. The command-line interfaces(CLI) allow administrators to perform numerous administrative tasks in batch as an alternative to using the SAS Environment Manager interface. In addition, calls to the CLI's can be chained together in scripts to automate more complex administration tasks. In this post, I will take a look at a few useful examples. (NOTE: this post is an update of the previous post on the Viya 3.x sas-admin CLI)

In Viya 3.x the command-line interface was sas-admin. In SAS Viya 4 the command-line interface:

is called sas-viya
consolidates all existing Viya command-line interfaces in one location.

The sas-viya command-line interface will run on Linux, Windows, or OSX and is available for download from support.sas.com

The sas-viya CLI is the main interface, it acts as a wrapper for the provided plugins. The individual plug-ins operate as interfaces to administration functionality in Viya. The CLI's provide a simplified interface to the SAS Viya REST services, they abstract the functionality of the REST services allowing an administrator to enter commands on a command line and receive a response back from the system.

Installing

To install the CLI you download it from support.sas.com. Once you have the executable you need to install any plug-ins that you want to use. Plug-ins are installed from a repository. To see what repository you are configured to use, run the command.

sas-viya plugins list-repos

Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.

This is the default SAS hosted repository.

If you navigate to the URL http://support.sas.com/repos/viyacli/ you can see information on the plug-ins available in the repository. You can check the status of your locally installed plug-ins using the following command.

sas-viya plugins list-repo-plugins

The command outputs all the plug-ins available in the repository and also compares them to the plugins installed locally. In the output of the command plug-ins are flagged with an indicator that reflects their status:

asterix( *) : plugin is installed locally and the version in the repository is the same as the version installed
accent (^): plugin is installed locally and the version in the repository is more recent than the version installed
no indicator the plugin is available in the repository but has not been installed locally.

Check out this article to see how to install all available plug-ins (it covers sas-admin but the details are the same for sas-viya).

Using

With the plug-ins installed there are two preliminary steps required to use the command-line interface you need to:

create a profile:
authenticate to Viya

To create a default profile:

sas-viya profile set-endpoint "http://gelcorp.pdcesx*****.race.sas.com"

sas-viya profile set-output json

You can also create named profiles to connect to different Viya Environments.

Profiles are stored in the user's home directory in a file <homedir>/.sas/config.json and contain the endpoint of the Viya environment to connect to and the output setting.

The output options range from text, which provides a simplified text output of the result to fulljson which provides the full JSON output that is returned by the REST calls that the CLI submits.

To authenticate:

sas-viya auth login --user sasadm --password ********

The authentication step creates a token in a file stored in the user's home directory which is valid for, by default, 10 hours. The file location is <homedir>/.sas/credentials.json. If you don't want to hard-code the userid and password you can use the .authinfo file approach to store your credentials described here.

The syntax of a call to the sas-viya CLI is shown below. The CLI requires a plugin and command, and potentially a sub-command, options, and arguments. The example shows a call to the identities plugin. This command will list all the users who are members of the SAS Administrators custom group.

In this execution of sas-viya:

the plug-in is identities
there is a global option --output set so that the result is returned in basic text
the command is list-members
the command option --group-id specifies the group whose members you wish to list.

The built-in help of the CLI's is a very useful feature.

./sas-viya --help

This command provides help on the commands and the plugins available, and the global options that may be used.

You can also display help on the specific plugins by adding the plugin name and then specifying --help.

./sas-viya authorization --help

A simple example

Let's look at an example of using the command-line interface to perform some common administrative tasks. In the example we will create:

a new folder that is the sub-folder of an existing folder
secure the folder
import some existing content
create and secure a CAS Library
Load data into memory

Many of the folders commands require the ID from the previous request. The id of the item is displayed when you create the items and also when you list them using the CLI. In the examples, we will use JQ to capture pars the JSON output of one command and pass the result on to a subsequent command.

Create a folder

Create a new folder at the root of the folder tree.

sas-viya folders create --name gelcontent

Create a sub-folder

The next step is to create a folder that is a sub-folder of the /gelcontent folder. The id of the parent folder and the name of the new folder is passed to the create command of the folders plugin.

sas-viya --output json folders create --description "Sales" --name "Sales" --parent-path /gelcontent

Set permissions on the folder

Next using the folder plugin to retrieve the folder id from the previous step set authorization on the folder. In this call to the authorization plug-in, we grant full control to the group Sales on the new folder and its content.

folderid=$(sas-viya --output json folders show --path /gelcontent | jq -r '.["id"]')

sas-viya --output json authorization create-rule grant --permissions read,create,update,delete,add,remove,secure --group Sales --object-uri /folders/folders/${folderid}/** --container-uri /folders/folders/${folderid}

In SAS Environment Manager check that the folder has been created and check the authorization settings. The authorization setting on the folder shows that a new rule has been created and applied to provide full access to Sales.

Import a content to the folder

The transfer CLI allows us to import and export content from a Viya Environment. In this step we will

upload a transfer package that contains content
import the package
list the contents of the folder with the content

#upload the package to Viya and capture the packagedid
packageid=$(sas-viya --output json transfer upload --file /tmp/viya4packages/gelcontent_sales_reports.json | jq | jq -r '.["id"]')
echo ID of the uploaded package is $packageid
#import the package using the id
sas-viya  --output text transfer import --id $packageid

View the folders and their content.

sas-viya --output text folders list-members --path /gelcontent/Sales --recursive --tree

Create a CASLIB and set permissions

The next task we might perform is to add a caslib, set authorization and load data. We can do that with the following calls to the CAS plugin.

sas-viya --output text cas caslibs create path --name salesdl --path /gelcontent/gelcorp/sales/data --server cas-shared-default

sas-viya --output text cas caslibs add-control --server cas-shared-default --caslib salesdl --group Sales --grant ReadInfo

sas-viya --output text cas caslibs add-control --server cas-shared-default --caslib salesdl --group Sales --grant Select

sas-viya --output text cas caslibs add-control --server cas-shared-default --caslib salesdl --group Sales --grant LimitedPromote

Load data into memory

Load all the tables in the caslibs path into memory.

sas-viya --output text cas tables load --table=* --server cas-shared-default --caslib salesdl

Conclusion

The SAS Viya command-line interfaces provide an extremely useful set of functionality in support of automating common administration tasks. There is obviously much more that can be done with the CLI's than we can cover in this blog. For more information and details of the available interfaces please check out the following resources (some refer to sas-admin but the details remain the same):

Find more articles from SAS Global Enablement and Learning here.