<!doctype linuxdoc system>

<article>
<title>The PartImage Handbook
<author>François Dupoux <tt><htmlurl url="mailto:fdupoux@partimage.org" name = "fdupoux@partimage.org"></tt>
<date>$Revision: 1.19 $ for version 0.6.2, Dec 12th, 2001 
<abstract>
This Handbook describes PartImage Version 0.6.2.
</abstract>

<toc> 

<sect>Introduction
 
<p>
<figure>
<eps FILE="screenshot-004.eps">
<img SRC="screenshot-004.png">
</figure>

<p>
<sect1>What is new in documentation?
<p>
Revision 1.5: License is now Gnu FDL
<p>
Revision 1.6: Minor changes
<p>
Revision 1.7: Partimaged port changed from 13000 to 4025, assigned by IANA
<p>
Revision 1.8: A new section about Usage / Apple iMac
<p>
Revision 1.11: A new section about Usage / Backup, update and add images
<p>
Revision 1.12: New section in FAQ: Does partimage take ACL into account?
<p>
Revision 1.13: New section in FAQ: What does partimage give you over the following DD...?
<p>
Revision 1.14: Updates from Nick Veitch
<p>
Revision 1.15: Minor updates
<p>
Revision 1.16: Fixed openssl command line
<p>
Revision 1.17: Updates version to 0.6.1
<p>
Revision 1.18: Minor updates, update to 0.6.2
<p>
Revision 1.19: Extracted FAQ section into new file: faq.sgml
<p>
<p>
<sect1>What is it?
<p>
- Partition Image is a Linux/UNIX partition imaging utility: it saves partitions formatted using the <bf>Ext2FS</bf>
(the linux standard), <bf>ReiserFS</bf> (a new journaled and powerful file system), <bf>JFS</bf> IBM journaled file systems from AIX, <bf>NTFS</bf> (Windows NT File System),
<bf>FAT16/32</bf> (DOS & Windows file systems), or HPFS (OS/2 file system) file system formats to an image file. Only used blocks are copied.
The image file can be compressed in the <bf>GZIP/BZIP2</bf> formats to save disk space, and split into multiple
files to be copied on removable media (ZIP for example), or burned on a CD-R ...


- This allows the user to save a full Linux/Windows system, with a single operation. When problems occur (viruses, crash, error, ...),
you just have to restore, and after several minutes, all your system is restored (boot, files, ...),
and fully working.


- This is very useful when installing the same software on many machines: just install one of them, create
an image, and then restore the image on all other machines. After the first one, each  subsequent installation
can be made automaticaly, and only requires a few minutes.

<p>
<sect1>Changes
<p>

<itemize>
<item>0.6.1: (2001-11-21)
	<itemize>
		<item>LS120 support
		<item>BeFS detection
		<item>Bug fixes in FAT and NTFS support
	</itemize>
<item>0.6.0: (2001-xx-yy)
	<itemize>
		<item>Network support with SSL encryption: there are two versions (server and clients).
	  	      For example, you can save the image of a computer on the disk of another computer.
	        <item>The multi-thread copy: it increases the speed of the copy.
	        <item>Copy optimisations: several blocks are copied in a single operation. This dramatically increases the speed of the copy.
	        <item>The batch mode, which allows for unattended operation (no questions, no forms, no message boxes)
	        <item>Many new other options (For example, partimage can exit automatically on finish)
	        <item>New debug log file: it will make debugging easier
	        <item>Support of ReiserFS-3.6 (provided with kernel-2.4) New image file format to have a better error detection, a new source code kernel, to save the MBR
	        <item>The MBR is saved, and can be restored (it contains the boot loader and the partition table)
		<item>IBM JFS support added (still experimental)
		<item>partimaged official port is 4025
	</itemize>
<item>0.3.5.3:(2001-04-02) New translations
<item>0.3.5.2:(2001-03-09) ReiserFS-3.6 support
<item>0.3.5.1:(2001-02-01) Bug fixes, to avoid a segfault
<item>0.3.5:(2000-10-09) Bug fixes, HPFS file system support
<item>0.3.4:(2000-10-01) Bug fixes, Italian translation, debian files for packaging
<item>0.3.3: (2000-09-20) Bug fixes, New option: "Halt/Shutdown on finish", Documentation (in english, SGML to HTML), French translation
<item>0.3.2: (2000-09-12) Bug fixes (NTFS support, Splitting), new debug system to make debug easy.
<item>0.3.1: (2000-09-06) Bug fixes, compression level auto-detection at restore, beginning of the NTFS support
<item>0.3.0: (2000-08-27) New semi-graphical interface (based on newt) which can be run under a console, bug fixes
<item>0.2.4: (2000-08-21) Support of the ReiserFS file system, file system auto-detection
<item>0.2.3: (2000-08-15) Bug fixes, removed the 2 GB partition size limitation
<item>0.2.2: (2000-07-25) FAT16 and FAT32 support, bug fixes, 2 GB limit check, e2fsck check before saving, new options
<item>0.2.1: (2000-06-04) Split image support, bug fixes, size check, new options
<item>0.2.0: (2000-05-29) First version
</itemize>

