1. Introduction

This document is intended for Techila Administrators who wish manage their Techila Distributed Computing Engine (TDCE) environment using a command line interface.

The Techila Administrator CLI is accessible from command line interpreters for operating systems that support Java, including but not limited to:

  • Command Prompt for Windows based operating systems

  • Shells for Unix-like systems

This document contains descriptions of the available commands in the Techila Administrator CLI and provides examples on how to use the commands. If you are unfamiliar with the terminology or theory used in this document, please refer to the documents Introduction to Techila Distributed Computing Engine and Techila Distributed Computing Engine Administration Guide for more information.

The structure of this document is as follows:

Introduction contains information about the general prerequisites for accessing the Techila Administrator CLI and instructions for making the usage of the Techila Administrator CLI more user friendly by using environment variables.

Configuring and Testing the Techila Administrator CLI contains instructions on how to configure and test the Techila Administrator CLI. After following the instructions in this Chapter, you should be able to execute all Techila CLI administrator commands.

Commands contains descriptions about available Techila CLI administrator commands. These include commands for adding a new End-User to the TDCE environment and executing reports on the Techila Server. Simple examples are included for each command.

1.1. Checking Java Availability

In order to use the Techila Administrator CLI, Java needs to be installed on the computer you are using.

Please ensure that you have Java installed on your computer. Java Platform, Standard Edition 6 (or newer) Java Development Kit (JDK) or Java Runtime Environment (JRE) are supported.

When Java is installed and available from the command line, Java version can be verified with the following command. Please note that executing the command requires that the Java installation path is listed in the PATH environment variable.

java -version
java
Figure 1. Verifying the Java version from the command line.

1.2. Available Commands

The Techila Administrator CLI enables the administrator to interact with the Techila Server by executing commands using the command line interpreter of their operating system. The Techila Administrator CLI can be used to execute commands that enable you to perform the following tasks:

  • adduser - Creates a Techila Account and an End-User Key

  • removeuser - Removes a Techila Account

  • createuser - Creates a Techila Account

  • setpassword - Sets the Techila Account password

  • addkey - Transfers an End-User Key to the Techila Server

  • setkeytrust - Sets End-User Key trust value

  • assignkey - Assign an End-User Key to a Techila Account

  • unassignkey - Unassigns an End-User Key from a Techila Account

  • assigngroup - Assigns a Techila Worker Group to a Techila Account

  • unassigngroup - Unassigns a Techila Worker Group from a Techila Account

  • listgroupusers - Lists Techila Accounts having access to specified Worker Group

  • listusergroups - Lists Techila Worker Groups assigned to a Techila Account

  • listusers - Displays a list of Techila Accounts

  • listuserkeys - Lists End-User Keys on the Techila Server

  • listworkers - Lists all Techila Workers

  • listworkergroups - Lists Techila Worker Groups

  • listgroupworkers - Lists Techila Workers in a Techila Worker Group

  • startworker - Starts a Techila Worker

  • stopworker - Stops a Techila Worker

  • listreports - Lists available reports

  • report - Executes a report on the Techila Server

  • addreport - Adds a new report

  • setreport - Modifies existing report

  • removereport - Removes a report

  • configureic - Configures the interconnect Techila Worker Groups

  • listsemaphores - Lists semaphores on the Techila Server

  • addsemaphore - Creates a new global semaphore

  • removesemaphore - Removes a semaphore

The Techila Administrator CLI can be accessed by using the file techila.jar, which is included in the Techila SDK and is located in the techila/lib folder.

image006
Figure 2. The techila.jar file is located in the lib directory in the Techila SDK.

1.3. Accessing the Techila Administrator CLI

The Techila CLI administrator commands can be accessed by changing your current working directory to the techila/lib directory in the Techila SDK and executing the following command:

java -jar techila.jar admin

Executing the command shown above will display the internal help, which will list available Techila CLI administrator commands. This is illustrated the image below.

image007
Figure 3. Displaying the internal help.

If you do not wish to set your current working directory to techila/lib, the path to the techila.jar file needs to be defined when executing the commands. For example, if full path to the techila.jar file is C:\techila\lib\techila.jar, internal help can be displayed with command:

java -jar C:\techila\lib\techila.jar admin

Executing Techila CLI administrator commands is done by defining the name of the administrator command and any possible parameters for the command. This general syntax is shown below:

java -jar techila.jar admin <command> <parameters>

The <command> notation will be replaced with the Techila CLI administrator command that will be executed and the <parameters> notation with applicable parameters (if any) for the command.

Again, if the current working directory does not contain the techila.jar file, the path to application needs to be defined. For example, if full path to the directory that contains the techila.jar application is C:\techila\lib, Techila CLI administrator commands could be executed with the following command:

java -jar C:\techila\lib\techila.jar admin <command> <parameters>

1.4. Location of the techila_settings.ini configuration file

In order to use the Techila Administrator CLI, a properly configured techila_settings.ini file must be available.

The techila_settings.ini file will be automatically used if it exists in any of the locations listed below:

  • The file specified in environment variable TECHILA_SETTINGS_FILE

  • The current working directory

  • The following files from the users home directory

    • .techilarc

    • techila_settings.ini

  • The path specified with the environment variable TECHILA_SDKROOT

  • The parent folder of the techila.jar file

  • The directory containing the techila.jar file

The locations are searched in the order they are listed above. The search process will stop, when the techila_settins.ini file is found.

If the techila_settings.ini file is not found in any of the locations listed above, the location of the file can be defined by using the -c switch. The general syntax for defining the location by using the -c switch is illustrated below:

java -jar techila.jar -c <path_to>\techila_settings.ini admin <command>

The <path_to> notation needs to be replaced with the path leading to the techila_settings.ini file.

For example, the following syntax would use the techila_settings.ini file located in C:\my_files\ when executing Techila CLI administrator commands.

java -jar techila.jar -c C:\my_files\techila_settings.ini admin <command>

1.5. Accessing the Techila Administrator CLI by Using Environment Variables

Environment variables can be used for accessing the Techila Administrator CLI and for defining any other static parameters, such as the location of the techila_settings.ini file and the techila.jar file. This will reduce the amount of repetition and provides a convenient way for executing Techila CLI administrator commands.

To create an environment variable in a Windows environment to access the Techila Administrator CLI, execute the command shown below in the Windows Command Prompt. Note that the <path_to> notation should be replaced with the path leading to the techila.jar file:

set techila=java -jar <path_to>\techila.jar admin

You can also create the environment variable by using the functionality in the Windows Control Panel. Using the Windows Control Panel to create the environment variable will make the environment variable accessible in all Command Prompt sessions.

To create an environment variable in a Linux environment to access the Techila Administrator CLI, use the command shown below. Again, replace the <path_to> notation in the command with the path leading to the techila.jar file on your computer:

techila="java -jar <path_to>/techila.jar admin"

Note that you can also create an alias that accesses the Techila Administrator CLI by using the user configuration files (e.g. .bashrc) which are executed when logging in. This will make the Techila Administrator CLI accessible by using the alias and removes the need for setting the environment variable manually.

After an environment variable has been created, it can be used for executing Techila CLI administrator commands.

For example in a Windows environment, a Techila CLI administrator command could be executed with the following syntax:

%techila% <command>

And respectively in a Linux environment, a Techila CLI administrator command could be executed using the syntax shown below:

$techila <command>

2. Configuring and Testing the Techila Administrator CLI

This Chapter contains instructions on how to configure the Techila Administrator CLI and test the configuration by using the Techila Administrator CLI to add a new End-User to your Techila Distributed Computing Engine (TDCE) environment.

The procedures described in this Chapter have the following prerequisites:

  • Techila SDK available on your computer

Additionally, you must have deployed a Techila Server in one of the following supported environments:

  • Amazon EC2

  • Microsoft Azure

  • Google Cloud Platform

  • ESXi (Techila Virtual Server)

2.1. Configuring the Techila SDK for Techila Administrator CLI

Following Chapters contain instructions how to configure the Techila SDK to allow executing Techila CLI administrator commands. Please follow the configuration Chapter that is applicable to your situation:

If you are using a Techila Virtual Server, please follow instructions in Chapter:

OR

If you are using a Techila Server deployed in a public cloud environment (Microsoft Azure, Amazon EC2 or Google Cloud Platform), please follow instructions in Chapter:

2.1.1. Techila Virtual Server

This Chapter contains instructions about how to configure your Techila SDK to allow executing Techila CLI administrator commands when using a Techila Server deployed in one of the following supported virtualization environments:

VMware ESXi 5.0

Please refer to the document Techila Virtual Server Installation Guide VMWare for login credentials and password information if required.

