mirror of
https://github.com/Limnoria/Limnoria-doc.git
synced 2025-04-04 14:29:46 +00:00
Rewrite the Configuration guide
Rewrite the Configuration guide to be more concise, and display lists in bullet form (instead of prose) for better readability. I've also added a couple more notes: - How to get the path of a config option from the results of looking through `config list`, in case it isn't obvious - A quick description of the `config reset channel` and `config reset network` commands
This commit is contained in:
James Lu
Val Lorentz
@ -4,198 +4,175 @@ 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.
|
||||
Much of Limnoria's behaviour, as well as those of its plugins, is configurable.
|
||||
|
||||
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 provides a hierarchical configuration system, which is usually managed
|
||||
via IRC using the `Config` plugin. By default, it will write back its configuration
|
||||
periodically to the same ``botname.conf`` file created by ``supybot-wizard``.
|
||||
|
||||
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.
|
||||
The main commands to interact with the config system are ``config``,
|
||||
``config list``, and ``config help``, which are described in the following
|
||||
sections.
|
||||
|
||||
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.
|
||||
Navigating the Configuration Registry
|
||||
-------------------------------------
|
||||
|
||||
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::
|
||||
The root of Limnoria's config registry is named ``supybot``. At this level you
|
||||
can find a few config variables (e.g. ``nick``, which sets the bot's nick), as
|
||||
well as many more options nested within groups. This hierarchy allows config
|
||||
options to be grouped naturally, and provides each plugin with a dedicated space
|
||||
to declare its settings.
|
||||
|
||||
You can list the options in any group with the ``config list`` 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.
|
||||
Some of the most common config groups include:
|
||||
|
||||
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.
|
||||
- `supybot.directories`: contains options on where to store log files, search for plugins, etc.
|
||||
- `supybot.networks`: contains the configuration for all known IRC networks
|
||||
- `supybot.log`: contains options relating to Limnoria's logs, such as verbosity
|
||||
- `supybot.plugins.<plugin name>`: contains the configuration for each plugin
|
||||
- `supybot.replies`: contains options for Limnoria's standard replies
|
||||
- `supybot.reply`: contains options on how Limnoria should format its command output
|
||||
|
||||
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
|
||||
Configuration Option Types
|
||||
---------------------------
|
||||
|
||||
Inside ``config list``, the type of each configuration entry is labeled with a
|
||||
symbol:
|
||||
|
||||
- **@** indicates that a config variable contains a group. (i.e. you can
|
||||
``config list`` it as well). Note that some groups like ``supybot.nick`` are
|
||||
also configuration options themselves as well.
|
||||
- **:** indicates that a config variable can be set per-network.
|
||||
- **#** indicates that a config variable can be set per-channel. Most
|
||||
per-channel options can be set per-network as well, so you will often see them
|
||||
marked as **#:**
|
||||
- Everything else is an option that can only be set globally.
|
||||
|
||||
The next section will focus on setting variables globally. Changing network and
|
||||
channel-specific configuration is described
|
||||
:ref:`later on <channel-specific-configuration>`.
|
||||
|
||||
Getting / Setting Configuration Values
|
||||
--------------------------------------
|
||||
|
||||
To access a config option, you need to first construct its full path. An option's
|
||||
path reflects the groups that you traversed in order to find it:
|
||||
e.g. ``supybot.nick`` or ``supybot.reply.whenAddressedBy.chars``.
|
||||
|
||||
Then, you can run ``config help`` on an option to see how to use it.
|
||||
For example, to see what ``supybot.snarfThrottle`` means, run::
|
||||
|
||||
<jemfinch> @config help supybot.snarfThrottle
|
||||
<supybot> jemfinch: 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?
|
||||
To fetch the current value of a configuration variable, run the ``config``
|
||||
command with just the name of the variable, e.g. ::
|
||||
|
||||
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> @config supybot.reply.whenAddressedBy.chars
|
||||
<supybot> jemfinch: '@'
|
||||
|
||||
<jemfinch|lambda> @config supybot.reply.whenAddressedBy.chars
|
||||
<supybot> jemfinch|lambda: '@'
|
||||
To set a variable, add the new value after the name. This command sets the
|
||||
bot's prefix character to either `@` or `$`::
|
||||
|
||||
To set this value, just stick an extra argument after the name::
|
||||
<jemfinch> @config supybot.reply.whenAddressedBy.chars @$
|
||||
<supybot> jemfinch: The operation succeeded.
|
||||
|
||||
<jemfinch|lambda> @config supybot.reply.whenAddressedBy.chars @$
|
||||
<supybot> jemfinch|lambda: The operation succeeded.
|
||||
<jemfinch> $config supybot.reply.whenAddressedBy.chars
|
||||
<supybot> jemfinch: '@$'
|
||||
|
||||
Now check this out::
|
||||
To revert this change::
|
||||
|
||||
<jemfinch|lambda> $config supybot.reply.whenAddressedBy.chars
|
||||
<supybot> jemfinch|lambda: '@$'
|
||||
<jemfinch> $config supybot.reply.whenAddressedBy.chars @
|
||||
<supybot> jemfinch: The operation succeeded.
|
||||
<jemfinch> $note that this makes no response.
|
||||
|
||||
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.
|
||||
By default, Limnoria writes its config to disk periodically
|
||||
(see ``supybot.flush`` and ``supybot.upkeepInterval`` options), as well as when
|
||||
shutting off the bot. This can also be manually triggered by running the
|
||||
``flush`` command.
|
||||
|
||||
Default Values
|
||||
--------------
|
||||
If you're ever curious what the default for a given configuration
|
||||
variable is, use the ``config default`` command::
|
||||
To find the default value for a given configuration variable, use the
|
||||
``config default`` command::
|
||||
|
||||
<jemfinch|lambda> @config default supybot.reply.whenAddressedBy.chars
|
||||
<supybot> jemfinch|lambda: ''
|
||||
<jemfinch> @config default supybot.reply.whenAddressedBy.chars
|
||||
<supybot> jemfinch: ''
|
||||
|
||||
Thus, to reset a configuration variable to its default value, you can
|
||||
simply say::
|
||||
To reset a configuration variable to its default value, use ``config setdefault``::
|
||||
|
||||
<jemfinch|lambda> @config setdefault supybot.reply.whenAddressedBy.chars
|
||||
<supybot> jemfinch|lambda: The operation succeeded.
|
||||
<jemfinch|lambda> @note that this does nothing
|
||||
|
||||
Simple, eh?
|
||||
<jemfinch> @config setdefault supybot.reply.whenAddressedBy.chars
|
||||
<supybot> jemfinch: The operation succeeded.
|
||||
<jemfinch> @note that this does nothing
|
||||
|
||||
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::
|
||||
|
||||
Limnoria allows searching for configuration variables by name, using the
|
||||
``config search`` command::
|
||||
|
||||
<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.
|
||||
Do note 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.
|
||||
Many configuration variables can be set on a per-channel or per-network basis
|
||||
via the ``config channel`` and ``config network`` commands. For example, to
|
||||
set the bot's prefix character for the current channel, run::
|
||||
|
||||
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).
|
||||
<jemfinch> @config channel supybot.reply.whenAddressedBy.chars !
|
||||
<supybot> jemfinch: The operation succeeded.
|
||||
|
||||
Similarly, many configuration variables can be specific to individual
|
||||
networks. This works similarly by substituting ``channel`` with network::
|
||||
If you are not in a channel, or want to set the option for another channel, you
|
||||
can also do so with the extended syntax: ``config channel [<network>] [<channel>]
|
||||
<name> [<value>]``
|
||||
|
||||
<jemfinch|lambda> @config network supybot.reply.whenAddressedBy.chars !
|
||||
<supybot> jemfinch|lambda: The operation succeeded.
|
||||
To set the default prefix character for all channels on the current network,
|
||||
run::
|
||||
|
||||
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 '#:'.
|
||||
<jemfinch> @config network supybot.reply.whenAddressedBy.chars !
|
||||
<supybot> jemfinch: The operation succeeded.
|
||||
|
||||
Note that channel-specific settings take precedence over network-specific ones.
|
||||
|
||||
Finally, you can also unset any channel-specific or network-specific variables
|
||||
with the ``config reset channel`` and ``config reset network`` commands.
|
||||
|
||||
Editing the Configuration Values by Hand
|
||||
----------------------------------------
|
||||
|
||||
NOTE: **We don't recommend this and you shouldn't ever do this, you should
|
||||
NOTE: **We don't recommend this; you should normally
|
||||
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.
|
||||
To reload Limnoria's configuration from disk, use the ``config reload`` command.
|
||||
This will refresh the bot's main configuration as well as any user/channel/ignore
|
||||
databases, which are stored by default in separate files under the ``conf/``
|
||||
directory.
|
||||
|
||||
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.
|
||||
Note that Limnoria writes its configuration files to disk periodically,
|
||||
so it may overwrite manual edits to configuration files.
|
||||
To prevent this, set the ``supybot.flush`` option to ``false`` while editing
|
||||
its config files to disable automatic flushing.
|
||||
|
||||
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).
|
||||
as ``config reload`` (note that the Config plugin has to be loaded for this
|
||||
to work).
|
||||
|
||||
Reference in New Issue
Block a user