diff options
Diffstat (limited to 'yhttpd/README')
| -rw-r--r-- | yhttpd/README | 462 |
1 files changed, 462 insertions, 0 deletions
diff --git a/yhttpd/README b/yhttpd/README new file mode 100644 index 0000000..5fa183e --- /dev/null +++ b/yhttpd/README @@ -0,0 +1,462 @@ +yhttpd; Homepage: www.yChat.org; Version 0.8-CURRENT + +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: + +1.0 GENERAL +1.1 ABOUT DEVELS +2.0 INSTALLATION AND SETUP +2.1 REQUIREMENTS +2.2 TESTED PLATFORMS +2.3 HOW TO OBTAIN YHTTPD +2.4 INSTALLATION QUICK-START +2.4 INSTALLATION +2.3 HOW TO USE OPENSSL WITH YHTTPD +2.3 HOW TO USE SCREEN WITH YHTTPD +2.3 HOW TO USE SIGNALS WITH YHTTPD +2.4 CONFIGURING YHTTPD +3.0 EXTENDING YHTTPD +3.1 SOURCE FILES +4.0 DIVERSE +4.1 WRITING BUG REPORTS +4.2 CONTACT ADDRESSES +4.3 CREDITS + +1.0 GENERAL + +1.1 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 around 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 STABLDEVEL. + +- 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. + +- 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 +DEVEL aka REL aka R +LEGACY aka LEG aka L +STABLE aka SBL aka S +DEVEL aka DEV aka D +PRE aka P + +STABLDEVEL aka STBREL aka SR +DEVEL aka PREREL aka PR +PRELEGACYDEVEL aka PRELEGREL aka PLR +etc... + +The short name of the chat is "yC" +The short name of the httpd is "yh" +The short name of ycurses is "yu" + +- 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. Version numbers can be also normal +alphabetic characters. Example: Version 0.7.A follows 0.7. Version 0.T.Y.2 +would be also valid. + +Therefore: The lowest value is 0, the highest possible value is Z. + + +2.0 INSTALLATION AND SETUP + +2.1 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. + +- OpenSSL + Includes libssl and the ssl header files of the open source SSL library. + OpenSSL is only needed if you chose to compile yhttpd w/OpenSSL support. + +- 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. + +2.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.4-DEVEL (i386) 3.4 3.80 +- 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. + +2.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. + +2.4 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! If you chose OpenSSL support, then +also run gmake ssltest before starting yhttpd. + +2.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 ssltest (generates a self signed ssl test certificate) + 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 :-). + +2.3 HOW TO USE OPENSSL WITH YHTTPD + +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/yhttpd.conf file. yhttpd 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 yhttpd server. + + +2.3 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 ). + +2.3 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 + +2.4 CONFIGURING YHTTPD: + +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 ). + +Read also section 3.0 of this README. + + +3.0 EXTENDING YHTTPD + +3.1 SOURCE FILES + +This list is not complete. Only the most important files are listed here! + +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 + + +4.0 DIVERSE + +4.1 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: + +gmake clean confdebug all run + +4.2 CONTACT ADDRESSES + +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 + +4.2 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 + 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. |