Techila SDK configuration steps:

  1. Establish a SFTP connection to your Techila Virtual Server.

    The screenshot below illustrates how to use FileZilla to establish the SFTP connection

    cliimage008
    Figure 4. Establishing an sftp connection to the Techila Server
  2. After establishing connection, navigate to directory /home/techila-admin/userkeys and download the file subadmin1.jks to your computer.

    cliimage009
    Figure 5. Downloading the keystore file.
  3. After downloading the subadmin1.jks file, make a mental note where the file is on located on your computer. This information will be needed in the following steps.

    In the example below, the path of the file is:

    C:\TechilaKeys\subadmin1.jks
    cliimage010
    Figure 6. Check the location of the keystore file and make a mental note of the location.
  4. Navigate to your Techila SDK directory and rename techila_settings.ini.template file to techila_settings.ini.

  5. Open the techila_settings.ini file using a text editor.

  6. Replace the value of the keystore parameter with the path of your subadmin1.jks file. In this example, the path is:

    C:\TechilaKeys\subadmin1.jks

    The configured value is illustrated below.

    cliimage011
    Figure 7. Configuring the location of the keystore file in the techila_settings.ini file.
  7. In the techila_settings.ini file, replace the value of the hostname parameter with the network address of your Techila Virtual Server.

    In the example below, the IP address has been used. This is the same IP address that was used when establishing the SFTP connection to the Techila Virtual Server.

    cliimage012
    Figure 8. Configuring the network address of the Techila Server in the techila_settings.ini file.
  8. Save the changes you made to the techila_settings.ini file and close the text editor. The configuration is now complete.

Please continue by testing the configuration as described in Testing the Techila Administrator CLI.

2.1.2. Techila Server in Public Cloud Environment

This Chapter contains instructions about how to configure your Techila SDK to allow executing Techila CLI administrator commands when using a Techila Server deployed in one of the following supported public cloud environments:

  • Microsoft Azure

  • Amazon EC2

  • Google Compute Engine

Screenshots used in this Chapter correspond to a situation where the Techila Server is deployed in Amazon EC2. If your Techila Server is deployed in Microsoft Azure or Google Compute Engine, please modify the steps accordingly.

For the remainder of this document the term "Techila Deployment Tool" will be used to refer to Techila Deployment Tool for Amazon EC2, Techila Deployment Tool for Microsoft Azure and Techila Deployment Tool for Google Compute Engine.

Please note that steps described in this Chapter require that your Techila Server is currently deployed. If required, deploy your Techila Server by using the Techila Deployment Tool.

Techila SDK configuration steps:

  1. Locate the subadmin1.jks file on your computer. This file is automatically created when the Techila Server is deployed with the Techila Deployment Tool. The file should be in the same directory that contains the Techila Deployment Tool.

    In this example, the Techila Deployment Tool has been used to deploy the Techila Server. Deploying the Techila Server has created the file subadmin1.jks illustrated below to directory C:\AWSDeployment.

    Please make a mental note where the file is located, because this information will be needed in the next step.

    image013
    Figure 9. The path to the highlighted subadmin1.jks file will need to be entered to the techila_settings.ini file in the next steps.
  2. Navigate to your Techila SDK directory and open the techila_settings.ini file using a text editor.

  3. Replace the value of the keystore parameter with the path of your subadmin1.jks file. In this example, the path is:

    C:\AWSDeployment\subadmin1.jks

    The configured value is illustrated below.

    image014
    Figure 10. Configured keystore parameter in the techila_settings.ini file.
  4. In the techila_settings.ini file, replace the value of the hostname parameter with the network address of your Techila Server. The network address of the Techila Server can be copied from the message area of the Techila Deployment Tool

    Note! The network address of the Techila Server will be automatically displayed in the message area when the "Test AWS Connection" button is clicked.

    image015
    Figure 11. Define the network address of Techila Server in the hostname parameter. You can do this by copying the network address from the message area of the Techila Deployment Tool.
  5. Save the changes you made to the techila_settings.ini file and close the text editor. The configuration is now complete.

Please continue by testing the configuration as described in Testing the Techila Administrator CLI.

2.2. Testing the Techila Administrator CLI

This Chapter contains instructions how to test the Techila CLI administrator commands.

  1. Launch a command prompt and change your current working directory to techila/lib in the Techila SDK.

    In the example below, the path to the directory is:

    C:\techila\lib
    cliimage016
    Figure 12. Command Prompt window after navigating to techila/lib in the Techila SDK.
  2. Execute the following command in the command prompt to test network connectivity to the Techila Server.

    java -jar techila.jar testsession
  3. When prompted, enter the following keystore password:

    adminpass

    After entering the password, you should get the output illustrated in the screenshot below.

  4. If the network connection test fails, please check that your firewall has been configured to allow network connections from your computer to the Techila Server TCP port 25001.

    cliimage017
    Figure 13. View after a successful network connection test.
  5. Note! By default, the keystore password will be prompted each time you execute a Techila CLI command. If you do not want to be prompted for a password, please use one of the following options:

    Option 1 (recommended)

    1. Create a session to the Techila Server with Techila CLI init command. This command will prompt for the keystore password.

    2. Execute an arbitrary number of Techila CLI administrator commands. You will not be prompted for your keystore password.

    3. Remove the session with Techila CLI unload command.

    Option 2 (not recommended)

    Specify your keystore password in the techila_settings.ini file using the password parameter. After defining the password, you will not be prompted for your keystore password when executing Techila CLI commands.

    In the following steps, Option 1 will be used to create a session with the Techila Server.

  6. Create a session to the Techila Server with the init command using the syntax shown below:

    java -jar techila.jar init

    This is illustrated in the screenshot below:

    cliimage018
    Figure 14. Creating a session.
  7. When prompted, enter the following keystore password:

    adminpass

  8. This step will test that the Techila Account has the admin checkbox ticked in the Techila Web Interface.

    Execute the following Techila CLI administrator command to get a list of Techila Accounts:

    java -jar techila.jar admin listusers

    After executing the command, a list of Techila Accounts should be displayed as illustrated in the screenshot below. Please note that the list generated in your Techila environment might be different than the one illustrated here.

    cliimage019
    Figure 15. List of Techila Accounts returned by the listusers command.
  9. This step will test that the subadmin1.jks keystore file contains an administrator key and that you are using the correct password to access the administrator key.

    Note! The test will be done by using the adduser command, which will create a Techila Account and a keystore containing an End-User Key. Techila Accounts cannot be easily removed due to accounting mechanics. This means that if you execute the example command shown below, a Techila Account with login exampleuser will be created. This will not cause any problems to the operation of the Techila Server, but means that you cannot create another Techila Account with the same login value (exampleuser).

    Execute the following example command to create the End-User`s keystore file and Techila Account.

    Note! Modify the path defined in adminkeystore parameter to match the location of your subadmin1.jks file.

    java -jar techila.jar admin adduser adminkeystore=C:\AWSDeployment\subadmin1.jks adminpass=adminpass userkeystore=C:\techila\exampleuser.jks userpass=userpass123 validity=730 login=exampleuser username="Example User"

    Executing the command should generate similar output as illustrated in the screenshot below:

    cliimage020
    Figure 16. Output generated after executing the adduser command.
  10. The new Techila Account will now be visible when getting the list of Techila Accounts with command:

    java -jar techila.jar admin listusers
    cliimage021
    Figure 17. The new Techila Account will be visible when executing the listusers command.

    The Techila Administrator CLI has now been tested successfully. You are now able to execute any Techila CLI administrator command.

  11. Execute the unload command to remove the session:

    java -jar techila.jar unload

    This is illustrated in the screenshot below:

    cliimage022
    Figure 18. Remove the session with the unload command.

3. Commands

This Chapter contains a description of Techila CLI administrator commands.

Please note that the example syntaxes used in the following Chapters assume that the current working directory is techila/lib in the Techila SDK.

If you are using a different current working directory, please modify the commands accordingly.

3.1. ListUsers

ListUsers - Display a list of Techila Accounts.

3.1.1. Syntax

listusers [showdeleted=<false|true>] [columns="<columns>..."]

3.1.2. Description

The ListUsers command displays a list of Techila Accounts. By default, the list will display the login , username and lastseen columns for each Techila Account.

Additional (or fewer) columns can be returned by defining a comma separated list of desired column names as input for the command.

3.1.3. Parameters

Parameter Default value Description

showdeleted

false

Defines whether or not removed Techila Accounts will be displayed.

Value false: Do no display removed Techila Accounts

Value true: Also displays removed Techila Accounts

columns

login,username, lastseen

Comma separated list of columns that will be returned in the list. Please see Table below for a list of available column names

The Table below contains a list of column names that can be given to columns parameter when executing the command. Any columns defined when executing the command will be returned in the output.

Column Return Value Description

userid

<int>

The user identification number. Each Techila Account will have a unique userid.

username

<string>

The Techila Account owner name

isadmin

<boolean>

Does the Techila Account have the administrative permissions in the Techila Web Interface?

Return value 1: Administrative permissions

Return value 0: No administrative permissions

lastseen

<timestamp>

Timestamp of the last activity of the End-User. This timestamp is updated by Techila Web Interface activity and each time a session is created using management interface (typically during Project creation).

If the End-User has not logged in to the Techila Web Interface or created management interface sessions, a minus sign (-) will be displayed.

cloudpermission

<boolean>

Does the Techila Account have permission to deploy Techila Workers in public cloud providers with the Techila Starter Tool?

Return value 1: Permission to deploy Techila Workers

Return value 0: No permissions

login

<string>

The login associated with the Techila Account

projectpermission

<boolean>

Does the Techila Account have the permission to create computational Projects?

Return value 1: Permission to create Projects

Return value 0: No permissions

email

<string>

The email address associated with the Techila Account.

expire

<int>

The session expiration time for the Techila Account. If the Techila Account remains inactive for a longer time period than defined here, they will need to re-enter their login credentials to the Techila Web Interface.

priority

<int>

The Techila Account priority. This priority value will be used by the Techila Server scheduling algorithm and will have a small effect when determining which Projects are given computational capacity. By default, all Techila Accounts have the same priority.

isdeleted

<boolean>

Has the Techila Account been removed?

Return value 1: Techila Account is removed

Return value 0: Existing Techila Account

bundlepermission

<boolean>

Does the Techila Account have the permission to approve Bundles on the Techila Server?

Return value 1: Permission to approve Bundles

Return value 0: No permission

3.1.4. Example 1: Display List of Techila Accounts with Default Columns

The example command below gets a list of Techila Accounts with the default columns.

java -jar techila.jar admin listusers

Below screenshot shows the output of the ListUsers command when executed without any additional parameters. This will display the columns login, username and lastseen for each Techila Account on the Techila Server.

image023
Figure 19. Displaying a list of all Techila Accounts.

3.1.5. Example 2: Display List of Techila Accounts with Specified Columns

The example command below gets a list of Techila Accounts with all default columns and the isadmin column, which displays information whether or not the Techila Account has administrative permissions in the Techila Web Interface.

java -jar techila.jar admin listusers columns=login,username,lastseen,isadmin

Below screenshot shows the output of the ListUsers command when executed by using the columns parameter to define a list of desired columns. The column isadmin contains information about the Techila Account`s permission status in the Techila Web Interface.

