Multiple versions of an application or tool might be available in the same image. Each version of the application is available to users by specifying the full path. One version, called the preferred version, is available from a common directory such as /usr/bin for ease of use. If all versions participate in the same mediation, you can easily reset the version that is the preferred version. This administrative selection is retained across package updates.
A mediation is a set of links in which the link path is the same for each link in the set, and the target of each link is different. For example, the link path might be /usr/bin/myapp and targets of the link might include /usr/myapp/myapp1/bin/myapp and /usr/myapp/myapp2/bin/myapp. Each link in a mediation is called a participant in the mediation. If /usr/bin/myapp currently invokes myapp1, you can easily change the selection so that /usr/bin/myapp invokes myapp2. The version of the software that is currently the target of the link is the preferred version.
If you sometimes must use one version and other times must use a different version, consider specifying the full path rather than changing the mediated link.
Use the pkg mediator command to display the preferred versions of all mediated links in the image.
In the following output, MEDIATOR is the name of the set of links that share the same preferred link path. VER. SRC. and IMPL. SRC. show whether the preferred version was selected by the system, was selected according to an assigned priority (vendor or site) or was set by an administrator (local). VERSION is the version of the selected mediation participant, which should be similar to the version of the software that the link represents. The VERSION is set by the package developer. IMPLEMENTATION is a string that can be set by the package developer in addition to or instead of the version string. Your list will be different, depending on what you have installed.
$ pkg mediator MEDIATOR VER. SRC. VERSION IMPL. SRC. IMPLEMENTATION apache system 2.2 system apr-1-config system 1.5 system apu-1-config system 1.5 system java system 1.8 system openssl vendor vendor default perl vendor 5.12 vendor php vendor 5.3 vendor python vendor 2.7 vendor sendmail vendor vendor sendmail ssh vendor vendor sunssh
The -a option shows all mediation participants. Use this option to show your choices if you want to select a different preferred version. The following example shows all participants in the java mediation. The system keywords indicate that the preferred version in this mediation is not specified with a priority setting in the package and was not set by an administrator: The packaging system selected the version with the higher VERSION value as the preferred version.
$ pkg mediator -a java MEDIATOR VER. SRC. VERSION IMPL. SRC. IMPLEMENTATION java system 1.8 system java system 1.7 system
The following output shows all packages that deliver the java mediation:
$ pkg search -lo pkg.name,mediator-version link:mediator:java PKG.NAME MEDIATOR-VERSION runtime/java/jre-7 1.7 runtime/java/jre-8 1.8
The following output confirms that two different versions of the Java Runtime Environment are installed in this image and version 1.8.0_112 is the currently selected preferred version:
$ pkg list -s '*jre*' NAME (PUBLISHER) SUMMARY runtime/java/jre-7 Java Platform Standard Edition Runtime Environment (1.7.0_131-b12) runtime/java/jre-8 Java Platform Standard Edition Runtime Environment (1.8.0_121-b13) $ java -version java version "1.8.0_121" Java(TM) SE Runtime Environment (build 1.8.0_121-b13) Java HotSpot(TM) 64-Bit Server VM (build 25.121-b13, mixed mode)
The following output shows the mediated links (PATH) and where they link (TARGET):
$ pkg contents -o mediator-version,path,target -t link -a mediator=java jre-8 jre-7 MEDIATOR-VERSION PATH TARGET 1.7 usr/java jdk/jdk1.7.0_131 1.8 usr/java jdk/jdk1.8.0_121 1.7 usr/jdk/jdk1.7.0_131 instances/jdk1.7.0 1.8 usr/jdk/jdk1.8.0_121 instances/jdk1.8.0 1.7 usr/jdk/latest jdk1.7.0_131 1.8 usr/jdk/latest jdk1.8.0_121 $ ls -l /usr/java lrwxrwxrwx 1 root root 16 Mar 23 16:11 /usr/java -> jdk/jdk1.8.0_121/
Both the jre-8 and jre-7 packages define a symbolic link whose path is /usr/bin/java. In the jre-7 package, the target of the link is jdk1.6.0. In the jre-8 package, the target of the link is jdk1.7.0. The pkg mediator and java -version commands above show that version 1.8 is currently the preferred version, the target of the /usr/bin/java link.
The following output shows all currently available participants in the openssl mediation:
$ pkg mediator -a openssl MEDIATOR VER. SRC. VERSION IMPL. SRC. IMPLEMENTATION openssl vendor vendor default
The following output shows that the fips-140 implementation of openssl will be available after you install the openssl-fips-140 package or the apache-ssl-fips-140 package (the apache-ssl-fips-140 package installs the openssl-fips-140 package):
$ pkg search -o pkg.name,mediator-implementation link:mediator:openssl PKG.NAME MEDIATOR-IMPLEMENTATION web/server/apache-24/module/apache-ssl default web/server/apache-24/module/apache-ssl-fips-140 fips-140 library/security/openssl default library/security/openssl/openssl-fips-140 fips-140
The following output shows only one implementation available in this image for the perl command:
$ pkg mediator -a perl MEDIATOR VER. SRC. VERSION IMPL. SRC. IMPLEMENTATION perl vendor 5.12 vendor
Though only one implementation is available, the path is still a mediated link:
$ which perl /usr/bin/perl $ ls -l /usr/bin/perl lrwxrwxrwx 1 root root 22 Mar 23 16:06 /usr/bin/perl -> ../perl5/5.12/bin/perl
Perhaps you know that a newer version exists, and you enter the following command to update the link to point to the newer version. The following command is incorrect because the specified version is not currently available in this image:
$ pkg set-mediator -vV 5.22 perl Packages to change: 2 Mediators to change: 1 Estimated space available: 867.06 GB Estimated space to be consumed: 241.78 MB Create boot environment: No Create backup boot environment: Yes Rebuild boot archive: No Changed mediators: mediator perl: version: 5.12 (vendor default) -> 5.22 (local default) ...
The pkg mediator command shows the updated setting:
$ pkg mediator perl MEDIATOR VER. SRC. VERSION IMPL. SRC. IMPLEMENTATION perl local 5.22 system
However, the pkg mediator -a command shows that the current setting is not available:
$ pkg mediator -a perl MEDIATOR VER. SRC. VERSION IMPL. SRC. IMPLEMENTATION perl vendor 5.12 vendor
The result of the incorrect version specification is that the mediated link was removed:
$ which perl no perl in /usr/sbin /usr/bin $ ls -l /usr/bin/perl /usr/bin/perl: No such file or directory
You could work around this problem by specifying the full path to the command (/usr/perl5/5.12/bin/perl). The target path was not affected. Only the mediated link was removed.
Any one of the following actions should fix this problem:
Set the preferred version back to the version that is available.
$ pkg set-mediator -V 5.12 perl
Use the pkg unset-mediator command to allow the system to select a new implementation from among the available implementations.
$ pkg unset-mediator perl
Install the packages that deliver the updated version that you want.
The output from the following command shows which packages deliver perl mediated links:
$ pkg search -o pkg.name,mediator-version link:mediator:perl
The runtime/perl-522 and terminal/cssh-522 packages deliver perl mediated links for version 5.22. The terminal/cssh-522 package installs the runtime/perl-522 package. To fix the problem, you only need to install terminal/cssh-522.
$ pkg install terminal/cssh-522
If you cannot fix or work around the issue, reboot to the backup BE that was created when you used the pkg set-mediator command.
Use the pkg set-mediator command to reset the version of a specified mediation that is the default or preferred version.
Use the output from pkg mediator -a to select a version for the -V argument or an implementation for the -I argument. Do not specify a mediation participant that is not shown by pkg mediator -a.
![]() | Caution - If you make a typographical error or otherwise specify a mediator version or implementation that is not currently available, any links that are managed by that mediator are removed as shown in Setting a Preferred Path that is Not Available: Consequences and Recovery. |
Use the -n option with the set-mediator subcommand to see whether a backup BE will be created. If no backup BE will be created, you can specify the --require-backup-be option with the set-mediator subcommand. The mediator change is made in the current BE. When you have determined that your current BE has no problems after the mediator change, you can use beadm destroy to destroy the backup BE.
The following output shows that version 1.8 is the currently selected preferred version of the java mediation, and version 1.7 also is available in this image:
$ pkg mediator java MEDIATOR VER. SRC. VERSION IMPL. SRC. IMPLEMENTATION java system 1.8 system $ pkg mediator -a java MEDIATOR VER. SRC. VERSION IMPL. SRC. IMPLEMENTATION java system 1.8 system java system 1.7 system
The following command shows setting version 1.7 as the preferred version, which means that invoking /usr/bin/java will invoke JRE version 1.7. JRE version 1.8 is still available on the system when users specify the full path to that version. Compare the output of the two pkg mediator commands. When you changed the preferred version for the mediation, the VER. SRC. also changed to local, indicating that the selection was specified by an administrator. This selection will persist across reboots and package updates.
$ pkg set-mediator -v -V 1.7 java Packages to change: 3 Mediators to change: 1 Estimated space available: 867.06 GB Estimated space to be consumed: 238.26 MB Create boot environment: No Create backup boot environment: Yes Rebuild boot archive: No ... $ pkg mediator java MEDIATOR VER. SRC. VERSION IMPL. SRC. IMPLEMENTATION java local 1.7 system
This administrative selection is retained across package updates, even if the selected implementation is no longer installed. If the selected implementation is no longer installed, the target of the mediated link does not exist. Use one of the following methods to reset the preferred implementation:
Use the pkg set-mediator command again to select a different implementation from the updated list shown by pkg mediator -a.
Use the pkg unset-mediator command to allow the system to select a new implementation.