_ _ m o z i l l a |.| o r g | | _ __ ___ ___ ___| |__ ___ | |_ | '_ ` _ \ / _ \_ / '_ \ / _ \| __| | | | | | | (_) / /| |_) | (_) | |_ |_| |_| |_|\___/___|_.__/ \___/ \__| ==================================== INSTALLATION ------------ You will need the following programs and libraries to run mozbot2: perl wget Net::IRC Net::SMTP IO::Select IO::Pipe These packages may have additional requirements of their own. In order to do anything useful with mozbot2, you will need some Bot Modules. Several are included in this distribution, and they may have requirements above and beyond those given above. Once you have set up all the packages on which mozbot2 depends, make mozbot.pl executable: chmod +x mozbot.pl This is needed since mozbot2 will occasionally attempt to restart itself (e.g. if its source code is changed). Then, simply run mozbot.pl: ./mozbot.pl Currently, you MUST run mozbot from the directory in which mozbot.pl is placed. This may be changed in a future version. SECURITY -------- Since mozbot interacts with the outside world, do not run it as a privileged user!!! In addition, since mozbot calls external programs (currently perl and wget, possibly others in future versions) make sure that none of the directories on your path are writable by untrusted users! (e.g., do not put /tmp into your path!) Make sure that '.' is not in your path! This is a security risk in a situation like this, and perl will rightly refuse to execute external programs (like wget, used to get remote URIs for many functions) if '.' is on your path. Do not run the bot straight into a public channel on the first run! One important reason not to load the bot straight into a public channel on the first run is that until it has been properly configured, it will have a well defined username and password to access all its admin functions. Thus a malicious user could hijack the bot the moment it joined the channel. If this is a serious problem for you (e.g., your users are of a particularly high calibre and are doing regular polls of the /who command to see if any bots join) then use another server, such as one that you control, on localhost! See the "Administration" section for instructions on how to change the administration password (important!). Note: Passwords are printed in clear text on the console and in the log files. Secure them accordingly. Of course, IRC is an inherently insecure protocol anyway, and any machine between your IRC client's and your bot's, going through the IRC network's servers, will have access to the passwords. For this reason, change them often, and don't use passwords that you use for important things here. The default setting is for mozbot to run with taint checking enabled. I *STRONGLY* recommend not changing this. CONFIGURATION ------------- When you start up mozbot for the first time, it will prompt you for the following information: 1. IRC server. What machine you want the bot to connect to. At the moment, mozbot only supports connecting to a single server at a time. It would require a *significant* amount of work to change this. 2. Port. What port to connect to on the IRC server. Typically, this will be 6667 or therabouts. 3. Password. If your server has a password, enter it here. If there isn't one (and this is almost certainly the case) then just hit enter. 4. Channels. What channels the bot should initially connect to. It is recommended that this just be a bot channel or a test channel, for example #mozbot, since running a bot for the first time before it is known to be ready is a bad idea. You can enter more than one channel, just hit enter after each one (leave a blank line when you have finished). (To make mozbot join a keyed channel, you must first add the channel's key to the 'channelKeys' variable. To do this, the bot will have to be on IRC first, so don't worry about it for now.) 5. Your e-mail address. In case of great difficulties, mozbot may try to e-mail you. If this happens, it will use the e-mail address you gave here. This only happens if (a) it absolutely cannot connect to the server you gave it, or (b) it cannot find a nick that is not in use. 6. SMTP server. The name of the SMTP server it should try to talk with in order to send you mail. If you type in an invalid server name, it will just fail to send mail and instead will complain bitterly to its console. 7. Nicks. Some nicks for IRC. For example, 'mozbot'. It is customary to clearly mark the bot as being non-human, for example by putting 'bot' in the name. You should enter several possibilities here. Hit enter after each one. Leave a blank line to finish. Once the bot is running, there are many other things that can be configured with it. See "variables". Note. The bot will treat all channel names as lowercase to avoid case sensitivity issues. LOGGING ------- Normally, mozbot will output its complaints to the console (stdout). If you run mozbot in an xterm or screen session, you can therefore easily keep track of what is going on. It will also continuously log output to ~/logs/$0.$$.log, where $0 is the file name and $$ is the PID. You may wish to set up a cron job to prune this file on a regular basis, it gets LARGE. However, it can sometimes be the only way to track down how your system was compromised if it turns out that mozbot has a security flaw. Control over the logging is currently not available. This may change in future versions. Note that when the bot forks and then outputs a message, which happens occasionally, it will therefore use a new log file for the forked process. This should only happen when something bad happens, e.g. something forces the bot to restart or the bot forks and then the child enters a bad state. Note. Authentication passwords will be displayed in cleartext on the console and in the log files. ADMINISTRATION -------------- Once the bot is active and on the IRC server, it starts to listen to all messages seen on any channels on which it is present, and all messages sent to it using /msg. Your first task should be to change the admin password. To do this, authenticate yourself using the "auth" command. The default username is "admin", and the default password is "password". If the bot is called "mozbot", then the command to authenticate would be as follows: /msg mozbot auth admin password The bot should respond with "Hi admin!". Now create yourself an account by adding a username/password pair to the bot. You do this with the "newuser" command. Next, you should bless this new user, making it a bot administrator. This is done using these commands: /msg mozbot newuser /msg mozbot bless Now authenticate yourself again, as the new user: /msg mozbot auth The moment you authenticate as the new admin, the default admin account is deleted. You are now in a position to add the modules you want and to put the bot in the channels you want it in. To load modules is easy. /msg mozbot load module ...where "module" is a module name, such as "HelloWorld" (note that the ".bm" extension is not included). By default, the General, Greeting, Infobot and Parrot modules are loaded. The General module provides the 'help' command and responds to CTCP VERSION messages. The Greeting module responds to greetings and generally tries to be friendly. The Infobot module provides information storage and retrieval functions. The Parrot module lets an admin control the bot much like a puppet. By default, modules will be enabled in all channels. See the "variables" section below to change this. HINTS ----- If the bot goes mad and starts flooding a channel -- e.g., if someone keeps asking it for information -- then authenticate and then send it the following message: /msg mozbot shutup please It should respond within a few seconds. You can authenticate while it is speaking, that's not a problem. VARIABLES --------- For information on changing variables on the fly, use the "vars" command: /msg mozbot vars Each module has several variables that you can change. You can see what they are by typing: /msg mozbot vars module ...where module is the module in question. These always include "Admin" and "General". Admin provides the commands such as "auth", "newuser", "password", and provides additional commands to admins, such as "shutdown", "cycle", "leave", "restart", and so on. "General" provides the "help" command to everyone. The main variables are: channels -- which channels the module should listen in, and which channels the module should send announcements to. Must be in lowercase! channelKeys -- a mapping of (lowercase) channel names to keys. It is assumed that any channel without an entry in this variable has no key. For example, to tell mozbot that the key for channel #channel is 'password', you would use: /msg mozbot vars Admin channelKeys '+|#channel|password' autojoin -- whether (1) or not (0) the module should automatically add a new channel to its "channels" list when the bot joins a new channel. If this is not enabled, then you will have to add new channels to the "channels" list of this module each time. channelsBlocked -- channels that will not be autojoined, so if a module has been disabled, it won't rejoin the channel if the bot is kicked then reinvited. denyusers -- user@host regexp masks of users that should be completely ignored (for this module). The regexp will be placed between "^" and "$" modifiers, so do not include them, and *do* include everything required to make the whole user@host mask match. allowusers -- identical in usage to denyusers, but checked first to override it. So to give access to everyone but a few people, leave allowusers blank and add some masks to denyusers, but to give access to only a few people, add their user@host masks to allowusers, and add ".*" to denyusers. In addition, other modules may have extra variables. The admin variable has quite a few variables, including all those that are prompted for during initial startup. The interesting ones are: currentnick -- the nick. This can be changed on the fly. server, port, password -- the server and port to connect to, and the server password to use. If you change these and then cycle the bot (/msg mozbot cycle) then the bot will change servers without shutting down. localAddr -- if you don't seem to be able to establish a connection, but it works fine with other software, then you should try setting the localAddr variable to your IP address. Technically, this variable sets which interface to use to form the outgoing connection. (This is to work around a limitation of Net::IRC.) Typically you would set this variable directly in the configuration file, by adding a line that says "localAddr=10.11.12.13" or whatever your IP address is. simpleIRCNameServer -- if the value of this variable equals the name of the server, then the IRC Name sent to the server will be simplified so that it doesn't include the URI of the mozbot help files. This is usually dealt with automatically, but if you are having troubles connecting, you could try setting it. (It is set to the name of the server so that if you change servers, by default mozbot will use a complete IRC Name again.) username -- if this variable has a true value, then the bot will use its value as its IRC username. By default, the bot uses "pid-1234" as the username, where "1234" is the bot's process ID. This can cause problems on networks or with BNCs that require a valid and accurate ident, in which case this variable can provide a solution. (You can also set this variable by entering "username=blah" into the configuration file, where blah is the username you want to use.) channels -- unlike other modules, the channels variable for the Admin module actually controls which channels the bot itself appears in. The preferred method for controlling this is using /invite and /kick or "join" and "part", though (since editing the list directly will probably require a cycle of the bot to take effect). admins -- the administrators. See "Administration" above. allowInviting -- this controls whether the /invite IRC command will be obeyed or not. allowChannelAdmin -- this controls whether or not the bot will accept admin commands that are given in a channel or not. In any case, the "auth" command is never accepted in a channel. files -- this is a list of files whose timestamps are monitored to decide if the source code has changed. If it is established that any of these files have changed while the bot is running, then the bot will shutdown and restart itself. Modules are dealt with separately, and need not be listed here. (And when modules change, the whole bot is not restarted, only the module.) sourceCodeCheckDelay -- number of seconds between checks of the bot and module sources. Note that changes will only take effect after the previous timer has passed, so changing it from 3600 (an hour) to 10 (10 seconds) may not be of much immediate use. In these cases, setting the variable to the new value then cycling the bot is a good plan. ignoredUsers -- a list of regular expressions that are matched against the user@host strings of everything that is said. If a user matches one of the entires in this list, then that user will be completely ignored. (^ and $ symbols are implied at the start and end of this regular expression.) Use this sparingly. It will stop the user's statements from having _any_ effect on the bot, including in any statistic-collecting modules, etc. If you just want to block a user from certain modules, add a regular expression to the 'denyusers' variable of those modules. Example: >mozbot< vars Admin ignoredUsers '+root@.*' *** moron (root@example.org) has joined #mozbot mozbot: help * you watch the tumbleweed roll on by ignoredTargets -- when someone says something to someone who matches one of the regular expressions in this list, the line will be ignored as if the person saying it was banned with ignoreUsers. This is useful when you have other bots in the channel, and don't want the mozbot to respond in place of the other bots (e.g. with an auto-helping Infobot module). Note: It is safe to user a regular expression that matches the mozbot bot's name; it will always respond to messages to itself (as well as messages that are sent via /msg) irrespective of this setting. Example: foobot: what is green? user: green is good. user: green is good. mozbot: vars Admin ignoredTargets '+.*bot[0-9]*' Variable 'ignoredTargets' in module 'Admin' has changed. foobot: what is green? user: green is good. * user patpats mozbot Changes to variables are usually immediately recorded in the configuration file and will be saved for the next time the bot is loaded. There are three types of editable variables: scalars, arrays of scalars, and hashes of scalars. Scalars are easy, and lists are explained by the bot quite well, just try to set a list and it will tell you if you are doing something wrong! To add a value to a hash, there is a more complex syntax. For example, to add a new site to the list of sites that the RDF module monitors, use the following command: /msg mozbot vars RDF sites '+|slashdot|http://slashdot.org/slashdot.rdf' First, note that the value is surrounded by quotes. You can nest quotes without any problems, the quotes are just needed to differentiate significant trailing whitespace from mistakes. The "+" means you want to add a value to the hash (as you'll see in a minute, to remove an item you use "-"). Then, since a hash is a key/value pair, you have to delimit the two. In this case, we have used "|" as a delimiter. However, you could use anything. The first occurance tells mozbot what delimiter you have picked. The second separates the key (in this case the site nickname) from the value (in this case the URI). For example: /msg mozbot vars RDF sites '+*key*value' You could even use a letter as a delimiter, but since that is usually a sign that you have forgotten to declare which delimiter you are using, mozbot will warn you about this. For example (the 'users' hash, BTW, is the hash in which all the username/password pairs are kept): /msg mozbot vars Admin users '+sarah|lisa' ...will be treated the same as: /msg mozbot vars Admin users '+*arah|li*a' ..., i.e. the username added would be "arah|li" and the password would be "a". This is not a bug, it's a feature. It means you can include any character, including "'", "|", and so on, in the key, without fear of it being interpreted as a delimiter. To remove a user, or any key/value pair in a hash, you use this syntax: /msg mozbot vars Admin users '-admin' That's it. No need to say what the value is, since each key in a hash has to be unique. (Although, in this particular case, it should be noted that the preferred way to remove users is actually the 'deleteuser' command.) -- end --