| 1 | // -*- C -*- mondo.dox
|
|---|
| 2 | // This file contains documentation definitions for stuff that just didn't fit anywhere else.
|
|---|
| 3 |
|
|---|
| 4 |
|
|---|
| 5 |
|
|---|
| 6 | /****************************** BEGIN MAIN PAGE ****************************/
|
|---|
| 7 | /**
|
|---|
| 8 | * @mainpage
|
|---|
| 9 | *
|
|---|
| 10 | * Welcome to the Mondo Rescue API manual!
|
|---|
| 11 | *
|
|---|
| 12 | * Mondo Rescue is a backup/disaster recovery program and library
|
|---|
| 13 | * intended to allow backups to be restored completely and simply
|
|---|
| 14 | * even if the hard drive has been wiped. No data loss has been
|
|---|
| 15 | * reported since mid-2000.
|
|---|
| 16 | *
|
|---|
| 17 | * <b>If you are not a Mondo developer, don't want to become one,
|
|---|
| 18 | * don't want to write an add-on, and don't want to know about Mondo's
|
|---|
| 19 | * internals for some other reason, <i>this page is not for you</i></b>.
|
|---|
| 20 | * This is not a user manual; it is a developer's manual. This is our
|
|---|
| 21 | * internal documentation. It's intended to be complete, not easily
|
|---|
| 22 | * comprehensible by non-programmers. You have been warned.
|
|---|
| 23 | *
|
|---|
| 24 | * Currently all functions except those involved in prepping hard
|
|---|
| 25 | * drives and restoring data have been placed into a shared library
|
|---|
| 26 | * which can be used in add-ons to Mondo (for example, a new interface
|
|---|
| 27 | * or network transparency). Generally you'll want to call
|
|---|
| 28 | * backup_data() or verify_data() to do the work for you, but if you
|
|---|
| 29 | * want to do the steps yourself, that's OK too. See the modules
|
|---|
| 30 | * called "Mid-Level Backup Functions" and "Low-Level Backup
|
|---|
| 31 | * Functions" for details.
|
|---|
| 32 | *
|
|---|
| 33 | * If you want to write a facelift for mondorestore, please note that
|
|---|
| 34 | * the restore/prep functions are not in the shared library. If you
|
|---|
| 35 | * wish to use those, please either:-
|
|---|
| 36 | * - copy the code or file from the mondo/mondorestore directory to
|
|---|
| 37 | * where you want to put your add-on, or
|
|---|
| 38 | * - pester us at <mondo-devel@lists.sourceforge.net> (please
|
|---|
| 39 | * subscribe first; see the Mondo "support" page for info on how) to
|
|---|
| 40 | * add it to libmondo. This is on the TODO list but it's not a high
|
|---|
| 41 | * priority, so if it's important please tell us. Hey, any work on
|
|---|
| 42 | * something useful for the project is good work for us :-)
|
|---|
| 43 | *
|
|---|
| 44 | * There are two versions of the libmondo library. One is a generic
|
|---|
| 45 | * version (you must link in Newt to use it, though it doesn't
|
|---|
| 46 | * actually @e use newt) which requires a separate GUI library; the
|
|---|
| 47 | * other is an X library rather tightly coupled to XMondo. See the
|
|---|
| 48 | * source code in mondo/xmondo/*.cpp for more details. Currently only
|
|---|
| 49 | * a Newt add-on GUI library is available for the "generic" library;
|
|---|
| 50 | * if you want another please copy newt-specific.c and change the
|
|---|
| 51 | * function bodies. (If you think your work might be useful to us,
|
|---|
| 52 | * please email the list). To link with the generic Mondo library, add
|
|---|
| 53 | * these flags to your link command: \n
|
|---|
| 54 | * @code -I/usr/include/mondo -I/usr/local/include/mondo -lmondo -lmondo-newt @endcode \n
|
|---|
| 55 | * and #include \<my-stuff.h\>, \<mondostructures.h\>, and any other
|
|---|
| 56 | * Mondo header files you are using. A @c mondo-config script to
|
|---|
| 57 | * generate the flags automatically may be coming; watch this space.
|
|---|
| 58 | *
|
|---|
| 59 | * To use the X library, compile with the flags as above but replace
|
|---|
| 60 | * @c -lmondo @c -lmondo-net with @c -lXmondo. And <b>read the XMondo
|
|---|
| 61 | * source code first</b>! Your problem may have already been solved.
|
|---|
| 62 | *
|
|---|
| 63 | * Mondo currently runs on i386 Linux and FreeBSD using a rather ugly
|
|---|
| 64 | * mess of #ifdefs. Ports to other OSs may come someday, probably only
|
|---|
| 65 | * if someone writes them.
|
|---|
| 66 | *
|
|---|
| 67 | * Mondo uses Mindi to create the boot disks. Mindi is rather system
|
|---|
| 68 | * dependent; currently there are separate versions for each port (two),
|
|---|
| 69 | * but eventually the two may be combined. The current version of Mindi
|
|---|
| 70 | * is a shell script, but the next generation (goes live Nov. 1) is in
|
|---|
| 71 | * Perl (and runs about 4 times faster). <b>If you are experiencing
|
|---|
| 72 | * bugs related to the mountlist, or anything that happens before you
|
|---|
| 73 | * get the mondorestore Newt screen, you should look at Mindi; Mondo
|
|---|
| 74 | * does not control the boot process</b>.
|
|---|
| 75 | *
|
|---|
| 76 | * The s_bkpinfo structure (commonly referred to as "the bkpinfo") is
|
|---|
| 77 | * the heart of Mondo. If you're new to the code, you really should read
|
|---|
| 78 | * its documentation first. Trust us, that will help your understanding
|
|---|
| 79 | * of the rest of it immensely. The functions in libmondo-archive.c are the
|
|---|
| 80 | * most important; tackle those first. If you're writing an add-on, you may
|
|---|
| 81 | * be able to get away with just those and the ones in newt-specific.c.
|
|---|
| 82 | *
|
|---|
| 83 | * Thank you for using Mondo Rescue, and good luck in your development!
|
|---|
| 84 | *
|
|---|
| 85 | * @section Glossary
|
|---|
| 86 | * Here is a list of terms used throughout the documetation and what they mean.
|
|---|
| 87 | * - @b afioball (or @b tarball): The @c afio archive for a particular fileset.
|
|---|
| 88 | * Sometimes "tarball" is used, even though the archives were not made by @c
|
|---|
| 89 | * tar. @c afio provides many benefits, including the ability to compress
|
|---|
| 90 | * files individually so a bad block doesn't ruin the whole archive.
|
|---|
| 91 | * - @b biggiefile (or @b bigfile): A file larger than 32MB. These are archived
|
|---|
| 92 | * separately from the regular files; they are split into
|
|---|
| 93 | * <tt>bkpinfo->optimal_set_size</tt>-sized chunks and compressed. The file's
|
|---|
| 94 | * stat() information (name, modification date, mode, owner, group, etc.), as
|
|---|
| 95 | * well as its checksum, is stored in the "zeroth" slice. This allows us to
|
|---|
| 96 | * split large files over multiple CDs, without resorting to things like the
|
|---|
| 97 | * "cutstream" method practiced by mkCDrec.
|
|---|
| 98 | * - @b bkpinfo: The backup information structure (s_bkpinfo). This is
|
|---|
| 99 | * discussed above, and also in the structure's documentation.
|
|---|
| 100 | * - @b filelist (or @b fileset): The small "chunks" that the normal-sized
|
|---|
| 101 | * files are divided up into. Each one is archived separately by afio, so we
|
|---|
| 102 | * can provide a better progress meter, faster selective restore, and better
|
|---|
| 103 | * reliability if an archive is corrupted. Filesets are usually about 8MB,
|
|---|
| 104 | * but this is controlled by @c bkpinfo->optimal_set_size.
|
|---|
| 105 | * - @b imagedev: A device that is backed up like a biggiefile instead of as
|
|---|
| 106 | * individual files. Its size cannot be changed at restore-time. This is
|
|---|
| 107 | * most useful for NTFS partitions.
|
|---|
| 108 | * - @b isodir (When backing up to ISOs/NFS): The directory where the ISO
|
|---|
| 109 | * images are to be stored (could be a remote NFS server).
|
|---|
| 110 | * - @b mountlist: The list of all partitions on all hard drives. This is
|
|---|
| 111 | * created so Mondo knows exactly how to recreate the partitions at
|
|---|
| 112 | * restore-time.
|
|---|
| 113 | * - @b raidlist: The list of RAID devices, along with additional information,
|
|---|
| 114 | * in the mountlist. This is used to create /etc/raidtab.
|
|---|
| 115 | * - @b scratchdir: The directory where the ISO image tree is created.
|
|---|
| 116 | * This must be in a location with at least enough space for a complete
|
|---|
| 117 | * CD.
|
|---|
| 118 | * - @b stream: A tape device, CD stream, or "udev" (allows one to use
|
|---|
| 119 | * stream format without an actual stream device). We give up speed and
|
|---|
| 120 | * flexibility (no selective restores without Mondo present) in exchange
|
|---|
| 121 | * for compatibility with some very common backup hardware.
|
|---|
| 122 | * - @b tmpdir: The temporary directory where just-created files are kept
|
|---|
| 123 | * while waiting to put them in the scratchdir (possibly creating a CD in
|
|---|
| 124 | * the mean time).
|
|---|
| 125 | */
|
|---|
| 126 | /***************************** END OF MAIN PAGE ****************************/
|
|---|
| 127 |
|
|---|
| 128 |
|
|---|
| 129 |
|
|---|
| 130 |
|
|---|
| 131 |
|
|---|
| 132 | /************************** BEGIN GROUP DEFINITIONS *************************
|
|---|
| 133 | * The group hierarchy looks something like this:
|
|---|
| 134 | * - Backup functions - mostly libmondo-archive.c
|
|---|
| 135 | * - backup_data()
|
|---|
| 136 | * - Mid-level general backup functions
|
|---|
| 137 | * - Low-level general backup functions
|
|---|
| 138 | * - Filelist creation functions
|
|---|
| 139 | * - Verify functions
|
|---|
| 140 | * - verify_data()
|
|---|
| 141 | * - Low-level verify functions - libmondo-verify.c
|
|---|
| 142 | * - Mountlist functions
|
|---|
| 143 | * - libmondo-mountlist.c
|
|---|
| 144 | * - RAID functions
|
|---|
| 145 | * - libmondo-raid.c
|
|---|
| 146 | * - Device functions
|
|---|
| 147 | * - libmondo-devices.c
|
|---|
| 148 | * - Tape functions
|
|---|
| 149 | * - libmondo-stream.c
|
|---|
| 150 | * - Utility functions
|
|---|
| 151 | * - String functions
|
|---|
| 152 | * - libmondo-string.c
|
|---|
| 153 | * - File functions
|
|---|
| 154 | * - libmondo-files.c
|
|---|
| 155 | * - FIFO functions
|
|---|
| 156 | * - libmondo-fifo.c
|
|---|
| 157 | * - libmondo-tools.c
|
|---|
| 158 | * - GUI functions
|
|---|
| 159 | * - newt-specific.c
|
|---|
| 160 | * - Global variables
|
|---|
| 161 | ***************************************************************************/
|
|---|
| 162 | /**
|
|---|
| 163 | * @defgroup archiveGroup Backup Functions
|
|---|
| 164 | * Functions for backing up data.
|
|---|
| 165 | */
|
|---|
| 166 | /**
|
|---|
| 167 | * @defgroup MLarchiveGroup Mid-Level Backup Functions
|
|---|
| 168 | * @ingroup archiveGroup
|
|---|
| 169 | * Mid-level backup functions (the ones that backup_data calls directly).
|
|---|
| 170 | */
|
|---|
| 171 | /**
|
|---|
| 172 | * @defgroup LLarchiveGroup Low-Level Backup Functions
|
|---|
| 173 | * @ingroup archiveGroup
|
|---|
| 174 | * Low-level backup functions (the ones that do the actual work).
|
|---|
| 175 | */
|
|---|
| 176 | /**
|
|---|
| 177 | * @defgroup verifyGroup Verification Functions
|
|---|
| 178 | * Functions for verifying data while booted from the hard drive (as opposed
|
|---|
| 179 | * to a "compare", which is done while booted from CD/floppy).
|
|---|
| 180 | */
|
|---|
| 181 | /**
|
|---|
| 182 | * @defgroup LLverifyGroup Low-Level Verification Functions
|
|---|
| 183 | * @ingroup verifyGroup
|
|---|
| 184 | * Low-level verification functions (the ones that do the actual work).
|
|---|
| 185 | */
|
|---|
| 186 | /**
|
|---|
| 187 | * @defgroup compareGroup Compare Functions
|
|---|
| 188 | * Functions for comparing data while booted from CD/floppy (as opposed
|
|---|
| 189 | * to a "verify", which is done while booted from the hard drive).
|
|---|
| 190 | */
|
|---|
| 191 | /**
|
|---|
| 192 | * @defgroup LLcompareGroup Low-Level Compare Functions
|
|---|
| 193 | * Low-level compare functions (the ones that do the actual work).
|
|---|
| 194 | * @ingroup compareGroup
|
|---|
| 195 | */
|
|---|
| 196 | /**
|
|---|
| 197 | * @defgroup restoreGroup Restoration Functions
|
|---|
| 198 | * Functions for restoring data.
|
|---|
| 199 | */
|
|---|
| 200 | /**
|
|---|
| 201 | * @defgroup prepGroup Disk Preparation Functions
|
|---|
| 202 | * Functions for prepping disks (partitioning, formatting, mounting, slicing, dicing, etc.)
|
|---|
| 203 | * @ingroup restoreGroup
|
|---|
| 204 | */
|
|---|
| 205 | /**
|
|---|
| 206 | * @defgroup restoreGuiGroup GUI Restore Functions
|
|---|
| 207 | * Functions for editing mountlists, filelists, etc.
|
|---|
| 208 | * @ingroup restoreGroup
|
|---|
| 209 | */
|
|---|
| 210 | /**
|
|---|
| 211 | * @defgroup LLrestoreGroup Low-Level Restoration Functions
|
|---|
| 212 | * Functions for individual restoration of filesets/biggiefiles.
|
|---|
| 213 | * @ingroup restoreGroup
|
|---|
| 214 | */
|
|---|
| 215 | /**
|
|---|
| 216 | * @defgroup restoreUtilityGroup Restore Utility Functions
|
|---|
| 217 | * Utility functions to help with restores.
|
|---|
| 218 | * @ingroup restoreGroup
|
|---|
| 219 | */
|
|---|
| 220 | /**
|
|---|
| 221 | * @defgroup filelistGroup Filelist Creation Functions
|
|---|
| 222 | * Filelist preparation/chopping/other tasks done during backup.
|
|---|
| 223 | */
|
|---|
| 224 | /**
|
|---|
| 225 | * @defgroup mountlistGroup Mountlist Functions
|
|---|
| 226 | * Functions for loading, manipulating, and saving mountlists (but not doing
|
|---|
| 227 | * any prep work with them).
|
|---|
| 228 | */
|
|---|
| 229 | /**
|
|---|
| 230 | * @defgroup raidGroup Software RAID Functions
|
|---|
| 231 | * Functions for dealing with software RAID (md devices on Linux; vinum
|
|---|
| 232 | * on FreeBSD).
|
|---|
| 233 | */
|
|---|
| 234 | /**
|
|---|
| 235 | * @defgroup deviceGroup Device Manipulation Functions
|
|---|
| 236 | * Functions for dealing with backup devices.
|
|---|
| 237 | */
|
|---|
| 238 | /**
|
|---|
| 239 | * @defgroup streamGroup Stream Functions
|
|---|
| 240 | * @ingroup deviceGroup
|
|---|
| 241 | * Functions for reading from and writing to tapes and other data streams.
|
|---|
| 242 | */
|
|---|
| 243 | /**
|
|---|
| 244 | * @defgroup utilityGroup Utility Functions
|
|---|
| 245 | * General utility functions for doing small, specific, useful tasks.
|
|---|
| 246 | */
|
|---|
| 247 | /**
|
|---|
| 248 | * @defgroup stringGroup String Functions
|
|---|
| 249 | * @ingroup utilityGroup
|
|---|
| 250 | * Functions for working with strings.
|
|---|
| 251 | */
|
|---|
| 252 | /**
|
|---|
| 253 | * @defgroup fileGroup File Functions
|
|---|
| 254 | * @ingroup utilityGroup
|
|---|
| 255 | * Functions for working with files.
|
|---|
| 256 | */
|
|---|
| 257 | /**
|
|---|
| 258 | * @defgroup fifoGroup FIFO Functions
|
|---|
| 259 | * @ingroup utilityGroup
|
|---|
| 260 | * Functions for dealing with the buffering of data as it is read from and
|
|---|
| 261 | * written to tape.
|
|---|
| 262 | */
|
|---|
| 263 | /**
|
|---|
| 264 | * @defgroup guiGroup GUI Functions
|
|---|
| 265 | * GUI functions - things like progress indicators, dialog boxes, etc.
|
|---|
| 266 | */
|
|---|
| 267 | /**
|
|---|
| 268 | * @defgroup cliGroup Command-Line Interface Functions
|
|---|
| 269 | * Functions for parsing command lines passed to mondoarchive. <b>Not in libmondo yet.</b>
|
|---|
| 270 | */
|
|---|
| 271 | /**
|
|---|
| 272 | * @defgroup globalGroup Global Variables
|
|---|
| 273 | * Mondo's global variables.
|
|---|
| 274 | */
|
|---|
| 275 | /*************************** END GROUP DEFINITIONS *************************/
|
|---|
