My first book, named Troubleshooting Riverbed Steelhead WAN Optimizers, has been published officially. Well, made available to Riverbed customers with access to the Riverbed Support website. It has been a multi-year effort and as usual the most difficult part was to get approval for external publishing.
The things that went smooth were the editing and the publishing: That approach was taken more or less from how the FreeBSD Project makes their documentation: The source is based on DocBook XML (Was DocBook SGML when I started) which compiles it into various formats like HTML, PDF and ePub. This makes sure you have the style and the content separated, so that even if you make certain style changes afterwards you just do it in the style sheets and it automatically propagates through the whole output without the fear of missing a part somewhere in the text.
But after two chapters of that SGML/XML, I had enough of the excess of markup tags like <para> and <sectx> which presence made my automatic reformatting habbit spending more time on the smoothness of the tags than on the content. Time for a different approach!
In the past I have worked with HTML, various *roff formatters and Perl's perldoc and ended up with a mixture of things: Use the *roff .-prefix to initiate a command, use the HTML h1-h5 and i/tt/b kind of tags for the commands and use the automatic approach of perldoc to know where the paragraphs end. And then you end up with something like:
.h2 Steelhead xx20 series models The xx20 series models consist of a set of desktop models, 1RU rack models and 3RU rack models. To upgrade between models, except [...] .h3 No route to host A .i No route to host error is shown when the remote host does not exist and the router on that subnet sends back an ICMP Host Unreachable message or when
After that a convertor changes it into a real DocBook XML document:
which then gets converted into HTML or PDF.<sect2 ><title>Steelhead xx20 series models</title> <para>The xx20 series models consist of a set of desktop models, 1RU rack models and 3RU rack models. To upgrade between models, except [...] <sect2 ><title>Telnet failure scenarios</title> <sect3 ><title>No route to host</title> <para>A <emphasis role="italics">No route to host</emphasis> error is shown when the remote host does not exist and the router on that subnet sends back an ICMP Host Unreachable message or when
Easy editing, easy markup, easy publishing. That worked fine. The book was used internally at Riverbed for training the new TAC engineers and everybody was very excited about it.
What didn't go smooth was to get the approval to publish it to customers. Everybody saw the value in the book, realized that education at this part could help releasing pressure on the TAC engineers and improve the customers Steelhead experience.
But nobody knew how to take up the book and help to get approval to make it available for the outside world. People who promised to help me moved outside Support or outside Riverbed, I was pushed around by various departments to the same various departments which already told me earlier that I should talk to the people who just send them back to me. It shouldn't be so difficult, the TAC does have access to the full contents of their own website and the TAC does publish KB articles of various quality levels without going through proper review before they get published.
So after three years of editing and publishing internally and trying to get it to the outside world, it has finally been done: My first book named Troubleshooting Riverbed(r) Steelhead(r) WAN Optimizers is available for the Riverbed customers. You can download it at http://rvbd.ly/1p5MMgu or http://supportkb.riverbed.com/support/index?page=content&id=S24051.
As described in the "About the Author" chapter the book Network Administration with FreeBSD 7 by Babak Farrokhi and published by Packt Publishing, this is a book made of scattered notes. And that makes the context of this book so good: It are the notes from an experienced administrator who wants to share his secrets with the world. Although I have been using FreeBSD since the 2.2 versions and I am well known with it, his notes show that there is nothing better to learn from than the experience of peers in the same field you are in.
The size of the pages in the book is wider than the O'Reilly books, which makes it possible to leave it open on your desk while you try out the suggestions and commands printed on them. The order of the chapters is System Configuration, Network Configuration and Network Services and it doesn't only describe the commands available in the base operation system, but also the important ports in the third party software ports collection. The commands and examples in the book are consistent and include the command line, /etc/rc.conf and kernel configuration lines everytime where it is necessary.
Because of the fast development and the broad range of features on the FreeBSD operating system, it is hard to know everything others know. That goes for me with regarding to the GEOM chapter for example, which I never had touched before because I always have used hardware based RAID solutions. And it goes for the author, who didn't write about the GUID partition table for large harddisks.
The FreeBSD operating system has often the approach of "use tools and approaches which have been proven over time" and the mindset of system administrators often reflect this: cvsup is one of these things. But luckely the author mentions the portsnap and freebsd-update tools, although he doesn't mention the fact that the last one can be used for minor version and major version upgrades of the base operating system.
The chapter about jails, one of my favourite features of FreeBSD, is very clear and verbose, but it lacks a reference to the sysutils/ezjail port.
Despite being a book for administrators, the Network Configuration part starts with the basic stuff on how network interfaces work and how to configure them. But it quickly moves forward to VLANs and monitoring mode and Fast EtherChannels. The chapter about tunnelling is partly simple and partly tricky: The simple part is the GRE tunnel in two pages and the tricky part is the IPSEC tunnel in 8 pages. The chapter about PPP describes beside the client configuration also the server configuration, something I have never done before.
The chapter about my favourite thing on network equipment, dynamic routing, is a good start to get things up and running but is missing an essential paragraph about what goes over the wire in case of a successful (or unsuccessful) establishing of routing neighbours.
The firewalls chapter is technically fine, but it shows that the author is natively speaking a language in which words like "a", "an" or "the" are not compulsory to write a grammatically correct sentence: Often these words are missing and its confusing. But there is nothing wrong with the context.
The chapters about Internet Servers and Local Network Services are fine to have a complete overview of all aspects of a FreeBSD system, but it doesn't give more than a quickly name them, give an example and tell how to install them. The book should have been done without these two chapters and they could have been in their own book, with more and deeper examples and troubleshooting tips.
My opinion: Great book, worth having and reading. It could use a review of somebody who is a native English speaker to get the lines better rolling now and then, and a technical review of somebody who can make sure that the examples are correct, but for the rest I would say that it belongs next to the other books like Absolutely FreeBSD and The Complete FreeBSD.