FURMS user manual

In various places in this document, the following text is used to mark a limitation which is specific to the current release:
v2 limitation
All such marked limitations will be removed in the final release.

Fenix User and Resource Management Service (FURMS for short) is a central system responsible for the authorization of access and resource management across multiple research infrastructures.

FURMS is organized around three main concepts: sites, communities and projects:

Site represents a service provider. Site administrator defines resources offered by the site.
Community is an umbrella over a set of related research projects. Human Brain Project can be considered as an example of FURMS community.
Project, defined under a community, groups users who are working together. Project, and its members are consuming resources which are contributed by sites.

FURMS organizes the process of resources distribution offered by sites to communities and subsequently to individual projects. What is more FURMS aggregates and presents resource usage metrics.

Resource allocation process works as follows:

Site administrator defines a resource.
Site administrator creates one or more resource credits which define an amount of contributed resource usage units.
Fenix administrator can see unallocated resource credits and assign them to communities. In majority of cases a single resource credit can be split across multiple communities.
Community administrator can in turn distribute community resource credits to projects in the community.
Project administrator can control which project users have access to individual resources which were granted to the project.

FURMS has dedicated UI modes for each type of its user. User who has only a single role in the system will simply see the only view matching her or his role. Users with multiple roles can switch the view mode with a dropdown situated in the top right corner of the screen.

In order to authenticate to FURMS user has to contain an account which is available for the Fenix Central Identity Provider.

v2 limitation the final shape of the sign-up process will be implemented in the phase 4 of the project. The current version provides only a simplified signup mechanism, allowing for complete testing of other, already delivered functions. That said, the onboarding described below is tentative and will be changed in next versions.

Regular user sign in is handled via the Fenix Central IdP. After entering the FURMS public address (as configured during installation) user is redirected to the Central IdP and has to authenticate using his/her home identity provider.

Each user who can authenticate using Fenix Central IdP can access FURMS. Initially only access to User Settings view is granted, without access to any of the projects. Access to a project needs to be granted either by community or project’s administrator. User can be also added to Fenix, site, community or project administrators by other administrators.

Initial onboarding

Since initially every user authenticated with the Central IdP has no administrative privileges, the initial setup of the system has to be performed in special way.

During FURMS installation a local user account is created with configured user name and password. The created user is granted Fenix administrator privileges as well as Unity administrative privileges. To sign in as a local user, a special URL parameter needs to be added when entering FURMS Web UI, as follows:

https://FURMS-PUBLIC-HOST/?showSignInOptions

Entering FURMS web interface with the showSignInOptions parameter prevents FURMS to trigger automatic authentication with the Central IdP. Instead user can choose to authenticate locally. This authentication method must be used at least once to initially configure the system, and can be used at will later on.

Since the complete invitation mechanism is going to be delivered in future releases, currently inviting of users to become administrators or ordinary project users is limited to those Central IdP users who has signed into FURMS at least once.

Let’s consider an example where Local Fenix Admin wants to invite Mary — a Central IdP user — to become community admin:

Local Fenix Admin has to sign in using the showSignInOptions parameter.
Mary has to sign in into FURMS in a regular way. She won’t have access to anything besides her profile at this time. Mary can sign out now.
Local Fenix Admin can now add Mary as a community admin as she signed into FURMS at least once.
After Mary signs into FURMS next time she will have access to her community administrative functions.

Fenix federation management

Fenix administrator is responsible for:

creating sites,
creating communities,
distributing site provided resource credits to communities.

Managing sites

Fenix admin can create sites providing only the basic information: site name. Additional site attributes are supposed to be setup by the site admin.

After creating a site, Fenix admin should provide at least a single administrator for the site. The appropriate view can be activated from the site’s context menu "Administrators". From there the Fenix admin can freely add and remove site administrators.

Site administrators can also themselves manage administrators of their site, so the Fenix admin is not the only person controlling the set of administrators. However, setting the initial site admin must be always performed by the Fenix admin.

