Introduction
So, anyone with experience troubleshooting Apple’s wiki server in 10.5 will be familiar with the black art that is involved with nursing one of these beasts back to life. Unfortunately, first party documentation on the subject is mostly fluff. This means that if the system actually breaks, the lowly engineer or admin is left to reverse engineering of the product to figure out how it’s supposed to work. In my line of work, I have access to lots of broken servers, so I’ve amassed a decent amount of experience fixing broken Wiki’s. Here are some pointers that I’ve learned along the way, and may provide help should you find yourself in such a situation.
The Players
In my mind, understanding the components involved in the system is absolutely critical to being able to isolate and resolve potential problems that crop up. Apple’s wiki server exists through the implementation of four core technologies; the omnipresent Apache webserver, the ‘Teams’ server, which is a python-built webapp based off of the Twisted Engine, a SQLite-driven backend store, and an Open Directory system.
In this combo, Apache’s httpd daemon is responsible for the delivery of all static content, such as compressed javascript, stylesheets, and images. It also serves as the gateway for all dynamic content. Specifically, Apache passes all queries to url paths ‘/users’ and ‘/groups’ to the Teams server by utilizing Apache’s mod_proxy module. This redirect is specified in the configuration file ‘/etc/apache2/httpd_groups.conf’ and ‘/etc/apache2/httpd_users.conf’:
ProxyPassReverse http://127.0.0.1:8087/groups
ProxyPass http://127.0.0.1:8087/groups retry=5
…
Our Teams server utilizes the twistd engine which provides network connectivity and is responsible for listening to inbound requests over port 8087, all fed from Apache. Once Teams takes over it accesses the backend store which has a default location at /Library/Collaboration/. Inside this directory reside separate subdirectories for Groups and Users, each containing a subdirectory for every registered group or user in the system. For the most part, Teams serves out basic flat-file html pages. Searching, tagging, and revisioning is all handled via SQLite database files.
Officially, an Apple Teams server must reside on an Open Directory Master. Any groups hosting wiki’s must be configured using Workgroup Manager for display.
Wiki User/Group Folder structure
A wiki’s group folder resides by default at ‘/Library/Collaboration/groupshortname’ and is created upon first login to the site or blog. This directory contains several pertinent files that we need to be aware of.
1. metadata.plist
• This file contains our wiki’s settings, localized to this group. These settings include custom themes, banners, sidebars, and comment restrictions. One key thing to know about this file is that it contains a GUID string, which MUST match the GUID associated with the group name in your directory system. If this is not the case, this file will get over-written by the Teams server, reverting it back to as-new state. This is particularly key to know if you are migrating the wiki from a different systems.
2. index.db
• This is our wiki’s database. It contains two tables, ‘pages’ and ‘tags’. The pages table contains all current pages in the system including metadata such as author, modification date, and tags, as well as their actual content. The tags table includes all tags and their associated pages. This database is primarily used by our searching system.
3. discussions
• This directory contains plists linking comments to pages
4. weblog
• This directory contains page directories for all of our weblogs
5. wiki
• This directory contains page directories for every page in our wiki.
Page Directories
In this context, a ‘page directory’ simply refers to a standard directory structure utilized by Apple’s wiki. It contains 3 files and 2 directories. Amongst these files is ‘page.html’, which is the actual HTML code of our page. This file is served out to requesting web user agents. ‘page.plist’ is a property list file containing metadata about the page; author, revision dates, and status. Our last file in this directory is revisions.db, which is a SQLite database containing all revisions of the current page. Subdirectories include ‘attachments’ and ‘images’, which contain keyed subdirectories for version control of uploaded files.
From the Ground Up
One way to learn how all of this works is to implement wiki services for our own pre-existing group, severing our reliance on the GUI to do this for us.
First, I’ll discuss the actual “discovery” portion of Apple’s wikiserver, that is, actually getting the wiki to display your group. Which groups actually display for use on Apple’s main landing page is specified in the SQLite database stored at ‘/Library/Application Support/Apple/WikiServer/userGroupIndex.db’. This is a pretty basic table, containing 9 fields:
%sqlite3 /Library/Appliction\ Support/Apple/WikiServer/userGroupIndex.db
sqlite>.schema
CREATE TABLE users_groups(user_groupID INTEGER PRIMARY KEY AUTOINCREMENT, userType, name, longName, comment, iconPath, path, host, hasEntries);
CREATE INDEX user_index ON users_groups(longName);
We can inject our own data here, and the system will proudly serve it out:
sqlite>insert into users_groups names(‘userType’,'name’,'longName’,'iconPath’,'path’,'host’,'hasEntries’) values(‘group’,'testgroup’,'My test group’,'/collaboration/images/group.jpg’,'groups/testgroup’,'*’,0);
So, if we visit the landing page now, we’ll see our new ‘testgroup’ wiki. However, the page is not accessible when we click on it (error 404). For this to happen, our Teams server needs to be able to find the group in our directory system, which is the primary crux of the issue; this userGroupIndex.db file is generated at runtime by Teams, it’s contents should match those groups as defined in our Directory, and any direct modifications to this file will eventually be overridden by dynamic data pulled from DS. Thus, hand modifying this file is a futile endeavor.
To get this new group to be discovered AND functional, we need to update our group in the directory. Wiki group discovery is done based on the groups ‘ServiceLocator’ attribute, and has a colon-delimited value that consists of our servers’ GUID, our sites GUID, and the service it is responsible. The following commands can be used to determine these:
%dscl /Search read /Computers/myservername GeneratedUID
GeneratedUID: 87880872-1EB2-4504-9698-DFC6C7CB9A29
%serveradmin settings web | SiteGUID
web:Sites:_array_id:10.0.2.3\:80_mysite.com:SiteGUID = “DC7EB82B-068F-48C9-94EB-72C2FAD58752″
So, now that I have determined the server and site guid, I can inject these settings into my group record. This step assumes the group ‘testgroup’ is already created in Workgroup Manager.
%dscl -u diradmin /LDAPv3/127.0.0.1 create /Groups/testgroup ServicesLocator “87880872-1EB2-4504-9698-DFC6C7CB9A29:DC7EB82B-068F-48C9-94EB-72C2FAD58752:wiki”
And then restart Teams to ensure that the new group is picked up.
%serveradmin stop teams; serveradmin start teams
At this point, we can now navigate to our new group, and see that we now have a landing page. Once we log in, the group will now have a wiki folder at /Library/Collaboration/.
If your group still isn’t displaying at this point, then something else is wrong. I suggest verifying your DS Search path to ensure that Teams can properly read your LDAP data. Additionally, verify your apache sites configuration, as well as forward/reverse DNS resolution, it’s possible that your Apache virtual host is not properly being determined.
So there you have it, wiki troubleshooting in a nutshell.