Globus Connect Server Domain Guide

Last Updated: May 6, 2021

1. Introduction

This document describes the configuration of a custom domain name for a Globus Connect Server endpoint or collection.

Globus Connect Server uses DNS names to access virtual hosts for each of the services provided by Globus Connect Server. In GCSv5.4, there are separate virtual hosts with different DNS names for the service providing the management API for the Globus Connect Server endpoint and for each collection available on the endpoint.

Endpoint

The Globus Connect Server API is hosted on this domain name.

Collection

Each mapped or guest collection provided by the endpoint has a unique domain name. These domain names are all subdomains of the endpoint domain by default, though independent domain names can be used starting in v5.4.13.

This document assumes that you have already created and deployed an endpoint by following the Globus Connect Server version 5 Installation Guide. The commands in this guide assume you have access to the globus-connect-server command-line tool.

Important

In this document, we will show some example invocations of the Globus Connect Server version 5 management commands. If you plan to follow along on your own system, you’ll need to change the commands to reflect your organization and login policies. Anywhere you see something highlighted like this you’ll need to replace the text with something that matches the desired policies for your own endpoint.

2. Globus Domain Names

By default, Globus assigns a subdomain of data.globus.org for endpoints and collections.

2.1. Default Domain Names

The globus-connect-server endpoint setup command allocates a subdomain of data.globus.org and uses it for the endpoint’s domain name. All collections use domain names that are subdomains of the endpoint by default.

Example 1. Endpoint and Collection Defaults

For example, if Globus Connect Server allocates 9009.09ad6.data.globus.org for the endpoint domain, the Globus Connect Server API will be available at https://9009.09ad6.data.globus.org/api/.

Each collection will be assigned a random name such as m-4283f.9009.09ad6.data.globus.org, which is a subdomain of the endpoint’s domain. The GridFTP server for the collection is accessed at tlsftp://m-4283f.9009.09ad6.data.globus.org and the https server for the collection is accessed at https://m-4283f.9009.09ad6.data.globus.org.

This configuration is the default, and you do not need to use any special command-line options to the globus-connect-server tool when creating or updating collections to get this behavior.

2.2. Custom Label for a Mapped Collection

Endpoint owners or administrators can set a non-random DNS label for a mapped collection. When using this, the endpoint domain is still a randomly assigned data.globus.org domain, but the collection has a slightly more memorable domain name. The domain label for the collection must be a subdomain of the endpoint domain name.

You can use the --domain-name NAME option to globus-connect-server collection create to set the domain name to use for a mapped collection. You must be have an endpoint owner or administrator role to create a collection.

Example 2. Create a collection using a custom domain label

This example uses the configuration options from the Data Access Guide, and adds the domain label configuration to set the DNS name for the collection to be genome.9009.09ad6.data.globus.org.

globus-connect-server collection create \
    7187a9a0-68e4-48ea-b3b9-7fd06630f8ab \
    / "POSIX example.org home directories" \
    --organization 'Example organization' \
    --contact-email support@example.org \
    --info-link \https://example.org/storage/info \
    --description "Collection of home directories for the example.org's users" \
    --keywords example.org,home \
    --allow-guest-collections \
    --sharing-restrict-paths file:sharing_restrictions.json \
    --sharing-user-allow alice --sharing-user-allow bob \
    --user-message "Tape storage: Do not upload small files" \
    --user-message-link \https://example.org/tape-policy \
    --enable-https \
    --domain genome.9009.09ad6.data.globus.org

Collection ID: 56c3dff0-d827-4f11-91f3-b0704c53aa4c

You can also use the same option to update an existing collection using globus-connect-server collection update. This requires an endpoint owner or administrator role, or a collection administrator role.

Example 3. Update a collection using a custom domain label

If the collection 56c3dff0-d827-4f11-91f3-b0704c53aa4c already exists, this command will change its domain label to genome.9009.09ad6.data.globus.org.

globus-connect-server collection update 56c3dff0-d827-4f11-91f3-b0704c53aa4c \
    --domain genome.9009.09ad6.data.globus.org
