Skip to content

Install XRootD Standalone

XRootD is a hierarchical storage system that can be used in many ways to access data, typically distributed among actual storage resources. In its standalone configuration, XRootD acts as a simple layer exporting data from a storage system to the outside world.

This document focuses on installing a default configuration of XRootD standalone that provides the following features:

  • Supports any POSIX-based storage system
  • Macaroons, X.509 proxy, and VOMS proxy authentication
  • Third-Party Copy over HTTP (HTTP-TPC)

Before Starting

Before starting the installation process, consider the following points:

  • User IDs: If it does not exist already, the installation will create the Linux user ID xrootd
  • Service certificate: The XRootD service uses a host certificate and key pair at /etc/grid-security/xrd/xrdcert.pem and /etc/grid-security/xrd/xrdkey.pem that must be owned by the xrootd user
  • Networking: The XRootD service uses port 1094 by default

As with all OSG software installations, there are some one-time (per host) steps to prepare in advance:

Installing XRootD

To install an XRootD Standalone server, run the following command:

root@xrootd-standalone # yum install osg-xrootd-standalone

Configuring XRootD

To configure XRootD as a standalone server, you will modify /etc/xrootd/xrootd-standalone.cfg and the config files under /etc/xrootd/config.d/ as follows:

  1. Configure a rootdir in /etc/xrootd/config.d/10-common-site-local.cfg, to point to the top of the directory hierarchy which you wish to serve via XRootD.

    set rootdir = <DIRECTORY>

    Carefully consider your rootdir

    Do not set rootdir to /. This might result in serving private information.

  2. If you want to limit the sub-directories to serve under your configured rootdir, comment out the all.export / directive in /etc/xrootd/config.d/90-osg-standalone-paths.cfg, and add an all.export directive for each directory under rootdir that you wish to serve via XRootD.

    This is useful if you have a mixture of files under your rootdir, for example from multiple users, but only want to expose a subset of them to the world.

    For example, to serve the contents of /data/store and /data/public (with rootdir configured to /data):

    all.export /store/
    all.export /public/

    If you want to serve everything under your configured rootdir, you don't have to change anything.


    The directories specified this way are writable by default. Access controls should be managed via authorization configuration.

  3. In /etc/xrootd/config.d/10-common-site-local.cfg, add a line to set the resourcename variable. Unless your supported VOs' policies state otherwise, this should match the resource name of your XRootD service. For example, the XRootD service registered at the University of Florida site should set the following configuration:

    set resourcename = UFlorida-XRD

Configuring authentication and authorization

XRootD offers several authentication options using security plugins to validate incoming credentials, such as bearer tokens, X.509 proxies, and VOMS proxies. Please follow the XRootD authorization documentation for instructions on how to configure authentication and authorization, including validating credentials and mapping them to users if desired.

Optional configuration

The following configuration steps are optional and will likely not be required for setting up a small site. If you do not need any of the following special configurations, skip to the section on using XRootD.

Enabling multi-user support

The xrootd-multiuser plugin allows XRootD to write files on the storage system as the authenticated user instead of the xrootd user. If your XRootD service only allows read-only access, you should skip installation of this plugin.

To set up XRootD in multi-user mode, install the xrootd-multiuser package:

root@xrootd-standalone # yum install xrootd-multiuser


If you are using XRootD-Multiuser with a VOMS FQAN, you need XRootD 5.5.0 or greater.

Throttling IO requests

