swmodify(1M)

NAME

swmodify — modify software products in a target root or depot

SYNOPSIS

swmodify [-d|-r] [-p] [-u] [-v] [-V] [-a attribute=[value]] [-c catalog] [-C session_file] [-f software_file] [-P pathname_file] [-s product_specification_file| [-S session_file] [-x option=value] [-X option_file] [software_selections] [@ target_selection]

Remarks

For an overview of all SD commands, see the sd(5) man page by typing man 5 sd on the command line.

DESCRIPTION

The swmodify command modifies the definitions of software objects installed into a primary or alternate root, or available from a software depot. It supports the following features:

adding new objects - The user can add new bundles, products, subproducts, filesets, control files, and files to existing objects (which will contain them).
deleting existing objects - The user can delete existing bundles, products, subproducts, filesets, control files, and files from the objects which contain them.
modifying attribute values - The user can add an attribute, delete an attribute, or change the existing value of an attribute for any existing object. When adding a new object, the user can at the same time define attributes for it.
committing software patches - The user can remove saved backup files, committing the software patch.

With the exception of control files, swmodify does not manipulate the actual files that make up a product (fileset). The command manipulates the catalog information which describes the files. However, swmodify can replace the contents of control files.

Common uses of swmodify include:

adding file definitions to the existing list of file definitions in a fileset. Example: If a fileset's control scripts add new files to the installed file system, the scripts can call swmodify to "make a record" of those new files.
changing the values of existing attributes. Example: If a product provides a more complex configuration process (beyond the SD configure script), that script can set the fileset's state to CONFIGURED upon successful execution.
defining new objects. Example: to "import" the definition of an existing application that was not installed by SD, construct a simple PSF describing the product. Then invoke swmodify to load the definition of the existing application into the IPD.

Options

swmodify supports the following options:

-d

Perform modifications on a depot (not on a primary or alternate root). The given target_selection must be a depot.

-p

Preview a modify session without modifying anything within the target_selection.

-r

Performs modifications on an alternate root directory, which must be specified in the @ target_selections option. (This option is not required for alternate root operations but is maintained for backward compatibility. See the Alternate Root Directory and Depot Directory heading in sd(5) for more information.)

-u

If no -a attribute=value options are specified, then delete the given software_selections from within the given target_selection. This action deletes the definitions of the software objects from the depot catalog or installed products database.

If -a attribute options are specified, then delete these attribute definitions from the given software_selections (from within the given target_selection).

-v

Turn on verbose output to stdout.

-V

List the data model revisions that this command supports.

-a attribute[=value]

Add, modify, or delete the value of the given attribute. If the -u option is specified, then delete the attribute from the given software_selections (or delete the value from the set of values currently defined for the attribute). Otherwise add/modify the attribute for each software_selection by setting it to the given value.

Multiple -a options can be specified. Each attribute modification will be applied to every software_selection.

The -s and -a options are mutually exclusive; the -s option cannot be specified when the -a option is specified.

-c catalog

Specifies the pathname of the catalog which will be added, modified, or used as input by swmodify.

The -c and -a options are mutually exclusive, the -c option cannot be specified when the -a option is specified.

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

-f software_file

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

-P pathname_file

Specify a file containing the pathnames of files being added to or deleted from the IPD instead of having to specify them individually on the command line.

-s product_specification_file

The source Product Specification File (PSF) describes the product, subproduct, fileset, and/or file definitions which will be added, modified, or used as input by swmodify.

The -s and -u options are mutually exclusive, the -s option cannot be specified when the -u option is specified.

-S session_file

Execute swmodify 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.

Operands

The swmodify command supports two types of operands: software selections followed by target selections. These operands are separated by the "at" (@) character. This syntax implies that the command operates on "software selections at targets".

Software Selections

If a product_specification_file is specified, swmodify will select the software_selections from the full set defined within the PSF. The software selected from a PSF is then applied to the target_selection, with the selected software objects either added to it or modified within it. If a PSF is not specified, swmodify will select the software_selections from the software defined in the given (or default) target_selection.

The swmodify 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 Selection

The swmodify command supports the specification of a single, local target_selection, using the syntax:

[ @ /directory] 

When operating on the primary root, no target_selection needs to be specified. (The target / is assumed.) When operating on a software depot, the target_selection specifies the path to that depot. If the -d option is specified and no target_selection is specified, the default distribution_target_directory is assumed (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. Using the prefix limits the change in the default value to that command. If you leave the prefix off, the change applies to all 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 keywords are supported by swmodify. If a default value exists, it is listed after the =. The commands that this option applies to are also specified. The policy options that apply to swmodify are:

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.
If you set the value of the installed_software_catalog default option to a relative path, that path is resolved relative to the value of this option.

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 installed_software_catalog and run_as_superuser options.

allow_large_files=false

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

When set to true, this option tells swmodify to permit files with a size greater than or equal to 2 gigabytes to be modified. If the files are in a depot, then 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)

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.

control_files=

When adding or deleting control file objects, this option lists the tags of those control files. There is no supplied default. If there is more than one tag, they must be separated by white space and surrounded by quotes.

distribution_target_directory=/var/spool/sw

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

files=

When adding or deleting file objects, this option lists the pathnames of those file objects. There is no supplied default. If there is more than one pathname, they must be separated by white space.

installed_software_catalog=products

Defines the directory path where the Installed Products Database (IPD) is stored. This information describes installed software. When set to an absolute path, this option defines the location of the IPD. When this option contains a relative path, the SD controller appends the value to the value specified by the admin_directory option to determine the path to the IPD. For alternate roots, this path is resolved relative to the location of the alternate root. This option does not affect where software is installed, only the IPD location.

This option permits the simultaneous installation and removal of multiple software applications by multiple users or multiple processes, with each application or group of applications using a different IPD.

Caution: use a specific installed_software_catalog to manage a specific application. SD does not support multiple descriptions of the same application in multiple IPDs.

See also the admin_directory and run_as_superuser options, which control SD's nonprivileged mode. (This 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.)

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<modify>.log

Defines the default log file for swmodify.

loglevel=1 (for direct invocation)

loglevel=0 (for invocation by a control script)

Controls the log level for the events logged to the swmodify 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.

To enable logging by swmodify commands invoked by control files, add the following line to the system defaults file:

swmodify.loglevel=1

patch_commit=false

Commits a patch by removing files saved for patch rollback. When set to true, you cannot roll back (remove) a patch unless you remove the associated base software that the patch modified.

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.

See also the admin_directory and installed_software_catalog options.

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=

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.

targets=

Defines the default target_selections. There is no supplied default (see select_local above). 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.

verbose=1

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 swmodify, enables very verbose messaging to stdout.

Session File

Each invocation of the swmodify command defines a modify 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 automatically saved to the file $HOME/.sw/sessions/swmodify.last. This file is overwritten by each invocation of swmodify.

You can also save session information to a specific file by executing swmodify 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 swmodify. See the swpackage(4) by typing man 4 swpackage for PSF syntax.

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 swmodify take precedence over the values in the session file.

Environment Variables

The environment variable that affects swmodify 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 swmodify command ignores SIGHUP, SIGTERM, SIGUSR1, and SIGUSR2. The swmodify command catches SIGINT and SIGQUIT. If these signals are received, swmodify prints a message and then exits. During the actual database modifications, swmodify blocks these signals (to prevent any data base corruption). All other signals result in their default action being performed.

RETURN VALUES

The swmodify command returns:

0: The add, modify, or delete operation(s) were successfully performed on the given software_selections.
1: An error occurred during the session (e.g. bad syntax in the PSF, invalid software_selection, etc.) Review stderr or the logfile for details.

DIAGNOSTICS

The swmodify command writes to stdout, stderr, and to specific logfiles.

Standard Output

In verbose mode, the swmodify command writes messages for significant events. These include:

a begin and end session message,
selection, analysis, and execution task messages.

Standard Error

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

Logfile

The swmodify command logs events to the command logfile and to the swmodify logfile associated with each target_selection.

Command Log: The swmodify command logs all messages to the the logfile /var/adm/sw/swmodify.log. (The user can specify a different logfile by modifying the logfile option.)
Target Log: When modifying installed software, swmodify logs messages to the file var/adm/sw/swagent.log beneath the root directory (e.g. / or an alternate root directory). When modifying available software (within a depot), swmodify logs messages to the file swagent.log beneath the depot directory (e.g. /var/spool/sw).

EXAMPLES

Add additional files to an existing fileset:

swmodify -xfiles='/tmp/a /tmp/b /tmp/c'  PRODUCT.FILESET 

Replace the definitions of existing files in an existing fileset (e.g. to update current values for the files' attributes):

chown root /tmp/a /tmp/b 
swmodify -x files='/tmp/a /tmp/b'  PRODUCT.FILESET 

Delete control files from a fileset in an existing depot:

swmodify -d -u -x control_files='checkinstall subscript' \ 
         PRODUCT.FILESET @  /var/spool/sw 

Create a new fileset definition where the description is contained in the PSF file new_fileset_definition:

swmodify -s new_fileset_definition 

Delete an obsolete fileset definition:

swmodify -u PRODUCT.FILESET 

Commit a patch (remove files saved for patch rollback):

swmodify -x patch_commit=true PATCH 

Create some new bundle definitions for products in an existing depot:

swmodify -d -s new_bundle_definitions \* @ /mfg/master_depot

Modify the values of some fileset's attributes:

swmodify -a state=installed  PRODUCT.FILESET 

Modify the attributes of a depot:

swmodify -a title='Manufacturing's master depot' \ 
         -a description=</tmp/mfg.description @  /mfg/master_depot 

WARNINGS

If the target_selection is a software depot and you delete file definitions from the given software_selections, the files' contents are not deleted from the depot.

FILES

$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/adm/sw/products/: The Installed Products Database (IPD), a catalog of all products installed on a system.
/var/spool/sw/: The default location of a target software depot.

AUTHOR

swmodify was developed by the Hewlett-Packard Company.