NAME

sd − SD objects, attributes, and storage formats

DESCRIPTION

The HP OpenView Software Distributor (SD) creates, distributes, installs, and manage software products. In addition, SD defines and manages other objects in support of the software administration tasks which users perform.  This manual page describes the SD object classes, their attributes, and the file formats used to store their definitions.

OBJECT CLASSES

The SD object classes are:

host This class represents a host at which software is installed, will be installed, or is being managed.  A host contains one or more roots (installed filesystems) and zero or more depots.

depot This class represents a software depot which contains software products available for installation.  It also represents a distribution media (e.g. tape or CD-ROM) which contains products available for installation. 

root This class represents a set of installed software products, usually the operational software installed in the primary root filesystem, "/".  It also represents also the set of products installed into an alternate root directory.

product This class represents a software product, which vendors package and distribute, and which users purchase and install.  A product contains one or more filesets and zero or more subproducts. A product can also contain zero or more control scripts.

vendor This class represents the vendor who packaged and distributed a product. It is an optional component of a product.

subproduct This class represents a subset or partitioning of a software product.  It is an optional component of a product. A subproduct contains one or more filesets.

fileset This class represents a grouping of one or more files contained in a product. It groups a subset of a product’s files into a manageable unit. A fileset can also contain zero or more control scripts.

file This class represents the actual files that make up a fileset; which files get installed, configured, and removed by SD.

control script
This class represents the scripts developed by vendors to perform product- or fileset-specific operations during various SD tasks.

OBJECT ATTRIBUTES

The following tables summarize the valid attributes for each SDU object class.  A subset of these attributes can be defined for an object when creating products with swpackage.  See swpackage(4) for details on this subset. 

The value types for each attribute are defined after the attribute tables. 

Host Attributes

 

Attribute	Type	Size	Example
name	one_line_string	64	newdist.fc.hp.com
machine_type	uname_string	32	9000/720
os_name	uname_string	32	HP-UX
os_release	uname_string	32	A.09.01
os_version	uname_string	32	C
contained	list of depot
depots	objects

name The official name of the network host. 

machine_type
The host’s machine and architecture designation. (uname -m).  field). 

os_name
The host’s operating system name. (uname -s). 

os_release
The host’s operating system release. (uname -r). 

os_version
The host’s operating system version. (uname -v). 

contained depots
The depots registered at the host.

Depot Attributes

 

Attribute	Type	Size	Example
tag	tag_string	16	APPLICATIONS_CD
data_model_revision	revision_string	32	2.00
title	one_line_string	80	Applications Software Disc
description	multi_line_string	2048	"This depot ..."
copyright	multi_line_string	8192	"This depot ..."
number	tag_string	32	B2358-13601
uuid	hex_string	40	25CA7C86-6F0C-080009353595
date	one_line_string	64	Tue Jun 22 12:52:09 1993
timestamp	unsigned_integer		740774837
media_sequence_	unsigned_integer		1
number
path_max	unsigned_integer		1023
name_max	unsigned_integer		255
contained	list of product
products	objects

tag The identifier (short name) for the distribution depot/tape. 

data_model_revision
The SD format revision used to store the depot definition.

title
The full name (one-line description) of the distribution depot/tape.

description
The multi-paragraph description of the distribution depot/tape.

copyright
The copyright information for the depot/tape;

number
The part or manufacturing number of the depot/tape.

uuid The depot’s Universal Unique Indentifier (UUID). 

timestamp
The time of the last operation performed on the depot.

date The string format of the timestamp. 

media_sequence_number
For a multiple tape distribution, defines the tape number of each tape.

path_max
The maximum length of file pathnames in the depot.

name_max
The maximum length of file basenames in the depot.

contained products
The products available from the depot.

Root Attributes

 

Attribute	Type	Size	Example
data_model_revision	revision_string	32	2.00
timestamp	unsigned_integer		740774837
contained	list of product
products	objects

data_model_revision
The SD format revision used to store the root definition.

timestamp
The time of the last operation performed on the root.

contained products
The products installed into the root.

Product Attributes

 