A new administrator can be invited either by selecting one of existing FURMS users or by providing an email address. In the latter case the invited person must have a Fenix infrastructure account. The invited user needs to accept the invitation to a new role.

Managing communities

Fenix admin can create communities providing site name, description and logo. Community settings can be also changed subsequently by community admins and therefore only the name of a created community is mandatory.

After creating a community, Fenix admin should provide at least a single administrator for it. The appropriate view can be activated from the community’s context menu "Administrators". From there the Fenix admin can freely add and remove community administrators.

Community administrators can also themselves manage administrators of their community, so the Fenix admin is not the only person controlling the set of administrators. However, setting the initial community admin must be always performed by the Fenix admin.

Managing Fenix administrators

FURMS allows for having multiple users with the Fenix administrator role. Each Fenix admin can add (and remove) other administrators from the "Fenix administrators" view.

Note that removing the last administrator is not allowed.

Distributing resources to communities

Distribution of resource credits provided by sites can be performed from two parts of the FURMS user interface.

The typical way to distribute credits starts at the Fenix administrator dashboard. Dashboard shows all resource credits. By default only the not-fully distributed and valid credits are shown, though it is possible to show also all excluded ones. Fenix admin can use the (+) button on each credit to create an allocation from it. When creating allocation this way, the target community has to be selected.

The other way to create allocations from credits is to start from a target community, in the Communities view. After selecting a community and navigating to its Allocations tab, Fenix administrator can create an allocation for that community. When creating allocation this way, the resource credit needs to be selected. Interface allows for using multiple level of filters to easily find the desired credit.

REST API access credentials

To access FURMS REST API, administrator has to generate an API key (secret token) and use it together with its user identifier when authenticating against FURMS REST API endpoints.

The token can be generated in User Settings → API Key. The view also provides information about the fixed user identifier as well an option to revoke a previously generated token.

The user identifier and API key should be used with the HTTP Basic authorization scheme when accessing the REST API. For example using cURL:

curl [other params] -u USER_ID:API_KEY <FURMS_ENDPOINT_URL>

Note that the generated key is bound to a user, so a user who has multiple roles (e.g. admin of a site and a project) should use the same token, regardless of the role. The generated credential is authorized to perform the same operations as its owner.

Site management

FURMS site acts a resource provider. Site defines resources (which are always site specific in FURMS), and advertises amounts of those resources available to the Fenix infrastructure.

Additionally site can define policy documents which are need to be accepted in order to access the site or its resources.

Site settings

Under site settings menu entry, site administrator can provide details about the site. It is advised to fill up the form, as initially site definition consists of a minimal set of attributes (like name) only.

Site administrator may set a requirement on SSH keys installed by FURMS, to always include the 'from' option (specifying allowed client addresses for the key). If this option is set after some keys without the 'from' option were already installed, FURMS will not auto-remove the offending keys. However, user will be forced to either remove the key from the site or to add the 'from' option upon the next editing of the key.

What is more site administrator can require users not to reuse previously used SSH keys.

Site can have a policy document set. Accepting site policy is a prerequisite for any user, to be added to the site. Any policy defined for the site can be selected as a site-wide policy.

Policy documents

Site can define multiple policy documents. A policy document can be used in two places: as a site-wide policy or as a service-specific policy. Policy documents can be provided either as an uploaded PDF file, or can be embedded inside FURMS using rich text editor.

Policy documents are defined in a single place (Policy Documents menu entry). Assigning policy document to a service is available in serivice’s edit view, while selection of a site-wide policy can be performed in site’s settings view.

FURMS supports two types of policy document workflows:

web based policies are electronically processed documents, i.e. users can accept them on-line, from the FURMS app.
paper policies need to be printed and physically delivered to site authorities.