Note

The domain label may be any valid DNS label, except that it may not begin with the character sequence m- or g-.

3. Custom Domains (new in v.5.4.13)

Globus Connect Serverv5.4.13 provides support for using domains other than data.globus.org for endpoints or collections. The administrator must provides a domain name, certificate, and private key for the custom domain for the endpoint and/or collections to use.

Globus Connect Server provides several options and flexibility for configuring these domains. Administrators can choose any of the following options, independent of each other:

  • A custom domain may be assigned to the endpoint. If it is a wildcard domain, mapped and guest collections are automatically assigned subdomains of that domain.

  • A custom domain may be assigned to a mapped collection. If it is a wildcard domain, guest collections are automatically assigned subdomains of mapped collection.

  • A custom domain may be assigned to a guest collection.

Globus Connect Server also provide options for Globus to manage the deployment of certificates and keys, or for administrators to manually deploy them across nodes.

Important
If you use the fully-qualified hostname of the local node as the custom domain, it may cause conflicts between httpd’s default virtual host configuration and the Globus Connect Server virtual host configuration which could result in a nonfunctional endpoint or collection.

3.1. Trusted Certificate Authorities

The Globus Transfer service trusts all certificate authorities which are trusted by common browsers. Additionally, Globus supports the following authorities, as well as valid intermediate CAs included in the certificate chain.

C=BM, O=QuoVadis Limited, CN=QuoVadis Root CA 2

C=BM, O=QuoVadis Limited, CN=QuoVadis Root CA 2 G3

C=BM, O=QuoVadis Limited, CN=QuoVadis Root CA 3 G3

C=BM, O=QuoVadis Limited, OU=Root Certification Authority, CN=QuoVadis Root Certification Authority

C=DE, O=T-Systems Enterprise Services GmbH, OU=T-Systems Trust Center, CN=T-TeleSec GlobalRoot Class 2

C=GB, ST=Greater Manchester, L=Salford, O=COMODO CA Limited, CN=COMODO RSA Certification Authority

C=US, O=DigiCert Inc, OU=www.digicert.com, CN=DigiCert Assured ID Root CA

C=US, O=DigiCert Inc, OU=www.digicert.com, CN=DigiCert Global Root CA

C=US, O=Internet Security Research Group, CN=ISRG Root X1

C=US, ST=New Jersey, L=Jersey City, O=The USERTRUST Network, CN=USERTrust ECC Certification Authority

C=US, ST=New Jersey, L=Jersey City, O=The USERTRUST Network, CN=USERTrust RSA Certification Authority

It is our intention to support all common trusted root certificates needed to support custom domain configurations for GCSv5 installations. If your domain is not supported, you will see errors similar to the following when accessing your GCSv5 collection:

Details: an authentication operation failed\nglobus_xio_gsi:
gss_init_sec_context failed.\nGSS failure: \nGSS Major Status: Authentication
Failed\nGSS Minor Status Error Chain:\nglobus_gsi_gssapi: SSL handshake
problems\nOpenSSL Error: ../ssl/statem/statem_clnt.c:1913: in library: SSL
routines, function tls_process_server_certificate: certificate verify failed\n
globus_gsi_callback_module: Could not verify credential\n globus_gsi_callback_module:
Can't get the local trusted CA certificate: Cannot find trusted CA certificate
with hash 3513523f in /etc/grid-security/certificates\n\n

If you use another provider for your certificate, please contact support@globus.org.

3.2. DNS Configuration

To configure a domain for use by Globus Connect Server, it must already be configured by your DNS provider. There are two ways this can be setup:

  1. An A, AAAA, or CNAME record that resolves to the IP addresses of the data transfer nodes. With this configuration, if you add or remove a data transfer node, you’ll need to update the DNS record to reflect the change.

  2. A CNAME record that points to the data.globus.org domain initially assigned to your endpoint. In this case, Globus Connect Server will update the A and AAAA records for that domain whenever a data transfer node is added or taken offline via the command line tools.

