UCC Manual

Overview

The UNICORE Commandline Client (UCC) is a full-featured client for the UNICORE middleware. UCC has client commands for all the UNICORE basic services and the UNICORE workflow system.

It offers the following functions

Job submission and management

Batch mode job submission and processing with many performance tuning options

Data movement (upload, download, server-to-server copy, etc) using the UNICORE storage management functions and available data transfer protocols

Storage functions (ls, mkdir, ...) including creation of storage instances via storage factories

Support for UNICORE workflow submission and management

Support for the UNICORE metadata system

Support for sharing UNICORE resources via ACLs

Information about the available services is provided via the system-info command

Various utilities like a shell mode, low-level REST API operations and others

Extensibility through custom commands and the possibility to run scripts written in the Groovy programming language

Built-in help

For more information about UNICORE visit https://www.unicore.eu.

Installation and configuration

Prerequisites

To run UCC, you need a Java runtime version 11 or later (OpenJDK preferred).

Download

You can get the latest UCC version from GitHub.

Installation and configuration

To install, unpack the distribution package (ZIP, DEB or RPM file) into a directory of your choice. For example, to install the UCC using a ZIP file, run the following command:

$ unzip unicore-ucc-<version>.zip

This will create the <UCC_HOME> directory in your current location. All configuration files will be located into the <UCC_HOME>/conf directory. Sample files can be found in <UCC_HOME>/samples directory.

It is recommended to add the path to the <UCC_HOME>/bin directory to your PATH enviroment variable:

$ export PATH=$PATH:<UCC_HOME>/bin

Here, <UCC_HOME> refers to the directory where UCC was installed.

Note

Windows only

Environment variables can be set (as Administrator) via: Control panel ‣ System ‣ Extras panel.

Please do not install UCC in a directory that contains spaces (e.g. Program files). Also, avoid long path names, as this may cause errors due to Windows command-line length limitations.

Note

Debian distribution on Linux

Alternatively, on a Linux system, you can install the Debian package as follows:

$ sudo dpkg -i unicore-ucc-<version>_all.deb

This will install the UNICORE client into /usr/share/unicore/ucc and automatically configure the system to include the /usr/bin/ucc start script in your PATH. All configuration files will be placed in the <USER_HOME>/.ucc directory. Sample files can be found in /usr/share/doc/unicore/ucc/samples directory.

Preferences file

While many parameters can be specified on the command line, it is often more convenient to use a configuration file, so you don’t have to enter the same information repeatedly.

By default, UCC looks for the file <USER_HOME>/.ucc/preferences and reads it at startup. If the file does not exist, it will be created when you run your first UCC command (e.g. ucc -h).

A minimal example specifying your username, password, and the UNICORE registry URL might look like this:

registry=<your registry>

authentication-method=username
username=demouser
password=test123

truststore.type=directory
truststore.directoryLocations.1=<path to CA file(s)>

client.serverHostnameChecking=NONE

Ensure that the path to your trusted CA files (e.g., cacert.pem) is correct to avoid warning messages. For a complete list of available configuration options, please refer to the Configuration file section.

Note

If you are concerned about security and prefer not to specify the password in the preferences file, UCC will prompt you for it if it is not provided either in the file or on the command line.

Note

Windows only

On Windows, the preferences file is typically located at: c:\Users\<user_name>\.uccpreferences.

When specifying paths in the preferences file, you must either use double backslashes (\) or replace them with forward slashes (/).

For example, if you are using a local UNICORE installation for testing, you might set:

registry=https://localhost:8080/DEMO-SITE/rest/core/registries/default_registry

Tip

To change the default location of the preferences file, you can set a Java system property in the UCC startup script (ucc on Linux or ucc.batch on Windows). For example, modify the Java command as follows:

$ java .... -Ducc.preferences=<preferences location> ....

Logging

UCC displays some messages to the console, and provides more detailed information when verbose mode is enabled using the -v option. If you need detailed logging (e.g. when using the batch mode), you can edit the <UCC_HOME>/conf/logging.properties (or <UCC_HOME>/.ucc/logging.properties in the Debian distribution) file. This file configures the Log4J logging infrastructure used by UNICORE.

Installing UCC extensions

UCC can be extended with additional commands by simply copying the extension librarie files (.jar files) into a directory that UCC scans at startup. By default, these directories are:

<UCC_HOME>/lib (or /usr/share/unicore/ucc/lib if UCC was installed via a Debian package)

<USER_HOME>/.ucc/lib

Testing the installation

To test your UCC installation and retrieve information about the services available in the UNICORE system you’re connecting to, run the following command:

$ ucc system-info -l -v

Getting started with UCC

Assuming you have successfully installed UCC, this section shows how to get started quickly.

Getting help

Calling UCC with the -h option displays the available options. To view a list of available commands, use:

$ ucc -h

To get help on a specific command, use:

$  ucc <command> -h

See also Common options to UCC for a list of common options.

Connecting

First, contact UNICORE and make sure you have access to at least one target system:

$ ucc connect

List available sites

Next, list the sites available to you using:

$ ucc list-sites

Running your first job

The UCC distribution contains some job examples located in the <UCC_HOME>/samples directory that you can run. Let’s run the date.u sample. The -v switch enables verbose output, so you can see more details about what is happening.

$ ucc run -v <UCC_HOME>/samples/date.u

This command will run date on a randomly chosen site, and retrieve the output. To target a specific site, use the -s option to specify the desired system.

Note

Debian distribution on Linux

If UCC was installed from a DEBIAN file, sample files can be found in /usr/share/doc/unicore/ucc/samples directory.

Listing your jobs

To list your jobs along with their status, use the following command:

$ ucc list-jobs -l

This will print a list of job URLs with their respective status (RUNNING, SUCCESSFUL, etc).

Job Execution Example

After submitting a job, you can access its output files using various UCC commands. This example shows how to submit a job, inspect its status, explore the working directory, and handle output files.

# start a job and exit immediately (asynchronous submission)
$ ucc run -a date.u
https://134.94.198.76:8080/DEMO-SITE/rest/core/jobs/DkNJ0b38aD0

# list all jobs
$ ucc list-jobs
https://134.94.198.76:8080/DEMO-SITE/rest/core/jobs/DkNJ0b38aD0

# check the job's status
$ ucc job-status -l https://134.94.198.76:8080/DEMO-SITE/rest/core/jobs/DkNJ0b38aD0
https://134.94.198.76:8080/DEMO-SITE/rest/core/jobs/DkNJ0b38aD0 SUCCESSFUL exit code: 0
Working directory: https://134.94.198.76:8080/DEMO-SITE/rest/core/storages/DkNJ0b38aD0-uspace
Job type: BATCH, queue: 'batch'

# list files in the job's working directory
$ ucc ls -l https://134.94.198.76:8080/DEMO-SITE/rest/core/storages/DkNJ0b38aD0-uspace
-rw-r-----   2 2025-06-11T13:27:25+0000 /UNICORE_SCRIPT_EXIT_CODE
-rw-r--r--   0 2025-06-11T13:27:25+0000 /stderr
-rw-r--r--  29 2025-06-11T13:27:25+0000 /stdout
-rwxrwxr-- 1099 2025-06-11T13:27:25+0000 /UNICORE_Job_1749648445137
-rwxrwxr-- 362 2025-06-11T13:27:25+0000 /bss_submit_1749648445137

# To access individual files, append /files/<filename> to the working directory URL!
# For example, to view the contents of the stdout file:
$ ucc cat https://mygateway:8080/DEMO-SITE/rest/core/storages/DkNJ0b38aD0-uspace/files/stdout
Wed Jun 11 13:27:25 UTC 2025

