FirecREST for Daint-XC (legacy)

FirecREST is a RESTful API for managing High-Performance Computing resources developed at CSCS. Scientific platform developers can integrate Firecrest into web-enabled portals and applications, allowing them to securely access authenticated and authorized CSCS services such as job submissions and data transfer on HPC systems. Please refer to the documentation of FirecREST for more details.

FirecREST features

Users can make HTTP requests to perform the following operations:

• basic system utilities like ls, mkdir, mv, chmod, chown, among others
• actions against the Slurm workload manager (submit, query, and cancel jobs of the user)
• internal (between CSCS systems) and external (to/from CSCS systems) data transfers

For a full feature set, have a look at the FirecREST API specification.

FirecREST deployment at CSCS

The public Gateway to FirecREST is https://firecrest.cscs.ch. Users can access all file systems served by Piz Daint and Eiger using FirecREST, except for the $HOME which has been disabled for security reasons.

Getting started

One way to get started is by using pyFirecREST, which is a python package with a collection of wrappers for the different functionalities of FirecREST. This package simplifies the usage of FirecREST by making multiple requests in the background for more complex workflows as well as by refreshing the access token before it expires.

Here is an example of how one can try FirecREST through the python wrapper:

import firecrest as fc


client_id = <client_id>
client_secret = <client_secret>
token_uri = "https://auth.cscs.ch/auth/realms/firecrest-clients/protocol/openid-connect/token"

# Setup the client for the specific account
client = fc.Firecrest(
    firecrest_url="https://firecrest.cscs.ch",
    authorization=fc.ClientCredentialsAuth(client_id, client_secret, token_uri)
)

print(client.all_systems())
# Output: (one dictionary per system)
# [{
#      'system': 'daint'
#      'status': 'available',
#      'description': 'System ready',
#  }]

print(client.list_files('daint', '/scratch/snx3000/<username>'))
# Example output: (one dictionary per file)
# [{
#      'name': 'file.txt',
#      'user': 'username'
#      'last_modified': '2022-04-28T12:03:33',
#      'permissions': 'rw-r--r--',
#      'size': '2021',
#      'type': '-',
#      'group': 'project',
#      'link_target': '',
#  },
#  {
#       'name': 'test-dir',
#       'user': 'username'
#       'last_modified': '2022-04-20T11:22:41',
#       'permissions': 'rwxr-xr-x',
#       'size': '4096',
#       'type': 'd',
#       'group': 'project',
#       'link_target': '',
#  }]

The tutorial is written for a generic instance of FirecREST but if you have a valid user at CSCS you can test it directly with your resource allocation on Piz Daint.

OIDC Client Registration & Management

A client application that makes requests to FirecREST will not be using directly the credentials of the user for the authentication, but an access token instead. The access token is a signed JSON Web Token (JWT) which contains expiry information. Behind the API, all commands launched by the client will use the account of the user that registered the client, inheriting their access rights. You can register, modify and delete your personal clients in https://oidc-dashboard-prod.cscs.ch/.

Every client will have a client ID and a secret that will be used to get a short-lived access token with an HTTP request. Here is an example curl call to fetch the access token:

curl -s -X POST https://auth.cscs.ch/auth/realms/firecrest-clients/protocol/openid-connect/token \
     --data "grant_type=client_credentials" \
     --data "client_id=<your_client>" \
     --data "client_secret=<your_secret>"

Users are allowed to have up to 10 registered clients.

Download large files through FirecREST

A staging area is used for external transfers and downloading/uploading a file from/to a CSCS filesystem.

Please follow the steps below to download a file:

1. Request FirecREST to move the file to the staging area: a download link will be provided
2. The file will remain in the staging area for 7 days or until the link gets invalidated with a request to the /storage/xfer-external/invalidate endpoint or through the pyfirecrest method
3. The staging area is common for all users, therefore users should invalidate the link as soon as the download has completed

We may be forced to delete older files sooner than 7 days whenever large files are moved to the staging area and the link is not invalidated after the download, to avoid issues for other users: we will contact the user in this case.

When uploading files through the staging area, you don't need to invalidate the link. FirecREST will do it automatically as soon as it transfers the file to the filesystem of CSCS.

Further information

• Full list of FirecREST calls
• Documentation of FirecREST
• Documentation of pyFirecREST
• Demo FirecREST environment in Git
• https://www.oauth.com
• Python Requests