Provided by: s3ql_3.7.0+dfsg-2build1_amd64 bug

NAME

       s3qlcp - Copy-on-write replication on S3QL file systems

SYNOPSIS

          s3qlcp [options] <source-dir> <dest-dir>

DESCRIPTION

       S3QL is a file system for online data storage. Before using S3QL, make sure to consult the
       full documentation (rather than just  the  man  pages  which  only  briefly  document  the
       available userspace commands).

       The  s3qlcp  command  duplicates  the  directory  tree  source-dir  into  dest-dir without
       physically copying the file contents.  Both source and destination  must  lie  inside  the
       same S3QL file system.

       The replication will not take any additional space. Only if one of directories is modified
       later on, the modified data will take additional storage space.

       s3qlcp can only be called by the user that mounted the file system and (if the file system
       was mounted with --allow-other or --allow-root) the root user.

       Note that:

       · After  the  replication,  both  source  and  target  directory  will still be completely
         ordinary directories. You can regard <src> as a snapshot  of  <target>  or  vice  versa.
         However,  the  most  common  usage  of  s3qlcp is to regularly duplicate the same source
         directory,  say  documents,  to  different  target  directories.  For  a  e.g.   monthly
         replication,   the   target   directories   would  typically  be  named  something  like
         documents_January for the replication in January, documents_February for the replication
         in  February  etc.   In  this  case  it  is  clear that the target directories should be
         regarded as snapshots of the source directory.

       · Exactly the same effect could be achieved by  an  ordinary  copy  program  like  cp  -a.
         However,  this  procedure  would be orders of magnitude slower, because cp would have to
         read every file completely (so that S3QL had to fetch all the data over the network from
         the backend) before writing them into the destination folder.

   Snapshotting vs Hardlinking
       Snapshot  support  in  S3QL  is  inspired  by  the  hardlinking feature that is offered by
       programs like rsync or storeBackup.  These programs  can  create  a  hardlink  instead  of
       copying a file if an identical file already exists in the backup. However, using hardlinks
       has two large disadvantages:

       · backups and restores always have to be made with a special program that  takes  care  of
         the  hardlinking.  The  backup  must not be touched by any other programs (they may make
         changes that inadvertently affect other hardlinked files)

       · special care needs to be taken to handle files which are already hardlinked (the restore
         program needs to know that the hardlink was not just introduced by the backup program to
         safe space)

       S3QL snapshots do not have these problems, and they can be used with any backup program.

OPTIONS

       The s3qlcp command accepts the following options:

          --log <target>
                 Destination for log messages. Specify none for standard output or syslog for the
                 system  logging  daemon.  Anything  else will be interpreted as a file name. Log
                 files will be rotated when they reach 1 MiB, and at most 5 old log files will be
                 kept. Default: None

          --debug-modules <modules>
                 Activate  debugging  output  from  specified  modules  (use  commas  to separate
                 multiple modules). Debug messages will be written to the target specified by the
                 --log option.

          --debug
                 Activate  debugging output from all S3QL modules. Debug messages will be written
                 to the target specified by the --log option.

          --quiet
                 be really quiet

          --version
                 just print program version and exit

EXIT CODES

       s3qlcp may terminate with the following exit codes:

       0      Everything went well.

       1      An unexpected error occured. This may indicate a bug in the program.

       2      Invalid command line argument or configuration file key.

SEE ALSO

       The S3QL homepage is at https://github.com/s3ql/s3ql/.

       The full S3QL documentation should also be installed  somewhere  on  your  system,  common
       locations are /usr/share/doc/s3ql or /usr/local/doc/s3ql.

COPYRIGHT

       © 2008 Nikolaus Rath <Nikolaus@rath.org>