<sect>Installation
<p>
<sect1>How to obtain PartImage 
<p>

To obtain the last version of Partition Image, you can surf to the project
home-page: <url url="http://www.partimage.org/">.
You can download the sources in tar.bz2 format, or in binary.
<p>

<sect1>Requirements
<p>
Many libraries are required to compile/run Partition Image:

<itemize>
<item><bf>libz</bf> gzip compression support
<item><bf>libbz2</bf> bzip2 compression support
<item><bf>liblzo</bf> lzo compression support
<item><bf>libnewt</bf> GUI (Graphical User Interface)
<item><bf>libslang</bf> Required for newt
<item><bf>libssl</bf> OpenSSL: encryption of data over the network
<item><bf>libcrypt</bf> support for password
</itemize>

You can go on the download section of the home-page of Partition Image to find more details about these libraries: where to download them, and how to compile them.

Warning: If you want to compile partimage as a shared program, you need to have all the shared version of these libraries installed on your system. 
If you want to compile partimage as a static program, you need to have all the static version of these libraries installed on your system. 

<sect1>Compilation and installation

<sect2>Different versions of Partition Image
<p>
There are 3 versions of Partition Image you can use:
<itemize>
<item><bf>The source code</bf> you have to compile it, and it may be difficult, because it require many libraries
<item><bf>The static binary</bf> this is very easy to use: this is an i386 executable binary, you just have to run it.
<item><bf>The boot/root disks</bf> if you don't have an installed linux system, or if you want to work on your root linux partition
<item><bf>The bootable eltorito cdrom</bf> you can run partimage from a bootable cdrom, where the image files are burned
</itemize>

All these versions can be downloaded from the web site. Here, we will explain how to compile the source code:

<sect2>Compiling Partition Image sources
<p>
In order to compile and install PartImage on your system, type the following in
the base directory of the PartImage distribution:

<tscreen><verb>
% ./configure
% make
% make install
</verb></tscreen>

After this, if you enabled SSL, you can install the needed certificate with

<tscreen><verb>
% make certificates
</verb></tscreen>

Since PartImage uses <bf>autoconf</bf> you should have not trouble
compiling it.
Should you run into problems please report them to the the author at 
<htmlurl url="mailto:fdupoux@partimage.org" name = "François Dupoux">


<p>
<sect> Usage
<p>
There are two ways to use Partition Image:
<itemize>
<item><bf>The command line</bf> You must type a command. For example: partimage -od -f1 -z1 save /dev/hda12 /mnt/backup/hda12.partimg.gz
<item><bf>The GUI (Graphical User Interface)</bf> This is an easy way: you just have to fill in the boxes in the GUI window.
</itemize>

You can obtain the list of all commands, by typing <bf>partimage --help</bf>, so they won't be explained here.

<figure>
<eps FILE="screenshot-001.eps">
<img SRC="screenshot-001.png">
</figure>

<sect1> How to save a partition into an image file
<p>
<figure>
<eps FILE="screenshot-003.eps">
<img SRC="screenshot-003.png">
</figure>

When saving a partition, you must specify two important things. First, the partition you want to save. You must give
the Linux <bf>name of the partition</bf>, then a file of the /dev/ directory. For example, if the partition to save is the first
of your first IDE hard disk, it might be /dev/hda1. The second important thing is the file where to save this partition.
This file is called the <bf>image file</bf>. To see what partitions your have on your hard disk, you can run <bf>fdisk</bf>
or, you can type <bf>cat /proc/partitions</bf>. Then, you will have to type this information on the first window
of Partition Image. In the screenshot, we are saving the <bf>/dev/hda12</bf> partition to <bf>redhat-6.2.partimg.gz.</bf>
The extension of the image file should fit with the compression mode which will be used (.gz for gzip, and .bz2 for bzip2).
When ready, click on <bf>Next ></bf>

On the next window, you can choose many options. The most important one is the compression level. The size of your image, and
the time which will be used to save the image depend on the compression level you use.
The split options allow you to split the image file into several small files. It can be useful to save your partition into
removable media, such ZIP drives. For example, you can split into files of 95 MB to fit on multiple Zip disks.

When all options are set, you can click on the <bf>save</bf> button to run the operation.


<sect1> How to restore a partition from an image file
<p>
<figure>
<eps FILE="screenshot-006.eps">
<img SRC="screenshot-006.png">
</figure>

Restoring data will copy the data which were saved into an image file, into a partition. <bf>Data already on the partition you are restoring
to will be lost!</bf> The partition to restore data to must already exist before you proceed. If it doesn't exist, you must
create it before with a tool, such as fdisk, GNU parted, or other tools. You won't be able to restore information if it won't fit in the new
partition, so make sure you create one with enough space.

