swinstall(8)
Contents
swinstall -- Install POSIX and RPM packages.
swinstall [-p] [-r] [-s source_file] [-f file] \
[-t targetfile] [-x option=value] [-X options_file] [-W option] \
[software_selections] [@target [target1...]]
swinstall -s - # Minimum unambiguous invocation.
As of 2004-04-03 swinstall is usable at an alpha release level.
As of 2005-05-03 swinstall is usable at an alpha release level with
additional newly implemented features for checkinstall, preinstall, and
postinstall execution. Fileset state and script exit status recording
are also newly implemented. Dependency checks are not implemented.
Software selections are not implemented. Only distributions with one
(1) product and one (1) fileset are supported. At this time, symlink,
hard links, directory, and device files are not supported unless they
appear in the storage section in which case they will be installed
using the local system archive reading utility, either 'tar' or 'pax'.
(The Posix spec does not require non-regular files to exist in the
storage section).
swinstall installs a Posix distribution from a source archive to a tar-
get directory. A Posix distribution is a package, typically a com-
pressed tarball with metadata files in the prescribed file layout.
Neither swinstall nor any component of swbis is required on the target
host, however, the target host must look like a Unix system at the
shell and command-line utility level and have a posix shell. Remote
network connections are made by ssh. Ssh is the default but rsh can be
selected by a command line option.
By default and with no external influences (i.e. swdefaults file) swin-
stall will read an archive on stdin and install all products and file-
sets of package in "/" directory on the target host. An alternate root
may be specified using the target syntax. The distribution source
directory (swbis default: stdin) is selectable via the defaults file,
therefore it should be specified in uncontrolled environments.
swinstall operates on cpio or tar archives. swinstall supports cpio
archives by first translating to tar format, therefore, to reduce the
data transformations performed by swinstall, distributors encouraged to
deliver products in tar format.
-f FILE
Reads software_selections from FILE. (Not implemented).
-p
Preview the operation. Depending on the verbose level informa-
tion is written to stdout. The target is not modified although
a remote connection is established.
-r
This option has no affect.
-s SOURCE
Specify the source file SOURCE, "-" is standard input. The syn-
tax is the same as for a target. SOURCE may be an archive file
or stdin.
-t targetfile
Specify a file containing a list of targets (one per line).
-x option=value
Specify the extended option overriding the defaults file value.
-X FILE
Specify the extended options filename, FILE, overriding the
default filenames. This option may be given more then once. If
the resulting specified value is an empty string then reading of
any options file is disabled.
-v
Given one time it is identical to -x verbose=2. This option can
be given multiple times with increasing effect. (Implementation
extension option).
-v is level 2, -vv is level 3,... etc.
level 0: silent on stdout and stderr.
level 1: fatal and warning messages to stderr.
-v level 2: level 1 plus a progress bar.
-vv level 3: level 2 plus script stderr.
-vvv level 4: level 3 plus events.
-vvvv level 5: level 4 plus events.
-vvvvv level 6: level 5 plus set shell -vx option.
-vvvvvv level 7 and higher: level 6 plus debugging messages.
--version, -V
Show version (Implementation extension)
--help
Show help (Implementation extension)
-W option[,option,...]
Specify the implementation extension option.
Syntax: -W option[=option_argument[,option...]
Options may be separated by a comma. The implementation exten-
sion options may also be given individually using the '--long-
option[=option_arg]' syntax.
-W preview-tar-file=FILE
This is a testing/development option. Writes the fileset
archive to FILE. This is the same data stream that would have
been loaded on the target. This option should only be used with
the '-p' option. The output sent to FILE is a tar archive but
without trailer blocks.
-W remote-shell=NAME
Defaults File Option: swbis_remote_shell_client
This is the remote connection client program on the management
(originating host). The path NAME may be an absolute path (not
located in $PATH). The basename of NAME is used for intermedi-
ate hops. Supported shells are "ssh" and "rsh". The default is
"ssh".
-W quiet-progress
Defaults File Option: swbis_quiet_progress_bar Disable progress
bar, which is active for verbose levels 2 and higher (i.e. -v).
-W show-options-files
Show the complete list of options files and if they are found.
-W show-options
Show the options after reading the files and parsing the command
line options.
-W pax-command={tar|pax|star|gtar}
Set the portable archive command for all operations. The
default is "pax".
-W pax-read-command={tar|pax|star|gtar}
Set the read command for local and remote hosts.
-W remote-pax-read-command={tar|pax|star|gtar}
Defaults File Option: swbis_remote_pax_read_command
Set the read command for remote hosts. This is the command that
runs on the target (e.g. pax -r, tar xpf -). The default is
"pax".
-W local-pax-read-command={tar|pax|star|gtar}
Defaults File Option: swbis_local_pax_read_command
Set the read command for local hosts. This is the command that
runs on the target (e.g. pax -r, tar xpf -). The default is
"pax".
-W pax-write-command={tar|pax|star|gtar|swbistar}
Set the write command for local and remote hosts. This is the
command that runs on the target (e.g. pax -w, tar cf -).
-W remote-pax-write-command={tar|pax|star|gtar|swbistar}
Defaults File Option: swbis_remote_pax_write_command
Set the write command for remote hosts.
-W local-pax-write-command={tar|pax|star|gtar|swbistar}
Defaults File Option: swbis_local_pax_write_command
Set the portable archive write command for local host opera-
tions. This is the command that runs on the source (e.g. pax
-w, tar cf -). The default is "pax".
-W remote-pax-write-command={tar|pax|star|gtar|swbistar}
Defaults File Option: swbis_remote_pax_write_command
Set the portable archive write command for remote host opera-
tions. This is the command that runs on the source (e.g. pax
-w, tar cf -). The default is "pax".
-W no-defaults
Do not read any defaults files.
-W no-remote-kill
Defaults File Option: swbis_no_remote_kill
Disables the use of a second remote connection to tear down the
first in the event of SIGINT or SIGTERM or SIGPIPE. Only has
effect if the number of ssh hops is greater than 1. A single
host remote connection (ssh hop = 1) never uses a second remote
connection.
-W no-getconf
Defaults File Option: swbis_no_getconf
Makes the remote command be '/bin/sh -s' instead of the default
-W shell-command=NAME
Defaults File Option: swbis_shell_command
This is the interactive shell on the target host. NAME may be
one of "bash", "sh", "ksh" or "posix" and specifies the remote
command run by the remote shell. "posix" is 'PATH=`getconf
PATH` sh -s', "bash" is "/bin/bash -s", "sh" is "/bin/sh -s",
and "ksh" is "ksh -s". The default is "posix".
-W use-getconf
Opposite of --no-getconf.
-W allow-rpm
Defaults File Option: swbis_allow_rpm
Enable automatic detection, translation to Posix format, and
installation of RPMs.
-W pump-delay1=NANOSECONDS
Adds a NANOSECONDS delay (999999999 nanoseconds ~ 1 second)
every ADJSIZE bytes in the file data byte pump. A delay of
10111000 nanoseconds (~1/100th second) is added for 2-hop or
greater target (i.e more than 1 remote host in the target spec).
This is a work around for a bug in OpenSSH [or Linux kernel]
that is seen for multi-hop installs where the intermediate host
is a Linux kernel. If 2-hop install fails, try it again, you
may get lucky, or, increase this delay, or, use ssh protocol
version 1 by using ''--ssh-options=1'', or try a 2-hop install
where the middle host is BSD. To disable delay for multi-hop
targets specify zero. For more information about this bug see
the README file from the source distribution.
-W burst-adjust=ADJSIZE
ADJSIZE is the pumped data size, in bytes, between the NANOSEC-
ONDS delays. This is a work around for a bug in OpenSSH or the
Linux kernel that is seen for multi-hop installs where the
intermediate host is a Linux kernel. The default is 72000 for
2-hops or greater, and zero for single hop and localhost
installs.
-W ssh-options=OPTIONS
ssh client program options. For example -W ssh-options=1 sets
the
-W source-script-name=NAME
Write the script that is written into the remote shell's stdin
to NAME. This is useful for debugging.
-W target-script-name=NAME
Write the script that is written into the remote shell's stdin
to NAME. This is useful for debugging.
software_selections
Refer to the software objects (products, filesets) on which to
be operated. (Not implemented). The implementation defined
behavior for no selections is to operate on the entire distribu-
tion.
target
Refers to the software_collection where the software selections
are to be applied. Allows specification of host and pathname
where the software collection is to be located. A target that
contains only one part is assumed to be a hostname. To force
interpretation as a path, use an absolute path or prefix with
':'. The default target path for 'swinstall' is always '/'.
Source and Target Specification and Logic
Synopsis:
Posix:
host[:path]
host
host:
/path # Absolute path
Swbis Implementation Extension:
- # This means write the payload to stdout
[user@]host[:path]
:path # Relative or absolute path
Swbis Multi-hop Target Implementation Extension:
# '@@' is the target delimiter
target@@target[@@targetN...]
[user@]host[@@[user@]host[@@...]][:path]
A more formal description:
target : HOST_CHARACTER_STRING ':' PATHNAME_CHARACTER_STRING
| HOST_CHARACTER_STRING ':'
| HOST_CHARACTER_STRING
| PATHNAME_CHARACTER_STRING
| ':' PATHNAME_CHARACTER_STRING # Impl extension
;
PATHNAME_CHARACTER_STRING must be an absolute path unless
a HOST_CHARACTER_STRING is given. Allowing
a relative path is a feature of the swbis
implementation.
NOTE: A '.' as a target is an implementation
extension and means extract in current
directory.
NOTE: A '-' indicating stdout/stdin is an
implementation extension.
NOTE: A ':' in the first character indicates a filename.
This is an implementation extension.
HOST_CHARACTER_STRING is an IP or hostname.
Examples:
Translate your RPM on stdin to a tar archive on stdout
containing the RPM payload.
swinstall -s - @- | tar tvf -
Install the distribution /var/tmp/foo.tar.gz to the
root '/' directory at 192.168.1.10 :
swinstall -s /var/tmp/foo.tar.gz @192.168.1.10
NOTE: For swinstall, '/' is the hard coded default
target directory.
Install the distribution /var/tmp/foo.tar.gz to the
home directory of the login user at 192.168.1.10 :
swinstall -s /var/tmp/foo.tar.gz @192.168.1.10:.
Implementation Extension Syntax (multi ssh-hop) :
Syntax:
%start wtarget # the Implementation Extension Target
wtarget : wtarget DELIM sshtarget
| sshtarget
;
sshtarget : user '@' target # Note: only the last target
| target # may have a PATHNAME
;
target : HOST_CHARACTER_STRING
| HOST_CHARACTER_STRING ':' PATHNAME_CHARACTER_STRING
;
user : PORTABLE_CHARACTER_STRING # The user name
DELIM : '@@' # The multi-hop delimiter.
;
** As of 2004-02-12 the form and features of the catalog are under
active development. **
The form or format of an installed software catalog is not specified by
the ISO/IEC spec although it does specify an interface to it (e.g.
swlist utility) and operations on it.
This implementation creates a de-facto installed software catalog
rooted at the file system path specified by the value of the and direc-
tories.
CATALOG FILE LAYOUT
<path>/
<path>/<ISC>/
<path>/<ISC>/<bundle>/
<path>/<ISC>/<bundle>/<product>/
<path>/<ISC>/<bundle>/<product>/<pr>/
<path>/<ISC>/<bundle>/<product>/<pr>/<seqence_number>/
<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/export/
<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/export/catalog.tar
<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/export/catalog.tar.sig
<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/export/catalog.tar.sig<N>
<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/INSTALLED
<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/control.sh
<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/session_options
<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/vendor_tag
<path> is the target path. <ISC> is the value of the installed_soft-
ware_cataglog extended option. <bundle> and <product> are bundle and
product tags. If there is no bundle in the distribution the product
tag is used. <pr> is the product revision. Other items are explained
below.
CATALOG LOCATION
/<path>/
/<path>/<installed_software_catalog>/
/<path>/<installed_software_catalog>/...
* Root or Alternate Root
/<path>/
<path>/ is the target path specified in the target syntax. By default
"/".
* Catalog Relative Root Directory
/<path>/
/<path>/<installed_software_catalog>/
<installed_software_catalog>/ is the value of the extended option by
the same name. By default "var/lib/swbis/catalog".
PACKAGE CATALOG RELATIVE ROOT
/<{bundle|prod}.tag>/<prod.tag>/<prod.revision>/...
In other words, if 'product' and 'bundle' refers to tags, and prod-
uct_revision is the value of the product.revision attribute then the
path segment is:
/bundle/product/product_revision
CATALOG SEQUENCE NUMBER
/<sequence_number>/
/<sequence_number>/...
sequence_number is a decimal integer starting with '0'. It is chosen
by swinstall to be unique at the time of installation.
CATALOG CONTENTS
<sequence_number>/
<sequence_number>/export/
<sequence_number>/export/catalog.tar
<sequence_number>/export/catalog.tar.sig
<sequence_number>/INSTALLED
<sequence_number>/control.sh
<sequence_number>/session_options
<sequence_number>/vendor_tag
The export directory
export/
export/...
export/catalog.tar
export/catalog.tar.sig
export/catalog.tar.sig2
...
export/catalog.tar.sigN
The export/ is a file system directory and its name is constant for all
packages and is unique to the swbis implementation. The export/cata-
log.tar file is the signed file from the Posix distribution. The
export/catalog.tar.sig file is the signature file from the distribu-
tion. If there is more than one signature, then it is the last one.
export/catalog.tar.sig2 is the next to last signature, and export/cata-
log.tar.sigN is the first one, where N is the total number of signa-
tures.
INSTALLED -- The state metadata file
<sequence_number>/INSTALLED
The INSTALLED file is similar to an INDEX file in its grammar and syn-
tax. Unlike an INDEX file, it may contain control_file definitions.
The INSTALLED file stores the control script return codes and fileset
installation state. It is updated several times during the operation
of 'swinstall'. It can be parsed using libexec/swbisparse and the
'--installed' option.
control.sh -- The master control script
<sequence_number>/control.sh
SYNOPSIS: control.sh tag_spec script_tag
The control.sh file is a Posix shell script that is automatically gen-
erated by swinstall. It provides a common interface for control script
execution. Its primary purpose is to set up the script's execution
environment and map script tags to the control script pathnames. It
assumes that 'export/catalog.tar' is unpacked in export/.
session_options -- The extended options
<sequence_number>/session_options
This file contains the extended options in a form that may be executed
by the shell '.' (dot) command. It is automatically generated by swin-
stall. The value of the SW_SESSION_OPTIONS environment variable is the
absolute pathname of the this file.
EXAMPLE CATALOG ENTRY
Below is an example entry of the catalog created by swbis version
0.405. In this example, the target path is '/mnt/test', the
installed_software_catalog is '/var/lib/swbis/catalog/', the bundle tag
is 'foobare', the product tag is 'foobare-doc', and the product revi-
sion attribute is '0.902'.
/mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/export
/mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/export/catalog.tar
/mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/export/catalog.tar.sig
/mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/INSTALLED
/mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/control.sh
/mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/vendor_tag
/mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/session_options
Although swinstall does not depend on the file name as this accommo-
dates installing from standard input, a typical name for this package
would be:
foobare-doc-0.902-sl04.tar.gz
where 'sl04' is the vendor tag.
Software Specification Targets
A dash '-' is supported and means stdout or stdin. Operations with
stdout and stdin on a remote host is not supported.
A decimal '.' is supported and means the current directory. This is
supported for remote and non-remote targets. If the source is standard
input, the distribution will be unpacked (e.g. pax -r) in the directory
'.'. If the source is a regular file then a regular file in '.' will
be created with the same name.
RPM Translation
RPM (RedHat Package Manager) format packages are installed by first
translating to an equivalent ISO/IEEE file layout in Posix tar format
and then installing as a Posix package. This translation and detection
is transparent to the user if the ''--allow-rpm'' option is set in the
command line args or the swbis_allow_rpm is set to "true" by the
defaults files, otherwise an error occurs.
Since translation is done on the local (management) host, RPM is not
required on the remote (target) host.
The translation is (internally) equivalent to :
cat your-0.0-1.bin.rpm |
/usr/lib/swbis/lxpsf --psf-form2 -H ustar |
swpackage -W source=- -s @PSF | swinstall -s - @/
Testing with RPM
To test the swbis components, a completely independent means to
install and verify a package is needed. RPM provides this means and
can be used in the following way:
rpm -i --nodeps --force your-0.0-1.i386.rpm # Install
rpm --verify --nodeps your-0.0-1 # Show that all is well
rpm -e --nodeps your-0.0-1 # Remove it.
rpm -i --nodeps --justdb your-0.0-1.i386.rpm # Install just the database.
rpm --verify --nodeps your-0.0-1 # Shows the files are missing.
swinstall --allow-rpm -s - < your-0.0-1.i386.rpm
rpm --verify --nodeps your-0.0-1 # Show that all is well again
Extended options can be specified on the command line using the -x
option or from the defaults file, swdefaults. Shown below is an actual
portion of a defaults file which show default values.
Posix
These options are set in the /usr/lib/swbis/swdefaults or the ~/.swde-
faults
allow_downdate = false # Not Implemented
allow_incompatible = false # Not Implemented
ask = false # Not Implemented
autoreboot = false # Not Implemented
autorecover = false # Not Implemented
autoselect_dependencies = false # Not Implemented
defer_configure = false # Not Implemented
distribution_source_directory = - # Stdin
enforce_dependencies = false # Not Implemented
enforce_locatable = false # Not Implemented
enforce_scripts = false # Not Implemented
enforce_dsa = false # Not Implemented
installed_software_catalog = var/lib/swbis/catalog
logfile = /var/lib/sw/swinstall.log #Not Implemented
loglevel = 0 # Not Implemented
reinstall = false # Not Implemented
select_local = false # Not Implemented
verbose = 1
Swbis Implementation
These options are set in the /usr/lib/swbis/swbisdefaults or the
${HOME}/.swbis/swbisdefaults file.
swinstall.swbis_no_getconf = false # true or false
swinstall.swbis_shell_command = posix # {sh|bash|posix}
swinstall.swbis_no_remote_kill = false # true or false
swinstall.swbis_no_audit = false # true or false
swinstall.swbis_quiet_progress_bar = false # true or false
swinstall.swbis_local_pax_write_command=pax #{pax|tar|star|gtar}
swinstall.swbis_remote_pax_write_command=pax #{pax|tar|star|gtar}
swinstall.swbis_local_pax_read_command=pax #{pax|tar|gtar|star}
swinstall.swbis_remote_pax_read_command=pax #{pax|tar|gtar|star}
swinstall.swbis_enforce_sig=false # true or false
swinstall.swbis_enforce_file_md5=false # true or false
swinstall.swbis_allow_rpm=false # true or false
swinstall.swbis_remote_shell_client=ssh
swinstall.swbis_install_volatile=true
swinstall.swbis_volatile_newname= #empty string, e.g. ".rpmnew"
0 if all targets succeeded, 1 if all targets failed, 2 if some targets
failed and some succeeded.
Multiple ssh-hops is an implementation extension.
swinstall requires a Posix shell accessible by the remote shell com-
mand. This is the remote command run by ssh (or rsh) for all opera-
tions. This command can be controlled by the --shell-command option or
the swbis_shell_command defaults file option. Permitted values are
"bash" (/bin/bash -s) or "sh" (/bin/sh -s) or "posix" ('PATH=`getconf
PATH` sh -s'). The default is "posix". swinstall requires the Posix
capability of reading commands on stdin according to the specification
described in IEEE Std 1003.1, 2003 Ed.; sh -shell, Section STDIN. This
requirement accommodates reading of shell program code and data on
STDIN. This capability may not be present in some /bin/sh shells. The
"/bin/sh" on FreeBSD-5.1 may be broken in this regard, hence ''--shell-
command=bash'' should be used for BSD hosts. The public domain Korn
shell (pdksh-5.2.14) seems to work OK, that is, it complies by luck or
intent with the Posix capability of reading data and code on stdin.
If the --no-getconf option is set or the swinstall.swbis_no_getconf
defaults option is "true" then the remote command is '/bin/sh -s'. Use
of the no-getconf option is needed for communication with user accounts
on remote machines whose login shell is not a Bourne shell (e.g. csh)
such as root on some default BSD installations. Other *nix systems may
require use of getconf because their /bin/sh is broken or not Posix
enough (e.g. Sun platforms). Still other systems may not have getconf.
Other utilities required to be in $PATH on the remote host are: dd, pax
(or tar|star|gtar), hostname, mkdir, expr, echo, test, sleep, read (if
not builtin).
/usr/lib/swbis/swdefaults
/usr/lib/swbis/swbisdefaults
$HOME/.swbis/swdefaults
$HOME/.swbis/swbisdefaults
ISO/IEC 15068-2:1999, Open Group CAE C701
info swbis
swcopy(8), sw(5), swbisparse(1), swign(1), swverify(8)
swinstall(8): The installation utility of the swbis project.
Author: Jim Lowe Email: jhlowe at acm.org
Version: 0.499
Last Updated: 2006-02-01
Copying: GNU Free Documentation License
swinstall is subject to breakage if a user's account on an intermediate
(or terminal) host in a target spec is not configured to use a Bourne
compatible shell. (This breakage may be eliminated by use of the --no-
getconf option as explained above.)
A multiple ssh hop source spec (more than 1 remote host involved in
the source transfer) upon a SIGINT may result in sshd and ssh processes
being left on on the intermediate host(s), this despite, swinstall's
action of sending a SIGTERM to the remote script's parent process.
swinstall does not currently implement Software Selections, not fileset
dependencies, and much more. Only packages with one product and one
fileset are supported.
swinstall(8)
[ Index ] [ Back ]