path: root/README

yChat; Homepage: ychat.buetow.org; Version 0.9.0-CURRENT

Copyright (C) 2003 Paul C. Buetow, Volker Richter
Copyright (C) 2004 Paul C. Buetow
Copyright (C) 2005 EXA Digital Solutions GbR
Copyright (C) 2006, 2007 Paul C. Buetow
-----------------------------------------------------------------
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
-----------------------------------------------------------------

YCHAT TABLE OF CONTENTS: 

1.0.0 GENERAL
1.1.0 ABOUT RELEASES 
1.2.0 YCHAT FEATURES //<<
2.0.0 INSTALLATION AND SETUP
2.1.0 REQUIREMENTS
2.2.0 TESTED PLATFORMS
2.3.0 HOW TO OBTAIN YCHAT
2.4.0 INSTALLATION QUICK-START
2.4.1 INSTALLATION
2.5.0 HOW TO USE OPENSSL WITH YCHAT
2.5.1 HOW TO USE SCREEN WITH YCHAT
2.5.2 HOW TO USE SIGNALS WITH YCHAT
2.5.3 HOW TO USE GNU READLINE WITH YCHAT
2.5.4 HOW TO USE MYSQL WITH YCHAT //<<
2.6.0 CUSTOMIZING YCHAT
2.7.0 YHTTPD CODE BASE GENERATION //<<
3.0.0 EXTENDING YCHAT
3.1.0 SOURCE FILES
4.0.0 DIVERSE 
4.1.0 WRITING BUG REPORTS
4.2.0 CONTACT ADDRESSES
4.3.0 CREDITS

1.0.0 GENERAL

1.1.0 ABOUT RELEASES 

There are several projects involved:

- The chat -
Its a HTTP based chat server written in C++. Clients are normal web browsers 
such as MSIE or Gecko based browsers using only CSS, HTML and JavaScript. 

- The httpd -
Its a small http server based on the chat's socket and threading engine.
yhttpd does not have as much features but is easy to use and faster than
apache. yhttpd is a subset of the chat. It can be generated using the
srcipts/yhttpdbase.pl script in the chat's source tree. 

There are different branches:

- CURRENT - 
The CURRENT branch is unstable, this is the bleeding developing edge with 
all the new experimental features.

A RELEASE of CURRENT can be referred as CURRENTRELEASE.

- STABLE -
The STABLE branch is more stable than CURRENT. This branch may get new
features as well. But those will be more conservative compared to 
CURRENT.

A RELEASE of STABLE can be referred as STABLERELEASE.

- BASIC -
The BASIC branch is a very minimal one. This branch may get bugfixes and
updates and might get minor improvements. This is a version of yChat
with only very few features.  

A RELEASE of BASIC can be referred as BASICRELEASE.

- LEGACY -
The LEGACY branch has no real support. This branch may get bugfixes and
updates and might get minor improvements. But there is no garuantee to
be bug free and stable at all. LEGACY versions are of historic meaning. 

- DEVEL -
DEVEL is only a meta name. If a version is labeled with DEVEL, then its
currently undefined if this is a CURRENT, STABLE or LEGACY branch. It
can be everything. Commonly DEVEL versions are CURRENT. 

There are also releases made:

- RELEASE -
There can be RELEASEs made out of each branch. While a branch can get
new features, a RELEASE can not. A RELEASE of a branch is just like
a snapshot. RELEASEs are complete versions to test and use. But keep
in mind, that a RELEASE of the STABLE branch is recommended over a
RELEASE of a CURRENT or a LEGACY branch in a production environment.
RELEASEs of CURRENT are still the bleeding edge and RELEASEs of LEGACY
may be out of date.

- Short names -

In addition, each description also has short names: (short names are needed 
if your text space is limited which happens very fast in IRC channel topics)

CURRENT aka CUR aka C
RELEASE aka REL aka R
LEGACY  aka LEG aka L
STABLE  aka SBL aka S
BASIC	aka BSC aka B
DEVEL   aka DEV aka D
PRE     aka P

STABLERELEASE aka STBREL aka SR
PRERELEASE aka PREREL aka PR
PRELEGACYRELEASE aka PRELEGREL aka PLR
etc...

