Core Config Section#

sopel.config.core_section.COMMAND_DEFAULT_HELP_PREFIX = '.'#

Default help prefix used in commands’ usage messages.

sopel.config.core_section.COMMAND_DEFAULT_PREFIX = '\\.'#

Default prefix used for commands.

class sopel.config.core_section.CoreSection(config, section_name, validate=True)#

The config section used for configuring the bot itself.

Important

All Required values must be specified, or Sopel will fail to start.

Note

You can use the command sopel configure to generate a config file with the minimal required options.

admin_accounts#

The list of admin accounts other than the owner’s.

Each account is allowed to administer the bot and can perform commands that are restricted to admins.

Example:

admin_accounts =
    favadmin
    otheradm
    yetanotherone

Important

This should not be set for networks that do not support IRCv3 account capabilities. In that case, use admins instead.

admins#

The list of people (other than the owner) who can administer the bot.

Example:

admin =
    YourFavAdmin
    TheOtherAdmin
    YetAnotherRockstarAdmin
alias_nicks#

List of alternate names users may call the bot.

These aliases are used along with the bot’s nick for $nick and $nickname regex substitutions.

For example, a bot named “William” (its nick) could have these aliases:

alias_nicks =
    Bill
    Will
    Liam

This would then allow both “William: Hi!” and “Bill: Hi!” to work with nickname_command().

antiloop_repeat_text#

The replacement text sent when detecting a repeated message.

Default:

...

This is equivalent to the default value:

antiloop_repeat_text = ...

See also

The Loop prevention chapter to learn what each antiloop-related setting does.

New in version 8.0.

antiloop_silent_after#

How many times the anti-looping message will be sent before stopping.

Default:

3

This is equivalent to the default value:

antiloop_silent_after = 3

See also

The Loop prevention chapter to learn what each antiloop-related setting does.

New in version 8.0.

antiloop_threshold#

How many times a message can be repeated without anti-looping action.

Default:

5

This is equivalent to the default value:

antiloop_threshold = 5

You can deactivate the anti-looping feature (not recommended) by setting this to 0:

antiloop_threshold = 0

See also

The Loop prevention chapter to learn what each antiloop-related setting does.

New in version 8.0.

antiloop_window#

The time period (in seconds) checked when detecting repeated messages.

Default:

120

This is equivalent to the default value:

antiloop_window = 120

See also

The Loop prevention chapter to learn what each antiloop-related setting does.

New in version 8.0.

auth_method#

Simple method to authenticate with the server.

Can be one of nickserv, authserv, Q, sasl, server, or userserv.

This allows only a single authentication method; to use both a server-based authentication method and a nick-based authentication method, see server_auth_method and nick_auth_method.

For more information about these methods, see Authentication.

Note

If this is specified, nick_auth_method will be ignored, and this value will override server_auth_method.

auth_password#

The password to use to authenticate with the auth_method.

See Authentication.

auth_target#

Target for authentication.

Default:

The nickname of the NickServ or UserServ service, or the name of the desired SASL mechanism, if auth_method is set to one of these methods. For SASL, the EXTERNAL option is available in case the IRC network requires it (e.g. for CertFP using client_cert_file). This value is otherwise ignored.

See Authentication.

auth_username#

The user/account name to use when authenticating.

Required for an auth_method of authserv, Q, or userserv — otherwise ignored.

See Authentication.

auto_url_schemes#

List of URL schemes that will trigger URL callbacks.

Default:

['http', 'https', 'ftp']

Used by the URL callbacks feature to call plugins when links are posted in chat; see the sopel.plugin.url() decorator.

The default value allows http, https, and ftp. It is equivalent to this configuration example:

auto_url_schemes =
    http
    https
    ftp
bind_host#

Bind the connection to a specific IP.

Default:

0.0.0.0 (all interfaces)

This is equivalent to the default value:

bind_host = 0.0.0.0
ca_certs#

The path to the CA certs PEM file.

Example:

ca_certs = /etc/ssl/certs/ca-certificates.crt

If not specified, the system default will be used.

If the given value is not an absolute path, it will be interpreted relative to the directory containing the config file with which Sopel was started.

channels#

List of channels for the bot to join when it connects.

If a channel key needs to be provided, separate it from the channel name with a space:

