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