ispman/docs INSTALL,1.5,1.6
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-serv28511/docs
Modified Files:
INSTALL
Log Message:
changed/added installation instructions according to new procedures
Index: INSTALL
===================================================================
RCS file: /cvsroot/ispman/ispman/docs/INSTALL,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- INSTALL 30 Jun 2004 06:31:27 -0000 1.5
+++ INSTALL 1 Aug 2004 21:00:51 -0000 1.6
@@ -1,76 +1,289 @@
Installing ISPMan
=================
-In order to use ISPMan, you will need an ldap server and a web server. ISPMan
-is developed using OpenLDAP and Apache. This file goes over the process for
-installing the ispman files, populating a new ldap tree, installing the
-ispman-agent and setting up a virtual host for apache.
-Beyond this file, the next step is configuring individual applications such as
-postfix, pop3/imap and other applications to query the ldap tree.
+ISPMan is developed using OpenLDAP and Apache.
+This file covers
+ - necessary requirements
+ - basic concepts
+ - process for installing
+ - populating a new ldap tree
+ - setting up a virtual host for apache.
+Beyond this file, the next step is configuring individual applications
+such as postfix, pop3/imap and other applications to query the ldap
+tree.
-Quickstart
-----------
-This is the quick process to install or upgrade. See the sections below for
-detailed installation.
-- Update and install
- cvs -z3 update -dP
- ./configure
- make ispman install_ispman_common install_ispman_web
+In the Appendix section you can find some additional information about
+security suggestions, distribution packaging and customizations.
-- Configure ldap server, then import ispman base into ldap with:
- make ldif-install
-- Setup the apache vhost.
-- Configure ispman through web interface.
-- Copy the agent to remote hosts.
-- Start it on all hosts participating in the server group.
+Requirements
+============
+In order to use ISPMan, you will need ...
+... 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.
-Installing ISPMan Files
+... 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.
+The module for this is exchangeable, though, so an experienced ISPMan
+admin may come up with his own interface for some other web server
+type.
+
+... perl:
+This is mandatory, since ISPMan is written in perl ;)
+Perl 5.6 (or higher) is recommended.
+
+... CPAN (optional but highly recommended):
+The "Comprehensive Perl Archive Network". A perl module, which gives
+you online access to the CPAN repository. This allows you to add
+missing perl modules needed for proper ISPMan operation.
+As an alternative, you can use precompiled modules provided by your
+distribution. For a last fallback, ISPMan has a set of bundled
+modules, that can be installed on request.
+
+
+ISPMan Concepts
+===============
+If you got 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:
+ * Perl libraries providing the business logic
+ * Command-Line-Tools for non-web administration
+ * ISPMan agent - The "executive" doing the actual work
+ * Web CGIs - Providing an user interface for admin & customers
+
+Depending on your ISP architecure you will deploy all or a subset of the
+above on one or more machines (see ARCHITECTURE doc).
+
+In contrast to earlier ISPMan versions there are now definite
+procedures for installation, software and release management.
+
+For one there is your *ispman_source_repository*, which you have already
+created when unpacking the ISPMan tarball (otherwise you wouldn't be
+able to read this ;)
+Put this wherever you want. I would recommend a nice place in your
+general software repository where you store all your other software,
+too.
+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.
+
+That's it! No more "build", "tmp", or whatever directories confusing you.
+
+See sections below for some more information 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.
+
+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
+7) Finish ISPMan configuration through web interface
+8) Prepare your hosts to run ispman-agent
+
+
+1) Unpack tarball & get latest bugfixes via CVS
+-----------------------------------------------
+ISPMan is available as tar packages created at release intervals.
+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".
+
+As described above (in Concepts), untar the ISPMan package somewhere
+in your software repository.
+ -> tar xfz ispman-1.2.tar.gz
+ -> cd ispman-1.2
+
+Be sure to have internet access and download the latest bug fixes from
+cvs:
+ -> cvs -z3 update -dP
+
+The necessary CVS structures are already contained in the tarball, so
+don't worry about the cvs tags.
+
+Result of this section:
+You should have a complete, uptodate copy of that ISPMan version.
+
+
+2) Install ISPMan files
-----------------------
-ISPMan is available as tar packages created at release intervals. Bugfixes are
-made available only through CVS updates. For version 1.2, the cvs tag is
-"rel_1_2-bugfixes".
+Configure the install.
+ -> ./configure --prefix=/path/to/ispman/directory
-The default location for ispman is in /opt. Extract and install the tar file:
- cd /opt
- tar xfz ispman-1.2.tar.gz
- cd ispman-1.2
+Specify "--prefix" if your installation directory is not the default
+(/opt/ispman).
-Download the latest bug fixes from cvs:
- cvs -z3 update -dP
+Generate ISPMan core data & schemas
+ -> make
+(alternate targets:)
+ -> make ldif
+ -> make schema
-Configure the install. Default installation dir is /opt/ispman. --prefix is
-not necessary unless you wish to change location.
- ./configure --prefix=/path/to/ispman/directory
+Notice:
+There is no more interactive configuration at this time. This is done
+(manually) after installation.
-Next you will be asked configuration questions. Most of the configuration will
-end up in /opt/ispman/conf/ispman.conf. Some will go in your ldap tree. The
-ldap administrator password given here, is also set in the ldap server
-configuration and used to log in to the web interface.
- make ispman
+Initial install of ISPMan files.
+Right now, there are basically two installation profiles available:
+ install-bin for all CLI tools, including ispman-agent
+ install-web for all files needed for web interface
-Install the rest of the files.
- make install_ispman_common
- make install_ispman_web
+Depending on your ISPMan deployment scenario (see ARCHITECURE), you'll
+use either one or both.
+For the following initial ISPMan setup, we assume doing a full install
+on this host you are doing this installation.
+ -> make install
+(alternate targets:)
+ -> make install-bin
+ -> make install-web
-OpenLDAP Configuration
-----------------------
-The above commands generated slapd.conf and ldap.conf in tmp/conf. 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.
+Notice:
+Every install target includes any 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
+sync somehow.
-Copy dnszone.schema, pureftpd.schema and ispman.schema from tmp/schema to your
-ldap server's schema directory. This might be in paths like
-/etc/openldap/schema or /etc/ldap/schema, etc. OpenLDAP comes with some schema
-files, and looking at your original slapd.conf, the openldap package or
-Makefile listings will tell you where they go. These schema files need to be
-referenced in the slapd.conf file as well.
+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
+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
+further configuration:
+ - ispman.conf.example configuration example
+ - ldif/* inital ISPMan data
+ - schema/* schema files for LDAP
-You need at least the following schemas defined:
+
+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
+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
+modules, they were removed from the lib directory.
+
+To have all needed modules available though, you can install them
+easily by using CPAN or the bundled module files in the contrib/perl
+directory.
+
+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,
+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.
+If you eventually come up with a list of needed packages for a specific
+distribution (e.g. RedHat, Debian, etc.), please provide it to the
+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
+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
+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.
+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
+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.
+ -> cd contrib/perl
+ -> make install-bundled
+
+
+Notice:
+You will need at least the CPAN module installed, to use option #2/#3.
+Since any CPAN related option installs the latest module version
+available, there is a possible chance it renders modules incompatible
+with ISPMan.
+If you think this is the case, please fall back to option #4 and file
+a bug with ISPMan.
+
+Result of this section:
+All the needed perl modules are in place.
+Besides the following core configuration, installation of ISPMan files
+is complete.
+
+
+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
+ispman.conf.
+ -> cd <installdir>/conf
+ -> cp ispman.conf.example ispman.conf
+
+Notice:
+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).
+
+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
+---------------------------------------------------------------
+Configuration of the necessary ldap server is actually an issue for
+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.
+
+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.
+
+Adjust the schema files to support ISPMan data.
+The needed schema files are provided in <installdir>/conf/schema.
+You are free to copy them to your LDAP schema dir (usualy
+/etc/ldap/schema) or refer to them directly in your slapd.conf
+
+Be sure to have at least the following schemas defined:
core.schema
cosine.schema
nis.schema
@@ -80,38 +293,51 @@
pureftpd.schema
ispman.schema
-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 default. Starting the server with a
-debug option will print messages to the screen if the server fails to start.
+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
+default. Starting the server with a debug option will print messages
+to the screen if the server fails to start.
-Populate the base ispman tree. This will run ldapadd with the file
-tmp/ldif/ispman.ldif and can be substituted with other methods.
- make ldif-install
+Next step is to populate the base ispman tree.
+We use the installed <installdir>/ldif/ispman.ldif for that, 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
+your core configuration.
+
+The proper way of doing the initial load of ispman.ldif is
+ -> cd <installdir>
+ -> cat conf/ldif/ispman.ldif | ./bin/ispman.substConf | \
+ ./bin/ispman.loadldif -f -
+
+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
installed. Here is an example that should print many variables like
'ispmanVar:'. Make sure this works before going any further.
- ldapsearch -x -LLL ispmanVar=*
+ -> ldapsearch -x -LLL ispmanVar=*
-Run an ispman command to test the ispman configuration against the ldap tree.
-Again fix errors before continuing.
- /opt/ispman/bin/ispman.listVars
+Run an ispman command to test the ispman configuration against the
+ldap tree. Again fix errors before continuing.
+ -> <installdir>/bin/ispman.listVars
-Web Interface Configuration
-----------------------------
-ISPMan has an Administrator Panel and a Customer Control Panel. Both 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.
+6) Setup 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
+tree. These can be installed either with a dedicated webserver or
+appended on to an existing web server.
-This interface should run on a protected network and should not be available
-from the internet. If it is, using SSL to secure transmissions is strongly
-recommended.
+This interface should run on a protected network and should not be
+available from the internet. If it is, using SSL to secure
+transmissions is strongly recommended.
-There are no special requirements for use with Apache Server. Just create a
-regular virtual host such as the following.
+There are no special requirements for use with Apache Server. Just
+create a regular virtual host such as the following.
<VirtualHost *>
ServerName ispman.yourdomain.tld
@@ -131,18 +357,20 @@
</Directory>
</VirtualHost>
-To increase speed you might consider serving the interface from a mod_perl
-enabled webserver so persistent objects can be kept in memory. This can result
-in a very significant speed increase. Use the following instructions instead.
-The speed difference can literally be amazing as it is with Apache running off
-of a Sun Blade 100.
+To increase speed you might consider serving the interface from a
+mod_perl enabled webserver so persistent objects can be kept in
+memory. This can result in a very significant speed increase. Use the
+following instructions instead.
+The speed difference can literally be amazing as it is with Apache
+running off of a Sun Blade 100.
-Ensure mod_perl is installed and loaded. When you compile, or install your
-unix distribtion's version of mod_perl, you should have a line like this added
-to your server configuration. You may need to uncomment it:
+Ensure mod_perl is installed and loaded. When you compile, or install
+your Unix distribtion's version of mod_perl, you should have a line
+like this added to your server configuration. You may need to
+uncomment it:
LoadModule perl_module /usr/lib/apache/1.3/mod_perl.so
or maybe:
- LoadModule perl_module libexec/libperl.so
+ LoadModule perl_module libexec/libperl.so
Then use this virtual host instead:
<VirtualHost *>
@@ -165,69 +393,90 @@
</Directory>
</VirtualHost>
+
+7) Finish ISPMan configuration through web interface
+----------------------------------------------------
Restart the webserver and visit the following link to get the ispman web
interface.
http://ispman.yourdomain.tld
Select "Login as an Administrator".
-Login with username "ispman".
-The password is what you set for the LDAP administator.
+Login with username "ispman" and the password you specified during
+ISPMan core configuration for LDAP administrator.
IMPORTANT:
-Before making any changes, click the "Configure" menu then setup "Hosts" and
-"HostGroups".
-
-Next, browse throught the other configuration settings and make sure paths,
-commands, ip addresses and other settings are correct for your network.
+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.
-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
-systems that do actual tasks like creating users, setting up DNS, etc.
+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.
-ISPMan's web interface only edits infomation in the LDAP tree. The
-ispman-agents running on each node do the real work. ISPMan writes tasks for
-them to perform in ldap. These tasks are set by hostgroups, so it is VERY
-IMPORTANT that they are properly defined. As an example, a "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.
+ISPMan's web interface only edits infomation in the LDAP tree. The
+ispman-agents running on each node do the real work. ISPMan creates
+tasks for them in ldap. These tasks are set by hostgroups, so it is
+VERY IMPORTANT that they are properly defined. As an example, a
+"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.
-Installing ispman-agent
------------------------
-The agent is the work horse of ISPMan. It should be installed on each machine
-taking part for some function of ISPMan. Each agent needs to 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.
+8) Prepare your hosts to run ispman-agent
+-----------------------------------------
+The agent is the work horse of ISPMan. It should be installed on each
+machine taking part for some function of ISPMan. Each agent needs to
+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.
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 start
-at boot and run on each host.
+directory from the first installed host to the next. Then set it up to
+start at boot and run on each host.
-Using a supervise program like DJB's supervise is recommended. This 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
- echo '#!/bin/sh' >> run
- echo 'echo Starting ispman agent' >> run
- echo 'exec /opt/ispman/bin/ispman-agent nodetach' >> run
- chmod +x /service/ispman/run
- svc -u /service/ispman
+Using a supervise program like DJB's supervise is recommended. This
+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
+ -> echo '#!/bin/sh' >> run
+ -> echo 'echo Starting ispman agent' >> run
+ -> echo 'exec /opt/ispman/bin/ispman-agent nodetach' >> run
+ -> chmod +x /service/ispman/run
+ -> svc -u /service/ispman
-Regardless of the supervise program, run the ispman-agent with the desired
-start/stop options as below. "forcerestart" will restart after an unclean
-shutdown. "nodetach" start in the foreground and won't detach from the
-controlling terminal.
+Regardless of the supervise program, run the ispman-agent with the
+desired start/stop options as below:
+ * "forcerestart" restart after an unclean shutdown
+ * "nodetach" start in the foreground without detaching from the
+ controlling terminal.
- /opt/ispman/bin/ispman-agent {start|stop|restart|forcerestart|nodetach}
+ -> /opt/ispman/bin/ispman-agent {start|stop|restart|forcerestart|nodetach}
+
+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
+the log to ensure it is started. Otherwise processes will remain in
+the queue shown in the web interface for a very long time (until the
+agent is actually started).
+
+
+
+Appendix: Security
+==================
+
+
+Appendix: Distribution packaging
+================================
-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 the log to ensure it is started. Otherwise processes will remain in the
-queue shown in the web interface for a very long time (until the agent is
-actually started).
+Appendx: Customizations
+=======================
\ No newline at end of file
-------------------------------------------------------
This SF.Net email is sponsored by OSTG. Have you noticed the changes on
Linux.com, ITManagersJournal and NewsForge in the past few weeks? Now,
one more big change to announce. We are now OSTG- Open Source Technology
Group. Come see the changes on the new OSTG site. www.ostg.com