Introduction

Pulse uses zip archives in various places to transfer files between machines. Where possible, creating and extracting archives using native tools (such as Info-Zip) is preferred, as native tools can preserve some system-specific information that may otherwise be lost. For example, on Unix systems symbolic links and file permissions can be preserved. By default, pulse™ will try to use commands zip and unzip if they are available and appear to accept Info-Zip style parameters (such zips are found on most Linux and BSD varieties, including OS X). Where no suitable tool is found automatically, pulse™ falls back on an internal zip mechanism that supports the lowest common denominator.

This cookbook article describes how to configure pulse™ to use a zip and unzip program of your choice. This allows you to customise pulse™ archiving for systems that have a tool that produces compatible archives to Info-Zip, but is not command-line compatible with Info-Zip.

Archiving Tool Requirements

Before using any external archiving tool, pulse™ will perform a test run of the tool to ensure it is capable of working with suitable archives. This test verifies two main things:

1. The command is specified correctly by your configuration; and
2. The command is compatible with the internal pulse™ archving code. This is important because pulse™ is a distributed system, where not all machines necessarily have access to the same archiving tools. In all cases the archives should be compatible.

If the test run fails for some reason, your will see a log message similar to:

28/03/2007 22:49:37 com.zutubi.pulse.util.ZipUtils useExternalZip
WARNING: I/O error testing external archiving: CreateProcess: nonexistant error=2
...
28/03/2007 22:49:37 com.zutubi.pulse.util.ZipUtils useExternalZip
WARNING: External archiving is disabled

Configuration

All external archving configuration is currently handled via System Properties. Note that you must set the properties individually on each agent.

Enabling Archiving

Use of external archiving is controlled by the property pulse.use.external.archving. This property is true by default if there is a command named "zip" in the PATH of pulse™. If this property is false, pulse™ internal archiving is always used.

Archive Command

The archive command is configured via the property pulse.archive.command. The property value should be a command that will produce a standard zip archive. The value should include the properties ${zipfile}, which is the name of the zip file to create, and ${files}, which is a space-separated list of the files and directories to include in the zip, relative to the working directory. For example, when executed in a directory with contents:

d1/
  d1f1
  d1d1/
    d1f1
d2/
  d2f1
f1
f2

with a ${zipfile} of "archive.zip" and a ${files} of "d1 f2", the archive command should produce an archive named "archive.zip" that contains:

d1/
  d1f1
  d1d1/
    d1d1f1
f2

The default archive command is:

zip -qry ${zipfile} ${files}

Un-archive Command

The un-archive command is configured via the property pulse.unarchive.command. The property value should be a command that will unpack a standard zip archive. The value should include the property ${zipfile}, which is the name of the zip file to unpack. Files should be unpacked relative to the working directory for the command.

The default un-archive command is:

unzip -qq ${zipfile}