man/update-alternatives.pod

   1 # dpkg manual page - update-alternatives(1)
   2 #
   3 # Copyright © 1997-1998 Charles Briscoe-Smith
   4 # Copyright © 1999 Ben Collins <bcollins@debian.org>
   5 # Copyright © 2000 Wichert Akkerman <wakkerma@debian.org>
   6 # Copyright © 2003 Adam Heath <doogie@debian.org>
   7 # Copyright © 2005 Scott James Remnant <scott@netsplit.com>
   8 # Copyright © 2006-2015 Guillem Jover <guillem@debian.org>
   9 # Copyright © 2008 Pierre Habouzit <madcoder@debian.org>
  10 # Copyright © 2009-2011 Raphaël Hertzog <hertzog@debian.org>
  11 #
  12 # This is free software; you can redistribute it and/or modify
  13 # it under the terms of the GNU General Public License as published by
  14 # the Free Software Foundation; either version 2 of the License, or
  15 # (at your option) any later version.
  16 #
  17 # This is distributed in the hope that it will be useful,
  18 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 # GNU General Public License for more details.
  21 #
  22 # You should have received a copy of the GNU General Public License
  23 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  24
  25 =encoding utf8
  26
  27 =head1 NAME
  28
  29 update-alternatives - maintain symbolic links determining default commands
  30
  31 =head1 SYNOPSIS
  32
  33 B<update-alternatives>
  34 [I<option>...] I<command>
  35
  36 =head1 DESCRIPTION
  37
  38 B<update-alternatives>
  39 creates, removes, maintains and displays information about the symbolic
  40 links comprising the alternatives system.
  41
  42 It is possible for several programs fulfilling the same or similar
  43 functions to be installed on a single system at the same time.
  44 For example, many systems have several text editors installed at once.
  45 This gives choice to the users of a system, allowing each to use a
  46 different editor, if desired, but makes it difficult for a program
  47 to make a good choice for an editor to invoke if the
  48 user has not specified a particular preference.
  49
  50 The alternatives system aims to solve this problem.
  51 A generic name in the filesystem is
  52 shared by all files providing interchangeable functionality.
  53 The alternatives system and the system administrator
  54 together determine which actual file is referenced by this generic name.
  55 For example, if the text editors
  56 L<ed(1)>
  57 and
  58 L<nvi(1)>
  59 are both installed on the system, the alternatives system will cause
  60 the generic name
  61 I</usr/bin/editor>
  62 to refer to
  63 I</usr/bin/nvi>
  64 by default.
  65 The system administrator can override this and cause
  66 it
  67 to refer to
  68 I</usr/bin/ed>
  69 instead,
  70 and the alternatives system will not alter this setting until explicitly
  71 requested to do so.
  72
  73 The generic name is not a direct symbolic link to the selected alternative.
  74 Instead, it is a symbolic link to a name in the
  75 I<alternatives>
  76 I<directory>,
  77 which in turn is a symbolic link to the actual file referenced.
  78 This is done so that the system administrator's changes can be confined
  79 within the
  80 I<%CONFDIR%>
  81 directory: the FHS (q.v.) gives reasons why this is a Good Thing.
  82
  83 When each package
  84 providing a file with a particular functionality is
  85 installed, changed or removed,
  86 B<update-alternatives>
  87 is called to update information about that file in the alternatives system.
  88 B<update-alternatives>
  89 is usually called from the following Debian package maintainer scripts,
  90 B<postinst>
  91 (configure) to install the alternative and from
  92 B<prerm> and B<postrm>
  93 (remove) to remove the alternative.
  94 B<Note>: In most (if not all) cases no other maintainer script actions should
  95 call B<update-alternatives>, in particular neither of B<upgrade> nor
  96 B<disappear>, as any other such action can lose the manual state of an
  97 alternative, or make the alternative temporarily flip-flop, or completely
  98 switch when several of them have the same priority.
  99
 100 It is often useful for a number of alternatives to be synchronized,
 101 so that they are changed as a group; for example, when several versions
 102 of the
 103 L<vi(1)>
 104 editor are installed, the manual page referenced by
 105 I</usr/share/man/man1/vi.1>
 106 should correspond to the executable referenced by
 107 I</usr/bin/vi>.
 108 B<update-alternatives>
 109 handles this by means of
 110 I<master>
 111 and
 112 I<slave>
 113 links; when the master is changed, any associated slaves are changed
 114 too.
 115 A master link and its associated slaves make up a
 116 I<link>
 117 I<group>.
 118
 119 Each link group is, at any given time,
 120 in one of two modes: automatic or manual.
 121 When a group is in automatic mode, the alternatives system will
 122 automatically decide, as packages are installed and removed,
 123 whether and how to update the links.
 124 In manual mode, the alternatives system will retain the choice of
 125 the administrator and avoid changing the links (except when something is
 126 broken).
 127
 128 Link groups are in automatic mode when they are first introduced to
 129 the system.
 130 If the system administrator makes changes to the system's
 131 automatic settings,
 132 this will be noticed the next time
 133 B<update-alternatives>
 134 is run on the changed link's group,
 135 and the group will automatically be switched to manual mode.
 136
 137 Each alternative has a
 138 I<priority>
 139 associated with it.
 140 When a link group is in automatic mode,
 141 the alternatives pointed to by members of the group
 142 will be those which have the highest priority.
 143
 144 When using the
 145 B<--config>
 146 option,
 147 B<update-alternatives>
 148 will list all of the choices for the link group
 149 of which given
 150 I<name>
 151 is the master alternative name.
 152 The current choice is marked with a ‘*’.
 153 You will then be prompted for your choice regarding this link group.
 154 Depending on the choice made, the link group might no longer be in
 155 I<auto>
 156 mode.
 157 You will need to use the
 158 B<--auto>
 159 option in order to return to the automatic mode (or you can rerun
 160 B<--config>
 161 and select the entry marked as automatic).
 162
 163 If you want to configure non-interactively you can use the
 164 B<--set>
 165 option instead (see below).
 166
 167 Different packages providing the same file need to do so
 168 B<cooperatively>.
 169 In other words, the usage of
 170 B<update-alternatives>
 171 is
 172 B<mandatory>
 173 for all involved packages in such case.
 174 It is not possible to
 175 override some file in a package that does not employ the
 176 B<update-alternatives>
 177 mechanism.
 178
 179 =head1 TERMINOLOGY
 180
 181 Since the activities of
 182 B<update-alternatives>
 183 are quite involved, some specific terms will help to explain its
 184 operation.
 185
 186 =over
 187
 188 =item generic name (or alternative link)
 189
 190 A name, like
 191 I</usr/bin/editor>,
 192 which refers, via the alternatives system, to one of a number of
 193 files of similar function.
 194
 195 =item alternative name
 196
 197 The name of a symbolic link in the alternatives directory.
 198
 199 =item alternative (or alternative path)
 200
 201 The name of a specific file in the filesystem, which may be made
 202 accessible via a generic name using the alternatives system.
 203
 204 =item alternatives directory
 205
 206 A directory, by default
 207 I<%CONFDIR%/alternatives>,
 208 containing the symlinks.
 209
 210 =item administrative directory
 211
 212 A directory, by default
 213 I<%ADMINDIR%/alternatives>,
 214 containing
 215 B<update-alternatives>'
 216 state information.
 217
 218 =item link group
 219
 220 A set of related symlinks, intended to be updated as a group.
 221
 222 =item master link
 223
 224 The alternative link in a link group which determines how the other links in the
 225 group are configured.
 226
 227 =item slave link
 228
 229 An alternative link in a link group which is controlled by the setting of
 230 the master link.
 231
 232 =item automatic mode
 233
 234 When a link group is in automatic mode,
 235 the alternatives system ensures that the links in the group
 236 point to the highest priority alternative
 237 appropriate for the group.
 238
 239 =item manual mode
 240
 241 When a link group is in manual mode,
 242 the alternatives system will not make any changes
 243 to the system administrator's settings.
 244
 245 =back
 246
 247 =head1 COMMANDS
 248
 249 =over
 250
 251 =item B<--install> I<link name path priority> [B<--slave> I<link name path>]...
 252
 253 Add a group of alternatives to the system.
 254 I<link>
 255 is the generic name for the master link,
 256 I<name>
 257 is the name of its symlink in the alternatives directory, and
 258 I<path>
 259 is the alternative being introduced for the master link.
 260 The arguments after B<--slave> are the generic name, symlink name in the
 261 alternatives directory and the alternative path for a slave link.
 262 Zero or more
 263 B<--slave>
 264 options, each followed by three arguments,
 265 may be specified.
 266 Note that the master alternative must exist or the call will fail.
 267 However if a slave alternative doesn't exist, the corresponding
 268 slave alternative link will simply not be installed (a warning will still
 269 be displayed).
 270 If some real file is installed where an alternative link
 271 has to be installed, it is kept unless B<--force> is used.
 272
 273 If the alternative name specified exists already
 274 in the alternatives system's records,
 275 the information supplied will be added as a new
 276 set of alternatives for the group.
 277 Otherwise, a new group, set to automatic mode,
 278 will be added with this information.
 279 If the group is in automatic mode,
 280 and the newly added alternatives' priority is higher than
 281 any other installed alternatives for this group,
 282 the symlinks will be updated to point to the newly added alternatives.
 283
 284 =item B<--set> I<name> I<path>
 285
 286 Set the program
 287 I<path>
 288 as alternative for
 289 I<name>.
 290 This is equivalent to
 291 B<--config>
 292 but is non-interactive and thus scriptable.
 293
 294 =item B<--remove> I<name> I<path>
 295
 296 Remove an alternative and all of its associated slave links.
 297 I<name>
 298 is a name in the alternatives directory, and
 299 I<path>
 300 is an absolute filename to which
 301 I<name>
 302 could be linked.
 303 If
 304 I<name>
 305 is indeed linked to
 306 I<path>,
 307 I<name>
 308 will be updated to point to another appropriate alternative
 309 (and the group is put back in automatic mode), or
 310 removed if there is no such alternative left.
 311 Associated slave links will be updated or removed, correspondingly.
 312 If the link is not currently pointing to
 313 I<path>,
 314 no links are changed;
 315 only the information about the alternative is removed.
 316
 317 =item B<--remove-all> I<name>
 318
 319 Remove all alternatives and all of their associated slave links.
 320 I<name>
 321 is a name in the alternatives directory.
 322
 323 =item B<--all>
 324
 325 Call B<--config> on all alternatives.
 326 It can be usefully combined with
 327 B<--skip-auto> to review and configure all alternatives which are
 328 not configured in automatic mode.
 329 Broken alternatives are also displayed.
 330 Thus a simple way to fix all broken alternatives is to call
 331 B<yes '' | update-alternatives --force --all>.
 332
 333 =item B<--auto> I<name>
 334
 335 Switch the link group behind the alternative for
 336 I<name>
 337 to automatic mode.
 338 In the process, the master symlink and its slaves are updated
 339 to point to the highest priority installed alternatives.
 340
 341 =item B<--display> I<name>
 342
 343 Display information about the link group.
 344 Information displayed includes the group's mode
 345 (auto or manual),
 346 the master and slave links,
 347 which alternative the master link currently points to,
 348 what other alternatives are available
 349 (and their corresponding slave alternatives),
 350 and the highest priority alternative currently installed.
 351
 352 =item B<--get-selections>
 353
 354 List all master alternative names (those controlling a link group)
 355 and their status (since version 1.15.0).
 356 Each line contains up to 3 fields (separated by
 357 one or more spaces).
 358 The first field is the alternative name, the second
 359 one is the status (either B<auto> or B<manual>), and the last one contains
 360 the current choice in the alternative (beware: it's a filename and thus
 361 might contain spaces).
 362
 363 =item B<--set-selections>
 364
 365 Read configuration of alternatives on standard input in the format
 366 generated by B<--get-selections> and reconfigure
 367 them accordingly (since version 1.15.0).
 368
 369 =item B<--query> I<name>
 370
 371 Display information about the link group
 372 like B<--display> does, but in a machine parseable way
 373 (since version 1.15.0, see section L</QUERY FORMAT> below).
 374
 375 =item B<--list> I<name>
 376
 377 Display all targets of the link group.
 378
 379 =item B<--config> I<name>
 380
 381 Show available alternatives for a link group and allow the user to
 382 interactively select which one to use.
 383 The link group is updated.
 384
 385 =item B<--help>
 386
 387 Show the usage message and exit.
 388
 389 =item B<--version>
 390
 391 Show the version and exit.
 392
 393 =back
 394
 395 =head1 OPTIONS
 396
 397 =over
 398
 399 =item B<--altdir> I<directory>
 400
 401 Specifies the alternatives directory, when this is to be
 402 different from the default.
 403 Defaults to «I<%CONFDIR%/alternatives>».
 404
 405 =item B<--admindir> I<directory>
 406
 407 Specifies the administrative directory, when this is to be
 408 different from the default.
 409 Defaults to «I<%ADMINDIR%/alternatives>» if B<%ADMINDIR_ENVVAR%> has not
 410 been set.
 411
 412 =item B<--instdir> I<directory>
 413
 414 Specifies the installation directory where alternatives links will be created
 415 (since version 1.20.1).
 416 Defaults to «I</>» if B<%INSTDIR_ENVVAR%> has not been set.
 417
 418 =item B<--root> I<directory>
 419
 420 Specifies the root directory (since version 1.20.1).
 421 This also sets the alternatives, installation and administrative
 422 directories to match.
 423 Defaults to «I</>» if B<%INSTDIR_ENVVAR%> has not been set.
 424
 425 =item B<--log> I<file>
 426
 427 Specifies the log file (since version 1.15.0), when this is to be different
 428 from the default (%LOGDIR%/alternatives.log).
 429
 430 =item B<--force>
 431
 432 Allow replacing or dropping any real file that is installed
 433 where an alternative link has to be installed or removed.
 434
 435 =item B<--skip-auto>
 436
 437 Skip configuration prompt for alternatives which are properly configured
 438 in automatic mode.
 439 This option is only relevant with B<--config> or
 440 B<--all>.
 441
 442 =item B<--quiet>
 443
 444 Do not generate any comments unless errors occur.
 445
 446 =item B<--verbose>
 447
 448 Generate more comments about what is being done.
 449
 450 =item B<--debug>
 451
 452 Generate even more comments, helpful for debugging, about what is being done
 453 (since version 1.19.3).
 454
 455 =back
 456
 457 =head1 EXIT STATUS
 458
 459 =over
 460
 461 =item B<0>
 462
 463 The requested action was successfully performed.
 464
 465 =item B<2>
 466
 467 Problems were encountered whilst parsing the command line
 468 or performing the action.
 469
 470 =back
 471
 472 =head1 ENVIRONMENT
 473
 474 =over
 475
 476 =item B<%INSTDIR_ENVVAR%>
 477
 478 If set and the B<--instdir> or B<--root> options have not been
 479 specified, it will be used as the filesystem root directory.
 480
 481 =item B<%ADMINDIR_ENVVAR%>
 482
 483 If set and the B<--admindir> option has not been specified, it will
 484 be used as the base administrative directory.
 485
 486 =back
 487
 488 =head1 FILES
 489
 490 =over
 491
 492 =item I<%CONFDIR%/alternatives/>
 493
 494 The default alternatives directory.
 495 Can be overridden by the
 496 B<--altdir>
 497 option.
 498
 499 =item I<%ADMINDIR%/alternatives/>
 500
 501 The default administration directory.
 502 Can be overridden by the
 503 B<--admindir>
 504 option.
 505
 506 =back
 507
 508 =head1 QUERY FORMAT
 509
 510 The B<--query> format is using an
 511 RFC822-like flat format.
 512 It's made of I<n> + 1 stanzas where I<n> is the number of alternatives
 513 available in the queried link group.
 514 The first
 515 stanza contains the following fields:
 516
 517 =over
 518
 519 =item B<Name:> I<name>
 520
 521 The alternative name in the alternative directory.
 522
 523 =item B<Link:> I<link>
 524
 525 The generic name of the alternative.
 526
 527 =item B<Slaves:> I<list-of-slaves>
 528
 529 When this field is present, the B<next> lines hold all slave links
 530 associated to the master link of the alternative.
 531 There is one slave per line.
 532 Each line contains one space, the generic name of the slave
 533 alternative, another space, and the path to the slave link.
 534
 535 =item B<Status:> I<status>
 536
 537 The status of the alternative (B<auto> or B<manual>).
 538
 539 =item B<Best:> I<best-choice>
 540
 541 The path of the best alternative for this link group.
 542 Not present if
 543 there is no alternatives available.
 544
 545 =item B<Value:> I<currently-selected-alternative>
 546
 547 The path of the currently selected alternative.
 548 It can also take the magic value B<none>.
 549 It is used if the link doesn't exist.
 550
 551 =back
 552
 553 The other stanzas describe the available alternatives in the queried
 554 link group:
 555
 556 =over
 557
 558 =item B<Alternative:> I<path-of-this-alternative>
 559
 560 Path to this stanza's alternative.
 561
 562 =item B<Priority:> I<priority-value>
 563
 564 Value of the priority of this alternative.
 565
 566 =item B<Slaves:> I<list-of-slaves>
 567
 568 When this field is present, the B<next> lines hold all slave alternatives
 569 associated to the master link of the alternative.
 570 There is one slave per line.
 571 Each line contains one space, the generic name of the slave
 572 alternative, another space, and the path to the slave alternative.
 573
 574 =back
 575
 576 =head2 Example
 577
 578  $ update-alternatives --query editor
 579  Name: editor
 580  Link: /usr/bin/editor
 581  Slaves:
 582   editor.1.gz /usr/share/man/man1/editor.1.gz
 583   editor.fr.1.gz /usr/share/man/fr/man1/editor.1.gz
 584   editor.it.1.gz /usr/share/man/it/man1/editor.1.gz
 585   editor.pl.1.gz /usr/share/man/pl/man1/editor.1.gz
 586   editor.ru.1.gz /usr/share/man/ru/man1/editor.1.gz
 587  Status: auto
 588  Best: /usr/bin/vim.basic
 589  Value: /usr/bin/vim.basic
 590
 591  Alternative: /bin/ed
 592  Priority: -100
 593  Slaves:
 594   editor.1.gz /usr/share/man/man1/ed.1.gz
 595
 596  Alternative: /usr/bin/vim.basic
 597  Priority: 50
 598  Slaves:
 599   editor.1.gz /usr/share/man/man1/vim.1.gz
 600   editor.fr.1.gz /usr/share/man/fr/man1/vim.1.gz
 601   editor.it.1.gz /usr/share/man/it/man1/vim.1.gz
 602   editor.pl.1.gz /usr/share/man/pl/man1/vim.1.gz
 603   editor.ru.1.gz /usr/share/man/ru/man1/vim.1.gz
 604
 605 =head1 DIAGNOSTICS
 606
 607 With B<--verbose>
 608 B<update-alternatives>
 609 chatters incessantly about its activities on its standard output channel.
 610 If problems occur,
 611 B<update-alternatives>
 612 outputs error messages on its standard error channel and
 613 returns an exit status of 2.
 614 These diagnostics should be self-explanatory;
 615 if you do not find them so, please report this as a bug.
 616
 617 =head1 EXAMPLES
 618
 619 There are several packages which provide a text editor compatible
 620 with B<vi>, for example B<nvi> and B<vim>.
 621 Which one is used
 622 is controlled by the link group B<vi>, which includes links for the
 623 program itself and the associated manual page.
 624
 625 To display the available packages which provide B<vi> and the current
 626 setting for it, use the B<--display> action:
 627
 628 =over
 629
 630  update-alternatives --display vi
 631
 632 =back
 633
 634 To choose a particular B<vi> implementation, use this command as root
 635 and then select a number from the list:
 636
 637 =over
 638
 639  update-alternatives --config vi
 640
 641 =back
 642
 643 To go back to having the B<vi> implementation chosen automatically, do
 644 this as root:
 645
 646 =over
 647
 648  update-alternatives --auto vi
 649
 650 =back
 651
 652 =head1 SEE ALSO
 653
 654 L<ln(1)>,
 655 FHS (the Filesystem Hierarchy Standard).