swpackage(1M)

NAME

swpackage — package software products into a target depot or tape

SYNOPSIS

swpackage [-p] [-v] [-V] [-C session_file] [-d directory|device] [-f software_file] [-s product_specification_file|directory] [-S session_file] [-x option=value] [-X option_file] [software_selections] [@ target_selection]

Remarks

For a description of the Product Specification File (PSF) used as input to the swpackage command, see the swpackage(4) man page by typing man 4 swpackage.

DESCRIPTION

The swpackage command is not distributed; it only operates on the local host. It packages software products into:

a distribution directory (which can be accessed directly or copied onto a CD-ROM),
a distribution tape (such as DDS, nine-track or cartridge tapes).

A software product is organized into a three-level hierarchy: products, subproducts, and filesets. The actual files that make up a product are packaged into filesets. Subproducts can be used to partition or subset the filesets into logical groupings. (Subproducts are optional.) A product, subproduct, and fileset also have attributes associated with them.

Both directory and tape distributions use the same format. The swpackage command:

Organizes the software to be packaged into products, subproducts, and filesets,
Provides flexible mechanisms to package source files into filesets,
Modifies existing products in a distribution directory,
Repackages products in a distribution directory into a distribution tape.

Both the swpackage and swcopy commands create or modify a target depot. The differences between these commands are:

The swcopy command copies products from an existing depot to another depot. The swpackage command creates products based on the user's specification, and packages these products into a depot.
swpackage can be used to re-package software_selections from an existing distribution directory to a distribution tape.
The swcopy command can copy from a local or remote source to a set of local or remote targets. The swpackage command packages source files from the local filesystem into a product, for insertion into a local distribution directory or tape.
After creating a target depot, swcopy registers that directory with the local swagentd so that it can be found by swlist, swinstall, etc. With swpackage, the depot is not registered; the user must explicitly invoke the swreg command.

Layout Version

By default, SD object and attribute syntax conforms to the layout_version 1.0 specification of the IEEE POSIX 1387.2 Software Administration standard. SD commands still accept the keyword names associated with the older layout version 0.8, but you should use the older version only to create distributions readable by older versions of SD.

Which layout_version the SD commands write is controlled by the layout_version option or by specifying the layout_version attribute in the PSF file.

See sd(4), the description of the layout_version option in the following section and in sd(5) for more information. See sd(4) for more information on PSF files.

Options

swpackage supports the following options:

-p

Previews a package session without actually creating or modifying the distribution tape.

-v

Turns on verbose output to stdout. Verbose output is enabled by default, see the verbose option below.

-V

List the SD data model revision(s) which swpackage supports. By default, swpackage always packages using the latest SDU data model revision.

-C session_file

Save the current options and operands to session_file. You can enter a relative or absolute path with the file name. The default directory for session files is $HOME/.sw/sessions/. You can recall a session file with the -S option.

-d directory|device

If creating a distribution directory, this option defines the pathname of the directory. If creating a distribution tape, this option defines the device file on which to write the distribution. When creating a distribution tape, the tape device (file) must exist, and the -x media_type=tape option must be specified (see below).

Note that the -d option is obsolete. Use the @ target_selection operand instead.

You can also specify that the swpackage output be "piped" to an external command using:

swpackage -d "| <command>"-x media_type=tape-s <source>

The | symbol and command must be quoted because it is interpreted by swpackage and not the shell.

-f software_file

Read the list of software_selections from software_file instead of (or in addition to) the command line.

-s product_specification_file|directory

The source PSF describes the product, subproduct, fileset, and file definitions used to build a software product from a set of source files.

The source can also be an existing directory depot (which already contains products).

-S session_file

Execute swpackage based on the options and operands saved from a previous session, as defined in session_file. You can save session information to a file with the -C option.

-x option=value

Set the session option to value and override the default value (or a value in an alternate options_file specified with the -X option). Multiple -x options can be specified.

-X option_file

Read the session options and behaviors from options_file.

Software Selections

The swpackage command supports the following syntax for each software_selection:

bundle[.product[.subproduct][.fileset]][,version] 

product[.subproduct][.fileset][,version] 

The version component has the form:

[,r <op> revision][,a <op> arch][,v <op> vendor] 
[,c <op> category][,l=location][,fr <op> revision] 
[,fa <op> arch] 

