diff options
Diffstat (limited to 'yhttpd-0.7.2/README')
| -rwxr-xr-x | yhttpd-0.7.2/README | 395 |
1 files changed, 395 insertions, 0 deletions
diff --git a/yhttpd-0.7.2/README b/yhttpd-0.7.2/README new file mode 100755 index 0000000..f21fdeb --- /dev/null +++ b/yhttpd-0.7.2/README @@ -0,0 +1,395 @@ +yhttpd; Homepage: www.yChat.org; Version 0.7.2-RELEASE + +Copyright (C) 2003 Paul C. Buetow, Volker Richter +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 +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. +----------------------------------------------------------------- + +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: + +- GNU GCC G++ + The GNU C++ compiler version 3.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. + yhttpd 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. + +- ncurses 5.x + Includes libncurses and the ncurses.h header files. + +- Screen + Only needed if yhttpd should run in background with + ncurses or CLI enabled. + +- 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.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 HOW TO OBTAIN YHTTPD: + +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://pub.buetow.org/yhttpd/yhttpd . + +For CVS download type: + +cvs -d:pserver:anonymous@buetow.org:/usr/home/cvs/cvsroot login +( You will be asked for a password. Use "just enter" ). + +vs -z3 -d:pserver:anonymous@buetow.org:/usr/home/cvs/cvsroot co BRANCH +( The sources will be copied into your local folder ) + +cvs -d:pserver:anonymous@buetow.org:/usr/home/cvs/cvsroot logout +( Logs your CVS session out ). + +Now you may continue with the installation. + +here are different branches in the CVS: + +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. + +The CURRENT branch of yhttpd is mostly untested and unstable, so don't +cry if you get errors. + +1.3 INSTALLATION: + +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. + + +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): + + 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) + +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/yhttpd. + +Aferwards point your webbrowser to http://yourip:port ! + +... have fun :-). + +1.3 INSTALLATION QUICK START: + +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! + + + +1.4 HOW TO USE SCREEN WITH YHTTPD: + +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 ) + +Screen will terminate automaticaly if all processes in its sessions are +terminated. + +For a closer look read the screen manual page ( man screen ). + +1.4 HOW TO USE SIGNALS WITH YHTTPD: + +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. + +Run one of the following commands to send the signal you want: +($PID is here the process id of the current yhttpd process) + +kill -USR1 $PID # yhttpd clears the HTML template cache +kill -HUP $PID # yhttpd will shutdown savely + +1.5 CUSTOMIZATION: + +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). + +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. + +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. + +Exmpl: ./bin/yhttpd -o chat.database.password secretpassword + +You can also use multiple words for a specific option. + +Exmpl: ./bin/yhttpd -o yhttpd.version "word1 word2 word3" + +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. + +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. + +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 ). + +1.6 FILES: + +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. + +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 + + +1.7 WRITING BUG REPORTS + +How to submit a good bug report? + +Send them to mail at yhttpd dot org. + +First you should give the following information: +- 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 yhttpd crashes +randomly. If after crash you see text: + + "segmentation fault (core dumped)" + +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: + + 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> > >&) () + (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 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 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: Buetow at yhttpd point org ( core developer ) + Mail at yhttpd dot org ( reaches everybody of yhttpd ) + +- ICQ + Paul C. Buetow: 11655527 + +- IRC + #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. |