--- loncom/build/make_domain_coordinator.pl	2002/09/09 17:57:33	1.6
+++ loncom/build/make_domain_coordinator.pl	2002/10/12 16:23:21	1.7
@@ -11,7 +11,7 @@ make_domain_coordinator.pl - Make a doma
 # The LearningOnline Network
 # make_domain_coordinator.pl - Make a domain coordinator on a system
 #
-# $Id: make_domain_coordinator.pl,v 1.6 2002/09/09 17:57:33 harris41 Exp $
+# $Id: make_domain_coordinator.pl,v 1.7 2002/10/12 16:23:21 harris41 Exp $
 #
 # This file is part of the LearningOnline Network with CAPA (LON-CAPA).
 #
@@ -35,6 +35,7 @@ make_domain_coordinator.pl - Make a doma
 #
 # YEAR=2002
 # 3/1,3/3,3/4 Scott Harrison
+# 10/12 Scott Harrison
 #
 ###
 
@@ -52,7 +53,8 @@ These are the steps that are executed on
 =item * 
 
 Tests to see if user already exists for linux system or for
-LON-CAPA, if so aborts
+LON-CAPA, if so aborts.  A message is output that recommends following
+a manual procedure enabling this user if so desired.
 
 =item *
 
@@ -83,16 +85,19 @@ Set roles.hist and roles.db
 
 # This is a standalone script.  It *could* alternatively use the
 # lcuseradd script, however lcuseradd relies on certain system
-# dependencies.  make_domain_coordinator.pl should be able
-# to run freely as possible irrespective of the status of a LON-CAPA
+# dependencies.  In order to have a focused performance, I am trying
+# to avoid system dependencies until the LON-CAPA code base becomes
+# more robust and well-boundaried.  make_domain_coordinator.pl should be able
+# to run freely as possible, irrespective of the status of a LON-CAPA
 # installation.
 
 # ---------------------------------------------------- Configure general values
 
-my %perlvar;
+my %perlvar; # Holds network-wide and machine-specific configuration values.
+# We only need one configuration value however, lonUsersDir.  Rather than
+# read this out of loncapa.conf, I am just going to hard-code this for now.
 $perlvar{'lonUsersDir'}='/home/httpd/lonUsers';
 
-
 =pod
 
 =head1 OPTIONS
@@ -122,42 +127,64 @@ if (@ARGV!=2) {
 }
 my ($username,$domain)=(@ARGV); shift @ARGV; shift @ARGV;
 unless ($username=~/^\w+$/ and $username!~/\_/) {
-    die 'Username '.$username.' must consist only of alphanumeric characters'.
-	"\n";
+    die('**** ERROR **** '.
+	'Username '.$username.' must consist only of alphanumeric characters'.
+	"\n");
 }
 unless ($domain=~/^\w+$/ and $domain!~/\_/) {
-    die 'Domain '.$domain.' must consist only of alphanumeric characters'.
-	"\n";
+    die('**** ERROR **** '.
+	'Domain '.$domain.' must consist only of alphanumeric characters'.
+	"\n");
 }
 