image024
Figure 20. The output of the ListUsers command. In this example, Techila Accounts with login admin and exampleadmin have administrative permissions in the Techila Web Interface, as indicated by the value 1 in the isadmin column.

3.2. ListWorkers

ListWorkers - Lists all Techila Workers.

3.2.1. Syntax

listworkers [columns="<columns>..."]

3.2.2. Description

The ListWorkers command can be used to retrieve a list of all Techila Workers. By default, the Techila Worker ID, status, alias and uptime for each Techila Worker is displayed.

Additional (or fewer) columns can be returned by defining a comma separated list of desired column names as input for the command.

3.2.3. Parameters

Parameter Default value Description

columns

workerid,status,alias,uptime

Comma separated list of columns that will be displayed in the list. Please see Table below for a list of available column names.

The Table below contains a list of column names that can be used as values to the columns parameter. All specified columns will be included in the list returned by the command.

Column Return Value Description

jobs

<int>

Number of Jobs on the Techila Worker, including Jobs that have been expired. This value is also shown in the Techila Web Interface.

benchmark

<float>

Benchmark result of the Techila Worker. Benchmark units are an internal metric used when sorting the Techila Workers based on CPU performance.

totaldiskspace

<int>

Total amount of disk space on the partition the Techila Worker software is installed on. Value in bytes.

totalmem

<int>

The total amount of RAM memory on the computer the Techila Worker is installed on. Value in bytes.

lastseen

<timestamp>

Time stamp of the last network connection established to the Techila Server from the Techila Worker.

activejobs

<int>

Number of Jobs on the Techila Worker, which have not been expired.

errors

<int>

Number of errors generated in Jobs on the Techila Worker since the last Job that was successfully completed.

cpufree

<float>

Amount of free CPU power on the Techila Worker.

osarch

<string>

Processor architecture of the Techila Worker.

osname

<string>

Operating system of the Techila Worker.

alias

<string>

The alias of the Techila Worker. The alias is generated automatically when the Techila Worker software is installed. The alias can also be changed in the Techila Web Interface.

status

<int>

The status of the Techila Worker. Status values shown below:

  • 0 = "Stopped"

  • 1 = "Running"

  • 32 = "Suspended"

  • 33 = "Suspended"

  • 64 = "Initializing"

  • 65 = "Initializing"

  • 96 = "Initializing"

  • 97 = "Initializing"

uptime

<string>

The uptime of the Techila Worker processes. If a Techila Worker is offline, a minus sign (-) will be displayed as the value. Value displayed in seconds.

processors

<int>

Total number of CPU cores on the Techila Worker.

usablecpus

<int>

Number of CPU cores that can be used to assign computational Jobs. By default, one Job will be assigned to one CPU core.

workerid

<int>

The Techila Worker ID number. Each Techila Worker in the Techila environment will have a unique Techila Worker ID.

freediskspace

<int>

Amount of free disk space on the Techila Worker.

bundlesize

<int>

Amount of disk space used by Bundles on the Techila Worker. Value in bytes.

3.2.4. Example 1: Getting a List of Techila Workers

The example command below gets a list of Techila Workers.

java -jar techila.jar admin listworkers

The above command will display the following information:

  • Techila Worker ID of each Techila Worker

  • Status of the Techila Worker

  • Alias of the Techila Worker

  • Uptime of the Techila Worker processes in seconds

Below screenshot contains an example output of this command. In the list of Techila Workers, two Techila Workers are currently online as indicated by the values in the uptime column. Remaining eight Techila Workers are offline, as indicated by the minus signs in the uptime column. Both of the Techila Workers that are online are in the Running state, as indicated by the value 1 in the status column.

image025
Figure 21. Displaying a list of Techila Workers. The uptime of currently online Techila Workers will be visible in the uptime column.

3.2.5. Example 2: Getting a List of Jobs on Techila Workers

The example command below gets a list of Jobs assigned to Techila Workers.

java -jar techila.jar admin listworkers columns=workerid,jobs,activejobs

Below screenshot shows an example output when the command is executed. Each line in the output will display the Techila Worker ID of a Techila Worker and the number of Jobs currently assigned to the Techila Worker. The jobs column shows how many Jobs (including expired Jobs) are assigned to the Techila Worker in total and the activejobs column displays the number of non-expired Jobs.

In this example, Techila Worker with Techila Worker ID 10 is currently processing 32 Jobs as shown by the value in the jobs column. One of these Jobs is expired, as indicated by the value 31 in the activejobs column.

image026
Figure 22. Displaying the number of Jobs assigned to Techila Workers.

3.3. ListGroupUsers

ListGroupUsers - Lists Techila Accounts have access to specified Techila Worker Group.

3.3.1. Syntax

listgroupusers group=<group name> [columns="<columns>..."]

3.3.2. Description

The ListGroupUsers command can be used to get a list of Techila Accounts that have access to the specified Techila Worker Group.

In order for an End-User to successfully use the Techila Distributed Computing Engine (TDCE) environment for computational purposes, their Techila Account will need to have access to at least one Techila Worker Group, which has suitable Techila Workers for their purposes.

3.3.3. Parameters

Parameter Default value Description

group

No default value. Mandatory parameter

Name of the Techila Worker Group for which the Techila Accounts will be listed.

Note! If there are no Techila Accounts assigned to the Techila Worker Group, the command will only return the column headers.

Note! If you attempt to get a list of Techila Accounts assigned to a non-existing Techila Worker Group, the command will only return the column headers.

columns

login,name

Comma separated list of columns that will be displayed in the list. Please see Table below for a list of available column names.

The Table below contains a list of column names that can be used as values to the columns parameter. All specified columns will be included in the list returned by the command.

Column Return Value Description

login

<string>

The login of the Techila Account.

name

<string>

The name of the Techila Account owner.

3.3.4. Example 1: Getting a List of Techila Accounts Assigned to a Techila Worker Group

The example command below gets a list of Techila Accounts assigned to the Techila Worker Group named "All Workers".

java -jar techila.jar admin listgroupusers group="All Workers"
image027
Figure 23. Displaying a list of Techila Accounts that have access to Techila Worker Group "All Workers".

3.4. ListUserGroups

ListUserGroups - Lists Techila Worker Groups assigned to specified Techila Account.

3.4.1. Syntax

listusergroups login=<login> [columns="<columns>..."]

3.4.2. Description

The ListUserGroups command can be used to get a list of Techila Worker Groups that are assigned to a Techila Account.

3.4.3. Parameters

Parameter Default value Description

login

No default value. Mandatory parameter

The Techila Account for which Techila Worker Groups will be listed.

Note! If there are no Techila Accounts assigned to the Techila Worker Group, the command will only return the column headers.

columns

name,cpriority

Comma separated list of columns that will be displayed in the list. Please see Table below for a list of available column names and descriptions.

The Table below contains a list of column names that can be used as values to the columns parameter. All specified columns will be included in the list returned by the command.

Column Return Value Description

name

<string>

The name of the Techila Worker Group.

priority

<string>

The Techila Worker Group priority.

3.4.4. Example 1: Getting a List of Techila Worker Groups Assigned to a Techila Account

The example command below gets a list of Techila Worker Groups assigned to the Techila Account with login exampleuser.

java -jar techila.jar admin listusergroups login=exampleuser

The screenshot below contains an example output of the command. The command returns three lines of output, first line containing the column headers and the remaining two lines containing the Techila Worker Groups that are assigned to the exampleuser Techila Account. In this example, Techila Worker Groups "All Workers" and "Example Group" are assigned to the Techila Account. This means that the owner of the Techila Account can use Techila Workers belonging to either Techila Worker Group in their computational Projects.