Attribute	Type	Size	Example
tag*	tag_string	16	SD
data_model_revision	revision_string	32	2.00
revision*	revision_string	32	2.0
title	one_line_string	80	Software Distributor
description	multi_line_string	2048	"This product ..."
copyright	multi_line_string	8192	"This product ..."
readme	multi_line_string	1024K	< README
number	tag_string	32	J2326AA
category	one_line_string	80	systems management
vendor*	vendor object
instance_id	unsigned_integer		1
control_directory	path_string	255	SD
size	unsigned_integer		14638872
date	one_line_string	64	Mon Jun 14 13:01:19 1993
timestamp	unsigned_integer		740084479
directory	path_string	1024	/
is_locatable	boolean	5	false
location	path_string	1024	/
architecture*	one_line_string*	80	S700/S800_HP-UX_9.0
machine_type	uname_string	64	9000/7*|9000/8*
os_name	uname_string	32	HP-UX
os_release	uname_string	32	?.09.*
os_version	uname_string	32	[A-Z]
all_filesets	one-line list of		commands agent data man
	tag_string values
contained	list of fileset
filesets	objects
contained	list of subproduct
subproducts	objects
contained	list of control
control scripts	script objects

The attributes marked with a * determine the uniqueness of a product object.  Their values are also of type version_component, in addition to the defined type above. 

tag The identifier (short name) for the product. 

data_model_revision
The SD format revision used to store the product definition.

revision
The revision (release number, version number) of the product.

title
The full name (one-line description) of the product.

description
The multi-paragraph description of the product.

copyright
The copyright information for the product.

readme
The README information for the product.

number
The part or order number for the product.

category
The term or phrase that categorizes the product.

vendor
The vendor object defined for the product.

instance_id
The secondary identifier for products which have the same tag (or truncated tag) value. 

control_directory
The relative pathname to the product catalog (within the depot/root catalog).

size The size of the product in bytes. 

timestamp
The time of the last operation performed on the product.

date The string format of the timestamp. 

directory
The default pathname in which the product’s files will be installed.

is_locatable
Defines whether (or not) the product can be installed into a arbitrary directory.

location
The installed pathname of the product.

architecture
The target system(s) on which the product will run.

machine_type
The machine(s) on which the product will run.

os_name
The operating system(s) on which the product will run.

os_release
The operating system release(s) on which the product will run.

os_version
The operating system versions(s) on which the product will run.

all_filesets
All the filesets originally packaged into the product.

contained filesets
The fileset defined for the product.

contained subproducts
The subproducts defined for the product.

contained control scripts
The scripts defined for the product.

Vendor Attributes

 

Attribute	Type	Size	Example
tag*	tag_string	16	HP
uuid*	hex_string	40	1234567-CDEF-0123-4569ABCDEF
title	one_line_string	80	Hewlett-Packard Company
description	multi_line_string	2048	"This vendor ..."

The attributes marked with a * determine the uniqueness of a product object.  Their values are also of type version_component, in addition to the defined type above. 

tag The identifier (short name) for the vendor. 

uuid The vendor’s NetLS Universal Unique Indentifier (UUID). 

title
The full name (one-line description) for the vendor.

description
The multi-paragraph description of the vendor.

When listing the vendor attributes with swlist, the option -a vendor lists all of the vendor attributes.  The option -a vendor.attribute can be used to list specific vendor attributes (e.g.  -a vendor.title). 

Subproduct Attributes

 

Attribute	Type	Size	Example
tag	tag_string	16	Manager
title	one_line_string	80	Management Utilities
description	multi_line_string	2048	"This subproduct ..."
size	unsigned_integer		14638872
contents	one-line list of		commands agent data man
	tag_string values

tag The identifier (short name) for the subproduct. 

title
The full name (one-line description) of the subproduct.

description
The multi-paragraph description of the subproduct.

size The size of the subproduct in bytes. 

contents
A list of the filesets that make up the subproduct.

Fileset Attributes

 

Attribute	Type	Size	Example
tag	tag_string	16	commands
data_model_revision	revision_string	32	2.00
revision	revision_string	32	2.15
title	one_line_string	80	Commands
description	multi_line_string	2048	"This fileset ..."
instance_id	unsigned_integer		1
control_directory	path_string	255	SD
size	unsigned_integer		14638872
state	state_enumeration		corrupt
date	one_line_string	64	Mon Jun 14 13:01:19 1993
timestamp	unsigned_integer		740084479
is_kernel	boolean	5	false
is_reboot	boolean	5	false
media_sequence_	unsigned_integer		1
number
prerequisites	list of software_		SD.agent
	specifications
corequisites	list of software_		SD.man
	specifications
contained	list of control
control scripts	script objects
contained	list of file
files	objects

tag The identifier (short name) for the fileset. 

data_model_revision
The SD format revision used to store the fileset definition.

revision
The revision (release number, version number) of the fileset.

title
The full name (one-line description) of the fileset.

