Specifying a Default Application Implementation

Language:

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.

Identifying Participants in a Mediation

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.

Identifying Mediation Participants That Are Not Currently Available

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

Setting a Preferred Path that is Not Available: Consequences and Recovery

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.

Changing the Preferred Application

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.