@database AmiBot.guide

@node main Documentation for AmiBot

                               AmiBot v0.97

                               Public Domain

       This archive may be distributed in any way as long as it is complete.

                 960703, johan englund, na94jed@student.hgs.se

                            @{"Acknowledgements  " link ack}
                            @{"Introduction      " link whatis}
                            @{"Installation      " link install}
                            @{"Configuration     " link variables}
                            @{"Usage             " link using}
                            @{"Future plans      " link future}
                            @{"History           " link history}


            In case you wonder, this program  has NO  backdoors written
            by me. If there  are any, they  have been hacked into place
            by other low-life creatures. I have no interests in getting
            inside  your amiga. Though, this is hard  to prove  without
            releasing the  sourcecode, which  I do  not  plan to do, so
            the best way for you  to feel secure  is to get it  from my
            WWW, this  way you  will only have to trust me, and not all
            the couriers!
                                    Hey! I'm a nice guy!
@endnode

@node ack Acknowledgements

@{b}Thanks goes to:@{ub}

    Commodore for the best computer ever made.

    The AmiTCP/IP group. Couldn't have done it without ya!

    SAS Institute for their superb compiler.

    Osma Ahvenlampi (tau) for the help with dcc send/move.

    All the people who helped me find BUGS, there were plenty of them,
    and still are, I suppose :).

@{b}Contact address@{ub}

    If I'm on the IRC (mostly undernet) I usually go under the nick
    Texas or TexasX. Feel free to chat with me there!

    Send your bugreports, comments, suggestions, requests, contributions,
    donations, postcards, party invitations, flighttickets to the caribbean,
    16mb 72pib sim module, 1260 card, harddisks, icecream, blind dates,
    unused porno magazines (no sticky pages), ..., ...

    By email to na94jed@student.hgs.se

    By smail to Johan Englund
                Tomtasv. 7
                818 91 Valbo
                SWEDEN


                 You can check out the amibot homepage on

                      http://www.hgs.se/~na94jed

            This is where you can get the most recent version.

@endnode

@node whatis What is a Bot?

@{b}What is a Bot?@{ub}

    A bot is a standalone program which serve users directly on the IRC.
    The bots duties could be things like controlling a channel, making
    sure that only the right peoples gets operator status or serving the
    IRC community with files.

@endnode

@node install Installing

@{b}Installation instructions@{ub}

    Unpack the file into a dir of its own or wherever you would like it.

    No installation script provided, seems meaningless.

    No changes has to be made in the TCP/IP configuration.

@endnode

@node using Using the bot

@{b}So how do I use the bot ?@{ub}

    Start the bot from a shell or WB.

    @{"Main window" link mainwin}

    @{"Command line arguments" link arguments}
    @{"Bot commands" link commands}
    @{"Arexx" link Arexx}

@endnode

@node mainwin Main Window

    This is the window that opens up when you execute AmiBot.

    What are these buttons for then ?


    Servers - These are the servers that you have configed and
              they are the ones you may connect to.

              A * infront of the server indicates that you have marked it
                  as enabled.

              A > infront of the server indicates that it is currently
                  connected.

    Connect - Try to connect to the selected (highlighted) server.
              Will connect even if the server isn't 'enabled'.

    Connect Sel - Connect to all 'enabled' servers.

    Control - A big feature. Brings up a logwindow and a string gadget
              in which you may enter commands directly to the bot.
              To make this work you must specify the accesslevel 100.
              Enable everything except the ban/kick/ignore options in
              that level.

    DisConnect - Close connection to the selected (highlighted) server.
                 However, if there is any DCCs still active that was started
                 trough this server, they will not be closed. To close these
                 you must use the command killdcc or shutdown the bot.

    Config Server - Open the server configuration window.

    Iconify - Iconify amibot.
              NOTE: The bot is still in operation. No actions will freeze.


    When closing this window amibot will terminate all active connections.
    Before terminating connections to servers the bot will send the
    configged exitmessage.

