{INCLUDE _LOGOS.HTM}

PicLan-IP for D³ / Pro Plus
Installation and Concepts Guide

September 7, 1998

PicLan-IP for D³/ProPlus is currently in pre-release. This implementation of the PicLan-IP suite of products is very similar to other PicLan-IP hosted releases. This document describes the pre-requesites of using PicLan-IP on D³/ProPlus, it installation, and operation.

Required D³/ProPlus Configuration

PicLan-IP will run with D³/ProPlus version 7.1 when installed on top of any compatible version of Linux. This includes the RedHat 4.2 release that Pick Systems ships with D³/ProPlus as either a standard or enhanced configuration.

Required Linux Components

In order to use PicLan-IP, you must install and configure Linux to support TCP/IP network connections. This can include installing ethernet adapters, setting up PPP connections, or whatever. The important thing to understand is that PicLan-IP uses Linux supplied TCP/IP services and you must set these up in Linux before PicLan-IP will run.

Required D³/ProPlus Components

PicLan-IP runs on D³/ProPlus phantom processes. For most installations, you will need a total of three phantom processes to run PicLan-IP, so you should install D³/ProPlus with a sufficient number of phantom processes configured for PicLan-IP and other tasks that you will need to run.

Conflicts with Other Linux Software

Apache Web Server

In order to use PicLan-IP and Apache at the same time (on the same host system), you must configure the two software packages to use either differnet IP addresses or different TCP port addresses. If you configure Linux for multiple IP addresses, you can then have PicLan-IP's Coyote web server control some of the addresses and have Apache control the others. This configuration allows you to run both Coyote and Apache on the standard HTTP TCP port 80.

If you do not have multiple IP addresses configured, then you must configure Coyote and Apache to use different TCP port numbers. You could setup Coyote to use port 80 (the default for HTTP) and Apache to use port 81.

The other option is for you to not start Apache. Coyote is fully capable of serving all of the HTTP requests of the system and provides the additional benefits of control from within the Pick environment.

Sendmain Mail Server

At the present time, it does not appear possible to use PicLan-IP mail functions at the same time as sendmail mail functions. Further research for solutions to allow both products to co-exist on a single platform are in works, but sendmail does not appear to be configurable to allow it to run on only a single IP address instead of every IP address on the system. If you are a sendmail expert and know how to do this, please let us know.

Exeuction Limitations

Maximum Number of TCP Connection Handles

Because of the underlying Linux architechure, a maximum of 1024 open connection handles are supported. The underlying OS uses about 5 of these and then PicLan-IP uses a connection handle for RPC synchronization so that limits the number of usable TCP connections to about 1000. In practice, this should not be a serious limitation for most sites.

Untested Aspects

Multiprocessor Support

The design of PicLan-IP on Linux is such that it should work with multiprocessor systems, but this has not been tested.

Installation Proceedure

Linux Install Steps

The PicLan-IP software is supplied as a Linux TAR archive file. These installation steps are designed to be executed by the root user. You should either logon as root or execute the su command before attempting to install PicLan-IP. In order to install the file, you should copy the install file to your Linux system and perform the following steps:
mkdir /usr/piclan-ip
cp plip-d3lx.tar.gz /usr/piclan-ip
cd /usr/piclan-ip
tar x -v -z -f plip-2.0.0.119-d3linux.gzip
This should process should extract several files into the /usr/piclan-ip directory including:
Makefile
plip.tap
plip_c.o
plip_d
px_user.o
After verifying that these files were extracted, you should execute:
make
This process will relink the D³ monitor so that the PicLan-IP C support routines are included and copy the newly made monitor along with the plip_d daemon executable to the /usr/bin directory.

D³ Install Steps

After you have rebuilt the D³ monitor, you can continue the PicLan-IP installation process. If D3 is current running, you must shutdown D³ and then restart it. This is necessary so that all processes, including phantom processes, are using the D³ monitor that contains the PicLan-IP support code.
After you have restarted D³, you need to load the PICLAN-IP account from the virtual tape in the /usr/piclan-ip directory. You can load this tape by performing the following operations. You should be logged on to the 'dm' account.
T-SELECT 3
CHG-DEVICE 3 name=/usr/piclan-ip/plip.tap
T-ATT
T-REW
T-LOAD MD (O
This will start the restore process of the PICLAN-IP account.
After the PICLAN-IP account is installed, you can proceed with standard PicLan-IP configuration by editing the PLIP.CTRL CONFIG item.

Troubleshooting

The PicLan-IP daemon has logging and command-line switches that can be used to resolve several system problems.

Setting up the plip_d startup parameters

The PLIP.CTRL CONFIG item line ...

DAEMON COMMAND=Z !plip_d >> /var/log/plip_d_log &

is used to control how the PicLan-IP communications daemon is started. This command works by shelling (the Z) a phantom process that then shells the plip_d command. The '&' will cause the shell to run in the background. The reason that this is run on a phantom is so that the daemon will continue to run even if the calling process exits.

The ">> /var/log/plip_d_log" part of the command line redirects output from the daemon to the specified log file. Using the double arrow ">>" redirect causes the log file to append and not be erased whenever the daemon is started.

How PicLan-IP processes communicate with the daemon

The default (or fast) option is for the daemon to allocate a large block of kernel memory as a shared memory segment. This memory segment is used to transfer data to and from running D3 processes as a large process-private buffer area. Then a TCP/IP pipe is opened to synchronize the operation of the daemon and the calling D3 processes. On most systems, this works very well. Some systems have trouble allocating the amount of kernel memory that we require. On these systems, we have added a command-line option that switches the PicLan-IP daemon into "remote mode". In this mode, the shared kernel segment is not allocated and instead the TCP/IP pipe itself is used not only for synchronization, but also for data transfer functions. This "slow" mode is still very fast, but there are measurable latency factors, particularily with large web page operations. In any case, if you are having problems getting PicLan-IP to communicate with the plip_d daemon, you should change the DAEMON COMMAND line in PLIP.CTRL CONFIG to:

DAEMON COMMAND=Z !plip_d -z >> /var/log/plip_d_log &

PicLan-IP for D3 / Pro Plus Installation and Concepts Guide

Required D3/ProPlus Configuration