Only Perun admin is competent to work with facility in a full scope, but Facility manager is entitled to do following tasks:

Create facility

VO MANAGER role needed

Please log in into the Perun system and then go to the Facility manager section.

On the left panel please click on Facilities. Now you can see the list of the facilities you can manage.

Click on Create button in the top bar. Creating facility is at eight steps.

1. Create definition

Fill Name of facility and her definition in box Description. The description should be brief for what purpose the device was created.
- Facility can be created as a copy of another already created facility.
- Use Cancel button to cancel creating new facility.
- If you are satisfy with all the actions, click on Create button.

At this moment facility has been created.

2. Add managers

When creating facility, you will automatically become a facility manager.
- In this step you may add other managers.
- If you don‘t want to, click on Continue.

Click on Add button if you want to add another manager.
- Fill name of user and click on Search button. Pick required user by clicking on check-box and click on Add button up in bar.
- Click on Close button when you are finished with adding other managers.

If you want to remove the manager from required facility, mark manager and click on Remove button.
- By clicking on Continue button you get further.

3. Add owners

You may skip this step.

Click on Add button if you want to add owner.
- Pop up window of possible device owners will be shown.
- Pick required owner by clicking on check-box and click on Add button up in bar.
- Click on Close button will close pop up window.
If you want to delete the owner from the required facility, mark the owner and click Remove button.
- By clicking on Continue button you get further.

4. Add hosts

You may skip this step. Create a host if the facility is represented by a computer (physical or virtual).

Fill hostname at window in left one host per line and click Add button.
If you want to delete the hostname, mark the hostname and click Remove button.
Click on Continue button.

5. Select services

Select a set of services that will be managed by Perun throught this facility.
- Select a list of services using the check-box in the table, the left buttons group the services according to their purpose and click on them to select the set of services.
- Click on Continue button.

6. Configure services

Fill in the values of each field.
- Fill the attribute values for given services and click on Save to save the changes.
- Click on Continue button to go to the next step.

7. Configure service destinations

You can skip this step, but without setting destinations, Perun don‘t sent any configurations of services nowhere. We recommend setting destinations until you are satisfied with the facility and resource settings, destinations can be added at any time later.
Here you add destinations for service configuration delivery.
Select a destination type and enter value by type. Destination value can‘t be empty.
The most common type is a host that transmits the configuration using SSH to target facility. In the case of a host type, it is not necessary to list the host manually.
- You can use the Use names of all facility hosts check-box.
Service destination add by clicking Add button.
You can also remove service destinations by selecting check-box and click on Remove button.
- Click on Continue button.

8. Finish

Now your facility was created and configured.
- Continue by clicking on Create new resource button and create resource(s) for Vos.
- You can exit by click on Exit button.

Please note: You may edit every steps which you skipped. Use Back button to re-edit your adjustments.

Add owner

Every facility must have his owner to know what organization is responsible for its utilization. There are list of owners in the page of selected facility in GUI. Click Owners in left menu. Buttons Add and Remove serve to add new owners or remove the old ones.

Create a Resource

FACILITY MANAGER role needed

Resource is a part of facility that serves for particular VO. Only Facility manager is allowed to create and delete a resource. Facility manager can only see which resources are connected to facility by selecting particular facility and clicking on Resources in the left menu. In the same place can be resource created or deleted.

Here is created bond of services and resources, if you want to add a group to a resource you must be a VO manager.

Please log in into the Perun system and then go to the Facility manager section. On the left panel please click on Select facility. If you have not created a facility yet, follow the Create facility manual.

Use the filter window to locate the facility you created. Enter the facility name and search.
Click on the facility to select the facility you want. On the Resource tab, click the Create button.

Create resource

In the small window, select the VO for which source you want to create.
Fill Name and Description.
- Name - Please insert the desired resource name. Name of resource can be whatever, but you shall keep conventions in your VO.
- Description - Here you can insert your own resource description to specify its purpose.
Click on Create button or cancel by clicking on Cancel button

Create resource: Assign and configure services

Select service you want to assign from drop-down Selected service of all services.

Service settings will be shown in table below.

Check-box Show assigned to show you the services already assigned to the resource.

If you want to add the selected service, click on Add button.

The Remove button deletes the already created service.

You can save the changes with the Save button for the selected service.

