[Ispman-docs] [PATCH] INSTALL corrections

[Finn T. <ft...@te...>]

Hi,

Here are some suggestions for the INSTALL file, in the form of a patch. 
The changes are improvements to grammar, spelling and consistency.

I'm in the process of setting up ISPman, so I haven't read much of the 
rest of the docs yet. Is it appropriate to send patches against HEAD?

Regards
Finn Thain



Index: docs/INSTALL
===================================================================
RCS file: /cvsroot/ispman/ispman/docs/INSTALL,v
retrieving revision 1.8
diff -u -r1.8 INSTALL
--- docs/INSTALL	4 Aug 2004 20:15:39 -0000	1.8
+++ docs/INSTALL	7 Aug 2005 07:28:39 -0000
@@ -3,9 +3,9 @@
 
 ISPMan is developed using OpenLDAP and Apache.
 This file covers
- - necessary requirements
+ - prerequisites
  - basic concepts
- - process for installing
+ - installation process
  - populating a new ldap tree
  - setting up a virtual host for apache.
 
@@ -21,13 +21,13 @@
 ============
 In order to use ISPMan, you will need ...
 
-... a ldap server:
+... A LDAP server:
 This will be preferably OpenLDAP, but actually any LDAP server could
 do the job. The following inststructions are based on OpenLDAP, so
-you'll probably need to adjust the configs and schemas accordingly, if
-you use an alternate LDAP server.
+you'll probably need to adjust the configs and schema accordingly, if
+you use an alternative LDAP server.
 
-... a web server:
+... A web server:
 Apache is the suggested choice. While ISPMan itself will probably run
 on any CGI enabled web server, the managed vhosts within ISPMan are
 generated with apache's vhost.conf style config files.
@@ -35,7 +35,7 @@
 admin may come up with his own interface for some other web server
 type.
 
-... perl:
+... Perl:
 This is mandatory, since ISPMan is written in perl ;)
 Perl 5.6 (or higher) is recommended.
 
@@ -50,13 +50,13 @@
 
 ISPMan Concepts
 ===============
-If you got your requirements in place, you are ready for install.
+If you have your requirements in place, you are ready for install.
 But before starting off, be sure to understand the main principles
 behind ISPMan:
 
-ISPMan consists primarily out of for main parts:
+ISPMan consists primarily of four main parts:
  * Perl libraries providing the business logic
- * Command-Line-Tools for non-web administration
+ * Command-line tools for non-web administration
  * ISPMan agent - The "executive" doing the actual work
  * Web CGIs - Providing an user interface for admin & customers
 
@@ -75,29 +75,29 @@
 This will be the place from which you will install, update and
 customize your ISPMan.
 
-Besides this you will have your *ispman_install_directory* where all
-the files will get installed.
+Besides this, you will have your *ispman_install_directory* where all
+the files will be installed.
 
-That's it! No more "build", "tmp", or whatever directories confusing you.
+That's it! No more "build", "tmp", or whatever directory to confuse you.
 
-See sections below for some more information how to effectively update
+See sections below for some more information as to how to effectively update
 and customize your ISPMan installation.
 
 
 
 Installation Overview
 =====================
-This is quick overview process about the installation process.  See
-the sections below for detailed installation.
+This is quick overview of the installation process. See the sections below
+for detailed installation.
 
 1) Unpack tarball & get latest bugfixes via CVS
 2) Install ISPMan files
 3) Install needed perl modules
 4) Configure ISPMan core (ispman.conf)
-5) Configure ldap server and do the initial load of ISPMan data
-6) Setup the apache vhost for ISPMan
+5) Configure LDAP server and do the initial load of ISPMan data
+6) Set up the Apache vhost for ISPMan
 7) Finish ISPMan configuration through web interface
-8) Prepare your hosts to run ispman-agent
+8) Prepare your host(s) to run ispman-agent
 
 
 1) Unpack tarball & get latest bugfixes via CVS
@@ -106,8 +106,8 @@
 Bugfixes are made available only through CVS updates.
 
 Example:
-ISPMan version 1.2 is realeased as tar package ispman-1.2.tar.gz.
-The cvs tag matching this version is "rel_1_2-bugfixes".
+ISPMan version 1.2 is available as a tar package, ispman-1.2.tar.gz.
+The CVS tag matching this release is "rel_1_2-bugfixes".
 
 As described above (in Concepts), untar the ISPMan package somewhere
 in your software repository.
@@ -115,25 +115,25 @@
         -> cd ispman-1.2
 
 Be sure to have internet access and download the latest bug fixes from
-cvs:
+CVS:
         -> cvs -z3 update -dP
 
 The necessary CVS structures are already contained in the tarball, so
-don't worry about the cvs tags.
+don't worry about the CVS tags.
 
 Result of this section:
-You should have a complete, uptodate copy of that ISPMan version.
+You should have a complete and up-to-date copy of an ISPMan release.
 
 
 2) Install ISPMan files
 -----------------------
-Configure the install.
+Configure the installation.
         -> ./configure --prefix=/path/to/ispman/directory
 
 Specify "--prefix" if your installation directory is not the default
 (/opt/ispman). 
 
-Generate ISPMan core data & schemas 
+Generate ISPMan core data & schemas.
         -> make
 (alternate targets:)
         -> make ldif
@@ -148,11 +148,11 @@
         install-bin     for all CLI tools, including ispman-agent
         install-web     for all files needed for web interface
 
-Depending on your ISPMan deployment scenario (see ARCHITECURE), you'll
-use either one or both.
+Depending on your ISPMan deployment scenario (see ARCHITECTURE), you'll
+use either or both.
 
-For the following initial ISPMan setup, we assume doing a full install
-on this host you are doing this installation.
+For the following initial ISPMan setup, we assume a full install on the
+present host.
         -> make install
 (alternate targets:)
         -> make install-bin
@@ -160,31 +160,31 @@
         -> make install-agent
 
 Notice:
-Every install target includes any necessary common files.
+Every install target includes the necessary common files.
 If you are deploying on several hosts, make sure to either share the
-ISPMan configuration ($install_dir/conf/ispman.conf) or keep it in
+ISPMan configuration (<installdir>/conf/ispman.conf) or keep it in
 sync somehow.
 
 Result of this section:
-You will have a full ISPMan installation in the issued install
-directory (default: /opt/ispman). This dir is clean of any temporary
+You will have a full ISPMan installation in the given install
+directory. This dir is clean of any temporary
 files as well as any CVS files/dirs, because we certainly don't want
-to upgrade our productive installation directly.
-In the $installdir/conf dir, you'll find the following files for
+to upgrade our production installation directly.
+In the <installdir>/conf directory, you'll find the following files for
 further configuration:
  - ispman.conf.example          configuration example
