Installing the OSDF Cache¶
This document describes how to install an Open Science Data Federation (OSDF) cache service. This service allows a site or regional network to cache data frequently used on the OSG, reducing data transfer over the wide-area network and decreasing access latency.
The OSDF cache was previously named "Stash Cache" and some documentation and software may use the old name.
Before starting the installation process, consider the following requirements:
- Operating system: Ensure the host has a supported operating system
- User IDs: If they do not exist already, the installation will create the Linux user IDs
- Host certificate: Required for reporting and authenticated caches. Authenticated caching is an optional feature. See our documentation for instructions on how to request and install host certificates.
- Network ports: The cache service requires the following ports open:
- Inbound TCP port 1094 for file access via the XRootD protocol
- Inbound TCP port 8000 for file access via HTTP
- Inbound TCP port 8443 for authenticated file access via HTTPS (optional)
- Outbound UDP port 9930 for reporting to
- Hardware requirements: We recommend that a cache has at least 10Gbps connectivity, 1TB of disk space for the cache directory, and 12GB of RAM.
As with all OSG software installations, there are some one-time steps to prepare in advance:
Registering the Cache¶
To be part of the OSDF, your cache must be registered with the OSG. You will need basic information like the resource name and hostname, and the administrative and security contacts.
To register your cache host, follow the general registration instructions here.
The service type is
XRootD cache server.
This step must be completed before installation.
In your registration, you must specify which VOs your cache will serve by adding an
AllowedVOs list, with each line specifying a VO whose data you are willing to cache.
There are special values you may use in
ANY_PUBLICindicates that the cache is willing to serve public data from any VO.
ANYindicates that the cache is willing to serve data from any VO, both public and non-public.
There are extra requirements for serving non-public data:
- In addition to the cache allowing a VO in the
AllowedVOslist, that VO must also allow the cache in its
AllowedCacheslist. See the page on getting your VO's data into OSDF.
- There must be an authenticated XRootD instance on the cache server.
- There must be a
DNattribute in the resource registration with the subject DN of the host certificate
This is an example registration for a cache server that serves all public data:
MY_OSDF_CACHE: FQDN: my-cache.example.net Service: XRootD cache server Description: OSDF cache server AllowedVOs: - ANY_PUBLIC
This is an example registration for a cache server that only serves authenticated data for the Open Science Pool:
MY_AUTH_OSDF_CACHE: FQDN: my-auth-cache.example.net Service: XRootD cache server Description: OSDF cache server AllowedVOs: - OSG DN: /DC=org/DC=opensciencegrid/O=Open Science Grid/OU=Services/CN=my-auth-cache.example.net
This is an example registration for a cache server that serves all public data and authenticated data from the OSG VO:
MY_COMBO_OSDF_CACHE: FQDN: my-combo-cache.example.net Service: XRootD cache server Description: OSDF cache server AllowedVOs: - OSG - ANY_PUBLIC DN: /DC=org/DC=opensciencegrid/O=Open Science Grid/OU=Services/CN=my-combo-cache.example.net
Once initial registration is complete, you may start the installation process. In the meantime, open a help ticket with your cache name. Mention in your ticket that you would like to "Finalize the cache registration."
Installing the Cache¶
The OSDF software consists of an XRootD server with special configuration and supporting services. To simplify installation, OSG provides convenience RPMs that install all required packages with a single command:
[email protected] # yum install stash-cache
Configuring the Cache¶
First, you must create a "cache directory", which will be used to store downloaded files.
By default this is
We recommend using a separate file system for the cache directory,
with at least 1 TB of storage available.
The cache directory must be writable by the
xrootd:xrootd user and group.
stash-cache package provides default configuration files in
Administrators may provide additional configuration by placing files in
/etc/xrootd/config.d/1*.cfg (for files that need to be processed BEFORE the OSG configuration) or
/etc/xrootd/config.d/9*.cfg (for files that need to be processed AFTER the OSG configuration).
You must configure every variable in
The mandatory variables to configure are:
set rootdir = /mnt/stash: the mounted filesystem path to export. This document refers to this as
set resourcename = YOUR_RESOURCE_NAME: the resource name registered with the OSG.
Ensure the xrootd service has a certificate¶
The service will need a certificate for reporting and to authenticate to origins. The easiest solution for this is to use your host certificate and key as follows:
- Copy the host certificate to
- Set the owner of the directory and contents
[email protected] # chown -R xrootd:xrootd /etc/grid-security/xrd/
You must repeat the above steps whenever you renew your host certificate.
If you automate certificate renewal, you should automate copying as well.
In addition, you will need to restart the XRootD services (
[email protected] and/or
so they load the updated certificates.
For example, if you are using Certbot for Let's Encrypt, you should write a "deploy hook" as documented
on the Certbot site.
Configuring Optional Features¶
Adjust disk utilization¶
To adjust the disk utilization of your cache, create or edit a file named
and set the values of
pfc.diskusage 0.90 0.95
The two values correspond to the low and high usage water marks, respectively. When usage goes above the high water mark, the XRootD service will delete cached files until usage goes below the low water mark.
Enable remote debugging¶
XRootD provides remote debugging via a read-only file system named digFS. This feature is disabled by default, but you may enable it if you need help troubleshooting your server.
To enable remote debugging, edit
/etc/xrootd/digauth.cfg and specify the authorizations for reading digFS.
An example of authorizations:
all allow gsi g=/glow h=*.cs.wisc.edu
See the XRootD manual for the full syntax.
Remote debugging should only be enabled for as long as you need assistance.
As soon as your issue has been resolved, revert any changes you have made to
Enable HTTPS on the unauthenticated cache¶
By default, the unauthenticated cache instance uses plain HTTP, not HTTPS. To use HTTPS:
Add a certificate according to the instructions above
set EnableVoms = 1in
Upgrading from OSG 3.5
If upgrading from OSG 3.5, you may have a file with the following contents in
# Support HTTPS access to unauthenticated cache if named stash-cache http.cadir /etc/grid-security/certificates http.cert /etc/grid-security/xrd/xrdcert.pem http.key /etc/grid-security/xrd/xrdkey.pem http.secxtractor /usr/lib64/libXrdLcmaps.so fi
You must delete this config block or XRootD will fail to start.
Manually Setting the FQDN (optional)¶
The FQDN of the cache server that you registered in Topology may be different than its internal hostname
(as reported by
For example, this may be the case if your cache is behind a load balancer such as LVS or MetalLB.
In this case, you must manually tell the cache services which FQDN to use for topology lookups.
- Create the file
/etc/systemd/system/stash-cache-authfile.service.d/override.confwith the following contents:
[Service] Environment=CACHE_FQDN=<Topology-registered FQDN>
Managing OSDF services¶
These services must be managed by
systemctl and may start additional services as dependencies.
As a reminder, here are common service commands (all run as
root) for EL7:
|To...||On EL7, run the command...|
|Start a service||
|Stop a service||
|Enable a service to start on boot||
|Disable a service from starting on boot||
Public cache services¶
||The XRootD daemon, which performs the data transfers|
||Reports usage information to collector.opensciencegrid.org|
|Required to authenticate monitoring services. See CA documentation for more info|
Authenticated cache services (optional)¶
In addition to the public cache services, there are three systemd units specific to the authenticated cache.
||Renew a proxy for authenticated downloads to the cache|
||The xrootd daemon which performs authenticated data transfers|
||Trigger daily proxy renewal|
||Generate the Authentication configuration file for XRootD|
||Periodically generate the Authentication configuration file for XRootD|
Validating the Cache¶
The cache server functions as a normal HTTP server and can interact with typical HTTP clients, such as
[email protected] $ curl -O http://cache_host:8000/osgconnect/public/rynge/test.data
curl may not correctly report a failure, so verify that the contents of the file are:
Test cache server reporting to the central collector¶
To verify the cache is reporting to the central collector, run the following command from the cache server:
[email protected] $ condor_status -any -pool collector.opensciencegrid.org:9619 \ -l -const "Name==\"[email protected]`hostname`\""
The output of the above command should detail what the collector knows about the status of your cache. Here is an example snippet of the output:
AuthenticatedIdentity = "[email protected]" AuthenticationMethod = "GSI" free_cache_bytes = 868104454144 free_cache_fraction = 0.8022261674321525 LastHeardFrom = 1552002482 most_recent_access_time = 1551997049 MyType = "Machine" Name = "[email protected]" ping_elapsed_time = 0.00763392448425293 ping_response_code = 0 ping_response_message = "[SUCCESS] " ping_response_status = "ok" STASHCACHE_DaemonVersion = "1.0.0" ...
Updating to OSG 3.6¶
The OSG 3.5 series has reached end-of-life on May 1, 2022. Admins are strongly encouraged to move their caches to OSG 3.6.
Unauthenticated caches (
[email protected] service) do not need any configuration changes,
unless HTTPS access has been enabled.
See the "enable HTTPS on the unauthenticated cache" section)
for the necessary configuration changes.