Add documentation.

1 files changed, 242 insertions, 11 deletions

diff --git a/perl/Wallet/Config.pm b/perl/Wallet/Config.pm
index 776cc5a..4bc8e2f 100644
--- a/perl/Wallet/Config.pm
+++ b/perl/Wallet/Config.pm
@@ -6,10 +6,6 @@
 #
 # See README for licensing terms.
 
-##############################################################################
-# Modules and declarations
-##############################################################################
-
 package Wallet::Config;
 require 5.006;
 
@@ -24,28 +20,250 @@ $VERSION = '0.01';
 # Path to the config file to load.
 $PATH = '/etc/wallet.conf';
 
-##############################################################################
-# Variables
-##############################################################################
+=head1 NAME
+
+Wallet::Config - Configuration handling for the wallet server
+
+=head1 SYNOPSIS
+
+    use Wallet::Config;
+    my $driver = $Wallet::Config::DB_DRIVER;
+    my $info;
+    if (defined $Wallet::Config::DB_INFO) {
+        $info = $Wallet::Config::DB_INFO;
+    } else {
+        $info = "database=$Wallet::Config::DB_NAME";
+        $info .= ";host=$Wallet::Config::DB_HOST"
+            if $Wallet::Config::DB_HOST;
+        $info .= ";port=$Wallet::Config::DB_PORT"
+            if $Wallet::Config::DB_PORT;
+    }
+    my $dsn = "dbi:$driver:$info";
+    my $user = $Wallet::Config::DB_USER;
+    my $password = $Wallet::Config::DB_PASSWORD;
+    my $dbh = DBI->connect ($dsn, $user, $password);
+
+=head1 DESCRIPTION
+
+Wallet::Config encapsulates all of the site-specific configuration for the
+wallet server.  It is implemented as a Perl class that declares and sets the
+defaults for various configuration variables and then, if it exists, loads
+the file F</etc/wallet.conf>.  That file should contain any site-specific
+overrides to the defaults, and at least some parameters must be set.
+
+This file must be valid Perl.  To set a variable, use the syntax:
+
+    $VARIABLE = <value>;
+
+where VARIABLE is the variable name (always in all-capital letters) and
+<value> is the value.  If setting a variable to a string and not a number,
+you should normally enclose <value> in C<''>.  For example, to set the
+variable DB_DRIVER to C<MySQL>, use:
+
+    $DB_DRIVER = 'MySQL';
+
+Always remember the initial dollar sign (C<$>) and ending semicolon (C<;>).
+Those familiar with Perl syntax can of course use the full range of Perl
+expressions.
+
+This configuration file should end with the line:
+
+    1;
+
+This ensures that Perl doesn't think there is an error when loading the
+file.
+
+=head1 DATABASE CONFIGURATION
+
+=over 4
+
+=item DB_DRIVER
+
+Sets the Perl database driver to use for the wallet database.  Common values
+would be C<SQLite> or C<MySQL>.  Less common values would be C<Oracle>,
+C<Sybase>, or C<ODBC>.  The appropriate DBD::* Perl module for the chosen
+driver must be installed and will be dynamically loaded by the wallet.  For
+more information, see DBI(3).
+
+This variable must be set.
+
+=cut
 
-# Database configuration.
 our $DB_DRIVER;
+
+=item DB_INFO
+
+Sets the remaining contents for the DBI DSN (everything after the driver).
+Using this variable provides full control over the connect string passed to
+DBI.  When using SQLite, set this variable to the path to the SQLite
+database.  If this variable is set, DB_NAME, DB_HOST, and DB_PORT are
+ignored.  For more information, see DBI(3) and the documentation for the
+database driver you're using.
+
+Either DB_INFO or DB_NAME must be set.  If you don't need to pass any
+additional information to DBI, set DB_INFO to the empty string (C<''>).
+
+=cut
+
 our $DB_INFO;
+
+=item DB_NAME
+
+If DB_INFO is not set, specifies the database name.  The third part of the
+DBI connect string will be set to C<database=DB_NAME>, possibly with a host
+and port appended if DB_HOST and DB_PORT are set.  For more information, see
+DBI(3) and the documentation for the database driver you're using.
+
+Either DB_INFO or DB_NAME must be set.
+
+=cut
+
 our $DB_NAME;
+
+=item DB_HOST
+
+If DB_INFO is not set, specifies the database host.  C<;host=DB_HOST> will
+be appended to the DBI connect string.  For more information, see DBI(3) and
+the documentation for the database driver you're using.
+
+=cut
+
 our $DB_HOST;
+
+=item DB_PORT
+
+If DB_PORT is not set, specifies the database port.  C<;port=DB_PORT> will
+be appended to the DBI connect string.  If this variable is set, DB_HOST
+should also be set.  For more information, see DBI(3) and the documentation
+for the database driver you're using.
+
+=cut
+
 our $DB_PORT;
