qnetd: Improve dead peer detection

[mirror_corosync-qdevice.git] / man / corosync-qnetd.8

.\"/*
.\" * Copyright (C) 2016-2020 Red Hat, Inc.
.\" *
.\" * All rights reserved.
.\" *
.\" * Author: Jan Friesse <jfriesse@redhat.com>
.\" *
.\" * This software licensed under BSD license, the text of which follows:
.\" *
.\" * Redistribution and use in source and binary forms, with or without
.\" * modification, are permitted provided that the following conditions are met:
.\" *
.\" * - Redistributions of source code must retain the above copyright notice,
.\" *   this list of conditions and the following disclaimer.
.\" * - Redistributions in binary form must reproduce the above copyright notice,
.\" *   this list of conditions and the following disclaimer in the documentation
.\" *   and/or other materials provided with the distribution.
.\" * - Neither the name of Red Hat, Inc. nor the names of its
.\" *   contributors may be used to endorse or promote products derived from this
.\" *   software without specific prior written permission.
.\" *
.\" * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
.\" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
.\" * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
.\" * THE POSSIBILITY OF SUCH DAMAGE.
.\" */
.TH COROSYNC-QNETD 8 2020-11-18
.SH NAME
corosync-qnetd \- QNet daemon
.SH SYNOPSIS
.B "corosync-qnetd [-46dfhv] [-l listen_addr] [-p listen_port] [-s tls]
.B [-c client_cert_required] [-m max_clients] [-S option=value[,option2=value2,...]]"

.SH DESCRIPTION
.B corosync-qnetd
is a daemon running outside of the cluster with the purpose of providing a vote to the
.B corosync-qdevice
model net. It's designed to support multiple clusters and be almost configuration
and state free. New clusters are handled dynamically and no configuration file exists.
It's also able to run as non-root user - which is recommended. Connection between the
.B corosync-qdevice
model net client can be optionally configured with TLS client certificate checking. 
The communication protocol between server and client is designed to be very simple 
and allow backwards compatibility.
.SH OPTIONS
.TP
.B -4
and its counterpart
.B -6
are used to force IPv4 or IPv6 communication. The default is to listen on both address families.
.TP
.B -d
Turn on debug logging. By default the messages sent to syslog are purely operational, this
option sends additional debug messages. For bumping syslog messages priority to info, use the
.B -d
parameter twice.
.TP
.B -f
Do not daemonize, run in the foreground.
.TP
.B -h
Show short help text
.TP
.B -v
Show version and supported communication protocol messages/options.
.TP
.B -l
IP address to listen on. By default the daemon listens on all addresses (wildcard).
.TP
.B -p
TCP port to listen on. Default port is 5403.
.TP
.B -s
Determines if TLS should be used and can be one of
.I on/off/required
(the default is
.I on
).
.I on
means TLS is enabled but the client is not required to start TLS,
.I off
means TLS is completely disabled, and
.I required
means TLS is required.
.I on
and
.I required
require the NSS database to be properly initialized by running the
.B corosync-qnetd-certutil
command.
.TP
.B -c
can be set to
.I on/off.
This option only makes sense if TLS is enabled. When
.B -c
is
.I on
a client is required to send its client certificate (default).
.TP
.B -m
Maximum simultaneous clients. The default is 0 which means no limit.
.TP
.B -S
Set advanced settings described in its own section below. This option
shouldn't be generally used because most of the options are
not safe to change.
.SH UNPRIVILEGED USER CONFIGURATION
It's generally recommended to run
.B corosync-qnetd
as a non root user. If you get a package from a distribution its highly
possible that the packager has done all the hard work for you. If the installation 
is performed from source code, a few steps have to be taken.

First it's necessary to create an unprivileged user/group. The following commands
can be used (executed as root):

.nf
# groupadd -r coroqnetd
# useradd -r -g coroqnetd -d / -s /sbin/nologin -c "User for corosync-qnetd" coroqnetd
.fi

The next step is to set the correct owner and group on /etc/corosync/qnetd and /var/run/corosync-qnetd
directories.

.nf
# chown -R coroqnetd:coroqnetd /etc/corosync/qnetd /var/run/corosync-qnetd
.fi