The Fill button automatically fills the service field and the Remove button deletes the selected service settings.

If you finished all operations, click on Finish button to finished resource creating.

Assign service to Resource

Services serve to synchronize state of facility (in real world) with its state configured in the Perun system. Assigning service to resource, facility manager allows VO connected with resource to utilize this service. Services are assigned to each resource separately because not every services are required by every VO. Service must be set on facility first, then on the resource.

Tutorial how to assign services

Set attributes

It is essential to set all necessary attributes for proper utilization of facility. Attributes must be set in a good order. First attributes in the facility, then attributes in the resource. In addition, attributes in resources can be set only in scope of attributes in facility. Every service has required attributes that must be set for correct work of service.

Tutorial to set service attributes

Show destinations

Destinations are tightly connected with services. Only facility manager can assign services to destinations. Service destinations are available after clicking on button Service destinations in left menu of particular facility.

There are several types of Destinations:

host - data will be sent to the machine using SSH
url - data will be sent to the URL using POST
email - data will be sent in the body of email to the given address
semail - data will in the body of digitally signed email

How to monitor states of services

GUI: select facility and click on Propagation status in left menu. Detail of service is obtained by clicking on the line with service.
CLI: getTaskResultsForDestinations
Perl: $propagationStatsReaderAgent->getTaskResultsForDestinations(destinations => \@destinations)

All states of all facilities administered by you, you see by clicking All Facility states in the left menu.

Services from the facility manager's point

Introduction

Services are tools to keep real-life facilities synchronized with their settings in the Perun system. Most of the services are implemented by a set of scripts:

gen scripts serves to get data from the Perun and prepare configuration files for the service in expected format
send scripts serves to send data from Perun to their destinations (real-life facility)
slave scripts serves to process data on the facilities (eg. update local settings by the data from Perun).

Facility and VO manager make an arrangement for services that facility utilize and for structure and type of data. Especially slave scripts are important for facility admin.

Service propagation

By clicking on the Service propagation in the left menu, list of services and their propagation status is obtained. By button Force propagation, propagation of particular service is queued. Dependig on the lenght of queue, it may take several seconds to propagate your task.

Slave scripts instalation

In order to actually manage the services on facility, slave scripts needs to be installed. There are prepared DEB and RPM packages. Perun needs to be authorized to access the machine (usually using SSH key). All installed scripts are located in /opt/perun/bin/. For facilities which are installed by puppet modules, there is prepared module described at https://forge.puppetlabs.com/ceritsc/perun

How to install scripts to facility for RPM based systems

For RPM based systems (like RedHat Linux or CentOS) there is RPM repository https://homeproj.cesnet.cz/rpm/perunv3/

Create file /etc/yum.repos.d/perun.repo with the following content:

[Perun]
name=Perun IdM Slave Scripts
baseurl=https://homeproj.cesnet.cz/rpm/perunv3/stable/noarch/
enabled=1
gpgcheck=1
gpgkey=https://homeproj.cesnet.cz/rpm/perunv3/RPM-GPG-KEY-perunv3

and issue the following commands:

# loads list of available RPM packages
dnf makecache --repo Perun

# installs RPM with slave for [service-name]
dnf install perun-slave-process-[service-name]

You may want to check whether GPG key's fingerprint matches, dnf should present you this when importing the key:

Importing GPG key 0x287C5498:
 Userid     : "Perun RPM repository (Perun RPM repository) <perun@cesnet.cz>"
 Fingerprint: DBEB E257 4DCC 3666 92E1 416D 0979 577A 287C 5498
 From       : https://homeproj.cesnet.cz/rpm/perunv3/RPM-GPG-KEY-perunv3

You can install all slave script with this command:

# installs all RPMs for slave scripts 
dnf install perun-slave-full

How to install scripts to facility for DEB based systems

For Debian based systems use MetaCentrum DEB Repository https://repo.metacentrum.cz

Create /etc/apt/sources.list.d/meta_repo.list (if not already created) and put there the following:

deb https://repo.metacentrum.cz/ all main pilot
deb-src https://repo.metacentrum.cz/ all main pilot

DEB packages are signed. In order to verify their signature you must add following PGP key to the list of trusted keys.

Put the following PGP key A385CDB0 block into a temporary file, eg. /tmp/key

