www.astrolox.com

** Offfical APIB Design Sheet **

++++++++++++ WARNING +++++++++++
+++ This is work in progress +++
++++++++++++ WARNING +++++++++++

Title: IMHO Almost Perfect IRC Bot Design (APIB)
Author: Astrolox, http://www.astrolox.com/
Date: January, 2000
 Index: Versions Modest Goals High Security Commands List APIB BotNet Protocol Add-In Protocol  Versions: Design:        release 1 revision 0 beta 1 APIB BotNet:   release 1 revision 0 beta 1 APIB Add-Ins:  release 1 revision 0 beta 1  Modest Goals:  DC - Designed?, Commands Designed?  (Y = Yes, N = No, F = Future)  *  General N       +  Simple Setup YY      +  Flexable Configuration YY      +  High Security Y       +  Add-Ins YY      +  Channel Protector [on/off], auto(de)ops, bans, invites, autovoice NN      +  Nick Protector [on/off] NN       -  Channel specific - allowing only people with the correct password to use that in nick in the channel, kick FF       -  Server wide - allowing only people with the correct password to stay on the server, kill YY      +  Messages Server [on/off] YY       -  Send and Receive messages from other users YY      +  File Server [on/off] FF       -  Channel specific areas YY       -  Upload / Download ratios Y      *  Telnet F       +  Actual VT100 emulation Y      *  Bot Network YF      +  Protocol apib v1.0 FF      +  Protocols eggdrop v1.3 & 1.4, emech v2.7 N       +  User file merging -or- Master & Slave setup  High Security:  Anyone who understands the chmod command under unix will be able to understand this similar system really easily.  Anyone else will just have to play and tweek until they figger it out.  This system is designed to give major flexability without cluttering each user with a million flags and making a major headache for the Bot Owner.  Points:  1) Each user has an id number - when on the bot net the id translates to a id@bot pair  2) The bot owner sets up groups, each group has an id number.  3) Each user belongs to one or more groups  4) Each command and privilage has an (num groups) limited number of groups and a (num groups + num chans) limited number of attributes. The first set of attributes is for everyone not covered by any others. The second set of attributes is for the first group it has. The third set of attributes is for the second group it has. The ….. set of attributes is for the …… group it has. .. etc ..  NOTE: As well as giving access to just two groups of people it can be used to remove access from just two groups of people.  5) The attributes for the commands and privileges can be either no, yes or the name of a channel.  The channel name will allow you to create users that can only op people in one channel but not annother.  6) When several sets of attributes for the command being executed, or priv being used are valid then the set of attributes used is defined by a user configured variable which has the options “best” or “worst”.  If it is best then the bot shall grant the best rights allowed to the user, if worst then the bot shall grant the worst rights found to the user.  The second is the default value.  This could cause a problem with incorrectly written subroutines (if you are writting patches, etc … be warned).  7) All id numbers start at 1, number 0 is reserved for “disable”  Security Example: Users: id  nick        Groups: id  name           members 1 - MrOwner             1 - BotOwners    - 1 2 - Usr2                2 - Users        - 1,2,3,4,5 3 - Usr3                3 - ChanMasters  - 1,2 4 - Usr4                4 - BotMasters   - 1,3 5 - Usr5                5 - Chan2Masters - 1,4  Commands: name        c/p    groups   attr 1   attr 2   attr 3 & Privs  die       - cmd  - 1      - no     - yes link      - cmd  - 4      - no     - yes op        - cmd  - 3,5    - no     - yes    - #chan2 ban       - cmd  - 3,4    - no     - yes    - yes message   - cmd  -        - yes hello     - cmd  - 2      - yes    - no partyline - priv - 2      - no     - yes  Usings these three tables it is pretty simple to see at a glance which users have access to what and while they are in which channels.  Summary: MrOwner can do everything that anyone else is allowed to do because his id (1) is in every group. Usr2 is a channel master via group 3 which is not restricted to any certian channel, so Usr2 is a master in all channels the bot is sitting on.
Usr3 is a bot master and is the only person other than MrOwner who can link
bots together.  However, because he is a bot master he does not get any
special rights given to channel masters, etc.. like on some bots 
Usr4 is a channel master via group 5 which is restricted to #chan2 only, so
Usr4 is a master in #chan2 only and a normal user in all other channels.
Usr5 is a standard user that can do nothing other than use the partyline.

Anyone, if they are, or are not, in a group can send messages.
Only people who are not in the users group can introduce them self (hello),
however a user defined varabile can mess these attributes up a little (see
High Security Point 6), so the routine should not rely on the attributes
making sure the wrong people don’t execute them.

