Quickstart ARC: towards distributed computing in a few minutes - token edition

Scared of distributed computing complexities?

With ARC7 you can setup a Computing Element and try common distributed computing workflows in just a few minutes!

ARC7 comes with so-called zero configuration included and works out of the box without any manual configuration. It has a pre-installed x509 host certificate signed by a Test-CA.

If you want to test your ARC-CE with token submission there are two extra steps that need to be performed in order to set up a Test JWT issuer and allow the client (remote client or on the ARC-CE itself) to trust tokens from this issuer.

If you want to test job submission on a remote ARC client, the client must trust the ARC-CE host certificate which is issued by the Test-CA, and you must therefore apply the extra step for both the token and the x509 user case. These are described in Step 5c or Step 5b respectively.

You can try ARC by using the legacy x509 user certificate, or with the newer Jason Web Token capability. The procedure below splits into x509 versus token at Step 5. The two require slightly different configuration options on the ARC server, and different procedures to aquire the authentication document (certificate or token).

The ARC server can be set up to accept both user x509 certificates and user tokens in paralell, or just one of the two. This is up to you.

Note

The zero configured A-REX comes with the REST interface enabled. It runs on port 443, so make sure it is not firewalled if you want to submit jobs from a remote client host.

Step 1. Enable NorduGrid ARC7 repos

Prepare your system to install via the NorduGrid Repositories.

Note

Alpha and release-candidate packages are in testing repository, so please make sure it is enabled, e.g. on RHEL-based systems you can use dnf --enablerepo=nordugrid-testing to enable it for one transaction or dnf config-manager --enable nordugrid-testing to enable permanently.

If you want to test ARC7 including all latest developments, set up your repository to include the nightly builds following Using ARC packages from nightly builds instructions.

Step 2. Install required Packages

RHEL flavour

The NorduGrid repositories for RedHat Enterprise Linux/CentOS depends on the EPEL, in addition powertools (rhel8) or crb (rhel9) repositories must be enabled:

For RHEL8 flavour:

dnf install -y epel-release
dnf config-manager --set-enabled powertools

For RHEL9 flavour:

dnf install -y epel-release
dnf config-manager --set-enabled crb

Debian flavour

apt-get update

Step 3. Install A-REX

ARC Resource-coupled EXecution service (A-REX) is a core component that manages authentication, authorization and job life cycle. It is enough to have A-REX installed to have a minimal computing element:

[root ~]# dnf -y install nordugrid-arc-arex

Step 4. Run A-REX

To start ARC services just run:

[root ~]# arcctl service start --as-configured

You can check if A-REX is running with:

[root ~]# arcctl service list
arc-arex                         (Installed, Disabled, Running)
arc-arex-ws                      (Installed, Disabled, Running)
arc-datadelivery-service         (Not installed, Disabled, Stopped)
arc-infosys-ldap                 (Not installed, Disabled, Stopped)

Note

arcctl tool automates many ARC CE operations and is designed with bash-completion in mind. If you would like to use ARC in production it is advised to have completion enabled:

[root ~]# dnf install -y bash-completion python-argcomplete
[root ~]# activate-global-python-argcomplete

Step 5. Install the ARC client

Install ARC client tools on the client host

Note

In the zero-conf setup - we install the client on the same server as the ARC-CE, so client and host is the same machine. Typically you would install the client on another machine.

[root ~]# dnf -y install nordugrid-arc-client

Step 6. Set up test jwt token issuer and trust

Note

All Steps 6 are only necessary for the zero-conf test-setup case, and not in the production setup.

• If your ARC client and A-REX server are the same machine: do Steps 6a and 6b only.

• If your ARC client and A-REX server are different machines: do also Step 6c.

Note

Quick-start if your ARC client and A-REX server is the same machine - and you want to skip explanations, the following command compreses Step 6a and 6b in one go.

sudo $(arcctl test-jwt init --force | tail -n 1)

You now go to Step 7.

Step 6a. Set up a test jwt token issuer on the ARC client

For the zero-conf setup we will use ARC’s inbuilt test-token issuer to submit a token. This is run on the ARC client machine. In our case this is the same machine as the ARC-CE server, but it can equally well be a remote ARC client.

