Services configuration

The services section controls which listeners are started and how each one behaves at the network level. Each entry is named after the process that reads it: the *_login entries are the login proxies', which alone terminate client TLS, and the bare names are the session backends', one plain listener each. A process reads its own entries only: one it needs that is missing stops its start, naming the key. enabled: false leaves the listener off.

Common fields

All services share the following fields:

`enabled`

Default: false
Type: boolean

Start this listener on startup.

`address`

Default: 127.0.0.1 on a session backend and on yarilo; every interface on a login proxy
Type: string
See also: port
Added: 2.4.6

Host the listener binds. Empty leaves it to the process that binds it: a session backend entry (imap, pop3, submission, lmtp, managesieve, jmap) binds 127.0.0.1, in its own binary and in the single yarilo binary alike, since a backend takes logins only through a login proxy; a login proxy's *_login entry binds every interface. Each listener logs the address it bound and whether it came from this key or from the role. The Helm chart and the compose example set 0.0.0.0, every interface.

`port`

Default: 0
Type: integer

TCP port to bind. Required: there is no default, and an unset port binds port 0, a random one. The table below gives the conventional ports.

`ssl_mode`

Default: none
Type: string
Values: ssl starttls required no

TLS mode: ssl is implicit TLS; starttls is plain with a STARTTLS upgrade; required is starttls with no authentication before TLS; no is plain only. required applies to imap_login, pop3_login, submission_login and managesieve_login, needs a certificate and auth_allow_cleartext: false; the server refuses to start otherwise. Under required a connection is secured by TLS, a local peer, or a PROXY header whose PP2_TYPE_SSL TLV carries PP2_CLIENT_SSL; a peer in general.xclient.trusted_nets and a plain PROXY header are not. Before that no mechanism is offered, SCRAM included: IMAP advertises LOGINDISABLED and no AUTH=, POP3 neither USER nor SASL, ManageSieve no SASL, EHLO no AUTH. AUTHENTICATE/AUTH get "Authentication disallowed on non-secure (SSL/TLS) connections." (IMAP NO [PRIVACYREQUIRED], POP3 -ERR [AUTH], ManageSieve NO (ENCRYPT-NEEDED)), logged as Login failed: SSL required for authentication; LOGIN and USER/PASS get the auth_allow_cleartext refusal. Submission answers every command but EHLO, STARTTLS, NOOP and QUIT with 530 5.7.0 TLS required. In the chart: components.<login>.listeners.<listener>.ssl_mode, starttls by default.

`haproxy_protocol`

Default: false
Type: boolean
See also: timeout

Extract the real client IP from the HAProxy PROXY header. Uses general.haproxy for the timeout and trusted nets. yarilo-managesieve-login reads it and the general trusted networks like the other login proxies; its pre-2.4.7 managesieve_login_service.haproxy_protocol and managesieve_login_service.haproxy_trusted_nets are still accepted with a warning, and when both nets keys are set the general one is used.

`xclient_protocol`

Default: false
Type: boolean

Accept the XCLIENT command from trusted relays. Uses general.xclient.trusted_nets, empty by default; only peers in it see XCLIENT advertised.

`auth_allow_cleartext`

Default: false
Type: boolean
Helm: components.<login>.listeners.<listener>.auth_allow_cleartext

When false, cleartext mechanisms (PLAIN, LOGIN, OAUTHBEARER, XOAUTH2, POP3 USER/PASS, HTTP Basic and Bearer) are hidden and refused on a connection that is not secured, on any listener: a listener with ssl_mode: no needs true to take a password login. A connection is secured by TLS (implicit or after STARTTLS/STLS), by a local peer (same IP on both ends of the socket), by a peer in general.xclient.trusted_nets, or by a PROXY header accepted from general.haproxy.haproxy_trusted_networks. While refused, IMAP advertises LOGINDISABLED instead of AUTH=PLAIN AUTH=LOGIN, sends * BAD [ALERT] when the password was already sent, and answers LOGIN/AUTHENTICATE with NO [PRIVACYREQUIRED]; POP3 drops USER and SASL PLAIN LOGIN from CAPA and answers -ERR [AUTH]; SMTP AUTH gets 523 5.7.10; ManageSieve drops PLAIN LOGIN from SASL and answers NO "Cleartext authentication disallowed on non-secure (SSL/TLS) connections.". Each refusal logs Login failed: Cleartext authentication disabled.

A service may also carry ssl, a per-service SSL override with the same fields as general.ssl; it overrides only the fields it sets.

Renamed with an inverted sense

auth_allow_cleartext replaces the pre-beta disable_plaintext_auth, and the meaning is flipped: auth_allow_cleartext: false is what disable_plaintext_auth: true used to say. The old key is still accepted on its own. Setting both keys on one listener refuses startup - even when their values agree - because a config carrying both is one edit away from meaning the opposite of what it says.

Listeners