# download output to current directory
$ ucc get-output https://mygateway:8080/DEMO-SITE/rest/core/storages/DkNJ0b38aD0-uspace/files/stdout

# optionally check if stderr contains error messages
$ ucc cat https://mygateway:8080/DEMO-SITE/rest/core/storages/DkNJ0b38aD0-uspace/files/stderr

Common options to UCC

The following table lists the options understood by most UCC commands. Most commands have additional options. You can always get a summary of all available options for a command by calling UCC with the -h or --help option, for example,

$ ucc run --help

Since it is not possible to give all the required options on the commandline, it is recommended to create a preferences file containing e.g. your settings for keystore, registry, etc.

Table 1 Common options for the UCC
Option (short and long form)	Description
-c,–configuration <Properties_file>	Properties file containing your preferences. By default, a file `$HOME/.ucc/preferences` is checked.
-k,–authentication-method <auth>	Authentication method to use (default: USERNAME)
-o,–output <Output_dir>	Directory for any output produced (default is the current directory)
-r,–registry <List_of_Registry_URLs>	The comma-separated list of URLs of UNICORE registries
-v,–verbose	Verbose mode
-h,–help	Print help message
-y,–with-timing	Timing mode

User preferences

If you have multiple user IDs or belong to multiple Unix groups that are mapped within UNICORE on the target system, you may want to control which user attributes are used when invoking UCC.

Here is a list of options related to user attributes:

Table 2 User attribute options
Option (short and long form)	Description
-Z, –preference	Select from your remote attributes (e.g. xlogin)

The preference option accepts multiple arguments of the form <name>:<value> where name:

Table 3 User attribute options
Name	Description
uid	Remote login
pgid	Primary group ID
supgids	Secondary group IDs (comma-separated)
role	UNICORE role (user, admin, …)
vo	virtual organisation

Configuration file

By default, UCC checks for the existence of a file <userhome>/.ucc/preferences and reads settings from it. If the file does not exist, it will be created when you run your first UCC command. As shown above, you can specify a different configuration file on the command line using the -c option.

The configuration file can include default settings for many command-line options, provided in the format <option name>=<value> where <option name> referes to the long form of the option. The property values may include variables in the form ${VAR_X}, which are automatically replaced with the corresponding environment variable values. Additionally, a special variable ${UCC_CONFIG} is recognized and will be replaced with the absolute path of your configuration file.

The most important part of configuration is specifying how UCC should authenticate you to the UNICORE server(s) and which server(s) should be trusted.

An overview of the available authentication options can be obtained using the following command:

$ ucc help-auth

A minimal example for using the quickstart installation would be:

registry=https://localhost:8080/DEMO-SITE/services/Registry?res=default_registry

authentication-method=username
username=demouser
password=test123

truststore.type=directory
truststore.directoryLocations.1=<path to CA file(s)>

Important

To protect your passwords, you should make the file unreadable by others - for example, on Unix systems, by using a command such as: chmod 600 preferences.

Note

If required passwords are not specified in the properties file, they will be requested interactively.

Username and password authentication

To authenticate with username and password, set the following:

authentication-method=username
username=<your remote username>
password=<your remote password>

Support for token based authentication

UCC has three different options for using token-based authentication:

via oidc-agent
directly contact an OIDC server as an OIDC client (requires client ID and secret)
specify the token directly as a config property

OIDC-Agent

UCC supports the oidc-agent tool that allows to interact with common OIDC servers to retrieve new access tokens.

To configure oidc-agent, UCC supports the following properties:

Table 4 Options for oidc-agent
Property name	Type	Default value / mandatory	Description
oidc-agent.account	string	mandatory	Account short name.
oidc-agent.lifetime	integer >= 1		Minimum lifetime of the issued access token.
oidc-agent.refreshInterval	integer number	300	Interval (seconds) before refreshing the token.
oidc-agent.scope	string		OpenID scope(s) to request.

Your config file would require at least:

authentication-method=oidc-agent
oidc-agent.account=<oidc-agent account to be used>

OIDC Server

This is a low-level approach that requires the details on how to act as an OIDC client, you’ll need at least an OIDC token endpoint, client ID and secret.

Table 5 Options for oidc-server
Property name	Type	Default value / mandatory	Description
oidc.authentication	[BASIC, POST]	BASIC	How to authenticate (i.e. send client id/secret) to the OIDC server (BASIC or POST).
oidc.clientID	string		Client ID for authenticating to the OIDC server.
oidc.clientSecret	string		Client secret for authenticating to the OIDC server.
oidc.endpoint	string	mandatory	The OIDC server endpoint for requesting a token
oidc.grantType	string	client_credentials	Grant type to request.
oidc.otp	string		Additional one-time password for two-factor authentication. Set this to ‘QUERY’ to query it interactively.
oidc.password	string		Password used to log in. It is suggested not to use this option for security reasons. If not given in configuration, it will be asked interactively.
oidc.refreshInterval	integer number	300	Interval (seconds) before refreshing the token.
oidc.refreshTokenFile	string		(internal) Filename for storing the refresh token between UCC invocations.
oidc.request_key_for_otp	string	otp	(internal) How to send the OTP value to the server.
oidc.scope	string		Token scope to request from the OIDC server.
oidc.username	string		Username used to log in. If not given in configuration, it will be asked interactively.

authentication-method=oidc-server
oidc.endpoint=<oidc server token endpoint>
oidc.username=...
oidc.password=...

UCC also supports sending a one-time password (OTP) to Keycloak. To enable this feature, add the following line to your configuration:

oidc.otp=QUERY

This setting causes UCC to prompt for the OTP on the command line. Alternatively, the OTP value can be provided directly in the preferences file, e.g.:

.. ``oidc.otp=your_otp_value``

UCC stores the refresh token (if available) and tries to use it before falling back to username/password authentication - even accross multiple UCC invocations. By default, the token is stored in the file $HOME/.ucc/refresh-tokens. This location can be changed using a configuration variable.

Bearer token in config

Last not least, if you have a Bearer token via some other means, you can directly put the token into your config file:

authentication-method=bearer-token
token=...

Certificate-based authentication

For UNICORE installations that support (or even require) client certficates for authentication, configure the following settings:

authentication-method=X509
credential.path=<your keystore>
credential.password=XXXXXXX

Replace <your keystore> with the path to your client certificate keystore, and provide the corresponding password.

Table 6 Credential properties

Property name

Type

Default value / mandatory

Description

credential.path

filesystem path

mandatory

Credential location. In case of ‘jks’, ‘pkcs12’ and ‘pem’ store it is the only location required. In case when credential is provided in two files, it is the certificate file path.

credential.format

[jks, pkcs12, der, pem]

Format of the credential. It is guessed when not given. Note that ‘pem’ might be either a PEM keystore with certificates and keys (in PEM format) or a pair of PEM files (one with certificate and second with private key).

credential.password

string

Password required to load the credential.

credential.keyPath

string

Location of the private key if stored separately from the main credential (applicable for ‘pem’ and ‘der’ types only),

credential.keyPassword

string

Private key password, which might be needed only for ‘jks’ or ‘pkcs12’, if key is encrypted with different password then the main credential password.

credential.keyAlias

string

Keystore alias of the key entry to be used. Can be ignored if the keystore contains only one key entry. Only applicable for ‘jks’ and ‘pkcs12’.

credential.reloadOnChange

[true, false]

true

Monitor credential location and trigger dynamical reload if file changes.

Truststore options

