This manual is for swbis (version 0.951, 01 Dec 2007), which is a implementation of the POSIX System Administration – Part 2: Software Administration conforming to IEEE Std 1387.2-1995 (ISO/IEC 15068-2) and Open Group CAE C701. Currently, not all of the standard is implemented. There are extensions for package authentication. Extensions to the standard are indicated as such in this document.
Copyright © 2005, 2006 James H. Lowe, Jr.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being “A GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License.”(a) The FSF's Back-Cover Text is: “You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development.”
The first step in package signing is to obtain GNU Privacy Guard and its command line program gpg. The next step is to invoke it directly to test your gpg configuration. The gpg program is invoked by swpackage with the following options:
gpg --no-tty --no-secmem-warning --armor --passphrase-fd 3 -sb -o -
The --passphrase-fd and --no-tty options would not be used if running the gpg utility from the command line. The option swpackage --gpg-name option maps to gpg --local-user option and the swpackage --gpg-path option maps to gpg --homedir option. The default id to sign and home directory depends on gpg's defaults, the default home directory is is usually ~/.gnupg.
If you experience difficulty signing a test file using gpg then consult the gpg manual, since configuring gpg is outside the scope of swbis.
Once you know swpackage works without signing enabled simply invoke it with the additional option --sign and possibly --gpg-name=YOUR_ID and --gpg-path=PATH. swpackage should ask for your passphrase. Note that the --sign turns on --archive-digests automatically since a package is not fully verifiable without archive digests.
Other swpackage options you may which to use are --files and --file-digests.
For example:
swpackage -Wsign,files,gpg-name="Test User" -s PSF @- >/dev/null
There are defaults file options which can be set to your preferences. The command line options always override the the defaults file settings.
swpackage.swbis_file_digests = "true" # true or false
swpackage.swbis_files = "false" # true or false
swpackage.swbis_sign = "false" # true or false
swpackage.swbis_gpg_name =
swpackage.swbis_gpg_path = "~/.gnupg"
swpackage.swbis_signer_pgm = "GPG"
In addition, signed packages can be created using the ad-hoc extension utility swign. It was designed especially to create signed POSIX packages of free software source packages.
The operational constraints for using swign are that every file in the current directory is packaged, all files have the same ownerships, the archive will have a single leading package directory equal to the current directory name, and the package will contain the catalog directory. Other than the additional catalog directory, the package can be identical to the non-POSIX package created with tar.
swign is designed to be fail safe. swign uses swpackage and GNU tar as tools in a fashion such that all data copied to the user is generated by GNU tar from a file list generated by swpackage. Therefore, there is no chance the archive is corrupt, and because of sanity checks on the file list using existing GNU file system utilities, little to no chance of missing data.
swign requires GNU tar version 1.13.25 or 1.14 or 1.15.x. Using a version other than these will produce a valid archive, but the signature may not be valid.
swign packages all the files in the current directory, makes the path name prefix the name of the current directory, and all the files will have the same ownerships. These constraints are suited to GNU and Unix free software source packages.
Creating a signed package with swign is easy. Just change directory to the directory you want to archive, verify the documented side-effect of removing and replacing a directory name catalog is not a problem. If your directory has a file named catalog (that is not a POSIX exported catalog) that belongs to your data set you must rename it. For better or worse 'catalog' is a keyname of the POSIX standard.
Then type:
swign -o 0 -o 0 --show-psf
-or-
swign --show-psf
to show the internally PSF to stdout. It tries to make a reasonable PSF
using the name of the current directory. You can supply you own PSF from
a file or on standard input like this
swign -o 0 -o 0 --show-psf | swign -s - --show-psf
Now, make a package for real.
swign -o 0 -o 0 --show-psf | swign -u "My GPG Name" @- >../my_new_signed_tarball
swign writes to stdout.
You must redirect the archive to a more useful file.
You could verify it like this:
swign -u "My GPG Name" @- | swverify -d @-
-or like this-
swverify -d @:../my_new_signed_tarball
If a checkdigest script is included then you should unpack the package at a new location and run 'swverify –checksig "."' in the new location. See Providing a checkdigest script.
Creating a signed directory is actually the first step that swign does when creating a signed archive. Using the -S simply causes swign to exit early.
Aside:
This feature exposes a regression test constraint, namely
that the byte stream generated by 'swpackage' and installed
by 'tar' is identical to the byte stream generated by GNU 'tar'
from the newly installed 'catalog' directory.
To sign the directory, and then verify it:
swign -S; swverify -d @.
This produces the output:
swign: Generating the catalog and installing with tar...
swpackage: Warning: exclude definition source [catalog] does not exist.
Enter Password:
swverify: GPG signature verified.
swverify: checkdigest script not found
swverify: Package authenticity not confirmed.
For more information about the 'checkdigest' script:
See (swbis_swverify)IMPLEMENTATION EXTENSION DISTRIBUTOR SCRIPTS, and
See (swbis_swverify)Verifying the Directory Form of a Distribution.
Swign can be used to sign any directory using the file ownerships of the source files. The following commands act as a test of swpackage's ability to generate an archive identical to GNU tar. (Note: checkdigest.sh is found in ./bin of the source distribution.)
swign -D $HOME/checkdigest.sh -u "Test User" -o "" -g "" -S;
swverify -d @.
swverify is affected by the following environment variables: SWPACKAGEPASSFD, SWPACKAGEPASSPHRASE, GNUPGHOME, and GNUPGNAME. For more information: (See (swbis_swpackage)ENVIRONMENT.)
The checkdigest script is a distributor extension script. Only the swbis implementation of swverify knows how to use it. An example file is found in the swbis source package.
You need to supply a checkdigest script only if you wish your customers to be able to verify the directory form (i.e. unpacked archive) of a POSIX package. There are constraints on the usefulness of this script which are the same as when attempting to verify manually. See (swbis_swverify)Verifying a POSIX Distribution Directory Manually. It is not used when verifying the archive file form. Also, since it should only use non-swbis standard GNU tools and is a shell script, it does not do anything that the end user could not do themselves.
The script is included in the package one of two ways: using the -D option of the swign command or by specifying in a PSF to be processed by swpackage. The syntax for referencing from a PSF is:
checkdigest < /path/name/to/your/checkdigest.sh
This line should be added in the distribution object of the PSF.
Here is a target to put in your Makefile.am (This example was tested with Automake version 1.9):
# Provide am__remove_distdir ourselves since am__remove_distdir may be a
# private automake variable.
sw_am__remove_distdir = \
{ test ! -d $(distdir) \
|| { find $(distdir) -type d ! -perm -200 -exec chmod u+w {} ';' \
&& rm -fr $(distdir); }; }
dist-swbis: distdir
(cd $(distdir) && swign -s PSF.in --name-version=$(distdir) @-) | GZIP=$(GZIP_ENV) gzip -c >$(distdir).tar.gz
$(sw_am__remove_distdir)
An example invocation using the environment controls:
(SWPACKAGEPASSFD="agent"; GNUPGNAME="Your Name"; make dist-swbis)
The PSF.in should employ the replacement strings '%__tag' and '%__revision' as in this example PSF.in (See (swbis_swign)SAMPLE SOURCE PACKAGE PSF).
In summary, alot is working and alot is not.
swpackage is the most complete utility. It implements all of the ISO/IEC 15068-2 features of the Product Specification File, the input file of swpackage.
swpackage can create POSIX tar archives with a POSIX file layout with an embedded GPG signature and payload digest (md5 and sha1). This capability is mature and safe, but for those who are paranoid about using a new tool to create archives of your data, there is swign. swign signs the current working directory, presumably a directory containing your source tree, and then uses tar to emit the archive. The result is a package, created by GNU tar, which looks like a source tar archive with a leading directory. The archive has the ./catalog/ directory which contains the package metadata, GPG signature and digests which are stored as separate regular files, and as ascii text of course.
swinstall is usable though missing some Posix features. Control script execution is implemented for checkinstall, preinstall, and postinstall. Dependency checks are not implemented. Only packages with one product and one fileset are supported. swinstall can install RPM packages on/to hosts that have neither rpm nor swinstall.
swcopy is usable though missing lots of POSIX capability. It can be used to translate an RPM to a POSIX package with a single path name prefix. It can unpack and copy archives from host to host.
swverify is usable though missing lots of POSIX capability. It most stable feature is verifying signed tar archives (i.e. packages signed according to how GNU swpackage does it). The ability to verify the GPG signature and file metadata of installed software (as opposed to the compressed tarball) is a work in progress.
Below is more detail about current capabilities.
Command: swinstall
swinstall is missing many features but it is useful for packages with a single fileset and product and if control script execution is not required. It can install RPMs to the local or a remote host (but the postinst script will not be executed.)
Command: swcopy
swcopy is missing many features specified in the POSIX spec. Several degenerative basic features work and can be useful. It can unpack compressed tar archives handling compression transparently. It can copy directories from host to host. It can be used as a copying tool for arbitrary data, however this is not its intended application. Unfortunately, many of its intended uses don't work yet.
Command: swinstall or swcopy
swcopy can translate RPMs to a tar archive. This is useful for installing the contents of a source RPM into a single directory.
swinstall can install a RPM as a POSIX package (i.e by translating first).
Command: swpackage
swpackage is at a beta release level. It supports all Product Specification File (PSF) features in the IEEE spec.
Command: swverify
swverify is used to verify the payload digests and GPG signature (if any) of a POSIX package (i.e. tar archive in POSIX format). Currently, swverify does not completely implement verification of installed software.
Command: swign
swign is a ad-hoc implementation extension utility.
swign is used to create a GPG signed POSIX package from the contents of the current directory. The intended use is for creation of signed source tar archives.
It is a shell script that uses swpackage and gpg and GNU tar. Since the created archive is written to stdout by GNU tar and makes sanity checks using standard utilities it is safe to use.
The utilities are invoked from the command line.
The commands share a common syntax that is:
<sw_utility> [options] [software_selections] [@Targets]
The current swbis utilities are swpackage, swinstall, swverify, swcopy, swign.
A central element of all the commands is the target syntax. See Target Syntax.
Here are several rules worth remembering about the Target:
If the target path is not given for a remote target, the target path is either '.' or '/' depending on the utility and the defaults files. (The default target path for swinstall is always '/')
Here are several example of Targets:
@ root@host1
@ root@host1@@guest@host2:/tmp/mnt/test
@ user@host1:.
@ :file1 # Impl Extension
The command swbis can be used to invoke the swbis utilities. The swbis command is useful if the utilities are not installed in $PATH. Alternatively, individual utilities can be invoked by themselves.
Here are some example invocations:
swbis --version
swbis --help
swpackage --sign --gpg-name="Your GPG Identity" --format=ustar -s /tmp/mypsf >/tmp/foo.tar
swverify -d @/tmp/foo.tar
swinstall -s -
swcopy -s /tmp/myrpm.rpm --audit --allow-rpm @- | tar tvf -
swign -u "Your GPG Identity" @- | tar tvf -
Source and Target Specification and Logic
Synopsis:
Posix:
host[:path]
host
host:
/path # Absolute path
Swbis Extension:
[user@]host[:path]
[user@]host_port[:path]
:path
Swbis Multi-hop Target Extension:
# ':' is the target delimiter
# '_' delimits a port number in the host field
[user@]host[@@[user@]host[@@...]][:file]
[user@]host_port[@@[user@]host[@@...]][:file]
# Using ':', a trailing colon is used to
# disambiguate between a host and file.
# For Example,
:file
host:
host
host:file
host:host:
host_port:host_port:
host:host:file
user@host:user@host:
user@host:user@host:host:
user@host:user@host:file
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:
Copy the distribution /var/tmp/foo.tar.gz at 192.168.1.10
swcopy -s /var/tmp/foo.tar.gz @192.168.1.10:/root
Implementation Extension Syntax (multi ssh-hop) :
Syntax:
%start wtarget # the Implementation Extension Target
# Note: a trailing ':' forces interpretation
# as a host, not a file.
wtarget : wtarget DELIM sshtarget
| sshtarget
| sshtarget DELIM
;
sshtarget : user '@' target # Note: only the last target
| target # may have a PATHNAME, and only a host
; * may have a user
target : HOST_CHARACTER_STRING
| PATHNAME_CHARACTER_STRING
;
user : PORTABLE_CHARACTER_STRING # The user name
DELIM : ':' # The multi-hop delimiter.
;
Copyright © 2000,2001,2002 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ascii without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.
A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (C) year your name.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with...Texts.” line with this:
with the Invariant Sections being list their titles, with
the Front-Cover Texts being list, and with the Back-Cover Texts
being list.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.
The related standards are IEEE Std 1387.2-1995 (ISO/IEC 15068-2:1999), OpenGroup CAE C701.
ISO/IEC 15068-2:1999 is identical to 1387.2 except for its name.
CAE C701 is nearly identical to 1387.2 and can be viewed online at http://www.opengroup.org/publications/catalog/c701.htm
The implementation reference specification is a printed postscript rendering of the C701 pdf file available at http://www.opengroup.org/publications/catalog/c701.htm (size: 696095 bytes; md5sum: a98e5fd7d723db63e27136c70bfff7aa) and a copy of IEEE Std 1387.2-1995 (ISBN 1-55937-537-X). These two documents match up line-for-line except for chapter ordering and where there are descriptions of C701's additional attributes.
(The IEEE standard is superseded by and identical to ISO/IEC 15068-2:1999).
Commands
Formats
swpackage(8) swpackage(8)
NAME
swpackage — Package a software distribution.
SYNOPSIS
swpackage # Filter: read PSF on stdin, write a tar archive to stdout
swpackage [-p] [-s psf_file] [-f file] [-x option=value] \
[-X options_file] [-W option] [software_selections] [@targets]
swpackage [options] --to-swbis [-s package_file] # format translator
DESCRIPTION
swpackage reads a Product Specification File (PSF) and writes a dis-
tribution to the specified target. If no options are given a PSF is
read on stdin and a distribution is written to the default target
either a directory, device, or standard output. To specify standard
output use a dash ’-’ as the target. This implementation only sup-
ports writing to stdout.
OPTIONS
software_selections
Refer to the software objects (products, filesets) on which to
be operated. (Not yet implemented)
targets
Refers to the software_collection where the software selections
are to be applied. To specify standard output use a dash ’-’,
this overrides media_type setting to ’serial’. Target may be a
file system directory, or device file or ’-’ Currently this
implementation only supports a serial archive written to std-
out.
-f FILE
Reads software_selections from FILE. (Not implemented).
-p
Preview the package. Perform all the packaging operations
except writing the target. In verbose level 1, nothing is
written. Higher verbose levels write information on stdout.
Error and warning messages are written to stderr for verbose
levels 1 and higher.
-s PSF
Specify the PSF file, "-" is standard input.
-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
(Implementation extension.) Given one time it is identical to
-x verbose=2. This option can be given multiple times with
increasing effect.
level 0: silent on stdout and stderr (not implemented).
level 1: fatal and warning messages.
-v level 2: level 1 plus file list and trailer message.
-vv level 3: level 2 verbose tar-like listing.
-vvv level 4: level 3 extra verbose tar listing.
-b BYTES
Set blocksize to BYTES number of bytes (octets). The default
is 10240. (implementation extension)
--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 cksum
Compute POSIX cksum of the individual files.
-W file-digests -W digests
Compute md5 digests of the individual files. (-W digests is
deprecated, use -W file-digests).
-W files
Store the distribution file list in .../dfiles/files.
-W dir=NAME
Use NAME as the path name prefix of a distribution and also as
the value of the distribution.control_directory and distribu-
tion.tag attribute (if not set). May be set to an empty string
to eliminate stray leading "./".
-W sign
Compute the md5sum, sha1sum and adjunct_md5sum digests and sign
the package.
-W dummy-sign
Same as -W sign except use a dummy signature. The signer pro-
gram is not run and no password is required.
-W signer-pgm=SIGNER
Recognized SIGNERs are GPG, PGP2.6, and PGP5. swverify only
supports GPG, however, other types can be verified manually
using the options of swverify and command line utilities.
-W archive-digests
Compute the md5sum, sha1sum and adjunct_md5sum digests. See
sw(5) for info on the digest and signed data input files. The
sha1sum and md5sum attributes have identical input streams.
-W no-sha1
Do not compute the sha1 digest even if directed to by other
options. (Deprecated: There is limited reason to use this
option).
-W signed-file
Write only the signed data to the specified target but do not
sign. (Deprecated: There is limited reason to use this
option).
-W gpg-name=NAME
Use NAME as the user ID to sign. NAME becomes the option arg
of the gpg --local-user option.
-W gpg-path=PATH
Use PATH as the gpg homedir.
-W gzip
compress output with file system gzip utilty
-W bzip2
compress output with file system bzip2 utility
-W source=FILE
Use serial archive located at FILE as the source instead of the
file system. The files referred by the PSF are taken from the
serial archive and not the file system.
-W numeric-owner
Same as GNU tar option. Emitted archive has only uid and gids.
-W absolute-names
Same as GNU tar option. Leading slash ’/’ are always stripped
unless this option is given.
-W format=FORMAT
FORMAT is one of:
ustar is the POSIX.1 tar format capable of storing
pathnames up to 255 characters in length.
Identical to GNU tar 1.15.1 --format=ustar
This is the default format but may be changed by
the options files.
ustar0 is a different POSIX.1 tar personality.
Identical to GNU tar 1.13.25 --posix -b1 for 99 char pathnames
Has different rendering of device numbers for non-device files,
but otherwise identical to ’ustar’
gnu Identical to GNU tar version 1.15.1 --format=gnu
oldgnu Identical to GNU tar version 1.13 and later with
block size set to 1. i.e. with option -b1.
Also identical to GNU tar 1.15.1 --format=oldgnu
gnutar same as oldgnu, oldgnu preferred.
pax Extended header tar (Not implemented).
odc Posix.1 cpio (magic 070707).
newc cpio format (magic 070701).
crc cpio format (magic 070702).
bsdpax3 Identical to pax v3.0, ustar format with option -b 512.
-W create-time=TIME
Applies to catalog files and the create_time attribute. TIME
is the seconds since the Unix Epoch. You must use this option
to make the catalog directory identical in subsequent invoca-
tions.
-W list-psf
Write the PSF to stdout after having processed the extended
definitions.
-W to-swbis
Read a package on standard input and write a POSIX package on
standard output. Requires the .../libexec/swbis/lxpsf program.
Supported formats are any supported format of lxpsf. Identical
to:
/swbis/lxpsf --psf-form3 -H ustar | swpackage -Wsource=- -s@PSF
-W passphrase-fd=N
Read the passphrase on file descriptor N.
-W passfile=FILE
Read the passphrase from FILE in the file system. Setting FILE
to /dev/tty resets (i.e unsets) all passphrase directives, thus
establishing the default action, reading from the terminal.
-W dir-owner=OWNER
Set the owner of the leading directory archive member to OWNER.
If the option arg is "", then the owner is the owner of the
current directory.
-W dir-group=OWNER
Set the group of the leading directory archive member to OWNER.
If the option arg is "", then the owner is the owner of the
current directory.
-W dir-modep=MODE
Set the file permissions mode of the leading directory archive
member to MODE.
-W catalog-owner=OWNER
Set the owner of the catalog section to OWNER.
-W catalog-group=GROUP
Set the group of the catalog section to GROUP.
-W files-from=NAME
Read a list of files from file NAME. Directories are not
descended recursively.
-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 com-
mand line options.
-W no-catalog
Do not write the catalog section.
-W no-front-dir
Do not write the directory archive members that preceed the
catalog section.
EXTENDED OPTIONS
These extended options can be specified on the command line using the
-x option or from the defaults file, swdefaults.
Posix
Shown below is an actual portion of a defaults file which show default
values. These options are set in the /usr/lib/swbis/swdefaults or the
~/.swdefaults file.
swpackage.distribution_target_directory = /var/spool/sw # Not used
swpackage.distribution_target_serial = - # Not used
swpackage.enforce_dsa = false # Not used
swpackage.follow_symlinks = false # Not used
swpackage.logfile = /var/lib/swbis/swpackage.log # Not used
swpackage.loglevel = 1 # Not used
swpackage.media_capacity = 0 # Not used
swpackage.media_type = serial # Not used
swpackage.psf_source_file = - # Not used
swpackage.software = # Not used
swpackage.verbose = 1 # May be 1 2 or 3
Swbis Implementation
These extended options can be specified on the command line using
-Woption=optionarg or --option=optionarg syntax.
These options are set in the /usr/lib/swbis/swbisdefaults or the
~/.swbis/swbisdefaults file.
swpackage.swbis_cksum = "false" # true or false
swpackage.swbis_file_digests = "false" # true or false
swpackage.swbis_file_digests_sha2 = "false" # true or false
swpackage.swbis_files = "false" # true or false
swpackage.swbis_sign = "false" # true or false
swpackage.swbis_archive_digests = "false" # true or false
swpackage.swbis_archive_digests_sha2 = "false" # true or false
swpackage.swbis_gpg_name = ""
swpackage.swbis_gpg_path = "~/.gnupg"
swpackage.swbis_gzip = "false" # true or false
swpackage.swbis_bzip2 = "false" # true or false
swpackage.swbis_numeric_owner = "false" # true or false
swpackage.swbis_absolute_names = "false" # true or false
swpackage.swbis_format = "ustar" # gnutar or ustar
swpackage.swbis_signer_pgm = "GPG" # GPG or PGP5 or PGP2.6
PACKAGE SIGNING
Support for embedded cryptographic signature.
Description
Package signing is accomplished by including, as a package attribute,
a detached signature in the package metadata (the catalog section of
the package). The signed data is the catalog section of the package
(see sw(5) for a description) excluding the signature files archive
header and data. The package leading directory that does not contain
the /catalog/ directory in its name is not included in the signed
stream. The signed stream is terminated by two (2) null tar blocks
(which are not in the actual package file). The storage section (or
payload) of the package is included in the signed data by computing
its md5 and sha1 message digests and storing these as attributes in
the catalog section.
Signature Generation
The signature is generated by the file system signing utility. Cur-
rently, swpackage supports GPG PGP-2.6 and PGP-5. The default is GPG
but can be selected using the -Wsigner-pgm command line option and the
swpackage.swbis_signer_pgm defaults file option. The options and pro-
gram can the displayed with the -Wshow-signer-pgm option. The options
in each case produce a detached ascii-armored signature. The maximum
length for the ascii armored file is 1023 bytes.
Passphrase Handling
The passphrase can be read from the tty, a file descriptor, and envi-
ronment variable or the GNUpg passphrase agent. These are controlled
by the options or the environment variables SWPACKAGEPASSFD and
SWPACKAGEPASSPHRASE. Placing your passphrase in an environment vari-
able is insecure but may be usefull to sign packages with a test key
and later replace it [when on a different host for example].
SIGNATURE VERIFICATION
swpackage does not perform verification of the embedded cryptographic
signature, although, a description is included here for completness.
Overview
Verification requires verifying the payload section md5 and sha1 mes-
sage digests and then verifying the signature. Naturally, it is
required that the signed data include the payload messages digests.
See swverify.
Manual Verification
Verification requires re-creating the signed and digested byte streams
from the archive file. This is not possible using any known extant
tar reading utility because of a lack of ability to write selected
archive members to stdout instead of installing in the file system;
however, the swverify utility can be used to write these bytes streams
to stdout allowing manual inspection and verification. See swverify.
Manual Verification Using Standard Tools
Verification using standard GNU/Linux tools is possible if the archive
is installed in the file system. Success depends on the following
factors:
1) The tar utility preserves modification times
(e.g. not GNU tar 1.3.19).
2) The archive does not contain Symbolic Links
(see sw(5) for explanation).
3) The file system is a Unix file system (e.g. ext2).
4) The package was created using -Wformat=gnutar or, -Wformat=ustar
with no file name longer than 99 octets.
Recreating the signed and digested byte streams is then accomplished
using GNU tar and the file list stored in the <path>/cata-
log/dfiles/files attribute file as follows:
In this example, the package has a single path name prefix called,
namedir and the file owner/group are root. These restrictions are
suited to source packages.
Verify the signature:
#!/bin/sh
tar cf - -b1 --owner=root --group=root \
--exclude=namedir/catalog/dfiles/signature \
namedir/catalog | gpg --verify namedir/catalog/dfiles/signature -
If this fails try using GNU tar option --posix. If this fails then
you are out of luck as nothing in the catalog section can be trusted.
Verify the payload digests:
#!/bin/sh
grep -v namedir/catalog namedir/catalog/dfiles/files | \
tar cf - -b1 --owner=root --group=root \
--files-from=- --no-recursion | md5sum
cat namedir/catalog/dfiles/md5sum
Likewise for the sha1 digest.
If the package has symbolic links, Verify the adjunct_md5sum:
#!/bin/sh
grep -v namedir/catalog namedir/catalog/dfiles/files | \
( while read file; do if [ ! -h $file ]; then echo $file; fi done; )|\
tar cf - -b1 --owner=root --group=root \
--files-from=- --no-recursion | md5sum
cat namedir/catalog/dfiles/adjunct_md5sum
The symbolic link files must be verified manually by comparing to the
INFO file information.
SWPACKAGE OUTPUT FORMAT
The output format is either one of two formats specified in POSIX.1
(ISO/IEC 9945-1) which are tar (header magic=ustar) or cpio (header
magic=070707). The default format of the swbis implementation is
"ustar". The POSIX spec under specifies definitions for some of the
ustar header fields. The personality of the default swbis ustar for-
mat mimics GNU tar 1.15.1 and is designed to be compliant to POSIX.1.
The personality of the "ustar0" format mimics, for pathnames less than
99 octets, GNU tar 1.13.25 using the "-b1 --posix" options. This
bit-for-bit sameness does not exist for pathnames greater than 99
chars as swbis follows the POSIX spec and GNU tar 1.13.25 does not.
The "ustar0" ustar personality is deprecated. It is only slightly
different from ’ustar’ in how device number fields are filled (with
spaces, zeros or NULs) for non-device files.
In addition the swbis implementation supports several other tar vari-
ants including bit-for-bit mimicry of GNU tar (1.13.25) default format
which uses a non-standard name split and file type (type ’L’). This
format is known as ’--format=oldgnu’. Also supported is the gnu for-
mat of GNU tar 1.15.1 specified by ’--format=gnu’
The defacto cpio formats are also supported. "new ASCII" (sometimes
called SVR4 cpio) and "crc" cpio formats with header magic "070701"
and "070702" respectively.
Support for "pax Interchange Format" (Extended header tar) described
in IEEE 1003.1-2001 under the "pax" manual page is planned.
The entirety of the output byte stream is a single valid file of one
the formats mentioned above.
The swbis implementation writes its output to stdout. The default
output block size is 10240 bytes. The last block is not padded and
therefore the last write(2) may be a short write. The selected block
size does not affect the output file contents.
The swbis implementation is biased, in terms of capability and default
settings, to the tar format. Package signing is only supported in tar
format.
SWPACKAGE INPUT FILE FORMAT
The input file is called a product specification file or PSF. It con-
tains information to direct swpackage and information that is package
meta-data [that is merely transferred unchanged into the global INDEX
file].
A PSF may contain object keywords, attributes (keyword/value pairs)
and Extended Definitions (described below). An object keyword con-
notes a logical object (i.e. software structure) supported by the
standard. An object keyword does not have a value field after it, as
it contains Attributes and Extended Definitions. An attribute keyword
conotes an attribute which is always in the form of a keyword/value
pair.
Attribute keywords not recognized by the standard are allowed and are
transferred into the INDEX file. Object keywords not recognized by
the standard are not allowed and will generate an error. Extended
Definitions may only appear in a PSF (never in a INDEX or INFO created
by swpackage). Extended Definitions are translated [by swpackage]
into object keywords (objects) and attributes recognized by the stan-
dard.
Comments in a PSF are not transferred into the INDEX file by the swbis
implementation of swpackage.
The file syntax is the same as a INDEX, or INFO file. A PSF may con-
tain all objects defined by the standard as well as extended defini-
tions.
For additional information see
XDSA C701 http://www.opengroup.org/publications/catalog/c701.htm, or
sw manual page.
EXTENDED DEFINITIONS
A Product Specification File (PSF) can contain Extended Definitions in
the fileset, product or bundle software definitions. They would have
the same level or containment relationship as a file or control_file
definition in the same contaning object.
Extended Definitions represent a minimal, expressive form for specify-
ing files and file attributes. Their use in a PSF is optional in that
an equivalent PSF can be constructed without using them, however,
their use is encouraged for the sake of brevity and orthogonality.
The swbis implementation requires that no [ordinary] attributes appear
after Extended Definitions in the containing object, and, requires
that Extended Definitions appear before logically contained objects.
That is, the parser uses the next object keyword to syntacticly and
logically terminate the current object even if the current object has
logically contained objects.
o Extended Control File Definitions
checkinstall source [path]
preinstall source [path]
postinstall source [path]
verify source [path]
fix source [path]
checkremove source [path]
preremove source [path]
postremove source [path]
configure source [path]
unconfigure source [path]
request source [path]
unpreinstall source [path]
unpostinstall source [path]
space source [path]
control_file source [path]
The source attribute defines the location in distributors’s develop-
ment system where the swpackage utility will find the script. The
keyword is the value of the tag attribute and tells the utilities when
to execute the script. The path attribute is optional and specifies
the file name in the packages distribution relative to the con-
trol_directory for software containing the script. If not given the
tag value is used as the filename.
o Directory Mapping
directory source [destination]
Applies the source attribute as the directory under which the subse-
quently listed files are located. If destination is defined it will
be used as a prefix to the path (implied) file definition. source is
typically a temporary or build location and dest is its unrealized
absolute pathname destination.
o Recursive File Definition
file *
Specifies every file in current source directory. The directory
extended definition must be used before the recursive specification.
o Explicit File Definition
file [-t type] [-m mode] [-o owner[,uid]] [-g group[,gid]] [-n] [-v] source [path]
source
source defines the pathname of the file to be used as the
source of file data and/or attributes. If it is a relative
path, then swpackage searches for this file relative to the the
source argument of the directory keyword, if set. If directory
keyword is not set then the search is relative to the current
working directory of the swpackage utility’s invocation.
All attributes for the destination file are taken from the
source file, unless a file_permissions keyword is active, or
the -m, -o, or -g options are also included in the file speci-
fication.
path
path defines the destination path where the file will be cre-
ated or installed. If it is a relative path, then the destina-
tion path of the of the directory keyword must be active and
will be used as the path prefix. If path is not specified then
source is used as the value of path and directory mapping
applied (if active).
-t type
type may one of ’d’ (directory), or ’h’ (hard link), or ’s’
(symbolic link).
-t d Create a directory.
If path is not specified source is used as the path attribute.
-t h Create a hard link.
path and source are specified. source is used as the value of
the link_source attribute, and path is the value of the path
attribute.
-t s Create a symbolic link.
path and source are specified. source is used as the value of
the link_source attribute, and path is the value of the path
attribute.
-m mode
mode defines the octal mode for the file.
o Default Permission Definition
file_permissions [-m mode] [-u umask] [-o [owner[,]][uid]] [-g [group[,]][gid]]
Applies to subsequently listed file definitions in a fileset. These
attributes will apply where the file attributes were not specified
explicitly in a file definition. Subsequent file_permissions defini-
tions simply replace previous definitions (resetting all the options).
To reset the file_permission state (i.e. turn it off) use one of the
following:
file_permissions ""
or the preferred way is
file_permissions -u 000
o Excluding Files
exclude source
Excludes a previously included file or an entire directory.
o Including Files
include <filename
The contents of filename may be more definitions for files. The syn-
tax of the included file is PSF syntax.
SWBIS PSF CONVENTIONS
This section describes attribute usage and conventions imposed by the
swbis implementation. Not all attributes are listed here. Those that
are have important effects or particular interest.
o Distribution Attributes
The standard defines a limited set of attributes for the distribution
object. An expanded set is suggested by the informative annex however
a conforming implementation is not required act on them. The reason
for this is a distribution may be acted upon by a conforming utility
in such a way that attributes of the distribution become invalid. For
this reason, some attributes that refer to an entire "package" [in
other package managers] are referred from the product object and
attain their broadened scope by the distributor’s convention that
their distribution contains just one product.
For example, the package NAME and VERSION are referred from the prod-
uct tag and revision, not the distribution’s. This convention sup-
ports multiple products in a distribution and is consistent with the
standard.
tag
tag is the short, file system friendly, name of the distribu-
tion. Providing a distribution tag is optional. The swbis
implementation will use this as the [single] path name prefix
if there is no distribution.control_directory attribute. A
distribution tag attribute and swpackage’s response to it is an
implementation extension. The leading package path can also be
controlled with the ’’-W dir’’ option.
control_directory
control_directory, in a distribution object, is the constant
leading package path. Providing this attribute is optional. A
distribution control_directory attribute and swpackage’s
response to it is an implementation extension. The leading
package path can also be controlled with the ’’-W dir’’ option.
This attribute will be generated by swpackage if not set in a
PSF.
o Bundle Attributes
A bundle defines a collection of products whether or not the distribu-
tion has all the products present.
tag
tag is the short, file system friendly, name of the bundle.
This value is used by the swbis implementation as a path name
component in the installed software catalog. If it is not
present the product tag is used.
o Product Attributes
A product defines the software product.
tag
tag is the short, file system friendly, name of the product.
This value is used by the swbis implementation as a path name
component in the installed software catalog. It is required.
The swbis implementation uses it in a way that is analogous to
the RPMTAG_NAME attribute, namely as the public recognizable
name of the package.
control_directory
Is the directory name in the distribution under which the prod-
uct contents are located. This value has no affect on the
installed software catalog. If it is not given in a PSF then
the tag is used.
revision
Is the product revision. It should not contain a "RELEASE"
attribute part or other version suffix modifiers. This value
is used by the swbis implementation as a path name component in
the installed software catalog. It is required by swinstall.
vendor_tag
This is a short identifying name of the distributor that sup-
plied the product and may associate (refer to) a vendor object
from the INDEX file that has a matching tag attribute. This
attribute is optional. This attribute value should strive to
be unique among all distributors. The swbis implementation mod-
ifies the intended usage slightly as a string that strives to
be globally unique for a given product.tag and product.revi-
sion. In this capacity it serves to distinguish products with
the same revision and tag from the same or different distribu-
tor. It most closely maps to the RPMTAG_RELEASE or
"debian_revision" attributes. It is one of the version distin-
guishing attributes of a product specified by the standard. It
is transfered into the installed_software catalog (not as a
path name component) by swinstall. If this attribute exists
there should also be a vendor object in the PSF in the distri-
bution object that has this tag. This attribute is assigned
the value of RPMTAG_RELEASE by swpackage when translating an
RPM.
architecture
This string is one of the version attributes. It is used to
disambiguate products that have the same tag, revision and ven-
dor_tag. It is not used for determining a products compatibil-
ity with a host. The form is implementation defined. swbis
uses the output of GNU config.guess as the value of this
string. A wildcard pattern should not be used. The canonical
swbis architecture string can be listed with swlist. For exam-
ple
swlist -a architecture @ localhost
Here are some example outputs from real systems.
System ‘uname -srm‘ architecture
Red Hat 8.0: Linux 2.4.18 i686 i686-pc-linux-gnu
OpenSolaris: SunOS 5.11 i86pc i386-pc-solaris2.11
NetBSD 3.1: NetBSD 3.1 i386 i386-unknown-netbsdelf3.1
Red Hat 4.1: Linux 2.0.36 i586 i586-pc-linux-gnulibc1
Debian 3.1: Linux 2.6.8-2-386 i686 i686-pc-linux-gnu
os_name os_release os_version machine_type
These attributes are used to determine compatibility with a
host. They correspond to the uname attributes defined by
POSIX.1. If an value is nil or non-existent it is assumed to
match the host. All attributes must match for there to be com-
patibility. Distributors may wish to make these values a shell
pattern in their PSF’s so to match the intended collection of
hosts. swbis uses fnmatch (with FLAGS=0) to determine a match.
o Fileset Attributes
A fileset defines the fileset.
tag
tag is the short, file system friendly, name of the fileset.
It is required although selection of filesets is not yet sup-
ported therefore the end user will have little to do with the
fileset tag.
control_directory
Is the directory name in the product under which the fileset
contents are located. This value has no affect on the
installed software catalog. If it is not given in a PSF then
the tag is used.
o Example Source Package PSF
This PSF packages every file is current directory. It uses nil control
directories so the package structure does not change relative to a
vanilla tarball.
distribution
description "fooit - a program from fooware
that does everything."
title "fooit - a really cool program"
COPYING < /usr/local/fooware/legalstuff/COPYING
vendor
the_term_vendor_is_misleading false
tag fooware
title fooware Consultancy Services, Inc.
description ""
vendor
the_term_vendor_is_misleading true
tag myfixes1
title Bug fixes, Set 1
description "a place for more detailed description"
product
tag fooit
control_directory ""
revision 1.0
vendor_tag myfixes1 # Matches the vendor object above
fileset
tag fooit-SOURCE
control_directory ""
directory .
file *
exclude catalog
o Example Runtime (Binary) Package PSF
This is a sample PSF for a runtime package. It implies multiple prod-
ucts (e.g. sub-packages) using the bundle.contents attribute. Since
the bundle and product tags exist in a un-regulated namespace and are
seen by end users they should be carefully chosen. Note that the
bundle and product have the same tag which may force downstream users
to disambiguate using software selection syntax such as fooit,bv=* or
fooit,pv=* .
distribution
description "fooit - a program from fooware
that does everything."
title "fooit - a really cool program"
COPYING < /usr/local/fooware/legalstuff/COPYING
vendor
the_term_vendor_is_misleading false
tag fooware
title fooware Consultancy Services, Inc.
description "Provider of the programs
that do everything"
vendor
the_term_vendor_is_misleading true
tag fw0
title fooware fixes
description "More fixes from the fooware users"
# Bundle definition: Use a bundle
bundle
tag fooit
vendor_tag fooware
contents fooit,v=fw0 fooit-devel fooit-doc
# Product definition:
product
tag fooit # This is the package name
revision 1.0 # This is the package version
vendor_tag fw0 # This is a release name e.g. RPMTAG_RELEASE
postinstall scripts/postinstall
fileset
tag fooit-RUN
file doc/man/man1/fooit.1 /usr/man/man1/fooit.1
file src/fooit /usr/bin/fooit
SAMPLE PRODUCT SPEC FILES
This section shows several example PSF files.
o A minimal PSF to package all files in current directory.
distribution
product
tag prod
control_directory ""
revision 1.0
fileset
tag files
control_directory ""
directory .
file *
o A PSF that uses directory mapping.
This PSF creates a package with live system paths from source that is
installed in non-live temporary locations. It is modeled on the swbis
source package.
distribution
product
tag somepackage # this is the package name
control_directory ""
revision 1.0 # this is the package revision
fileset
tag files
control_directory ""
file_permissions -o root -g root
directory swprogs /usr/bin
file swpackage
file swinstall
file swverify
file -m 755 -o root -g root / /usr/libexec/swbis
directory swprogs /usr/libexec/swbis
file swbisparse
directory swsupplib/progs /usr/libexec/swbis
file swbistar
file -m 755 -o root -g root / /usr/share/doc/swbis
directory . /usr/share/doc/swbis
file -m 444 ./README
file -m 444 CHANGES
When this PSF is processed by the command:
swpackage -Wsign -s - @- | tar tvf -
It produces the following:
drwxr-x--- root/root 0 2003-06-03 ... catalog/
-rw-r----- root/root 307 2003-06-03 ... catalog/INDEX
drwxr-x--- root/root 0 2003-06-03 ... catalog/dfiles/
-rw-r----- root/root 65 2003-06-03 ... catalog/dfiles/INFO
-rw-r----- root/root 33 2003-06-03 ... catalog/dfiles/md5sum
-rw-r----- root/root 41 2003-06-03 ... catalog/dfiles/sha1sum
-rw-r----- root/root 33 2003-06-03 ... catalog/dfiles/adjunct_md5sum
-rw-r----- root/root 512 2003-06-03 ... catalog/dfiles/sig_header
-rw-r----- root/root 1024 2003-06-03 ... catalog/dfiles/signature
drwxr-x--- root/root 0 2003-06-03 ... catalog/pfiles/
-rw-r----- root/root 65 2003-06-03 ... catalog/pfiles/INFO
-rw-r----- root/root 1503 2003-06-03 ... catalog/INFO
-rwxr-xr-x root/root 510787 2003-06-03 ... usr/bin/swpackage
-rwxr-xr-x root/root 301255 2003-06-03 ... usr/bin/swinstall
-rwxr-xr-x root/root 4105 2003-06-03 ... usr/bin/swverify
drwxr-xr-x root/root 0 2003-06-03 ... usr/libexec/swbis/
-rwxr-xr-x root/root 365105 2003-06-03 ... usr/libexec/swbis/swbisparse
-rwxr-xr-x root/root 243190 2003-06-03 ... usr/libexec/swbis/swbistar
drwxr-xr-x root/root 0 2003-06-03 ... usr/share/doc/swbis/
-r--r--r-- root/root 8654 2003-05-27 ... usr/share/doc/swbis/README
-r--r--r-- root/root 10952 2003-06-03 ... usr/share/doc/swbis/CHANGES
o Create a PSF from a list of files.
find . -print | swpackage -Wfiles-from=- -Wlist-psf
RETURN VALUE
0 on success, 1 on error and target medium not modified, 2 on error if
target medium modified.
SIDE EFFECTS
No temporary files are used in the package generation process. When
using the default target of stdout (directed to /dev/null), there are
no file system side effects from swpackage. GNU Privacy Guard (gpg)
may alter its keys when invoked for package signing.
ENVIRONMENT
SWPACKAGEPASSFD
Sets the --passphrase-fd option. Set the option arg to a inte-
ger value of the file descriptor, or to "env" to read the
passphrase from the environment variable SWPACKAGEPASSPHRASE,
or to "agent" to cause gpg to use gpg-agent, or to "tty" to
restore default behavoir to reading passphrase from the termi-
nal.
SWPACKAGEPASSPHRASE
Use the value as the passphrase if --passphrase-fd is set to
"env"
GNUPGHOME
Sets the --gpg-home option.
GNUPGNAME
Sets the --gpg-name option, which is turn set the --local-user
option of gpg.
REQUISITE UTILITIES
Swpackage does not use any archive writing utilities, it has its own
code to generate archives.
Package signing uses one of the following:
/usr/bin/gpg
/usr/bin/pgp (PGP 2.6.x)
/usr/bin/pgps (PGP 5)
Swpackage will use /usr/bin/uuidgen if present to create the uuid.
You must use this option to make the catalog directory identical in
subsequent invocations.
FILES
libdir/swbis/swdefaults
libbir/swbis/swbisdefaults
$HOME/.swbis/swdefaults
$HOME/.swbis/swbisdefaults
APPLICABLE STANDARDS
ISO/IEC 15068-2:1999, Open Group CAE C701.
SEE ALSO
info swbis
sw(5), swpackage(5), swbisparse(1), swign(1), swverify(8)
IDENTIFICATION
swpackage(8): The packaging utility of the swbis project.
Author: Jim Lowe Email: jhlowe at acm.org
Version: 0.951
Last Updated: 2006-07-01
Copying: GNU Free Documentation License
BUGS
A comment after an object keyword is wrongly not allowed by this PSF
parser. The --dir="" does not do what one would expect sometimes.
The output stream content is unaffected by the blocksize, that is the
last write may be short write. Signing is broken for cpio format
archives.
swpackage(8)
swinstall(8) swinstall(8)
NAME
swinstall — Install POSIX and RPM packages.
SYNOPSIS
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.
DESCRIPTION
swinstall installs a POSIX distribution from a source archive to a
target 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)
swinstall will read an archive on stdin and install all products and
filesets 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.
swinstall will create an entry in an installed software catalog. This
is a directory usually located at /var/lib/swbis/catalog. Using this
information checks for upgrade, downdate, dependencies, and reinstal-
lation are made.
OPTIONS
-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
syntax 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. (Implemen-
tation 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 com-
mand 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
’PATH=‘getconf PATH‘ sh -s’.
-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 interme-
diate 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 ’-1’ ssh client option which specifies protocol version 1.
-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
Refers to the software objects (products, filesets) on which to
be operated. This is not implemented, however, specification of
a location and qualifier are supported. location allow speci-
fication of a alternate relative root path within the target
path, and qualifier allows specification of a user-selectable
modifier. For example:
swinstall q=exp @ 192.168.1.1 # Tag the package as experimental
swinstall l=/unionfs/somepackage-1.0 @ 192.168.1.1 # Allows multiple
# packages with same tag to exist in the
# same target path, where the location
# disambiguates.
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 Extension:
[user@]host[:path]
[user@]host_port[:path]
:path
Swbis Multi-hop Target Extension:
# ’:’ is the target delimiter
# ’_’ delimits a port number in the host field
[user@]host[@@[user@]host[@@...]][:file]
[user@]host_port[@@[user@]host[@@...]][:file]
# Using ’:’, a trailing colon is used to
# disambiguate between a host and file.
# For Example,
:file
host:
host
host:file
host:host:
host_port:host_port:
host:host:file
user@host:user@host:
user@host:user@host:host:
user@host:user@host:file
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:
Copy the distribution /var/tmp/foo.tar.gz at 192.168.1.10
swcopy -s /var/tmp/foo.tar.gz @192.168.1.10:/root
Implementation Extension Syntax (multi ssh-hop) :
Syntax:
%start wtarget # the Implementation Extension Target
# Note: a trailing ’:’ forces interpretation
# as a host, not a file.
wtarget : wtarget DELIM sshtarget
| sshtarget
| sshtarget DELIM
;
sshtarget : user ’@’ target # Note: only the last target
| target # may have a PATHNAME, and only a host
; * may have a user
target : HOST_CHARACTER_STRING
| PATHNAME_CHARACTER_STRING
;
user : PORTABLE_CHARACTER_STRING # The user name
DELIM : ’:’ # The multi-hop delimiter.
;
INSTALLED SOFTWARE CATALOG
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
installed_software_catalog extended option. The catalog is a file
system hierarchy containing regular files and directories.
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>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/location
<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/qualifier
<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
<sequence_number>/location
<sequence_number>/qualifier
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/catalog.tar file is the signed file from the POSIX distribu-
tion. The export/catalog.tar.sig file is the signature file from the
distribution. 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/catalog.tar.sigN is the first one, where N is the total number
of signatures.
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 exe-
cution environment and map script tags to the control script path-
names. 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
swinstall. 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
revision 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/location
/mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/qualifier
/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.
IMPLEMENTATION EXTENSIONS
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 stan-
dard 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 detec-
tion 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
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"
RETURN VALUE
0 if all targets succeeded, 1 if all targets failed, 2 if some targets
failed and some succeeded.
NOTES
Multiple ssh-hops is an implementation extension.
REQUISITE UTILITIES
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 com-
plies 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).
FILES
/usr/lib/swbis/swdefaults
/usr/lib/swbis/swbisdefaults
$HOME/.swbis/swdefaults
$HOME/.swbis/swbisdefaults
APPLICABLE STANDARDS
ISO/IEC 15068-2:1999, Open Group CAE C701
SEE ALSO
info swbis
swcopy(8), sw(5), swbisparse(1), swign(1), swverify(8)
IDENTIFICATION
swinstall(8): The installation utility of the swbis project.
Author: Jim Lowe Email: jhlowe at acm.org
Version: 0.951
Last Updated: 2008-04-18
Copying: GNU Free Documentation License
BUGS
swinstall is subject to breakage if a user’s account on an intermedi-
ate (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 pro-
cesses being left on on the intermediate host(s), this despite, swin-
stall’s action of sending a SIGTERM to the remote script’s parent pro-
cess.
swinstall does not currently implement Software Selections, not file-
set dependencies, and much more. Only packages with one product and
one fileset are supported.
swinstall(8)
swremove(8) swremove(8)
NAME
swremove — Remove installed software
SYNOPSIS
swremove [-d|-r] [-v] [-t targetfile] \
[-x option=value] [-X options_file] [-W option] \
[software_selections] [@targets]
swremove --cleansh [options] [@targets]
DESCRIPTION
swremove removes installed software. swremove is a distributed util-
ity. Neither swremove 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. Remote network connections
are made by ssh. Ssh is the default but rsh can be selected by a com-
mand line option.
swremove operates on installed software identified by a software
selection and target.
OPTIONS
-d
Specify the target is a distribution.
Note: This is currently not supported by this implemen-
tation.
-f FILE
Read the list of software selections from FILE.
-p
Preview mode, establish contact with target host, however, mod-
ify nothing.
-r
Indicates that the operation is on installed software at a
location indicated by the the target.
Note: This is the default mode among -d and -r
-t targetfile
Specify a file containing a list of targets (one per line).
-v
Increment the verbose level.
-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.
--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.
--allow-ambig
Allows swremove to act on all matching entries. Without this
option a software selection that matches more than one
installed software entry is an error.
--sig-level=N
Specify number of required GPG signatures, N equal to 0 means
don’t require the catalog to be signed.
--cleansh
Kill stray or zombied processes that match the pattern ‘‘sh
-s.*_swbis’’. These may be caused by a distributed utility
segfaulting or a signal handling defect in the swbis utility.
-W remote-shell=SHELL
Defaults File Option: swbis_remote_shell_client
Supported shells are "ssh" and "rsh", ssh is the default.
-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 com-
mand 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-getconf
Defaults File Option: swbis_no_getconf
Makes the remote command be ’/bin/sh -s’ instead of the default
’PATH=‘getconf PATH‘ sh -s’.
-W shell-command=NAME
Defaults File Option: swbis_shell_command
NAME may be one of "bash", "sh" or "posix" and specifies the
remote command run by the remote shell. "posix" is ’PATH=‘get-
conf 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 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) using soft-
ware spec syntax. (See sw(5) for syntax).
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 located. A target that
contains only one part is assumed to be a hostname. To force
interpretation as a path, use a absolute path or prefix with
’:’.
Source and Target Specification and Logic
Synopsis:
Posix:
host[:path]
host
host:
/path # Absolute path
Swbis Extension:
[user@]host[:path]
[user@]host_port[:path]
:path
Swbis Multi-hop Target Extension:
# ’:’ is the target delimiter
# ’_’ delimits a port number in the host field
[user@]host[@@[user@]host[@@...]][:file]
[user@]host_port[@@[user@]host[@@...]][:file]
# Using ’:’, a trailing colon is used to
# disambiguate between a host and file.
# For Example,
:file
host:
host
host:file
host:host:
host_port:host_port:
host:host:file
user@host:user@host:
user@host:user@host:host:
user@host:user@host:file
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:
Copy the distribution /var/tmp/foo.tar.gz at 192.168.1.10
swcopy -s /var/tmp/foo.tar.gz @192.168.1.10:/root
Implementation Extension Syntax (multi ssh-hop) :
Syntax:
%start wtarget # the Implementation Extension Target
# Note: a trailing ’:’ forces interpretation
# as a host, not a file.
wtarget : wtarget DELIM sshtarget
| sshtarget
| sshtarget DELIM
;
sshtarget : user ’@’ target # Note: only the last target
| target # may have a PATHNAME, and only a host
; * may have a user
target : HOST_CHARACTER_STRING
| PATHNAME_CHARACTER_STRING
;
user : PORTABLE_CHARACTER_STRING # The user name
DELIM : ’:’ # The multi-hop delimiter.
;
USAGE EXAMPLES
Remove everything at 192.168.1.2 from the root directory
swremove --allow-ambig \* @ root@192.168.1.2:/
Preview removal of every package listing every file, but modify nothing
swremove -vv -p --allow-ambig \* @ root@192.168.1.2:/
Remove everything at 192.168.1.2 from the home directory of user ’jail-
bird’.
swremove --allow-ambig \* @ jailbird@192.168.1.2:.
Remove package foo from the root ’/’, or elevate your credentials via ssh
swremove foo @ /
swremove foo @ root@localhost:/
Show the options
swremove --show-options
EXTENDED OPTIONS
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 on the local (management host, host where swremove is invoked).
These files on the target host are not used.
autoselect_dependencies = false
distribution_target_directory = /
enforce_dependencies = false
enforce_scripts = true
installed_software_catalog = var/lib/swbis/catalog/
logfile = /var/log/sw.log
loglevel = 1
select_local = true
verbose = 1
Swbis Implementation
These options are set in the /usr/lib/swbis/swbisdefaults or the
~/.swbis/swbisdefaults file.
swremove.swbis_no_getconf = false # true or false
swremove.swbis_shell_command = posix # {sh|bash|posix|ksh}
swremove.swbis_no_remote_kill = false # true or false
swremove.swbis_local_pax_write_command=pax #{pax|tar|star|gtar|swbistar}
swremove.swbis_remote_pax_write_command=pax #{pax|tar|star|gtar|swbistar}
swremove.swbis_local_pax_read_command=pax #{pax|tar|gtar|star}
swremove.swbis_remote_pax_read_command=pax #{pax|tar|gtar|star}
swremove.swbis_local_pax_remove_command=tar
swremove.swbis_remote_pax_remove_command=tar
swremove.swbis_remote_shell_client=ssh
swremove.swbis_forward_agent=True
swremove.swbis_sig_level=0
swremove.swbis_enforce_all_signatures=false
RETURN VALUE
0 if all targets succeeded, 1 if all targets failed or internal error,
2 if some targets failed and some succeeded.
NOTES
Multiple ssh-hops is an implementation extension.
REQUISITE UTILITIES
swremove uses rm and rmdir for file and directory removal.
Other utilities required to be in $PATH on the remote host are: dd,
pax (or tar|star|gtar), mkdir, echo, test, sleep, read (if not
builtin).
FILES
/usr/lib/swbis/swdefaults
/usr/lib/swbis/swbisdefaults
$HOME/.swbis/swdefaults
$HOME/.swbis/swbisdefaults
APPLICABLE STANDARDS
ISO/IEC 15068-2:1999, Open Group CAE C701
SEE ALSO
info swbis
swbis(7), sw(5), swlist(8)
IDENTIFICATION
swremove(8): The package removal utility of the swbis project.
Author: Jim Lowe Email: jhlowe at acm.org
Version: 0.951
Last Updated: 2008-04-18
Copying: GNU Free Documentation License
BUGS
swremove 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.) swremove does not support rollback
if an error occurs during processing.
swremove(8)
swcopy(8) swcopy(8)
NAME
swcopy — Copy POSIX and RPM packages.
SYNOPSIS
swcopy [-p] [-s source_file] [-f file] [-t targetfile] \
[-x option=value] [-X options_file] [-W option] \
[software_selections] [@target [target1...]]
DESCRIPTION
swcopy copies a POSIX distribution from a source archive or directory
to a target archive directory. Neither swcopy 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.
Remote network connections are made by ssh. Ssh is the default but
rsh can be selected by a command line option.
Before and during data transfer to the target, the distribution is
audited. Package auditing includes parsing the INDEX and INFO meta-
data files. The package pathnames are checked for consistency with a
valid layout. swcopy can be made to operate on arbitrary data or
archives not in POSIX format by using the --no-audit option. By
default and with no external influences (i.e. swdefaults file) swcopy
will read a archive on stdin and write an audited archive on stdout.
The uncompressed audited output file will be identical to the uncom-
pressed input file unless an error occurs. Compressed archives that
are audited will be re-compressed in the same format, however, the
resulting file may not be identical to the input file (i.e. date,
filename, and other stored data in the compressed format will be dif-
ferent).
swcopy operates on serial archives (e.g. compressed tar archives) or
on file system directories. It will attempt to preserve the form
(archive or directory) and compression state of the source object. An
exception is "." as a target (See Implementation Extensions below).
OPTIONS
-f FILE
Reads software_selections from FILE. (Not implemented).
-p
Preview the operation. Information is written to stdout. The
target is not written and no remote connections are estab-
lished.
-s SOURCE
Specify the source file SOURCE, "-" is standard input. The
syntax is the same as for a target. SOURCE may be a directory
or archive file.
-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. (Implemen-
tation 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.
The progress meter is suppressed if swcopy is using stdout for
data.
-b SIZE
Set block size, same as --block-size=N (Implementation exten-
sion option).
--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 no-audit
Defaults File Option: swbis_no_audit
Do not audit the transferred file. This allows copying of
arbitrary data.
-W audit
Do audit the transferred file. Useful for overriding swbisde-
faults file.
-W block-size=SIZE
SIZE is number of octets.
-W login
Establishes a interactive shell on the (remote) target host.
Intended for debugging/verifying ssh operation.
-W gzip
Compress output using gzip.
-W bzip
Compress output using bzip2.
-W extract
Install the source using the archive reading utility at the
target.
-W pty
Do use pseudo-tty. The system Ptys are only used for the
--login feature. A warning is emitted to stderr which says
that the usage may be insecure.
-W no-pty
Do not use pseudo-tty. The system Ptys are only used by
default for the --login feature, otherwise they are not used
and this option would have no effect. If ptys are used a warn-
ing is emitted to stderr which says that the usage may be inse-
cure.
-W uncompress
Write output archive that is uncompressed.
-W remote-shell=SHELL
Defaults File Option: swbis_remote_shell_client
Supported shells are "ssh" and "rsh", ssh is the default.
-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-progress
Enables progress bar.(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 com-
mand 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
’PATH=‘getconf PATH‘ sh -s’.
-W shell-command=NAME
Defaults File Option: swbis_shell_command
NAME may be one of "bash", "sh" or "posix" and specifies the
remote command run by the remote shell. "posix" is ’PATH=‘get-
conf 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
Allows detection and translation of RPMs. (--audit must also
be set.)
-W unrpm
Turns on options --allow-rpm and --audit.
-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 distri-
bution.
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 located. A target that con-
tains only one part is assumed to be a hostname. To force
interpretation as a path, use a absolute path or prefix with
’:’.
Source and Target Specification and Logic
Synopsis:
Posix:
host[:path]
host
host:
/path # Absolute path
Swbis Extension:
[user@]host[:path]
[user@]host_port[:path]
:path
Swbis Multi-hop Target Extension:
# ’:’ is the target delimiter
# ’_’ delimits a port number in the host field
[user@]host[@@[user@]host[@@...]][:file]
[user@]host_port[@@[user@]host[@@...]][:file]
# Using ’:’, a trailing colon is used to
# disambiguate between a host and file.
# For Example,
:file
host:
host
host:file
host:host:
host_port:host_port:
host:host:file
user@host:user@host:
user@host:user@host:host:
user@host:user@host:file
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:
Copy the distribution /var/tmp/foo.tar.gz at 192.168.1.10
swcopy -s /var/tmp/foo.tar.gz @192.168.1.10:/root
Implementation Extension Syntax (multi ssh-hop) :
Syntax:
%start wtarget # the Implementation Extension Target
# Note: a trailing ’:’ forces interpretation
# as a host, not a file.
wtarget : wtarget DELIM sshtarget
| sshtarget
| sshtarget DELIM
;
sshtarget : user ’@’ target # Note: only the last target
| target # may have a PATHNAME, and only a host
; * may have a user
target : HOST_CHARACTER_STRING
| PATHNAME_CHARACTER_STRING
;
user : PORTABLE_CHARACTER_STRING # The user name
DELIM : ’:’ # The multi-hop delimiter.
;
TARGET COPYING RULES
Currently, file permissions and ownerships are not copied. ’swcopy’ is
not intended to be used in the way of cp or scp, although it can be if
forced. Non-existing directories in a target are created. A source
directory cannot be renamed (although a regular file can be), that is
if a directory is being copied, it will never be a different name on
the target. A single source file is specified for one or more tar-
gets. The syntax does not support multiple source files. A portable
character string in the target spec is assumed to be a hostname unless
it begins with a slash ’/’ or a colon ’:’.
Rules
If a target directory on the host does not exist it will be created
using mkdir -p using the file creation mask of the originating swcopy
process. A trailing slash in the target spec signifies that the last
path component should be a directory. A source spec that is a direc-
tory will be created on the target as a directory with the same name
in the target directory. If the source spec is stdin then the exis-
tence of directories in the target spec and a trailing slash in the
target spec path determines whether the created file will be a regular
file or directory, that is, stdin will be copied as a file unless the
last target path component is a directory or ends in a slash ’/’. If
the source spec is a regular file, the source basename will be used as
the basename in the target if the last target path component is a
directory or ends in a slash ’/’, otherwise, the target basename is
the last path component of the target spec. The implementation option
--extract biases these rules to install using the archive reading com-
mand (e.g. pax -r).
Examples
Install a tarball in the current directory:
Note: Must use stdin as source and "." as the target.
swcopy --no-audit -s - @. < foo.tar.gz
Copy thru a firewall:
swcopy -s /var/tmp/foo.tar.gz \
@root@host1@@root@host2:/var/tmp
Copy Stdin to a remote host:
Unpack the archive on stdin in the directory
/a/b/c if ’c’ is a directory, otherwise copy
the archive file to a file named ’c’ in
directory /a/b creating it if possible and
overwriting if required.
swcopy -s - @host1:/a/b/c
Copy Stdin to a remote host:
Unpack the serial archive on stdin in the
directory /a/b/c if ’c’ is a directory,
otherwise make the directory ’c’ but fail if
directory ’c’ cannot be created.
swcopy -s - @host1:/a/b/c/
# Note trailing slash.
Copy a regular file:
Copy file yy to directory /aa/bb/cc/ on the
remote host, creating it if required and possible.
If cc is a regular file then fail.
swcopy -s /xx/yy @host1:/aa/bb/cc/
Copy a regular file thru intermediate host ’fw’:
Copy file yy to home directory of user1 on host1
thru a an intermediate host fw,
swcopy -s /xx/yy @fw@@user1@host1:.
Copy a directory from one host to another
Copy directory yy into directory cc if cc exists,
otherwise create cc and copy yy into it. If cc
is and copy as yy.
swcopy -s /xx/yy @host1:/aa/bb/cc
IMPLEMENTATION EXTENSIONS
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 stan-
dard 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.
Thus,
# swcopy -s ‘pwd‘/myarchive.tgz @. # Do NOT do this even
# though in most cases
# swcopy is a coward.
will destroy the source file myarchive.tgz, whereas
# swcopy -s - @. <‘pwd‘/myarchive.tgz
will install it with the configured archive reading utility.
RPM Translation
RPM (RedHat Package Manager) format packages are copied by first
translating to an equivalent ISO/IEEE file layout in POSIX tar format
and then copying as a POSIX package. The RPM detection and transla-
tion occurs if the ’’--allow-rpm’’ option is on (either by the command
line args or defaults file) and the ’’--audit’’ option is on. If the
’’--allow-rpm’’ option is not set an error occurs. If the ’’--audit’’
is not set, the RPM is copied as arbitrary data and translation does
not occur.
Since translation is done on the local (management) host, RPM is not
reqired on the remote (target) host.
The translation is (internally) equivalent to :
cat your-poor-poor-0.0.bin.rpm |
/usr/lib/swbis/lxpsf --psf-form2 -H ustar |
swpackage -Wsource=- -s@PSF
EXTENDED OPTIONS
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
autoselect_dependencies = false # Not Implemented
compress_files = false # Not Implemented
compression_type = none # Not Implemented
distribution_source_directory = -
distribution_target_directory = -
enforce_dependencies = false # Not Implemented
enforce_dsa = false # Not Implemented
logfile = /var/lib/sw/swcopy.log #Not Implemented
loglevel = 1 # Not Implemented
recopy = false # Not Implemented
select_local = false # Not Implemented
uncompress_files = false # Not Implemented
verbose = 1
Swbis Implementation
These options are set in the /usr/lib/swbis/swbisdefaults or the
~/.swbis/swbisdefaults file.
swcopy.swbis_no_getconf = false # true or false
swcopy.swbis_shell_command = posix # {sh|bash|posix|ksh}
swcopy.swbis_no_remote_kill = false # true or false
swcopy.swbis_no_audit = false # true or false
swcopy.swbis_quiet_progress_bar = false # true or false
swcopy.swbis_local_pax_write_command=pax #{pax|tar|star|gtar|swbistar}
swcopy.swbis_remote_pax_write_command=pax #{pax|tar|star|gtar|swbistar}
swcopy.swbis_local_pax_read_command=pax #{pax|tar|gtar|star}
swcopy.swbis_remote_pax_read_command=pax #{pax|tar|gtar|star}
swcopy.swbis_allow_rpm = false # true or false
swcopy.swbis_remote_shell_client=ssh
RETURN VALUE
0 if all targets succeeded, 1 if all targets failed, 2 if some targets
failed and some succeeded.
NOTES
Multiple ssh-hops is an implementation extension.
REQUISITE UTILITIES
Swcopy requires a Posix shell accessible by the remote shell command.
This is the remote command run by ssh (or rsh) for all operations.
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), "sh" (/bin/sh -s), "ksh" (/bin/ksh -s) or "posix"
(’PATH=‘getconf PATH‘ sh -s’). The default is "posix". swcopy
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 is 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 swcopy.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), mkdir, echo, test, sleep, read (if not
builtin).
FILES
/usr/lib/swbis/swdefaults
/usr/lib/swbis/swbisdefaults
$HOME/.swbis/swdefaults
$HOME/.swbis/swbisdefaults
APPLICABLE STANDARDS
ISO/IEC 15068-2:1999, Open Group CAE C701
SEE ALSO
info swbis
sw(5), swbisparse(1), swign(1), swverify(8)
IDENTIFICATION
swcopy(8): The archive copying utility of the swbis project.
Author: Jim Lowe Email: jhlowe at acm.org
Version: 0.951
Last Updated: 2006-07
Copying: GNU Free Documentation License
BUGS
Swcopy 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 pro-
cesses being left on on the intermediate host(s), this despite,
swcopy’s action of sending a SIGTERM to the remote script’s parent
process.
Swcopy does not currently implement Software Selections nor the events
of the Selection and Analysis Phases nor dependency copying nor file-
set state transitions. The Execution (copying) phase is done on the
entire distribution by the utility selected in .../swbisdefaults which
is pax(1) by default. Pax is not found on all GNU/Linux systems.
Also, the pax version shipped with some (older) GNU/Linux systems man-
gles the pathname of files whose pathname is exactly 100 octets long.
Despite this pax is the the builtin default. GNU tar is widely used
and trusted but creates non-standard archives for long pathnames.
Perhaps the best compromise is to use star (with -H ustar header
option) for archive creation and (GNU) tar for archive reading. If
your environment is 100% GNU/Linux using GNU tar is safe (GNU tar
1.13.25 is recommended). Swcopy does not support using the cpio util-
ity since its archive writing interface is unlike pax and tar,
although, future support is possible for archive reading.
swcopy(8)
swlist(8) swlist(8)
NAME
swlist — List information about the software
SYNOPSIS
swlist [-d|-r] [-v] [-a attribute] [-l level] [-t targetfile] \
[-c file] [-x option=value] [-X options_file] [-W option] \
[software_selections] [@targets]
swlist --products [software_selections] [@targets]
swlist --files [@targets]
swlist --dir [software_selections] [@targets]
swlist --dependencies [--prerequisites sw_spec] [--exrequisites sw_spec] \
[@targets]
DESCRIPTION
swlist lists information about a distribution or installed software.
Neither swlist 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. Remote network connections are
made by ssh. Ssh is the default but rsh can be selected by a command
line option.
swlist operates on serial archives (e.g. compressed tar archives) or
on a file system directory representing installed software. The
default target directory is ’/’, this default is subject to user con-
figuration.
OPTIONS
-a attribute
Specify an attribute to list. Only the architecture attribute
is supported for installed_software at this time (MAR 2007).
The returned value is determined by running GNU config.guess on
the target host.
-c FILE
Write the catalog to FILE. Software selections are applied.
The only supported FILE is ’-’ causing a dump of the catalog to
stdout in tar format.
-d
Specify the target is a distribution.
-f FILE
Read the list of software selections from FILE.
-l LEVEL
Specify a level to list. LEVEL is an enumerated list of
objects: bundle, product, fileset, control_file, file (Not yet
implemented)
-r
Indicates that the operation is on installed software at a
location indicated by the the target.
-t targetfile
Specify a file containing a list of targets (one per line).
-v
List attribute value pairs in INDEX file format according to
attibutes specified by the -a option, list all attributes if -a
not used; or, increment the verbose level.
Note: This option is overloaded. It means two different
things depending on the context. If a mode is explic-
itly given, then it means increment verbosity, otherwise
it means list in INDEX file format.
-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.
--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.
--products
List the product’s tag, revision, vendor_tag and location.
--directory
List the catalog directory entries.
--files
List files as defined in the installed catalog
--sys
List files as exists in the file system
--dependencies
Run in check dependency mode. Assert dependencies against
installed software catalog. Dependencies are software specs
given by the --prerequisites and --extrequisites options
--prerequisites=SW_SPEC
Specify depencency to check, may be used multiple times. Pre-
requisites packages are required to be installed.
--exrequisites=SW_SPEC
Specify depencency to check, may be used multiple times.
Exrequisites packages are required not to be installed.
-W remote-shell=SHELL
Defaults File Option: swbis_remote_shell_client
Supported shells are "ssh" and "rsh", ssh is the default.
-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 com-
mand 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-getconf
Defaults File Option: swbis_no_getconf
Makes the remote command be ’/bin/sh -s’ instead of the default
’PATH=‘getconf PATH‘ sh -s’.
-W shell-command=NAME
Defaults File Option: swbis_shell_command
NAME may be one of "bash", "sh" or "posix" and specifies the
remote command run by the remote shell. "posix" is ’PATH=‘get-
conf 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 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) using soft-
ware spec syntax. (See sw(5) for syntax).
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 located. A target that con-
tains only one part is assumed to be a hostname. To force
interpretation as a path, use a absolute path or prefix with
’:’.
Source and Target Specification and Logic
Synopsis:
Posix:
host[:path]
host
host:
/path # Absolute path
Swbis Extension:
[user@]host[:path]
[user@]host_port[:path]
:path
Swbis Multi-hop Target Extension:
# ’:’ is the target delimiter
# ’_’ delimits a port number in the host field
[user@]host[@@[user@]host[@@...]][:file]
[user@]host_port[@@[user@]host[@@...]][:file]
# Using ’:’, a trailing colon is used to
# disambiguate between a host and file.
# For Example,
:file
host:
host
host:file
host:host:
host_port:host_port:
host:host:file
user@host:user@host:
user@host:user@host:host:
user@host:user@host:file
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:
Copy the distribution /var/tmp/foo.tar.gz at 192.168.1.10
swcopy -s /var/tmp/foo.tar.gz @192.168.1.10:/root
Implementation Extension Syntax (multi ssh-hop) :
Syntax:
%start wtarget # the Implementation Extension Target
# Note: a trailing ’:’ forces interpretation
# as a host, not a file.
wtarget : wtarget DELIM sshtarget
| sshtarget
| sshtarget DELIM
;
sshtarget : user ’@’ target # Note: only the last target
| target # may have a PATHNAME, and only a host
; * may have a user
target : HOST_CHARACTER_STRING
| PATHNAME_CHARACTER_STRING
;
user : PORTABLE_CHARACTER_STRING # The user name
DELIM : ’:’ # The multi-hop delimiter.
;
IMPLEMENTATION EXTENSIONS
The --dependencies, --products, and --files are implementation exten-
sion modes.
USAGE EXAMPLES
Show the path of the installed software catalog.
swlist --show-options | grep installed_
List Products
* List products from a certain distributor, foo (Note: this requires
that the foo vendor uses foo_something_ as the product vendor_tag in
their distributions.
swlist v="foo*"
* List all products
swlist @/ # If distribution_target_directory=/ then "swlist" alone
# will suffice.
* List products installed at alternate root
swlist @/mnt/test
* List products according to a name pattern and revision, and distrib-
utor
swlist emacs"*","r>20",v=rh"*" @/
Test Dependencies
* Check if a given dependency passes against a given installed catalog
on a host
swlist -x verbose=3 --depend --pre="foo*,r>=1.0,r<2" @192.168.3.1:/; echo $?
EXTENDED OPTIONS
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 on the local (management host, host where swlist invoked).
These files on the target host are not used.
distribution_target_directory = /
installed_software_catalog = var/lib/swbis/catalog/
one_liner = files|products # Mode when -v not given
select_local = false # Not Implemented
verbose = 1
Swbis Implementation
These options are set in the /usr/lib/swbis/swbisdefaults or the
~/.swbis/swbisdefaults file.
swlist.swbis_no_getconf = false # true or false
swlist.swbis_shell_command = posix # {sh|bash|posix|ksh}
swlist.swbis_no_remote_kill = false # true or false
swlist.swbis_local_pax_write_command=pax #{pax|tar|star|gtar|swbistar}
swlist.swbis_remote_pax_write_command=pax #{pax|tar|star|gtar|swbistar}
swlist.swbis_local_pax_read_command=pax #{pax|tar|gtar|star}
swlist.swbis_remote_pax_read_command=pax #{pax|tar|gtar|star}
swlist.swbis_remote_shell_client=ssh
swlist.swbis_forward_agent=True
RETURN VALUE
0 if all targets succeeded, 1 if all targets failed or internal error,
2 if some targets failed and some succeeded. When checking dependen-
cies, 3 if the given sw_specs failed as dependencies, 0 if succeeded.
NOTES
Multiple ssh-hops is an implementation extension.
REQUISITE UTILITIES
swlist requires a Posix shell accessible by the remote shell command.
This is the remote command run by ssh (or rsh) for all operations.
swlist makes use of the system ’awk’ program for querying the
installed software catalog, it should work. swlist is tested with
gawk (GNU awk) and the AT awkbook awk.
If the --no-getconf option is set or the swlist.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), mkdir, echo, test, sleep, read (if not
builtin).
FILES
/usr/lib/swbis/swdefaults
/usr/lib/swbis/swbisdefaults
$HOME/.swbis/swdefaults
$HOME/.swbis/swbisdefaults
APPLICABLE STANDARDS
ISO/IEC 15068-2:1999, Open Group CAE C701
SEE ALSO
info swbis
swbis(7), sw(5), swbisparse(1), swign(1), swverify(8)
IDENTIFICATION
swlist(8): The query/listing utility of the swbis project.
Author: Jim Lowe Email: jhlowe at acm.org
Version: 0.951
Last Updated: 2006-07
Copying: GNU Free Documentation License
BUGS
swlist 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.)
swlist does not currently implement the -v,-a options. Listing prod-
ucts in a distribution is not supported. Operating on a distribution
in directory form is not supported. The catalog query funtions are
implemented in awk and subject to its bugs.
swlist(8)
swverify(8) swverify(8)
NAME
swverify — Verify Software
SYNOPSIS
Posix:
swverify [-d|-r] [-F] [-f file] [-t targetfile] \
[-x option=value] [-X options_file] [-W option] \
[software_selections] [@targets]
swverify # Verify standard input
swverify -r selection [@ target]
swverify -d [@ target]
swverify -d @- # dash means standard input
swverify [--scm|--order-files] -d @. # . means current directory
swverify [--scm|--order-files] -d @:package_directory
Implementation Extension:
swverify [-Wd] -Wemit-digest-file [portable_archive_file]
swverify [-Wd] -Wemit-signed-file [portable_archive_file]
swverify [-Wd] [-Wsha1] -Wemit-digest-file [portable_archive_file]
swverify [-Wd] -Wget-sig-if=sigfilename [portable_archive_file]
DESCRIPTION
The swverify utility checks the accuracy of software in distributions
and installed_software. If no options are given, a serial distribu-
tion on stdin is verified.
Currently, swverify does not read the defaults files. "/" is the
default target for installed software. Stdin is the default target
for distributions. The built-in value of "installed_software_catalog"
is "var/lib/swbis/catalog".
OPTIONS
-d
Specify to operate on a distribution rather than installed
software.
-r
Specify to operate on installed software at the target path.
software_selections
See other man pages.
targets
See other man pages. Currently, only one (1) target can be
specified.
-x option=value
Specify the extended option overriding the defaults file value.
This option not yet implemented.
-X FILE
Specify the extended options filename, FILE, overriding the
default filename. This option not yet implemented.
Other POSIX options not implemented.
POSIX EXTENDED OPTIONS
Not yet implemented.
IMPLEMENTATION EXTENSION OPTIONS
-W option[,option,...]
Specify the implementation extension option.
Syntax: -W option[=option_argument[,option...]
Options may be separated by a comma.
--checksig | -W checksig
This is the default action and is the same as the POSIX syntax
"-d @target". If target file is not a directory then verify
archive md5 and sha1 and gpg signature directly from the file.
If target file is a directory, attempt to verify the signature
using GNU tar and gpg and if successful execute the distributor
extension script checksig. If checksig does not exist then
exit with failure.
FILE may be "." (current directory) or "-" (standard input). A
serial archive file may be compressed with gzip, bzip2, or Unix
compress.
--order-catalog
Use the order of files in catalog/dfiles/files to recreate the
signed data when verifying the directory (unpacked tarball)
form of the package.
--cvs
Read and process information in the ./catalog (before it is
authenticated) to correct the file sytem meta-data in an
attempt to verify the GPG signature. It only affects verifica-
tion on the directory (unpacked tarball), not tarball verifica-
tion. It is required when verifying an exported or working SCM
(Source Code Management, such as CVS) directory if the SCM does
not preserve and restore file system meta-data. This option
also emliminates the dependency on the order of files in file
system directories.
--scm
Currently, same as the --cvs option.
--no-checkdigest
When verifying the directory form, do not run the checkdigest
script even if the GPG signed data contains the checkdigest
script.
--signed-file [FILE]
Write the GPG signed portion of the package to stdout without
verifying it. Read archive file FILE or standard input and
write the signed file (i.e. gpg’s signed stuff) to stdout.
This is the catalog section of the Posix package. This option
is supported for the tarball file and unpacked tarball direc-
tory. Use of the --scm option may be required for the unpacked
tarball directory form.
--digest-file [FILE]
Write the payload portion of the package to stdout without ver-
ifying its digest matches the digest in the signed data. This
is the storage section of the Posix package. This option is
not supported for the unpacked tarball form.
-W emit-signed-file | -W C
Same as --signed-data. Also the same as -WC
-W emit-digest-file [FILE]
Same as --digest-data. Also the same as -WS
-W show-auth-files | -W d
Writes the relevent security file to stderr. Applies to emit-
digest-file and emit-signed-file modes.
-W sig-number=N
Operates on the Nth signature, 0 is last, 1 is the first.
-W get-sig-if=outputfile
Verifies the archive digests by comparing to the digests in the
catalog and if they match write the sigfile to outputfile and
the signed data to stdout.
DISTRIBUTOR SCRIPTS
Not yet implemented.
IMPLEMENTATION EXTENSION DISTRIBUTOR SCRIPTS
checkdigest <path>/catalog/<dfiles>/checkdigest
This script was named ’checksig’. As of 2006-03-28, the name of this
script should be ’checkdigest’. The name ’checksig’ should be consid-
ered deprecated for new packages.
A software distributor may choose to provide a checkdigest script.
The checkdigest script is part of the distribution object. It is
used to verify the directory form of a distribution (as distinguished
from installed_software). The verified attributes are the same as
those verified from the archive file form with the addition of the
distribution file list. In addition the script may chose to verify
the adjunct_md5sum and file.md5 digests and symbolic links. Due to
the constraints of reproducing the archive message digests from the
directory, which include tar utility dependence and file owner/group
specification, this script may not be useful to all distributors.
Execution Environment
The script may require the SW_CONTROL_TAG environment variable be set
to "checkdigest" or "checkfile" and if not exit with failure. swver-
ify will set this variable to "checkfile" if the --scm or --cvs option
is used, and otherwise to "checkdigest". The script may take differ-
ent action based on the value. Currently, the checkdigest script used
by the swbis source package will omit the archive digests checks if
set to SW_CONTROL_TAG="checkfile" since reproducing the archive digest
is not possible when the package is exported from CVS due to file sys-
tem meta-data non-preservation. In this case the file list is checked
and the md5 and sha1 digests are verified for each regular file.
VERIFYING SIGNATURES
The design separates the payload and catalog, therefore, verification
requires verifying the storage section md5 and sha1 message digests
and then verifying the signature of the catalog. Naturally, it is
required that the signed data include the storage section message
digests and that they match the storage sections. The storage section
digests are stored as separate attribute files in the dfiles catalog
directory.
The checksig (i.e. swverify -d @-) mode verifies a tarballs embedded
signature. This mode checks all the security files in the package and
is the preferred way to authenticate a package. The emit-signed-file,
emit-digest-file modes are useful for testing, sanity checks and cus-
tom applications. The get-sig-if is the function used when verifying
a tarball.
Verifying a POSIX Distribution Archive Manually
The design of the authentication attributes supports manual verifica-
tion of the archive file (e.g. tarball) form of the distribution, that
is verification take place on the uncompressed archive using ’gpg’,
GNU ’tar’ and the swbis utility ’swverify’ (or the library utility
’arf2arf’).
The authentication requires the following steps:
1) Obtain the signature from the package.
2) Recreate the signed data and present this byte stream and
the signature to GNU privacy guard (gpg) for authentication.
3) Obtain the message digest (md5, sha1,) contained in the
control file in the authenticated archive byte stream.
4) Recreate the digest byte stream and present to the appropriate
hash generation program to generate the message digest.
5) Compare the digest message generated in step 4 to the
authenicated digest obtained in step 3.
1) Obtain the signature from the package.
#!/bin/sh
tar zxf - -O \*/catalog/dfiles/signature < swbis-0.460.tar.gz
2) Recreate the signed data
#!/bin/sh
swverify -WC < swbis-0.460.tar.gz | gpg --verify /dev/tty -
# Cut and paste the signature file obtained in step 1
3) Obtain the message digest
#!/bin/sh
swverify -WC < swbis-0.460.tar.gz | tar xf - -O \*/catalog/dfiles/md5sum
4) Create the digested byte stream
#!/bin/sh
swverify -WS < swbis-0.460.tar.gz | md5sum
Verifying a POSIX Distribution Directory Manually
Verifying the unpacked tarball package form.
The design of the authentication attributes supports manual verifica-
tion of the directory (unpacked) form of the distribution, that is
verification takes place on the leading package directory and its con-
tents. It should be noted that it is left to the user to verify that
the archive installed no files outside of this directory as this would
likely indicate a trojan’ed package.
If authenticating on a GNU/Linux system using GNU tar it is possible
to validate the archive message digests and signature if the following
are true:
1) The package file is a tar archive.
2) The installed version of GNU tar produces archives with
bit-for-bit sameness relative to the swpackage(8) utility
that generated the signature and message digests. For packages
made with swbis versions >= 0.474 and with format option "ustar"
you will need GNU tar 1.14 or 1.15.*
3) The package has a single leading package directory, like a source
package.
4) The package catalog contains the ’checkdigest’ script.
5) The package catalog contains the distribution file list.
6) The ownership names are present and have the same uid’s and gid’s.
7) The package was unpacked with a version of tar that
preserves all file times. Use for example "tar xpf".
In this example, the package has a single path name prefix called,
namedir and the file owner/group are root. These restrictions are
suited to source packages.
Verify the signature:
#!/bin/sh
tar cf - -b1 --owner=root --group=root \
--exclude=namedir/catalog/dfiles/signature \
namedir/catalog | gpg --verify namedir/catalog/dfiles/signature -
If this fails try using GNU tar option --posix. If this fails then,
try experimenting with the owner, group, and numeric-id options. If
you are unable to verify a tar byte stream using gpg(1) that contains
the storage section message digests, then the package cannot be
authenticated.
Assuming you successfully verified the catalog as shown above, now
generate the message digest and compare it to the md5sum file
attribute from the same byte stream that gpg(1) claims is authenti-
cate.
#!/bin/sh
grep -v namedir/catalog namedir/catalog/dfiles/files | \
tar cf - -b1 --owner=root --group=root \
--files-from=- --no-recursion | md5sum
tar cf - -b1 --owner=root --group=root \
--exclude=namedir/catalog/dfiles/signature \
namedir/catalog | tar xf - -O namedir/catalog/dfiles/md5sum
Likewise for the sha1 digest.
If the package has symbolic links, Verify the adjunct_md5sum:
#!/bin/sh
grep -v namedir/catalog namedir/catalog/dfiles/files | \
( while read file; do if [ ! -h $file ]; then echo $file; fi done; )|\
tar cf - -b1 --owner=root --group=root \
--files-from=- --no-recursion | md5sum
cat namedir/catalog/dfiles/adjunct_md5sum
The symbolic link files must be verified manually by comparing to the
INFO file information.
Verifying a POSIX distribution in tar format
Below is output from successful authentication. The authentication
requires checking the archive md5 message digest (and sha1 if
present). All present message digests must succeed and if this is
true then the signed file is written and gpg proceeds to check the
signature. If the sig_header file is present then the requirement
that its data be identical to the ustar header of every signature file
is enforced. If any one of these checks fails, authentication fails.
#!/bin/sh
swverify --checksig mypackage-00.1.tar.gz
# - or -
swverify -d @- < mypackage-00.1.tar.gz
gpg: /home/userx/.gnupg/options:82: deprecated option "honor-http-proxy"
gpg: please use "keyserver-options honor-http-proxy" instead
gpg: WARNING: using insecure memory!
gpg: please see http://www.gnupg.org/faq.html for more information
swbis: Archive digest: md5 OK (Good)
swbis: Archive digest: sha1 OK (Good)
gpg: Signature made Sun Mar 16 20:28:23 2003 EST using DSA key ID 82B0DBE4
gpg: Good signature from "Test User (pass=Iforgot) localhost>"
Primary key fingerprint: 77BB A98E B3A2 ED4C 217E 8A25 2BF4 28AB 82D0 DDE4
Verifying the Directory Form of a Distribution
Authenticating using ’swverify’ is subject to the same constraints as
verifying manually using GNU tools because swverify implements this
using GNU tools.
’swverify’ when verifying the directory form of a distribution
attempts to authenticate the exported catalog signature. If it is
successful it executes the ’checkdigest’ script found in the ’cata-
log/dfiles’ directory of the exported catalog. If the ’checkdigest’
script does not exist, authentication fails. ’swverify’ will only
attempt to run the ’checkdigest’ script if it is found in the dfiles
directory of an authenticated catalog.
’swverify’ currently has no provision to verify the archive section
(i.e. the file storage structure) of a directory (unpacked) form of a
POSIX distribution. It is the role of the checkdigest script to do
this.
For example, if filemypackage-00.1 is a directory unpacked with a tar
reading utility that preserved file times then try,
#!/bin/sh
swverify --checksig mypackage-00.1
or change directory into mypackage-00.1 and use the POSIX syntax:
swverify -d @.
swverify -d @‘pwd‘/mypackage-00.1
Below is example output of a package with a ’checksig’ script.
swverify: Attempting to verify using --posix tar option.
gpg: /home/userx/.gnupg/options:82: deprecated option "honor-http-proxy"
gpg: please use "keyserver-options honor-http-proxy" instead
gpg: WARNING: using insecure memory!
gpg: please see http://www.gnupg.org/faq.html for more information
gpg: Signature made Sun Mar 16 21:00:54 2003 EST using DSA key ID 82B0DBE4
gpg: BAD signature from "Test User (pass=Iforgot) localhost>"
swverify: First attempt failed.
swverify: Attempting to verify without using --posix tar option.
gpg: /home/jhl/.gnupg/options:82: deprecated option "honor-http-proxy"
gpg: please use "keyserver-options honor-http-proxy" instead
gpg: WARNING: using insecure memory!
gpg: please see http://www.gnupg.org/faq.html for more information
gpg: Signature made Sun Mar 16 21:00:54 2003 EST using DSA key ID 82B0DBE4
gpg: Good signature from "Test User (pass=Iforgot) localhost>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: 77BB A98E B3A2 ED4C 217E 8A25 2BF4 28AB 82D0 DDE4
swverify: GPG signature verified.
swverify: Got it!
swverify: The vendor extension script checksig can now be executed.
checksig: Checking files OK (Good)
checksig: Checking Archive md5 OK (Good)
checksig: Checking Archive sha1 OK (Good)
gpg: /home/userx/.gnupg/options:82: deprecated option "honor-http-proxy"
gpg: please use "keyserver-options honor-http-proxy" instead
gpg: WARNING: using insecure memory!
gpg: please see http://www.gnupg.org/faq.html for more information
gpg: Signature made Sun Mar 16 21:00:54 2003 EST using DSA key ID 82B0DBE4
gpg: Good signature from "Test User (pass=Iforgot) localhost>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: 77BB A98E B3A2 ED4C 217E 8A25 2BF4 28AB 82D0 DDE4
checksig: Signature proper OK (Good)
checksig: /usr/bin/gpg exit status : 0
Verifying Installed Software
(This capability is only partially implemented.) Verifying Installed
Software involves comparing the package meta-data to the live file
system. The validity of a successful comparison depends on the valid-
ity of the installed software catalog. swverify makes no attempt to
check the validity of the entire catalog, however, it can use the
distribution GPG signature, which is stored in the catalog, to authen-
ticate the meta-data of the selected package.
Below is an example. Note, the package is selected on the basis of its
product or bundle tag.
$ swverify -r your_product_tag @ /
swverify: verifying installed software at:
swverify: //var/lib/swbis/catalog/swbis/your_product_tag/0.000/0
gpg: WARNING: --honor-http-proxy is a deprecated option.
gpg: please use "--keyserver-options honor-http-proxy" instead
gpg: Signature made Fri Feb 20 00:21:00 2004 EST using DSA key ID 82B0DBE4
gpg: Good signature from "Test User (pass=Iforgot) localhost>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Fingerprint: 77BB B98D A3A2 ED4C 217E 9A25 8BF4 05AB 82B0 DBE4
swverify: Warning: file checks not implemented
swverify: signature verification return status=0
Create the digest byte stream -Wemit-digest-file mode:
Here are some examples that verify the archive digests.
#!/bin/sh
cat your-tarball | swverify -Wd -WS | md5sum
Your should see a pair of identical digests. Use the -Wsha1 option to
check the sha1 digest in a similar manner.
** IMPORTANT **
This does not mean that the data is authenticate in the sense of being
attributable to a person, merely that the md5sum attribute and the
payload byte stream match.
To inspect the digested data, try:
#!/bin/sh
cat your-tarball | swverify -WS | tar tvf -
Create the signed byte stream -Wemit-signed-file mode:
Here is an example which allows inspection of the signed file.
cat your-tarball | swverify -WC | tar tvf -
-Wget-sig-if mode:
This is the mode that is used internally when verifying a tarball.
Below is an example of using this mode manually.
#!/bin/sh
cat your-tarball | swverify -Wget-sig-if=/dev/tty | \
gpg --verify /dev/tty -
Now try to copy and paste the sigfile and gpg should attempt to verify
the signature.
Note: This verifies the md5 or sha1 digests before writing the
signed data to stdout. If the sha1 or md5 match fails then an
empty file is written to stdout.
EXAMPLES
Examples of verifying distributions and installed software.
Distribution Verification
* Verify a tar archive
swverify -d < foo-1.1.tar.gz
or
swverify -d @‘pwd‘/foo-1.1.tar.gz
or
swverify -d @:foo-1.1.tar.gz
or
cat foo-1.1.tar.gz | swverify -d @-
Note: --checksig and ’-d’ perform the same operations.
* Verify a unpacked distribution
swverify -d @‘pwd‘/foo-1.1
or
cd foo-1.1; swverify -d @.
or
swverify -d @:foo-1.1
Note: --checksig and ’-d’ perform the same operations.
* Verify an exported SCM Directory
# This is the same as directory verification except the ’--cvs’ option is needed.
Installed Software Verification
* Verify installed software
swverify -r foo.foo @/tmp/test
or
swverify -r foo.foo
Note: This will attempt to verify the GPG signature.
The POSIX operations are not yet implemented.
RETURN VALUE
Exit status of the checksig script or gpg utility for --checksig
directory operation. 0 if successful on all targets, 1 if failed on
all targets, 2 if failed on some targets.
FILES
None
APPLICABLE STANDARDS
IEEE Std 1387.2-1995 (ISO/IEC 15068-2:1999), Open Group CAE C701.
SEE ALSO
info swbis
sw(5), swign(1), swpackage(8), gpg(1), libexec/swbis/arf2arf
IDENTIFICATION
swverify: The verification utility of the swbis project.
Author: James Lowe, Jr. Email: jhlowe at acm.org
Version: 0.951
Last Updated: 2008-04-18
Copying: GNU Free Documentation License
BUGS
The signature file’s archive header (or data) is not part of the
signed data therefore it may be subject to undetectable tampering,
however, swverify does perform sanity checks on the pathname, permis-
sions and filetype if the sig_header file (See sw(5) manual page.) is
not present [due to being signed by a old swpackage version], and if
sig_header is present, swverify requires that it match the sig file
header. The ability to verify the unpacked directory form of the
package depends on many factors not immediately obvious, among them
are the tar header uname and gname, and whether they are preserved by
the reading utility, and whether these names are in the system
database files /etc/passwd and /etc/group, and if so, whether they
assign the same uid/gid as the package.
Verification of the directory form of a distribution (i.e. the
installed tarball path name prefix) such as running ’swverify -d @.’
after running ’swign @.’ will fail if the order of directory entries
is not compatible with traditional Unix file system directory entry
ordering, which is the order of file creation. This ordering is
almost always apparent on Ext2 file system for small directories (but
not always for big directories). Ext3, reiserFS, and DarwinOS et.al
file systems do not have this ordering, use of the ’--order-catalog’
option is therefore required. Use of the ’--cvs’ or ’--order-catalog’
options is theoretically problematic because it causes the use and
interpretation of data in the verification of that same data therefore
opening possible attack vectors.
swverify(8)
swign(1) swign(1)
NAME
swign — Create a tar archive of a directory with an embedded GPG sig-
nature.
SYNOPSIS
swign [options] [-u gpg-name] [--homedir=gpg-homedir] @-
swign [options] [-u gpg-name] [--homedir=gpg-homedir] @.
swign -S [options] [-u gpg-name] [--homedir=gpg-homedir]
DESCRIPTION
swign reads a PSF (Product Specfication File) and writes the coore-
sponding archive to stdout or into the current directory. The PSF is
read from standard input by default. To use an internally generated
PSF with name and revision attributes determined from the name of the
current directory use ’-s.’.
The PSF is scanned for replacement tokens for tag and revision
attributes determined from the current directoy name. It is expected
that the current directory name have the form: ’tag-revision’. The
replacement string has the form ’%__NAME’ where NAME is ’tag’ or
’revision’. The directory derived values can be overridden with the
’--revision’ or ’--name-version’ options.
swign does this by loading the ’./catalog/’ meta-data directory into
the current directory and then, using GNU tar and the distribution
file list, writing the archive to stdout. The result is a tar archive
written entirely with GNU tar that contains an embedded GPG signature
in the control file ’./catalog/dfiles/signature’. The contents of
’./catalog/’ are consistent with the POSIX packaging standard ISO/IEC
15068-2:1999. The package layout of the resulting archive is
unchanged except for the addition of the ’./catalog’ directory.
The contents of the archive is the contents of the current directory
".". The pathnames in the archive are prefixed by the base name of
".". The owner and group of all the files in the emitted archive are
specified by the PSF file and command line options.
In order for the signature to be valid, the file ownerships specified
in the PSF must be consistent with the ’swign’ command. swign will
read the PSF to determine these ownerships automatically from the
’file_permissions’ directive unless the ’-o’ or ’-g’ command line
options are used or if this feature is disabled using the ’--no-psf-
detect’ option is given.
The default ownerships for all the files are the current user’s owner
and group. If the -o (or -g) option is used with a empty string for
the option arg then the file ownerships of the source files are used.
This script assumes GNU tar is installed.
After writing the ./catalog/ file and before writing the archive, the
file list stored in ./catalog/dfiles/files is compared to the current
directory contents, if any difference is found the archive is not
written and error returned.
OPTIONS
--help
show help.
--show-psf
show the PSF to stdout, and then exit.
--no-psf-detect
Disable automatic detection of the PSF’s file ownerships pol-
icy.
--no-remove
Don’t remove the ./catalog directory before overwriting.
-u, --local-user name
Use name as the user ID to sign.
--homedir=DIR
Set the name of the home directory to DIR. If not specified
then use "~/.gnupg".
-s, --source=FILE
Specify a PSF file name or one of two special names, ’-’ for
stdin, and ’.’ for the internally generated PSF.
-T, --show-names-only
show some info (for help and debugging) and exit.
-t, --run-sanity-check
Instead of writing stdout, write the archive to ../pack-
ageDirName.swigntest.tar.gz and run some sanity tests.
-S, --sign-this
Write the ./catalog/ file containing the digest and signature
into "." and then exit without writing the archive to stdout.
Same as using "." as the target such as ’swign @.’
-D, --with-checkdigest FILE
Include the checkdigest control script sourced from FILE. This
is only needed when not supplying a PSF, that is this option
modifies an internally generated PSF.
-o, --owner OWNER
Specify owner. Use an empty string "" to specify the source
file owner.
-g, --group GROUP
Specify group. Use an empty string "" to specify the source
file group.
--name-version=NAME-REV
Specify a product tag and revision as dash delimited.
-r, --revision REV
Specify a product revision. This will override a revision part
of the current directory’s name.
-x format
Specify the archive format. Must be one of the formats of
swpackage.
@-
Target, only supported target is standard output.
EXTERNAL EFFECTS
The program will remove and replace a file in "." named ./catalog/.
Nothing outside of ’./catalog/’ is modified.
Standard output is the target for the tar archive.
When using the ’-t’ option an archive file is written to ../pack-
ageDirName.swigntest.tar.gz
A copy of the PSF is made in /var/tmp/swign$$. It is normally created
and erased by the program.
EXAMPLES
Show the internally generated PSF to stdout. Change directory into
the directory to package, then type
swign -s. --show-psf
#
# or specify a owner and group policy
swign -s. -o 0 -g 0 --show-psf
Create a signed metadata (i.e. catalog/) directory of a live direc-
tory, for example /bin
swign -D $HOME/checkdigest.sh -u "YourGPGNAME" -o "" -g "" @.
Generate the package (and verify it) using a PSF that you supply on
standard input. Change directory into the directory to package, then
type
swign -o 0 -g 0 --show-psf | swign -s - -u "gpgName" @- | swverify -d @-
TESTING
After running successfully with options -S and -D FILE the following
should be true (report no error).
swverify --checksig . # Deprecated form
-or-
swverify -d @. # POSIX syntax
Similarly,
swign -u "your GPG Name" @- | swverify --checksig -
-or-
swign -u "your GPG Name" @- | swverify -d @-
If a checkdigest script is included then you should unpack the package
at a new location and run swverify -d @. in the new location. The
checkdigest script is a vendor extension control file that is part of
the GPG signed ./catalog directory. As an implementation extension
behavior the swverify program will execute this script after verifica-
tion of the signature. The script may take any action at this point,
but the intention is that it be used to verify the contents of the
package directory using GNU tools such as md5sum, sha1sum, and tar.
If a checkdigest script is not included, then the package user will
have to manually execute the commands that would have been executed by
the script using the file meta-data in an authenticated INFO file.
When verifying the unpacked directory form of a package, the swverify
program will return an error if the checkdigest script is not present,
though, it is not required for verification of the tar archive file
itself using swverify.
Swign can be used to sign any directory using the file ownerships of
the source files. The following commands act as a test of swpackage’s
ability to generate an archive identical to GNU tar. (Note: the
script checkdigest.sh is found in ./bin of the source distribution.)
swign -D $HOME/checkdigest.sh -u "Test User" -o "" -g "" -S;
swverify -d @.
PSF ATTRIBUTE REPLACEMENT
A PSF that is provided using the ’-s’ option will be scanned for a
special character sequence ’%__NAME’ where NAME is either ’tag’ or
’revision’. ’tag’ is replaced with the package name portion of the
currrent directory. ’revision’ is replaced with the version portion.
SAMPLE SOURCE PACKAGE PSF
# PSF.in -- INPUT file to swign
# This file contains the replacement macros %__tag and %__revision which
# are only processed by swign.
# The distribution object need not have any attributes.
distribution
# Attributes in the distribution are mostly ignored although
# distributor control files that pertain to the distribution
# as a whole are properly placed here. Two examples of files
# that are useful here are:
AUTHORS < AUTHORS # This places the file in ./catalog/dfiles
COPYING < COPYING # This places the file in ./catalog/dfiles
# This places the checkdigest script in ./catalog/dfiles/checkdigest
# For a description of the checkdigest script see the info document for
# ’swbis’ or the swverify manual page.
# The checkdigest script is a verification hook for swverify used when
# verifying the unpacked tarball (i.e. the package path name
# prefix directory).
checkdigest < bin/checkdigest.sh
# The vendor object provides attributes to describe
# the distributor. At this time, how these attributes
# are used is not addressed.
# The Vendor object is optional
vendor
the_term_vendor_is_misleading True # One of: True, False
tag shortName # Other vendor tags could be the short name of your
# organization name, or your initials, etc.
title Your Name
qualifier author
description "Maintainer of somepackage"
# Most packages do not need a bundle. At this point in swbis’
# development ’bundles’ are mostly ignored. Bundles are meta
# packages, it is an object that contains other bundles and
# products whether included in this distribution tarball or not.
# The Bundle object is optional
bundle
tag somepackage
# The product object contains the attributes of common
# interest such as the description, version and name.
product
description "somepackage description
can be mult-line"
tag %__tag # This is the package name
revision %__revision # This is the package version
vendor_tag shortName # Match vendor.tag above
title "somepackage - software"
control_directory "" # Empty string, Important
# The fileset object contains the files. The tag, revision,
# and description attributes are mostly ignored.
# At this time swbis supports only one (1) fileset.
fileset
tag sources
control_directory "" # Empty string, Important
title somepackage source code
description "The source distribution of somepackage"
# file_permissions:
# Here is an important policy. This will cause ’swpackage’
# to create the tar achive with all files owned by uid and
# gid zero (0), the user name ’root’ will not be included
# in the uname and gname tar header fields. This is similar
# to the effect of GNU tar options --numeric --owner=root
# --group=root .
# To use the name and ids of the source files delete the line
# or reset the file_permissions adding after or changing to:
# file_permissions -u 000
#
# NOTE: Using "file_permissions -o 0 -g 0" is preferred
# because it will allow the end user to more easily verify
# the directory (unpacked) form of the package using standard
# non-swbis tools.
# file_permissions -u 000 # To use ownerships of source files
file_permissions -o 0 -g 0
# The following two (2) lines mean include every file in the current
# directory.
directory .
file *
# You want to exclude the files in ./catalog because it
# should not be part of the paylaod section. This is
# mandatory.
exclude catalog
# You may also want other excludes
exclude CVS
exclude */CVS
# exclude .svn
# exclude */.svn
# End of PSF
ENVIRONMENT
SWPACKAGEPASSFD
Sets the swpackage --passphrase-fd option. Set the option arg
to a integer value of the file descriptor, or to "env" to read
the passphrase from the environment variable SWPACK-
AGEPASSPHRASE, or to "agent" to cause gpg to use gpg-agent, or
"tty" to read from the terminal.
SWPACKAGEPASSPHRASE
Use the value as the passphrase if swpackage’s --passphrase-fd
is set to "env"
GNUPGHOME
Sets the --gpg-home option of swpackage.
GNUPGNAME
Sets the --gpg-name option of swpackage, which is turn set the
--local-user option of gpg.
RETURN VALUE
0 on success, non-zero on failure.
FILES
<path>/catalog/
SEE ALSO
info swbis
swpackage(8), gpg
IDENTIFICATION
swign(1): The source directory signing utility of the swbis project.
Author: J. Lowe jhlowe@acm.org
Version: 0.951
Last Updated: 2008-01
Copying: GNU Free Documentation License
BUGS
Symbolic links in a package are problematic for verifying the unpacked
form of a package since the modification time is not preserved. They
have no affect on verification of the tar archive file using ’swver-
ify’.
If a directory is signed using the ’-S’ option and has a file path
greater than 99 chars in length then it will be unverifiable if the
’ustar0’ format and GNU tar 1.13.25 was used.
Verification of the directory form of a distribution (i.e. the
installed tarball path name prefix) such as running ’swverify -d @.’
after running ’swign -S’ will fail if the order of directory entries
is not compatible with traditional Unix file system directory entry
ordering. This incompatibility may be present in the Ext3, reiserFS,
and DarwinOS et.al file systems.
The file ownership policy of the PSF, the checkdigest script (if any)
and the command line options must agree. The default file ownership
policies of this program are suited to packaged products where file
user and group ownerships are not a critical feature.
swign(1)
LXPSF(1) LXPSF(1)
NAME
lxpsf - Translate package to a portable Unix format with a PSF.
SYNOPSIS
lxpsf [options] [package_file]
DESCRIPTION
Lxpsf reads the input package and writes a tar or cpio archive to std-
out, depending on the native (or encapsulated) format of the input
package. The output layout has a single leading directory named
according to the name, version, and release attributes.
The first regular file is ‘‘PSF’’, and is a IEEE 1387.2-1995 (ISO/IEC
15068-2:1999) Product Specification File containing the package meta-
data. Subsequent files are control data represented as files, and,
the files of the distribution. The output is designed so the swpack-
age utility is able to form a Posix package from the installed output.
Currently, only RPM format is supported.
Options
-p ,--psf-only
Write only the psf file to stdout.
-A ,--psf-form1
A PSF form for RPM translation.
-A ,--psf-form2
A second PSF form for RPM translation.
-H format
Force the specified format. The choices are currently
(only) ustar.
-x ,--use-recursive-fileset
Use "file *" instead of individual file definitions in
the PSF.
-r ,--no-leading-path
use "." as the leading archive path.
-o ,--info-only
Write the INFO file for the rpm archive to stdout.
-D ,debug-level=TYPE
Always set to "link"
HOWTO Use with swpackage
Either install into file system or use the -W source=- option
of GNU swpackage.
cat your_rpm.rpm |
lxpsf --format=ustar --psf-form2 |
(mkdir /tmp/swbis; cd /tmp/swbis && tar xpf -; exit $?) &&
(cd /tmp/swbis && swpackage -s PSF @- ) | tar tvf -
cat your_rpm.rpm |
lxpsf --format=ustar --psf-form2 |
swpackage -W source=- -s@PSF @- | tar tvf -
FILES
RELATED STANDARDS
POSIX.1, IEEE 1387.2, XDSA C701
IDENTIFICATION
The RPM translation program of the swbis project.
DATE: 2005-10-22
Revision: 0.470
SEE ALSO
swbisparse(1), swpackage(8)
BUGS
Probably many. A de-facto conversion policy is intimated in the
PSF by this program.
LXPSF(1)
swpackage(5) swpackage(5)
NAME
swpackage — file formats
SYNOPSIS
Output format - Data Interchange Formats
Input format - Product Specification File (PSF)
SWPACKAGE OUTPUT FORMAT
The output format is either one of two formats specified in POSIX.1
(ISO/IEC 9945-1) which are tar (header magic=ustar) or cpio (header
magic=070707). The default format of the swbis implementation is
"ustar". The POSIX spec under specifies definitions for some of the
ustar header fields. The personality of the default swbis ustar for-
mat mimics GNU tar 1.15.1 and is designed to be compliant to POSIX.1.
The personality of the "ustar0" format mimics, for pathnames less than
99 octets, GNU tar 1.13.25 using the "-b1 --posix" options. This
bit-for-bit sameness does not exist for pathnames greater than 99
chars as swbis follows the POSIX spec and GNU tar 1.13.25 does not.
The "ustar0" ustar personality is deprecated. It is only slightly
different from ’ustar’ in how device number fields are filled (with
spaces, zeros or NULs) for non-device files.
In addition the swbis implementation supports several other tar vari-
ants including bit-for-bit mimicry of GNU tar (1.13.25) default format
which uses a non-standard name split and file type (type ’L’). This
format is known as ’--format=oldgnu’. Also supported is the gnu for-
mat of GNU tar 1.15.1 specified by ’--format=gnu’
The defacto cpio formats are also supported. "new ASCII" (sometimes
called SVR4 cpio) and "crc" cpio formats with header magic "070701"
and "070702" respectively.
Support for "pax Interchange Format" (Extended header tar) described
in IEEE 1003.1-2001 under the "pax" manual page is planned.
The entirety of the output byte stream is a single valid file of one
the formats mentioned above.
The swbis implementation writes its output to stdout. The default
output block size is 10240 bytes. The last block is not padded and
therefore the last write(2) may be a short write. The selected block
size does not affect the output file contents.
The swbis implementation is biased, in terms of capability and default
settings, to the tar format. Package signing is only supported in tar
format.
SWPACKAGE INPUT FILE FORMAT
The input file is called a product specification file or PSF. It con-
tains information to direct swpackage and information that is package
meta-data [that is merely transferred unchanged into the global INDEX
file].
A PSF may contain object keywords, attributes (keyword/value pairs)
and Extended Definitions (described below). An object keyword con-
notes a logical object (i.e. software structure) supported by the
standard. An object keyword does not have a value field after it, as
it contains Attributes and Extended Definitions. An attribute keyword
conotes an attribute which is always in the form of a keyword/value
pair.
Attribute keywords not recognized by the standard are allowed and are
transferred into the INDEX file. Object keywords not recognized by
the standard are not allowed and will generate an error. Extended
Definitions may only appear in a PSF (never in a INDEX or INFO created
by swpackage). Extended Definitions are translated [by swpackage]
into object keywords (objects) and attributes recognized by the stan-
dard.
Comments in a PSF are not transferred into the INDEX file by the swbis
implementation of swpackage.
The file syntax is the same as a INDEX, or INFO file. A PSF may con-
tain all objects defined by the standard as well as extended defini-
tions.
For additional information see
XDSA C701 http://www.opengroup.org/publications/catalog/c701.htm, or
sw manual page.
EXTENDED DEFINITIONS
A Product Specification File (PSF) can contain Extended Definitions in
the fileset, product or bundle software definitions. They would have
the same level or containment relationship as a file or control_file
definition in the same contaning object.
Extended Definitions represent a minimal, expressive form for specify-
ing files and file attributes. Their use in a PSF is optional in that
an equivalent PSF can be constructed without using them, however,
their use is encouraged for the sake of brevity and orthogonality.
The swbis implementation requires that no [ordinary] attributes appear
after Extended Definitions in the containing object, and, requires
that Extended Definitions appear before logically contained objects.
That is, the parser uses the next object keyword to syntacticly and
logically terminate the current object even if the current object has
logically contained objects.
o Extended Control File Definitions
checkinstall source [path]
preinstall source [path]
postinstall source [path]
verify source [path]
fix source [path]
checkremove source [path]
preremove source [path]
postremove source [path]
configure source [path]
unconfigure source [path]
request source [path]
unpreinstall source [path]
unpostinstall source [path]
space source [path]
control_file source [path]
The source attribute defines the location in distributors’s develop-
ment system where the swpackage utility will find the script. The
keyword is the value of the tag attribute and tells the utilities when
to execute the script. The path attribute is optional and specifies
the file name in the packages distribution relative to the con-
trol_directory for software containing the script. If not given the
tag value is used as the filename.
o Directory Mapping
directory source [destination]
Applies the source attribute as the directory under which the subse-
quently listed files are located. If destination is defined it will
be used as a prefix to the path (implied) file definition. source is
typically a temporary or build location and dest is its unrealized
absolute pathname destination.
o Recursive File Definition
file *
Specifies every file in current source directory. The directory
extended definition must be used before the recursive specification.
o Explicit File Definition
file [-t type] [-m mode] [-o owner[,uid]] [-g group[,gid]] [-n] [-v] source [path]
source
source defines the pathname of the file to be used as the
source of file data and/or attributes. If it is a relative
path, then swpackage searches for this file relative to the the
source argument of the directory keyword, if set. If directory
keyword is not set then the search is relative to the current
working directory of the swpackage utility’s invocation.
All attributes for the destination file are taken from the
source file, unless a file_permissions keyword is active, or
the -m, -o, or -g options are also included in the file speci-
fication.
path
path defines the destination path where the file will be cre-
ated or installed. If it is a relative path, then the destina-
tion path of the of the directory keyword must be active and
will be used as the path prefix. If path is not specified then
source is used as the value of path and directory mapping
applied (if active).
-t type
type may one of ’d’ (directory), or ’h’ (hard link), or ’s’
(symbolic link).
-t d Create a directory.
If path is not specified source is used as the path attribute.
-t h Create a hard link.
path and source are specified. source is used as the value of
the link_source attribute, and path is the value of the path
attribute.
-t s Create a symbolic link.
path and source are specified. source is used as the value of
the link_source attribute, and path is the value of the path
attribute.
-m mode
mode defines the octal mode for the file.
o Default Permission Definition
file_permissions [-m mode] [-u umask] [-o [owner[,]][uid]] [-g [group[,]][gid]]
Applies to subsequently listed file definitions in a fileset. These
attributes will apply where the file attributes were not specified
explicitly in a file definition. Subsequent file_permissions defini-
tions simply replace previous definitions (resetting all the options).
To reset the file_permission state (i.e. turn it off) use one of the
following:
file_permissions ""
or the preferred way is
file_permissions -u 000
o Excluding Files
exclude source
Excludes a previously included file or an entire directory.
o Including Files
include <filename
The contents of filename may be more definitions for files. The syn-
tax of the included file is PSF syntax.
SWBIS PSF CONVENTIONS
This section describes attribute usage and conventions imposed by the
swbis implementation. Not all attributes are listed here. Those that
are have important effects or particular interest.
o Distribution Attributes
The standard defines a limited set of attributes for the distribution
object. An expanded set is suggested by the informative annex however
a conforming implementation is not required act on them. The reason
for this is a distribution may be acted upon by a conforming utility
in such a way that attributes of the distribution become invalid. For
this reason, some attributes that refer to an entire "package" [in
other package managers] are referred from the product object and
attain their broadened scope by the distributor’s convention that
their distribution contains just one product.
For example, the package NAME and VERSION are referred from the prod-
uct tag and revision, not the distribution’s. This convention sup-
ports multiple products in a distribution and is consistent with the
standard.
tag
tag is the short, file system friendly, name of the distribu-
tion. Providing a distribution tag is optional. The swbis
implementation will use this as the [single] path name prefix
if there is no distribution.control_directory attribute. A
distribution tag attribute and swpackage’s response to it is an
implementation extension. The leading package path can also be
controlled with the ’’-W dir’’ option.
control_directory
control_directory, in a distribution object, is the constant
leading package path. Providing this attribute is optional. A
distribution control_directory attribute and swpackage’s
response to it is an implementation extension. The leading
package path can also be controlled with the ’’-W dir’’ option.
This attribute will be generated by swpackage if not set in a
PSF.
o Bundle Attributes
A bundle defines a collection of products whether or not the distribu-
tion has all the products present.
tag
tag is the short, file system friendly, name of the bundle.
This value is used by the swbis implementation as a path name
component in the installed software catalog. If it is not
present the product tag is used.
o Product Attributes
A product defines the software product.
tag
tag is the short, file system friendly, name of the product.
This value is used by the swbis implementation as a path name
component in the installed software catalog. It is required.
The swbis implementation uses it in a way that is analogous to
the RPMTAG_NAME attribute, namely as the public recognizable
name of the package.
control_directory
Is the directory name in the distribution under which the prod-
uct contents are located. This value has no affect on the
installed software catalog. If it is not given in a PSF then
the tag is used.
revision
Is the product revision. It should not contain a "RELEASE"
attribute part or other version suffix modifiers. This value
is used by the swbis implementation as a path name component in
the installed software catalog. It is required by swinstall.
vendor_tag
This is a short identifying name of the distributor that sup-
plied the product and may associate (refer to) a vendor object
from the INDEX file that has a matching tag attribute. This
attribute is optional. This attribute value should strive to
be unique among all distributors. The swbis implementation mod-
ifies the intended usage slightly as a string that strives to
be globally unique for a given product.tag and product.revi-
sion. In this capacity it serves to distinguish products with
the same revision and tag from the same or different distribu-
tor. It most closely maps to the RPMTAG_RELEASE or
"debian_revision" attributes. It is one of the version distin-
guishing attributes of a product specified by the standard. It
is transfered into the installed_software catalog (not as a
path name component) by swinstall. If this attribute exists
there should also be a vendor object in the PSF in the distri-
bution object that has this tag. This attribute is assigned
the value of RPMTAG_RELEASE by swpackage when translating an
RPM.
architecture
This string is one of the version attributes. It is used to
disambiguate products that have the same tag, revision and ven-
dor_tag. It is not used for determining a products compatibil-
ity with a host. The form is implementation defined. swbis
uses the output of GNU config.guess as the value of this
string. A wildcard pattern should not be used. The canonical
swbis architecture string can be listed with swlist. For exam-
ple
swlist -a architecture @ localhost
Here are some example outputs from real systems.
System ‘uname -srm‘ architecture
Red Hat 8.0: Linux 2.4.18 i686 i686-pc-linux-gnu
OpenSolaris: SunOS 5.11 i86pc i386-pc-solaris2.11
NetBSD 3.1: NetBSD 3.1 i386 i386-unknown-netbsdelf3.1
Red Hat 4.1: Linux 2.0.36 i586 i586-pc-linux-gnulibc1
Debian 3.1: Linux 2.6.8-2-386 i686 i686-pc-linux-gnu
os_name os_release os_version machine_type
These attributes are used to determine compatibility with a
host. They correspond to the uname attributes defined by
POSIX.1. If an value is nil or non-existent it is assumed to
match the host. All attributes must match for there to be com-
patibility. Distributors may wish to make these values a shell
pattern in their PSF’s so to match the intended collection of
hosts. swbis uses fnmatch (with FLAGS=0) to determine a match.
o Fileset Attributes
A fileset defines the fileset.
tag
tag is the short, file system friendly, name of the fileset.
It is required although selection of filesets is not yet sup-
ported therefore the end user will have little to do with the
fileset tag.
control_directory
Is the directory name in the product under which the fileset
contents are located. This value has no affect on the
installed software catalog. If it is not given in a PSF then
the tag is used.
o Example Source Package PSF
This PSF packages every file is current directory. It uses nil control
directories so the package structure does not change relative to a
vanilla tarball.
distribution
description "fooit - a program from fooware
that does everything."
title "fooit - a really cool program"
COPYING < /usr/local/fooware/legalstuff/COPYING
vendor
the_term_vendor_is_misleading false
tag fooware
title fooware Consultancy Services, Inc.
description ""
vendor
the_term_vendor_is_misleading true
tag myfixes1
title Bug fixes, Set 1
description "a place for more detailed description"
product
tag fooit
control_directory ""
revision 1.0
vendor_tag myfixes1 # Matches the vendor object above
fileset
tag fooit-SOURCE
control_directory ""
directory .
file *
exclude catalog
o Example Runtime (Binary) Package PSF
This is a sample PSF for a runtime package. It implies multiple prod-
ucts (e.g. sub-packages) using the bundle.contents attribute. Since
the bundle and product tags exist in a un-regulated namespace and are
seen by end users they should be carefully chosen. Note that the
bundle and product have the same tag which may force downstream users
to disambiguate using software selection syntax such as fooit,bv=* or
fooit,pv=* .
distribution
description "fooit - a program from fooware
that does everything."
title "fooit - a really cool program"
COPYING < /usr/local/fooware/legalstuff/COPYING
vendor
the_term_vendor_is_misleading false
tag fooware
title fooware Consultancy Services, Inc.
description "Provider of the programs
that do everything"
vendor
the_term_vendor_is_misleading true
tag fw0
title fooware fixes
description "More fixes from the fooware users"
# Bundle definition: Use a bundle
bundle
tag fooit
vendor_tag fooware
contents fooit,v=fw0 fooit-devel fooit-doc
# Product definition:
product
tag fooit # This is the package name
revision 1.0 # This is the package version
vendor_tag fw0 # This is a release name e.g. RPMTAG_RELEASE
postinstall scripts/postinstall
fileset
tag fooit-RUN
file doc/man/man1/fooit.1 /usr/man/man1/fooit.1
file src/fooit /usr/bin/fooit
APPLICABLE STANDARDS
POSIX.1, IEEE Std 1387.2-1995 (Identical to ISO 15068-2:1999), Open
Group CAE C701.
SEE ALSO
XDSA C701 http://www.opengroup.org/publications/catalog/c701.htm
info swbis
sw(5)
swpackage(8)
swbisparse(1) -- An implementation extension parser utility.
IDENTIFICATION
Copyright (C) 2004,2005 Jim Lowe
Version: 0.951
Last Updated: 2006-07-01
Copying Terms: GNU Free Documentation License
BUGS
None
swpackage(5)
sw(5) sw(5)
NAME
sw — POSIX Software Packaging
SYNOPSIS
Software Packaging Layout
Software Definitions
Software Selections
Extended Definitions
Distributor Keywords
Package Security
Software Definition Files: INFO, INDEX, PSF
Example Package
SOFTWARE PACKAGING LAYOUT
A package may exist in two forms: as a directory in a file system, or
a serial access tar or cpio archive file. A package consists of two
main sections: 1) the exported catalog structure, and, 2) the software
file storage structure. Each section may contain path name components
which serve to segregate distribution, product and fileset objects.
Shown below is an example with one (1) product and one (1) fileset.
<path>/
<path>/catalog/
<path>/catalog/INDEX
<path>/catalog/<dfiles>
<path>/catalog/<dfiles>/...
<path>/catalog/<prod_dir>/
<path>/catalog/<prod_dir>/<pfiles>/INFO
<path>/catalog/<prod_dir>/<pfiles>/...
<path>/catalog/<prod_dir>/<fileset_dir>/
<path>/catalog/<prod_dir>/<fileset_dir>/INFO
<path>/catalog/<prod_dir>/<fileset_dir>/...
<path>/catalog/<prod_dir>/<fileset_dir>/<script>
<path>/<prod_dir>/
<path>/<prod_dir>/<fileset_dir>/
<path>/<prod_dir>/<fileset_dir>/<distribution_files>
<path>/<prod_dir>/<fileset_dir>/<distribution_files>/...
The exported catalog structure consists of the files with pathnames
that begin <path>/catalog. Note that catalog is not a legal prod_dir
name. Also, "dfiles", and "pfiles" should not be used as control
directory names, they are the default names for the Distribution and
Product files directories. The dfiles and pfiles defaults are com-
monly accepted.
The order of files in a serial access archive is specified and shown
above. The order of products and filesets within a product is not
specified, although they must be grouped together. Notably, the INDEX
file is the first regular file in the package, followed by the
<dfiles> directory. For each product, the <prod_dir> is followed
immediately by the <prod_dir>/<pfiles> directory.
Minimal Package Layout
To support extant usage of tar archives, this implementation supports
a minimal package layout. The layout is non-intrusive to the current
practice of extracting a ’binary’ package in the ’/’ directory where
<path>/ is nil and, likewise to ’source’ packages where <path> is typ-
ically the package name and version. The use of nil control directo-
ries is not attested to in the POSIX standard.
<path>/
<path>/catalog/
<path>/catalog/INDEX
<path>/catalog/dfiles/
<path>/catalog/dfiles/INFO
<path>/catalog/dfiles/...
<path>/catalog/pfiles/INFO
<path>/catalog/pfiles/...
<path>/catalog/INFO
<path>/<distribution_files>/...
In this layout a single product and fileset have control_directory
attributes specified as an empty string.
Distribution Files
catalog/<dfiles>/...
<dfiles> is the value of the dfiles attribute and the default value is
"dfiles". This directory can store an INDEX file or INFO file per-
taining to the distribution. It can also store an attribute of the
distribution as a separate file where file name is the name of the
attribute and the file contents the value.
Product Files
catalog/<prod_dir>/<pfiles>/...
<pfiles> is the value of the pfiles attribute and the default value is
"pfiles". This directory can store an INFO file pertaining to the
product control_files, control scripts defined in the INFO file, and
all other distributor-defined control_files. It can also store an
attribute of the product as a separate file.
Fileset Files
catalog/<prod_dir>/<fileset_dir>/...
This directory contains information in the same form as does the Prod-
uct Files although pertaining to the fileset.
Control Directory Names
The <prod_dir>/<fileset_dir> names are the values of the con-
trol_directory attribute for the product and fileset respectively.
The default value is the value of the tag attribute. <prod_dir> must
be unique within a distribution and <fileset_dir> must be unique
within a product.
File Storage
<prod_dir>/<fileset_dir>/<distribution_files>/...
The listing of control directories in the exported catalog structure
is repeated and files of the distribution appear under these directo-
ries in a location determined by the metadata.
The standard does not require that files that are not regular files
appear in the storage section.
SOFTWARE DEFINITIONS
The Software Definitions are metadata representations of the objects
and attributes recognized by the standard. The right hand column in
each definition shows the default attribute value. The defining stan-
dard for each attribute is indicated as a comment (leading ’#’ sign)
if it is not IEEE-1387.2, other defining standards are XDSA C701
(C701), and, this implementation (impl.).
Host Definition
host
hostname hostname None
os_name os_name None
os_release os_release None
os_version os_version None
machine_type machine_type None
The host definition was attested to only in the informative annex of
the standard. An implementation may chose to define this class.
A host object can contain a distribution, or installed_software
object.
Distribution Definition
distribution
layout_version layout_version 1.0
path path Implementation Defined
dfiles dfiles dfiles
pfiles pfiles pfiles
uuid uuid Empty string
The path attribute is not in a PSF nor INDEX files. A PSF does not
contain a uuid attribute. An INDEX file will contain a layout_version
attribute as the first attribute.
A distribution object can contain bundles, products, and, media in the
form of software definitions.
The following attributes are recognized as valuable by the Informative
Annex of POSIX.7.2.
tag tag Empty string
title title Empty string
description description Empty string
revision revision Empty string
media_type media_type Empty string
copyright copyright Empty string
create_time create_time Empty string
number number Empty string
architecture architecture Empty string
The following attributes are recognized by this implementation.
signature < pathname None # impl.
sig_header < pathname None # impl.
sha1sum < pathname None # impl.
sha512sum < pathname None # impl.
md5sum < pathname None # impl.
adjunct_md5sum < pathname None # impl.
files < pathname None # impl.
control_directory control_directory Empty string # impl.
owner name root # impl.
group name root # impl.
mode mode 0755 # impl.
signer_pgm utility_name GPG # impl.
signer_pgm_version version 1 # impl.
tar_format_emulation_options program_options # impl.
tar_format_emulation_utility software spec # impl.
The url attribute is the universal record locator of the packager
qualified vendor. The control_directory attribute in the distribution
object appears as the <path> leading directory path in the a serial
archive package. The owner, group, and mode attributes control the
file attributes of the single path name prefix. The signature,
sig_header, md5sum, and adjunct_md5sum attributes are described below
and are stored as separate files in the dfiles directory. The tar_for-
mat_emulation_* options define the GNU tar version and format options
that the archive file mimics, these attributes are used by the ’check-
digest’ script.
Installed_software Definition
installed_software
layout_version layout_version 1.0
path path Implementation Defined
dfiles dfiles dfiles
pfiles pfiles dfiles
catalog catalog Undefined
install_time install_time Undefined # impl.
A software object can be listed (written to stdout) in the form of an
INDEX file by the swlist utility.
Media Definition
media
sequence_number sequence_number 1
An INDEX file must contain the sequence_number attribute if the dis-
tribution spans multiple media.
Vendor Definition
vendor
the_term_vendor_is_misleading true True or False #impl
tag tag Empty string
title title Empty string
description description Empty string
qualifier qualifier Empty string # impl.
url url Empty string # impl.
vendor_tag tag Empty string # impl.
The tag attribute is required. The the_term_vendor_is_misleading is
required in a PSF file to avert a (harmless) warning, please use it.
It exists to allow persons, for example, who are distributors (of
existing free software) to qualify themselves away from the connota-
tions of a "vendor" which has specific meaning not applicable to a
free software distributor. A INDEX and PSF files can contain vendor
definitions. The vendor_tag attribute contains the vendor.tag of the
upstream distributor. The qualifier attribute value may be one of:
seller, author, packager, maintainer. A distribution may have more
than one vendor definition. They may form a chain of references from
the product.vendor_tag to the last vendor referred to by the ven-
dor.vendor_tag attributes.
Bundle Definition
bundle
tag tag architecture architecture Empty string
location location <bundle.directory>
qualifier qualifier Empty string
revision revision Empty string
vendor_tag vendor_tag Empty string
create_time create_time None
description description Empty string
contents contents Empty string
copyright copyright Empty string
directory directory Empty string
instance_id instance_id 1
is_locatable is_locatable true
layout_version layoyt_version 1.0
machine_type machine_type Empty string
mod_time mod_time Empty string
number number Empty string
os_name os_name Empty string
os_release os_release Empty string
os_version os_version Empty string
size size Empty string
title title Empty string
category_tag category_tag Empty list or patch # C701
is_patch is_patch false # C701
The tag and contents attributes are required in INDEX and PSF files.
The size attribute is not allowed in either file. The value of size is
generated dynamically. An INDEX file will contain a instance_id
attribute. Bundle definitions for distributions will not contain
either the location or qualifier, installed_software objects may con-
tain these attributes.
Product Definition
product
tag tag None
architecture architecture Empty string
location location <product.directory>
qualifier qualifier Empty string
revision revision Empty string
vendor_tag vendor_tag Empty string
all_filesets all_filesets Empty list
control_directory control_directory <product.tag>
copyright copyright Empty string
create_time create_time None
directory directory /
description description Empty string
instance_id instance_id 1
is_locatable is_locatable true
postkernel postkernel Implemen. defined
layout_version layout_version 1.0
machine_type machine_type Empty string
number number Empty string
os_name os_name Empty string
os_release os_release Empty string
os_version os_version Empty string
mod_time mod_time None
size size None
title title title
category_tag category_tag Empty list # C701
is_patch is_patch false # C701
copyrighters copyrighters None # impl.
build_root build_root None # impl.
build_host build_host None # impl.
source_package source_package None # impl.
source_rpm source_rpm None # impl.
all_patches all_patches None # impl.
url url None # impl.
rpm_provides rpm_provides None # impl.
change_log change_log None # impl.
The tag and control_directory attributes are required. The size
attribute is not allowed in either file. The value of size is gener-
ated dynamically. An INDEX file will contain a instance_id attribute.
A product object can contain control_files, files, and, subproducts in
the form of software definitions.
The product.vendor_tag refers to the downstream distributor. This
value is be the analogous to the RPMTAG_RELEASE or debian_release
attributes. The original upstream author’s package, for example,
would not use this attribute because that package would not have a
release part in its name, but could (or should) provide a vendor
object in the PSF.
The architecture attribute contains an implementation defined name
describing the architecture. This attribute may be a pattern. The
swbis implementation uses the output of GNU config.guess (times-
tamp=2007-01-15) as the string to be matched by this pattern.
Category Definition
category
tag tag None # C701
title title Empty string # C701
description description Empty string # C701
revision revision Empty string # C701
The Category definition describes attributes of products and bundles
related to its category. If is_patch is "true" then category.tag must
equal "patch".
Subroduct Definition
subproduct
tag tag None
create_time create_time None
description description Empty string
mod_time mod_time None
size size None
title title Empty string
contents contents Empty list
category_tag category_tag Empty list # C701
is_patch is_patch false # C701
The tag and contents attributes are required.
Fileset Definition
fileset
tag tag None
create_time create_time None
mod_time mod_time None
control_directory control_directory <fileset.tag>
corequisites corequisites Empty list
description description Empty string
exrequisites exrequisites Empty list
is_kernel is_kernel false
is_locatable is_locatable true
is_reboot is_reboot false
location location <product.directory>
media_sequence_number media_sequence_number 1
prerequisites prerequisites Empty list
revision revision None
size size None
state state None
title title Empty string
is_sparse is_sparse "false" # C701
is_patch is_patch "false" # C701
category_tag category_tag empty list # C701
ancestor ancestor <product.tag>,ver_id # C701
applied_patches applied_patches empty list # C701
patch_state patch_state applied or, # C701
committed or,
superseded, (no default).
saved_files_directory saved_files_directory None # C701
supersedes supersedes None # C701
superseded_by superseded_by None # C701
The tag and control_directory attributes are required. A PSF should
not contain the location, media_sequence_number, size, or state
attributes. A fileset object can contain control_files, files, in the
form of software definitions.
File Definition
file
path path None
cksum cksum None
compressed_cksum compressed_cksum None
compressed_size compressed_size None
compression_state compression_state uncompressed
compression_type compression_type Empty string
revision revision Empty string
size size None
source source None
gid gid Undefined
group group Empty string
is_volatile is_volatile false
link_source link_source None
major major None
minor minor None
mode mode None
mtime mtime None
owner owner Empty string
type type f
uid uid undefined
archive_path archive_path empty string # C701
md5sum md5sum empty string # impl.
sha1sum sha1sum empty string # impl.
sha512sum sha512sum empty string # impl.
rdev rdev empty string # impl.
rpm_fileflags rpm_fileflags empty string # impl.
A PSF must contain source attribute. A source attribute in an INFO
will be ignored. A PSF should not contain the cksum, com-
pressed_cksum, compressed_size, compression_state, compression_type,
or size attributes.
Control File Definition
control_file
tag tag None
cksum cksum None
compressed_cksum compressed_cksum None
compressed_size compressed_size None
compression_state compression_state uncompressed
compression_type compression_type Empty string
revision revision Empty string
size size None
source source None
path path None
interpreter interpreter sh
result result none
A control_file defines a control script such as those listed below
(see Extended Control File Definitions) or an attribute stored as a
file.
SOFTWARE SELECTIONS
The Software Selections provide a means to specify and select (possi-
bly with a shell matching pattern) specific Software objects. A
selection is made using a software spec. A software spec may not con-
tain white space (a list of multiple selections is white space delim-
ited). A software spec consists of tag values and version_ids. Mul-
tiple tags are ’.’ (dot) delimited with the leftmost specifying the
broadest (most general) software object such as a bundle or product
and the rightmost being most specific (The swbis implementation does
not support fileset tags in a software spec). The tags may be followed
by nothing, or a comma and one or more Version Identifiers which are
’,’ comma delimited.
Dependency Specs are software specs.
Version Identifiers
Version Identifiers specify specific attributes of a software object.
There are five (5) specified. They are signified by a single letter:
r,a,v,l,q. An implementation may support additional ones and may sup-
port qualification to a specific object type by prefixing a ’p’ or ’b’
or ’f’ for bundle, product, or fileset respectively. The value of the
attribute follows an equals sign ’=’, or in the case of a revision id,
a relational operator.
Letter Attribute
r revision r<relop>revsion
# A relop may be ==,<,>,<=,>=
v vendor_tag v=vendor_tag
q qualifier q=qualifier
l location l=location
a architecture a=arch
Implementation Extension Version Ids are the following:
Letter Attribute
i catalog_instance_id i=number
The catalog instance_id is a directory in the installed software cat-
alog that distinguishes installed instances of packages with the same
name and revision but at different locations.
Example Software Specs
emacs,r==21.2
kde.kdegames # This assumes that ’kde’ was specified as the bundle
# in the kdegames package
foobar,r>1.0,v=tycoon003
somepackage,r>1.0,r<=1.3 # revision is the product revision by default
somepackage,pr>1.0,pr<=1.3 # explicitly specify revision is the product revision
DEPENDENCY SPECS
A dependency spec is a software spec. There are three types: prereq-
uisites, exrequisites, corequisites. These attributes apply to the
fileset and are placed in the fileset object in a PSF file. A prereq-
uisites is something that must be installed, and a exrequisites is
something that must not be installed. A corequisites is something
that must be installed with, corequisites are not supported at this
time. prerequisites map to RPMTAG_REQUIRENAME, RPMTAG_REQUIREVERSION,
and RPMTAG_REQUIREFLAGS attributes.
Dependency Spec Examples
# Alternation Require a package named foo1 or foo2
prerequisite foo1|foo2
# Require a package named foo1 and foo2
prerequisite foo1 foo2
# multiple prerequisite keywords can be used
prerequisite foo1
prerequisite foo2
# Require a revision range and a certain vendor_tag
prerequisite foo1,r>2,r<3,v=mydist*
EXTENDED DEFINITIONS
A Product Specification File (PSF) can contain Extended Definitions in
the fileset, product or bundle software definitions. They would have
the same level or containment relationship as a file or control_file
definition in the same contaning object.
Extended Definitions represent a minimal, expressive form for specify-
ing files and file attributes. Their use in a PSF is optional in that
an equivalent PSF can be constructed without using them, however,
their use is encouraged for the sake of brevity and orthogonality.
The swbis implementation requires that no [ordinary] attributes appear
after Extended Definitions in the containing object, and, requires
that Extended Definitions appear before logically contained objects.
That is, the parser uses the next object keyword to syntacticly and
logically terminate the current object even if the current object has
logically contained objects.
o Extended Control File Definitions
checkinstall source [path]
preinstall source [path]
postinstall source [path]
verify source [path]
fix source [path]
checkremove source [path]
preremove source [path]
postremove source [path]
configure source [path]
unconfigure source [path]
request source [path]
unpreinstall source [path]
unpostinstall source [path]
space source [path]
control_file source [path]
The source attribute defines the location in distributors’s develop-
ment system where the swpackage utility will find the script. The
keyword is the value of the tag attribute and tells the utilities when
to execute the script. The path attribute is optional and specifies
the file name in the packages distribution relative to the con-
trol_directory for software containing the script. If not given the
tag value is used as the filename.
o Directory Mapping
directory source [destination]
Applies the source attribute as the directory under which the subse-
quently listed files are located. If destination is defined it will
be used as a prefix to the path (implied) file definition. source is
typically a temporary or build location and dest is its unrealized
absolute pathname destination.
o Recursive File Definition
file *
Specifies every file in current source directory. The directory
extended definition must be used before the recursive specification.
o Explicit File Definition
file [-t type] [-m mode] [-o owner[,uid]] [-g group[,gid]] [-n] [-v] source [path]
source
source defines the pathname of the file to be used as the
source of file data and/or attributes. If it is a relative
path, then swpackage searches for this file relative to the the
source argument of the directory keyword, if set. If directory
keyword is not set then the search is relative to the current
working directory of the swpackage utility’s invocation.
All attributes for the destination file are taken from the
source file, unless a file_permissions keyword is active, or
the -m, -o, or -g options are also included in the file speci-
fication.
path
path defines the destination path where the file will be cre-
ated or installed. If it is a relative path, then the destina-
tion path of the of the directory keyword must be active and
will be used as the path prefix. If path is not specified then
source is used as the value of path and directory mapping
applied (if active).
-t type
type may one of ’d’ (directory), or ’h’ (hard link), or ’s’
(symbolic link).
-t d Create a directory.
If path is not specified source is used as the path attribute.
-t h Create a hard link.
path and source are specified. source is used as the value of
the link_source attribute, and path is the value of the path
attribute.
-t s Create a symbolic link.
path and source are specified. source is used as the value of
the link_source attribute, and path is the value of the path
attribute.
-m mode
mode defines the octal mode for the file.
o Default Permission Definition
file_permissions [-m mode] [-u umask] [-o [owner[,]][uid]] [-g [group[,]][gid]]
Applies to subsequently listed file definitions in a fileset. These
attributes will apply where the file attributes were not specified
explicitly in a file definition. Subsequent file_permissions defini-
tions simply replace previous definitions (resetting all the options).
To reset the file_permission state (i.e. turn it off) use one of the
following:
file_permissions ""
or the preferred way is
file_permissions -u 000
o Excluding Files
exclude source
Excludes a previously included file or an entire directory.
o Including Files
include <filename
The contents of filename may be more definitions for files. The syn-
tax of the included file is PSF syntax.
DISTRIBUTOR KEYWORDS
A software definition file (INFO, INDEX or psf) may contain keywords
not recognized by the standard. Such keywords will be parsed as an
attribute keyword, that is as an attribute of the containing object
(keyword) software definition.
PACKAGE SECURITY
The Package Security Attributes are distribution attributes stored as
separate files. They are implementation extensions. They consist of
archive digests, catalog signature, catalog signature header, and
individual file md5, sha1, and sha512 digests.
Archive Digests
md5sum, sha1sum, and sha512sum are the md5 and sha1 and sha512 digests
(ascii representations) of the leading package directories that do not
have the catalog pathname component followed by the software file
storage structure portion of the uncompressed serial access package
file including all archive format trailer blocks.
<path>/catalog/<dfiles>/md5sum
<path>/catalog/<dfiles>/sha1sum
<path>/catalog/<dfiles>/sha512sum
Adjunct Md5 Digest
adjunct_md5sum is the same as the md5sum excluding symbolic links. If
a package does not contain symbolic links the md5sum and
adjunct_md5sum will be identical.
<path>/catalog/<dfiles>/adjunct_md5sum
Explanation: This attribute is called ’adjunct’ because it is a digest
of a subset of the files in the package. It exists to facilitate ver-
ifying file integrity of the directory form of a package in an envi-
ronment where the modification time of symbolic link files are not
preserved from the serial archive by the tar utility or operating sys-
tem. The ability to verify even the adjunct_md5sum from the directory
form of the package is dependent on the tar creating utility and other
attributes of a POSIX.2 environment.
Catalog Signature Header
The sig_header file is a ustar header that is identical bit-for-bit to
the ustar header of the signature file. It always precedes the signa-
ture file archive members.
<path>/catalog/<dfiles>/sig_header
The sig_header protects the tar header of the signature files from
tampering. This is required because neither the signature file bytes
nor the signature tar header are included in the signed data.
Catalog Signature
The signature protects the metadata section of the archive. The con-
tents of payload section are only included in the form of a cryto-
graphic digest. The sha1 digest is preferred over the md5 digest for
technical reasons. If the metadata section does not contain the pay-
load section digests then there is no way to verify the payload from
the signature.
<path>/catalog/<dfiles>/signature
The signed data is the exported catalog structure of the uncompressed
serial archive package file up to but not including the first byte of
the software file storage structure followed by two (2) 512 byte null
blocks if tar format, and no trailer bytes if not tar format. The
signature file archive member itself is not included in the signed
stream, it is intended that the <path>/catalog/<dfiles>/md5sum file is
included in the signed stream.
The signature file is ASCII armored. The last printable character of
the signature is followed by one or more newline characters (0x0A)
followed by one or more NUL characters (0x00). The total length of
the file must match the file size specified in the size field of the
sig_header file. The ustar header of every signature archive member
shall be identical to the sig_header file. The padded size is prede-
termined [by swpackage] and currently set to be 1024 octets. This
means the armored sig file has a length limitation of 1023 octets.
If multiple signature archive members exist they must follow one
another in the archive with no other intervening files; and, the same
sig_header file is the ustar header for all the signature archive mem-
bers. A signature archive member, whether alone or one of many, is
never part of the signed data stream.
File Digests
file.cksum
file.md5sum
file.sha1sum
file.sha512sum
Each file can have none or all of these digests.
SOFTWARE DEFINITION FILES
The metadata files, INDEX, INFO and PSF, contain information about the
software in the form of software definitions. The INDEX and INFO
files appear in a package directory structure. They are automatically
generated by the ’swpackage’ command. The location in the directory
structure indicates the higher level object to which their data per-
tains. The PSF file does not appear in the package. It is created by
a person or program and it directs the action of the swpackage util-
ity. It is internal data unless released by the distributor.
The files contain keywords (and values) to represent the attributes
defined in the standard. There are three (3) different keyword types:
object, attribute, and, extended. The object keyword type has no value
and there are eleven (11) of these corresponding to the Software Defi-
nitions defined above: installed_software, distribution, media, bun-
dle, vendor, category, product, subproduct, fileset, control_file,
file.
Each object keyword is followed by and newline and attributes in the
form of keyword/value pairs. Whitespace separates the keyword and
value. Whitespace outside of a quoted value is not significant. A
quoted value can span multiple lines. An object keyword with its list
of attribute keywords (and values) forms a Software Definition. A
Software Definition is terminated by the start of the next Software
Definition. Extended keywords (meaning Extended Definitions) only
appear in a PSF file.
The order of objects (i.e Software Definitions) is significant and a
containment hierarchy is determined according to parser’s grammar.
Additional Syntax Rules
· A ’#’ (pound) character designates a comment. A comment may
begin a line or appear at the end of a single line containing
the keyword/value pair.
· A value may be quoted by the ’"’ (double quote) character; and,
multi-line values must be quoted. Trailing white space from an
unquoted value will be removed.
· The order of attributes is not significant although the INDEX
file grammar requires the layout_version attribute appear first
in distribution or installed software object.
· The ", #, and, \ characters must be escaped with a backslash (\)
in a quoted value.
· If a value begins with a < (less than), the value is interpreted
as a filename whose contents will be treated as a quoted value
although the storage of the attribute will be in the form of a
control file (i.e. a separate file in the control directory).
For INDEX files, the filename is relative to the control direc-
tory in which this attribute is contained. For PSF files, the
filename is a path on the host.
Software Definition File Grammar
A PSF may contain all Software Definitions. An INDEX file does not
contain control_file, or file definitions. An INFO file contains only
control_file, and file definitions.
software_definition_file : INDEX
| INFO
| PSF
;
PSF : distribution_definition
swo_contents
;
INDEX : swo_definition
swo_contents
;
INFO : fileset_contents
;
swo_definition : distribution_definition
| installed_software
;
distribution_definition : distribution
media
;
swo_contents : vendor(s)
| category(s)
| products
| bundles
;
products : product
product_contents
;
bundles : bundle
;
product_contents : control_files
/* control_files not valid in INDEX file */
| subproducts
| filesets
;
filesets : fileset
/* fileset_contents not valid in INDEX file */
fileset_contents
;
fileset_contents : control_files
| files
;
EXAMPLE PACKAGE
Layout
swm-1.0/catalog
swm-1.0/catalog/INDEX
swm-1.0/catalog/dfiles
swm-1.0/catalog/dfiles/INFO
swm-1.0/catalog/dfiles/md5sum
swm-1.0/catalog/dfiles/sha1sum
swm-1.0/catalog/dfiles/adjunct_md5sum
swm-1.0/catalog/dfiles/sig_header
swm-1.0/catalog/dfiles/signature
swm-1.0/catalog/gsoft_swm
swm-1.0/catalog/gsoft_swm/pfiles
swm-1.0/catalog/gsoft_swm/pfiles/INFO
swm-1.0/catalog/gsoft_swm/pfiles/remove
swm-1.0/catalog/gsoft_swm/pfiles/configure
swm-1.0/catalog/gsoft_swm/bin
swm-1.0/catalog/gsoft_swm/bin/INFO
swm-1.0/catalog/gsoft_swm/bin/postinstall
swm-1.0/catalog/gsoft_swm/bin/configure
swm-1.0/catalog/gsoft_swm/doc
swm-1.0/catalog/gsoft_swm/doc/INFO
swm-1.0/catalog/gsoft_swm/doc/postinstall
swm-1.0/gsoft_swm
swm-1.0/gsoft_swm/bin
swm-1.0/gsoft_swm/bin/usr/bin/swpackage
swm-1.0/gsoft_swm/bin/usr/bin/sw_build
swm-1.0/gsoft_swm/doc
swm-1.0/gsoft_swm/doc/usr/man/man1/swpackage.1
swm-1.0/gsoft_swm/doc/usr/man/man1/sw_build.1
Hypothetical PSF file
distribution
control_directory swm-1.0 #Implementation Extension.
vendor
the_term_vendor_is_misleading false # True or False
tag greatsoft
title Greatersoft Corporation
description "Greatersoft Corporation, Inc."
product
tag swm
title POSIX 1387 package builder
revision 1.0
control_directory gsoft_swm
vendor_tag greatsoft
description A package building Utility.
machine_type i386
control_file
path remove
source /var/tmp/sw/remove.source
configure /var/tmp/sw/configure.source
fileset
tag bin
control_directory bin
title Executable Files
state available
postinstall /var/tmp/sw/bin/postinstall
configure /var/tmp/sw/bin/configure
file -m 0755 -o root -g root /var/tmp/sw/build/bin/swpackage \
/usr/bin/swpackage
file -m 0755 -o root -g root /var/tmp/sw/build/bin/sw_build \
/usr/bin/sw_build
fileset
tag doc
control_directory doc
title Manual Pages
state available
postinstall /var/tmp/sw/bin/postinstall
file -m 0644 -o root -g root /var/tmp/sw/build/man/swpackage.1 \
/usr/man/man1/swpackage.1
file
mode 0644
owner root
group root
source /var/tmp/sw/build/man/sw_build.1
path /usr/man/man1/sw_build.1
INDEX File swm-1.0/catalog/INDEX
distribution
layout_version 1.0
tag swm-1.0
uuid 880ccf8b-de2c-4422-bff0-fd686279da73
md5sum < md5sum
adjunct_md5sum < adjunct_md5sum
sig_header < sig_header
signature < signature
media
sequence_number 1
vendor
the_term_vendor_is_misleading false # True or False
tag greatsoft
title Greatersoft Corporation
description "Greatersoft Corporation, Inc."
product
tag swm
title POSIX 1387 package builder
revision 1.0
instance_id 1
control_directory gsoft_swm
vendor_tag greatsoft
description A package building Utility.
machine_type i386
fileset
tag bin
control_directory bin
size 196643
title Executable Files
state available
fileset
tag doc
control_directory doc
size 19643
title Manual Pages
state available
INFO File swm-1.0/catalog/dfiles/INFO
control_file
path INFO
tag INFO
size 92
control_file
path md5sum
tag md5sum
size 36
control_file
path adjunct_md5sum
tag adjunct_md5sum
size 36
control_file
path sig_header
tag sig_header
size 512
control_file
path signature
tag signature
size 512
INFO File swm-1.0/catalog/gsoft_swm/bin/INFO
control_file
path INFO
tag INFO
size 337
control_file
path postinstall
type f
size 803
cksum 3928827394
mode 550
uid 0
gid 0
owner root
group root
mtime 739080341
control_file
path configure
type f
size 432
cksum 3934546394
mode 550
uid 0
gid 0
owner root
group root
mtime 739340771
file
path /usr/bin/swpackage
type f
size 80860
cksum 3929827394
mode 755
uid 0
gid 0
owner root
group root
mtime 739080771
file
path /usr/bin/sw_build
type f
size 120860
cksum 9894925524
mode 755
uid 0
gid 0
owner root
group root
mtime 7393808731
SWBIS PSF CONVENTIONS
This section describes attribute usage and conventions imposed by the
swbis implementation. Not all attributes are listed here. Those that
are have important effects or particular interest.
o Distribution Attributes
The standard defines a limited set of attributes for the distribution
object. An expanded set is suggested by the informative annex however
a conforming implementation is not required act on them. The reason
for this is a distribution may be acted upon by a conforming utility
in such a way that attributes of the distribution become invalid. For
this reason, some attributes that refer to an entire "package" [in
other package managers] are referred from the product object and
attain their broadened scope by the distributor’s convention that
their distribution contains just one product.
For example, the package NAME and VERSION are referred from the prod-
uct tag and revision, not the distribution’s. This convention sup-
ports multiple products in a distribution and is consistent with the
standard.
tag
tag is the short, file system friendly, name of the distribu-
tion. Providing a distribution tag is optional. The swbis
implementation will use this as the [single] path name prefix
if there is no distribution.control_directory attribute. A
distribution tag attribute and swpackage’s response to it is an
implementation extension. The leading package path can also be
controlled with the ’’-W dir’’ option.
control_directory
control_directory, in a distribution object, is the constant
leading package path. Providing this attribute is optional. A
distribution control_directory attribute and swpackage’s
response to it is an implementation extension. The leading
package path can also be controlled with the ’’-W dir’’ option.
This attribute will be generated by swpackage if not set in a
PSF.
o Bundle Attributes
A bundle defines a collection of products whether or not the distribu-
tion has all the products present.
tag
tag is the short, file system friendly, name of the bundle.
This value is used by the swbis implementation as a path name
component in the installed software catalog. If it is not
present the product tag is used.
o Product Attributes
A product defines the software product.
tag
tag is the short, file system friendly, name of the product.
This value is used by the swbis implementation as a path name
component in the installed software catalog. It is required.
The swbis implementation uses it in a way that is analogous to
the RPMTAG_NAME attribute, namely as the public recognizable
name of the package.
control_directory
Is the directory name in the distribution under which the prod-
uct contents are located. This value has no affect on the
installed software catalog. If it is not given in a PSF then
the tag is used.
revision
Is the product revision. It should not contain a "RELEASE"
attribute part or other version suffix modifiers. This value
is used by the swbis implementation as a path name component in
the installed software catalog. It is required by swinstall.
vendor_tag
This is a short identifying name of the distributor that sup-
plied the product and may associate (refer to) a vendor object
from the INDEX file that has a matching tag attribute. This
attribute is optional. This attribute value should strive to
be unique among all distributors. The swbis implementation mod-
ifies the intended usage slightly as a string that strives to
be globally unique for a given product.tag and product.revi-
sion. In this capacity it serves to distinguish products with
the same revision and tag from the same or different distribu-
tor. It most closely maps to the RPMTAG_RELEASE or
"debian_revision" attributes. It is one of the version distin-
guishing attributes of a product specified by the standard. It
is transfered into the installed_software catalog (not as a
path name component) by swinstall. If this attribute exists
there should also be a vendor object in the PSF in the distri-
bution object that has this tag. This attribute is assigned
the value of RPMTAG_RELEASE by swpackage when translating an
RPM.
architecture
This string is one of the version attributes. It is used to
disambiguate products that have the same tag, revision and ven-
dor_tag. It is not used for determining a products compatibil-
ity with a host. The form is implementation defined. swbis
uses the output of GNU config.guess as the value of this
string. A wildcard pattern should not be used. The canonical
swbis architecture string can be listed with swlist. For exam-
ple
swlist -a architecture @ localhost
Here are some example outputs from real systems.
System ‘uname -srm‘ architecture
Red Hat 8.0: Linux 2.4.18 i686 i686-pc-linux-gnu
OpenSolaris: SunOS 5.11 i86pc i386-pc-solaris2.11
NetBSD 3.1: NetBSD 3.1 i386 i386-unknown-netbsdelf3.1
Red Hat 4.1: Linux 2.0.36 i586 i586-pc-linux-gnulibc1
Debian 3.1: Linux 2.6.8-2-386 i686 i686-pc-linux-gnu
os_name os_release os_version machine_type
These attributes are used to determine compatibility with a
host. They correspond to the uname attributes defined by
POSIX.1. If an value is nil or non-existent it is assumed to
match the host. All attributes must match for there to be com-
patibility. Distributors may wish to make these values a shell
pattern in their PSF’s so to match the intended collection of
hosts. swbis uses fnmatch (with FLAGS=0) to determine a match.
o Fileset Attributes
A fileset defines the fileset.
tag
tag is the short, file system friendly, name of the fileset.
It is required although selection of filesets is not yet sup-
ported therefore the end user will have little to do with the
fileset tag.
control_directory
Is the directory name in the product under which the fileset
contents are located. This value has no affect on the
installed software catalog. If it is not given in a PSF then
the tag is used.
o Example Source Package PSF
This PSF packages every file is current directory. It uses nil control
directories so the package structure does not change relative to a
vanilla tarball.
distribution
description "fooit - a program from fooware
that does everything."
title "fooit - a really cool program"
COPYING < /usr/local/fooware/legalstuff/COPYING
vendor
the_term_vendor_is_misleading false
tag fooware
title fooware Consultancy Services, Inc.
description ""
vendor
the_term_vendor_is_misleading true
tag myfixes1
title Bug fixes, Set 1
description "a place for more detailed description"
product
tag fooit
control_directory ""
revision 1.0
vendor_tag myfixes1 # Matches the vendor object above
fileset
tag fooit-SOURCE
control_directory ""
directory .
file *
exclude catalog
o Example Runtime (Binary) Package PSF
This is a sample PSF for a runtime package. It implies multiple prod-
ucts (e.g. sub-packages) using the bundle.contents attribute. Since
the bundle and product tags exist in a un-regulated namespace and are
seen by end users they should be carefully chosen. Note that the
bundle and product have the same tag which may force downstream users
to disambiguate using software selection syntax such as fooit,bv=* or
fooit,pv=* .
distribution
description "fooit - a program from fooware
that does everything."
title "fooit - a really cool program"
COPYING < /usr/local/fooware/legalstuff/COPYING
vendor
the_term_vendor_is_misleading false
tag fooware
title fooware Consultancy Services, Inc.
description "Provider of the programs
that do everything"
vendor
the_term_vendor_is_misleading true
tag fw0
title fooware fixes
description "More fixes from the fooware users"
# Bundle definition: Use a bundle
bundle
tag fooit
vendor_tag fooware
contents fooit,v=fw0 fooit-devel fooit-doc
# Product definition:
product
tag fooit # This is the package name
revision 1.0 # This is the package version
vendor_tag fw0 # This is a release name e.g. RPMTAG_RELEASE
postinstall scripts/postinstall
fileset
tag fooit-RUN
file doc/man/man1/fooit.1 /usr/man/man1/fooit.1
file src/fooit /usr/bin/fooit
APPLICABLE STANDARDS
IEEE Std 1387.2-1995 (Identical to ISO 15068-2:1999), Open Group CAE
C701
SEE ALSO
XDSA C701 http://www.opengroup.org/publications/catalog/c701.htm
swbisparse(1) -- An implementation extension parser utility.
swcopy(8)
swinstall(8)
swpackage(5)
swpackage(8)
swverify(8)
IDENTIFICATION
Copyright (C) 2005 Jim Lowe
Version: 0.951
Last Updated: 2006-01
Copying Terms: GNU Free Documentation License
BUGS
None
sw(5)
(This section is currently under construction).
The configuration file is called a defaults file. The defaults file contains extended options which also can be specified using the '-x' option.
There are two (2) defaults files, the POSIX file named swdefaults and the swbis specific file named swbisdefaults. The swbis extension options all begin with "swbis_".
For GNU/Linux users the following changes to the config files are recommended:
swbis_local_pax_write_command = tar # {pax|tar|star|gtar|swbistar}
swbis_remote_pax_write_command = tar # {pax|tar|star|gtar|swbistar}
swbis_local_pax_read_command = tar # {pax|tar|star|gtar}
swbis_remote_pax_read_command = tar # {pax|tar|star|gtar}
swbis_no_getconf = true # true or false
swbis_shell_command = bash # {sh|bash|posix|ash|ksh}
swbis_allow_rpm = true
swcopy.swbis_no_audit = true # true or false
The files are located in two places, in the package library directory such as /usr/lib/swbis, and in the user's home directory in the .swbis directory.
To show these locations:
swinstall --show-options-files
To show the options:
swinstall --show-options
To show the compiled in defaults if no defaults files are read:
swinstall --no-defaults --show-options
# File: sw defaults
## uncomment options as needed.
installed_software_catalog = var/lib/swbis/catalog
#swinstall.allow_downdate = false
#swinstall.allow_incompatible = false
#swinstall.ask = false
#swinstall.autoreboot = false
#swinstall.autoselect_dependencies = false
#swinstall.defer_configure = false
#swinstall.distribution_source_directory = -
#swinstall.enforce_dependencies = false
#swinstall.enforce_dsa = false
#swinstall.enforce_locatable = false
#swinstall.enforce_scripts = false
#swinstall.installed_software_catalog = var/lib/swbis/catalog
#swinstall.logfile = /var/log/swinstall.log
#swinstall.loglevel = 1
#swinstall.reinstall = false
#swinstall.select_local =
#swinstall.software =
#swinstall.targets =
#swinstall.verbose = 1
#swcopy.autoselect_dependencies = false # Support not implemented.
#swcopy.compress_files = false # Support not implemented.
#swcopy.compression_type = none # Support not implemented.
#swcopy.distribution_source_directory = - # Standard input
#swcopy.distribution_target_directory = - # Standard output
#swcopy.enforce_dependencies = false # Support not implemented.
#swcopy.enforce_dsa = false # Support not implemented.
#swcopy.logfile = /var/log/swcopy.log
#swcopy.loglevel = 0 # Support not implemented.
#swcopy.recopy = false # Support not implemented.
#swcopy.select_local = false # Support not implemented.
#swcopy.software =
#swcopy.targets =
#swcopy.uncompress_files = false # Support not implemented.
#swcopy.verbose = 1
#swremove.autoselect_dependencies = true
#swremove.distribution_target_directory = /var/spool/sw
#swremove.enforce_dependencies = true
#swremove.enforce_scripts = true
#swremove.enforce_dsa = true
#swremove.installed_software_catalog = var/lib/swbis/catalog
#swremove.logfile = /var/log/swremove.log
#swremove.loglevel = 1
#swremove.select_local = true
#swremove.software =
#swremove.targets =
#swremove.verbose = 1
#swconfig.allow_incompatible = false
#swconfig.allow_multiple_versions = false
#swconfig.ask = false
#swconfig.autoselect_dependencies = true
#swconfig.autoselect_dependents = false
#swconfig.enforce_dependencies = true
#swconfig.installed_software_catalog = var/lib/swbis/catalog
#swconfig.logfile = /var/log/swconfig.log
#swconfig.loglevel = 1
#swconfig.reconfigure = false
#swconfig.select_local = true
#swconfig.software =
#swconfig.targets =
#swconfig.verbose = 1
#swask.autoselect_dependencies = true
#swask.distribution_source_directory = /var/spool/sw
#swask.distribution_source_serial = -
#swask.logfile = /var/log/swask.log
#swask.loglevel = 1
#swask.select_local = true
#swask.software =
#swask.targets =
#swask.verbose = 1
#swmodify.distribution_target_directory = /var/spool/sw
#swmodify.installed_software_catalog = var/lib/swbis/catalog
#swmodify.files =
#swmodify.logfile = /var/log/swmodify.log
#swmodify.loglevel = 1
#swmodify.select_local = true
#swmodify.software =
#swmodify.targets =
#swmodify.verbose = 1
#swverify.allow_incompatible = false
#swverify.autoselect_dependencies = true
#swverify.check_contents = true
#swverify.check_permissions = true
#swverify.check_requisites = true
#swverify.check_scripts = true
#swverify.check_volatile = false
#swverify.distribution_target_directory = /var/spool/sw
#swverify.enforce_dependencies = true
#swverify.enforce_locatable = true
#swverify.installed_software_catalog = var/lib/swbis/catalog
#swverify.logfile = /var/log/swverify.log
#swverify.loglevel = 1
#swverify.select_local =
#swverify.software =
#swverify.targets =
#swverify.verbose = 1
#swlist.distribution_target_directory = /
#swlist.installed_software_catalog = var/lib/swbis/catalog
#swlist.one_liner = products # {products|files|dir}
#swlist.select_local = true
#swlist.software =
#swlist.targets =
#swlist.verbose = 1
#swpackage.distribution_target_directory = /var/spool/sw
#swpackage.distribution_target_serial = -
#swpackage.enforce_dsa = false
#swpackage.follow_symlinks = false
#swpackage.logfile = /var/log/swpackage.log
#swpackage.loglevel = 1
#swpackage.media_capacity = 0
#swpackage.media_type = serial
#swpackage.psf_source_file = -
#swpackage.software =
#swpackage.verbose = 1
# end of swdefaults file
# File: swbisdefaults
## Uncomment options as needed.
#swbis_no_getconf = false # true or false, Deprecated.
#swbis_shell_command = posix # {sh|bash|posix|ash|ksh}
#swbis_no_remote_kill = true # true or false
#swbis_quiet_progress_bar = true # true or false
#swbis_local_pax_write_command = tar # {pax|tar|star|gtar|swbistar}
#swbis_remote_pax_write_command = tar # {pax|tar|star|gtar|swbistar}
#swbis_local_pax_read_command = tar # {pax|tar|star|gtar}
#swbis_remote_pax_read_command = tar # {pax|tar|star|gtar}
#swbis_remote_shell_client = ssh
#swbis_allow_rpm = true
#swbis_forward_agent = true # Forward ssh agent. true=yes false=no
#swcopy.swbis_no_getconf = false # true or false, Deprecated.
#swcopy.swbis_shell_command = posix # {sh|bash|posix|ksh}
#swcopy.swbis_no_remote_kill = false # true or false
#swcopy.swbis_quiet_progress_bar = true # true or false
#swcopy.swbis_no_audit = true # true or false
#swcopy.swbis_local_pax_write_command = pax # {pax|tar|star|gtar|swbistar}
#swcopy.swbis_remote_pax_write_command = pax # {pax|tar|star|gtar|swbistar}
#swcopy.swbis_local_pax_read_command = pax # {pax|tar|star|gtar}
#swcopy.swbis_remote_pax_read_command = pax # {pax|tar|star|gtar}
#swcopy.swbis_remote_shell_client = ssh
#swcopy.swbis_forward_agent = true
#swinstall.swbis_no_getconf = false # true or false, Deprecated.
#swinstall.swbis_shell_command = posix # {sh|bash|posix|ksh}
#swinstall.swbis_no_remote_kill = false # true or false
#swinstall.swbis_quiet_progress_bar = true # true or false
#swinstall.swbis_local_pax_write_command = pax # {pax|tar|star|gtar|swbistar}
#swinstall.swbis_remote_pax_write_command = pax # {pax|tar|star|gtar|swbistar}
#swinstall.swbis_local_pax_read_command = pax # {pax|tar|star|gtar}
#swinstall.swbis_remote_pax_read_command = pax # {pax|tar|star|gtar}
#swinstall.swbis_sig_level = 0 # number of signatures to require
#swinstall.swbis_enforce_file_md5 = false
#swinstall.swbis_allow_rpm = false
#swinstall.swbis_remote_shell_client = ssh
#swinstall.swbis_install_volatile = true
#swinstall.swbis_volatile_newname = "" # e.g. ".rpmnew"
#swinstall.swbis_forward_agent = true
#swinstall.swbis_ignore_scripts = false
#swpackage.swbis_cksum = "false" # true or false
#swpackage.swbis_file_digests = "true" # true or false
#swpackage.swbis_files = "false" # true or false
#swpackage.swbis_sign = "false" # true or false
#swpackage.swbis_archive_digests = "false" # true or false
#swpackage.swbis_gpg_name = ""
#swpackage.swbis_gpg_path = "~/.gnupg"
#swpackage.swbis_gzip = "false" # true or false
#swpackage.swbis_bzip2 = "false" # true or false
#swpackage.swbis_numeric_owner = "false" # true or false
#swpackage.swbis_absolute_names = "false" # true or false
#swpackage.swbis_format = "ustar"
#swpackage.swbis_signer_pgm = "GPG"
#swlist.swbis_no_getconf = false # true or false, Deprecated.
#swlist.swbis_shell_command = posix # {sh|bash|posix|ksh}
#swlist.swbis_no_remote_kill = false # true or false
#swlist.swbis_local_pax_write_command = pax # {pax|tar|star|gtar|swbistar}
#swlist.swbis_remote_pax_write_command = pax # {pax|tar|star|gtar|swbistar}
#swlist.swbis_local_pax_read_command = pax # {pax|tar|star|gtar}
#swlist.swbis_remote_pax_read_command = pax # {pax|tar|star|gtar}
#swlist.swbis_remote_shell_client = ssh
#swlist.swbis_any_format = false # true or false
#swlist.swbis_forward_agent = true
#swlist.swbis_sig_level = 0 # Number of required valid signatures
#swlist.swbis_enforce_all_signatures = false
#swremove.swbis_no_getconf = false # true or false, Deprecated.
#swremove.swbis_shell_command = posix # {sh|bash|posix|ksh}
#swremove.swbis_no_remote_kill = false # true or false
#swremove.swbis_local_pax_write_command = tar # {pax|tar|star|gtar|swbistar}
#swremove.swbis_remote_pax_write_command = tar # {pax|tar|star|gtar|swbistar}
#swremove.swbis_local_pax_read_command = tar # {pax|tar|star|gtar}
#swremove.swbis_remote_pax_read_command = tar # {pax|tar|star|gtar}
#swremove.swbis_local_pax_remove_command = tar # {tar|gtar} Must have the --remove-files option
#swremove.swbis_remote_pax_remove_command = tar # {tar|gtar} Must have the --remove-files option
#swremove.swbis_remote_shell_client = ssh
#swremove.swbis_forward_agent = false
#swremove.swbis_sig_level = 0 # Number of required valid signatures
#swremove.swbis_enforce_all_signatures = false
#swverify.swbis_no_getconf = false # true or false, Deprecated.
#swverify.swbis_shell_command = posix # {sh|bash|posix|ksh}
#swverify.swbis_no_remote_kill = false # true or false
#swverify.swbis_local_pax_write_command = tar # {pax|tar|star|gtar|swbistar}
#swverify.swbis_remote_pax_write_command = tar # {pax|tar|star|gtar|swbistar}
#swverify.swbis_local_pax_read_command = tar # {pax|tar|star|gtar}
#swverify.swbis_remote_pax_read_command = tar # {pax|tar|star|gtar}
#swverify.swbis_local_pax_remove_command = tar # {tar|gtar} Must have the --remove-files option
#swverify.swbis_remote_pax_remove_command = tar # {tar|gtar} Must have the --remove-files option
#swverify.swbis_remote_shell_client = ssh
#swverify.swbis_forward_agent = false
#swverify.swbis_sig_level = 0 # Number of required valid signatures
#swverify.swbis_enforce_all_signatures = false
# end of swbisdefaults file
Users of GNU/Linux systems might find the default utility, pax, especially annoying or even non-existent. Therefore, editing the /usr/lib/swbis/swbisdefaults file might be in order:
swbis_local_pax_write_command = tar # {pax|tar|star|gtar|swbistar}
swbis_remote_pax_write_command = tar # {pax|tar|star|gtar|swbistar}
swbis_local_pax_read_command = tar # {pax|tar|star|gtar}
swbis_remote_pax_read_command = tar # {pax|tar|star|gtar}
Use in networks where there are only GNU/Linux and BSD systems may allow these changes to /usr/lib/swbis/swbisdefaults. These changes will likely break operation on Sun Solaris hosts (as well as other non GNU hosts) since use of getconf is needed to locate the POSIX shell. These changes, however, simplify the command invoked on the remote host.
swbis_no_getconf = true # true or false
swbis_shell_command = bash # {sh|bash|posix|ash|ksh}
You are reading about GNU Swbis, the GNU implementation of the POSIX Software Administration Standard ISO/IEC 15068-2:1999 (formerly IEEE Std 1387.2-1995). This spec describes a interchange format, package file layout, meta-data file format and utilities for package creation, installation, query, listing, and verification.
The GNU implementation adds capabilities for package authentication using strong cryptographic digests and GPG signatures that are embedded in the package as an ordinary control files as allowed by the standard.
The GNU implementation is compatible with traditional free software distribution package file layouts by supporting empty names for control directories in the POSIX layout. This makes a swbis package no different from current packages except for the addition of the meta-data directory.
Other features of the GNU implementation are direct use of GNU Privacy Guard for signature creation and verification, direct use of the Ssh client for remote host operations, GNU tar format compatibility, no new utility or program requirements for remote installation beyond POSIX compatible GNU utilities that are probably already present on all GNU and GNU/Linux hosts.
GNU Swbis also can translate and install packages in RPM format.
This manual contains information not found in the Unix-style Manual Pages such as a user guides, Tutorials, and Internal design features, however, the Manual Pages and this manual share common source and many sections transparently reference a different rendering of the Manual Page source documents.
Other sources of documentation include ISO/IEC or IEEE printed standard, the online version of the Open Group Specification CAE C701.
The swbis man pages are maintained and may be considered authoritative.
Documentation from other implementations based on the Standard likely describe features that are a superset of the POSIX spec, whereas, the swbis implementation currently is a subset, hence, may not now or ever apply to swbis.
The input file to swpackageis a called a Product Specification File or PSF. It contains information to direct swpackage and information that is package meta-data [that is merely transferred unchanged into the global INDEX file].
A PSF may contain object keywords, attributes (keyword/value pairs) and Extended Definitions (See (swbis_sw)EXTENDED DEFINITIONS.) An object keyword connotes a logical object or software structure supported by the standard. An object keyword does not have a value field after it, as it contains attributes and Extended Definitions. An attribute keyword conotes an attribute (i.e. keyword/value pair) and always has a value.
Attribute keywords not recognized by the standard are allowed and are transferred into the INDEX file. Object keywords not recognized by the standard are not allowed and will generate an error. Extended Definitions may only appear in a PSF (never in a INDEX or INFO created by swpackage). Extended Definitions are translated [by swpackage] into object keywords (objects) and attributes recognized by the standard.
Comments in a PSF are not transferred into the INDEX file by the swbis implementation of swpackage.
The file syntax is the same as a INDEX, or INFO file. See (swbis_sw)SOFTWARE DEFINITION FILES.
A PSF may contain all objects defined by the standard as well as extended definitions.
Currently, swpackage does not enforce requirements for revision and name meta-data that other the 'swinstall' might need. Therefore you should perform a test install of your package. The preview '-p' option of swinstall internally simulates most of the install operation but does not alter the file system. The example below previews the package on standard input.
swinstall -p -x verbose=6 -s - < your_package
Other restrictions of the swbis implementation are the default values for the 'dfiles' and 'pfiles' attributes (which are 'dfiles' and 'pfiles') must be used for minimal layout packages, i.e. packages that have the product and fileset control directories specified as empty strings (i.e have a minimal package layout).
# This PSF packaged all files in the current # directory. distribution dfiles dfiles product title somepackage version 0.1 description Source package for somepackage version 0.1 tag somepackage # < Change this to your package name revision 0.1 # < Change this to your package version control_directory "" fileset tag somepackage-sources # Not used by swbis currently control_directory "" file_permissions -o 0 -g 0 directory . file * exclude catalog
This PSF packages all the files in the directory where swpackage is invoked. It uses NUL control directory names which maintain the package directory structure.
This is as simple as:
swinstall <your-package
The default target directory is always '/'.
See Command Reference.
'swbis' is designed to be as non-intrusive as possible and this applies to host requirements which are minimal.
For package creation you need uuidgen and if creating signed distributions you need gpg.
For package installation you need sh, bash, getconf, dd, tar, hostname, mkdir, expr, echo, test, sleep.
Installation of packages on remote hosts (i.e. using swinstall with a remote host target) does not require swbis to be installed there.
The swverify and swign commands are shell scripts which may have additional requirements.
Here are the technical details about requirements for swinstall, the same apply to swcopy:
swinstall requires a Posix shell accessible by the remote shell command. This is the remote command run by ssh (or rsh) for all operations. 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).
Installing RPMs results in the RPM first being translated to a POSIX archive in tar format, See Translating RPM Format Packages to a POSIX Distribution, then installation by swinstall proceeds normally.
swinstall --allow-rpm -s - @ host1:/mnt/test/root1 < your-0.1.arch.rpm
In this example, a remote host and target path is specified. No files will be installed outside of the target path. The allow-rpm may be turned on in the swbisdefaults file or by command line option.
Translation of RPMs is done in memory. No temporary files are created. Large RPMs or RPMs with many small files may take many seconds or several minutes to translate.
Translation is performed by the swbis library executable lxpsf and swpackage.
/usr/lib/swbis/lxpsf --psf-form2 -H ustar |
swpackage -Wsource=- -s@PSF
The lxpsf is the only swbis program with RPM library dependencies, and this is the program that does the actual meta-data translation.
Depending on compilation options, it is possible to disable RPM translation ability (this is the default), or specify that the built-in library is to be used. The built-in library is base on RedHat rpm release 3.0.5. If the built-in compile option, with-self-rpm is used there are no dependencies on other packages.
The easiest way to invoke translation is with the --unrpm of swpackage and swcopy.
swcopy --unrpm -s - @- <your-0.1.arch.rpm | tar tvf -
-or-
swpackage --unrpm @- <your-0.1.arch.rpm | tar tvf -
To verbosely preview the translated RPM:
swcopy --unrpm -s - @- | swinstall -p -x verbose=5
swbis is network transparent from the ground up. It uses ssh (or rsh) to establish remote connections. Communication then takes place on standard input, output and error as established by the remote shell client on the local host. Operations which are entirely local are symmetric with remote operations in that swbis communicates via Unix pipes and makes no distinction based on the locality of the communication endpoints.
swbis uses the ssh client program 'ssh' as found by the PATH variable. swbis adds the '-T' option to disable pseudo-tty allocation.
swbis supports an extension to the POSIX target syntax to support multiple host hops. Use of password authentication for multi-hop targets requires use of the SSH_ASKPASS program and redirection of X11 connections over the secure ssh channel. See the 'ForwardX11' option in the ssh client configuration. Use of public key authentication is more reliable since the authentication agent is forwarded by use of the '-A' ssh option.
Important Note: When making a multi-hop connection using either authentication method, the authentication credentials appear on the intermediate hosts and are subject to hijack, hence, the intermediate hosts' trust requirement should be no less than the terminal host's.
One overriding design goal of swbis is zero re-invention. To that end, swbis uses '/usr/bin/gpg' for signing and authentication. It uses 'rsh' and 'ssh' for remote connections. It uses 'bash' (as a POSIX shell) for command processing. It uses 'pax' or 'tar' for archive installation. It uses a file system directory structure as the database for installed software.
swbis is non-intrusive relative to current practice for data interchange and storage using tar archives.
swbis supports a 'minimal package layout' (See (swbis_sw)Minimal Package Layout.) This layout follows the POSIX spec but has nil control directories (Note: nil control directories are not attested to in the POSIX specification).
By specifying control directories as empty strings and specifying a non-empty leading directory for the archive, a swbis POSIX package may be used inter-changeably with free software tar archive source packages which commonly have a leading package directory.
Binary (run-time) packages follow the same pattern except the leading directory is specified as an empty string as well. The result is a run-time package directly installable by tar.
The non-inventive nature of swbis extends into the format level as well. swbis has its own archive writing utility, swpackage, and it is self contained, however, it writes tar archives which are identical to archives produced by GNU tar.
This data format mimicry has several advantages. It forms the basis for a very brittle regression test, namely bit-for-bit sameness with GNU tar. This also preserves symmetry between a package archive and package directory in that swbis archives installed with tar can be repackaged with GNU tar with no bit-wise change relative to the original.
Together, these layers of mimicry are put to practical application in the swign program (See (swbis_swign)) which creates GPG signed POSIX packages without any data copying except by GNU tar.