description
The multi-paragraph description of the fileset.

instance_id
The secondary identifier for filesets which have the same tag (or truncated tag) value. 

control_directory
The relative pathname to the fileset catalog (within the product catalog).

size The size of the fileset in bytes. 

state
The current state of the fileset (resulting from the most recent SD operation performed on it).

timestamp
The time of the last operation performed on the fileset.

date The string format of the timestamp. 

is_kernel
Defines whether (or not) the fileset contains kernel files.

is_reboot
Defines whether (or not) the fileset requires a reboot after install.

media_sequence_number
For a multiple tape distribution, defines the tape on which the fileset is archived.

prerequisites
A list of install-time dependencies on other software.

corequisites
A list of run-time dependencies on other software.

contained control scripts
The scripts defined for the fileset.

contained files
The files defined for the fileset.

Control Script Attributes

 

Attribute	Type	Size	Example
tag	tag_string	16	checkinstall
path	path_string	255	checkinstall
result	result_enumeration		success

Control scripts can be defined for filesets and/or products. 

tag The identifier (short name) for the control script. 

path The relative pathname to the control script (same as the tag for SD 2.0). 

result
The result obtained from executing the control script.

File Attributes

 

Attribute	Type	Size	Example
path	path_string	255	/usr/sbin/swpackage
type	file_type_enumeration		f
mode	unsigned integer		04555
owner	tag_string	32	root
group	tag_string	32	sys
uid	unsigned_integer		0
gid	unsigned_integer		0
mtime	unsigned_integer		740084479
size	unsigned_integer		2494464
cksum	hex_string	8	18355158
revision	revision_string	32	1.3
link_source	path_string	1024	/usr/sbin/swinstall
source_path	path_string	1024	/mfg/sbin/swinstall
is_volatile	boolean	5	false

path The full pathname to the file. 

type The type of file. 

mode The file permission mode. 

owner
The name of the file’s owner.

group
The name of the file’s group.

uid The UID of the file’s owner. 

gid The GID of the file’s owner. 

mtime
The last modification time of the file.

size The size of the file in bytes. 

cksum
The 32-bit checksum of the file.

revision
The what(1) or ident(1) revision of the file. 

link_source
The path to which a hard or symbolic points.

source_path
The full path to the source file for files which have been "packaged in place"; see swpackage(8).

is_volatile
Defines whether the file can be modified or removed.

Value Types

The value for each attribute must be of a specific type (as noted in the table above).  The types are:

tag_string
maximum length: 16 bytes
examples: HP, SD

Tag strings containing a subset of isascii(3) characters only. 
Requires one or more characters from: A-Z, a-z, 0-9, including the first character.
The isspace(3) characters are not allowed.
SDU metacharacters not allowed: .,=#
Shell metacharacters not allowed: ;&(){}|<>
Shell quoting characters not allowed: "‘’\
Directory path character not allowed: /

hex_string
maximimum length: 40 bytes
examples: 01234567-CDEF-0123-4569ABCDEF

Uuids composed of 32 hexadecimal digits separated by dashes. 
Represents an unsigned integer. (Each hex digit represents 4 bits of the unsigned integer.)
Allows hexadecimal digits: 0-9, A-F
Allows separator characters: -

one_line_string
maximum length: 80 bytes
examples: Hewlett-Packard Company

One-line strings support a subset of isascii(3) characters only. 
No isspace(3) characters, except for space and tab, are allowed. multi_line_string maximum length: 2048, 8192, or 1024K bytes

Multi-line strings support all isascii(3) characters.  They represent one or more paragraphs of text.  They are usually specified in-line, surrounded by double-quotes.  (The product readme is stored in a file, and specified using the "< filename" format). 

revision_string
maximum length: 32 bytes
examples: 2.0, A.09.00

Revision strings contain zero or more dot-separated one_line_strings (above). 

boolean
maximum length: 5 bytes
examples: true, false

One of the values "true" or "false". 

path_string
maximum length: 255 bytes for tapes, 1024 bytes for depots
examples: /usr, /mfg/sd/scripts/configure

An absolute or relative path to a file. 

uname_string
maximum length: 32 or 64 bytes
examples: 9000/7*|9000/8*, HP-UX, ?.09.*, [A-Z]

Uname strings containing a subset of isascii(3) characters only. 
No isspace(3) characters are allowed.
Shell pattern matching notation allowed: []*?!
Patterns can be "or’ed" together using the separator: |

