One of the canards about Free and Open Source Software that is peddled by the unscrupulous marketers of proprietary software is that their product is superior because, among other things, the scruffy, sandal-wearing Communists that write and distribute their software for free do not bother to adequately document that software; thereby placing in jeopardy the business processes in the enterprise that rely on said software to continue to profitably grease the wheels of the juggernaut of Capitalism.

At heart, it really is an attempt to paint FOSS as a hobbyist’s pursuit, unworthy of consideration by Fortune 500 CIOs as it is not in the same league as “professional,” proprietary product. This FUD is not restricted to the usual suspects; it has also been raised by other, presumably more objective commentators:

Open Source documentation is terrible. There is no kinder way to put it. Even the commercially distributed software in the Open Source world has substandard documentation. (And believe me, as a technical writer coming from the Windows world, when I tell you that the commercial industrial standards are pretty low). Only a bare handful of Open Source software packages have any documentation at all. And out of the few that do, much of it is either unfinished, inaccurate, or outdated. What counts as explanatory text among geeks would bewilder a nuclear physicist, even a sober one.

A more recent survey, published in 2010, identifed the same issue for businesses, in slightly less histrionic language:

The No. 1 reason for not choosing open-source solutions was lack of support followed by poor documentation.

My experience of FOSS documentation, particularly over the last twelve months, has been just the opposite.

From the middle of 2012 on, I made a couple of significant changes in my computing environment; I moved from SysVinit to systemd, garden variety to UEFI booting and changed my shell from Bash to Zsh. In each of these cases I found myself having to turn to the documentation the community has provided in order to understand the implications of the change, and to familiarise myself with the new tool or approach.

I posted at the time about moving to systemd, and I don’t think—in retrospect—I credited Lennart Poettering enough for the series of posts he wrote detailing the design decisions and implementation of that system; those posts (at the time 12, now grown to 20) are an impressively thorough, and thoughtful, document of the new init system.

Similarly, when I started reading about UEFI booting, I quickly found myself at Rod Smith’s site. Rod has compiled an exhaustive and authoritative resource on GPT, EFI Stub loading and UEFI booting in general. Reading through his clear, approachable documentation made transitioning to UEFI a much simpler process than, given the inherent complexity in the ecosystem, I would have thought possible.

Then there is Zsh.

Because zsh contains many features, the zsh manual has been split into a number of sections…

And goes it on to list those seventeen sections. If you are not a fan of man pages¹, there is the Zsh Documentation, the User’s Guide and wiki. This amounts to a literally staggering amount of information—it is no wonder that preconfigured zsh systems like grml are so popular; they provide relatively simple ingress to the byzantine ways of this powerful shell.

Finally, also last year, I was privileged to chair the judging for the 2012 New Zealand Open Source Awards. This exposed me to the amazing contribution Michael Kerrisk has made to GNU/Linux over the last decade. He is the author, or co-author, of over 300 man pages; and these aren’t the glamorous, application pages read by the masses, but the system pages that document the kernel and glibc APIs.

All of this suggests to me that the state of documentation for FOSS is anything but parlous. At every turn over the last year, when I needed to be able to refer to documentation for a project, there was a surfeit of it. And I have only touched on what would normally constitute the primary sources; there is also all of the other community-driven documentation around projects, like the Arch Wiki or the Stack Exchange sites, the support available on forums, IRC, blog posts, etc.

Compared to the sterile, mostly out-of-date (and expensive) documentation that accompanies proprietary software, FOSS is an Alexandrine utopia…

Notes

1. And, god knows, I am; man pages are a constant source of knowledge and delight (and pretty much the only way I can contribute to projects that I am indebted to).

Creative Commons image of documents by Marcin Wichary on Flickr.

Just before Christmas my EeePC 901 started to behave erratically. Rather than prolong the final throes, I decided to replace it and, after looking around and having played with a colleague’s Samsung Series 9, I decided that I would swallow my pride, pay the Windows tax and opt for one of these sleek, fast little notebooks. Given my experience with it over the last six to eight weeks, I am confident that it was a decision that I am unlikely to regret.

The machine came with Secure Boot enabled and running Windows 8.¹ After sedulously ignoring the mounting number of posts on the Arch boards that had UEFI in the title, initially convinced that it had something to do with Apple hardware and therefore would be unlikely to impact on me at any point in the future, I now found myself in the position of having to understand all of the disparate elements involved in UEFI booting.

This proved to be a non-trivial task. It is not that there is insufficient information available; quite the opposite. The Arch Wiki has a typically thorough entry on UEFI; the real challenge is revealed when you scroll to the bottom of that page to the reference links where you begin to reach an appreciation that this isn’t a drop-in replacement for Grub in the way Syslinux was, for example. This is a whole new booting ecosystem.

I wanted a LVM on LUKS setup and, after reading a lot more documentation on UEFI bootloaders, GUID Partition Tables and EFISTUB² than I had bargained on, I felt reasonably well equipped to proceed. And while this was an admittedly time consuming (and sometimes confusing) process, I believe it was worth it.

Once I had a reasonable grasp of the conceptual model—and I am convinced this is the single biggest hurdle in this process—I chose the EFISTUB boot approach with gummiboot, as the boot manager; mostly because it seemed the simplest approach (the name may also have been a factor).

Armed with all this new knowledge, I embarked on the install process. It didn’t take long at all. Mostly because I couldn’t boot in UEFI mode from the USB drive.