Some systems have the /var/run directory on a tmpfs file system which gets discarded after
a reboot. The solution is to use an initscript or systemd unit, because both of them takes
care of the /var/run/corosync-qnetd creation and sets the correct owner and permissions.

The last step is to make sure
.B corosync-qnetd
is really executed as an unprivileged user. For initscript systems it's enough to set the
line COROSYNC_QNETD_RUNAS in /etc/(sysconfig|default)/corosync-qnetd file. If the file
is not already installed then use the one provided in the corosync source code
(init/corosync-qnetd.sysconfig.example). For systemd, overwrite/copy the
corosync-qnetd.service unit file and uncomment/change the "User=" directive.

.SH TLS CONFIGURATION
For TLS to work its necessary to create the NSS database. If pcs is used then the following
steps are not needed because pcs does them automatically.

.B corosync-qnetd-certutil
is the tool to perform required actions. Just run:

.nf
# corosync-qnetd-certutil -i
.fi

If TLS is not required then simply edit /etc/(sysconfig|default)/corosync-qnetd or
systemd unit file and add the parameter
.B -s
.I off
in the proper place.

Depending on configuration of NSS (stored in nss.config file usually in
/etc/crypto-policies/back-ends/ directory) disabled ciphers or too short keys
may be rejected. Proper solution is to regenerate NSS databases for both
.B corosync-qnetd
and
.B corosync-qdevice
daemons. As a quick workaround it's also possible to set environment variable
.I NSS_IGNORE_SYSTEM_POLICY=1
before running
.B corosync-qnetd
daemon.

When NSS is updated it may also be needed to upgrade database into new format. There is no
consensus on recommended way, but following command seems to work just fine (if qnetd
sysconfdir is set to /etc)

.nf
# certutil -N -d /etc/corosync/qnetd/nssdb -f /etc/corosync/qnetd/nssdb/pwdfile.txt
.fi

.SH ADVANCED SETTINGS
Set by the
.B -S
option. The default value is shown in parentheses.
.TP
.B listen_backlog
Parameter passed to the listen syscall on the network socket. (10)
.TP
.B max_client_send_buffers
Maximum number of send buffers for one client. (32)
.TP
.B max_client_send_size
Maximum size of one send buffer (message) to be sent to a client. (32768)
.TP
.B max_client_receive_size
Maximum size of the receive buffer for a client message (maximum
allowed message size received by client). (32768)
.TP
.B nss_db_dir
NSS database directory. (/etc/corosync/qnetd/nssdb)
.TP
.B cert_nickname
NSS nickname of qnetd server certificate. (QNetd Cert)
.TP
.B heartbeat_interval_min
Minimum heartbeat timeout accepted by server in ms. (1000)
.TP
.B heartbeat_interval_max
Maximum heartbeat timeout accepted by server in ms. (120000)
.TP
.B dpd_enabled
Dead peer detection enabled. (on)
.TP
.B dpd_interval_coefficient
Value is multiplied with heartbeat interval sent by qdevice client and used as a timeout
for dead peer detection. (1.5)
.TP
.B lock_file
Lock file location. (/var/run/corosync-qnetd/corosync-qnetd.pid)
.TP
.B local_socket_file
Internal IPC socket file location. (/var/run/corosync-qnetd/corosync-qnetd.sock)
.TP
.B local_socket_backlog
Parameter passed to listen syscall on the local socket. (10)
.TP
.B ipc_max_clients
Maximum allowed simultaneous IPC clients. (10)
.TP
.B ipc_max_receive_size
Maximum size of a message received by IPC client. (4096)
.TP
.B ipc_max_send_size
Maximum size of a message sent to an IPC client. (10485760)
.TP
.B keep_active_partition_tie_breaker
When tie happens prefer partition with members of previously active (quorate) partition.
This is hard-coded behavior of LMS algorithm so this setting affects only FFSplit algorithm. (off)
.SH SEE ALSO
.BR corosync-qnetd-tool (8)
.BR corosync-qnetd-certutil (8)
.BR corosync-qdevice (8)
.SH AUTHOR
Jan Friesse
.PP