1. Basic Tutorial setup

1.1. Tutorial goal

The aim of the tutorial is to have a self contained DIRAC setup. You will be guided through the whole installation process both of the server part and the client part. By the end of the tutorial, you will have:

  • a Configuration service, to serve other servers and clients
  • a ComponentMonitoring service to keep track of other services and agents installed
  • a SystemAdministrator service to manage the DIRAC installation in the future
  • the WebApp, to allow for web interface access

The setup you will have at the end is the base for all the other tutorials.

1.3. Basic requirements

This section is to be executed as root user.

We assume that you have at your disposition a fresh CC7 64bit installation. If you don’t, we recommend installing a virtual machine. Instructions for installing CC7 can be found here

In this tutorial, we will use a freshly installed CC7 x86_64 virtual machine, with all the default options, except the hostname being dirac-tuto.

Make sure that the hostname of the machine is set to dirac-tuto. Modify the HOSTNAME variable in the /etc/sysconfig/network file as such:

HOSTNAME=dirac-tuto

Then reboot the machine and check the hostname. You should get the following output:

[[email protected] ~]# hostname
dirac-tuto

1.4. Machine setup

This section is to be executed as root user.

Make sure that the machine can address itself using the dirac-tuto alias. Modify the /etc/hosts file as such:

127.0.0.1   localhost localhost.localdomain localhost4 localhost4.localdomain4 dirac-tuto
::1         localhost localhost.localdomain localhost6 localhost6.localdomain6 dirac-tuto

1.4.1. Create the dirac user

The user that will run the server will be dirac. Set the password for that user to password, and ensure that files below /opt/dirac/ belong to this user:

adduser -s /bin/bash -d /home/dirac dirac || echo "User dirac already exists."
echo password | /usr/bin/passwd --stdin dirac
mkdir -p /opt/dirac/sbin
chown -R dirac:dirac /opt/dirac/

1.4.2. Install runit

The next step is to install runit, which is responsible for supervising DIRAC processes

First, install the RPM:

yum localinstall -y http://diracproject.web.cern.ch/diracproject/rpm/runit-2.1.2-1.el7.cern.x86_64.rpm

Create the file /opt/dirac/sbin/runsvdir-start, which is responsible for starting runit, with the following content:

