1 .\" Copyright (c) 2010-2012 Advanced Computing Technologies 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
77 utility is a tool for managing updates to files that are not updated as
82 It manages updates by doing a three-way merge of changes made to these
83 files against the local versions.
84 It is also designed to minimize the amount of user intervention with
85 the goal of simplifying upgrades for clusters of machines.
87 To perform a three-way merge,
89 keeps copies of the current and previous versions of files that it manages.
90 These copies are stored in two trees known as the
101 copies of each file to determine which changes need to be merged into the
102 local version of each file.
103 If a file can be updated without generating a conflict,
105 will update the file automatically.
106 If the local changes to a file conflict with the changes made to a file in
108 then a merge conflict is generated.
109 The conflict must be resolved after the merge has finished.
112 utility will not perform a new merge until all conflicts from an earlier
117 utility supports several modes of operation.
118 The mode is specified via an optional command argument.
119 If present, the command must be the first argument on the command line.
120 If a command is not specified, the default mode is used.
122 The default mode merges changes from the source tree to the destination
131 it compares the two trees merging changes into the destination directory.
133 it displays warnings for any conditions it could not handle automatically.
137 option is not specified,
138 then the first step taken is to update the
146 then that tree is saved as the
151 tree is removed if it exists.
154 tree is built from a source tree.
156 if a tarball is specified via the
159 then the tree is extracted from that tarball instead.
163 compares the files in the
168 If a file was removed from the
171 then it will be removed from the destination directory only if it
172 does not have any local modifications.
173 If a file was added to the
176 then it will be copied to the destination directory only if it
177 would not clobber an existing file.
178 If a file is changed in the
183 will attempt to merge the changes into the version of the file in the
184 destination directory.
185 If the merge encounters conflicts,
186 then a version of the file with conflict markers will be saved for
188 If the merge does not encounter conflicts,
189 then the merged version of the file will be saved in the destination
193 is not able to safely merge in changes to a file other than a merge conflict,
194 it will generate a warning.
196 For each file that is updated a line will be output with a leading character
197 to indicate the action taken.
198 The possible actions follow:
200 .Bl -tag -width "A" -compact -offset indent
214 if any warnings were encountered they are displayed after the merge has
217 Note that for certain files
219 will perform post-install actions any time that the file is updated.
223 .Pa /etc/master.passwd
227 .Pa /etc/login.conf.db
233 .Pa /etc/mail/aliases
240 One exception is that if
241 .Pa /etc/mail/aliases
242 is changed and the destination directory is not the default,
243 then a warning will be issued instead.
244 This is due to a limitation of the
250 is changed and the destination directory is not the default,
253 will not be executed due to a limitation of that script.
254 In this case no warning is issued as the result of
256 is merely cosmetic and will be corrected on the next reboot.
260 mode is used to build a tarball that contains a snapshot of a
263 This tarball can be used by the default and extract modes.
264 Using a tarball can allow
266 to perform a merge without requiring a source tree that matches the
267 currently installed world.
270 argument specifies the name of the file to create.
278 mode compares the versions of files in the destination directory to the
280 tree and generates a unified format diff of the changes.
281 This can be used to determine which files have been locally modified and how.
284 does not manage files that are not maintained in the source tree such as
294 Unlike the default mode,
295 it does not save any existing
297 tree and does not modify any existing
302 tree can either be built from a source tree or extracted from a tarball.
306 mode is used to resolve any conflicts encountered during a merge.
309 iterates over any existing conflicts prompting the user for actions to take
310 on each conflicted file.
311 For each file, the following actions are available:
313 .Bl -tag -width "(tf) theirs-full" -compact
315 Ignore this conflict for now.
317 Show all changes made to the merged file as a unified diff.
319 Change the merged file in an editor.
321 Install the merged version of the file into the destination directory.
323 Use the version of the file in the destination directory and ignore any
324 changes made to the file in the
328 Use the version of the file from the
330 tree and discard any local changes made to the file.
332 Display the list of commands.
337 mode shows a summary of the results of the most recent merge.
338 First it lists any files for which there are unresolved conflicts.
339 Next it lists any warnings generated during the last merge.
340 If the last merge did not generate any conflicts or warnings,
341 then nothing will be output.
343 The following options are available.
344 Note that most options do not apply to all modes.
345 .Bl -tag -width ".Fl d Ar workdir"
347 Do not build generated files in a private object tree.
349 reuse the generated files from a previously built object tree that matches
351 This can be useful to avoid gratuitous conflicts in
354 files when bootstrapping.
355 It can also be useful for building a tarball that matches a specific
358 Specify an alternate directory to use as the work directory.
359 The work directory is used to store the
363 trees as well as unresolved conflicts.
364 The default work directory is
365 .Pa <destdir>/var/db/etcupdate .
367 Always install the new version of any files that match any of the patterns
370 Each pattern is evaluated as an
373 This option may be specified multiple times to specify multiple patterns.
374 Multiple space-separated patterns may also be specified in a single
376 Note that ignored files specified via the
380 option will not be installed.
382 Specify an alternate destination directory as the target of a merge.
383 This is analogous to the
386 .Sq make installworld .
387 The default destination directory is an empty string which results in
390 on the local machine.
392 Ignore changes in the FreeBSD ID string when comparing files in the
393 destination directory to files in either of the
401 this reduces noise due to FreeBSD ID string changes in the output.
402 During an update this can simplify handling for harmless conflicts caused
403 by FreeBSD ID string changes.
406 if a file in the destination directory is identical to the same file in the
408 tree modulo the FreeBSD ID string,
409 then the file is treated as if it was unmodified and the
411 version of the file will be installed.
413 if a file in the destination directory is identical to the same file in the
415 tree modulo the FreeBSD ID string,
418 version of the file will be installed to update the ID string.
423 versions of the file are identical,
426 will not change the file in the destination directory.
428 Due to limitations in the
431 this option may not have an effect if there are other changes in a file that
432 are close to the FreeBSD ID string.
434 Ignore any files that match any of the patterns listed in
436 No warnings or other messages will be generated for those files during a
438 Each pattern is evaluated as an
441 This option may be specified multiple times to specify multiple patterns.
442 Multiple space-separated patterns may also be specified in a single
445 Specify an alternate path for the log file.
448 utility logs each command that it invokes along with the standard output
449 and standard error to this file.
450 By default the log file is stored in a file named
452 in the work directory.
456 as additional parameters to
461 This can be used for to set the
465 variables for a cross-build.
470 Do not merge any changes to the destination directory.
472 report what actions would be taken during a merge.
473 Note that the existing
477 trees will not be changed.
480 option is not specified,
483 tree will be extracted to perform the comparison.
489 trees during a merge.
492 a previous merge operation.
494 Specify an alternate source tree to use when building or extracting a
497 The default source tree is
502 tree from a tarball previously generated by the
504 command rather than building the tree from a source tree.
509 utility can also be configured by setting variables in an optional
510 configuration file named
511 .Pa /etc/etcupdate.conf .
512 Note that command line options override settings in the configuration file.
513 The configuration file is executed by
515 so it uses that syntax to set configuration variables.
516 The following variables can be set:
517 .Bl -tag -width ".Ev ALWAYS_INSTALL"
518 .It Ev ALWAYS_INSTALL
519 Always install files that match any of the patterns listed in this variable
524 Specify an alternate destination directory similar to the
528 Specify a program to edit merge conflicts.
530 Ignore changes in the FreeBSD ID string similar to the
533 This is enabled by setting the variable to a non-empty value.
535 Ignore files that match any of the patterns listed in this variable
540 Specify an alternate path for the log file similar to the
544 Pass additional options to
552 Specify an alternate source tree similar to the
556 Specify an alternate work directory similar to the
563 utility uses the program identified in the
565 environment variable to edit merge conflicts.
570 is used as the default editor.
572 .Bl -tag -width ".Pa /var/db/etcupdate/log" -compact
573 .It Pa /etc/etcupdate.conf
574 Optional config file.
575 .It Pa /var/db/etcupdate
576 Default work directory used to store trees and other data.
577 .It Pa /var/db/etcupdate/log
583 If the source tree matches the currently installed world,
584 then the following can be used to bootstrap
586 so that it can be used for future upgrades:
588 .Dl "etcupdate extract"
590 To merge changes after an upgrade via the buildworld and installworld process:
594 To resolve any conflicts generated during a merge:
596 .Dl "etcupdate resolve"
598 The following warning messages may be generated during a merge.
599 Note that several of these warnings cover obscure cases that should occur
600 rarely if at all in practice.
602 if a file changes from a file to a directory in the
605 and the file was modified in the destination directory,
606 then a warning will be triggered.
608 when a warning references a pathname,
609 the corresponding file in the destination directory is not changed by a
612 .It "Directory mismatch: <path> (<type>)"
613 An attempt was made to create a directory at
615 but an existing file of type
617 already exists for that path name.
618 .It "Modified link changed: <file> (<old> became <new>)"
619 The target of a symbolic link named
628 The symbolic link has been modified to point to a target that is neither
632 in the destination directory.
633 .It "Modified mismatch: <file> (<new> vs <dest>)"
641 but the file exists as a different type
643 in the destination directory.
644 .It "Modified <type> changed: <file> (<old> became <new>)"
656 The file in the destination directory of type
659 so it could not be merged automatically.
660 .It "Modified <type> remains: <file>"
665 has been removed from the
668 but it has been locally modified.
669 The modified version of the file remains in the destination directory.
670 .It "Needs update: /etc/mail/aliases.db (required manual update via newaliases(1))"
672 .Pa /etc/mail/aliases
673 was updated during a merge with a non-empty destination directory.
674 Due to a limitation of the
678 was not able to automatically update the corresponding aliases database.
679 .It "New file mismatch: <file> (<new> vs <dest>)"
684 has been added to the
687 A file of that name already exists in the destination directory,
688 but it is of a different type
690 .It "New link conflict: <file> (<new> vs <dest>)"
691 A symbolic link named
693 has been added to the
697 A symbolic link of the same name already exists in the destination
699 but it links to a different target
701 .It "Non-empty directory remains: <file>"
707 but it contains additional files in the destination directory.
708 These additional files as well as the directory remain.
709 .It "Remove mismatch: <file> (<old> became <new>)"
721 but it has been removed in the destination directory.
722 .It "Removed file changed: <file>"
728 but it has been removed in the destination directory.
729 .It "Removed link changed: <file> (<old> became <new>)"
730 The target of a symbolic link named
739 but it has been removed in the destination directory.
751 utility first appeared in
756 utility was written by
757 .An John Baldwin Aq jhb@FreeBSD.org .
759 Rerunning a merge does not automatically delete conflicts left over from a
761 Any conflicts must be resolved before the merge can be rerun.
762 It it is not clear if this is a feature or a bug.
764 There is no way to easily automate conflict resolution for specific files.
765 For example, one can imagine a syntax along the lines of
767 .Dl "etcupdate resolve tf /some/file"
769 to resolve a specific conflict in an automated fashion.
771 It might be nice to have something like a
773 command to replace a locally modified version of a file with the stock
777 .Dl "etcupdate revert /etc/mail/freebsd.cf"
781 often results in gratuitous diffs in
783 that cause conflicts in the first merge.
784 If an object tree that matches the source tree is present when bootstrapping,
789 command can work around this.