Users are asked to check the policy whenever they get access to a resource, which is either on a new site or a new service, for which the policy is defined and was not accepted yet. Regardless of the policy type, user can always read & download its text. In the case of the web policies, direct acceptance is possible by the user. Contrary, the fact that the hand-signed paper policy document was received, must be recorded by site administrator or site support (see Managing site administrators). This functionality is available after entering into details of users policy acceptance status, in the Policy Documents view.

Policy documents can be updated after creation. Update can be done in two ways:

As a silent update, useful for correcting typos and formatting. In such a case, users who previously accepted the policy won’t be notified in any way.
As an official update. Official update triggers requests to users who previously accepted the policy, to review and accept the updated version. Official update is also tracked with a policy revision number, which is incremented each time the policy is officially updated.

Services

Services are used in FURMS to represent different offerings of a single site. The most important aspect of service is that it can have its own access policy agreement defined. Also each service creates a namespace for its resources.

Computing cluster, data store system or an OpenStack VM service can be examples of services.

Service can have its own policy document. Any of the policy documents defined for the site can be selected.

Resource types

Resource type represents resource which have independent allocations and has its usage accounted separately.

Administrator has to decide type and a dependent unit of the resource type. Type defines generic treatment of resource and available units. FURMS supports two generic types integer and floating point as well as two more specific types: time and data.

Units are different for each type. Note that FURMS does not scale the amounts of a given resource type, always the selected Unit is used.

Resource credits

Resource credits are used to express site’s offering to the FURMS managed infrastructure. Credit is an offer of a particular amount of a given resource in a defined timeframe. Credits are further distributed by Fenix administrators to communities and eventually to projects.

Each credit is always based on a single resource type (and therefore is also bound to a particular service).

Credit has its lifetime, expired credits can not be allocated to communities or projects, even if were not completely consumed.

Site can control whether credit can be allocated in multiple parts or just as a single one. In the later case it must be allocated to a single community and to a single project in this community.

Finally credits can be marked as granted to all project members. Allocation derived from credits created with this flag will not have separate access authorization: each project member will be able to use it, without any further actions.

Site agent connection and requests

v2 limitation This functionality is available only partially, allowing site administrators to check whether the agent is up and connected.

Managing site administrators

FURMS allows for multiple users with the site administrator role. Each site administrator can add (and remove) other administrators from the "Site administrators" view.

Additionally the view allows for adding users with the site support role. Such users will be able to access only the Policy Documents view and record the fact that a hand-signed paper policy document was received.

A new administrator can be invited by providing an email address of the invitation recipient. The invited person must possess a Fenix infrastructure account.

Note that removing the last administrator is not allowed.

REST API access credentials

To access FURMS REST API, administrator has to generate an API key (secret token) and use it together with its user identifier when authenticating against FURMS REST API endpoints.

The token can be generated in User Settings → API Key. The view also provides information about the fixed user identifier as well an option to revoke a previously generated token.

The user identifier and API key should be used with the HTTP Basic authorization scheme when accessing the REST API. For example using cURL:

curl [other params] -u USER_ID:API_KEY <FURMS_ENDPOINT_URL>

Community management

FURMS community groups closely related projects and organizes the process of allocating resources to them.

Managing projects

Community administrator can create projects providing set of initial project settings. Selected project settings can be also changed subsequently by project administrators.

When creating a project, community administrator needs to setup project leader, who will also become the initial project administrator. Additional administrators can be also setup after activating the "Administrators" option from the project’s context menu.

Project administrators can also themselves manage administrators of their project, and so community administrator is not the only person controlling the set of administrators.

Managing community administrators

FURMS allows for having multiple users with the community administrator role. Each community administrator can add (and remove) other administrators from the "Community Administrators" view.

Note that removing the last administrator is not allowed.

Managing community metadata

Community name, description and logo can be modified at any time. It can be performed from the "Settings" view.

Distributing resources to projects

Distribution of community resource allocations to projects can be performed in two different ways.