In most cases, you only need a truststore directory containing trusted certificates:

truststore.type=directory
truststore.directoryLocations.1=/trust/dir/*.pem

A full list of options related to truststore management is available in the following table:

Table 7 Truststore properties
Property name	Type	Default value / mandatory	Description
truststore.allowProxy	[ALLOW, DENY]	ALLOW	Controls whether proxy certificates are supported.
truststore.type	[keystore, openssl, directory]	mandatory	The truststore type.
truststore.updateInterval	integer number	600	How often the truststore should be reloaded, in seconds. Set to negative value to disable refreshing at runtime.(runtime updateable)
truststore.directoryConnectionTimeout	integer number	15	Connection timeout for fetching the remote CA certificates in seconds.
truststore.directoryDiskCachePath	filesystem path		Directory where CA certificates should be cached, after downloading them from a remote source. Can be left undefined if no disk cache should be used. Note that directory should be secured, i.e. normal users should not be allowed to write to it.
truststore.directoryEncoding	[PEM, DER]	PEM	For directory truststore controls whether certificates are encoded in PEM or DER. Note that the PEM file can contain arbitrary number of concatenated, PEM-encoded certificates.
truststore.directoryLocations.*	list of properties with a common prefix		List of CA certificates locations. Can contain URLs, local files and wildcard expressions.(runtime updateable)
truststore.keystoreFormat	string		The keystore type (jks, pkcs12) in case of truststore of keystore type.
truststore.keystorePassword	string		The password of the keystore type truststore.
truststore.keystorePath	string		The keystore path in case of truststore of keystore type.
truststore.opensslNewStoreFormat	[true, false]	false	In case of openssl truststore, specifies whether the trust store is in openssl 1.0.0+ format (true) or older openssl 0.x format (false)
truststore.opensslNsMode	[GLOBUS_EUGRIDPMA, EUGRIDPMA_GLOBUS, GLOBUS, EUGRIDPMA, GLOBUS_EUGRIDPMA_REQUIRE, EUGRIDPMA_GLOBUS_REQUIRE, GLOBUS_REQUIRE, EUGRIDPMA_REQUIRE, EUGRIDPMA_AND_GLOBUS, EUGRIDPMA_AND_GLOBUS_REQUIRE, IGNORE]	EUGRIDPMA_GLOBUS	In case of openssl truststore, controls which (and in which order) namespace checking rules should be applied. The ‘REQUIRE’ settings will cause that all configured namespace definitions files must be present for each trusted CA certificate (otherwise checking will fail). The ‘AND’ settings will cause to check both existing namespace files. Otherwise the first found is checked (in the order defined by the property).
truststore.opensslPath	filesystem path	/etc/grid-security/certificates	Directory to be used for opeenssl truststore.
truststore.crlConnectionTimeout	integer number	15	Connection timeout for fetching the remote CRLs in seconds (not used for Openssl truststores).
truststore.crlDiskCachePath	filesystem path		Directory where CRLs should be cached, after downloading them from remote source. Can be left undefined if no disk cache should be used. Note that directory should be secured, i.e. normal users should not be allowed to write to it. Not used for Openssl truststores.
truststore.crlLocations.*	list of properties with a common prefix		List of CRLs locations. Can contain URLs, local files and wildcard expressions. Not used for Openssl truststores.(runtime updateable)
truststore.crlMode	[REQUIRE, IF_VALID, IGNORE]	IF_VALID	General CRL handling mode. The IF_VALID setting turns on CRL checking only in case the CRL is present.
truststore.crlUpdateInterval	integer number	600	How often CRLs should be updated, in seconds. Set to negative value to disable refreshing at runtime.(runtime updateable)
truststore.ocspCacheTtl	integer number	3600	For how long the OCSP responses should be locally cached in seconds (this is a maximum value, responses won’t be cached after expiration)
truststore.ocspDiskCache	filesystem path		If this property is defined then OCSP responses will be cached on disk in the defined folder.
truststore.ocspLocalResponders.<NUMBER>	list of properties with a common prefix		Optional list of local OCSP responders
truststore.ocspMode	[REQUIRE, IF_AVAILABLE, IGNORE]	IF_AVAILABLE	General OCSP ckecking mode. REQUIRE should not be used unless it is guaranteed that for all certificates an OCSP responder is defined.
truststore.ocspTimeout	integer number	10000	Timeout for OCSP connections in miliseconds.
truststore.revocationOrder	[CRL_OCSP, OCSP_CRL]	OCSP_CRL	Controls overal revocation sources order
truststore.revocationUseAll	[true, false]	false	Controls whether all defined revocation sources should be always checked, even if the first one already confirmed that a checked certificate is not revoked.

Truststore examples

Below are some examples for commonly used trust store configurations.

The most common setup is a directory-based truststore, which requires minimal configuration:

truststore.type=directory
truststore.directoryLocations.1=/trust/dir/*.pem

An OpenSSL-based truststore can be configured as follows:

truststore.type=openssl
truststore.opensslPath=/etc/grid-security/
truststore.opensslNsMode=EUGRIDPMA_GLOBUS_REQUIRE
truststore.updateInterval=1200
truststore.crlMode=IF_VALID

To use a Java keystore as a truststore, use this configuration:

truststore.type=keystore
truststore.keystorePath=/some/dir/truststore.jks
truststore.keystoreFormat=JKS
truststore.keystorePassword=xxxxxx

Client options

The configuration file may also contain low-level options, for example, if you need to specify connection timeouts, HTTP proxies, other advanced networking settings.

Table 8 Client options
Property name	Type	Default value / mandatory	Description
client.digitalSigningEnabled	[true, false]	true	Controls whether signing of key web service requests should be performed.
client.httpAuthnEnabled	[true, false]	false	Whether HTTP basic authentication should be used.
client.httpPassword	string	empty string	Password for use with HTTP basic authentication (if enabled).
client.httpUser	string	empty string	Username for use with HTTP basic authentication (if enabled).
client.maxWsCallRetries	integer number	3	Controls how many times the client should try to call a failing web service. Note that only the transient failure reasons cause the retry. Note that value of 0 enables unlimited number of retries, while value of 1 means that only one call is tried.
client.messageLogging	[true, false]	false	Controls whether messages should be logged (at INFO level).
client.securitySessions	[true, false]	true	Controls whether security sessions should be enabled.
client.serverHostnameChecking	[NONE, WARN, FAIL]	WARN	Controls whether server’s hostname should be checked for matching its certificate subject. This verification prevents man-in-the-middle attacks. If enabled WARN will only print warning in log, FAIL will close the connection.
client.sslAuthnEnabled	[true, false]	true	Controls whether SSL authentication of the client should be performed.
client.sslEnabled	[true, false]	true	Controls whether the SSL/TLS connection mode is enabled.
client.wsCallRetryDelay	integer number	10000	Amount of milliseconds to wait before retry of a failed web service call.
client.http.allow-chunking	[true, false]	true	If set to false, then the client will not use HTTP 1.1 data chunking.
client.http.connection-close	[true, false]	false	If set to true then the client will send connection close header, so the server will close the socket.
client.http.connection.timeout	integer number	20000	Timeout for the connection establishing (ms)
client.http.maxPerRoute	integer number	6	How many connections per host can be made. Note: this is a limit for a single client object instance.
client.http.maxRedirects	integer number	3	Maximum number of allowed HTTP redirects.
client.http.maxTotal	integer number	20	How many connections in total can be made. Note: this is a limit for a single client object instance.
client.http.socket.timeout	integer number	0	Socket timeout (ms)
client.http.nonProxyHosts	string		Space (single) separated list of hosts, for which the HTTP proxy should not be used.
client.http.proxy.password	string		Relevant only when using HTTP proxy: defines password for authentication to the proxy.
client.http.proxy.user	string		Relevant only when using HTTP proxy: defines username for authentication to the proxy.
client.http.proxyHost	string		If set then the HTTP proxy will be used, with this hostname.
client.http.proxyPort	integer number		HTTP proxy port. If not defined then system property is consulted, and as a final fallback 80 is used.
client.http.proxyType	string	HTTP	HTTP proxy type: HTTP or SOCKS.

Other options

The following table lists additional options, that are less commonly used:

Table 9 Other options for the UCC
Property name	Description
blacklist	Comma separated patterns for sites / URLs to ignore
contact-registry	Do not attempt to contact the registry, even if one is configured

Running jobs

Introduction

The UCC can run jobs specified in the JSON job description format that is used by the UNICORE REST API, including some extensions for handling of local files, submission options, etc. See Job Description Format for details.

In the following, it is assumed that you have UCC installed Installation and configuration and tried some examples Getting started with UCC.

For example, assume the file myjob.u looks as follows:

{
  "ApplicationName": "Date"
}

To run this through UCC, issue the following command:

$ ucc run myjob.u

This submits the job, waits for completion, downloads stdout and stderr, and saves them in your default output directory.

To see all available options for the run command, use the built-in help:

$ ucc run -h

Caution

Windows only

If you want to run a Bash script that was created on Windows, it may contain Windows-style line endings (CRLF), which can cause execution errors on UNIX systems (where LF line endings are expected). Since the script will be executed on a UNIX system, you should convert it to UNIX format using the dos2unix command:

$ dos2unix script.sh

Alternatively, if dos2unix is installed on the server, you can include a User pre-command in your JSON job description file to convert the script automatically before execution:

{
 "Executable": "/bin/bash",
 "Arguments": ["script.sh"],
 "User pre-command": "dos2unix script.sh",
 "Imports": [
 { "From": "script.sh", "To": "script.sh" },
 ],
}

Controlling the Output Location and File Names

Output files will be placed in the directory specified using the -o option. If this option is not provided, the current working directory is used by default.

By default, output files are stored in a subdirectory named after the job ID to prevent accidental overwriting of existing files. This behavior can be changed using the -b option.

When -b is specified, no subdirectory will be created, and all output files will be written directly to the specified (or current) directory.

Specifying the Site

In the example above, a random site is selected to execute the job. To explicitly choose a site, use the -s option. This option accepts the name of a target system.

To list all available target systems, use the following command:

$ ucc list-sites

Accessing a Job’s Working Directory

Using UCC’s data management functions, the job’s working directory can be accessed at any time after job submission.

For more information, see section Data Management Functions.

Options Overview

The following options are available when running jobs (see also the general options overview in Common options to UCC):

Table 10 Job submission options for UCC
Option (Short and long form)	Description
-a,–asynchronous	Run asynchronously
-A,–allocation <URL>	Submit into the given allocation
-b,–brief	Do not create a sub-directory for output files
-B,–broker	Select the type of resource broker to use (see `run -h` for a list)
-d,–dry-run	Don’t actually submit anything
-J,–multi-threaded	For each job file listed on the command line, launch a thread
-s,–sitename <SITE>	Site where the job shall be run
-S,–schedule <Time>	Schedule the submission of the job at the given time
-o,–output <Output_dir>	Directory for any output produced (default is the current directory)

Resource Selection

In general, the user selects the execution site. If no site is specified during job submission, UCC will automatically select a suitable site where the job’s requirements (e.g. resources, applications) can be fulfilled.

If other types of brokers are available, they can be selected using the -B or --broker option.

LOCAL (default): brokering is handled by UCC itself.

To check if other brokers are available, run:

ucc run -h

The available broker options will be listed in the help for the -B option.

Processing Jobs Asynchronously

For long-running jobs, it is often desirable to run the job asynchronously — that is, submit the job, stage in any files, and start it, then retrieve the results later.

Asynchronous Submission

Use the -a flag when submitting a job:

$ ucc run -a <job file>

This will submit the job, stage in any local files, start the job, and exit immediately. A job file will be written containing information about the job endpoint and any exported files to retrieve once the job has completed. You can use this file later with the get-output and job-status commands.

Get the Status of Particular Jobs

To check the status of one or more jobs, use:

$ ucc job-status <job_file_or_url> <job_file_or_url_2> ...

If no job is specified on the command line, a job URL will be read from the console. Each argument may be either a job URL or the name of a job file (as written by the run -a command).

Download Results

To retrieve stdout, stderr, and any other files marked for export, use:

$ ucc get-output -o <outdir> <job_file_or_url> <job_file_or_url_2> ...

The -o option specifies the directory where the output files will be saved. If not provided, the current directory is used by default. As before, a job address can also be entered interactively via the console if no job file or URL is given on the command line.

Referencing a Job by Its URL (Endpoint Address)

If you want to check a job that was not submitted through UCC, you can refer to it by its URL. The ucc list-jobs command will produce a list of all job URLs accessible to you.

Note that in this case, UCC will only retrieve the stdout and stderr files. To download other result files, you need to use the data movement functions described in Data Management Functions.

Scheduling Job Submission to the Batch System

Sometimes a user wishes to control the time when a job is submitted to the batch queue, for example, because he/she knows that a certain queue will be empty at that time.

To schedule a job, you can use the -S option with the ucc run command:

$ ucc run -S "12:24" ...

Alternatively, you can specify the start time in your job file using the Not before keyword:

{
  "Not before": "12:30"
}

In both cases, the specified start time can be given in the brief “HH:mm” (hours and minutes) format shown above—in this case, the time is interpreted as the local time on the UNICORE/X server — or in the full ISO 8601 format including year, date, time, and time zone:

{
  "Not before": "2011-12-24T12:30:00+0200"
}

Using Allocations

Batch systems such as Slurm support allocations, i.e., the user can get a chunk of resources for a certain time, into which jobs can then be submitted. This allows a more interactive use of an HPC system, where you only have to wait once for the allocation to be granted, then subsequent jobs will be launched immediately.

To create an allocation, you need to launch a job of type ALLOCATE containing only resource requests:

{
  "Job type": "ALLOCATE",

  "Resources": {
    "Nodes": "1",
    "Runtime": "1h"
  }
}

If you run this with ucc run, a new job will be created that is not yet executing anything. The job URL can then be used with a subsequent ucc run -A <url>:

$ export ALLOCATION=$(ucc run -a allocation.u)
$ ucc run -A $ALLOCATION yourjob1.u yourjob2.u

Note that you should submit the allocation job asynchronously, otherwise UCC would wait for it to finish. In addition, the allocation must be in the RUNNING state before it can accept any jobs.

Executing a Command

If you just want to execute a simple command remotely (i.e., without data staging, resource specifications, etc.), you can use the exec command. This will run the given command remotely (similarly to ssh) and print the output to the console. You can specify the site with the -s option. If you do not specify the site, a random site will be chosen.

UNICORE will run the command on the login node; it will not be submitted to the batch system. For example, try:

$ ucc exec /bin/date

To safely pass arguments to the executable, use -- to end the UCC part of the command line. For example, to execute the date --rfc-email query, which refers to the date and time format used in email messages, use:

$ ucc exec -- date --rfc-email

Job Description Format

UCC uses the JSON Job description format that is used by the UNICORE REST API, adding support for handling local files.

Several complete job samples can be found in the samples directory of the distribution. On Linux, check also the /usr/share/unicore/ucc/samples directory.

To view an example job showing most of the available options, run:

$ ucc run -H

(most of the options shown are not mandatory, of course).

Specifying the Execution Site

As an alternative to using the --sitename option to specify the execution site, you can use the following top-level keyword in the job description:

{
  "Site": "DEMO-SITE"
}

Note that the commandline option, if present, takes precedence.

Handling Local Files

It is often the case that your job requires files from your local workstation, or you want UCC to download result files once the job has finished.

UCC achieves this by allowing paths to local files in the To and/or From directives of the data staging part(s) in your job.

Local files can be given as an absolute or relative path; in the latter case the configured output directory will be used as base directory.

Importing Local Files into the Job Workspace

To import files from your local computer, you can use the usual Imports keyword, with a path as the From argument.

You can of course mix local and remote files. This example shows some of the possibilities:

{
  "Imports": [

    // Import a local file from the client machine into the job workspace
    { "From": "/work/data/fileName", "To": "fileName" },

    // Import a set of local files from the client machine into the job workspace
    { "From": "/work/data/pdf/*.pdf", "To": "/" },

    // Import a remote file from a UNICORE storage using the UFTP protocol
    { "From": "UFTP:https://gw:8080/DEMO-SITE/rest/core/storages/Home/files/testfile",
      "To": "testfile" },

    // Create a symlink from a file on the compute machine
    { "From": "link:/work/data/testfile", "To": "linked-file" },

    // Copy a file on the compute machine
    { "From": "file:/work/data/testfile", "To": "copied-file" }
  ]
}

If for some reason an import fails, but you want the job to run anyway, there is a flag FailOnError that can be set to false:

"Imports": [
  {
    "From": "/work/data/fileName",
    "To": "fileName",
    "FailOnError": "false"
  }
]

Note

UCC supports simple wildcards (* and ?) for importing and exporting files.

Exporting Result Files from the Job Workspace

To export files from the job’s working directory to your local machine, use the normal Exports keyword, with a file path as the To argument.

Here is an example Exports section that specifies two exports:

{
  "Exports": [

    // This exports all PNG files to a local directory
    { "From": "*.png", "To": "/home/me/images/" },

    // This exports a single file to a local directory
    // Failure of this data transfer will be ignored
    { "From": "error.log", "To": "/home/me/logs/error.log",
      "FailOnError": "false" },

    // This exports to a UNICORE storage
    { "From": "stdout",
      "To": "https://gw:8080/DEMO-SITE/rest/core/storages/Home/files/results/myjob/stdout" }
  ]
}

As a special case, UCC also supports downloading files from other UNICORE storages (after the job has finished), using the Exports keyword:

{
  "Exports": [
    // This exports a file from a UNICORE storage
    { "From": "https://gw:8080/DEMO-SITE/rest/core/storages/Work/files/somefile",
      "To": "/home/me/somefile" }
  ]
}

Data Management Functions

UCC offers access to all the data management functions in UNICORE. You can upload or download data from a remote server, initiate a server-to-server transfer, create directories, and more.

Specifying Remote Locations

Remote locations are specified via URIs that include protocol, storage server (host/port), site name, and filename. For example:

BFT:https://mygateway:8080/SITE/rest/core/storages/HOME/files/my_file

This URI specifies a file named /my_file on the storage instance https://mygateway:8080/SITE/rest/core/storages/HOME, using the BFT protocol.

Important

The /files/ part is part of the API endpoint and not part of the filename.

Paths are always relative to the storage root, not the root of the actual file system.

The protocol is optional and defaults to BFT if not specified.

Data movement

cp

The cp command is a generic command for copying source file(s) to a target destination, where source and target can be remote locations or files on the local machine. Wild card characters * and ? are supported.

Examples for client-server transfers:

$ ucc cp data/*.pdf https://server/rest/core/storages/SHARE/files/pdfs
$ ucc cp https://server/rest/core/storages/SHARE/files/pdfs .

The -R option allows to choose whether subdirectories are to be copied too.

The -X option allows to resume a previous transfer. Missing data will be appended to an existing target file (if the chosen protocol supports it).

Please note that the “/files/” part is part of the API endpoint, and not part of the filename.

Examples for server-server transfer:

$ ucc cp https://server/rest/core/storages/SHARE/files/*.pdf  \
     https://otherserver/rest/core/storages/WORK/data/

For server-to-server transfers, the cp command supports several additional options.

The -S option allows to schedule a transfer for a certain time. For example,

$ ucc cp -S "23:00" ...

The format is simply HH:mm (hours and minutes). Alternatively, you can give the time in the full ISO 8601 format including year, date, time and time zone:

$ ucc cp -S "2011-12-24T12:30:00+0200" ...

Another useful option is -a which will execute the server-server transfer asynchronously, i.e. the client will not wait for the transfer to finish.

copy-file-status

This will print the status of the given data transfer. As argument, it expects a file name containing the transfer reference, or directly the reference.

Example (for Unix) which captures the reference into a shell variable:

$ export ID=$(ucc cp -a ...)
$ ucc copy-file-status $ID

Specifying the file transfer protocol

To use a different protocol from the default BFT, you can use the -P option to specify your preferred protocol. UCC will try to match them with the capabilities of the storage and use the first match. Your preferred protocol can also be listed in your preferences file using the protocols key:

protocols=UFTP

Note

If necessary, you can specify additional filetransfer options in your preferences file as well. For example, to use the UFTP protocol you may need to specify the client host address and the number of parallel streams explicitely:

uftp.client.host=your_client_ip_address
uftp.streams=2
# encrypt data (at the cost of performance)
uftp.encryption=true
# compress data
uftp.compression=true

Use the special value all to enable all available client IP addresses for UFTP.

uftp.client.host=all

You can also override the UFTP server host, which can be useful in case the UFTP server is accessible via multiple network interfaces:

uftp.server.host=myhost.com

UCC will try to use reasonable defaults for any missing parameters.

General commands

mkdir

This will create a directory (including required parent directories) remotely.

Example:

$ ucc mkdir https://mygateway:8080/SITE/rest/core/storages/HOME/files/pdfs

rm

This will remove a file or directory remotely. By default, UCC will ask for a confirmation. Use the --quiet or -q option to disable this confirmation (e.g. when using this command in scripts).

Example:

$ ucc rm https://mygateway:8080/SITE/rest/core/storages/HOME/files/pdfs

rename

This will rename/move a remote file/directory on the same storage.

Example:

$ ucc rename https://mygateway:8080/SITE/rest/core/storages/HOME/files/data/foo1.pdf /files/data/foo2.pdf

will rename the file foo1.pdf to foo2.pdf.

stat

This command shows full information on a certain file or directory. Add the -m flag to also print user-defined metadata.

Example:

$ ucc stat -m https://mygateway:8080/SITE/rest/core/storages/HOME/files/foo.txt

Finding data

ls

This command lists the contents of a remote directory.

Useful options are:

-l : detailed output
-H : human-readable sizes
-R : recursive listing

Basic example:

$ ucc ls -l -H https://mygateway:8080/SITE/rest/core/storages/HOME/

If the storage supports metadata, you can display it for a specific file using -m along with -l:

$ ucc ls -l -m https://mygateway:8080/SITE/rest/core/storages/HOME/.bashrc

To list all PDF files in a folder:

$ ucc ls https://mygateway:8080/SITE/rest/core/storages/HOME/*.pdf

To recursively list all files in a directory and subdirectories:

$ ucc ls -R https://mygateway:8080/SITE/rest/core/storages/HOME/projects/

Using the StorageFactory service

UNICORE sites may allow users to dynamically create storage resources, which even can be linked to special back-end systems like Apache HDFS, iRODS, or cloud storage like Amazon S3.

You can find out if there are sites supporting this StorageFactory service either by running the system-info -l command, or better using

$ ucc create-storage -i

This will list the available StorageFactory services and also show which types of storage are supported and how much space is left on each of them.

UCC supports creating storages via the create-storage command. The simple

$ ucc create-storage

will create a new storage resource using the default storage type at some site.

Usually you want to control at least where the storage is created. Additionally, the type of storage and some parameters can be passed to UCC.

As an example, creating a storage of type S3 would look like this:

$ ucc create-storage -t S3 accessKey=... secretKey=...

You can also read parameters from a file. Say you have your S3 keys in a file s3.properties, then you can use the following syntax:

$ ucc create-storage -t S3 @s3.properties

You can also mix this with the normal key=value syntax, or mix it like this:

$ ucc create-storage -t S3 accessKey=@s3.accessKey secretKey=@s3.secretKey

The last version key=@file causes just the value to be read from the named file.

Metadata management functions

UCC offers a simple interface to access the metadata management service in UNICORE.

Basics

The metadata functions are all accessed via a single UCC command metadata. The actual operation to be performed is given with the -C (i.e. command) option.

The storage to be operated upon is given using the -s option.

In addition to the URL, the name of the target file on the storage is required.

Metadata is represented in JSON format. The metadata operations usually read metadata from a file (or write results to a file), which is specified using the -f option.

In the following examples, <STORAGE> denotes the URL of a storage capable of handling metadata.

Available commands

Creating metadata

To create metadata, a file in JSON format is required containing key-value pairs. For example, edit the file meta.json to contain:

{
  "foo": "bar"
}

Say we have a file test on our storage, then you can create metadata as follows:

$ ucc metadata -C create -f meta.json -s <STORAGE> /test

If you now look at the file with ls -l -m,

$ ucc ls -l -m  <STORAGE>/test

you should get something like this:

-rw-           3344 2011-06-27 22:32 /test
{
  "foo": "bar",
  "resourceName": "/test"
}

Reading metadata

Apart from the ls -l -m used above, there is also an explicit read command, which can write the metadata to a file as well:

$ ucc metadata -C read -s <STORAGE> /test -f out.json

The -f option is optional.

Updating metadata

Using update, the given metadata is merged with any existing metadata. Say we have a file x.json containing:

{
 x: y
}

We can append this to the existing metadata:

$ ucc metadata -C update -s <STORAGE> /test -f x.json

Check that the metadata has indeed been appended.

Deleting metadata

Explicitely deleting is also possible:

$ ucc metadata -C delete -s <STORAGE> /test

Check that the metadata has indeed been deleted.

Searching

Searching requires a search string (according to the rules of Apache Lucene), and is triggered by the search command:

$ ucc metadata -C search -q "foo" -s <STORAGE> /

Triggering metadata extraction

To trigger the extraction of metadata on the server, use the start-extract command:

$ ucc metadata -C start-extract -s <STORAGE> /

In this case the / denotes the base path from which to start the extraction process.

Workflows

Introduction

UCC supports the UNICORE Workflow service and allows to submit workflows and manage them.

The workflows are executed server-side, and UCC is used only for submitting, managing data and getting results. UCC also provides helper features for dealing with the workflows’ input/output data and parametrised workflow templates.

Note

Version 8.x of the Workflow service has changed a lot, and existing 7.x XML workflows will need to be converted / refactored.

Command overview

The following commands are provided:

workflow-submit: submit a workflow file

workflow-control: abort or resume a running workflow

list-workflows: list information about workflows

More details and examples follow below.

Basic use

To check the availability of the Workflow service in the configured registry, issue the following command:

$ ucc system-info -l

This should show at least one accessible Workflow service.

The distribution includes some example workflow files in the samples/workflows directory which you can edit and submit. For example:

$ ucc workflow-submit twostep.json

This command submits a workflow with two jobs and prints the workflow’s URL to the standard output.

To list all your workflows, use list-workflows command:

$ ucc list-workflows

To get the status of a specific workflow specify the workflow’s URL:

$ ucc list-workflows <workflow_address> -l

This also lists all jobs submitted within the workflow.

To get the working directory of a specific job, run:

$ ucc list-job <job_address> -l

To display the content of the stdout file of a specific job:

$ ucc cat <job_working_directory>/files/stdout

Workflow description format

The JSON format used by that the Workflow service can be found here.

Managing workflow data

Importing local data for use by a workflow

If you have local files that need to be imported before starting the workflow, you can use a normal UCC job file that contains only an Imports section:

{
 "Imports":
 [
   { "From": "local_file_1", "To": "wf:workflow_file_name_1", },
   { "From": "local_file_2", "To": "wf:workflow_file_name_2", },
 ...
 ],
}

UCC will upload the local files to a remote storage (which you can specify) and automatically register them with the workflow upon submission.

Your workflow JSON can then reference them as wf:... in the workflow activities.

You can also manually register files by adding in inputs section to your workflow JSON.

{
 "inputs": {
   "wf:infile1" : "remote_url_1",
   "wf:infile2" : "remote_url_2",
 },
}

Workflow templates

If the workflows contains a Template parameters section, the corresponding replacement will be done by reading parameter values from the .u file. These so-called workflow templates can be a very simple and safe way to make adjustments in complex workflows before submission. As an example, consider the following workflow:

{
  "Template parameters": {
      "SLEEPTIME": {
         "type" : "INTEGER",
         "default": "10",
      }
  },

  "activities" : [
      {
          "id": "sleep1",
          "job": {
              "Executable": "sleep",
              "Arguments": ["${SLEEPTIME}"],
          },
      },
  ],
}

This introduces a parameter SLEEPTIME with default value 10.

When the workflow is submitted, you can specify a JSON file with the -u option, which will be checked for a parameter named SLEEPTIME

{
  "SLEEPTIME": "1",
}

and if present, the value will be replaced in the workflow.

Resuming a held workflow

A workflow in status HELD can be resumed using the workflow-control resume command. If the workflow has variables/parameters, updated values can be sent with the resume command.

Batch processing

The batch command allows you to run many jobs without having to start UCC each time. You can control how many jobs should go to which site. This allows efficient job processing, while putting some load on the client machine. If you need to take the client offline, you should consider using the workflow system instead, which also allows efficient high-throughput processing.

Assume you have a bunch of jobs in UCC’s job description format stored in a directory jobs. The output should go to a directory out. You can run them all through UCC using a single invocation as follows:

$ ucc batch -i jobs -o out

As job files, UCC will accept files ending in .u.

Options

You can run in follow mode, where UCC will watch the input directory, and will process new files as they arrive:

$ ucc batch -f -i jobs -o out

Performance tuning options

Getting the most performance out of UCC and the UNICORE installation can be a challenging task. Sending too many jobs to a site might decrease throughput, sometimes the client machine can be the limiting factor, etc.

You should experiment a bit to get the best performance for your specific setup. UCC has many options available for tuning. Here is an overview:

Table 11 Tuning options for the UCC batch mode
Option (short and long form)	Description
-K,–keep	Do not delete finished jobs on the server. By default, finished jobs are destroyed.
-m,–max <MaxRunningJobs>	Limit on jobs submitted by UCC at one time (default: 100)
-t,–threads <NumThreads>	Number of threads to be used for processing (default: 4)
-u,–update <UpdateInterval>	Minimum time in milliseconds between status requests on a single job (Default: 1000)
-R,–no-resource-check	Do not check if the necessary application is available on the target system (will increase performance a bit)
-X,–no-fetch-outcome	Do not fetch standard output and error
-S,–submit-only	Only submit the jobs, do not wait for them to finish
-M,–max-new-jobs	Limit the number of job submissions (default: 100)
-s,–sitename	Specify which site to use
-W,–site-weights	Specify a file containing site weights

Resource selection in batch mode

By default, the UCC batch mode will select a random site for running a job. You can modify the selection in different ways:

using the -s option or a Site: <sitename>, entry in the job file, you can specify the site directly
use the -W option to specify a file containing site weights

Say you have two sites where one site is a big cluster and the other a small cluster. To send more jobs to the big cluster, you can use the site weights file:

#example site weights file for use with "ucc batch -W ..."

BIG-CLUSTER = 100
SMALL-CLUSTER = 10

#send no jobs to this site
BAD-CLUSTER = 0

# set default weight (for any sites not specified here)
UCC_DEFAULT_SITE_WEIGHT = 10

This would tell UCC to send 10 times more jobs to the BIG-CLUSTER site, and send no jobs to the BAD-CLUSTER. All other sites would get weight 10, i.e. the same as SMALL-CLUSTER.

The UCC shell

If you want to run a larger number of UCC commands, the overhead of starting the Java VM or checking the registry may become annoying. For this scenario, UCC offers a shell that allows the user to enter UCC commands interactively.

It is started by

$ ucc shell <options>

If you want to process a list of commands from a file instead of typing them, you can start the shell like this:

$ ucc shell -f commandsfile

or on Unix you can use the redirection features:

$ ucc shell < commandsfile

Changing property settings

To change a property setting in shell mode, you can use the set command. Without additional arguments, current properties are listed:

ucc> set registry=https://...  output=/tmp  ...

To set one or more properties, add space separated key=value strings:

ucc> set output=/work registry=https://....

You can also clear a property (set it to null) by using unset:

ucc> unset registry

Variables referenced via $var_name or ${var_name} will be replaced in commands. You can use this to make commands shorter and more readable. It’s also possible and useful to pre-set certain things in your preferences file.

For example,

ucc> set S1=https://myserver/my_site/rest/core/storages/HOME
ucc> ls -l $S1

A special variable $_ exists that is set by various commands to the last thing that was created or accessed.

For example,

ucc> run -a date.u
ucc> job-status $_

Running an external command

You can run an external command via the system (or simply !) shell command. For example,

ucc> system vi job.u

or simply

ucc> ! cat job.u

Exiting the shell

To exit, type exit or press Control-D.

Port forwarding / tunneling

Starting with UNICORE 9.1.0, it is possible to open a tunnel (TCP socket connection) from the client to a service running on the HPC cluster. The service can run on a login node or on a compute node.

Since this mechanism uses only the established UNICORE communication channels, it will work in any situation, unhindered by firewalls.

Traffic is forwarded from the client through the UNICORE HTTPS stack down to the cluster login node, where the (UNICORE TSI) starts a process which connects to the backend service and forwards data back through the UNICORE stack to the client. So there is chain of connections, forwarding data through the following stack

Client application

Client-side listener (e.g. UCC)

Gateway

UNICORE/X

Server-side listener (TSI process) on the login node

Service

(in both directions).

That is quite a number of hops, so latency and throughput will be limited accordingly. As soon as one of the connections is closed, the whole stack is shut down.

To establish the client side, UCC has a command open-tunnel, which behaves similarly to an SSH tunnel (ssh -L ...)

It is started by

$ ucc open-tunnel -L <listen-port> <endpoint>

The listen-port is the port where a local application can connect. You can use “0” to use any free port.

The endpoint is a UNICORE job endpoint URL, with a few extra parameters added:

/forward-port?port=<service_port>&host=<service_host>&loginNode=<tsinode

The port parameter is mandatory, and denotes the port where the backend service is listening.

The host and loginNode are optional:

host is the host where the service is running, must be reachable from the TSI (login node). It defaults to localhost (as seen from the login node!).

loginNode is useful in cases where there are multiple login nodes, and you wish to control on which login node the forwarding process is launched.

Upon connection, the tunneling process is initiated, and the forwarding of data is started. To stop listening and forwarding, press Control-C, or use some other method to stop the UCC process.

Example

While usually the backend service is also started via UNICORE, that is not strictly necessary. Any of your job endpoints will do.

In this example, however, we launch a Python web server via UNICORE, and then connect to that Python service via a tunnel. In the first step, the service will run on a login node

Launch a UCC shell with ucc shell ... and run the following job to start the service, which will be listening on port 8877:

run -a

{
  "Executable": "python3 -m http.server 8877",
  "Job type":   "ON_LOGIN_NODE"
}

(type CTRL-D to to launch the job)

Make sure to wait until this job is running, i.e.

job-status $_

shows it as RUNNING. The UCC shell special variable $_ automatically contains the last URL, i.e. the new job’s URL.

To open the tunnel:

open-tunnel -L 4321 $_/forward-port?port=8877

this will open a local listener on port 4321.

To test your tunnel, run something like the following (from ANOTHER terminal, don’t kill UCC):

wget http://localhost:4321/stdout

You might also try and open "http://localhost:4321" in a browser.

Level 2: connecting to a service running on a compute node

The next step is to connect to a service running on a compute node. To be able to do that, you need to know which compute node it is, so UNICORE can connect to it via the TSI.

There are several ways to achieve that. One way would be to check the job’s low-level details and get the node from there.

For example, tunning the following job:

run -a

{
  "Executable": "python3 -m http.server 8877"
}

(type CTRL-D to to launch the job)

Once it is running, check its details:

rest get $_/details

If your cluster is running SLURM, the host name(s) will be in the “NodeList” field.

With that, you can launch the tunnel via

open-tunnel -L 4321 $_/forward-port?port=8877&host=...

making sure to add the name/IP of the compute node via the “&host=…” parameter.

If this is not enoough (for example if your job is multi-node), the best way is to write the hostname where your service is running to a file in the job directory, and read that from the client.

Final notes

Attention

USE RESPONSIBLY! This tool is not intended for high volume data streaming or a very high number of concurrent connections, since it does incur some overhead on the UNICORE infrastructure.

UCC for site administrators

UCC can be used for administrative and user support tasks, like checking server status, or getting the full details of a user job.

Security considerations

Usually, each UNICORE user has only access to his or her own resources (such as jobs). For administrative use, you will need to aquire administrator privileges. The recommended way is to create dedicated user credentials (e.g. username/password) and map them to the role admin (in the XUUDB, or whatever attribute source you are using).

Admin commands

UCC has dedicated commands for accessing the AdminService of a UNICORE/X container. To get started, try:

$ ucc admin-info -l

UCC will try to access the admin service on each availabe UNICORE/X server. For each server, a list of statistical and performance data will be listed.

It will also list the available admin commands for each server, with a short description of their parameters. For example, here is a sample output:

https://localhost:8080/DEMO-SITE/rest/admin
  Metrics:
    use.security.ServerIdentity: ServerIdentity: CN=UNICOREX,O=UNICORE,C=EU;Expires: Sat Jun 24 10:42:02 CEST 2051;IssuedBy: CN=Demo CA,O=UNICORE,C=EU
    use.throughput: count=29,mean=0.00,m1_rate=0.00,m5_rate=0.01,m15_rate=0.01
    MeanTimeQueued-1: n/a
  Commands:
    ToggleResourceAvailability : parameters: resources (comma separated list of IDs)
    ToggleJobSubmission : parameters: [message]
    AbortJob : parameters: jobID, [cleanup:false/true], [xnjsReference]
    ShowJobDetails : parameters: [jobID], [xnjsReference]
    ListPartitions : parameters: [xnjsReference]
    ShowServerUsageOverview : parameters: [clientDN]

To invoke a command, the admin-runcommand is used. It can take optional parameters. For example:

$ ucc admin-runcommand ShowJobDetails jobID=4VGUfmFYdSR

Disabling/enabling job submission

For example, it is possible to disable/enable job submission to the server, using the ToggleJobSubmission command, which can take an optional message:

$ ucc admin-runcommand ToggleJobSubmission message="Maintenance"

The service will reply:

$> SUCCESS, service reply: OK - job submission is disabled

If a user now tries to submit, she will receive an error message on submission. Running the command again will re-enable the service:

$ ucc admin-runcommand ToggleJobSubmission message="Maintenance"
$> SUCCESS, service reply: OK - job submission is now enabled

Getting job details

To get the full job details (for example in user support), try:

$ ucc admin-runcommand ShowJobDetails jobID=<unique_jobid>

For example,

$ ucc admin-runcommand ShowJobDetails jobID=7IAPQXlNue0

SUCCESS, service reply: Job information for 7IAPQXlNue0
  {Info=Action ID       : 7IAPQXlNue0
  Action type     : JSON
  Status          : DONE
  Result          : SUCCESSFUL [Success.]
  Owner           : CN=Demo User, O=UNICORE, C=EU
  Job definition: {"ApplicationName":"Date","DetailedStatusDisplay":"true","KeepFinishedJob":"true","Output":"/tmp","Imports":[],"haveClientStageIn":"false","Exports":[]}
  Processing context: {_TIME_END_STAGEIN=1723641157070, eu.unicore.xnjs.ems.ApplicationExecutionStatus=DONE, _TIME_END=1723641164106, USAGE.logged=true, _TIME_START=1723641156661, _TIME_START_STAGEOUT=1723641164106, _TIME_SUBMITTED=1723641157289, _TIME_END_MAIN=1723641164054, EMS_AUTOSUBMIT=true}
  Application Info: Application <Date:1.0>
  Job log:
  Wed Aug 14 15:12:36 CEST 2024: Created with type 'JSON'
  Wed Aug 14 15:12:36 CEST 2024: Client: Name: CN=Demo User,O=UNICORE,C=EU
  Xlogin: uid: [schuller:demouser, active=schuller], gids: [schuller, active=schuller, addingOSgroups: true]
  Role: user: role from attribute source
  Security tokens: User: CN=Demo User,O=UNICORE,C=EU
  Client's original IP: 127.0.0.1
  Wed Aug 14 15:12:37 CEST 2024: Created job directory </home/schuller/UNICORE-Jobs/7IAPQXlNue0/>
  Wed Aug 14 15:12:37 CEST 2024: Status set to READY.
  Wed Aug 14 15:12:37 CEST 2024: Status set to PENDING.
  Wed Aug 14 15:12:37 CEST 2024: Requesting resources: [Queue=batch, Nodes=1, Runtime=3600]
  Wed Aug 14 15:12:37 CEST 2024: Command is: #!/bin/bash -l
  ...
  Wed Aug 14 15:12:37 CEST 2024: TSI reply: submission OK.
  Wed Aug 14 15:12:37 CEST 2024: Submitted to TSI as [schuller schuller:DEFAULT_GID] with BSSID=187312841157244
  Wed Aug 14 15:12:43 CEST 2024: Exit code 0
  Wed Aug 14 15:12:43 CEST 2024: Job completed on BSS.
  Wed Aug 14 15:12:44 CEST 2024: End of processing - successful.
  Wed Aug 14 15:12:44 CEST 2024: Total: 7 sec., Stage-in: 0 sec., Stage-out: 0 sec.}

Thus you can get a full view of what the user submitted and what was executed.

Listing jobs, sites, …

You can also use all normal UCC commands to access the server. Note however that due to the authentication and authorisation system in UNICORE, this may not always work as expected: the admin user might not have the required Unix permissions to access files, list directories, etc.

The UCC commands that list server-side things (list-jobs, etc.) accept a filtering option, that can be used to limit the results of the operation. Filtering works on the XML resource properties of the resource in question.

Filtering is enabled by the -f or --filter option of the form:

-f NAME OPERATOR VALUE

where NAME is the name of an element from the JSON resource properties.

For example, to list all jobs:

$ ucc list-jobs -f status equals RUNNING

To list all jobs submitted on Nov 13, 2007:

$ ucc list-jobs -f submissionTime contains 2007-11-13

Table 12 Filtering options
Operator (long and short form)	Description
equals, eq	String equality (ignoring case)
notequals, neq	String inequality (ignoring case)
contains, c	Substring match
notcontains, nc	substring non-match
greaterthan, gt	Lexical comparison
lessthan, lt	Lexical comparison

Low-level operations

UCC supports low-level access to REST API endpoints using the rest command, specifically you can execute HTTP GET, PUT, POST and DELETE requests with JSON content.

For example, to delete (destroy) a resource:

$ ucc rest delete <Address>

To get a complete property listing (i.e. print the JSON resource property document):

$ ucc rest get <Address>

To change properties, use the put command with JSON content:

$ ucc rest put '{"Tags": ["tests", "hpc" ]}'

These commands can be abbreviated, e.g. ucc rest d <Address>

Scripting

UCC can execute Groovy scripts. Groovy is a dynamic scripting language similar to Python or Ruby, but very closely integrated with Java. The scripting facility can be used for automation tasks or implementation of custom commands, but it needs a bit of insight into how UCC and UNICORE work.

Script context

Your Groovy scripts can access some predefined variables that are summarized in the following table:

Table 13 Variables accessible for scripts
variable	description	Java type
registry	A preconfigured client for accessing the registry	eu.unicore.client.registry.IRegistryClient
configurationProvider	Security configuration provider (truststore, etc)	eu.unicore.ucc.authn.UCCConfigurationProvider
auth	REST authentication mechanism	eu.unicore.services.rest.client.IAuthCallback
registryURL	the URL of the registry	java.lang.String
commandLine	the command line	org.apache.commons.cli.CommandLine
properties	defaults from the user’s properties file	java.util.Properties

Examples

Some example Groovy scripts can be found in the samples directory of the UCC distribution.

Frequently asked questions

Configuration

🤔 Do I really have to store my password in the preferences file? Isn’t this insecure?

Putting the password in a file or giving it as a commandline parameter can be considered insecure. The file could be read by others, and the commandline parameters may be visible in for example in the output of the ps command. Thus, UCC will simply ask for the password in case you did not specify it.

🤔 How can I enable more detailed logging?

UCC uses Log4j 2, by default the configuration is done in <UCC_HOME>/conf/logging.properties. You can edit this file and increase the logging levels, choose to log to a file or to the console, etc.

Usage

🤔 Can I use multiple registries with UCC?

Yes. Simply use a comma-separated list of URLs for the -r option. However, you may only use a single authentication setup, so all registries (and sites listed in them) must accept the same security credentials.

🤔 Can I upload and execute my own executable?

Yes. Check Running jobs.

🤔 Can I use UCC to list the contents of the registry?

Using the rest command this is very easy. For example,
$ ucc rest get https://localhost:8080/DEMO-SITE/rest/registries/default_registry
will list the content of the registry.