Shawn,
Nicely done. Please consider the enclosed comments.
Shawn Walker wrote:
pkg(5): image packaging system
LICENSE ACTIONS ACCEPTANCE PROPOSAL
1. Overview
License actions represent a license or other informational data
Add "textual" after "other"
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".
In updatetool, we've been implementing the default behavior of "true",
understanding that pkg(1) has always implemented a default behavior of
"false". I'm wondering if maybe when the tag is omitted, the value
could be "depends on the client" or "undefined".
must-display A boolean value indicating whether the content of the
action's payload must be displayed by clients during
packaging operations.
What is the default value?
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:
Will the global attributes be stored in the [property] section of the
cfg_cache file?
Presumably the per-publisher value overrides the image value, right?
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.
Presumably explicit is the default value if the policy is not specified?
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.
Default values for these are empty, right?
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.
Here, the policy keyword "license" doesn't match the name of the policy
"license-policy". But below, the keyword "license-display" matches the
name of the policy. It seems redundant to use --policy
license-policy=accept, but it might be nice that the values passed to
the --policy option are all policy names.
* 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.
Currently, policies such as "flush-content-cache-on-success" are set,
unset, and displayed with the set-property subcommand. Policies are
just properties that have a boolean value. Do we really need to add
these policy subcommands?
Is the [policy] section of the cfg_cache file going to be reintroduced?
Thanks.
Tom
* 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,
_______________________________________________
pkg-discuss mailing list
[email protected]
http://mail.opensolaris.org/mailman/listinfo/pkg-discuss
