NAME

description - distribution layout file

DESCRIPTION

The contents and layout of a distribution are controlled by the description file. This file consists of a number of keywords, one on each line, containing zero or more arguments. Blank lines and lines beginning with a hash ('#') character are ignored.

Some keywords define the version and name of the module while others list files and directories included in the distribution so that they can be installed and uninstalled.

Take care when naming files to be installed since modules may collide. Files or directories named after an Agent service name and version can be considered safe.

Each module should provide a directory under the lib installation directory where module-specific files can be placed.

Keywords

Most keywords in the description file are a single alphabetic character and cause files to be copied from the distribution to the installation directories. The Agent SDK provides a simple tool called distcopy that reads the description file and builds the distribution by copying files from the development directory to the distribution directory.

Most of the file copying directives have the following syntax:

  command destination-path source-path

command is usually a single character.

destination-path is relative to the directory defined by the last target keyword.

source-path is relative to the distribution directory.

All paths use the slash ('/') character as separator, regardless of platform. Pathnames should not contain space characters.

The development directory must have the same layout as the distribution directory.

fileset module description
This must occur first in the file. module must be the name of the module directory in the distribution, which must in turn be the name of the Agent, with the format

  E<lt>nameE<gt>-E<lt>majorE<gt>.E<lt>minorE<gt>.

The description is shown during installation but is not used otherwise.

brand shortname longname
Optional. This is branding information with a short and a long name. The names can be identical.

version ver patchlevel build crypto
ver has the format <major>.<minor>. patchlevel should start with 0 and increment by 1 for each new patch. build should start with 0, and increment by 1 for each build. crypto is either ``export'' or ``domestic''. The setting depends on the type of Agent SDK.

system
Platform identifier.

agent
Only in Agents. Indicates that the module is an Agent and triggers special handling during install/uninstall. Not all the magic stuff is implemented yet.

require module
Indicates that the module requires other modules. All Agents the RSA Keon Agent Base System. If an Agent depends on several modules, use multiple require lines.

d directory
Creates a directory for the use of the Agent. Do not use this command to define directories that already exist.

p destination source
Installs an executable program (unchanged copy).

P destination source
Installs an executable script, which is subject to variable expansion (see below).

f destination source
Installs a text file without variable expansion. Line termination conversion will be performed to suit the installation platform.

F destination source
As for f but with variable expansion (see below).

b destination source
Installs the specified executable binary file.

i destination source
This file will be included in the distribution but will not be installed by the installation program.

target $DIRECTORY
Sets the target directory for all file-copying keywords that follow. DIRECTORY must be one of the following:

APPDIR
For programs, documentation, libraries, and other data files that can be considered read-only during Agent operation.

ETCDIR
For configuration files.

VARDIR
For dynamic data files such as logs. Files are not normally installed here.

Special File Names

Some files receive special handling by the distribution packaging tool, by the installation program, or by both. These files are:

VERSION.txt
If this is the destination name and it does not exist in the distribution, it is created. Every Agent must have this file (see below).

ltagentgt.boks
If the destination file has the suffix .boks and there is no source file during packaging, a Keon Security Server 4.x definition file is generated.

LICENSE.txt
If an Agent distribution contains a file with this name, the contents of the file are displayed during installation and the user is prompted to accept the license in order to continue installation.

Variable Expansion

Files copied with the F and <P> keywords are subject to variable expansion during installation. Variables that are expanded are written as <<INSTALL:VARIABLE>>. All occurrences of matching sequences will be replaced.

The VARIABLE can currently have any of the following values:

APPDIR
Expands to the full path of the application installation directory.

ETCDIR
Expands to the path of the configuration file directory.

VARDIR
Expands to the path of the data file directory.

MODULE
The Agent module name (<name>-<major>.<minor>).

MODULENAME
The module description string.

Variable sequences with an unknown VARIABLE field will be left untouched.

The VERSION File

All Agent distributions must have a file called VERION.txt. This should be installed in the private library directory of the Agent. If the distribution packaging tool (distcopy) supplied with the Agent SDK is used to create a distribution, this file is automatically generated from the information into the description file.

The file consists of parameters, with one parameter on each line. Lines starting with a hash ('#') character are ignored. This file should define the DESCRIPTION, VERSION, PATCHLEVEL, REV, and CRYPT_LICENSE parameters.

The values for these parameters are taken from the fileset and version keywords of the description file (see above).

EXAMPLES

The following is an example of a description file:

  # The module name with a short description
  fileset telnet_sample-5.0 "Keon Sample Agent for telnet"

  # version 5.0 build 0 patch level 0 and domestic crypto
  version 5.0 0 9 domestic

  # Brand name with the short name long name identical
  brand "Keon" "Keon"

  # depends on the Base System
  require catbase-5.2

  # For solaris 2.6 SPARC
  system solaris-2.6

  # It is an Agent
  agent

  # No source for the .boks file. Auto generated
  # The .boks, .gap and .properties file will not make it past
  # the distribution
  i ../../adf/telnet_sample_5_0.boks
  i ../../adf/telnet_sample_5_0.gap              gap.tmp
  i ../../adf/telnet_sample_5_0.properties       properties.tmp

  # Set the 
  target $APPDIR
  p bin/telnet_sample-5.0                       telnet_sample-5.0
  d lib/$MOD
  f lib/$MOD/VERSION.txt  VERSION.txt
  target $ETCDIR
  F services/$MOD.cfg   cfg.tmp

The following is an example of a VERSION.txt file corresponding to the above description file example:

  DESCRIPTION="Keon sample Agent for telnet"
  VERSION=5.0
  PATCHLEVEL=0
  REV=9
  CRYP_LICENSE=domestic

SEE ALSO

cat