location applies only to installed software and refers to software installed to a location other than the default product directory.
fr and fa apply only to filesets.
The <op> (relational operator) component can be of the form:
- ==, >=, <=, <, >, or !=
which performs individual comparisons on dot-separated fields.
For example, r>=B.10.00 chooses all revisions greater than or equal to B.10.00. The system compares each dot-separated field to find matches.
The = (equals) relational operator lets you specify selections with the shell wildcard and pattern-matching notations:
- [ ], *, ?, !
For example, the expression r=1[01].* returns any revision in version 10 or version 11.
All version components are repeatable within a single specification (e.g. r>=A.12, r<A.20). If multiple components are used, the selection must match all components.
Fully qualified software specs include the r=, a=, and v= version components even if they contain empty strings. For installed sofrware, l= is also included.
No space or tab characters are allowed in a software selection.
The software instance_id can take the place of the version component. It has the form:
- [instance_id]
within the context of an exported catalog, where instance_id is an integer that distinguishes versions of products and bundles with the same tag.

The \* software specification selects all products. It is not allowed when removing software from the root directory /.

If specified, the software selections cause swpackage to only (re)package those software selections from the full set defined in the source product_specification_file. If no software_selections are specified, then swpackage will (re)package all the products defined in the source product_specification_file.

Target Selections

The swpackage command supports the following syntax for a target_selection:

@ /path

If creating a distribution directory, this option defines the path to the directory. If creating a distribution tape, this option defines the path to the device file on which to write the distribution. When creating a distribution tape, the tape device (file) must exist, and the -x media_type=tape option must be specified (see below).

EXTERNAL INFLUENCES

Default Options

In addition to the standard options, several SD behaviors and policy options can be changed by editing the default values found in:

/var/adm/sw/defaults: the system-wide default values.
$HOME/.swdefaults: the user-specific default values.

Values must be specified in the defaults file using this syntax:

[command_name.]option=value 

The optional command_name prefix denotes one of the SD commands.

You can also override default values from the command line with the -x or -X options:

command -x option=value

command -X option_file

The following section lists all of the keywords supported by swpackage and swcopy. If a default value exists, it is listed after the "=". The commands that this option applies to are also specified.

compress_cmd=/usr/contrib/bin/gzip

Defines the command called to compress files before installing, copying or packaging. If the compression_type option is set to other than gzip or compress, this path must be changed.

compress_files=false

If set to true, files are compressed, if not already compressed, before transfer from a source. This will enhance performance on slower networks for swcopy and swinstall, and will result in smaller depots for swcopy and swpackage, unless the uncompress_files is also set to true.

compression_type=gzip

Defines the default compression type used by the agent when it compresses files during or after transmission. If uncompress_files is set to false, the compression_type is recorded for each file compressed so that the correct uncompression can later be applied during a swinstall, or a swcopy with uncompress_files set to true. The compress_cmd specified must produce files with the compression_type specified. The uncompress_cmd must be able to process files of the compression_type specified unless the format is gzip, which is uncompressed by the internal uncompressor (funzip).

create_target_acls=true

If creating a target depot, swpackage will create Access Control Lists (ACLs) for the depot (if it is new) and all products being packaged into it. If set to false, and if the user is the superuser, swpackage will not create ACLs. (The swpackage command never creates ACLs when software is packaged on to a distribution tape.)

distribution_source_directory=/var/spool/sw

Defines the default distribution directory to read as the source (when the source_type is directory). The -s option overrides this default.

distribution_target_directory=/var/spool/sw

Defines the default distribution directory of the target depot. The target_selection operand overrides this default.

distribution_target_serial=/dev/rmt/0m

Defines the default location of the target tape device file. The target_selection operand overrides this default.

enforce_dsa=true

Prevents a command from proceeding past the analysis phase if the disk space required is beyond the available free space of the impacted file systems. If set to false, then the install, copy, or package operation will use the file systems' minfree space and may fail because it reaches the file system's absolute limit.

follow_symlinks=false

Do not follow symbolic links in the package source files, but include the symbolic links in the packaged products. A value of true for this keyword causes swpackage to follow symbolic links in the package source files and include the files they reference in the packaged products.

include_file_revisions=false

Do not include each source file's revision attribute in the products being packaged. Because this operation is time consuming, by default the revision attributes are not included. If set to true, swpackage will execute what(1) and possibly ident(1) (in that order) to try to determine a file's revision attribute.

layout_version=1.0

Specifies the POSIX layout_version to which the SD commands conform when writing distributions and swlist output. Supported values are "1.0" (default) and "0.8".

SD object and attribute syntax conforms to the layout_version 1.0 specification of the IEEE POSIX 1387.2 Software Administration standard. SD commands still accept the keyword names associated with the older layout version, but you should use layout_version=0.8 only to create distributions readable by older versions of SD.

See the description of the layout_version option in sd(5) for more information.

logdetail=false

The logdetail option controls the amount of detail written to the log file. When set to true, this option adds detailed task information (such as options specified, progress statements, and additional summary information) to the log file. This information is in addition to log information controlled by the loglevel option.

