Edit: Some links no longer work.
Originally posted August 2015 by IBM Systems Magazine
Back in 2012, I wrote a blog post titled “The Case for Documentation.” Then just recently, a reader made a comment:
“I see in 3 years there has not been a single comment on this article. I’ve been so deep into Power and AIX, like you mentioned, walking around with knowing all there is to know in and around the environment I look after. Finally there has been an official request submitted to document PowerHA clustered environments and other smaller ones. I am so much in the thick of it that I start off and end up with a too technical visio drawing or veer off track in explaining an area. Have you got a guideline or template to give me an idea how I can start and get to finish a fairly sort and sweet “walk through” document that is just informative enough to satisfy those at management level or even my specialized level?”
Let me address this with some of my favorite tools to document Power Systems. Some of these tools have “prettier” output than others, but I think they’re all valuable when it comes to documenting your running systems.
PowerHA Tools
The original question was PowerHA specific, so let’s start with the PowerHA snapshot tool. The cluster snapshot tool lets you save and restore cluster configurations by saving a file a record of all the data that defines a particular cluster configuration. Then, you can recreate a particular cluster configuration, provided the cluster is configured with the requisite hardware and software to support the configuration. This snapshot tool can also make remote problem determination easier because the snapshots are simple ASCII files that can be sent via e-mail.
You can also use the PowerHA-specific qha and qcaa scripts. These are real-time tools that you can use with your running systems more than as a deliverable, but they’re still valuable. Alex Abderrazag has provided a nice script to help you understand cluster manager internal states.
HMC Scanner
When it comes to documenting the way my servers have been configured, I like to use HMC Scanner. HMC Scanner gives you a nice summary spreadsheet with almost anything you want to know about your environment, including serial numbers, how much memory and CPU are free on your frame, how each LPAR is configured, information on VLANS and WWNs, and much more. I did a video on running HMC Scanner and IBM’s Nigel Griffiths has also posted a video on HMC Scanner for Power Systems. HMC Scanner works for AIX, IBM i, Power Linux and VIOS LPAR/VM.
System Planning Tool
I also like to use the IBM System Planning Tool (SPT), which I blogged about in “Configuring Your Machine Before it Arrives” and which you can find on the IBM support tools website. The SPT provides nice pictures of the machines showing which slots are populated and assigned to which LPARs.
If you’re comfortable with the command line, you can manipulate sysplans with the following commands, which may be easier than going into the GUI to do the same functions:
lssysplan rmsysplan mksysplan cpsysplan
viosbr
For VIO server-specific documentation, I like to use viosbr. After you’ve taken a backup, run:
viosbr –view –file
This provides a lot of information to document the setup of your VIO server. It will show your controllers, physical volumes, optical devices, tape devices, Ethernet interfaces, IP addresses, hostnames, storage pools, optical repository information, ether channel adapters, shared Ethernet adapters, and more.
snap –e
AIX-specific commands would include snap –e, which lets you gather a great deal of system information and run custom scripts to include other information with your snap. This tool is often run in conjunction with support to collect the information they need to help resolve issues with your machine.
prtconf
Another worthwhile command is prtconf. This command gives you information like model number, serial number, processor mode, firmware levels, clock speed, network information, volume group information, installed hardware, and more.
IBM i Options
For IBM i, the midrange wiki has good information about different methods you can use to gather data, including how to print a rack config from a non-LPAR system:
- Sign on to IBM i with an appropriate userid
- On a command line, perform command STRSST
- Select option 1, Start a service tool
- Select option 7, Hardware service manager
- F6 to Print Configuration
- Take the defaults on Print Format Options (use 132 columns)
HMC
In the new HMC GUI, you can select your managed server then Manage PowerVM and you have options to see your virtual networks, virtual storage, virtualized I/O, and more. This information can also be helpful in documenting your environment.
Self-Documenting Tools
I find there’s value in having systems that can “self-document” via scripts and tools compared to administrators creating spreadsheets that might or might not get regular updates as soon as changes occur. Somhotlinke might find self-documenting tools don’t provide the correct information, which leaves us with the question of whether it’s better to have no documentation or wrong documentation when you’re working on a system.
Self-documenting tools are a starting point. Whatever documentation you have on hand, take the time to double-check what the actual running system looks like compared to what you think it looks like. By not assuming anything about your running systems, you can avoid creating additional problems and outages because reality didn’t match what the documentation said.
Many Different Documentation Tools
From the frame, to the OS, to the VIOS, to the HMC, there are many different pieces of your infrastructure to keep an eye on and many different tools you can use to document your environment. I’m sure readers use many other tools and I’d be interested in hearing about those. Please weigh in with a comment.