[user ~] arcctl test-jwt init

This will output an arcctl deploy command that needs to be issued on the ARC-CE server. Copy this to your clipboard.

Example output from arcctl test-jwt init:

Issuer URL: https://arc.example.org/arc/testjwt/8b7baf79
JWKS:
{
  "keys": [
    {
      "e": "AQAB",
      "kid": "testjwt",
      "kty": "RSA",
      "n": "r0nMfmRfhJFiyCPRUc8m9K7yl0qksmIRIQeiMNEi3_Und6WVNhLpERrzwb6jTHu5wr_Tk408ve-ig1udpqEZ5PUcV6K25MohYu1b6ifrYDo6go-bQ0cEaEyZRYGm1scOUb_gWCAYOLe-hv7hZGnQ3rojLZ2BJwUwBVOj5Hp_ROPUdbifKfNkBiujhGPJAegrPrKgsskQNA2GkXWACeS85WPKIQ54bkUiASsmz3_b0Ik9jQaQnHsU0znM3G-EpjnLB-1PS7FC1tIMaXcJ2BJZuFfkDyIv1Ymn8vKf9WeQjQ80L08k78pzTGOerZLcc5BQ2ZWEUhADWRWzkqHmEDymIw",
      "use": "sig"
    }
  ]
}


Run the following command on the ARC CE to trust the Test JWT issuer:
arcctl deploy jwt-issuer --deploy-conf test-jwt://H4sIAOzQRGYC/73T3XKiMBQA4HfheqmgRbB3qFTxF7CUys4OAyFIiCQ0CTLY8d03brezT9C9yjlJznwnmeRDqaFI81SkytOHgjhvIVOelFKIhj8NBikDAnKhqQQiMHxU+blltQrPE1WumCqA+gOAjKj3TQ8touBM2/yB0Hvh4D5ZdWJgZWaWFuZE+aEIiiFJIMkbioj4Lmjwh5FcyyFDpKDfL35JEpUMo7yBQCD6H876j5N22oqSMnRN/4/9xUFJVx3mScvQt2F3QLl9QvfHimEvx58fCpSk7dtT2QRGuUz+lt5z0cs8ONgyJjJiGtkWdVCUq2fUz7wgBFY9WZv9WXvHvHYD14dou3PQKAlJPo5ed+WmcQJ27bJx9bJsjY4lL/hRsy5QRSe9zZt3Jza8ELyO10NjS8tjq2djVLDjnI5PVM18DTip08fBcVHrHOzDLDlFM/u430C1vJhlvCD+iNFqEw+nqy7spq/7ylg2SbD3wjxDxbrY4Slqq3LhrWx4Yh5bnzjH/s4eLvBbZM/gwTIib+36xmOGQ2QfeH0dJZnm4knlpz5Z8lC7ku1ooTpNRTZTVfcO5vNMF+42fQMrqcbtc4HnvXvRjzWxLutiEkG/8i1to1nYtJrry2IPWbwBwJj6wzhywtKeR0F0xe/L2pn3tdt9/jR5vRydlNuv2+03J4GqklYEAAA=

Step 6b. On the A-REX server - setup trust of the client’s Test JWT issuer

Run the arcctl deploy jwt-issuer command from Step 6a on the A-REX server.

Example:

[root ~]# arcctl deploy jwt-issuer --deploy-conf test-jwt://H4sIAOzQRGYC/73T3XKiMBQA4HfheqmgRbB3qFTxF7CUys4OAyFIiCQ0CTLY8d03brezT9C9yjlJznwnmeRDqaFI81SkytOHgjhvIVOelFKIhj8NBikDAnKhqQQiMHxU+blltQrPE1WumCqA+gOAjKj3TQ8touBM2/yB0Hvh4D5ZdWJgZWaWFuZE+aEIiiFJIMkbioj4Lmjwh5FcyyFDpKDfL35JEpUMo7yBQCD6H876j5N22oqSMnRN/4/9xUFJVx3mScvQt2F3QLl9QvfHimEvx58fCpSk7dtT2QRGuUz+lt5z0cs8ONgyJjJiGtkWdVCUq2fUz7wgBFY9WZv9WXvHvHYD14dou3PQKAlJPo5ed+WmcQJ27bJx9bJsjY4lL/hRsy5QRSe9zZt3Jza8ELyO10NjS8tjq2djVLDjnI5PVM18DTip08fBcVHrHOzDLDlFM/u430C1vJhlvCD+iNFqEw+nqy7spq/7ylg2SbD3wjxDxbrY4Slqq3LhrWx4Yh5bnzjH/s4eLvBbZM/gwTIib+36xmOGQ2QfeH0dJZnm4knlpz5Z8lC7ku1ooTpNRTZTVfcO5vNMF+42fQMrqcbtc4HnvXvRjzWxLutiEkG/8i1to1nYtJrry2IPWbwBwJj6wzhywtKeR0F0xe/L2pn3tdt9/jR5vRydlNuv2+03J4GqklYEAAA=
ARC CE now trust JWT signatures of https://arc.example.org/arc/testjwt/8b7baf79 issuer.

Auth configuration for issuer tokens has been written to /etc/arc.conf.d/10-jwt-a7374e17.conf
ARC restart is needed to apply configuration.

This command does two things

1. creates a tokenissuers folder in your control directory

   Our control directory now contains a folder tokenissuers/a7374e17 where the issuer url, key and metadata is stored:

[root ~]# ls /var/spool/arc/jobstatus/tokenissuers/a7374e17
issuer    keys      metadata

2. automatically sets up the arc configuration token authentication for tokens issued by this test-jwt issuer.

The token authentication file 10-jwt-a7374e17.conf produced by the arcctl deploy jwt-issuer command looks like this in our example:

[root ~]# cat /etc/arc.conf.d/10-jwt-a7374e17.conf
[authgroup:testjwt-a7374e17]
authtokens = * https://arc.example.org/arc/testjwt/8b7baf79 arc * *

[mapping]
map_to_user = testjwt-a7374e17 nobody:nobody

[arex/ws/jobs]
allowaccess = testjwt-a7374e17

Here we see that a separate authgroup has been automatically created for tokens issued by this test-jwt issuer. Mapping of this authgroup is done to the nobody user (which is the only user we assume for zero-conf), and access is enabled for job submission by jobs issued with a token from this test-jwt issuer.

Note

When you set up your production ready service later on, you will remove the test-jwt authgroup and add your real token issuers as per [authgroup] authokens section.

Step 6a+6b

If your ARC-CE and ARC client are the same machine - below is a compressed command that does both steps 6a and 6b in one go.

sudo $(arcctl test-jwt init --force | tail -n 1)

Step 6c. For a remote client: Setup trust of the A-REX server

Note

If you are submitting jobs from the ARC-CE itself (as we assume in this zero-conf setup) and not a remote client - you can skip this step.

With the zero-conf setup A-REX is pre-installed with a host certificate issued by the Test-CA. A remote client will need to trust this Test-CA, and therefore the following steps are needed.

On the A-REX host print out the Test-CA certificate:

[user@arc-ce]  arcctl test-ca info -o ca-cert
-----BEGIN CERTIFICATE-----
MIIFyTCCA7GgAwIBAgIUeLkSbksS9r3raPvkT2rR0ep06X8wDQYJKoZIhvcNAQEM
BQAwdDETMBEGCgmSJomT8ixkARkWA29yZzEZMBcGCgmSJomT8ixkARkWCW5vcmR1
<output omitted>
TJ9f0I8ktHACLvLvJE9SIDWs2zPo8o4cmvLBAtxe+jaijn22THtpLLUSXt1ozexS
ZHGFtsUBuIoNzXoRXxJwkGBA1ZpLBbOpjyp6PzNcTPYFG51+EHTUMPkbfyQ5
-----END CERTIFICATE-----

Copy this output to your clipboard, and then on the ARC client machine do:

