Imprints Retrieval Server and Repository

Installation and Setup Guide

Before You Start

This is a guide for the administrator that wants to set up their own Imprints repository and retrieval server. Most users will never have to do this, they'll just point their Imprints client at an existing retrieval server.

This guide is mainly for printer vendors or corporate system administrators. If you intend to build and maintain your own collection of Imprints Windows Printer Driver packages, you'll want to read this guide.

The Repository is Separate from the Server

It's important to understand that the retrieval server and the repository are two separate things. The retrieval server is the web-based software and database files that contain references to Imprints driver packages. The repository is a web-accessible directory that contains the Imprints packages themselves.

Other Packages You'll Need

We've tried to minimize the number of dependencies the retrieval server has to other packages, but there are a few.

RDB

RDB is a set of tools for manipulating RDB-style data tables. This is a small package of perl programs. They are available at ftp://ftp.rand.org/pub/RDB-hobbs/RDB-2.6d.tar.gz.

GNU Privacy Guard

Gnu Privacy Guard is an open source alternative to PGP. It's available at http://www.gpg.org.

CGI Perl Library

The CGI perl library is a popular collection of routines for simplifying Common Gateway Interface programming in perl. It's available at http://cpan.perl.org, though if you use any one of several standard Linux distributions, and you've installed perl, you probably already have it installed.

Setting Up a Basic Repository

The repository is just a web-accessible directory where Imprints packages are stored. The packages should be accessible via normal http download.

