The Isso configuration file is an INI-style textfile. It reads integers, booleans, strings and lists. Here’s the default isso configuration: isso.conf <https://github.com/posativ/isso/blob/master/share/isso.conf>. A basic configuration from scratch looks like this:
[general] dbpath = /var/lib/isso/comments.db host = https://example.tld/ [server] listen = http://localhost:1234/
To use your configuration file with Isso, append
-c /path/to/cfg to the
executable or run Isso with an environment variable:
~> isso -c path/to/isso.cfg ~> env ISSO_SETTINGS=path/to/isso.cfg isso
Sections covered in this document:
In this section, you configure most comment-related options such as database path, session key and hostname. Here are the default values for this section:
[general] dbpath = /tmp/isso.db name = host = max-age = 15m notify = stdout log-file =
- file location to the SQLite3 database, highly recommended to change this location to a non-temporary location!
- required to dispatch multiple websites, not used otherwise.
Your website(s). If Isso is unable to connect to at least on site, you’ll get a warning during startup and comments are most likely non-functional.
You’ll need at least one host/website to run Isso. This is due to security reasons: Isso uses CORS to embed comments and to restrict comments only to your website, you have to “whitelist” your website(s).
I recommend the first value to be a non-SSL website that is used as fallback if Firefox users (and only those) supress their HTTP referer completely.
[general] host = http://example.tld/ https://example.tld/
- time range that allows users to edit/remove their own comments. See Appendum: Timedelta for valid values.
Select notification backend(s) for new comments, separated by comma. Available backends:
- Log to standard output. Default, if none selected. Note, this functionality is broken since a few releases.
- Send notifications via SMTP on new comments with activation (if moderated) and deletion links.
- Log console messages to file instead of standard out.
Enable moderation queue and handling of comments still in moderation queue
[moderation] enabled = false purge-after = 30d
- enable comment moderation queue. This option only affects new comments. Comments in modertion queue are not visible to other users until you activate them.
- remove unprocessed comments in moderation queue after given time.
HTTP server configuration.
[server] listen = http://localhost:8080 reload = off profile = off
interface to listen on. Isso supports TCP/IP and unix domain sockets:
; UNIX domain socket listen = unix:///tmp/isso.sock ; TCP/IP listen = http://localhost:1234/
Does not apply for uWSGI.
- reload application, when the source code has changed. Useful for development. Only works with the internal webserver.
- show 10 most time consuming function in Isso after each request. Do not use in production.
Isso can notify you on new comments via SMTP. In the email notification, you
also can moderate (=activate or delete) comments. Don’t forget to configure
notify = smtp in the general section.
[smtp] username = password = host = localhost port = 587 security = starttls to = from = timeout = 10
- self-explanatory, optional
- self-explanatory (yes, plain text, create a dedicated account for notifications), optional.
- SMTP server
- SMTP port
- use a secure connection to the server, possible values: none, starttls or ssl. Note, that there is no easy way for Python 2.7 and 3.3 to implement certification validation and thus the connection is vulnerable to Man-in-the-Middle attacks. You should definitely use a dedicated SMTP account for Isso in that case.
- recipient address, e.g. your email address
- sender address, e.g. “Foo Bar” <firstname.lastname@example.org>
- specify a timeout in seconds for blocking operations like the connection attempt.
Enable basic spam protection features, e.g. rate-limit per IP address (
/48 for IPv6).
[guard] enabled = true ratelimit = 2 direct-reply = 3 reply-to-self = false require-author = false require-email = false
- enable guard, recommended in production. Not useful for debugging purposes.
- limit to N new comments per minute.
- how many comments directly to the thread (prevent a simple while true; do curl …; done.
allow commenters to reply to their own comments when they could still edit the comment. After the editing timeframe is gone, commenters can reply to their own comments anyways.
Do not forget to configure the client.
force commenters to enter a value into the author field. No validation is performed on the provided value.
Do not forget to configure the client accordingly.
force commenters to enter a value into the email field. No validation is performed on the provided value.
Do not forget to configure the client.
Customize markup and sanitized HTML. Currently, only Markdown (via Misaka) is supported, but new languages are relatively easy to add.
[markup] options = strikethrough, superscript, autolink allowed-elements = allowed-attributes =
- Misaka-specific Markdown extensions, all flags starting with EXT_ can be used there, separated by comma.
- Additional HTML tags to allow in the generated output, comma-separated. By default, only a, blockquote, br, code, del, em, h1, h2, h3, h4, h5, h6, hr, ins, li, ol, p, pre, strong, table, tbody, td, th, thead and ul are allowed.
- Additional HTML attributes (independent from elements) to allow in the generated output, comma-separated. By default, only align and href are allowed.
To allow images in comments, you just need to add
allowed-elements = img and
allowed-attributes = src.
Customize used hash functions to hide the actual email addresses from commenters but still be able to generate an identicon.
[hash] salt = Eech7co8Ohloopo9Ol6baimi algorithm = pbkdf2
- A salt is used to protect against rainbow tables. Isso does not make use of pepper (yet). The default value has been in use since the release of Isso and generates the same identicons for same addresses across installations.
Hash algorithm to use – either from Python’s hashlib or PBKDF2 (a computational expensive hash function).
The actual identifier for PBKDF2 is pbkdf2:1000:6:sha1, which means 1000 iterations, 6 bytes to generate and SHA1 as pseudo-random family used for key strengthening. Arguments have to be in that order, but can be reduced to pbkdf2:4096 for example to override the iterations only.
A human-friendly representation of a time range: 1m equals to 60 seconds. This works for years (y), weeks (w), days (d) and seconds (s), e.g. 30s equals 30 to seconds.
You can add different types: 1m30s equals to 90 seconds, 3h45m12s equals to 3 hours, 45 minutes and 12 seconds (12512 seconds).