The typical path to distribute available resource allocations starts at the community administrator dashboard. Dashboard shows all resource allocations of the community. By default only the not-fully distributed and valid allocations are shown, though it is possible to show also the ones excluded by default. Community admin can use the (+) button on each community allocation to create a project allocation from it. When creating allocation this way, the target project has to be selected.

The other way to create project allocations is to start from a target project, in the Projects view. After selecting a project and navigating to its Allocations tab, community administrator can create an allocation for that project. When creating allocation this way, one of community allocations needs to be selected.

Managing groups

FURMS allows community administrators to create groups and control membership of community users in the groups.

There are no limits on membership in groups, any community member can be a member of zero, one or many groups. The sole restriction is that only existing community users can be added to a group (i.e. users of any of the community projects and community admins). Adding and removing a user to a group does not require user’s consent.

Group membership is not changing the way how FURMS works in any way. It is, however, exposed on the REST APIs: both for the Fenix Central IdP and over Community REST API.

REST API access credentials

To access FURMS REST API, administrator has to generate an API key (secret token) and use it together with its user identifier when authenticating against FURMS REST API endpoints.

The token can be generated in User Settings → API Key. The view also provides information about the fixed user identifier as well an option to revoke a previously generated token.

The user identifier and API key should be used with the HTTP Basic authorization scheme when accessing the REST API. For example using cURL:

curl [other params] -u USER_ID:API_KEY <FURMS_ENDPOINT_URL>

Project management

FURMS project groups users who work on a common topic and consume resources provided by sites and assigned by communities.

Each project must have a project leader, who is a formal representative and a responsible person. Besides this formal role, project has one or more administrators, who can manage the project in FURMS.

Project management in FURMS consists of two main operations:

managing users who work within the project,
managing access of project users to resources allocated to the project.

What is more, FURMS collects resource usage information from sites on which resources are consumed. This information can be used to track budget consumption and its spread over time.

Managing users

Under the Users menu entry, project administrator can view, add and remove project users. Note that project administrator needs not to be (and does not become by default) a regular project user. Administrator can however assign him/her-self project user role with a dedicated action button.

A new project user can be invited by providing his or her email address. Note that the invited person must possess a Fenix infrastructure account and accept the invitation to eventually become project user.

Users can also on their own apply for project membership. Such applications needs to be accepted (or rejected) by project admin.

Project settings

Under the Settings menu entry, project administrator can control project details. Some of the settings are under control of the parent community and therefore are presented as read-only values.

Resource access

Users of a project do not access to each allocation automatically. Instead, the project administrator is responsible for granting (or removing) access to each individual allocation. This is controlled on the Resource access view.

Note that there is one exception to that rule. Site sometimes define resources which are available to all users at the site. Such resources are available to all users at the site, and control of resource access is not possible for them as it is always enabled.

Resource allocations

Resource allocations view shows a table with all allocations that were assigned to the project by its community. Each allocation is specific to a site and a single resource offered by this site.

It is important to know that community assigned allocation needs to be acknowledged and installed by the site. In effect of this process, the site may decide to allocate less (or even more) resources than the community requested for the project. What is more site can allocate the resources in several portions, e.g. distributing a bigger allocation into several monthly or quarterly parts.

To see the resources which were actually assigned by the site, a row with community assigned allocation needs to be expanded. This is presented on the example below, where a single community allocation for 64 hours was assigned in two chunks, of 32 and 16 hours. It is possible that the TOPSITE will provide in future additional chunk, with remaining 16 hours.

Defining alarms

v2 limitation This functionality is not available yet.

Managing project administrators

FURMS project can have multiple administrators. Each project administrator can add (and remove) other administrators from the "Site administrators" view.

Project must have a single project leader defined. Typically this is one of the administrators but this is not strictly necessary.

REST API access credentials

To access FURMS REST API, administrator has to generate an API key (secret token) and use it together with its user identifier when authenticating against FURMS REST API endpoints.

The token can be generated in User Settings → API Key. The view also provides information about the fixed user identifier as well an option to revoke a previously generated token.