The short name of the chat is "yC"
The short name of the httpd is "yh"

- Versioning - 
In general, versions are made up like X.Y.Z.W. X specifies the major version,
Y specifies the branch of the major version, Z specifies a sub revision
of a specific branch. The optional W can be used to specify a maintenance
revision which only changes small issues. 

//<<*
1.2.0 YCHAT FEATURES

- Its free & portable -
yChat is developed under the GNU general public license and is based on GNU 
tools (gcc, gmake), other open source library stuff (such as GNU Readline etc.)
and should run on any POSIX capable operating system (such as all Linux based 
systems, FreeBSD, NetBSD, OpenBSD and other BSD-Systems and on UNICES like 
IRIX, HP-UX, Solaris etc.).

- There is no need for special chat clients -
yChat is web based, that means clients may only connect to the chat server 
with an normal web browser such as Microsoft Internet Explorer or any Gecko-
Engine powerd browsers like Mozilla, Firefox, Camino etc.

- It has features of a real HTTP webserver -
yChat runs completely stand alone and does not need another webserver to build
on like Apache and does not need to be run via any kind of CGI. yChat creates 
its own socket on a customized port (standard port: 2000) and seems to be a full
featured HTTP web server to the clients (web browsers). 

The yChat code base can be converted to an yhttpd code base automaticaly. yhttpd
is the webserver subset of yChat which runs completely stand alone and provides
normal websites to the net. It also supports Common Gateway Interface (CGI)
scripting.

- Its fast and secure -
yChat is written in C++ which is faster than any Java based Chat-Server or any
server written in a scripting language like PHP, Python or Perl. As the
internal data structures hash maps are used to garuantee searching certain
values in O(1) amount of time. If a hash maps gets full, it will be rehashed.
Currently, yChat has been measured providing over 1000 hits/requests per second 
on a FreeBSD based server box while using less than 2% of CPU usage
on a Athlon XP 1900+. Performance seems to be limited by your bandwith only. 
Also, each user gets its own session id (random string) with a standard length 
of 50 chars to authenticate each logged in user. The length of the session id 
can be redefined as well. Also, the session id will get md5-hashed optionally 
so thats even harder to reverse engineering the session ids of other users.
Also, yChat supports secure hypertext transfer protocol (HTTPS) connections
using the OpenSSL library. Then, all chat messages will be encrypted in a
secure manner. HTTPS is optional to HTTP (unsecured connections). 

- Its HTML template based and easy to customize via XML based configuration -
All HTML sites are predefined as HTML-Template files and can be easily modified
to use with an customized web design. Also, a lot of yChat preferences can be
set in the main configuration file (ychat.conf). ychat.conf is completely written
in XML 1.0 which makes it easier to use the configuration options in programs of
3rd persons which may want to write some usefull tools for yChat.
yChat caches all HTML and web images to improve overall performance. If needed, the
cache can be cleared to recache new versions of the template files.

- Its language template based -
The administrator can easily create a new language in which all system messages
appear to the Chat-User. The predefined languages is english but others can be
added easily. The language can be edited in the XML based configuration file.

- MySQL based database -
Registered users are stored in a MySQL database. C++ Programmers may feel free
to replace the database wrapper class (data.h) with another database routines
to use other databases such as PostgreSQL, SQLite or a text based database etc.
If wished, you can disable database support in the pre-compile options.

- It has an administration interface -
yChat includes an libreadline based administration interface which tracks some
interesting statistics and system messages and enables you to do certain
administrative tasks like keeping track of the current system usage etc.
If you dont like libreadline you can disable both options in the pre-compile
options. 

- It has logging capabilities -
The logging manager keeps track to all yChat system messages (such as users 
wich log in and out, modules which are loaded, MySQL queries etc.). Also, an
Apache-Style combined log file format is created by yChat (you can parse this
logfile with any Apache logfile parser like awstats etc.). And last but not
least, all public messages of all available rooms will be logged to disk as 
well . To improve performance, you can define the logging puffer (standardly
new logs will be written to disk after each 20 lines). If you want to log
everything immediately, you can reset this option to 1 in ychat.conf.