-print "Password: "; $|=1;
+# Output a warning message.
+print('**** NOTE **** '.
+      'Generating a domain coordinator is "serious business".'."\n".
+      'Choosing a difficult-to-guess (and keeping it a secret) password '."\n".
+      'is highly recommended.'."\n");
+
+print("Password: "); $|=1;
 my $passwd=<>; # read in password from standard input
 chomp($passwd);
 
 if (length($passwd)<6 or length($passwd)>30) {
-    die 'Password is an unreasonable length.'."\n";
+    die('**** ERROR **** '.'Password is an unreasonable length.'."\n".
+	'It should be at least 6 characters in length.'."\n");
 }
 my $pbad=0;
 foreach (split(//,$passwd)) {if ((ord($_)<32)||(ord($_)>126)){$pbad=1;}}
 if ($pbad) {
-    die 'Password must consist of standard ASCII characters'."\n";
+    die('**** ERROR **** '.
+	'Password must consist of standard ASCII characters'."\n");
 }
 
 # And does user already exist
 
+my $caveat =
+    'For security reasons, this script will only automatically generate '."\n".
+    'new users, not pre-existing users.'."\n".
+    "If you want to make '$username' a domain coordinator, you "."\n".
+    'should do so manually by customizing the MANUAL PROCEDURE'."\n".
+    'described in the documentation.  To view the documentation '."\n".
+    'for this script, type '.
+    "'perldoc ./make_domain_coordinator.pl'."."\n";
+
 if (-d "/home/$username") {
-    die ($username.' is already a linux operating system user.'."\n");
+    die ('**** ERROR **** '.$username.' is already a linux operating system '.
+	 'user.'."\n".$caveat);
 }
 my $udpath=propath($domain,$username);
 if (-d $udpath) {
-    die ($username.' is already defined as a LON-CAPA user.'."\n");
+    die ('**** ERROR **** '.$username.' is already defined as a LON-CAPA '.
+	 'user.'."\n".$caveat);
 }
 
 =pod
 
 =head1 MANUAL PROCEDURE
 
-There are 10 steps to a manual procedure.
+There are 10 steps to manually recreating what this script performs
+automatically.
 
 You need to decide on three pieces of information
 to create a domain coordinator.
@@ -187,7 +214,7 @@ login as root on your Linux system
 
 # ------------------------------------------------------------ So, are we root?
 
-if ($< != 0) {
+if ($< != 0) { # Am I root?
   die 'You must be root in order to generate a domain coordinator.'."\n";
 }
 
@@ -203,7 +230,7 @@ if ($< != 0) {
 # ----------------------------------------------------------- /usr/sbin/useradd
 
 $username=~s/\W//g; # an extra filter, just to be sure
-`/usr/sbin/useradd $username`;
+`/usr/sbin/useradd $username`; # Add the user with the 'useradd' command.
 
 =pod
 
@@ -218,15 +245,16 @@ $username=~s/\W//g; # an extra filter, j
 
 =cut
 
-$username=~s/\W//g; # an extra filter, just to be sure
-$pbad=0;
+# Process password (taint-check, then pass to the UNIX passwd command).
+$username =~ s/\W//g; # an extra filter, just to be sure
+$pbad = 0;
 foreach (split(//,$passwd)) {if ((ord($_)<32)||(ord($_)>126)){$pbad=1;}}
 if ($pbad) {
-    die 'Password must consist of standard ASCII characters'."\n";
+    die('Password must consist of standard ASCII characters'."\n");
 }
-open OUT,"|passwd --stdin $username";
-print OUT $passwd."\n";
-close OUT;
+open(OUT,"|passwd --stdin $username");
+print(OUT $passwd."\n");
+close(OUT);
 
 =pod
 
@@ -247,11 +275,18 @@ close OUT;
  Let S equal second letter of USERNAME
  Let E equal third letter of USERNAME
  Command: [prompt %] install -d DOMAIN/U/S/E/USERNAME
- Example: [prompt %] install -d 103/d/c/1/dc103
+
+ Here are three examples of the commands that would be needed
+ for different domain coordinator names (dc103, morphy, or ng):
+
+ Example #1 (dc103):  [prompt %] install -d 103/d/c/1/dc103
+ Example #2 (morphy): [prompt %] install -d 103/m/o/r/morphy
+ Example #3 (ng):     [prompt %] install -d 103/n/g/_/ng
 
 =cut
 
-`install -o www -g www -d $udpath`;
+# Generate the user directory.
+`install -o www -g www -d $udpath`; # Must be writeable by httpd process.
 
 =pod
 
@@ -266,10 +301,11 @@ close OUT;
 
 =cut
 
-open OUT, ">$udpath/passwd";
-print OUT 'unix:'."\n";
-close OUT;
-`chown www:www $udpath/passwd`;
+# UNIX (/etc/passwd) style authentication is asserted for domain coordinators.
+open(OUT, ">$udpath/passwd");
+print(OUT 'unix:'."\n");
+close(OUT);
+`chown www:www $udpath/passwd`; # Must be writeable by httpd process.
 
 =pod
 
@@ -280,21 +316,22 @@ close OUT;
 
 =cut
 
-use GDBM_File;
+use GDBM_File; # A simplistic key-value pairing database.
 my %hash;
-        tie(%hash,'GDBM_File',"$udpath/roles.db",
-	    &GDBM_WRCREAT,0640);
 
-$hash{'/'.$domain.'/_dc'}='dc';
-open OUT, ">$udpath/roles.hist";
+tie(%hash,'GDBM_File',"$udpath/roles.db",
+    &GDBM_WRCREAT,0640); # Interface with GDBM database thru a hash variable.
+
+$hash{'/'.$domain.'/_dc'}='dc'; # Set the domain coordinator role.
+open(OUT, ">$udpath/roles.hist"); # roles.hist is the synchronous plain text.
 map {
-    print OUT $_.' : '.$hash{$_}."\n";
+    print(OUT $_.' : '.$hash{$_}."\n");
 } keys %hash;
-close OUT;
+close(OUT);
+untie(%hash); # Finish interfacing with GDBM database.
 
-untie %hash;
-`chown www:www $udpath/roles.hist`;
-`chown www:www $udpath/roles.db`;
+`chown www:www $udpath/roles.hist`; # Must be writeable by httpd process.
+`chown www:www $udpath/roles.db`; # Must be writeable by httpd process.
 
 =pod
 
@@ -305,26 +342,30 @@ by going to http://MACHINENAME/adm/creat
 
 =cut
 
-print "$username is now a domain coordinator\n";
-my $hostname=`hostname`; chomp $hostname;
-print "http://$hostname/adm/createuser will allow you to further define".
-      " this user.\n";
+# Output success message, and inform sysadmin about how to further proceed.
+print("$username is now a domain coordinator\n"); # Output success message.
+my $hostname=`hostname`; chomp($hostname); # Read in hostname.
+print("http://$hostname/adm/createuser will allow you to further define".
+      " this user.\n"); # Output a suggested URL.
 
-# ----------------------------------------------------------------- SUBROUTINES
+# ================================================================= SUBROUTINES
+# Subroutine propath: take in domain and username, and generate filesystem path
 sub propath {
-    my ($udom,$uname)=@_;
-    $udom=~s/\W//g;
-    $uname=~s/\W//g;
-    my $subdir=$uname.'__';
-    $subdir =~ s/(.)(.)(.).*/$1\/$2\/$3/;
-    my $proname="$perlvar{'lonUsersDir'}/$udom/$subdir/$uname";
-    return $proname;
+    my ($udom,$uname)=@_; # The lonDefDomain, and the domain coord. username.
+    $udom =~ s/\W//g; # Taint removal.
+    $uname =~ s/\W//g; # Taint removal.
+    my $subdir = $uname.'__';
+    $subdir =~ s/(.)(.)(.).*/$1\/$2\/$3/; # The path must have three subdirs.
+    my $proname = "$perlvar{'lonUsersDir'}/$udom/$subdir/$uname"; # Total path.
+    return $proname; # Return the total user directory filesystem path.
 }
 
 =pod
 
 =head1 AUTHOR
 
-Scott Harrison, harris41@msu.edu
+Written to help the LON-CAPA project.
+
+Scott Harrison, sharrison@users.sourceforge.net
 
 =cut