Butler in 5 minutes
- This Quickguide
-
This quickguide aims at allowing you to get, install and start a Butler
IRC bot without prior knowledge. The green links are glossar-links. If
you don't understand an instruction due to such a word, click on the glossary
link, it contains more information about that topic.
- Formattings
-
Every thing that means something different is formatted in a different style. A list of
all styles can be found here.
- Prerequisites
-
In order to install and run Butler, we need ruby in version 1.8 or higher.
You can test that running the following command in your
shell:
ruby -v
If you're missing ruby, visit
ruby-lang.org.
Another prerequisite is rubygems. If
installed, an executable named gem is present. Else, there's an
instruction on how to
install it.
- Install
-
The next step is installing Butler, it is as simple as typing:
sudo gem install butler
This will install the gem, which means the
libraries and
botcontrol.
Unfortunately RubyGems has no post-install hooks, so we have to do:
sudo botcontrol setup
This will ask you where you want your configuration and stores that value
into the global configuration, which is what it needs the sudo for.
It will also ask you where you want your bots and pidfiles stored. Those
values are stored in the configuration location you gave and should not
require sudo to be changed later.
- Setup & run
-
Now we set up a bot instance and let it run. Butlers layout is so, that your
main application is botcontrol.
With that application you can create new bots, start existing bots, add/edit/delete users
and privileges and all kinds of other stuff.
To create a new bot, you do:
botcontrol quickcreate botname
Of course you can choose any name. For the course of this quickguide, we will refer to the
created bot as 'butler' (lowercase, in contrast to 'Butler', the whole).
Botcontrol will ask you all necessary questions to be able to launch it for the first time.
All defaults are set up so that butler would connect to irc.freenode.org#butler.
To start the newly created bot, type:
botcontrol start -i butler
If you chose to name your but differently than 'butler', use the appropriate name.
You can create any number of bots.
The -i flag lets botcontrol run your bot printing everything to STDOUT, not daemonizing.
Just omit it if you want the bot to run in the background.
- Testing it
-
To get Butler to do what you want from him you have to authorize yourself to it.
The dialog will look as following (assuming your bots nick is 'butler', replace with the
nickname you actually assigned him), where username and password are
what you provided as username and password for the admin in the 'botcontrol create butler'
command:
/msg botname login username password
botname: You are now authenticated.
The 'You are now authenticated' confirms that your login was successful. You now are allowed
to use all commands butler offers. For example you can try the simplest:
If you use butler on networks which prohibit private message -
like freenode for example - you have to register your bots nickname to see the 'You
are now authenticated', since otherwise the irc server will prohibit the message
from being delivered.
Also if you try to authenticate somewhere else than via a private query, butler will log you
in, deactivate your password and ask you to set it to a new one.
yournick: botname ping
botname: pong
Useful commands are 'help', 'usage' and 'about'.
To manage your plugins (load/unload/list), use the command 'plugins'.
- What now?
-
The next steps depend on how you intend to use butler. If you want to write plugins,
then there's a plugin tutorial.
To get a more thorough information on how to use butler, consult the
manual.
Valid XHTML, 2008-21-05 21:22 CEST
