---------------------------------
      NETBOTS DOCUMENTATION
---------------------------------
	netbots.tcl v2.20
       by slennox, 23/6/99
botnet script for eggdrop 1.3.17+
---------------------------------
E-mail:   slennox@egghelp.org
IRC:      #eggheads on EFnet
URL:      http://www.egghelp.org/
---------------------------------

Use an editor that supports word wrap to view the documentation files.

This file contains general information about netbots.tcl that you'll need to know before you use the script. You will also need to read components.txt which describes each component and their settings. If you're updating from an earlier version of netbots.tcl, I recommend you read updates.txt.

Important: you should only download new versions of this script from http://www.egghelp.org/ or http://www.ozemail.com.au/~slenny/eggdrop/ - these are the *only* valid distribution sites for netbots.tcl v2.xx. Copies of this script found at other locations may contain backdoors.


INDEX
 Introduction
 Features
 Setup
 Netupdate Explained
 Using Netupdate
 Configuration & Components
 Adding Your Own Components
 Support
 Credits
 Disclaimer


INTRODUCTION

netbots.tcl is a flexible, feature-rich, and relatively secure botnet script for eggdrop 1.3.17 and later versions. It combines many of my previous standalone scripts, such as netbots.tcl v1.xx, sentinel.tcl, botnetop.tcl, etc. with additional refinements and features designed to make botnet management easier and less time-consuming.


FEATURES

* Allows you to make a whole botnet perform a function with a single command (e.g. make all bots join a channel, rehash, reply with shell info, etc.). Integrated help explains all the different netbot commands.
* Built-in update feature lets you update netbots.tcl, bot config files, and motd files across a whole botnet with a single command on the hub bot (or other file distribution bot). No longer do you need to FTP to each bot's shell for updates and changes.
* Update-check automatically informs you when a newer version of netbots.tcl is available.
* Botnet communications are encrypted. Multiple security options allow you to strike an appropriate balance between functionality and security for your situation.
* Component structure lets you load only those components of the script you need to use - the script won't bloat your bot with features you don't need. You can also add your own tcl scripts as components.
* Many useful components included, such as sentinel.tcl for flood protection, chanlimit.tcl for automatic channel limiting, mainserver.tcl for bot server management, and many more.
* You can customise script settings for each bot in a single copy of the script - no need to have separate versions of the script to use different settings on a particular bot.
* This nice big documentation file, with integrated headings, bulleted lists, indented text, and correct spelling! :P~~


SETUP

In this section it's assumed you have a reasonable knowledge of eggdrop and how to use tcl scripts - if you don't, you should stop here and not use this script.

1) At the moment, you only need to change one setting in the netbots.tcl file. You can deal with the rest later. Near the top of the file you'll see the line 'set nb_key "changethis"'. Change that to a random set of alpha-numeric characters, e.g. "e9gn4bMu".
2) Copy the netbots.tcl script to each bot's shell. You can place it in the /scripts directory with other tcl scripts, but you may instead place it somewhere else within the bot's directory if you wish. Unless you plan on having a strange setup, the filename and location of the netbots.tcl script must be the same on all netbots - e.g. if it's located at scripts/netbots.tcl on one bot's shell, it must be scripts/netbots.tcl in all the others.
3) At the end of each bot's config file, add the line 'source scripts/netbots.tcl' (assuming scripts/netbots.tcl is where you placed the script).
4) Rehash each bot on the botnet (if you have any of my old standalone scripts installed, you should probably shut down and restart each bot instead of just rehashing). The basic netbots component with the default settings will be loaded on each bot.


NETUPDATE EXPLAINED

Before you start to customise the settings, you need to be familiar with the netupdate feature. You should choose a bot on your botnet, preferably the hub bot, which will serve as a distribution bot for the netbots.tcl script, bot config files, and motd files. In the rest of the documentation, I'll assume you're using the hub as the distribution bot.

The hub's shell must contain the netbots.tcl script, all bot config files (with separate filenames for each bot's config), and motd. Using a fictitious hub bot (BigBoy) and a couple of leaf bots (Camelback and Mallard), here is a visual example of a typical setup:

 BigBoy's shell (hub bot):
  bigboy.conf camelback.conf mallard.conf motd netbots.tcl
 Camelback's shell:
  camelback.conf motd netbots.tcl
 Mallard's shell:
  mallard.conf motd netbots.tcl

When a script netupdate is initiated, Camelback and Mallard will request the file 'netbots.tcl' from BigBoy. When an motd netupdate is initiated, they will request 'motd'. However, when a config file netupdate is initiated, Camelback will request 'camelback.conf' while Mallard will request 'mallard.conf'. Now let's say you want BigBoy, Camelback, and Mallard to each have their own motd:

 BigBoy's shell (hub bot):
  bigboy.conf bigboy.motd camelback.conf camelback.motd mallard.conf mallard.motd netbots.tcl
 Camelback's shell:
  camelback.conf camelback.motd netbots.tcl
 Mallard's shell:
  mallard.conf mallard.motd netbots.tcl

In this setup, Camelback will request 'camelback.motd' during an motd netupdate, while Mallard will request 'mallard.motd'.

