
PDM? What is it?
-------------------------------------

This is a small PHP script which reads a given source directory
(with its subdirectories) and then creates a set of directories
filled with the content of the source directory, arranged in
groups to fit a given capacity. It can be used to create CD sets
for backups. It also supports ISO image creation, direct CD
burning via cdrecord, automatic file index creation, and more.


Requirements
-------------------------------------

Obligatory:

 - PHP interpreter <http://php.net>. This script is developed
   with PHP 4.2.x but any 4.x would do (it will fail on 3.x
   as it uses PHP 4.x specific functions here and there).
   Core installation will do. No extra modules is required.

Optional:

 - mkisofs <http://freshmeat.net/projects/mkisofs/>
   if you want to create ISO images or burn CDs
 - cdrecord <http://freshmeat.net/projects/cdrecord>
   if you want to burn any CDs with this script
   (you need to configure your kernel first and config
   the script - see inside for details)


Configuration
-------------------------------------

Most parameters can be passed as argument when script
is invoked. But some of them (i.e. cd recording related)
have to be configured first by creating valid pdm.ini
file. Here's how to do so (I will simplify this later):

  cd ~
  mkdir .pdm
  cp PATH_TO_PDM_UNPACKED/pdm.ini.orig ~/.pdm/pdm.ini

Then use any text editor, and open the pdm.ini file,
and configure whatever you wish (pleasae note, that
the script does NOT validate these values. If you put
"abcd" as i.e. capacity you will get unexpected errors
in the script.


 General settings (PDM section):
 ----------------------------------

 media = 700

 Specify how many megabytes (MB) fits on your CDRs. 700MB
 are most widely used. Check the booklet for details.
 This can be overwriten with -media option


 ignore_file = .pdm_ignore

 This is ignore marker. Ignore marker is a file
 that tells PDM to skip the directory it resides in from
 being processed. It can be 0 bytes large (content
 just does not matter, so you can create it by calling:
    echo -n >.pdm_ignore


 ignore_subdirs = On

 If ignore_file is found PDM may also skip all subdirs
 that can be found in this directory too (this is default
 behaviour). Set it to Off, to avoid this (you'll have
 to put ignore_file in each subdir if you would like it
 to be skipped


 check_files_readability = On

 By default PDM checks if each file can be read. This
 prevents i.e. mkisofs from terminating in the middle
 of its work with error "Can't read file". However this
 option slows file processing a bit, I stronly suggest
 to keep it on for safety. If PDM is called by root,
 check_files_readability is automatically deactivated
 (as it makes no sense for might root).



 CD recording (CDRECORD section)
 -----------------------------------
 Plase note that if you don't plan to burn nor produce ISO
 images, you can ignore most of these settings. Check
 NOTEs below for more details about what to keep eye on
 mostly.


 enabled = Off

 If you want to make burning available switch this to
 "On" (w/o quotes). Make sure you got external software
 like cdrecord and mkisofs installed and available.


 device = "1,0,0"

 if you want to burn anything you need to tell on which
 device your CDR burner is. Use "cdrecord -scanbus" to
 find this out, and put the 1st column value as shown
 on above example. If you don't plan to burn, nor have
 any burner, leave it as is.


 fifo_size = 10

 FIFO queue is used when you burn on-the-fly. It's memory buffer
 used to communicate between mkisofs that creates CD structures
 and cdrecord that burns your data. If it's too small, cdrecord
 may burn faster than mkisofs is able to deliver the data (this
 mostly happens if you burn thousands of millions small files
 on-the-fly). Unless you use burn-proof device, you get
 "Buffer underrun" if this happen, and in result broken CD.
 By default, 10MB is used, which shall be fine for 99,9% of
 uses. Most probably you won't ever need to touch this.


Configuring PHP
-------------------------------------

No special configuration is needed, but please make sure you
don't have command line scripts working in Safe Mode (most
probably you have this option turned off), as it needs to
disable script timeout limits (it takes some time to process
all the data). You also should check if memory_limit in your
config file (/etc/php4/CGI/php.ini) is high enough. I don't
belive default 8MB will do for anything. If PHP aborts while
processing your files throwing memory related errors, edit
your config and increase it. I usually got 30MB (but even
that wasn't enough for 45000 file set).


Usage
-------------------------------------

Run it without arguments to get help page:

 ./cd_dump_maker.php mode src [dest]

mode - specify method of CD set creation. Available:

       "test" - is you want to see how many CDs you
                need to store you data, try this

       "move" - moves source files into destination CD
                set directory much free disk space as
                source takes.

       "copy" - copies files into destination CD set
                directory. Needs as much free disk space
                as source data takes

       "link" - creates symbolic links to source data
                in destination directory. NOTE: some
                CD burning software needs to be ordered
                to follow symlinks, otherwise you burn
                no data!

       "iso"  - acts as "link" described above, but
                additionally creates ISO image files for
                each CD created. Requires mkisofs and
                as much free disk space as source takes

       "burn" - burns CD sets on-the-fly (have to be
		          enabled first)

src  - source directory (i.e. "data/") which you are going
       to process and backup

dest - destination directory where CD sets will be created.
       If ommited, your current working directory will be
       used


How it works:
-------------------------------------

First, it scans source directory to learn its structure,
get files and subdirs. Then it toss the data to fit in
given CD_CAPACITY capacity. Then, depending on the
work mode it either copies the data, moves it or links.
Additionally it may burn it.

For "iso" and "burn" it needs to create temporary data
sets, which are produced as in "link" mode.


Examples
-------------------------------------

To check how many CDs you will need to backup STUFF directory:

 ./cd_dump_maker.php test STUFF


to burn STUFF directory (on the fly):

 ./cd_dump_maker.php burn STUFF


to create ISO images (for any reason ;-)

 ./cd_dump_maker.php iso STUFF


I want to know more about CD Burning
-------------------------------------

Bother to know more about all the CDs and CD burning topics?
Visit a great source of practical information at:

  http://www.cdrfaq.org


Bugs? Suggestions?
-------------------------------------

If you got any bug report or feature request, PLEASE, PLEASE
USE SOURCEFORGE.NET bugtracker or forum for this. DO NOT
mail me directly!


Author
-------------------------------------

 Written by Marcin Orlowski <carlos@wfmh.org.pl>
 Home page: http://freshmeat.net/projects/pdm/


--
$Id: README,v 1.5 2003/01/18 21:32:57 carl-os Exp $