image028
Figure 24. Displaying a list of Techila Worker Groups assigned to Techila Account with login exampleuser.

3.5. ListUserKeys

ListUserKeys - Lists End-User Keys on the Techila Server.

3.5.1. Syntax

listuserkeys [login=<login>] [columns="<columns>..."]

3.5.2. Description

The ListUserKeys command can be used to retrieve a list of End-User Keys on the Techila Server.

If an End-User Key is not assigned to any Techila Account, the userid column returned by this command will have the value 0 and the login column will be empty.

This command can also be used to retrieve a list of End-User Keys that are assigned to a specific Techila Account. This is done by defining the login of the Techila Account when executing the command (see Example 2).

3.5.3. Parameters

Parameter Default value Description

login

All logins. By default, will display list of all End-User Keys on the Techila Server.

The Techila Account for which End-User Keys will be listed.

columns

userid,login,trusted,dn

Comma separated list of columns that will be displayed in the list. Please see Table below for a list of available column names and descriptions.

The Table below contains a list of column names that can be used as values to the columns parameter. All specified columns will be included in the list returned by the command.

Column Return Value Description

trusted

<boolean>

The status of End-User Key`s trust value.

Return value true: End-User Key is trusted.

Return value false: End-User Key is not trusted

Key trusted status can be changed with the SetKeyTrust command.

dn

<string>

The distinguished name of the End-User Key. Each End-User Key will have a unique distinguished name.

login

<string>

The login of the Techila Account the key is assigned to. If the key is not assigned to any Techila Account, this column will be empty.

validfrom

<timestamp>

Start of the End-User Key validity period.

validto

<timestamp>

End of the End-User Key validity period.

userid

<int>

The user id of the Techila Account the End-User Key is assigned to. If the End-User Key is not assigned to any Techila Account, the value 0 will be displayed.

3.5.4. Example 1: Getting a List of All End-User Keys on the Techila Server

The command shown below displays a list of all End-User Keys on the Techila Server.

java -jar techila.jar admin listuserkeys

The screenshot below shows an example output of the command. The first line of the output displays the column headers, following lines display a list of End-User Keys on the Techila Server. The End-User Key on the first line is unassigned, as indicated by the value 0 in the userid column and the empty login column.

image029
Figure 25. Getting a list of all End-User Keys on the Techila Server.

3.5.5. Example 2: Getting a List of Assigned Keys to a Techila Account

The command below gets a list of keys assigned to the Techila Account which has login exampleuser.

java -jar techila.jar admin listuserkeys login=exampleuser

The screenshot below contains an example output of the command. The first line contains the column headers and the following two lines contain information about the keys that are assigned to the Techila Account exampleuser. In this example, there are two lines, meaning that there are two keys assigned to the Techila Account.

The value of the trusted column for the key on the second line is false, meaning the key cannot be used to establish a session to the Techila Server. This means that this key cannot be used when creating computational Projects.

The value of the trusted column for the key on the third line is true, meaning that the key could be used to establish a session to the Techila Server. This means that this key can be used to create computational Projects.

Note! If required, you can use the SetKeyTrust command to toggle the status of the key`s trusted value.

image030
Figure 26. Displaying a list of End-User Keys assigned to a Techila Account.

3.6. ListWorkerGroups

ListWorkerGroup - Lists Techila Worker Groups.

3.6.1. Syntax

listworkergroups [columns="<columns>"]

3.6.2. Description

The ListWorkerGroups command can be used to retrieve a list of existing Techila Worker Groups.

Note! After retrieving a list or Techila Worker Groups with this command, you can use the AssignGroup command to assign any of the Techila Worker Groups to a Techila Account. This will allow the owner of the Techila Account to use Techila Workers in the Techila Worker Group in their computational Projects.

3.6.3. Parameters

Parameter Default value Description

columns

groupid,name,description

Comma separated list of columns that will be displayed in the list. Please see Table below for a list of available column names and descriptions.

The Table below contains a list of column names that can be used as values to the columns parameter. All specified columns will be included in the list returned by the command.

Column Return Value Description

groupid

<int>

The Techila Worker Group identification number. Each Techila Worker Group will have a unique identification number.

Note! If a Techila Worker Group is deleted, the identification number of the Techila Worker Group will not be re-used when creating new Techila Worker Groups.

name

<string>

The name of the Techila Worker Group

description

<string>

The description of the Techila Worker Group

isdefault

<boolean>

Will this Techila Worker Group be automatically assigned to new Techila Accounts?

Return value t: The Techila Worker Group will be assigned

Return value f: The Techila Worker Group will not be assigned

The default value of Techila Worker Groups can be configured in the Techila Web Interface on the "Worker Groups" page.

3.6.4. Example 1: Displaying a List of Techila Worker Groups

The example command below displays a list of existing Techila Worker Groups.

java -jar techila.jar admin listworkergroups

The below screenshot contains an example output of the command. The first line contains the column headers and the following three lines display all existing Techila Worker Groups. One Techila Worker Group is displayed on each line. The groupid column has the values 1,2 and 5 while values 3 and 4 are missing. This indicates that two Techila Worker Groups (with groupids 3 and 4) have been deleted at some point before executing the command.

image031
Figure 27. Displaying a list of Techila Worker Groups.

3.6.5. Example 2: Displaying Automatically Assigned Techila Worker Groups

The command shown below can be used to display which Techila Worker Groups will be automatically assigned to new Techila Accounts. This is done by listing isdefault as one of the column names that will be returned (columns parameter).

java -jar techila.jar admin listworkergroups columns=name,isdefault

The screenshot below displays an example output of the command. In the example, the value of the isdefault column is t (true) for Techila Worker Group "All Workers" and f (false) for other Techila Worker Groups. This means that only Techila Worker Group "All Workers" will be assigned to new Techila Accounts.

Note! If required, the isdefault status of Techila Worker Groups can be defined in the Techila Web Interface, on the "Worker Groups" page.

image032
Figure 28. Checking which Techila Worker Groups will be automatically assigned to new Techila Accounts.

3.7. ListGroupWorkers

ListGroupWorkers - Displays a list of Techila Workers in the specified Techila Worker Group.

3.7.1. Syntax

listgroupworkers group=<group> [columns="<columns>"]

3.7.2. Description

The ListGroupWorkers command can be used to display a list of Techila Workers in the specified Techila Worker Group.

If no Techila Workers are assigned in the Techila Worker Group, only the column headers will be returned by the command.

3.7.3. Parameters

Parameter Default value Description

group

No default value. Mandatory parameter.

The name of the Techila Worker Group for which you want to display assigned Techila Workers.

