documentation updates.

for all new commands, mogstats, and MogileFS::Utils notes.

lib/MogileFS/Utils.pm

@@ -31,7 +31,7 @@ sub _readconf {
     my $args = shift;
 
     # Liftedish from mogadm, but we can refactor mogadm to use this instead.
-    my @configs = ($args->{config}, $ENV{MOGUTILSCONF},
+    my @configs = ($args->{conf}, $ENV{MOGUTILSCONF},
         "$ENV{HOME}/.mogilefs.conf",
         "/etc/mogilefs/mogilefs.conf");
     my %opts = ();
@@ -62,7 +62,7 @@ sub getopts {
 
     my %opts = ();
     $self->abort_usage($usage) unless @ARGV;
-    GetOptions(\%opts, @want, qw/help trackers=s domain=s/)
+    GetOptions(\%opts, @want, qw/help trackers=s domain=s conf=s/)
         or $self->abort_usage($usage);
     my $config = $self->_readconf(\%opts);
 
@@ -120,7 +120,7 @@ MogileFS::Utils - Command line utilities for the MogileFS distributed file syste
 
 L<mogadm>
 
-L<mogtool>
+L<mogstats>
 
 L<mogupload>
 
@@ -134,14 +134,30 @@ L<moglistkeys>
 
 L<moglistfids>
 
+L<mogtool> (DEPRECATED: Do not use!)
+
 =head1 SUMMARY
 
 Please refer to the documentation for the tools included in this distribution.
 
+=head1 CONFIGURATION FILE
+
+Most of the utilities in this package support a configuration file. Common
+options can be pushed into the config file, such as trackers, domain, or
+class. The file is in B</etc/mogilefs/mogilefs.conf> and B<~/.mogilefs.conf>
+by default. You may also specify a configuration via B<--conf=filename>
+
+Example:
+
+    trackers = 10.0.0.1:7001,10.0.0.3:7001
+    domain = foo
+
 =head1 AUTHOR
 
 Brad Fitzpatrick E<lt>L<[email protected]>E<gt>
 
+Dormando E<lt>L<[email protected]>E<gt>
+
 =head1 BUGS
 
 Please report any on the MogileFS mailing list: L<http://groups.google.com/group/mogile/>.

mogadm

@@ -1437,16 +1437,6 @@ Check to ensure that all of the MogileFS system components are functioning
 and that we can contact everybody.  The quickest way of ensuring that the
 entire MogileFS system is functional from the current machine's point of view.
 
-=item B<stats>
-
-Attempt to get statistics for the MogileFS world. This should provide
-statistics on: the number of files present on each device; the number of files
-in each (domain,class) tuple; statistics about present replication devcounts
-and pending replications.
-
-Due to design constraints, the stats command may presently fail if some
-statistic takes too long to generate.
-
 =item B<host add E<lt>hostE<gt> [host options]>
 
 =item B<host modify E<lt>hostE<gt> [host options]>
@@ -1662,10 +1652,6 @@ Check the status of your entire MogileFS system:
 
     $ mogadm check
     
-Check MogileFS system statistics:
-
-    $ mogadm stats
-
 Check every file in the entire MogileFS system:
 
     $ mogadm fsck reset

mogdelete

@@ -1,5 +1,45 @@
 #!/usr/bin/perl
 
+=head1 NAME
+
+mogdelete -- Delete keys from a MogileFS installation
+
+=head1 SYNOPSIS
+
+    $ mogdelete --trackers=host --domain=foo --key="/hello.jpg"
+
+=head1 OPTIONS
+
+=over
+
+=item --trackers=host1:7001,host2:7001
+
+Use these MogileFS trackers to negotiate with.
+
+=item --domain=<domain>
+
+Set the MogileFS domain to use.
+
+=item --key="<key>"
+
+A key to delete. Can be an arbitrary string.
+
+=back
+
+=head1 AUTHOR
+
+Dormando E<lt>L<[email protected]>E<gt>
+
+=head1 BUGS
+
+Produces a slightly weird error if key does not exist.
+
+=head1 LICENSE
+
+Licensed for use and redistribution under the same terms as Perl itself.
+
+=cut
+
 use strict;
 use warnings;
 

mogfetch

@@ -1,5 +1,53 @@
 #!/usr/bin/perl
 
+=head1 NAME
+
+mogfetch -- Fetch data from a MogileFS installation
+
+=head1 SYNOPSIS
+
+    $ mogfetch [options]
+    $ mogfetch [options] --file="-" > filename
+
+    $ mogfetch --trackers=host --domain=foo \
+               --key="/hello.jpg" --file="output.jpg"
+
+=head1 OPTIONS
+
+=over
+
+=item --trackers=host1:7001,host2:7001
+
+Use these MogileFS trackers to negotiate with.
+
+=item --domain=<domain>
+
+Set the MogileFS domain to use.
+
+=item --key="<key>"
+
+The key to locate the data with. Can be an arbitrary string.
+
+=item --file="<filename|->"
+
+A local destination file. If '-', data is written to STDOUT instead.
+
+=back
+
+=head1 AUTHOR
+
+Dormando E<lt>L<[email protected]>E<gt>
+
+=head1 BUGS
+
+None known.
+
+=head1 LICENSE
+
+Licensed for use and redistribution under the same terms as Perl itself.
+
+=cut
+
 use strict;
 use warnings;
 

mogfileinfo

@@ -1,5 +1,45 @@
 #!/usr/bin/perl
 
+=head1 NAME
+
+mogfileinfo -- Fetch key metadata from a MogileFS installation
+
+=head1 SYNOPSIS
+
+    $ mogfileinfo --trackers=host --domain=foo --key="/hello.jpg"
+
+=head1 OPTIONS
+
+=over
+
+=item --trackers=host1:7001,host2:7001
+
+Use these MogileFS trackers to negotiate with.
+
+=item --domain=<domain>
+
+Set the MogileFS domain to use.
+
+=item --key="<key>"
+
+The key to inspect. Can be an arbitrary string.
+
+=back
+
+=head1 AUTHOR
+
+Dormando E<lt>L<[email protected]>E<gt>
+
+=head1 BUGS
+
+None known, but output might change in the future.
+
+=head1 LICENSE
+
+Licensed for use and redistribution under the same terms as Perl itself.
+
+=cut
+
 use strict;
 use warnings;
 

moglistfids

@@ -1,5 +1,49 @@
 #!/usr/bin/perl
-# Example for building into a backup program.
+
+=head1 NAME
+
+moglistfids -- Iterate fid/key data from a MogileFS installation
+
+=head1 DESCRIPTION
+
+Example utility for pulling all file data out of a MogileFS installation.
+Utilities like this can be built on for creating backup systems,
+Mogile<->Mogile syncronization systems, or Mogile->S3 syncronization.
+
+This method is only a way of pulling new files which have existed since the
+last time it was checked, as there's no logging of deleted files.
+
+=head1 OPTIONS
+
+=over
+
+=item --trackers=host1:7001,host2:7001
+
+Use these MogileFS trackers to negotiate with.
+
+=item --fromfid=<fid>
+
+The highest numbered fid fetched the last time this utility was run.
+
+=item --count=<count>
+
+Numer of fids to inspect and return.
+
+=back
+
+=head1 AUTHOR
+
+Dormando E<lt>L<[email protected]>E<gt>
+
+=head1 BUGS
+
+None known.
+
+=head1 LICENSE
+
+Licensed for use and redistribution under the same terms as Perl itself.
+
+=cut
 
 use strict;
 use warnings;

moglistkeys

@@ -1,4 +1,52 @@
 #!/usr/bin/perl
+
+=head1 NAMe
+
+moglistkeys -- Lists keys out of a MogileFS domain
+
+=head1 SYNOPSIS
+
+    $ moglistkeys --trackers=host --domain=foo --key_prefix="/foo/bar/"
+
+=head1 DESCRIPTION
+
+If you store your MogileFS keys in a logical "structure", you may use this
+tool to view lists of subsets of keys. Note that this is not going to be
+equivalent to "cd" and "ls" tools, as listing "foo/" will list everything
+underneath, so it's more akin to "ls -R"
+
+=head1 OPTIONS
+
+=over
+
+=item --trackers=host1:7001,host2:7001
+
+Use these MogileFS trackers to negotiate with.
+
+=item --domain=<domain>
+
+Set the MogileFS domain to use.
+
+=item --key_prefix="/foo/bar/"
+
+Search for keys starting with this prefix. Can be an arbitrary string.
+
+=back
+
+=head1 AUTHOR
+
+Dormando E<lt>L<[email protected]>E<gt>
+
+=head1 BUGS
+
+None known.
+
+=head1 LICENSE
+
+Licensed for use and redistribution under the same terms as Perl itself.
+
+=cut
+
 # TODO: Add ways to limit # of keys displayed
 
 use strict;