channels =
    "#channel"
    "#logs"
    &rare_prefix_channel
    "#private password"

Important

If you edit the config file manually, make sure to wrap each line starting with a # in double quotes, as shown in the example above. An unquoted # denotes a comment, which will be ignored by Sopel’s configuration parser.

client_cert_file#

Filesystem path to a certificate file for CertFP.

This is expected to be a .pem file containing both the certificate and private key. Most networks that support CertFP will give instructions for generating this, typically using OpenSSL.

Some networks may refer to this authentication method as SASL EXTERNAL.

New in version 8.0.

commands_on_connect#

A list of commands to send upon successful connection to the IRC server.

Each line is a message that will be sent to the server once connected, in the order they are defined:

commands_on_connect =
    PRIVMSG Q@CServe.quakenet.org :AUTH my_username MyPassword,@#$%!
    PRIVMSG MyOwner :I'm here!

$nickname can be used in a command as a placeholder, and will be replaced with the bot’s nick. For example, if the bot’s nick is Sopel, MODE $nickname +Xxw will be expanded to MODE Sopel +Xxw.

New in version 7.0.

db_driver#

The driver to use for connecting to the database.

This is optional, but can be specified if user wants to use a different driver than the default for the chosen db_type.

See also

Refer to SQLAlchemy’s documentation for more information.

db_filename#

The filename for Sopel’s database.

Used only for SQLite. Ignored for all other db_type values.

db_host#

The host for Sopel’s database.

Ignored when using SQLite.

db_name#

The name of Sopel’s database.

Ignored when using SQLite.

db_pass#

The password for Sopel’s database.

Ignored when using SQLite.

db_port#

The port for Sopel’s database.

Ignored when using SQLite.

db_type#

The type of database Sopel should connect to.

Default:

sqlite (part of Python’s standard library)

The full list of values Sopel recognizes is:

  • firebird

  • mssql

  • mysql

  • oracle

  • postgres

  • sqlite

  • sybase

Here are the additional PyPI packages you may need to install to use one of the most commonly requested alternatives:

mysql

pip install mysql-python (Python 2)

pip install mysqlclient (Python 3)

postgres

pip install psycopg2

mssql

pip install pymssql

This is equivalent to the default value:

db_type = sqlite

See also

Refer to SQLAlchemy’s documentation for more information about the different dialects it supports.

Note

Plugins originally written for Sopel 6.x and older might not work correctly with db_types other than sqlite.

db_url#

A raw database URL.

If this option is present, Sopel will ignore all other db_* settings and use this option’s value only.

Note

Specifying this option via the SOPEL_CORE_DB_URL environment variable may prove especially useful in certain cloud environments, avoiding the need to split a database URI provided by the platform at runtime into its components with a startup script.

New in version 8.0.

db_user#

The user for Sopel’s database.

Ignored when using SQLite.

default_time_format#

The default format to use for time in messages.

Default:

%Y-%m-%d - %T %Z

Used when plugins format times with sopel.tools.time.format_time().

This is equivalent to the default value:

default_time_format = %Y-%m-%d - %T %Z

See also

Time format reference is available in the documentation for Python’s time.strftime() function.

default_timezone#

The default timezone to use for time in messages.

Default:

UTC

Used when plugins format times with sopel.tools.time.format_time().

For example, to make Sopel fall back on British time:

default_timezone = Europe/London

And this is equivalent to the default value:

default_timezone = UTC
enable#

A list of the only plugins you want to enable.

If set, Sopel will only load the plugins named here. All other available plugins will be ignored:

enable =
    url
    xkcd
    help

In that case, only the url, xkcd, and help plugins will be enabled and loaded by Sopel.

To load all available plugins, clear this setting by removing it, or by making it empty:

enable =

To disable only a few plugins, see exclude.

See also

The Plugins chapter for an overview of all plugin-related settings.

exclude#

A list of plugins which should not be loaded.

If set, Sopel will load all available plugins except those named here:

exclude =
    url
    calc
    meetbot

In that case, url, calc, and meetbot will be excluded, and they won’t be loaded by Sopel.

A plugin named both here and in enable will not be loaded; exclude takes priority.

See also

The Plugins chapter for an overview of all plugin-related settings.

extra#

A list of other directories in which to search for plugin files.

Example:

extra =
    /home/myuser/custom-sopel-plugins/
    /usr/local/lib/ad-hoc-plugins/

