Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve quick configuration guide #1085

Merged
merged 5 commits into from
Nov 28, 2024
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion data/settings.js
Original file line number Diff line number Diff line change
Expand Up @@ -10093,7 +10093,6 @@ auth_ssl_require_client_cert = yes
},

ssl_cert_file: {
default: '</etc/ssl/certs/dovecot.pem',
seealso: [ 'ssl', 'ssl_key_file', '[[link,ssl_configuration]]' ],
values: setting_types.FILE,
text: `
Expand Down
35 changes: 12 additions & 23 deletions docs/core/config/guides/quick.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,18 +101,11 @@ doveconf -nP > dovecot.conf
* Usually it does not matter in which file you write the setting. You only need
to be aware that later settings replace earlier ones. If you use the same
section multiple times, the settings are merged together.
* To read the content of a file, for instance for the SSL certificate option,
prefix the filename with a `<`, e.g.:

```[dovecot.conf]
ssl_cert_file = /etc/ssl/certs/imap.pem
```

## Authentication

By default, Dovecot is setup to use system user authentication.
You'll probably be using PAM authentication. See the page [[link,auth_pam]]
for how to configure it.
The above example configures Dovecot to use PAM for system user authentication.
See [[link,auth_pam]] for how to configure it.

A typical configuration with Linux would be to create `/etc/pam.d/dovecot`
which contains:
Expand All @@ -132,8 +125,8 @@ Later when you know Dovecot is working, you can do it differently (see
Run as your own non-root user:

```sh
echo "$USER:{PLAIN}password:$UID:$GID::$HOME" > users
sudo mv users /etc/dovecot/
echo "$USER:{PLAIN}password" > passwd
sudo mv passwd /etc/dovecot/

# If SELinux is enabled:
restorecon -v /etc/dovecot/users
Expand All @@ -144,21 +137,17 @@ wish to use, but don't use any important password here as we'll be
logging in with insecure plaintext authentication until [[link,ssl]]
is configured.

Switch to passwd-file authentication by adding to `dovecot.conf`:
Switch to passwd-file authentication by replacing `passdb pam` in
`dovecot.conf` with `passdb passwd-file`:

```
passdb passwd-file {
default_password_scheme = CRYPT
passwd_file_path = /etc/dovecot/users
}

userdb passwd-file {
passwd_file_path = /etc/dovecot/users
passwd_file_path = /etc/dovecot/passwd
}
```

Verify with `doveconf -n passdb userdb` that the output looks like
above (and there are no other passdbs or userdbs).
Verify with `doveconf -n passdb` that the output looks like
above (and there are no other passdbs and no userdbs).

If you're using something else, see [[link,passdb]] and [[link,userdb]].

Expand Down Expand Up @@ -189,10 +178,10 @@ them than the defaults.

## SSL and Plaintext Authentication

If you intend to use SSL, set [[setting,ssl_cert_file]] and
[[setting,ssl_key_file]] settings. Otherwise set [[setting,ssl,no]].
Configure SSL certificate and private key paths with [[setting,ssl_cert_file]]
and [[setting,ssl_key_file]] settings.

Easiest way to get SSL certificates built is to use Dovecot's
An easy way to build a self-signed test certificate is using Dovecot's
`doc/mkcert.sh` script. For more information see [[link,ssl_configuration]].

By default [[setting,auth_allow_cleartext,no]], which means that Dovecot
Expand Down
2 changes: 1 addition & 1 deletion docs/core/man/doveconf.1.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ configuration in easy human readable output.

**-x**
: Expand configuration variables (e.g. `$ENV:foo`) and show file contents
(from e.g. `ssl_cert = \</etc/ssl/certs/dovecot.pem`).
(from e.g. `ssl_key_password = \</etc/ssl/password.txt`).

*section_name*
: Show only the current configuration of one or more specified sections.
Expand Down