Restoring an image into a partition is an easy operation. You must specify the image file to use (it will only be read),
and the partition to restore (it will be overwritten).
The only extra option you can choose is <bf>Erase free blocks with zero values</bf>. If this option is enabled, all blocks which
are not used are erased with zero bytes. This may be useful if you want to be sure that the data which were on the partition before this operation are fully erased.
If this option is disabled, old data which was on currently unused blocks can be accessed (with some difficulty), because nothing is written on these blocks. These old data can be read
with tools such as dd (GNU convert and copy).

When all options are set, you can click on the <bf>restore</bf> button to run the operation.

The partition to restore must have the same size as the saved partition. If the partition is smaller than the
original one, the operation will fail. If it is bigger, space can be lost. You can read the FAQ of this handbook,
for more details about this.

<sect1> What compression level to use ?
<p>
When you save a partition into an image file, you can choose one of four compression levels:
<itemize>
<item><bf>none</bf> There is no compression
<item><bf>gzip</bf> Image will be compressed with gzip (default)
<item><bf>bzip2</bf> Image will be compressed with bzip2
<item><bf>lzo</bf> Image will be compressed with lzo
</itemize>

With <bf>No compression</bf> you will have a very big image file, which will have the same size of the used data
of your saved partition. This is really interesting only if you have a lot of space. But this is very fast, and useful if you
are dealing with small images (your /boot partition perhaps)

<p>
With <bf>Gzip compression</bf> you will have a small image file. This is the most useful mode, and the default setting.
This operation takes more time due to the compression, but it creates a much smaller file.

<p>
With <bf>Bzip2 compression</bf> you will have a very small image file: Bzip2 has a better compression ratio than gzip
on big files (though in some rare cases, it can actually create a bigger archive files). This will be very very slow to compress. This
option is useful only if you really can't waste any space, or if you have a lot of time (you can run it before going to bed).

<p>
With <bf>Lzo compression</bf> this is a very fast compression algorithm. It's a lot faster than gzip, but a little
less efficient. Choose this option if you have enough space to save a big image, and you want to save time.
This compression level is available for version 0.7.0 of partimage and later.

<p>
You can compress and uncompress image files, after creation. For example, if the image <bf>redhat-6.2.partimg.gz</bf>
was made with the gzip compression level, you can type <bf>gzip -d redhat-6.2.partimg.gz</bf> to uncompress the image
file. You can also compress an image which was not compressed. For example, you can type <bf>bzip2 debian-2.2.partimg</bf>.
This may be usful if you wish to experiment with other compression utilities. Partition Image will be able to read uncompressed files,
or those created using a supported compression routine even though the software itself was not used for the compression.

<sect1> The splitting option
<p>

Image files created by Partition Image are very big, and can reach a size of several Gigabytes sometimes.
This can be inconvenient if you want to copy the files onto removeable Media, or burn CD-R discs from them for storage.

Splitting is an option to use when creating an image. It makes it possible to create a number of smaller files containing the partition image rather than one large one.
Two splitting modes are available<itemize>
<item><bf>Automatic: when no space left</bf> A new volume will be created when there is no space left on the currently
selected device. Then you will be asked for a new location to save the next part of the image.
<item><bf>Into files of a fixed size</bf> Several files of this size will be created instead of one big file.
</itemize>

<p>
You can use the <bf>fixed size</bf> mode if you want to copy your files onto removable media, or CD-R. For example,
to burn your image onto CD, you might want to split it into files of 600 MB. Then, you can specify a fixed size to use, in
Kilobytes (in this example, it would be 614400 KB).


You can choose the <bf>automatic</bf> mode if you are not sure if there is enough space on a device for the destination
image file. Then, if you run out of space, you will be asked for a new location, and the next part of the image will be written in this new
location. This can be useful if you directly create your partition into a removable media.

<sect1> The network support
<p>

Since  version 0.5/0.6, Partition Image provides network support: it allows you to save the image from one computer (the client) onto another computer (the server)over a standard network.
You can also restore a partition to a computer (the client) from the image stored on another computer (the server). This method provides SSL encryption support
if the partition you save/restore contains data which needs to be kept secure. The server can work with several clients connected at the same time.

The network support is very useful in several cases:
<itemize>
<item>If there is only one partition on the computer whose disk is to be backed up. In this case ther is no spare artition to save the image to.
<item>If you don't have enough space to save the image file on the same computer.
<item>To increase the security: if the image file is stored on another computer, a disk crash or a virus on the client cannot damage the image file.
<item>It you have the same image file for several computers, which have the same partitions and the same software installed.
</itemize>

