Running StashCache Cache in a Container¶
The OSG operates the StashCache data federation, which provides organizations with a method to distribute their data in a scalable manner to thousands of jobs without needing to pre-stage data across sites or operate their own scalable infrastructure.
Stash Caches transfer data to clients such as jobs or users. A set of caches are operated across the OSG for the benefit of nearby sites; in addition, each site may run its own cache in order to reduce the amount of data transferred over the WAN. This document outlines how to run StashCache in a Docker container.
Before starting the installation process, consider the following points:
- Docker: For the purpose of this guide, the host must have a running docker service
and you must have the ability to start containers (i.e., belong to the
- Network ports: Stash Cache listens for incoming HTTP/S connections on port 8000 (by default)
- File Systems: Stash Cache needs a partition on the host to store cached data
Configuring Stash Cache¶
In addition to the required configuration above (ports and file systems), you may also configure the behavior of your cache with the following variables using an environment variable file:
Where the environment file on the docker host,
/opt/xcache/.env, has (at least) the following contents
YOUR_SITE_NAME with the name of your site as
registered in Topology):
Further behavior of the cache can be configured by setting the following in the environment variable file:
XC_SPACE_LOW_WM: High-water and low-water marks for disk usage; when usage goes above the high-water mark, the cache will delete files until it hits the low-water mark.
XC_PORT: TCP port that XCache listens on
XC_RAMSIZE: Amount of memory to use for storing blocks before writting them to disk. (Use higher for slower disks).
XC_BLOCKSIZE: Size of the blocks in the cache.
XC_PREFETCH: Number of blocks to prefetch from a file at once. This controls how aggressive the cache is to request portions of a file. If you set it to
0, prefetching will be disabled, but that is not recommended.
Running a Cache¶
To run the container, use
docker run with the following options, replacing the text within angle brackets
with your own values:
[email protected] $ docker run --rm --publish <HOST PORT>:8000 \ --volume <HOST PARTITION>:/cache \ --env-file=/opt/xcache/.env \ opensciencegrid/stash-cache:stable
Running Stash Cache on container with systemd¶
An example systemd service file for Stash Cache.
This will require creating the environment file in the directory
This example systemd file assumes
<HOST PORT> is
<HOST PARTITION> is
Create the systemd service file
/etc/systemd/system/docker.stash-cache.service as follows:
[Unit] Description=Stash Cache Container After=docker.service Requires=docker.service [Service] TimeoutStartSec=0 Restart=always ExecStartPre=-/usr/bin/docker stop %n ExecStartPre=-/usr/bin/docker rm %n ExecStartPre=/usr/bin/docker pull opensciencegrid/stash-cache:stable ExecStart=/usr/bin/docker run --rm --name %n --publish 8000:8000 --volume /srv/cache:/cache --env-file /opt/xcache/.env opensciencegrid/stash-cache:stable [Install] WantedBy=multi-user.target
Enable and start the service with:
[email protected] $ systemctl enable docker.stash-cache [email protected] $ systemctl start docker.stash-cache
You must register the cache before considering it a production service.
For caches that are connected to NIC's over
40Gbps we recommend to disable the virtualized network and "bind" the container to the host network:
[email protected] $ docker run --rm \ --network="host" \ --volume <HOST PARTITION>:/cache \ --env-file=/opt/xcache/.env \ opensciencegrid/stash-cache:stable
The cache uses the host's memory for two purposes:
- Caching files recently read from disk (via the kernel page cache).
- Buffering files recently received from the network before writing them to disk (to compensate for slow disks).
An easy way to increase the performance of the cache is to assign it more memory.
If you set a limit on the container's memory usage via the docker option
--memory or Kubernetes resource limits,
make sure it is at least twice the value of
For caches that store over 10 TB or that have assigned space for storing the cached files over multiple partitions
/partition1, /partition2, ...) we recommend the following:
Create a config file
90-my-stash-cache-disks.cfgwith the following contents:
pfc.spaces data oss.space data /data1 oss.space data /data2 . . .
Run the container with the following options:
[email protected] $ docker run --rm --publish <HOST PORT>:8000 \ --volume <HOST PARTITION>:/cache \ --volume /partition1:/data1 \ --volume /partition2:/data2 \ --volume /opt/xcache/90-my-stash-cache-disks.cfg:/etc/xrootd/config.d/90-stash-cache-disks.cfg \ --env-file=/opt/xcache/.env \ opensciencegrid/stash-cache:stable
Under this configuration the
<HOST PARTITION> is not used to store the files.
Instead, the host partition stores symlinks to the files in
For over 100 TB of assigned space we highly encourage to use this setup and mount
<HOST PARTITION> in solid state disks or NVME.
Validating the Cache¶
The cache server functions as a normal HTTP server and can interact with typical HTTP clients, such as
<HOST PORT> is the port chosen in the
docker run command,
8000 by default.
[email protected] $ curl -O http://cache_host:<HOST PORT>/osgconnect/public/rynge/test.data
curl may not correctly report a failure, so verify that the contents of the file are: