ispman/docs AUTH_LDAP_README,NONE,1.1.2.1 INSTALL,1.2,1.2.8.1 README,1.2,1.2.8.1 TODO,1.1,1.1.2.1 Quickstart.txt,1.4,NONE
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-serv5341/docs
Modified Files:
Tag: rel_1_2-bugfixes
INSTALL README TODO
Added Files:
Tag: rel_1_2-bugfixes
AUTH_LDAP_README
Removed Files:
Tag: rel_1_2-bugfixes
Quickstart.txt
Log Message:
last minute doc changes merged from HEAD
Index: README
===================================================================
RCS file: /cvsroot/ispman/ispman/docs/README,v
retrieving revision 1.2
retrieving revision 1.2.8.1
diff -u -d -r1.2 -r1.2.8.1
--- README 24 Apr 2003 20:24:32 -0000 1.2
+++ README 21 Jun 2004 19:46:36 -0000 1.2.8.1
@@ -1,80 +1,48 @@
-ISPMan is an ISP management system designed to meet the needs of the ever growing infrastructure
-that an ISP has to manage.
-
-ISPMan was written to manage DNS, Web Virtual hosts and Mail accounts at large ISPs.
-
-Since then it has moved to a modular structure with help from ispman-developers
-<ispman-developers-5NWGOfrQmneRv+LV9MX5uipxlwaOVQ5f@public.gmane.org>.
-
-ISPMan can now support
-User Managemnet
-DNS Management
-Different kind of domains management (Primary, Secondary, Replicas etc)
-
-ISPMan is split into two main parts.
-1) Manager
-2) Agent
-
-The manager is the web interface from which you can add/delete users, domains, dns data,
-http virtual servers etc, while the agent is the software that runs on one or more machines
-and does the actual work. Example:
-* Creating/deleting dirctories
-* reloading/reconfiguring services such as dnsServer, httpServer etc.
-
-The agent checks the LDAP directory every few minutes to see if there are any jobs allocated
-to that host. If there are any jobs, it takes appropriate actions, else does nothing.
-This relieves the administrator from running some scripts or cron entries to reload services.
-
-Example: If you have changed the dns entry for a domain, then the agent running on the dns
-server(s) will automatically reconfigure and reload your dns software.
-
-
-
-ispman-agent
--------------
-
-this software should run on all machines taking part in the ISP that should get some data
-from the LDAP server.
-
-Example:
-smtp servers
-dns servers
-file server
-web servers
-
-To Install, simply follow the install procedure. Read Quickstart.txt
-
-
-To start ispman-agent run
-/opt/ispman/bin/ispman-agent start
-
-to stop
-/opt/ispman/bin/ispman-agent stop
-
-to restart
-/opt/ispman/bin/ispman-agent restart
-
-to restart after an unclean shutdown
-/opt/ispman/bin/ispman-agent forcerestart
-
-to start in foreground
-/opt/ispmanbin/ispman-agent nodetach
+ISPMan
+======
-ispman-agent writes log file to /opt/ispman/var/hostname.ispman-agent.log
-Make sure you clean this file from time to time or it gets LARGE.
+ISPMan is an ISP management system designed to meet the needs of the ever
+growing infrastructure that an ISP has to manage. It was originally written to
+manage DNS, Web Virtual hosts and Mail accounts at large ISPs. Since then it
+has moved to a modular structure with help from ispman-developers.
+ISPMan now supports the following features:
+ - Centralized user and email management via LDAP
+ - Primary DNS management (some secondary and replica support)
+ - Virtual web hosting management
+ - Customer managed domains and virtual hosts
+ - Client/Reseller login support
+ - Multiple tiered architecture
+ - GUI and command line interfaces
-ispman-web interface
----------------------
-This should run on a protected network. It should not be available from the internet for
-your own safety. Also, the software will not function correctly unless you are logged on
-correctly as some user.
+ISPMan is built of four main components:
+ - LDAP directory and schema
+ - ISPMan administrator's web interface
+ - ISPMan customer control panel
+ - ISPMan-agent
-To get a reasonable speed you should serve this interface from a mod_perl enabled webserver
-so that persistent objects can be kept in memory.
+The LDAP schema defines a structure that facilitates management of hundreds or
+thousands of domains and as many users within each. Unlike SQL relational
+databases, LDAP is a heirarchical database. This means it stores data in a
+tree like structure, as opposed to many flat tables. Each have their
+advantages, but for user accounts within domains, the tree structure makes
+sense.
+The administrator's web interface allows one to create or delete domains,
+users, dns zones, virtual hosts and other settings. All operations are put on
+a dispatch list for another module to take care of.
+The customer control panel is a simplified version of the administrator's web
+interface. It is restricted to managing only their domain. It is designed for
+the customer and is similar to customer control panels of other ISPs using
+commercial software.
-Read the file Quickstart.txt for more info.
+Finally, the ispman-agent is the real work horse. The agents running on each
+server in the group track the dispatch list in the ldap tree. When a new job
+is created via the admin or customer web interfaces, they go to work. If the
+job is for the web server groups, say, the agent will modify the virtual host
+listings as specified. The agent is the same software on each machine that can
+do various functions. Like cron, it sits idle when there is no work to do.
+Read through INSTALL to learn how to setup each of these components.
--- NEW FILE: AUTH_LDAP_README ---
About Installing Webservers for Customers.
-----------------------------------------
You can have one or more webservers installed. When creating a vhost, you can
tell ispman which webserver it belongs to, this lets you distribute the load
across mulitple servers or distribute for other reasons.
Example: you may want to put
* customer who requires Oracle and jserver on
a Solaris box with these features
* customers who require PHP on a Linux box
* some friends (non-paying customers) on an old Indy
etc
etc
For the customer webservers which your client will access,
you may need to have auth_ldap compiled in as a module.
Auth_ldap is a module that provides authentification services by looking
up information in the LDAP directory.
This module is only needed if you wish to use the Access control feature of
the customer control panel.
You can download auth_ldap from its homepage
http://www.rudedog.org/auth_ldap
You don't need to recompile your Apache server if it is compiled with loadable
modules support
To check if you Apache binary is compiled with loadable module support
run
/path/to/your/httpd -l
look for mod_so.c in the result. If you see it, then your server supports
loadable modules.
For help on building the auth_ldap module see
http://www.rudedog.org/auth_ldap/1.6/auth_ldap.html#building
I normally compile with
./configure --activate --with-ldap-sdk=openldap --with-apxs=/path/to/apxs
make all install
You will be prompted for a username/pass
The username is the same as you set for the admin
example, if you set
uid=ispman, ou=ispman, o=ispman
then the username is "ispman"
and the password that you set for the admin
Index: TODO
===================================================================
RCS file: /cvsroot/ispman/ispman/docs/TODO,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -d -r1.1 -r1.1.2.1
--- TODO 20 Jun 2004 14:06:18 -0000 1.1
+++ TODO 21 Jun 2004 19:46:36 -0000 1.1.2.1
@@ -1,13 +1,22 @@
+CCP
- more CCP debugging
-- more syntax/semantic checks on forms
+
+General
+- more syntax/semantic and validity checks on forms
+
+Administration
+- debian package generation
+
+Design
- posixGroup conflict resolution
- multiport vhost patch
- ispman.agent LDAP features: reconnect, SSL
- bind generation bugfixes
-- debian package generation
- dealing with vhost.conf.hash
- redesign of DNS forms
- custom hooks for create/delete user/vhost/domain
- forms for reseller/client management
+- generic quota solution
- caching of data to enhance performance
-- generic quota solution
\ No newline at end of file
+ Could be handled just by instructing how to install ncsd, mod_perl?
+
Index: INSTALL
===================================================================
RCS file: /cvsroot/ispman/ispman/docs/INSTALL,v
retrieving revision 1.2
retrieving revision 1.2.8.1
diff -u -d -r1.2 -r1.2.8.1
--- INSTALL 24 Apr 2003 20:24:29 -0000 1.2
+++ INSTALL 21 Jun 2004 19:46:36 -0000 1.2.8.1
@@ -1,19 +1,223 @@
-see Quickstart.txt.
+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.
-Keep this directory around. In case we release new fixes for
-this version you can simply update it from CVS.
+Beyond this file, the next step is configuring individual applications such as
+postfix, pop3/imap and other applications to query the ldap tree.
-To update from CVS type
-cvs login (when promted for password, just hit enter)
-cvs -z3 update -dP
-then do the usual install
-./configure
-make ispman
-make install_ispman_common
-make install_ispman_web
+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
-etc
-etc
+- 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.
+
+
+Installing 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".
+
+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
+
+Download the latest bug fixes from cvs:
+ cvs -z3 update -dP
+
+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
+
+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
+
+Install the rest of the files.
+ make install_ispman_common
+ make install_ispman_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.
+
+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.
+
+You need at least the following schemas defined:
+ core.schema
+ cosine.schema
+ nis.schema
+ misc.schema
+ inetorgperson.schema
+ dnszone.schema
+ 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.
+
+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
+
+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.
+ /opt/ispman/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.
+
+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.
+
+ <VirtualHost *>
+ ServerName ispman.yourdomain.tld
+ DocumentRoot /opt/ispman/htdocs
+ <Directory /opt/ispman/htdocs>
+ DirectoryIndex index.html index.cgi
+ AllowOverride None
+ <Files *.cgi>
+ Options ExecCGI
+ AddHandler cgi-script .cgi
+ </Files>
+ </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.
+
+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
+
+Then use this virtual host instead:
+ <VirtualHost *>
+ ServerName ispman.yourdomain.tld
+ DocumentRoot /opt/ispman/htdocs
+ PerlModule Apache::Registry
+ <Directory /opt/ispman/htdocs>
+ DirectoryIndex index.html index.cgi
+ AllowOverride None
+ <Files *.cgi>
+ Options ExecCGI
+ SetHandler perl-script
+ PerlHandler Apache::Registry
+ </Files>
+ </Directory>
+ </VirtualHost>
+
+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.
+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.
+
+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.
+
+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.
+
+
+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.
+
+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.
+
+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.
+
+ /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).
--- Quickstart.txt DELETED ---
-------------------------------------------------------
This SF.Net email sponsored by Black Hat Briefings & Training.
Attend Black Hat Briefings & Training, Las Vegas July 24-29 -
digital self defense, top technical experts, no vendor pitches,
unmatched networking opportunities. Visit www.blackhat.com