<p>
If the shared version of OpenSSL is installed on your computer (it must have been compiled with <bf>./config --prefix=/usr -shared</bf>), then the SSL encryption is enabled
by default.

There are two versions of partition image to use, and two kinds of computers: All the computers used in network operations must have a valid network
configuration. You can use <bf>netcfg</bf> to do it.

<sect2>The server
<p>

<figure>
<eps FILE="screenshot-002.eps">
<img SRC="screenshot-002.png">
</figure>

The server is the computer which contains the image files. No partition is directly saved/restored on this computer.

First, you have to add a user <bf>partimag</bf> because the server will lose root capabilities as soon as possible (for security)
and will continue to run under uid partimag. Don't make partimaged SUID, run it as root.
Make a note of the IP address of the server, as you will need this for configuring the clients. If you are unsure of the address,
you can run <bf>ifconfig </bf>. usually you will find the IP details listed under eth0. If you have several ethernet connections, you may have to check what the
address is on the network you will be using.
<bf>Note:</bf> If you are using DHCP on your network, you cannot rely on the fact that the server will always have the same IP address. In these cases it is better to assign a static IP address to the server.

By default the server software uses a login as a security measure to avoid giving read/write access to the image files to any user. This check can be disabled at compilation time, by typing
<bf>./configure --disable-login</bf>, if the security is not important.
The first time you use partimaged, you will have to create accounts to allow clients to connect to the server.
You must create a file which contains the list of the users which will be allowed to connect.
This file is stored as <bf>/usr/etc/partimaged/partimagedusers</bf> by default.
And its access mode must be 600, this file must belong to user 'partimag'.
For example, if you want to allow linus to use the server, type:
<bf> mkdir /usr/etc/partimaged && echo linus > /usr/etc/partimaged/partimagedusers && chmod 600 /usr/etc/partimaged/partimagedusers.</bf>
The users added to this file must be existing users of the system (it must have an entry in /etc/passwd).
When logging in, the passord must match the password of the user in the system.
For the moment, only DES or MD5 passwords are supported, but it's now a standard.

Then run the partimage server version, by typing <bf>partimaged</bf>.
If you want to change some settings, the best option is to specify these on the command line: Type
<bf>partimaged --help</bf> for more information on these.
The most important option is <bf>-p port</bf> which allows you to choose the port which will be used by the server.
4025 is the default port number. If you change this value, make a note of it so you can configure the clients accordingly.
For ease of use, you should run partimaged from the directory where the image files are to be saved - then
this will be the current directory when no path is chosen by the client. If you intend setting up a permanent server, it may be useful to setup a startup script to initialise the server automatically.
The server is now ready to accept up to 10 client connections.

<sect3>SSL mode
<p>
Using SSL requires a certificate and a key file. Both files will be generated using "make certificates" when installing from sources. See FAQ if you don't have sources or you want to change certificate or key.

<sect3>chroot environnement
<p>
To improve security, you can run the server in chroot jail. Refer to FAQ for more details.

<sect2>The client
<p>
The client is the computer which contains the partition to be saved. The standard version of Partition Image will be used: don't use <bf>partimaged</bf> here.
The first thing to do is to give partimage the IP address of the server. You can do it by using the <bf>-sIP</bf> option in the command line. Use <bf>-s192.168.10.2</bf> for
example. The second way is to check the network box, and to type the IP in the main window.

You can change the port to use with the <bf>-pPORT</bf> switch. Use <bf>-p4001</bf> for example to use the port 4001. The default value is 4205.

All the other steps are the same as when there is no network. Then, the only important thing to change when you use the network is the IP address of the server. All the other
steps are the same.

<p>
<sect1> Using PartitionImage with Apple iMac
<p>
Thanks goes to Steffen Schwenke for all in this section.
<p>

Download the ISO <htmlurl url="http://prdownloads.sourceforge.net/partimage/partimage-0.6.0rc3-PPC-bootcd-1.img.bz2" name="partimage-0.6.0rc3-PPC-bootcd-1.img.bz2"> 
and refer to next section to know howto to build the bootable cdrom. This is a bzippped ISO image, not a bootcd image. Type <bf>bzip2 -d *img.bz2</bf> to decompress this image.

Insert cdrom and bootup your iMac and then

<itemize>
  <item>press C on startup
  <item>at the yaboot prompt type in -> cd
  <item>pray that /dev/ram3 mounts ;)
  <item>login as root (no passwd)
  <item>start partimage
</itemize>

<bf>Note:</bf> the cdrom has to be on primary ide controller as slave (/dev/hdb)
like on most iMac's.
an nfs server is mounted automatically if you change the fstab
on the ramimage

<p>
<sect1> Making a backup of the partition table

