Advanced content caching settings on Mac

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 need to 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 need to 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 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 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 need to also specify the ListenRanges key.

You can also set this value in Content Caching settings.

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:

• If the Mac was updated or upgraded to macOS 10.13.4 from an earlier version of macOS, the default value is No.

• If the Mac has a new installation of macOS 10.13.4 or later, the default value is Yes.

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.

• If the value is > 1, metrics are added at the top of each interval. For example, at 60 seconds, metrics are added at the top of each minute.

• Flushing the cache flushes out the current row of metrics (if any).

• No metrics are added while content caching is idle.

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:

• first-available: Always use the first parent in the Parents list that is available. This is useful for designating permanent primary, secondary, and subsequent parents.

• url-path-hash: Hash the path part of the requested URL so that the same parent is always used for the same URL. This is useful for maximizing the size of the combined caches of the parents.

• random: Choose a parent at random. This is useful for load balancing.

• round-robin: Rotate through the parents in order. This is useful for load balancing.

• sticky-available: Starting with the first parent in the Parents list, always use the first parent that is available. Use that parent until it becomes unavailable, then advance to the next one. This is useful for designating floating primary, secondary, and subsequent parents.

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 set to 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 set to 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 set to TRUE, the content cache only queries and successfully responds to peer queries from content caches on the same immediate local network.

When PeerLocalSubnetsOnly is set to TRUE, it overrides the configuration of PeerFilterRanges and PeerListenRanges.

When PeerLocalSubnetsOnly is set to FALSE, the content cache defers to PeerFilterRanges and PeerListenRanges for configuring the peering restrictions.

When PeerLocalSubnetsOnly is set to 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 can’t 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 seven 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 seven 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 is set to 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 log command in the Terminal app to view content caching logs. See the man page for log. Content caching logs to the subsystem com.apple.AssetCache.

For example: log show --predicate 'subsystem == "com.apple.AssetCache"'

You can also use the Console app to view the logs.

No