@endnode

@node arguments Commandline arguments

@{b}Command line arguments@{ub}

    SERVERS/K    If you do not want to use the default server config, define the
                 one to use here

    ACCESS/K     If you do not want to use the default access config, define the
                 one to use here

    USERS/K      If you do not want to use the default userfile, define the
                 one to use here

    CONFIG/K     If you do not want to use the default configfile, define the
                 one to use here

    SEEN/K       If you do not want to use the default seenfile, define the
                 one to use here

    CONNECT/S    If you want the bot to connect directly upon startup,
                 define this switch.

    LOGFILE/S    If this argument is present AmiBot will open and keep a
                 logfile in PROGDIR named AmiBot.log.
                 This file will be feeded with error and some other messages.

    SCROLLSIZE/N Size of the scrollback for the control window. Default 15kb.

    PUBSCREEN/K  Name of screen to open AmiBot on. If screen isn't present or
                 doesn't have the right modes, AmiBot will try to open on WB.
@endnode


@node commands Bot commands

@{b}Bot commands@{ub}

    These commands can be issued through IRC using a client like AmIRC, or
    directly through the local controlwindow.


    addhost <user> <host>
        -- Add a additional host to a userrecord. This feature is nice if the
           user has access to more than one account.

    addnick <nick> <level>
        -- Adds a nick to the userlist.

           This command searches for the nick on the current server.
           If it succesfully locates the nick it will construct a expression
           from the information and add this to the userlist.

    adduser <user> <level>
        -- Add a user to the userlist.

    axx
        -- Show access level

    ban <channel> <expr.>
        -- Bans users from a channel.
           ex. /msg AmiBot ban #Amiga *@*luth.se

    botinfo
        -- Quick info on the server and channel status.

    cd [<dir>]
        -- Change directory.

    comment <file> <comment>
        -- Attach AmigaDOS filecomment to a file or directory.

    dcclist
        -- Show list of all current DCCs.

    delete <entry>
        -- Delete file or directory. No wildcards supported yet.

    dir [<dir>]
        -- List contents of directory.

    getusers
        -- Reread the userlist from disk.

    help
        -- Show some quick help.

           This command will only show help on the commands that the user
           has access to.

           If there is a valid filename defined in the current servers config
           this file will be displayed instead.

    join #<channel>
        -- Make the bot join a channel. Currently the IRC standard only allow
           a client to be joined to 10 channels simultaneous.

    kick <channel> <nick>
        -- Kick a user from channel.
           ex. /msg AmiBot kick #Amiga Texas

    killdcc <id>
        -- Kill a DCC-connection. The id can be found with the cmd dcclist.

    killuser <user>
        -- Remove a user from the userlist.

    mkdir <dir>
        -- Make a directory in the current path.

    move [<nick>] <file>
        -- DCC MOVE a file.

           If the key <nick> is present AmiBot will offer the DCC to that user
           instead.

    msg <nick/channel> <message>
        -- Send message to a nick or a channel.
           Ex. /msg AmiBot msg Texas Hello!
           Ex. /msg AmiBot msg #Amiga Hello!

    nick <nick>
        -- Changes bots nick.

    nicklist
        -- Shows all users currently joined on the channels.

    op <channel> <nick>
        -- Give op.

    part #<channel>
        -- Make the bot part from channel.

    passwd <pass>
        -- Lets the user identify himself from a different host than
           that stated in the userlist. This host will show up in the
           userlist when issuing a 'userlist' cmd, but it wont be saved
           to disk when using 'saveusers'

    raw <msg>
        -- Sends a message directly to the current server. Note that this cmd
           will allow user to do all operations like op/deop/kick/ban.
           Refer to the IRC RFC for details about talking to the server.

    remhost <user> <host>
        -- Remove a host from a userrecord.

    rx <script> [arguments]
        -- Executes a arexx script.

    saveusers
        -- Saves the current userlist.

    seen <nick>
        -- When did <nick> leave the channel ?

    send [<nick>] <file>
        -- DCC SEND a file.

           If the key <nick> is present AmiBot will offer the DCC to that user
           instead.

    server <server> [<port>]
        -- Change server.

    setaxx <user> <level>
        -- Change the users accesslevel.

    setpasswd <passwd>
        -- Change current password.

    shutdown
        -- Kill the bot

    time
        -- Show local time, ie. the time on the computer from where the bot
           is running.

    userinfo
        -- Quick info for the user about his record.

    userlist
        -- Show list of users.