- Its modular through own command and dynamic HTML engine -
All chat commands are realized through dynamic loadable module files which can
be recompiled and reloaded without restarting the whole yChat server. Also 
HTML-Sites with certain tasks can be compiled as a module like 
mods/html/yc_register.so, mods/html/yc_options.so and mods/html/yc_colors.so
etc. so you can also program your dynamic yChat websites in C++.

- Its multi threaded (POSIX threads) -
There is only one main process which spawns several threads, each for its own
unique task. For example one thread is used to handle the servers's events.
(see libevent) Another thread is used to control the libreadline based 
administration command line interface.

- Its event driven (libevent) -
yChat is event driven. Non-blocking sockets are used to serve the client
requests. In contrast do a multi-threaded based client handling, this approach
is more effective on single processor systems and there is no complex mutex
structure inside of the code which leads to much cleaner and easier code
design. The libevent controls all read/write operations of the server and also
does handle signal and timer events. The timer events prove if clients are still 
active and frees not needed memory in certain time intervals (see also "Garbage 
collector") and does some other continuous tasks.

- Its using a smart garbage collection engine -
All users and rooms which dont have to be kept in the main memory (because the
user has logged out or the room has been destroyed because it was empty) will
not be deleted immediately but be placed for about 10 minutes in the yChat
garbage collector. Each time a new room is created the systems checks the
garbage to reuse an inactive room object. If a certain user wants to log in, the
system checks if he is already present in the garbage collector. If yes, he will
be reactivated without wasting expensive database queries to fetch the user's
options. This improves overall performance on heavily loaded yChat servers if a
lot of user and room objects are created and destroyed frequently.
//*>>

2.0.0 INSTALLATION AND SETUP

2.1.0 REQUIREMENTS: 

- GNU GCC G++  
  The GNU C++ compiler version 4.2.1 or up.

- GNU make 3.80 (gmake) or higher
  If you dont have a gmake executable but make is gnu make then you need
  to add a symlink or alias from gmake to make.
  yChat Makefiles only have been tested with GNU make and may not work with
  other make versions.

- SGI STL extension 
  Includes ext/hash_map which may be already default on every Linux distro.
  On *BSD you have to install it first before compiling. On FreeBSD
  /usr/ports/devel/stlport is your friend.

- OpenSSL (optional)
  Includes libssl and the ssl header files of the open source SSL library. 
  OpenSSL is only needed if you chose to compile yChat w/OpenSSL support. 

- GNU Readline (optional)
  This library can be used with the command line interface (CLI) of 
  ychat to make the editing easier. 

//<<*
- mysql-client 4.x (optional) [3.x may do too but is not supported]
  Includes libmysqlclient and the mysql.h header files. mysql-client is only
  needed if you chose to compile yChat w/database support.
//*>>

- Screen (optional)
  Only needed if yChat should run in background with
  the CLI enabled.

- Perl 5.x
  Is needed for some scripts. Is not needed if you use precompiled binaries.

2.2.0 TESTED PLATFORMS:

The following platforms have been tested with success. If you find out that
a listed platform did not work at all please contact me:

  Operating system (arch)	GNU G++		GNU make
- FreeBSD 7.0-BETA2 (i386)		4.2.1		3.81

  Tested longer time before:
- FreeBSD 6.2-RELEASE (amd64)	3.4.6		3.81	
- FreeBSD 6.0-RELEASE (i386)	3.4.4		3.80	
- FreeBSD 5.3-RELEASE (i386)	3.4.2		3.80
- FreeBSD 5.4-RELEASE (i386)	3.4.2		3.80
- FreeBSD 4.10-RELEASE (i386)	3.4.1		3.80
- Gentoo Linux 2004 (i386)	3.3.2		3.80
- OpenBSD 3.6 SMP (i386)	3.3.2		3.80
- Red Hat Linux 8.0 SMP	(i386)	3.2-7		3.79
- Slackware Linux 10.0 (i386)	3.4.0		3.80 
- SUSE Linux 9.0 (i386)		3.3.1		3.80
- SUSE Linux 8.1 (i386)		3.2		3.79.1

Other platforms like Linux based systems, other BSD-Systems or UNICES
are very likely to work too. 

2.3.0 HOW TO OBTAIN YCHAT:

For SVN download type:

svn co --username=anon http://svn.buetow.org/repos/ychat/trunk

Now you may continue with the installation.

There are different branches in the CVS:

ychat: This is the latest CURRENT branch of yChat.
ychat-stable: This is the latest STABLE branch of yChat.
ychat-X.Y: This is the branch with the specified version prefix.
yhttpd: This is the latest CURRENT snapshot of yhttpd.

The CURRENT branch of ychat is mostly untested and unstable, so don't 
cry if you get errors.

2.4.0 INSTALLATION QUICK START

If you in hury, then you may just run the following commands:

  sh -c 'CXXFLAGS="" ./configure'
  gmake install clean

yChat will get compiled without debugging symbols and its default values. 
Afterwards yChat will get installed into the default prefix which is 
/usr/local.  Afterwards it is ready to run with the '/usr/local/bin/ychat'
command! 

2.4.1 INSTALLATION

If you wanna quick start, then please refer to section 2.4.0 instead.

Invoke './configure --help'. Afterwards you will get prompted with all the 
possible compile options. Take a closer look at the --enable-FEATURE and the
--disable-FEATURE options. Afterwards run configure with your wanted options.
Now, you can run 'gmake'. See below what gmake is doing. By default yChat uses
loosy debugging symbols. To disable them, then run configure this way:

  sh -c 'CXXFLAGS="" ./configure --options' 

Dont forget to replace --options with your desired values. You can read more
about debugging symbols in section '4.1.0 WRITING BUG REPORTS'.

//<<*
If you have choosen MySQL database support, then take a look at section 1.3.2 
how to setup a valid database table. Be also sure to enter the valid MySQL 
accessing data in the yChat configuration file which is normally located in 
the etc/ychat.conf file.
//*>>

You may also invoke gmake with the following options:

 gmake or gmake all (compiles everything, also modules and runs "gmake mail")
 gmake base (only compiles the base)
 gmake base_start (only compiles the base and starts the server)
 gmake build (increments the current build number by one)
 gmake clean (cleans everything)
 gmake clean_base (only cleans the base obj and rpo files)
 gmake clean_modules (only cleans the modules .so files) 
 gmake confdebug (runs the configure with strong debugging symboles enabled) 
 gmake debug (runs gdb on ./ychat.core)
 gmake deinstall (same as gmake uninstall)
 gmake dist (creates a .tar.bz2 ball)
 gmake headers (rewrites the source file headers using doc/header.txt)
 gmake help (shows all available yChat gmake targets)
 gmake install (removes debugging symbols and installs yChat into the PREFIX)
 gmake license (shows the GNU General Public License)		
 gmake modules (only compiles modules)
 gmake mrproper (same as gmake clean plus removing all temp files) 
 gmake quick (runs all configure scripts and afterwards gmake all)
 gmake replace (replace in the source the content of $FROM into $INTO)
 gmake stats (generates yChat statistics)
 gmake strip (removes debugging symbols from binary)
 gmake ssltest (generates a self signed ssl test certificate)
 gmake touch (resets the date of each file in the source tree)
 gmake uninstall (uninstalls yChat from the current default PREFIX)
 gmake version (shows the current version of yChat)
//<<*
 gmake yhttpdbase (generates an yhttpd code base)
//*>> (See section 1.9 to read about this marks)

Example: 'gmake all install clean' compiles everything, installs it to PREFIX
and cleans the source directories.

Now its time to run the server with './bin/ychat'.

Aferwards point your webbrowser to http://yourip:port !

... have fun :-).

