###############################################################################
###############################################################################
###############################################################################
#########                                                             #########
#########             THIS DOCUMENT EXPLAINS HOW TO USE               #########
#########               RISKY PROGRAMS AND PROCEDURES                 #########
#########        THAT MAY COMPLETELY AND IRREVERSIBLY DELETE          #########
#########                ALL THE DATA ON YOUR DISKS                   #########
#########                                                             #########
#########                                                             #########
#########         THE AUTHOR DECLINES ALL RESPONSIBILITIES            #########
#########               FOR ANY DAMAGE THAT MAY DERIVE                #########
#########           FROM USING THE PROGRAMS AND PROCEDURES            #########
#########               DESCRIBED IN THIS DOCUMENT                    #########
#########                                                             #########
#########                                                             #########
#########                   IF YOU CANNOT COMPLY                      #########
#########      WITH THE TERMS AND DISCLAIMERS STATED ABOVE,           #########
#########                 PLEASE STOP READING NOW                     #########
#########    AND DO NOT TRY TO USE THE PROGRAMS AND PROCEDURES        #########
#########               EXPLAINED IN THIS DOCUMENT                    #########
#########                                                             #########
#########                                                             #########
#########                  IF YOU KEEP READING,                       #########
#########       YOU MUST UNDERSTAND AND ACCEPT ALL THE RISKS          #########
#########                   BEFORE PROCEEDING                         #########
#########                                                             #########
###############################################################################
###############################################################################
###############################################################################

This document explains how use the script 'fstransform'
to transform the contents of a Linux device - usually a disk partition -
from a filesystem type to another.

For example, a disk partition can be transformed from 'jfs' to 'ext4',
or from 'ext2' to 'xfs', or many other combinations.

Currently, the script has been tested on the following filesystems
both as source and as target:
minix, ext2, ext3, ext4, reiserfs, jfs, xfs.

Do NOT use the script with other filesystems unless you are willing to LOSE your data.

In particular, fstransform does NOT (yet) support ntfs, msdos and vfat file systems.


Common sense and experience tell that you should ALWAYS have a backup
of your valuable data.

This script is intended for those cases where such backup is either already done,
or is not feasible or unnecessary, typically because the data is not valuable.

There is ALWAYS a possibility that the script will irreversibly delete
ALL the data on the device you run it on, even if you use
a tested combination of filesystems.

All this foreword means only one thing:

      IF YOU LOSE YOUR DATA, IT IS YOUR PROBLEM.

The author declines ALL responsibilities for ANY damage that may derive
from using the programs and procedures described in this document.

No matter how unpleasant is for you to read the statements above,
they are necessary to clarify the point, and also to protect you and the author
from problems, because transforming a device from one filesystem to another
WITHOUT backup is a RISKY procedure.

If you are still reading, you MUST understand and accept all the RISKS
BEFORE actually using the procedures described here.

###############################################################################
###############################################################################
###############################################################################

Enough legalese... now let's get to the interesting part.

The script 'fstransform' does the following:

it takes a device with a filesystem on it (even if almost full)
and transforms the device to a different filesystem type,
in-place (i.e. without backup) and non-destructively
(i.e. it preserves all your data).

It works even if the filesystem is almost full
- several empyrical tests have succeeded even with a 95% full filesystem -
and even if it contains very large files, for example if some files
are larger than half the device or larger than the available space.

There are four requirements for the script to have a chance to succeed:

1) the device must have a little free space, typically at least 5%

   WARNING: transforming an almost full device to 'xfs' file-system
   can be tricky:
   * you need either slightly more free space, typically at least 10%,
   * or you must be VERY quick at suspending fstransform 
     when either the source or the target (or both) file-system is almost full
     and run 'xfs_fsr' on the source or target device (or both)
     before resuming fstransform.
     A future fstransform version may automate this operation.

