diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 668 |
1 files changed, 668 insertions, 0 deletions
@@ -0,0 +1,668 @@ +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 + +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! |