In summary, you can choose any filename you want for the netbots.tcl file(s), config files, and motd file(s). You just need to make sure the files needed by each leaf bot is present on the hub bot's shell with the same filename and location.

Note: config files, motds, and the netbots.tcl file should be edited and saved in an editor that supports the Unix file format, such as EditPlus (available at http://www.editplus.com/). Windows editors which save in the PC file format may cause problems with netupdate. Another option is to use your Windows editor, then after uploading the file to you shell open the file and save it in pico - that will convert it to the Unix format.


USING NETUPDATE

You will typically use netupdate when you want to:

  upgrade a bot or bots to a new version of netbots.tcl;
  update netbots.tcl settings for a bot or bots;
  update config files for a bot or bots;
  update motd files for a bot or bots.

To use netupdate, do the following:

1) Upload the new/changed netbots.tcl script, config file(s), or motd(s) to the hub's shell. If updating netbots.tcl to a new version or if changing the nb_key or nb_flag options, don't rehash the hub just yet as certain changes may prevent the transfer.
2) Use the '.netupdate [option] [bot]' command on the hub bot. Valid options are -config, -motd, and -script. If a bot is specified, the specified bot is updated, otherwise all bots are updated. Examples: 'netupdate -script' will transfer netbots.tcl to all bots, 'netupdate -config Mallard' will transfer the appropriate config file to Mallard.
3) Depending on how many bots you have and which files you're updating, the transfer may take a few seconds to a several minutes. Each bot will rehash itself after receiving an update (except on motd updates).
4) Once all transfers are complete, .rehash the hub if you updated netbots.tcl or the hub's config file.


CONFIGURATION & COMPONENTS

The netbots.tcl script is split into two sections - the netbots core script, and additional 'component' scripts. Additional components include such scripts as sentinel.tcl, botnetop.tcl, etc. Using the settings section at the top of the netbots.tcl file, you can choose whether or not a bot or bots should load a component. For more information about each component and their respective settings, see the components.txt file.

All script and component settings are set in the top section of the netbots.tcl file. Settings are set in pretty much the same way you set them in other scripts, but there are two distinct features - nb_component and nb_set.

The nb_component setting determines whether or not to load a particular component. Example:

  set nb_component(sentinel) 1
  set nb_component(chanlimit) 0

In the above case, the bot will load the sentinel component, but not the chanlimit component. 1 loads the component, 0 skips the component.

The nb_set feature allows you to customise components and settings for each netbot in the hub's copy of the netbots.tcl file - you don't need to create different versions of netbots.tcl to have different components/settings for each bot. By default, all bots will use the standard settings - e.g. if you have 'set nb_idlekick 0', all the other bots will use that setting for nb_idlekick. If you'd like a bot to use a different setting, you add an nb_set line. The nb_set syntax is:

  set nb_set(Bot!setting) value
               OR
  set nb_set(Bot,Bot,Bot!setting) value
               OR
  set nb_set($nb_group(groupname)!setting) value   (nb_group is explained in components.txt)

The nb_set line is placed after the default setting. Example:

  set nb_idlekick 0
  set nb_set(Mikado,BoBo!nb_idlekick) 60

Mikado and BoBo will set nb_idlekick to 60, while all other bots will set it to 0.

To customise *components* for different bots, simply do:

  set nb_component(chanlimit) 0
  set nb_set(BoBo!nb_component(chanlimit)) 1

BoBo will load the chanlimit.tcl component, while other bots won't.


ADDING YOUR OWN COMPONENTS

Adding components (i.e. scripts) to netbots.tcl is quite simple, and you will be able to take advantage of nb_component and nb_set features with your component. Furthermore, because your component is integrated with netbots.tcl, it can be updated across the botnet with the .netupdate -script command. To add your own component, all you really need to do is add a couple of lines to netbots.tcl, and do a bit of copying and pasting. Scroll down near the bottom of the netbots.tcl file, and find the section specified for additional components. Now take a look at the following:

  # Start of additional components

  set nb_component(scriptname) 1
  script settings

  if {$nb_component(scriptname)} {

  the script (including procs, binds, etc.)

  }

  # End of additional components

As you can see, all you need to do is put the nb_component setting and script settings (if any) at the top, add the nb_component check (including the open and close braces), and paste the script in between. You can take advantage of the nb_set feature in the script settings, using the same syntax as for the included netbots.tcl components.

Whenever you update to a new version of netbots.tcl, simply copy whatever you've put between "Start of additional components" and "End of additional components" to the same section in the new version.


SUPPORT

Need help with the script? Found a bug?

You can contact me at slennox@egghelp.org, or find me in the #eggheads channel on EFnet.

Note: while I accept suggestions for changes and new features, I don't like being hounded about these things. Remember that you're not paying to use this software, so if there are missing features or you don't like the way something works, tough cookies. If you don't like it, don't use it.


CREDITS

Many thanks to Bass, dw, Tothwolf, and especially guppy (my little hunnybunny :P~). Thanks also to \-\iTman and upstream for their help testing my scripts.


DISCLAIMER

netbots.tcl is provided 'as is' without warranty of any kind.
