diff options
Diffstat (limited to 'yhttpd/README')
| -rw-r--r-- | yhttpd/README | 462 |
1 files changed, 0 insertions, 462 deletions
diff --git a/yhttpd/README b/yhttpd/README deleted file mode 100644 index 5fa183e..0000000 --- a/yhttpd/README +++ /dev/null @@ -1,462 +0,0 @@ -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. |