The user identifier and API key should be used with the HTTP Basic authorization scheme when accessing the REST API. For example using cURL:

curl [other params] -u USER_ID:API_KEY <FURMS_ENDPOINT_URL>

FURMS Command Line Interface (CLI)

FURMS ecosystem provides a command line executable, which can be used to conveniently access FURMS. The CLI application simplifies the use of the FURMS REST API, on which it is based.

FURMS CLI is designed in the first place for the Fenix and site level admins. It can be used as well by community and project admins.

Access credentials of the FURMS CLI are the same as the ones used for the REST API access and can be generated in the FURMS web UI under User Settings → API Key view.

Downloading

FURMS CLI releases are published on GitHub. Please navigate to:

https://github.com/unity-idm/furms/releases

and select the version of the CLI for download. Usually the latest release should be used.

Configuring the CLI

FURMS CLI can be run an a Linux AMD64 platform. There are no external dependencies, however it might be good to have an installation of Java Runtime Environment (of any recent version) in order to more quickly setup a truststore (see below).

To run FURMS CLI the following parameters have to be provided:

FURMS server URL
Access credentials: user is and API key
TLS/HTTPS truststore

The options can be set in number of ways, enumerated here in priority order:

Provided as a command line parameter
Provided as an environmental variable
Loaded from a configuration file

The following table lists all mandatory parameters:

Setting Config file property Env variable Command line Default value

Setting	Config file property	Env variable	Command line	Default value
FURMS URL	`url`	`FURMS_URL`	`--furms-url`	-
Username	`username`	`FURMS_USER`	`--user`	-
API key	`apikey`	`FURMS_APIKEY`	`--api-key`	-
Truststore path	`truststore`	`FURMS_TRUSTSTORE`	`--truststore`
Truststore type	`truststoreType`	`FURMS_TRUSTSTORE_TYPE`	`--truststore-type`	`JKS`
Truststore password	`truststorePass`	`FURMS_TRUSTSTORE_PASS`	`--truststore-pass`	`changeit`

FURMS URL

url

FURMS_URL

--furms-url

Username

username

FURMS_USER

--user

API key

apikey

FURMS_APIKEY

--api-key

Truststore path

truststore

FURMS_TRUSTSTORE

--truststore

Truststore type

truststoreType

FURMS_TRUSTSTORE_TYPE

--truststore-type

JKS

Truststore password

truststorePass

FURMS_TRUSTSTORE_PASS

--truststore-pass

changeit

Configuration file

Using the configuration file is typically a preferred way to configure the client. Configuration file location can be either set as a command line parameter --config-file or placed in the default location which is .furms.properties in user’s home directory.

Example configuration file contents:

apikey=12345678-b9b9-4444-5555-71123d000820
username=12345678-daaa-6666-7777-28324ec7ac88
url=https://furms.example.com

Configuring truststore

The most easy way to configure HTTPS (TLS) trusted certificates is to have an installation of JRE. It includes a truststore which will be automatically picked by FURMS CLI, if only $JAVA_HOME environment variable is properly pointing to the root of the JRE installation.

Otherwise a JKS or PKCS12 file needs to be created, including a CA certificate, which was used to issue a certificate of the FURMS server. In such case truststore needs to be configured with the three options shown in the table above.

Using the client

All CLI main commands are listed with the -h switch, e.g.:

[user001@examplebox]$ ./furms -h
Usage: furms [-hV] [COMMAND]
  -h, --help      Show this help message and exit.
  -V, --version   Print version information and exit.
Commands:
  community
  group
  project
  site

Each main command can have a subcommand (and sometimes even sub-sub command). In each case typing the -h switch after all commands provides contextual help:

[user001@examplebox]$ ./furms site policy list -h
Usage: furms site policy list [-dhsvV] [--api-key=<apiKey>]
                                     [--config-file=<configFile>]
                                     [--furms-url=<furmsurl>]
                                     [--truststore=<truststore>]
                                     [--truststore-pass=<truststorepass>]
                                     [--truststore-type=<truststoreType>]
                                     [--user=<username>] <siteId>
