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