[root@client ~]# arcctl deploy ca-cert
[2024-10-25 21:40:50,328] [ARCCTL.ThirdParty.Deploy] [INFO] [726706] [Reading CA Certificate PEM data from stdin]
-----BEGIN CERTIFICATE-----
MIIFyTCCA7GgAwIBAgIUeLkSbksS9r3raPvkT2rR0ep06X8wDQYJKoZIhvcNAQEM
BQAwdDETMBEGCgmSJomT8ixkARkWA29yZzEZMBcGCgmSJomT8ixkARkWCW5vcmR1
<output omitted>
TJ9f0I8ktHACLvLvJE9SIDWs2zPo8o4cmvLBAtxe+jaijn22THtpLLUSXt1ozexS
ZHGFtsUBuIoNzXoRXxJwkGBA1ZpLBbOpjyp6PzNcTPYFG51+EHTUMPkbfyQ5
-----END CERTIFICATE-----
[2024-10-25 21:40:54,173] [ARCCTL.ThirdParty.Deploy] [INFO] [726706] [CA Certificate for /DC=org/DC=nordugrid/DC=ARC/O=TestCA/CN=ARC TestCA fdb0a5e3 is deployed successfully to /etc/grid-security/certificates/ARCTestCAfdb0a5e3.pem]

This will create all necessary files in your x509_cert_dir and allow your remote client to trust the ARC-CE.

Step 7. Get a submission token

To submit jobs or perform any other action towards the ARC-CE you must authenticate yourself. We will do this using a token issued from the test-jwt issuer.

To generate a token do:

[user ~]$ export BEARER_TOKEN=$(arcctl test-jwt token)

Step 8. Restart A-REX

On the ARC-CE, restart A-REX services to activate the configuration changes

[root ~]# arcctl service restart -a

Step 9. Check all is ok

You can run the client commands (arcinfo, arcsub etc) from the host running A-REX or from any other host in the network. In any case you must install the ARC client (steps 4 and 5)

Warning

The zero configured A-REX comes with the REST interface enabled. It runs on port 443, so make sure it is not firewalled if you want to submit jobs from a remote client host.

You can start with the information query about your newly installed ARC computing element [1]:

[user ~]$ arcinfo -C https://arc.example.org/arex
Computing service:
  Information endpoint: https://arc.example.org:443/arex
  Submission endpoint: https://arc.example.org:443/arex (status: ok, interface: org.nordugrid.arcrest)

[1]

Examples use arc.example.org as a domain name for A-REX host

This means that all is ok, and the ARC client got back information from the ARC-CE that the information and service endpoints are available and ok.

Warning

It can take some minutes after the setup for everything to be fine, so if you see status: critical wait a little while (~1 minute) and check again.

Note

Tip: You can use $(hostname) instead of typing the hostname for these tests in your zero-conf setup. For example:

arcinfo -C $(hostname)

Step 10. Submit a job and check that it is running

A simple job can be submitted with the arctest tool:

[user ~]$ arctest -J 2 -C https://arc.example.org/arex
Job submitted with jobid: https://arc.example.org:443/arex/rest/1.0/jobs/f77b3d1b1efb

The job status can be checked with the arcstat tool:

[user ~]$ arcstat https://arc.example.org:443/arex/rest/1.0/jobs/f77b3d1b1efb
Job: https://arc.example.org:443/arex/rest/1.0/jobs/f77b3d1b1efb
 Name: arctest2
 State: Running

Status of 1 jobs was queried, 1 jobs returned information

To fetch the job’s stdout run arccat tool:

[user ~]$ arccat https://arc.example.org:443/arex/rest/1.0/jobs/f77b3d1b1efb
HOSTNAME=arc.example.org
GRID_GLOBAL_JOBURL=https://arc.example.org:443/arex/f77b3d1b1efb
MALLOC_ARENA_MAX=2
PWD=/var/spool/arc/sessiondir/f77b3d1b1efb
SYSTEMD_EXEC_PID=374194
<output_omitted>

Step 11. Play more with the ARC Computing Element

As an admin you might frequently need to extract information from the logs and directories that ARC computing element uses. The brief list of the relevant paths can be obtained from:

[root ~]# arcctl config brief
ARC Storage Areas:
    Control directory:
        /var/spool/arc/jobstatus
    Session directories:
        /var/spool/arc/sessiondir
    Scratch directory on Worker Node:
        Not configured
    Additional user-defined RTE directories:
        Not configured
