Frequently Asked Questions about the Dancer bot - 17th of June 1998. Table of contents 1. In general 1.1 Is Dancer based on ? 1.2 Why should I choose Dancer in preference to other bots? 1.3 What machine/OS does it need. 1.4 How do I report bugs? 1.5 How do I contribute? 1.6 How do I apply patches? 2. Running 2.1 How do I run it? 2.1.1 How do I compile it? 2.1.1.1 Problems when compiling 2.1.1.2 Fpl not found 2.1.2 Which files do I have to edit? 2.1.3 How do I start it? 2.2 Do I have to use the launch script? 2.3 It doesn't start. 2.3.1 The logfile contains a DEBUG statement. 2.3.2 The logfile contains an ERROR statement. 2.4 It doesn't recognize me. 2.5 My friend forgot his password. Can I find it somewhere? 2.6 I cannot dcc chat with it. 2.7 It crashes in mysterious ways. 2.8 How do I upgrade smoothly? 2.9 How do I make it register with Dalnet or Undernet channel service? 2.10 How do I bind a dancer to a vhost? 2.11 How do I enable longer than 9 letter nicks? 3. Commands 3.1 It doesn't answer me if I talk to it from outside the channel. 3.2 How do I use ? 3.3 Can I issue commands in public? 3.4 Can I redirect the output of a command to someone else? 3.5 Can I add my own commands? 3.6 Invite? 4. Fpl 4.1 What is fpl? 5. Files 5.1 Where can I get the latest version of Dancer? 5.2 Where can I find the fpl library? 5.3 Where can I find ? =================================================================== 1. In general 1.1 Is Dancer based on ? No, Dancer was started entirely from scratch. It basically started out as TCP programming experience. Many of the commands were inspired by the Mama bot made by pjotr (sourcecode wasn't available, probably still isn't.) 1.2 Why should I choose Dancer in preference to other bots? It contains many useful services to its users. You may have a more thorough look at the commands SEEN, TELL, EXPLAIN, EXCHANGE, COUNTRY, CONVERT, TZ, and TOP. Provided some external programs are present at your site, you can also have online spell checker (SPELL), webster lookup (WEBSTER), DNS lookup (HOST), email verification (VRFY), and more. It is very configurable, either by the fixed settings in the dancer.config file, or by the on-line SETtings, or by using the 99% C-alike fpl scripts. It fights clonebots attack very well - it has already handled numerous attacks by up to 20 clonebots from 4 different sites. Much effort has gone into making efficient clonebot defences, while at the same time minimizing unfortunate effects on the innocent user. Future support is almost guaranteed - being a free product no absolute guarantees are given, but because the development team consists of more than one person it is unlikely to be discarded because one person drops out. 1.3 What machine/OS does it need. Dancer is for Unix. It is being developed on SunOS and Solaris. It also has compiled and run from Linux, NetBSD, IRIX, FreeBSD, HPUX, and Ultrix. Furthermore, it works on Amiga. 1.4 How do I report bugs? Send a very detailed report to the mailing list (include OS and bot version). It gives any experienced user the opportunity to help and share wisdom. Bug reports and requests for help in private emails are not as good. 1.5 How do I contribute? Dancer is an open-source project, which means it is being written by volountary authors on their spare time. Join the mailist list and discuss new features and functions with the rest of us. Write additions and send context patches to the project maintainer when done and thoroughly tested. 1.6 How do I apply patches? Every now and then there are patches distributed that fix bugs or add features to existing Dancers. To apply one of those patches to your version, do as follows: You must have the tool known as 'patch', and then preferably the GNU version. 1. cd into your dancer source dir % cd path/to/dancer/src 2. run patch with the patch file as input like % patch < path/to/patch =================================================================== 2. Running 2.1 How do I run it? There are three phases to get Dancer up and running the first time (or each time you receive a new version.) First phase is to compile it; second phase editing important files (this can be done via the install script); third phase starting it. 2.1.1 How do I compile it? All three steps - system configuration, compilation, and installment are done in one go. > make 2.1.1.1 Problems when compiling SunOS Solaris (2.6 upwards usually with gcc versions 2.7.1 - 2.7.3) ------------- Problem: gcc gives you the #error: "No DATAMODEL_NATIVE specified" and/or warning: `NBBY' redefined. Solution: Its time to upgrade your gcc to a new version. See also: http://www.wins.uva.nl/pub/solaris/solaris2.html#q6.28 2.1.1.2 Fpl not found - If the Makefile script doesn't do it for you: If you have compiled fpl and the library wasn't found during the system configuration checks (because it is unable to find libraries placed in non-standard directories) you have to add it yourself. It can also end up that the configure script does find your fpl library, but that when using i.e gdb on the Solaris dancer, it doesn't find the library. The following changes must be done _after_ the system configuration checks (make configure), and _before_ compilation (make). In config.h you have to find and change the line /* #undef HAVE_LIBFPL */ to #define HAVE_LIBFPL In Makefile you have to add -lfpl to the LIBS variable, and -L/path/to/your/libfpl (and also -R/path/to/your/libfpl on Solaris) to the LDFLAGS variable. - If things run the way they were designed to: Invoking the command 'make configure' (or 'make') should already have made the 'fplcheck' shell script run and search for libfpl for you. If it doesn't find it by itself, it asks for a manually entered path. If that doesn't work either, your system simply doesn't have fpl installed. Accept it or install it. 2.1.2 Which files do I have to edit? Using 'make install' (or 'make') pretty much edits the necessary files for you. After that, your bot should be able to run. If the above failed (or you just didn't do it) you have to... Most important is 'dancer.config'. You _must_ edit the "server", "nick", and "channel" fields. If you run 'dancer config', you will get a good standard template written to stdout that we recommend you to start with. Secondly you have to add yourself to the userlist in 'dancer.users', otherwise Dancer will not recognize you at all. If you want to use the 'launch.sh' script to start Dancer (which is highly recommended -- see 2.2) you must edit the "path" variable to point to the directory from where you are running it (if you are in doubt, try the shell command 'pwd'.) 2.1.3 How do I start it? From the directory where you want to run Dancer, type either the name of the executable file (per default 'dancer') or use the 'launch.sh' script (see also 2.2) Dancer may quit IRC, due to server crashes, connections timeouts, system shutdown, and bugs in Dancer. To ensure that it will reconnect you can either run it from a shell loop (don't use 'launch.sh' in that case) or from cron ('launch.sh' contains a short summary of the syntax.) 2.2 Do I have to use the launch script? No, you can start the bot directly with 'dancer'. The advantage of using the launch script is that it will check if you already are running the bot, and exit if so. This make it suitable to use in a cron job. 2.3 It doesn't start. Make sure that your dancer.config and dancer.users are in the same directory as the executable file and that they contain valid information. 2.3.1 The logfile contains a DEBUG statement. If the logfile contains DEBUG statements similar to 02.47.22 DEBUG Parse error in OnJoin(from = "SomeLongNick!user@example.com", line = ":#channel") (snapshot: server.c line 973) and the IRC network you are connected to supports nicks longer than 9 letters, make sure Dancer has been compiled to support them, see question 2.11. If everything else fails try setting the environment variable DANCER_MYHOST to the full name (host and internet domain) of your machine, ie. "setenv DANCER_HOST breese.imada.ou.dk" (this assumes that the machine the bot runs on is called "breese" and is located in the "imada.ou.dk" domain.) It may also be a good idea to add this line to launch.sh if you run it from cron. 2.3.2 The logfile contains an ERROR statement. The end of the logfile may show a few lines similar to this: 12.06.00 *** ERROR: (:Closing Link: [foobar@139.99.99.225] (Ping timeout)) from irc.that-funny-server.com 12.06.00 *** Cleanup 12.06.00 *** No seen item changed, no save performed. 12.06.00 *** Exit This is no stranger than it sounds. The 'ping timeout' message is an error message the ircd server sent you because the bot did not respond properly to the server within time. It is likely because your network connection to the server is very bad at the moment. You could list more than one server for the bot to use, which will make it move on and try the next one in cases like this. 2.4 It doesn't recognize me. Some commands are password protected. The default password is "pass". Type "/msg pass pass" to authenticate. Check if your host name is registered (SVIEW -A). Sometimes DNS fails and you enter IRC with an IP numerics address instead of a hostname. To be on the safe side register both types to your accounts, ie. you@*.site and you@999.999.999.* NOTE: the default password is possible to configure in the .config file and thus you must change the commands suggested accordingly. If the IRC network you are connected to supports nicks longer than 9 letters and you are or have been using such a long nick, make sure Dancer has been compiled to support them, see question 2.11. 2.5 My friend forgot his password. Can I find it somewhere? No, all passwords are encrypted. You cannot read his password, but you can re-install the default password (which can be changed, but is "pass" in all 'factory default' bots) by using the DEFPASS command. 2.6 I cannot dcc chat with it. If you're behind a firewall, try CLIENT. This command makes Dancer send a dcc chat request to you instead. If it says that you already have a connection or a pending attempt to get one, you can abort it with CUT. Sometimes, due to congestion of the network, it is unable to establish a connection because of some TCP timeout value. In that case there's not much else to do than to try again. 2.7 It crashes in mysterious ways. First, remove the optimize (-O, -O2 or -O3) option from the compile flags. (A lot of gcc-versions do generate bad executables when optimizing.) If the bug remains, send us a report and include things like: * the latest entries in the logfile * possible trace-log * details of how we should do to repeat it If the crash generated a core file, enter 'gdb dancer core' (or if the crash happens while you're running the bot through gdb) enter 'bt' and include that output in your report. enter 'quit' to leave gdb again. For systems with limited stack sizes (such as AmigaOS), we suggest you enlarge the stack a lot before running Dancer to prevent getting problems with that. 2.8 How do I upgrade smoothly? Unpack the new archive (it will get extracted in a new directory (named after the new version). Compile the new version. Read the CHANGES file carefully. Perform all actions that are mentioned in it as must-do-things. Rename the old executable and the dancer.config files (just to be able to go back if wanted). Copy the new executabable to the place of the old one. Run 'dancer config' in the old directory. Redirect the output to a temporary file. Edit the file according to your preferences and then save it as 'dancer.config'. Do note that it might contain new entries as well as old ones may have been removed or got different comments. Run the new one. 2.9 How do I make it register with Dalnet or Undernet channel service? Support for channel services has to be enabled at compile time, see section 5.3 and 5.4 in the Dancer documentation. 2.10 How do I bind a dancer to a vhost? Enter a line similar to 'myhost=192.168.10.255' in your normal config file. Replace the above IP address with your own prefered one. 2.11 How do I enable longer than 9 letter nicks? Edit your dancer.h, the lines of interest look like: #define NICKLEN 9 #define NICKLENTXT "9" /*QUOTE(NICKLEN)*/ Change both of these to fit the maximum nick length of your network. Recompile. =================================================================== 3. Commands 3.1 It doesn't answer me if I talk to it from outside the channel. Dancer is a _channel_ bot. It ignores all commands from people it cannot see on the channel. The exceptions are all CTCP, /invite, INVITE, and everything sent through a dcc chat connection. 3.2 How do I use ? Dancer has a simple on-line help feature. HELP gives a short description of the command, and SYNTAX summarize the available arguments and options. 3.3 Can I issue commands in public? Yes, start your command with at least the first 4 letters of the nickname of the bot. Not all commands are publicly available. To use a public command you need at least level 20, or at least level 10 and to be chanop. The reason for this is that public commands should be used if the output is of interest to more than just the one issuing it. See also 'HELP CMD'. 3.4 Can I redirect the output of a command to someone else? Yes. Use "SHOW ". Not all commands allow redirection of their output. 3.5 Can I add my own commands? Yes. It is possible to add commands through fpl. Some examples can be found in the distribution. 3.6 Invite? There are two kinds of invitations. Do not confuse these two! (1) Inviting Dancer to a certain channel. This is used if you want to move Dancer to another channel. It is done by the /invite command (this is an ircII command and may be slightly different on other clients.) Dancer will only react to /invites from users with level 50 and above. If you don't want Dancer to migrate to other channels, you can turn this feature off with "SET INVITE OFF". (2) Getting an invitation from Dancer to an invite-only channel. This is used if you want to join an invite-only (+i) channel where Dancer resides. It is done by sending the command "INVITE " to Dancer. Only users with level 10 and above are able to use this feature. =================================================================== 4. Fpl 4.1 What is fpl? Frexx Programming Language, FPL, is a shared library interpreting language copyright (C) 1992-1998 by FrexxWare. FPL is Freeware and freely distributable for non-commercial purposes only, including extensive documentation and source code. Use within commercial products must be done with written permission from the author. FPL is entirely isolated from the rest of the software. FPL is only the programming language and nothing else. FPL is OS independent. It can (and will) be used under other Operating Systems than this. For more information about FPL, fpl.library (Amiga shared library), fpl.DLL (OS/2 dynamically linked library), fpllib.a (UNIX shared library), other FPL versions, porting issues, bug reports, enhancement requests or anything else regarding this subject, don't hesitate to get in touch with the author. Author: Daniel Stenberg =================================================================== 5. Files 5.1 Where can I get the latest version of Dancer? The official homepage of Dancer, which always contains the latest relevant information, is at: http://dancer.sourceforge.net 5.2 Where can I find the fpl library? http://www.contactor.se/~dast/fpl/ http://www.contactor.se/~dast/fpl-old/ 5.3 Where can I find ? For finding programs in general 'archie' is highly recommended. If 'archie' isn't installed at your site you can try one of the web versions (http://www.funet.fi/funet/archie/archieplexform.html.) You may also want to try a web search (guide.infoseek.com, altavista.digital.com) The following are examples of places where you can find some of the more exotic programs used by Dancer. Basic programs like the sh shell, echo, head, grep, etc. are not listed. host -- DNS lookup ftp://ftp.nikhef.nl/pub/network/host.tar.gz vrfy -- Email verifier ftp://ftp.nikhef.nl/pub/network/vrfy.tar.gz ispell -- Spellchecker http://fmg-www.cs.ucla.edu/geoff/ispell.html webster -- English dictionary lookup ftp://moose.cs.indiana.edu/pub/webster/webster.tar.Z