software_specification
maximum length: none
examples: SD.agent, SD,r=2.0,a=Series_700/800_HP-UX_9.0,v=HP

An SD software specification of the form:

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

where the version component has the form:

[r=revision][,a=arch][,v=vendor][,vid=vendor_uuid]

version_component
maximum length: none

A further restriction for the tag, revision, architecture, vendor tag, and vendor uuid, attributes. 
No isspace(3) characters are allowed.
Shell pattern matching notation not allowed: []*?!

unsigned_integer
maximum length: none

An integer in the range >= 0 and <= 2^32. 

state_enumeration
maximum length: none

One of the following fileset states: transient, corrupt, available, installed, or configured. 

result_enumeration
maximum length: none

One of the following control script results: not yet, error, warning, or success. 

file_type_enumeration
maximum length: none

One of the following file types: file, directory, hard link, or symbolic link. 

HOST OBJECT FORMAT

The file /var/adm/sw/host_object defines the software depots on the local host which have been registered with the swagentd daemon running on the host.  The file has this format:

host
    data_model_revision  2.00

    distribution           Defines a contained (registered) depot
        path directory

    distribution
        path directory

    ... 

DEPOT (DISTRIBUTION) FORMAT

An SD 2.0 depot is formatted using the following directory structure:

catalog/	Catalog of depot’s contents
INDEX	Global index (table of contents)
swlock	Controls simultaneous modification
dfiles/	Stores all depot-specific information
INDEX	Defines depot-specific attributes
INFO	Defines depot-specific files
_ACL	Access Control List (ACL) for the depot
_OWNER	Owner and group of the depot’s creator
_LOCK_FILE	Controls simultaneous ACL modification
_PROD_DFLT_ACL	Default ACL for new products
product_directory/	Catalog for a product
pfiles/	Stores all product-specific information
INDEX	Defines product attributes
INFO	Defines product files and scripts
README	The product’s README attribute
scripts	Zero or more product control scripts
_ACL	ACL for the product
_OWNER	Owner and group of the product’s creator
_LOCK_FILE	Controls simultaneous ACL modification
fileset_directory/	Catalog for a fileset
INDEX	Defines fileset attributes
INFO	Defines fileset files and scripts
scripts	Zero or more fileset control scripts
fileset_directory/	Catalog for the next fileset
...
product_directory/	Catalog for the next product
...
product_directory/	Contents of a product
fileset_directory/	Contents of a fileset
...	Contents of the next fileset
product_directory/	Contents of the next product
...

The format is divided into two areas:

• the catalog, which contains all the information which describes the products contained in the depot;

• the contents, which stores the actual files contained in each product (one product_directory per product.) 

Product and Fileset Directory Names

The product_directory and fileset_directory values are unique storage directories for a given product and fileset.  They have this syntax:

tag[.instance_id]

The tag component is the product or fileset tag attribute.  If more than one product with the same tag exists in the software depot, then the instance_id component is also necessary for all additional products with the same tag.  This component is the product or fileset.  instance_id attribute. 

On a short-filename filesystem, the tag component is truncated to the first 9 characters (if necessary).  All products with the same truncated tag will also have a unique storage directory based on the instance_id component. 

Distribution Tape Format

A distribution tape contains the depot format (above), archived to one or more tapes in tar(1) format.  The entire catalog precedes the depot contents on a distribution tape. 

If the distribution spans multiple tapes, then the first tape contains the entire catalog, and as many fileset contents directories as will fit on the tape.  Each additional tape contains only the catalog/INDEX followed by as many fileset contents directories as will fit on the tape. 

INSTALLED PRODUCTS DATABASE FORMAT

An SD 2.0 Installed Products Database (IPD) describes the software installed in a primary or alternate root filesystem.  The format of an IPD is similar to the format of a software depot.  An IPD is formatted using the following directory structure:

var/adm/sw/products/	Catalog of root’s contents
INDEX	Global index (table of contents)
swlock	Controls simultaneous modification
ifiles/	Stores all root-specific information
INDEX	Defines root-specific attributes
INFO	Defines root-specific files
_ACL	Access Control List (ACL) for the root
_OWNER	Owner and group of the root’s creator
_LOCK_FILE	Controls simultaneous ACL modification
product_directory/	Catalog for a product
pfiles/	Stores all product-specific information
INDEX	Defines product attributes
INFO	Defines product files and scripts
README	The product’s README attribute
scripts	Zero or more product control scripts
fileset_directory/	Catalog for a fileset
INDEX	Defines fileset attributes
INFO	Defines fileset files and scripts
scripts	Zero or more fileset control scripts
fileset_directory/	Catalog for the next fileset
...
product_directory/	Catalog for the next product
...

