From 94b1fef28e9f5f1c330995ab250f117993780720 Mon Sep 17 00:00:00 2001 From: Martin Zimmermann Date: Sun, 27 Oct 2013 12:44:59 +0100 Subject: [PATCH] rewrite CONFIGURATION.md in reST and extend document --- docs/CONFIGURATION.md | 90 --------------------- docs/CONFIGURATION.rst | 177 +++++++++++++++++++++++++++++++++++++++++ isso/__init__.py | 2 +- isso/core.py | 7 +- isso/db/spam.py | 2 +- 5 files changed, 182 insertions(+), 96 deletions(-) delete mode 100644 docs/CONFIGURATION.md create mode 100644 docs/CONFIGURATION.rst diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md deleted file mode 100644 index cba2f8a..0000000 --- a/docs/CONFIGURATION.md +++ /dev/null @@ -1,90 +0,0 @@ -Isso Configuration -================== - -The Isso configuration file is an INI-style textfile. You can point Isso to -your configuration file either with `-c path/to/isso.cfg` or with a environment -variable set to the *absolute* path. - -The configuration has several sections: *general* for general application behavior, -*server* to specify host and port when not using uWSGI, *SMTP* to send mail -notifications (heavily recommended to use) and *guard*, a naive solution for spam -and abuse detection. - -## Example Configuration - - [general] - dbpath = /var/lib/isso/comments.db - host = https://example.tld/ - [server] - port = 1234 - -For more information on the syntax, refer to [Wikipedia: INI file][1] - -[1]: https://en.wikipedia.org/wiki/INI_file - -## general - -dbpath -: location to the SQLite3 database, defaults to /tmp/isso.db (may pruned -after system restart, so use a proper location). - -secretkey -: session key. If you restart the application several times per hour for -whatever reason, use a static key. Defaults to a random string per application -start. - -host -: location to your website or blog. When you start Isso, it will try to -establish a connection to your website (a simple HEAD request). If this -check fails, none can comment on your website. - -max-age -: time to allow users to remove or edit their comments. Defaults to `15m`. - -## server (not applicable for uWSGI) - -host -: interface to listen on, defaults to `localhost`. - -port -: port to listen on, defaults to 8080. - -reload -: reload application, when editing the source code (only useful for developers), -disabled by default. - -## moderation - -enabled -: enable comment moderation queue, disabled by default - -purge-after -: remove unprocessed comments in moderation queue after, by default, `30d`. - -## SMTP - -username -: self-explanatory - -password -: self-explanatory (yes, plain text, create a dedicated account for notifications. - -host -: server host, defaults to `localhost`. - -port -: server port, defaults to `465`. - -ssl -: use SSL, defaults to `on`. - -to -: recipient address - -from -: sender address - -## guard - -enabled -: defaults to `on`. diff --git a/docs/CONFIGURATION.rst b/docs/CONFIGURATION.rst new file mode 100644 index 0000000..76b462e --- /dev/null +++ b/docs/CONFIGURATION.rst @@ -0,0 +1,177 @@ +Isso Configuration +================== + +The Isso configuration file is an `INI-style`__ textfile. Below is an example for +a basic Isso configuration. Each section has its own documentation. + +.. code-block:: ini + + [general] + dbpath = /var/lib/isso/comments.db + host = https://example.tld/ + [server] + port = 1234 + +You can point Isso to your configuration file either witg a command-line parameter +or using 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 + + +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 + host = http://localhost:8080/ + max-age = 15m + session-key = ... # python: binascii.b2a_hex(os.urandom(24)) + +dbpath + file location to the SQLite3 database, highly recommended to change this + location to a non-temporary location! + +host + URL to your website. When you start Isso, it will probe your website with + a simple ``GET /`` request to see if it can reach the webserver. If this + fails, Isso may not be able check if a web page exists, thus fails to + accept new comments. + +session-key + private session key to validate client cookies. If you restart the + application several times per hour for whatever reason, use a fixed + key. + +max-age + time range that allows users to edit/remove their own comments. See + :ref:`Appendum: Timedelta ` for valid values. + + +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, does **not** apply to uWSGI. + +.. code-block:: ini + + [server] + host = localhost + port = 8080 + reload = off + +host + listen on specified interface + +port + application port + +reload + reload application, when the source code has changed. Useful for + development (don't forget to use a fixed `session-key`). + + +SMTP +---- + +Isso can notify you on new comments via SMTP. In the email notification, you +also can moderate comments. If the server connection fails during startup, a +null mailer is used. + +.. code-block:: ini + + [smtp] + username = + password = + host = localhost + port = 465 + ssl = on + to = + from = + +username + self-explanatory, optional + +password + self-explanatory (yes, plain text, create a dedicated account for + notifications), optional. + +host + SMTP server + +port + SMTP port + +ssl + use SSL to connect to the server. Python probably does not validate the + certificate. Needs research, though. But you should use a dedicated + email account anyways. + +to + recipient address, e.g. your email address + +from + sender address, e.g. isso@example.tld + + +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 + +enabled + enable guard, recommended in production. Not useful for debugging + purposes. + +ratelimit: N + limit to N new comments per minute. + + +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). diff --git a/isso/__init__.py b/isso/__init__.py index 0df63bd..82f4cba 100644 --- a/isso/__init__.py +++ b/isso/__init__.py @@ -86,7 +86,7 @@ class Isso(object): self.conf = conf self.db = db.SQLite3(conf.get('general', 'dbpath'), conf) - self.signer = URLSafeTimedSerializer(conf.get('general', 'secretkey')) + self.signer = URLSafeTimedSerializer(conf.get('general', 'session-key')) self.j2env = Environment(loader=FileSystemLoader(join(dirname(__file__), 'templates/'))) super(Isso, self).__init__(conf) diff --git a/isso/core.py b/isso/core.py index f9c5c63..a354db8 100644 --- a/isso/core.py +++ b/isso/core.py @@ -51,9 +51,8 @@ class Config: default = [ "[general]", - "dbpath = /tmp/isso.db", "secretkey = %r" % binascii.b2a_hex(os.urandom(24)), - "host = http://localhost:8080/", "passphrase = p@$$w0rd", - "max-age = 15m", + "dbpath = /tmp/isso.db", "session-key = %r" % binascii.b2a_hex(os.urandom(24)), + "host = http://localhost:8080/", "max-age = 15m", "[moderation]", "enabled = false", "purge-after = 30d", @@ -64,7 +63,7 @@ class Config: "host = localhost", "port = 465", "ssl = on", "to = ", "from = ", "[guard]", - "enabled = on", + "enabled = true", "ratelimit = 2" "" ] diff --git a/isso/db/spam.py b/isso/db/spam.py index 5713bce..1b840f2 100644 --- a/isso/db/spam.py +++ b/isso/db/spam.py @@ -21,7 +21,7 @@ def check(func): 'SELECT id FROM comments WHERE remote_addr = ? AND created > ?;' ], (c["remote_addr"], time.time() + 60)).fetchall() - if len(rv) >= 2: + if len(rv) >= self.db.conf.getint("guard", "ratelimit"): raise TooManyComments # block more than three comments as direct response to the post