1.1 --- a/cdbackup.1	Sat Dec 29 15:22:44 2007 +0100
     1.2 +++ b/cdbackup.1	Sat Dec 29 15:23:49 2007 +0100
     1.3 @@ -1,22 +1,22 @@
     1.4 -.TH "cdbackup" "1" "0.6.2" "Stefan Hülswitt" ""
     1.5 +.TH "cdbackup" "1" "0.6.3" "Stefan Hülswitt" ""
     1.6  .SH "NAME"
     1.7  .LP 
     1.8  cdbackup \- Streaming backup to CD\-R(W)
     1.9  .SH "SYNOPSIS"
    1.10  .LP 
    1.11 -cdbackup [\-mvVX] [\-d \fIdevice\fP] [\-r \fIscsi\-dev\fP] [\-s \fIspeed\fP]
    1.12 +cdbackup [\-mvDVX] [\-d \fIdevice\fP] [\-r \fIscsi\-dev\fP] [\-s \fIspeed\fP]
    1.13           [\-p \fInum\fP] [\-l \fIsize\fP] [\-a \fIlabel\fP] [\-c \fIcommand\fP]
    1.14           [\-\- \fIcdrecord\-options\fP]
    1.15  .SH "DESCRIPTION"
    1.16  .LP 
    1.17  cdbackup is a utility to make streaming backups to CD\-R(W) disks. It's designed to work with any backup tool which writes the backup to stdout (like tar/cpio/afio).
    1.18  .LP 
    1.19 -NOTE: this program REQUIRES that a recent version of cdrecord is present in the PATH.
    1.20 +\fINOTE:\fR this program REQUIRES that a recent version of \fBcdrecord\fR(1) is present in the PATH.
    1.21  .LP 
    1.22 -WARNING! When using this program under Linux, be sure not to use dump with
    1.23 -kernels in the 2.4.x series. Using dump on an ext2 filesystem has a very
    1.24 -high potential for causing filesystem corruption. As of kernel version
    1.25 -2.4.18, this has not been fixed and it may not be fixed at all.
    1.26 +\fIWARNING!\fR When using this program under Linux, be sure not to use dump on a mounted
    1.27 +filesystem. This has a high potential for creating corrupted backups. As of kernel version
    1.28 +2.4.19, this has not been fixed and it may not be fixed at all.
    1.29 +You can read Linus statement about this at <http://search.alphanet.ch/cgi\-bin/search.cgi?max_results=10&type=long&msgid=Pine.LNX.4.21.0104270953280.2067\-100000@penguin.transmeta.com&domain=ml\-linux\-kernel>
    1.30  .SH "OPTIONS"
    1.31  .LP 
    1.32  .TP 
    1.33 @@ -27,13 +27,13 @@
    1.34  
    1.35  .TP 
    1.36  \fB\-r\fR \fIscsi\-device\fP
    1.37 -The scsi device which is passed to cdrecord (via dev=\fIscsi\-device\fP). Must be given as three, comma seperated number: \fIscsibus\fR,\fItarget\fR,\fIlun\fR.
    1.38 +The scsi device which is passed to \fBcdrecord\fR(1) (via dev=\fIscsi\-device\fP). Must be given as three, comma seperated number: \fIscsibus\fR,\fItarget\fR,\fIlun\fR.
    1.39  .br 
    1.40  (default: none)
    1.41  
    1.42  .TP 
    1.43  \fB\-s\fR \fIspeed\fP
    1.44 -The writing speed which is passed to cdrecord (via speed=\fIspeed\fP).
    1.45 +The writing speed which is passed to \fBcdrecord\fR(1) (via speed=\fIspeed\fP).
    1.46  .br 
    1.47  (default: 4)
    1.48  
    1.49 @@ -45,7 +45,7 @@
    1.50  
    1.51  .TP 
    1.52  \fB\-X\fR
    1.53 -Enables the use of CDROM XA2 mode in cdrecord. By default CDROM mode 1 is used. The default is possibly causing problems during restore on certain kernel version/CDROM hardware combinations at the end of the last session on a media. Sony drives doesn't support CDROM XA 2 mode (see \fBcdrecord\fR(1) multi).
    1.54 +Enables the use of CDROM XA2 mode in \fBcdrecord\fR(1). By default CDROM mode 1 is used. The default is possibly causing problems during restore on certain kernel version/CDROM hardware combinations at the end of the last session on a media. Sony drives doesn't support CDROM XA 2 mode (see \fBcdrecord\fR(1) \-multi).
    1.55  
    1.56  .TP 
    1.57  \fB\-l\fR \fIsize\fP
    1.58 @@ -74,12 +74,16 @@
    1.59  Enables verbose mode.
    1.60  
    1.61  .TP 
    1.62 +\fB\-D\fR
    1.63 +Enables DEBUG output (probably not usefull for normal use).
    1.64 +
    1.65 +.TP 
    1.66  \fB\-V\fR
    1.67  Prints out version information and exits.
    1.68  
    1.69  .TP 
    1.70  \fB\-\-\fR \fIcdrecord\-options\fP
    1.71 -All options following \fB\-\-\fR are passed to cdrecord.
    1.72 +Pass following options to \fBcdrecord\fR(1).
    1.73  .SH "EXAMPLES"
    1.74  .LP 
    1.75  To create a tar archive of /home and
    1.76 @@ -91,6 +95,29 @@
    1.77  To create a tar archive of /usr and output it to a series (multi\-disk mode) of 650 MB CD\-R(W) on /dev/sr1 (scsi device 1,4,0) with writting speed 12 and verbose output:
    1.78  .IP 
    1.79  tar cf \- /usr | cdbackup \-d /dev/sr1 \-r 1,4,0 \-s 12 \-m \-v
    1.80 +.SH "KNOWN PROBLEMS"
    1.81 +.LP 
    1.82 +Certain combinations of CDROM drivers and kernel versions are causing a problem when restoring data. The restore process aborts with an read error close to the end of the session, while the data on the media is perfectly good.
    1.83 +.LP 
    1.84 +All CDR sessions written in track\-at\-once mode (which is unavoidable for multisessions) end in at least two unreadable runout sectors (for additional information refer to the file README.copy from the cdrecord package). As the kernel does some readahead on the device, it stumbles over these unreadable sectors before reaching the actual end of data.
    1.85 +.LP 
    1.86 +Some drivers are reporting to syslog but doesn't pass the error to the application, while others make the application fail. From user feedback, it seems that pure SCSI setups are mostly working fine, while ide\-scsi setups are likely to fail.
    1.87 +.LP  
    1.88 +The author isn't able to provide a full solution, but some hints which may help:
    1.89 +.TP 
    1.90 +1.
    1.91 +Update to a recent kernel.
    1.92 +.TP 
    1.93 +2.
    1.94 +Disable kernel readahead with option \-R when restoring.
    1.95 +.TP 
    1.96 +3.
    1.97 +Increase the padsize with option \-p. Use values >= 128.
    1.98 +.TP 
    1.99 +4.
   1.100 +Use option \-X if your writer supports this (Sony drives doesn't supports this mode).
   1.101 +.LP 
   1.102 +Please contact the author if you can contribute additional information about the problem.
   1.103  .SH "AUTHORS"
   1.104  .LP 
   1.105  Stefan Hülswitt <huels@iname.com>