ARC Log Files:
    A-REX Service log:
        /var/log/arc/arex.log
    A-REX Jobs log:
        /var/log/arc/arex-jobs.log
    A-REX Helpers log:
        /var/log/arc/job.helper.errors
    A-REX WS Interface log:
        /var/log/arc/ws-interface.log
    Infosys Infoproviders log:
        /var/log/arc/infoprovider.log

To get information and manage jobs on A-REX server, the arcctl job is useful. Operations include but is not limited to:

• Listing jobs:

[root ~]# arcctl job list
f5ab040cdc51
f617259d58ec
<output omitted>

[root ~]# arcctl job list --long
f5ab040cdc51      FINISHED   arctest2                                https://wlcg.cloud.cnaf.infn.it//b9f1e5e2-a8f0-4332-bd9d-58bd63898cc6
f617259d58ec      FINISHED   arctest2                                https://wlcg.cloud.cnaf.infn.it//b9f1e5e2-a8f0-4332-bd9d-58bd63898cc6
<output omitted>

• Job general information:

[root ~]# arcctl job info f77b3d1b1efb
Name         : arctest2
Owner        : https://wlcg.cloud.cnaf.infn.it//b9f1e5e2-a8f0-4332-bd9d-58bd63898cc6
State        : FINISHED
LRMS ID      : 376176
Modified     : 2023-06-02 16:07:05

• Job log:

[root ~]# arcctl job log f77b3d1b1efb
2023-06-02T14:06:51Z Job state change UNDEFINED -> ACCEPTED   Reason: (Re)Accepting new job
2023-06-02T14:06:51Z Job state change ACCEPTED -> PREPARING   Reason: Starting job processing
2023-06-02T14:06:51Z Job state change PREPARING -> SUBMIT   Reason: Pre-staging finished, passing job to LRMS
----- exiting submit_fork_job -----

2023-06-02T14:06:53Z Job state change SUBMIT -> INLRMS   Reason: Job is passed to LRMS
---------- Output of the job wrapper script -----------
Detecting resource accounting method available for the job.
Looking for /usr/bin/time tool for accounting measurements
GNU time found and will be used for job accounting.
------------------------- End of output -------------------------
2023-06-02T14:07:05Z Job state change INLRMS -> FINISHING   Reason: Job finished executing in LRMS
2023-06-02T14:07:05Z Job state change FINISHING -> FINISHED   Reason: Stage-out finished.

• A-REX logs that mentions the job:

[root ~]# arcctl job log f77b3d1b1efb --service
### /var/log/arc/arex.log:
[2023-06-02 16:06:51] [Arc] [INFO] [374270/3] f77b3d1b1efb: State: ACCEPTED: parsing job description
[2023-06-02 16:06:51] [Arc] [INFO] [374270/3] f77b3d1b1efb: State: ACCEPTED: moving to PREPARING
[2023-06-02 16:06:51] [Arc] [INFO] [374270/3] f77b3d1b1efb: State: PREPARING from ACCEPTED
[2023-06-02 16:06:51] [Arc] [INFO] [374270/3] f77b3d1b1efb: State: SUBMIT from PREPARING
[2023-06-02 16:06:51] [Arc] [INFO] [374270/3] f77b3d1b1efb: state SUBMIT: starting child: /usr/share/arc/submit-fork-job
[2023-06-02 16:06:53] [Arc] [INFO] [374270/3] f77b3d1b1efb: state SUBMIT: child exited with code 0
[2023-06-02 16:06:53] [Arc] [INFO] [374270/3] f77b3d1b1efb: State: INLRMS from SUBMIT
[2023-06-02 16:07:05] [Arc] [INFO] [374270/3] f77b3d1b1efb: Job finished
[2023-06-02 16:07:05] [Arc] [INFO] [374270/3] f77b3d1b1efb: State: FINISHING from INLRMS
[2023-06-02 16:07:05] [Arc] [INFO] [374270/3] f77b3d1b1efb: State: FINISHED from FINISHING
### /var/log/arc/ws-interface.log:

• Getting job attributes:

[root ~]# arcctl job attr f77b3d1b1efb jobname
arctest2

Get production ready

Now you are ready to Install production ARC7 Computing Element!