OpenPKG Specs: comparison openpkg/register.pod

--1:000000000000
+:2b96da343145
+=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 / file comparison

comparison: openpkg/register.pod

openpkg/register.pod