You’ll also need to create a TXT record at your domain in order to support DNS based validation of association of the domain with the endpoint. The value of the TXT record must match the client id used to create the endpoint. This is the value of ID in the output of globus-connect-server endpoint show.

3.2.1. Wildcard Domains

If you want Globus Connect Server to automatically configure collections to use subdomains of the custom endpoint domain, you’ll need to provide a wildcard domain and set the wildcard flag in Globus Connect Server when configuring the domain.

Example 4. Example DNS Configuration

This example shows DNS records for the data.example.edu domain, configured to use a single data transfer node. This domain is a wildcard domain, so it can be used with the endpoint and its collections. The TXT record is configured with the client_id used to create the endpoint.

data.example.edu            A       203.0.113.1
*.data.example.edu          A       203.0.113.1
data.example.edu            TXT     b7cf3b1b-c306-456f-9ff9-a29fb8d2d26d

All collections created will be automatically assigned subdomains of data.example.edu.

3.3. Certificate and Key Configuration

The certificate must include the domain, and wildcard subdomain if a wildcard domain is used, in either the Common Name (CN) or the Subject Alternative Names (SAN) fields. For example, to use the wildcard domain data.example.edu, the certificate CN and SAN fields may be:

Certificate:
    Signature Algorithm: sha256WithRSAEncryption
        Issuer: C=US, O=Let's Encrypt, CN=R3
        Validity
            Not Before: May  2 21:03:12 2021 GMT
            Not After : Jul 31 21:03:12 2021 GMT
        Subject: CN=data.example.edu
    X509v3 extensions:
        X509v3 Subject Alternative Name:
            DNS:*.data.example.edu, DNS:data.example.edu

The certificate and private key must also be included in the configuration for the endpoint in order to use a custom domain name. Globus Connect Server supports two ways of configuring these: managed and manual.

3.3.1. Managed Deployment of Certificates and Keys

Globus Connect Server can automatically manage certificates and keys for the domain. In this configuration, Globus Connect Server automatically encrypts and synchronizes the certificate and key between data transfer nodes. The Globus Connect Server processes on the data transfer nodes decrypt the data, store it in the local filesystem, and then configure the web server hosting the Globus services to use these credentials.

When a certificate is renewed, the administrator must use the Globus Connect Server CLI to update the configuration with the new certificates and keys. These changes will be propagated to all data transfer nodes for that endpoint.

3.3.2. Manual Deployment of Certificates and Keys

Alternatively, Globus Connect Server supports manual deployment of certificates and keys for the domain. Globus Connect Server synchronizes the paths to the certificates and key. The administrator must ensure that each data transfer node has these files available at the same path.

When a certificate is renewed or a data transfer node is added to an endpoint, the administrator must ensure that the file contents are available at the configured certificate and key paths on each data transfer node.

Important
The certificate and key files must exist in a directory that is readable by the gcsweb user. Additionally, the certificate and key files must be readable by either the root or the gcsweb user, and the private key must have permissions rw-------. If SELinux is enforcing, the certificate and key files must be labeled system_u:object_r:cert_t:s0.

4. Configuration and Management of Custom Domains

4.1. Endpoint Domain

You can configure an endpoint to have a specific domain name outside of the default data.globus.org domain. If you configure the domain as a wildcard domain, then all collections will use subdomains of this endpoint domain. Later sections outline how collections can be configured with their own domain, rather than the default option.

Example 5. Endpoint Domain Example

A university wants its endpoint to appear as data.example.edu and collections to be subdomains of that.

The Globus Connect Server Manager API is hosted at data.example.edu. By default, mapped collections are given names that look like m-13ea0.data.example.edu and guest collections are given names that look like g-8ff7e.data.example.edu.

The endpoint administrator allocates the DNS name data.example.edu and wildcard DNS name *.data.example.edu from the campus DNS authority and obtains a single certificate that includes both domains. The administrator then registers the domain and certificate with Globus Connect Server and chooses the managed certificate and key deployment option.

The following command sets the domain for the endpoint to be data.example.edu as a wildcard domain.

