From 8c4d5f256bdd8dd52c5f2b8bd7eb7c164b9f21f2 Mon Sep 17 00:00:00 2001 From: Vsevolod Stakhov Date: Mon, 8 Sep 2014 12:20:15 +0100 Subject: [PATCH] Add migration notes. --- doc/migration.md | 156 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 156 insertions(+) create mode 100644 doc/migration.md diff --git a/doc/migration.md b/doc/migration.md new file mode 100644 index 000000000..9af812b48 --- /dev/null +++ b/doc/migration.md @@ -0,0 +1,156 @@ +# Migrating between rspamd version + +This document describes incompatible changes introduced in the recent rspamd +versions. Here you can find information about how to overcome this incompatibilities +and update your rules and configuration according to these changes. + +## Migrating from rspamd 0.6 to rspamd 0.7 + +### Webui changes + +Rspamd web interface is now a part of distribution. Moreover, all static files +are now served by rspamd itself so you won't need to setup additional web server +to distribute static files. At the same time, webui worker is now removed and +the controller acts as webui+old_controller allowing to work with both web browser +and rspamc client. However, one might still want to setup a full-featured HTTP +server before rspamd to enable, for example TLS and access controls. + +Now there are two password levels for rspamd: `password` for read-only commands +and `enable_password` for data changing commands. If `enable_password` is not +specified then `password` is used for both commands. + +Here is an example of the full configuration of rspamd controller worker to +serve webui: + +~~~nginx +worker { + type = "controller"; + bind_socket = "localhost:11334"; + count = 1; + password = "q1"; + enable_password = "q2"; + secure_ip = "127.0.0.1"; # Allows to use *all* commands from this IP + static_dir = "${WWWDIR}"; +} +~~~ + +### Lua changes + +There are many changes in lua API and some of them are unfortunately breaking ones. + +* remove many superglobals: now rspamd modules need to be loaded explicitly, +the only global remaining is `rspamd_config`. This affects the follwing modules: + - `rspamd_logger` + - `rspamd_ip` + - `rspamd_http` + - `rspamd_cdb` + - `rspamd_regexp` + - `rspamd_trie` + +~~~lua +local rspamd_logger = require "rspamd_logger" +local rspamd_trie = require "rspamd_trie" +local rspamd_cdb = require "rspamd_cdb" +local rspamd_ip = require "rspamd_ip" +local rspamd_regexp = require "rspamd_regexp" +~~~ + +* new system of symbols registration: now symbols can be registered by adding +new indices to `rspamd_config` object. Old version: + +~~~lua +local reconf = config['regexp'] +reconf['SYMBOL'] = function(task) +... +end +~~~ + +new one: + +~~~lua +rspamd_config.SYMBOL = function(task) +... +end +~~~ + +* `rspamd_message` is **removed** completely, you should use task methods to +access message's data. This includes such methods as: + - `get_date` - now this method can return date for task and message based + on the arguments: + +~~~lua +local dm = task:get_date{format = 'message'} -- MIME message date +local dt = task:get_date{format = 'connect'} -- check date +~~~ + + - `get_header` - this function is now totally reworked. Now `get_header` version + returns just a decoded string, `get_header_raw` returns undecoded string and + `get_header_full` returns the full list of tables. Please consult with the + corresponding [documentation](https://rspamd.com/doc/lua/task.html) for details. + You also might want to correct old invocation of task:get_header to new one. + Old version: + +~~~lua +function kmail_msgid (task) + local msg = task:get_message() + local header_msgid = msg:get_header('Message-Id') + if header_msgid then + -- header_from and header_msgid are tables + for _,header_from in ipairs(msg:get_header('From')) do + ... + end + end + return false +end +~~~ + + new one: + +~~~lua +function kmail_msgid (task) + local header_msgid = task:get_header('Message-Id') + if header_msgid then + local header_from = task:get_header('From') + -- header_from and header_msgid are strings + end + return false +end +~~~ + + or with the full version: + +~~~lua +rspamd_config.FORGED_GENERIC_RECEIVED5 = function (task) + local headers_recv = task:get_header_full('Received') + if headers_recv then + -- headers_recv is now the list of tables + for _,header_r in ipairs(headers_recv) do + if re:match(header_r['value']) then + return true + end + end + end + return false +end +~~~ + + - `get_from` and `get_recipients` now accepts optional numeric argument that + specifies where to get a sender and recipients for a message. By default this + argument is `0` which means that data is initially checked in SMTP envelope + (meaning `MAIL FROM` and `RCPT TO` SMTP commands) and if envelope data is + unaccessible then it is grabbed from MIME headers. Value `1` means that data + is checked on envelope only, whilst `2` switches mode to MIME headers. Here is + an example from `forged_recipients` module: + +~~~lua + -- Check sender +local smtp_from = task:get_from(1) +if smtp_from then + local mime_from = task:get_from(2) + if not mime_from or + not (string.lower(mime_from[1]['addr']) == + string.lower(smtp_from[1]['addr'])) then + task:insert_result(symbol_sender, 1) + end +end +~~~ \ No newline at end of file -- 2.39.5