diff options
Diffstat (limited to 'README')
| -rwxr-xr-x | README | 423 |
1 files changed, 279 insertions, 144 deletions
@@ -1,8 +1,9 @@ -yChat; Homepage: www.yChat.org; Version 0.5.3-RELEASE +yhttpd; Homepage: www.yChat.org; Version 0.7.2-RELEASE + Copyright (C) 2003 Paul C. Buetow, Volker Richter -Copyright (C) 2005 Paul C. Buetow +Copyright (C) 2004 Paul C. Buetow +Copyright (C) 2005 EXA Digital Solutions GbR ----------------------------------------------------------------- - 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 @@ -16,224 +17,335 @@ 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. - ----------------------------------------------------------------- -0.0.0 LEGACY YCHAT 0.5 TABLE OF CONTENTS -1.0.0 REQUIREMENTS -1.1.0 TESTED PLATFORMS -1.2.0 IMPORTANT NOTES -1.3.0 HOW TO OBTAIN YCHAT -1.3.1 INSTALLATION -1.5.0 CUSTOMIZATION -1.6.0 FILES -1.7.0 WRITING BUG REPORTS -1.8.0 CONTACT +YHTTPD TABLE OF CONTENTS: + +0.0 ABOUT DEVELS +1.0 REQUIREMENTS +1.1 TESTED PLATFORMS +1.2 IMPORTANT NOTICES +1.3 HOW TO OBTAIN YHTTPD +1.3 INSTALLATION +1.3 INSTALLATION QUICK-START +1.4 HOW TO USE SCREEN WITH YHTTPD +1.4 HOW TO USE SIGNALS WITH YHTTPD +1.5 CUSTOMIZATION +1.6 FILES +1.7 WRITING BUG REPORTS +1.8 CONTACT +2.0 CREDITS + +0.0 ABOUT DEVELS + +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. + +- The ycurses - +ycurses is a easy to use and small C++ wrapper of the C ncurses API. + +There are different branches: + +- CURRENT - +The CURRENT branch is unstable, this is the bleeding developing edge with +all the new experimental features. + +A DEVEL of CURRENT can be referred as CURRENTDEVEL. + +- 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 DEVEL of STABLE can be referred as STABLEDEVEL. + +- 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: + +- DEVEL - +There can be DEVELs made out of each branch. While a branch can get +new features, a DEVEL can not. A DEVEL of a branch is just like +a snapshot. DEVELs are complete versions to test and use. But keep +in mind, that a DEVEL of the STABLE branch is recommended over a +DEVEL of a CURRENT or a LEGACY branch in a production environment. +DEVELs of CURRENT are still the bleeding edge and DEVELs of LEGACY +may be out of date. + + +1.0 REQUIREMENTS: -1.0.0 REQUIREMENTS: +- GNU GCC G++ + The GNU C++ compiler version 3.1 or up. -- gcc 3.x - The GNU C++ compiler. +- 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. + yhttpd Makefiles only have been tested with GNU make and may not work with + other make versions. -1.1.0 TESTED PLATFORMS: +- 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. -The following platforms have been tested with success: +- ncurses 5.x + Includes libncurses and the ncurses.h header files. -- Linux with GCC 3.2.0, GNU make 3.79.1 -- FreeBSD 5.1-RELEASE-p2, GCC 3.2.2, GNU make 3.80 -- FreeBSD 5.3-RELEASE, GCC 3.4, GNU make 3.80 +- Screen + Only needed if yhttpd should run in background with + ncurses or CLI enabled. -1.2.0 IMPORTANT NOTES: +- Perl 5.x + Is needed for some scripts. Is not needed if you use precompiled binaries. + +1.1 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 5.3-DEVEL (i386) 3.4 3.80 + + Tested longer time before: +- FreeBSD 5.2-DEVEL (i386) 3.3 3.80 +- FreeBSD 4.10-DEVEL (i386) 3.4 3.80 +- FreeBSD 4.9-DEVEL (i386) 3.3 3.80 +- Gentoo Linux 2004 (i386) 3.3 3.80 +- OpenBSD 3.6 SMP (i386) 3.3 3.80 +- Red Hat Linux 8.0 SMP (i386) 3.2-7 3.79 +- Slackware Linux 10.0 (i386) 3.4 3.80 +- SUSE Linux 9.0 (i386) 3.3 3.80 +- SUSE Linux 8.1 (i386) 3.2 3.79 + +Other platforms like Linux based systems, other BSD-Systems or UNICES +are very likely to work too. + +1.2 IMPORTANT NOTICES: Before you compile the source you have to be sure to use at least GCC -version 3.x with pthreads enabled. ( Type gcc -v to check it ). -GCC 2.95 did not work while testing on linux and WON'T BE SUPPORTED! -If you like to support yChat please write us an email and tell what -you can/like/would help ;-]. Please also take a look at the yChat +version 3.1 with pthreads enabled. ( Type gcc -v to check it ). +GCC 2.95 and 3.0 did not work while testing and WON'T BE SUPPORTED! +If you like to support yhttpd, please write us an email and tell what +you can/like/would help ;-]. Please also take a look at the yhttpd homepage which is located at http://www.yChat.org. -1.3.0 HOW TO OBTAIN YCHAT: +1.3 HOW TO OBTAIN YHTTPD: -yChat can be downloaded as a source package or through CVS. +yhttpd can be downloaded as a source package or through CVS. The packages are located at http://www.yChat.org -> Sourcecode -> -Packages or go to http://programming.buetow.org/CPP-yChat . +Packages or go to http://pub.buetow.org/yhttpd/yhttpd . -For CVS download type also look at the homepage please. +For CVS download type: -1.3.1 INSTALLATION: +cvs -d:pserver:anonymous@buetow.org:/usr/home/cvs/cvsroot login +( You will be asked for a password. Use "just enter" ). -Invoke "./configure" and afterwards "make", edit the conf.txt. +vs -z3 -d:pserver:anonymous@buetow.org:/usr/home/cvs/cvsroot co BRANCH +( The sources will be copied into your local folder ) -Now we want to compile all the dynamic loadable modules of ychat. -Invoke "cd cmnd && ./compile.sh && cd -". All command modules should get -compiled. +cvs -d:pserver:anonymous@buetow.org:/usr/home/cvs/cvsroot logout +( Logs your CVS session out ). -Now its time to run the server with ./ychat. -Then point your webbrowser to http://yourip:port ! +Now you may continue with the installation. -... have fun :-). +here are different branches in the CVS: -1.5.0 CUSTOMIZATION: +yhttpd: This is the latest CURRENT branch of yhttpd. +yhttpd-stable: This is the latest STABLE branch of yhttpd. +yhttpd-X.Y: This is the branch with the specified version prefix. +yhttpd: This is the latest CURRENT snapshot of yhttpd. -If you like to customize the design/layout/language of yChat, you will have -to edit msgs.h and glob.h before you compile the sources. Afterwards you can -change the html-template files which are placed in the html/ subdirectory. -Dynamic loadable modules can be found in the cmnd/ subdirectory. +The CURRENT branch of yhttpd is mostly untested and unstable, so don't +cry if you get errors. -1.6.0 FILES: ( This list is not complete ) +1.3 INSTALLATION: -conf.txt - The yChat configuration file. ( read by conf.cpp ). +Invoke "./configure". Afterwards you will get prompted with the before-compile +options of yhttpd. After choosing those options you are ready to type "gmake" +afterwards. See below what gmake is doing. -Files in ./src: -base.cpp - Encapsulates vector fields of room's or user ( may be later - hash_maps ) and provides methods for manipulating data - objects. +You may also invoke gmake with the following options (the PREFIX can be set +in the yhttpd configurator which will be launched by the top configure script +or gmake config): -hmap.cpp - The hash map implementation which is a very fast data - structure. is needed for saving users, rooms and so on. + 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 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 ./configure with enabling debugging) + gmake config (runs yhttpd configurator) + gmake debug (runs gdb on ./yhttpd.core) + gmake dist (creates a .tar.bz2 ball) + gmake gpl (shows the GNU General Public License) + gmake help (shows all available yhttpd gmake targets) + gmake mail (sends a mail to the yhttpd developers containing build opts.) + gmake modules (only compiles modules) + gmake mrproper (same as gmake clean plus removing all temp files) + gmake setup (runs all configure scripts and afterwards gmake all) + gmake stats (generates yhttpd statistics) + gmake version (shows the current version of yhttpd) -main.cpp - This includes the required manager headers for starting - the server and finally regulates the correct starting. +Example: "gmake all install clean" compiles everything, installs it to PREFIX +and cleans the source directories. -modl.cpp - The module loader. Stores pointers of all dynamic loaded - yChat modules in a hash map object and loads new modules - if desired or returns their pointers. +Now its time to run the server with ./bin/yhttpd. -pool.cpp - The implementation of the thread pool. all threads are stored - in a queue. Each thread will be reused if the assigned job is - finished. +Aferwards point your webbrowser to http://yourip:port ! -reqp.cpp - This class implements the http request parser. If a client - starts a request to the server the reqp class will be - invoked. +... have fun :-). -room.cpp - Specifies a chat room. For each chat room an instance of - this class exists. +1.3 INSTALLATION QUICK START: -thrd.cpp - This class is needed by sock.cpp while creating a POSIX thread. - All data which a thread needs to do its tasks are stored in a - thrd object and then a pointer to it will be passed to the - POSIX thread function. +If you in hury, then you may just type gmake setup. In the yhttpd configurator +you may just choose all the default values. If done, yhttpd will get compiled +and is ready to run with ./bin/yhttpd! -user.cpp - Specifies a chat user. For each chat user an instance of - this class exists. -Abstract classes: -cont.cpp - All classes which need to store "key - value" data sets - inherit from this class. ( cont for content ). +1.4 HOW TO USE SCREEN WITH YHTTPD: -name.cpp - All classes which own a private member string name inherit - from this class. It also provides public get_name and - set_name methods. +If you are running yhttpd in ncurses mode you might want to install +the tool which is called "screen". This will enable you putting the +ncurses interface into the background, closing the terminal session +and reusing the interface later through another terminal. + +Just do: + + screen -S yhttpd ./bin/yhttpd ( creates a new session and starts yhttpd in it ) + ctrl+d+a ( will detach the yhttpd session ) + ( closing the terminal ) + ( opening a new terminal ) + screen -r yhttpd ( will return you to the yhttpd process ) -As described ( main.cpp ), there are so called managers. Managers are -accessible through their assigned wrapper classes and may be -instanciated only once. +Screen will terminate automaticaly if all processes in its sessions are +terminated. -chat.cpp - The chat manager. Is responsible for managing the internal - data structure of the system and also covers a lot of - important methods of the system. +For a closer look read the screen manual page ( man screen ). -conf.cpp - The config manager. Parses the config file specified in - glob.h and stores all the values of it in a map. +1.4 HOW TO USE SIGNALS WITH YHTTPD: -html.cpp - The html-template manager. Reads the requested html-template - files, stores them in an internal cache ( averts reading - template-files from hd twice or more ) and parses the - partivular template in order to substituate dynamic values - of it. +You can send UNIX signals to yhttpd. This becomes very interesting if you +don't use the command line interface or the ncurses interface and you +don't have access to the options below. -mutx.cpp - The mutex manager. Contains all global mutex handlers for - synchronizing POSIX thread shared data. until now only the - stdout is synchronized by mutx.cpp because most of objects - use their own mutex'. +Run one of the following commands to send the signal you want: +($PID is here the process id of the current yhttpd process) -sock.cpp - The socket manager. Manages the socket connections. There - are multiplexed sockets. For each requests a new POSIX thread - will be created. +kill -USR1 $PID # yhttpd clears the HTML template cache +kill -HUP $PID # yhttpd will shutdown savely -Files with a leading s_ contain static C++ classes +1.5 CUSTOMIZATION: -s_chat.cpp - Static wrapper for the dynamic chat class. holds one global - reachable instance of chat until the program shuts down. +If you like to customize the design/layout/language of yhttpd, 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/yhttpd.conf). -s_conf.cpp - Static wrapper for the dynamic conf class. holds one global - reachable instance of conf until the program shuts down. +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. -s_html.cpp - Static wrapper for the dynamic html class. holds one global - reachable instance of conf until the program shuts down. +You can edit the etc/yhttpd.conf to fit your needs. If you dont want to change +the config file, then you also can use yhttpd start parameters. -s_mutx.cpp - Static wrapper for the dynamic mutx class. holds one global - reachable instance of conf until the program shuts down. +Exmpl: ./bin/yhttpd -o chat.database.password secretpassword -s_sock.cpp - Static wrapper for the dynamic sock class. holds one global - reachable instance of conf until the program shuts down. +You can also use multiple words for a specific option. -s_tool.cpp - Static class which includes some usefull global reachable - methods which are not integraded in independent classes. +Exmpl: ./bin/yhttpd -o yhttpd.version "word1 word2 word3" -Special header files ( all other header files which are not listed here -belong to their respective .cpp files ): +will overwrite the default database password value of the yhttpd.conf. You can +do this with every configuration element by adding several -o option value +arguments to the start command. -glob.h - Defines global variables which are known by compilation - time. +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 your new module gets compiled. -incl.h - This file is included from every other header file and - includes a set of headers which every class should be able - to use. +All messages defined in the msgs.h file contain server messages only ( a chat +user never wont read them, only the administrator will get to see them ). -msgs.h - Defines console output messages for verbosity level 0 ( see - glob.h for setting up verbosity levels ). and also defines - all the system messages. you may edit this file for translating - the system user language. +1.6 FILES: -The basic class structure: +etc/yhttpd.conf - The yhttpd configuration file +html/* - The html template files +src/* - The yhttpd base sources +src/mods/* - The dynamic loadable modules sources +scripts/* - Some nice scripts needed for building & co. - base<room> base<user> - | | name - | | / \ - | | / \ - chat room user +The following is created by building yhttpd: +obj/* - The object files of the compiled yhttpd base +mods/* - The compiled dynamic loadable modules +bin/yhttpd - The yhttpd binary (linked by the object files) + +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 - cont - / \ - / \ -conf html 1.7 WRITING BUG REPORTS How to submit a good bug report? -Send them to Bug@yChat.org. +Send them to mail at yhttpd dot org. First you should give the following information: -- yChat version, if CVS (or devel. tarball) then which day? +- yhttpd 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: +Getting backtrace of the crash also helps a lot, especially if yhttpd 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: +It writes a file named "core" or "yhttpd.core" depending on your OS to directory +where you started yhttpd. 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 yhttpd. To do this, say: ulimit -c unlimited -So, if you have the core file and GNU debugger (gdb), you can get the backtrace with: +So, if you have the core file and GNU debugger (gdb), you can get the +backtrace with: - gdb ychat core + gdb ./bin/yhttpd yhttpd.core 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> > >&) () + 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> > >&) () + #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*) () @@ -241,20 +353,43 @@ Here's an example session: #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 yhttpd using +debuggig symbols. You can do it this way: + +cd yhttpd +gmake clean confdebug all run + 1.8 CONTACT: You may contact us through the following addresses: - Homepage - The yChat homepage is located at http://www.yChat.org + The yhttpd homepage is located at http://www.yChat.org + The EXA Digital Solutions homepage is located at http://www.exa-ds.com - E-Mail - Paul C. Buetow: Snooper@yChat.org ( core developer ) - Volker Richter: Rover@yChat.org ( core developer ) - Mail@yChat.org ( reaches everybody of yChat ) + Paul C. Buetow: Buetow at yhttpd point org ( core developer ) + Mail at yhttpd dot org ( reaches everybody of yhttpd ) - ICQ Paul C. Buetow: 11655527 - IRC - #ychat at irc.german-elite.net + #Ychat and #Coding at irc.german-elite.net + +- EXA Digital Solutions GbR + Laubenstr. 16b + D-44866 Bochum + Germany + + +2.0 CREDITS + +Thanks to the following persons. Without them yhttpd would not be like today: + +- Volker Richter <volker at exa-ds dot de> of EXA Digital Solutions GbR + (http://www.exa-ds.com) for adding initial MySQL support and lots of more + code. + +- Joshia Teitelbaum <joshuat at cryptomail.org> of CryptpMail.org for adding + lots of security patches in the HTTP header handling. |