update-alternatives(1)

update-alternatives - maintain symbolic links determining default commands
dpkg suite

update-alternatives [option...] command

Creates, removes, maintains and displays information about symbolic links comprising the alternatives system.

It is possible for several programs fulfilling similar functions to be installed on a system. For example, many systems have several text editors installed at once. This gives choice to the users of a system, allowing each to use a different editor but makes it difficult for a program to make a good choice for an editor to invoke if the user has not specified a preference.

The alternatives system aims to solve this problem. A generic name in the filesystem is shared by all files providing interchangeable functionality. The alternatives system and the administrator determine which actual file is referenced by the generic name. For example, if the text editors ed and nvi are installed on the system, the alternatives system may cause the generic name /usr/bin/editor to refer to /usr/bin/nvi by default. The system administrator can override this and cause it to refer to /usr/bin/ed . The alternatives system will not alter this setting.

The generic name is not a direct symbolic link to the selected alternative. It is a symbolic link to a name in the alternatives directory, which in turn is a symbolic link to the actual file referenced. This is done so that the system administrator's changes can be confined within /etc: the FHS (q.v.) gives reasons why this is a Good Thing.

When each package providing a file with a particular functionality is installed, changed or removed, update-alternatives is called to update information about that file in the alternatives system. Called from the package maintainer scripts, postinst (configure) installs the alternative and from prerm and postrm (remove) to remove the alternative. In most cases no other maintainer script actions should call update-alternatives, neither of upgrade nor disappear, as any other such action can lose the manual state of an alternative, or make the alternative temporarily flip-flop, or completely switch when several of them have the same priority.

A number of alternatives can be synchronized, so that they are changed as a group; for example, when several versions of vi are installed, the man page referenced by /usr/share/man/man1/vi.1 should correspond to the executable referenced by /usr/bin/vi. This is handled by means of master and slave links.
When the master is changed, associated slaves are changed .

A master link and its associated slaves make up a link group.

For links in automatic mode, the system decides if and how to update the links.
for links in manual mode, the choice of the administrator is retained and avoids changing the links (except when something is broken).

Link groups are in automatic mode when introduced to the system. If the system administrator makes changes to the system's automatic settings, this will be noticed the next time update-alternatives is run on the changed link's group, and the group will be switched to manual mode.

Each alternative has a priority . When a link group is in automatic mode, the alternatives pointed to by members of the group will be those which have the highest priority.

With --config all of the choices for the link group of which given name is the master alternative name is listed. The current choice is marked with a '*'. You will be prompted for choice regarding this link group. Depending on the choice made, the link group might no longer be in auto mode. --auto to return to the automatic mode (or rerun --config and select the entry marked as automatic).

To configure non-interactively use --set

Different packages providing the same file need to do so cooperatively. The usage of update-alternatives is mandatory for all involved packages in such case. It is not possible to override some file in a package that does not employ the update-alternatives mechanism.

TERMINOLOGY

The activities of update-alternatives are quite involved, specific terms help to explain its operation. 

       generic name (or alternative link)
           A name, like /usr/bin/editor, which refers, to one of a number of files of similar function.

       alternative name
           The name of a symbolic link in the alternatives directory.

       alternative (or alternative path)
           The name of a file in the filesystem, which may be made accessible via a generic name using the alternatives system.

       alternatives directory
           default /etc/alternatives, containing the symlinks.

       administrative directory
           default /var/lib/dpkg/alternatives containing update-alternatives' state information.

       link group
           A set of related symlinks, intended to be updated as a group.

       master link
           The alternative link in a link group which determines how the other links in the group are configured.

       slave link
           An alternative link in a link group which is controlled by the setting of the master link.

       automatic mode
           When a link group is in automatic mode, the links in the group point to the highest
           priority alternative appropriate for the group.

       manual mode
           in manual mode, no changes to the system administrator's settings.