The ports are the conventional ones; the Helm chart puts the login pods on the 10xxx container ports behind their Services.

Key	Port	ssl_mode	Read by	Protocol doc
`imaps_login`	`993`	`ssl`	`yarilo-imap-login`	IMAP configuration
`imap_login`	`143`	`starttls`	`yarilo-imap-login`	IMAP configuration
`submissions_login`	`465`	`ssl`	`yarilo-submission-login`	Submission configuration
`submission_login`	`587`	`starttls`	`yarilo-submission-login`	Submission configuration
`pop3s_login`	`995`	`ssl`	`yarilo-pop3-login`	POP3 configuration
`pop3_login`	`110`	`starttls`	`yarilo-pop3-login`	POP3 configuration
`lmtp_login`	`24`	`no`	`yarilo-lmtp-login`	LMTP configuration
`managesieve_login`	`4190`	`starttls`	`yarilo-managesieve-login`	SIEVE
`jmap_login`	`8443`	`ssl`	`yarilo-jmap-login`	JMAP

Session backends

One plain listener per backend, which its login proxy dials; the single yarilo binary reads these entries and none of the *_login ones.

Key	Port (chart)	Read by
`imap`	`10143`	`yarilo-imap`
`pop3`	`10110`	`yarilo-pop3`
`submission`	`10587`	`yarilo-submission`
`lmtp`	`10024`	`yarilo-lmtp`
`managesieve`	`14190`	`yarilo-managesieve`
`jmap`	`10443`	`yarilo-jmap`

Removed in 2.4.6

These keys stop the start, and the message names the key that replaced them:

Removed	Use
`imaps`, `pop3s`, `submissions`	`imaps_login`, `pop3s_login`, `submissions_login`; a backend has no implicit-TLS listener
`managesieve_be`	`managesieve`
`jmap_be`	`jmap`

Before 2.4.6, imap, pop3, submission, lmtp, managesieve and jmap were the login proxies' entries; they are the backends' now.

Internal services

Outside k8s, the internal services listen on 127.0.0.1 unless the config names an address, and so does a session backend whose address is empty. A host install that reaches any of them from another host sets the address explicitly. The Helm chart sets every one of them, so a release listens as before. The director's ring and API (director_service.listen) and the quota policy service (quota_status.listen) follow the same rule.

`listen`

Default: 127.0.0.1:9100
Type: string
Helm: components.auth.listen
Changed 2.4.6: The default was :9100, every interface.

Client-protocol listener of yarilo-auth, where the login proxies check passwords. unix:/path listens on a Unix socket.

`listen`

Default: 127.0.0.1:9101
Type: string
Helm: components.warden.service.listen
Changed 2.4.6: The default was :9101, every interface.

Listener of yarilo-warden, the per-IP authentication penalty service. unix:/path listens on a Unix socket.

`listen`

Default: 127.0.0.1:9105
Type: string
Helm: components.backendAPI.listen
Changed 2.4.6: The default was :9105, every interface. An empty value now refuses startup.

Listener of yarilo-backend-api, the per-account admin API that yarctl backend talks to.

`fts_listen`

Default: 127.0.0.1:9106
Type: string
Helm: fts.fts_listen
Changed 2.4.6: The default was :9106, every interface. An empty value now refuses startup.

Listener of yarilo-fts, which the backends call to index and search.

`listen`

Default: 127.0.0.1:12345
Type: string
Changed 2.4.6: The default was :12345, every interface. An empty value now refuses startup.

Listener a fronting MTA names in smtpd_sasl_path. The chart sets it from components.saslLogin.containerPort.

Unix sockets

On one host, yarilo-auth, yarilo-warden and yarilo-dict can listen on Unix sockets instead: a listen or dial address written unix:/path is a socket, and yarilo-locks in embedded mode uses one already.

The socket gets its mode and group after the bind, so the umask does not decide them. A group that does not exist, or that the process may not give the socket, stops the start.
A socket file left by a process that is gone is replaced. One a running process answers on is left to it and the start fails, so a second instance cannot take it; a path that is not a socket is never removed.
internal_tls does not apply to a socket, on either side: its permissions are the boundary. With internal_tls on, the process logs that once per address.
The master listener issues sessions without a password. On a socket, yarilo-auth reads the peer's uid from the kernel and issues one only to the users in auth_service.master_session_users, so a login proxy that can reach the socket still cannot issue itself a session.

`addr`

Default: none
Type: string
Helm: components.auth.addr

Address the login proxies dial to reach yarilo-auth. Empty is auth_service.listen. unix:/path dials a Unix socket.

`master_listen`

Default: none
Type: string
Helm: components.auth.masterListen
See also: master_socket_mode

Master listener of yarilo-auth, which answers userdb lookups without a password. Empty does not open it. unix:/path listens on a Unix socket.

`master_addr`

Default: none
Type: string

Address session processes dial for userdb lookups on the master listener. unix:/path dials a Unix socket.

`socket_mode`

