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
85 utility is a tool for managing updates to files that are not updated as
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.
95 To perform a three-way merge,
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
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,
113 will update the file automatically.
114 If the local changes to a file conflict with the changes made to a file in
116 then a merge conflict is generated.
117 The conflict must be resolved after the merge has finished.
120 utility will not perform a new merge until all conflicts from an earlier
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.
130 The default mode merges changes from the source tree to the destination
139 it compares the two trees merging changes into the destination directory.
141 it displays warnings for any conditions it could not handle automatically.
145 option is not specified,
146 then the first step taken is to update the
154 then that tree is saved as the
159 tree is removed if it exists.
162 tree is built from a source tree.
164 if a tarball is specified via the
167 then the tree is extracted from that tarball instead.
171 compares the files in the
176 If a file was removed from the
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
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
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
196 If the merge does not encounter conflicts,
197 then the merged version of the file will be saved in the destination
201 is not able to safely merge in changes to a file other than a merge conflict,
202 it will generate a warning.
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:
208 .Bl -tag -width "A" -compact -offset indent
222 if any warnings were encountered they are displayed after the merge has
225 Note that for certain files
227 will perform post-install actions any time that the file is updated.
231 .Pa /etc/master.passwd
235 .Pa /etc/login.conf.db
241 .Pa /etc/mail/aliases
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
268 is changed and the destination directory is not the default,
271 will not be executed due to a limitation of that script.
272 In this case no warning is issued as the result of
274 is merely cosmetic and will be corrected on the next reboot.
278 mode is used to build a tarball that contains a snapshot of a
281 This tarball can be used by the default and extract modes.
282 Using a tarball can allow
284 to perform a merge without requiring a source tree that matches the
285 currently installed world.
288 argument specifies the name of the file to create.
296 mode compares the versions of files in the destination directory to the
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.
302 does not manage files that are not maintained in the source tree such as
312 Unlike the default mode,
313 it does not save any existing
315 tree and does not modify any existing
320 tree can either be built from a source tree or extracted from a tarball.
324 mode is used to resolve any conflicts encountered during a merge.
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:
331 .Bl -tag -width "(tf) theirs-full" -compact
333 Ignore this conflict for now.
335 Show all changes made to the merged file as a unified diff.
337 Change the merged file in an editor.
339 Install the merged version of the file into the destination directory.
341 Use the version of the file in the destination directory and ignore any
342 changes made to the file in the
346 Use the version of the file from the
348 tree and discard any local changes made to the file.
350 Display the list of commands.
355 mode is used to restore the stock versions of files.
358 installs the stock version of requested files.
359 This mode cannot be used to restore directories, only individual files.
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.
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"
373 Always install the new version of any files that match any of the patterns
376 Each pattern is evaluated as an
379 This option may be specified multiple times to specify multiple patterns.
380 Multiple space-separated patterns may also be specified in a single
382 Note that ignored files specified via the
386 option will not be installed.
388 Do not build generated files in a private object tree.
390 reuse the generated files from a previously built object tree that matches
392 This can be useful to avoid gratuitous conflicts in
395 files when bootstrapping.
396 It can also be useful for building a tarball that matches a specific
399 Specify an alternate destination directory as the target of a merge.
400 This is analogous to the
403 .Sq make installworld .
404 The default destination directory is an empty string which results in
407 on the local machine.
409 Specify an alternate directory to use as the work directory.
410 The work directory is used to store the
414 trees as well as unresolved conflicts.
415 The default work directory is
416 .Pa <destdir>/var/db/etcupdate .
418 Ignore changes in the FreeBSD ID string when comparing files in the
419 destination directory to files in either of the
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.
432 if a file in the destination directory is identical to the same file in the
434 tree modulo the FreeBSD ID string,
435 then the file is treated as if it was unmodified and the
437 version of the file will be installed.
439 if a file in the destination directory is identical to the same file in the
441 tree modulo the FreeBSD ID string,
444 version of the file will be installed to update the ID string.
449 versions of the file are identical,
452 will not change the file in the destination directory.
454 Due to limitations in the
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.
460 Ignore any files that match any of the patterns listed in
462 No warnings or other messages will be generated for those files during a
464 Each pattern is evaluated as an
467 This option may be specified multiple times to specify multiple patterns.
468 Multiple space-separated patterns may also be specified in a single
471 Specify an alternate path for the log file.
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
478 in the work directory.
482 as additional parameters to
487 This can be used for to set the
491 variables for a cross-build.
496 Do not merge any changes to the destination directory.
498 report what actions would be taken during a merge.
499 Note that the existing
503 trees will not be changed.
506 option is not specified,
509 tree will be extracted to perform the comparison.
514 Only merge changes to files that are necessary to successfully run
515 .Sq make installworld
517 .Sq make installkernel .
518 When this flag is enabled,
523 trees are left alone.
525 a temporary tree is populated with the necessary files.
526 This temporary tree is compared against the
529 This allows a normal update to be run after
530 .Sq make installworld
532 Any conflicts generated during a
534 update should be resolved by a
542 trees during a merge.
545 a previous merge operation.
547 Specify an alternate source tree to use when building or extracting a
550 The default source tree is
555 tree from a tarball previously generated by the
557 command rather than building the tree from a source tree.
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
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
577 Specify an alternate destination directory similar to the
581 Specify a program to edit merge conflicts.
583 Ignore changes in the FreeBSD ID string similar to the
586 This is enabled by setting the variable to a non-empty value.
588 Ignore files that match any of the patterns listed in this variable
593 Specify an alternate path for the log file similar to the
597 Pass additional options to
605 Specify an alternate source tree similar to the
609 Specify an alternate work directory similar to the
616 utility uses the program identified in the
618 environment variable to edit merge conflicts.
623 is used as the default editor.
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
636 To compare the files in
638 with the stock versions:
642 To merge changes after an upgrade via the buildworld and installworld process:
646 To resolve any conflicts generated during a merge:
648 .Dl "etcupdate resolve"
652 utility may need to be bootstrapped before it can be used.
655 command will fail with an error about a missing reference tree if
656 bootstrapping is needed.
660 requires a source tree that matches the currently installed world.
661 The easiest way to ensure this is to bootstrap
663 before updating the source tree to start the next world upgrade cycle.
665 generate a reference tree:
667 .Dl "etcupdate extract"
672 command to compare the reference tree to your current files in
674 Undesired differences should be removed using an editor,
676 or by copying files from the reference tree
679 .Pa /var/db/etcupdate/current
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
691 can then be generated via:
693 .Dl "etcupdate extract -s /path/to/tree"
697 command can be used as above to remove undesired differences.
699 the changes in the tree at
701 can be merged via a regular merge.
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.
707 if a file changes from a file to a directory in the
710 and the file was modified in the destination directory,
711 then a warning will be triggered.
713 when a warning references a pathname,
714 the corresponding file in the destination directory is not changed by a
717 .It "Directory mismatch: <path> (<type>)"
718 An attempt was made to create a directory at
720 but an existing file of 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
733 The symbolic link has been modified to point to a target that is neither
737 in the destination directory.
738 .It "Modified mismatch: <file> (<new> vs <dest>)"
746 but the file exists as a different type
748 in the destination directory.
749 .It "Modified <type> changed: <file> (<old> became <new>)"
761 The file in the destination directory of type
764 so it could not be merged automatically.
765 .It "Modified <type> remains: <file>"
770 has been removed from the
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))"
781 was not able to refresh
783 from its source file in
784 .Fa /usr/share/zoneinfo .
791 permitting future updates to refresh
794 .It "Needs update: /etc/mail/aliases.db (required manual update via newaliases(1))"
796 .Pa /etc/mail/aliases
797 was updated during a merge with a non-empty destination directory.
798 Due to a limitation of the
802 was not able to automatically update the corresponding aliases database.
803 .It "New file mismatch: <file> (<new> vs <dest>)"
808 has been added to the
811 A file of that name already exists in the destination directory,
812 but it is of a different type
814 .It "New link conflict: <file> (<new> vs <dest>)"
815 A symbolic link named
817 has been added to the
821 A symbolic link of the same name already exists in the destination
823 but it links to a different target
825 .It "Non-empty directory remains: <file>"
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>)"
845 but it has been removed in the destination directory.
846 .It "Removed file changed: <file>"
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
863 but it has been removed in the destination directory.
873 .Xr services_mkdb 8 ,
878 utility first appeared in
883 utility was written by
884 .An John Baldwin Aq Mt jhb@FreeBSD.org .
886 Rerunning a merge does not automatically delete conflicts left over from a
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.
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
894 .Dl "etcupdate resolve tf /some/file"
896 to resolve a specific conflict in an automated fashion.
900 often results in gratuitous diffs in
902 that cause conflicts in the first merge.
903 If an object tree that matches the source tree is present when bootstrapping,
908 command can work around this.