diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 363 |
1 files changed, 135 insertions, 228 deletions
@@ -21,44 +21,40 @@ Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. YCHAT TABLE OF CONTENTS: -1.0.0 GENERAL -1.1.0 ABOUT RELEASES -1.2.0 YCHAT FEATURES //<< -2.0.0 INSTALLATION AND SETUP -2.1.0 REQUIREMENTS -2.2.0 TESTED PLATFORMS -2.3.0 HOW TO OBTAIN YCHAT -2.4.0 INSTALLATION QUICK-START -2.4.1 INSTALLATION -2.5.0 HOW TO USE OPENSSL WITH YCHAT -2.5.1 HOW TO USE SCREEN WITH YCHAT -2.5.2 HOW TO USE SIGNALS WITH YCHAT -2.5.3 HOW TO USE GNU READLINE WITH YCHAT -2.5.4 HOW TO USE MYSQL WITH YCHAT //<< -2.6.0 CUSTOMIZING YCHAT -2.7.0 YHTTPD CODE BASE GENERATION //<< -3.0.0 EXTENDING YCHAT -3.1.0 SOURCE FILES -4.0.0 DIVERSE -4.1.0 WRITING BUG REPORTS -4.2.0 CONTACT ADDRESSES -4.3.0 CREDITS - -1.0.0 GENERAL - -1.1.0 ABOUT RELEASES +0.0.0 ABOUT RELEASES +0.0.1 YCHAT FEATURES //<< +1.0.0 REQUIREMENTS +1.1.0 TESTED PLATFORMS +1.2.0 IMPORTANT NOTICES +1.3.0 HOW TO OBTAIN YCHAT +1.3.1 INSTALLATION +1.3.2 INSTALLATION QUICK-START +1.3.3 MYSQL SETUP //<< +1.4.0 HOW TO USE SCREEN WITH YCHAT +1.4.1 HOW TO USE SIGNALS WITH YCHAT +1.5.0 CUSTOMIZATION +1.6.0 FILES +1.7.0 WRITING BUG REPORTS +1.8.0 CONTACT +1.9.0 YHTTPD CODE BASE GENERATION //<< +2.0.0 CREDITS + +0.0.0 ABOUT RELEASES 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. +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. +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. - The ycurses - ycurses is a easy to use and small C++ wrapper around the C ncurses API. @@ -135,11 +131,11 @@ of a specific branch. The optional W can be used to specify a maintenance revision which only changes small issues. //<<* -1.2.0 YCHAT FEATURES +0.0.1 YCHAT FEATURES - Its free & portable - yChat is developed under the GNU general public license and is based on GNU -tools (gcc, gmake), other open source library stuff (such as GNU Readline etc.) +tools (gcc, gmake), other open source library stuff (such as libncurses etc.) and should run on any POSIX capable operating system (such as all Linux based systems, FreeBSD, NetBSD, OpenBSD and other BSD-Systems and on UNICES like IRIX, HP-UX, Solaris etc.). @@ -172,9 +168,6 @@ Also, each user gets its own session id (random string) with a standard length of 50 chars to authenticate each logged in user. The length of the session id can be redefined as well. Also, the session id will get md5-hashed optionally so thats even harder to reverse engineering the session ids of other users. -Also, yChat supports secure hypertext transfer protocol (HTTPS) connections -using the OpenSSL library. Then, all chat messages will be encrypted in a -secure manner. HTTPS is optional to HTTP (unsecured connections). - Its HTML template based and easy to customize via XML based configuration - All HTML sites are predefined as HTML-Template files and can be easily modified @@ -197,7 +190,7 @@ to use other databases such as PostgreSQL, SQLite or a text based database etc. If wished, you can disable database support in the pre-compile options. - It has an administration interface - -yChat includes an libreadline based administration interface which tracks some +yChat includes an ncurses based administration interface which tracks some interesting statistics and system messages and enables you to do certain administrative tasks. In addition, you can switch to the CLI (command line interface) mode of the administration interface in order to be provided with @@ -246,9 +239,7 @@ options. This improves overall performance on heavily loaded yChat servers if a lot of user and room objects are created and destroyed frequently. //*>> -2.0.0 INSTALLATION AND SETUP - -2.1.0 REQUIREMENTS: +1.0.0 REQUIREMENTS: - GNU GCC G++ The GNU C++ compiler version 3.1 or up. @@ -264,28 +255,22 @@ lot of user and room objects are created and destroyed frequently. On *BSD you have to install it first before compiling. On FreeBSD /usr/ports/devel/stlport is your friend. -- OpenSSL (optional) - Includes libssl and the ssl header files of the open source SSL library. - OpenSSL is only needed if you chose to compile yChat w/OpenSSL support. - -- GNU Readline (optional) - This library can be used with the command line interface (CLI) of - ychat to make the editing easier. - //<<* -- mysql-client 4.x (optional) [3.x may do too but is not supported] - Includes libmysqlclient and the mysql.h header files. mysql-client is only - needed if you chose to compile yChat w/database support. +- mysql-client 4.x (3.x may do too but is not supported) + Includes libmysqlclient and the mysql.h header files. + //*>> +- ncurses 5.x + Includes libncurses and the ncurses.h header files. -- Screen (optional) +- Screen Only needed if yChat should run in background with - the CLI enabled. + ncurses or CLI enabled. - Perl 5.x Is needed for some scripts. Is not needed if you use precompiled binaries. -2.2.0 TESTED PLATFORMS: +1.1.0 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: @@ -297,6 +282,7 @@ a listed platform did not work at all please contact me: Tested longer time before: - FreeBSD 5.4-RELEASE (i386) 3.4.2 3.80 - FreeBSD 4.10-RELEASE (i386) 3.4.1 3.80 +- FreeBSD 4.9-RELEASE (i386) 3.3.4 3.80 - Gentoo Linux 2004 (i386) 3.3.2 3.80 - OpenBSD 3.6 SMP (i386) 3.3.2 3.80 - Red Hat Linux 8.0 SMP (i386) 3.2-7 3.79 @@ -307,7 +293,14 @@ a listed platform did not work at all please contact me: Other platforms like Linux based systems, other BSD-Systems or UNICES are very likely to work too. -2.3.0 HOW TO OBTAIN YCHAT: +1.2.0 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 yChat, please write us an email and tell what +you can/like/would help ;-]. Please also take a look at the yChat +homepage which is located at http://www.yChat.org. yChat can be downloaded as a source package or through CVS. @@ -336,109 +329,95 @@ yhttpd: This is the latest CURRENT snapshot of yhttpd. The CURRENT branch of ychat is mostly untested and unstable, so don't cry if you get errors. -2.4.0 INSTALLATION QUICK START - -If you in hury, then you may just run the following commands: - - sh -c 'CXXFLAGS="" ./configure' - gmake install clean - -yChat will get compiled without debugging symbols and its default values. -Afterwards yChat will get installed into the default prefix which is -/usr/local. Afterwards it is ready to run with the '/usr/local/bin/ychat' -command! - -2.4.1 INSTALLATION - -If you wanna quick start, then please refer to section 2.4.0 instead. +1.3.1 INSTALLATION: -Invoke './configure --help'. Afterwards you will get prompted with all the -possible compile options. Take a closer look at the --enable-FEATURE and the ---disable-FEATURE options. Afterwards run configure with your wanted options. -Now, you can run 'gmake'. See below what gmake is doing. By default yChat uses -loosy debugging symbols. To disable them, then run configure this way: - - sh -c 'CXXFLAGS="" ./configure --options' - -Dont forget to replace --options with your desired values. You can read more -about debugging symbols in section '4.1.0 WRITING BUG REPORTS'. +Invoke "./configure". Afterwards you will get prompted with the before-compile +options of yChat. After choosing those options you are ready to type "gmake" +afterwards. See below what gmake is doing. //<<* If you have choosen MySQL database support, then take a look at section 1.3.2 how to setup a valid database table. Be also sure to enter the valid MySQL accessing data in the yChat configuration file which is normally located in -the etc/ychat.conf file. +the etc/ychat.conf file if not changed by you with the yChat configurator. //*>> -You may also invoke gmake with the following options: +You may also invoke gmake with the following options (the PREFIX can be set +in the yChat 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 build (increments the current build number by one) 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 the configure with strong debugging symboles enabled) + gmake confdebug (runs ./configure with enabling debugging) + gmake config (runs yChat configurator) gmake debug (runs gdb on ./ychat.core) - gmake deinstall (same as gmake uninstall) gmake dist (creates a .tar.bz2 ball) - gmake headers (rewrites the source file headers using doc/header.txt) - gmake help (shows all available yChat gmake targets) - gmake install (removes debugging symbols and installs yChat into the PREFIX) - gmake license (shows the GNU General Public License) + gmake gpl (shows the GNU General Public License) + gmake help (shows all available ychat gmake targets) + gmake mail (sends a mail to the yChat developers containing build opts.) gmake modules (only compiles modules) gmake mrproper (same as gmake clean plus removing all temp files) - gmake quick (runs all configure scripts and afterwards gmake all) - gmake replace (replace in the source the content of $FROM into $INTO) - gmake stats (generates yChat statistics) - gmake strip (removes debugging symbols from binary) - gmake ssltest (generates a self signed ssl test certificate) - gmake touch (resets the date of each file in the source tree) - gmake uninstall (uninstalls yChat from the current default PREFIX) + gmake setup (runs all configure scripts and afterwards gmake all) + gmake stats (generates ychat statistics) gmake version (shows the current version of yChat) //<<* gmake yhttpdbase (generates an yhttpd code base) //*>> (See section 1.9 to read about this marks) -Example: 'gmake all install clean' compiles everything, installs it to PREFIX +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/ychat'. +Now its time to run the server with ./bin/ychat. Aferwards point your webbrowser to http://yourip:port ! ... have fun :-). -2.5.0 HOW TO USE OPENSSL WITH YCHAT - -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: +1.3.2 INSTALLATION QUICK START: -The private key can be created w/the following command: +If you in hury, then you may just type gmake setup. In the yChat configurator +you may just choose all the default values. If done, yChat will get compiled +and is ready to run with ./bin/ychat! - openssl genrsa -des3 -out privkey.pem 2048 -Afterwards, you can create a self-signed test certificate using the following -command: +//<<* +1.3.3 MYSQL SETUP - openssl req -new -x509 -key privkey.pem -out cert.pem -days 1095 +If you chose to use MySQL database support you have to create a valid database +to use with yChat. -Be sure to move the privkey.pem and cert.pem files into the ./etc directory -or edit the path names in the ./etc/ychat.conf file. yChat wont start if there -are no valid files found. +Create a new MySQL database called 'ychat' and type the following command into +a MySQL command line client of your choice: -To learn more about SSL certificates, visit http://www.openssl.org/docs/HOWTO/. +USE ychat +CREATE TABLE `user` ( + `uid` int(10) NOT NULL auto_increment, + `nick` varchar(30) NOT NULL default '', + `password` varchar(30) NOT NULL default '', + `color1` varchar(30), + `color2` varchar(30), + `email` varchar(50) default '-', + `registerdate` varchar(30) default '-', + `logincounter` varchar(10) default '0', + `status` char(1) default '3', + PRIMARY KEY (`uid`), + KEY `uid` (`uid`) +) TYPE=MyISAM; +GRANT ALL PRIVILEGES ON ychat.* to ychat@localhost IDENTIFIED BY "yctest"; -Now use https:// and NOT http:// to connect to the yChat server. +This database uses the default MySQL access informations which are stored in the +ychat.conf file. +//*>> -2.5.1 HOW TO USE SCREEN WITH YCHAT: +1.4.0 HOW TO USE SCREEN WITH YCHAT: -If you are running yChat in CLI mode you might want to install +If you are running yChat in ncurses mode you might want to install the tool which is called "screen". This will enable you putting the -CLI interface into the background, closing the terminal session +ncurses interface into the background, closing the terminal session and reusing the interface later through another terminal. Just do: @@ -454,11 +433,11 @@ terminated. For a closer look read the screen manual page ( man screen ). -2.5.2 HOW TO USE SIGNALS WITH YCHAT: +1.4.1 HOW TO USE SIGNALS WITH YCHAT: You can send UNIX signals to yChat. This becomes very interesting if you -don't use the command line interface and you don't have access to the options -below. +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 yChat process) @@ -467,60 +446,18 @@ kill -USR1 $PID # yChat clears the HTML template cache kill -USR2 $PID # yChat reloads all dynamic loadable modules //<< kill -HUP $PID # yChat will shutdown savely -2.5.3 HOW TO USE GNU READLINE WITH YCHAT: - -This library can be used with the command line interface (CLI) of ychat. To -use it, yChat has to be compiled with readline support (which is the default -setting). - -Readline offers editing capabilities while the user is entering the line. -By default, the line editing commands are similar to those of emacs. A vi-style -line editing interface is also available. - -For configuration and usage of the yChat readline CLI prompt, read the readline -manpage. :) - -//<<* -2.5.4 HOW TO USE MYSQL WITH YCHAT - -If you chose to use MySQL database support you have to create a valid database -to use with yChat. - -Create a new MySQL database called 'ychat' and type the following command into -a MySQL command line client of your choice: - -USE ychat -CREATE TABLE `user` ( - `uid` int(10) NOT NULL auto_increment, - `nick` varchar(30) NOT NULL default '', - `password` varchar(30) NOT NULL default '', - `color1` varchar(30), - `color2` varchar(30), - `email` varchar(50) default '-', - `registerdate` varchar(30) default '-', - `logincounter` varchar(10) default '0', - `status` char(1) default '3', - PRIMARY KEY (`uid`), - KEY `uid` (`uid`) -) TYPE=MyISAM; -GRANT ALL PRIVILEGES ON ychat.* to ychat@localhost IDENTIFIED BY "yctest"; - -This database uses the default MySQL access informations which are stored in the -ychat.conf file. -//*>> - -2.6.0 CUSTOMIZING YCHAT: +1.5.0 CUSTOMIZATION: If you like to customize the design/layout/language of yChat, 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/ +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/ychat.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 (See './configure --help'). +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/ychat.conf to fit your needs. If you dont want to change +You can edit the etc/ychat.conf to fit your needs. If you dont want to change the config file, then you also can use ychat start parameters. Exmpl: ./bin/ychat -o chat.database.password secretpassword @@ -533,53 +470,38 @@ will overwrite the default database password value of the ychat.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 +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' or 'gmake modules' your new module gets compiled. - -All messages defined in the ./src/msgs.h file contain server messages only (a chat -user never wont read them, only the administrator will get to see them). +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. -Read also section 3.0.0 of this README. +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 ). -//<<* -2.7.0 YHTTPD CODE BASE GENERATION +1.6.0 FILES: -See docs/yhttpd.txt -//*>> - -3.0.0 EXTENDING YCHAT - -3.1.0 SOURCE FILES - -This list is not complete. Only the most important files are listed here! - -./etc/ychat.conf - The yChat configuration file -./html/* - The html template files -./src/* - The yChat base sources -./src/mods/* - The dynamic loadable modules sources -./scripts/* - Some nice scripts needed for building & co. +etc/ychat.conf - The yChat configuration file +html/* - The html template files +src/* - The yChat base sources +src/mods/* - The dynamic loadable modules sources +scripts/* - Some nice scripts needed for building & co. The following is created by building yChat: -./obj/* - The object files of the compiled yChat base -./mods/* - The compiled dynamic loadable modules -./bin/ychat - The yChat binary (linked by the object files) -./bin/ychat.bak - An yChat binary of a previous build process +obj/* - The object files of the compiled yChat base +mods/* - The compiled dynamic loadable modules +bin/ychat - The yChat 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 - +src/glob.h - Contains some global building options +src/msgs.h - Defines some server side messages -4.0.0 DIVERSE -4.1.0 WRITING BUG REPORTS +1.7 WRITING BUG REPORTS How to submit a good bug report? -Send them to Mail at yChat dot org. +Send them to mail at yChat dot org. First you should give the following information: - yChat version, if CVS (or devel. tarball) then which day? @@ -591,8 +513,8 @@ 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 +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: @@ -601,7 +523,7 @@ before running yChat. To do this, say: So, if you have the core file and GNU debugger (gdb), you can get the backtrace with: - gdb ./bin/ychat ychat.core (or gmake debug instead) + gdb ./bin/ychat ychat.core bt Paste all the lines starting from line having #0 at the beginning. @@ -624,29 +546,10 @@ Here's an example session: If you dont get such a gdb output, you need to recompile the yChat using debuggig symbols. You can do it this way: - gmake clean_base base run +cd ychat +gmake clean confdebug all run -By default, ychat gets compiled with loosy debugging symbols. If you want to -get strong debugging symbols, then type: - - gmake confdebug clean_base base run - -or if you didnt run a ./configure before, then type: - - sh -c 'CXXFLAGS="-g3 -ggdb" ./configure'; gmake clean_base base run - -instead. - -In order to remove all the debugging symbols, then just type 'gmake strip' -afterwards. If you use 'gmake install', then the binary will be stripped -automatically. - -If you dont wanna compile with debugging symbols by default, then use this -command: - - sh -c 'CXXFLAGS="" ./configure'; gmake clean_base base run - -4.2.0 CONTACT ADDRESSES +1.8 CONTACT: You may contact us through the following addresses: @@ -664,12 +567,16 @@ You may contact us through the following addresses: - IRC #Ychat and #Coding at irc.german-elite.net -4.2.0 CREDITS +- EXA Digital Solutions GbR + Laubenstr. 16b + D-44866 Bochum + Germany -Thanks to the following persons. Without them yChat would not be like today: +//<<* +1.9.0 YHTTPD CODE BASE GENERATION -- Volker Richter <volker at exa-ds dot de> of EXA Digital Solutions GbR - for adding initial MySQL support and lots of more code. +See docs/yhttpd.txt +//*>> - Joshua Teitelbaum <joshuat at cryptomail.org> of CryptpMail.org for adding initial OpenSSL support and lots of security patches in the HTTP header |