Turns out a couple of things were thwarting me; one I had disabled Secure Boot in the UEFI menu, but had neglected to disable the fast boot option. Secondly, and more worryingly, I kept encountering kernel panics once I had got the machine to boot. Seems that booting in UEFI mode triggers a nasty bug with the samsung_laptop module.

Once I could boot from the USB drive, I was able to successfully complete the install. Rather than include a blow-by-blow account of that process here, I have uploaded a gist with the details, for the morbidly curious or preternaturally bored.

The whole process, for me, epitomised what Arch is really about. No matter how comfortable a point you reach with your understanding of the tools you use, the rolling release model constantly challenges you to adopt and adapt to new technologies. Sure, I could have just opted to boot in regular BIOS mode, but what would be the point of that? I wouldn’t have learned anything.

The other thing that quickly became apparent is that, contrary to some commentary on the boards about the removal of the AIF, the new install scripts are quite superb; simple, direct and quite unambiguous, the whole install procedure now feels a lot more Arch-like. The developers have done a great job with these tools.

Notes

1. Surely the worst operating system, at least in terms of the user interface, I have had the misfortune to encounter (and I include Vista and Ubuntu’s Unity in that cavalcade of fail)…

2. I’ll post more on the voluminous documentation around this, and other aspects of GNU/Linux, in the coming weeks.

I have used TrueCrypt since just before I migrated to Linux, so somwehere around six or seven years, dating back to version 3 or 4. It is an incredibly handy utility, allowing you to create and manage encrypted volumes on the fly and—for the especially paranoid—to hide the existence of those volumes from inquisitive others.

In the intervening years, with all aspects of my personal life increasingly mediated digitally, in order to properly safeguard my privacy, and that of my family, I have taken to using LUKS to fully encrypt all of my machines. And I have used TrueCrypt, both personally and for work, to encrypt some of my USB drives and as a container in Dropbox , for as long as I have used that service.

Early last year, however, I became aware of concerns that TrueCrypt was not truly open source; that almost all of the larger distros, including Arch, and the Open Source Initiative did not regard TrueCrypt as free (as in Freedom) software:

The TrueCrypt License has not been officially approved by the Open Source Initiative and is not considered "free" by several major Linux distributions (Arch Linux, Debian, Ubuntu, Fedora, openSUSE, Gentoo), mainly because of distribution and copyright-liability reasons.

When I initially accessed the page, in February 2012, there was also a paragraph—now removed—that highlighted further, more alarmist, concerns about the shadowy identity of the people behind TrueCrypt:

The anonymity of the developers and the abnormalities mentioned above have led users to raise suspicions about the provenance of the product and speculate about the possible existence of vulnerabilities or backdoors that might exist in the source code or executables. http://www.privacylover.com/encryption/analysis-is-there-a-backdoor-in-truecrypt-is-truecrypt-a-cia-honeypot/ However its open source and it can be check for funerabilities that way. [sic]

While I don’t subscribe to the theory that the CIA have planted a backdoor in the software (if they had, it clearly doesn’t work), I was relieved to see at the end of last year that someone had written a simple utility that allows you to manage TrueCrypt containers from the command line; tcplay is decribed as:

a free (BSD-licensed), pretty much fully featured (including multiple keyfiles, cipher cascades, etc) and stable TrueCrypt implementation.

With a simple, two paragraph license and a brief but comprehensive man page, I was sold. I uninstalled TrueCrypt late last year and haven’t missed it since. Quite the contrary. The only “issue” that I have had with tcplay is remembering the commands to map and mount a drive. Initially, I jotted down some notes, but opening them up several times a week to refer to them quickly seemed pointless so I eventually wised up and wrote a wrapper script to do the job for me…

The script is quite simple, it finds the first available loop device, maps the encrypted volume to it and mounts it read-writeable for your user.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

#!/bin/bash
# manage truecrypt containers using tcplay

user=jason
cryptdev=Safebox
cryptpath=/home/jason/Dropbox/"$cryptdev"
loopdev=$(losetup -f)
mountpt=/media/"$cryptdev"

# must be run as root
if (( $EUID != 0 )); then
  printf "%s\n" "You must be root to run this."
  exit 1
fi

# unecrypt and mount container
if [[ $1 == open ]]; then
  losetup "$loopdev" "$cryptpath"
  tcplay --map="$cryptdev" --device="$loopdev"

  # read passphrase
  read -r -s passphrase <<EOF
  "$passphrase"
EOF

  # mount container
  [[ -d $mountpt ]] || mkdir "$mountpt"

  # mount options
  userid=$(awk -F"[=(]" '{print $2,$4}' <(id "$user"))
  mount -o nosuid,uid="${userid% *}",gid="${userid#* }" /dev/mapper/"$cryptdev" "$mountpt"

# close and clean up…
elif [[ $1 == close ]]; then
  device=$(awk -v dev=$cryptdev -F":" '/dev/ {print $1}' <(losetup -a))
  umount "$mountpt"
  dmsetup remove "$cryptdev" || printf "%s\n" "demapping failed"
  losetup -d "$device" || printf "%s\n" "deleting $loopdev failed"
else
  printf "%s\n" "Options are open or close."
fi

Once you are done, the script will unmount your volume and clean up. Undoubtedly, the script could be improved; patches are welcome.

There is a PKGBUILD in the AUR. Uninstall TrueCrypt and give tcplay a go, it is a simple, powerful application; and it is free software…

Update

As cr notes in the comments, the uid and gid values are because when I created this container I needed to ocassionally mount it from windows, so it is a FAT32 filesystem. For ext3 or ext4, you would use bindfs -u $user -g $group "$mountpt" "$backuppath".

Notes

Creative Commons image on Flickr by xserv.