<sect2> Introduction to partitions
<p>
Even if you have only one volume, your hard disk is divided into partitions. <bf>The standard MSDOS voulme label allows to have up to 4 primary partitions.</bf>
The partition table is stored in the MBR (Master Boot Record). This area is the first 512 bytes of the physical hard drive.
It also contain some code which will start the operating system, which can be the bootloader (LILO, grub, ...). If your hard disk is hda, parimary partitions are hda1, hda2, hda3 and hda4.
It's easy to save to primary partitions table, by copying the MBR.

<bf>To get past this limitation of 4 primary partitions, you can create an extended partition.</bf> An extended partition is a primary partition which contains
a lot of partitions. For example, if hda2 is an extended partition, its logicial partitions will lappear as hda5, hda6, hda7, ... even if you don't use 4 primary
partitions. That's why you can have an hda5 device, with no hda4. The problem with extended partition is there is no table we can easily save. The extended partition
contains a linked list. hda5 will point to hda6, hda6 will point to hda7 and so on. This makes it difficult to save the partition table of the extended partition.

Partimage can save the data of one partition, but <bf>it won't save your partition table</bf>.
If you have a major problem with your hard drive, you may have to restore both the partition table and the data - having the images of the partitions won't be
a lot of help on there own. Which is why we'll show you how to save the partition image now.

<sect2> Making a backup of the partition entries
<p>
We will save all the partitions entries (both primary and logicial ones which appear in the extended partition).
In this example, we'll be assuming that hda (the first IDE hard disk) is to be backed up.

First, we will save the MBR with DD (GNU convert and copy)
<itemize>
  <item>cd /root
  <item>mkdir partition-backup
  <item>cd partition-backup
  <item><bf>dd if=/dev/hda of=backup-hda.mbr count=1 bs=512</bf>
</itemize>

It will produce a very small, but very important file: 512 bytes of data.
Now, we will save entries of the extended partitions:
<itemize>
  <item><bf>sfdisk -d /dev/hda > backup-hda.sf</bf>
</itemize>

sfdisk is a tool provided with the <htmlurl url="http://www.kernel.org/pub/linux/utils/util-linux/" name="util-linux"> package.

<bf>IMPORTANT!</bf> You should now put these files somewhere safe - copy them to a floppy disk (and take a copy of it!), or burn them onto a CD. Keep these files safe. Do not leave them on your hard drive - if there is a problem with th drive, you may not be able to access these files,
 and while your partition images won't be wortheless, it will certainly be a lot harder to restore your data.

<sect2> Restoring partition entries from the backup
<p>
Be careful, restoring is a dangerous action - it can destroy data! First, we will restore the Master Boot Record:
<itemize>
  <item><bf>dd if=backup-hda.mbr of=/dev/hda</bf>
</itemize>

Then, here is how to restore extended partitions entries:
<itemize>
  <item><bf>sfdisk /dev/hda < backup-hda.sf</bf>
</itemize>

To finish, you will have to reboot your computer.

<sect>The BOOT/ROOT disks  and  Eltorito bootable CD-Rom
<p>
Two disks are provided to allow using partition image from floppy disks. The boot disk was created from a recent kernel. This
kernel include the support of many file systems, as ext2fs, vfat, ntfs, and reiserfs.
It allows you to save/read image files on many file systems.
The kernel also includes many drivers,such as those for the parallel ZIP drive, various SCSI interfaces and so on, to allow the use of many
types of media to read/write the image files.
The root disk was created from a slackware root disk.
There is very little space on the disk, so some common commands may be missing, but there are anough for the normal operations of Partition Image.
We have tried to remove debug data from executable binary files with objcopy, and we
compressed the root disk with gzip -9, but all the libraries and commands require too much disk space.If you require particular modules not included on the disk, you can
compile you own modules and swap them for some of the disk that you don't need. To do this though, you will need to compile from the same kernel source. Check the disk to ensure you use the correct version code.See the FAQ for this and other options.

Since the 0.3.5 version, an eltorito CD-ROM, created from the slackware 7.0 one, is provided.
It allows you to run Partition Image from a CD-ROM, without any installed linux system.
This is useful for systems which don't run Linux, or when your only drive is the one which needs to be restored. Providing the image file is small enough,
it is even possible to include these on the same CD, making restoring very easy.

<sect1>Why these disks ?
<p>
You may need these two floppies to use Partition Image in some cases:
<itemize>
<item>You want partition image to work on your only linux root partition and then you cannot run partition image from the system which uses this partition to work.
<item>You don't have any linux system installed on your computer and you want to run partition image
<item>You don't want to compile Partition Image
</itemize>

<sect1>How to create these disks ?
<p>
When you have downloaded the two files (boot disk image and root disk image), you will use them to create the floppies disks. You need two 1,44 MB floppies.

<bf>Under Linux:</bf>
<itemize>
<item>insert the boot disk
<item>type: dd if=partimage-x.y.z-bootdisk-w.raw of=/dev/fd0
<item>insert the root disk
<item>type: dd if=partimage-x.y.z-rootdisk-w.raw of=/dev/fd0
</itemize>

