The bain of a sysadmin’s existence is documention. Most of us hate doing the tedious paperwork, but doing so helps the group around you and many times yourself once you’ve moved on to new projects. I know its a struggle for me and my co-workers.
Part of the problem is that documentation tends to get outdated. Keeping your notes updated as changes are made is tough. Old documentation is sometimes worse than no documentation… Its sometimes better to get inside and dig around to see how things are actually working/setup.
After I started at HTC, my co-worker David showed me his Mediawiki setup and running from his personal Linux desktop that he was using for documentation. He has amassed a pretty respectible collection of documents on the *nix, backup and networking side of the house. Too bad I was a Windows guy for the company (ouch, did I just type that… I’m so the anti-Windows Windows guy…).
After I started the VMware VI 3 deployment, I quickly realized I needed to be keeping notes somewhere for this monster project. I asked if I would be able to use the wiki he’d established to keep my notes and he agreed. As we talked on, we quickly realized that everyone in our group was likely in the same boat with their notes. We had documents strown all over our file share with a hodge podge of information, none of it readily available (searchable) when needed.
So, after getting VMware deployed and as a test of deploying our first Red Hat VM, we setup something we called NetAdminWiki… We secretly plotted planned to continue putting our information in this repository and then open it up to our co-workers over time to get them on-board. I’m glad to say that a year later, we’ve now got all our co-workers with working accounts on the wiki, but we ran into a few issues that we needed to conquer before putting it out before our bosses.
MediaWiki in the enterprise
MediaWiki is a great solution for documentation, but its meant for everyone to contribute – that’s its focus – a very wide audience. In our case, we wanted it to only be available and accessible to a select audience. That initially ment password protecting the Apache website using HTAccess. Most of our co-workers didn’t like the idea of logging onto the web server and then into MediaWiki…
We found an extension for MediaWiki that allowed us to do seemless signin using the authenticated account passed from Apache. That worked great, but then users wanted to use their AD account and password. That led us to making Apache authenticate against AD’s LDAP and login users that way. This method was messy and it messed with MediaWiki’s built in account creations method.
This past week, I finally cleaned all this up as I was asked to add our last co-worker into the wiki. MediaWiki now has a great LDAP Authentication module with few dependancies. Once I setup this module, we were logging in against the domain with ease. We removed the Apache authentication and we now have users logging in through the normal MediaWiki method, but that introduced a new problem. Anyone could read our content.
The extension library for MediaWiki is expansive, so finding a solution for the new problem was a snap. With just a few changes to the LocalSettings.php file, we were able to lock down access to the wiki, so that you had to login to ready any content or make changes. MediaWiki has a great article about preventing access in their online manual.
With these two extensions, we’ve now made a pretty nice documentation solution for our group. Its possible to take this much farther. The LDAP Authentication solution also has the ability to synchronize MediaWiki groups with AD groups and you can provide additional permissioning using AD groups. There are a lot of options here.