Retrieve site policies
[...]

Output of the operation is printed in JSON format.

Format of selected inputs

Creation of community allocation

Creation of community allocation requires its definition provided in JSON format. The syntax should be as follows:

{
  "name" : "My CLI Allocation",
  "creditId" : "fe1f2d62-4568-42da-809d-0a59f6bc6174",
  "amount" : 10
}

Example use:

furms community allocation create --file <PATH_TO_JSON_FILE> <COMMUNITY-ID>

Diagnostic messages

By default FURMS client prints command result in JSON, and can also print (rather rarely) some extra information prefixed with the [INFO] label.

What is more all FURMS CLI commands share several options:

-s, --silent will turn off any diagnostic output on the standard output. Only the results of operations are output in JSON format. Note that typically even without this option no extra messages are printed anyway; this option sets up the client not to print anything extra in any case.
-v, --verbose contrary to --silent will instruct the app to print more diagnostic data on standard output.
-d, --debug as above but even more diagnostic output can be printed.

End User support

Every user that signs into FURMS has access to her/his FURMS profile & settings view. For the users who have no additional roles, this is the only accessible view, others can activate it from the top-right view chooser.

User settings allows every FURMS user to check:

personal information which is exposed to FURMS by the Fenix infrastructure,
user’s sites and projects,
SSH keys management.

Sites

Sites view shows all sites to which access is granted. Note that if access to a site is granted through several projects, then multiple entries will show up, for each project.

Table shows the local user identifier at the site as well as the site-provided information on connection and other special access rules.

Projects

The projects view provides a list of all FURMS projects. By default only the projects where the user is a member are shown.

For each project of the user, it is possible to drill down and check available allocations in that project.

It is possible to apply for a membership in a project. In order to do so, first the filter to include "Remaining projects" must be selected. Then after locating a project of interest an access application can be submitted.

SSH keys management

The 'SSH Keys' view allows for managing public SSH keys across all sites to which access is granted via project membership.

FURMS allows to define separate keys per each site, or to share the same key across several sites. Multiple keys can be installed for each site.

Format of SSH key is the same as used in the authorized_keys file of SSH. See http://man.openbsd.org/sshd.8#AUTHORIZED_KEYS_FILE_FORMAT for more details.

Update of a key removes the old value from sites and then installs an updated one.

Some sites may require to set the 'from' option in the SSH key. Keys without that option can’t be added to sites requiring the 'from' option.

Policy documents

Sites providing resources may require acceptance of their policy document(s). Typically there is a single document per site, and sometimes there are additional documents per a site-offered service.

Typically the pending policy documents can be accepted from FURMS "User Settings" → "Policy Documents" view. Site may also require delivery of physical paper document with a hand signature. In such case FURMS will provide the necessary document with an ability to download it.

Note that lack of acceptance of the site’s policy document will prevent user account creation on the site.

In case when a previously accepted document is updated, a notification will be delivered asking for an acceptance of the updated version.

FURMS user manual

Sign in and sign up

Initial onboarding

Fenix federation management

Managing sites

Managing communities

Managing Fenix administrators

Distributing resources to communities

REST API access credentials

Site management

Site settings

Policy documents

Services

Resource types

Resource credits

Site agent connection and requests

Managing site administrators

REST API access credentials

Community management

Managing projects

Managing community administrators

Managing community metadata

Distributing resources to projects

Managing groups

REST API access credentials

Project management

Managing users

Project settings

Resource access

Resource allocations

Defining alarms

Managing project administrators

REST API access credentials

FURMS Command Line Interface (CLI)

Downloading

Configuring the CLI

Configuration file

Configuring truststore

Using the client

Format of selected inputs

Creation of community allocation

Diagnostic messages

End User support

Sites

Projects

SSH keys management

Policy documents