update_alternatives

Debian, Ubuntu, and the Red Hat family let several installed programs provide one generic command, such as editor or java. The alternatives system chooses which one the command runs. update_alternatives sets that choice, through the node's update-alternatives command; on the Red Hat family it is the same program as alternatives.

Inputs

  • name (string; required): the generic name, such as editor
  • program_path (string; optional): required unless automatic: true; the program the generic name runs, set in manual mode so a package upgrade does not switch it back; it must be one of the name's registered choices, or generic_command_path and priority_when_registered register it
  • automatic (boolean; default false): true takes no program_path and returns the name to automatic mode, in which the registered choice with the highest priority wins
  • generic_command_path (string; optional): with priority_when_registered: the generic command's path, such as /usr/bin/java; MMX then registers program_path as a choice for name when it is not one (update-alternatives --install)
  • priority_when_registered (integer; optional): with generic_command_path: a whole number; in automatic mode the highest wins

Outputs

The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.

  • status
  • change
  • value.program_path_before
  • value.program_path_after
  • value.automatic_before
  • value.automatic_after

What a dryrun reports

Supported; reads the name's mode, program, and choices and reports what would be set; a path that is not a registered choice is not checked, because an earlier package task may register it.

Retries and time limits

Bounded automatic retries by default; retry: false turns them off.

The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.

Examples

Choose the editor

- update_alternatives:
    name: editor
    program_path: /usr/bin/vim.basic

After this node task, the command editor runs /usr/bin/vim.basic on the node. MMX reads the name's current choice and mode, and sets program_path in manual mode (update-alternatives --set), so a later package upgrade does not switch it back. The node task reports the old and the new choice.

Register a program that no package registers

A JDK unpacked under /opt is not a registered choice of java. generic_command_path and priority_when_registered register it first:

- update_alternatives:
    name: java
    program_path: /opt/jdk-21/bin/java
    generic_command_path: /usr/bin/java
    priority_when_registered: 2100

generic_command_path is the path of the generic command that runs the selected program, such as /usr/bin/java. priority_when_registered is a whole number assigned to the program during registration. In automatic mode, the alternatives system selects the registered program with the highest numeric priority.

With generic_command_path and priority_when_registered, MMX first registers program_path as a choice for name when the program is not registered (update-alternatives --install). Then MMX selects program_path for the generic command specified by name.

Return to automatic mode

- update_alternatives:
    name: editor
    automatic: true

When automatic: true, omit program_path. MMX returns the generic command specified by name to automatic mode, which selects the registered program with the highest priority. The automatic setting defaults to false.

How it works

  • program_path must be one of the name's registered choices; each package that provides the command registers its program as a choice. program_path is required unless automatic: true.
  • Results and dryrun show program_path_before and program_path_after, the program the name runs before and after, and automatic_before and automatic_after, true in automatic mode and false in manual mode, in .this_node_task.value. Unchanged runs show no value. A run where update-alternatives --set or --auto fails shows no value, so a node task in on_failure can read what happened.

Errors and what they mean

The reason holds What the error means, and what to do
... is not a registered choice for editor; the registered choices are: ... A program_path that is not a registered choice, without generic_command_path, fails the node task and lists the registered choices. Install the package that registers it in an earlier node task, or give generic_command_path and priority_when_registered. A dryrun reports the node task not checked, because an earlier apt_package or dnf_package task may install the package that registers it.
the alternatives system has no choices for ... yet; ... The name has no choices at all, here with automatic: true. The packages that provide the command register them. It is treated as above: not checked in a dryrun.
update_alternatives supports nodes with apt or dnf; the node's package manager is ... The node is not one of the distributions above. A symlink node task can make a generic command run a program there. The node task fails in a dryrun too.

Tested on

Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10.

The suite tests/integration/node_settings.py runs on Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, and AlmaLinux 10, in containers on the first four and in virtual machines on the last two. The validation record has the latest results.

Why it works this way

  • A module named for its tool. 20 independent authors set the alternatives system in the Ansible projects MMX was checked against, with a shell recipe.
  • priority_when_registered names when MMX uses the priority. MMX uses priority_when_registered only when registering the program, following the creation-name rule.
  • Manual mode for a chosen program_path. In automatic mode, a later package upgrade can switch the command to another program.

This page is docs/reference/modules/update_alternatives.md in the MMX repository.