Next: , Up: (dir)

swbis

This manual is for swbis (version 0.499, 03 Aug 2006), 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.”


Next: , Previous: Making PSFs for Package Creation, Up: Top

1 Creating Signed Distributions

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.


Next: , Up: Creating Signed Distributions

Creating a signed POSIX archive

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.


Next: , Previous: Creating a signed POSIX archive using <span class="command">swign</span>, Up: Creating Signed Distributions

Creating a signed directory

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


Next: , Previous: Creating a signed directory using <span class="command">swign</span>, Up: Creating Signed Distributions

Environment Variables that direct swign

swverify is affected by the following environment variables: SWPACKAGEPASSFD, SWPACKAGEPASSPHRASE, GNUPGHOME, and GNUPGNAME. For more information: (See (swbis_swpackage)ENVIRONMENT.)


Next: , Previous: Environment Variables that direct <span class="command">swign</span>, Up: Creating Signed Distributions

Providing a checkdigest script

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.


Previous: Providing a <span class="file">checkdigest</span> script, Up: Creating Signed Distributions

Using swign in an Automake target

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


Next: , Previous: Glossary, Up: Top

2 What features are working?

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.


Next: , Previous: Configuring swbis, Up: Top

3 How to invoke swbis

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:

Here are several example of Targets:

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:


Up: Invoking swbis

Target Syntax

Source and Target Specification and Logic
     
     Synopsis:
          Posix:
               host[:path]
               host
               host:
               /path  # Absolute path

          Swbis Extension:
               [user@]host[:path]
               :path

          Swbis Multi-hop Target Extension:
               # '@@' is the target delimiter
               target@@target[@@targetN...]
               [user@]host[@@[user@]host[@@...]][:path] 
               
     A more formal description:

     target : HOST_CHARACTER_STRING ':' PATHNAME_CHARACTER_STRING
            | HOST_CHARACTER_STRING ':'
            | HOST_CHARACTER_STRING 
            | PATHNAME_CHARACTER_STRING 
            | ':' PATHNAME_CHARACTER_STRING   # Impl extension
            ; 

       PATHNAME_CHARACTER_STRING must be an absolute path unless
                       a HOST_CHARACTER_STRING is given.  Allowing
                       a relative path is a feature of the swbis
                       implementation.

                NOTE: A '.' as a target is an implementation
                      extension and means extract in current
                      directory.
 
                NOTE: A '-' indicating stdout/stdin is an 
                      implementation extension.

                NOTE: A ':' in the first character indicates a filename.
                      This is an implementation extension.

       HOST_CHARACTER_STRING is an IP or hostname.

    Examples:
       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
    wtarget   : wtarget DELIM sshtarget
              | sshtarget
              ; 
    sshtarget : user '@' target # Note: only the last target
              | target          # may have a PATHNAME
              ;
    target   : HOST_CHARACTER_STRING
             | HOST_CHARACTER_STRING ':' PATHNAME_CHARACTER_STRING
             ;
    user     : PORTABLE_CHARACTER_STRING  # The user name

    DELIM    : '@@'   # The multi-hop delimiter.
             ;  


Next: , Previous: Top, Up: Top

Appendix A Copying This Manual


Up: Copying This Manual

A.1 GNU Free Documentation License

Version 1.2, November 2002
     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.
  1. PREAMBLE

    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.

  2. APPLICABILITY AND DEFINITIONS

    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.

  3. VERBATIM COPYING

    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.

  4. COPYING IN QUANTITY

    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.

  5. MODIFICATIONS

    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:

    1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
    2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
    3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
    4. Preserve all the copyright notices of the Document.
    5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
    6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
    7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
    8. Include an unaltered copy of this License.
    9. Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
    10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
    11. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
    12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
    13. Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version.
    14. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section.
    15. Preserve any Warranty Disclaimers.

    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.

  6. COMBINING DOCUMENTS

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

  7. COLLECTIONS OF DOCUMENTS

    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.

  8. AGGREGATION WITH INDEPENDENT WORKS

    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.

  9. TRANSLATION

    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.

  10. TERMINATION

    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.

  11. FUTURE REVISIONS OF THIS LICENSE

    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.

A.1.1 ADDENDUM: How to use this License for your documents

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.


Next: , Previous: Status, Up: Top

2 Applicable Standards

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


Next: , Previous: Invoking swbis, Up: Top

Appendix A Command Reference

Commands

Formats


Next: , Previous: (swbis_swpackage), Up: Command Reference

swpackage.8 in one text file

swpackage(8)							  swpackage(8)



NAME
       swpackage -- Package a software distribution.

SYNOPSIS
       swpackage  [-p]	[-s psf_file]  [-f file] [-x option=value] \
       [-X options_file] [-W option] [software_selections] [@targets]

