(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.)
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
- 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)
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.gzor
gzip -dc pikt-current.tar.gz | tar -xf -(if your tar does not support -z) and enter the directory
cd pikt-x.y.zRead 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 806422610to /etc/rpc (there's a tab between the two columns)
mkdir `./config.guess`(you need to use the backtick quotes)
../configure 2>&1 | tee configure.log
make 2>&1 | tee make.log
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.)
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.)
- 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 yesto the PIKT.conf file located in src/test/etc of your PIKT distribution. (Note: this line is installed by default in recent PIKT versions.)
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
cp -r /usr/local/src/pikt-x.y.z/lib/configs_starter/* /pikt/lib/configsor
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/configsSome 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 mysystemIf 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 mysystemThen 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 mysystemThis tells the piktc script to install all 'Critical' alerts on host 'mysystem'.
You should get
processing mysystem... installing file(s)... Critical.alt installedBefore we enable it, we're going to execute the alert manually.
First, put the fence up:
echo up > /tmp/fenceThen, 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.
/pikt/bin/piktc -xv +A Critical +H mysystemThis executes all the 'Critical' alerts. You should get
processing mysystem... executing alert(s)/script(s)... Critical executedYou 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/fenceAnd re-execute the alert:
/pikt/bin/piktc -xv +A Critical +H mysystemAfter 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/fenceNow 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.
/pikt/bin/piktc -ev +A Critical +H mysystemgiving
processing mysystem... enabling alert(s)... Critical enabledThe 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/fenceNow 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/fenceYou 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 mysystemThe 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'
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|