pkg

HISTORY

1. Summary

The intent of history is to enable pkg clients to maintain a record of all

image-modifying operations that they perform.

2. Discussion

2.1 Operations

    The following operations are currently recorded by the clients that are

    part of pkg(5):

        add-publisher

        image-create

        image-set-attributes

        image-update

        install

        purge-history

        rebuild-index

        refresh-publisher

        remove-publisher

        set-publisher

        set-preferred-publisher

        uninstall

        update-publisher

    These operations were chosen because they have the potential to alter the

    behavior of pkg(5) operations or because they modify an image.

3. History Entries

3.1 Information Recorded

    Each history entry contains a record of basic information about the client

    performing the operation, along with a mix of required and optional

    information about the operation performed.

    The following information about the client is always recorded:

        client_name     - The name of the client performing the operation

                          (e.g. pkg, packagemanager)

        client_version  - The value of pkg.VERSION at the time the client

                          performed the operation (e.g. 2e5300c4f0a4+)

        client_args     - The command-line arguments used when executing the

                          client (e.g. /usr/bin/pkg install foo)

    The following information about the operation performed is always recorded:

        operation_name  - The name of the operation performed (refer to 2.1)

        start_time      - When the operation started (e.g. 20080916T214726Z)

        end_time        - When the operation ended (e.g. 20080916T214800Z)

        userid          - The id of the user that performed the operation

                          (e.g. 0)

        username        - The username of the user that performed the operation

                          (e.g. root)

        result          - The outcome of the operation and the reason for it

                          (e.g. Failed, Transport) This maps to the pkg history

                          output columns of 'outcome' and 'reason'.

    The following information about the operation will be recorded if provided

    by the client or api:

        start_state     - Information about the operation requested before any

                          evaluation of that request is performed (e.g. an

                          image plan before evaluation)

        end_state       - Information about the operation requested after

                          evaluation of that request has been performed (e.g.

                          image plan after evaluation)

        errors          - Any errors that were encountered while performing the

                          operation (i.e. tracebacks, exceptions, etc.)

        be              - The name of the boot environment on which the

                          operation was performed

        be_uuid         - The uuid corresponding to the boot environment

        new_be          - The name of any new boot environment that was created

                          while performing the operation.

        new_be_uuid     - The uuid corresponding to the new boot environment

        snapshot        - The name of the snapshot that was taken as a result of

                          this operation.  If the operation completed

                          successfully and the snapshot was destroyed, this

                          this information is not stored.

3.2 Storage

    Each history entry is recorded in a XML file located in the metadata

    directory of an image (e.g. /var/pkg) in a directory named "history".

    Each XML file is named after the pattern %Y%m%dT%H%M%SZ-sequence.xml.

    Where sequence is a numeric value appended so that when multiple

    operations are performed on an image within the same second (e.g. -02,

    -03, etc.) entries are still written correctly.

3.3 File Format

    It should be noted that this format description is that of a private

    interface and is subject to change.

    History entries are recorded in a XML file with a fairly simplistic

    structure.  The format is as follows:

        The first line of each file is a standard xml header along with the

        encoding used to save the information.  This allows the pkg history

        command to correctly display this information if the client changes

        locales later.

        <?xml version="1.0" encoding="ascii"?>

        The second element of every history XML file is a root element used to

        contain the client and operation information.  Only one per file ever

        occurs.

        <history>

            The client element has a name and version attribute used to record

            client_name and client_version.  Only one per file ever occurs.

            <client name="pkg" version="2e5300c4f0a4+">

                The args element contains one or more "arg" (argument) elements

                that match each element of the system argument list used to

                execute the client.  It has no attributes.  Only one per file

                ever occurs.

                <args>

                    Each arg element contains a CDATA element to encapsulate

                    the raw information for the argument.  It has no attributes.

                    <arg>

                        <![CDATA[/usr/bin/pkg]]>

                    </arg>

                    <arg>

                        <![CDATA[-R]]>

                    </arg>

                    <arg>

                        <![CDATA[/tmp/test-image]]>

                    </arg>

                    <arg>

                        <![CDATA[install]]>

                    </arg>

                    <arg>

                        <![CDATA[SUNWvim]]>

                    </arg>

                </args>

            </client>

            The operation element has the following attributes: name,

            start_time, end_time, userid, and username.  Optional attributes

            are be, snapshot and new_be, indicating the boot environment the

            operation was applied to, the snapshot taken during this operation,

            and any new boot environment created as a result.

            It can also contain the following, optional elements: start_state,

            end_state, and errors.  It only occurs once per file.

            <operation end_time="20080912T225513Z" name="install" result="Succeeded"

                start_time="20080912T225327Z" userid="101" be="solaris" username="username">

                The start_state element is used to store information about the

                operation performed before a request is evaluated (e.g. image

                plan before evaluation).  It always contains a CDATA element with

                the related information and only occurs once per file.  It has no

                attributes.

                <start_state>

                    <![CDATA[UNEVALUATED:

                    +pkg:/[email protected],5.11-0.96:20080825T192756Z

                    ]]>

                </start_state>

                The end_state element is used to store information about the

                operation performed after a request is evaluated (e.g. image

                plan after evaluation).  It always contains a CDATA element with

                the related information and only occurs once per file.  It has no

                attributes.

                <end_state>

                    <![CDATA[None -> pkg:/[email protected],5.11-0.96:20080825T192756Z

                    None -> pkg:/[email protected],5.11-0.96:20080825T183047Z

                    None -> pkg:/[email protected],5.11-0.96:20080825T191747Z

                    None -> pkg:/[email protected],5.11-0.96:20080825T191518Z

                    None -> pkg:/[email protected],5.11-0.96:20080825T193230Z

                    None -> pkg:/[email protected],5.11-0.96:20080825T191411Z

                    None -> pkg:/[email protected],5.11-0.96:20080825T194948Z

                    None -> pkg:/[email protected],5.11-0.96:20080825T191417Z

                    None -> pkg:/[email protected],5.11-0.96:20080825T192030Z

                    None -> pkg:/[email protected],5.11-0.96:20080825T192639Z

                    ]]>

                The errors element contains one or more "error" elements

                that encapsulate the information about each error that was

                recorded during the operation.  It has no attributes, and

                only occurs once per file.

                <errors>

                    Each error element contains a CDATA element to encapsulate

                    the raw information about the error.  It has no attributes.

                    <error>

                        <![CDATA[]]>

                    </error>

                </errors>

            </operation>

        </history>