1 .\" Copyright (c) 2010-2013 Hudson River Trading LLC
2 .\" Written by: John H. Baldwin <jhb@FreeBSD.org>
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
33 .Nd "manage updates to system files not updated by installworld"
38 .Op Fl r | Fl s Ar source | Fl t Ar tarball
62 .Op Fl s Ar source | Fl t Ar tarball
78 utility is a tool for managing updates to files that are not updated as
83 It manages updates by doing a three-way merge of changes made to these
84 files against the local versions.
85 It is also designed to minimize the amount of user intervention with
86 the goal of simplifying upgrades for clusters of machines.
88 To perform a three-way merge,
90 keeps copies of the current and previous versions of files that it manages.
91 These copies are stored in two trees known as the
102 copies of each file to determine which changes need to be merged into the
103 local version of each file.
104 If a file can be updated without generating a conflict,
106 will update the file automatically.
107 If the local changes to a file conflict with the changes made to a file in
109 then a merge conflict is generated.
110 The conflict must be resolved after the merge has finished.
113 utility will not perform a new merge until all conflicts from an earlier
118 utility supports several modes of operation.
119 The mode is specified via an optional command argument.
120 If present, the command must be the first argument on the command line.
121 If a command is not specified, the default mode is used.
123 The default mode merges changes from the source tree to the destination
132 it compares the two trees merging changes into the destination directory.
134 it displays warnings for any conditions it could not handle automatically.
138 option is not specified,
139 then the first step taken is to update the
147 then that tree is saved as the
152 tree is removed if it exists.
155 tree is built from a source tree.
157 if a tarball is specified via the
160 then the tree is extracted from that tarball instead.
164 compares the files in the
169 If a file was removed from the
172 then it will be removed from the destination directory only if it
173 does not have any local modifications.
174 If a file was added to the
177 then it will be copied to the destination directory only if it
178 would not clobber an existing file.
179 If a file is changed in the
184 will attempt to merge the changes into the version of the file in the
185 destination directory.
186 If the merge encounters conflicts,
187 then a version of the file with conflict markers will be saved for
189 If the merge does not encounter conflicts,
190 then the merged version of the file will be saved in the destination
194 is not able to safely merge in changes to a file other than a merge conflict,
195 it will generate a warning.
197 For each file that is updated a line will be output with a leading character
198 to indicate the action taken.
199 The possible actions follow:
201 .Bl -tag -width "A" -compact -offset indent
215 if any warnings were encountered they are displayed after the merge has
218 Note that for certain files
220 will perform post-install actions any time that the file is updated.
224 .Pa /etc/master.passwd
228 .Pa /etc/login.conf.db
234 .Pa /etc/mail/aliases
251 One exception is that if
252 .Pa /etc/mail/aliases
253 is changed and the destination directory is not the default,
254 then a warning will be issued instead.
255 This is due to a limitation of the
261 is changed and the destination directory is not the default,
264 will not be executed due to a limitation of that script.
265 In this case no warning is issued as the result of
267 is merely cosmetic and will be corrected on the next reboot.
271 mode is used to build a tarball that contains a snapshot of a
274 This tarball can be used by the default and extract modes.
275 Using a tarball can allow
277 to perform a merge without requiring a source tree that matches the
278 currently installed world.
281 argument specifies the name of the file to create.
289 mode compares the versions of files in the destination directory to the
291 tree and generates a unified format diff of the changes.
292 This can be used to determine which files have been locally modified and how.
295 does not manage files that are not maintained in the source tree such as
305 Unlike the default mode,
306 it does not save any existing
308 tree and does not modify any existing
313 tree can either be built from a source tree or extracted from a tarball.
317 mode is used to resolve any conflicts encountered during a merge.
320 iterates over any existing conflicts prompting the user for actions to take
321 on each conflicted file.
322 For each file, the following actions are available:
324 .Bl -tag -width "(tf) theirs-full" -compact
326 Ignore this conflict for now.
328 Show all changes made to the merged file as a unified diff.
330 Change the merged file in an editor.
332 Install the merged version of the file into the destination directory.
334 Use the version of the file in the destination directory and ignore any
335 changes made to the file in the
339 Use the version of the file from the
341 tree and discard any local changes made to the file.
343 Display the list of commands.
348 mode shows a summary of the results of the most recent merge.
349 First it lists any files for which there are unresolved conflicts.
350 Next it lists any warnings generated during the last merge.
351 If the last merge did not generate any conflicts or warnings,
352 then nothing will be output.
354 The following options are available.
355 Note that most options do not apply to all modes.
356 .Bl -tag -width ".Fl A Ar patterns"
358 Always install the new version of any files that match any of the patterns
361 Each pattern is evaluated as an
364 This option may be specified multiple times to specify multiple patterns.
365 Multiple space-separated patterns may also be specified in a single
367 Note that ignored files specified via the
371 option will not be installed.
373 Do not build generated files in a private object tree.
375 reuse the generated files from a previously built object tree that matches
377 This can be useful to avoid gratuitous conflicts in
380 files when bootstrapping.
381 It can also be useful for building a tarball that matches a specific
384 Specify an alternate destination directory as the target of a merge.
385 This is analogous to the
388 .Sq make installworld .
389 The default destination directory is an empty string which results in
392 on the local machine.
394 Specify an alternate directory to use as the work directory.
395 The work directory is used to store the
399 trees as well as unresolved conflicts.
400 The default work directory is
401 .Pa <destdir>/var/db/etcupdate .
403 Ignore changes in the FreeBSD ID string when comparing files in the
404 destination directory to files in either of the
412 this reduces noise due to FreeBSD ID string changes in the output.
413 During an update this can simplify handling for harmless conflicts caused
414 by FreeBSD ID string changes.
417 if a file in the destination directory is identical to the same file in the
419 tree modulo the FreeBSD ID string,
420 then the file is treated as if it was unmodified and the
422 version of the file will be installed.
424 if a file in the destination directory is identical to the same file in the
426 tree modulo the FreeBSD ID string,
429 version of the file will be installed to update the ID string.
434 versions of the file are identical,
437 will not change the file in the destination directory.
439 Due to limitations in the
442 this option may not have an effect if there are other changes in a file that
443 are close to the FreeBSD ID string.
445 Ignore any files that match any of the patterns listed in
447 No warnings or other messages will be generated for those files during a
449 Each pattern is evaluated as an
452 This option may be specified multiple times to specify multiple patterns.
453 Multiple space-separated patterns may also be specified in a single
456 Specify an alternate path for the log file.
459 utility logs each command that it invokes along with the standard output
460 and standard error to this file.
461 By default the log file is stored in a file named
463 in the work directory.
467 as additional parameters to
472 This can be used for to set the
476 variables for a cross-build.
481 Do not merge any changes to the destination directory.
483 report what actions would be taken during a merge.
484 Note that the existing
488 trees will not be changed.
491 option is not specified,
494 tree will be extracted to perform the comparison.
499 Only merge changes to files that are necessary to successfully run
500 .Sq make installworld
502 .Sq make installkernel .
503 When this flag is enabled,
508 trees are left alone.
510 a temporary tree is populated with the necessary files.
511 This temporary tree is compared against the
514 This allows a normal update to be run after
515 .Sq make installworld
517 Any conflicts generated during a
519 update should be resolved by a
527 trees during a merge.
530 a previous merge operation.
532 Specify an alternate source tree to use when building or extracting a
535 The default source tree is
540 tree from a tarball previously generated by the
542 command rather than building the tree from a source tree.
547 utility can also be configured by setting variables in an optional
548 configuration file named
549 .Pa /etc/etcupdate.conf .
550 Note that command line options override settings in the configuration file.
551 The configuration file is executed by
553 so it uses that syntax to set configuration variables.
554 The following variables can be set:
555 .Bl -tag -width ".Ev ALWAYS_INSTALL"
556 .It Ev ALWAYS_INSTALL
557 Always install files that match any of the patterns listed in this variable
562 Specify an alternate destination directory similar to the
566 Specify a program to edit merge conflicts.
568 Ignore changes in the FreeBSD ID string similar to the
571 This is enabled by setting the variable to a non-empty value.
573 Ignore files that match any of the patterns listed in this variable
578 Specify an alternate path for the log file similar to the
582 Pass additional options to
590 Specify an alternate source tree similar to the
594 Specify an alternate work directory similar to the
601 utility uses the program identified in the
603 environment variable to edit merge conflicts.
608 is used as the default editor.
610 .Bl -tag -width ".Pa /var/db/etcupdate/log" -compact
611 .It Pa /etc/etcupdate.conf
612 Optional config file.
613 .It Pa /var/db/etcupdate
614 Default work directory used to store trees and other data.
615 .It Pa /var/db/etcupdate/log
621 To compare the files in
623 with the stock versions:
627 To merge changes after an upgrade via the buildworld and installworld process:
631 To resolve any conflicts generated during a merge:
633 .Dl "etcupdate resolve"
637 utility may need to be bootstrapped before it can be used.
640 command will fail with an error about a missing reference tree if
641 bootstrapping is needed.
645 requires a source tree that matches the currently installed world.
646 The easiest way to ensure this is to bootstrap
648 before updating the source tree to start the next world upgrade cycle.
650 generate a reference tree:
652 .Dl "etcupdate extract"
657 command to compare the reference tree to your current files in
659 Undesired differences should be removed using an editor,
661 or by copying files from the reference tree
664 .Pa /var/db/etcupdate/current
671 is already newer than the currently installed world,
672 a new tree matching the currently installed world can be checked out to
673 a temporary location.
674 The reference tree for
676 can then be generated via:
678 .Dl "etcupdate extract -s /path/to/tree"
682 command can be used as above to remove undesired differences.
684 the changes in the tree at
686 can be merged via a regular merge.
688 The following warning messages may be generated during a merge.
689 Note that several of these warnings cover obscure cases that should occur
690 rarely if at all in practice.
692 if a file changes from a file to a directory in the
695 and the file was modified in the destination directory,
696 then a warning will be triggered.
698 when a warning references a pathname,
699 the corresponding file in the destination directory is not changed by a
702 .It "Directory mismatch: <path> (<type>)"
703 An attempt was made to create a directory at
705 but an existing file of type
707 already exists for that path name.
708 .It "Modified link changed: <file> (<old> became <new>)"
709 The target of a symbolic link named
718 The symbolic link has been modified to point to a target that is neither
722 in the destination directory.
723 .It "Modified mismatch: <file> (<new> vs <dest>)"
731 but the file exists as a different type
733 in the destination directory.
734 .It "Modified <type> changed: <file> (<old> became <new>)"
746 The file in the destination directory of type
749 so it could not be merged automatically.
750 .It "Modified <type> remains: <file>"
755 has been removed from the
758 but it has been locally modified.
759 The modified version of the file remains in the destination directory.
760 .It "Needs update: /etc/localtime (required manual update via tzsetup(8))"
766 was not able to refresh
768 from its source file in
769 .Fa /usr/share/zoneinfo .
776 permitting future updates to refresh
779 .It "Needs update: /etc/mail/aliases.db (required manual update via newaliases(1))"
781 .Pa /etc/mail/aliases
782 was updated during a merge with a non-empty destination directory.
783 Due to a limitation of the
787 was not able to automatically update the corresponding aliases database.
788 .It "New file mismatch: <file> (<new> vs <dest>)"
793 has been added to the
796 A file of that name already exists in the destination directory,
797 but it is of a different type
799 .It "New link conflict: <file> (<new> vs <dest>)"
800 A symbolic link named
802 has been added to the
806 A symbolic link of the same name already exists in the destination
808 but it links to a different target
810 .It "Non-empty directory remains: <file>"
816 but it contains additional files in the destination directory.
817 These additional files as well as the directory remain.
818 .It "Remove mismatch: <file> (<old> became <new>)"
830 but it has been removed in the destination directory.
831 .It "Removed file changed: <file>"
837 but it has been removed in the destination directory.
838 .It "Removed link changed: <file> (<old> became <new>)"
839 The target of a symbolic link named
848 but it has been removed in the destination directory.
858 .Xr services_mkdb 8 ,
863 utility first appeared in
868 utility was written by
869 .An John Baldwin Aq Mt jhb@FreeBSD.org .
871 Rerunning a merge does not automatically delete conflicts left over from a
873 Any conflicts must be resolved before the merge can be rerun.
874 It is not clear if this is a feature or a bug.
876 There is no way to easily automate conflict resolution for specific files.
877 For example, one can imagine a syntax along the lines of
879 .Dl "etcupdate resolve tf /some/file"
881 to resolve a specific conflict in an automated fashion.
883 It might be nice to have something like a
885 command to replace a locally modified version of a file with the stock
889 .Dl "etcupdate revert /etc/mail/freebsd.cf"
893 often results in gratuitous diffs in
895 that cause conflicts in the first merge.
896 If an object tree that matches the source tree is present when bootstrapping,
901 command can work around this.