See also

The Plugins chapter for an overview of all plugin-related settings.

flood_burst_lines#

How many messages can be sent in burst mode.

Default:

4

This is equivalent to the default value:

flood_burst_lines = 4

See also

The Flood Prevention chapter to learn what each flood-related setting does.

New in version 7.0.

flood_empty_wait#

How long to wait between sending messages when not in burst mode, in seconds.

Default:

0.7

This is equivalent to the default value:

flood_empty_wait = 0.7

See also

The Flood Prevention chapter to learn what each flood-related setting does.

New in version 7.0.

flood_max_wait#

How many seconds to wait at most when flood protection kicks in.

Default:

2

Note

If the maximum wait is 0, flood protection is effectively disabled.

This is equivalent to the default value:

flood_max_wait = 2

See also

The Flood Prevention chapter to learn what each flood-related setting does.

New in version 7.1.

flood_penalty_ratio#

Ratio of the message length used to compute the added wait penalty.

Default:

1.4

Messages longer than flood_text_length will get an added wait penalty (in seconds) that will be computed like this:

overflow = max(0, (len(text) - flood_text_length))
rate = flood_text_length * flood_penalty_ratio
penalty = overflow / rate

Note

If the penalty ratio is 0, this penalty will be disabled.

This is equivalent to the default value:

flood_penalty_ratio = 1.4

See also

The Flood Prevention chapter to learn what each flood-related setting does.

New in version 7.1.

flood_refill_rate#

How quickly burst mode recovers, in messages per second.

Default:

1

This is equivalent to the default value:

flood_refill_rate = 1

See also

The Flood Prevention chapter to learn what each flood-related setting does.

New in version 7.0.

flood_text_length#

Length of text at which an extra wait penalty is added.

Default:

50

Messages longer than this (in bytes) get an added wait penalty if the flood protection limit is reached.

This is equivalent to the default value:

flood_text_length = 50

See also

The Flood Prevention chapter to learn what each flood-related setting does.

New in version 7.1.

help_prefix#

The prefix to use in help output.

Default:

.

This is equivalent to the default value:

help_prefix = .

If prefix is changed from the default, this setting must be updated to reflect the prefix your bot will actually respond to, or the built-in help functionality will provide incorrect example usage.

property homedir#

The directory in which various files are stored at runtime.

Specifying the homedir option is useful for e.g. running Sopel as a system service.

If not set, the config file’s parent directory will be used. This value cannot be changed at runtime.

host#

The IRC server to connect to.

Default:

irc.libera.chat

Required:

host = irc.libera.chat
host_blocks#

A list of hostnames which Sopel should ignore.

Sopel will ignore messages from any user whose connection hostname matches one of these values. Regular expression syntax is supported, so remember to escape special characters:

host_blocks =
    (.+\.)*domain\.com

See also

The nick_blocks list can be used to block users by their nick.

Note

Plugin callables with the plugin.unblockable() decorator run regardless of matching *_blocks entries.

We are working toward a better block system; see #1355 for more information and updates.

log_raw#

Whether a log of raw lines as sent and received should be kept.

Default:

no

To enable this logging:

log_raw = yes

See also

The Raw Logs chapter.

logdir#

Directory in which to place logs.

Default:

logs

If the given value is not an absolute path, it will be interpreted relative to the homedir of the config file with which Sopel was started.

See also

The Logging chapter.

logging_channel#

The channel to send logging messages to.

See also

The Log to a Channel chapter.

logging_channel_datefmt#

The format string to use for timestamps in IRC channel logs.

If not specified, this falls back to using logging_datefmt.

See also

Time format reference is available in the documentation for Python’s time.strftime() function.

For more information about logging, see Log to a Channel.

New in version 7.0.

logging_channel_format#

The logging format string to use in IRC channel logs.

If not specified, this falls back to using logging_format.

See also

The Log to a Channel chapter.

New in version 7.0.

logging_channel_level#

The lowest severity of logs to display in IRC channel logs.

See also

The Log to a Channel chapter.

New in version 7.0.

Changed in version 8.0: No longer uses the value of logging_level if not set. Removed DEBUG from the available choices; setting it caused the bot to get caught in an ever-increasing flood prevention loop.

logging_datefmt#

