---
name: xcache
description: >-
  Use when planning or debugging an XCache proxy for repeated XRootD reads:
  choosing cache boundaries, routing root:// requests through the proxy,
  validating cache hits and bypass behavior, or handling credentials and
  storage limits safely.
---

# XCache

XCache is an XRootD caching proxy. Use it when repeated remote reads justify a
managed local cache; direct XRootD access is simpler for one-off or small jobs.

## Deployment invariants

- Configure explicit cache and data directories on storage intended for cache
  eviction. Do not point them at user source trees or irreplaceable data.
- Restrict who can reach the proxy and which upstream namespaces it may fetch.
- Size high/low watermarks and eviction policy for the available filesystem.
- Preserve the upstream `root://host//path` exactly when constructing the
  proxied request; use the deployment's documented proxy URI form.
- Pass credentials using the site's supported XRootD mechanism. Do not copy
  proxy files or bearer tokens into the plugin or cache directory.

## Validate behavior

1. Read a small authorized file directly from the upstream endpoint.
2. Read the same file through XCache and compare checksums or ROOT metadata.
3. Repeat the cached read and inspect server metrics or logs for a hit.
4. Test a missing or unauthorized path and confirm that it fails closed.
5. Test cache-full behavior before sending a large workload.

Record the proxy endpoint in job configuration rather than rewriting source
dataset identifiers permanently. Provide a documented bypass path so an
operator can distinguish cache failures from upstream storage failures.