Configure advanced cache settings

Caching service can be fine-tuned for your network configuration.

Set advanced configuration settings for Caching service using the command line or by modifying the value of keys in the /Library/Server/Caching/Config/Config.plist.

Note: Don’t change any settings in the Config.plist file other than the ones described below.

A key can have a value that’s clamped between two values. The value can be any number in the range between the low and high values. If the value is set below the lower-bound value, the lower-bound value is used. If it’s set above the upper-bound value, the upper-bound value is used. For example, PeerDownloadTimeout is clamped between 5 and 300, and can be set to any value in the range of 5 and 300. If it’s set to 301 or 1000, then the value is set to 300 instead. If the value is set to 4 or -10, then the value is set to 5 instead.

Key	Default	Description
CacheLimit	0 (unlimited)	The maximum number of bytes of disk space that will be used to cache assets. You can also set this value using the Server app.
DataPath	/Library/Server/Caching/Data	The path to the directory used to store cached assets. You can also set this path using the Server app.
Interface	listen on all interfaces	The BSD name of a network interface to be used by Caching service.
ListenRanges	none	An array of dictionaries describing the range of client IP addresses to serve.
ListenRangesOnly	false	If ListenRangesOnly is set to true, the server provides assets only to clients in the ranges specified by the ListenRanges key. You must specify the ListenRanges key to use the ListenRangesOnly key.
LogClientIdentity	false	Determines whether or not the server should log the IP address and port number of the client requesting each asset.
LogLevel	info	Set this to the level of items being logged. You can set this to any of the following: default off error warn info verbose Note: You should leave the logging level at the default setting on a production system; if you raise it, there may be a performance penalty. If you increase the logging level above the default, additional logging is saved to /Library/Server/Caching/Logs/Debug.log, and won’t appear in the Server app under the Logs section.
MaxConcurrentClients	0 (allow unlimited clients)	The maximum number of simultaneous client requests allowed.
MaxPeersToQuery	0 (unlimited)	The maximum number of peer caching servers to ask for each asset.
OriginDownloadTimeout	60	How long, in seconds, to allow a download from Apple’s servers to sit idle before giving up (and possibly trying the download again). Clamped between 5 and 300 seconds, inclusive.
PeerDownloadTimeout	30	How long, in seconds, to allow a download from a peer caching server to sit idle before giving up (and possibly trying the download again). Clamped between 5 and 300 seconds, inclusive.
PeerFilterRanges	none	When PeerFilterRanges is an array (of entries like those for ListenRanges) the caching server filters and sorts its list of peers according to the ranges in the array. The caching server will only query peers that are in the PeerFilterRanges. The filtering and sorting are applied before truncating the list of peers at MaxPeersToQuery entries (if that setting is present). When PeerFilterRanges is boolean true, the caching server does the same as the above but uses the ListenRanges rather than the PeerFilterRanges value. When PeerFilterRanges is any other type or value or is missing, the caching server neither filters nor sorts its list of peers before truncating the list at MaxPeersToQuery entries. PeerFilterRanges only affects the list of other servers this caching server queries for assets and downloads from. It has no effect on incoming requests for assets from any other caching servers.
PeerNotifyTimeout	30	How long, in seconds, to wait for replies from peer caching servers when “pinging” them on startup. Clamped between 5—300 seconds, inclusive.
PeerQueryTimeout	5	How long, in seconds, to wait for replies from peer caching servers when asking them about assets in their caches. Clamped between 1 and 60 seconds, inclusive.
PeerRetryInterval	60	How long, in seconds, to ignore peer caching servers after they have accrued three consecutive notify or query failures. After the retry interval has passed, peer caching servers are restored to the list of peers to query for assets. Clamped between 30 and 3600 seconds, inclusive.
Port	0 (use a random port)	The TCP port number on which Caching service accepts requests for downloads.
ReservedVolumeSpace	25000000000	The minimum number of bytes of free disk space to be maintained for the volume that stores the cached assets.

Key

Default

Description

CacheLimit

0 (unlimited)

The maximum number of bytes of disk space that will be used to cache assets. You can also set this value using the Server app.

DataPath

/Library/Server/Caching/Data

The path to the directory used to store cached assets. You can also set this path using the Server app.

Interface

listen on all interfaces

The BSD name of a network interface to be used by Caching service.

ListenRanges

none

An array of dictionaries describing the range of client IP addresses to serve.

ListenRangesOnly

false

If ListenRangesOnly is set to true, the server provides assets only to clients in the ranges specified by the ListenRanges key. You must specify the ListenRanges key to use the ListenRangesOnly key.

LogClientIdentity

false