- - ldif/*                       inital ISPMan data
+ - ldif/*                       initial ISPMan data
  - schema/*                     schema files for LDAP
 
 
 3) Install needed perl modules
 ------------------------------
 ISPMan uses quite a bunch of other perl modules that have to be
-available for proper operations.
-In the past, those dependant modules where provided within the ISPMan
+available for proper operation.
+In the past, those dependencies were provided within the ISPMan
 lib directory, which provided a kind of "hardcoded" environment,
-because any installed site perl modules where ignored.
-To overcome this limitation and provide better ways of having uptodate
+because any installed site-perl modules were ignored.
+To overcome this limitation and provide better ways of having up-to-date
 modules, they were removed from the lib directory.
 
 To have all needed modules available though, you can install them
@@ -193,8 +193,8 @@
 
 You have quite a few options here, so let's shed some light on that:
 
-option #1) Perl libs are provided by your system/distribution.
-This is probably the most wanted, but also most difficult option,
+option #1) Use Perl libs provided by your system/distribution.
+This is probably the most desirable, but also the most difficult option,
 since it very much depends on your OS distribution.
 You will find a list of needed perl modules in contrib/perl/modules,
 which you can match to packages in your distribution.
@@ -203,24 +203,24 @@
 developers, which will ease the creation of ISPMan distribution
 packages a lot.
 
-option #2) Perl libs are installed sitewide through CPAN.
-You don't care about distribution packages and just want to install
+option #2) Install Perl libs site-wide using CPAN.
+If you don't care about distribution packages, you may want to install
 any missing perl modules in the perl site directories.
         -> cd contrib/perl
         -> make install-cpan-site
 
-option #3) Perl libs are installed in ISPMan installation directory.
-You want to be independant of any installed site modules but like to
+option #3) Install Perl libs in ISPMan installation directory.
+If you want to be independant of any installed site modules but like to
 use the latest available module versions.
 In fact, this is pretty simmilar to the old way (before 1.3), except
 that it uses the latest versions available.
         -> cd contrib/perl
         -> make install-cpan
 
-option #4) Bundled perl libs are installed in ISPMan installation dir.
+option #4) Use bundled Perl libs installed in ISPMan installation dir.
 ISPMan comes with bundled perl modules, which are installed within the
 ISPMan install directory.
-This is probably the most easiest and convenient option, because you
+This is probably the easiest and most convenient option, because you
 don't need CPAN or an online connection. It uses fixed, but tested
 modules, so be sure to fallback here if you have trouble getting
 things to work.
@@ -245,39 +245,38 @@
 4) Configure ISPMan core
 ------------------------
 Provide a core ISPMan configuration (ispman.conf).
-If you are doing this install the first time, you can get an example
+If you are doing this install for the first time, you can get an example
 ispman.conf.
         -> cd <installdir>/conf
         -> cp ispman.conf.example ispman.conf
 
-Notice:
-If you already used earlier versions of ISPMan, be sure to migrate
+NB: If you already used earlier versions of ISPMan, be sure to migrate
 your old ispman.conf to the new config format.
 
 Edit the config file (ispman.conf) and change it according to your
-environment (esp. ldap server configuration).
+environment (especially the LDAP server configuration).
 
 Finaly, verify that ispman.conf has proper file permissions. It
 contains cleartext password, so no regular user should be able to read
 it (see Appendix about Security)!
 
 
-5) Configure ldap server and do the initial load of ISPMan data
+5) Configure LDAP server and do the initial load of ISPMan data
 ---------------------------------------------------------------
-Configuration of the necessary ldap server is actually an issue for
+Configuration of the necessary LDAP server is actually an issue in
 itself, and to have a secure and fast server, you should make yourself
 familiar with this issue by consulting the manual.
 
 Notice:
-From ISPMan's perspective there is no need to use a LDAP server
-exclusively, so you may in fact use any LDAP server that is already
-present, presumed you are able to adjust it's configuration accordingly.
+From ISPMan's perspective there is no need to have exclusive use of
+the LDAP server, so you may in fact use any LDAP server that is already
+present, presuming you are able to adjust its configuration accordingly.
 
 To give you a good starting point, there are example configurations
 for OpenLDAP bundled with ISPMan (install-data/examples/openldap).
-They can be used to modify or replace your OpenLDAP's server and
-client configuration files, respectively. Note that there may be some
-differences in paths with your unix distribution.
+They can be used to modify or replace your OpenLDAP server and
+client configuration files. Note that there may be some differences in
+paths compared with your unix distribution.
 
 Adjust the schema files to support ISPMan data.
 The needed schema files are provided in <installdir>/conf/schema.
@@ -294,18 +293,18 @@
     pureftpd.schema
     ispman.schema
 
-Restart your ldap server and ensure that it started without
+Restart your LDAP server and ensure that it started without
 errors. Look in the log. OpenLDAP logs to the LOCAL4 syslog facility
-by default, and many unix distributions don't listen or log this by
+by default, and many Unix distributions don't listen or log this by
 default. Starting the server with a debug option will print messages
 to the screen if the server fails to start.
 
 Next step is to populate the base ispman tree.
-We use the installed <installdir>/ldif/ispman.ldif for that, which
+We use the installed <installdir>/ldif/ispman.ldif for this, which
 provides the base LDAP tree for ISPMan data.
 Though this file is basically LDIF, you can't load this directly into
 your LDAP server, because it still contains some placeholders
-(e.g. ldapBaseDN) which have to be substituted with the real values of
+(e.g. ldapBaseDN) which have to be substituted with the real values from
 your core configuration.
 
 The proper way of doing the initial load of ispman.ldif is
@@ -316,20 +315,20 @@
 This should run through smoothly. In case you are getting errors here,
 solve them first before continuing.
 
-Run a test query to ensure ldap is working and the ispman base has been
+Run a test query to ensure LDAP is working and the ISPman base has been
 installed.  Here is an example that should print many variables like
 'ispmanVar:'.  Make sure this works before going any further.
         -> ldapsearch -x -LLL ispmanVar=*
 
 Run an ispman command to test the ispman configuration against the
-ldap tree. Again fix errors before continuing.
+LDAP tree. Again, fix any errors before continuing.
         -> <installdir>/bin/ispman.listVars
 
 
-6) Setup the apache vhost for ISPMan
+6) Set up the Apache vhost for ISPMan
 ------------------------------------
 ISPMan has an Administrator Panel and a Customer Control Panel. Both
-are cgi files installed in the same virtual host or directory
+are CGI files installed in the same virtual host or directory
 tree. These can be installed either with a dedicated webserver or
 appended on to an existing web server.  
 
@@ -397,7 +396,7 @@
 
 7) Finish ISPMan configuration through web interface
 ----------------------------------------------------
-Restart the webserver and visit the following link to get the ispman web
+Restart the web server and visit the following link to get the ispman web
 interface.
     http://ispman.yourdomain.tld
 
@@ -406,17 +405,16 @@
 ISPMan core configuration for LDAP administrator.
 
 IMPORTANT:
-Before going excited and start playing around, click the "Configure"
-menu and finish the ISPMan configuration by supplying proper
-information for all config groups. Especially the "Hosts" and
-"HostGroups" tabs are important.
+Before excitedly playing around, click the "Configure"
+menu and finish the ISPMan configuration by supplying the proper
+information for all config groups.
 
 Without configuring hosts and hostgroups, ISPMan will just be a fancy
 LDAP browser/editor. The hosts and host groups are VERY
 important. They are the linkage between generated processes and
-executed tasks by ispman-agent like creating users, setting up DNS,
-etc. So, if generated processes are not executed by ispman-agent, this
-is the place to check.
+tasks executed by ispman-agent, like creating users, setting up DNS,
+etc. So, if generated processes are not being executed by ispman-agent,
+this is the place to check.
 
 ISPMan's web interface only edits infomation in the LDAP tree. The
 ispman-agents running on each node do the real work. ISPMan creates
@@ -425,7 +423,7 @@
 "modifyDomain" request will go to dnsgroup. An agent on a host sees
 the task in the ldap tree set for its hostgroup and make the change in
 the dns server.  If you have not defined dnsgroup properly, the
-request will be strayed. 
+request will go astray. 
 
 
 8) Prepare your hosts to run ispman-agent
@@ -435,7 +433,7 @@
 connect to the LDAP server to get its task list. Anywhere ISPMan is
 updating files requires the agent. This will be on servers listed
 under "hosts" and "hostgroups" under configuration in the web
-interface. This includes smtp, dns, file and web servers.
+interface. This includes SMTP, DNS, file and web servers.
 
 The easiest way to setup ispman-agent is to just copy the whole ispman
 directory from the first installed host to the next. Then set it up to
@@ -445,8 +443,8 @@
 will ensure that ispman-agent is running on the appropriate
 machines. This can be done quickly, assuming supervise is already
 installed, with the following:
-        -> mkdir /supervise/ispman
-        -> cd /supervise/ispman
+        -> mkdir /service/ispman
+        -> cd /service/ispman
         -> echo '#!/bin/sh' >> run
         -> echo 'echo Starting ispman agent' >> run
         -> echo 'exec /opt/ispman/bin/ispman-agent nodetach' >> run
@@ -461,7 +459,7 @@
 
         -> /opt/ispman/bin/ispman-agent {start|stop|restart|forcerestart|nodetach}
 
-Ispman-agent writes a log file to
+ispman-agent writes a log file to
 /opt/ispman/var/<hostname>.ispman-agent.log. Be sure to clean out this
 file from time to time or use logrotate as it can get LARGE. When the
 agent has been started by booting, manual start or supervisor, review
@@ -478,8 +476,8 @@
 
 a) ISPMan files:
 Requirements: 
- * unix admin user should be able to use the CLI Tools (e.g. "admin")
- * ispman-agent needs to execute ISPMan processes (this usualy must be
+ * Unix admin user should be able to use the CLI Tools (e.g. "admin")
+ * ispman-agent needs to execute ISPMan processes (this usually must be
    "root" to be able to create/chown directories) 
  * web server needs to execute CGIs (running as "www" for example)
  * ispman.conf contains cleartext passwords and thus must not be
@@ -492,26 +490,26 @@
  - change group of all ISPMan files:
         -> cd <installdir>
         -> chgrp -R ispman .
- - if you didn't do ISPMan install as root I suggest reowning all
+ - if you didn't do the ISPMan installation as root I suggest giving all
    files to root:
         -> cd <installdir>
         -> chown -R root .
 
 During the install process all file modes should already be set
-adequately. Basicall only one file is of greater concern, because it
-contains cleartext passwords -> ispman.conf.
+adequately. Basically, only one file is of great concern, because it
+contains cleartext passwords, i.e. ispman.conf.
 Be sure that this file will not be readable by non-admin users!
         -> chmod 640 ispman.conf
 
 
 b) Web:
-Some users where claiming that ISPMan is unsecure, because ISPMan
-files (including ispman.conf) is readable by the webserver and thus
-any CGI programm a users calls could read those files.
-
-Although, this might be correct for some webserver installations, this
-is no security problem with ISPMan but rather the used webserver
-installation.
+Some users were claiming that ISPMan is not secure, because ISPMan
+files (including ispman.conf) are readable by the webserver and thus
+any CGI program a user calls could read those files.
+
+Although this might be correct for some webserver installations, this
+is not a security problem with ISPMan but one with those webserver
+installations.
 There are established techiques for secure CGI execution in place
 (suexec, jails, etc.). With such configured properly, there is no
 security problem with ISPMan at all.
@@ -524,8 +522,8 @@
 
 Simple example:
 You want to build a tar file which can be used to distribute the
-ispman-agent on all of your hosts. The ispman install dir should be
-placed in "/usr/local/ispman".
+ispman-agent on all of your hosts. The ISPman install dir is to be
+"/usr/local/ispman".
 
 Do this as follows:
         -> configure --prefix=/usr/local/ispman
@@ -535,32 +533,31 @@
 /usr/local/ispman only to build the tarball. So do this:
         -> make install-agent DESTDIR=/tmp/install
 
-This will install the complete ISPMan tree necessary to run the agent
-in /tmp/install. Just tar it there and you have a nice little
-distribution package.
+This will install the complete ISPMan tree in /tmp/install. Just tar
+it there and you have a nice little distribution package.
 
 
 Appendix: Customizations
 ========================
 You may have the need to change some of the ISPMan files to fit your
-requirements. Especially the library (*.lib) and template (*.template)
-files are designed for individual customizations.
+requirements. The library (*.lib) and template (*.template) files are
+especially designed for individual customizations.
 
 If that's the case for you, it may be advantageous to plan a litte bit
 ahead.
-Most users go the greedy way and just change the required files in their
+Most users go the obvious way and just change the required files in their
 installation directory. While this may be adequate for some quick
-tests, you should not do this on a permanent basis.
+tests, you cannot do this on a permanent basis.
 On next ISPMan update you'll know why, because the upgrade will
-overwrite all your nice litte changes.
+overwrite all your nice changes.
 
-So, what's the best practice for such changes:
+So, what's the best practice for such changes?
 Well, it's easy! Apply your changes to the *source* directory, not the
 installation directory.
-This has some obvious advantages:
- - Your customizations will persist cvs updates. In fact, any changes
-   in the same file will be merged, presumed it doesn't conflict with
-   your modifications.
+This has some real advantages:
+ - Your customizations will survive CVS updates. In fact, any change
+   to the same file will be merged, presuming that it doesn't conflict
+   with your modifications.
  - Any (upgrade) installation will already contain your modifications.