2) the filesystem on the device must support SPARSE FILES, i.e. files with holes
   (see for example http://en.wikipedia.org/wiki/Sparse_file for an explanation of what they are)
   and at least one of the two system calls "ioctl(FS_IOC_FIEMAP)" or "ioctl(FIBMAP)"
   (see the file Documentation/filesystems/fiemap.txt in any recent Linux kernel
   for an explanation, or search for the same file on Internet)

3) the initial and final filesystems must be supported by the Linux kernel
   (i.e. it must be able to mount them)
   and by the tools 'mkfs' and 'fsck'
   (i.e. it must be possible to create them and check them for errors)

4) the following programs must be available:
   the two custom-made programs 'fsmove' and 'fsremap' (distributed with the script)
   and several common Linux tools:
      which, expr, id, blockdev, losetup, mount, umount,
      mkdir, rmdir, rm, mkfifo, dd, sync, fsck, mkfs 


FOREWORD:

If the original device is almost full, the tool 'fsremap'
will create a relatively small backup file ("secondary storage")
in your $HOME directory.
This secondary storage file will be at most as large as half your free RAM.

You can pass the option '-s <size>[k|M|G|T|P|E|Y|Z]' to the tool 'fsremap'
in order manually set the secondary storage size,
but please understand that using a too small secondary storage
can slow down the procedure.

To pass the same option to 'fstransform', you must execute something like
  fstransform --opts-fsremap='-s <size>' <other-options-and-arguments> 


PROCEDURE:

0) compile fsmove and fsremap.
   Running "./configure" then "make" should suffice on any recent Linux machine,
   as long as g++ is installed.
   
   You will get two executables, fsmove and fsremap.
   They will be located at
     fstransform-{version}-src/fsmove/Release/fsmove
   and
     fstransform-{version}-src/fsremap/Release/fsmap
   
   You are suggested to either run "make install" or to copy them to a simpler path.
   Below, they will be referred as {fsmove} and {fsremap}


1) mount read-write the device you want to remap to a new file-system type

   mount {device} {device-mount-point} [your-options]

   if the device is already mounted, check that it is mounted read-write
   and that no process is using it.

2) decide the target file-system type.

   For some combinations of the initial and final filesystems
   it is not necessary to use 'fstransform',
   as the same result can be obtained with much simpler - and SAFER - tools.

   For example, an 'ext2' or 'ext3' filesystem can be transformed into 'ext3' or 'ext4'
   using the program 'tune2fs'.
   
   Explaining how to use 'tune2fs' is beyond the scope of this document,
   just read its man-page or search on the Internet for one of
   "convert Linux File System ext2 to ext3" 
   "convert Linux File System ext2 to ext3" 
   "convert Linux File System ext3 to ext4" 
   
   But for most combinations, the only way is either to do a full backup + format +
   restore the data, or use 'fstransform'

3) execute the script

   fstransform {device} {target-file-system-type}

4) follow the instructions - the script will tell you what it is doing
   and both 'fsmove' and 'fsremap' also show progress percentage and estimated time left.
   
   Note that 'fsmove' and 'fsremap' approximately need the same time to run,
   so if 'fsmove' tells you that it will need 2 hours, 'fsmove' will
   likely need a similar amount of time, for a total of 4 hours.
   
   In case there are errors, you can even try to fix them instead of aborting the script
   
5) be PATIENT. Transforming a large device takes a LONG time...
   On a fairly fast disk, it takes about 1 minute per 1 gigabyte.
   It means transforming 250GB of takes about 4 hours.
   Solid state disks (SSD) can be MUCH faster.
   
   Also, you should count the _used_ disk space, not the _total_ one.

6) if something goes really wrong, check in $HOME/.fstransform
   for the log-files produced by the script: they are absolutely necessary
   if you want someone to analyze the problem
   - but in most cases you can forget about recovering your data... 


Good luck!

Massimiliano Ghilardi
<paperinik@users.sf.net>
