Getting Started

(The Getting Started portion of this Tutorial was originally written by Thomas Vander Stichele.  The rest of the Tutorial was written by Robert Osterlund.  Since the additional material bases on the revised configs_starter, and in order to make the introduction to PIKT easier still for the new user, we have revised Thomas' original Getting Started guide, merging his examples into the revised configs_starter.)

(A note about page layout:  In the interest of readability, we have added artificial line wraps in several examples.  Even though displayed here broken up across several screen lines, in general quoted strings, preprocessor directives, etc. should all be unbroken on a single line.)

Getting Started

The purpose of this Getting Started guide is to help the new user get PIKT up and running easily.  PIKT is a complex system, and we want to give the new user a quick taste of what it can do without frustrating him or her too much in the beginning.

Before We Begin

You need:

• a machine running a UNIX-like operating system (we used Red Hat Linux 7.0 when writing this tutorial)
• gcc, make, flex, bison, and rx (see the INSTALL file for version numbers)

In this document, we'll be referring to the PIKT source directory as /usr/local/src/pikt-x.y.z, where x.y.z should be replaced by the version number of your PIKT source.  For example, the latest PIKT version is 1.18.0, and thus the PIKT source dir is /usr/local/src/pikt-1.18.0.  Be sure to replace x.y.z with your PIKT version number where applicable in this document.

The homepage for PIKT is at this site.  You should download the source code, test suite, sample configuration, and documentation.  It's the first link on the PIKT Software page.

Move the pikt-current.tar.gz file to your /usr/local/src directory and change to that directory.

Extract the package with

tar xzf pikt-current.tar.gz

or

gzip -dc pikt-current.tar.gz | tar -xf -

(if your tar does not support -z) and enter the directory

cd pikt-x.y.z

Read the INSTALL file.  (We assume that you will follow Plan A and not use Linux RPMS.).  Here's a quick list of the steps.  If you have any problems during a step, some common issues are dealt with in the next paragraph.  If one of the steps goes wrong, stop the list and start thinking about what went wrong.

• Be root.
• Add the line

    piktc_svc      806422610
  
  

  to /etc/rpc (there's a tab between the two columns)
• Do this

    mkdir `./config.guess`
  
  

  (you need to use the backtick quotes)
• Do this

    cd `./config.guess`
  
  

• Do this

    ../configure 2>&1 | tee configure.log
  
  

• Do this

    make 2>&1 | tee make.log
  
  

• Do this

    make check 2>&1 | tee make_check.log
  
  

  (Please do something more productive while waiting for the checks to complete.  On older machines, these tests may take several hours.)
• Do this

    make install 2>&1 | tee make_install.log
  
  

• Make a sym-link to your PIKT install directory:

    ln -s pikt-x.y.z /pikt
  
  

  (This is optional, but assumed for the rest of this document.  You can install the PIKT distribution in a different directory if you want, or make the symbolic link somewhere else.)

Some remarks about the install and possible problems you might encounter:

• If you can't be root, you might not need to be running PIKT anyway.  If you do need to run PIKT, sit down with your sysadmin and walk through this install guide together.  If you su, please use 'su -' to change to root; most distributions haven't set up /sbin and /usr/sbin in the path if you do a regular su.
• Later on, you should use a different rpc number, but for now, we'll leave it at this.
• If configure fails because it cannot find rpcinfo:  Check the location of rpcinfo: 'whereis rpcinfo'.  It usually resides in /usr/sbin.  If it's there, you don't have that directory in your path.  You did do 'su -' as per above, didn't you?
• If configure complains about a PVTKEY:  Ignore it for now.  Read up on it (and change it) later on after completing the tutorial.
• If configure complains about an FQDN:  You should make sure that your system can detect it's own fully qualified domain name.  Ideally, if you execute 'hostname' you should get an FQDN pointing back to your own machine.  The easiest way is to set it by typing it after the hostname command, e.g. 'hostname mymachine.mydomain'.  This is, however, only a temporary fix, and you are advised to ensure that either 'hostname' or 'nslookup hostname' returns a fully qualified, dotted domain name.  If you do not know how to do this, please consult your system administrator.  Check your /etc/hosts file as well; the line for your machine should read

    192.168.1.1     master.mydomain master
  
  

  (if your machine has this ip and is called master.mydomain).  If you cannot tell why configure failed:  inspect configure.log.
• 'make check' fails:  Inspect make_check.log for possible reasons.
• 'make check' seems to hang at 'Test 119: piktc -KvT +H vienna':  Please try adding the line

    tcp_only        yes
  
  

  to the PIKT.conf file located in src/test/etc of your PIKT distribution.  (Note: this line is installed by default in recent PIKT versions.)

Now you can start the PIKT RPC service which will be responsible for executing commands on behalf of the piktc program.

/pikt/bin/piktc_svc

Starter Setup

In this section, we'll describe how to arrive at a starter working configuration for your PIKT system.  The source distribution contains three sets of configuration files:

• configs_samples, used for PIKT testing and full of good examples
• configs_starter, a starter configuration which we will use in this Tutorial
• configs_minimal, which are basically empty except for some comments

We'll use the configs_starter set.  Copy these by executing

cp -r /usr/local/src/pikt-x.y.z/lib/configs_starter/* /pikt/lib/configs

or

cd /pikt/lib/configs
tar -cf - -C /usr/local/src/pikt-x.y.z/lib/configs_starter . | tar -xf -

Then go to your configs directory (if you're not already there)

cd /pikt/lib/configs

Some of the .cfg files you find here may be empty except for some comments.  One important note here is that some of the files HAVE to contain directives.  You cannot leave those you don't use empty and hope everything works.  A minimal setup for use with piktc, piktc_svc, and piktd requires systems.cfg, macros.cfg, alarms.cfg, and alerts.cfg

For the example setup used in this tutorial, we'll assume you have a RedHat Linux host called 'mysystem.mydomain'.  In everything that follows (file edits, commands, etc.), please substitute your own hostname and domain where appropriate.

Also, in the following .cfg files, if it looks like we used tabs to separate text, then we probably did!

First of all, we'll set up systems.cfg.  Here's where you define the systems used in your network.  You can also put them in groups according to your logical network structure.  For now this file can be kept pretty simple:

///////////////////////////////////////////////////////////////////////////
// 
// PIKT systems.cfg
// 
///////////////////////////////////////////////////////////////////////////
// 
// since #if-#endif's reference system names, this file cannot contain
// any #if-#endif's, since the system names are still in the process of
// specification!  (neither can this file contain #ifdef's or any of the
// other #-style preprocessor directives, except for #include; it can
// contain comments, though and obviously)
// 
///////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////

// hosts, grouped by operating system or operating system version

linux
        hosts           mysystem

///////////////////////////////////////////////////////////////////////////

// host aliases

mysystem
        aliases         piktmaster      // note: although =piktmaster is a
                                        // predefined macro, the piktmaster
                                        // alias here is needed if you want
                                        // to use '#if piktmaster' later
                                        // on in the config files
                        mysystem.mydomain

///////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////

...                     [ignore the rest of this file for now]

///////////////////////////////////////////////////////////////////////////

This file:

• Defines the group 'linux' containing the host 'mysystem'.
• Defines two aliases for mysystem, namely 'piktmaster' (which is used as the master control machine) and 'mysystem.mydomain', the FQDN.

A First Alarm

Now we're ready for our first alarm.  We'll keep it simple, safe, and useless for now.  What we'll do is write an alarm to check if a certain file in /tmp contains a word.

The file we'll be monitoring is /tmp/fence, and it should contain either 'up' or 'down'.

In alarms.cfg, the first alarm script is:

///////////////////////////////////////////////////////////////////////////

CheckFenceUpCritical    // check if the fence is still up

        init
                status active
                level critical
                task "Is the fence in /tmp/fence still up?"
                input file "/tmp/fence" 
                dat $result 1

        rule
                if $result !~ "up"
                        output mail "/tmp/fence is down!"
                endif

///////////////////////////////////////////////////////////////////////////

(Ignore the rest of the alarm scripts for now.)

How does it work?

First of all, you give your alarm a name.

Then you put in the stuff to describe the alarm.  Give it a status, a level, and a description (with 'task').

Then the alarm needs some input to check on; this is done with the 'input' tag.  We'll check the contents of the /tmp/fence file.  You could also take input from a process by using 'proc' instead of 'file' in the input line.

Then you store the data returned by the input statement in variables.

The alarm uses rules to act upon each line of the input data. These are set with the rule directive.  In this case, the rule is simple: we check if the file contains the word 'up'.  In case it doesn't, we'll notify the administrator by writing a descriptive mail of the problem.  This is done with 'output mail'.

Now we're ready to configure the alert.

You will find this in your alerts.cfg:

///////////////////////////////////////////////////////////////////////////

Critical                // things that should be dealt with before too long,
                        // preferably by day's end; (things reported here
                        // may not be especially "critical" but are so
                        // designated to conform with syslog's log levels)

        timing          * * * * *
//      timing          20 * * * *
        mailcmd         "=mailx -s 'PIKT Alert on =pikthostname:
                                            Critical' =piktadmin"
        alarms
                        CheckFenceUpCritical

...                     [ignore the rests of the (commented out) alarms,
                         as well as the rest of this file, for now]

///////////////////////////////////////////////////////////////////////////

What we do here is define the alerts that are Critical and how they're treated.

With the timing tag, we define how often the Critical alarms should be run.  The text after the timing tag uses the same syntax as lines in the cron files (check man crontab for a more thorough explanation).  This line tells the alert to check every minute.  (Ignore the commented out timing line for now.)

The mailcmd tag defines what command to use to mail.  This line generally contains a few pieces defined in the macros.cfg file.  Every line you see preceded by '=' is defined somewhere else (in one of the macros.cfg files).  '=mailx' will resolve to the mail program on your system, =pikthostname to the current host, and =piktadmin will resolve to the root e-mail address on your system.

The alarms tag lists the alarms to be grouped under Critical.

Now, try and execute:

/pikt/bin/piktc -cv +H mysystem

If all goes well, you should get the line

checking mysystem...

And that's it.  If you didn't get any errors, we're on the right track.  If you did, you most likely made a mistake in the one file you've been instructed to edit so far, systems.cfg.  Please review the instructions above.

Just to make sure, we can also double-check the files:

/pikt/bin/piktc -Cv +H mysystem

Then you should get

doublechecking mysystem...

This should work as well.

Now we can actually install the alarm on the host.  In a real situation, this would entail preprocessing the script to the target host and copying it to the other host.  In this example, the target host is the same as the master host, but the installation will still happen as though they were two different machines.

Install the alert by typing

/pikt/bin/piktc -iv +A Critical +H mysystem

This tells the piktc script to install all 'Critical' alerts on host 'mysystem'.

You should get

processing mysystem...
installing file(s)...
Critical.alt installed

Before we enable it, we're going to execute the alert manually.

First, put the fence up:

echo up > /tmp/fence

Then, in another terminal, open up your mail reader for the root user, since you will get mail when the alarm doesn't find the fence up.

Now, type:

/pikt/bin/piktc -xv +A Critical +H mysystem

This executes all the 'Critical' alerts.  You should get

processing mysystem...
executing alert(s)/script(s)...
Critical executed

You shouldn't get any mail at this point since the fence is up and everything is normal.

Now, bring the fence down:

echo down > /tmp/fence

And re-execute the alert:

/pikt/bin/piktc -xv +A Critical +H mysystem

After a few seconds, you should get a mail in root's mailbox looking like this:

Subject: PIKT Alert on mysystem: Critical


                                PIKT ALERT
                         Sat Sep 22 13:26:31 2001
                                 mysystem

CRITICAL:
    CheckFenceUpCritical
        Is the fence in /tmp/fence still up?

        /tmp/fence is down!

This means our alarm script works!  Time to enable it and have PIKT check it automatically.

Before doing so, put the fence back up:

echo up > /tmp/fence

Now the fence is back up.  We can safely enable the alert with piktc.  We'll supply a few options:

• 'e' used to enable the alert by registering a crontab-like entry for the alert in the target host's piktd.conf
• 'r' to restart piktd on the target host, thus allowing it to load the new alert entry
• 'v' to get more verbose output from the piktc command.

So, issue the command

/pikt/bin/piktc -ev +A Critical +H mysystem

giving

processing mysystem...
enabling alert(s)...
Critical enabled

The piktd daemon is responsible for executing alerts on your behalf.  Start it up by typing:

/pikt/bin/piktd

(Note that you could have both enabled the alert and started the piktd with the single command '/pikt/bin/piktc -erv +A Critical +H mysystem'.)

Wait a bit until a minute has passed (use 'date' to check).  After that, bring the fence down:

echo down > /tmp/fence

Now wait until the next minute; again you should get a mail.  This time you got it automatically!

Wait another two minutes.  You get two new mails.  You will keep getting mails every minute.  To avoid this, bring the fence back up:

echo up > /tmp/fence

You shouldn't get any mails anymore.

To bring your system back to the state it was in before starting to learn about PIKT, issue the following commands:

/pikt/bin/piktc -k +H mysystem
/pikt/bin/piktc -K +H mysystem

The first command kills the piktd daemon on the target host, the second one kills piktc_svc.  Be sure to execute them in the right order; it's the piktc_svc process that is responsible for receiving commands issued through piktc!

This concludes our first alarm.

If All Else Fails

If you can't get PIKT to compile or test, please supply the PIKT maintainers with as much debug info as possible.

• For the configure step, do a '../configure 2>&1 | tee configure.log'
• For the make step, do a 'make 2>&1 | tee make.log'
• For the test step, do a 'make check 2>&1 | tee make_check.log'

Send the three files as plaintext, together with explanatory comments, to .

Quick Reference

• Checking for syntactical validity of all configuration files for all hosts:

    /pikt/bin/piktc -cv +H all
  
  

• Doublechecking just your <mysystem> for syntactical validity of its configuration files:

    /pikt/bin/piktc -Cv +H <mysystem>
  
  

• Install all your alerts on <host>:

    /pikt/bin/piktc -iv +A all +H <host>
  
  

• Execute all your alerts on <host>:

    /pikt/bin/piktc -xv +A all +H <host>
  
  

• Enable all your alerts on <host>:

    /pikt/bin/piktc -ev +A all +H <host>
  
  

• Restart the piktd on <host>:

    /pikt/bin/piktc -rv +H <host>
  
  

prev page

1st page

next page