GNUWorld / CMaster / CControl Manual

************************************************************************************************************************
************************************************************************************************************************

Version : 1.1
Author : Cti- Cti@zurna.org
Language : English
Document : General info (manual)
Last Update: 22/12/2001
Web Address: http://gnuworld.undernet.org/cmaster/manual.htm

UPDATES:

1.1 - Fixed missing sections (2.2, 2.3, 3.1) - Added links for easy use - Rewrite HTML.


************************************************************************************************************************

This file contains general information about
the manuals. There are four main manuals you can find.
manual.gnuworld : GNUWorld installation guide
manual.ccontrol : ccontrol installation guide (EUworld)
manual.cservice : cservice installation guide (X)
manual.website : Customized Web Interface guide

************************************************************************************************************************

These manuals does NOT include problems occured during the compiling of GNUWorld, I accept that
you compiled and configured GNUWorld correctly. But you can still find a quick installation guide
inside the manual.gnuworld. For details refer to the README file by GNUWorld development team.
If you still have some errors visit us at #coder-com on Undernet, if you are lucky you can find
someone to help you there.

************************************************************************************************************************
ccontrol.manual includes
************************************************************************************************************************
Short description of ccontrol module
Setting up ccontrol for the first time
Example *.conf file
F.A.Q (not yet)


************************************************************************************************************************
cservice.manual includes
************************************************************************************************************************
Short description of cservice module
Setting up cservice for the first time
Example *.conf file
How to add extra level 1000's to DB
F.A.Q

************************************************************************************************************************
manual.website includes
************************************************************************************************************************
Short description of website
How to install Apache for your box
How to install an PHP interpreter
Config files for apache and php
Explanation on config.inc
F.A.Q (again)

If you have any questions regarding these fallowing topics please feel free to mail to
"gnuworld-devel@lists.sourceforge.net" and we will insert it as soon as possible.
************************************************************************************************************************
INDEX
************************************************************************************************************************
PART I - MANUAL.GNUWORLD
Section 1.1 - Obtaining GNUWorld with CVS
Section 1.2 - Building GNUWorld
Section 1.3 - Editing the config file (localhost.conf)
Section 1.4 - Running GNUWorld

PART II - MANUAL.CSERVICE
Section 2.1 - Setting up cservice module for the first time
Section 2.2 - Editing cservice.conf file
Section 2.3 - Adding Extra Level 1000 accounts to DB

PART III - MANUAL.CCONTROL
Section 3.1 - Setting up ccontrol module for the first time
Section 3.2 - Editing ccontrol.conf file

PART IV - MANUAL.WEBSITE
Section 4.1 - Obtaining Apache & PHP interpreter
Section 4.2 - Compiling Apache & PHP interpreter
Section 4.3 - Configuring Apache & PHP interpreter
Section 4.4 - Editing config.inc file

PART V - PostGreS Short Manual


************************************************************************************************************************
************************************************************************************************************************
************************************************************************************************************************

PART I - MANUAL.GNUWORLD

We assume that you have the fallowing stuff installed
and working properly on your box to run GNUWorld

- A working PostGreSQL server with right permissions
- An uplink IRC server with the proper U Lines
- Copy of GNUWorld (check section 1.1 to how to get)
- A machine to run GNUWorld

For the customized web site you also need the
following services working properly