+
+=item DB_USER
+
+Specifies the user for database authentication.  Some database backends,
+particularly SQLite, do not need this.
+
+=cut
+
 our $DB_USER;
+
+=item DB_PASSWORD
+
+Specifies the password for database authentication.  Some database backends,
+particularly SQLite, do not need this.
+
+=cut
+
 our $DB_PASSWORD;
 
-# Configuration for the keytab object type.
+=back
+
+=head1 KEYTAB OBJECT CONFIGURATION
+
+These configuration variables only need to be set if you intend to use the
+C<keytab> object type (the Wallet::Object::Keytab class).  They point the
+keytab object implementation at the right Kerberos server and B<kadmin>
+client.
+
+=over 4
+
+=item KEYTAB_FILE
+
+Specifies the keytab to use to authenticate to B<kadmind>.  The principal
+whose key is stored in this keytab must have the ability to create, modify,
+inspect, and delete any principals that should be managed by the wallet.
+(In MIT Kerberos F<kadm5.acl> parlance, this is C<admci> privileges.)
+
+KEYTAB_FILE must be set to use keytab objects.
+
+=cut
+
 our $KEYTAB_FILE;
-our $KEYTAB_FLAGS     = '-clearpolicy';
+
+=item KEYTAB_FLAGS
+
+These flags, if any, are passed to the C<addprinc> command when creating a
+new principal in the Kerberos KDC.  To not pass any flags, set KEYTAB_FLAGS
+to the empty string.  The default value is C<-clearpolicy>, which clears any
+password strength policy from principals created by the wallet.  (Since the
+wallet randomizes the keys, password strength checking is generally
+pointless and may interact poorly with the way C<addprinc -randkey> works
+when third-party add-ons for password strength checking are used.)
+
+=cut
+
+our $KEYTAB_FLAGS = '-clearpolicy';
+
+=item KEYTAB_HOST
+
+Specifies the host on which the kadmin service is running.  This setting
+overrides the C<admin_server> setting in the [realms] section of
+F<krb5.conf> and any DNS SRV records and allows the wallet to run on a
+system that doesn't have a Kerberos configuration for the wallet's realm.
+
+=cut
+
 our $KEYTAB_HOST;
-our $KEYTAB_KADMIN    = 'kadmin';
+
+=item KEYTAB_KADMIN
+
+The path to the B<kadmin> command-line client.  The default value is
+C<kadmin>, which will cause the wallet to search for B<kadmin> on its
+default PATH.
+
+=cut
+
+our $KEYTAB_KADMIN = 'kadmin';
+
+=item KEYTAB_PRINCIPAL
+
+The principal whose key is stored in KEYTAB_FILE.  The wallet will
+authenticate as this principal to the kadmin service.
+
+KEYTAB_PRINCIPAL must be set to use keytab objects, at least until B<kadmin>
+is smart enough to use the first principal found in the keytab it's using
+for authentication.
+
+=cut
+
 our $KEYTAB_PRINCIPAL;
+
+=item KEYTAB_REALM
+
+Specifies the realm in which to create Kerberos principals.  The keytab
+object implementation can only work in a single realm for a given wallet
+installation and the keytab object names are stored without realm.
+KEYTAB_REALM is added when talking to the KDC via B<kadmin>.
+
+KEYTAB_REALM must be set to use keytab objects.  C<ktadd> doesn't always
+default to the local realm.
+
+=cut
+
 our $KEYTAB_REALM;
+
+=item KEYTAB_TMP
+
+A directory into which the wallet can write keytabs temporarily while
+processing C<get> commands from clients.  The keytabs are written into this
+directory with predictable names, so this should not be a system temporary
+directory such as F</tmp> or F</var/tmp>.  It's best to create a directory
+solely for this purpose that's owned by the user the wallet server will run
+as.
+
+KEYTAB_TMP must be set to use keytab objects.
+
+=cut
+
 our $KEYTAB_TMP;
 
+=back
+
+=cut
+
 # Now, load the configuration file so that it can override the defaults.
 if (-r $PATH) {
     do $PATH or die (($@ || $!) . "\n");
@@ -53,3 +271,16 @@ if (-r $PATH) {
 
 1;
 __END__
+
+=head1 SEE ALSO
+
+DBI(3), Wallet::Object::Keytab(3), Wallet::Server(3), wallet-backend(8)
+
+This module is part of the wallet system.  The current version is available
+from L<http://www.eyrie.org/~eagle/software/wallet/>.
+
+=head1 AUTHOR
+
+Russ Allbery <rra@stanford.edu>
+
+=cut