The format string to use for timestamps in logs.

If not set, the datefmt argument is not provided, and logging will use the Python default.

See also

Time format reference is available in the documentation for Python’s time.strftime() function.

New in version 7.0.

logging_format#

The logging format string to use for logs.

Default:

[%(asctime)s] %(name)-20s %(levelname)-8s - %(message)s

The default log line format will output the timestamp, the package that generated the log line, the log level of the line, and (finally) the actual message. For example:

[2019-10-21 12:47:44,272] sopel.irc            INFO     - Connected.

This is equivalent to the default value:

logging_format = [%(asctime)s] %(name)-20s %(levelname)-8s - %(message)s

See also

Python’s logging format documentation: LogRecord attributes

New in version 7.0.

logging_level#

The lowest severity of logs to display.

Default:

INFO

Valid values sorted by increasing verbosity:

  • CRITICAL

  • ERROR

  • WARNING

  • INFO

  • DEBUG

For example to log only at WARNING level and above:

logging_level = WARNING
modes#

User modes to be set on connection.

Include only the mode letters; this value is automatically prefixed with + before Sopel sends the MODE command to IRC.

Changed in version 8.0.0: Now empty by default. Previous default was B, which has been dropped in favor of the formal bot mode specification.

name#

The “real name” of your bot for WHOIS responses.

Default:

Sopel: https://sopel.chat/

nick#

The nickname for the bot.

Default:

Sopel

Required:

nick = Sopel
nick_auth_method#

The nick authentication method.

Can be one of nickserv, authserv, Q, or userserv.

See also

The Authentication chapter for more details.

New in version 7.0.

nick_auth_password#

The password to use to authenticate the bot’s nick.

See also

The Authentication chapter for more details.

New in version 7.0.

nick_auth_target#

The target user for nick authentication.

Default:

NickServ for nickserv authentication; UserServ for userserv authentication

May not apply, depending on the chosen nick_auth_method.

See also

The Authentication chapter for more details.

New in version 7.0.

nick_auth_username#

The username/account to use for nick authentication.

Default:

the value of nick

May not apply, depending on the chosen nick_auth_method.

See also

The Authentication chapter for more details.

New in version 7.0.

nick_blocks#

A list of nicks which Sopel should ignore.

Sopel will ignore messages from any user whose nickname matches one of these values. Regular expression syntax is supported, so remember to escape special characters:

nick_blocks =
    ExactNick
    _*RegexMatch_*

See also

The host_blocks list can be used to block users by their host.

Note

Plugin callables with the plugin.unblockable() decorator run regardless of matching *_blocks entries.

We are working toward a better block system; see #1355 for more information and updates.

not_configured#

For package maintainers. Not used in normal configurations.

Default:

False

This allows software packages to install a default config file, with this option set to True, so that commands to start, stop, or restart the bot won’t work until the bot has been properly configured.

owner#

The IRC name of the owner of the bot.

Required even if owner_account is set.

owner_account#

The services account name of the owner of the bot.

This should only be set on networks which support IRCv3 account capabilities.

pid_dir#

The directory in which to put the file Sopel uses to track its process ID.

Default:

.

If the given value is not an absolute path, it will be interpreted relative to the directory containing the config file with which Sopel was started.

You probably do not need to change this unless you’re managing Sopel with systemd or similar.

port#

The port to connect on.

Default:

6697

Required:

port = 6697

Or if SSL is disabled:

port = 6667
use_ssl = false
prefix#

The prefix to add to the beginning of commands as a regular expression.

Default:

\.

Required:

prefix = \.

With the default value, users will invoke commands like this:

<nick> .help

Since it’s a regular expression, you can use multiple prefixes:

prefix = \.|\?

Important

As the prefix is a regular expression, don’t forget to escape it when necessary. It is not recommended to use capturing groups, as it will create problems with argument parsing for commands.

Note

Remember to change the help_prefix value accordingly:

prefix = \?
help_prefix = ?

In that example, users will invoke commands like this:

<nick> ?help xkcd
<Sopel> ?xkcd - Finds an xkcd comic strip
<Sopel> Takes one of 3 inputs:
[...]
reply_errors#

Whether to reply to the sender of a message that triggered an error.

Default:

True

If True, Sopel will send information about the triggered exception to the sender of the message that caused the error.