- Running web server (Recommended Apache)
(get latest apache server relase from http://www.apache.org)
- PHP interpreter
(get latest relase from http://www.php.net)
************************************************************************************************************************
Section 1.1 * Obtaining GNUWorld and Web site with CVS
************************************************************************************************************************

1- cvs -d :pserver:anonymous@cvs.gnuworld.sourceforge.net:/cvsroot/gnuworld
login
2- When prompted for a password, hit the return key
3- cvs -z3 -d :pserver:anonymous@cvs.gnuworld.sourceforge.net:/cvsroot/gnuworld
co gnuworld
4- cvs -z3 -d :pserver:anonymous@cvs.gnuworld.sourceforge.net:/cvsroot/gnuworld
co website
(Execute the above commands on a single line in your shell) Line 3 will create
a directory under your current directory named "gnuworld" in which all of
GNUWorld's files will be placed. Line 4 will create a directory under your
current directory named "website" in which all of website files will be
placed.

If you downloaded the tar gzipped version of GNUWorld use
the fallowing command to unpack the archive as fallows:

gzip -cd gnuworld.xxx.tar.gz | tar xf -

where xxx is the version of GNUWorld you have obtained.


************************************************************************************************************************
Section 1.2 * Building GNUWorld
************************************************************************************************************************

To build GNUWorld you need a complier that supports ANSI C++ Standart.
(gmake also recommended).
1- cd gnuworld

2- ./configure
(if you do not want to load all the modules but a specific one
use the following commands as needed)

CONFIGURE FOR ONLY THE CSERVICE CLIENT:
./configure --enable-modules=cservice
CONFIGURE FOR ONLY THE CCONTROL CLIENT:
./configure --enable-modules=ccontrol
CONFIGURE BOTH THE CSERVICE & CCONTROL MODULES:
./configure --enable-modules=cservice,ccontrol

Configure will build the Makefiles that GNUWorld will use to
compile its source.

3- make
This will build all the libraries and binaries.

4- make install
To install the binaries and library.

************************************************************************************************************************
Section 1.3 * Editing the config file
************************************************************************************************************************

Switch to the /bin directory and edit the localhost.conf

uplink = 25.202.242.30 # The server we will connect to
port = 5500 # The port we will connect to
password = santa # Our server password in Uplink's C: Line
name = channels.undernet.org # Our server name
description = Channel Service # The description will be seen in /links
numeric = 63 # Our server numeric (must be unique on the network)
maxclients = 50 # maxclients we can run


module = libcservice.la (related conf file)
module = libccontrol.la (related conf file)

Example:

module = libcservice.la cservice.conf
(This will load the cservice module and looks for cservice.conf file for its configration. If you have a
differnt name than cservice.conf, like X.conf etc. specify it here like : module = libcservice.la X.conf )

Don't touch the rest of the file for fine tuning.

************************************************************************************************************************
Section 1.4 * Running GNUWorld
************************************************************************************************************************

Simply type
./gnuworld -f localhost.conf

EOP ( End of Part :P )
************************************************************************************************************************
************************************************************************************************************************
************************************************************************************************************************


PART II - MANUAL.CSERVICE
CService module is used to maintain channels over the network and keep them open

********************************************************************************
Section 2.1 * Setting up cservice for the first time
********************************************************************************

We assume that pgSQL is running and configured and you have the right permissions to create and
modify a database.


1- Create the database for cservice module
>createdb cservice

(assume cservice database does not exist)

2- Install the PL Language
> createlang plpgsql cservice -L /usr/local/pgsql/lib

3- Switch to gnuworld/doc directory

4- Load the schema
> psql cservice


> psql cservice
> psql cservice
> psql cservice

5- Add the administrator account
> psql cservice

This will create an account with level 1000 on channel "*"
NOTE: "*" is not a physical channel that you can not /join it.

6- Connect to the IRC Server and login to your admin account.

Username: Admin
Password: temPass

Be sure to change your password.


************************************************************************************************************************
Section 2.2 * Example conf file
************************************************************************************************************************

The default conf file is cservice.conf. You can find it under /bin directory.

sql_host = 127.0.0.1 # Hostname/IP of PostGreSQL server
sql_port = 5432 # Port of PostGreSQL server
sql_db = Database name
(If you did everything as we told you it have to be cmaster,sql_db = cservice )

sql_user = gnuworld # sql_user is the username to pass to PostGreSQL
on connection.Usefull if your accoount name is
not the same as your Database username.

nickname = E42-b # Bot name (X on Undernet)
username = cservice # Bot username (Cservice on Undernet)
hostname = undernet.org # Bot Hostname (undernet.org on Undernet)
userdescription = # Client description For help type: /msg X help
mode = +idk # Usermodes

relay_channel = #cmaster.info # Channel to relay useful information.

debug_channel = #cmaster.debug # Channel to relay debug information.

You can get info about other values in the conf file itself.


************************************************************************************************************************
Section 2.3 * Adding Extra level 1000 admin accounts.
************************************************************************************************************************

Adding extra 1000's has two ways. First one is adding them directly to the database and second one is editing
cservice.addme.sql file and loading it with: psql cservice

Its suggested that, add any extra level 1000 accounts before adding any new channels/usernames to database.


INSERT into users (user_name,password,language_id,last_updated)
VALUES ('the_user_name','07d976a29bdb3ff42e10c102852151b28097bbad',1,now()::abstime::int4);

INSERT into levels (channel_id,user_id,access,last_updated)
VALUES (1,the_user_id,1000,now()::abstime::int4);

* the_user_name should be the username will be added with level 1000

* the_user_id should be the "current users +1". If you only added the admin
account it should be 2 now. When adding a third person it should be 3
and go on...

The password of the newuser will be temPass again.

Change the values in cservice.addme.sql and load it with the command above or switch to
pgsql's directory (default is /usr/local/pgsql/bin) type psql and hit enter.
After that copy and paste the changed values (the ones above)into the shell and hit enter.

EOP
************************************************************************************************************************
************************************************************************************************************************
************************************************************************************************************************

PART III - MANUAL.CCONTROL

CControl is an IRC Operator Service which is also in use on Undernet now.
This part dedicated to ccontrol :P

********************************************************************************
Section 3.1 * Setting up ccontrol module for the first time
********************************************************************************

Follow these steps to setup the database for the ccontrol module. This
file assumes that postgresql is running and configured, and that you have
access to add and modify databases within it.

1- Create the database if you didn't do it before
> createdb ccontrol

2- Switch to doc directory
cd doc

3- Load the schema
> psql ccontrol < ccontrol.sql
> psql ccontrol < ccontrol.help.sql

4- Add yourself to the bot
> psql ccontrol < ccontrol.addme.sql

This will add the user Admin with *!*@* hostmask and all the commands enabled.
Handle: Admin password: temPass
(This script should be run once and before any modifications to database)

Do NOT forget to change your hostmask for your needs after your first login.
You can get more info by: /msg bot help modoper

********************************************************************************
Section 3.2 * Editing ccontrol.conf file
********************************************************************************

The default conf file is ccontrol.conf you can find it under /bin directory

sql_host = 127.0.0.1 # Host/IP of the PostGreSQL server
sql_port = 5432 # Port of SQL server
sql_db = database name (default ccontrol)

## Bot Info ##

username = KWorld2 # Bot's username
nickname = KWorld2 # Bot's nickname
hostname = KWorld2.krushnet.org # Bot's hostname
userdescription = KWorld2 # Information seen in /whois
operchanmodes = +isn # IRC Operator channel modes to set
mode = +iodkw # Default Bot modes
operchan = #valhalla # IRC Operator channel
msgchan = #gnuworld.message # Channel where useful info relayed
glength = 3600 # Default gline length (in seconds)
operchanreason = Oper only channel # Default reason for adding an oper chan
abuse_mail = abuse@yournet.org # the email that the report should be emailed to
ccemail = ccontrol@yournet.org # the email that ccontrol will put in the from field of the report
sendmail = /usr/sbin/sendmail # Full path to the sendmail program
mail_report = 0 # set 1 for the bot to mail the report , 0 if you dont want a report to be mailed
gline_interval = 3600 # the interval in which ccontrol should check for expired glines
max_connection = 5 # the maximum connections a host can have before glined
max_GLen = 86400 # the length of the gline the for excessive connection (in seconds)


EOP
************************************************************************************************************************
************************************************************************************************************************
************************************************************************************************************************

PART IV - MANUAL.GNUWORLD

Here is the part where everybody is waiting for...

********************************************************************************
Section 4.1 * Obtaining Apache Web Server & PHP interpreter
********************************************************************************

You can get the latest relase of apache web server at:
http://httpd:apache.org/distbinaries/linux/

You can get the latest relase of PHP interpreter at:
http://www.php.net


********************************************************************************
Section 4.2 * Compiling Apache Web Server & PHP interpreter
********************************************************************************

Be sure that Complete Source Codes of both these are in the same directory.
Name of the apache should be something like that: apapche_1.3.x.tar.gz

1- After downloading the latest version of Apache untar it:
> gunzip -c apache_1.3.x.tar.gz | tar -xf
where x is the version you have just downloaded.
2- Unpack the php-4.0.x.tar.gz file
> gunzip -c php-4.0.x.tar.gz | tar -xf
again x is the version info.

After these two steps we have two new directories. One for Apache and one for PHP.
Now let's switch to apache and configure it

3- After you unpack, switch to Apache's directory.
cd apache_1.3.x

4- Run the configure script:
./configure

5- Then part apache's directory
cd ..

It's PHP interpreters turn now... Well performance is important for us so we will
use module installation of PHP. And we will use Static Module where we insert
PHP into Apache. They will work like 1 program :)

6- Switch to PHP's directory
cd php-4.0.x
7- And configure it:
./configure-with-pgsql-with-apache=../apache_1.3.x-enable-track-vars
!!! IMPORTANT !!!
After "apache=" specify the directory of apache...
8- If you want to use PHP with graphics also you will need GD Library
like we insert apache and pgsql support with "-with" tag we will insert
GD library with "-with-gd"
./configure-with-pgsql-with-gd-with-apache=../apache_1.3.x-enable-track-vars

9- Make and install it (depends on your box this will take 2-8 minutes)
make
make install


After compiling switch back to Apache's directory

10- cd ../apache_1.3.x

11- Configure it
./configure-prefix=/www-active-module=src/modules/php4/libphp4.a

the -prefix=/www paramater tells where to install apache. If you want to install it to /home/httpd
than you have to use -prefix=/home/httpd

12- make and install again (this time apache)
make
make install

13- After that copy the php.ini file to /usr/local/lib/ and edit it with a text editor.
cd ../php-4.0.x
cp php.ini-dist /usr/local/lib/php.ini

14- Now add some little info to apache's conf file (httpd.conf) for PHP.
you can find that file under apache_1.3.x/conf/

Addtype application/x-httpd-php .php
Addtype application/x-httpd-php .php3
Addtype application/x-httpd-php .php4

15- Pray to god and start apache
./apactrl start

16- To check if its running type:
ps -aux | grep 'httpd'



********************************************************************************
Section 4.3 * Configuring Apache & PHP interpreter
********************************************************************************

This section includes the *must* variables you have to set in apache and php's conf
files before you run them... For more details of conf file of Apache see Section 4.5

To run apache properly you have to set some variables in httpd.conf. You can find this
file under /conf directory of apache. Simply open httpd.conf with a text editor

!!!IMPORTANT!!! Edit these variables to suit your needs. Do not copy paste.

ServerRoot "/www" -- The top directory which server conf files and error files kept.
KeepAlive On -- To allow persistant connectios. On or Off. GNUWorld needs this value on.
ServerAdmin you@yournet -- The Server Administrator's info
Port 80 -- The listening port for standalone servers.
DocumentRoot "/home/root" -- The directory out of which you will serve your documents.
By default, all requests are taken from this directory,
but symbolic links and aliases may be used to point to other locations.

ServerName "www.your.net" -- Specifies your server's name. In older relases apache won't run if you
do not define this.

-- This should be the same as DocumentRoot.

*****************************

in the php.ini file edit these

[PostgresSQL]
; Allow or prevent persistent links.
pgsql.allow_persistent = On

[extension_dir]
; Directory in which the loadable extensions (modules) reside.
extension_dir = ./


This is the basic stuff for apache and php. If you have more questions come and ask in #coder-com
But do not forget we are not apache experts but couple of ppl coding for Undernet on our free
times.

********************************************************************************
Section 4.4 * Editing config.inc file
********************************************************************************

Config.inc file is the only file you have to EDIT for your *very own* customized
Web Interface. If you don't have PHP experience don't play with the other files
that you might have screw them up.

define(LIVE_LOCATION,"/live"); define this to "" if you dont put it in a subdirectory like '/live' (default) but in '/' for example.
define(IFACE_URL,"http://cservice.undernet.org/live/"); // The GUI main URL (the one to access it)
define(SERVICE_CHANNEL,"#cservice"); // The CService Official Channel

/* NOTE: to FORGE reply adresses, user 'nobody' needs a 'Tnobody' line added in /etc/sendmail.cf (or equiv.) */
define(NETWORK_NAME,"Undernet"); // Define this to your network name... better to be a "normal" single word ;)
define(BOT_NAME,"X"); // You bot's name, defines some strings in the website to fit more your configuration.
define(IRC_SERVER,"irc.undernet.org"); // Default server for irc:// option.
define(NETWORK_EMAIL,"cservice@undernet.org"); // the email of your network (default).

define(PURGE_EMAIL,"purge@undernet.org"); // the email where channel purge request form is sent.
define(XAT_EMAIL,"x@undernet.org"); // the email where manager change form is sent.

define(FROM_NEWUSER,"cmaster@undernet.org"); // the From: email for a NEWUSER registration email.
define(FROM_NEWUSER_SUBJECT,"Your Undernet Channel Service Account"); // the subject of that mail.

define(FROM_FPASS,"cmaster-recovery@undernet.org"); // the From: email for a FORGOTTEN PASSWORD email.
define(FROM_FPASS_SUBJECT,"Your Undernet Channel Service Password for "); // the sujbect of that mail. 'username' is added at this string's end.

/******************************/
/* LOCAL DATABASE DEFINITIONS */
/******************************/
define(LOCALDB_NAME,"local_db"); // the local database that contains the gnuworld/doc/local_db.sql information.
define(LOCALDB_USER,"gnuworld"); // the local user that has full access to LOCALDB_NAME.
define(LOCALDB_PASS,""); // the password, use blank if you dont use passwords.

/*******************************/
/* REMOTE DATABASE DEFINITIONS */
/*******************************/
define(REMOTEDB_NAME,"cservice"); // the remote databasr that contains cservice.sql, cservice.web.sql information.
define(REMOTEDB_USER,"gnuworld"); // the user that has access remotely to that db
define(REMOTEDB_PASS,""); // the password, use blank if you dont use passwords.
define(REMOTEDB_HOST,"127.0.0.1"); // define to whatever host/IP of the "remote" db is.

/*******************************/
/* LOCAL WEBSITE CONFIGURATION */
/*******************************/
define(HEAD_LOGO,"cservice-head.jpg"); // this points to an existing image in website/docs/gnuworld/images. 59 pixels max height.
define(HOSTING_LOGO,""); // this image should go in website/docs/gnuworld/images and be maximum 250*33 pixels.
define(HOSTING_URL,"");

define(CSERVICE_SITE_URL,"../");

those options are only used when using multiple mirrors of your CService website
if you dont do mirrors at all, just leave those options as they are, this wont affect anything.
if you do mirrors, the following options means that if the website is accessed with "ROUNDROBIN",
it will automatically redirect accesses to "LOCALMIRROR".

define(LOCALMIRROR,"cservice-live.xx.undernet.org");
define(ROUNDROBIN,"cservice-live.undernet.org");


/* IP CHECK OPTIONS */

define(IPCHK_MAXHITS,3); // Number of failed forgotten_pass/login attempts before IP_LOCK
define(IPCHK_BANTIME,86400); // Time your IP/username is locked (seconds) when caught into IPCHK_MAXHITS+ failed attempts.

define(LREQ_TIME,600); // min time between forgotten password requests to avoid flooding, set this to 0 to disable.
define(UNETUB_TIME,14400); // 4 hours before being able to create another user from the same IP. set to 0 to disable.



!!!! DONT FORGET TO REMOVE THE LAST LINE ON THE CONFIG.INC OR IT WILL NOT WORK... !!!!




For More questions you know what to do !!! Send them to me and I will add them on the next relase of this help file.


EOP
************************************************************************************************************************
************************************************************************************************************************
************************************************************************************************************************

PART V - PostGre Short Installation

This is the file that you can find also in the INSTALL file.
If you have questions please send them to cti@zurna.org
and I will add them to FAQ's when I do it. Cti-

(You have to switch to Super User -Root- to do these steps)

./configure
gmake
gmake install
adduser postgres
su - postgres
/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data >logfile 2>&1 &
adduser cmaster

When it asked you "this user can add other users? y/n" Hit no (or yes)
and when it asked "this user can create databases" hit YES

After that switch to cmaster ( or whatever your username is)
and type /usr/local/pgsql/bin createdb cmaster (or what you want your database name to be)

And its ready now !!!!

[Go Back] - [Maintainer]