ispman/docs INSTALL,1.8,1.9
Joerg Delker <[email protected]>
| Newsgroups | gmane.comp.isp.ispman.cvs |
|---|---|
| Message-ID | <[email protected]> |
Update of /cvsroot/ispman/ispman/docs In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv13193 Modified Files: INSTALL Log Message: some textual corrections (thanks to Finn Thain <fthain-PnMVE5gNl/[email protected]>) Index: INSTALL =================================================================== RCS file: /cvsroot/ispman/ispman/docs/INSTALL,v retrieving revision 1.8 retrieving revision 1.9 diff -u -d -r1.8 -r1.9 --- INSTALL 4 Aug 2004 20:15:39 -0000 1.8 +++ INSTALL 7 Aug 2005 20:16:15 -0000 1.9 @@ -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. +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 no security problem with ISPMan but rather the used webserver -installation. +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. ------------------------------------------------------- SF.Net email is Sponsored by the Better Software Conference & EXPO September 19-22, 2005 * San Francisco, CA * Development Lifecycle Practices Agile & Plan-Driven Development * Managing Projects & Teams * Testing & QA Security * Process Improvement & Measurement * http://www.sqe.com/bsce5sf