@endnode


@node Arexx Using Arexx

@{b}Arexx@{ub}
------
    Allright, now we have a Arexxport! BUT, I am not very good at arexx,
    actually, I've never used it...of some strange reason.

    Well, I havn't given this very much thought, yet, so it might not
    look and feel very good.

    There are currently only one port, not one for each server.
    The portname is 'AmiBot'. For each new copy amibot in memory the
    portname will be increased by one, ie. second amibot will be named
    'AmiBot.1' (hmmm).

    As it is now you execute the script with the cmd 'rx'. AmiBot will
    then insert a number associated to the server (the index number in
    the "Server Config") from which the script was executed, before any
    of your private arguments.

@{b}Commands@{ub}
---------
    RAW <servernumber>: <Text to be sent to the server>

        RETURN: 1 if successful, 9 if failure. If failure, an errormessage
                will be present in RC2.


    LOCAL <servernumber>: <Text to be sent to controlwindow>

        This is just a visual command. The bot will take no action.


        RETURN: 1 if successful, 9 if failure. If failure, an errormessage
                will be present in RC2.

@{b}Examples@{ub}
---------
    Arexx script:

    ------ Cut ------
    arg Server ' ' Nick ' '

    raw ''Server': PRIVMSG 'Nick' :Hello, How are you ?'
    ------ Cut ------

    Executing the following script by issuing the cmd 'rx <script> Texas'
    to AmiBot will have the result of Amibot sending the private message
    'Hello, How are you ?' to the nick 'Texas'.

@endnode


@node variables Configuration of Amibot

@{b}The Bot configuration@{ub}

    Currently there are three configs:

    @{"Main config" link MainConfig}
    @{"Server config" link ServerConfig}
    @{"Accesslevel config" link AccessLevelConfig}

    @{"Adding users" link AddUsers}

@endnode

@node MainConfig Main Configuration.

    This file was added to make it possible to configure certain global
    variables like what the bot should reply when the user have entered
    a bad command.

    All reply variables supports multiple entries. In case of muiltiple
    entries the bot will randomly select one each time it replies.

    None of these entries, nor the file itself has to be present.

    The default main config file is 'PROGDIR:AmiBot.config'. If you want to
    use a alternate config use the CONFIG/K commandline option.


@{b}Config fileformat@{ub}

    VERSION: - What the bot will reply to a CTCP VERSION query.
               Supports multiple entries.

    USERINFO: - What the bot will reply to a CTCP USERINFO query.
                Supports multiple entries.

    NOAXXMSG: - What the bot will reply if the user does not have
                access enough to execute the command.
                Supports multiple entries.

    UNKNOWNCMD: - What the bot will reply if the user enters a
                  command that does not exist.
                  Supports multiple entries.

    SEENREMOVE: - How long time in HOURS that the seen entry will remain
                  in the seen logfile. This is for keeping the logfile
                  from getting big and slow down the actions on it.
                  If the bot cannot find this entry it will disable the
                  seen feature.

@endnode

