OpenPKG Specs: openpkg/register.pod@a2c6460cfb16 (annotated)

openpkg/register.pod@a2c6460cfb16 (annotated)

openpkg/register.pod

Mon, 28 Jan 2013 17:37:18 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Mon, 28 Jan 2013 17:37:18 +0100
changeset 758: a2c6460cfb16
permissions: -rw-r--r--

Correct socket error reporting improvement with IPv6 portable code,
after helpful recommendation by Saúl Ibarra Corretgé on OSips devlist.

 =pod
 =head1 NAME
 B<openpkg register> - OpenPKG Registry Command-Line Client
 =head1 SYNOPSIS
 B<register> [-u|--user=<user|token>] [-l|--link=<token>] [I<-d|--desc=<text>>]
           [-m|--mode=fake|post|wipe] [I<-a|--args=<args>>]
           [I<--plat=<text>>] [I<--orel=<text>>] [I<--uuid=<file>>]
           [I<--conf=<file>>] [I<--prep=<file>>] [I<--tran=<file>>]
           [I<--util=<file>>] [--data=<tag>[,<tag>...]]
           [I<-P|--preparation>] [I<-T|--transaction>]
           [I<-U|--utilization>] [I<-C|--convenience>]
           [I<-I|--interaction>]
           [I<-v|--verbose>] [I<-h|--help>]
 B<register> -S|--printstatus
 B<register> -R|--rewriteurls [I<url> ...]
 =head1 DESCRIPTION
 B<openpkg register> is the Command-Line Client the OpenPKG Registry. It is
 used by administrators to register an instance with the OpenPKG Registry for
 later association.
 After association, B<openpkg register> can be used for repetitive
 reregistrations which update the heartbeat of the instance on the Registry
 server, avoiding premature depature from the database. It is assumed that
 every instance will be reregistered daily. Dormant
 instances might be discarded from the Registry, revoking their access to
 additional resources.
 =head1 PRIMARY OPERATIONS
 The following primary operations are available:
 =over 4
 =item B<-h>, B<--help>
 Display brief usage message.
 =item B<-v>, B<--verbose>
 Display progress information during data posting.
 =item B<-P>, B<--preparation>
 Execute the primary operation "preparation".
 Creates registry data for one request and dumps it stdout
 in XML format. That request can be filtered and piped into
 the transaction phase or it can be copied and pasted into the
 XMLdump CGI facility manually.
 A copy of the output of the last run is also saved to the C<${REGISTRY_PREP}> file.
 =item B<-T>, B<--transaction>
 Execute the primary operation "transaction".
 Reads registry data with one request from stdin, executes
 the transaction and writes registry data with one or more
 responses to stdout in XML format.
 Depending on the mode of operation, the transaction might be an actual
 transport to the XMLdump CGI facility or a fake activity which complements the
 manual preparation.
 A copy of the output of the last run is also saved to the C<${REGISTRY_TRAN}> file.
 =item B<-U>, B<--utilization>
 Execute the primary operation "utilization".
 Reads registry data with one response from stdin and updates the local
 registry information.
 Depending on the mode of operation, the utilization might be an actual
 processing of a transaction response or a fake activity which complements the
 manual transaction.
 Anyway, this step finalizes the registration process and makes the instance
 assume it has been properly registered. This status can be printed. URL
 rewriting is activated.
 A copy of the output of the last run is also saved to the C<${REGISTRY_UTIL}> file.
 =item B<-C>, B<--convenience>
 Execute the primary operation "convenience".
 This executes the three primary operations "preparation", "transaction" and
 "utilization" in that order and pipes data through this chain.
 =item B<-I>, B<--interaction>
 Execute the primary operation "interaction".
 Like "convenience" but user is interactively asked for information. This is
 the easiest way to do registration but it is not meat to be automated.
 =item B<-S>, B<--printstatus>
 If the instance has been registered, information about the registration is printed in a
 format suitable for shell evaluation and return code is true.
 Otherwise nothing is printed and return code is false.
 =item B<-R>, B<--rewriteurls> [I<url> ...]
 If the instance has been registered, the given URLs are rewritten to prepend
 user:pass information before hostnames below the openpkg.(org|net|com)
 domains.  Note the username is is UUID_REGISTRY and the password is the
 concatenation of UUID_INSTANCE and UUID_PLATFORM from the
 PREFIX/etc/openpkg/uuid file. Both informations are not meant to be used for
 traditional authentication, they are merly statistical information.
 Otherwise the URLs are returned verbatim.
 =back
 =head1 STANDARD OPTIONS
 Standard options are typically used to automate registration (not
 association).
 =over 4
 =item B<-m>, B<--mode> fake|post|wipe
 Overrides C<${REGISTRY_MODE}> variable in C<${REGISTRY_CONF}> file.
 Has no default and is a manadatory setting.
 In B<post> mode, transactions are carried out using real network connectivity.
 The "preparation" step creates a XMLdump and writes it into the
 C<${REGISTRY_PREP}> file. The "transaction" step posts it to the DropXML form
 using a HTTP request. The response coming back from Registration server is
 also in XML format and is saved to  C<${REGISTRY_TRAN}> file.  The
 "utilization" step processes this response and writes the final results to the
 C<${REGISTRY_UTIL}> file.
 In B<fake> mode, no network connectivity takes place.
 The "prepararation" step creates a XMLdump and writes it into the
 C<${REGISTRY_PREP}> file. The "transaction" step is a fake only. It assumes a
 successful response from the Registration server and saves it to
 C<${REGISTRY_TRAN}> file.  The "utilization" step processes this response and
 writes the final results to the C<${REGISTRY_UTIL}> file.
 I<Note>: fake mode is meant as a way to register instances which cannot or must
 not post data directly to the Registration server.
 In B<wipe> mode, the registration is wiped out locally. The status is reset
 and URL rewriting is disabled.
 I<Note>: the registration server is not contacted, the instace must be removed
 manually using the web interface.
 I<Note>: wiping registration is highly recommended as a precursor action of
 cloning activities.
 =item B<-a>, B<--args> "arg [arg ...]"
 Overrides C<${REGISTRY_ARGS}> variable in C<${REGISTRY_CONF}> file.
 Complements the mode and is specific to it.
 Defaults to "http://registry.openpkg.org/register" which is the official registry of the OpenPKG Project.
 This default is useful for "post" mode.
 =item B<-u>, B<--user> I<user|token>
 Overrides C<${REGISTRY_USER}> variable in C<${REGISTRY_CONF}> file.
 Indicates the registry user which will find this registration in his arrival queue.
 The user can also specified as a token which is enabled for use as "user".
 If the token is also enabled for "assoc" the registered instance is immediately associated
 to the user with no need for the user to visit the web interface.
 This information in submitted via the "registry_user" attribute of the XML request.
 Retrieves default online from http://openpkg.org/go/autoregister and is a manadatory setting.
 =item B<-l>, B<--link> I<token>
 Overrides C<${REGISTRY_LINK}> variable in C<${REGISTRY_CONF}> file.
 Indicates the registry user which will find this registration linked to his token.
 The link must be specified as a token which is enabled for use as "link".
 If a user token is used and the link token is also enabled for "assoc" then the registered instance
 is immediately associated to the user with no need for the user to visit the web interface.
 This information in submitted via the "registry_link" attribute of the XML request.
 Has no default and is an optional setting.
 Be aware that linked users see the same information about an instance as the associated user
 can find on his "association" page but they cannot alter or delete information.
 =item B<-d>, B<--desc> I<description>
 Overrides C<${REGISTRY_DESC}> variable in C<${REGISTRY_CONF}> file.
 Indicates a human readable description of the instance.
 This information in submitted via the "registry_desc" attribute of the XML request.
 It appears in the "description" column on the "association" page of the web form and can be edited on the server side.
 Defaults to "openpkg://${FQDN}${PREFIX}"
 =back
 =head1 ADVANCED OPTIONS
 Advanced options can be enganged to tailor and fully automate a registration
 (not association).
 =over 4
 =item B<--plat>
 Overrides C<${REGISTRY_PLAT}> variable in C<${REGISTRY_CONF}> file.
 Indicates the platform. Concatenated information from CPU architecture (arch) and Operating System (os).
 This information in submitted via the "registry_plat" attribute of the XML request.
 Defaults to "%{l_platform -p}", e.g. "ix86-freebsd6.1"
 =item B<--orel>
 Overrides C<${REGISTRY_VERS}> variable in C<${REGISTRY_CONF}> file.
 Indicates the OpenPKG release.
 This information in submitted via the "registry_orel" attribute of the XML request.
 Defaults to "%{l_openpkg_release}", e.g. "OpenPKG-CURRENT", "OpenPKG-2-STABLE", "OpenPKG-2.5",
 =item B<--uuid>
 Overrides C<${REGISTRY_UUID}> variable in C<${REGISTRY_CONF}> file.
 Indicates the UUID file of the instance.
 This information in submitted via the "uuid_registry", "uuid_instance" and "uuid_platform" attributes of the XML request.
 Defaults to F<${PREFIX}/etc/openpkg/uuid>
 =item B<--conf>
 Overrides C<${REGISTRY_CONF}> variable from previous C<${REGISTRY_CONF}> file. Processing
 of the current configuration file is aborted immediately with all variables
 read so far kept. THe new configuration file is read in immediately and
 processing continues there. This works similar to an include but is more
 primitive as it does not allow nesting, only chaining.
 Defaults to F<${PREFIX}/etc/openpkg/register.conf>
 =item B<--prep>
 Overrides C<${REGISTRY_PREP}> variable in C<${REGISTRY_CONF}> file.
 File to save a copy of the output from the "preparation" step.
 Defaults to F<${PREFIX}/etc/openpkg/register.prep>
 =item B<--tran>
 Overrides C<${REGISTRY_TRAN}> variable in C<${REGISTRY_CONF}> file.
 File to save a copy of the output from the "transaction" step.
 Defaults to F<${PREFIX}/etc/openpkg/register.tran>
 =item B<--util>
 Overrides C<${REGISTRY_UTIL}> variable in C<${REGISTRY_CONF}> file.
 File to save a copy of the output from the "utilization" step.
 Defaults to F<${PREFIX}/etc/openpkg/register.util>
 =item B<--data>
 Overrides C<${REGISTRY_DATA}> variable in C<${REGISTRY_CONF}> file.
 Comma separated list of tags to prepare. Available tags are "request",
 "package" and "provides". The "request" refers to the whole thing and
 is mandatory. The "package" includes name-version-release information
 for all installed packages and "provides" adds more details required to
 capture package options. For details see OPENPKG_PREP below.
 Defaults to "request,package,provides"
 =back
 =head1 FILES
 The following files are used by B<openpkg register>:
 =over 4
 =item OPENPKG_UUID=F<${PREFIX}/etc/openpkg/uuid>
  UUID_REGISTRY="..."
  UUID_INSTANCE="..."
  UUID_PLATFORM="..."
 =item OPENPKG_CONF=F<${PREFIX}/etc/openpkg/register.conf>
 Format suitable for shell evaluation. Interactive mode appends remarked date
 and current settings for reuse as new defaults for future runs. Can be preset
 to customize or automate registration.
 =item OPENPKG_PREP=F<${PREFIX}/etc/openpkg/register.prep>
  <?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
  <!DOCTYPE registry
    PUBLIC "-//OpenPKG//DTD OpenPKG Registry 0.0.1//EN"
    "http://registry.openpkg.org/registry.dtd" []>
  <registry>
      <request id="..."
          registry_user="me@example.com"
          registry_desc="openpkg://rm0.openpkg.net/openpkg-dev"
          registry_plat="ix86-freebsd6.1"
          registry_orel="OpenPKG-CURRENT"
          uuid_registry="..."
          uuid_instance="..."
          uuid_platform="..."
      />
      <package id="..." name="ssmtp" version="2.61" release="20050608">
         <provides name="ssmtp::with_ssl" flag="=" version="no"/>
         <provides name="MTA" flag="" version=""/>
         <provides name="ssmtp" flag="=" version="2.61-20050608"/>
      </package>
  </registry>
 The XML request starts with <?xml version ...> and <!DOCTYPE registry ...>
 headers followed by a <registry> container. The request is inside a <request>
 tag. Successful submission into the XMLdump form requires the headers and
 exactly one container. It is possible to merge multiple requests into a single
 container manually or otherwise and submit them all at once.
 =item OPENPKG_TRAN=F<${PREFIX}/etc/openpkg/register.tran>
  <?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
  <!DOCTYPE registry
    PUBLIC "-//OpenPKG//DTD OpenPKG Registry 0.0.1//EN"
    "http://registry.openpkg.org/registry.dtd" []>
  <registry>
      <response id="..." done="yes">openpkg://rm0.openpkg.net/openpkg-dev</response>
  </registry>
 The XML response starts with <?xml version ...> and <!DOCTYPE registry ...>
 headers followed by a <registry> container. The response is inside a <request>
 tag. The data carried in the tag comes from the "description" column on the
 "association" page of the web form and can be edited on the server side.
 =item OPENPKG_UTIL=F<${PREFIX}/etc/openpkg/register.util>
  REGISTRY_DBID="..."
  REGISTRY_DONE="yes"
  REGISTRY_RESP="openpkg://foo.example.com/my/openpkg/prefix"
 =back
 =head1 EXAMPLES
  # su - openpkg-mop
  $ openpkg register --printstatus
  REGISTRY_DBID="..."
  REGISTRY_DONE="yes"
  REGISTRY_RESP="openpkg://foo.example.com/my/openpkg/prefix"
  $ openpkg register --printstatus >/dev/null && echo "Yup"
  Yup
  $ eval `openpkg register --printstatus`; echo DONE=$REGISTRY_DONE
  DONE=yes
  $ openpkg register --mode=wipe
  $ openpkg register --printstatus || echo "Nope"
  Nope
  $ openpkg register --user=thl@openpkg.net --mode=post
  REGISTRY_DBID="...."
  REGISTRY_DONE="yes"
  REGISTRY_RESP="openpkg://foo.example.com/my/openpkg/prefix"
  $ openpkg register --printstatus >/dev/null && echo "Yup"
  Yup
  $ openpkg register --rewriteurls http://download.openpkg.org/foo/bar
  ftp://...:...@download.openpkg.org/foo/bar
 =head1 SEE ALSO
 bash(1), C<openpkg man uuid>, C<http://registry.openpkg.org/>
 =head1 AUTHOR
 Thomas Lotterer E<lt>thl@openpkg.orgE<gt>
 =cut

OpenPKG Specs / annotate

openpkg/register.pod@a2c6460cfb16 (annotated)

openpkg/register.pod