Target audience: Workspace administrators

Overview

TeamCache is a read-through cache that sits on your local network between LucidLink clients and cloud object storage. The first client to read a file pulls it from the cloud through the cache. Every following read of that file is served from the cache's local disk.

You install TeamCache on a dedicated Linux server with the teamcache package. The package starts a guided setup wizard that validates your license, sets the listening port, prepares cache storage, starts the TeamCache service, and runs a health check.

Frequently Asked Questions

What if the wizard fails? The package stays fully installed, never half-configured. Fix the problem and run sudo teamcache-setup again.

Will the wizard open my firewall? No. It prints a reminder to allow incoming traffic on the cache port from your LucidLink clients. You add the rule yourself.

Does the wizard reuse my existing cache? Yes. If you re-run the wizard with the same directory or disk from a previous run, the wizard detects and reuses the same storage. It does not proactively choose storage based on prior decisions.

Do I have to re-run the wizard when I upgrade? No. Installing a newer package leaves the service running with its existing port and storage, and the wizard does not start. If the upgrade ships a new cache configuration, run sudo systemctl reload teamcache to pick it up.

Prerequisites

• A dedicated Linux server with systemd and root access (sudo). TeamCache is tested on Ubuntu 24.04 and Rocky Linux 9. Use the .deb package on Ubuntu and Debian, and the .rpm package on RHEL, Rocky Linux, and AlmaLinux.

• Architecture: x86_64 and arm64

• A LucidLink filespace on S3 storage, in a workspace whose subscription includes TeamCache.

• Cache storage: a directory with at least 20 GB free, or a dedicated empty disk of at least 20 GB.

• A free TCP port for clients (default: 80).

Setting up TeamCache

Download the TeamCache package for your distribution from the LucidLink support page, copy it to your server, then install it:

https://www.lucidlink.com/download/teamcache-rpm
https://www.lucidlink.com/download/teamcache-deb

# Ubuntu / Debian
sudo apt install ./teamcache_<version>_all.deb

# RHEL / Rocky / AlmaLinux
sudo dnf install ./teamcache-<version>-1.noarch.rpm

On an interactive installation, the wizard starts automatically. Otherwise, you see Package installed. Run 'sudo teamcache-setup' to configure. and you run sudo teamcache-setup yourself.

The wizard runs six steps in order and stops at the first failure. Prompts that take a value allow three attempts. Press Enter to accept a default.

1. Check prerequisites: No input is needed.

2. Validate license: Enter the path to your .lic file, or press Enter to use defaults.

3. Configure port: Enter the port clients will connect to, or press Enter for 80. If another program uses the port, the wizard names it and asks again. If the port is already held by TeamCache itself, the wizard recognises it and continues successfully. Make sure your firewall allows this port.

4. Configure storage: Choose directory mode or raw disk mode.

   1. Directory mode (default): Enter an absolute path. The cache is created in a teamcache subfolder. The provided directory must exist, must not be on tmpfs, and there has to be at least 20 GB free storage. The wizard reserves 10% of the filesystem (at least 10 GB) for the operating system and uses most of the rest for the cache.

   2. Raw disk mode: Enter y, then select a disk from the list. The wizard offers only disks of at least 20 GB, and hides system, boot, swap, LVM, and RAID disks. It formats the disk, mounts it at /cache/disk1, and gives 98% of it to the cache.

1. Start cache: The wizard installs and starts the teamcache service and enables it at boot.

2. Health check: The wizard runs teamcache-health and prints a report. Health warnings do not fail the setup.

When all steps finish, you see Setup complete. and the cache is ready for clients.

Connecting clients

First confirm TeamCache is enabled for the filespace:

lucid config --hidden

If the result for TeamCache.Enabled is 0, the workspace subscription does not include TeamCache. Contact your LucidLink account representative before going further.

Then set the cache address on each LucidLink client (--global) or only on the current client (--local) that should use the cache:

lucid config --set [--global/--local] --TeamCache.Location <cache-address>

The address can be an IP address or a host name. Add the port when it is not 80, for example 10.0.0.5:8080. Confirm the setting by checking the effective value for TeamCache.Location – lucid config --effective.

After installation

Check health. Run sudo teamcache-health for a PASS/WARN/FAIL report, grouped by area: service, license, process health, cache, storage, backend, threads and sessions, system, and connectivity. It ends with a summary line in the form PASS — X passed, Y warnings, Z failures (N checks), saves a full report to /var/log/teamcache/health-<timestamp>.txt. It must be run as root.

Manage the service. Use sudo systemctl status|start|stop|restart teamcache. The service restarts automatically on failure and starts on boot. Restarting the service does not clear cached content — objects remain available after restart.

Change settings. Run sudo teamcache-setup again to change the license, port, or storage. It repeats all six steps. Storage that is already configured is detected and reused, and the service is restarted with the new settings.

Renew the license. The licenses are time-bound. An expired license stops the cache from starting, so renew before the expiry date and re-run sudo teamcache-setup to install the replacement file.

Upgrade. Install the newer package the same way you installed the first one. The wizard does not run, and the service keeps its port, storage, and cached content. You do not need to re-run sudo teamcache-setup if TeamCache is already set up and working. To apply an updated cache configuration, run sudo systemctl reload teamcache. The reload has no effect on other changes.

Uninstall. Run sudo apt remove teamcache or sudo dnf remove teamcache. This removes only the setup and health commands. The cache service keeps running, and its configuration and data stay on disk. To stop the cache, run sudo systemctl disable --now teamcache.

Troubleshooting

• No license file found or License missing required field: Check that the license is indeed on the provided path and that its contents match exactly the license you were provided.

• Port is already in use: Stop the listed process or choose another port.

• Directory is on tmpfs — will not survive a reboot or Not enough free space: Choose a directory on a persistent disk with at least 20 GB free, or use a dedicated disk.

• No suitable disks found: Raw disk mode lists only unused disks of 20 GB or more. Attach a suitable disk or use directory mode.

• Confirmation not matched — aborting: The raw disk confirmation must match exactly, including case and the device name, with no trailing space. Re-run sudo teamcache-setup and type it as shown.

• Too many attempts: A value prompt was answered incorrectly three times. Re-run sudo teamcache-setup.

• Failed to start teamcache: Run sudo journalctl -u teamcache. An invalid or expired license is the usual cause. Fix it and re-run the wizard.

Related articles

• What is LucidLink TeamCache?

• Pre-Hydrate Files into TeamCache

• Adjust filespace settings (cache size and location)