202 lines
9.5 KiB
ReStructuredText
202 lines
9.5 KiB
ReStructuredText
=============
|
|
Configuration
|
|
=============
|
|
|
|
Introduction
|
|
------------
|
|
So you've got your Limnoria up and running and there are some things you
|
|
don't like about it. Fortunately for you, chances are that these things
|
|
are configurable, and this document is here to tell you how to configure
|
|
them.
|
|
|
|
Configuration of Limnoria is handled via the `Config` plugin, which
|
|
controls runtime access to Limnoria's registry (the configuration file
|
|
generated by the 'supybot-wizard' program you ran). The `Config` plugin
|
|
provides a way to get or set variables, to list the available variables,
|
|
and even to get help for certain variables. Take a moment now to read
|
|
the help for each of those commands: ``config``, ``list``, and ``help``.
|
|
If you don't know how to get help on those commands, take a look at the
|
|
GETTING_STARTED document.
|
|
|
|
Configuration Registry
|
|
----------------------
|
|
Now, if you're used to the Windows registry, don't worry, Limnoria's
|
|
registry is completely different. For one, it's completely plain text.
|
|
But there is at least one good idea in Windows' registry: hierarchical
|
|
configuration.
|
|
|
|
Limnoria's configuration variables are organized in a hierarchy:
|
|
variables having to do with the way Limnoria makes replies all start with
|
|
`supybot.reply`; variables having to do with the way a plugin works all
|
|
start with `supybot.plugins.Plugin` (where 'Plugin' is the name of the
|
|
plugin in question). This hierarchy is nice because it means the user
|
|
isn't inundated with hundreds of unrelated and unsorted configuration
|
|
variables.
|
|
|
|
Some of the more important configuration values are located directly
|
|
under the base group, `supybot`. Things like the bot's nick, its ident,
|
|
etc. Along with these config values are a few subgroups that contain
|
|
other values. Some of the more prominent subgroups are: `plugins`
|
|
(where all the plugin-specific configuration is held), `reply` (where
|
|
variables affecting the way a Limnoria makes its replies resides),
|
|
`replies` (where all the specific standard replies are kept), and
|
|
`directories` (where all the directories a Limnoria uses are defined).
|
|
There are other subgroups as well, but these are the ones we'll use in
|
|
our example.
|
|
|
|
Configuration Groups
|
|
--------------------
|
|
Using the `Config` plugin, you can list values in a subgroup and get or
|
|
set any of the values anywhere in the configuration hierarchy. For
|
|
example, let's say you wanted to see what configuration values were
|
|
under the `supybot` (the base group) hierarchy. You would simply issue
|
|
this command::
|
|
|
|
<Mikaela> @config list supybot
|
|
<Limnoria> #alwaysJoinOnInvite, @abuse, @capabilities, @commands, @databases, @debug, @directories, @drivers, @log, @networks, @nick, @plugins, @protocols, @replies, @reply, @servers, defaultIgnore, defaultSocketTimeout, externalIP, flush, followIdentificationThroughNickChanges, ident, language, pidFile, snarfThrottle, upkeepInterval, and user
|
|
|
|
These are all the configuration groups and values which are under the
|
|
base `supybot` group. Actually, their full names would each have a
|
|
'supybot.' prepended to them, but it is omitted in the listing in order
|
|
to shorten the output. The first entries in the output are the groups
|
|
(distinguished by the '@' symbol in front of them), and the rest are the
|
|
configuration values. The '@' symbol (like the '#' symbol we'll discuss
|
|
later) is simply a visual cue and is not actually part of the name.
|
|
|
|
Configuration Values
|
|
--------------------
|
|
Okay, now that you've used the Config plugin to list configuration
|
|
variables, it's time that we start looking at individual variables and
|
|
their values.
|
|
|
|
The first (and perhaps most important) thing you should know about each
|
|
configuration variable is that they all have an associated help string
|
|
to tell you what they represent. So the first command we'll cover is
|
|
``config help``. To see the help string for any value or group, simply
|
|
use the ``config help`` command. For example, to see what this
|
|
`supybot.snarfThrottle` configuration variable is all about, we'd do
|
|
this::
|
|
|
|
<jemfinch|lambda> @config help supybot.snarfThrottle
|
|
<supybot> jemfinch|lambda: A floating point number of seconds to
|
|
throttle snarfed URLs, in order to prevent loops between two
|
|
bots snarfing the same URLs and having the snarfed URL in
|
|
the output of the snarf message. (Current value: 10.0)
|
|
|
|
Pretty simple, eh?
|
|
|
|
Now if you're curious what the current value of a configuration variable
|
|
is, you'll use the ``config`` command with one argument, the name of the
|
|
variable you want to see the value of::
|
|
|
|
<jemfinch|lambda> @config supybot.reply.whenAddressedBy.chars
|
|
<supybot> jemfinch|lambda: '@'
|
|
|
|
To set this value, just stick an extra argument after the name::
|
|
|
|
<jemfinch|lambda> @config supybot.reply.whenAddressedBy.chars @$
|
|
<supybot> jemfinch|lambda: The operation succeeded.
|
|
|
|
Now check this out::
|
|
|
|
<jemfinch|lambda> $config supybot.reply.whenAddressedBy.chars
|
|
<supybot> jemfinch|lambda: '@$'
|
|
|
|
Note that we used '$' as our prefix character, and that the value of the
|
|
configuration variable changed. If I were to use the ``flush`` command
|
|
now, this change would be flushed to the registry file on disk (this
|
|
would also happen if I made the bot quit, or pressed Ctrl-C in the
|
|
terminal which the bot was running). Instead, I'll revert the change::
|
|
|
|
<jemfinch|lambda> $config supybot.reply.whenAddressedBy.chars @
|
|
<supybot> jemfinch|lambda: The operation succeeded.
|
|
<jemfinch|lambda> $note that this makes no response.
|
|
|
|
Default Values
|
|
--------------
|
|
If you're ever curious what the default for a given configuration
|
|
variable is, use the ``config default`` command::
|
|
|
|
<jemfinch|lambda> @config default supybot.reply.whenAddressedBy.chars
|
|
<supybot> jemfinch|lambda: ''
|
|
|
|
Thus, to reset a configuration variable to its default value, you can
|
|
simply say::
|
|
|
|
<jemfinch|lambda> @config setdefault supybot.reply.whenAddressedBy.chars
|
|
<supybot> jemfinch|lambda: The operation succeeded.
|
|
<jemfinch|lambda> @note that this does nothing
|
|
|
|
Simple, eh?
|
|
|
|
Searching the Registry
|
|
----------------------
|
|
Now, let's say you want to find all configuration variables that might
|
|
be even remotely related to opping. For that, you'll want the ``config
|
|
search`` command. Check this out::
|
|
|
|
<Mikaela> @config search op
|
|
<Limnoria> supybot.plugins.AutoMode.op, supybot.plugins.AutoMode.halfop, supybot.plugins.ChannelStatus.topic, supybot.plugins.LinkRelay.topicSync, supybot.plugins.NoLatin1.operator, supybot.plugins.Services.ChanServ.op, supybot.plugins.Services.ChanServ.halfop, supybot.plugins.Topic, supybot.plugins.Topic.public, supybot.plugins.Topic.separator, supybot.plugins.Topic.format, (1 more message)
|
|
<Mikaela> @more
|
|
<@Limnoria> supybot.plugins.Topic.recognizeTopiclen, supybot.plugins.Topic.default, supybot.plugins.Topic.alwaysSetOnJoin, supybot.plugins.Topic.undo, supybot.plugins.Topic.undo.max, and supybot.plugins.Topic.requireManageCapability
|
|
|
|
|
|
Sure, it showed all the topic-related stuff in there, but it also showed
|
|
you all the op-related stuff, too. Do note, however, that you can only
|
|
see configuration variables for plugins that are currently loaded or
|
|
that you loaded in the past; if you've never loaded a plugin there's no
|
|
way for the bot to know what configuration variables it registers.
|
|
|
|
.. _channel-specific-configuration:
|
|
|
|
Network- and Channel-Specific Configuration
|
|
-------------------------------------------
|
|
Many configuration variables can be specific to individual channels.
|
|
The `Config` plugin provides an easy way to configure something for a
|
|
specific channel; for instance, in order to set the prefix chars for a
|
|
specific channel, do this in that channel::
|
|
|
|
<jemfinch|lambda> @config channel supybot.reply.whenAddressedBy.chars !
|
|
<supybot> jemfinch|lambda: The operation succeeded.
|
|
|
|
That'll set the prefix chars in the channel from which the message was
|
|
sent to '!'. Voila, channel-specific values! Also, note that when
|
|
using the `Config` plugin's ``list`` command, channel-specific values are
|
|
preceeded by a '#' character to indicate such (similar to how '@' is
|
|
used to indicate a group of values).
|
|
|
|
Similarly, many configuration variables can be specific to individual
|
|
networks. This works similarly by substituting ``channel`` with network::
|
|
|
|
<jemfinch|lambda> @config network supybot.reply.whenAddressedBy.chars !
|
|
<supybot> jemfinch|lambda: The operation succeeded.
|
|
|
|
Network-specific configuration values are preceeded by a ':' character.
|
|
As most (if not all) channel-specific values are also network-specific,
|
|
they are preceeded by '#:'.
|
|
|
|
|
|
Editing the Configuration Values by Hand
|
|
----------------------------------------
|
|
|
|
NOTE: **We don't recommend this and you shouldn't ever do this, you should
|
|
do everything with the commands in the Config plugin.**
|
|
|
|
Some people might like editing their registry file directly rather than
|
|
manipulating all these things through the bot. For those people, we
|
|
offer the ``config reload`` command, which reloads both registry
|
|
configuration and user/channel/ignore database configuration.
|
|
|
|
Just edit the interesting files and then give the bot the ``config
|
|
reload`` command and it'll work as expected. Do note, however, that
|
|
Limnoria flushes its configuration files and database to disk every hour
|
|
or so, and if this happens after you've edited your configuration files
|
|
but before you reload your changes, you could lose the changes you made.
|
|
To prevent this, set the `supybot.flush` value to 'Off' while editing
|
|
the files, and no automatic flushing will occur.
|
|
|
|
If you cannot access the bot on IRC and your bot is running on a POSIX
|
|
system, you can also send it a SIGHUP signal; it is exactly the same
|
|
as ``config reload`` (note that the Config plugin has to be loaded to
|
|
do that).
|