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::allocator > >&) () (gdb) bt #0 0x0805c287 in reqp::parse(thrd*, std::string, std::map, std::allocator > >&) () #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 of EXA Digital Solutions GbR for adding initial MySQL support and lots of more code. - Joshua Teitelbaum of CryptpMail.org for adding initial OpenSSL support and lots of security patches in the HTTP header handling.