--install
link name path priority
[--slave link name path[]…		 Add a group of alternatives.
link : generic name for the master link
name : name of its symlink in the alternatives directory, and
path : alternative being introduced for the master link.
The arguments after --slave are the generic name, symlink name in the alternatives directory and the alternative path for a slave link.
Zero or more --slave options, each followed by three arguments, may be specified.
The master alternative must exist.
If a slave alternative doesn't exist, the corresponding slave alternative link will not be installed (a warning will still be displayed).
If some real file is installed where an alternative link has to be installed, it is kept unless --force is used.
Where the alternative name exists in the alternatives system's records, the information supplied will be added as a new set of alternatives for the group.
Where the alternative name does not exists, a new group, set to automatic mode, will be added.

If the group is in automatic mode, and the newly added alternatives' priority is higher than any other installed alternatives for this group, the symlinks will be updated to point to the newly added alternatives.

--set name path Equivalent to --config but is non-interactive.
--remove adname afile Remove an alternative and all of its associated slave links.
adname is a name in the alternatives directory,
afile is an absolute filename to which name could be linked.
If adname is linked to afile , adname will be updated to point to another appropriate alternative (and the group is put back in automatic mode), or removed if there is no such alternative left. Associated slave links will be updated or removed.
If the link is not currently pointing to afile, no links are changed; the information about the alternative is removed.
--remove-all name alternatives and all of associated slave links. name,/code> is a name in the alternatives directory.
--all Call --config on all alternatives. Usefully with --skip-auto to review and configure all alternatives which are not configured in automatic mode.
Broken alternatives are also displayed.
To fix all broken alternatives yes '' | update-alternatives --force --all. ??
--auto name Switch the link group behind the alternative for to automatic mode.
The master symlink and its slaves are updated to point to the highest priority installed alternatives.
--display name about the link group including the group's
mode (auto or manual),
the master and slave links,
which alternative the master link currently points to,
what other alternatives are available (and their slave alternatives), and
the highest priority alternative currently installed.
--get-selections List all master alternative names (those controlling a link group) and their status .
Each line contains up to 3 fields (separated by spaces).
  1. alternative name,
  2. status (either auto or manual),
  3. the current choice in the alternative (a filename and might contain spaces).
--set-selections Read configuration of alternatives on standard input in the format generated by --get-selections and
reconfigure them
--query name Output information, in a machine parseable way, about the link group like --display ,
--list name Display all targets of the link group.
--config name Show available alternatives for a link group and allow
the user to interactively select which one to use. The link group is updated.
--help Show the usage message and exit.
--version Show the version and exit.

A

OPTIONS
--altdir directory Default .
--admindir directory Default /var/lib/dpkg/alternatives
--instdir directory Where alternatives links will be created
--root directory also sets the alternatives, installation and administrative directories to match. Defaults to
--log file Default /var/log/alternatives.log.
--force Allow replacing or dropping any real file that is installed where an alternative link has to be installed or removed.
--skip-auto With --config or --all, Skip configuration prompt for alternatives which are properly configured in automatic mode.
--quiet Only errors
--verbose Generate more comments
--debug Generate even more comments

EXIT STATUS

0> The requested action was successfully performed.

2 Problems were encountered whilst parsing the command line or performing the action.

ENVIRONMENT DPKG_ADMINDIR If set and the --admindir option has not been specified, it will be used as the base administrative directory.

FILES

The default alternatives directory. Can be overridden by the --altdir option. /etc/alternatives/ The default administration directory. Can be overridden by the --admindir option. /var/lib/dpkg/alternatives/

QUERY FORMAT

       The --query format is using an RFC822-like flat format. It's made of n + 1 blocks where n is the number of alternatives available
       in the queried link group. The first block contains the following fields:

       Name: name
           The alternative name in the alternative directory.

       Link: link
           The generic name of the alternative.

       Slaves: list-of-slaves
           When this field is present, the next lines hold all slave links associated to the master link of the alternative. There is
           one slave per line. Each line contains one space, the generic name of the slave alternative, another space, and the path to
           the slave link.

       Status: status
           The status of the alternative (auto or manual).

       Best: best-choice
           The path of the best alternative for this link group. Not present if there is no alternatives available.

       Value: currently-selected-alternative
           The path of the currently selected alternative. It can also take the magic value none. It is used if the link doesn't exist.

       The other blocks describe the available alternatives in the queried link group:

       Alternative: path-of-this-alternative
           Path to this block's alternative.

       Priority: priority-value
           Value of the priority of this alternative.

       Slaves: list-of-slaves
           When this field is present, the next lines hold all slave alternatives associated to the master link of the alternative.
           There is one slave per line. Each line contains one space, the generic name of the slave alternative, another space, and the
           path to the slave alternative.

   Example
        $ update-alternatives --query editor
        Name: editor
        Link: /usr/bin/editor
        Slaves:
         editor.1.gz /usr/share/man/man1/editor.1.gz
         editor.fr.1.gz /usr/share/man/fr/man1/editor.1.gz
         editor.it.1.gz /usr/share/man/it/man1/editor.1.gz
         editor.pl.1.gz /usr/share/man/pl/man1/editor.1.gz
         editor.ru.1.gz /usr/share/man/ru/man1/editor.1.gz
        Status: auto
        Best: /usr/bin/vim.basic
        Value: /usr/bin/vim.basic

        Alternative: /bin/ed
        Priority: -100
        Slaves:
         editor.1.gz /usr/share/man/man1/ed.1.gz

        Alternative: /usr/bin/vim.basic
        Priority: 50
        Slaves:
         editor.1.gz /usr/share/man/man1/vim.1.gz
         editor.fr.1.gz /usr/share/man/fr/man1/vim.1.gz
         editor.it.1.gz /usr/share/man/it/man1/vim.1.gz
         editor.pl.1.gz /usr/share/man/pl/man1/vim.1.gz
         editor.ru.1.gz /usr/share/man/ru/man1/vim.1.gz

DIAGNOSTICS

With --verbose update-alternatives chatters incessantly about its activities on its standard output channel. If problems occur, update-alternatives outputs error messages on its standard error channel and returns an exit status of 2. These diagnostics should be self-explanatory; if you do not find them so, please report this as a bug.

EXAMPLES

There are several packages which provide a text editor compatible with vi, for example nvi and vim. Which one is used is controlled by the link group vi, which includes links for the program itself and the associated manpage.

display the available packages which provide vi and the current setting for it, use the --display action: update-alternatives --display vi

To choose a particular vi implementation, use this command as root and then select a number from the list: update-alternatives --config vi

To go back to having the vi implementation chosen automatically, do this as root: update-alternatives --auto vi

SEE ALSO

ln(1), FHS (the Filesystem Hierarchy Standard). 1.20.12 2022-09-13