This command will only succeed if the user has logged in to the endpoint and has an endpoint owner or administrator role.

globus-connect-server endpoint domain update \
    --wildcard \
    --certificate-path /etc/ssl/certs/data.example.edu.crt \
    --private-key-path /etc/ssl/certs/data.example.edu.pkey \
    --domain data.example.edu \
    --managed

Globus Connect Server updates the domain name used in the endpoint to be that domain, and updates the collection definitions to be hosted on subdomains of that domain. The contents of the certificate and key files on the machine on which the command is run will be encrypted and synchronized between data transfer nodes.

4.2. Mapped Collection Domains

You can configure a mapped collection to have a specific domain name outside of the default data.globus.org domain. It can also be a completely different domain than the endpoint’s domain, as shown in the next example.

Example 6. Mapped Collection Domain Example

A cross-institutional research project with researchers at university-1.example.edu and university-2.example.edu want to have their data available using the research project’s domain project.example.org rather than that of either university.

The project administrator configures a DNS entry to point to the resource hosting the endpoint and registers a certificate and key with the Globus Connect Server Manager.

The domain name used to contact the Globus Connect Server Manager API is still based on the endpoint’s domain, which may be either the .data.globus.org domain or a custom domain as in the previous example, but the mapped collection appears at project.example.org.

If the --wildcard option is passed to this command, then all guest collections created from the mapped collection will have domain names that are subdomains of project.example.org. In this case, the administrator must also configure the wildcard DNS entry and include the wildcard domain in the certificate.

If the --wildcard option is omitted (as in this example), the guest collection domains will be based on the endpoint domain.

This command will only succeed if the user has logged in to the endpoint and has an endpoint owner or administrator role.

globus-connect-server collection domain update 56c3dff0-d827-4f11-91f3-b0704c53aa4c \
    --certificate-path /etc/ssl/certs/data.project.example.org.crt \
    --private-key-path /etc/ssl/certs/data.project.example.org.pkey \
    --domain project.example.org \
    --managed

4.3. Guest Collection Domains

You also can configure a guest collection to have a domain name independent of both the endpoint and the collection domain name.

Example 7. Guest Collection Domain Example

A research project has a policy of only allowing data access via their guest collections. The project wants to use a name that represents the project’s ownership of the data, so they want it to appear as project.example.org.

The project administrator configures a DNS entry to point to the resource hosting the endpoint and registers a certificate and key with the Globus Connect Server Manager so that it can update the collection vhost.

The domain name used to contact the Globus Connect Server Manager API is still handled based on the endpoint’s domain, and the mapped collection can also have a different domain name, but the project’s users will not be directly using either of those services, so they don’t need to set the domain for them.

In this case, the wildcard flag is not needed, as there is no need to use subdomains.

This command will only succeed if the user has logged in to the endpoint and has an endpoint owner or administrator role.

globus-connect-server collection domain update 56c3dff0-d827-4f11-91f3-b0704c53aa4c \
    --certificate-path /etc/ssl/certs/data.project.example.org.crt \
    --private-key-path /etc/ssl/certs/data.project.example.org.pkey \
    --domain data.project.example.org \
    --managed

4.4. Deleting Domains

Domains can be removed from endpoints or collections. When a wildcard domain is removed from a mapped collection or endpoint, it may affect the domains of other collections on the endpoint.

4.4.1. Deleting an Endpoint Domain

When an endpoint domain is deleted, the endpoint reverts to the data.globus.org domain allocated during endpoint setup.

If the endpoint domain was a wildcard domain, then the change will affect all collections that are using subdomains of the endpoint domain. This includes all mapped collections without a domain assignment. It also includes all guest collections where they don’t have a domain assignment and the mapped collection they were created from does not have a wildcard domain assignment.

Example 8. Deleting an Endpoint Domain

The following command deletes the endpoint domain, causing it to revert to the data.globus.org domain allocated during endpoint setup.

This command will only succeed if the user has logged in to the endpoint and has an endpoint owner or administrator role.

globus-connect-server endpoint domain delete

4.4.2. Deleting a Collection Domain