<p>
<bf>Under DOS/Windows:</bf>
You need to download RAWRITE.EXE, which wan be found on Partition Image home page.(14 KB)

<itemize>
<item>insert the boot disk
<item>type: rawrite -f partimage-x.y.z-bootdisk-w.raw -d a:
<item>insert the root disk
<item>type: rawrite -f partimage-x.y.z-rootdisk-w.raw -d a:
</itemize>

<sect1>How to use these disks ?
<p>
First, you must insert the boot disk, and power on your computer. Wait a few minutes. When you see the message
"VFS: Insert root floppy disk to be loaded into RAM disk and press ENTER", insert the root disk and press enter.
Instructions will explain you what to do to continue.

<sect1>How to create an eltorito bootable CD-Rom ?
<p>

This section will help you to create a bootable CD-Rom, from the image file
provided on partimage web site.
Then, you just have to start your computer on this CD-Rom to able to run
Partition Image, and to save/restore partitions. You won't need to have a
linux system installed on your computer, or to use floppy disks to use partimage.

You will need to download the file partimage-x.y.z-bootcd-w.img first.
(2.88 MB)

1) Create your main burning directory: for example "CDBurning".

2) Go in your main burning directory, and create a sub-directory named
   ".eltorito", and copy the 2.88 MB image file in this directory.

3) Copy all the other files in the main "CDBurning" directory. For example,
   your can copy all your image files. You can put 650 MB files here.

4) Now, create the ISO image with "mkisofs"
   Go in your main burning directory, with a console.
   Type the following command:
   mkisofs -o /tmp/cd-rescue.iso -R -V "Partition Image rescue" -v -J -T -d -D
           -b .eltorito/partimage-x.y.z-bootcd-w.img -c .eltorito/eltorito.boot
	   -A "Partition Image" .

   Don't forget the final point "." and update the file name with the name of
   the current version.

   /tmp/cd-rescue.iso is the image file to create. You may need up to about 700 MB of free
   space to create this file. Then, if you don't have enough space on your root
   directory, please choose another temp path.

   mkisofs will create a 650 MB image file (or smaller if you don't have a full
   CD), it can take time it's around 15 minutes usually.

5) It's time to burn your CD. You can use "cdrecord in console mode", or
   another GUI, as gCombust. See the man pages for cdrecord for more info if you need it.

6) Your bootable CD-Rom is now ready

<p> You can also burn the bootable CD-Rom with Nero under Windows. That's very easy:
You just have to choose the image file, and select that's a 2.88 MB floppy disk.
<p>
<figure>
<eps FILE="nero-burnpi.eps">
<img SRC="nero-burnpi.png">
</figure>


<sect>Partition Image Internals

<sect1> Note about the NTFS support
<p>

<sect2> Note for users
<p>
The NTFS file system is very complex (system files are implemented as regular files).
For this reason it is not fully supported in Partition Image. It mean that you can have problems
when trying to save an NTFS partition, if your system files are very fragmented, or are not
written in standards location. Then, you will have a warning at the beginning of the operation:
<bf>The NTFS support is experimental</bf>.

But in most cases, it will work without any problem. The best thing to do is to try to save
your NTFS partition. If you have an error message, then you will have to stop. If there was
no error, you can continue. If you can save the partition, you won't have problem when trying
to restore (except if there is a bug).

<sect2> Details for developers
<p>
The only difficulty we have with adding NTFS support to Parititon Image is that the
$Bitmap system file is difficult to read. In deed, all system files as the
$MFT, $Bitmap, ... are written on the disk as regulars files. Then, to read
the bitmap, all the code need to read files need to be implemented.

$Bitmap is a file that contains a map of bits. Each cluster of the NTFS partition
can be used or free. There is a bit in the bitmap for each cluster. The bit
is 0 if the cluster is free and is 1 if the cluster is used.

Partition Image need to read the bitmap to know what clusters are used. Then,
it is possible to copy only used clusters of the partition.

With the boot sector, we can read the FILE RECORD of the $MFT. We must then
read the FILE RECORD of the $Bitmap file. But now, we only read this record
at a constant position, which may be false if the MFT was fragmented.

1) First problem: how to have the position of the File Record of the $Bitmap file ?

Then, if we have this file record, we can check the file name, and read the run
list, to know what clusters contains the bitmap data. But we have another problem:
If the $bitmap is very fragmented, the run list cannot be written in the base
file record. Then we must use the "attribute list" to have another run lists...

2) Second problem: how to read the "attribute list" to be able to read all clusters
which contains the $bitmap data...

Without the $Bitmap file, we must save all clusters, even the free ones... That's
not a good way.

3) Another problem is the compression: what to do if the $bitmap file is compressed ?

