You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
304 lines
8.0 KiB
304 lines
8.0 KiB
Server Configuration
|
|
====================
|
|
|
|
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:
|
|
|
|
.. code-block:: ini
|
|
|
|
[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:
|
|
|
|
.. code-block:: sh
|
|
|
|
~> isso -c path/to/isso.cfg
|
|
~> env ISSO_SETTINGS=path/to/isso.cfg isso
|
|
|
|
__ https://en.wikipedia.org/wiki/INI_file
|
|
|
|
Sections covered in this document:
|
|
|
|
.. contents::
|
|
:local:
|
|
|
|
|
|
General
|
|
-------
|
|
|
|
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:
|
|
|
|
.. code-block:: ini
|
|
|
|
[general]
|
|
dbpath = /tmp/isso.db
|
|
name =
|
|
host =
|
|
max-age = 15m
|
|
notify = stdout
|
|
|
|
dbpath
|
|
file location to the SQLite3 database, highly recommended to change this
|
|
location to a non-temporary location!
|
|
|
|
name
|
|
required to dispatch :ref:`multiple websites <configure-multiple-sites>`,
|
|
not used otherwise.
|
|
|
|
host
|
|
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.
|
|
|
|
.. code-block:: ini
|
|
|
|
[general]
|
|
host =
|
|
http://example.tld/
|
|
https://example.tld/
|
|
|
|
max-age
|
|
time range that allows users to edit/remove their own comments. See
|
|
:ref:`Appendum: Timedelta <appendum-timedelta>` for valid values.
|
|
|
|
notify
|
|
Select notification backend(s) for new comments, separated by comma.
|
|
Available backends:
|
|
|
|
stdout
|
|
Log to standard output. Default, if none selected.
|
|
|
|
smtp
|
|
Send notifications via SMTP on new comments with activation (if
|
|
moderated) and deletion links.
|
|
|
|
|
|
.. _CORS: https://developer.mozilla.org/en/docs/HTTP/Access_control_CORS
|
|
|
|
|
|
Moderation
|
|
----------
|
|
|
|
Enable moderation queue and handling of comments still in moderation queue
|
|
|
|
.. code-block:: ini
|
|
|
|
[moderation]
|
|
enabled = false
|
|
purge-after = 30d
|
|
|
|
enabled
|
|
enable comment moderation queue. This option only affects new comments.
|
|
Comments in modertion queue are not visible to other users until you
|
|
activate them.
|
|
|
|
purge-after
|
|
remove unprocessed comments in moderation queue after given time.
|
|
|
|
|
|
Server
|
|
------
|
|
|
|
HTTP server configuration.
|
|
|
|
.. code-block:: ini
|
|
|
|
[server]
|
|
listen = http://localhost:8080
|
|
reload = off
|
|
profile = off
|
|
|
|
listen
|
|
interface to listen on. Isso supports TCP/IP and unix domain sockets:
|
|
|
|
.. code-block:: ini
|
|
|
|
; UNIX domain socket
|
|
listen = unix:///tmp/isso.sock
|
|
; TCP/IP
|
|
listen = http://localhost:1234/
|
|
|
|
When ``gevent`` is available, it is automatically used for `http://`
|
|
Currently, gevent can not handle http requests on unix domain socket
|
|
(see `#295 <https://github.com/surfly/gevent/issues/295>`_ and
|
|
`#299 <https://github.com/surfly/gevent/issues/299>`_ for details).
|
|
|
|
Does not apply for `uWSGI`.
|
|
|
|
reload
|
|
reload application, when the source code has changed. Useful for
|
|
development. Only works with the internal webserver.
|
|
|
|
profile
|
|
show 10 most time consuming function in Isso after each request. Do
|
|
not use in production.
|
|
|
|
.. _configure-smtp:
|
|
|
|
SMTP
|
|
----
|
|
|
|
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.
|
|
|
|
.. code-block:: ini
|
|
|
|
[smtp]
|
|
username =
|
|
password =
|
|
host = localhost
|
|
port = 587
|
|
security = starttls
|
|
to =
|
|
from =
|
|
timeout = 10
|
|
|
|
username
|
|
self-explanatory, optional
|
|
|
|
password
|
|
self-explanatory (yes, plain text, create a dedicated account for
|
|
notifications), optional.
|
|
|
|
host
|
|
SMTP server
|
|
|
|
port
|
|
SMTP port
|
|
|
|
security
|
|
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.
|
|
|
|
to
|
|
recipient address, e.g. your email address
|
|
|
|
from
|
|
sender address, e.g. `"Foo Bar" <isso@example.tld>`
|
|
|
|
timeout
|
|
specify a timeout in seconds for blocking operations like the
|
|
connection attempt.
|
|
|
|
|
|
Guard
|
|
-----
|
|
|
|
Enable basic spam protection features, e.g. rate-limit per IP address (``/24``
|
|
for IPv4, ``/48`` for IPv6).
|
|
|
|
.. code-block:: ini
|
|
|
|
[guard]
|
|
enabled = true
|
|
ratelimit = 2
|
|
direct-reply = 3
|
|
reply-to-self = false
|
|
|
|
enabled
|
|
enable guard, recommended in production. Not useful for debugging
|
|
purposes.
|
|
|
|
ratelimit
|
|
limit to N new comments per minute. Use -1 to disable rate limit.
|
|
|
|
direct-reply
|
|
how many comments directly to the thread (prevent a simple
|
|
`while true; do curl ...; done`.
|
|
|
|
reply-to-self
|
|
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.
|
|
|
|
Markup
|
|
------
|
|
|
|
Customize markup and sanitized HTML. Currently, only Markdown (via Misaka) is
|
|
supported, but new languages are relatively easy to add.
|
|
|
|
.. code-block:: ini
|
|
|
|
[markup]
|
|
options = strikethrough, superscript, autolink
|
|
allowed-elements =
|
|
allowed-attributes =
|
|
|
|
options
|
|
`Misaka-specific Markdown extensions <http://misaka.61924.nl/api/>`_, all
|
|
flags starting with `EXT_` can be used there, separated by comma.
|
|
|
|
allowed-elements
|
|
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.
|
|
|
|
allowed-attributes
|
|
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``.
|
|
|
|
Hash
|
|
----
|
|
|
|
Customize used hash functions to hide the actual email addresses from
|
|
commenters but still be able to generate an identicon.
|
|
|
|
.. code-block:: ini
|
|
|
|
[hash]
|
|
salt = Eech7co8Ohloopo9Ol6baimi
|
|
algorithm = pbkdf2
|
|
|
|
salt
|
|
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.
|
|
|
|
algorithm
|
|
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.
|
|
|
|
Appendum
|
|
--------
|
|
|
|
.. _appendum-timedelta:
|
|
|
|
Timedelta
|
|
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).
|