The Caching Server in OS X is a little bit of a black box. But, it’s not all that complicated, compared to some things in the IT world. I’d previously written about command line management of the service itself here. When you enable the caching service, the server registers itself as a valid Caching Server. Nearby devices then lookup the closest update server with Apple and register with that update server using a GUID:
/Applications/Server.app/Contents/ServerRoot/usr/sbin/serveradmin settings caching:ServerGUID
Then, each time the device looks for an update, it does so against http://mesu.apple.com/assets/com_apple_MobileAsset_SoftwareUpdate/com_apple_MobileAsset_SoftwareUpdate.xml using the device model. Noticed this with this line in my proxy logs:
"GET http://mesu.apple.com/assets/com_apple_MobileAsset_SoftwareUpdate/com_apple_MobileAsset_SoftwareUpdate.xml HTTP/1.1" 200 - "-" "MobileAsset/1.0"
Let’s say that the device is an iPad 2,7, then the following information is used for the update, with a URL of http://appldnld.apple.com/iOS9.3.1/031-56322-20160331-F8B29F9E-F68D-11E5-AF11-0744ED25FABD/com_apple_MobileAsset_SoftwareUpdate/1c02ea51b4d2d50b04526c4ec29780b8e02dfe76.zip, which is created using the _BaseURL string followed by the _RelativePath string:
You can then use these dictionaries to assemble this path for all items in the dictionary with “iPad 2,7” in the SupportedDevices key. You can also choose to assemble this path for all items with the OSVersion of a given string, such as 9.3.1 in this case. You could curl these updates down to a client, or request them through the caching service, which would cache them to the Caching Server, using the IP of the server (e.g. 10.1.1.2) http://10.1.1.2:55491/iOS9.3.1/031-56322-20160331-F8B29F9E-F68D-11E5-AF11-0744ED25FABD/1c02ea51b4d2d50b04526c4ec29780b8e02dfe76.zip?source=appldnld.apple.com
Found the above URL using a reverse proxy. This URL is generated based on an http request to the IP address of the caching service, followed by the port. The port is derived using the serveradmin command and query the settings for caching:Port as follows:
/Applications/Server.app/Contents/ServerRoot/usr/sbin/serveradmin settings caching:Port
In this example, the URL is then
But the URL then splits the _BaseURL into two parts, taking appldnld.apple.com from the URL and appending ?source=appldnld.apple.com. So without the update, the URL would be the following:
OK, so now we’ll pop the other part of that _BaseURL in there:
And then there’s one more step, which is throw the zip in there:
Viola. Curl that and the caching server will download that update and make it ready for clients to access. Everything is hashed and secure in the directory listed using this command:
/Applications/Server.app/Contents/ServerRoot/usr/sbin/serveradmin settings caching:DataPath
krypted April 18th, 2016
I’ve written a couple of articles about the Caching service in OS X Server 5 for El Capitan. As of OS X Server 5, the Caching service now caches local copies on the computer running the Caching service of iCloud content. This allows you to cache content once and then have it accessed by multiple devices faster. I’m torn on this option. On the one hand, I love the fact that I can cache things and on the other hand I find it frightening that a random user can cache things I might not want them to cache on behalf of another user. I know, I know, they’re encrypted with a device key. But when you have data on disk, it can always be decrypted. I almost feel like there should be a plist on machines that whitelists allowed caching servers. Maybe I should make a feature request on that.
Either way, as it stands now, I might be disabling this option in larger offices. To do so, I can write an AllowPersonalCaching key into the Config.plist file at /Library/Server/Caching/Config/. The most graceful way to do this is using the serveradmin command, followed by the settings verb and then caching:AllowPersonalCaching option, setting that equals no, as follows:
sudo serveradmin settings caching:AllowPersonalCaching = no
To turn it back on:
sudo serveradmin settings caching:AllowPersonalCaching = yes
This can also be done by dropping a Config.plist file into the correct location for new server installations. I’ll have an article out shortly on doing so, as you’d want to normalize a few options in the file before deploying en masse (e.g. if you have a large contingent of Caching servers to manage.
krypted October 16th, 2015
Posted In: Mac OS X Server
The caching service in Mountain Lion Server (OS X Server 10.8) by default can use any interface installed on the system. I’ve now seen a couple instances where we have a Small Tree card and when a big update comes up, we loose file services speed due to caching data. To combat this, we can tell the Caching service to use the built-in Ethernet interface exclusively instead. To do so, first use ifconfig to determine which interface is which. Then tell the caching service which to use, using the serveradmin command, followed by settings and then the name of the setting, caching:Interface, setting the value to the en of the interface you’d like to use:
serveradmin settings caching:Interface = en1
I’ve had to restart the caching service to have this change take effect:
serveradmin stop caching
serveradmin start caching
Clients will then automatically use the correct interface.
krypted August 22nd, 2013
Posted In: Mac OS X Server
These days, new services get introduced in OS X Server during point releases. OS X now has a Software Caching server built to make updates faster. This doesn’t replace Apple’s Software Update Server mind you, it supplements. And, it’s very cool technology. “What makes it so cool” you might ask, given that Software Update Server has been around for awhile. Namely, the way that clients perform software update service location and distribution with absolutely no need (or ability) for centralized administration.
Let’s say that you have 200 users with Mac Minis and an update is released. That’s 200 of the same update those devices are going to download over your Internet connection, at up to 2 to 3 gigs per download. If you’re lucky enough to have eaten at the Varsity in Atlanta, just imagine trying to drink one of those dreamy orange goodnesses through a coffee stirrer. Probably gonna’ be a little frustrating. Suck and suck and suck and it’ll probably melt enough to make it through that straw before you can pull it through. For that matter, according to how fast your Internet pipe is, there’s a chance something smaller, like an update to Expensify will blow out that same network, leaving no room for important things, like updates to Angry Birds!
Now, let’s say you have an OS X Server running the new Caching service. In this case, the first device pulls the update down and each subsequent device uses the WAN address to determine where the nearest caching service is. If there’s one on the same subnet, provided the subnet isn’t a Class B or higher, then the client will attempt to establish a connection to the caching service. If it can and the update being requested is on that server then the client will pull the update from the server once the signature of the update is verified with Apple (after all, we wouldn’t want some funky cert getting in the way of our sucking). If the download is stopped it will resume after following the same process on a different server, or directly from Apple. The client-side configuration is automatic so provides a seamless experience to end users.
Pretty cool, eh? But you’re probably thinking this new awesomeness is hard as all heck to install. Well, notsomuch. There are a few options that can be configured, but the server is smart enough to do most of the work for you. Before you get started, you should:
Once all of the requirements have been met, you will need to install the actual Caching Service. To do so, open Server.app from the /Applications directory and connect to the server with which you would like to install the Caching service.
Click on Caching from the SERVICES section of the Server sidebar. Here, you have 3 options you can configure before starting the service. The first is which volume with which to place updates. This should typically be a Pegasus or other form of mass storage that is not your boot volume. Use the Edit… button to configure which volume will be used. By default, when you select that volume you’ll be storing the updates in the Library/Server/Caching/Data of that volume.
The next button is used to clear out the cache currently used on the server. Click Reset and the entire contents of the aforementioned Data directory will be cleared.
Next, configure the Cache Size. Here, you have a slider to configure about as much space as you’d like, up to “Unlimited”. You can also use the command line to do some otherwise unavailable numbers, such as 2TB.
Once you’ve configured the correct amount of space, click on the ON button to fire up the service. Once started, grab a client from the local environment and download an update. Then do another. Time both. Check the Data folder, see that there’s stuff in there and enjoy yourself for such a job well done.
Now, let’s look at the command line management available for this service. Using the serveradmin command you can summon the settings for the caching service, as follows:
sudo serveradmin settings caching
The settings available include the following results:
caching:ReservedVolumeSpace = 25000000000
caching:SingleMachineMode = no
caching:Port = 0
caching:SavedCacheSize = 0
caching:CacheLimit = 0
caching:DataPath = "/Volumes/Base_Image/Library/Server/Caching/Data"
caching:ServerGUID = "FB78960D-F708-43C4-A1F1-3E068368655D"
caching:ServerRoot = "/Library/Server"
Don’t change the caching:ServerRoot setting on the server. This is derived from the root of the global ServerRoot. Also, the ServerGUID setting is configured automatically when connecting to Apple and so should not be set manually. When you configured that Volume setting, you set the caching:DataPath option. You can make this some place completely off, like:
sudo serveradmin settings caching:DataPath = "/Library/Server/NewCaching/NewData"
Now let’s say you wanted to set the maximum size of the cache to 800 gigs:
sudo serveradmin settings caching:CacheLimit = 812851086070
To customize the port used:
sudo serveradmin settings caching:Port = 6900
The server reserves a certain amount of filesystem space for the caching service. This is the only service I’ve seen do this. By default, it’s about 25 gigs of space. To customize that to let’s say, ‘around’ 50 gigs:
sudo serveradmin settings caching:ReservedVolumeSpace = 50000000000
To stop the service once you’ve changed some settings:
sudo serveradmin stop caching
To start it back up:
sudo serveradmin start caching
Once you’ve started the Caching service in OS X Server and familiarized yourself with the serveradmin caching options, let’s look at the status options. I always use fullstatus:
sudo serveradmin fullstatus caching
Returns the following:
caching:Active = yes
caching:state = "RUNNING"
caching:Port = 57466
caching:CacheUsed = 24083596
caching:TotalBytesRequested = 24083596
caching:CacheLimit = 0
caching:RegistrationStatus = 1
caching:CacheFree = 360581072384
caching:StartupStatus = "OK"
caching:CacheStatus = "OK"
caching:TotalBytesReturned = 24083596
caching:CacheDetails:.pkg = 24083596
The important things here:
Look into the /Library/Server/Caching/Config/Config.plist file to see even more information, such as the following:
There are also a number of other keys that can be added to the Config.plist file including CacheLimit, DataPath, Interface, ListenRanges, LogLevel, MaxConcurrentClients, Port and ReservedVolumeSpace. These are described further at http://support.apple.com/kb/HT5590.
As you can see, this provides the host name of the server and path on that server that the Caching server requires access to, the last port connected to and the last date that the contents were flushed.
In the Data directory that we mentioned earlier is a SQLite database, called AssetInfo.db. In this database, a number of files are mentioned. These are in a file hierarchy also in that Data directory. Client systems access data directly from that folder.
Finally, the Server app contains a log that is accessed using the Logs option in the Server app sidebar. If you have problems with the service, information can be accessed here (use the Caching Service Log to access Caching logs).
The Caching Service uses the AssetCache service, located at
then starts as the new user _assetcache user. It’s LaunchDaemon is at
Note: In my initial testing it appeared that after rebooting devices, that iOS updates were being cached; however, several have reported that this is not yet possible. I’ll try and replicate and report my findings later.
krypted December 17th, 2012
Tags: Caching Server, caching service, Config.plist, Flush, ios, iPad, LastPort, logs, MAC, mountain lion server, OS X Server 2.2, server.app, serveradmin, Software Update Server, Software Updates, sqlite