pkg(5): image packaging system
LICENSE ACTIONS ACCEPTANCE PROPOSAL
1. Overview
License actions represent a license or other informational data
associated with the contents of a package. A package may deliver
licenses, actions, and other legal informational data that applies to
a package such as disclaimers and guidance to the package installer.
The data, intended to be textual in nature, can then be presented to a
user on-demand, in preparation for a packaging operation, or used to
help define policies that will determine what software can be delivered
into an image.
This proposal has the following core goals for the implementation of
license acceptance functionality:
* Support for non-interactive and interactive package operations
* Enablement of package creators to provide guidance to pkg(5) client
api consumers as to how licensing or other informational data should
be presented and interacted with
* Enablement of administrators and users to query and report on the
licensing or other informational data related to packages contained
within an image
* Enablement of administrators and users to restrict what packages
can be delivered into an image based on the package's provided
licensing information.
To achieve these goals, changes must be made to the following pkg(5)
components:
* License Actions
* Image configuration
* Client API
* Publication API
* cli: pkg(1), pkgsend(1)
* gui: packagemanager(1), updatemanager(1)
This proposal omits the gui programs as a separate team will develop
and
deliver the enhancements related to the changes discussed here.
2. License Action attribute changes and additions
Currently, the license attribute of license actions is not restrictive
enough in what characters are allowed for the name of the license. To
ensure cross-platform compatibility and consistent naming, it is
proposed that the license attribute's definition be amended as follows:
license The keyword identifying the license type, for use in filter
and query operations. The name of the license should be
limited to the characters [A-Za-z][A-Za-z0-9_-.]* as it is
intended that only short, descriptive text be used as the
identifier for the license payload, such as "copyright" or
"CDDLv1". This value must be unique within a package.
This new restriction will only be enforced at publication time to
permit
backwards compatibility with existing packages.
To support license acceptance functionality, new attributes for license
actions are needed to allow packages to provide guidance to pkg(5)
client
api consumers:
must-accept A boolean value indicating whether this license must be
accepted by a user before the related package can be
installed or updated. Acceptable values are "true" or
"false". Omission of this attribute must be considered
equivalent to "false".
must-display A boolean value indicating whether the content of the
action's payload must be displayed by clients during
packaging operations.
3. Image configuration additions
To enable administrators and users to effectively manage the packages
contained within an image, users need to be able to define, on a per-
publisher basis, what the behaviour of the packaging system and clients
should be in the following key areas related to licenses:
* filtering
Administrators and users need to be able to define a policy that
can
be used to determine what packages are delivered into an image
based
on licensing information defined in packages.
* acceptance
Administrators and users need to be able to define a policy that
can
be used to determine what behaviour clients should exhibit when
encountering a license that requires explicit acceptance.
To accomplish this, the following new attributes will be stored in the
image configuration on a per-publisher (and/or global) basis:
license-policy A keyword indicating what the behaviour of clients
should be when the license of a package requires
acceptance. The following keywords are supported:
accept Automatically accepts any license with
must-accept=true after license filtering
has been applied.
decline Automatically declines any license with
must-accept=false after license filtering
has been applied.
explicit Requires explicit acceptance of any
licenses with must-accept=true by the user
after licensing filtering has been applied.
This could be implemented as an interactive
prompt, or by a failure of the client with
a requirement to pass an explicit command-
line option for acceptance.
license-accept A list of license keywords that will be used to mark
any
corresponding licenses as accepted automatically if
they
require acceptance.
license-decline A list of license keywords that will be used to mark
any
corresponding licenses as declined automatically,
regardless of whether they require acceptance.
license-display A keyword indicating what the behaviour of the client
should be when displaying the text of license actions.
The following keywords are supported:
all Suggests clients display the text of all
license
actions, but must display the text of license
actions that have must-display=true.
auto The default value for the image configuration,
which indicates that clients must display the
text of license actions that have
must-display=true.
4. Client API
4.1 pkg.client.api
The client api, to enable license acceptance functionality enforcement
and control for clients, will need to change in the following ways:
* Plan creation will be changed to analyze and determine license
acceptance and or build a list of licenses and their acceptance
status for packages being installed or updated.
* The ImagePlan object will have a new method named 'get_licenses'
added. After plan creation is finished, consumers may call this
method to retrieve a list of tuples containing a LicenseInfo object,
whether the license is allowed by image policy, and the current
acceptance status of the license as detailed later. The default
acceptance status of a license will be 'declined' unless otherwise
defined by image policy or operation policy.
* The ImagePlan object will have a new method named 'set_license' which
will allow callers to mark the explicit acceptance of a package's
license by a user:
set_license(fmri, license_keyword, status)
* Two new exceptions will be added to pkg.client.api_errors. The first
will be named 'PlanExecutionError' and be used as a base exception
class for all plan execution errors. The second exception will be
named 'PlanExecutionLicenseError' and will inherit from the first
exception, while being used to indicate that a licensing related
error occurred.
* Plan execution will be changed to verify that each license that
has must-accept=True has been marked as accepted. If any license
has not been marked as accepted, and requires acceptance, a
'PlanExecutionLicenseError' will be raised.
* Plan execution will be changed to record each package that is part
of the operation using pkg.client.history. The full FMRI, the
keywords identifying the licenses contained within the package, and
acceptance status of each license within a package will be recorded.
The following statuses will be used to indicate a package's license
acceptance:
* accepted
Indicates that the license was accepted through the api,
presumably by the user.
* accepted-policy
Indicates that the license was automatically accepted based
on image policy.
* declined
Indicates that the license required acceptance and was not
marked as accepted.
* declined-policy
Indicates that the license was automatically rejected based
on image policy.
* not-applicable
Indicates that the license did not require acceptance and
was not declined by policy.
4.2 pkg.client.history
To ease logging of license acceptance information, and to accurately
reflect operation failure, the following changes will be made to
pkg.client.history:
* New operation result constants will be added:
RESULT_FAILED_LICENSE_DECLINED
Used to indicate that an operation failed because a license
that required acceptance was not marked as accepted.
RESULT_FAILED_LICENSE_POLICY
Used to indicate that an operation failed because a license
was declined based on image policy.
* log_operation_error() will be changed to ensure that the new
'PlanExecutionLicenseError' triggers an appropriate failure
result as noted above.
LOG_PKG_OP_INSTALL
LOG_PKG_OP_UPDATE
LOG_PKG_OP_REMOVE
* A new method to log license status information about a package will
be added:
log_pkg_license(license_keyword, status)
* A new method to log operation information about a package will be
added:
log_pkg_operation(operation, old_fmri, new_fmri)
5. Publication API
The publication api will be changed to enforce additional verification
on license actions as noted in section 2. However, this additional
verification, though enabled by default, will be optional through the
api so that existing packages can be republished without modification,
when using publication clients such as pkgrecv(1).
6. cli
6.1. pkg(1)
The pkg(1) client that pkg(5) provides needs to be enhanced to provide
the following functionality:
* Explicit acceptance of licensing terms for package operations
A new command-line option as shown below will be added to the
install and image-update subcommands:
--policy license=(accept|decline)
It is intentional that command-line overrides of the
license-accept,
and license-decline image properties are not provided. This option
is named '--policy' in anticipation that there may be other
policies
that a user may wish to control during a packaging operation in the
future.
* Graceful, informative failure due to license-related exceptions
pkg(1) will be changed to exit with return code 4 if a license-
related exception occurs during plan execution. The failure
message
when displayed may look something like this:
The following packages are not permitted by image policy due to
the current image's license policy:
--------------------------------------------------
License A
--------------------------------------------------
Foo
Bar
The following packages contain licenses that require acceptance
before they can be installed (use --policy license=accept to
accept these licenses):
--------------------------------------------------
License B
--------------------------------------------------
Baz
Quux
Note that it may be possible for the same license to be marked as
requiring acceptance in one package and not another, and so the
display above may indicate the same license more than once.
* Display of licenses that require it during packaging operations
A --policy option as shown below will be added:
--policy license-display=(all|auto)
pkg(1) will be changed to retrieve and display the text of any
licenses that must be displayed or have been requested for
display after plan creation. The default value is based on image
policy as noted in section 3.
The display of the license text will be the same as the proposed
output for the 'info' subcommand as noted below.
* Improvement of license display by 'info' subcommand
Currently, the info subcommand will display license information for
one or more given FMRIs but does so without any visual separation
other than a newline between distinct license text output, does not
indicate which package the license belongs to, and does not provide
any clear indication of the keyword identity of a license.
The output of this subcommand will be changed so that the keyword
identity of the license will be clear and a visual separator will
be placed between the output of each license. The revised output
may look something like this:
============================================================
Package: Foo
------------------------------------------------------------
License: copyright
------------------------------------------------------------
Copyright 2009 Example Company, Inc. All Rights Reserved.
------------------------------------------------------------
License: Termsv1
------------------------------------------------------------
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus
in risus sem, id blandit justo. Maecenas nulla massa, mollis sed
lobortis a, placerat vel elit. Quisque eleifend leo ipsum. Donec
feugiat gravida molestie. Nulla facilisi. Nullam sit amet ligula
sed mauris tempor fermentum quis at purus.
============================================================
Package: Bar
------------------------------------------------------------
License: Termsv2
------------------------------------------------------------
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus
in risus sem, id blandit justo. Maecenas nulla massa, mollis sed
lobortis a, placerat vel elit.
* A set-policy subcommand will be added to allow setting policy values
that functions as follows:
set-policy [-p publisher] -n policy-name -v policy-value
If -p is not provided, the policy value is considered global.
* An unset-policy subcommand will be added to allow unsetting/resetting
policy values that functions as follows:
unset-policy [-p publisher] -n license-policy
If -p is not provided, the policy value is considered global.
* A policy subcommand will be added for retrieving policy volues that
functions as follows:
policy [-H] [-p publisher] [-n policy-name]
If -p is not provided, then all matching policy values will be shown.
If -H is provided, headers will be omitted.
If -n is not provided, then only the other options provided will be
used to filter the policies shown.
6.2. pkgsend(1)
The pkgsend(1) client that pkg(5) provides will enforce the additional
publication checks described in section 2 for all packages.
Cheers,
