Installing the Checkpoint Architecture on Linux (x86)

Author: Will Dickson, CCS

Version: 1.5.0

Date: 31 July 2007

Summary

This document describes how to install or upgrade Checkpoint or Checkpoint Commander onto a Linux/x86 host. It's not difficult, but please read carefully. NB. the rest of this document refers to "Checkpoint"; if you're installing Checkpoint Commander, substitute accordingly.

This document should be sufficient to install Checkpoint, and (hopefully) to allow you to troubleshoot configuration problems which are severe enough to prevent Checkpoint from running. Once you're up and running, you should be able to access the Checkpoint user guide. This will give you further information about running Checkpoint and administering your Checkpoint installation.

This document is part of the Checkpoint user guide. It isn't linked into the navigation for that guide (and doesn't follow its document naming convention) so that it can be available at install time, which is when it's primarily needed. The rest of the Checkpoint documentation is available after you've installed Checkpoint.

You will need

Root privileges.
Basic familiarity with Linux. In particular, you're going to be interacting with the command line (shell / konsole / xterm / terminal) so you need to be comfortable with basic operations such as changing folder and launching applications.
A Java runtime; the required version will be in the release notes for the product you are installing. At the time of writing Checkpoint requires version 1.6.0 or greater (Java 6). We use the Sun implementation; there are others, including at least one Free version, but at the time of writing this isn't ready for production use.
The application distribution zip for Linux, uncompressed into some directory (say ~yourself/tmp). Since you're reading this, I presume that you already have the zip.
Except for the GPL (Free) version of Checkpoint Commander, a licence key. You should have been given this when you obtained Checkpoint. Please note that the licence key is locked to the Licence Holder name and Organisation name specified.
A workstation with a GUI that is compatible with Java's AWT / Swing - typically X plus a suitable window manager. We use KDE, but most window managers should work OK.
A web browser that can handle HTML4.0 and CSS1. See the release notes for more details.

Installing the Java Runtime Environment

This depends on your Linux distribution. Some modern ones may come with a suitable version of java as part of the distribution itself; in other cases, you'll have to download it separately. You can get the Sun JRE from java.com. [Don't be put off by all the adverts which make it look like a domain-squatter; it is official. We checked.] The JRE distribution should tell you how to install it.

It doesn't matter where the JRE is installed, as long as the java executable is on the system PATH. Generally this will be taken care of by whatever mechanism installed Java. If this doesn't happen for some reason, the Checkpoint installer will abort (cleanly). If this happens you'll need to provide a symlink to the java executable, in a suitable folder on the system PATH.

Choosing a configuration

You can install Checkpoint in one of two configurations.

Single-user: This has a graphical installer which you may find more comfortable if you're used to Windows (welcome!). It's only suitable if you're the only person who uses the machine. If you've installed Checkpoint in single-user configuration, you should not run services which can be accessed from other machines.
Multi-user: This has a text-based ("headless") installer which you may find more efficient if you're used to Linux. It is suitable for all situations.

Installing Checkpoint

Single-user install

Run the install script, as yourself, from an xterm or similar, from the folder where you unzipped the distribution. (X must be running.) If you unzipped the distribution zip into ~yourself/tmp, then the code (where '>' represents the shell prompt) would be something like:

> cd ~yourself/tmp
> source installSingleUser.sh

Multi-user install

If you're upgrading, make sure that all Checkpoint applications and the Checkpoint Daemon have been shut down before continuing.

Run the install script, as root, from the folder where you unzipped the distribution. If you unzipped the distribution zip into ~yourself/tmp, then the code (where '>' represents your shell prompt, and '#' represents the root prompt) would be something like:

> sudo -i
(or)
> su root
# cd ~yourself/tmp
# source installMultiUser.sh

[Tip: for fully-automatic install using all the defaults, pass the argument --force to the script, thus
source installMultiUser.sh --force ]

