macOS High Sierra

Configure advanced content caching settings

You can fine-tune content caching for your network configuration.

You can set advanced configuration settings 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.

You can set advanced configuration parameters using the command sudo -u _assetcache defaults write /Library/Preferences/com.apple.AssetCache.plist, followed by the command sudo AssetCacheManagerUtil reloadSettings. Use the command AssetCacheManagerUtil settings to view the standard (non-advanced) settings.

For more information about the AssetCacheManagerUtil command, see the AssetCacheManagerUtil(8) man page.

Use the defaults command

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 en1

ListenRanges 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 reloadSettings

For 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

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

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)

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:

  • 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 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 log command in the Terminal app to view content caching logs. See the log(1) man page. 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

About the ListenRanges key

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.

  • 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 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> <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>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>