Determines whether or not the server should log the IP address and port number of the client requesting each asset.

LogLevel

info

Set this to the level of items being logged. You can set this to any of the following:

default
off
error
warn
info
verbose

Note: You should leave the logging level at the default setting on a production system; if you raise it, there may be a performance penalty. If you increase the logging level above the default, additional logging is saved to /Library/Server/Caching/Logs/Debug.log, and won’t appear in the Server app under the Logs section.

MaxConcurrentClients

0 (allow unlimited clients)

The maximum number of simultaneous client requests allowed.

MaxPeersToQuery

0 (unlimited)

The maximum number of peer caching servers to ask for each asset.

OriginDownloadTimeout

How long, in seconds, to allow a download from Apple’s servers to sit idle before giving up (and possibly trying the download again). Clamped between 5 and 300 seconds, inclusive.

PeerDownloadTimeout

How long, in seconds, to allow a download from a peer caching server to sit idle before giving up (and possibly trying the download again). Clamped between 5 and 300 seconds, inclusive.

PeerFilterRanges

none

When PeerFilterRanges is an array (of entries like those for ListenRanges) the caching server filters and sorts its list of peers according to the ranges in the array.

The caching server will only query peers that are in the PeerFilterRanges. The filtering and sorting are applied before truncating the list of peers at MaxPeersToQuery entries (if that setting is present).

When PeerFilterRanges is boolean true, the caching server does the same as the above but uses the ListenRanges rather than the PeerFilterRanges value.

When PeerFilterRanges is any other type or value or is missing, the caching server neither filters nor sorts its list of peers before truncating the list at MaxPeersToQuery entries.

PeerFilterRanges only affects the list of other servers this caching server queries for assets and downloads from. It has no effect on incoming requests for assets from any other caching servers.

PeerNotifyTimeout

How long, in seconds, to wait for replies from peer caching servers when “pinging” them on startup. Clamped between 5—300 seconds, inclusive.

PeerQueryTimeout

How long, in seconds, to wait for replies from peer caching servers when asking them about assets in their caches. Clamped between 1 and 60 seconds, inclusive.

PeerRetryInterval

How long, in seconds, to ignore peer caching servers after they have accrued three consecutive notify or query failures. After the retry interval has passed, peer caching servers are restored to the list of peers to query for assets. Clamped between 30 and 3600 seconds, inclusive.

Port

0 (use a random port)

The TCP port number on which Caching service accepts requests for downloads.

ReservedVolumeSpace

25000000000

The minimum number of bytes of free disk space to be maintained for the volume that stores the cached assets.

You can use the ListenRanges key to specify preferred caching servers in advanced network topologies where multiple caching servers are used behind the same public IP address. For example:

caching1.example.com uses the ListenRanges key to specify a range of 10.0.0.1 through 10.0.0.254 and 10.1.0.1 through 10.1.0.254.

caching2.example.com uses the ListenRanges key to specify a range of 10.1.0.1 through 10.1.0.39 (note the overlap with the second range of caching1).

If a client whose IP address is 10.0.0.10 requests an asset, it’s directed to caching1.

If a client whose IP address is 10.1.0.10 requests an asset, it’s directed to either caching1 or caching2. The server is chosen randomly.

If a client whose IP address is 10.2.0.10 requests an asset, it’s directed to either caching1 or caching2. The server is chosen randomly.

If caching1 is shut down or loses power but caching2 remains available, all clients are directed to caching2.

To set a key with a simple value, use the serveradmin command. For example, to set the Interface key to en1, you would execute this command as an administrator:

sudo serveradmin settings caching:Interface = en1

The ListenRanges key has a complex value, making it easier to edit /Library/Server/Caching/Config/Config.plist to set the value. If you manually edit this file, be sure to set the user and group ownership to _assetcache before starting Caching service. For example:

sudo chown _assetcache:_assetcache /Library/Server/Caching/Config/Config.plist

Below is an example Config.plist file.

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0"><dict> <key>CacheLimit</key>  <integer>200000000000</integer> <string>/Volumes/BigDisk/Caching/Data</string> <key>Interface</key> <string>en1</string> <key>ListenRanges</key> <array> <dict> <key>type</key> <string>IPv4</string> <key>first</key> <string>10.1.2.1</string> <key>last</key> <string>10.1.2.254</string> </dict> <key>type</key> <string>IPv6</string> <key>first</key> <string>2001:500:88:200::1</string> <key>last</key> <string>2001:500:88:200::99</string> <dict> </dict> </array> <key>LogLevel</key> <string>verbose</string> <key>Port</key> <integer>12345</integer> <key>ReservedVolumeSpace</key>  <integer>1000000000</integer></dict></plist>