1 '\" te 2 .\" Copyright (c) 1998 Sun Microsystems, Inc. All Rights Reserved. 3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. 4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. 5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] 6 .TH FILESYNC 1 "Nov 6, 2000" 7 .SH NAME 8 filesync \- synchronize ordinary, directory or special files 9 .SH SYNOPSIS 10 .LP 11 .nf 12 \fBfilesync\fR [\fB-aehmnqvy\fR] [\fB-o\fR src | dst] 13 [\fB-f\fR src | dst | old | new] [\fB-r\fR \fIdirectory\fR]... 14 .fi 15 16 .LP 17 .nf 18 \fBfilesync\fR [\fB-aehmnqvy\fR] \fB-s\fR \fIsource-dir\fR \fB-d\fR \fIdest-dir\fR \fIfilename\fR... 19 .fi 20 21 .SH DESCRIPTION 22 .sp 23 .LP 24 The \fBfilesync\fR utility \fIsynchronizes\fR files between multiple computer 25 systems, typically a server and a portable computer. \fBfilesync\fR 26 synchronizes ordinary, directory or special files. Although intended for use on 27 nomadic systems, \fBfilesync\fR is useful for backup and file replication on 28 more permanently connected systems. 29 .sp 30 .LP 31 If files are synchronized between systems, the corresponding files on each of 32 the systems are \fIidentical\fR. Changing a file on one or both of the systems 33 causes the files to become different (not synchronized). In order to make the 34 files identical again, the differences between the files must be 35 \fIreconciled\fR. See \fBReconciling and Synchronizing Files\fR for specific 36 details about how \fBfilesync\fR reconciles and synchronizes files. 37 .sp 38 .LP 39 There are two forms of the \fBfilesync\fR command. The first form of 40 \fBfilesync\fR is invoked without file arguments. This form of \fBfilesync\fR 41 reconciles differences between the files and systems specified in the 42 \fB$HOME/.packingrules\fR file. \fB$HOME/.packingrules\fR is a packing rules 43 list for \fBfilesync\fR and \fBcachefspack\fR, and contains a list of files to 44 be kept synchronized. See \fBpackingrules\fR(4) and \fBcachefspack\fR(1M). 45 .sp 46 .LP 47 The second form of \fBfilesync\fR copies specific files from a directory on the 48 source system to a directory on the destination system. In addition, this form 49 of \fBfilesync\fR adds the file or files specified as arguments 50 (\fIfilename\fR) to \fB$HOME/.packingrules\fR. See \fB-s\fR and \fB-d\fR for 51 information about specifying directories on source and destination systems. See 52 \fBOPERANDS\fR for details about specifying file (\fIfilename\fR) arguments. 53 .sp 54 .LP 55 Multiple \fBfilesync\fR commands are cumulative (that is, the specified files 56 are added to the already existing packing rules file list). See \fBMultiple 57 filesync Commands\fR. 58 .SS "Reconciling and Synchronizing Files" 59 .sp 60 .LP 61 \fBfilesync\fR synchronizes files between computer systems by performing the 62 following two tasks: 63 .RS +4 64 .TP 65 1. 66 \fBfilesync\fR examines the directories and files specified in the packing 67 rules file on both systems, and determines whether or not they are identical. 68 Any file that differs requires reconciliation. 69 .sp 70 \fBfilesync\fR also maintains a baseline summary in the 71 \fB$HOME/.filesync-base\fR file for all of the files that are being monitored. 72 This file lists the names, types, and sizes of all files as of the last 73 reconciliation. 74 .RE 75 .RS +4 76 .TP 77 2. 78 Based on the information contained in the baseline file and the specified 79 options (see \fBResolving filesync Conflicts\fR), \fBfilesync\fR determines 80 which of the various copies is the correct one, and makes the corresponding 81 changes to the other system. Once this has been done, the two copies are, 82 again, identical (synchronized). 83 .sp 84 If a source file has changed and the destination file has not, the changes on 85 the source system are propagated to the destination system. If a destination 86 file has changed and the corresponding source file has not, the changes on the 87 destination file are propagated to the source system. If both systems have 88 changed (and the files are not still identical) a warning message will be 89 printed out, asking the user to resolve the conflict manually. See 90 \fBResolving filesync Conflicts\fR. 91 .RE 92 .SS "Resolving filesync Conflicts" 93 .sp 94 .LP 95 In cases where files on both sides have changed, \fBfilesync\fR attempts to 96 determine which version should be chosen. If \fBfilesync\fR cannot 97 automatically determine which version should be selected, it prints out a 98 warning message and leaves the two incompatible versions of the file 99 unreconciled. 100 .sp 101 .LP 102 In these cases, you must either resolve the differences manually, or tell 103 \fBfilesync\fR how to choose which file should win. Use the \fB-o\fR and 104 \fB-f\fR options to tell \fBfilesync\fR how to resolve conflicts (see 105 \fBOPTIONS\fR). 106 .sp 107 .LP 108 Alternatively, for each conflicting file, you can examine the two versions, 109 determine which one should be kept, and manually bring the two versions into 110 agreement (by copying, deleting, or changing the ownership or protection to be 111 correct). You can then re-run \fBfilesync\fR to see whether or not any other 112 conflicts remain. 113 .SS "Packing Rules File" 114 .sp 115 .LP 116 The packing rules file \fB$HOME/.packingrules\fR contains a list of files to be 117 kept synchronized. The syntax of this file is described in 118 \fBpackingrules\fR(4). 119 .sp 120 .LP 121 The \fB$HOME/.packingrules\fR file is automatically created if users invoke 122 \fBfilesync\fR with filename arguments. By using \fBfilesync\fR options, users 123 can augment the packing rules in \fB$HOME/.packingrules\fR. 124 .sp 125 .LP 126 Many users choose to create the packing rules file manually and edit it by 127 hand. Users can edit \fB$HOME/.packingrules\fR (using any editor) to 128 permanently change the \fB$HOME/.packingrules\fR file, or to gain access to 129 more powerful options that are not available from the command line (such as 130 \fBIGNORE\fR commands). It is much easier to enter complex wildcard expressions 131 by editing the \fB$HOME/.packingrules\fR file. 132 .SS "Baseline File" 133 .sp 134 .LP 135 \fB$HOME/.filesync-base\fR is the \fBfilesync\fR baseline summary file. 136 \fBfilesync\fR uses the information in \fB$HOME/.filesync-base\fR to identify 137 the differences between files during the reconciliation and synchronization 138 process. Users do not create or edit the baseline file. It is created 139 automatically by \fBfilesync\fR and records the last known state of agreement 140 between all of the files being maintained. 141 .SS "Multiple filesync Commands" 142 .sp 143 .LP 144 Over a period of time, the set of files you want to keep synchronized can 145 change. It is common, for instance, to want to keep files pertaining to only a 146 few active projects on your notebook. If you continue to keep files associated 147 with every project you have ever worked on synchronized, your notebook's disk 148 will fill up with old files. Each \fBfilesync\fR command will waste a lot of 149 time updating files you no longer care about. 150 .sp 151 .LP 152 If you delete the files from your notebook, \fBfilesync\fR will want to perform 153 the corresponding deletes on the server, which would not be what you wanted. 154 Rather, you would like a way to tell \fBfilesync\fR to stop synchronizing some 155 of the files. There are two ways to do this: 156 .RS +4 157 .TP 158 1. 159 Edit \fB$HOME/.packingrules\fR. Delete the rules for the files that you 160 want to delete. 161 .RE 162 .RS +4 163 .TP 164 2. 165 Delete \fB$HOME/.packingrules\fR. Use the \fBfilesync\fR command to specify 166 the files that you want synchronized. 167 .RE 168 .sp 169 .LP 170 Either way works, and you can choose the one that seems easiest to you. For 171 minor changes, it is probably easier to just edit \fB$HOME/.packingrules\fR. 172 For major changes it is probably easier to start from scratch. 173 .sp 174 .LP 175 Once \fBfilesync\fR is no longer synchronizing a set of files, you can delete 176 them from your notebook without having any effect on the server. 177 .SS "Nomadic Machines" 178 .sp 179 .LP 180 When using \fBfilesync\fR to keep files synchronized between nomadic machines 181 and a server, store the packing rules and baseline files on the nomadic 182 machines, not the server. If, when logged into your notebook, the \fBHOME\fR 183 environment variable does not normally point to a directory on your notebook, 184 you can use the \fBFILESYNC\fR environment variable to specify an alternate 185 location for the packing rules and baseline files. 186 .sp 187 .LP 188 Each nomadic machine should carry its own packing rules and baseline file. 189 Incorrect file synchronization can result if a server carries a baseline file 190 and multiple nomadic machines attempt to reconcile against the server's 191 baseline file. In this case, a nomadic machine could be using a baseline file 192 that does not accurately describe the state of its files. This might result in 193 incorrect reconciliations. 194 .sp 195 .LP 196 To safeguard against the dangers associated with a single baseline file being 197 shared by more than two machines, \fBfilesync\fR adds a default rule to each 198 new packing rules file. This default rule prevents the packing rules and 199 baseline files from being copied. 200 .SH OPTIONS 201 .sp 202 .LP 203 The following options are supported: 204 .sp 205 .ne 2 206 .na 207 \fB\fB-a\fR\fR 208 .ad 209 .RS 28n 210 Force the checking of Access Control Lists (\fBACL\fRs ) and attempt to make 211 them agree for all new and changed files. If it is not possible to set the 212 \fBACL\fR for a particular file, \fBfilesync\fR stops \fBACL\fR synchronization 213 for that file. 214 .sp 215 Some file systems do not support \fBACL\fRs . It is not possible to synchronize 216 \fBACL\fRs between file systems that support \fBACL\fRs and those that do not; 217 attempting to do so will result in numerous error messages. 218 .RE 219 220 .sp 221 .ne 2 222 .na 223 \fB\fB-d\fR\fI dest-dir\fR\fR 224 .ad 225 .RS 28n 226 Specify the directory on the destination system into which \fIfilename\fR is to 227 be copied. Use with the \fB-s\fR\fI source-dir\fR option and the \fIfilename\fR 228 operand. See \fB-s\fR and \fBOPERANDS\fR. 229 .RE 230 231 .sp 232 .ne 2 233 .na 234 \fB\fB-e\fR\fR 235 .ad 236 .RS 28n 237 Flag all differences. It may not be possible to resolve all conflicts involving 238 modes and ownership (unless \fBfilesync\fR is being run with root privileges). 239 If you cannot change the ownership or protections on a file, \fBfilesync\fR 240 will normally ignore conflicts in ownership and protection. If you specify the 241 \fB-e\fR (everything must agree) flag, however, \fBfilesync\fR will flag these 242 differences. 243 .RE 244 245 .sp 246 .ne 2 247 .na 248 \fB\fB\fR\fB-f\fR\fB src\fR | \fBdst\fR | \fBold\fR | \fBnew\fR\fR 249 .ad 250 .RS 28n 251 The \fB-f\fR option tells \fBfilesync\fR how to resolve conflicting changes. If 252 a file has been changed on both systems, and an \fB-f\fR option has been 253 specified, \fBfilesync\fR will retain the changes made on the favored system 254 and discard the changes made on the unfavored system. 255 .sp 256 Specify \fB-f\fR \fBsrc\fR to favor the source-system file. Specify \fB-f\fR 257 \fBdst\fR to favor the destination-system file. Specify \fB-f\fR \fBold\fR to 258 favor the older version of the file. Specify \fB-f\fR \fBnew\fR to favor the 259 newer version of the file. 260 .sp 261 It is possible to specify the \fB-f\fR and \fB-o\fR options in combination 262 if they both specify the same preference (\fBsrc \fRand\fB dst\fR). If 263 \fB-f\fR and \fB-o\fR conflict, the \fB-f\fR option is ignored. See the 264 \fB-o\fR option description. 265 .RE 266 267 .sp 268 .ne 2 269 .na 270 \fB\fB-h\fR\fR 271 .ad 272 .RS 28n 273 Halt on error. Normally, if \fBfilesync\fR encounters a read or write error 274 while copying files, it notes the error and the program continues, in an 275 attempt to reconcile other files. If the \fB-h\fR option is specified, 276 \fBfilesync\fR will immediately halt when one of these errors occurs and will 277 not try to process any more files. 278 .RE 279 280 .sp 281 .ne 2 282 .na 283 \fB\fB-m\fR\fR 284 .ad 285 .RS 28n 286 Ensure that both copies of the file have the same modification time. The 287 modification time for newly copied files is set to the time of reconciliation 288 by default. File changes are ordered by increasing modification times so that 289 the propagated files have the same relative modification time ordering as the 290 original changes. Users should be warned that there is usually some time skew 291 between any two systems, and transferring modification times from one system 292 to another can occasionally produce strange results. 293 .sp 294 There are instances in which using \fBfilesync\fR to update some (but not all) 295 files in a directory will confuse the \fBmake\fR program. If, for instance, 296 \fBfilesync\fR is keeping \fB\&.c\fR files synchronized, but ignoring 297 \fB\&.o\fR files, a changed \fB\&.c\fR file may show up with a modification 298 time prior to a \fB\&.o\fR file that was built from a prior version of the 299 \fB\&.c\fR file. 300 .RE 301 302 .sp 303 .ne 2 304 .na 305 \fB\fB-n\fR\fR 306 .ad 307 .RS 28n 308 Do not really make the changes. If the \fB-n\fR option is specified, 309 \fBfilesync\fR determines what changes have been made to files, and what 310 reconciliations are required and displays this information on the standard 311 output. No changes are made to files, including the packing rules file. 312 .sp 313 Specifying both the \fB-n\fR and \fB-o\fR options causes \fBfilesync\fR to 314 analyze the prevailing system and report the changes that have been made on 315 that system. Using \fB-n\fR and \fB-o\fR in combination is useful if your 316 machine is disconnected (and you cannot access the server) but you want to know 317 what changes have been made on the local machine. See the \fB-o\fR option 318 description. 319 .RE 320 321 .sp 322 .ne 2 323 .na 324 \fB\fB\fR\fB-o\fR\fB src | dst\fR\fR 325 .ad 326 .RS 28n 327 The \fB-o\fR option forces a one-way reconciliation, favoring either the source 328 system (\fBsrc\fR) or destination system (\fBdst\fR). 329 .sp 330 Specify \fB-o\fR \fBsrc\fR to propagate changes only from the source system to 331 the destination system. Changes made on the destination system are ignored. 332 \fBfilesync\fR aborts if it cannot access a source or destination directory. 333 .sp 334 Specify \fB-o\fR \fBdst\fR to propagate changes only from the destination 335 system to the source system. Changes made on the source system are ignored. 336 \fBfilesync\fR aborts if it cannot access a source or destination directory. 337 .sp 338 Specifying \fB-n\fR with the \fB-o\fR option causes \fBfilesync\fR to analyze 339 the prevailing system and reports on what changes have been made on that 340 system. Using \fB-n\fR and \fB-o\fR in combination is useful if a machine is 341 disconnected (and there is no access to the server), but you want to know what 342 changes have been made on the local machine. See the \fB-n\fR option 343 description. 344 .sp 345 It is possible to specify the \fB-o\fR and \fB-f\fR options in combination if 346 they both specify the same preference (\fBsrc\fR or \fBdst\fR). If \fB-o\fR and 347 \fB-f\fR options conflict, the \fB-f\fR option will be ignored. See the 348 \fB-f\fR option description. 349 .RE 350 351 .sp 352 .ne 2 353 .na 354 \fB\fB-q\fR\fR 355 .ad 356 .RS 28n 357 Suppress the standard \fBfilesync\fR messages that describe each reconciliation 358 action as it is performed. 359 .sp 360 The standard \fBfilesync\fR message describes each reconciliation action in the 361 form of a UNIX shell command (for example, \fBmv\fR, \fBln\fR, \fBcp\fR, 362 \fBrm\fR, \fBchmod\fR, \fBchown\fR, \fBchgrp\fR, \fBsetfacl\fR, and so forth). 363 .RE 364 365 .sp 366 .ne 2 367 .na 368 \fB\fB-r\fR\fI directory\fR\fR 369 .ad 370 .RS 28n 371 Limit the reconciliation to \fIdirectory\fR. Specify multiple directories with 372 multiple \fB-r\fR specifications. 373 .RE 374 375 .sp 376 .ne 2 377 .na 378 \fB\fB-s\fR\fI source-dir\fR\fR 379 .ad 380 .RS 28n 381 Specify the directory on the source system from which the \fIfilename\fR to be 382 copied is located. Use with the \fB-d\fR\fI dest-dir\fR option and the 383 \fIfilename\fR operand. See the \fB-d\fR option description and 384 \fBOPERANDS\fR. 385 .RE 386 387 .sp 388 .ne 2 389 .na 390 \fB\fB-v\fR\fR 391 .ad 392 .RS 28n 393 Display additional information about each file comparison as it is made on the 394 standard output. 395 .RE 396 397 .sp 398 .ne 2 399 .na 400 \fB\fB-y\fR\fR 401 .ad 402 .RS 28n 403 Bypass safety check prompts. Nomadic machines occasionally move between 404 domains, and many of the files on which \fBfilesync\fR operates are expected to 405 be accessed by NFS. There is a danger that someday \fBfilesync\fR will be 406 asked to reconcile local changes against the wrong file system or server. This 407 could result in a large number of inappropriate copies and deletions. To 408 prevent such a mishap, \fBfilesync\fR performs a few safety checks prior to 409 reconciliation. If large numbers of files are likely to be deleted, or if high 410 level directories have changed their I-node numbers, \fBfilesync\fR prompts 411 for a confirmation before reconciliation. If you know that this is likely, and 412 do not want to be prompted, use the \fB-y\fR (yes) option to automatically 413 confirm these prompts. 414 .RE 415 416 .SH OPERANDS 417 .sp 418 .LP 419 The following operands are supported: 420 .sp 421 .ne 2 422 .na 423 \fB\fIfilename\fR\fR 424 .ad 425 .RS 12n 426 The name of the ordinary file, directory, symbolic link, or special file in the 427 specified source directory (\fIsource-dir\fR) to be synchronized. Specify 428 multiple files by separating each filename by spaces. Use the \fIfilename\fR 429 operand with the \fB-s\fR and \fB-d\fR options. See \fBOPTIONS\fR. 430 .sp 431 If \fIfilename\fR is an ordinary file, that ordinary file will be replicated 432 (with the same \fIfilename\fR) in the specified destination directory 433 (\fIdest-dir\fR). 434 .sp 435 If \fIfilename\fR is a directory, that directory and all of the files and 436 subdirectories under it will be replicated (recursively) in the specified 437 destination directory (\fIdest-dir\fR). 438 .sp 439 If \fIfilename\fR is a symbolic link, a copy of that symbolic link will be 440 replicated in the specified destination directory (\fIdest-dir\fR). 441 .sp 442 If \fIfilename\fR is a special file, a special file with the same major or 443 minor device numbers will be replicated in the specified destination directory. 444 (\fIdest-dir).\fR Only super-users can use \fBfilesync\fR to create special 445 files. 446 .sp 447 Files created in the destination directory (\fIdest-dir\fR) will have the same 448 owner, group and other permissions as the files in the source directory. 449 .sp 450 If \fIfilename\fR contains escaped shell wildcard characters, the wildcard 451 characters are stored in \fB$HOME/.packingrules\fR and evaluated each time 452 \fBfilesync\fR is run. 453 .sp 454 For example, the following would make sure that the two specified files, 455 currently in \fB$RHOME\fR, were replicated in \fB$HOME\fR: 456 .sp 457 .in +2 458 .nf 459 \fBfilesync \fR\fB-s\fR\fB $RHOME \fR\fB-d\fR\fB $HOME a.c \|b.c\fR 460 .fi 461 .in -2 462 .sp 463 464 The following example would ensure that all of the \fB*.c\fR files in 465 \fB$RHOME\fR were replicated in \fB$HOME\fR, even if those files were not 466 created until later. 467 .sp 468 .in +2 469 .nf 470 \fBfilesync \fR\fB-s\fR\fB $RHOME \fR\fB-d\fR\fB $HOME '*.c'\fR 471 .fi 472 .in -2 473 .sp 474 475 If any of the destination files already exist, \fBfilesync\fR ensures that 476 they are identical and issues warnings if they are not. 477 .sp 478 Once files have been copied, the distinction between the source and destination 479 is a relatively arbitrary one (except for its use in the \fB-o\fR and \fB-f\fR 480 switches). 481 .RE 482 483 .SH ENVIRONMENT VARIABLES 484 .sp 485 .ne 2 486 .na 487 \fB\fBFILESYNC\fR\fR 488 .ad 489 .RS 15n 490 Specifies the default location of the \fBfilesync\fR packing rules and baseline 491 files. The default value for this variable is \fB$HOME\fR. The suffixes 492 \fB\&.packingrules\fR and \fB\&.filesync-base\fR will be appended to form the 493 names of the packing rules and baseline files. 494 .RE 495 496 .sp 497 .ne 2 498 .na 499 \fB\fBLC_MESSAGES\fR\fR 500 .ad 501 .RS 15n 502 Determines how diagnostic and informative messages are presented. In the "C" 503 locale, the messages are presented in the default form found in the program 504 itself (in most cases, U.S. English). 505 .RE 506 507 .SH EXIT STATUS 508 .sp 509 .LP 510 Normally, if all files are already up-to-date, or if all files were 511 successfully reconciled, \fBfilesync\fR will exit with a status of \fB0\fR. 512 However, if either the \fB-n\fR option was specified or any errors occurred, 513 the exit status will be the logical OR of the following: 514 .sp 515 .ne 2 516 .na 517 \fB\fB0\fR\fR 518 .ad 519 .RS 7n 520 No conflicts, all files up to date. 521 .RE 522 523 .sp 524 .ne 2 525 .na 526 \fB\fB1\fR\fR 527 .ad 528 .RS 7n 529 Some resolvable conflicts. 530 .RE 531 532 .sp 533 .ne 2 534 .na 535 \fB\fB2\fR\fR 536 .ad 537 .RS 7n 538 Some conflicts requiring manual resolution. 539 .RE 540 541 .sp 542 .ne 2 543 .na 544 \fB\fB4\fR\fR 545 .ad 546 .RS 7n 547 Some specified files did not exist. 548 .RE 549 550 .sp 551 .ne 2 552 .na 553 \fB\fB8\fR\fR 554 .ad 555 .RS 7n 556 Insufficient permission for some files. 557 .RE 558 559 .sp 560 .ne 2 561 .na 562 \fB\fB16\fR\fR 563 .ad 564 .RS 7n 565 Errors accessing packing rules or baseline file. 566 .RE 567 568 .sp 569 .ne 2 570 .na 571 \fB\fB32\fR\fR 572 .ad 573 .RS 7n 574 Invalid arguments. 575 .RE 576 577 .sp 578 .ne 2 579 .na 580 \fB\fB64\fR\fR 581 .ad 582 .RS 7n 583 Unable to access either or both of the specified \fBsrc\fR or \fBdst\fR 584 directories. 585 .RE 586 587 .sp 588 .ne 2 589 .na 590 \fB\fB128\fR\fR 591 .ad 592 .RS 7n 593 Miscellaneous other failures. 594 .RE 595 596 .SH FILES 597 .sp 598 .ne 2 599 .na 600 \fB\fB$HOME/.packingrules\fR\fR 601 .ad 602 .RS 24n 603 list of files to be kept synchronized 604 .RE 605 606 .sp 607 .ne 2 608 .na 609 \fB\fB$HOME/.filesync-base\fR\fR 610 .ad 611 .RS 24n 612 baseline summary file 613 .RE 614 615 .SH SEE ALSO 616 .sp 617 .LP 618 \fBcachefspack\fR(1M), \fBpackingrules\fR(4), \fBattributes\fR(5)