Commands List:

When a command appears twice then you know the command will have a switch to
specifiy which way you wish for it to behave.  eg,  msg p  or  msg b.

Bot:
stat, set, rehash, restart, shutdown, die, cpset
Telnet:
stat, echo
BotNet:
stat, set, link, unlink, list, trace
Server:
stat, connect, disconnect, add, del, list, jump, dump, bnick, msg, ignore
Partyline:
stat, list, say, act, ban, msg
Channel:
stat, list, say, act, rejoin, mode, topic, invite, op, deop, kick, ban
UserAdin:
stat, list, add, del, whois, pass, set
GroupAdmin:
list, add, del, set
General:
help, set, motd

FileServer:
stat, ratio, dir, cd, get, put, attrib, tree
Network:
stat, ident, ping, traceroute, nslookup
tcp: connect, disconnect, send, listen, forward
udp: send, listen, forward

############################################################################
[?] Denotes that ? is reqired       Denotes that ? is optional
############################################################################

cpset [name]  :
Shows or sets the attributes on the command or privilege with the name of
‘name’ (to the attribute given).
Attribute num is the number of the attribute to alter - however, if it is
0 then attribute is a list of groups to add.

rehash:
Reloads the configuration file

restart [type] :
Restarts the bot
Type can be either “warm” or “cold”. If warm then the process will just
go back to the start of its code. If cold then it will execuate a new
copy of its self with a start-wait command, it will then quit.  The new
copy will start working once it sees the old copy has actually quit.
Seconds is how many seconds until restart should happen

shutdown :
Stops the process, saving files, etc..
Seconds is how many seconds until the shutdown should happen

die :
Stops the process and quites - no saves, not clean

echo [on|off]:
switches echo on or off for the current telnet session

link [bot]  :
SetsUp or Activates a link to annother bot

unlink [bot]:
Removes or Deactivates a link to annother bot

trace [bot]:
Shows how many bots are between this bot and the other bot

rejoin :
Makes the bot leave and then join the channel (good for testing)

jump:
Disconnects from current irc server and connects to a different one

dump [output]:
Sends raw commands to the irc server

bnick [nick]:
Changes the nick of the bot

ignore [nick]:
Sets the bot to ignore a certian nick

mode :
Displays or changes the channels mode

topic :
Displays or changes the channels topic

invite [nick]:
Sends someone an invite to join the channel

op [nick]  :
Ops a user in the channel
Seconds_in is how many seconds until the op should happen
Seconds_length is for how long the op should last, the bot will
automatically deop the nick once the time has elapsed

deop [nick] :
Removes ops from an op in the channel
Seconds is how many seconds until the deop should happen

kick [nick] :
Kicks a user from the channel
Seconds is how many seconds until the kick should happen

whois [nick]:
Gives information about a user

pass [nick] [password]:
Changes a users password

help :
Shows help screens

motd:
Shows the Message Of The Day

ratio :
Allows admins to set the ratio and users to check it, also shows the
current credit balance the calling user has

dir:
Shows listing of current directory

