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.
Set advanced settings
You can configure some advanced settings for the content caching service by going to System Settings (macOS 13 or later) or System Preferences (macOS 12.0.1 or earlier) > Sharing > Content Caching. Then press and hold the Option key and select Advanced Options.
You can configure even more advanced settings with the Terminal app on your Mac using the defaults command, followed by the command sudo AssetCacheManagerUtil reloadSettings. Use the command AssetCacheManagerUtil settings to view the standard (nonadvanced) settings.
You can set both simple and complex keys with the defaults command.
For example, to hard code the port number (50000) to a non-dynamic port number, the port number should be any number between 49192 to 65535, execute this command as an administrator:
$ sudo -u _assetcache defaults write /Library/Preferences/com.apple.AssetCache.plist Port -int 50000ListenRanges 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 reloadSettingsCaching 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:
macOS 13 or later: Choose Apple menu > System Settings > General > Sharing > Content Caching.
macOS 12.0.1 or earlier: Choose Apple menu > System Preferences > Sharing > Content Caching.
Key | Description | Default value | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
AgeForLowSpaceAlert | Alerts you when content is purged from the content cache because it’s low on storage 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 | Allows content to be purged from the cache automatically when the computer needs storage space for other apps. For best effectiveness of content caching, turn this setting off. | Yes | |||||||||
AllowImports | Allows import (upload) requests. | Yes | |||||||||
AllowPersonalCaching | Allows 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 settings. | 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 | Allows Mac laptop computers that have only Wi-Fi network connections to run content caching. | Yes | |||||||||
CacheLimit | Specifies the maximum number of bytes of storage space used for the content cache. You can also set this value in Content Caching settings. | 0 (unlimited) | |||||||||
DatabaseUpdateInterval | Specifies how often the content cache saves changes to its on-storage 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 | Specifies the path to the directory used to store cached content. Changing this setting manually doesn’t automatically move cached content from the old to the new location. To move content automatically, use Content Caching settings. You can also set this value in Content Caching settings. | /Library/Application Support/Apple/AssetCache/Data | |||||||||
DisplayAlerts | Displays notifications for content caching alerts. For best effectiveness of content caching, turn this setting on. | No | |||||||||
DownloadMinRate | Specifies 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 | Specifies 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 | Specifies 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 | Specifies 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 | Specifies the percentage of attenuation added to the upload time. Clamped minimum is 0% attenuation. Values too large exceed the ImportTimeout and cause failures. | .20 (percentage) | |||||||||
ImportTimeout | Specifies 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 | Specifies the BSD name of a network interface to be used by the content cache. For example, en0. Also always listens on the loopback interface (localhost). | Listen on the selected interface | |||||||||
KeepAwake | Keeps the computer awake when content caching is on. For best availability of content caching, turn this setting on. Select the “Prevent computer from sleeping automatically when the display is off” checkbox in Energy Saver in System Settings (in macOS 13 or later) or in System Preferences (in macOS 12.0.1 or earlier). | No | |||||||||
ListenRanges | An array of dictionaries describing the range of client IP addresses to serve. See below for an example using the ListenRanges key. The type subkey is no longer necessary and is ignored if present. You can also set this value in Content Caching settings. | 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 settings. | No | |||||||||
ListenWithPeers AndParents | 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 | Indicates whether 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 settings. | Yes | |||||||||
LogClientIdentity | Determines whether the content cache should log the IP address and port number of the clients that request content. | No | |||||||||
MaxConcurrentClients | Specifies the maximum number of clients that a content cache can support. Apple doesn’t guarantee that a content cache can achieve 3400 concurrent clients. | 3400 | |||||||||
MaxParentDepth | Specifies the maximum number of times, for a single request, that a child content cache forwards 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 | Specifies the maximum number of peer content caches to ask for content. | 0 (unlimited) | |||||||||
MetricsInterval | Specifies 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 | Specifies 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 | Specifies 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 | Specifies 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 | Specifies 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 aren’t 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 downloads from or uploads to Apple directly until a parent content cache becomes available again. You can also set this value in Content Caching settings. | 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 settings. | round-robin | |||||||||
ParentUploadTimeout | Specifies 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 | Specifies 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 won’t 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. The type subkey is no longer necessary and is ignored if present. You can also set this value in Content Caching settings. | none | |||||||||
PeerListenRanges | When PeerListenRanges is an array of dictionaries where each dictionary represents an IP address range, the content cache only successfully responds 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 responds with an error to cache queries from any other content cache. When PeerListenRanges is Boolean true, the content cache uses the ListenRanges value rather than the PeerListenRanges value to decide which other content caches it successfully responds to cache queries from. When PeerListenRanges is any other type or the value is missing, the content cache successfully responds to cache queries from all other content caches. PeerListenRanges only affects which content caches this content cache successfully responds to cache queries from. It has no effect on the list of peers this content cache queries for content and downloads 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 doesn’t attempt to query it again until the PeerRetryInterval has elapsed. The type subkey is no longer necessary and is ignored if present. You can also set this value in Content Caching settings. | none | |||||||||
PeerLocalSubnetsOnly | Indicates whether the content cache should only be a 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 restrictions on peers for the local network are updated appropriately. You can also set this value in Content Caching settings. | Yes | |||||||||
PeerNotifyTimeout | Specifies 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 | Specifies 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 | Specifies 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 | Limits how much storage space the content cache uses for cached iCloud data, in bytes. The PersonalCacheLimit must not exceed CacheLimit. | 0 (unlimited) | |||||||||
Port | Specifies 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 | Specifies 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 hasn’t been requested in this number of days is removed from the content cache automatically. Clamped minimum is 7 days. | 120 (days) | |||||||||
PruneAssetsInterval | Specifies 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 | Specifies the ranges of public IP addresses that the cloud servers should use for matching clients to content caches. You can also set this value in Content Caching settings. | no default | |||||||||
ReservedVolumeSpace | Specifies the minimum number of bytes of free storage space to be maintained for the volume that stores the cached content. | 2000000000 (2 GB) | |||||||||
TerminationTimeout | Specifies how long, in seconds, the content cache should try to deregister when it’s 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 isn’t 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.betterbag.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.betterbag.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/BigVolume/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>