When a mapped collection’s domain is deleted, the mapped collection reverts being a subdomain of the endpoint’s domain if the endpoint has a wildcard domain, or a subdomain of the data.globus.org domain allocated during endpoint setup.

If the mapped collection had a wildcard domain, deleting the domain for the mapped collection would also cause all guest collections of that mapped collection to revert to being a subdomain of the endpoint’s domain if the endpoint has a wildcard domain, or a subdomain of the data.globus.org domain allocated during endpoint setup.

When a guest collection’s domain is deleted, the change does not affect any other collections on the endpoint.

Example 9. Deleting a Collection Domain

The following command deletes the mapped collection’s domain.

This command will only succeed if the user has logged in to the endpoint and has an endpoint owner or administrator role.

globus-connect-server collection domain delete 56c3dff0-d827-4f11-91f3-b0704c53aa4c

4.5. Showing Domains

The Globus Connect Server CLI supports commands to show information about the domains assigned to endpoints or collections. The following examples show those commands. Note that these commands do not reveal any private key or certificate or key path information.

Example 10. Showing the Endpoint Domain
globus-connect-server endpoint domain show
Example 11. Showing the Collection Domain
globus-connect-server collection domain show 56c3dff0-d827-4f11-91f3-b0704c53aa4c

5. Automatically Obtaining Certificates Using CertBot

You can use the certbot command from Let’s Encrypt to automatically obtain certificates and deploy them so that Globus Connect Server can use them. This can be done using the Let’s Encrypt ACME server or any other CA that supports the DNS-01 challenge. This can be completely automated if you use a DNS provider which has a certbot plugin. These include CloudFlare, Google, Amazon Route53, and many others. See DNS Plugins for a list of plugins. For this document, we’ll use the Route 53 plugin, but configuring others is similar.

5.1. Install Certbot and the DNS plugin 

dnf install certbot python3-certbot-dns-route53
apt install certbot python3-certbot-dns-route53

5.2. Create Route53 credentials

Follow the steps in the Certbot Route53 Plugin Documentation to create an IAM credential to perform DNS updates for the ACME DNS challenge.

Save the credentials to a file readable only by root. For example, /etc/gcs-route53-config, you’ll set an environment variable in the certbot configuration to find the credentials.

5.3. Create script to deploy certificate and key to the GCS paths

To fully automate this process, you’ll need a script to automatically copy the results of the cert renewal to the GCS domains directory. An example script follows. Save this script to /usr/local/bin/gcs-certbot-deploy-hook and set the permissions so root can run it.

gcs-certbot-deploy-hook
#! /bin/sh

source="$RENEWED_LINEAGE"

if [ -z "$source" ]; then
    exit 1
fi
dest="/etc/gcs-domain"

if [ ! -d "$dest" ]; then
    install -d -o root -g gcsweb -m 0750 "$dest"
fi

install -o gcsweb -g gcsweb -m 0600 "$source/cert.pem" "$dest/cert.pem"
install -o gcsweb -g gcsweb -m 0600 "$source/chain.pem" "$dest/chain.pem"
install -o gcsweb -g gcsweb -m 0600 "$source/privkey.pem" "$dest/privkey.pem"

. /etc/os-release

apache_service=
case $ID:$VERSION_ID:$ID_LIKE in
    debian:* | ubuntu:* )
        apache_service=apache2
        ;;
    rhel:7*:* | amzn:2:* | centos:7*:* | ol:7*:* | scientific:7*:*)
        apache_service=httpd
        ;;
    rhel:8*:* | almalinux:8*:* | centos:8*:* | ol:8*:* | rocky:8*:*)
        apache_service=httpd
        ;;
    rhel:9*:* | almalinux:9*:* | centos:9*:* | ol:9*:* | rocky:9*:*)
        apache_service=httpd
        ;;
    *:7*:*rhel* | *:7*:*centos* )
        apache_service=httpd
        ;;
    *:8*:*rhel* | *:8*:*centos* )
        apache_service=httpd
        ;;
    *:9*:*rhel* | *:9*:*centos* )
        apache_service=httpd
        ;;
    fedora:*:*)
        apache_service=httpd
        ;;
    *suse* )
        apache_service=apache2
        ;;
    *)
        ;;
