doc: Replace and update README with POD markup

2 files changed, 154 insertions, 117 deletions

diff --git a/README b/README
deleted file mode 100644
index ff7c449..0000000
--- a/README
+++ /dev/null
@@ -1,117 +0,0 @@
-SquashFu - a combination of fun, squashfs, joy, happiness, aufs and rsync
-===================================================================
-REQUIREMENTS: bash, aufs, aufs2-util, squashfs-tools, rsync
-
-SquashFu is currently beta quality. While there may be some undiscovered bugs,
-the major components and structures in place will not change unless absolutely
-necessary. This means that backups created today will still be useful 6 months
-from now (if your config supports this).
-
-Mini FAQ:
-
-Why?
- - Why not?
-
-What currently works?
- - Regular incrementals. Execute with sudo and the -B option
- - Automatic merging incremenetals down to MIN_BINS once MAX_BINS has been exceeded
- - Rolling back. Execute with sudo, the -R option, and a number of backups to roll back
- - Reporting, executed with -Q, shows approx. disk usage and bin information
-
-What's not yet included?
- - A lot of error catching. While rsync takes care of itself and you'll suffer no
-   damage by aborting rsync in the middle of a backup, you could easily destroy
-   things by, for example, setting MIN_BINS greater than MAX_BINS.
-
-What not to expect?
- - Elephants
- - Salvation
-
-===================================================================
-
-Goal: To create a backup solution which provides incremental backups and compression,
-      and which also provides an easy way to roll back.
-
-Design:
-  A directory structure is created as follows (with some terminology included):
-      backup_root/
-       |- seed.sfs  <-- squash, or seed
-       |- .bin.list <-- bin inventory list (or binventory)
-       |- ro/       <-- squash mount point
-       |- rw/       <-- union mount point
-       |- .bins/    <-- incrementals
-           |-1/
-           | .....
-           | .....
-           | .....
-           | .....
-           | .....
-           |-n/
-
-  seed.sfs is created from an initial backup and compressed using SquashFS, which is
-  simply a read only filesystem which focuses on compression. It's mounted, using a 
-  loopback device, on ro/.
-
-  At the time of the backup, the next available bin is determined, created, and logged
-  to an inventory sheet with a timestamp. A union is created with all the available bins,
-  mounted in reverse chronological order on top of the seed (newest to oldest) on rw/.
-  At this point, the union represents the state of your files at the end of the last
-  backup. The newest branch is marked as read/write, and rsync is called. Because this
-  top branch is the only writable location in the union, the files rsync generates with
-  the -u (update) flag are placed into this branch. The backup finishes, and the union
-  and seed are unmounted.
-
-  At this point, Squashfu ensures compliance with the user's settings of MAX_BINS. If
-  the current number of used bins exceeds this value, a new seed is generated. The 
-  number of old incrementals merged into the new seed is determined by the difference
-  between MAX_BINS and MIN_BINS in the config file. In this way, you always have
-  MIN_BINS available to roll back to, but you're not forced to recompress your seed
-  at every backup -- an operation that may take a long time depending on how big
-  your backup source is.
-
-  If and when you want to roll back, execute Squashfu with the -R action, and supply
-  the number of bins you want to roll back. The bins are ordered chronologically,
-  and the oldest "number_of_bins - bins_to_rollback" are mounted on the union mount
-  point.
-
-WARNING:
-  You should not, under any circumstances, add or remove files contained in the bins, 
-  nor should you alter your binventory's time stamps. Doing so can result in non-recoverable
-  damage to the integrity of the backups.
-
-Further reading:
-  http://en.wikipedia.org/wiki/Aufs
-  http://en.wikipedia.org/wiki/UnionFS
-  http://aufs.sourceforge.net/
-  http://en.wikipedia.org/wiki/SquashFS
-  http://en.wikipedia.org/wiki/Rsync
-
-
-INSTALL (if you're not on Arch Linux)
--------------------------------------
--Copy squashfu.conf as /etc/squashfu.conf
--Make a backup directory somewhere where you want your files
--READ OVER /etc/squashfu.conf and set it the way you want
--Run manually with 'squashfu -B'
--If everything goes well, make a cron job to run this bad boy at the time you want
--Hang onto ya nuts. As this is still an alpha, I take no responsibility for
- loss of data, and I likely don't care much about bug reports.
-
-
-KNOWN BUGS
-------------------------------------
-1/17/2010
-    Issue: Paths with special chars or whitespace as includes or excludes are
-           not properly handled when passed to rsync.
-    Fix:   If you MUST be ridiculous, escape (not quote) the spaces and/or other
-           special characters.
-
-TODO
----------------------------------------
-In no particular order....
-
-- Add opt for shortened report that doesn't report sizes
-- Fix output funcs for non-color scenario
-- Add semantic error checking for config
-- Create man page
-- Make config more helpful by providing possible values, not just verbiage
diff --git a/README.pod b/README.pod
new file mode 100644
index 0000000..33956ba
--- /dev/null
+++ b/README.pod
@@ -0,0 +1,154 @@
+=head1 NAME
+
+squashfu - an incremental backup solution
+
+=head1 SYNOPSIS
+
+I<squashfu> <action> [options]
+
+=head1 DESCRIPTION
+
+I<squashfu> is a Bash based backup utility that uses the flexibility of rsync, squashfs, 
+and aufs to create incremental backups and offer limited compression.
+
+=head1 ACTIONS
+
+=over
+
+=item B<-B>
+
+Runs a regular backup, using the config file at /etc/squashfu.
+
+=item B<-C>
+
+Create a new squashed seed by merging old bins. This will leave you with a no more
+than the number of bins specified by the MIN_BINS setting in the config.
+
+=item B<-D> I<BIN>
+
+Delete the incremental backup with the number BIN. This is done interactively and you
+will have a chance to confirm before any files are deleted.
+
+=item B<-Q>
+
+Displays usage statistics, including the size of the compressed seed and each incremental
+backup with its creation date and bin number.
+
+=item B<-R>
+
+Cookies will be persistent and reused for logins. If you specify this option, you must
+also provide a cookie file path with the -C option or in the config file.
+
+=item B<-U>
+
+Unmount the squash and union. Although I<squashfu> will always check and unmount as
+necessary before an operation, this is provided as a convenience.
+
+=back
+
+=head1 OPTIONS
+
+=over
+
+=item B<-c> F<PATH>
+
+Specify an alternate config file as denoted by F<PATH>. The default config will still be
+sourced, but options specified in this config will override the defaults. If your extra
+config overrides the location of the backups, ensure that this config is always passed 
+for any operation.
+
+=back
+
+=head1 HOW IT WORKS
+
+
+Goal: To create a backup solution which provides incremental backups and compression,
+and which also provides an easy way to roll back.
+
+Design:
+
+  A directory structure is created as follows (with some terminology included):
+
+      backup_root/
+       |- seed.sfs  <-- squash, or seed
+       |- ro/       <-- squash mount point
+       |- rw/       <-- union mount point
+       |- .bins/    <-- incrementals
+           |-1/
+           | .....
+           | .....
+           | .....
+           | .....
+           | .....
+           |-n/
+
+      /var/
+       |- lib/
+          |- .squashfu.inv <-- bin inventory list (or binventory)
+
+seed.sfs is created from an initial backup and compressed using SquashFS, which is
+simply a read only filesystem which focuses on compression. It's mounted, using a 
+loopback device, on ro/.
+
+At the time of the backup, the next available bin is determined, created, and logged
+to an inventory sheet with a timestamp. A union is created with all the available bins,
+mounted in reverse chronological order on top of the seed (newest to oldest) on rw/.
+At this point, the union represents the state of your files at the end of the last
+backup. The newest branch is marked as read/write, and rsync is called. Because this
+top branch is the only writable location in the union, the files rsync generates with
+the -u (update) flag are placed into this branch. The backup finishes, and the union
+and seed are unmounted.
+
+At this point, Squashfu ensures compliance with the user's settings of MAX_BINS. If
+the current number of used bins exceeds this value, a new seed is generated. The 
+number of old incrementals merged into the new seed is determined by the difference
+between MAX_BINS and MIN_BINS in the config file. In this way, you always have
+MIN_BINS available to roll back to, but you're not forced to recompress your seed
+at every backup -- an operation that may take a long time depending on how big
+your backup source is.
+
+If and when you want to roll back, execute Squashfu with the -R action, and supply
+the number of bins you want to roll back. The bins are ordered chronologically,
+and the oldest "number_of_bins - bins_to_rollback" are mounted on the union mount
+point.
+
+B<WARNING:>
+You should not, under any circumstances, add or remove files contained in the bins,
+nor should you alter your binventory's time stamps. Doing so many result in your cat
+being set on fire or your backups being destroyed.
+
+=head1 INSTALLATION
+
+~ Ensure that squashfu.conf resides in F</etc/squashfu.conf>
+
+~ Determine your backup_root location.
+
+~ Read over each option in F</etc/squashfu.conf> and set it accordingly.
+
+~ Create your first backup with I<squashfu> B<-B> and validate that the backup was
+created successfully.
+
+~ It may be a wise idea to make more changes, run a new backup and inspect the resulting
+incremental.
+
+=head1 FURTHER READING
+
+L<http://en.wikipedia.org/wiki/Aufs>
+
+L<http://en.wikipedia.org/wiki/UnionFS>
+
+L<http://aufs.sourceforge.net/>
+
+L<http://en.wikipedia.org/wiki/SquashFS>
+
+L<http://en.wikipedia.org/wiki/Rsync>
+
+
+=head1 SEE ALSO
+
+B<aufs>(5), B<rsync>(1)
+
+=head1 AUTHOR
+
+Dave Reisner E<lt>d@falconindy.comE<gt>
+