If False, Sopel will only log the error and will appear to fail silently from the triggering IRC user’s perspective.

server_auth_method#

The server authentication method.

Can be sasl or server.

New in version 7.0.

server_auth_password#

The password to use to authenticate with the server.

New in version 7.0.

server_auth_sasl_mech#

The SASL mechanism.

Default:

PLAIN

EXTERNAL is also supported, e.g. for using client_cert_file to authenticate via CertFP.

New in version 7.0.

Changed in version 8.0: Added support for SASL EXTERNAL mechanism.

server_auth_username#

The username/account to use to authenticate with the server.

New in version 7.0.

ssl_ciphers#

The cipher suites enabled for SSL/TLS connections.

Default:

ECDHE-ECDSA-AES128-GCM-SHA256 ECDHE-RSA-AES128-GCM-SHA256 ECDHE-ECDSA-AES256-GCM-SHA384 ECDHE-RSA-AES256-GCM-SHA384 ECDHE-ECDSA-CHACHA20-POLY1305 ECDHE-RSA-CHACHA20-POLY1305 DHE-RSA-AES128-GCM-SHA256 DHE-RSA-AES256-GCM-SHA384

The default is the Mozilla Intermediate configuration as of February 2022. This parameter is in OpenSSL format; see the ciphers manual page for your version. This setting cannot be used to configure TLS 1.3.

ssl_ciphers =
    ECDSA+AES256
    !SHA1

Note

Cipher selection is also subject to the available SSL/TLS versions; see ssl_minimum_version.

ssl_minimum_version#

The minimum version allowed for SSL/TLS connections.

Default:

TLSv1_2

You should not set this lower than the default unless the server does not support modern versions. Set this to a TLSVersion value, e.g. TLSv1 or TLSv1_3.

ssl_minimum_version = TLSv1_3

Note

To use insecure SSL/TLS versions, you may also need to enable insecure cipher suites. See ssl_ciphers.

throttle_join#

Slow down the initial join of channels to prevent getting kicked.

Default:

0

Sopel will only join this many channels at a time, sleeping for a second between each batch to avoid getting kicked for joining too quickly. This is unnecessary on most networks.

If not set, or set to 0, Sopel won’t slow down the initial join.

In this example, Sopel will try to join 4 channels at a time:

throttle_join = 4

See also

throttle_wait controls Sopel’s waiting time between joining batches of channels.

throttle_wait#

Time in seconds Sopel waits between joining batches of channels.

Default:

1

In this example:

throttle_wait = 5
throttle_join = 2

Sopel will join 2 channels every 5s.

If throttle_join is 0, this setting has no effect.

See also

throttle_join controls channel batch size.

timeout#

The number of seconds acceptable since the last message before timing out.

Default:

120

You can change the timeout like this:

# increase to 200 seconds
timeout = 200
timeout_ping_interval#

The number of seconds before sending a PING command to the server.

Default:

(auto)

The default value is made to send at least 2 PINGs before the bot thinks there is a timeout, given that timeout is 120s by default:

  • t+54s: first PING

  • t+108s: second PING

  • t+120s: if no response, then a timeout is detected

This makes the timeout detection more lenient and forgiving, by allowing a 12s window for the server to send something that will prevent a timeout.

You can change the PING interval like this:

# timeout up to 250s
timeout = 250
# PING every 80s (about 3 times every 240s + 10s window)
timeout_ping_interval = 80

Note

Internally, the default value is 0 and the value used will be automatically calculated as 45% of the timeout:

ping_interval = timeout * 0.45

So for a timeout of 120s it’s a PING every 54s. For a timeout of 250s it’s a PING every 112.5s.

use_ssl#

Whether to use a SSL/TLS encrypted connection.

Default:

True

Example with SSL off:

use_ssl = false
user#

The “user” for your bot (the part before the @ in the hostname).

Default:

sopel

Required:

user = sopel
verify_ssl#

Whether to require a trusted certificate for encrypted connections.

Default:

True

Example with SSL on:

use_ssl = true
verify_ssl = true
sopel.config.core_section.URL_DEFAULT_SCHEMES = ['http', 'https', 'ftp']#

Default URL schemes allowed for URLs.

sopel.config.core_section.configure(config)#

Interactively configure the bot’s [core] config section.

Parameters:

config (Config) – the bot’s config object