                                                    packageserver(8)

NAME
    packageserver - shared software management server

SYNTAX
    packageserver [-name replicaName] [-c configFile] [-init]

DESCRIPTION
    This program is the server which provides the package management
    services described in the manpage for packagetool(1).  You must know
    what you are doing before attempting to run this program.  Please
    read the packagetool(1) manpage before proceeding any further.  More
    than likely, you will want to use smgr(1) to run this program
    automatically at system startup, so please read its manpage as well.

    With the -c option, the packageserver reads its configuration from
    the indicated file.  Otherwise, it fetches the configuration from
    the file "siphon.config" in the current working directory.
    
    The packageserver determines from its configuration file whether it
    is the lock server for the local site.  The lock server maintains
    a local database which is a stable record of all known packages and
    package state.   It also writes writes a user-readable "history" file
    which represents a "check-out" history of all packages.

    The lock server database is found in the "locks" subdirectory of the
    current working dir.  If the database doesn't exist, the "-init" option
    allows creation of an empty one.  The "-init" option also instructs
    the packageserver, if it also a lock server, to initially manage the
    set of repositories fond in its configuration file.  At startup time,
    these repositories are added to the lock database.  If there are remote
    sites, each locally known repository is enumerated at each foreign site.
    For each new package found, a local lock database entry is created.
    Each local replica then enumerates its file system and creates a lock
    server entry (managed by the local site) for any package directory found.

    The "-name" option is used to dictate the server name.  Otherwise the
    local host name is used.

    This program should be normally run as superUser so that it can change
    its uid to that of the site owner.

    If the configuration specifies the existence of remote sites, a
    designated packageserver replica will act as a "siphon" server.
    This siphon server is reponsible for propagating package updates
    for all repositories which are shared remotely. 

    The goal of the siphon is to present a consistent view of a a
    repository tree at all sites.  To change a package, a user checks
    it out, makes modifications, and then reships it.  (See
    packagetool(1).)  The ship operation updates the package
    (essentially) instantaneously at the local site, and also enqueues
    it for transmission to the other sites.  Since it typically takes
    several minutes (potentially several hours) for the transmission
    to make it to remote sites, there is an interval during which
    different sites have different versions of the package.  To prevent
    overlapping changes, the package tools use a version number scheme:
    users can only check out a package if the current site has the most
    recent version of that package.

    There is also a package fingerprint skulker that ensures consistency
    among replicas.  (See pkgfp(8).)  The fingerprinter runs every
    night at each site, and fingerprints every package that has changed
    at that site.  The skulker then compares the fingerprints for the
    various sites, and reports any inconsistencies that are found.

    To check the current status of the siphon, use pkgq(1)).