DESCRIPTION
       swpackage reads a Product Specification File (PSF) and writes a distri-
       bution 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 supports 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 stdout.

       -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 writ-
	      ten.  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
	      Not implemented.

       -W bzip2
	      Not implemented.

       -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 output reproducible by different invocations.

       -W list-psf
	      Write the PSF to stdout after having processed the extended def-
	      initions.

       -W unrpm
	      Same as -W 2posixformat

       -W 2posixformat
	      Read  a  package	on standard input and write a POSIX package on
	      standard output.	Requires the Supported formats	are  any  sup-
	      ported format of lxpsf.  Identical to:
	      /swbis/lxpsf --psf-form2 -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 cur-
	      rent 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 cur-
	      rent 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 command
	      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 cat-
	      alog 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 -Wop-
       tion=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_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"  # 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 is read by the swpackage utility from the  process  con-
       trolling terminal or stdin if there is no controlling terminal.	A sep-
       arate dedicated process reads the passphrase which may  be  up  to  239
       characters in length.  It is immediately written into a Unix pipe, read
       by the signer program on file descriptor three (fd=3), its memory loca-
       tion wiped, and the dedicated process exited.

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 fac-
       tors:

       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 format
       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  differ-
       ent  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 format
       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 out-
       put block size is 10240 bytes.  The last block is not padded and there-
       fore 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 connotes 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 Defini-
       tions 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.	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  logi-
       cally terminate the current object even if the current object has logi-
       cally 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 development
       system  where  the swpackage utility will find the script.  The keyword
       is the value of the tag attribute and tells the utilities when to  exe-
       cute the script.  The path attribute is optional and specifies the file
       name in the packages distribution relative to the control_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 typ-
       ically  a  temporary or build location and dest is its unrealized abso-
       lute 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  specifica-
	      tion.

       path

	      path defines the destination path where the file will be created
	      or installed.  If it is a relative path,	then  the  destination
	      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 syntax
       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  dis-
       tribution contains just one product.

       For example, the package NAME and VERSION are referred from the product
       tag and revision, not the  distribution's.   This  convention  supports
       multiple  products  in  a distribution and is consistent with the stan-
       dard.

       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 distri-
	      bution tag attribute and swpackage's response to it is an imple-
	      mentation  extension.  The leading package path can also be con-
	      trolled 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.


       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	associates  the vendor object from the
	      INDEX file.  This attribute is optional.	This  attribute  value
	      should strive to be unique among all distributors.  It is one of
	      the version distinguishing attributes of a product specified  by
	      the standard.  It is transfered into the installed_software cat-
	      alog (not as a path  name  component)  by  swinstall.   If  this
	      attribute exists there should also be a vendor object in the PSF
	      in the distribution object that has this tag.  This attribute is
	      assigned the value of RPMTAG_RELEASE by swpackage when translat-
	      ing an RPM.  In this capacity it serves to distinguish  products
	      with  the  same revision and tag from the same or different dis-
	      tributor.   It  most  closely  maps  to  the  RPMTAG_RELEASE  or
	      "debian_revision" attributes.

   o Fileset Attributes
       A fileset defines the fileset.

       tag

	      tag is the short, file system friendly, name of the fileset.  It
	      is required.

       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 bun-
       dle  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 terminal.


       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.

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


Next: , Previous: (swbis_swinstall), Up: Command Reference

