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:  [email protected]

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.
 
Home | FAQ | News | Intro | Samples | Tutorial | Reference | Software
Developer's Notes | Licensing | Authors | Pikt-Users | Pikt-Workers | Related Projects | Site Index | Privacy Policy | Contact Us
Page best viewed at 1024x768 or greater.   Page last updated 2019-01-12.   This site is PIKT® powered.
Copyright © 1998-2019 Robert Osterlund. All rights reserved.
Home FAQ News Intro Samples Tutorial Reference Software
PIKT Logo
PIKT Page Title
Learn how to
develop a PIKT
configuration
, also
develop & test
Pikt scripts