System scope

Throughout these tutorials and Beginner's Guides, we have referred to both public and private systems. In addition to roles, systems have a concept of scope associated with them. Not to be confused with OAuth scope mentioned in the Authentication Guide, system scope refers to the availability of a system to the general user community. The following table lists the available scopes and their meanings.

Scope Required role Description
private Admin System is visible and available for use to the owner and to anyone whom they grant a role.
read only Tenant admin Storage system is visible and available for data browsing and download by any API user. Write access is restricted unless explicitly granted to a specific user.
public Tenant admin System is visible and available to all users for reading and writing. Virtual user home directories are enforced and write access outside of a user's home directory is restricted unless explicitly granted by a system admin.

Private systems

All systems are private by default. This means that no one can use a system you register without you or another user with “admin” permissions granting them a role on that system. Most of the time, unless you are configuring a tenant for your organization, all the systems you register will stay private. Do not mistake the term private for isolated. Private simply means not public. Another way to think of private systems is as “invitation only.” You are free to share your system as many or as few people as you want and it will still remain a private system.

Public systems

Public systems are available for use by every API user within your tenant. Once public, systems inherit specific behavior unique to their type. We will cover each system type in turn.

Public Storage Systems

Public storage systems enforce a virtual user home directory with implied user permissions. The following table gives a brief summary of the permission implications. You can read more about chan in the Data Permissions tutorial.

rootDir homeDir URL path User permission
/ /home READ
/ /home / READ
/ /home /var READ
/ /home systest ALL
/ /home systest/some/subdir ALL
/ /home rjohnson NONE

Notice in the above example that on public systems, users will have implied ownership of a folder matching their username in the system’s homeDir. In the table, this means that user “systest” will have ownership of the physical home directory /home/systest on the system after it’s public. It is important that, before publishing a system, you make sure that the account used to access the system can actually write to these folders. Otherwise, users will not be able to access their data on the system you make public.

Before making a system public, make sure that you have a strategy for mapping API users to directories on the system you want to expose. If mapping to the /home folder on a Unix system, make sure the account used to access the system has write access to all user directories.

Public Execution Systems

Public execution systems do not share the same behavior as public storage systems. Unless explicit permission has been given, public execution systems are not accessible for data access by non-privileged users. This is because public systems allow all users to run applications on them and granting public access to the file system would expose user job data to all users. If you do need to expose the data on a public execution system, either register it again as a storage system (using an appropriate rootDir outside of the system scratchDir and workDir paths), or grant specific users a role on the system.

Publishing a system

To publish a system and make it public, you make a PUT request on the system’s url.

systems-publish -v $SYSTEM_ID
Show curl
curl -sk -H "Authorization: Bearer $ACCESS_TOKEN"
    -H "Content-Type: application/json"
    -X PUT
    --data-binary '{"action":"publish"}'
    https://api.tacc.utexas.edu/systems/v2/$SYSTEM_ID

The response from the service will be the same system description we saw before, this time with the public attribute set to true.

Unpublishing a system

systems-unpublish -v $SYSTEM_ID
Show curl
curl -sk -H "Authorization: Bearer $ACCESS_TOKEN"
    -H "Content-Type: application/json"
    -X PUT
    --data-binary '{"action":"unpublish"}'
    https://api.tacc.utexas.edu/systems/v2/$SYSTEM_ID

The response from the service will be the same system description we saw before, this time with the public attribute set to false.

To unpublish a system, make the same request with the action attribute set to unpublish.

Default systems

As you continue to use Tapis over time, it will not be uncommon for you to accumulate additional storage and execution systems through both self-registration and other people sharing their systems with you. It may even be the case that you have multiple public systems available to you. In this situation, it is helpful for both you and your users to specify what the default systems should be.

Default systems are the systems that are used when the user does not specify a system to use when performing a remote action in Tapis. For example, specifying an archivePath in a job request, but no archiveSystem, or specifying a deploymentPath in an app description, but no deploymentSystem. In these situations, Tapis will use the user’s default storage system.

Four types of default systems are possible. The following table describes them.

Type Scope Role needed to set Description
storage user default USER Default storage system for an individual user. This takes priority over any global defaults and will be used in all data operations in leu of a system being specified for this user.
storage global default Tenant admin Default storage system for an entire tenant. This will be used as the default storage system whenever a user has not explicitly specified another. Only public systems may be made the global default.
execution user default USER Default execution system for an individual user. This takes priority over any global defaults and will be used in all app and job operations in leu of an execution system being specified for this user. In the case of app registration, normal user role requirements apply.
execution global default Tenant admin Default execution system for an entire tenant. This will be used as the default execution system whenever a user has not explicitly specified another. Only public systems may be made the global default.

As a best practice, it is recommended to always specify the system you intend to use when interacting with Tapis. This will eliminate ambiguity in each request and make your actions more repeatable over time as the availability and configuration of the global and user default systems may change.

Setting user default system

To set a system as the user’s default, you make a PUT request on the system’s url. Only systems the user has access to may be used as their default.

systems-setdefault $SYSTEM_ID
Show curl
curl -sk -H "Authorization: Bearer $ACCESS_TOKEN"
    -H "Content-Type: application/json"
    -X PUT
    --data-binary '{"action":"setDefault"}'
    https://api.tacc.utexas.edu/systems/v2/$SYSTEM_ID

The response from the service will be the same system description we saw before, this time with the default attribute set to true.

Unsetting user default system

systems-unsetdefault $SYSTEM_ID
Show curl
curl -sk -H "Authorization: Bearer $ACCESS_TOKEN"
    -H "Content-Type: application/json"
    -X PUT
    --data-binary '{"action":"unsetDefault"}'
    https://api.tacc.utexas.edu/systems/v2/$SYSTEM_ID

The response from the service will be the same system description we saw before, this time with the default attribute set to false.

To remove a system as the user’s default, make the same request with the action attribute set to unsetDefault. Keep in mind that you cannot remove the global default system from being the user’s default. You can only set a different one to replace it.

Setting global default system

Tenant administrators may wish to set default storage and execution systems for an entire tenant. These are called global default systems. There may be at most one system of each type set as a global default. To set a global default system, first make sure that the system is public. Only public systems may be set as a global default. Next, make sure you have administrator permissions for your tenant. Only tenant admins may publish systems and manage the global defaults. Lastly, make a PUT request on the system’s url with an action attribute in the body set to unsetGlobalDefault.

systems-setdefault -G $SYSTEM_ID
Show curl
curl -sk -H "Authorization: Bearer $ACCESS_TOKEN"
    -H "Content-Type: application/json"
    -X PUT
    --data-binary '{"action":"setGlobalDefault"}'
    https://api.tacc.utexas.edu/systems/v2/$SYSTEM_ID

The response from the service will be the same system description we saw before, this time with both the default and public attributes set to true.

Setting global default systems does not preclude users from manually setting their own default systems. Any user-defined default systems will trump the global default system setting for that user.

To remove a system from being the global default, make the same request with the action attribute set to unsetGlobalDefault.

systems-unsetdefault -G $SYSTEM_ID
Show curl
curl -sk -H "Authorization: Bearer $ACCESS_TOKEN"
    -H "Content-Type: application/json"
    -X PUT
    --data-binary '{"action":"unsetGlobalDefault"}'
    https://api.tacc.utexas.edu/systems/v2/$SYSTEM_ID

This time the response from the service will have default set to false and public set to true.