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 needs to 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 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 | 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 need to 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 need to 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. | No | |||||||||
ListenRanges | An array of dictionaries describing the range of client IP addresses to serve. See below for an example using the 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 If you want to use the You can also set this value in Content Caching settings. | No | |||||||||
ListenWithPeersAndParents | Indicates whether content caching registers with the union of the Note that | 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 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 The content cache only queries peers that are in the When When When
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 When When When
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 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 When When When 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 | 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 seven days. | 30 (days) | |||||||||
PruneAffinitiesInterval | Specifies how often, in days, the content cache should scan for and remove user affinities older than | 7 (days) | |||||||||
PruneAssetsAge | Content that hasn’t been requested in this number of days is removed from the content cache automatically. Clamped minimum is seven days. | 120 (days) | |||||||||
PruneAssetsInterval | Specifies how often, in days, the content cache should scan for and remove content older than | 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 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.melardclothing.com uses the
ListenRangeskey 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 theListenRangesOnlykey to No.caching2.melardclothing.com uses the
ListenRangeskey 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 theListenRangesOnlykey 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>