Product and Fileset Directory Names

The product_directory and fileset_directory values are as described for the depot format above. 

INDEX FORMAT

An INDEX file describes all of the attributes (except for contained scripts and contained files) of a fileset, product, depot, or root.  In a depot, the fileset, product, and depot INDEX files are concatenated together to form the catalog/INDEX file.  In a root, the fileset, product, and root INDEX files are concatenated together to form the var/adm/sw/products/INDEX file. 

This section describes the keyword syntax used in an INDEX file.  The value for each keyword must meet the type restrictions described in the OBJECT ATTRIBUTES section. 

Fileset INDEX

fileset

tag	tag_value
data_model_revision	revision_value
revision	revision_value
title	title_value
description	description_value
instance_id	id_value
control_directory	control_directory_value
size	size_value
state	state_value
timestamp	timestamp_value
is_kernel	boolean_value
is_reboot	boolean_value
media_sequence_number	sequence_value
prerequisite	prerequisite_value
corequisite	corequisite_value

The tag attribute is always required.  The media_sequence_number attribute is required for filesets within a multiple tape distribution. 

Multiple prerequisite and corequisite definitions are allowed. 

Product INDEX

product

tag	tag_value
data_model_revision	revision_value
revision	revision_value
title	title_value
description	description_value
copyright	copyright_value
readme	readme_value
number	number_value
category	category_value
instance_id	id_value
control_directory	control_directory_value
timestamp	timestamp_value
directory	directory_value
is_locatable	boolean_value
location	location_value
architecture	architecture_value
machine_type	machine_type_value
os_name	os_name_value
os_release	os_release_value
os_version	os_version_value
all_filesets	all_filesets_value
vendor
tag	tag_value
uuid	uuid_value
title	title_value
description	description_value
subproduct
tag	tag_value
uuid	uuid_value
title	title_value
description	description_value
contents	contents_value

The tag attribute is always required. 

For subproducts, the tag and contents attributes are required.  Multiple subproduct definitions are allowed. 

For vendor, the tag attribute is required. 

Depot INDEX

distribution

tag	tag_value
data_model_revision	revision_value
title	title_value
description	description_value
copyright	copyright_value
number	number_value
uuid	uuid_value
timestamp	timestamp_value
media_sequence_	sequence_value
path_max	path_max_value
name_max	name_max_value

No attributes are required. 

Root INDEX

root

data_model_revision	revision_value
timestamp	timestamp_value

No attributes are required. 

INFO FORMAT

An INFO file describes all of the control scripts and files contained within a fileset, product, depot, or root.  (For SD 2.0, only the INDEX and INFO themselves are listed in a depot/root INFO file.)  This section describes the keyword syntax used in an INFO file.  The value for each keyword must meet the type restrictions described in the OBJECT ATTRIBUTES section. 

Control Script Format

control_file

path	path_value
tag	tag_value
result	result_value

The path, and tag attributes are required. 

File Format

file

path	path_value
type	file_type_value
mode	mode_value
owner	owner_value
group	group_value
uid	uid_value
gid	gid_value
mtime	mtime_value
size	size_value
cksum	cksum_value
revision	revision_value
link_source	source_value
source_path	source_value
is_volatile	boolean_value

The path, and type attributes are always required.  The link_source attribute is required for hard link and symbolic link files. 

ACL FORMAT

An SD Access Control List (ACL) has this format:

# default_realm = host_name
entry_type:[key:]permissions
entry_type:[key:]permissions
entry_type:[key:]permissions

See the swacl(8) manual page for details on the fields in an ACL entry.  Note that the permissions of a stored ACL are literal octal strings, but the permissions displayed by swacl are symbolic. 

The _OWNER file uses a subset of the ACL format.  It contains an entry for the user and group names of the user who created the corresponding object. 

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

The swacl command is restricted from simultaneous modification of an ACL using fcntl(2) read and write locks on the

_LOCK_FILE

associated with each ACL. 

AUTHOR

The Software Distributor was developed by the Hewlett-Packard Company. 

SEE ALSO

swacl(8), swagentd(8), swconfig(8), swcopy(8), swdepot(8), swinstall(8), swlist(8), swpackage(8), swremove(8), swverify(8), swpackage(4), sd(5), and the HP OpenView Software Distributor Administrator’s Guide.

Hewlett-Packard Company  —  Software Distributor 2.0