swinstall.8 in one text file

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
       As of 2004-04-03 swinstall is usable at an alpha release level.

       As  of  2005-05-03  swinstall  is usable at an alpha release level with
       additional newly implemented features for checkinstall, preinstall, and
       postinstall  execution.	Fileset state and script exit status recording
       are also newly implemented.  Dependency	checks	are  not  implemented.
       Software  selections  are not implemented.  Only distributions with one
       (1) product and one (1) fileset are supported.  At this time,  symlink,
       hard  links,  directory, and device files are not supported unless they
       appear in the storage section in which  case  they  will  be  installed
       using  the local system archive reading utility, either 'tar' or 'pax'.
       (The Posix spec does not require non-regular  files  to	exist  in  the
       storage section).

       swinstall installs a Posix distribution from a source archive to a tar-
       get directory.  A Posix distribution is a  package,  typically  a  com-
       pressed	tarball  with  metadata  files	in the prescribed file layout.
       Neither swinstall nor any component of swbis is required on the	target
       host,  however,	the  target  host  must look like a Unix system at the
       shell and command-line utility level and have a	posix  shell.	Remote
       network connections are made by ssh.  Ssh is the default but rsh can be
       selected by a command line option.

       By default and with no external influences (i.e. swdefaults file) swin-
       stall  will read an archive on stdin and install all products and file-
       sets of package in "/" directory on the target host.  An alternate root
       may  be	specified  using  the  target syntax.  The distribution source
       directory (swbis default: stdin) is selectable via the  defaults  file,
       therefore it should be specified in uncontrolled environments.

       swinstall  operates  on	cpio or tar archives.  swinstall supports cpio
       archives by first translating to tar format, therefore, to  reduce  the
       data transformations performed by swinstall, distributors encouraged to
       deliver products in tar format.

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 syn-
	      tax  is the same as for a target.  SOURCE may be an archive file
	      or stdin.

       -t targetfile

	      Specify a file containing a list of targets (one per line).

       -x option=value

	      Specify the extended option overriding the defaults file	value.

       -X FILE

	      Specify  the  extended  options  filename, FILE,	overriding the
	      default filenames.  This option may be given more then once.  If
	      the resulting specified value is an empty string then reading of
	      any options file is disabled.

       -v

	      Given one time it is identical to -x verbose=2.  This option can
	      be given multiple times with increasing effect.  (Implementation
	      extension option).
	      -v  is level 2, -vv is level 3,... etc.
		  level 0: silent on stdout and stderr.
		  level 1: fatal and warning messages to stderr.
	      -v  level 2: level 1 plus a progress bar.
	      -vv level 3: level 2 plus script stderr.
	      -vvv level 4: level 3 plus events.
	      -vvvv level 5: level 4 plus events.
	      -vvvvv level 6: level 5 plus set shell -vx option.
	      -vvvvvv level 7 and higher: level 6 plus debugging messages.

       --version, -V

	      Show version (Implementation extension)

       --help

	      Show help (Implementation extension)

       -W option[,option,...]

	      Specify the implementation extension option.
	      Syntax: -W option[=option_argument[,option...]
	      Options may be separated by a comma.  The implementation	exten-
	      sion  options  may also be given individually using the '--long-
	      option[=option_arg]' syntax.

       -W preview-tar-file=FILE

	      This  is	a  testing/development	option.   Writes  the  fileset
	      archive  to  FILE.  This is the same data stream that would have
	      been loaded on the target.  This option should only be used with
	      the  '-p'  option.  The output sent to FILE is a tar archive but
	      without trailer blocks.

       -W remote-shell=NAME


	      Defaults File Option: swbis_remote_shell_client

	      This is the remote connection client program on  the  management
	      (originating  host).  The path NAME may be an absolute path (not
	      located in $PATH).  The basename of NAME is used for  intermedi-
	      ate hops.  Supported shells are "ssh" and "rsh".	The default is
	      "ssh".

       -W quiet-progress

	      Defaults File Option: swbis_quiet_progress_bar Disable  progress
	      bar,  which is active for verbose levels 2 and higher (i.e. -v).

       -W show-options-files
	      Show the complete list of options files and if they are found.

       -W show-options
	      Show the options after reading the files and parsing the command
	      line options.

       -W pax-command={tar|pax|star|gtar}
	      Set  the	portable  archive  command  for  all  operations.  The
	      default is "pax".

       -W pax-read-command={tar|pax|star|gtar}
	      Set the read command for local and remote hosts.

       -W remote-pax-read-command={tar|pax|star|gtar}
	      Defaults File Option: swbis_remote_pax_read_command
	      Set the read command for remote hosts.  This is the command that
	      runs  on	the  target  (e.g. pax -r, tar xpf -).	The default is
	      "pax".

       -W local-pax-read-command={tar|pax|star|gtar}
	      Defaults File Option: swbis_local_pax_read_command
	      Set the read command for local hosts.  This is the command  that
	      runs  on	the  target  (e.g. pax -r, tar xpf -).	The default is
	      "pax".

       -W pax-write-command={tar|pax|star|gtar|swbistar}
	      Set the write command for local and remote hosts.  This  is  the
	      command that runs on the target (e.g. pax -w, tar cf -).

       -W remote-pax-write-command={tar|pax|star|gtar|swbistar}
	      Defaults File Option: swbis_remote_pax_write_command
	      Set the write command for remote hosts.

       -W local-pax-write-command={tar|pax|star|gtar|swbistar}
	      Defaults File Option: swbis_local_pax_write_command
	      Set  the	portable  archive  write command for local host opera-
	      tions.  This is the command that runs on the  source  (e.g.  pax
	      -w, tar cf -).  The default is "pax".

       -W remote-pax-write-command={tar|pax|star|gtar|swbistar}
	      Defaults File Option: swbis_remote_pax_write_command
	      Set  the	portable  archive write command for remote host opera-
	      tions.  This is the command that runs on the  source  (e.g.  pax
	      -w, tar cf -).  The default is "pax".

       -W no-defaults
	      Do not read any defaults files.

       -W no-remote-kill
	      Defaults File Option: swbis_no_remote_kill
	      Disables	the use of a second remote connection to tear down the
	      first in the event of SIGINT or SIGTERM or  SIGPIPE.   Only  has
	      effect  if  the  number of ssh hops is greater than 1.  A single
	      host remote connection (ssh hop = 1) never uses a second	remote
	      connection.

       -W no-getconf
	      Defaults File Option: swbis_no_getconf
	      Makes the remote command be '/bin/sh -s' instead of the default

       -W shell-command=NAME
	      Defaults File Option: swbis_shell_command
	      This  is	the interactive shell on the target host.  NAME may be
	      one of "bash", "sh", "ksh"  or "posix" and specifies the	remote
	      command  run  by	the  remote  shell.  "posix" is 'PATH=`getconf
	      PATH` sh -s', "bash" is "/bin/bash -s", "sh"  is	"/bin/sh  -s",
	      and "ksh" is "ksh -s".  The default is "posix".

       -W use-getconf
	      Opposite of --no-getconf.

       -W allow-rpm
	      Defaults File Option: swbis_allow_rpm
	      Enable  automatic  detection,  translation  to Posix format, and
	      installation of RPMs.

       -W pump-delay1=NANOSECONDS
	      Adds a NANOSECONDS delay	(999999999  nanoseconds  ~  1  second)
	      every  ADJSIZE  bytes  in  the  file data byte pump.  A delay of
	      10111000 nanoseconds (~1/100th second) is  added	for  2-hop  or
	      greater target (i.e more than 1 remote host in the target spec).
	      This is a work around for a bug in  OpenSSH  [or	Linux  kernel]
	      that  is seen for multi-hop installs where the intermediate host
	      is a Linux kernel.  If 2-hop install fails, try  it  again,  you
	      may  get	lucky,	or,  increase this delay, or, use ssh protocol
	      version 1 by using ''--ssh-options=1'', or try a	2-hop  install
	      where  the  middle  host is BSD.	To disable delay for multi-hop
	      targets specify zero.  For more information about this  bug  see
	      the README file from the source distribution.

       -W burst-adjust=ADJSIZE
	      ADJSIZE  is the pumped data size, in bytes, between the NANOSEC-
	      ONDS delays.  This is a work around for a bug in OpenSSH or  the
	      Linux  kernel  that  is  seen  for  multi-hop installs where the
	      intermediate host is a Linux kernel.  The default is  72000  for
	      2-hops  or  greater,  and  zero  for  single  hop  and localhost
	      installs.

       -W ssh-options=OPTIONS
	      ssh client program options.  For example -W  ssh-options=1  sets
	      the

       -W source-script-name=NAME
	      Write  the  script that is written into the remote shell's stdin
	      to NAME.	This is useful for debugging.

       -W target-script-name=NAME
	      Write the script that is written into the remote	shell's  stdin
	      to NAME.	This is useful for debugging.

       software_selections

	      Refer  to  the software objects (products, filesets) on which to
	      be operated.  (Not  implemented).   The  implementation  defined
	      behavior for no selections is to operate on the entire distribu-
	      tion.


       target

	      Refers to the software_collection where the software  selections
	      are  to  be  applied.  Allows specification of host and pathname
	      where the software collection is to be located.  A  target  that
	      contains	only  one  part is assumed to be a hostname.  To force
	      interpretation as a path, use an absolute path  or  prefix  with
	      ':'.  The default target path for 'swinstall' is always '/'.

	       Source and Target Specification and Logic

		   Synopsis:
			Posix:
			     host[:path]
			     host
			     host:
			     /path  # Absolute path

			Swbis Implementation Extension:
			     -	  # This means write the payload to stdout
			     [user@]host[:path]
			     :path  # Relative or absolute path

			Swbis Multi-hop Target Implementation Extension:
			     # '@@' is the target delimiter
			     target@@target[@@targetN...]
			     [user@]host[@@[user@]host[@@...]][:path]

		   A more formal description:

		   target : HOST_CHARACTER_STRING ':' PATHNAME_CHARACTER_STRING
			  | HOST_CHARACTER_STRING ':'
			  | HOST_CHARACTER_STRING
			  | PATHNAME_CHARACTER_STRING
			  | ':' PATHNAME_CHARACTER_STRING   # Impl extension
			  ;

		     PATHNAME_CHARACTER_STRING must be an absolute path unless
				     a HOST_CHARACTER_STRING is given.	Allowing
				     a relative path is a feature of the swbis
				     implementation.

			      NOTE: A '.' as a target is an implementation
				    extension and means extract in current
				    directory.

			      NOTE: A '-' indicating stdout/stdin is an
				    implementation extension.

			      NOTE: A ':' in the first character indicates a filename.
				    This is an implementation extension.

		     HOST_CHARACTER_STRING is an IP or hostname.

		  Examples:
		      Translate your RPM on stdin to a tar archive on stdout
		      containing the RPM payload.

			    swinstall -s - @- | tar tvf -

		      Install the distribution /var/tmp/foo.tar.gz to the
		      root '/' directory at 192.168.1.10 :

			    swinstall -s /var/tmp/foo.tar.gz @192.168.1.10
			    NOTE: For swinstall, '/' is the hard coded default
				  target directory.

		      Install the distribution /var/tmp/foo.tar.gz to the
		      home directory of the login user at 192.168.1.10 :

			    swinstall -s /var/tmp/foo.tar.gz @192.168.1.10:.


	      Implementation Extension Syntax (multi ssh-hop) :
		  Syntax:
		  %start   wtarget    # the Implementation Extension Target
		  wtarget   : wtarget DELIM sshtarget
			    | sshtarget
			    ;
		  sshtarget : user '@' target # Note: only the last target
			    | target	      # may have a PATHNAME
			    ;
		  target   : HOST_CHARACTER_STRING
			   | HOST_CHARACTER_STRING ':' PATHNAME_CHARACTER_STRING
			   ;
		  user	   : PORTABLE_CHARACTER_STRING	# The user name

		  DELIM    : '@@'   # The multi-hop delimiter.
			   ;




INSTALLED SOFTWARE CATALOG
       **  As  of  2004-02-12  the  form and features of the catalog are under
       active development. **

       The form or format of an installed software catalog is not specified by
       the  ISO/IEC  spec  although  it  does specify an interface to it (e.g.
       swlist utility) and operations on it.

       This implementation  creates  a	de-facto  installed  software  catalog
       rooted at the file system path specified by the value of the and direc-
       tories.

   CATALOG FILE LAYOUT
	<path>/
	<path>/<ISC>/
	<path>/<ISC>/<bundle>/
	<path>/<ISC>/<bundle>/<product>/
	<path>/<ISC>/<bundle>/<product>/<pr>/
	<path>/<ISC>/<bundle>/<product>/<pr>/<seqence_number>/
	<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/export/
	<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/export/catalog.tar
	<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/export/catalog.tar.sig
	<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/export/catalog.tar.sig<N>
	<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/INSTALLED
	<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/control.sh
	<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/session_options
	<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/vendor_tag


       <path> is the target path.  <ISC> is the value of  the  installed_soft-
       ware_cataglog  extended	option.  <bundle> and <product> are bundle and
       product tags.  If there is no bundle in the  distribution  the  product
       tag  is used.  <pr> is the product revision.  Other items are explained
       below.

   CATALOG LOCATION
       /<path>/
       /<path>/<installed_software_catalog>/
       /<path>/<installed_software_catalog>/...


       * Root or Alternate Root
       /<path>/

       <path>/ is the target path specified in the target syntax.  By  default
       "/".

       * Catalog Relative Root Directory
       /<path>/
       /<path>/<installed_software_catalog>/

       <installed_software_catalog>/  is  the  value of the extended option by
       the same name.  By default "var/lib/swbis/catalog".

   PACKAGE CATALOG RELATIVE ROOT
       /<{bundle|prod}.tag>/<prod.tag>/<prod.revision>/...

	In other words, if 'product' and 'bundle' refers to  tags,  and  prod-
       uct_revision  is  the  value of the product.revision attribute then the
       path segment is:

	/bundle/product/product_revision


   CATALOG SEQUENCE NUMBER
	/<sequence_number>/
	/<sequence_number>/...


       sequence_number is a decimal integer starting with '0'.	It  is	chosen
       by swinstall to be unique at the time of installation.

   CATALOG CONTENTS
       <sequence_number>/
	<sequence_number>/export/
	<sequence_number>/export/catalog.tar
	<sequence_number>/export/catalog.tar.sig
	<sequence_number>/INSTALLED
	<sequence_number>/control.sh
	<sequence_number>/session_options
	<sequence_number>/vendor_tag


       The export directory
	export/
	export/...
	export/catalog.tar
	export/catalog.tar.sig
	export/catalog.tar.sig2
		      ...
	export/catalog.tar.sigN


       The export/ is a file system directory and its name is constant for all
       packages and is unique to the swbis implementation.   The  export/cata-
       log.tar	file  is  the  signed  file  from the Posix distribution.  The
       export/catalog.tar.sig file is the signature file  from	the  distribu-
       tion.   If  there  is more than one signature, then it is the last one.
       export/catalog.tar.sig2 is the next to last signature, and export/cata-
       log.tar.sigN  is  the  first one, where N is the total number of signa-
       tures.

       INSTALLED -- The state metadata file
	<sequence_number>/INSTALLED


       The INSTALLED file is similar to an INDEX file in its grammar and  syn-
       tax.   Unlike  an  INDEX file, it may contain control_file definitions.
       The INSTALLED file stores the control script return codes  and  fileset
       installation  state.   It is updated several times during the operation
       of 'swinstall'.	It can be parsed  using   libexec/swbisparse  and  the
       '--installed' option.

       control.sh -- The master control script
	<sequence_number>/control.sh
	 SYNOPSIS: control.sh tag_spec script_tag


       The  control.sh file is a Posix shell script that is automatically gen-
       erated by swinstall.  It provides a common interface for control script
       execution.   Its  primary  purpose  is to set up the script's execution
       environment and map script tags to the control  script  pathnames.   It
       assumes that 'export/catalog.tar' is unpacked in export/.

       session_options -- The extended options
	<sequence_number>/session_options


       This  file contains the extended options in a form that may be executed
       by the shell '.' (dot) command.	It is automatically generated by swin-
       stall.  The value of the SW_SESSION_OPTIONS environment variable is the
       absolute pathname of the this file.

   EXAMPLE CATALOG ENTRY
       Below is an example entry of  the  catalog  created  by	swbis  version
       0.405.	 In   this  example,  the  target  path  is  '/mnt/test',  the
       installed_software_catalog is '/var/lib/swbis/catalog/', the bundle tag
       is  'foobare',  the product tag is 'foobare-doc', and the product revi-
       sion attribute is '0.902'.

       /mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/export
       /mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/export/catalog.tar
       /mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/export/catalog.tar.sig
       /mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/INSTALLED
       /mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/control.sh
       /mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/vendor_tag
       /mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/session_options


       Although swinstall does not depend on the file name  as	this  accommo-
       dates  installing  from standard input, a typical name for this package
       would be:

	      foobare-doc-0.902-sl04.tar.gz

	where 'sl04' is the vendor tag.

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 standard
       input, the distribution will be unpacked (e.g. pax -r) in the directory
       '.'.  If the source is a regular file then a regular file in  '.'  will
       be created with the same name.


   RPM Translation
       RPM  (RedHat  Package  Manager)	format packages are installed by first
       translating to an equivalent ISO/IEEE file layout in Posix  tar	format
       and then installing as a Posix package.	This translation and detection
       is transparent to the user if the ''--allow-rpm'' option is set in  the
       command	line  args  or	the  swbis_allow_rpm  is  set to "true" by the
       defaults files, otherwise an error occurs.

       Since translation is done on the local (management) host,  RPM  is  not
       required on the remote (target) host.

       The translation is (internally) equivalent to :

	  cat your-0.0-1.bin.rpm |
	  /usr/lib/swbis/lxpsf --psf-form2 -H ustar |
	  swpackage -W source=- -s @PSF | swinstall -s - @/


   Testing with RPM
	To  test  the  swbis  components,  a  completely  independent means to
       install and verify a package is needed.	RPM provides  this  means  and
       can be used in the following way:

	  rpm -i --nodeps --force your-0.0-1.i386.rpm  # Install
	  rpm --verify --nodeps your-0.0-1	       # Show that all is well
	  rpm -e --nodeps your-0.0-1		       # Remove it.
	  rpm -i --nodeps --justdb your-0.0-1.i386.rpm # Install just the database.
	  rpm --verify --nodeps your-0.0-1	       # Shows the files are missing.
	  swinstall --allow-rpm -s - < your-0.0-1.i386.rpm
	  rpm --verify --nodeps your-0.0-1	       # Show that all is well again


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

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.499
	Last Updated: 2006-02-01
	Copying: GNU Free Documentation License

BUGS
       swinstall is subject to breakage if a user's account on an intermediate
       (or  terminal)  host in a target spec is not configured to use a Bourne
       compatible shell. (This breakage may be eliminated by use of the  --no-
       getconf option as explained above.)

       A  multiple  ssh  hop source spec  (more than 1 remote host involved in
       the source transfer) upon a SIGINT may result in sshd and ssh processes
       being  left  on	on the intermediate host(s), this despite, swinstall's
       action of sending a SIGTERM to the remote script's parent process.

       swinstall does not currently implement Software Selections, not fileset
       dependencies,  and  much  more.	Only packages with one product and one
       fileset are supported.



								  swinstall(8)


Next: , Previous: (swbis_swcopy), Up: Command Reference

swcopy.8 in one text file

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, file-
       name,  and  other  stored data in the compressed format will be differ-
       ent).

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


       -s SOURCE

	      Specify the source file SOURCE, "-" is standard input.  The syn-
	      tax 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.  (Implementation
	      extension option).
	      -v  is level 2, -vv is level 3,... etc.
		  level 0: silent on stdout and stderr.
		  level 1: fatal and warning messages to stderr.
	      -v  level 2: level 1 plus a progress bar.
	      -vv level 3: level 2 plus script stderr.
	      -vvv level 4: level 3 plus events.
	      -vvvv level 5: level 4 plus events.
	      -vvvvv level 6: level 5 plus set shell -vx option.
	      -vvvvvv level 7 and higher: level 6 plus debugging messages.
	       The  progress meter is suppressed if swcopy is using stdout for
	      data.

       -b SIZE

	      Set block size, same as --block-size=N (Implementation extension
	      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 arbi-
	      trary 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 tar-
	      get.

       -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 warning is
	      emitted to stderr which says that the usage may be insecure.

       -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 command
	      line options.

       -W pax-command={tar|pax|star|gtar}
	      Set the  portable  archive  command  for	all  operations.   The
	      default is "pax".

       -W pax-read-command={tar|pax|star|gtar}
	      Set the read command for local and remote hosts.

       -W remote-pax-read-command={tar|pax|star|gtar}
	      Defaults File Option: swbis_remote_pax_read_command
	      Set the read command for remote hosts.  This is the command that
	      runs on the target (e.g. pax -r, tar xpf	-).   The  default  is
	      "pax".

       -W local-pax-read-command={tar|pax|star|gtar}
	      Defaults File Option: swbis_local_pax_read_command
	      Set  the read command for local hosts.  This is the command that
	      runs on the target (e.g. pax -r, tar xpf	-).   The  default  is
	      "pax".

       -W pax-write-command={tar|pax|star|gtar|swbistar}
	      Set  the	write command for local and remote hosts.  This is the
	      command that runs on the target (e.g. pax -w, tar cf -).

       -W remote-pax-write-command={tar|pax|star|gtar|swbistar}
	      Defaults File Option: swbis_remote_pax_write_command
	      Set the write command for remote hosts.

       -W local-pax-write-command={tar|pax|star|gtar|swbistar}
	      Defaults File Option: swbis_local_pax_write_command
	      Set the portable archive write command  for  local  host	opera-
	      tions.   This  is  the command that runs on the source (e.g. pax
	      -w, tar cf -).  The default is "pax".

       -W remote-pax-write-command={tar|pax|star|gtar|swbistar}
	      Defaults File Option: swbis_remote_pax_write_command
	      Set the portable archive write command for  remote  host	opera-
	      tions.   This  is  the command that runs on the source (e.g. pax
	      -w, tar cf -).  The default is "pax".

       -W no-defaults
	      Do not read any defaults files.

       -W no-remote-kill
	      Defaults File Option: swbis_no_remote_kill
	      Disables the use of a second remote connection to tear down  the
	      first  in  the  event of SIGINT or SIGTERM or SIGPIPE.  Only has
	      effect if the number of ssh hops is greater than	1.   A	single
	      host  remote connection (ssh hop = 1) never uses a second remote
	      connection.

       -W no-getconf
	      Defaults File Option: swbis_no_getconf
	      Makes the remote command be '/bin/sh -s' instead of the default

       -W shell-command=NAME
	      Defaults File Option: swbis_shell_command
	      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 distribu-
	      tion.


       target

	      Refers  to the software_collection where the software selections
	      are to be applied.  Allows specification of  host  and  pathname
	      where  the  software  collection is 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]
		      :path

		 Swbis Multi-hop Target Extension:
		      # '@@' is the target delimiter
		      target@@target[@@targetN...]
		      [user@]host[@@[user@]host[@@...]][:path]

	    A more formal description:

	    target : HOST_CHARACTER_STRING ':' PATHNAME_CHARACTER_STRING
		   | HOST_CHARACTER_STRING ':'
		   | HOST_CHARACTER_STRING
		   | PATHNAME_CHARACTER_STRING
		   | ':' PATHNAME_CHARACTER_STRING   # Impl extension
		   ;

	      PATHNAME_CHARACTER_STRING must be an absolute path unless
			      a HOST_CHARACTER_STRING is given.  Allowing
			      a relative path is a feature of the swbis
			      implementation.

		       NOTE: A '.' as a target is an implementation
			     extension and means extract in current
			     directory.

		       NOTE: A '-' indicating stdout/stdin is an
			     implementation extension.

		       NOTE: A ':' in the first character indicates a filename.
			     This is an implementation extension.

	      HOST_CHARACTER_STRING is an IP or hostname.

	   Examples:
	      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
	   wtarget   : wtarget DELIM sshtarget
		     | sshtarget
		     ;
	   sshtarget : user '@' target # Note: only the last target
		     | target	       # may have a PATHNAME
		     ;
	   target   : HOST_CHARACTER_STRING
		    | HOST_CHARACTER_STRING ':' PATHNAME_CHARACTER_STRING
		    ;
	   user     : PORTABLE_CHARACTER_STRING  # The user name

	   DELIM    : '@@'   # The multi-hop delimiter.
		    ;



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 targets.
       The syntax does not support multiple source files.  A portable  charac-
       ter  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 existence
       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 tar-
       get  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	command  (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 standard
       input, the distribution will be unpacked (e.g. pax -r) in the directory
       '.'.   If  the source is a regular file then a regular file in '.' will
       be created with the same name.

       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 trans-
       lating  to  an  equivalent ISO/IEEE file layout in POSIX tar format and
       then copying as a POSIX package.  The  RPM  detection  and  translation
       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  pub-
       lic 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 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.499
	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 processes
       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 fileset
       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 mangles 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 environ-
       ment is 100% GNU/Linux using GNU tar is safe (GNU tar 1.13.25 is recom-
       mended).   Swcopy  does	not  support  using the cpio utility since its
       archive writing interface is unlike pax and tar, although, future  sup-
       port is possible for archive reading.



								     swcopy(8)


Next: , Previous: (swbis_swverify), Up: Command Reference

swverify.8 in one text file

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 distribution
       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 soft-
	      ware.

       -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  verification  on
	      the  directory (unpacked tarball), not tarball verification.  It
	      is required when verifying an exported or  working  SCM  (Source
	      Code Management, such as CVS) directory if the SCM does not pre-
	      serve 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  directory.
	      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 veri-
	      fying 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  distribu-
       tion  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 direc-
       tory, which include tar utility dependence and file owner/group	speci-
       fication, 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.  swverify
       will  set  this variable to "checkfile" if the --scm or --cvs option is
       used, and otherwise to "checkdigest".  The script  may  take  different
       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 system 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 custom
       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 ver-
       ification 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 authen-
       ticated.


       Assuming you successfully verified the catalog as shown above, now gen-
       erate the message digest and compare it to the  md5sum  file  attribute
       from the same byte stream that gpg(1) claims is authenticate.

	 #!/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  iden-
       tical  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.

       authenticate the exported catalog signature.  If it  is	successful  it
       executes  the 'checkdigest' script found in the 'catalog/dfiles' direc-
       tory 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.

       file  storage structure) of a directory (unpacked) form of a POSIX dis-
       tribution.  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 sys-
       tem.   The  validity of a successful comparison depends on the validity
       of the installed software catalog.  swverify makes no attempt to  check
       the  validity  of the entire catalog, however, it can use the distribu-
       tion GPG signature, which is stored in the catalog, to authenticate 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 pay-
       load 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 direc-
       tory 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.499
	Last Updated: 2006-08-03
	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, permissions 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 interpreta-
       tion of data in the verification of that same  data  therefore  opening
       possible attack vectors.



								   swverify(8)


Next: , Previous: (swbis_swign), Up: Command Reference

swign.1 in one text file

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 loads the	'./catalog/'  meta-data  directory  into  the  current
       directory  and  then,  using  GNU  tar  and the distribution file list,
       writes 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  './cata-
       log/'   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 writ-
       ten 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 policy.


       --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 or '-' for stdin.  If this is not given then the
	      internally generated PSF	is  used.   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'.


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


       -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 --show-psf
	       -or-
	  swign -o 0 -g 0 --show-psf





       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 spe-
       cial character sequence '%__NAME'  where NAME is either 'tag' or 'revi-
       sion'.  '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.499
	Last Updated: 2006-08-03
	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 order-
       ing.   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)


Next: , Previous: (swbis_lxpsf), Up: Command Reference

lxpsf.1 in one text file

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


Previous: sw.5 in one text file, Up: Command Reference

swpackage.5 in one text file

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 format
       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 differ-
       ent 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 format
       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 out-
       put block size is 10240 bytes.  The last block is not padded and there-
       fore  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  connotes  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  Defini-
       tions  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.  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 logi-
       cally terminate the current object even if the current object has logi-
       cally 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 development
       system where the swpackage utility will find the script.   The  keyword
       is  the value of the tag attribute and tells the utilities when to exe-
       cute the script.  The path attribute is optional and specifies the file
       name in the packages distribution relative to the control_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 typ-
       ically a temporary or build location and dest is its  unrealized  abso-
       lute 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 specifica-
	      tion.

       path

	      path defines the destination path where the file will be created
	      or  installed.   If  it is a relative path, then the destination
	      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 syntax
       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 dis-
       tribution contains just one product.

       For example, the package NAME and VERSION are referred from the product
       tag  and  revision,  not  the distribution's.  This convention supports
       multiple products in a distribution and is consistent  with  the  stan-
       dard.

       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 distri-
	      bution tag attribute and swpackage's response to it is an imple-
	      mentation extension.  The leading package path can also be  con-
	      trolled 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.


       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 associates	the  vendor  object  from  the
	      INDEX  file.   This attribute is optional.  This attribute value
	      should strive to be unique among all distributors.  It is one of
	      the  version distinguishing attributes of a product specified by
	      the standard.  It is transfered into the installed_software cat-
	      alog  (not  as  a  path  name  component) by swinstall.  If this
	      attribute exists there should also be a vendor object in the PSF
	      in the distribution object that has this tag.  This attribute is
	      assigned the value of RPMTAG_RELEASE by swpackage when translat-
	      ing  an RPM.  In this capacity it serves to distinguish products
	      with the same revision and tag from the same or  different  dis-
	      tributor.   It  most  closely  maps  to  the  RPMTAG_RELEASE  or
	      "debian_revision" attributes.

   o Fileset Attributes
       A fileset defines the fileset.

       tag

	      tag is the short, file system friendly, name of the fileset.  It
	      is required.

       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 bun-
       dle 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.499
	Last Updated: 2006-07-01
	Copying Terms: GNU Free Documentation License

BUGS
       None



								  swpackage(5)


Next: , Previous: (swbis_sw), Up: Command Reference

sw.5 in one text file

sw(5)									 sw(5)



NAME
       sw -- POSIX Software Packaging

SYNOPSIS
       Software Packaging Layout
       Software Definitions
       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 direc-
       tory names, they are the default names for the Distribution and Product
       files  directories.   The  dfiles  and  pfiles  defaults  are  commonly
       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 typi-
       cally the package name and version.  The use of nil control directories
       is not attested to in the posix normative references.

	<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 pertain-
       ing to the distribution.  It can also store an attribute of the distri-
       bution 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 control_direc-
       tory  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 prod-
       uct.

   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 directories
       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.
	  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 qual-
       ified  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 distri-
       bution 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 defini-
       tions.	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 generated
       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.


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

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  logi-
       cally terminate the current object even if the current object has logi-
       cally 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 development
       system  where  the swpackage utility will find the script.  The keyword
       is the value of the tag attribute and tells the utilities when to  exe-
       cute the script.  The path attribute is optional and specifies the file
       name in the packages distribution relative to the control_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 typ-
       ically  a  temporary or build location and dest is its unrealized abso-
       lute 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  specifica-
	      tion.

       path

	      path defines the destination path where the file will be created
	      or installed.  If it is a relative path,	then  the  destination
	      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 syntax
       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 indi-
       vidual file md5 digests.


   Archive Digests
       md5sum and sha1sum are the md5 and sha1 digests (ascii representations)
       of the leading package directories that do not have the	catalog  path-
       name  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


   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 veri-
       fying  file integrity of the directory form of a package in an environ-
       ment where the modification time of symbolic link files	are  not  pre-
       served  from the serial archive by the tar utility or operating system.
       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 tam-
       pering.	 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 sig-
       nature 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) fol-
       lowed  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 Md5 Digest
	      file.md5sum

       Each file has a md5 digest in the metadata.

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 gener-
       ated  by the 'swpackage' command.  The location in the directory struc-
       ture indicates the higher level object to which	their  data  pertains.
       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 utility.	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, bundle,
       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  dis-
       tribution contains just one product.

       For example, the package NAME and VERSION are referred from the product
       tag and revision, not the  distribution's.   This  convention  supports
       multiple  products  in  a distribution and is consistent with the stan-
       dard.

       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 distri-
	      bution tag attribute and swpackage's response to it is an imple-
	      mentation  extension.  The leading package path can also be con-
	      trolled 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.


       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	associates  the vendor object from the
	      INDEX file.  This attribute is optional.	This  attribute  value
	      should strive to be unique among all distributors.  It is one of
	      the version distinguishing attributes of a product specified  by
	      the standard.  It is transfered into the installed_software cat-
	      alog (not as a path  name  component)  by  swinstall.   If  this
	      attribute exists there should also be a vendor object in the PSF
	      in the distribution object that has this tag.  This attribute is
	      assigned the value of RPMTAG_RELEASE by swpackage when translat-
	      ing an RPM.  In this capacity it serves to distinguish  products
	      with  the  same revision and tag from the same or different dis-
	      tributor.   It  most  closely  maps  to  the  RPMTAG_RELEASE  or
	      "debian_revision" attributes.

   o Fileset Attributes
       A fileset defines the fileset.

       tag

	      tag is the short, file system friendly, name of the fileset.  It
	      is required.

       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 bun-
       dle  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.499
	Last Updated: 2006-01
	Copying Terms: GNU Free Documentation License

BUGS
       None



									 sw(5)


Next: , Previous: Introduction, Up: Top

Glossary

(This section is currently under construction).

Distribution
This refers to the package in either a directory form (unpacked) or a serial archive form (e.g. a compressed tarball). A distribution is always in the form of the POSIX software packaging layout.
Exported Catalog Structure
This refers to the first portion of the distribution, the portion of the distribution that is contained in the catalog directory.
File Storage Structure
This refers to the second portion of the distribution, the portion that is not the catalog portion but follows it. The control directory names for products and filesets are repeated from the Exported Catalog Structure and serve to segregate and annotate the files that make up the fileset.
Installed Software
This refers abstractly to installed software files and installed software catalog.
Installed Software Catalog
This refers to the catalog of installed software. The form of this catalog is not specified by the standard.
software_spec
A software_spec follows a specific syntax of dot separated tags optionally followed by a comma (,) and then a comma separated list of version identifiers.
Software Selection
A software selection has the form of a software_spec. A Software Selection appears before the '@' and the targets on the command lines.
Target
A target specifies a host and file name on the host. The GNU implementation also supports a syntax to specify a user name on the host. A list of one or more targets is given after a single '@' and are the the last arguments on the command line.


Next: , Previous: Host Requirements, Up: Top

2 How to configure swbis

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


Next: , Up: Configuring swbis

swdefaults

# 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.reinstall				= false
#swverify.select_local				= 
#swverify.software				= 
#swverify.targets				= 
#swverify.verbose				= 1

#swlist.distribution_target_directory		= /var/spool/sw
#swlist.installed_software_catalog		= var/lib/swbis/catalog
#swlist.one_liner				= revision title
#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


Next: , Previous: swdefaults configuration file, Up: Configuring swbis

swbisdefaults

# 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

#swcopy.swbis_no_getconf			= false # true or false, Deprecated.
#swcopy.swbis_shell_command			= posix # {sh|bash|posix}
#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

#swinstall.swbis_no_getconf			= false # true or false, Deprecated.
#swinstall.swbis_shell_command			= posix # {sh|bash|posix}
#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_enforce_sig			= false
#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"

#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}
#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

# end of swbisdefaults file


Next: , Previous: swbisdefaults configuration file, Up: Configuring swbis

Archive Reading/Writing Utility Selection

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}


Previous: Archive Reading/Writing Utility Selection, Up: Configuring swbis

Shell Selection

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}


Next: , Previous: About This Manual, Up: Top

Introduction

3 Introduction

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.


Next: , Previous: Copying This Manual, Up: Top

About This Manual

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.


Next: , Previous: Applicable Standards, Up: Top

Other Resources

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.


Next: , Previous: Command Reference, Up: Top

Making PSFs for Package Creation

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


Next: , Previous: (swbis_sw)EXTENDED DEFINITIONS, Up: Making PSFs for Package Creation

PSF.minimal

# 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


Previous: A Minimal PSF, Up: Making PSFs for Package Creation

A PSF for Source Packages

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.


Next: , Previous: (swbis_swverify)VERIFYING SIGNATURES, Up: Top

Installing POSIX Distributions

This is as simple as:

     swinstall <your-package
The default target directory is always '/'. See Command Reference.


Next: , Previous: Other Resources, Up: Top

Host Requirements

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


Next: , Previous: Installing POSIX Distributions, Up: Top

Installing RPM Packages

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.


Next: , Previous: Installing RPM Packages, Up: Top

Translating RPM Format Packages

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


Next: , Previous: Translating RPM Format Packages to a POSIX Distribution, Up: Top

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.


Next: , Previous: Remote Host Operations, Up: Top

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.


Next: , Previous: GNU Toolset Orthogonality, Up: Top

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.


Previous: (swbis_sw)EXAMPLE PACKAGE, Up: Top

Index