Initial setup of ARCHERY instance

This document describes how to setup an ARCHERY instance in the DNS zone, including both DNS aspects and initial service endpoint information embedding.

The described procedures apply to either NorduGrid deployment case or any other ARCHERY instance setup flavors, e.g. country-level, project/experiment, virtual organization, etc.

Note

Administrative access to the DNS server is required during the ARCHERY initial setup to create DNS zone and configure remote access to this zone.

Further operating of ARCHERY instance DOES NOT require administrative access to the DNS.

Choose DNS zone name

ARCHERY registry instance is accessible by DNS name, that is used as an entry point (e.g. to submit jobs to the infrastructure).

This guide uses example.org as an organization-owned domain name that will contain a zone for ARCHERY setup.

Despite it is possible to put records directly into the example.org zone, for manageability and security [1] reasons it is strongly advised to have dedicated DNS sub-zone configured for ARCHERY records.

In the ARCHERY deployment for NorduGrid per-country sub-zone names are pre-defined.

Any other setup can use arbitrary sub-zone name. This guide uses index.example.org DNS zone for ARCHERY setup.

Generate transaction signature key to manage ARCHERY

ARCHERY implies the usage of Dynamic DNS (DDNS) updates to manage the data inside DNS zone.

The archery-manage tool, that is part of NorduGrid ARC middleware, will do the DDNS updates for you as described below.

DDNS eliminates typos, allows to maintain up-to-date information and keeps it simple operate ARCHERY without administrative access to the DNS server itself.

Use the following command to generate the key:

[user ~]$ dnssec-keygen -a HMAC-MD5 -b 256 -n USER archery

From the generated files you need a secret part to be included in both BIND and archery-manage configuration.

Define key in BIND

Note

Configuration examples in this guide are provided for BIND, however you can use any name server implementation configured in a similar way.

Create the /etc/named/archery.key and put the generated secret key inside:

key archery_key {
      algorithm hmac-md5;
      secret "S0Me+SecRet+keYgener@tedwithdnssec==";
};

Include the key definition into /etc/named.conf using the following config line:

include "/etc/named/archery.key";

Keyfile for archery-manage

Create a file archery-manage.key and put the generated key in the following format:

archery_key:S0Me+SecRet+keYgener@tedwithdnssec==

Configure DNS zone for ARCHERY

It is generally required by the worldwide DNS infrastructure that at least one slave DNS server should be configured for every DNS zone for reliability reasons.

In this guide the following addressed will be used:

Primary (master) DNS: ns1.example.org (192.0.2.100)

Seondary (slave) DNS: ns2.example.org (192.0.2.200)

Define zone in BIND

Add zone definition to master DNS /etc/named.conf:

zone "index.example.org." IN {
    type master;
    file "master/index.example.org.db";
    notify yes;
    also-notify {
        # slave DNS IP address
        192.0.2.200;
    };
    allow-transfer {
        # slave DNS IP address
        192.0.2.200;
    };
    allow-update {
        key archery_key;
    };
};

Please observer the allow-update directive that authorize DDNS update requests signed by archery-manage key.

The secondary DNS should be configured without any special options:

zone "index.example.org." IN {
    type slave;
    file "slave/index.example.org.db";
    masters {
        192.0.2.100;
    };
    allow-transfer {
        192.0.2.100;
    };
};

Create zonefile with a basic zone info

Basic zonefile requires only SOA record. It will be filled with data by archery-manage later.

You can use following zonefile template (timers are subject to arrange depending on the planned update frequency):

$ORIGIN example.org.
$TTL 3600
index   IN SOA    ns1.example.org. hostmaster.example.org. (
             2018082401 ; serial
             1200       ; refresh (20 minutes)
             180        ; retry (3 minutes)
             604800     ; expire (1 week)
             60         ; minimum (1 minute)
             )
        NS    ns1.example.org.
        NS    ns2.example.org.

Define records in parent zone

Note

If you setup a country-level index for the Nordugrid infrastructure such records are defined in the parent nordugrid.org zone.

Please provide your DNS setup information to us instead of following this section.

Define NS records [2] to refer to defined subzone:

$ORIGIN example.org.
# dedicated ARCHERY zone
index   NS ns1.example.org.
index   NS ns2.example.org.

To create an ARCHERY entry point in the parent zone you can:

define CNAME record to use example.org as an entry point:
$ORIGIN example.org.
# ARCHERY entry point
_archery CNAME _archery.index
OR define TXT resource record with ARCHERY data pointing to group:
$ORIGIN example.org.
# ARCHERY entry point
_archery TXT “u=index.example.org t=archery.group”

The same technique can be used to define any other DNS aliases for an entry point (even in a completele different domain).

CNAME is recommended if you referring only one ARCHERY group.

Populate ARCHERY DNS zone with initial data

The archery-manage is a dedicated tool to manage information in the ARCHERY DNS zone. It is available as nordugrid-arc-archery-manage package in the NorduGrid repositories and EPEL.

The tool uses the configuration file in the plain text of JSON format that define services topology. Configuration file syntax is very simple and described in details in the operations guide.

For initial data provisioning you should run archery-manage once supplying config, DNS zone and transaction signature key path generated in the previous steps.

After zone is populated with data Operating ARCHERY instance comes down to kepping it up to date, running periodic updates.