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 on the command line.
For an overview of all SD commands, see the sd(5) man page by typing man 5 sd on the command line.
For descriptions of all SD objects, attributes and data formats, see the sd(4) man page by typing man 4 sd on the command line.

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,
Copies products in a distribution directory to 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 data model revision that swpackage supports. By default, swpackage always packages using the latest 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

(Obsolete but allowed for backward compatibility. Use the @ target_selection operand instead.)

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).

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

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.

The swpackage command supports the following syntax for each software_selection:

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

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

The = (equals) relational operator lets you specify selections with the following shell wildcard and pattern-matching notations:
- [ ], *, ?
Bundles and subproducts are recursive. Bundles can contain other bundles and subproducts can contain other subproducts.
The \* software specification selects all products. Use this specification with caution.

The version component has the form:

[,r <op> revision][,a <op> arch][,v <op> vendor] 
[,c <op> category][,q=qualifier][,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.
r , a , v , c , and l apply only to bundles and products. They are applied to the leftmost bundle or product in a software specification.
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 software, 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.

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.

admin_directory=/var/adm/sw (for normal mode)

admin_directory=/var/home/LOGNAME/sw (for nonprivileged mode)

The location for SD logfiles and the default parent directory for the installed software catalog. The default value is /var/adm/sw for normal SD operations. When SD operates in nonprivileged mode (that is, when the run_as_superuser default option is set to true):

The default value is forced to /var/home/LOGNAME/sw.
The path element LOGNAME is replaced with the name of the invoking user, which SD reads from the system password file.
If you set the value of this option to HOME/path, SD replaces HOME with the invoking user's home directory (from the system password file) and resolves path relative to that directory. For example, HOME/my_admin resolves to the my_admin directory in your home directory.

SD's nonprivileged mode is intended only for managing applications that are specially designed and packaged. This mode cannot be used to manage the HP-UX operating system or patches to it. For a full explanation of nonprivileged SD, see the Software Distributor Administration Guide, available at the http://docs.hp.com web site.

See also the run_as_superuser option.

allow_large_files=false

Determines whether packaging of files with a size greater than or equal to 2 gigabytes is allowed. In the default state of false, this option tells swpackage to not allow files with a size greater than or equal to 2 gigabytes to be packaged.

When set to true, this option tells swpackage to permit files with a size greater than or equal to 2 gigabytes to be packaged. The depot can only be used by the December 2005 OEUR (HP-UX 11i v2) version of SD and newer versions of SD on HP-UX 11i v1, HP-UX 11i v2, and future releases.

This version of SD supports a large file up to 2 terabytes (2048 gigabytes)

allow_large_serial_depot=false

Determines whether a serial depot can be created larger than 2 gigabytes. In the default state of false, this option tells swpackage to limit the size of the depot to 2 gigabytes.

When set to true, this option tells swpackage to permit the creation of a serial depot greater than 2 gigabytes. The depot is only usable by SD in the HP-UX 11i v1 (11.11) December 2004 OEUR, HP-UX 11i v2 (11.23) March 2005 OEUR and newer releases.

allow_partial_bundles=true

Determines whether to process partial bundles without WARNINGs and NOTEs. In the default state of true, this option tells swpackage to package what is available in the PSF. Missing or ambiguous bundle contents are ignored and no WARNINGs and NOTEs are issued.

When set to false, this option tells swpackage to expect all the bundle contents to be present and unique in the PSF. Objects that are ambiguous or missing generates a NOTE and every bundle with missing or ambiguous content generates a WARNING. (Note that swpackage succeeds even if NOTEs and WARNINGS occur.)

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, uncompressed files are compressed before transfer from a source. This enhances performance on slower networks for swcopy and swinstall, and results in smaller depots for swcopy and swpackage, unless the uncompress_files option is also set to true.

compress_index=false

Determines whether SD commands create compressed INDEX and INFO catalog files when writing to target depots or roots. The default of false does not create compressed files. When set to true, SD creates compressed and uncompressed INDEX and INFO files. The compressed files are named INDEX.gz and INFO.gz, and reside in the same directories as the uncompressed files.

Compressed files can enhance performance on slower networks, although they may increase disk space usage due to a larger Installed Products Database and depot catalog. SD controllers and target agents for HP-UX 11.01 and higher automatically load the compressed INDEX and INFO files from the source agent when:

The source agent supports this feature.
INDEX.gz or INFO.gz exist on the source depot.
INDEX.gz or INFO.gz are not older than the corresponding uncompressed INDEX or INFO files.

The uncompressed INDEX or INFO file is accessed by the source agent if any problem occurs when accessing, transferring, or uncompressing the INDEX.gz or INFO.gz file.

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 location of the source depot (when the source_type is directory). You can also use the host:path syntax. 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.

log_msgid=0

Adds numeric identification numbers at the beginning of SD logfile messages:

0: (default) No identifiers are attached to messages.
1: Adds identifiers to ERROR messages only.
2: Adds identifiers to ERROR and WARNING messages.
3: Adds identifiers to ERROR, WARNING, and NOTE messages.
4: Adds identifiers to ERROR, WARNING, NOTE, and certain other informational messages.

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 or multiple-directory media such as a CD-ROM, this keyword specifies the capacity of the tape in one million byte units (not 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 the default of 1,330 Mbytes for tape or to the amount of free space on the disk up to minfree for a disk file. SD uses the same format across multiple directory media as it does for multiple serial media, including calculations of the correct size based partitioning of filesets and setting of the media_sequence_number attributes.

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=false

Controls the overwriting of files, which may enhance performance on slow networks or disks. At the default value of false, SD compares each file in a source fileset to corresponding files on the target system. SD compares the files based on size, timestamp, and (optionally) the checksum (see reinstall_files_use_cksum). If the files are identical the files on the target system are not overwritten.

When set to true, SD does not compare files and overwrites any identical files on the target.

reinstall_files_use_cksum=false

Controls the use of checksum comparisons when the reinstall_files option is set to false. At the default value of true, this option causes SD to compute and compare checksums to determine if a new file should overwrite an old file. Use of checksums slows the comparison but is a more robust check for equivalency than size and time stamp.

If set to false, SD does not compute checksums and compares files only by size and timestamp.

run_as_superuser=true

This option controls SD's nonprivileged mode. This option is ignored (treated as true) when the invoking user is super-user.

When set to the default value of true, SD operations are performed normally, with permissions for operations either granted to a local super-user or set by SD ACLs. (See swacl(1M) for details on ACLs.)

When set to false and the invoking user is local and is not super-user, nonprivileged mode is invoked:

Permissions for operations are based on the user's file system permissions.
SD ACLs are ignored.
Files created by SD have the uid and gid of the invoking user, and the mode of created files is set according to the invoking user's umask.

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 swpackage is:

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.

LC_ALL

Determines the locale to be used to override any values for locale categories specified by the settings of LANG or any environment variables beginning with LC_.

LC_CTYPE

Determines the interpretation of sequences of bytes of text data as characters (e.g., single-versus multibyte characters in values for vendor-defined attributes).

LC_MESSAGES

Determines the language in which messages should be written.

LC_TIME

Determines the format of dates (create_date and mod_date) when displayed by swlist. Used by all utilities when displaying dates and times in stdout, stderr, and logging.

TZ

Determines the time zone for use when displaying dates and times.

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 PSF 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 

FILES

/dev/rmt/0m: The default location of a source and target tape. (Note that SD can read both tar and cpio tape depots.)
$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)).