cd [dir]:
Changes directory
get [file]: DCC Sends the requested file to the user - if possible  put [file]: DCC Gets the requested file from the user - if possible  attrib [file] [+|- dfh]: Allows admins to change file attributes d = downloadable, f = free, h = hidden  tree : Shows a directory tree  ident [host]: makes an ident request  ping [host]: pings a host  traceroute [host]: uses icmp to trace a route to a host  nslookup [host|ip]: looks up a dns address for an ip or reverse  stat [type]: type can be; bot: Gives status of the bot telnet: incomming connections, since when, etc botnet: who we are connected to, since when, etc server: to where, for how long, etc party: how many users on party line, etc channel: bans/kicks lists, how many kicks, etc.. files: how many file transfers, etc.. network: listening connections, outgoing conn, incomming conn, etc… users: status of all online users  set [type] … type can be; var [name] <+>: Sets name = data - saved to current users record botnet [item] [bot] <+>: Sets item = data on given bot - saved to botnet config bot [item] [bot] <+>: Sets item = data on given bot - saved to bot config user [id] [r|w] [item] <+>: Sets item = data to nick’s user record Specify r is it is read only (ie user can not change only admin) or w if it is writtable group [id] <-|+ uids>: Adds or removes space seperated user ids (uids) from a group  list [type]: Type can be; bots:     Lists all known bots servers:  Lists all irc servers in the list users:    Lists all users groups:   Lists all groups  channel:  Lists current users on the channel party:    Lists current users on the partyline (current room?)  connect [type] [ip] [port]: Type can be either irc or tcp.  disconnect [sid]: sid = Session ID use, ’stat network’ or ’stat server’ to find it Disconnects an exisiting connection  send [protocol] … Protocol can be; tcp [sid] [data]: Sends tcp data down stream numbered sid udp [data] [ip] [port]: Sends udp data to given address  listen [protocol] [port]: Protocol can be either tcp, udp or both Starts a listening server on given port with given protocol  forward [protocol] [lport] [rip] : Protocol can be either tcp, udp or both lport = local port, rip = remote ip, rport = remote port Forwards a port on the bots computer to annother computer:port pair  add [type] … Type can be; server [ip] [port]: Adds an irc server to the list user [nick]: Adds a new user (they are not told) group [name]: Adds a group  del [type]: Type can be; server, user or group  msg [type] [to] [message]: Type can be; irc or private (bot user 2 bot user) To is the person to receive the message Message is the message  say  [message]: Where can be the name of a channel, if not given the partyline is used (note: don’t start your sentense with & or # on the partyline)  act  [message]: Where can be the name of a channel, if not given the partyline is used (note: don’t start your sentense with & or # on the partyline) Makes the bot do something on the channel or the user do something on the partyline (like using /ME)  ban [nick|hostmask|ip] : Bans a hostmask/ip, or a user from entering a channel Channel can be * to be all channels  APIB BotNet Protocol:  The reasons behind why people link bots together are usually dependant on the user that is doing the linking.  Sometimes it is to share information, other times it is to provide communication over between irc networks, other times it is just for fun, and the list goes on .. needless to say it is a very popular thing to do.  So this is how APIB does it …  Points:  1) Everything is sent as packets  2) ASCII characters 0 to 7 are reserved and can not be used as data * ASCII 0 - end of packet * ASCII 1 - end of feild * ASCII 2 - end of data sub feild  3) Each packet looks like this; * Sending bots protocol version, 3 bytes long only * Sending bots software version, end with ASCII 1 * Sending bots name, end with ASCII 1 * Receiving bots name, end with ASCII 1 * Max number of hops, end with ASCII 1 * Sending users id, end with ASCII 1 * Receiving users id, end with ASCII 1 * Command Code, end with ASCII 1 * Data, end with ASCII 0

4) User ids can be 0 to specify no user. This would include;
* bot 2 bot error messages
* user 2 bot commands (eg, adie, ashutdown, alink, aop)

5) Command codes are any combination of letters and numbers and can be any
length, but MUST start with a letter.  Lowercase letters are defined
by this design sheet.  Uppercase letters are custom commands (see later).

6) Bots do not confirm packets, as long as there is not an error you can
assume they have received them.

Command Codes:

Add-Ins are not allowed to reserve any command codes starting with a
lowercase letter for use over the bot net, only an uppercase letter.
Command codes are case sensitive! (duh)

a*     All commands starting with a lower case ‘a’ (ASCII 97) are console
commands (these commands are listed above)

bpass  Data contains a password only.  This command allows a bot to
authenticate to annother bot upon linking

bcons  Requests a list of all the bot that the receiving bot has an active
connection to.  Sending is with a empty packet, reply is with full
packet.

btime  Requests the current GMT time from annother bot. Sending is with a
empty packet, reply is with full packet.
Can be used as a bot ping tool.

btrace This is a command that is acted upon by all bots that receive it.
** This command can be switched off **
When received the bot should add it’s name to the list (CR delimited)
stored in the data feild and forward it on, as long as reply is not
at the start of the data, in which case it just forwards it.
If this bot is the receiver then it should add the word reply to the
start of the data feild and then send the packet back to the sender.

++++++ More Commands to come

APIB Add-Ins Protocol:

Most bots used some kind of scripting language to allow people to create
additions and new features.  Some bots don’t bother at all, if you want
something new then you have to recompile.  This bot uses a cgi like design
where each add-in is not a script or even a part of the bot.  An add-in is
a totally different process that communicates with the bot via STDIN and
STDOUT. This is how it works;

1/ The add-in is called to install its self .. it adds its commands and
events to the CmdEvn file.  This can be done when the bot is or is not
running, it don’t matter.

2/ A user calls one of the add-in commands or triggers an add-in event,
the bot starts the new program and passes it all the information via
the STDOUT (add-ins STDIN).

3/ The add-in works on the data and does what it needs, it can send commands
back to the bot via STDOUT (bots STDIN) if it wishes.  The bot will give
all add-ins complete access to all the commands.  ** BE WARNED **

4/ The add-in quits.
It can run for as long as it likes however a new instance will be started
everytime a command is called or an event occurs.