usr.sbin/etcupdate/etcupdate.8

   1 .\" Copyright (c) 2010-2013 Hudson River Trading LLC
   2 .\" Written by: John H. Baldwin <jhb@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd April 20, 2021
  29 .Dt ETCUPDATE 8
  30 .Os
  31 .Sh NAME
  32 .Nm etcupdate
  33 .Nd "manage updates to system files not updated by installworld"
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Op Fl npBF
  37 .Op Fl d Ar workdir
  38 .Op Fl r | Fl s Ar source | Fl t Ar tarball
  39 .Op Fl A Ar patterns
  40 .Op Fl D Ar destdir
  41 .Op Fl I Ar patterns
  42 .Op Fl L Ar logfile
  43 .Op Fl M Ar options
  44 .Nm
  45 .Cm build
  46 .Op Fl B
  47 .Op Fl d Ar workdir
  48 .Op Fl s Ar source
  49 .Op Fl L Ar logfile
  50 .Op Fl M Ar options
  51 .Ar tarball
  52 .Nm
  53 .Cm diff
  54 .Op Fl d Ar workdir
  55 .Op Fl D Ar destdir
  56 .Op Fl I Ar patterns
  57 .Op Fl L Ar logfile
  58 .Nm
  59 .Cm extract
  60 .Op Fl B
  61 .Op Fl d Ar workdir
  62 .Op Fl s Ar source | Fl t Ar tarball
  63 .Op Fl D Ar destdir
  64 .Op Fl L Ar logfile
  65 .Op Fl M Ar options
  66 .Nm
  67 .Cm resolve
  68 .Op Fl p
  69 .Op Fl d Ar workdir
  70 .Op Fl D Ar destdir
  71 .Op Fl L Ar logfile
  72 .Nm
  73 .Cm revert
  74 .Op Fl d Ar workdir
  75 .Op Fl D Ar destdir
  76 .Op Fl L Ar logfile
  77 .Ar
  78 .Nm
  79 .Cm status
  80 .Op Fl d Ar workdir
  81 .Op Fl D Ar destdir
  82 .Sh DESCRIPTION
  83 The
  84 .Nm
  85 utility is a tool for managing updates to files that are not updated as
  86 part of
  87 .Sq make installworld
  88 such as files in
  89 .Pa /etc .
  90 It manages updates by doing a three-way merge of changes made to these
  91 files against the local versions.
  92 It is also designed to minimize the amount of user intervention with
  93 the goal of simplifying upgrades for clusters of machines.
  94 .Pp
  95 To perform a three-way merge,
  96 .Nm
  97 keeps copies of the current and previous versions of files that it manages.
  98 These copies are stored in two trees known as the
  99 .Dq current
 100 and
 101 .Dq previous
 102 trees.
 103 During a merge,
 104 .Nm
 105 compares the
 106 .Dq current
 107 and
 108 .Dq previous
 109 copies of each file to determine which changes need to be merged into the
 110 local version of each file.
 111 If a file can be updated without generating a conflict,
 112 .Nm
 113 will update the file automatically.
 114 If the local changes to a file conflict with the changes made to a file in
 115 the source tree,
 116 then a merge conflict is generated.
 117 The conflict must be resolved after the merge has finished.
 118 The
 119 .Nm
 120 utility will not perform a new merge until all conflicts from an earlier
 121 merge are resolved.
 122 .Sh MODES
 123 The
 124 .Nm
 125 utility supports several modes of operation.
 126 The mode is specified via an optional command argument.
 127 If present, the command must be the first argument on the command line.
 128 If a command is not specified, the default mode is used.
 129 .Ss Default Mode
 130 The default mode merges changes from the source tree to the destination
 131 directory.
 132 First,
 133 it updates the
 134 .Dq current
 135 and
 136 .Dq previous
 137 trees.
 138 Next,
 139 it compares the two trees merging changes into the destination directory.
 140 Finally,
 141 it displays warnings for any conditions it could not handle automatically.
 142 .Pp
 143 If the
 144 .Fl r
 145 option is not specified,
 146 then the first step taken is to update the
 147 .Dq current
 148 and
 149 .Dq previous
 150 trees.
 151 If a
 152 .Dq current
 153 tree already exists,
 154 then that tree is saved as the
 155 .Dq previous
 156 tree.
 157 An older
 158 .Dq previous
 159 tree is removed if it exists.
 160 By default the new
 161 .Dq current
 162 tree is built from a source tree.
 163 However,
 164 if a tarball is specified via the
 165 .Fl t
 166 option,
 167 then the tree is extracted from that tarball instead.
 168 .Pp
 169 Next,
 170 .Nm
 171 compares the files in the
 172 .Dq current
 173 and
 174 .Dq previous
 175 trees.
 176 If a file was removed from the
 177 .Dq current
 178 tree,
 179 then it will be removed from the destination directory only if it
 180 does not have any local modifications.
 181 If a file was added to the
 182 .Dq current
 183 tree,
 184 then it will be copied to the destination directory only if it
 185 would not clobber an existing file.
 186 If a file is changed in the
 187 .Dq current
 188 tree,
 189 then
 190 .Nm
 191 will attempt to merge the changes into the version of the file in the
 192 destination directory.
 193 If the merge encounters conflicts,
 194 then a version of the file with conflict markers will be saved for
 195 future resolution.
 196 If the merge does not encounter conflicts,
 197 then the merged version of the file will be saved in the destination
 198 directory.
 199 If
 200 .Nm
 201 is not able to safely merge in changes to a file other than a merge conflict,
 202 it will generate a warning.
 203 .Pp
 204 For each file that is updated a line will be output with a leading character
 205 to indicate the action taken.
 206 The possible actions follow:
 207 .Pp
 208 .Bl -tag -width "A" -compact -offset indent
 209 .It A
 210 Added
 211 .It C
 212 Conflict
 213 .It D
 214 Deleted
 215 .It M
 216 Merged
 217 .It U
 218 Updated
 219 .El
 220 .Pp
 221 Finally,
 222 if any warnings were encountered they are displayed after the merge has
 223 completed.
 224 .Pp
 225 Note that for certain files
 226 .Nm
 227 will perform post-install actions any time that the file is updated.
 228 Specifically,
 229 .Xr pwd_mkdb 8
 230 is invoked if
 231 .Pa /etc/master.passwd
 232 is changed,
 233 .Xr cap_mkdb 1
 234 is invoked to update
 235 .Pa /etc/login.conf.db
 236 if
 237 .Pa /etc/login.conf
 238 is changed,
 239 .Xr newaliases 1
 240 is invoked if
 241 .Pa /etc/mail/aliases
 242 is changed,
 243 .Xr services_mkdb 8
 244 is invoked if
 245 .Pa /etc/services
 246 is changed,
 247 .Xr tzsetup 8
 248 is invoked if
 249 .Pa /etc/localtime
 250 is changed and if
 251 .Fa /var/db/zoneinfo
 252 exists,
 253 and
 254 .Pa /etc/rc.d/motd
 255 is invoked if
 256 .Pa /etc/motd
 257 is changed.
 258 One exception is that if
 259 .Pa /etc/mail/aliases
 260 is changed and the destination directory is not the default,
 261 then a warning will be issued instead.
 262 This is due to a limitation of the
 263 .Xr newaliases 1
 264 command.
 265 Similarly,
 266 if
 267 .Pa /etc/motd
 268 is changed and the destination directory is not the default,
 269 then
 270 .Pa /etc/rc.d/motd
 271 will not be executed due to a limitation of that script.
 272 In this case no warning is issued as the result of
 273 .Pa /etc/rc.d/motd
 274 is merely cosmetic and will be corrected on the next reboot.
 275 .Ss Build Mode
 276 The
 277 .Cm build
 278 mode is used to build a tarball that contains a snapshot of a
 279 .Dq current
 280 tree.
 281 This tarball can be used by the default and extract modes.
 282 Using a tarball can allow
 283 .Nm
 284 to perform a merge without requiring a source tree that matches the
 285 currently installed world.
 286 The
 287 .Fa tarball
 288 argument specifies the name of the file to create.
 289 The file will be a
 290 .Xr tar 5
 291 file compressed with
 292 .Xr bzip2 1 .
 293 .Ss Diff Mode
 294 The
 295 .Cm diff
 296 mode compares the versions of files in the destination directory to the
 297 .Dq current
 298 tree and generates a unified format diff of the changes.
 299 This can be used to determine which files have been locally modified and how.
 300 Note that
 301 .Nm
 302 does not manage files that are not maintained in the source tree such as
 303 .Pa /etc/fstab
 304 and
 305 .Pa /etc/rc.conf .
 306 .Ss Extract Mode
 307 The
 308 .Cm extract
 309 mode generates a new
 310 .Dq current
 311 tree.
 312 Unlike the default mode,
 313 it does not save any existing
 314 .Dq current
 315 tree and does not modify any existing
 316 .Dq previous
 317 tree.
 318 The new
 319 .Dq current
 320 tree can either be built from a source tree or extracted from a tarball.
 321 .Ss Resolve Mode
 322 The
 323 .Cm resolve
 324 mode is used to resolve any conflicts encountered during a merge.
 325 In this mode,
 326 .Nm
 327 iterates over any existing conflicts prompting the user for actions to take
 328 on each conflicted file.
 329 For each file, the following actions are available:
 330 .Pp
 331 .Bl -tag -width "(tf) theirs-full" -compact
 332 .It (p)  postpone
 333 Ignore this conflict for now.
 334 .It (df) diff-full
 335 Show all changes made to the merged file as a unified diff.
 336 .It (e)  edit
 337 Change the merged file in an editor.
 338 .It (r)  resolved
 339 Install the merged version of the file into the destination directory.
 340 .It (mf) mine-full
 341 Use the version of the file in the destination directory and ignore any
 342 changes made to the file in the
 343 .Dq current
 344 tree.
 345 .It (tf) theirs-full
 346 Use the version of the file from the
 347 .Dq current
 348 tree and discard any local changes made to the file.
 349 .It (h)  help
 350 Display the list of commands.
 351 .El
 352 .Ss Revert Mode
 353 The
 354 .Cm revert
 355 mode is used to restore the stock versions of files.
 356 In this mode,
 357 .Nm
 358 installs the stock version of requested files.
 359 This mode cannot be used to restore directories, only individual files.
 360 .Ss Status Mode
 361 The
 362 .Cm status
 363 mode shows a summary of the results of the most recent merge.
 364 First it lists any files for which there are unresolved conflicts.
 365 Next it lists any warnings generated during the last merge.
 366 If the last merge did not generate any conflicts or warnings,
 367 then nothing will be output.
 368 .Sh OPTIONS
 369 The following options are available.
 370 Note that most options do not apply to all modes.
 371 .Bl -tag -width ".Fl A Ar patterns"
 372 .It Fl A Ar patterns
 373 Always install the new version of any files that match any of the patterns
 374 listed in
 375 .Ar patterns .
 376 Each pattern is evaluated as an
 377 .Xr sh 1
 378 shell pattern.
 379 This option may be specified multiple times to specify multiple patterns.
 380 Multiple space-separated patterns may also be specified in a single
 381 option.
 382 Note that ignored files specified via the
 383 .Ev IGNORE_FILES
 384 variable or the
 385 .Fl I
 386 option will not be installed.
 387 .It Fl B
 388 Do not build generated files in a private object tree.
 389 Instead,
 390 reuse the generated files from a previously built object tree that matches
 391 the source tree.
 392 This can be useful to avoid gratuitous conflicts in
 393 .Xr sendmail 8
 394 configuration
 395 files when bootstrapping.
 396 It can also be useful for building a tarball that matches a specific
 397 world build.
 398 .It Fl D Ar destdir
 399 Specify an alternate destination directory as the target of a merge.
 400 This is analogous to the
 401 .Dv DESTDIR
 402 variable used with
 403 .Sq make installworld .
 404 The default destination directory is an empty string which results in
 405 merges updating
 406 .Pa /etc
 407 on the local machine.
 408 .It Fl d Ar workdir
 409 Specify an alternate directory to use as the work directory.
 410 The work directory is used to store the
 411 .Dq current
 412 and
 413 .Dq previous
 414 trees as well as unresolved conflicts.
 415 The default work directory is
 416 .Pa <destdir>/var/db/etcupdate .
 417 .It Fl F
 418 Ignore changes in the FreeBSD ID string when comparing files in the
 419 destination directory to files in either of the
 420 .Dq current
 421 or
 422 .Dq previous
 423 trees.
 424 In
 425 .Cm diff
 426 mode,
 427 this reduces noise due to FreeBSD ID string changes in the output.
 428 During an update this can simplify handling for harmless conflicts caused
 429 by FreeBSD ID string changes.
 430 .Pp
 431 Specifically,
 432 if a file in the destination directory is identical to the same file in the
 433 .Dq previous
 434 tree modulo the FreeBSD ID string,
 435 then the file is treated as if it was unmodified and the
 436 .Dq current
 437 version of the file will be installed.
 438 Similarly,
 439 if a file in the destination directory is identical to the same file in the
 440 .Dq current
 441 tree modulo the FreeBSD ID string,
 442 then the
 443 .Dq current
 444 version of the file will be installed to update the ID string.
 445 If the
 446 .Dq previous
 447 and
 448 .Dq current
 449 versions of the file are identical,
 450 then
 451 .Nm
 452 will not change the file in the destination directory.
 453 .Pp
 454 Due to limitations in the
 455 .Xr diff 1
 456 command,
 457 this option may not have an effect if there are other changes in a file that
 458 are close to the FreeBSD ID string.
 459 .It Fl I Ar patterns
 460 Ignore any files that match any of the patterns listed in
 461 .Ar patterns .
 462 No warnings or other messages will be generated for those files during a
 463 merge.
 464 Each pattern is evaluated as an
 465 .Xr sh 1
 466 shell pattern.
 467 This option may be specified multiple times to specify multiple patterns.
 468 Multiple space-separated patterns may also be specified in a single
 469 option.
 470 .It Fl L Ar logfile
 471 Specify an alternate path for the log file.
 472 The
 473 .Nm
 474 utility logs each command that it invokes along with the standard output
 475 and standard error to this file.
 476 By default the log file is stored in a file named
 477 .Pa log
 478 in the work directory.
 479 .It Fl M Ar options
 480 Pass
 481 .Ar options
 482 as additional parameters to
 483 .Xr make 1
 484 when building a
 485 .Dq current
 486 tree.
 487 This can be used for to set the
 488 .Dv TARGET
 489 or
 490 .Dv TARGET_ARCH
 491 variables for a cross-build.
 492 .It Fl n
 493 Enable
 494 .Dq dry-run
 495 mode.
 496 Do not merge any changes to the destination directory.
 497 Instead,
 498 report what actions would be taken during a merge.
 499 Note that the existing
 500 .Dq current
 501 and
 502 .Dq previous
 503 trees will not be changed.
 504 If the
 505 .Fl r
 506 option is not specified,
 507 then a temporary
 508 .Dq current
 509 tree will be extracted to perform the comparison.
 510 .It Fl p
 511 Enable
 512 .Dq pre-world
 513 mode.
 514 Only merge changes to files that are necessary to successfully run
 515 .Sq make installworld
 516 or
 517 .Sq make installkernel .
 518 When this flag is enabled,
 519 the existing
 520 .Dq current
 521 and
 522 .Dq previous
 523 trees are left alone.
 524 Instead,
 525 a temporary tree is populated with the necessary files.
 526 This temporary tree is compared against the
 527 .Dq current
 528 tree.
 529 This allows a normal update to be run after
 530 .Sq make installworld
 531 has completed.
 532 Any conflicts generated during a
 533 .Dq pre-world
 534 update should be resolved by a
 535 .Dq pre-world
 536 .Cm resolve .
 537 .It Fl r
 538 Do not update the
 539 .Dq current
 540 and
 541 .Dq previous
 542 trees during a merge.
 543 This can be used to
 544 .Dq re-run
 545 a previous merge operation.
 546 .It Fl s Ar source
 547 Specify an alternate source tree to use when building or extracting a
 548 .Dq current
 549 tree.
 550 The default source tree is
 551 .Pa /usr/src .
 552 .It Fl t Ar tarball
 553 Extract a new
 554 .Dq current
 555 tree from a tarball previously generated by the
 556 .Cm build
 557 command rather than building the tree from a source tree.
 558 .El
 559 .Sh CONFIG FILE
 560 The
 561 .Nm
 562 utility can also be configured by setting variables in an optional
 563 configuration file named
 564 .Pa /etc/etcupdate.conf .
 565 Note that command line options override settings in the configuration file.
 566 The configuration file is executed by
 567 .Xr sh 1 ,
 568 so it uses that syntax to set configuration variables.
 569 The following variables can be set:
 570 .Bl -tag -width ".Ev ALWAYS_INSTALL"
 571 .It Ev ALWAYS_INSTALL
 572 Always install files that match any of the patterns listed in this variable
 573 similar to the
 574 .Fl A
 575 option.
 576 .It Ev DESTDIR
 577 Specify an alternate destination directory similar to the
 578 .Fl D
 579 option.
 580 .It Ev EDITOR
 581 Specify a program to edit merge conflicts.
 582 .It Ev FREEBSD_ID
 583 Ignore changes in the FreeBSD ID string similar to the
 584 .Fl F
 585 option.
 586 This is enabled by setting the variable to a non-empty value.
 587 .It Ev IGNORE_FILES
 588 Ignore files that match any of the patterns listed in this variable
 589 similar to the
 590 .Fl I
 591 option.
 592 .It Ev LOGFILE
 593 Specify an alternate path for the log file similar to the
 594 .Fl L
 595 option.
 596 .It Ev MAKE_OPTIONS
 597 Pass additional options to
 598 .Xr make 1
 599 when building a
 600 .Dq current
 601 tree similar to the
 602 .Fl M
 603 option.
 604 .It Ev SRCDIR
 605 Specify an alternate source tree similar to the
 606 .Fl s
 607 option.
 608 .It Ev WORKDIR
 609 Specify an alternate work directory similar to the
 610 .Fl d
 611 option.
 612 .El
 613 .Sh ENVIRONMENT
 614 The
 615 .Nm
 616 utility uses the program identified in the
 617 .Ev EDITOR
 618 environment variable to edit merge conflicts.
 619 If
 620 .Ev EDITOR
 621 is not set,
 622 .Xr vi 1
 623 is used as the default editor.
 624 .Sh FILES
 625 .Bl -tag -width ".Pa /var/db/etcupdate/log" -compact
 626 .It Pa /etc/etcupdate.conf
 627 Optional config file.
 628 .It Pa /var/db/etcupdate
 629 Default work directory used to store trees and other data.
 630 .It Pa /var/db/etcupdate/log
 631 Default log file.
 632 .El
 633 .Sh EXIT STATUS
 634 .Ex -std
 635 .Sh EXAMPLES
 636 To compare the files in
 637 .Pa /etc
 638 with the stock versions:
 639 .Pp
 640 .Dl "etcupdate diff"
 641 .Pp
 642 To merge changes after an upgrade via the buildworld and installworld process:
 643 .Pp
 644 .Dl "etcupdate"
 645 .Pp
 646 To resolve any conflicts generated during a merge:
 647 .Pp
 648 .Dl "etcupdate resolve"
 649 .Ss Bootstrapping
 650 The
 651 .Nm
 652 utility may need to be bootstrapped before it can be used.
 653 The
 654 .Cm diff
 655 command will fail with an error about a missing reference tree if
 656 bootstrapping is needed.
 657 .Pp
 658 Bootstrapping
 659 .Nm
 660 requires a source tree that matches the currently installed world.
 661 The easiest way to ensure this is to bootstrap
 662 .Nm
 663 before updating the source tree to start the next world upgrade cycle.
 664 First,
 665 generate a reference tree:
 666 .Pp
 667 .Dl "etcupdate extract"
 668 .Pp
 669 Second,
 670 use the
 671 .Cm diff
 672 command to compare the reference tree to your current files in
 673 .Pa /etc .
 674 Undesired differences should be removed using an editor,
 675 .Xr patch 1 ,
 676 or by copying files from the reference tree
 677 .Po
 678 located at
 679 .Pa /var/db/etcupdate/current
 680 by default
 681 .Pc
 682 .
 683 .Pp
 684 If the tree at
 685 .Pa /usr/src
 686 is already newer than the currently installed world,
 687 a new tree matching the currently installed world can be checked out to
 688 a temporary location.
 689 The reference tree for
 690 .Nm
 691 can then be generated via:
 692 .Pp
 693 .Dl "etcupdate extract -s /path/to/tree"
 694 .Pp
 695 The
 696 .Cm diff
 697 command can be used as above to remove undesired differences.
 698 Afterwards,
 699 the changes in the tree at
 700 .Pa /usr/src
 701 can be merged via a regular merge.
 702 .Sh DIAGNOSTICS
 703 The following warning messages may be generated during a merge.
 704 Note that several of these warnings cover obscure cases that should occur
 705 rarely if at all in practice.
 706 For example,
 707 if a file changes from a file to a directory in the
 708 .Dq current
 709 tree
 710 and the file was modified in the destination directory,
 711 then a warning will be triggered.
 712 In general,
 713 when a warning references a pathname,
 714 the corresponding file in the destination directory is not changed by a
 715 merge operation.
 716 .Bl -diag
 717 .It "Directory mismatch: <path> (<type>)"
 718 An attempt was made to create a directory at
 719 .Pa path
 720 but an existing file of type
 721 .Dq type
 722 already exists for that path name.
 723 .It "Modified link changed: <file> (<old> became <new>)"
 724 The target of a symbolic link named
 725 .Pa file
 726 was changed from
 727 .Dq old
 728 to
 729 .Dq new
 730 in the
 731 .Dq current
 732 tree.
 733 The symbolic link has been modified to point to a target that is neither
 734 .Dq old
 735 nor
 736 .Dq new
 737 in the destination directory.
 738 .It "Modified mismatch: <file> (<new> vs <dest>)"
 739 A file named
 740 .Pa file
 741 of type
 742 .Dq new
 743 was modified in the
 744 .Dq current
 745 tree,
 746 but the file exists as a different type
 747 .Dq dest
 748 in the destination directory.
 749 .It "Modified <type> changed: <file> (<old> became <new>)"
 750 A file named
 751 .Pa file
 752 changed type from
 753 .Dq old
 754 in the
 755 .Dq previous
 756 tree to type
 757 .Dq new
 758 in the
 759 .Dq current
 760 tree.
 761 The file in the destination directory of type
 762 .Dq type
 763 has been modified,
 764 so it could not be merged automatically.
 765 .It "Modified <type> remains: <file>"
 766 The file of type
 767 .Dq type
 768 named
 769 .Pa file
 770 has been removed from the
 771 .Dq current
 772 tree,
 773 but it has been locally modified.
 774 The modified version of the file remains in the destination directory.
 775 .It "Needs update: /etc/localtime (required manual update via tzsetup(8))"
 776 The
 777 .Fa /var/db/zoneinfo
 778 file does not exist,
 779 so
 780 .Nm
 781 was not able to refresh
 782 .Fa /etc/localtime
 783 from its source file in
 784 .Fa /usr/share/zoneinfo .
 785 Running
 786 .Xr tzsetup 8
 787 will both refresh
 788 .Fa /etc/localtime
 789 and generate
 790 .Fa /var/db/zoneinfo
 791 permitting future updates to refresh
 792 .Fa /etc/localtime
 793 automatically.
 794 .It "Needs update: /etc/mail/aliases.db (required manual update via newaliases(1))"
 795 The file
 796 .Pa /etc/mail/aliases
 797 was updated during a merge with a non-empty destination directory.
 798 Due to a limitation of the
 799 .Xr newaliases 1
 800 command,
 801 .Nm
 802 was not able to automatically update the corresponding aliases database.
 803 .It "New file mismatch: <file> (<new> vs <dest>)"
 804 A new file named
 805 .Pa file
 806 of type
 807 .Dq new
 808 has been added to the
 809 .Dq current
 810 tree.
 811 A file of that name already exists in the destination directory,
 812 but it is of a different type
 813 .Dq dest .
 814 .It "New link conflict: <file> (<new> vs <dest>)"
 815 A symbolic link named
 816 .Pa file
 817 has been added to the
 818 .Dq current
 819 tree that links to
 820 .Dq new .
 821 A symbolic link of the same name already exists in the destination
 822 directory,
 823 but it links to a different target
 824 .Dq dest .
 825 .It "Non-empty directory remains: <file>"
 826 The directory
 827 .Pa file
 828 was removed from the
 829 .Dq current
 830 tree,
 831 but it contains additional files in the destination directory.
 832 These additional files as well as the directory remain.
 833 .It "Remove mismatch: <file> (<old> became <new>)"
 834 A file named
 835 .Pa file
 836 changed from type
 837 .Dq old
 838 in the
 839 .Dq previous
 840 tree to type
 841 .Dq new
 842 in the
 843 .Dq current
 844 tree,
 845 but it has been removed in the destination directory.
 846 .It "Removed file changed: <file>"
 847 A file named
 848 .Pa file
 849 was modified in the
 850 .Dq current
 851 tree,
 852 but it has been removed in the destination directory.
 853 .It "Removed link changed: <file> (<old> became <new>)"
 854 The target of a symbolic link named
 855 .Pa file
 856 was changed from
 857 .Dq old
 858 to
 859 .Dq new
 860 in the
 861 .Dq current
 862 tree,
 863 but it has been removed in the destination directory.
 864 .El
 865 .Sh SEE ALSO
 866 .Xr cap_mkdb 1 ,
 867 .Xr diff 1 ,
 868 .Xr make 1 ,
 869 .Xr newaliases 1 ,
 870 .Xr sh 1 ,
 871 .Xr mergemaster 8 ,
 872 .Xr pwd_mkdb 8 ,
 873 .Xr services_mkdb 8 ,
 874 .Xr tzsetup 8
 875 .Sh HISTORY
 876 The
 877 .Nm
 878 utility first appeared in
 879 .Fx 10.0 .
 880 .Sh AUTHORS
 881 The
 882 .Nm
 883 utility was written by
 884 .An John Baldwin Aq Mt jhb@FreeBSD.org .
 885 .Sh BUGS
 886 Rerunning a merge does not automatically delete conflicts left over from a
 887 previous merge.
 888 Any conflicts must be resolved before the merge can be rerun.
 889 It is not clear if this is a feature or a bug.
 890 .Pp
 891 There is no way to easily automate conflict resolution for specific files.
 892 For example, one can imagine a syntax along the lines of
 893 .Pp
 894 .Dl "etcupdate resolve tf /some/file"
 895 .Pp
 896 to resolve a specific conflict in an automated fashion.
 897 .Pp
 898 Bootstrapping
 899 .Nm
 900 often results in gratuitous diffs in
 901 .Pa /etc/mail/*.cf
 902 that cause conflicts in the first merge.
 903 If an object tree that matches the source tree is present when bootstrapping,
 904 then passing the
 905 .Fl B
 906 flag to the
 907 .Cm extract
 908 command can work around this.