2.5.0 HOW TO USE OPENSSL WITH YCHAT

If you chose to use OpenSSL support you have to have a valid SSL private and
public key. If you are in hurry, use the gmake ssltest command from the top
source tree directory and follow the instructions. Otherwise type the
following commands manually:

The private key can be created w/the following command:

  openssl genrsa -des3 -out privkey.pem 2048

Afterwards, you can create a self-signed test certificate using the following
command: 

  openssl req -new -x509 -key privkey.pem -out cert.pem -days 1095

Be sure to move the privkey.pem and cert.pem files into the ./etc directory
or edit the path names in the ./etc/ychat.conf file. yChat wont start if there
are no valid files found.

To learn more about SSL certificates, visit http://www.openssl.org/docs/HOWTO/.

Now use https:// and NOT http:// to connect to the yChat server.

2.5.1 HOW TO USE SCREEN WITH YCHAT:

If you are running yChat in CLI mode you might want to install
the tool which is called "screen". This will enable you putting the
CLI interface into the background, closing the terminal session
and reusing the interface later through another terminal. 

Just do:
 
 screen -S ychat ./bin/ychat ( creates a new session and starts yChat in it )
 ctrl+d+a ( will detach the yChat session )
 ( closing the terminal )
 ( opening a new terminal )
 screen -r ychat ( will return you to the yChat process )

