mirror of
https://github.com/Limnoria/Limnoria-doc.git
synced 2025-04-06 15:29:50 +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
|
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
|
Much of Limnoria's behaviour, as well as those of its plugins, is configurable.
|
||||||
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
|
Limnoria provides a hierarchical configuration system, which is usually managed
|
||||||
----------------------
|
via IRC using the `Config` plugin. By default, it will write back its configuration
|
||||||
Now, if you're used to the Windows registry, don't worry, Limnoria's
|
periodically to the same ``botname.conf`` file created by ``supybot-wizard``.
|
||||||
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:
|
The main commands to interact with the config system are ``config``,
|
||||||
variables having to do with the way Limnoria makes replies all start with
|
``config list``, and ``config help``, which are described in the following
|
||||||
`supybot.reply`; variables having to do with the way a plugin works all
|
sections.
|
||||||
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
|
Navigating the Configuration Registry
|
||||||
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
|
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
|
||||||
Using the `Config` plugin, you can list values in a subgroup and get or
|
well as many more options nested within groups. This hierarchy allows config
|
||||||
set any of the values anywhere in the configuration hierarchy. For
|
options to be grouped naturally, and provides each plugin with a dedicated space
|
||||||
example, let's say you wanted to see what configuration values were
|
to declare its settings.
|
||||||
under the `supybot` (the base group) hierarchy. You would simply issue
|
|
||||||
this command::
|
You can list the options in any group with the ``config list`` command::
|
||||||
|
|
||||||
<Mikaela> @config list supybot
|
<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
|
<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
|
Some of the most common config groups include:
|
||||||
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
|
- `supybot.directories`: contains options on where to store log files, search for plugins, etc.
|
||||||
--------------------
|
- `supybot.networks`: contains the configuration for all known IRC networks
|
||||||
Okay, now that you've used the Config plugin to list configuration
|
- `supybot.log`: contains options relating to Limnoria's logs, such as verbosity
|
||||||
variables, it's time that we start looking at individual variables and
|
- `supybot.plugins.<plugin name>`: contains the configuration for each plugin
|
||||||
their values.
|
- `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
|
Configuration Option Types
|
||||||
<supybot> jemfinch|lambda: A floating point number of seconds to
|
---------------------------
|
||||||
|
|
||||||
|
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
|
throttle snarfed URLs, in order to prevent loops between two
|
||||||
bots snarfing the same URLs and having the snarfed URL in
|
bots snarfing the same URLs and having the snarfed URL in
|
||||||
the output of the snarf message. (Current value: 10.0)
|
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
|
<jemfinch> @config supybot.reply.whenAddressedBy.chars
|
||||||
is, you'll use the ``config`` command with one argument, the name of the
|
<supybot> jemfinch: '@'
|
||||||
variable you want to see the value of::
|
|
||||||
|
|
||||||
<jemfinch|lambda> @config supybot.reply.whenAddressedBy.chars
|
To set a variable, add the new value after the name. This command sets the
|
||||||
<supybot> jemfinch|lambda: '@'
|
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 @$
|
<jemfinch> $config supybot.reply.whenAddressedBy.chars
|
||||||
<supybot> jemfinch|lambda: The operation succeeded.
|
<supybot> jemfinch: '@$'
|
||||||
|
|
||||||
Now check this out::
|
To revert this change::
|
||||||
|
|
||||||
<jemfinch|lambda> $config supybot.reply.whenAddressedBy.chars
|
<jemfinch> $config supybot.reply.whenAddressedBy.chars @
|
||||||
<supybot> jemfinch|lambda: '@$'
|
<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
|
By default, Limnoria writes its config to disk periodically
|
||||||
configuration variable changed. If I were to use the ``flush`` command
|
(see ``supybot.flush`` and ``supybot.upkeepInterval`` options), as well as when
|
||||||
now, this change would be flushed to the registry file on disk (this
|
shutting off the bot. This can also be manually triggered by running the
|
||||||
would also happen if I made the bot quit, or pressed Ctrl-C in the
|
``flush`` command.
|
||||||
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
|
Default Values
|
||||||
--------------
|
--------------
|
||||||
If you're ever curious what the default for a given configuration
|
To find the default value for a given configuration variable, use the
|
||||||
variable is, use the ``config default`` command::
|
``config default`` command::
|
||||||
|
|
||||||
<jemfinch|lambda> @config default supybot.reply.whenAddressedBy.chars
|
<jemfinch> @config default supybot.reply.whenAddressedBy.chars
|
||||||
<supybot> jemfinch|lambda: ''
|
<supybot> jemfinch: ''
|
||||||
|
|
||||||
Thus, to reset a configuration variable to its default value, you can
|
To reset a configuration variable to its default value, use ``config setdefault``::
|
||||||
simply say::
|
|
||||||
|
|
||||||
<jemfinch|lambda> @config setdefault supybot.reply.whenAddressedBy.chars
|
<jemfinch> @config setdefault supybot.reply.whenAddressedBy.chars
|
||||||
<supybot> jemfinch|lambda: The operation succeeded.
|
<supybot> jemfinch: The operation succeeded.
|
||||||
<jemfinch|lambda> @note that this does nothing
|
<jemfinch> @note that this does nothing
|
||||||
|
|
||||||
Simple, eh?
|
|
||||||
|
|
||||||
Searching the Registry
|
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
|
Limnoria allows searching for configuration variables by name, using the
|
||||||
search`` command. Check this out::
|
``config search`` command::
|
||||||
|
|
||||||
<Mikaela> @config search op
|
<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)
|
<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
|
<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
|
<@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
|
Do note that you can only see configuration variables for plugins that are
|
||||||
you all the op-related stuff, too. Do note, however, that you can only
|
currently loaded or that you loaded in the past; if you've never loaded a plugin,
|
||||||
see configuration variables for plugins that are currently loaded or
|
there's no way for the bot to know what configuration variables it registers.
|
||||||
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:
|
.. _channel-specific-configuration:
|
||||||
|
|
||||||
Network- and 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 !
|
Many configuration variables can be set on a per-channel or per-network basis
|
||||||
<supybot> jemfinch|lambda: The operation succeeded.
|
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
|
<jemfinch> @config channel supybot.reply.whenAddressedBy.chars !
|
||||||
sent to '!'. Voila, channel-specific values! Also, note that when
|
<supybot> jemfinch: The operation succeeded.
|
||||||
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
|
If you are not in a channel, or want to set the option for another channel, you
|
||||||
networks. This works similarly by substituting ``channel`` with network::
|
can also do so with the extended syntax: ``config channel [<network>] [<channel>]
|
||||||
|
<name> [<value>]``
|
||||||
|
|
||||||
<jemfinch|lambda> @config network supybot.reply.whenAddressedBy.chars !
|
To set the default prefix character for all channels on the current network,
|
||||||
<supybot> jemfinch|lambda: The operation succeeded.
|
run::
|
||||||
|
|
||||||
Network-specific configuration values are preceeded by a ':' character.
|
<jemfinch> @config network supybot.reply.whenAddressedBy.chars !
|
||||||
As most (if not all) channel-specific values are also network-specific,
|
<supybot> jemfinch: The operation succeeded.
|
||||||
they are preceeded by '#:'.
|
|
||||||
|
|
||||||
|
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
|
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.**
|
do everything with the commands in the Config plugin.**
|
||||||
|
|
||||||
Some people might like editing their registry file directly rather than
|
To reload Limnoria's configuration from disk, use the ``config reload`` command.
|
||||||
manipulating all these things through the bot. For those people, we
|
This will refresh the bot's main configuration as well as any user/channel/ignore
|
||||||
offer the ``config reload`` command, which reloads both registry
|
databases, which are stored by default in separate files under the ``conf/``
|
||||||
configuration and user/channel/ignore database configuration.
|
directory.
|
||||||
|
|
||||||
Just edit the interesting files and then give the bot the ``config
|
Note that Limnoria writes its configuration files to disk periodically,
|
||||||
reload`` command and it'll work as expected. Do note, however, that
|
so it may overwrite manual edits to configuration files.
|
||||||
Limnoria flushes its configuration files and database to disk every hour
|
To prevent this, set the ``supybot.flush`` option to ``false`` while editing
|
||||||
or so, and if this happens after you've edited your configuration files
|
its config files to disable automatic flushing.
|
||||||
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
|
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
|
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
|
as ``config reload`` (note that the Config plugin has to be loaded for this
|
||||||
do that).
|
to work).
|
||||||
|
|||||||
Reference in New Issue
Block a user