https://docs.rspamd.com/assets/js/974d80ef.25c49092.js

1"use strict";(self.webpackChunkrspamd_docs=self.webpackChunkrspamd_docs||[]).push([[2850],{22637:(e,s,i)=>{i.r(s),i.d(s,{assets:()=>l,contentTitle:()=>t,default:()=>h,frontMatter:()=>o,metadata:()=>n,toc:()=>a});const n=JSON.parse('{"id":"configuration/redis","title":"Redis configuration","description":"This document provides instructions on setting up a Redis cache in Rspamd.","source":"@site/docs/configuration/redis.md","sourceDirName":"configuration","slug":"/configuration/redis","permalink":"/configuration/redis","draft":false,"unlisted":false,"editUrl":"https://github.com/rspamd/docs.rspamd.com/edit/master/docs/configuration/redis.md","tags":[],"version":"current","frontMatter":{"title":"Redis configuration"},"sidebar":"docs","previous":{"title":"Statistics settings","permalink":"/configuration/statistic"},"next":{"title":"Upstreams configuration","permalink":"/configuration/upstream"}}');var r=i(74848),d=i(28453);const o={title:"Redis configuration"},t="Redis configuration for Rspamd",l={},a=[{value:"Introduction",id:"introduction",level:2},{value:"Redis setup",id:"redis-setup",level:2},{value:"Available Redis options",id:"available-redis-options",level:2},{value:"Key expansion",id:"key-expansion",level:2},{value:"Redis Sentinel",id:"redis-sentinel",level:2}];function c(e){const s={a:"a",code:"code",h1:"h1",h2:"h2",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,d.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(s.header,{children:(0,r.jsx)(s.h1,{id:"redis-configuration-for-rspamd",children:"Redis configuration for Rspamd"})}),"\n",(0,r.jsx)(s.p,{children:"This document provides instructions on setting up a Redis cache in Rspamd."}),"\n",(0,r.jsx)(s.h2,{id:"introduction",children:"Introduction"}),"\n",(0,r.jsxs)(s.p,{children:["The ",(0,r.jsx)(s.a,{href:"https://redis.io",children:"Redis"})," cache server, is utilized as a highly efficient key-value storage by various Rspamd modules, including the following:"]}),"\n",(0,r.jsxs)(s.ul,{children:["\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.a,{href:"/modules/ratelimit",children:"Ratelimit plugin"})," uses Redis to store limits buckets"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.a,{href:"/modules/greylisting",children:"Greylisting module"})," stores data and meta hashes inside Redis"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.a,{href:"/modules/dmarc",children:"DMARC module"})," can save DMARC reports inside Redis keys"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.a,{href:"/modules/replies",children:"Replies plugin"})," requires Redis to save message ids hashes for outgoing messages"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.a,{href:"/modules/ip_score",children:"IP score plugin"})," uses Redis to store data about AS, countries and networks reputation"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.a,{href:"/modules/multimap",children:"Multimap module"})," can use Redis as readonly database for maps"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.a,{href:"/modules/mx_check",children:"MX Check module"})," uses Redis for caching"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.a,{href:"/modules/reputation",children:"Reputation module"})," uses Redis for caching"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.a,{href:"/modules/neural",children:"Neural network module"})," uses Redis for data storage"]}),"\n"]}),"\n",(0,r.jsxs)(s.p,{children:["Furthermore, Redis is used to store Bayes tokens in the ",(0,r.jsx)(s.a,{href:"/configuration/statistic",children:"statistics"})," module. Rspamd offers multiple configuration options for Redis storage. Moreover, Redis ",(0,r.jsx)(s.a,{href:"https://redis.io/docs/management/replication/",children:"replication"})," is supported, enabling Rspamd to ",(0,r.jsx)(s.strong,{children:"write"})," values to one set of Redis servers and ",(0,r.jsx)(s.strong,{children:"read"})," data from another set."]}),"\n",(0,r.jsx)(s.h2,{id:"redis-setup",children:"Redis setup"}),"\n",(0,r.jsx)(s.p,{children:"There are couple of ways to configure Redis for a module. First of all, you can place all Redis options inside the relevant module's section:"}),"\n",(0,r.jsx)(s.pre,{children:(0,r.jsx)(s.code,{className:"language-hcl",children:'dmarc {\n  servers = "127.0.0.1";\n}\n'})}),"\n",(0,r.jsxs)(s.p,{children:["However, it is recommended to use the local and override directories for such configurations. For instance, you can create a file called ",(0,r.jsx)(s.code,{children:"/etc/rspamd/local.d/dmarc.conf"})," for this specific case:"]}),"\n",(0,r.jsx)(s.pre,{children:(0,r.jsx)(s.code,{className:"language-hcl",children:'# local.d/dmarc.conf\nservers = "127.0.0.1";\n'})}),"\n",(0,r.jsx)(s.p,{children:"You can specify multiple servers by separating them with commas. Each server can also have an optional port value:"}),"\n",(0,r.jsx)(s.pre,{children:(0,r.jsx)(s.code,{className:"language-hcl",children:'  servers = "serv1,serv2:6371";\n'})}),"\n",(0,r.jsxs)(s.p,{children:["By default, Rspamd uses port ",(0,r.jsx)(s.code,{children:"6379"})," for Redis. Alternatively, you can define the full features of upstream options when specifying servers:"]}),"\n",(0,r.jsx)(s.pre,{children:(0,r.jsx)(s.code,{className:"language-hcl",children:'  servers = "master-slave:127.0.0.1,10.0.1.1";\n'})}),"\n",(0,r.jsxs)(s.p,{children:["You can simplify the configuration of Redis options for each individual module by using a common ",(0,r.jsx)(s.code,{children:"redis"})," section. This can be done by defining the section in a separate file, such as ",(0,r.jsx)(s.code,{children:"/etc/rspamd/local.d/redis.conf"}),". This approach helps streamline the configuration process and make it more organized.\nFor more detailed information, you can refer to the ",(0,r.jsx)(s.a,{href:"/configuration/upstream",children:"upstream

1s documentation"}),"."]}),"\n",(0,r.jsx)(s.pre,{children:(0,r.jsx)(s.code,{className:"language-hcl",children:'# /etc/rspamd/local.d/redis.conf\nread_servers = "127.0.0.1,10.0.0.1";\nwrite_servers = "127.0.0.1";\n'})}),"\n",(0,r.jsxs)(s.p,{children:["Please bear in mind that you should either use ",(0,r.jsx)(s.code,{children:"servers"})," for both ",(0,r.jsx)(s.code,{children:"read_servers"})," and ",(0,r.jsx)(s.code,{children:"write_servers"}),", or define ",(0,r.jsx)(s.code,{children:"read_servers"})," and ",(0,r.jsx)(s.code,{children:"write_servers"})," separately. So it is ",(0,r.jsx)(s.strong,{children:"either"})," ",(0,r.jsx)(s.code,{children:"servers"})," ",(0,r.jsx)(s.strong,{children:"alone"}),", or ",(0,r.jsx)(s.code,{children:"read_servers"}),"+",(0,r.jsx)(s.code,{children:"write_servers"})," ",(0,r.jsx)(s.strong,{children:"together"}),"."]}),"\n",(0,r.jsxs)(s.p,{children:["Additionally, you have the option to redefine Redis options inside the ",(0,r.jsx)(s.code,{children:"redis"})," section specifically for the desired module or modules. This provides flexibility in configuring Redis options on a per-module basis:"]}),"\n",(0,r.jsx)(s.pre,{children:(0,r.jsx)(s.code,{className:"language-hcl",children:'# /etc/rspamd/local.d/redis.conf\nread_servers = "127.0.0.1,10.0.0.1";\nwrite_servers = "127.0.0.1";\n\ndmarc {\n  servers = "10.0.1.1";\n}\n'})}),"\n",(0,r.jsxs)(s.p,{children:["In this example, the ",(0,r.jsx)(s.code,{children:"dmarc"})," module will use a different set of servers than other modules. If you want to exclude specific modules from using the common Redis options, you can add them to the ",(0,r.jsx)(s.code,{children:"disabled_modules"})," list, like this:"]}),"\n",(0,r.jsx)(s.pre,{children:(0,r.jsx)(s.code,{className:"language-hcl",children:'# /etc/rspamd/local.d/redis.conf\nservers = "127.0.0.1";\n\ndisabled_modules = ["ratelimit"];\n'})}),"\n",(0,r.jsxs)(s.p,{children:["This configuration snippet prevents the ",(0,r.jsx)(s.code,{children:"ratelimit"})," module from using the common Redis configuration. If Redis is not explicitly configured for this module (either in the ",(0,r.jsx)(s.code,{children:"redis"})," -> ",(0,r.jsx)(s.code,{children:"ratelimit"})," section or in the ",(0,r.jsx)(s.code,{children:"ratelimit"})," section), the module will be disabled."]}),"\n",(0,r.jsx)(s.h2,{id:"available-redis-options",children:"Available Redis options"}),"\n",(0,r.jsx)(s.p,{children:"Rspamd supports the following Redis options (common for all modules):"}),"\n",(0,r.jsxs)(s.ul,{children:["\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"servers"}),": ",(0,r.jsx)(s.a,{href:"/configuration/upstream",children:"upstreams list"})," for both read and write requests"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"read_servers"}),": ",(0,r.jsx)(s.a,{href:"/configuration/upstream",children:"upstreams list"})," for read only servers (usually replication slaves)"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"write_servers"}),": ",(0,r.jsx)(s.a,{href:"/configuration/upstream",children:"upstreams list"})," for write only servers (usually replication master)"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"timeout"}),": timeout in seconds to get reply from Redis (e.g. ",(0,r.jsx)(s.code,{children:"0.5s"})," or ",(0,r.jsx)(s.code,{children:"1min"}),")"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"db"}),": number of database to use (by default, Rspamd will use the default Redis database with number ",(0,r.jsx)(s.code,{children:"0"}),")"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"password"}),": password to connect to Redis (no password by default)"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"username"}),": username to use when authenticating to Redis"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"prefix"}),": use the specified prefix for keys in Redis (if supported by module)"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"expand_keys"})," (1.7.0+): if set to ",(0,r.jsx)(s.code,{children:"true"})," 'expand' key names used in queries (discussed further below)"]}),"\n"]}),"\n",(0,r.jsx)(s.h2,{id:"key-expansion",children:"Key expansion"}),"\n",(0,r.jsxs)(s.p,{children:["Starting from version 1.7.0, if you set the ",(0,r.jsx)(s.code,{children:"redis.expand_keys"})," configuration parameter to ",(0,r.jsx)(s.code,{children:"true"}),", special values can be replaced in key names before they are sent to Redis when performing queries via Lua (as in plugins like ",(0,r.jsx)(s.code,{children:"multimap"}),", ",(0,r.jsx)(s.code,{children:"ratelimit"}),", and ",(0,r.jsx)(s.code,{children:"settings"}),"). If you are using module-specific Redis configuration, you can specify this setting in the module configuration instead of ",(0,r.jsx)(s.code,{children:"redis"}),"."]}),"\n",(0,r.jsxs)(s.p,{children:["Given this setting is enabled, where-ever names of keys could be specified in configuration special values could be used, for example ",(0,r.jsx)(s.code,{children:'map = "redis://${ip}!foo'})," in multimap configuration would dynamically set key name to something like ",(0,r.jsx)(s.code,{children:"1.2.3.4!foo"}),". Variable names which could be used are as follows:"]}),"\n",(0,r.jsxs)(s.ul,{children:["\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"ip"}),": sending IP of a message"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"principal_recipient"}),": the address of the ",(0,r.jsx)(s.a,{href:"/lua/rspamd_task#mc5168",children:"principal recipient"})," of a message (",(0,r.jsx)(s.code,{children:"Deliver-To"})," request header, first SMTP recipient or MIME recipient according to availability)"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"principal_recipient_domain"}),": the domain name of the principal recipient"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"esld_principal_recipient_domain"}),": the domain name of the principal recipient, normalised to eSLD"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"smtp_from"}),": SMTP sender address"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"smtp_from_domain"}),": SMTP sender address domain"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"esld_smtp_from_domain"}),": SMTP sender address domain, normalised to eSLD"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"smtp_from_domain_or_helo"}),": SMTP sender address domain or HELO if address is empty/absent"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"esld_smtp_from_domain_or_helo"}),": SMTP sender address domain or HELO if address is empty/absent, normalised to eSLD"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"mime_from"}),": MIME sender address"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"mime_from_domain"}),": MIME sender address domain"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"esld_mime_from_domain"}),": MIME sender address domain, normalised to eSLD"]}),"\n"]}

1),"\n",(0,r.jsx)(s.h2,{id:"redis-sentinel",children:"Redis Sentinel"}),"\n",(0,r.jsxs)(s.p,{children:["From the version 1.8.3, Rspamd supports ",(0,r.jsx)(s.a,{href:"https://redis.io/topics/sentinel",children:"Redis Sentinel"}),". Sentinels could be defined as following:"]}),"\n",(0,r.jsx)(s.pre,{children:(0,r.jsx)(s.code,{className:"language-hcl",children:'# local.d/redis.conf\nsentinels = "127.0.0.1,10.0.0.1,10.0.0.2"; # Servers list (default port 5000)\nsentinel_watch_time = 1min; # How often Rspam will query sentinels for masters and slaves\nsentinel_masters_pattern = "^mymaster.*$"; # Defines masters pattern to match in Lua syntax (no pattern means all masters)\n'})}),"\n",(0,r.jsx)(s.p,{children:"Rspamd will utilize sentinels to determine which servers should be designated as write_servers and which should be designated as read_servers. Although Redis sentinel does not fully support multi-master configurations, this feature can still be valuable for switching masters when accessing non-volatile data such as statistics, fuzzy storage, or neural network data. However, it is important to note that you must still configure an initial set of servers to be used in case no sentinel is accessible."})]})}function h(e={}){const{wrapper:s}={...(0,d.R)(),...e.components};return s?(0,r.jsx)(s,{...e,children:(0,r.jsx)(c,{...e})}):c(e)}},28453:(e,s,i)=>{i.d(s,{R:()=>o,x:()=>t});var n=i(96540);const r={},d=n.createContext(r);function o(e){const s=n.useContext(d);return n.useMemo((function(){return"function"==typeof e?e(s):{...s,...e}}),[s,e])}function t(e){let s;return s=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:o(e.components),n.createElement(d.Provider,{value:s},e.children)}}}]);