Welcome to thebridge, a member of the CQiNet family. http://CQiNet.sourceforge.net Thebridge is an EchoLink compatible conference bridge that runs under FreeBSD, Linux, QNX, Mac OS X, Windows and hopefully most other Posix compatible operating systems. If you've never hear of EchoLink then this software probably won't make much sense to you. See: http://www.echolink.org then if you are still interested continue here. The EchoLink system, and by extension this software, are for Ham radio operators. Unfortunately unlike "real" Ham Radio SWLs (short wave listeners) are not welcomed so if you're not already a licensed ham it is unlikely that you will find much of value here, sorry. Finally I believe there is a moratorium on new Echolink conference servers so unless you are already running a conference or are using thebridge for other purposes you might as well save yourself the frustration and give up now. As of this writing there were 124 conferences on line and 81 (65 %) were empty. Spreading activity out the point that most conferences sit idle all day is counter productive in my opinion. If you haven't given up yet and are running Windows give up now ... No wait! I'm just kidding ! But seriously folks ... read the file README.txt instead of this one. ############################################ Updating from previous versions of thebridge ############################################ New versions of thebridge are usually backwards compatible with configuration files from earlier releases HOWEVER new variables are added frequently. Since the sample tbd.conf.sample file includes documentation on some features which are not mentioned elsewhere it is worthwhile to review the sample configuration file with each release to discover new capabilities which you may want to take advantage of. ########### Portability ########### A quick word on portability: I've tried to the best of my ability and means to make thebridge as portable as possible. I've tested it under several versions of FreeBSD and Linux, however *ALL* testing has been on the Intel x86 architecture. I hope the code will work on big endian machines as well, but it has not been tested on one yet. If you try this software on a big endian machine I would be very interested in hearing of your success or failure. ################### Building on a *nix: ################### Executive summary: (the usual) "tar xzf thebridge-{VERSION}.tgz" "cd thebridge-{VERSION}" "./configure" "make" "make install" Requirements: The only known requirement to build thebridge is the GNU GCC compiler or something compatible, a make program and a Bourne shell to run the configure script. GNU make is not required, any old make should be fine. I tried to avoid the use of exotic compiler features, hopefully any version of GCC will work. As of this writing thebridge has been built and run successfully on FreeBSD 2.2.7, FreeBSD 4.4, Red Hat 7.3, Suse 7.3, Slackware 8.0, QNX RTP 6.1 and Mac OS X. If for some reason either configure or the make should fail please send me the details and I'll try to help you correct the problem. Extract: The distribution tar file extracts into a version specific subdirectory so different releases do not conflict with each other. Substitute the actual version number for "{VERSION}" above. The ".tgz" extension signifies a Gzip'ed TAR file. GNU configure: Thebridge uses a GNU autoconfig generated configuration script to generate a site-specific Makefile that is then used to build thebridge. The configuration script is written to be as portable as possible by only assuming the availability of the most generic Bourne shell features. A suitable shell should be available on just about every *nix system. It will certainly be available on any system using other GNU tools. The configuration script provides a great deal of flexibility in the way the target program is built and installed, run "./configure --help" for the gory details. Luckily most of the features are seldom needed and running configure without any options is usually sufficient. Once the configure script has been run you should have a config.h and Makefile appropriate for your system. With any luck you should see something similar (but probably not identical) when you run configure: --- snip --- % tar xzf thebridge-0.10.tgz % cd thebridge-0.10 % ./configure creating cache ./config.cache checking for a BSD compatible install... /usr/bin/install -c checking whether build environment is sane... yes checking whether make sets ${MAKE}... yes checking for working aclocal... found checking for working autoconf... found checking for working automake... found checking for working autoheader... found checking for working makeinfo... found checking for gcc... gcc checking whether the C compiler (gcc ) works... yes checking whether the C compiler (gcc ) is a cross-compiler... no checking whether we are using GNU C... yes checking whether gcc accepts -g... yes checking for a BSD compatible install... /usr/bin/install -c checking whether ln -s works... yes checking for socket in -lsocket... no checking how to run the C preprocessor... gcc -E checking for ANSI C header files... yes checking for fcntl.h... yes checking for limits.h... yes checking for sys/time.h... yes checking for unistd.h... yes checking for sys/signal.h... yes checking for sys/timeb.h... yes checking for working const... yes checking for size_t... yes checking whether time.h and sys/time.h may both be included... yes checking whether struct tm is in sys/time.h or time.h... time.h checking for strdup... yes checking for getopt... yes checking for ftime... no checking for gettimeofday... yes checking for stricmp... no checking for strcasecmp... yes updating cache ./config.cache creating ./config.status creating Makefile creating src/Makefile creating config.h % --- snip --- Make: The generated makefile provides several useful targets, the default "all" builds thebridge. The other frequently used targets include "install", "clean", "distclean", and "uninstall". --- snip --- % make make all-recursive Making all in src gcc -DHAVE_CONFIG_H -I. -I. -I.. -Wall -DSYSCON_DIR=\"/usr/local/etc\" -g -O2 -c avl.c gcc -DHAVE_CONFIG_H -I. -I. -I.. -Wall -DSYSCON_DIR=\"/usr/local/etc\" -g -O2 -c conference.c gcc -DHAVE_CONFIG_H -I. -I. -I.. -Wall -DSYSCON_DIR=\"/usr/local/etc\" -g -O2 -c configfile.c gcc -DHAVE_CONFIG_H -I. -I. -I.. -Wall -DSYSCON_DIR=\"/usr/local/etc\" -g -O2 -c configvars.c gcc -DHAVE_CONFIG_H -I. -I. -I.. -Wall -DSYSCON_DIR=\"/usr/local/etc\" -g -O2 -c dirclient.c gcc -DHAVE_CONFIG_H -I. -I. -I.. -Wall -DSYSCON_DIR=\"/usr/local/etc\" -g -O2 -c main.c gcc -DHAVE_CONFIG_H -I. -I. -I.. -Wall -DSYSCON_DIR=\"/usr/local/etc\" -g -O2 -c thebridge.c gcc -DHAVE_CONFIG_H -I. -I. -I.. -Wall -DSYSCON_DIR=\"/usr/local/etc\" -g -O2 -c users.c gcc -Wall -DSYSCON_DIR=\"/usr/local/etc\" -g -O2 -o tbd avl.o conference.o configfile.o configvars.o dirclient.o main.o thebridge.o users.o % --- snip --- There shouldn't be any errors or warnings displayed during the build process. If you get warnings or errors I'd be interested in hearing about them. The final output of the build process is the thebridge daemon "tbd" which is built in the src subdirectory. The name of thebridge executable is tbd for "TheBridge Daemon (and it's also a good excuse to create yet another TLA). We'll test it before installing it. Before we test it we need to edit the configuration file. ####################### thebridge Configuration ####################### There is a single text file "tbd.conf.sample" that is used to configure thebridge. Fire up your favorite editor and change the various variables to appropriate values. Refer to the comments in the file for guidance. Most sites will only need to change the ConferenceCall, ConferencePass, ConferenceQth and WorkingDir settings. NOTE: the EchoLink directory servers *WILL NOT ACCEPT* a conference style callsign like "*W1AW*" unless you have specifically registered as a conference by the EchoLink administrators. I suggest that you test the conference using your usual callsign first. See www.echolink.org/el/conf.htm for more details. Lines beginning with ';' or '#' are comments, if you decide to set any of the optional settings be sure to delete leading ';' character before the configuration variable. --- snip --- % cp tbd.conf.sample tbd.conf % vi tbd.conf --- snip --- Since daemons are not connected to any console they must communicate with the sysop in some other manner. As with most *nix daemons thebridge uses the syslog system. Thebridge uses "LOG_LOCAL5" as the facility when opening the log and generates messages with priorities LOG_INFO, LOG_WARNING and LOG_ERR. It's up to the user to decide which message if any he wants to log, but unless you are a psychic I would strongly suggest that at least the LOG_ERR messages be logged. Lets assume we want to log all messages and that we also want to put them into a separate log file. To accomplish this we need to reconfigure the syslog daemon. The reconfiguration consists of nothing more than adding two lines to the bottom of /etc/syslog.conf. You will need to edit the file as root. Most daemons load their configuration files at system boot time and do not check for changes while running. In most cases sending the hangup signal (HUP) to the daemon will cause it to re-read the configuration file. Both syslogd and thebridge work this way. In order to send a signal to a daemon we need to know its process identification (pid) number. For convenience most daemons store their PID number in a file /var/run/{daemon name}.pid to make it easier for scripts to send signals to them. Again both syslogd and thebridge follow this convention. Some versions of syslog seem to require that a log file to exist before they will use it. Lets be safe and create the file before issuing the HUP. --- snip --- %su Password: fastbsd# vi /etc/syslog.conf (add the following at the end of the file) !tbd *.* /var/log/tbd.log (save the file and exit vi) fastbsd# touch /var/log/tbd.log fastbsd# kill -HUP `cat /var/run/syslog.pid` fastbsd# exit % --- snip --- Syslog should now be ready to log the messages from tbd. Refer to the syslog(3), syslogd(8), and syslog.conf(5) man page for more details. ####### Testing ####### The daemon has two command line switches to aid testing. The first switch -f specifies where the tbd.conf configuration is located. The second switch -d enables debug mode, causing the daemon to run in the foreground as a user process while displaying debug information on the screen. The debug switch may be used multiple times to increase the detail level of the information displayed up to a maximum of three times. For our purposes a single -d suffices. --- snip --- % src/tbd -d -f tbd.conf PullerLoginAck(): Client 2 successfully updated status. ParseStationList(): completed successfully, 376 stations listed. --- snip --- The first message indicates that the daemon was successful in logging into the directory server. Note: the EchoLink servers indicate a successful login even if the supplied callsign/password combination is unknown, invalid or banned. But the success does indicate that tbd was able to establish an TCP connection to the server. The second message is the real good news, our directory request returned 376 stations. If your callsign or password were not recognized there would be 0 stations. If you are not able to get a station list, check the configuration file. You might also want to rerun the test using more "-d" switches to help determine what when wrong. Unfortunately, due to the nature of the EchoLink protocols it is not possible to test thebridge further using a single computer. In particular the client program uses the same ports as the server so it's impossible to run a server and a client on the same host at the same time. Even if you have multiple computers you can't test the program unless you also have multiple *external, routable* IP addresses. You can't connect to thebridge from another computer on your local LAN if your local LAN is connected to the Internet using a NAT box or other form of Internet sharing where all of your computers appear to be coming from the same IP address. The easiest way to complete the testing is to have a couple of friends connect to thebridge and see if they can talk to each other. When a station connects to thebridge you'll see a message similar to the following: --- snip --- WD4NMQ JEFF logged into conference. W7NTF GARY logged into conference. --- snip --- Once you've verified that thebridge is operating correctly we're ready to complete the installation. Hit Ctrl-C to abort thebridge. --- snip --- ^CReceived SIGINT, shutting down PullerLoginAck(): Client 4 successfully updated status. Logged out, exiting. % --- snip --- ############ Installation ############ Thebridge is designed to run as a system daemon, i.e. a background program that's loaded automatically by the system as part of the bootup process. If you are not familiar with the system startup scripts or you are not comfortable starting thebridge automatically you can always start thebridge daemon manually when desired. Starting thebridge automatically is primarily needed when the host is unattended and it is desired to run thebridge 24/7. Refer to the "Running without Root access" section if you would rather not modify your system's startup behavior. Unfortunately my installation rules and knowledge are not complete enough about all of the various *nix variations to complete the installation without manual assistance. Most Posix operating systems start system daemons using approaches similar to either FreeBSD (i.e. the BSD camp) or RedHat (i.e. the System V camp). Scripts to install thebridge on FreeBSD and RedHat Linux have been provided. Start with the scripts that are the closest match to your system and then modify them if necessary. I will be happy to include installation scripts for other operating system that are sent to me with future releases. Configuration files for daemons are kept in different places on different systems. It doesn't really matter where the configuration file is as long as tbd can find it. If you want to put it somewhere other than where the GNU autoconf tools think it belongs just specify the full configuration file path on the command line using the -f switch. FreeBSD Local (not part of the standard distribution) daemons on FreeBSD systems are started by placing a shell script /usr/local/etc/rc.d directory with an ".sh" extension. During startup each script is called with an argument of "start". During system shutdown they are called again with an argument of "stop". If you are running on FreeBSD run the installation scripts from the FreeBSD subdirectory. The installation script will copy tbd, tbd.conf.sample and tbd.sh into the appropriate subdirectories. You will need to be root to when running the installation script. --- snip --- %cd FreeBSD %su Password: fastbsd# ./install + cd .. + make install Making install in src /bin/sh ../config/mkinstalldirs /usr/local/libexec /usr/bin/install -c tbd /usr/local/libexec/tbd /bin/sh ./config/mkinstalldirs /usr/local/etc /usr/bin/install -c -m 644 ./tbd.conf.sample /usr/local/etc/tbd.conf.sample + cd FreeBSD + cp tbd.sh /usr/local/etc/rc.d fastbsd# --- snip --- Since the installation process only copies tbd.conf.sample (to prevent accidents when thebridge is updated in the future) we must manually copy or configuration file to the "standard place": --- snip --- $ cp tbd.conf /usr/local/etc --- snip --- RedHat Linux If you are running on RedHat Linux run the installation scripts from the RedHat subdirectory. The installation script will copy the tbd executable, tbd.conf.sample, and tbd shell scripts into the appropriate subdirectories. It will then create links from /etc/rc.d/rc*.d subdirectories the /etc/rc.d/init.d/tbd shell script to start tbd in run levels 2, 3, 4 and 5 and to stop tbd in run levels 0, 1 and 6. You will need to be root to when running the installation script. --- snip --- $ su Password: [root@linux73 RedHat]# ./install + cd .. + make install Making install in src make[1]: Entering directory `/home/skip/thebridge-0.10/src' make[2]: Entering directory `/home/skip/thebridge-0.10/src' /bin/sh ../config/mkinstalldirs /usr/local/libexec /usr/bin/install -c tbd /usr/local/libexec/tbd make[2]: Nothing to be done for `install-data-am'. make[2]: Leaving directory `/home/skip/thebridge-0.10/src' make[1]: Leaving directory `/home/skip/thebridge-0.10/src' make[1]: Entering directory `/home/skip/thebridge-0.10' make[2]: Entering directory `/home/skip/thebridge-0.10' /bin/sh ./config/mkinstalldirs /usr/local/etc /usr/bin/install -c -m 644 ./tbd.conf.sample /usr/local/etc/tbd.conf.sample make[2]: Nothing to be done for `install-data-am'. make[2]: Leaving directory `/home/skip/thebridge-0.10' make[1]: Leaving directory `/home/skip/thebridge-0.10' + cd RedHat + ln -s /usr/local/libexec/tbd /usr/sbin + '[' '!' -d /etc/rc.d/init.d ']' + cp tbd /etc/rc.d/init.d + ln -s /etc/rc.d/init.d/tbd /etc/rc.d/rc0.d/K73tbd + ln -s /etc/rc.d/init.d/tbd /etc/rc.d/rc1.d/K73tbd + ln -s /etc/rc.d/init.d/tbd /etc/rc.d/rc2.d/S73tbd + ln -s /etc/rc.d/init.d/tbd /etc/rc.d/rc3.d/S73tbd + ln -s /etc/rc.d/init.d/tbd /etc/rc.d/rc4.d/S73tbd + ln -s /etc/rc.d/init.d/tbd /etc/rc.d/rc5.d/S73tbd + ln -s /etc/rc.d/init.d/tbd /etc/rc.d/rc6.d/K73tbd [root@linux73 RedHat]# exit $ --- snip --- Since the installation process only copies tbd.conf.sample (to prevent accidents when thebridge is updated in the future) we must manually copy or configuration file to the "standard place": --- snip --- $ cp tbd.conf /usr/local/etc --- snip --- Running without Root access If you don't have root access to the system you will not have the necessary rights to modify the configuration files necessary to start thebridge at boot time. Since the EchoLink protocols do not use any privileged ports you will still be able to run thebridge. Just execute it manually in debug mode specifying the location of the configuration file and redirecting the output to a log file or the bit bucket. --- snip --- %src/tbd -d -f tbd.conf > /dev/null & % --- snip ---