esac


if [ -n "$apache_service" ]; then
    systemctl restart "$apache_service"
fi

5.4. Modify Certbot CLI config

Update the certbot service configuration so that it will use the dns-route53 plugin and run the hook. Edit the file /etc/letsencrypt/cli.ini, adding the following lines:

Certbot CLI config additions
authenticator = dns-route53
deploy-hook = /usr/local/bin/gcs-certbot-deploy-hook

5.5. Modify Certbot Systemd Service Config

The certbot package includes a systemd timer and service unit. We’ll add an environment variable to this unit to allow it to find the route53 credentials.

As root, run the command systemctl edit certbot-renew to create local customizations of the certbot systemd unit to set the AWS_CONFIG_FILE environment variable

[Service]
Environment="AWS_CONFIG_FILE=/etc/gcs-route53-config"

As root, run the command systemctl edit certbot to create local customizations of the certbot systemd unit to set the AWS_CONFIG_FILE environment variable

[Service]
Environment="AWS_CONFIG_FILE=/etc/gcs-route53-config"

5.6. Request endpoint certificate

The certbot timer will automatically renew certificates managed by certbot, but doesn’t know about the certificates until they are first requested. The first time you execute this it will prompt for some information, but afterwards it will be able to automatically renew certificates.

For example purposes, this document uses MYDOMAIN and *.MYDOMAIN for the certificate; you’ll need to replace that with a name in the Route 53 managed zone which you created the AWS credential for earlier.

Request the certificate
export AWS_CONFIG_FILE=/etc/gcs-route53-config
certbot certonly -d MYDOMAIN -d "*.MYDOMAIN"

5.7. Update your endpoint to use the certificate

Now, we’ll update the endpoint configuration to use the wildcard domain and new certificate that was created in the previous step.

dest="/etc/gcs-domain"
globus-connect-server endpoint domain update \
    --domain MYDOMAIN \
    --wildcard \
    --private-key-path "$dest/privkey.pem" \
    --certificate-chain-path "$dest/chain.pem" \
    --certificate-path "$dest/cert.pem"

5.8. Enable auto-renewal

Run the following command to enable the certbot renew timer.

Run the following command to enable the systemd timer to automatically renew the certbot certificates.

Start the certbot timer to renew certificates
systemctl enable --now certbot-renew.timer

Run the following command to enable the systemd timer to automatically renew the certbot certificates.

Start the certbot timer to renew certificates
systemctl enable --now certbot.timer

6. Command Reference

The following links take you to the reference manuals for the commands used in this document:

7. Globus Help Resources

7.1. Documentation Website

This website (docs.globus.org) contains a wealth of information about configuring and using the Globus service. Many common issues can be resolved quickly by browsing our frequently asked questions and reading the relevant guides and how-tos. We recommend consulting these resources first when looking for fast resolution to any issue you are having with the Globus service.

7.2. Mailing Lists

If you use Globus, then participating in one or more of the public email lists is an excellent way to keep in touch with your peers in the Globus Community. For questions about managing your Globus deployment, e.g. installing software for a Globus endpoint, configuring your firewall, and integrating your institution’s identity system, subscribe to the admin list. For other inquiries and discussions, try the user or developer lists. For more information on mailing lists and how to subscribe, click here.

7.3. Globus Support

Questions or issues that pertain to Globus Connect Server version 5 installation or to any client or service that is used in the Globus software-as-a-service (SaaS) or platform-as-a-service (PaaS) offering can be directed to the Globus support team by submitting a ticket. Subscriptions include a guaranteed support service level.

When submitting a ticket for an issue with Globus Connect Server, please include the endpoint name, a description of your issue, and screenshot/text dumps of any errors you are seeing. Please also include the output of Globus Connect Server’s self-diagnostic command, run as root, from the server hosting the endpoint:

globus-connect-server self-diagnostic