You might want to deliver multiple implementations of a given application with the following characteristics:
All implementations are available in the image.
One of the implementations is available from a common directory such as /usr/bin for ease of discovery.
An administrator can easily change which implementation is available from the common directory, without adding or removing any packages.
Oracle Solaris 11 delivers multiple implementations of several different applications, such as Java and Python. To specify which implementation is available from a common directory such as /usr/bin, and to enable an administrator to easily change that selection, use a mediated link.
A mediated link manages multiple implementations of an application in a single image. A mediated link is a symbolic link with mediator attributes set (see Attributes of Mediated Links). Software that is packaged with a link action that has mediator attributes is a participant in a mediation. The mediation participant that is available from a common directory such as /usr/bin is called the preferred version. The preferred version in a mediation is determined in one of the following ways:
You can specify a version (mediator-version) or a versioned implementation (mediator-implementation) for each participant in the mediation. You can specify an overriding priority in case of conflicts (mediator-priority).
If a participant in the mediation has a priority specified, the participant with the highest value priority is selected as the preferred implementation.
If no participant in the mediation has a priority specified, and a participant has a version specified, the participant with the highest value version is selected as the preferred implementation.
If no participant in the mediation has a priority or version specified, an arbitrary participant is selected as the preferred implementation. If the mediator-implementation of the selected participant includes a version string, the participant with the highest value version string for that mediator-implementation is selected as the preferred implementation.
An administrator can set the preferred implementation by using the pkg set-mediator command. See Specifying a Default Application Implementation in Adding and Updating Software in Oracle Solaris 11.3.
If only one instance of a particular mediation is installed in an image, then that instance is automatically selected as the preferred implementation of that mediation. If the preferred implementation is set by a system administrator after package installation, installing additional participants in this same mediation does not change the preferred implementation set by the administrator.
The following attributes can be set on link actions to control how mediated links are delivered:
Specifies the entry in the mediation namespace shared by all path names that participate in a given mediation group. Examples include java, python, and ruby.
Every link that has a mediator attribute must also have either a mediator-version attribute or a mediator-implementation attribute. All mediated links for a given path name must specify the same mediator. However, not all mediator versions and implementations need to provide a link at a given path. If a mediation participant does not provide a link, then the link is removed when that participant is selected as the preferred implementation.
Specifies the version of the interface described by the mediator attribute. This attribute is required if mediator is specified and mediator-implementation is not specified. The value of mediator-version is a dot-separated sequence of integers. For ease of use, the value specified should match the version of the package that is delivering the link. For example, the runtime/ruby-19 package should specify mediator-version=1.9. Setting the version value appropriately helps administrators determine what software is participating in the mediation, which packages delivered that software, and which version of the software is currently set as the preferred version. If no participant in the mediation has a mediator-priority set, IPS selects the mediation participant with the highest value mediator-version as the preferred implementation.
Specifies the implementation of the interface described by the mediator attribute. This attribute is required if mediator is specified and mediator-version is not specified. Implementation strings are not considered to be ordered. An implementation is arbitrarily selected by IPS as the preferred implementation if no participant in the mediation has a mediator-version or mediator-priority set.
The value of mediator-implementation can be a string of arbitrary length composed of alphanumeric characters and spaces. If the implementation itself can be versioned, then the version should be specified at the end of the string, after an at sign (@). The version is a dot-separated sequence of integers. If multiple versions of an implementation exist, the implementation with the highest version is selected. For example, a mediator-implementation value of 4DB@12 would be selected over a mediator-implementation value of 4DB@11.
Specifies the priority of the interface described by the mediator attribute. Either a mediator-version or a mediator-implementation must also be specified. For example, if one participant in the mediation has a mediator-version value of 1.6 and another participant has a mediator-version value of 1.7, the participant with the mediator-version value of 1.6 can be specified as the preferred implementation by assigning a mediator-priority attribute.
The mediator-priority attribute can have one of the following values:
The link is preferred over those that do not have a mediator-priority specified.
The link is preferred over those that do not have a mediator-priority specified and over those that have a mediator-priority value of vendor.
The following command shows the currently selected preferred implementations of Python, Ruby, and Secure Shell:
$ pkg mediator python ruby ssh MEDIATOR VER. SRC. VERSION IMPL. SRC. IMPLEMENTATION python vendor 2.6 vendor ruby system 1.9 system ssh vendor vendor sunssh
The following command shows all participants in each of these mediations:
$ pkg mediator -a python ruby ssh MEDIATOR VER. SRC. VERSION IMPL. SRC. IMPLEMENTATION python vendor 2.6 vendor python system 2.7 system ruby system 1.9 system ruby system 1.8 system ssh vendor vendor sunssh
The lower version was selected by the system as the preferred Python implementation because it has a mediator-priority specified, as shown by the VER. SRC. and IMPL. SRC. and by the following command:
$ pkg contents -Ho action.raw -t link -a path=usr/bin/python 'runtime/python*' link mediator=python mediator-version=2.7 path=usr/bin/python pkg.linted.pkglint .dupaction010.2=true target=python2.7 link mediator=python mediator-priority=vendor mediator-version=2.6 path=usr/bin/ python target=python2.6
If you specify mediator=python as the argument to the -a option, the output shows many more links in the python mediation. Remember to include all necessary paths in the mediation.
$ pkg contents -Ho action.raw -t link -a mediator=python runtime/python-26 link mediator=python mediator-priority=vendor mediator-version=2.6 path=usr/bin/ 2to3 target=2to3-2.6 link mediator=python mediator-priority=vendor mediator-version=2.6 path=usr/bin/ python target=python2.6 link mediator=python mediator-priority=vendor mediator-version=2.6 path=usr/bin/ pydoc target=pydoc-2.6 link mediator=python mediator-priority=vendor mediator-version=2.6 path=usr/bin/ idle target=idle-2.6 link mediator=python mediator-priority=vendor mediator-version=2.6 path=usr/bin/ python-config target=python2.6-config link mediator=python mediator-priority=vendor mediator-version=2.6 path=usr/bin/ amd64/python target=python2.6 variant.arch=i386 link mediator=python mediator-priority=vendor mediator-version=2.6 path=usr/bin/ amd64/python-config target=python2.6-config variant.arch=i386 link facet.doc.man=all mediator=python mediator-priority=vendor mediator-version =2.6 path=usr/share/man/man1/python.1 target=python2.6.1
The pkg.linted.pkglint.dupaction010.2=true attribute in the usr/bin/python mediated link in the runtime/python-27 package indicates that the /usr/bin/python link is delivered by more than one package and is a valid mediated link. Mediated links are an exception to the rule that an action can be delivered by only one package. The pkglint utility checks for duplicate actions. Setting pkg.linted.check.id to true bypasses checks for check.id for that action. See Verify the Package and the pkglint(1) man page. Use the pkglint -L command to show the full list of checks that pkglint performs. The description of the pkglint.dupaction010 check is “Mediated links should be valid.”
The higher version was selected by the system as the preferred Ruby implementation.
$ pkg contents -Ho action.raw -t link -a path=usr/bin/ruby runtime/ruby-19 link mediator=ruby mediator-version=1.9 path=usr/bin/ruby pkg.linted.pkglint.dup action010.2=true target=./ruby19
The ssh mediation has only one participant. If you anticipate delivering additional implementations of an application, define the mediation in the original package so that the original package will be a participant in the mediation when other implementations are delivered. Otherwise, you will need to deliver an update to the original package, or users will not be able to select the original implementation as the preferred implementation.
In addition to showing the link action, the following command shows the name of the package where this action is defined.
$ pkg contents -o pkg.name,action.raw -t link -a path=usr/bin/ssh '*' PKG.NAME ACTION.RAW network/ssh link mediator=ssh mediator-implementation=sunssh mediator-priority= vendor path=usr/bin/ssh target=../lib/sunssh/bin/ssh
A mediated link that specifies a mediator-implementation can also specify a mediator-version, a mediator-priority, or both. If all participants in the mediation specify only a mediator-implementation, the system selects the preferred implementation arbitrarily. If the selected mediator-implementation is versioned, the highest version is selected, as shown by the following commands:
$ pkg mediator -a myapp MEDIATOR VER. SRC. VERSION IMPL. SRC. IMPLEMENTATION myapp system system db@12 myapp system system db@11 myapp system system db $ pkg mediator myapp MEDIATOR VER. SRC. VERSION IMPL. SRC. IMPLEMENTATION myapp system system db@12
If another implementation is added to the mediation, that implementation might be selected by the system, as shown by the following commands:
$ pkg mediator -a myapp MEDIATOR VER. SRC. VERSION IMPL. SRC. IMPLEMENTATION myapp system system aa myapp system system db@12 myapp system system db@11 myapp system system db $ pkg mediator myapp MEDIATOR VER. SRC. VERSION IMPL. SRC. IMPLEMENTATION myapp system system aa
Do not deliver the same path as a link in one package and a directory or file in another package. In general, do not deliver the same path more than once. If you deliver the same link path more than once, make sure each instance has a different target, and make sure each instance participates in the same mediation.
Remember to include all necessary paths in the mediation. Libraries, configuration files, man pages, and other file system objects might be different for each implementation.
If you anticipate delivering additional implementations of an application, define the mediation in the original package so that the original package will be a participant in the mediation when other implementations are delivered. Otherwise, you will need to deliver an update to the original package, or users will not be able to select the original implementation as the preferred implementation.
If other software has a dependency on software that participates in a mediation, and if any version of that software satisfies the dependency, use a require-any dependency. See Depend Actions for information about require-any dependencies.
For ease of use, the value specified for mediator-version should match the version of the package that is delivering the link. Setting the version value appropriately helps administrators determine what software is participating in the mediation, which packages delivered that software, and which version of the software is currently set as the preferred version.