Configure advanced content caching settings on Mac
You can use advanced configuration parameters to fine-tune content caching for your network configuration.
You set advanced configuration parameters for the content cache either by using the command line in Terminal or by modifying the value of keys in the /Library/Preferences/com.apple.AssetCache.plist file. For some changes to take effect, content caching must be stopped and restarted.
Use Terminal to set advanced configuration parameters
In the Terminal app 
on your Mac, you can set advanced configuration parameters using the defaults command, followed by the command sudo AssetCacheManagerUtil reloadSettings. Use the command AssetCacheManagerUtil settings to view the standard (nonadvanced) settings.
For more information about the AssetCacheManagerUtil command, see Manage content caching from the command line and the AssetCacheManagerUtil(8) man page.
You can set both simple and complex keys with the defaults command.
For example, to set the Interface key to en1, execute this command as an administrator:
$ sudo -u _assetcache defaults write /Library/Preferences/com.apple.AssetCache.plist Interface -string en1ListenRanges is a complex key that takes an array of dictionaries. For example, execute this command as an administrator to set two IP address ranges for the ListenRanges key:
$ sudo -u _assetcache defaults write /Library/Preferences/com.apple.AssetCache.plist ListenRanges '( { first = 10.0.0.1; last = 10.0.0.254; }, { first = 10.1.0.1; last = 10.1.0.254; } )'After using the defaults command, be sure to run the following command to reload the content cache settings:
$ sudo AssetCacheManagerUtil reloadSettingsFor more information about the defaults command, see the defaults(1) man page.
Caching configuration plist keys and values
Important: Don’t change any settings in the com.apple.AssetCache.plist file other than the ones described in the table below.
A key can have a value that’s clamped between two values. The key value can be any number in the range between the low and high values. If it’s 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. If it’s set to 301 or 1000, then the value is set to 300. If it’s set to 4 or -10, then the value is set to 5.
Some changes take effect after you run AssetCacheManagerUtil reloadSettings; others require that you stop and then restart content caching. The only keys that support reloadSettings are those that can also be set in Content Caching preferences (noted in the table below). To set values in Content Caching preferences, choose Apple menu 
> System Preferences, click Sharing, then click Content Caching.
Key | Description | Default | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
AgeForLowSpaceAlert | When content is purged from the content cache because it’s low on disk space, and the purged content was added to the content cache less than this many days ago, you receive a low space alert. | 30 (days) | |||||||||
AllowCacheDelete | Allow content to be purged from the cache automatically when the computer needs disk space for other apps. | Yes | |||||||||
AllowImports | Allow import (upload) requests. | Yes | |||||||||
AllowPersonalCaching | Allow the caching of users’ iCloud data. At least one of the AllowPersonalCaching or AllowSharedCaching keys must be yes. You can also set this value in Content Caching preferences. | Yes | |||||||||
AllowSharedCaching | Controls the caching of non-iCloud content, such as apps and software updates. At least one of the AllowPersonalCaching or AllowSharedCaching keys must be yes. | Yes | |||||||||
AllowWirelessPortable | Allow portable computers that have only Wi-Fi network connections to run content caching. | Yes | |||||||||
CacheLimit | The maximum number of bytes of disk space that will be used for the content cache. You can also set this value in Content Caching preferences. | 0 (unlimited) | |||||||||
DatabaseUpdateInterval | How often the content cache saves changes to its on-disk database. Raising the interval increases the risk of losing cached content after a power failure. The maximum is 3600 seconds (1 hour). An interval of 0 means always update the database immediately, with no delay, which decreases performance. | 5 (seconds) | |||||||||
DataPath | The path to the directory used to store cached content. Changing this setting manually does not automatically move cached content from the old to the new location. To move content automatically, use Content Caching preferences (see Select a volume for caching). You can also set this value in Content Caching preferences. | /Library/Application Support/Apple/AssetCache/Data | |||||||||
DownloadMinRate | The minimum number of bytes per second clients must sustain while downloading content from the content cache. The content cache stops downloads that transfer data slower than this rate. Clamped minimum is 1000 bytes per second. | 8000 (bytes per second) | |||||||||
DownloadTimeout | How long, in seconds, to allow a download to a client to sit idle before giving up. Clamped minimum is 10 seconds. | 180 (seconds) | |||||||||
ImportMaxRate | The maximum number of bytes per second at which the content cache receives data from each client. A value of 0 indicates an unlimited number of bytes per second. | 0 (bytes per second) | |||||||||
ImportMinRate | The minimum number of bytes per second that clients must sustain while importing (uploading) content. The content cache stops imports that transfer data slower than this rate. The minimum rate is 100 bytes per second. | 2000 (bytes per second) | |||||||||
ImportRateAttenuation | The percentage of attenuation added to the upload time. Clamped minimum is 0% attenuation. Values too large will exceed the ImportTimeout and cause failures. | .20 (percentage) | |||||||||
ImportTimeout | How long, in seconds, to allow an import (upload) from a client to sit idle before giving up. The minimum is 10 seconds. | 300 (seconds) | |||||||||
Interface | The BSD name of a network interface to be used by the content cache. | Listen on all interfaces | |||||||||
ListenRanges | An array of dictionaries describing the range of client IP addresses to serve. See below for an example using the ListenRanges key. You can also set this value in Content Caching preferences. | none | |||||||||
ListenRangesOnly | If ListenRangesOnly is set to true, the content cache provides content only to clients in the ranges specified by the ListenRanges key. If you want to use the ListenRangesOnly key, you must also specify the ListenRanges key. You can also set this value in Content Caching preferences. | No | |||||||||
ListenWithPeersAndParents | Indicates whether content caching registers with the union of the ListenRanges, PeerListenRanges, and Parents keys, or only with the ListenRanges key. Note that ListenRanges could be automatically generated from LocalSubnetsOnly, and PeerListenRanges could be automatically generated from PeerLocalSubnetsOnly. | The default value depends on the history of the computer:
| |||||||||
LocalSubnetsOnly | Whether or not the content cache should offer content only to clients on the same immediate local network as the content cache, rather than to clients on all local networks reachable by the content cache. You can also set this value in Content Caching preferences. | Yes | |||||||||
LogClientIdentity | Determines whether or not the content cache should log the IP address and port number of the clients that request content. | No | |||||||||
MaxConcurrentClients | This limit is to prevent content caching from running out of file descriptors. Apple does not guarantee that a content cache can achieve 3400 concurrent clients. | 3400 | |||||||||
MaxParentDepth | The maximum number of times, for a single request, that a child content cache will forward the request to a parent content cache. Requests that are too deep (forwarding chain is too long) are forced to the origin rather than to a parent. | 8 | |||||||||
MaxPeersToQuery | The maximum number of peer content caches to ask for content. | 0 (unlimited) | |||||||||
MetricsInterval | How often, in seconds, to add a row of metrics to the metrics database in /Library/Application Support/Apple/AssetCache/Metrics/Metrics.db.
Clamped between 1-60 seconds, inclusive. You can view these metrics in the Cache pane of Activity Monitor. | 60 (seconds) | |||||||||
MetricsMaxAge | Metrics that are older than this are removed from the metrics database, once per day. Clamped minimum is 30 days. | 30 (days) | |||||||||
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. | 60 | |||||||||
OriginUploadTimeout | How long, in seconds, to allow an upload to an origin server to sit idle before giving up. Clamped between 5 and 3600 seconds, inclusive. | 600 | |||||||||
ParentDownloadTimeout | How long, in seconds, to allow a download from a parent content cache to sit idle before giving up (and possibly trying the download again). Clamped between 5-300 seconds, inclusive. | 60 | |||||||||
ParentRetryInterval | How long, in seconds, to ignore parent content caches after they have accrued five consecutive network failures or server errors. Clamped between 30-3600 seconds, inclusive. | 900 | |||||||||
Parents | A list of the local IP addresses of other content caches from which this cache should download or upload content instead of downloading from or uploading to Apple directly. Invalid addresses and addresses of computers that are not content caches are ignored. Parent caches that become unavailable are skipped according to the ParentRetryInterval. If all parent content caches become unavailable, the content cache will download from or upload to Apple directly until a parent content cache becomes available again. You can also set this value in Content Caching preferences. | none | |||||||||
ParentSelectionPolicy | The policy to use when choosing among more than one configured parent content cache. With every policy, parent caches that are temporarily unavailable are skipped. The policies are:
You can also set this value in Content Caching preferences. | round-robin | |||||||||
ParentUploadTimeout | How long, in seconds, to allow an upload to a parent content cache to sit idle before giving up. Clamped between 5-3600 seconds, inclusive. | 600 | |||||||||
PeerDownloadTimeout | How long, in seconds, to allow a download from a peer content cache to sit idle before giving up (and possibly trying the download again). Clamped between 5 and 300 seconds, inclusive. | 30 | |||||||||
PeerFilterRanges | When PeerFilterRanges is an array (of entries like those for ListenRanges), the content cache filters and sorts its list of peers according to the ranges in the array. The content cache only queries 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 an empty array, the content cache will not query any peers. When PeerFilterRanges is Boolean true, the content cache does the same as above, but uses the ListenRanges rather than the PeerFilterRanges value. When PeerFilterRanges is any other type or the value is missing, the content cache neither filters nor sorts its list of peers before truncating the list at MaxPeersToQuery entries. PeerFilterRanges only affects the list of other content caches this content cache queries for content and downloads. It has no effect on incoming requests for content from any other content cache. You can also set this value in Content Caching preferences. | none | |||||||||
PeerListenRanges | When PeerListenRanges is an array of dictionaries where each dictionary represents an IP address range, the content cache will only successfully respond to peer cache queries from content caches with an IP address contained within this array of ranges. When PeerListenRanges is an empty array, the content cache will respond with an error to cache queries from any other content cache. When PeerListenRanges is Boolean true, the content cache will use the ListenRanges value rather than the PeerListenRanges value to decide which other content caches it will successfully respond to cache queries from. When PeerListenRanges is any other type or the value is missing, the content cache will successfully respond to cache queries from all other content caches. PeerListenRanges only affects which content caches this content cache will successfully respond to cache queries from. It has no effect on the list of peers this content cache will query for content and download content from. When a content cache responds with an error from a cache query, the querying content cache marks the responding content cache as unfriendly and does not attempt to query it again until the PeerRetryInterval has elapsed. You can also set this value in Content Caching preferences. | none | |||||||||
PeerLocalSubnetsOnly | Whether or not the content cache should only peer with other content caches on the same immediate local network, rather than with content caches that use the same public IP address as this computer. When PeerLocalSubnetsOnly is true, the content cache only queries and successfully responds to peer queries from content caches on the same immediate local network. When PeerLocalSubnetsOnly is true, it overrides the configuration of PeerFilterRanges and PeerListenRanges. When PeerLocalSubnetsOnly is false, the content cache defers to PeerFilterRanges and PeerListenRanges for configuring the peering restrictions. When PeerLocalSubnetsOnly is true and the network changes, the local network peering restrictions update appropriately. You can also set this value in Content Caching preferences. | Yes | |||||||||
PeerNotifyTimeout | How long, in seconds, to wait for replies from peer content caches when pinging them on startup. Clamped between 5 and 300 seconds, inclusive. | 30 | |||||||||
PeerQueryTimeout | How long, in seconds, to wait for replies from peer content caches when asking them about content in their caches. Clamped between 1 and 60 seconds, inclusive. | 5 | |||||||||
PeerRetryInterval | How long, in seconds, to ignore peer content caches after they have accrued three consecutive notify or query failures. After the retry interval has passed, peer content caches are restored to the list of peers to query for content. Clamped between 30 and 3600 seconds, inclusive. | 900 (seconds) | |||||||||
PersonalCacheLimit | Limit how much disk space the content cache uses for cached iCloud data, in bytes. The PersonalCacheLimit must not exceed CacheLimit. | 0 (unlimited) | |||||||||
Port | The TCP port number on which content caching accepts requests for uploads or downloads. | 0 (use a random port) | |||||||||
PruneAffinitiesAge | User affinities older than this number of days are removed from the affinities cache automatically. User affinities provide hints to clients as to where their content is cached, for improved performance. Pruning user affinities has no effect on cached content. Clamped minimum is 7 days. | 30 (days) | |||||||||
PruneAffinitiesInterval | How often, in days, the content cache should scan for and remove user affinities older than PruneAffinitiesAge days. User affinities, used only by iCloud, provide hints to clients as to where their content is cached, for improved performance. Pruning user affinities has no effect on cached content. Clamped minimum is one day. | 7 (days) | |||||||||
PruneAssetsAge | Content that has not been requested in this number of days is removed from the content cache automatically. Clamped minimum is 7 days. | 120 (days) | |||||||||
PruneAssetsInterval | How often, in days, the content cache should scan for and remove content older than PruneAssetsAge days. Clamped minimum is one day. | 7 (days) | |||||||||
PublicRanges | Ranges of public IP addresses the cloud servers should use for matching clients to content caches. You can also set this value in Content Caching preferences. | no default | |||||||||
ReservedVolumeSpace | The minimum number of bytes of free disk space to be maintained for the volume that stores the cached content. | 2000000000 (2 GB) | |||||||||
TerminationTimeout | How long, in seconds, the content cache should try to deregister when it is being stopped. Deregistering informs clients that the content cache is no longer available so they won’t try to use that content cache anymore (or until the content cache is started again). Clamped between 1 and 60 seconds, inclusive. | 10 (seconds) | |||||||||
Verbose | When Verbose=true the content cache logs a little more information about its activities. The increased logging can reduce performance. This setting is not recommended for long-term use. Use the For example: You can also use the Console app to view the logs. | No | |||||||||
ListenRanges key example
You can use the ListenRanges key to specify preferred content caches in advanced network topologies where multiple content caches 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, and sets the ListenRangesOnly key to No.
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), and sets the ListenRangesOnly key to No.
If a client whose IP address is 10.0.0.10 requests content, it’s directed to caching1.
If a client whose IP address is 10.1.0.10 requests content, it’s directed to either caching1 or caching2, selected randomly.
If a client whose IP address is 10.2.0.10 requests content, it’s directed to either caching1 or caching2, selected randomly.
If caching1 is shut down or loses power but caching2 remains available, all clients are directed to caching2.
Example plist file
The following is an example /Library/Preferences/com.apple.AssetCache.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> <!-- Set a CacheLimit of 200 GB --> <integer>200000000000</integer> <key>DataPath</key> <string>/Volumes/BigDisk/Library/Application Support/Apple/AssetCache/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> <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> </array> <key>LogClientIdentity</key> <string>true</string> <key>Port</key> <integer>12345</integer> <key>ReservedVolumeSpace</key> <!-- Set the ReservedVolumeSpace to 1 GB --> <integer>1000000000</integer></dict></plist>