NAME
	copynilfs -- backup your NILFS partition

SYNOPSIS

	copynilfs [options..] <source device> <destination device>


DESCRIPTION

The ``copynilfs'' is a prototype backup tool of NILFS partitions.  It
copies NILFS filesystem states including past data stored on disk.
This prototype utilizes the rsync command to make diff copies among
checkpoints.

This tool can be used to backup existing NILFS partitions to other
local or remote (if applying remote block devices such as iSCSI)
devices.  It's applicable to migrating data when NILFS on-disk format
changes, or to cleaning unnecessary data from the partitions.


OPTIONS SUMMARY

The following options are available:

 -f <cp-list-file> 
     Read first columns of the <cp-list-file> as selected 
     checkpoints (list of block # of segment)

 -F "<cmd> <arg1> <arg2> ..."
     Specify a filter command that selects checkpoints.
     <cmd> is called with arguments, and its standard input is piped
     from a list of checkpoint which is same as the output of
     `listcp -le <device>`.  See also FILTERS.

 -q  Quiet mode; suppress messages.

 -t <nr-blocks>
     Set threshold value of dirty data blocks.  This value affects
     granularity of segments to be written on the new device.

 -X  Do not preserve hard links.
 -h  Show help message.


The following options are available.  Parameters described here are
inherited from the source device by default.  We can change them
through the partition cloning by specifying these options.

 -b <block-size>
     Specify blocksize of the destination device.

 -B <integer>
     Specify number of blocks per segment.

 -L <label>
     Specify label of the new NILFS partition.


EXAMPLES

The following example shows how to copy NILFS on /dev/hdc1 to
/dev/hdc2.

 hack> sudo copynilfs /dev/hdc1 /dev/hdc2
 copynilfs will overwrite all existing data on /dev/hdc2.
 Do you proceed [y/N]? y
 mkfs.nilfs ver 1.0
 Start writing file system initial data to the device
 Blocksize:4096  Device:/dev/hdc2
 File system initialization succeeded !!
 Copying checkpoints:
 segblk=9
 segblk=11294
 segblk=13312
 segblk=13491
 segblk=14081
 segblk=14286
 segblk=14299
 segblk=14336
 segblk=14378
 segblk=18607
 segblk=18772
 segblk=18794
 segblk=18797
 segblk=18821
 segblk=18853
 segblk=18857
 segblk=18867
 segblk=19456
 segblk=19603
 segblk=19620
 segblk=19633
 segblk=19647
 segblk=19667
 Done.
 hack> sudo listcp -l /dev/hdc2
          1     8 Thu Mar 16 16:56:18 2006 MajorCP|LogiBegin|LogiEnd    0
          9    12 Tue Mar 14 09:48:31 2006 MajorCP|LogiBegin|LogiEnd    0
      11264 12206 Tue Mar 14 10:30:17 2006 MajorCP|LogiEnd    0
      13312  1263 Tue Mar 14 10:30:23 2006 MajorCP|LogiEnd    0
      ...
      19546    15 Wed Mar 15 16:34:02 2006 MajorCP|LogiBegin|LogiEnd   40
      19561    14 Wed Mar 15 16:39:47 2006 MajorCP|LogiBegin|LogiEnd   32
      19575    18 Thu Mar 16 09:40:37 2006 MajorCP|LogiBegin|LogiEnd   56
      19593    20 Thu Mar 16 16:34:02 2006 MajorCP|LogiBegin|LogiEnd   40


The following example only copies representatives (i.e. the last
checkpoint in each cluster) among neighboring checkpoints.

 hack> sudo listcp -l /dev/loop0
          1     8 Tue Mar 14 21:57:03 2006 MajorCP|LogiBegin|LogiEnd    0
          9     4 Tue Mar 14 21:57:32 2006 MajorCP|LogiBegin|LogiEnd    0
         13    10 Tue Mar 14 21:57:39 2006 MajorCP|LogiBegin|LogiEnd    0
      11264 11673 Tue Mar 14 22:03:47 2006 MajorCP|LogiEnd  143
      11697   255 Tue Mar 14 22:04:07 2006 MajorCP|LogiBegin|LogiEnd    0
      13312  1629 Tue Mar 14 22:04:15 2006 MajorCP|LogiEnd    0
      13581     3 Tue Mar 14 22:21:38 2006 MajorCP|LogiBegin|LogiEnd    0
      13584   462 Tue Mar 14 23:14:50 2006 MajorCP|LogiBegin|LogiEnd   30
      15360  1748 Tue Mar 14 23:37:37 2006 MajorCP|LogiEnd    0
      70656 55297 Tue Mar 14 23:38:08 2006 MajorCP|LogiEnd    0
      99328 28274 Tue Mar 14 23:38:29 2006 MajorCP|LogiEnd    0
      99365    12 Wed Mar 15 01:33:20 2006 MajorCP|LogiBegin|LogiEnd   30
      99377    11 Wed Mar 15 19:07:27 2006 MajorCP|LogiBegin|LogiEnd    0
      99388     9 Wed Mar 15 19:07:37 2006 MajorCP|LogiBegin|LogiEnd    0
      99397     9 Wed Mar 15 19:08:41 2006 MajorCP|LogiBegin|LogiEnd    0
      99406   388 Fri Mar 17 10:44:14 2006 MajorCP|LogiBegin|LogiEnd   30
      99794    20 Fri Mar 17 12:43:52 2006 MajorCP|LogiBegin|LogiEnd   30
      99814   138 Fri Mar 17 14:47:43 2006 MajorCP|LogiBegin|LogiEnd   30
      99952     5 Fri Mar 17 14:47:43 2006 MajorCP|LogiBegin|LogiEnd    0
 hack> sudo copynilfs -F landmark /dev/loop0 /dev/loop1
 copynilfs will overwrite all existing data on /dev/loop1.
 Do you proceed [y/N]? y
 mkfs.nilfs ver 1.0
 Start writing file system initial data to the device
 Blocksize:4096  Device:/dev/loop1
 File system initialization succeeded !!
 Copying checkpoints:
 segblk=13581
 segblk=13584
 segblk=99328
 segblk=99365
 segblk=99397
 segblk=99406
 segblk=99794
 segblk=99952
 Done.


Options of filters can be specified as follows.
In this example, sketch data on dropped checkpoints are aggregated to
successive checkpoints.

 hack> sudo copynilfs -F "landmark -c" /dev/loop0 /dev/loop1
 copynilfs will overwrite all existing data on /dev/loop1.
 Do you proceed [y/N]? y
 mkfs.nilfs ver 1.0
 Start writing file system initial data to the device
 Blocksize:4096  Device:/dev/loop1
 File system initialization succeeded !!
 Copying checkpoints:
 segblk=13581
 segblk=13584
 ...
 Done.


FILTERS

At present two filters are available:

 sketch

     Select checkpoints having sketch data


 landmark [-i <cluster interval>|-S <max span>|-c|-s]...

     Separate checkpoints into clusters and select last checkpoints as
     representatives from each cluster.
     The CP-clusters are separated by an interval more than <cluster
     interval>, and their spans are limited by <max span>. 
     By default, <cluster interval> and <max span> are set to 20
     minutes and 1 hour respectively.

     Relating to sketch data, two further options are available.  The
     -c option concatenates sketch data between selected checkpoints.
     The -s option substitutes the latest valid sketch data if the
     selected checkpoint has no sketch data.


LIMITATIONS

 * Creation time of in-between partial segments not having the
   checkpoint, are not inherited.  Their timestamps are altered by
   those of the subsequent segment that has a checkpoint and closes
   the logical segments they are belonging to.

 * Sparse files are expanded.  That may increase disk usage
   significantly on the destination device.

 * The following volume information is not taken over from the source
   to the destination.

   - Revision levels (both major and minor)
   - Volume uuid
   - Mount counts
   - Parameters such as timeout value or threshold value
   - Write time
   - Mount time
   - State flags
   - Time of last check
   - Check interval
   - Default uid/gid for reserved blocks
   - Maximal mount count
   - And so on

---
copynilfs.txt,v 1.8 2006/07/14 11:52:29 amagai Exp