Screen will terminate automaticaly if all processes in its sessions are 
terminated.

For a closer look read the screen manual page ( man screen ). 

2.5.2 HOW TO USE SIGNALS WITH YCHAT:

You can send UNIX signals to yChat. This becomes very interesting if you 
don't use the command line interface and you don't have access to the options 
below.

Run one of the following commands to send the signal you want: 
($PID is here the process id of the current yChat process)

kill -USR1 $PID # yChat clears the HTML template cache 
kill -USR2 $PID # yChat reloads all dynamic loadable modules //<< 
kill -HUP  $PID # yChat will shutdown savely

2.5.3 HOW TO USE GNU READLINE WITH YCHAT:

This library can be used with the command line interface (CLI) of ychat. To 
use it, yChat has to be compiled with readline support (which is the default
setting).

Readline offers editing capabilities while the  user  is  entering  the line.
By default, the line editing commands are similar to those of emacs.  A vi-style
line editing interface is also available.

For configuration and usage of the yChat readline CLI prompt, read the readline
manpage. :)

//<<*
2.5.4 HOW TO USE MYSQL WITH YCHAT

If you chose to use MySQL database support you have to create a valid database
to use with yChat.

Create a new MySQL database called 'ychat' and type the following command into
a MySQL command line client of your choice:

USE ychat
CREATE TABLE `user` ( 
  `uid` int(10) NOT NULL auto_increment, 
  `nick` varchar(30) NOT NULL default '', 
  `password` varchar(30) NOT NULL default '', 
  `color1` varchar(30),
  `color2` varchar(30),
  `email` varchar(50) default '-', 
  `registerdate` varchar(30) default '-', 
  `logincounter` varchar(10) default '0', 
  `status` char(1) default '3', 
  PRIMARY KEY  (`uid`), 
  KEY `uid` (`uid`) 
) TYPE=MyISAM;
GRANT ALL PRIVILEGES ON ychat.* to ychat@localhost IDENTIFIED BY "yctest";

This database uses the default MySQL access informations which are stored in the
ychat.conf file.
//*>>

2.6.0 CUSTOMIZING YCHAT:

If you like to customize the design/layout/language of yChat, you will have 
to edit ./src/msgs.h and ./src/glob.h before you compile the sources. Afterwards 
you can change the html-template files which are placed in the ./html/ 
subdirectory and the language-templates which are placed in the XML config 
file (etc/ychat.conf).

Notice, that you dont have to edit the ./src/glob.h file by hand any more, its
already done by the top ./configure script for you (See './configure --help').

You can edit the ./etc/ychat.conf to fit your needs. If you dont want to change
the config file, then you also can use ychat start parameters.

Exmpl: ./bin/ychat -o chat.database.password secretpassword

You can also use multiple words for a specific option.

Exmpl: ./bin/ychat -o ychat.version "word1 word2 word3"

will overwrite the default database password value of the ychat.conf. You can
do this with every configuration element by adding several -o option value 
arguments to the start command.

Dynamic loadable modules can be found in the ./mods/ subdirectory. (chat 
commands are realized through modules too). Sources of modules can be found
in ./src/mods instead. If you want to create a new module just create a new
.cpp file and run in ./src/mods the ./configure script again. Next time
you run 'gmake' or 'gmake modules' your new module gets compiled. 

All messages defined in the ./src/msgs.h file contain server messages only (a chat
user never wont read them, only the administrator will get to see them).

Read also section 3.0.0 of this README.

//<<*
2.7.0 YHTTPD CODE BASE GENERATION

