Shawn Walker wrote:
pkg(5): image packaging system
LICENSE ACTIONS ACCEPTANCE PROPOSAL
As requested, this is the most up-to-date version of the proposal with
all changes discussed so far incorporated (and wrapped at 72 characters):
pkg(5): image packaging system
LICENSE ACTIONS ACCEPTANCE PROPOSAL
1. Overview
License actions provide a way to deliver the textual data
contained within licenses, copyright notices, disclaimers, or
other legally-related documents that need to be associated with
the contents of a package. They also provide a way for packages
to provide guidance to pkg(5) clients as to how this information
should be presented or if it requires acceptance by the user
before the package 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) 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". The reason for this is that many
licenses (especially copyleft ones) do not
require this and clients should not prompt for it
unless provided guidance to do so by the package
creator.
must-display A boolean value indicating whether the content of
the action's payload must be displayed by clients
during packaging operations. Omission of this
value must be considered equivalent to "false".
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.
This is the default value.
license-accept A list of license keywords that will be used to
mark any corresponding licenses as accepted
automatically if they require acceptance. This
value is undefined by default.
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. This value is undefined by default.
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.
Per-publisher values will override the global value based on the
publisher of the package that is being evaluated by the client
api.
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_status(fmri, license_keyword, status)
* To allow pkg.client.api consumers access to set_license_status
and get_licenses(), equivalent wrapper functions will be added
to the PlanDescription object provided by the api.
* 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-policy=(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 policies:
--------------------------------------------------
License A
--------------------------------------------------
Foo
Bar
The following packages contain licenses that require
acceptance before they can be installed (use --policy
license-policy=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 text 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 identity
of a license (e.g. CDDL, BSD, etc.).
The output of this subcommand will be changed so that the
keyword identity of the license will be shown 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 or
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,
--
Shawn Walker
_______________________________________________
pkg-discuss mailing list
[email protected]
http://mail.opensolaris.org/mailman/listinfo/pkg-discuss
