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 *************************/
|
---|