@node ServerConfig Server Configuration.

    The default server config file is 'PROGDIR:AmiBot.servers'. If you want to
    use a alternate config use the SERVERS/K commandline option.

    A breif explanation of the server config window!
    -------------------------------------------------

    Enabled      - Toggle this switch to tell AmiBot whether to try connecting
                   to it or not.

    Server       - IRC Server to connect to.

    Port         - Port # on the server to use.

    MaxDCC       - Maximum number of dcc sessions.

    DCC Bufsize  - Size of the buffer that each dcc session will use for
                   reading/writing data. If you make this buffer to big
                   the bot may be "ping timedout" and killed from the IRC.
                   A buffer of about 10kb usually works good.

    Server Retry - Number of tries to connect to the server, should be >0.

    Nick         - The nickname the bot will get on the IRC.

    Login        - The username under which the bot will run. Could be
                   anything. Though some servers have the policy to ban
                   clients with a phony username.

    Channel      - Channel to join on the IRC

    Owner        - The bots owner, will show in the internal help if present

    IRC Name     - The bots IRC name (!)

    Exit msg     - Message the bot will exit with

    Join txt     - Text to show a user joining the channel, if no file is
                   specified, no message will be sent upon join

    DCC text     - If you want a textfile to be presented to the user when
                   initiating a DCC CHAT, specify it here.

    Channels     - Specify the channels you want the bot to join upon connect.

@endnode

@node AccessLevelConfig Accesslevel Configuration.

    The default access config file is 'PROGDIR:AmiBot.access'. If you want to
    use a alternate config use the ACCESS/K commandline option.

    Make sure that there is a accesslevel with the # 100 configured. With all
    options enabled except ban/kick/ignore. This is for the local commandwindow
    to work.

@{b}Fileformat@{ub}

    # - Each new level must begin with this character on a own line.

    LEVEL: - Number of the accesslevel.

    BYTERATIO: - Example: If set to 5, the user must upload 50kb for every
                 10kb he can download. If set to 0, this feature is disabled.

    FILERATIO: - Like byteratio but for files.

    FREEBYTES: - Number of bytes the user may download without affecting the
                 byteratio.

    NAME: - Name of the accesslevel

    PATH: - This is where you specify which directories users of this
            accesslevel will have access to. After the dir you should enter
            a alias for that dir. That is what the user will see when doing
            a dir/ls on the root. You may have multiple PATH entries.

    In the rest of the space for this record you shall enter what commands
    and features the user of this level will have access to on the bot.
    These may be entered on a single line separated with a space and/or spread
    out over several lines.

    These are the things that you may enter.

    DCCCHAT      - Allow DCC CHAT with the bot.
 
    DCCUL        - Allow DCC upload.

    DCCDL        - Allow DCC downloads

    DCCLIST      - May use this command.

    KILLDCC      - May use this command.

    CD           - May use this command.

    DIR          - May use this command.

    MKDIR        - May use this command.

    DELETE       - May use this command.

    COMMENT      - May use this command.

    ADDNICK      - May use this command.

    ADDUSER      - May use this command.

    KILLUSER     - May use this command.

    ADDHOST      - May use this command.

    REMHOST      - May use this command.

    SETAXX       - May use this command.

    USERLIST     - May use this command.

    GETUSERS     - May use this command.

    SAVEUSERS    - May use this command.

    GIVEOP       - May use this command.

    BAN          - May use this command.

    KICK         - May use this command.

    JOIN         - May use this command.

    PART         - May use this command.

    NICK         - May use this command.

    MSG          - May use this command.

    BOTINFO      - May use this command.

    SHUTDOWN     - May use this command.

    HELP         - May use this command.

    TIME         - May use this command.

    AXX          - May use this command.

    USERINFO     - May use this command.

    ACCESSLEVELS - May use this command.

    OPJOIN       - User will get opped as soon as the bot spots him.

    KICKJOIN     - User will get kicked as soon as the bot spots him.

    BANJOIN      - User will get banned as soon as the bot spots him.

    IGNORE       - The bot will ignore ALL all data coming from the
                   user with this enabled

    PASSWD       - May use this command.

    SETPASSWD    - May use this command.

    RAW          - May use this command.

    SERVER       - May use this command.

    SEEN         - May use this command.

    RX           - May use this command.

    NICKLIST     - May use this command.


    Example:

        <<<CUT HERE>>>
        #
        LEVEL: 5
        BYTERATIO: 10
        FILERATIO: 10
        FREEBYTES: 10000
        NAME: Opped!
        PATH: RAM: Ram:
        PATH: DH0:Games/ Games
        DCCCHAT DCCUL DCCDL DCCLIST
        CD DIR MKDIR COMMENT
        USERLIST
        BOTINFO SEEN
        HELP TIME AXX USERINFO ACCESSLEVELS OPJOIN SETPASSWD PASSWD
        <<<CUT HERE>>>

