Show me the man pages

As a long term Unix admin, it’s frustrating when there are commands on my systems for which there aren’t man pages. As a long-term NetWorker user, it’s equally frustrating when there aren’t man pages for particular NetWorker commands.

When I’ve discussed this in the past, I’ve usually had a response of “that’s because you shouldn’t be running that command”. That’s a bad response. The correct response should be something along the lines of “oops, we’ll write a man page for the next release that states:

That command is for internal NetWorker use only. It does X. It should not be run manually.”

Having undocumented commands that give no output, hang or produce strange results is just inviting frustration. Of just the nsr prefixed commands, on my current 7.6 lab server, the following commands are undocumented:

• nsravamar
• nsravtar
• nsrbmr
• nsrcatconfig
• nsr_cp_install
• nsrdmpix
• nsrdsa_recover
• nsrdsa_save
• nsrfile
• nsrfsra
• nsrlmc
• nsrndmp_2fh
• nsrrcopy
• nsrrcopy2
• nsrvcbserv_tool

So out of the 55 nsr prefixed commands I have on my server, 15 (or 27%) are undocumented.

Note to EMC: This does not produce a healthy level of trust. Please – get some documentation on these commands, even if that documentation gives us a one line overview of where they’re used and tells us not to run them ourselves.

Release notes are your friend

To me the most valuable documents produced by EMC in relation to NetWorker or the modules are the Release Notes. These accompany any cited version update and typically contain at least the following chunks of information:

• New features to the product
• Changes to existing behaviour
• Fixed problems
• Known issues and limitations

This information is gold. To anyone thinking of updating either a NetWorker server or a NetWorker module who isn’t planning on thoroughly reading the release notes first I say this: are you nuts?

I’m the first to admit that I don’t re-read the administration guides every time they are updated. There’s just too much content in them. Instead, I rely on the release notes to tell me what has been added, and if any of that is relevant to my needs, I go searching through the administration guides for said information. In fact, I consider the release notes important enough that they’re the only NetWorker documentation I ever print. Why do I print them? Because it means I can take them away from the computer and go sit down and read them carefully – very carefully.

The release notes don’t always contain all information about an update. They also may not fully elucidate on particular problems that have been fixed*.

To me the most important aspect to the release notes – the bit I check first, is the “Known problems and limitations”. Why? This is the bit that gives you the warnings of “things that don’t work”, or “things that you may have to pay more attention to than you would otherwise think to”. I.e., what is known to not work. One would ignore these in particular at ones own peril.

So, next time you’re thinking of updating any part of your NetWorker environment, please, make sure you download and read the release notes.

—
* I can attest to this when I review release notes and see LGTscABCDEF numbers that have been created in response to bug filings I’ve made … a 2-3 line entry can’t convey all the details of sometimes complex, sometimes esoteric escalations.