Default: 0660
Type: string
Helm: components.auth.socket_mode
Added: 2.4.6

Octal mode of a unix:/path client listener, set after the bind, so the umask does not decide it.

`socket_group`

Default: none
Type: string
Helm: components.auth.socket_group
Added: 2.4.6

Group name of a unix:/path client listener. Empty keeps the process's group; a group that does not exist, or that the process may not give the socket, stops the start.

`master_socket_mode`

Default: 0660
Type: string
Helm: components.auth.master_socket_mode
Added: 2.4.6

Octal mode of a unix:/path master listener. It answers without a password, so it has its own mode; 0600 keeps it to the auth user.

`master_socket_group`

Default: none
Type: string
Helm: components.auth.master_socket_group
Added: 2.4.6

Group name of a unix:/path master listener; empty keeps the process's group.

`master_session_users`

Default: yarilo-delivery
Type: list
Helm: components.auth.master_session_users
Added: 2.4.6

Users, by name or numeric uid, whose processes may issue a session on a unix:/path master listener: the master listener issues one for any user without a password, which is how yarilo-lmtp-login delivers. Every other peer gets FAIL, and so does a peer whose uid cannot be read; an empty list lets none. An unknown name stops the start, and so does an OS that gives no peer credentials on a Unix socket (NetBSD, OpenBSD). Over TCP the internal TLS roles decide and this list is not read.

`addr`

Default: none
Type: string

Address the login proxies and yarilo-auth dial to reach yarilo-warden. Empty is warden_service.listen. unix:/path dials a Unix socket.

`fail_open`

Default: false
Type: boolean
Helm: components.warden.service.fail_open
Added: 2.4.6

What a login proxy does when it cannot reach yarilo-warden to count a connection. false refuses the connection: IMAP answers NO [UNAVAILABLE] and JMAP 503. true lets it in uncounted, so the connection limits are approximate until warden is back. A reached connection limit is refused either way. See Connection limits.

`socket_mode`

Default: 0660
Type: string
Helm: components.warden.service.socket_mode
Added: 2.4.6

Octal mode of a unix:/path warden listener, set after the bind.

`socket_group`

Default: none
Type: string
Helm: components.warden.service.socket_group
Added: 2.4.6

Group name of a unix:/path warden listener; empty keeps the process's group.

Examples

A whole host, with every process reading one file, is in One host.

yaml

services:
  imaps_login:
    enabled: true
    port: 993
    ssl_mode: ssl
    haproxy_protocol: true
  imap_login:
    enabled: true
    port: 143
    ssl_mode: starttls
    haproxy_protocol: true
    auth_allow_cleartext: false

yaml

services:
  submission_login:
    enabled: true
    port: 587
    ssl_mode: starttls
    auth_allow_cleartext: false
  submissions_login:
    enabled: true
    port: 465
    ssl_mode: ssl
    auth_allow_cleartext: false

LMTP backend (yarilo-lmtp)

yaml

services:
  lmtp:
    enabled: true
    port: 10024
    ssl_mode: "no"

Accepts preamble connections from yarilo-lmtp-login only. See LMTP configuration for architecture and lmtp_login_service config.

Per-service TLS certificate override

yaml

services:
  imaps_login:
    enabled: true
    port: 993
    ssl_mode: ssl
    ssl:
      ssl_server_cert_file: /etc/ssl/mail.example.com/cert.pem
      ssl_server_key_file:  /etc/ssl/mail.example.com/key.pem

Services configuration ​

Common fields ​

enabled ​

address ​

port ​

ssl_mode ​

haproxy_protocol ​

xclient_protocol ​

auth_allow_cleartext ​

Listeners ​

Login proxies ​

Session backends ​

Removed in 2.4.6 ​

Internal services ​

listen ​

listen ​

listen ​

fts_listen ​

listen ​

Unix sockets ​

addr ​

master_listen ​

master_addr ​

socket_mode ​

socket_group ​

master_socket_mode ​

master_socket_group ​

master_session_users ​

addr ​

fail_open ​

socket_mode ​

socket_group ​

Examples ​

IMAP login proxy behind HAProxy ​

Submission login proxy ​

LMTP backend (yarilo-lmtp) ​

Per-service TLS certificate override ​

Services configuration

Common fields

`enabled`

`address`

`port`

`ssl_mode`

`haproxy_protocol`

`xclient_protocol`

`auth_allow_cleartext`

Listeners

Login proxies

Session backends

Removed in 2.4.6

Internal services

`listen`

`listen`

`listen`

`fts_listen`

`listen`

Unix sockets

`addr`

`master_listen`

`master_addr`

`socket_mode`

`socket_group`

`master_socket_mode`

`master_socket_group`

`master_session_users`

`addr`

`fail_open`

`socket_mode`

`socket_group`

Examples

IMAP login proxy behind HAProxy

Submission login proxy

LMTP backend (yarilo-lmtp)

Per-service TLS certificate override