@endnode

@node AddUsers Add users

@{b}Adding users@{ub}

    The default user file is 'PROGDIR:AmiBot.users'. If you want to
    use a alternate file use the USERS/K commandline option.

    Currently I there isn't any GUI for user administration. The file can
    however be edited by hand in a text editor.

    For first time use you will have to add yourself with a access level
    that may add users. When this is done you may add other users.

	Ex. Your nickname on the IRC is MyNick.
        /msg AmiBot addnick MyNick <accesslevel>

	Users are matched with help of the amiga wildcard expressions.

		Ex. You want to add the user

   		       ~mramiga@ppp17.gars.america.org

	       this could look like

	    	   /msg AmiBot adduser *ramiga@*america.org <access>


@{b}Userfile format@{ub}

    # - Each new userrecord should begin with this character.

    LEVEL: - Accesslevel of the user.
    ULBYTES: - # of bytes uploaded to the bot.
    ULFILES: - # of files uploaded to the bot.
    DLBYTES: - # of bytes downloaded from the bot.
    DLFILES: - # of files downloaded from the bot.
    INFO: - Short info about the user.
    PASSWORD: - The users password.
    ACCOUNT: - The account upon which amibot will recognice this user.
               There may be several ACCOUNT: entries for each user.

    Example:
    -----------
    <<<CUT HERE>>>
    #
    LEVEL: 50
    ULBYTES: 16657
    ULFILES: 2
    DLBYTES: 567866
    DLFILES: 7
    INFO: Do you feel lucky today ?
    PASSWORD: NotForYourEyes
    ACCOUNT: *a94jed@*HGS.SE
    ACCOUNT: *exas@*HGS.SE
    ACCOUNT: *exas@*130.238.205.*
    <<<CUT HERE>>>
             
@endnode


@node future Future plans for AmiBot

@{b}What will happen to AmiBot?@{ub}

    If you feel like helping me writing a better documentation,
    please contact me. I hate writing this.

    New features that should be added:

        A "type" cmd.

		SUGGESTIONS ?!??!
        Mail me with ideas. I'm runnin out of em...(not really, but...)

@endnode


@node history Historical changes in AmiBot

@{b}What has happened ?@{ub}

@{i}0.97@{ui}
    First version released on AmiNet!
    Fixed several bugs related with the GUI.
    Fixed a bug in the setpasswd cmd.
    Fixed problems with the BAN/KICK/NICK cmds.
    The cmd NICK changed to BOTNICK. It gave some problems.
    Changed the format of the access configfile to ASCII. No convert program
      availible, sorry.
    Rewrote the GUI for the main window.
    Skipped the GUI for the Accesslevel configuration.
    New AmiBot.info and Iconify icon. They're really cute, arn't they ?
    Added a new configfile.
    Configurable textfile to send when initiating a DCC CHAT.
    Fixed "seen" support.
    Plenty of bugfixes
    Cleaned up the code a bit.

@{i}0.96ß@{ui}
    Changed userfile format into readable form again. Use the supplied
      program UserConvert to change your userfile into this new format.
    Found a bug in the userlist save routine. Made the userlist crippled.

@{i}0.951ß@{ui}
    Fixed ban/kick bug. Fixed bug that made AmiBot fail to always op users
      when joining.
    Remember to config accesslevel 100. Read the "Configuration" part.