/opt/dirac/sbin/runsvdir-start
cd /opt/dirac
RUNSVCTRL='/sbin/runsvctrl'
chpst -u dirac $RUNSVCTRL d /opt/dirac/startup/*
killall runsv svlogd
RUNSVDIR='/sbin/runsvdir'
exec chpst -u dirac $RUNSVDIR -P /opt/dirac/startup 'log:  DIRAC runsv'

Then, edit the systemd runsvdir-start service to match the following:

/usr/lib/systemd/systemd/runsvdir-start.service
[Unit]
Description=Runit Process Supervisor

[Service]
ExecStart=/opt/dirac/sbin/runsvdir-start
Restart=always
KillMode=process

[Install]
WantedBy=multi-user.target

make runsvdir-start executable and (re)start runsvdir:

chown dirac:dirac /opt/dirac/sbin/runsvdir-start
chmod +x /opt/dirac/sbin/runsvdir-start
systemctl daemon-reload
systemctl start runsvdir-start

1.4.3. Install MySQL

First of all, remove the existing (outdated) installation, and install all the necessary RPMs for MySQL 5.7:

yum remove -y $(rpm -qa | grep -i -e mysql -e mariadb | paste -sd ' ') || echo  "MySQL is not yet installed"
rm -rf /var/lib/mysql/*
yum install -y \
    https://dev.mysql.com/get/Downloads/MySQL-5.7/mysql-community-devel-5.7.25-1.el7.x86_64.rpm \
    https://dev.mysql.com/get/Downloads/MySQL-5.7/mysql-community-server-5.7.25-1.el7.x86_64.rpm \
    https://dev.mysql.com/get/Downloads/MySQL-5.7/mysql-community-client-5.7.25-1.el7.x86_64.rpm \
    https://dev.mysql.com/get/Downloads/MySQL-5.7/mysql-community-libs-5.7.25-1.el7.x86_64.rpm \
    https://dev.mysql.com/get/Downloads/MySQL-5.7/mysql-community-common-5.7.25-1.el7.x86_64.rpm

Start the mysql service, which will then initialize itself, and, among other things, create temporary password for the mysql root account, which needs to be changed during the first login:

systemctl start mysqld || systemctl restart mysqld

To change the root password, create a mysqlSetup.sql file, which changes the password to a strong password, removes a plugin to enforce the strong password (only for tutorial purposes, of course), and then sets the password to password, which is easier to remember:

mysqlSetup.sql
ALTER USER 'root'@'localhost' IDENTIFIED BY '[email protected]';
FLUSH PRIVILEGES;
uninstall plugin validate_password;
ALTER USER 'root'@'localhost' IDENTIFIED BY 'password';
FLUSH PRIVILEGES;
quit

Now get the temporary password from the /var/log/mysqld.log, and change it using the mysqlSetup.sql file:

MY_PW=`grep "temporary password" /var/log/mysqld.log | tail -n1 | sed "s/.* //"`
mysql -u root --password=${MY_PW} --connect-expired-password < mysqlSetup.sql

1.5. Server installation

This section is to be executed as dirac user

1.5.1. CA and certificate

DIRAC relies on TLS for securing its connections and for authorization and authentication. Since we are using a self contained installation, we will be using our own CA. There are a bunch of utilities that we will be using to generate the necessary files.

We create a script setupCA to download utilities from the DIRAC repository and source utilities.sh, and then create the CA and certificates both for the server and the client:

setupCA
mkdir -p ~/caUtilities/ && cd ~/caUtilities/
curl -O -L https://raw.githubusercontent.com/DIRACGrid/DIRAC/integration/tests/Jenkins/utilities.sh
curl -O -L https://raw.githubusercontent.com/DIRACGrid/DIRAC/integration/tests/Jenkins/config/ci/openssl_config_ca.cnf
curl -O -L https://raw.githubusercontent.com/DIRACGrid/DIRAC/integration/tests/Jenkins/config/ci/openssl_config_host.cnf
curl -O -L https://raw.githubusercontent.com/DIRACGrid/DIRAC/integration/tests/Jenkins/config/ci/openssl_config_user.cnf
export SERVERINSTALLDIR=/opt/dirac
export CI_CONFIG=~/caUtilities/
source utilities.sh
generateCA
generateCertificates 365
generateUserCredentials 365

Execute the script:

bash setupCA

At this point, you should find:

  • The CA in /opt/dirac/etc/grid-security/certificates:

    [[email protected] caUtilities]$ ls /opt/dirac/etc/grid-security/certificates/
    855f710d.0  ca.cert.pem
    
  • The host certificate (hostcert.pem) and key (hostkey.pem) in /opt/dirac/etc/grid-security:

    [[email protected] caUtilities]$ ls /opt/dirac/etc/grid-security/
    ca  certificates  hostcert.pem  hostkey.pem  openssl_config_host.cnf  request.csr.pem
    
  • The user credentials for later in /opt/dirac/user/:

    [[email protected] caUtilities]$ ls /opt/dirac/user/
    client.key  client.pem  client.req  openssl_config_user.cnf
    

1.5.2. Install DIRAC Server

This section is to be run as dirac user in its home folder:

sudo su dirac
cd ~

We will install DIRAC v6r21 with DIRACOS.

First we create the install.cfg file, which is used to tell the installation script we obtain in a moment what to install and how to configure the server with the following content:

install.cfg
LocalInstallation
{
  #  DIRAC release version to install
  Release = v6r21p5
  #  Installation type
  InstallType = server
  #  Each DIRAC update will be installed in a separate directory, not overriding the previous ones
  UseVersionsDir = yes
  #  The directory of the DIRAC software installation
  TargetPath = /opt/dirac
  #  Install the WebApp extension
  Extensions = WebApp

  # Name of the VO we will use
  VirtualOrganization = tutoVO
  # Name of the site or host
  SiteName = dirac-tuto
  # Setup name
  Setup = MyDIRAC-Production
  #  Default name of system instances
  InstanceName = Production
  #  Flag to skip download of CAs
  SkipCADownload = yes
  #  Flag to use the server certificates
  UseServerCertificate = yes

  # Name of the Admin user (from the user certificate we created )
  AdminUserName = ciuser
  # DN of the Admin user certificate (from the user certificate we created)
  AdminUserDN = /C=ch/O=DIRAC/OU=DIRAC CI/CN=ciuser/emailAddress=[email protected]
  AdminUserEmail= [email protected]
  # Name of the Admin group
  AdminGroupName = dirac_admin

  # DN of the host certificate (from the host certificate we created)
  HostDN = /C=ch/O=DIRAC/OU=DIRAC CI/CN=dirac-tuto/emailAddress=[email protected]
  # Define the Configuration Server as Master
  ConfigurationMaster = yes

  # List of DataBases to be installed (what's here is a list for a basic installation)
  Databases = InstalledComponentsDB
  Databases += ResourceStatusDB

  #  List of Services to be installed (what's here is a list for a basic installation)
  Services  = Configuration/Server
  Services += Framework/ComponentMonitoring
  Services += Framework/SystemAdministrator
  #  Flag determining whether the Web Portal will be installed
  WebPortal = yes
  WebApp = yes

  Database
  {
    #  User name used to connect the DB server
    User = Dirac
    #  Password for database user access
    Password = Dirac
    #  Password for root DB user
    RootPwd = password
    #  location of DB server
    Host = localhost
  }
}

Then we download the installer, make it executable, and run it with the install.cfg file (assuming the file is in the user’s home folder):

mkdir -p ~/DiracInstallation && cd ~/DiracInstallation
curl -O -L https://github.com/DIRACGrid/DIRAC/raw/integration/Core/scripts/install_site.sh
chmod +x install_site.sh
cp ../install.cfg .
./install_site.sh --dirac-os install.cfg

The output should look something like this:

--2019-04-11 08:51:21--  https://github.com/DIRACGrid/DIRAC/raw/integration/Core/scripts/dirac-install.py
Resolving github.com... 140.82.118.4, 140.82.118.3
Connecting to github.com|140.82.118.4|:443... connected.
HTTP request sent, awaiting response... 302 Found

[...]

Status of installed components:

  Name                          Runit Uptime PID
=================================================
1 Web_WebApp                    Run        4 24338
2 Configuration_Server          Run       53 24142
3 Framework_ComponentMonitoring Run       36 24207
4 Framework_SystemAdministrator Run       20 24247

You can verify that the components are running:

[[email protected] DIRAC]$ runsvstat /opt/dirac/startup/*
/opt/dirac/startup/Configuration_Server: run (pid 24142) 288 seconds
/opt/dirac/startup/Framework_ComponentMonitoring: run (pid 24207) 271 seconds
/opt/dirac/startup/Framework_SystemAdministrator: run (pid 24247) 255 seconds
/opt/dirac/startup/Web_WebApp: run (pid 24338) 239 seconds

The logs are to be found in /opt/dirac/runit/, grouped by component.

The installation created the file /opt/dirac/etc/dirac.cfg. The content is the same as the install.cfg, with the addition of the following:

DIRAC
{
  Setup = MyDIRAC-Production
  VirtualOrganization = tutoVO
  Extensions = WebApp
  Security
  {
  }
  Setups
  {
    MyDIRAC-Production
    {
      Configuration = Production
      Framework = Production
    }
  }
  Configuration
  {
    Master = yes
    Name = MyDIRAC-Production
    Servers = dips://dirac-tuto:9135/Configuration/Server
  }
}
LocalSite
{
  Site = dirac-tuto
}
Systems
{
  Databases
  {
    User = Dirac
    Password = Dirac
    Host = localhost
    Port = 3306
  }
  NoSQLDatabases
  {
    Host = dirac-tuto
    Port = 9200
  }
}

This part is used as configuration for all your services and agents that you will run. It contains two important information:

  • The database credentials
  • The address of the configuration server: Servers = dips://dirac-tuto:9135/Configuration/Server

The Configuration service will serve the content of the file /opt/dirac/etc/MyDIRAC-Production.cfg to every client, be it a service, an agent, a job, or an interactive client. The content looks like such:

DIRAC
{
  Extensions = WebApp
  VirtualOrganization = tutoVO
  Configuration
  {
    Name = MyDIRAC-Production
    Version = 2019-04-11 06:52:18.414086
    MasterServer = dips://dirac-tuto:9135/Configuration/Server
  }
  Setups
  {
    MyDIRAC-Production
    {
      Configuration = Production
      Framework = Production
    }
  }
}
Registry
{
  Users
  {
    ciuser
    {
      DN = /C=ch/O=DIRAC/OU=DIRAC CI/CN=ciuser/[email protected]
      Email = [email protected]
    }
  }
  Groups
  {
    dirac_user
    {
      Users = ciuser
      Properties = NormalUser
    }
    dirac_admin
    {
      Users = ciuser
      Properties = AlarmsManagement
      Properties += ServiceAdministrator
      Properties += CSAdministrator
      Properties += JobAdministrator
      Properties += FullDelegation
      Properties += ProxyManagement
      Properties += Operator
    }
  }
  Hosts
  {
    dirac-tuto
    {
      DN = /C=ch/O=DIRAC/OU=DIRAC CI/CN=dirac-tuto/[email protected]
      Properties = TrustedHost
      Properties += CSAdministrator
      Properties += JobAdministrator
      Properties += FullDelegation
      Properties += ProxyManagement
      Properties += Operator
    }
  }
  DefaultGroup = dirac_user
}
Operations
{
  Defaults
  {
    EMail
    {
      Production = [email protected]
      Logging = [email protected]
    }
  }
}
WebApp
{
  Access
  {
    upload = TrustedHost
  }
}
Systems
{
  Framework
  {
    Production
    {
      Services
      {
        ComponentMonitoring
        {
          Port = 9190
          Authorization
          {
            Default = ServiceAdministrator
            componentExists = authenticated
            getComponents = authenticated
            hostExists = authenticated
            getHosts = authenticated
            installationExists = authenticated
            getInstallations = authenticated
            updateLog = Operator
          }
        }
        SystemAdministrator
        {
          Port = 9162
          Authorization
          {
            Default = ServiceAdministrator
            storeHostInfo = Operator
          }
        }
      }
      URLs
      {
        ComponentMonitoring = dips://dirac-tuto:9190/Framework/ComponentMonitoring
        SystemAdministrator = dips://dirac-tuto:9162/Framework/SystemAdministrator
      }
      FailoverURLs
      {
      }
      Databases
      {
        InstalledComponentsDB
        {
          DBName = InstalledComponentsDB
          Host = localhost
          Port = 3306
        }
      }
    }
  }
}

This configuration will be used for example by Services in order to:

  • know their configuration (for example the ComponentMonitoring Service will use everything under Systems/Framework/Production/Services/ComponentMonitoring )
  • Identify host and persons (Registry section)

Or by clients to get the URLs of given services (for example ComponentMonitoring = dips://dirac-tuto:9190/Framework/ComponentMonitoring)

Since this configuration is given as a whole to every client, you understand why no database credentials are in this file. Services and Agents running on the machine will have their configuration as a merge of what is served by the Configuration service and the /opt/dirac/etc/dirac.cfg, and thus have access to these private information.

The file /opt/dirac/bashrc is to be sourced whenever you want to use the server installation.

1.6. Client installation

Now we will create another linux account diracuser and another installation to be used as client

1.6.1. Setup client session

This section has to be ran as root

Create an account diracuser with password password, and add in its ~/.globus/ directory the user certificate you created earlier:

adduser -s /bin/bash -d /home/diracuser diracuser || echo "User diracuser already exists."
echo password | /usr/bin/passwd --stdin diracuser
mkdir -p ~diracuser/.globus/
cp /opt/dirac/user/client.pem ~diracuser/.globus/usercert.pem
cp /opt/dirac/user/client.key ~diracuser/.globus/userkey.pem
chown -R diracuser:diracuser ~diracuser/.globus/

1.6.2. Install DIRAC client

This section has to be ran as diracuser in its home directory:

sudo su diracuser
cd

We will do the installation in the ~/DiracInstallation directory. For a client, the configuration is really minimal, so we will just install the code and its dependencies. Create the structure, download the installer, and then install the same version as for the server:

mkdir -p ~/DiracInstallation && cd ~/DiracInstallation
curl -O -L https://github.com/DIRACGrid/DIRAC/raw/integration/Core/scripts/dirac-install.py
chmod +x dirac-install.py
./dirac-install.py -r v6r21p5 --dirac-os

The output from the dirac-install.py command should look something like this:

<SomeDate> dirac-install [NOTICE]  Processing installation requirements
<SomeDate> dirac-install [NOTICE]  Destination path for installation is /home/diracuser/DIRAC
<SomeDate> dirac-install [NOTICE]  Discovering modules to install
<SomeDate> dirac-install [NOTICE]  Installing modules...
<SomeDate> dirac-install [NOTICE]  Installing DIRAC:v6r21
<SomeDate> dirac-install [NOTICE]  Retrieving http://diracproject.web.cern.ch/diracproject/tars/DIRAC-v6r21.tar.gz
<SomeDate> dirac-install [NOTICE]  Retrieving http://diracproject.web.cern.ch/diracproject/tars/DIRAC-v6r21.md5
<SomeDate> dirac-install [NOTICE]  Deploying scripts...
           Scripts will be deployed at /home/diracuser/DIRAC/scripts
           Inspecting DIRAC module
<SomeDate> dirac-install [NOTICE]  Installing DIRAC OS ...
<SomeDate> dirac-install [NOTICE]  Retrieving https://diracos.web.cern.ch/diracos/releases/diracos-1.0.0.tar.gz ...........................................................................................................................
<SomeDate> dirac-install [NOTICE]  Retrieving https://diracos.web.cern.ch/diracos/releases/diracos-1.0.0.md5
<SomeDate> dirac-install [NOTICE]  Fixing externals paths...
<SomeDate> dirac-install [NOTICE]  Running externals post install...
<SomeDate> dirac-install [NOTICE]  Creating /home/diracuser/DIRAC/bashrc
<SomeDate> dirac-install [NOTICE]  Defaults written to defaults-DIRAC.cfg
<SomeDate> dirac-install [NOTICE]  Executing /home/diracuser/DIRAC/scripts/dirac-externals-requirements...
<SomeDate> dirac-install [NOTICE]  DIRAC properly installed

You will notice that among other things, the installation created a ~/DiracInstallation/bashrc file. This file must be sourced whenever you want to use dirac client.

In principle, your system administrator will have managed the CA for you. In this specific case, since we have our own CA, we will just link the client installation CA with the server one:

mkdir -p ~/DiracInstallation/etc/grid-security/
ln -fs /opt/dirac/etc/grid-security/certificates/ ~/DiracInstallation/etc/grid-security/certificates

The last step is to configure the client to talk to the proper configuration service. This is easily done by creating a ~/DiracInstallation/etc/dirac.cfg file with the following content:

~/DiracInstallation/etc/dirac.cfg
DIRAC
{
  Setup = MyDIRAC-Production
  Configuration
  {
    Servers = dips://dirac-tuto:9135/Configuration/Server
  }
}

You should now be able to get a proxy:

[[email protected] DIRAC]$ source ~/DiracInstallation/bashrc
[diracus[email protected] DIRAC]$ dirac-proxy-init
Generating proxy...
Proxy generated:
subject      : /C=ch/O=DIRAC/OU=DIRAC CI/CN=ciuser/[email protected]/CN=460648814
issuer       : /C=ch/O=DIRAC/OU=DIRAC CI/CN=ciuser/[email protected]
identity     : /C=ch/O=DIRAC/OU=DIRAC CI/CN=ciuser/[email protected]
timeleft     : 23:59:59
DIRAC group  : dirac_user
rfc          : True
path         : /tmp/x509up_u501
username     : ciuser
properties   : NormalUser

And you can observe that the Configuration Service has served the client:

[[email protected] DIRAC]$ grep ciuser /opt/dirac/runit/Configuration/Server/log/current
2019-04-11 14:54:10 UTC Configuration/Server NOTICE: Executing action ([::1]:33394)[dirac_user:ciuser] RPC/getCompressedDataIfNewer(<masked>)
2019-04-11 14:54:10 UTC Configuration/Server NOTICE: Returning response ([::1]:33394)[dirac_user:ciuser] (0.00 secs) OK

1.6.3. Use the WebApp

This section is to be executed as diracuser.

First you need to convert your user certificate into a p12 format (you will be prompt for a password, you can leave it empty):

cd ~/.globus/
openssl pkcs12 -export -out certificate.p12 -inkey userkey.pem -in usercert.pem

This will create the file ~/.globus/certificate.p12.

Use your favorite browser, and add this certificate.

You should be able to access the WebApp using the following address https://localhost:8443/DIRAC/

1.7. Conclusion

We have seen how to install a DIRAC server and client using a personal CA, and how to access the WebApp. Starting from here, you will be able to extend on further tutorials.