SIPHON CONFIGURATION FILE

    The packageserver gets its configuration information from
    a file.  The contents of this file are interpreted as
    an S-expression which is a list of attribute value pairs.
    The list describes the site to be considered "local"
    by the packageserver.  The following attribute/value pairs
    are recognized:

         site "string"

               The corresponding value is a string which
               names the site being described.  Site names are chosen
               arbitrarily.   We use the convention "S-xxx" (e.g.
               S-SRC, S-PRL).  This attribute is required.

         lockServer "replicaName"

               Specifies the network name of the lock server for
               the site being specified.  For the present, this
               must be an IP hostname recognizable to gethostbyname(3).
               This attribute is required.

         siphonServer "replicaName"

               Specifies the name of the siphon server for
               the site being specified.  For the present, this
               must be an IP address recognizable to gethostbyname(3).
               This attribute can be omitted.  It is irrelevant if
               there are no remote sites, otherwise it defaults to
               the value of the "lockServer" attribute.

          replicaServers  "replicaName1"  "replicaName2" ...

               Specifies a list of server names, one for each replica
               at this site.  This attribute can be omitted.  It defaults
               to a single element list consisting of the value of the
               lock server attribute.  If this attribute exists, the
               lock server name must be included as an value element.

          ipPort "stringPortNumber"

               Determines the IP port to which the packagetools will
               target new requests.  The default Network Object daemon
               (netobjd(1)) serve this purpose instead if no "ipPort"
               is specified.

          remoteSites  site-exprA site-exprB  ...
    
               Each value element of this attribute is in itself an
               attribute-value list representing a remote
               site.  Within these lists, the following attribute
               types are recognized:

                    site
                    siphonServer
                    ipPort
                    route

               The first three have the same semantics as in a top
               level site description.  The "route" attribute is
               optional and is interpreted as follows:

                    route "siteName1" "siteName2" ...

               Updates should not be sent directly to the site being
               described, rather they should be routed through one
               of the sites in the route list.  This list is ordered
               by route preference. The first element is the best candidate.

               The "remoteSites" attribute is optional.

         repositories "repositorySpec1" "repositorySpec2" ...

              This attribute specifies the repositories known to the
              local replica.  Each repositorySpec is a list with three
              elements: a repository name; a file system directory to
              which the repository maps; and an optional list of file system
              directories which may be used to hold packages.  For example:

                  (repositories
                      ("cra" "/proj/cra/pkg"
                           ("/proj/disks/d0/cra"
                            "/proj/disks/d2/cra"
                            "/proj/disks/d3/cra")))

              This indicates single repository "cra" whose file system
              directory is "/proj/cra/pkg".  Three different directories
              in "/proj/disks" are cited as locations for new packages.

              The final list argument in a repositorySpec is intended to
              allow repositories to be split accross multiple volumes.
              At package creation time, the server determines which of
              the listed directories contatins the greatest amount of
              free disk space.  The new package is created there, and
              a symbolic link to the new package is created in the actual
              repository directory (/proj/m3/pkg) if necessary.

         exports "exportSpec1" "exportSpec2" ...

              This attribute specifies the set of export paths known to
              the local replica.  Each exportSpec is itself a list with two
              elements: an export path and a file system directory to which
              the export path corresponds.  For example:

                  (exports ("mips" "/proj/mips"))

              This indicates a single export path knwon as "mips" which
              maps to the local directory name "/proj/mips".

         defaultRepository "repositoryName"

              This attribute specifies the repository name to be used
              as the default by the packagetool(1) when presented with
              a package name which is a relative path name.  This
              attribute is not required.  If it is not present, relative
              package names are disallowed by the packagetool.

          backupServers  "replicaName1"  "replicaName2" ...

              List of package server names. Packages shipped with
              the "-b" option ("shippackage -b") will be backed up on the
              indicated servers.  This attribute is not required.

    For example, consider the SRC configuration file:

        (
            (site "S-SRC")
            (lockServer "swindle.pa.dec.com")
            (replicaServers "swindle.pa.dec.com" "bamboozle.pa.dec.com")
            (owner "firefly")
            (backupServers "swindle.pa.dec.com")
            (defaultRepository "cra")
            (ipPort "5555")
            (repositories
                ("cra" "/proj/cra/pkg"
                    ("/proj/disks/d0/cra" "/proj/disks/d2/cra"
                                          "/proj/disks/d3/cra"))
                ("m3" "/proj/m3/pkg"
                    ("/proj/disks/d0/m3" "/proj/disks/d1/m3"
                     "/proj/disks/d2/m3" "/proj/disks/d3/m3"))
                ("adm" "/proj/adm/pkg" ("/proj/disks/d2/adm"))
                ("src" "/proj/src/pkg" ("/proj/disks/d2/src"))
            )
            (exports
                ("mips" "/proj/mips")
                ("man" "/proj/man")
                ("doc" "/proj/doc")
                ("LINUX" "/proj/LINUX")
                ("m3" "/proj/m3")
                ("local" "/proj/local")
                ("ultrix" "/proj/ultrix")
                ("vax" "/proj/vax")
                ("alpha" "/proj/alpha")
                ("generic" "/proj/generic")
                ("sun3" "/proj/sun3")
            )
            (remoteSites 
                (
                    (site "S-PRL")
                    (siphonServer "mother.prl.dec.com")
                    (ipPort "5555")
                ))))

    This specifies that the local site is name "S-SRC", with a lock server
    and siphon server at the host "swindle.pa.dec.com".  There is a secondary
    packageserver replica at "bamboozle.pa.dec.com".  All repositories
    are file system directories owned by the user "firefly".  This replica
    knows about repositories "cra", "m3", "adm", and "src", and export
    paths "mips", "man", "doc", "LINUX", "m3", "local", "ultrix", vax",
    "alpha", "generic", and "sun3".  Backups will be kept (if requested) at
    the server on swindle.  The default repository for all new packages
    is "cra".  This server listens on TCP port 5555.  There is one remote
    site, S-PRL, whose siphon server can be found at "mother.prl.dec.com"
    listening on IP port 5555.

EXPORT DIRECTORY MANAGEMENT

    As described in the packagetool(1) manpage, the package server allows
    for the "export" of symbolic links to directories outside of the
    repository file space.  These links point back to the repository and
    make it possible to implement search paths containing related files
    from unrelated packages.  This is useful, for example, when publishing
    executable or manpages for public use.

    The packageserver allows for automatic creation of export directories
    under certain conditions:

        1)  A parent of the export path exists in the "exports" map
            (see the previous section).

        2)  The packageserver has the necessary access control rights to
            create the child directory.
            
    It is possible to export a link to a path which is not present at one
    or more local replicas.   Links will be exported at all replicas
    supporting the path nonetheless. 

LOCAL CONFIGURATION

    The standard SRC site is called "S-SRC".  The lock server is 
    swindle.  The lock database and history file can be found in the 
    directory /swindle/usr/adm/servers/ps/locks.

SEE ALSO
    packagetool(1), smgr(1), pkgq(1)

AUTHOR OF OBJECT
    Ted Wobber and Francis Prusker

AUTHOR OF DOCUMENTATION
    Ted Wobber and Francis Prusker

