Greetings,
My apologies for not sending this on Dec. 28th when the change was
originally made (I mistakenly believed I already had).
Please __READ THIS__ if you are using or developing tools that perform
automated installs using the pkg(5) client or client API (delivered in
b131+).
Revision 1618:04f7471c9e72 integrated the following fixes and enhancements:
5943 add 'must-accept' attribute to license actions
5586 licenseinfo api needs to expose license action attributes
13155 add 'must-display' attribute to license actions
13158 change pkg.client.api to understand and require license acceptance
13160 pkg(1) needs update for client api license acceptance changes
These changes were made to support packages that require display or
acceptance of license related data during package install and update
operations. As a result of these changes, the pkg(1) client and client
API require explicit acceptance and/or indication of license display
during install and update operations.
Please note that (currently) no packages exist that use this
functionality, but they are expected in the near future.
==============================
Client Software Considerations
==============================
If any of the license actions contained in a package being installed or
updated have must-accept=true, the following pkg(1) subcommands require
that the new --accept option be provided before the operation will proceed:
* install
* fix
* image-update
* change-variant
* change-facet
In addition, all of the above subcommands also now have a --licenses
option to display the payload of all the licenses for packages part of
the operation. For example:
pkg install -n --licenses foo
The above command would display all of the licenses for the packages
that would be installed or updated if the package 'foo' were installed
or updated.
If the --accept option is not provided, and a license requires
acceptance, the pkg(1) client will now exit with exit code 6, indicating
license acceptance failure.
If a license requires display, the pkg(1) client will display it during
install/update operations; this cannot be suppressed.
=========================
Client API Considerations
=========================
Version 29:
Incompatible with clients using versions 0-28:
The ImageInterface class has changed as follows:
* set_plan_license_status() was added. This is used to indicate
whether licenses for the packages being operated on have been
accepted or displayed. Clients must do this if the related
license requires acceptance or display.
The LicenseInfo class has changed as follows:
* get_text() may now trigger a remote retrieval of the license
payload if needed to return the text.
* The related package FMRI and license attributes are now
properties: fmri, license, must_accept, and must_display.
The PlanDescription class has changed as follows:
* get_changes() is now a generator function.
* get_licenses() was added to allow clients to retrieve the
list of licenses related to the plan's operations as well
as the current accepted and displayed status of each. Please
note that this function returns _all_ licenses related to the
operation; not just those that require acceptance or display.
==========================
Publication Considerations
==========================
To use this new license acceptance functionality, simply add
must-accept=true or must-display=true (as appropriate) to license
actions in your package manifest. An example pkgsend sequence might
look like this:
open licensed at 1.3,5.11-0
add depend type=require fmri=baz at 1.0
add file /tmp/libc.so.1 mode=0555 owner=root group=bin path=/lib/libc.so.1
add license/tmp/libc.copyright license=libc.copyright must-display=True
add license /tmp/libc.license license=libc.license must-accept=True
close
Please note that this functionality is not supported before build 131,
and that you should use this functionality sparingly. must-accept=true
should never be placed on open source licenses (GPL, etc.) and
must-display should only be set if absolutely necessary.
Cheers,
--
Shawn Walker
