Managing XNAT Cache and Temp Storage

The data lifecycle in XNAT often generates temporary or cached files as part of processing operations or workflows. These temporary or cached files can be useful for forensics or data security purposes. For example, failed anonymization operations can be analyzed with the help of the DICOM files generated by the operations. Files deleted by users may be stored outside of the archive and available for recovery if deleted by mistake. The downside of these temporary or cached files is that they can accumulate in various locations on your server's back-end storage, decreasing the available space for storing archive data and, in the worst-case scenario, leading to system errors and crashes from a lack of space available on the storage device.

An upcoming release of XNAT will include services to manage these temporary storage and cache folders.Until that service is available, this page provides a reference to these temporary and cache folders, as well as how to manage data stored in them without interfering with XNAT's on-going operations.

The primary temporary and cache storage locations on a standard XNAT include:

Application cache

The application cache is XNAT's primary cache location. The path to this folder is stored in the site preference cachePath. This folder may contain a number of files and subfolders depending on the version of your XNAT and what types of operations have been performed on it. These may include:

Group permissions queries. These are named in the form group-perms-groupId.sql. These are saved for diagnostics and can be deleted without issue. Starting with 1.8.5, XNAT will no longer write these files (you can have XNAT write these queries to standard logs by setting the log level for the org.nrg.xdat.security package to TRACE or by adding a logger just for org.nrg.xdat.security.UserGroupManager and setting that to TRACE; the first is easier, but may generate far too many log entries from other classes in and under that package).
Prearchive lock folders. The top-level folder for prearchive locks is named prearc_locks and can be found directly under the application cache folder. The folders under there are structured the same as within the prearchive: projectId/yyyyMMdd_HHmmssSSS/experimentLabel. For a session labeled Project_01_01_MR_01 in the project Project_01, this would be something like Project_01/20220120_232447819/Project_01_01_MR_01. Generally these folders should be cleaned up and/or contain very little data. As long as the corresponding prearchive entry has either been built (i.e. its status is READY) or archived (no longer even in the prearchive), you can delete the lock folder.
Project-specific folders for merge operations when archiving a session from the prearchive. These can be found under the primary cache folder and are named with the project ID. You can safely delete these folders as long as they are empty and the corresponding session has either been archived or is not currently archiving.

Deleted file cache

XNAT uses the deleted cache file to store files from deleted image sessions when the following conditions are met:

The session is deleted with the removeFiles parameter set to true
The site preference backupDeletedToCache is set to true

In that case, instead of deleting the files for the deleted session, XNAT moves them to a folder named DELETED under the application cache folder in a subfolder named with the current date in the form yyyyMMdd/HHmmssSSS. For example, if your application cache is set to the default of /data/xnat/cache, the folder would be something like /data/xnat/cache/DELETED/20220124/134227723.

For the standard XNAT REST API calls to delete an image session (e.g. DELETE /data/experiments/experimentId), if the removeFiles parameter is set to false or not specified at all, the image session is deleted from the database, but all associated files are left in place in the archive storage.

If removeFiles parameter is set to true and backupDeletedToCache is set to false, all associated files are deleted from the archive storage, with no option to recover them.

Backing up "deleted" files to the cache provides security against accidental deletion of data. However it can also result in a great deal of data piling up in the deleted file cache. You can check how much data is in the deleted file cache with something like this:

BASH

# du -sh /data/xnat/cache/DELETED
87M     /data/xnat/cache/DELETED

If you find the deleted file cache taking up too much space, you can safely delete any folders contained in there once you've reviewed the data to ensure it was intentionally and properly deleted. The deleted file cache is strictly for preservation: XNAT itself never references this cache or its contents.

You can also set up a cron task or similar scheduled job to delete any folders in the deleted file cache older than some expiration period. For example, if you wanted to delete anything older than a month, you could add a script to /etc/cron.daily with something like this:

CODE

find /data/xnat/cache/DELETED -mindepth 1 -maxdepth 1 -type d ! -newermt "$(date +"%Y-%m-%d %H:%M:%S" -d "1 month ago")" | while read FOLDER; do
    rm -rf ${FOLDER}
done

Alternatively, you could have a command that finds folders older than a month and sends an email to alert you, one that only alerts you when the amount of data stored in the deleted file cache exceeds a certain threshold, or any other alert or handling function you might need.

User caches

User caches are stored under the application cache folder in the subfolder USERS. When a user performs an operation that uses the user cache, XNAT creates a folder under the USERS folder using the ID of the row in the xdat_user table. What is stored underneath that is dependent on the particular operation using the cache. For example, uploaded CSV files may be converted to XML, resource catalogs may be copied and merged, etc.

Build folders

XNAT uses the build folder to store intermediate files for data processing. These intermediate files may be worth retaining for forensics purposes, but this depends on the processing being performed.

The build folder is used extensively for operations by the XNAT pipeline engine and container service. If you use either of these frequently, you will want to monitor the data stored in your build folder.

Anonymization backup folder

XNAT uses the anonymization backup folder to store the results from running anonymization scripts on DICOM data. If the anonymization operation is successful, the corresponding folder should be deleted upon completion. These folders are only retained when anonymization fails for some reason.

XNAT creates the anonymization backup folder with the name anon_backup under the temporary directory. On older systems this usually means /tmp, but if you are running XNAT on a system that uses systemd for service management, Tomcat is usually configured to use a private tmp space. These folders can be found under /tmp, with names like this:

CODE

systemd-private-2f651bf4587740dba1f04044963f6539-tomcat9.service-OfVqAh

The name always starts with systemd-private, then the boot ID (as found in /proc/sys/kernel/random/boot_id), then the service name (in this case, tomcat9.service), then a random six-character hash. These private tmp spaces are directly accessible only to root users, so if you need to inspect the contents directly you'll need to use sudo.

If errors occur frequently during anonymization, this folder can accumulate a lot of data quickly, especially if you're working with large sessions. You can delete unwanted data directly by using sudo to gain root access, then deleting the contents of anon_backup as appropriate. Or, because the private tmp spaces are deleted when a service is stopped, you can simply stop and restart your Tomcat service if you're using a systemd-based service.

Work folder

The work folder is located under the XNAT home folder, e.g. /data/xnat/home/work. Generally this folder doesn't accumulate much extraneous data. The most common files found here include:

XNAT and Hibernate caches and locks, which are stored under work/cache/xnat and work/cache/hbm respectively
Transitory storage space for incoming multipart form data, stored under work/xnat_nnn, where nnn is a long numeric string
Logger configuration conversions for XNAT plugins, stored under work/logback-nnn, where nnn is a long numeric string

You can safely delete all of the contents of the work folder with XNAT shut down.