logfile=/var/adm/sw/sw<package>.log

Defines the default log file for the swpackage command.

loglevel=1

Controls the log level for the events logged to the command logfile, the target agent logfile, and the source agent logfile. This information is in addition to the detail controlled by the logdetail option. See logdetail for more information.

A value of

0: provides no information to the log files.
1: enables verbose logging to the log files.
2: enables very verbose logging to the log files.

media_capacity=1330

If creating a distribution tape, this keyword specifies the capacity of the tape in Mbytes. This option is required if the media is not a DDS tape or a disk file. Without this option, swpackage sets the size to 1330 Mbytes for tape and "free space up to minfree" on a disk file.

media_type=directory

Defines the type of distribution to create. The recognized types are directory and tape.

package_in_place=false

If set to true, swpackage does not put the files that make up a product in the target depot. Instead, swpackage inserts references to the original source files, saving disk space.

reinstall_files=true

Causes all the files in a fileset to always be re-installed, re-copied, or re-packaged, even when the file already exists at the target and is identical to the new file. If set to false, files that have the same checksum (see next option), size and time stamp will not be re-installed, re-copied, or re-packaged. This check enhances performance on slow networks or slow disks.

reinstall_files_use_cksum=true

This option affects the operation when the reinstall_files option is set to false. It causes the checksums of the new and old file to be computed and compared to determine if the new file should replace the old one. (The checksum is slower, but is a more robust way to check for files being equivalent.) If set to false, the checksums are not computed, and files are (not) reinstalled based only on their size and time stamp. For swpackage, the default value for this option is false.

software=

Defines the default software_selections. There is no supplied default. If there is more than one software selection, they must be separated by spaces. Software is usually specified in a software input file, as operands on the command line, or in the GUI.

source_file=psf

Defines the default location of the source product specification file (PSF). The host:path syntax is not allowed, only a valid path can be specified. The -s option overrides this value.

source_type=directory

Defines the default source type: cdrom, file, directory, or tape. The source type derived from the -s option overrides this value.

targets=

Defines the default target_selections. There is no supplied default. If there is more than one target selection, they must be separated by spaces. Targets are usually specified in a target input file, as operands on the command line, or in the GUI.

uncompress_cmd=

Defines the command to uncompress files when installing, copying, or packaging. This command processes files which were stored on the media in a compressed format. If the compression_type of the file is gzip then the internal uncompression (funzip) is used instead of the external uncompress_cmd.

verbose=

Controls the verbosity of a non-interactive command's output:

0: disables output to stdout. (Error and warning messages are always written to stderr).
1: enables verbose messaging to stdout.
2: for swpackage and swmodify, enables very verbose messaging to stdout.

The -v option overrides this default if it is set to 0. Applies to all commands.

write_remote_files=false

Prevents the installation, copying, or packaging of files to a target which exists on a remote (NFS) filesystem. Also prevents the removal of files from a remote filesystem. All files destined for (or already on) a remote filesystem will be skipped.

If set to true and if the superuser has write permission on the remote filesystem, the remote files will not be skipped, but will be installed, copied, packaged, or removed.

Session File

Each invocation of the swpackage command defines a packaging session. The invocation options, source information, software selections, and target hosts are saved before the installation or copy task actually commences. This lets you re-execute the command even if the session ends before proper completion.

Each session is saved to the file $HOME/.sw/sessions/swpackage.last. This file is overwritten by each invocation of swpackage.

You can also save session information to a specific file by executing swpackage with the -C session__file option.

A session file uses the same syntax as the defaults files. You can specify an absolute path for the session file. If you do not specify a directory, the default location for a session file is $HOME/.sw/sessions/.

To re-execute a session file, specify the session file as the argument for the -S session__file option of swpackage.

Note that when you re-execute a session file, the values in the session file take precedence over values in the system defaults file. Likewise, any command line options or parameters that you specify when you invoke swpackage take precedence over the values in the session file.

Environment Variables

The environment variable that affects swpackageis:

LANG

Determines the language in which messages are displayed. If LANG is not specified or is set to the empty string, a default value of C is used. See the lang(5) man page by typing man 5 lang for more information.

NOTE: The language in which the SD agent and daemon log messages are displayed is set by the system configuration variable script, /etc/rc.config.d/LANG. For example, /etc/rc.config.d/LANG, must be set to LANG=ja_JP.SJIS or LANG=ja_JP.eucJP to make the agent and daemon log messages display in Japanese.

Signals

The swpackage command catches the signals SIGQUIT and SIGINT. If these signals are received, the command prints a message, sends a Remote Procedure Call (RPC) to the agents to wrap up, and then exits.