[NB. You don't need X running for multi-user install.]

Configuring a Browser

The installer will ask you to set the browser to use with Checkpoint applications. It's important to set this correctly, otherwise Checkpoint applications won't work properly and will be missing important features.

Checkpoint will try to auto-detect your browser.

[Tip: the first place Checkpoint looks is /etc/alternatives/x-www-browser. For best results, make sure this is a symlink to your browser of choice.]

Mainstream browsers shouldn't now require any special treatment to work properly with Checkpoint (some earlier versions did). Check the release notes for recommended browser versions.

The Checkpoint Daemon

Starting the Daemon

All Checkpoint applications except for Checkpoint Commander use a shared resource called the Checkpoint Daemon, and won't work properly unless it's running.

Single-user: You don't need to start the Daemon manually; it will be started automatically when it's needed.
Multi-user: The Daemon will be started automatically by the install script. On other occasions (eg. after rebooting) you'll need to start it manually. To do this, run the daemonctl script as root:
# /opt/cpoint/bin/daemonctl start

[Once you're comfortable that everything's working properly, and IF your comfortable with doing so, we recommend that you start the daemon automatically from your system boot scripts. If this paragraph is gibberish, don't worry about it.]

Stopping the Daemon

In general you can simply leave the Daemon running in the background; it doesn't eat much. When you do need to shut it down:

Single-user: Run the daemonctl script from a command line:
> /opt/cpoint/bin/daemonctl stop
Multi-user: Run the daemonctl script from a command line, as root:
# /opt/cpoint/bin/daemonctl stop

[NB. Don't stop the Daemon if there are any Checkpoint applications running. They'll stop working properly.]

Configuring Checkpoint

[If you're upgrading an existing Checkpoint installation, skip this section.]

After Checkpoint has been installed for the first time, it needs to be configured. Checkpoint Command Centre will automatically start this process as soon as you run it.

Single-user

The installer will ask you whether you want to launch Checkpoint Commander or Checkpoint (Command Centre). Tell it the latter. If you've already skipped that bit, do the multi-user version instead.

Multi-user

As yourself (not root or some other user) run the following command (where '>' stands for the shell prompt)

> /opt/cpoint/bin/cpcc

Your chosen browser will be launched, and a series of web pages will guide you through the configuration process.

Running Checkpoint applications

All Checkpoint apps are run as executable (JStart) shell scripts, located in /opt/cpoint/bin. For example, Checkpoint Commander is /opt/cpoint/bin/cpc . Pick one! You may find it convenient to put symlinks to commonly-used apps in /usr/local/bin. Alternatively, your desktop environment may allow you to add links to its launcher menu or equivalent.

Many Checkpoint apps are installed, controlled and / or launched using the Checkpoint Command Centre, /opt/cpoint/bin/cpcc. Consult the documentation for your application.

Lock file permissions

[This is a troubleshooting technique: bad lock files can (under unusual circumstances) prevent Checkpoint from running, which is why we've put it in here rather than in the main user guide.]

Every Checkpoint Persistent Object Store (aka. "CDB") has a main data file and a separate lock file. If the main data file is only used by the system user that owns it, the lock file's default permission set should be OK. However, others - ie. group and world - may not be able to access the data file even if the permissions on the data file allow them, because the permissions on the lock file don't.

To fix this, use the command-line utility /opt/cpoint/bin/lockfix, supplying the path to the affected main data file.

Applying lockfix is always safe. If you get strange problems which look as though they might be down to permissions, try it.

Don't delete lock files. If some local vandal does, then the lock file will be re-created the next time any application touches the corresponding data file (possibly with incorrect permissions). After root has accidentally locked the vandal in the tape safe for a day or so (or however long it takes for the noise to die away; this varies from site to site, please ask your BOFH for the exact figure, but only if you're sure this is a good idea) use lockfix again.

Installing on headless hosts

Some Checkpoint applications are services, which are accessed remotely. To support these, Checkpoint can be installed on a headless server (ie. one which does not have a GUI available). However, this is a more advanced technique which we will not cover here. (We generally do not recommend this: having a local GUI of some kind tends to make life easier.) See the Checkpoint User Guide for details.

FHS Compliance Issues

[You only need to read this if you want strict conformance with the FHS. If you don't know what this is, you can skip this section.]

The root, shadow and temporary-log databases, /opt/cpoint/lib/checkpoint*.cdb, /opt/cpoint/lib/shadow.cdb, and /opt/cpoint/lib/tmplog.cdb respectively, must be mounted read-write and may change even when system administration is not being performed. Therefore, according to the FHS, they're supposed to live in /var/opt/cpoint instead of /opt/cpoint/lib.

This violation arises because Checkpoint is a cross-platform application, and other platforms on which it must run (notably Windows) do not partition their filesystems along these axes.

To correct this, move the files referred to into the correct location, and provide symlinks thereto from the standard locations.