Init Section

(NOTE: Some of the techniques shown or described on this page--marked in purple--require new features in the latest official PIKT 1.19.0 release (pikt-current.tar.gz) that are unavailable in any previous version.)

After the script identifier, an init section usually follows. In the init section, you prepare the groundwork for subsequent script actions.

For example, here is a typical init section, from a script named RunawayCPUProcs:

        init
                status active
                level urgent
                task "Report runaway processes using a high % of the CPU"
                input proc "=psls | =trim(160) | =awk '\$3>=80.0'"
                filter "=egrep '^[A-Za-z0-9\-]+[ ]+[0-9]+ ' | =zapinterpreters"
                dat $PID 2
                dat #cpu 3
                dat #mem 4
                dat $sta 9
                dat $tim 10
                dat $prc 11
                keys $PID

The general format of the init section is:

        init
               status                  active|inactive|suspended|
                                       testing|debugging
               level                   emergency|urgent|critical|
                                       error|warning|notice|
                                       info|debug
               task                    "<script description>"
               input proc|file|logfile "<process|file|logfile|string>"
                                           ["<bakfile>"]
               filter                  "<process>"
               seps                    "<separators>"
               dat                     <var> <spec>
                                       ...
               keys                    <var> [<var> ...]

A script may have one of five different status settings:

active
inactive

suspended

testing

debugging

In normal operation, scripts have active status.

If a script is inactive, it is bypassed. Although it might seem that this field is useless, that is not the case. An administrator of a machine might not have access to the master control machine and might, for whatever reason, need to deactivate one or more scripts on a client machine. Changing "active" to "inactive"--on the client machine--achieves this.

suspended status is like inactive status. Scripts don't run in either case. Here is the difference: Suspended status is always logged, for example,

Mar 29 10:10:00 rouen pikt[31528]: [ID 9703 INFO] RunawayCPUProcsStats alarm in suspended status

while inactive status is only logged, for example,

Feb 11 22:32:02 prague pikt[30017]: [ID 9703 INFO] ProcessSystemDead alarm in inactive status

if verbose_log (in PIKT.conf) is set to true. (You might then schedule a log scanning script to remind you of suspended alarms on a regular basis.)

In testing status, script 'exec' and 'exec wait' statements become effectively 'output' (or 'output mail'), and command strings are reported and/or logged rather than executed, for example,

Feb 13 03:33:12 helsinki pikt[11959]: [ID 1 INFO] in TruncatePIKTLogFiles, exec wait
"/pikt/lib/programs/trunc.pl 1000 /pikt/var/log/piktd.log 2>> /pikt/var/log/Test.log;
/usr/bin/rm -f /pikt/etc/Test.exec.lock 2>/dev/null"

In debugging status, it's as if the 'pikt -G' debuG option were set but only for the scope of that script. In debuG mode, additional debugging information is output to stdout or logged.

An alarm script is given one of eight severity levels, analogous to syslog's severity levels. The severity levels are:

emergency
urgent
critical
error
warning
notice
info
debug

Note that "urgent" is used in place of syslog's "alert". You may also use the abbreviations "emerg", "crit", "err", and "warn".

In alert messages, alarms are sorted by severity levels, from "emergency" (highest) to "debug" (lowest). The idea here is to have more important alarm output appear toward the beginning of alert messages, and less important output appear toward the end.

Having said that, severity level designations are rather arbitrary. Interpret the meaning of "urgent", or what makes one alarm "critical" while another one merely a "warning", as you wish.

If for some reason you prefer that the alarm order you specify in the alerts.cfg listing determines the order of alarm output, you may override the default by adding this directive in PIKT.conf:

sort_messages           NO      [or: FALSE, OFF, ...;
                                 defaults to YES, ...]

"task" is a short description of the script's purpose. Note that, although the task description may contain PIKT macros, it may not contain (although this, too, might change in some future PIKT version) any function calls or other variable Pikt elements. Note, too, that you might need to backslash escape certain Pikt special characters (like "@", "#", "$", "%", "=", etc.) within the task description string.

