Permalink
Browse files

Added documentation on URL rewrites

  • Loading branch information...
1 parent 44491fe commit 096b31c54bc7f6c41288f2a454112640ba95de59 @gregneagle gregneagle committed Jun 27, 2012
Showing with 80 additions and 0 deletions.
  1. +78 −0 docs/URL_rewrites.txt
  2. +2 −0 docs/client_configuration.txt
View
@@ -0,0 +1,78 @@
+Introduction
+____________
+
+Apple's Software Update service has the ability to offer the "correct" catalog to a client that requests simply "index.sucatalog". This ability was first added with OS X Server 10.6.6, and involved the use of Apache's mod_rewrite.
+
+This feature is handy, as it greatly simplifies client configuration. You no longer need to take client OS version into consideration when setting the CatalogURL for the client.
+
+Lion Server's Software Update service has a similar capability, but this is done via a CGI instead.
+
+Since Reposado doesn't handle the web-serving part of offering Apple software updates, Reposado itself cannot provide a similar feature: instead you must configure your web server to do URL rewrites, or write your own CGI to provide this functionality.
+
+mod_rewrite example
+___________________
+
+If you are using Apache2 as your webserver, you may be able to configure mod_rewrite to return the "correct" OS-specific sucatalog:
+
+Here is an example .htaccess file you could place at the root of your Reposado repo:
+
+RewriteEngine On
+Options FollowSymLinks
+RewriteBase /
+RewriteCond %{HTTP_USER_AGENT} Darwin/8
+RewriteRule ^index(.*)\.sucatalog$ content/catalogs/index$1.sucatalog [L]
+RewriteCond %{HTTP_USER_AGENT} Darwin/9
+RewriteRule ^index(.*)\.sucatalog$ content/catalogs/others/index-leopard.merged-1$1.sucatalog [L]
+RewriteCond %{HTTP_USER_AGENT} Darwin/10
+RewriteRule ^index(.*)\.sucatalog$ content/catalogs/others/index-leopard-snowleopard.merged-1$1.sucatalog [L]
+RewriteCond %{HTTP_USER_AGENT} Darwin/11
+RewriteRule ^index(.*)\.sucatalog$ content/catalogs/others/index-lion-snowleopard-leopard.merged-1$1.sucatalog [L]
+RewriteCond %{HTTP_USER_AGENT} Darwin/12
+RewriteRule ^index(.*)\.sucatalog$ content/catalogs/others/index-mountainlion-lion-snowleopard-leopard.merged-1$1.sucatalog [L]
+
+(This requires Apache2 to be configured to actually pay attention to mod_rewite rules in .htaccess files. See your Apache and mod_rewrite documentation for details.)
+
+(Note that the format for these rules is specific for use in an .htaccess file. The rules would need to be changed if in the main Apache config file.)
+
+(Other web servers such as Nginx support URL rewriting; the specifics are slightly different, but the general concepts are similar.)
+
+
+Testing
+_______
+
+The current version of Reposado can help you test your URL rewrites. When catalogs are written out to disk, a key named "_CatalogName" is added to the catalog with the base filename of the catalog. This allows you to verify that the catalog being returned is the one you expect.
+
+For example, I want to test that I'm getting the Lion catalog:
+
+% curl --user-agent "Darwin/11.4.0" http://su.example.com/index_testing.sucatalog > /tmp/testing
+ % Total % Received % Xferd Average Speed Time Time Time Current
+ Dload Upload Total Spent Left Speed
+100 1024k 100 1024k 0 0 25.1M 0 --:--:-- --:--:-- --:--:-- 32.2M
+
+% tail -5 /tmp/testing
+ </dict>
+ <key>_CatalogName</key>
+ <string>index-lion-snowleopard-leopard.merged-1_testing.sucatalog</string>
+</dict>
+</plist>
+
+The _CatalogName is "index-lion-snowleopard-leopard.merged-1_testing.sucatalog", which is what I expect.
+
+I can repeat the test for Snow Leopard, this time against the "release" branch:
+
+% curl --user-agent "Darwin/10.8.0" http://su.example.com/index_release.sucatalog > /tmp/release
+ % Total % Received % Xferd Average Speed Time Time Time Current
+ Dload Upload Total Spent Left Speed
+100 912k 100 912k 0 0 29.7M 0 --:--:-- --:--:-- --:--:-- 31.8M
+
+% tail -5 /tmp/release
+ </dict>
+ <key>_CatalogName</key>
+ <string>index-leopard-snowleopard.merged-1_release.sucatalog</string>
+</dict>
+</plist>
+
+Conclusion
+----------
+
+Adding URL rewriting to your Reposado web server configuration makes client configuration much simpler, as you no longer have to worry about which OS the client is running.
@@ -9,6 +9,8 @@ sudo defaults write /Library/Preferences/com.apple.SoftwareUpdate CatalogURL <ca
where <catalog_url> is the URL to the catalog file.
+You can use URL rewriting on your web server to simplify client configuration. See URL_rewrites.txt for more on this.
+
Tiger Clients
-------------

0 comments on commit 096b31c

Please sign in to comment.