Then add key between trusted using following command

apt-key add /tmp/key

Install perun-slave-base package and then packages for the services you require, e.g. to support sshkeys service install perun-slave-process-sshkeys.

apt-get install perun-slave-base
# then for each service
apt-get install perun-slave-process-[service-name]

If you wish, you can install packages for all services using this meta-package: perun-slave-full.

apt-get install perun-slave-full

For MetaCentrum machines install perun-slave-meta-key package, which allows access from CESNET Perun instance. SSH key without using perun-slave-meta-key can be inserted manually: insert into /root/.ssh/authorizes_keys
- Also install perun-slave-metacentrum to get basic set of services for Metacentrum.

apt-get install perun-slave-meta-key perun-slave-metacentrum

New edits of slave scripts are made concerned matching versions of gen scripts. Version number contains 3 digits:

first is version of system Perun (now 3)
second is changed when gen script changed and new version of slave scripts is necessary to install
third is changed when gen script is changed, but slave script accept it

Configuration of services at target source

There is strong tendency to keep slave scripts same on all facilities, but sometimes facilities have specific requirements (e.g. settings of home directories, paths to scripts etc.). As a consequence, pre and post scripts were introduced. They differ on every facility and complement functionality of slave scripts. When slave script starts, it searchs for pre_ script in the service directory and runs it before its own functionality starts. The same process is after slave script execution, the post_ scripts are run.

All scripts are executed in the alphabetical order; therefore we recommend to name scripts according to pattern: pre_XX_name, where XX is number with two digits that specify order of script's execution. Pre and post scripts are created by facility managers. In addition, there is no need to create these scripts if facility manager is satisfied with default settings. Finally, there is a freedom in utilizing services thanks to customizable pre and post scripts.

Scripts pre and post are saved in /etc/perun/[service].d/ directory where ussually was saved some prototype of these scripts. If the directory does not exist it is necessary to create it.

Examples:

pre_01_set_custom_set_quota.storage-default for service fs_home:

QUOTA_ENABLED=1

pre_01_set_umask.sh.default for service fs_scratch:

UMASK=0555

post_15_nfsidmap_clear for services passwd, group, passwd_nfs4, group_nfs4:

/usr/sbin/nfsidmap -c

All slave scripts might be installed on the machine (facility). What slave scripts will actually run depends on the Perun instance performing provisioning (based on facility settings in Perun). But as a safequard, you can blacklist/whitelist specific services on the machine. As far as whitelisting is concerned, no other service with an exception of the whitelisted ones will be executed. As for blacklisting, all services will be executed except of the blacklisted one.

Example of blacklisting /etc/perunv3.conf:

 SERVICE_BLACKLIST[0]=fs_scratch
 SERVICE_BLACKLIST[1]=fs_home

Example of whitelisting /etc/perunv3.conf:

 SERVICE_WHITELIST[0]=passwd
 SERVICE_WHITELIST[1]=group

Pushed synchronous propagation

When installation is complete, it is necessary to propagate services. Command remctl is available in package remctl-client in distributions.

 remctl perun.ics.muni.cz perun propagate

Propagate all services defined in the machine.

Facility managers's manual

Obsah

Create facility

1. Create definition

2. Add managers

3. Add owners

4. Add hosts

5. Select services

6. Configure services

7. Configure service destinations

8. Finish

Add owner

Create a Resource

Create resource

Create resource: Assign and configure services

Assign service to Resource

Set attributes

Show destinations

How to monitor states of services

Services from the facility manager's point

Introduction

Service propagation

Slave scripts instalation

How to install scripts to facility for RPM based systems

How to install scripts to facility for DEB based systems

Configuration of services at target source

Pushed synchronous propagation

Navigační menu

Facility managers's manual

Create facility

1. Create definition

2. Add managers

3. Add owners

4. Add hosts

5. Select services

6. Configure services

7. Configure service destinations

8. Finish

Add owner

Create a Resource

Create resource

Create resource: Assign and configure services

Assign service to Resource

Set attributes

Show destinations

How to monitor states of services

Services from the facility manager's point

Introduction

Service propagation

Slave scripts instalation

How to install scripts to facility for RPM based systems

How to install scripts to facility for DEB based systems

Configuration of services at target source

Pushed synchronous propagation

Navigační menu

Hledat