When a script is run from the command line, status, level and task are pointless, therefore optional. When run by piktd with the intent to output to an e-mail and/or printer report, a script lacking status, level and task generates an error. In general, it is best always to include the status, level, and task description.

The primary script input is either the output of a process, the full contents of a text file, or logfile updates (new info since the previous script run). If a process, it can be any system process (including multiple processes tied together by pipes) yielding text output. Pikt does not deal with binary input.

If you add a second file path to 'input file' statements, as in

input file "/etc/passwd" "/etc/passwd.bak"

this signals the pikt script interpreter to open a temporary file, in the example case /etc/passwd.pikttmp, and write each input line to that temporary file--unless you have set the special reserved variable $outlin (or $outline or $outputline) for the current input line, in which case $outlin is written to the temporary file instead of $inlin.

If a script were reviewing the passwd file and encountered some problem for a particular line, a missing password for example, you could do this

if $password eq ""
        set $outlin = "$username:*:$uid:$gid:$gecos:$homedir:$shell"
fi

to lock out the account automatically.

To exclude a line, use

        set $outlin = $nil()

If you fail to specify a backup file in the 'input file' statement, $outlin is treated like any ordinary string variable.

When the input file is fully processed (at the end of the script, actually), /etc/passwd is backed up to /etc/passwd.bak (in the example), and the temporary file is moved in place of /etc/passwd--but only if one or more 'set $outlin' statements actually changed anything. The rewritten input file will have the same ownerships and permissions as the old. If no changes are indicated (or if there is some problem making the backup, for example a badly specified file path), the input file is left completely unchanged. (Note that without the backup file specification and any 'set $outlin' statements, input files are also left completely unchanged.)

If you specify 'input "<string>"', this is equivalent to 'input proc "echo <string>"'.

Before script processing, input is passed through an optional filter. In a proc statement, processes can pass output to a filter through pipes, making a separate filter statement unnecessary. filter statements are really intended for use with files and logfiles.

Input is processed, line by line. Before processing, an input line is broken apart, with each part assigned to a variable name.

One or more dat statements map input data to variables. The dat ("data", too, is legal) statement takes one of three forms. The ordinal form is:

        dat <var> [x]

where <var> is assigned to the data field in the x position.

By default, data fields are separated by one or more spaces and/or tabs. You override this with the seps statement. "<separators>" is a string of one or more characters (including possibly the default space and tab in addition to other characters).

In ordinal dat statements, $ signifies the last field, $-1 signifies the next-to-last field, $-2 the field before that, and so on.

You may combine field specifiers of the form 1, 2, ..., $, $-1, $-2 in the same set of data specifications.

Square brackets ("[" and "]")around the ordinal field number say to strip any leading and/or trailing whitespace characters. The brackets are optional.

The second form of the dat statement specifies columnar data:

        dat <var> [x,y]

This says to assign <var> to data found in columns x through y. In a series of such statements, column positions may not overlap, but don't have to be contiguous (i.e., there may be gaps).

Here, too, the optional square brackets say to strip leading/trailing whitespace--even if legitimate white space is found in the indicated columns. (Whitespace internal to the data string is not stripped.)

The third and final form of the dat statement employs a regular expression:

        dat "<regexp>"

Note that <var>'s are not specified. Rather, the special variable $0 captures the portion of the input line matching the entire regular expression. $1 captures the first part of the <regexp> enclosed by parentheses (if any), $2 captures the second parenthesized subexpression, and so on. You may reference these regexp values also by $[0], $[1], ..., especially within for loops (e.g., $[#i]). (See the Regular Expressions section of this Reference.)

If no dat statement is given, any or all of the following by default refer to the entire input line: $0, $[0], $inlin, $inline, $inputline. (Pikt provides synonyms for many of the language keywords, in particular, abbreviated versions of the longer keywords).

Even if you specify numbered or columnar variables in dat statements, you can still access all parsed data by means of $0 ($[0]), $1 ($[1]), ...

Concluding the init section, the optional keys line lists variables used as database lookup keys when referring to history values (values stored from previous script runs). (See the History Logging section of this Reference.)

Refer to the sample alarms.cfg for many more examples.

1st page