PIKT INSTALL
PIKT INSTALL
PIKT employs GNU autoconf/automake (a/a) for building, testing, and
installation.
You have two options at this point:
--Plan A. Utilize the a/a procedure to do just about everything
automatically.
--Plan B. If you are a Linux user, consider fetching the PIKT RPMs off the
PIKT Web site.
(There used to be a different Plan B, the option for making use of
precompiled binaries off the PIKT Web site. We regret that we can no longer
offer that option.)
You will want to make Plan A work if at all possible. Use Plan B if (you are
a Linux user and) you are most comfortable working with RPMs.
For Linux and AIX users especially, special caveats. With Linux, small
differences in the distributions can sometimes have negative consequences
for the PIKT compilation and installation. You might have to pay special
attention to fixing file paths. If you are an AIX user, study the README.AIX
file carefully.
Note that if you correctly build the PIKT binaries on one machine, you
should be able to copy those binaries over to other machines of the same
operating system. It is usually not essential to do a separate 'make' and
'make install' on each slave machine.
BUT: This does not always work with all machines. We have installed and
tested correct everything on one system, then copied the binaries over to
another system, only to see things fail. This will be the case if certain
essential file paths (e.g., to the ps, tail, and rm commands) resolve to an
NFS-automounted /usr/local/bin/ on the build machine, while those
commands resolve to /usr/bin/ on the target machines. The
binaries now include run-time file path checks. If certain crucial
compiled-in file paths fail a stat() test, the binary will abort then
report and log the error. Beginning with version 1.15.0, you may set
command file paths in PIKT.conf (e.g., "arpcmd /usr/sbin/arp") to override
the compiled-in command file paths and avoid these run-time errors.
For best results, however, you might want to do a separate compile on each
machine!
In order to make and install the PIKT binaries, you will need the following
GNU packages installed on your system: gcc, make (gmake), flex, bison, & rz.
If you lack any of these packages, they can be found at prep.ai.mit.edu
or many of its mirror sites. Most Linux installations will have the
first four packages in a standard setup, BUT YOU MAY HAVE TO INSTALL THE
RX PACKAGE SPECIALLY. Note that the GNU make, flex, bison, and rx packages
are now available for download at the PIKT Web site. We will make other
GNU packages (including gcc) available there, too, as needed.
PIKT has been successfully built and installed on the following Unixes:
Linux (various flavors), AIX, Digital UNIX, FreeBSD, HP-UX, IRIX, OpenBSD,
SCO OpenServer, and Solaris. Although you might try to build and install
the latest versions of PIKT on SunOS, we no longer officially support it.
(See the README.SUNOS file.)
No attempt has been made to build any of the PIKT binaries on any other
operating system or using anything except the listed GNU tools. We have
reports of other, non-GNU components working, especially the OS-standard
(awk) regex. The automake/autoconf code will make the necessary adjustments
for this. (If your build utilizes regex and you then get into
difficulties, consider starting over, doing a 'configure --without-regex'
and if needed setting 'LIBS = -lrx' in `./config.guess`/src/piktd/Makefile.
This assumes that you have GNU RX installed.)
To begin, first unzip/untar the PIKT compressed tar file. (If you
are reading this, we suppose you've already done that!) This should
create a directory pikt-x.y.z (where x.y.z represents the version and
release number). The unpacking will also create directories you can use
for PIKT's operation.
PLAN A (Using Autoconf/Automake)
Basic Installation
These are mainly generic installation instructions.
The 'configure' shell script attempts to guess correct values for
various system-dependent variables used during compilation. It uses
those values to create a 'Makefile' in each directory of the package.
It may also create one or more '.h' files containing system-dependent
definitions. Finally, it creates a shell script 'config.status' that
you can run in the future to recreate the current configuration, a file
'config.cache' that saves the results of its tests to speed up
reconfiguring, and a file 'config.log' containing compiler output
(useful mainly for debugging 'configure').
If you need to do unusual things to compile the package, please try
to figure out how configure could check whether to do them, and mail
diffs or instructions to the address given in the README so they can
be considered for the next release. If at some point config.cache
contains results you don't want to keep, you may remove or edit it.
The file configure.in is used to create configure by a program
called 'autoconf'. You only need configure.in if you want to change
it or regenerate configure using a newer version of autoconf.
Before you proceed, you might want to note the CONFIGURING PIKT FOR A
FIREWALL section below, and integrate its special instructions into the
following compile and setup steps.
The simplest way to compile this package is:
--If you are operating as root, edit the system /etc/rpc file to add
the line
piktc_svc 806422610
or some other piktc_svc RPC program number of your choosing. This
should be any number whose hexadecimal equivalent falls between
0x20000000 to 0x3FFFFFFF. Use the number you select across all of
your site's PIKT installations.
If you are not doing the build as root, the number above is compiled
into the piktc and piktc_svc binaries by default. You will be able to
build and self-test the binaries, but you will not be able to run
piktc_svc without the /etc/rpc registration.
--In the distribution top-level directory, do a 'mkdir `./config.guess`'.
Or, if you prefer, you can mkdir some other directory name in a
different directory tree.
--cd to the directory you just mkdir'ed and run '../configure' to
configure the package for your system. If you're using csh on an
old version of System V, you might need to type 'sh ./configure'
instead to prevent csh from trying to execute configure itself.
If your PIKT distribution comes on CD ROM, or if you want to build
the package in an entirely different directory tree, you will have
to run /configure instead.
********************************* IMPORTANT ********************************
Do not attempt to do a ./configure in the top-level directory. This will,
in all likelihood, not work. Please do all program builds in a separate
directory. It is recommended that you follow the procedure described
above. (We discourage doing the ./configure and make from the top-level
directory, because it is quite possible the distribution might reside on
CDROM or some other unwritable medium, and we have programmed around this.)
********************************* IMPORTANT ********************************
Running configure takes a while. While running, it prints some
messages telling which features it is checking for.
In the 'configure' output, you might see a warning to "Please edit
config.h and fix the entry for PVTKEY." By default, the PIKT pvtkey
private encryption key is set to PVTKEY, defined by default in src/config.h
as "CHANGE_ME". You can override this either by editing src/config.h
before doing the 'make' (below) or by specifying '--with-private-key=FOO'
when doing 'configure'. PVTKEY is compiled into the binaries (and can
be overridden by a setting in PIKT.conf or a separate etcdir/private_key
file).
*********************************** NOTE ***********************************
'configure' attempts to determine the system's fully qualified domain name
(FQDN) using either the command 'hostname' or 'uname -n'. If neither of
those returns the FQDN (returning instead just the simple system hostname),
'configure' issues the 'nslookup' command for the build system. If that
fails to determine the FQDN, 'configure' will abort with the message
"Can't find the fully-qualified domain name of this host." You should
attempt to correct this, either by editing your /etc/hosts file or by
making the appropriate DNS registration. Failing that, you could hand
edit the configure script, setting the FQDN directly (e.g.,
FQDN=vienna.uppity.edu). Or try adding the '--fqdn' argument to the
hostname command in configure.
*********************************** NOTE ***********************************
--Type 'make' to compile the package. (You might have to execute
'env CC= make' or possibly substitute 'gmake',
depending. This last point deserves emphasizing. You need to use GNU
make in order to compile PIKT.)
--Before you proceed, make sure that portmap (or possibly rpcbind or
portmapper) is running. PIKT requires the portmapper for network
communications. In particular, the command 'rpcinfo -p ' must
return a successful result (confirming portmapper operation).
--Optionally, type 'make check' to run the self-tests that come with
the package. These tests will be described at the end of this
document in the section VALIDATION SELF-TESTS.
--Type 'make install' to install the programs and any data files and
documentation.
'make install' copies the five PIKT binaries into the PIKT bin
directory, and copies a suitable PIKT.conf file into the PIKT etc
directory.
Optionally, you may use 'make install-strip' to install binaries stripped
of debugging info. This results in binaries much reduced in size.
--You can remove the program binaries and object files from the
source code directory by typing 'make clean'. To also remove the
files that configure created (so you can compile the package for
a different kind of computer), type 'make distclean'. There is
also a 'make maintainer-clean' target, but that is intended mainly
for the package's developers. If you use it, you may have to get
all sorts of other programs in order to regenerate files that came
with the distribution.
If you have gone as far as a successful 'make install', you can proceed
to the section POST-INSTALL SETUP below.
Compilers and Options
Some systems require unusual options for compilation or linking that
the configure script does not know about. You can give configure
initial values for variables by setting them in the environment. Using
a Bourne-compatible shell, you can do that on the command line like
this:
CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
Or on systems that have the env program, you can do it like this:
env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
Compiling For Multiple Architectures
You can compile the package for more than one kind of computer at the
same time, by placing the object files for each architecture in their
own directory. To do this, you must use a version of make that
supports the VPATH variable, such as GNU make. cd to the
directory where you want the object files and executables to go and run
the configure script. configure automatically checks for the
source code in the directory that configure is in and in '..'.
If you have to use a make that does not supports the VPATH variable,
you have to compile the package for one architecture at a time in the
source code directory. After you have installed the package for one
architecture, use 'make distclean' before reconfiguring for another
architecture.
Installation Names
By default, 'make install' will install the package's files in
/usr/local/pikt-x.y.z/bin, /usr/local/pikt-x.y.z/man, etc. You can specify
an installation prefix other than /usr/local by giving configure the
option '--prefix=PATH'.
You can specify separate installation prefixes for architecture-specific
files and architecture-independent files. If you give configure the
option '--exec-prefix=PATH', the package will use PATH as the prefix for
installing programs and libraries. Documentation and other data files
will still use the regular prefix.
In addition, if you use an unusual directory layout you can give
options like '--bindir=PATH' to specify different values for particular
kinds of files. Run 'configure --help' for a list of the directories
you can set and what kinds of files go in them.
If the package supports it, you can cause programs to be installed
with an extra prefix or suffix on their names by giving configure the
option '--program-prefix=PREFIX' or '--program-suffix=SUFFIX'.
Specifying the System Type
There may be some features configure can not figure out automatically,
but needs to determine by the type of host the package will run on.
Usually configure can figure that out, but if it prints a message saying
it can not guess the host type, give it the '--host=TYPE' option. TYPE can
either be a short name for the system type, such as 'sun4', or a canonical
name with three fields:
CPU-COMPANY-SYSTEM
See the file config.sub for the possible values of each field. If
config.sub isn't included in this package, then this package doesn't
need to know the host type.
If you are building compiler tools for cross-compiling, you can also
use the '--target=TYPE' option to select the type of system they will
produce code for and the '--build=TYPE' option to select the type of
system on which you are compiling the package.
Operation Controls
(Not all of these have been tested in the PIKT a/a.)
configure recognizes the following options to control how it
operates.
--cache-file=FILE
Use and save the results of the tests in FILE instead of
./config.cache. Set FILE to /dev/null to disable caching, for
debugging configure.
--help
Print a summary of the options to configure, and exit.
--quiet
--silent
-q
Do not print messages saying which checks are being made. To
suppress all normal output, redirect it to /dev/null (any error
messages will still be shown).
--srcdir=DIR
Look for the package's source code in directory DIR. Usually
configure can determine that directory automatically.
--version
Print the version of Autoconf used to generate the configure
script, and exit.
configure also accepts some other, not widely useful, options.
IF 'MAKE INSTALL' FAILED, OR YOU SIMPLY WANT TO SET UP BY HAND
If the 'make install' somehow failed for you, you will have to proceed as
follows.
--If your production PIKT HOME directory is, for example, /usr/local/pikt-x.y.z
(or /usr/local/pikt-x.y.z is a symlink to some other directory), mkdir the
following directories, if they don't already exist:
/usr/local/pikt-x.y.z/bin
etc
lib
lib/alerts
lib/objects
lib/programs
lib/configs [optional if this is a master]
lib/configs/staging [optional if this is a master]
lib/configs/diffing [optional if this is a master]
var
var/histories
var/log
Or, if you prefer to do PIKT logging into /var, soft link var to
/var/pikt (var -> /var/pikt), and mkdir /var/pikt, /var/pikt/log &
/var/pikt/histories.
--If you haven't already done so, copy the binaries you compiled (resulting
from the 'configure' and 'make') into the bin directory.
--In the etc directory, create a file PIKT.conf. Here is a sample:
uid 0
master vienna.uppity.edu
domain uppity.edu
access local
'uid' is the numerical userid of the account executing the piktc
program, usually root (uid 0).
Set 'master' to the hostname of your master control system (the one you
would issue piktc directives from). This must be a fully-qualified
domain name (e.g., simply 'vienna' would not work).
Set 'domain' to the network domain of the master control machine.
Set 'access' to either 'global', if you want the current host's
piktc_svc to entertain piktc service requests from a master
machine in a different network domain; or set it to 'local',
if you want to restrict such requests to within the local domain.
The second option is more secure, but if you have more than one network
domain it would require more than one master, one for each domain.
--For security reasons, you should modify all file ownerships and
permissions. All PIKT files and directories should be root owned,
all directories 750, all program files in the bin and lib/programs
directories 750, and all other files 640. Everything should be group
owned by either daemon or other. Issue the appropriate chown, chgrp,
and chmod commands to make it so (the example assumes you have installed
into /usr/local/pikt-x.y.z or a directory that /usr/local/pikt-x.y.z links
to):
# find /usr/local/pikt-x.y.z -type d -exec chmod 750 {} \;
# find /usr/local/pikt-x.y.z -type f -exec chmod 640 {} \;
# find /usr/local/pikt-x.y.z/bin -type f -exec chmod 750 {} \;
# find /usr/local/pikt-x.y.z/lib/programs -type f -exec chmod 750 {} \;
# find /usr/local/pikt-x.y.z -exec chown root {} \;
# find /usr/local/pikt-x.y.z -exec chgrp daemon {} \;
If you are logging to /var/pikt, chmod/chown/chgrp the directories
therein also.
--Your goal should be to have your production PIKT directory tree look
as follows (assumes that $PIKTDIR, the PIKT home directory, is
/usr/local/pikt-x.y.z):
drwxr-x--- 2 root daemon 1024 Apr 16 22:33 /usr/local/pikt-x.y.z/bin
-rwxr-x--- 1 root daemon 261996 Apr 11 19:50 /usr/local/pikt-x.y.z/bin/pikt
-rwxr-x--- 1 root daemon 20588 Apr 11 19:50 /usr/local/pikt-x.y.z/bin/piktd
-rwxr-x--- 1 root daemon 21100 Apr 11 19:50 /usr/local/pikt-x.y.z/bin/piktc_svc
-rwxr-x--- 1 root daemon 199756 Apr 11 19:50 /usr/local/pikt-x.y.z/bin/piktc
-rwxr-x--- 1 root daemon 9072 Apr 11 19:50 /usr/local/pikt-x.y.z/bin/pikts
-rwxr-x--- 1 root daemon 15209 Apr 11 19:50 /usr/local/pikt-x.y.z/bin/piktx
-rwxr-x--- 1 root daemon 15096 Apr 11 19:50 /usr/local/pikt-x.y.z/bin/rkey
drwxr-x--- 4 root daemon 1024 Apr 16 22:37 /usr/local/pikt-x.y.z/var
drwxr-x--- 2 root daemon 1024 Apr 16 22:37 /usr/local/pikt-x.y.z/var/log
drwxr-x--- 2 root daemon 1024 Apr 16 22:37 /usr/local/pikt-x.y.z/var/histories
drwxr-x--- 2 root daemon 1024 Apr 16 22:34 /usr/local/pikt-x.y.z/etc
-rwxr-x--- 1 root daemon 122 Mar 23 07:39 /usr/local/pikt-x.y.z/etc/PIKT.conf
drwxr-x--- 6 root daemon 1024 Apr 16 22:34 /usr/local/pikt-x.y.z/lib
drwxr-x--- 2 root daemon 1024 Apr 16 22:34 /usr/local/pikt-x.y.z/lib/alerts
drwxr-x--- 2 root daemon 1024 Apr 16 22:35 /usr/local/pikt-x.y.z/lib/objects
drwxr-x--- 2 root daemon 1024 Apr 16 22:35 /usr/local/pikt-x.y.z/lib/programs
drwxr-x--- 3 root daemon 1024 Apr 16 22:35 /usr/local/pikt-x.y.z/lib/configs
drwxr-x--- 2 root daemon 1024 Apr 16 22:35 /usr/local/pikt-x.y.z/lib/configs/diffing
drwxr-x--- 2 root daemon 1024 Apr 16 22:35 /usr/local/pikt-x.y.z/lib/configs/staging
POST-INSTALL SETUP
--If you haven't already done so, edit the /etc/rpc file as described
above.
(NOTE: For greater security, you really should not use the default
RPCPRGNUM, 806422610. Instead, select any number whose hexadecimal
equivalent falls between 0x20000000 to 0x3FFFFFFF. The number you
select should be the one you register in /etc/rpc. Use that same number
across all of your site's PIKT installations.
After you run the 'configure' step, a small utility to generate random
RPC program numbers is installed in the `./config.guess` directory.
% ./rrpc -h
Usage : rrpc.pl [-d|-a|-x]
-d : outputs decimal number
-x : outputs hexa number
-a : outputs decimal, then hexa number
A sample run:
% ./rrpc -a
867401727
0x33b37fff
After registering the decimal number in /etc/rpc, for example,
piktc_svc 867401727
you should then do a 'make distclean'. You can then rerun 'configure',
and redo the 'make' and 'make install'.
You would use rrpc to generate a random RPC program number just once,
for your first build. For subsequent builds on other machines, use the
same number as the one generated on the first machine.)
--Add code snippets to launch piktd & piktc_svc on system startup. For
instance, in Solaris you might have the file /etc/rc3.d/S90pikt
#!/bin/sh
# start pikt--the service daemon and alert daemon
if [ -d /usr/local/pikt-x.y.z/etc ] ; then
cd /usr/local/pikt-x.y.z/etc
rm alerts *.lock 2>/dev/null
fi
if [ -d /var/pikt/histories ] ; then
cd /var/pikt/histories
rm *.tmp 2>/dev/null
fi
if [ -x /usr/local/pikt-x.y.z/bin/piktc_svc ] ; then
echo "starting piktc_svc"
/usr/local/pikt-x.y.z/bin/piktc_svc
fi
if [ -x /usr/local/pikt-x.y.z/bin/piktd ] ; then
echo "starting piktd"
/usr/local/pikt-x.y.z/bin/piktd
fi
--Create the necessary config files in /usr/local/pikt-x.y.z/lib/configs:
/usr/local/pikt-x.y.z/lib/configs/alarms.cfg
/usr/local/pikt-x.y.z/lib/configs/defines.cfg
/usr/local/pikt-x.y.z/lib/configs/alerts.cfg
/usr/local/pikt-x.y.z/lib/configs/macros.cfg
/usr/local/pikt-x.y.z/lib/configs/objects.cfg
/usr/local/pikt-x.y.z/lib/configs/programs.cfg
/usr/local/pikt-x.y.z/lib/configs/files.cfg
/usr/local/pikt-x.y.z/lib/configs/systems.cfg
There are three ways you can go about this:
Start from scratch. Recursively copy the lib/configs_minimal directory
to your configs directory. configs_minimal is a set of empty config
files except for a few helpful comments.
Use the basic starter set. lib/configs_starter is a simple, bare bones
configuration that should work on just about any system as is. The
configs_starter was actually developed for use with the Tutorial and
Getting Started guide (in the doc directory).
Use the configs_samples set. Just recursively copy the lib/config_samples
directory to your configs directory. Remember that you can comment out
individual lines using // or whole sections using /* */ when doing this.
(See the comments prefacing lib/configs_samples/macros.cfg for more
details.) If referenced include files are of no importance to you, simply
delete those files and remove their corresponding #include directive.
Unless you really know what you are doing, are patient and methodical,
and know a thing or two about programming, you might find using the complex
and ornate configs_samples to be a confusing, frustrating experience.
For most beginners, we advise them to start out small, either from
scratch or from the simple configs_starter, then "grow" their configuration
from there. Read the Tutorial!
NOTE: We provide you with the configs_samples and configs_starter to get
you up and running as quickly as possible, also to inspire development
of your own personal configuration. We make no claims that either of the
provided configs sets are "correct" or "complete".
(A project is underway to build a PIKT "standard library" of configuration
files. When that is implemented, configs_samples will be demoted to being
just one among potentially many sample configs in a future contrib directory
tree.)
NOTE: Before launching into full production use of PIKT, make sure,
especially in the case of Linux, that you doublecheck all file paths in
macros.cfg (and macros/unixcmds_linux_macros.cfg, if you are using the
configs_samples). We have come to grief over the occasional
differences between the Linux distributions in this regard.
--When finished tailoring your config files, issue the command
# /usr/local/pikt-x.y.z/bin/piktc_svc [append "&" for AIX, FreeBSD, HP-UX,
IRIX, Linux, OpenBSD, and SunOS]
to start the service daemon.
--Next, issue the command
# /usr/local/pikt-x.y.z/bin/piktc -cv +D generic +H
to check the syntactical validity of all config files, for
only. If you have configured for a set of machines, issue the command
# /usr/local/pikt-x.y.z/bin/piktc -cv +D generic +H all
to check all machine configurations.
Use the '+D generic' command-line option if you are using the
configs_samples files. We have wrapped '#ifndef generic ...
#endifdef' around site-specific portions of the configs_samples.
By using the '+D generic' option, you can extract a basic "starter
set" of scripts, programs, and data files.
If instead you are using the configs_starter set, since the non-generic
parts have been taken out, there is no need to use the '+D generic'
option. (Indeed, if you use the '+D generic' option on the configs_starter,
an error will result, because that logical flag is undefined in that
starter set.)
If you run 'piktc -c' against the configs_minimal, that will cause an
error, since that set is without content (until you add to it)!
If you are the cautious type, you can also use the '-D doexec' option.
This disables any exec actions that might alter your system, and
enables reporting only.
--To install target config files on the current master, issue the
command
# /usr/local/pikt-x.y.z/bin/piktc -iv +A all +P all +F all +O all +H
or, using the configs_samples
# /usr/local/pikt-x.y.z/bin/piktc -iv +D generic +A all +P all +F all +O all +H
You will not be able to install onto any slave systems until you
have piktc_svc up and running on those systems.
--If your piktc install commands fail, try looking at the piktc.log and
piktc_svc.log files in /usr/local/pikt-x.y.z/var/log. For added log output,
try running both piktc and piktc_svc in debug (-G) mode. For even more
debug output, consider setting 'verbose_log' to 'yes' in PIKT.conf.
--If you get "access denied" messages from your piktc commands, and if
you can't figure out the cause from the log files, adding 'call_back no'
to PIKT.conf might help (but at the expense of reducing your security).
Try also, in PIKT.conf, setting 'authenticate_by_master' to 'no', and
'authenticate_by_master_address' to 'yes'; if the latter, be sure also
to set 'master_address' to the IP address of the master system.
Another thing you might try is setting 'tcp_only true' in your PIKT.conf
(this is the installation default). This might help you avoid some
potential firewalling difficulties. See the CONFIGURING PIKT FOR A
FIREWALL section below for more details.
If piktc or piktc_svc complain that they can't determine your host's
fully qualified domain name, check your /etc/hosts file. You might have
to change, for example, this
111.222.123.101 vienna loghost
to this
111.222.123.101 vienna.uppity.edu vienna loghost
--If you encounter other difficulties, for additional tweaks to try, read
the PIKT.conf section of the PIKT Reference Manual.
--To enable the alerts locally, issue the command
# /usr/local/pikt-x.y.z/bin/piktc -ev [+D generic] +A all +H
--You can, if you wish, test your alarms at the command line, for example
# /usr/local/pikt-x.y.z/bin/pikt +A Urgent
--Then, start the local piktd
# /usr/local/pikt-x.y.z/bin/piktc -rv +H
--To check the status of your alerts, do the command
# /usr/local/pikt-x.y.z/bin/piktc -sv +A all +H
Again, you must have the pikt, piktd & piktc_svc binaries installed on all
remote slave systems (piktc and pikts are installed on the master machine
only), and pikt_svc must be running on those systems, before you can
install and enable alerts and start the piktd daemon on those systems.
--If all goes well, you should start receiving error reports (or maybe not,
if you administer perfect systems!) sooner or later. If you don't, and
until you've got a set of alarms in place to monitor the PIKT log files
for errors, you will want to investigate those log files for clues for
what, if anything, has gone wrong.
--After you have all client machines set up properly with running
piktc_svc, remember to install svcstart.pl (in the sample programs.cfg) in
/usr/local/pikt-x.y.z/lib/programs on all machines. (You kill the service
daemon with the -k option, and restart with the -r option.) This will
come in handy. Note that for AIX, FreeBSD, HP-UX, IRIX, Linux, OpenBSD,
and SunOS systems, you will have to issue the svcstart.pl commands directly
on those systems. In our experience, you can rsh svcstart.pl commands
to Solaris systems only; rsh'ing svcstart.pl to AIX, FreeBSD, HP-UX, IRIX,
Linux, OpenBSD, and SunOS systems will result in a hang.
--Once you have the PIKT binaries up and running, and if your setup is
bug-free (i.e., there are no discernible problems with the binaries,
although you may and will probably still encounter occasional errors
in your configurations), you might consider stripping debugging info
out using the commands:
# cd /usr/local/pikt-x.y.z/bin
# strip *
This will give you more compact binaries of 16K to 400K in size
(about one quarter their non-stripped size), at the expense of
removing debugging info (for the binaries; routine PIKT error logging
to the log files would continue).
--If you install PIKT in different places on different machines--for example
in /usr/local/pikt-x.y.z on one machine, in /usr/local/pikt on another, and
in /home/pikt on a third, we *strongly* advise that you create these links
/pikt -> /usr/local/pikt-x.y.z
/pikt -> /usr/local/pikt
/pikt -> /home/pikt
so that you can reference all PIKT components in a common location, i.e.,
/pikt (or whatever other common link location you choose).
--If you encounter problems such as PIKT binaries exiting immediately with
no apparent effect (and with no useful error indicator in the appropriate
log file), you may be experiencing path problems. You can try this: (a)
Add the PIKT bin directory (e.g., /pikt/bin) to root's program PATH. (b)
Use absolute paths everywhere as much as possible. That is, avoid using
relative paths like './piktd' or implied paths like 'piktd'. Use absolute
paths like '/pikt/bin/piktd' instead.
Good luck with the installation!
CONFIGURING PIKT FOR A FIREWALL
When installing PIKT, the 'configure' operation will set the piktc_svc port
number to 850 by default. You can change this by instead doing
../configure ... --enable-rpcprtnum=XXX ...
where XXX is some other unused system port. Changing 850 to some other
unused port number is advisable.
After the 'make' step, you will want to add this line to PIKT.conf (on both
piktmaster and slave systems)
tcp_only TRUE
which will have PIKT use only TCP and avoid using UDP altogether. (There is
little reason not to do this.)
When you run the compiled piktc_svc binary, it binds itself to port 850 (or
whatever other port number you specified in the 'configure' step) for TCP
traffic. The portmapper will assign some other unspecified port for UDP
traffic, but since you have set tcp_only to TRUE (or YES or the equivalent) in
PIKT.conf, UDP becomes irrelevant.
Assuming you have blocked all unused system ports at the firewall, you may now
unblock the designated PIKT port using the appropriate firewall directives.
Note that you still need to run the portmapper, also unblock it at the
firewall.
(You don't need to unblock any portmapper-assigned piktc_svc UDP port if you
have set tcp_only to TRUE in PIKT.conf.)
In our implementation of this, we had to hack the rpcgen transport code,
replacing (in `mkdir ./config.guess`/src/piktc/rpc_svc.c)
transp = svctcp_create(RPC_ANYSOCK, 0, 0);
with
transp = svctcp_create(getsd(), 0, 0);
where getsd() is a newly created function (in src/lib/net.c) that achieves the
specific-port binding.
The above is example Linux rpcgen-created code, generated and modified
automatically in the 'make' step. We have not been able to test any of this
on other operating systems. Please report any problems or differences in your
operating system environment. Modify the rpcgen-created rpc_svc.c file
by yourself if needed, and if you don't mind doing a little code hacking.
Note that if, for any reason, you don't want to bind piktc_svc to a specific
port number (before pikt-1.18.0, this was the default arrangement), you may do
this in the 'configure' step
../configure ... --disable-rpcprtnum ...
which places piktc_svc (TCP) dynamic port assignment back under the control
of the portmapper.
VALIDATION SELF-TESTS
PIKT has a suite of over 1,000 torture tests to check and stress just
about every aspect of the config file preprocessor and script language.
NOTE: If your test system runs either SunOS or AIX, please read either
README.SUNOS or README.AIX before attempting these tests.
--Just before conducting any tests, you might want to invoke the "script"
command, as you will want to capture all test output that might otherwise
scroll off the top of the screen. Be sure to exit from the script subshell
at the conclusion of the test set.
--If you have a previous installation, you should kill any running
PIKT binaries first.
--If you have a pre-existing /pikt directory or link, you should mv it
aside (say, to /pikt.bak) for safekeeping, because the PIKT test routine
makes its own /pikt -> /tmp/pikt link. After the tests, be sure to mv
your /pikt directory or link back in place.
--In the `./config.guess` directory, invoking 'make check' will run
all tests. The tests are in three main phases. Running the second
and third phases requires you to be root.
--Instead of scripting the test run, you can run the tests this way:
# make check 2>&1 | tee make_check.log
In fact, this is the command sequence we usually use:
../configure 2>&1 | tee configure.log; /usr/local/bin/make 2>&1 |
tee make.log; /usr/local/bin/make check 2>&1 | tee make_check.log
Or, if you prefer, you might run the tests this way:
# nohup make check > make_check.log 2>&1 &
--The piktd tests are all run three times: (1) the first time in phase_i,
running off the distribution script files; (2) the second time in phase_ii,
running off the script files installed by piktc with encryption disabled
and callback enabled; (3) the third time in phase_iii, running off the
script files installed by piktc with encryption enabled and callback
disabled. The second and third round of piktd tests are, therefore,
really tests of piktc's and piktc_svc's effectiveness under different
operating modes.
--WARNING: These tests will take quite a while to finish, from less than an
hour on newer, faster systems to several hours on older, slower systems
(e.g., Sun SPARC 10s, PC 486s). If a piktc test hangs for more than 15
minutes, it is likely that the piktc program is broken on your system.
(Recent versions of piktc are known to hang completely in SunOS. See
README.SUNOS.)
--For the piktc tests, the output will be like so:
testing Test 1: piktc -cv +H munich ...
testing Test 2: piktc -cv +H munich munich munich ...
testing Test 3: piktc -cv +H munich -H munich munich ...
testing Test 4: piktc -cv +H sunostest -H paris kiev0 ...
If a test fails, you will see diff output, for example:
> checking paris...
--For the piktd tests, the output will be like:
testing alert StringFunc...
testing alert IsChar...
testing alert NumberFunc...
testing alert LogicalFunc...
testing alert StatFunc...
testing alert TimeFunc...
testing alert MiscFunc...
If a test fails, you will see diff output:
testing alert TimeFunc...
< yearweek test 2
< yearweek test 3
(The above is actual test output that we get on SunOS systems, but not--
using the identical test--on systems running the other supported OSes.
It certainly appears to us like something is broken in the SunOS 4.1.4 year
week calculations.)
Don't conclude that a test has failed because it just sits there for
a minute, sometimes much longer on slow systems. Please be patient.
On AIX, HP-UX, IRIX, and OpenBSD systems, the EscVar test produces the
result
testing alert EscVar...
1,4d0
< EscVar test 1
< EscVar test 2
< EscVar test 3
< EscVar test 4
This appears to result from a difference in POSIX-adherence. Since the
test conditions under which the above failure occurs are deliberately
obscure, the test failure is nothing to worry about under normal
circumstances.
Lately, we have begun seeing diffs like
1,3d0
< Bogus username *onati
< Bogus username labarre
< Bogus username ruggi
6a4,6
> Bogus username labarre
> Bogus username *onati
> Bogus username ruggi
on some systems but not on others. We don't understand the reasons for
these new diffs, but they appear to be inconsequential (merely a difference
in sort order).
On AIX systems, you might see a failure of the #pprocid() test. This is
because we have chosen inetd to test the ppid of, and on AIX alone inetd's
ppid does not equal 1.
If your test system doesn't run inetd, the #pprocid() test will fail.
On AIX systems only, and because of some earlier persistent RPC difficulties,
by default we bypass several of the phase_ii tests. Later versions of AIX
appear to have fixed these difficulties (while adding one or two new ones).
You may observe still other test failures with AIX. See the README.AIX
file for more details.)
At the conclusion of the tests, if you have scripted the test run,
exit the script session, then vi the 'typescript' file. If you have
tee'd to a log file, vi that log file. Do searches on '^<', '^>', '^diff',
else grep at the command line:
% grep '^<' typescript [or make_check.log]
% grep '^>' typescript [or make_check.log]
% grep '^diff' typescript [or make_check.log]
If any diffs are found, these are usually (but not always) signs of
test failure. To locate the point of each test run, do a search for
'^test'.
After the tests finish, you should run the 'ps -ef | grep pikt' or
'ps -aux | grep pikt' command to check if there are any orphaned PIKT
processes (there shouldn't be any).
Look also for any core files in the `./config.guess`/bin directory.
If one or more tests fail, don't be misled into thinking that your
PIKT binaries are at fault. Often we are dismayed to see apparent
test failures in Linux only to find out that we got a handful of
file paths in macros.cfg or unixcmds_macros.cfg wrong, and that the
PIKT binaries are not to blame.
The validation tests are not entirely independent. Sometimes, tests
depend on the successful completion of tests coming before. An error
in one test can have a cascading effect on subsequent tests, and many
followup tests will fail. So, if you see a flurry of failed tests,
don't conclude the worst. It may be just that the first test in the
dependency sequence has failed, and correcting the difficulty in the
first test will make the followup tests happy.
Note that if, for some reason, the /tmp/pikt link is not made, or
gets rm'ed during the course of the tests, just about every test will
then fail. The /tmp/pikt link is essential for testing purposes!
Remake it manually ('cd `config.guess`; ln -s `pwd` /tmp/pikt) if
need be.
All ~1,000 tests run (with the sole exception being the year week test
in SunOS) successfully, and without apparent error, on all of the
testbed systems we have tried them on so far. (These include
many different Solaris systems, several Linux and SunOS systems, and
a handful of AIX, FreeBSD, and HP-UX, IRIX, and OpenBSD systems.)
--If one or more tests fail, the place to start looking (well, the
next place after doublechecking file paths in macros.cfg) is in
`./config.guess`/src/test/lib/reports. For each test alert, you will
find three files, for example
`./config.guess`/src/test/lib/reports/TimeFunc.out
`./config.guess`/src/test/lib/reports/TimeFunc.base.rpt
`./config.guess`/src/test/lib/reports/TimeFunc.test.rpt
The first file is all pikt output, including log, error, and
debug messages. The second file is known "good" alert output
(lines sent to stdout by script output statements) minus the
logging stuff. The third file is the script output from the
test you have just run.
NOTE: For the 30 or so direct piktc tests in the first phase, also
for most of the 120 or more piktc tests in each of the second and third
phases, there will be no .out file.
"make check" diffs the .base.rpt & .test.rpt files, as well as
reports any ERROR messages.
By inspecting the .out file, and perhaps delving into the PIKT
source code, you should be able (sometimes with much effort) to
determine the cause of test failure.
If you are conducting the tests on a system other than the master
control system, pay special attention to the 'master' and 'domain'
settings in the PIKT.conf file. If you're conducting these tests on
machine A, and have set your master to machine B, you won't be able
to install the test files (using the procedure described below),
hence you won't be able to run the tests against refreshed script and
data files. In other words, if you want to run tests on machine A,
make sure that the piktc_svc you have running on machine A will
entertain piktc requests from machine A.
--If you have problems with the piktc tests in phase 1, phase 2, or
phase 3 (e.g., piktc hangs or fails with the error "input in flex scanner
failed"), you can run the piktd validation tests only and bypass all piktc-
related (master) tests. After the 'make' step but before 'make check',
you need to edit bin/Makefile. Change this:
check-local: phase_i phase_ii phase_iii
phase_i: check_piktc_i check_piktd_i
to this:
check-local: phase_i
phase_i: check_piktd_i
When you run 'make check', you should observe all tests passing except
for any mentioned in one of the OS-specific README files or elsewhere in
this PIKT INSTALL file. If the piktd tests pass, the tested system should
work fine as PIKT slave system. It will not, of course, serve as a
piktmaster.
A possible solution to the "input in flex scanner failed" problem is to
add a 'sleep(fork_delay)' call in the following three places:
# diff -C 2 src/piktc/piktc.c $P/src/piktc/piktc.c
*** src/piktc/piktc.c Fri Aug 23 11:55:30 2002
--- /export/home/berto/pikt/src/piktc/piktc.c Wed Oct 9 12:56:06 2002
***************
*** 1037,1040 ****
--- 1037,1041 ----
default: /* parent */
close(fd[1]);
+ sleep(fork_delay);
switch (cfgtype) {
case SYSCFG:
# diff -C 2 src/piktc/sys.l $P/src/piktc/sys.l
*** src/piktc/sys.l Fri Aug 23 11:55:30 2002
--- /export/home/berto/pikt/src/piktc/sys.l Wed Oct 9 12:56:49 2002
***************
*** 370,373 ****
--- 370,374 ----
default: /* parent */
close(fd[1]);
+ sleep(fork_delay);
sysin = fdopen(fd[0], "r");
tell_child(incnum, __FILE__, __LINE__);
# diff -C 2 src/piktc/tag.l $P/src/piktc/tag.l
*** src/piktc/tag.l Fri Aug 23 11:55:30 2002
--- /export/home/berto/pikt/src/piktc/tag.l Wed Oct 9 12:57:14 2002
***************
*** 437,440 ****
--- 437,441 ----
default: /* parent */
close(fd[1]);
+ sleep(fork_delay);
tagin = fdopen(fd[0], "r");
tell_child(incnum, __FILE__, __LINE__);
After making those changes, redo the 'make' and 'make check' to see if the
problem disappears.
--NOTE: In src/piktc/piktc.c, src/piktc/sys.l, and src/piktc/tag.l, we added
a sleep(fork_delay) call, commented out, just after the parent process forks
a child process. This seems to prevent hangs on slower and overloaded
systems. If you experience piktc hangs in the validation tests, or flex
scanner failures, try uncommenting the sleep() calls, then recompile and
retest.
There are limits to what one can do with automated testing. It would
be nice to include actual machine A piktc/piktc_svc to machine B
piktc_svc interaction in the automated tests. We simulate that to the
best we can with same-machine interaction in the existing test suite.
Limitations notwithstanding, the ~1,000 different tests (which actually
test many thousands of PIKT operations) give all of PIKT a pretty thorough
workout.
As new features are added to PIKT, we add new tests to validate them.
And, when bugs are discovered, we try to recreate the conditions that
led to them in the PIKT test code.
Of course we want to know about legitimate bugs in the PIKT code,
but please make every effort to rule out configuration errors
before reporting any test failures. When reporting any bugs,
it would be especially useful if you could devise or extend one
of the existing validation tests to deal with that bug.
Report bugs to:
Also, join the pikt-users
https://listhost.uchicago.edu/mailman/listinfo/pikt-users
and pikt-workers
https://listhost.uchicago.edu/mailman/listinfo/pikt-workers
mailing lists.
