// -*- C -*- mondo.dox
// This file contains documentation definitions for stuff that just didn't fit anywhere else.
/****************************** BEGIN MAIN PAGE ****************************/
/**
* @mainpage
*
* Welcome to the Mondo Rescue API manual!
*
* Mondo Rescue is a backup/disaster recovery program and library
* intended to allow backups to be restored completely and simply
* even if the hard drive has been wiped. No data loss has been
* reported since mid-2000.
*
* If you are not a Mondo developer, don't want to become one,
* don't want to write an add-on, and don't want to know about Mondo's
* internals for some other reason, this page is not for you.
* This is not a user manual; it is a developer's manual. This is our
* internal documentation. It's intended to be complete, not easily
* comprehensible by non-programmers. You have been warned.
*
* Currently all functions except those involved in prepping hard
* drives and restoring data have been placed into a shared library
* which can be used in add-ons to Mondo (for example, a new interface
* or network transparency). Generally you'll want to call
* backup_data() or verify_data() to do the work for you, but if you
* want to do the steps yourself, that's OK too. See the modules
* called "Mid-Level Backup Functions" and "Low-Level Backup
* Functions" for details.
*
* If you want to write a facelift for mondorestore, please note that
* the restore/prep functions are not in the shared library. If you
* wish to use those, please either:-
* - copy the code or file from the mondo/mondorestore directory to
* where you want to put your add-on, or
* - pester us at (please
* subscribe first; see the Mondo "support" page for info on how) to
* add it to libmondo. This is on the TODO list but it's not a high
* priority, so if it's important please tell us. Hey, any work on
* something useful for the project is good work for us :-)
*
* There are two versions of the libmondo library. One is a generic
* version (you must link in Newt to use it, though it doesn't
* actually @e use newt) which requires a separate GUI library; the
* other is an X library rather tightly coupled to XMondo. See the
* source code in mondo/xmondo/*.cpp for more details. Currently only
* a Newt add-on GUI library is available for the "generic" library;
* if you want another please copy newt-specific.c and change the
* function bodies. (If you think your work might be useful to us,
* please email the list). To link with the generic Mondo library, add
* these flags to your link command: \n
* @code -I/usr/include/mondo -I/usr/local/include/mondo -lmondo -lmondo-newt @endcode \n
* and #include \, \, and any other
* Mondo header files you are using. A @c mondo-config script to
* generate the flags automatically may be coming; watch this space.
*
* To use the X library, compile with the flags as above but replace
* @c -lmondo @c -lmondo-net with @c -lXmondo. And read the XMondo
* source code first! Your problem may have already been solved.
*
* Mondo currently runs on i386 Linux and FreeBSD using a rather ugly
* mess of #ifdefs. Ports to other OSs may come someday, probably only
* if someone writes them.
*
* Mondo uses Mindi to create the boot disks. Mindi is rather system
* dependent; currently there are separate versions for each port (two),
* but eventually the two may be combined. The current version of Mindi
* is a shell script, but the next generation (goes live Nov. 1) is in
* Perl (and runs about 4 times faster). If you are experiencing
* bugs related to the mountlist, or anything that happens before you
* get the mondorestore Newt screen, you should look at Mindi; Mondo
* does not control the boot process.
*
* The s_bkpinfo structure (commonly referred to as "the bkpinfo") is
* the heart of Mondo. If you're new to the code, you really should read
* its documentation first. Trust us, that will help your understanding
* of the rest of it immensely. The functions in libmondo-archive.c are the
* most important; tackle those first. If you're writing an add-on, you may
* be able to get away with just those and the ones in newt-specific.c.
*
* Thank you for using Mondo Rescue, and good luck in your development!
*
* @section Glossary
* Here is a list of terms used throughout the documetation and what they mean.
* - @b afioball (or @b tarball): The @c afio archive for a particular fileset.
* Sometimes "tarball" is used, even though the archives were not made by @c
* tar. @c afio provides many benefits, including the ability to compress
* files individually so a bad block doesn't ruin the whole archive.
* - @b biggiefile (or @b bigfile): A file larger than 32MB. These are archived
* separately from the regular files; they are split into
* bkpinfo->optimal_set_size-sized chunks and compressed. The file's
* stat() information (name, modification date, mode, owner, group, etc.), as
* well as its checksum, is stored in the "zeroth" slice. This allows us to
* split large files over multiple CDs, without resorting to things like the
* "cutstream" method practiced by mkCDrec.
* - @b bkpinfo: The backup information structure (s_bkpinfo). This is
* discussed above, and also in the structure's documentation.
* - @b filelist (or @b fileset): The small "chunks" that the normal-sized
* files are divided up into. Each one is archived separately by afio, so we
* can provide a better progress meter, faster selective restore, and better
* reliability if an archive is corrupted. Filesets are usually about 8MB,
* but this is controlled by @c bkpinfo->optimal_set_size.
* - @b imagedev: A device that is backed up like a biggiefile instead of as
* individual files. Its size cannot be changed at restore-time. This is
* most useful for NTFS partitions.
* - @b isodir (When backing up to ISOs/NFS): The directory where the ISO
* images are to be stored (could be a remote NFS server).
* - @b mountlist: The list of all partitions on all hard drives. This is
* created so Mondo knows exactly how to recreate the partitions at
* restore-time.
* - @b raidlist: The list of RAID devices, along with additional information,
* in the mountlist. This is used to create /etc/raidtab.
* - @b scratchdir: The directory where the ISO image tree is created.
* This must be in a location with at least enough space for a complete
* CD.
* - @b stream: A tape device, CD stream, or "udev" (allows one to use
* stream format without an actual stream device). We give up speed and
* flexibility (no selective restores without Mondo present) in exchange
* for compatibility with some very common backup hardware.
* - @b tmpdir: The temporary directory where just-created files are kept
* while waiting to put them in the scratchdir (possibly creating a CD in
* the mean time).
*/
/***************************** END OF MAIN PAGE ****************************/
/************************** BEGIN GROUP DEFINITIONS *************************
* The group hierarchy looks something like this:
* - Backup functions - mostly libmondo-archive.c
* - backup_data()
* - Mid-level general backup functions
* - Low-level general backup functions
* - Filelist creation functions
* - Verify functions
* - verify_data()
* - Low-level verify functions - libmondo-verify.c
* - Mountlist functions
* - libmondo-mountlist.c
* - RAID functions
* - libmondo-raid.c
* - Device functions
* - libmondo-devices.c
* - Tape functions
* - libmondo-stream.c
* - Utility functions
* - String functions
* - libmondo-string.c
* - File functions
* - libmondo-files.c
* - FIFO functions
* - libmondo-fifo.c
* - libmondo-tools.c
* - GUI functions
* - newt-specific.c
* - Global variables
***************************************************************************/
/**
* @defgroup archiveGroup Backup Functions
* Functions for backing up data.
*/
/**
* @defgroup MLarchiveGroup Mid-Level Backup Functions
* @ingroup archiveGroup
* Mid-level backup functions (the ones that backup_data calls directly).
*/
/**
* @defgroup LLarchiveGroup Low-Level Backup Functions
* @ingroup archiveGroup
* Low-level backup functions (the ones that do the actual work).
*/
/**
* @defgroup verifyGroup Verification Functions
* Functions for verifying data while booted from the hard drive (as opposed
* to a "compare", which is done while booted from CD/floppy).
*/
/**
* @defgroup LLverifyGroup Low-Level Verification Functions
* @ingroup verifyGroup
* Low-level verification functions (the ones that do the actual work).
*/
/**
* @defgroup compareGroup Compare Functions
* Functions for comparing data while booted from CD/floppy (as opposed
* to a "verify", which is done while booted from the hard drive).
*/
/**
* @defgroup LLcompareGroup Low-Level Compare Functions
* Low-level compare functions (the ones that do the actual work).
* @ingroup compareGroup
*/
/**
* @defgroup restoreGroup Restoration Functions
* Functions for restoring data.
*/
/**
* @defgroup prepGroup Disk Preparation Functions
* Functions for prepping disks (partitioning, formatting, mounting, slicing, dicing, etc.)
* @ingroup restoreGroup
*/
/**
* @defgroup restoreGuiGroup GUI Restore Functions
* Functions for editing mountlists, filelists, etc.
* @ingroup restoreGroup
*/
/**
* @defgroup LLrestoreGroup Low-Level Restoration Functions
* Functions for individual restoration of filesets/biggiefiles.
* @ingroup restoreGroup
*/
/**
* @defgroup restoreUtilityGroup Restore Utility Functions
* Utility functions to help with restores.
* @ingroup restoreGroup
*/
/**
* @defgroup filelistGroup Filelist Creation Functions
* Filelist preparation/chopping/other tasks done during backup.
*/
/**
* @defgroup mountlistGroup Mountlist Functions
* Functions for loading, manipulating, and saving mountlists (but not doing
* any prep work with them).
*/
/**
* @defgroup raidGroup Software RAID Functions
* Functions for dealing with software RAID (md devices on Linux; vinum
* on FreeBSD).
*/
/**
* @defgroup deviceGroup Device Manipulation Functions
* Functions for dealing with backup devices.
*/
/**
* @defgroup streamGroup Stream Functions
* @ingroup deviceGroup
* Functions for reading from and writing to tapes and other data streams.
*/
/**
* @defgroup utilityGroup Utility Functions
* General utility functions for doing small, specific, useful tasks.
*/
/**
* @defgroup stringGroup String Functions
* @ingroup utilityGroup
* Functions for working with strings.
*/
/**
* @defgroup fileGroup File Functions
* @ingroup utilityGroup
* Functions for working with files.
*/
/**
* @defgroup fifoGroup FIFO Functions
* @ingroup utilityGroup
* Functions for dealing with the buffering of data as it is read from and
* written to tape.
*/
/**
* @defgroup guiGroup GUI Functions
* GUI functions - things like progress indicators, dialog boxes, etc.
*/
/**
* @defgroup cliGroup Command-Line Interface Functions
* Functions for parsing command lines passed to mondoarchive. Not in libmondo yet.
*/
/**
* @defgroup globalGroup Global Variables
* Mondo's global variables.
*/
/*************************** END GROUP DEFINITIONS *************************/