Imprints packages are typically digitally signed using the gnuPG (GNU Privacy Guard, also known as gpg) package. They are signed with the repository owners private key. (For more information of gpg, see http://www.gnupg.org/.)

Publishing Your Public Key

Imprints clients will want to verify the signatures of the packages they receive. To do this, they'll need to have your site's gpg pubic key. The key should be stored in a file named public_key in any repository directory where Imprints packages are stored.

To create an ASCII-armored public key, you can use the following gpg command:

gpg --homedir your_gpg_dir --armor --export > public_key
The --homedir parameter points to the directory where your gpg keyring is located. Signing Your Packages After a package has been created, a digital signature must be created for it. This is typically handled with a gpg command like this: 
gpg \
--homedir your_gpg_dir \
--output my_package.sig \
--armor \
--detach-sig my_package.tar.gz
If you are signing multiple packages, this can become a tedious process, so a simple script or program like the one below can simplify the process:

#!/usr/bin/perl

#=================================================================
# imp_gpg_sign.pl [files...]
#
# 
#=================================================================

use File::Basename;

$gpg = "/usr/bin/gpg";
$passphrase = "my-gpg-passphrase";
$homedir = "/my/gpg/keyring/dir/";
$suffix = ".sig";

# Process each file listed on the command line.

for ($i=0; $i <= $#ARGV; $i++) {
    $infile = $ARGV[$i];

    # If file ends with expected package ending, then 
    # remove the old suffix and append the sig suffix.
    if (substr($infile, length($file)-7, 7) eq ".tar.gz") {
        $sigfile = substr($infile, 0, length($file)-7) . $suffix;
    }
    else {
        $sigfile = $infile . $suffix;
    }

    # Create the detached signature using the specified 
    # key.

    if (-e $infile) {
        $cmd = "echo $passphrase | $gpg "
               . "--homedir $homedir "
               . "--output $sigfile "
               . "--passphrase-fd 0 "
               . "--armor "
               . "--detach-sig $infile";

        $rc = system ($cmd);
        if ($rc == 0) {
            print "File $infile signed successfully.\n";
        }
        else {
            print "Could not sign $infile. gpg failed with exit code $rc.\n";
        }
    }
    else {
        print STDERR "File '$infile' does not exist. Skipping...\n";
    }
    
}
This perl program will take a list of packages from the command line, and created detached, ASCII-armored signatures for them. It automatically generates the signature file name by stripping the ".tar.gz" from the package name and replacing it with ".sig". A package file named mypackage.tar.gz will be given a signature file of mypackage.sig. This signature naming convention is important because the imp_admin.cgi Admin tool looks for signature files with this naming scheme so that it can automatically fill in the gpg fields in the retrieval server database during record adds and edits.

Setting Up a Basic Server

This section will describe how to set up the retrieval server and the retrieval database.

Installing and Setting Up the Basic Database Files

The easiest way to install the basic database files is to download the gzipped tar file from imprints.sourceforge.net. The file will have a name like imp_retrieval_database_V.vv.tar.gz, where "V.vv" will be the version number.

File and Directory Permissions

Create a directory outside of your web server's DocumentRoot path. File permissions for this directory, and the files within it are important. Untar the database files into this directory, then ensure that the directory and its files are readable and writeable by CGI programs running from your web server. If permissions are not set properly, the Imprints Admin tool (imp_admin.cgi) cannot update the retrieval database.

Editing The Configuration File

With the database files, you'll find a file named imprints-db.conf. This is the retrieval server's configuration file. The standard one will look something like this:

# Imprints Database Server - sample configuration file.
# This file should be in /etc/imprints-db.conf.

DB_DIR = /home/imprints/imprints-database/
DB_DEF_LOC_FILE=locations_1.rdb

# This is where the RDB utilities have been installed.

RDBDIR=/usr/local/bin

# The default language. This is the language assumed
# when no language is explicitly requested/

LANGUAGE=en

# Automatically attempt to fill in GPG fields
# (during imp_admin Add and Edit) by getting
# a .sig file from the location_url and parsing.

GPG_AUTO=1

# Attempt to fill the GPG fields from .sig files
# stored on the local machine in the GPG_SIGDIR
# directory.

GPG_LOCAL=0
GPG_SIGDIR = /home/imprints/imprints-database/
Make sure that DB_DIR is set to the directory where you have installed the database files (this should be the same location where you're editing the configuration file). Also, make sure you have installed the RDB package and that the path to these tools is properly assigned to RDBDIR.

Location of the Configuration File

You can leave the configuration file, imprints-db.conf, in the database directory, or you can move it elsewhere depending on your preferences. You'll need to remember where it's installed, so that you can properly set up the retrieval server and admin tool.

Setting Up the Server and Admin Programs

The simplest method for setting up the Imprints retrieval server and admin tools is to download the gzipped tar file from imprints.sourceforge.net. The file will have a name like imp_retrieval_server_V.vv.tar.gz, where "V.vv" is the version number.

You will want to untar these files into a directory within you web server's CGI directory. The tar file will create a directory, imp, that contains the imp_retrieval.cgi server program and its supporting files. A directory is also created below imp, called admin. This directory contains the imp_admin.cgi administration tool.

Editing imp_retrieval.cgi and imp_admin.cgi

Once installed, use a text editor to edit both imp_retrieval.cgi and imp_admin.cgi. Near the top of each of these perl programs is a line like this:

$conf_file = "/home/imprints/imprints-database/imprints-db.conf";
Change the $conf_file variable to point to the full path and file name where you have placed your configuration file. Neither program will work properly unless this variable is set correctly.

Security for imp_admin.cgi

The Imprints administration tool is used to add, edit, and delete records in the retrieval database. Obviously, not everyone should have this capability. The imp_admin.cgi program is stored in a separate directory so that you can take advantage of the security capabilities of your web server.

Imprints was tested using the Apache web server running under Linux. Access to the imp_admin.cgi program was restricted using Apache's standard .htaccess files and a password file. See the Apache web server documentation for more information on setting up this access. The imp/admin directory contains a sample .htaccess file, and the database directory includes a password file, .htpasswd, that contains a single user I.D. and password pair (the I.D. is "imprints" and the password is also "imprints"). These files are examples only, and you should set up and test proper security on your own server.