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