@database AmiBot.guide

@node main Documentation for AmiBot

                               AmiBot v0.95ß
                   960528, johan englund, na94jed@student.hgs.se

                            @{"Acknowledgements  " link ack}
                            @{"Introduction      " link whatis}
                            @{"Installation      " link install}
                            @{"Usage             " link using}
                            @{"Configuration     " link variables}
                            @{"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 too!
                                    Hey! I'm a nice guy!
@endnode

@node ack Acknowledgements

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

    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
    etc. by email to <na94jed@student.hgs.se>

    WWW: 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}

    Definition ? not ready... If anyone feels like writing this,
    please feel free to contact me....

@endnode

@node install Installing

@{b}Installation instructions@{ub}

    Unpack the file (which you aparently done allready) into a dir of its
    own or wherever you would like it.

    No installation script provided, seems meaningless.

@endnode

@node using Using the bot

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

    Start the bot from a shell or WB.

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

@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 user file, 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 main 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 currently only be issued through IRC. Some commands
    require that a DCC CHAT connection is present.

    This is because the output may involv many lines and IRC servers has flood
    protection preventing clients from sending many messages on a short time,
    thus slowing down the bot.

    DCC CHAT however eliminates this problem since it is a direct connection
    to the client.


    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.

    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 two main things to configure, servers and access levels.

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

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

    These files are binary and should not need to be edited with a text editor.
    Use the GUI interface instead.

    Use the example config files and alter them to suit your needs and it should
    work for ya without problems.

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

    Enabled      - Toggle this switch to indicate 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
    Server Retry - Number of retries to connect to the server
    Nick         - The nickname the bot will get on the IRC
    Login        - The bots account on your amiga
    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
    Site dir     - Directory from where the bot will do all file actions.
                   Observe that the user CAN NOT go below this dir.
                   I have tried the best I could without succeeding,
                   but if you manage to do it, don't hesitate to tell me
    Help txt     - If you don't approve to the built in help, you may write
                   your own help in this file and it will be displayed instead
    Join txt     - Text to show a user joining the channel, if no file is
                   specified, no message will be sent upon join

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

    Level        - Number of the accesslevel. This is the number that the bot
                   user commands will associate the level to
    Name         - Name of the accesslevel
    Byte ratio   - Example: If set to 5, the user must upload 50kb for every
                   10kb he can download. If set to 0, this feature is disabled
    File ratio   - See byte ratio
    Free bytes   - Number of bytes the user may download without affecting the
                   byte ratio

    Op on Join   - User will be opped upon joining the channel
    Kick on Join - User will be kicked upon joining the channel
    Ban on join  - User will be baned AND kicked upon joining the channel
    Ignore       - No error msg will be sent to a user with this enabled.
                   Earlier, evil persons could make the bot "hang" by sending
                   a large amount of undefined commands.

	Directories  - This is where you specify what directorys the user will have
                   access to. Alias is the directory name the user will see in
                   the directory listning of root.

    The rest of the switches is to indicate what functions the user will be able
    to use


@{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, so this has to
    be done through the IRC using a standard client (ie. AmIRC, GrapeVine).

    For first time use you will have to add yourself with a access level
    that may add users. This will be possible if amibot can't find a
    userfile. 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>


@endnode


@node future Future plans for AmiBot

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

    New features that should be added:

        A "type" cmd.

		SUGGESTIONS ?!??!
        Mail me with ideas. I'm runnin out of em...

@endnode


@node history Changes in AmiBot

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

@{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