<sect1> The 2 GB file limitation
<p>
The linux 2.2 kernel does not support files larger than 2 GB, so the size of your image
must not exceed this limit. You can solve this problem using the 2.4 kernel, which doesn't
have this limitation. You can also split your image into small files (of 1,9 GB for example).
You also require a recent glibc version: 2.2 or newer.

<sect1> How are the partitions read/written
<p>
Partition Image use a low level implementation. It mean that Partition Image makes a block/cluster
copy, when saving/restoring data. It read and write physical blocks of the partition. It doesn't use
the linux kernel (file systems support) to read data. It has many advantages:

<itemize>
<item>Dumping is fast, because there is no need to seek between indexes (FAT, inode table, ...) and files contents. No seek
between blocks when a file is fragmented.
<item>It really copies all the data of the file system: files contents, boot sector, inodes, ... Absolutely no
modification can be made while saving/restoring
<item>It keeps the file locations. For example, the location of your kernel image will be kept, and LILO won't fail
after you restore your partition.
</itemize>

But with this method, all files systems support must be implemented, and it's difficult to resize the partition
when restoring. It is also impossible to extract a file from an image.

<sect1> Developers information

<sect2> 64 bits numbers
<p>Many numbers are written in 64 bits, for example file sizes, in order to
avoid future limitations of the file formats. 64 bits variables must be declared as <bf>QWORD</bf>,
this is defined as <bf>unsigned long long int</bf> in <bf>partimage.h</bf>

<sect2> reserved data for future use
<p>There is free space, reserved for future use, in the main header, and in each file header, in
order to add other informations in the future, without making archives files uncompatibles.

<sect2> variables names
<p>Variables names are written in the following format: <bf>PositionTypeName</bf>:
<P>
<itemize>
<item><bf>Position</bf>: g_ for global variables, m_ for class members, and nothing for local variables.
<item><bf>Type</bf>: b for bool, n for int, qw for QWORD, sz for a NULL terminated string in ASCII, c for a char, f for a FILE* stream, dw for DWORD, ...
<item><bf>Name</bf>: the name of the variable, with an uppercase letter at the beginning of each word
</itemize>
</P>

<p>Examples:
<P>
<itemize>
<item><bf>m_bArchiveOpened</bf>: member of KFileCoderDoc (m_), of bool type (b), name = "ArchiveOpened"
<item><bf>dwLength</bf>: local, of DWORD type (dw), name = "Length"
<item><bf>g_szArchivePath</bf>: global variable (g_), null terminated ASCII string (sz), name = "ArchivePath"
</itemize>
</P>

<p>This has a lot of advantages:
When you see a variable, you know the type (int, bool, FILE *), and you know if it's a global, local or member one.

Likewise, if two variables have the same name, if resolves the problem. For example, we have:

<tscreen><verb>
bool CImage::m_qwCRC;

QWORD CImage::get_qwCRC()
{ 
  return m_qwCRC;
}

void CImage::setState(bool bState)
{
        m_bState = bState;
}
</verb></tscreen>

instead of:

<tscreen><verb>
bool CImage::CRC;

void CImage::setState(bool state2)
{
        state = state2;
}
</verb></tscreen>

<p>












<sect>Developers informations

<sect1> Creating images of BOOT/ROOT/Eltorito

<sect2> Creating the BOOT disk
<p>
<itemize>
<item> compile a recent kernel with many harware support,
   and many file systems (as ext2, fat, reiser, ntfs)
   with make bzImage (do not use DMA by default)
<item>use rdev on the image:
   rdev bzImage /dev/fd0
   rdev -r bzImage 49152 (49152 = ask disk, and read from 0)
   rdev -R bzImage 0 (to make the root RW and allow to login)
<item>dd if=bzImage of=/dev/fd0
</itemize>

<sect2> Creating the ROOT disk
<p>
<itemize>
<item>dd if=/dev/zero of=image count=3733 bs=1k
<item>mkfs.minix image
<item>mount -o loop -t minix image /mnt/image
<item>remove debug data from binaries executables
   libraries and programs to save space:
   program: strip program
   shared library: objcopy --stripdebug library.so
<item>copy all files to /mnt/image
<item>umount /mnt/image
<item>cat image | gzip -9 > image.gz
<item>dd if=image.gz of=/dev/fd0
</itemize>

<sect2> Creating the Eltorito bootcd image
<p>
The best way is to update an existring image. The size of the file is 2.88 MB (2949120 bytes). It contains a FAT file systems.

First, mount the image: <bf>mount -o loop bootcd.img /mnt/bootcd</bf>

Then, replace the vmlinuz with a new kernel (it can be the bootdisk.raw), and replace the
initrd.img with another root (it can be rootdisk.raw).

You will need syslinux to make this image bootable. It's easier to use than LILO.

Now, umount the bootcd image with <bf>umount /mnt/bootcd</bf>

