Where Do You Go from Here

By now, you should understand the basics of editing the central .cfg files and using piktc to centrally manage your PIKT operations. Where do you go from here?

You could just start over from scratch. For that purpose, you might want to make use of the configs_minimal in the PIKT distribution. This is simply a set of empty placeholder files with little or no content--blank slates on which you can write your own configuration.

Or you can build on what you have in place already. You can make up your own defines, macros, alerts, alarm scripts, objects sets, and whatnot, perhaps using the Introduction pages, the Samples pages, the Developer's Notes pages, and possibly also the supplied lib/configs_samples in the latest official software release, pikt-current.tar.gz (but view the cautionary README file in the configs_samples directory) for inspiration and reference.

What you should definitely not do is directly base your own configuration on the suggested samples. The samples are bits and pieces of several sites' configurations as they have evolved over the years. The sites have their own peculiar mix of users, administrative staff, hardware, services, networking environment, and operating policies. You should not expect the samples to be directly applicable to your own circumstances. Refer to the samples and incorporate some or many of their elements, but reflect on what you do as you're doing it.

Following are some suggestions and things to help your reflection.

Start out small, and grow your configuration incrementally. Don't attempt to do it all at once!

Especially at the beginning, run 'piktc -cv +H ...' often, after every several edits. Most of the time, preprocessor parser error messages pinpoint the problem, but occasionally they can be quite cryptic. It's much easier to identify the source of a problem among a half dozen recent edits than if you make changes all over the configuration and run 'piktc -cv +H ...' only at the end of an hours-long editing session.

Somewhat less often, doublecheck your configuration using 'piktc -Cv +H ...'.

Make regular backups of your configuration, and use perhaps a revision control system such as CVS or RCS. Roll back your configuration, or diff it against an on-disk daily backup (as we sometimes do), when faced with a really tough misconfiguration problem.

Read--and use!--the debugging tips and techniques described in the Reference section Parse Errors (repeated at the beginning of both the configs_starter and configs_samples macros.cfg files). Simply commenting out your mistakes is the easiest and most powerful technique you should remember.

Many users run afoul of the numerous #ifdef and #if constructs in the PIKT configuration. Debugging a parse error at the #ifdef and #if levels can be a bewildering, labyrinthian ordeal. #ifdef and #if have important purposes, of course, but one should use them carefully.

We are now of the opinion that Pikt scripts should be as simple and straightforward as practical. You are generally better off hiding away as much of the #ifdef and #if complexity in the *_macros.cfg and *_objects.cfg files as possible.

Develop one theme at a time. Focus on developing your disk monitoring first, for example. Look at the files configs_samples/alarms/disk_alarms.cfg and configs_samples/objects/diskcaps_objects.cfg. What can you make use of among that material? Edit or comment out out what you don't need. Add what's missing. Be careful about #include file and macro references--every referenced #include file and macro definition must be in place.

You might want to incorporate the Samples macros.cfg page or the configs_samples/macros.cfg file directly into your configuration, but if you do, be sure to inspect it carefully and adjust as necessary, especially any OS-specific differences.

Develop, test, and debug new alarm scripts using the Test alert technique described above. When testing new alerts, be sure to run in 'doexec FALSE' mode! Run your test scripts interactively at the command line, using either 'pikt +A Test' or 'piktc -xv +A Test +H ...'.

Use plenty of '#ifdef debug ... #endifdef' directives, to output values especially. Activate the debug material by installing with 'piktc -iv +D debug ...'. Use '#ifdef verbose ... #endifdef' where appropriate, too. Edit out, comment out, or leave in place your '#ifdef debug ... #endifdef' constructs after the testing period. It's all up to you.

Test out new scripts, macros, and objects sets on just one system initially! If you make a mistake, you affect just that one system and not potentially dozens or hundreds of others. You will not want to install a new, untested script on 100 different systems immediately, then receive Debug e-mail from those same 100 systems an hour or two later reporting some silly little mistake you made. If all looks well on that one test system, try the new material out on a few more systems. Only when you are confident that everything is perfectly right should you install the new stuff everywhere.

When in test mode, turn off paging! (You don't want to receive 100 bogus pages, and worse, every 15 minutes or so!) Install using 'piktc -iv +D test -D doexec page ...', or add this to your defines.cfg:

#ifdef test
#  setdef page = FALSE
#endifdef

Decide whether you prefer to use fewer, monolithic .cfg files, or break things out into separate #include files as we have done with the suggested samples.

Some advantages to using fewer, monolithic .cfg files:

With fewer files to manage, pieces are generally easier to locate. You'll know for sure that a certain alarm script is located within the one alarms.cfg file.
Your piktc commands will run faster (because of fewer file open and close operations).

Some advantages to breaking things out into separate #include files:

The configuration becomes more modular. Excluding (or incorporating) configuration submodules is as easy as commenting out (or uncommenting) their #include file directives. (#include files also make possible the use of some clever and powerful techniques involving automatic, and in some cases even real-time, #include file updates.)
By organizing your configuration around themes (for example, disk management, process monitoring, mail services, backups, etc.), one theme per #include file, it's easier to make sense of it all, to know what you've covered and what you've left out. With the "old-style" 10,000-line alarms.cfg, it was difficult to know what's what and where, to say the least. With 500-1,000-line files organized around themes, you can much more easily spot gaps in your coverage, not to mention duplication of effort.
When you make a mistake in your #ifdef ... #endifdef and #if ... #endif constructs, diagnosing and fixing the resulting parse errors becomes much easier. It's much simpler following the #ifdef and #if logic through a 500-line .cfg file than a 10,000-line file!

If you choose the second approach, we advise against your chopping your macros.cfg into many separate #include files for this reason: Unlike with the other .cfg files, in macros.cfg, order is important. You must define a macro before you can reference it. Nesting macros inside other macro definitions is simply too difficult to do just right unless all (or almost all) of your macro definitions are ordered in a single, top-level macros.cfg file.

Whether you prefer the fewer, monolithic .cfg files approach or the many, themes-oriented #include files approach is a matter of skill, temperament, and taste. You might be wise to begin with the monolithic files approach, then switch to the #include files approach when you are more comfortable using and managing PIKT.

Summing up, we can offer these specific words of advice:

Start out small, and grow things up from there.
Don't do everything at once.
Take things step by step.
Run 'piktc -cv' often.
Back up your configuration frequently (and perhaps use a revision control system).
Master the suggested debugging techniques.
Use '#if ... #endif' and '#ifdef ... #endifdef' intelligently and only when and where necessary.
Test things out on a small-scale first, initially on just one system, and when testing, turn off command execution and paging.
Be thoughtful, careful, and patient.
Join the pikt-users mailing list.

Good luck configuring and using PIKT!

1st page