The agent ignores SIGHUP, SIGINT, and SIGQUIT. It immediately exits gracefully after receiving SIGTERM, SIGUSR1, or SIGUSR2. Killing the agent may leave corrupt software on the system, and thus should only be done if absolutely necessary. Note that when an SD command is killed, the agent does not terminate until completing the task in progress.

The daemon ignores SIGHUP, SIGINT and SIGQUIT. It immediately exits gracefully after receiving SIGTERM and SIGUSR2. After receiving SIGUSR1, it waits for completion of a copy or remove from a depot session before exiting, so that it can register or unregister depots if necessary. Requests to start new sessions are refused during this wait.

Locking

SD commands use a common locking mechanism for reading and modifying both root directories and software depots. This mechanism allows multiple readers but only one writer on a root or depot.

The SD commands which modify software in an (alternate) root directory are restricted from simultaneous modification using fcntl(2) locking on the file

var/adm/sw/products/swlock 

relative to the root directory (e.g. /var/adm/sw/products/swlock).

The SD commands which modify software in a depot are restricted from simultaneous modification using fcntl(2) locking on the file

catalog/swlock 

relative to the depot directory (e.g. /var/spool/sw/catalog/swlock).

All commands set fcntl(2) read locks on roots and depots using the swlock file mentioned above. When a read lock is set, it prevents other SD commands from performing modifications (i.e. from setting write locks).

PRODUCT SPECIFICATION FILE

This section summarizes the product_specification_file (PSF) which drives the swpackage session. See swpackage(4) for a detailed description of a PSF's syntax and semantics.

A PSF is structured as follows:

[depot specification]
     [vendor specification]
     [category specification]
     [bundle specification]
     [product specification]
          [control script specification]
          [subproduct specification]
          [fileset specification]
               [control script specification]
               [file specification]
          [fileset specification]
          ...
     [product specification]
     ...

If errors encountered while parsing the PSF result in no valid product definitions, swpackage terminates. All errors are logged to both stderr and the logfile. In summary, the swpackage user can:

Specify one or more products;
For each product, specify one or more filesets.
For each fileset, specify one or more files.
(optional) Specify attributes for the target depot/tape;
(optional) Specify one or more bundles, defining the bundle contents;
(optional) Specify vendor information for products and bundles;
(optional) Specify category information for products, bundles and patches.
(optional) For each product, specify one or more subproducts, defining the subproduct contents;
(optional) For each product or fileset, specify one or more control scripts.

RETURN VALUES

The swpackage command returns:

0: The products specified in the product_specification_file were successfully packaged into the target depot/tape.
1: An error occurred during the swpackage session (e.g. bad syntax in the product_specification_file.) Review stderr or the log file for details.

DIAGNOSTICS

The swpackage command writes to stdout, stderr, and to the logfile.

Standard Output

The swpackage command writes messages for significant events. These include:

a begin and end session message,
selection, analysis, packaging, and tape creation messages.

Standard Error

The swpackage command writes messages for all WARNING and ERROR conditions to stderr.

Logfile

The swpackage command logs detailed events to the log file /var/adm/sw/swpackage.log. The user can specify a different logfile by modifying the logfile option.

EXAMPLES

Package the products defined in the PSF products into the default target depot:

swpackage -s products 

Preview the same operation (do not create the target depot), and generate very verbose output:

swpackage -p -vv -s products 

Package the products into the target depot no_files, insert references to the source files instead of copying them into the depot:

swpackage -s products -x package_in_place=true @  no_files 

Re-package a specific fileset:

swpackage -s products -x package_in_place=true product.fileset 
@  no_files 

Re-package the entire contents of the depot /var/spool/sw onto the tape at /dev/rmt/0m:

swpackage -s /var/spool/sw -x media_type=tape  @  /dev/rmt/0m 

LIMITATIONS

The swpackage command does not apply to HP OpenView Software Distributor PC software. PC software is packaged on the PC controller using the PC console, then copied to a UNIX® depot for subsequent distribution.

FILES

/dev/rmt/0m: The default location of a source and target tape.
$HOME/.swdefaults: Contains the user-specific default values for some or all SD options.
$HOME/.sw/sessions/: Contains session files automatically saved by the SD commands, or explicitly saved by the user.
/usr/lib/sw/sys.defaults: Contains the master list of current SD options with their default values.
/var/adm/sw/: The directory which contains all of the configurable and non-configurable data for SD. This directory is also the default location of logfiles.
/var/adm/sw/defaults: Contains the active system-wide default values for some or all SD options.
/var/spool/sw/: The default location of a source and target software depot.

AUTHOR

swpackage was developed by the Hewlett-Packard Company and Mark H. Colburn (see pax(1)).