Run <bf>losetup /dev/loop0 bootcd.img</bf>, run syslinux <bf>syslinux -s bootcd.img</bf>, and detach the loop device: <bf>losetup -d /dev/loop0</bf>

<sect1> Testing the file system support of partimage
<p>
In this section, we will explian how to test the file system support of partimage. Then, it does not explains how to test all the options (compression, splitting,) but
only how to be sure the data of the file system can be saved and restored successfully, and the result will be the exact copy of the original. The goal of this test is
to know if you will obtain a valid partition after the restoration, with all your files, or if a bug will encounter the data lost.

Tests are more useful if they are made on difficult file systems. For example it's easier to encounter a bug on a fragmented file system. Thus, making tests on fragmented
partitions can give better informations to the developpers, because it can work, even when it's not the best condition of use. Likewise, making test on partitions which contains
free space is more interesting.

If you want to create a test partition, the best thing to do it to fill all the space with files, and to erase some of them after, in order to create a fragmented file system.

There are two ways to test the copy of a partition:

<sect2> a) Using two test partitions of the same size
<p>
You need to have free disk space, to save an image, and to create a new partition. We will copy an existing partition to another one, using partimage.  
We need two partitions:
<itemize>
<item><bf>The original one</bf>: it will only be read (/dev/hdc5 in our example)
<item><bf>The destination one</bf>: it will be written on restoring, and compared to the original one (/dev/hdc6 in our example)
</itemize>

<p> 
What to do:
<itemize>
<item>Download and install the last version of Partition Image: don't signal bugs which are already fixed.
<item>Create an image of an existing partition (/dev/hdc5 in our example). This is the original partition we will copy.
<item>Create an empty partition on your hard-drive, with the same size as the original one. (/dev/hdc6 in our example)
<item>Erase the new partition with <bf>dd if=/dev/zero of=/dev/xxx</bf> (/dev/hdc6 in our example)
<item>Restore the image into the new created partition. (/dev/hdc6 in our example)
<item>To test, try to use the new created partition (/dev/hdc6). Try to mount it, and to run a file system check with 
<bf>e2fsck /dev/hdc6</bf> if this is an ext2fs partition, or run scandisk under Windows if a FAT one. You can compare the 
original partition files with the files of the new one. To do it, mount the two partitions (on /mnt/part1 and /mnt/part2 for example), 
and run the following command: <bf>diff -ur /mnt/part1 /mnt/part2</bf>. If nothing is printed on the screen, there are no difference between files of the partitions. 
Then it succeed. If there is something, then there are differences. You can send a bug report (and the <bf>partimage-debug.log</bf> file) to the debug mailing list, 
by giving all the details (size of the partition, state (percent usage: empty, full), file system, details (many small files, only 5 files)).
</itemize>

<sect2> b) Using only one partition and aide
<p>
First, you will require AIDE (Advanced Intrusion Detection Environment). It's a free software.





<sect> Contributing to the project
<p>
Everybody is welcome to contribute to the PartImage project. To do it, just e-mail the author,
and tell him what you can do. Please, before making any change in the project, download the latest version:
don't make changes in an older version ! 

You needn't to be programmer to contribute. Many others tasks can be done.
You can read the TODO file for more details.


<sect1> Writing the documentation
<p>
The original documentation must be written in English, because it's the most important language. Afterwards, it will
be translated into other languages. The documentation is written in the <bf>SGML</bf> language. It's not very difficult,
and it's near the HTML. Then, you need the sgml-tools, which are provided with all linux distributions. All the documentation,
is written in an only sgml file: <bf>index.sgml</bf>, and then we generate the HTML pages with <bf>sgml2html index.sgml</bf>.
Please, don't write any HTML page directly.

<sect1> Translators (from English)
<p>
Two things need to be translated from English:
<itemize>
<item><bf>The strings of the program</bf>: what users see on their screen
<item><bf>The SGML documentation</bf>
</itemize>

If you translate the strings of a program, you will have to translate a single file: <bf>partimage.pot</bf>. This
file is made for translation, from GNU xgettext, and doesn't contain any code. If can be translated with many tools,
as kbabel, or emacs with the PO mode.

<sect1> Beta-testers

<sect2> Why ?
<p> 
Testing Partition Image is a very important work. It will allow us to correct bugs, and to make a better quality software.
Please, report all bugs you have to the debug mailing list (partimage-debug@lists.sourceforge.net). The test procedure is described in the 
developer setion: <bf>Testing the file system support of partimage</bf>

<sect1> Writing C++ code
<p>
You can help us to correct bugs, or to add new features, by writing new C++ code. You need all standards tools, as GCC, GDB, ...


<sect>Copyright

PartImage Copyright 2000, 2001, 2002 François Dupoux, fdupoux@partimage.org

<p>
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation; with no Invariant Sections, with no Front-Cover Texts, and
with no Back-Cover Texts.
<p>
A copy of the license is included in top of package. 

<p>
</article>