@{i}0.95ß@{ui}
    New cmd: server
    Finally managed to get the listview in the controlwins to scroll smoothly.
    Arexx do not supply a pointer the the server anymore, but rather the index
      number of the server. This prevents from getting some nasty gurus.

@{i}0.94ß@{ui}
    An experimental Arexx port has been added. Only the 'raw' cmd is
      supported yet.
    New GUI. Now each server has it's own log/controll window in which you
      can communicate with the bot.
    Fixed a little bug in the GUI. Didn't use the system default font but the
      window default font.
    Shows cps in the dcclist and in the log.

@{i}0.93ß@{ui}
    New cmd: Raw
    New commandline options: Scrollsize, PubScreen.
    Added some user protection.
    New GUI in the "Config Server" and in the main window. The listview for
      the log is pretty slow. Will fix it, somehow.
    Increased channelname limit to the standard 200 chars.
    Fixed a bug that made it hard to get more than 1 DCC SEND/MOVE going.
      (Very strange that anyone havn't noticed this earlier)
    Fixed bug that made AmiBot hang when killing a DCC SEND/MOVE.

@{i}0.92ß@{ui}
    Changed wildcards to * instead of #?. This might get you some problems.
    New cmd: Nicklist
   Rewrote the channel/user handling

@{i}0.91ß@{ui}
    Format of the AmiBot.Access and AmiBot.Users has changed
    New cmds: addhost, remhost, passwd, setpasswd
    Support for multiple hosts for users
    Support for multiple paths, now accesslevel oriented
    Receiving DCC Send/Move might get faster on slow amigas
	Improved GUI

@{i}0.90ß@{ui}
    Bugfixes. The GUI font sensitivity now seems to work.
    Added the cmd Botinfo
    Added a Ignore feature
    Fixed bug that made all users being able to DCC CHAT with the bot,
      even those not registered.
    Found some enforcer hits! Fixed!

@{i}0.89ß@{ui}
    Too much for me to write here. Some major changes. U'll notice.

@{i}0.86ß@{ui}
    New commandline switches: CONFIG/K, CONNECT/S
    Configurable help
    May show a text to a user upon joining a channel

@{i}0.85ß@{ui}
    New cmd: time, op, kick, ban
    ls changed into dir and wildcard compatibility was added
    New access levels, -1 and -2
    Fixed a nasty bug that made amibot close down if user requested a
      that didn't existed! Can't belive that I didn't notice this bug.
    General bug fixes

@{i}0.81ß@{ui}
    Bug fixes

@{i}0.8ß@{ui}
    Got rid of MUI, code got about 3k smaller and AmiBot uses about 250kb less mem,
      incl. MUI, and the GUI is noticible faster. The GUI is font sensitive but some
      features still has to be added.
    Last message now shows the 10 last messages

@{i}0.72ß@{ui}
    Added ability to send dccs to another nick
    Fixed bugs

@{i}0.7ß@{ui}
    Removed bug that made the bot to hang if killing a dcc on a bad occation
	Rewrote parts, made it more stable, I hope :)
    Added some more messages for the "Last message" in the mui

@{i}0.6ß@{ui}
    All DCC stuff are now internal!
    Ability to select buffer size for the dccs, the bigger the better...to a certain point :)
    New cmds: saveusers, adduser, killuser, setaxx.
    Rewrote a couple of functions in asm to make the cpu happier

@{i}0.5ß@{ui}
    Internal DCC MOVE
    GUI Implemented (MUI)
    Userdefined shutdown msg.

@{i}0.4ß@{ui}
    New cmds, mkdir, delete.
    No more Excess flood!
    Found a nasty bug in the comment cmd.

@{i}0.3ß@{ui}
    Debugged and enhanced the comment command
    Fixed directory compatibility
    Tries to reconnect to server if connection is lost.
    Debugged the msg command, now it works :)
    Fixed a bug that made enforcer hits when closing a dcc.

@{i}0.2ß@{ui}
    Still hunting bugs and inventing new ones.

@endnode