See docs/yhttpd.txt
//*>>

3.0.0 EXTENDING YCHAT

3.1.0 SOURCE FILES

This list is not complete. Only the most important files are listed here!

./etc/ychat.conf  - The yChat configuration file
./html/*	- The html template files
./src/*		- The yChat base sources
./src/mods/*	- The dynamic loadable modules sources
./scripts/*	- Some nice scripts needed for building & co.

The following is created by building yChat:
./obj/*		- The object files of the compiled yChat base 
./mods/*	- The compiled dynamic loadable modules
./bin/ychat	- The yChat binary (linked by the object files)
./bin/ychat.bak	- An yChat binary of a previous build process

Customizable source files (if changed you need to run gmake clean all) 
./src/glob.h	- Contains some global building options
./src/msgs.h	- Defines some server side messages


4.0.0 DIVERSE 

4.1.0 WRITING BUG REPORTS

How to submit a good bug report?

Send them to Mail at yChat dot org.

First you should give the following information:
- yChat version, if CVS (or devel. tarball) then which day?
- operating system / distribution and it's version
- when did it crash? did you do something? can you reproduce the crash?

Getting backtrace of the crash also helps a lot, especially if yChat crashes 
randomly. If after crash you see text:

 "segmentation fault (core dumped)" 

It writes a file named 'core' or 'ychat.core' depending on your OS to directory
where you started yChat. If it doesn't print the '(core dumped)' or you can't
find the core file, you'll have to raise the limit for max. core file size
before running yChat. To do this, say:

 ulimit -c unlimited 

So, if you have the core file and GNU debugger (gdb), you can get the 
backtrace with:

 gdb ./bin/ychat ychat.core (or gmake debug instead)
 bt 

Paste all the lines starting from line having #0 at the beginning.

Here's an example session:

 in reqp::parse(thrd*, std::string, std::map<std::string, std::string, 
 std::less<std::string>, std::allocator<std::pair<std::string const, std::string> > >&) ()
 (gdb) bt
 #0 0x0805c287 in reqp::parse(thrd*, std::string, std::map<std::string, 
 std::string, std::less<std::string>, std::allocator<std::pair<std::string
 const, std::string> > >&) ()
 #1 0x0806060f in sock::read_write(thrd*, int) ()
 #2 0x080612ba in thrd::run() ()
 #3 0x0805a3b8 in pool::run_func(void*) ()
 #4 0x0805a375 in pool::tpool_thread(void*) ()
 #5 0x281d44ae in _thread_start () from /usr/lib/libc_r.so.5
 (gdb) 

If you dont get such a gdb output, you need to recompile the yChat using
debuggig symbols. You can do it this way:

  gmake clean_base base run

By default, ychat gets compiled with loosy debugging symbols. If you want to
get strong debugging symbols, then type:

  gmake confdebug clean_base base run

or if you didnt run a ./configure before, then type:

  sh -c 'CXXFLAGS="-g3 -ggdb" ./configure'; gmake clean_base base run

instead.

In order to remove all the debugging symbols, then just type 'gmake strip'
afterwards. If you use 'gmake install', then the binary will be stripped
automatically.

If you dont wanna compile with debugging symbols by default, then use this
command:

  sh -c 'CXXFLAGS="" ./configure'; gmake clean_base base run

4.2.0 CONTACT ADDRESSES

You may contact us through the following addresses:

- Homepage
  The yChat homepage is located at http://ychat.buetow.org

- E-Mail
  ychat at dev.buetow.org 
 
- IRC
  #coding at irc.german-elite.net  

4.2.0 CREDITS

Thanks to the following persons. Without them yChat would not be like today:

- Volker Richter <volker at exa-ds dot de> of EXA Digital Solutions GbR
  for adding initial MySQL support and lots of more code.

- Joshua Teitelbaum <joshuat at cryptomail.org> of CryptpMail.org for adding
  initial OpenSSL support and lots of security patches in the HTTP header
  handling.

- Ralf Huesing <ralf at stormbind (net)> for his nice rhttpd webserver which
  served as a nice libevent sample program! And also for his help mails
  concerning libevent!

- Dave K. (http://maligree.yi.org) for the nice JavaScript color selection
  menu!