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.