Note! If the Techila Worker Group name contains a whitespace, the name will need to be enclosed in quotation marks (").

columns

workerid,alias

Comma separated list of columns that will be displayed in the list. Please see Table below for a list of available column names and descriptions.

The Table below contains a list of column names that can be used as values to the columns parameter. All specified columns will be included in the list returned by the command.

Column Return Value Description

osname

<string>

The operating system of the Techila Worker.

hostname

<string>

The hostname (on Linux) or computername (on Windows) of the Techila Worker.

alias

<string>

The alias of the Techila Worker. The alias of a Techila Worker can be defined in the Techila Web Interface.

osarch

<string>

Processor architecture

lastseen

<timestamp>

Timestamp of the last active network connection

workerid

<int>

The Techila Worker identification number.

usablecpus

<int>

Number of CPU cores that can be used when assigning computational Jobs.

3.7.4. Example 1: Listing Techila Workers in a Techila Worker Group

The example command below displays a list of Techila Workers assigned to the "All Workers" Techila Worker Group (group parameter).

java -jar techila.jar admin listgroupworkers group="All Workers"

The screenshot below contains an example output generated by the command. The first line of the output contains the default column headers and the following lines contain a list of Techila Workers assigned to the "All Workers" Techila Worker Group. One line of output is generated per Techila Worker. In this example, there are 10 Techila Workers assigned in the Techila Worker Group, which means that there are also 10 lines of output.

image033
Figure 29. Displaying a list of Techila Workers in the Techila Worker Group "All Workers".

3.8. ListReports

ListReports - Lists available reports.

3.8.1. Syntax

listreports

3.8.2. Description

The ListReports command lists available reports that have been created on the Techila Server.

3.8.3. Parameters

This command takes no input parameters.

The Table below describes the output columns generated by the command.

Parameter Description

id

The Report ID number. Each report has a unique identifier.

description

The description of the report.

query

Displays the SQL query that will be executed when running the report

3.8.4. Example 1: Getting a List of Reports

The example command below gets a list of Techila Accounts with the default columns.

java -jar techila.jar admin listreports

In this example, there are four reports on the Techila Server.

image034
Figure 30. Displaying a list of reports.

3.9. AddUser

AddUser - Adds a new End-User to the TDCE environment by creating a new Techila Account and a new End-User Key.

3.9.1. Syntax

adduser [adminkeystore=<keystore>] [index=<indexfile>] [adminalias=<alias>] [adminpass=<password>] [userkeystore=<keystore.jks>] [useralias=<useralias>] login=<login> username="<user name>" [dn=<DN>] userpass=<userpass> [group="<worker group>"] [validity=<validity period>] [keyonly=<false|true>]

3.9.2. Description

This command can be used to create a new Techila Account and a keystore containing the End-User Key. The End-User Key will also be automatically transferred to the Techila Server and assigned to the Techila Account.

This command can also be used to only create the keystore file. This is useful in situations where the Techila Account has already been created and the End-User Key has expired. In this situation, the End-User Key will be assigned to the specified existing Techila Account.

Note! You can only create Techila Accounts, which have login values that have not been previously used. This applies even if you have removed the earlier Techila Account.

3.9.3. Parameters

Parameter Default value Description

adminkeystore

/home/techila-admin/admin/admin.jks

Location of the keystore that contains the administrator key

index

Path defined in parameter adminkeystore parameter.

The index file used to store key data, including serial number, distinguished name and validity period.

Information from the index file is typically only needed when revoking keys.

By default, the index.xml will be read from the same directory as defined in adminkeystore

adminalias

Alias of the first key in the admin keystore.

The alias of the administrator key in the administrator keystore.

Typically this parameter does not need to be defined.

Note! If your keystore contains multiple keys, this parameter needs to be used to define the alias.

adminpass

adminpass

The password of the administrator keystore file.

userkeystore

<login>.jks

The name of the keystore file that will be created and used to store the End-User Key

By default, the keystore name will be defined by using the value of the login parameter.

useralias

<login>

The alias of the End-User Key that will be created. By default, the alias will be same as defined in the parameter login.

login

No default value. Mandatory parameter.

The Techila Account login used to log in to the Techila Web Interface. This parameter is always required.

username

No default value. Mandatory parameter.

The name of the Techila Account owner

dn

CN=<username> <system timestamp in milliseconds>

The distinguished name of the End-User Key. By default, value will be set based on the username parameter and the system clock timestamp.

userpass

No default value. Mandatory parameter.

The password to the End-User keystore file that will be created. Same password will be set for the Techila Web Interface Techila Account.

group

All Workers

Techila Worker Groups that will be assigned to the End-User. By default, the "All Workers" Techila Worker Group will be assigned.

Note! If there are any Techila Worker Groups that have the default checkbox ticked in the Techila Web Interface "Worker Groups" page, these Techila Worker Groups will also be assigned to the Techila Account.

validity

365

The validity of the End-User Key in days. By default the validity period is 365 days.

keyonly

false

Toggles Techila Account creation on/off.

3.9.4. Example 1: Adding a New End-User

Below example command will add a new End-User to the Techila system by creating a Techila Account and a keystore containing the End-User Key.

java -jar techila.jar admin adduser adminkeystore=C:\AWSDeployment\subadmin1.jks adminpass=adminpass login=johndoe userpass=userpass123 username="John Doe" userkeystore=C:\techila\johndoe.jks validity=730

The first two parameters (adminkeystore, adminpass) in the example are used to define which administrator key is accessed. The syntax used accesses the administrator key in the C:\AWSDeployment\subadmin1.jks keystore file. The password used to access the keystore is adminpass.

The following parameters (login, username, userpass) in the example define the properties of the Techila Account that will be created for the End-User. The syntax used will create a Techila Web Interface account with the login johndoe (login parameter) and password userpass123 (userpass parameter). Name John Doe (username parameter) will be displayed when the user is logged in the Techila Web Interface.

The following parameters (userkeystore, userpass, validity) in the example define the properties of the keystore containing the End-User Key that will be created. The syntax used will create a keystore file in C:\techila\johndoe.jks (userkeystore parameter). The alias of this keystore will be set to johndoe (default value of alias parameter) the keystore will be protected with the password userpass123 (userpass parameter). The validity period of the End-User Key will be 730, which means 730 days or 2 years.

The Techila Worker Group named "All Workers" (default value for the group parameter) will be automatically assigned to the End-User.

Below is a screenshot of the Windows Command Prompt after executing the command. In this example, the keystore file johndoe.jks has been generated and stored in C:\techila\johndoe.jks.

image035
Figure 31. Executing the adduser command will create the keystore file in the directory you defined in the userkeystore parameter.

Below is a screenshot of the Techila Web Interface, displaying the new Techila Account. The "Bundles" and "Projects" checkboxes have been automatically ticked for the Techila Account, meaning the End-User automatically has necessary permissions to create computational Projects.

image036
Figure 32. The new Techila Account will be visible in the "End-Users" page in the Techila Web Interface.

Below is another screenshot from the Techila Web Interface, which displays the Techila Account settings. The "Assigned Keys" table displays the properties of the End-User`s Key (2 year validity period) and "Assigned Worker Groups" table displays that the Techila Worker Group "All Workers" is assigned to the Techila Account.

image037
Figure 33. The End-User Key and Techila Worker Group will be automatically configured.

3.9.5. Example 2: Create New End-User Key and Assign To Existing Techila Account

Below example command will create a keystore containing an End-User Key. This End-User Key will be assigned to an existing Techila Account.

java -jar techila.jar admin adduser adminkeystore=C:\AWSDeployment\subadmin1.jks adminpass=adminpass login=johndoe userpass=userpass123 username="John Doe" userkeystore=C:\techila\johndoenew.jks validity=1460 keyonly=true

The parameters of the command are identical to those in Example 1 in this Chapter, except for parameters userkeystore, validity and keyonly.

The new keystore will be saved in to C:\techila\johndoenew.jks (userkeystore parameter) and the validity of the new End-User Key will be set to 1460 days (validity parameter). The new End-User Key will be assigned to an existing Techila Account, meaning no new Techila Accounts will be created (login and keyonly parameters).

image038
Figure 34. The new keystore file will be stored in the path defined in the userkeystore parameter. In this example, the keystore file johndoenew.jks has been created in directory C:\techila.

The End-User Key will be assigned to the existing johndoe Techila Account and will be visible in the Techila Web Interface as illustrated in the screenshot below.

image039
Figure 35. The new End-User Key will be automatically assigned to the Techila Account and the key status will be set to trusted.

3.10. RemoveUser

RemoveUser - Removes a Techila Account.

3.10.1. Syntax

removeuser login=<userlogin>

3.10.2. Description

The RemoveUser command removes the Techila Account.

After the Techila Account has been removed, any End-User Keys assigned to the Techila Account cannot initiate new management session with the Techila Server, meaning the End-User Keys cannot be used for computational purposes.

Note! When a Techila Account is removed using the RemoveUser command, no new Techila Accounts with the same login value can be created. This is because the removed Techila Account will still be stored in the Techila Server database and used for accounting purposes.

3.10.3. Parameters

Parameter Default value Description

login

No default value. Mandatory parameter.

The login of the Techila Account that will be removed.

3.10.4. Example 1: Removing a Techila Account

The example command below will remove a Techila Account., which has the login exampleuser (login parameter).

java -jar techila.jar admin removeuser login=exampleuser

In the screenshot below, the Techila CLI administrator command listusers has been used to display a list of Techila Accounts, which includes an account for exampleuser. The Techila Account has then been removed with removeuser command. After removing the Techila Account, the Techila Account will no longer be visible when a list of Techila Accounts is retrieved with another listusers command.

Note! If you wish to view removed Techila Accounts, add the showdeleted=true parameter to the listusers command.

image040
Figure 36. After removing the exampleuser Techila Account, it will no longer be visible in the list of Techila Accounts.

3.11. CreateUser

CreateUser - Creates a Techila Account.

3.11.1. Syntax

createuser login=<login> name=<username> password=<password> [expire=<expiration>] [bundlepermission=<true|false>] [projectpermission=<true|false>] [isquest=<false|true>] [isadmin=<false|true>]

3.11.2. Description

The CreateUser command can be used to create a new Techila Account. The End-User can then access the Techila Web Interface using the Techila Account login and password.

Note! This command will not create a keystore file containing an End-User Key. If you wish to add a new End-User to your TDCE environment who is also able to create computational Projects, please use the AddUser command as described in AddUser.

3.11.3. Parameters

Parameter Default value Description

login

No default value. Mandatory parameter.

The login of the Techila Account that will be created.

name

No default value. Mandatory parameter

The name of the Techila Account owner. Will be displayed in the Techila Web Interface when the End-User is logged in.

password

No default value. Mandatory parameter

The Techila Account password. The End-User will be able to login to the Techila Web Interface with the password defined here.

expire

1800

The Techila Web Interface session expiration period. If the End-User remains inactive in the Techila Web Interface for a longer time period than defined with this parameter, they will be prompted to re-enter their login credentials. Value in seconds.

bundlepermission

true

Gives the Techila Account the permission to approve Bundles.

projectpermission

true

Gives the Techila Account the permission to create Projects.

isquest

false

Legacy feature. Can be used to give the Techila Account access to the administrator pages in the Techila Web Interface, without giving control over the features on these pages.

isadmin

false

Can be used to give the Techila Account access to the administrator pages in the Techila Web Interface and full control on these pages.

3.11.4. Example 1: Creating a Regular Techila Account

The example command below will create a regular Techila Account (no isadmin parameter, default false value will apply) with login exampleuser4 (login parameter) and password exPass123 (password parameter). The timeout for the Techila Account will be set to 1 hour (expire parameter)

java -jar techila.jar admin createuser login=exampleuser4 name="Example User" password=exPass123 expire=3600

The screenshot below illustrates how the new Techila Account will be visible in the list of Techila Accounts.

image041
Figure 37. After creating the new Techila Account, it will be visible in the list of Techila Accounts. The value in the isadmin column is 0, meaning the Techila Account does not have administrative permissions in the Techila Web Interface.

3.11.5. Example 2: Creating Techila Account with Administrator Permissions

The example command below will create a Techila Account, which has administrator permissions.

java -jar techila.jar admin createuser login=exampleadmin name="Example Admin" password=exPass123 expire=3600 isadmin=true

This command would create a Techila Account with login exampleadmin (login parameter) and password exPass123 (password parameter). This Techila Account will have administrative permissions in the Techila Web Interface (isadmin parameter).

image042
Figure 38. After creating the Techila Account, it will be visible in the list of Techila Accounts. The value in the isadmin column is 1, meaning the Techila Account has administrative permissions in the Techila Web Interface.

3.12. SetPassword

SetPassword - Resets the password of a Techila Account to the Techila Web Interface.

3.12.1. Syntax

setpassword login=<userlogin> password=<newpassword>

3.12.2. Description

The SetPassword command can be used to reset a Techila Account password.

Note! This command only resets the Techila Account password to the Techila Web Interface. The password for the keystore file containing the End-User Key will not be changed. Instructions for changing the keystore password can be found in the document "Introduction to Techila Distributed Computing Engine".

3.12.3. Parameters

Parameter Default value Description

login

No default value. Mandatory parameter.

The login of the Techila Account for which the password will be changed.

password

No default value. Mandatory parameter.

The new password for the Techila Account.

3.12.4. Example 1: Changing Techila Account Password

The example command below will change the password for a Techila Account with login exampleuser (login parameter). The new password for the Techila account will be set to examplepass (password parameter).

java -jar techila.jar admin setpassword login=exampleuser password=examplepass

After changing the password for the Techila Account, exampleuser would be able to login to the Techila Web Interface using password examplepass.

3.13. AddKey

AddKey - Transfers an End-User Key from an existing keystore file to the Techila Server.

3.13.1. Syntax

addkey keystore=<keystore> password=<password> [alias=<alias>]

3.13.2. Description

The AddKey command can be used to transfer an End-User Key from an existing keystore file to the Techila Server.

Note! The transferred End-User Key will not be assigned to any Techila Account. Please use command AssignKey to assign the End-User Key to a Techila Account.

3.13.3. Parameters

Parameter Default value Description

keystore

No default value. Mandatory parameter.

The path and name of the keystore file that contains the End-User Key that you wish to transfer to the Techila Server.

password

No default value. Mandatory parameter.

The existing keystore password. This password will be used to access the keystore file.

useralias

Alias of the first key in the keystore.

The alias of the End-User Key in the keystore. Typically this parameter does not need to be defined.

Note! If your keystore contains multiple keys, this parameter needs to be used to define the alias.

3.13.4. Example 1: Transferring an End-User Key to the Techila Server

The example command below accesses keystore located in C:\techila\exampleuser.jks (keystore parameter), which is protected with password examplepass (password parameter). The useralias parameter does not need to be defined, because the keystore file only contains one key.

java -jar techila.jar admin addkey keystore=C:\techila\exampleuser.jks password=examplepass

Below screenshot displays a list of End-User Keys on the Techila Server, before and after executing the AddKey command. After executing the AddKey command, the new End-User Key will be visible in the list of End-User Keys. The userid column displays the value 0 and the login column is empty, which means that the End-User Key is not assigned to any Techila Account.

image043
Figure 39. After transferring the End-User Key to the Techila Server, the unassigned End-User Key will be visible in the list.

3.14. SetKeyTrust

SetKeyTrust - Sets End-User Key trust value to true or false, depending on the parameters used.

3.14.1. Syntax

setkeytrust login=<login> dn=<key DN> [trust=<true|false>]

3.14.2. Description

The SetKeyTrust command sets the End-User Key trust value to trusted or untrusted, based on the value of the trust parameter.

In order for the End-User Key to be used for creating computational Projects, the End-User Key trust value needs to be set to trusted.

The SetKeyTrust command can also be used to set the trust value of an End-User Key to untrusted, which will prevent the End-User Key from being used to create computational Projects.

Note! End-Users that have been added using the Techila CLI administrator AddUser command or by using the "Add End-User" functionality in the Techila Deployment Tool will automatically have End-User Keys assigned and trusted to their Techila Accounts.

3.14.3. Parameters

Parameter Default value Description

login

No default value. Mandatory parameter.

The login of the Techila Account that the End-User Key is assigned to.

dn

No default value. Mandatory parameter

The distinguished name of the End-User Key for which the trust value will be modified. Distinguished names can be viewed with the ListUserKeys command.

trust

true

Defines whether the End-User Key will be trusted or untrusted. Key status can be set to untrusted by using value false

3.14.4. Example 1: Setting an Assigned End-User Key to Untrusted

The example command below modifies the trust status of End-User Key with distinguished name "CN=Example User 1414142504223" (dn parameter) assigned to Techila Account with login exampleuser (login parameter). The trusted status of the End-User Key will be set to untrusted (trust parameter).

java -jar techila.jar admin setkeytrust login=exampleuser dn="CN=Example User 1414142504223" trust=false

Below screenshot displays the trust status of the End-User Key assigned to the Techila Account with login exampleuser, before and after executing the SetKeyTrust command. After executing the SetKeyTrust command, the trust status of the End-User Key`s trust value will be false as highlighted.

image044
Figure 40. After modifying the trust value of the End-User Key, the status of the End-User key is untrusted.

3.15. AssignKey

AssignKey - Assigns an End-User Key to a Techila Account.

3.15.1. Syntax

assignkey login=<login> dn=<key DN>

3.15.2. Description

The AssignKey command can be used to assign an End-User Key to a Techila Account.

End-User Keys can only be assigned if they are available on the Techila Server. End-User Keys cannot be assigned directly from keystore files. Please use command AddKey to transfer and End-User Key to the Techila Account if needed.

This command can also be used to re-assign an assigned End-User Key to a different Techila Account. Reassigning the End-User Key will automatically remove it from the original Techila Account.

3.15.3. Parameters

Parameter Default value Description

login

No default value. Mandatory parameter.

The login of the Techila Account that the End-User Key will be assigned to.

dn

No default value. Mandatory parameter

The distinguished name of the End-User Key that will be assigned.

3.15.4. Example 1: Assigning an Unassigned End-User Key to a Techila Account

The example command below assigns an End-User Key with distinguished name CN=Example User 1414139663832 (dn parameter) to Techila Account with login exampleuser (login parameter).

java -jar techila.jar admin assignkey login=exampleuser dn="CN=Example User 1414139663832"

Below screenshot displays status of the End-User Keys assigned to Techila Accounts, before and after executing the AssignKey command. Before the AssingKey command is executed, the defined End-User Key is not assigned to any Techila Account. After the AssignKey command is executed, the End-User Key with the specified distinguished name is assigned the Techila Account with login exampleuser.

image045
Figure 41. After assigning the End-User Key to the exampleuser Techila Account, the value exampleuser will be displayed in the login column for the End-User Key.

3.15.5. Example 2: Reassigning End-User Key to a Different Techila Account

The example command below assigns an End-User Key with distinguished name CN=Example User 1414139663832 (dn parameter) to Techila Account with login testuser (login parameter).

java -jar techila.jar admin assignkey login=testuser dn="CN=Example User 1414139663832"

Below screenshot displays status of the End-User Keys assigned to Techila Accounts, before and after executing the AssignKey command. Before the AssingKey command is executed, the specified End-User Key is assigned to the Techila Account with login exampleuser.

After the AssignKey command is executed, the End-User Key with the specified distinguished name is has been reassigned to the Techila Account with login testuser. No End-User Keys are assigned to the exampleuser Techila Account.

image046
Figure 42. After reassigning the End-User Key, the login column will display the new value.

3.16. UnassignKey

UnassignKey - Removes an End-User Key from a Techila Account.

3.16.1. Syntax

unassignkey login=<login> dn=<key DN>

3.16.2. Description

The UnassignKey command can be used to remove an End-User Key from a Techila Account. After being removed, the End-User Key will not be assigned to any Techila Account.

End-User Keys that are not assigned to any Techila Account cannot be used to create sessions to the Techila Server or for signing Bundles, meaning the End-User Key cannot be used for computational purposes.

Unassigned End-User Keys can be assigned to Techila Accounts by using the AssignKey command.

3.16.3. Parameters

Parameter Default value Description

login

No default value. Mandatory parameter.

The login of the Techila Account from which the End-User Key will be removed.

dn

No default value. Mandatory parameter

The distinguished name of the End-User Key that will be unassigned.

3.16.4. Example 1: Unassigning an End-User Key from a Techila Account

The example command below unassigns an End-User Key with distinguished name CN=Example User 1414139663832 (dn parameter) from Techila Account with login testuser (login parameter).

java -jar techila.jar admin unassignkey login=testuser dn="CN=Example User 1414139663832"

Below screenshot displays status of the End-User Keys assigned to Techila Accounts, before and after executing the UnassignKey command. Before the UnassignKey command is executed, the defined End-User Key is assigned to the Techila Account with login testuser. After the UnassignKey command is executed, the End-User Key with the specified distinguished name is not assigned to any Techila Account. This can be seen from the userid column, which has the value 0 and the empty login column.

image047
Figure 43. After unassigning the End-User Key, the login and userid columns will reflect the change.

3.17. AssignGroup

AssignGroup - Assigns a Techila Worker Group to a Techila Account.

3.17.1. Syntax

assigngroup login=<login> group=<group name>

3.17.2. Description

The AssignGroup command can be used to assign a Techila Worker Group to a Techila Account. Assigning a Techila Worker Group to an End-User`s Techila Account will give the End-User access to all Techila Workers in the Techila Worker Group.

Several Techila Worker Groups can be assigned to a Techila Account by executing this command multiple times, with desired Techila Worker Group names.

3.17.3. Parameters

Parameter Default value Description

login

No default value. Mandatory parameter.

The login of the Techila Account that the Techila Worker Group will be assigned to.

group

No default value. Mandatory parameter

The name of the Techila Worker Group that will be assigned.

If the Techila Worker Group name contains a whitespace, the name will need to be enclosed in the quotation marks, e.g. "Example Group".

3.17.4. Example 1: Assigning a Techila Worker Group to a Techila Account

The example command below assigns a Techila Worker Group named "Example Group" (group parameter) to Techila Account with login johndoe (login parameter).

java -jar techila.jar admin assigngroup login=johndoe group="Example Group"

Below screenshot displays a list of Techila Worker Groups assigned to the Techila Account johndoe, before and after executing the AssignGroup command. Before the AssignGroup is executed, only the "All Workers" Techila Worker Group is assigned to the Techila Account. After the AssignGroup has been executed, the Techila Worker Group named "Example Group" is also assigned to the Techila Account.

image048
Figure 44. Assigning a Techila Worker Group to a Techila Account.

3.18. UnassignGroup

UnassignGroup - Removes a Techila Worker Group from a Techila Account.

3.18.1. Syntax

unassigngroup login=<login> group=<group name>

3.18.2. Description

The UnassignGroup command can be used to remove a Techila Worker Group from a Techila Account. Removing a Techila Worker Group from an End-User`s Techila Account will revoke the End-User access to all Techila Workers in the Techila Worker Group.

Several Techila Worker Groups can be removed from a Techila Account by executing this command multiple times, with desired Techila Worker Group names.

3.18.3. Parameters

Parameter Default value Description

login

No default value. Mandatory parameter.

The login of the Techila Account from which the Techila Worker Group will be removed from.

group

No default value. Mandatory parameter

The name of the Techila Worker Group that will be removed from the Techila Account.

If the Techila Worker Group name contains a whitespace, the name will need to be enclosed in the quotation marks, e.g. "Example Group".

3.18.4. Example 1: Removing a Techila Worker Group from a Techila Account

The example command below removes a Techila Worker Group named Example Group (group parameter) from Techila Account with login johndoe (login parameter).

java -jar techila.jar admin unassigngroup login=johndoe group="Example Group"

Below screenshot displays a list of Techila Worker Groups assigned to the Techila Account johndoe, before and after executing the UnassignGroup command. Before the UnassignGroup is executed, Techila Worker Groups "All Workers" and "Example Group" are assigned to the Techila Account. After the UnassignGroup command has been executed, only Techila Worker Group named "All Workers" is assigned to the Techila Account.

image049
Figure 45. After unassigning the Techila Worker Group "Example Group", only Techila Worker Group "All Workers" remains assigned.

3.19. StartWorker

StartWorker - Removes any possible Stopped statuses from Techila Workers.

3.19.1. Syntax

startworker <workerid>...

3.19.2. Description

The StartWorker command can be used to remove the Stopped status of the Techila Worker. Removing the Stopped status will allow Jobs to be assigned to the Techila Worker.

Several Techila Workers can be started using a single command by defining the Techila Worker IDs as a whitespace separated list.

Please note that if status of the Techila Worker is Suspended or Initializing after the Stopped status is removed, Jobs will not be assigned to the Techila Worker. In this case, Jobs will start to be assigned when any possible Suspended or Initializing statuses have been replaced with the Running status.

3.19.3. Parameters

Parameter Default value Description

workerid

No default value. Mandatory parameter.

Defines which Techila Workers will be affected.

3.19.4. Example 1: Starting One Techila Worker

The example command below removes the Stopped status from Techila Worker with Techila Worker ID 1.

java -jar techila.jar admin startworker 1

Below screenshot displays the status of Techila Workers, before and after executing the StartWorker command. Before the StartWorker command is executed, Techila Worker with Techila Worker ID 1 is stopped, as indicated by the value 0 in the status column. After the StartWorker command has been executed, the status of Techila Worker ID 1 is 1, indicating that the Techila Worker is no longer in the stopped state.

image050
Figure 46. Removing the Stopped status of a Techila Worker.

3.19.5. Example 2: Starting Several Techila Worker

The example command below removes the Stopped status from Techila Workers with Techila Worker IDs 1, 2, 6 and 7.

java -jar techila.jar admin startworker 1 2 6 7

Below screenshot displays the status of Techila Workers, before and after executing the StartWorker command. Before the StartWorker command is executed, all Techila Workers are stopped as indicated by the value 0 in the status column. After the StartWorker command has been executed, Techila Workers with Techila Worker IDs 1,2,6 and 7 have been started, as indicated by value in the status column 1.

image051
Figure 47. Removing the Stopped status of several Techila Workers.

3.20. StopWorker

StopWorker - Sets the status of Techila Workers to Stopped.

3.20.1. Syntax

stopworker <workerid>...

3.20.2. Description

The StopWorker command can be used to set the status of a Techila Worker to Stopped. Setting the status to Stopped will prevent new Jobs to be assigned to the Techila Worker.

Several Techila Workers can be stopped using a single command by defining the Techila Worker IDs as a whitespace separated list.

3.20.3. Parameters

Parameter Default value Description

workerid

No default value. Mandatory parameter.

Defines which Techila Workers will be stopped.

3.20.4. Example 1: Stopping One Techila Worker

The example command below stops one Techila Worker with Techila Worker ID 1.

java -jar techila.jar admin stopworker 1

Below screenshot displays the status of Techila Workers, before and after executing the StopWorker command. Before the StopWorker command is executed, all Techila Workers are running as indicated by the value 1 in the status column. After the StopWorker command has been executed, the status of Techila Worker with Techila Worker ID 1 is 0, indicating that the Techila Worker is now in the Stopped state.

image052
Figure 48. Stopping one Techila Worker.

3.20.5. Example 2: Stopping Several Techila Workers

The example command below stops Techila Workers with Techila Worker IDs 1, 2, 3 and 4.

java -jar techila.jar admin stopworker 1 2 3 4

Below screenshot displays the status of Techila Workers, before and after executing the StopWorker command. Before the StopWorker command is executed, all Techila Workers are in the Running state as indicated by the value 1 in the status column. After the StopWorker command has been executed, Techila Workers with Techila Worker IDs 1,2,3 and 4 have been stopped, as indicated by value in the status column 0.

image053
Figure 49. Stopping several Techila Workers.

3.21. AddReport

`AddReport` - Adds a new report to the Techila Server.

3.21.1. Syntax

addreport query=<SQL query> description=<description>

3.21.2. Description

The AddReport command can be used to add a new report to the Techila Server. After adding the report, the report can be executed by using the Report command.

This command requires an SQL query as an input argument. This will define what database operations are performed when this report is executed.

For more information about what SQL tables and columns can be used in reports, please see the document "Techila Distributed Computing Engine Reporting Guide".

3.21.3. Parameters

Parameter Default value Description

query

No default value. Mandatory parameter.

The SQL query that will be executed when the report is executed.

description

No default value. Mandatory parameter.

Description of the report.

3.21.4. Example 1: Adding a New Report

The command below adds a very simple report to the Techila Server. The example report will return the Project ID numbers of Projects that have been created by Techila Account with userid 1.

java -jar techila.jar admin addreport query="select projectid from projects where createdby=1 order by projectid" description="Example description text"

The screenshot below contains an example output when executing the command. After the AddReport command has been executed, the new report will be listed when getting a list of reports with the ListReports command.

image054
Figure 50. After adding a new report, it will be visible in the report list generated by ListReports command.

3.21.5. Example 2: Adding a Report Requiring Input Parameters

The example command shown below adds a similar query as in the previous example. The differentiating factor is that the userid of the Techila Account will need to be passed as an input parameter each time when the report is executed.

java -jar techila.jar admin addreport query="select projectid from projects where createdby=${uid:User ID:int} order by projectid" description="Query with input argument"

Below screenshot displays adding the report with the AddReport command. After the report has been added, the report will be visible when a list of reports is retrieved with the ListReports command.

Please see Example 2: Executing a Report with Input Parameters for instructions how to run this example report.

image055
Figure 51. Creating a report that requires input parameters.

3.22. Report

Report - Executes a report on the Techila Server.

3.22.1. Syntax

report [headers=<true|false>] [xml=<false|true>] [<parametername=value>...] <Report ID>

3.22.2. Description

The Report command can be used to run reports that have been previously added to the Techila Server.

The following output formats are supported:

  • XML

  • Semicolon separated values (default)

Input parameters can also be passed to the executable report. This is useful in situations where you want to execute the same report with different parameters (e.g. different userid).

The report output will be printed to the standard output stream. If you wish to store the output in a file, redirect the output to the desired output file as shown below:

report <id> > outputfile.txt

3.22.3. Parameters

Parameter Default value Description

headers

true

Toggles report headers on/off. Only affects output formatting when xml=false.

Value true: Headers on

Value false: Headers off

xml

false

Can be used to generate output in xml format.

Value false: Output in semicolon separated format

Value `true: Output in XML format

parametername

No default value.

Defines parameter for the report. Can be used to pass input arguments from the command line interface to the report.

3.22.4. Example 1: Executing a Report

Please see Example 1: Adding a New Report for information how to create the report that is executed in this example.

The example command shown below executes report with Report ID 8.

java -jar techila.jar admin report 8

In the screenshot below, the ListReports command has been used to display a list of reports on the Techila Server. After displaying the list, report with Report ID 8 has been executed using the report command.

image056
Figure 52. Displaying a list of reports and executing a report.

3.22.5. Example 2: Executing a Report with Input Parameters

Please see Example 2: Adding a Report Requiring Input Parameters for information how to create the report executed in this example.

The command shown below will execute report with Report ID 9. The value for the uid parameter is defined in the command line syntax.

java -jar techila.jar admin report uid=1 9

The value of the uid parameter will define which userid will be selected when retrieving the list of Projects with the report.

The screenshot below contains example syntax and output when executing the command. The ListReports command is used to get a list of reports. After retrieving the list of reports, the Report ID of the desired report can be selected and entered when executing the report with Report command.

image057
Figure 53. Executing a report that requires input parameters.

3.23. SetReport

SetReport - Replaces an existing report with a SQL query and description.

3.23.1. Syntax

setreport reportid=<Report ID> query=<SQL query> description=<description>

3.23.2. Description

The SetReport command can be used to replace the SQL query and description of an existing report with new values.

3.23.3. Parameters

Parameter Default value Description

reportid

No default value. Mandatory parameter.

Defines which report will be modified.

query

No default value. Mandatory parameter.

The new SQL query that will be set in the modified report.

description

No default value. Mandatory parameter.

The new description of the modified report

3.23.4. Example 1: Replace an Existing Report and Description

The example command below sets a new SQL query and description for an existing report with Report ID 8.

java -jar techila.jar admin setreport reportid=8 query="select status,projectid from projects where createdby=1 order by projectid" description="Modified example description text"

After executing the SetReport command, report with Report ID 8 has been modified to retrieve the Project status and Project ID number of Projects created by the Techila Account with userid 1. The modified SQL query and description can be viewed with the ListReports command.

image058
Figure 54. Modifying an existing report.

3.24. RemoveReport

RemoveReport - Removes an existing report from the Techila Server.

3.24.1. Syntax

removereport reportid=<report id>

3.24.2. Description

The RemoveReport command can be used to remove an existing report from the Techila Server.

After the report has been removed, the report cannot be executed with the Report command.

3.24.3. Parameters

Parameter Default value Description

reportid

No default value. Mandatory parameter.

Defines which report will be removed.

3.24.4. Example 1: Removing an Existing Report

The example command shown below will remove report with Report ID 8.

java -jar techila.jar admin removereport reportid=8

The screenshot below shows the execution of the command. After the report has been removed with the RemoveReport command, the report will no longer be visible in the report list returned by the ListReports command.

image059
Figure 55. Removing a report.

3.25. ConfigureIC

ConfigureIC - Automatically configures interconnect Techila Worker Groups.

Note! When running the configureic command, it is strongly recommended that all Techila Workers in the Techila Distributed Computing Engine (TDCE) environment are in the Running state. If Techila Workers are in the Suspended, Stopped or Initializing state, the interconnect test Projects will contain a reduced amount of Jobs. In this case, the result of the test Project might not be valid for the entire Techila Worker Group.

3.25.1. Syntax

configureic [forceclean=<false|true>] [keepall=<false|true>]

3.25.2. Description

The configureic command can be used to automatically create Techila Worker Groups, which are able to process Jobs that use the Techila interconnect functions.

The flowchart below illustrates what operations are performed when the command is executed.

icgroup

The table below describes the configurations that are created in the Techila Web Interface when the command is executed.

Feature Description

Worker Group(s)

The command will create one or more Techila Worker Groups based on network connectivity of the Techila Workers. I.e. Techila Workers are grouped so that that all Techila Workers in the Techila Worker Group can transfer interconnect data packages with other Techila Workers in the Techila Worker Group.

Techila Worker Groups will be named using the following convention (depending on how many unique Techila Worker Groups will be found):

  • IC Group 1

  • IC Group 2

  • IC Group 3

Please note that if network connectivity prevents establishing interconnect networks, no Techila Worker Groups will be created.

Policy Group

The command will create a Policy Group, which will be assigned to the All Workers Techila Worker Group. The name of the this Policy Group will be:

AllNeighbors

Policy Rules

The AllNeighbors Policy Group, will contain one Policy Rule. This Policy Rule will be used to list all Techila Workers as neighbors to all other Techila Workers. The description of this Policy Rule will be:

AllNeighborsListedHere

3.25.3. Parameters

Parameter Default value Description

forceclean

false

Defines whether or not override existing interconnect configurations

Value true: Any previous interconnect configurations will be removed when the command is executed.

Value false: Execution will be aborted if any previous interconnect configurations are detected.

keepall

false

Defines whether or not to keep interconnect Techila Worker Groups that failed during the testing phase. Setting this value to true can be useful when you want to keep non-working configurations for further investigation.

Value false: Remove all interconnect Techila Worker Groups which did not process the interconnect test Project successfully.

Value true: Keep all interconnect Techila Worker Groups that were created, even the Techila Worker Groups which did not process the interconnect test Project successfully.

3.25.4. Example 1: Creating interconnect Techila Worker Groups

The example command shown below will create interconnect Techila Worker Groups.

java -jar techila.jar admin configureic

The screenshot below shows an example output generated by the command when run in an environment, which consist of 11 Techila Workers. In this case, the command created two Techila Worker Groups, IC Group 1 (8 Techila Workers) and IC Group 2 (3 Techila Workers).

image061
Figure 56. Executing the configureic command.

3.26. ListSemaphores

ListSemaphores - Lists semaphores on the Techila Server

3.26.1. Syntax

listsemaphores

3.26.2. Description

The listsemaphores command can be used to retrieve a list of semaphores from the Techila Server.

3.26.3. Example 1: Listing semaphores on the Techila Server

The example command shown below will list retrieve a list of semaphores from the Techila Server.

java -jar techila.jar admin listsemaphores
image062
Figure 57. Retrieving a list of semaphores.

3.27. AddSemaphore

AddSemaphore - Adds a new semaphore

3.27.1. Syntax

addsemaphore name=<name> [size=<size>] [expiration=<expiration>]

3.27.2. Description

The AddSemaphore command can be used to either add a new global semaphore or modify the properties of an existing semaphore.

3.27.3. Parameters

Parameter Default value Description

name

No default value. Mandatory parameter.

Defines the name of the semaphore that will be the target of this command. If the name does not match with an existing semaphore, then a new semaphore will be created.

If the name matches to an existing semaphore, then the size and expiration values for that semaphore will be set to match the values used when the command was executed.

size

1

Defines how many semaphore tokens the semaphore will have. By default, the semaphore will be set to contain one semaphore token.

expiration

never

Defines the semaphore expiration time (in seconds). By default, the semaphore will never expire.

3.27.4. Example 1: Adding a new semaphore

The example command shown below will create a new semaphore named sema1 with 10 semaphore tokens, each token having an expiration time of 1800 seconds (30 minutes).

java -jar techila.jar admin addsemaphore name=sema1 size=10 expiration=1800

The screenshot below shows the execution of the command and illustrates how the new semaphore can be viewed after it has been added.

image063
Figure 58. Adding a new semaphore.

3.27.5. Example 2: Modifying an existing semaphore

The example command shown below will modify a semaphore named sema1. When the command is executed, the number of semaphore tokens will be increased from 10 to 100.

java -jar techila.jar admin addsemaphore name=sema1 size=100 expiration=1800

The screenshot below shows the execution of the command and illustrates how the new properties of the sema1 semaphore were changed when the command was executed.

image064
Figure 59. Modifying an existing semaphore.

3.28. RemoveSemaphore

RemoveSemaphore - Removes an existing semaphore.

3.28.1. Syntax

removesemaphore name=<name>

3.28.2. Description

The RemoveSemaphore command can be used to remove an existing semaphore.

3.28.3. Parameters

Parameter Default value Description

name

No default value. Mandatory parameter.

Defines the name of the semaphore that will removed.

3.28.4. Example 1: Removing an existing semaphore

The example command shown below will remove a semaphore named sema1.

java -jar techila.jar admin removesemaphore name=sema1

The screenshot below shows the execution of the command and illustrates how the new semaphore can be viewed after it has been added.

image064
Figure 60. Removing a new semaphore.