OS X Caching Server – Setup and Troubleshooting

The Apple OS X Server is a great and cheap server-extension and works very well to cache iOS- and OS X updates. It requires literally zero configuration (except that all connected devices need to have the same NATed outbound address and your local DNS needs to be configured properly) and this is probably also the reason for the lack of Apple documentation.

For the Caching Server to work, the Caching Server and all devices on the network need to have the same outbound IP address (you can check this via http://www.whatsmyip.org/). Without going into too much detail, this is how it all works:

• When the Caching Server starts, it will register with Apple via it’s internal and public IP address
• When an iDevice / Mac requests app-installs or updates, a request is sent to Apple Update servers and Apple then identifies that the device requesting the update/application has the same IP as the registered Caching Server. Apple will then direct the device requesting the update/application to the Caching Server’s internal IP address.

The OS X Server runs on top of any OS X installation and my preferred choice is to run it on a low-end Mac Mini. I typically manually set the server/host-name on the command line:

sudo scutil --set HostName osxcache.pvt.lan
sudo scutil --set LocalHostName osxcache
sudo scutil --set ComputerName osxcache

Once you have the Caching Server installed, enable to log the client-details (IP, device name) and also ensure that caching is enabled (it is by default). I also prefer locking down the Caching port:

sudo serveradmin settings caching:LogClientIdentity = yes
sudo serveradmin settings caching:AllowSharedCaching = yes
sudo serveradmin settings caching:AllowPersonalCaching = yes
sudo serveradmin settings caching:Port = 61000

Although the Caching Server and connected devices are pretty much “self-discoverable”, I found that publishing a DNS TXT record on your network will make it work more reliable:

_aaplcache._tcp 259200 IN TXT "prs=YOUR_WHATSMYIP_ORG_ADDRESS"

Once you start the Caching Server, you can very easily verify if it functions by looking at it’s log-file:

tail -f /Library/Server/Caching/Logs/Debug.log

To see if the Caching Server actually stores updates/applications, I connect to it’s own SQLite database and look at the content:

## Log onto SQL-Lite DB
sudo sqlite3 /Library/Server/Caching/Data/AssetInfo.db
 
## Then paste the following commands to see updates
.mode column
.headers on
select ZTOTALBYTES,datetime(ZCREATIONDATE+978307200, 'unixepoch', 'localtime') as "ZCREATIONDATE",datetime(ZLASTACCESSED+978307200, 'unixepoch', 'localtime') as "ZLASTACCESSED",ZLASTMODIFIEDSTRING,ZURI from ZASSET where ZURI like "%content%" or ZURI like "%ios%" order by ZCREATIONDATE;

The above query will show iOS updates/applications (URI starts with /ios) and OS X updates/applications (URI starts with /content):

A nice to have is reporting tool hosted on Github – https://github.com/macadmins/sashay

It might appear that OS X Caching Server does not cache properly, but I found that Apple serves different files / URLs for different devices – I have been able to determine this by downloading Waze across different iPhones and you will notice a difference in download URLs:

Waze (iPhone7,2 - iPhone 6) /apple-assets-us-std-000001/Purple42/v4/5d/3d/4f/5d3d4f4c-e0e5-f691-d34f-b55c8c4cace9/mzps.826157924980113038.ipa
Waze (iPhone8,1 - iPhone 6s) /apple-assets-us-std-000001/Purple62/v4/1f/84/57/1f8457e7-e0c7-629f-ff1e-39eb15fb7e78/mzps.7415653738222812626.ipa

This also shows up in SQLite (notice the difference in URI and file-size):

ZTOTALBYTES ZCREATIONDATE ZLASTACCESSED ZLASTMODIFIEDSTRING ZURI
----------- ------------------- ------------------- ----------------------------- ---------------------------------------------------------------------------------------------
14677044 2016-08-25 12:35:51 2016-08-25 12:47:52 Wed, 24 Aug 2016 18:25:56 GMT /apple-assets-us-std-000001/Purple42/v4/5d/3d/4f/5d3d4f4c-e0e5-f691-d34f-b55c8c4cace9/mzps.826157924980113038.ipa
14676898 2016-08-25 12:40:15 2016-08-25 12:40:15 Wed, 24 Aug 2016 19:24:48 GMT /apple-assets-us-std-000001/Purple62/v4/1f/84/57/1f8457e7-e0c7-629f-ff1e-39eb15fb7e78/mzps.7415653738222812626.ip