XRootD allows throttling of requests to the underlying filesystem. To enable this,

  1. In an /etc/xrootd/config.d/*.cfg file, e.g. /etc/xrootd/config.d/99-local.cfg, set the following configuration:

    xrootd.fslib throttle default
    throttle.throttle concurrency <CONCUR> data <RATE>

    Replacing <CONCUR> with the IO concurrency limit, measured in seconds (e.g., 100 connections taking 1ms each, would be 0.1), and <RATE> with the data rate limit in bytes per second. Note that you may also just specify either the concurrency limit:

    xrootd.fslib throttle default
    throttle.throttle concurrency <CONCUR>

    Or the data rate limit:

    xrootd.fslib throttle default
    throttle.throttle data <RATE>
  2. If XRootD is already running, restart the relevant XRootD service for your configuration to take effect.

For more details of the throttling implementation, see the upstream documentation.

Enabling CMS TFC support (CMS sites only)

For CMS sites, there is a package available to integrate rule-based name lookup using a storage.xml file. If you are not setting up a service for CMS, skip this section.

To install an xrootd-cmstfc, run the following command:

root@xrootd-standalone # yum install --enablerepo=osg-contrib xrootd-cmstfc

You will need to add your storage.xml to /etc/xrootd/storage.xml and then add the following line to your XRootD configuration:

# Integrate with CMS TFC, placed in /etc/xrootd/storage.xml
oss.namelib /usr/lib64/ file:/etc/xrootd/storage.xml?protocol=hadoop

Add the orange text only if you are running hadoop (see below).

See the CMS TWiki for more information:

Using XRootD

In addition to the XRootD service itself, there are a number of supporting services in your installation. The specific services are:

Software Service Name Notes
Fetch CRL EL8,EL9: fetch-crl.timer
EL7: fetch-crl-boot and fetch-crl-cron
See CA documentation for more info
XRootD xrootd@standalone Primary xrootd service if not running in multi-user mode
XRootD Multi-user xrootd-privileged@standalone Primary xrootd service to start instead of xrootd@standalone if running in multi-user mode

Start the services in the order listed and stop them in reverse order. As a reminder, here are common service commands (all run as root):

To … Run the command…
Start a service systemctl start SERVICE-NAME
Stop a service systemctl stop SERVICE-NAME
Enable a service to start during boot systemctl enable SERVICE-NAME
Disable a service from starting during boot systemctl disable SERVICE-NAME

Validating XRootD

To validate an XRootD installation, perform the following verification steps:


If you have configured authentication/authorization for XRootD, be sure you have given yourself the necessary permissions to run these tests. For example, if you are using an X.509 proxy, make sure your DN is mapped to a user in /etc/grid-security/grid-mapfile, make sure you have a valid proxy on your local machine, and ensure that the Authfile on the XRootD server gives write access to the mapped user from /etc/grid-security/grid-mapfile.

  1. Verify authorization of bearer tokens and/or proxies

  2. Verify HTTP-TPC using the same GFAL2 client tools:

    Requires gfal2 >= 2.20.0

    gfal2-2.20.0 contains a fix for a bug affecting XRootD HTTP-TPC support.

    1. Copy a file from your XRootD standalone host to another host and path where you have write access:

      root@xrootd-standalone # gfal-copy davs://localhost:1094/<PATH TO LOCAL FILE> \
                                         <REMOTE HOST>/<PATH TO WRITE REMOTE FILE>

      Replacing <PATH TO LOCAL FILE> with the path to a file that you can read on your host relative to rootdir; <REMOTE HOST> with the protocol, FQDN, and port of the remote storage host; and <PATH TO WRITE REMOTE FILE> to a location on the remote storage host where you have write access.

    2. Copy a file from a remote host where you have read access to your XRootD standalone installation:

      root@xrootd-standalone # gfal-copy <REMOTE HOST>/<PATH TO REMOTE FILE> \
                                         davs://localhost:1094/<PATH TO WRITE LOCAL FILE>

      Replacing <REMOTE HOST> with the protocol, FQDN, and port of the remote storage host; <PATH TO REMOTE FILE> with the path to a file that you can read on the remote storage host; and <PATH TO WRITE LOCAL FILE> to a location on the XRootD standalone host relative to rootdir where you have write access.

Registering an XRootD Standalone Server

To register your XRootD server, follow the general registration instructions here with the following XRootD-specific details:

  1. Add an XRootD component: section to the Services: list, with any relevant fields for that service. This is a partial example:

      XRootD component:
        Description: Standalone XRootD server

    Replacing <FULLY QUALIFIED DOMAIN NAME> with your XRootD server's DNS entry.

  2. If you are setting up a new resource, set Active: false. Only set Active: true for a resource when it is accepting requests and ready for production.

Getting Help

To get assistance. please use the Help Procedure page.


Service Configuration

The configuration that your XRootD service uses is determined by the service name given to systemctl. To use the standalone config, you would start XRootD with the following command:

root@host # systemctl start xrootd@standalone

File locations

Service/Process Configuration File Description
xrootd /etc/xrootd/xrootd-standalone.cfg Main XRootD configuration
/etc/xrootd/config.d/ Drop-in configuration dir
/etc/xrootd/auth_file Authorized users file
Service/Process Log File Description
xrootd /var/log/xrootd/standalone/xrootd.log XRootD server daemon log
Back to top