diff --git a/man/corosync-qdevice-net-certutil.8 b/man/corosync-qdevice-net-certutil.8 index 4cdda110..e689945d 100644 --- a/man/corosync-qdevice-net-certutil.8 +++ b/man/corosync-qdevice-net-certutil.8 @@ -1,84 +1,85 @@ .\"/* .\" * Copyright (C) 2016 Red Hat, Inc. .\" * .\" * All rights reserved. .\" * .\" * Author: Jan Friesse .\" * .\" * 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-QDEVICE-NET-CERTUTIL 8 2016-06-28 .SH NAME corosync-qdevice-net-certutil - tool to generate qdevice model net TLS certificates .SH SYNOPSIS .B "corosync-qdevice-net-certutil [-i|-m|-M|-r|-s|-Q] [-c certificate] [-n cluster_name]" .SH DESCRIPTION .B corosync-qdevice-net-certutil -is frontend for NSS certutil used for generating client certificate for net model of +is a frontend for NSS certutil used for generating client certificate for the net model of qdevice. .SH OPTIONS .TP .B -i -Initialize QDevice Net NSS certificate database. -Default directory with database is /etc/corosync/qdevice/net/. This directory -has to be writable by current user. It needs QNetd CA certificate passed as +Initialize the QDevice Net NSS certificate database. +The default directory for the database is /etc/corosync/qdevice/net/. This directory +has to be writable by the current user. It needs the QNetd CA certificate passed as the .B -c -parameter. Certificate can be found on server running QNetd in file +parameter. This certificate can be found on the server running QNetd in the file /etc/corosync/qnetd/nssdb/qnetd-cacert.crt. .TP .B -m -Import cluster certificate and key from pk12 file. +Import the cluster certificate and key from a pk12 file. .TP .B -r -Generate certificate request. Certificate request is exported into -/etc/corosync/qdevice/net/qdevice-net-node.crq file. It's required to -pass cluster name +Generate a certificate request. The certificate request is exported into +/etc/corosync/qdevice/net/qdevice-net-node.crq. It is necessary to +pass the cluster name using the .B -n -parameter. Cluster name has to match one defined in /etc/corosync/corosync.conf. +parameter. The cluster name has to match the one defined in /etc/corosync/corosync.conf. .TP .B -M -Import signed certificate and export certificate with private key into +Import a signed certificate and export a certificate with private key into pk12 file. .TP .B -Q Use ssh/scp to properly set both .B corosync-qnetd and .B corosync-qdevice -certificates on all nodes. It's highly recommended to use ssh agent, -otherwise ssh/scp will keep you asking for password roughly 8 times number of nodes. +certificates on all nodes. It's highly recommended that you use an ssh agent, +or ssh/scp will keep asking for a password - roughly 8 times the number of nodes. +.TP .B -c File with certificate to load. .TP .B -n Name of the cluster. .SH SEE ALSO .BR corosync-qnetd (8) .BR corosync-qdevice (8) .SH AUTHOR Jan Friesse .PP diff --git a/man/corosync-qdevice-tool.8 b/man/corosync-qdevice-tool.8 index 07786e8e..998e6f0a 100644 --- a/man/corosync-qdevice-tool.8 +++ b/man/corosync-qdevice-tool.8 @@ -1,126 +1,125 @@ .\"/* .\" * Copyright (C) 2016 Red Hat, Inc. .\" * .\" * All rights reserved. .\" * .\" * Author: Jan Friesse .\" * .\" * 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-QDEVICE-TOOL 8 2016-06-24 .SH NAME corosync-qdevice-tool \- corosync-qdevice control interface. .SH SYNOPSIS .B "corosync-qdevice-tool [-Hhsv] [-p qdevice_ipc_socket_path]" .SH DESCRIPTION .B corosync-qdevice-tool -is frontend to internal corosync-qdevice IPC. It's main purpose is to show important -information about current -.B corosync-qdevice -internal state. +is a frontend to the internal corosync-qdevice IPC. Its main purpose is to show important +information about the current internal state of +.B corosync-qdevice. .SH OPTIONS .TP .B -H -Properly shutdown +Properly shutdown the .B corosync-qdevice process .TP .B -h -Display short usage +Display a short usage text .TP .B -s -Display status of +Display the status of the .B corosync-qdevice -process. Output is described in it's own section. +process. The output is described in its own section below. .TP .B -v -Display more verbose output for +Display more verbose output for the .B -s option. .TP .B -p -Path to +Path to the .B corosync-qdevice communication socket. .SH STATUS COMMAND OUTPUT .nf Qdevice information ------------------- Model: Net Node ID: 1 HB interval: 10000ms Sync HB interval: 30000ms Configured node list: 0 Node ID = 1 Ring ID: 1.a00000000021b48 Membership node list: 1 Quorate: Yes Quorum node list: 0 Node ID = 1, State = member Expected votes: 2 Last poll call: 2016-06-24T17:05:20 (cast vote) Qdevice-net information ---------------------- Cluster name: Cluster QNetd host: localhost:5403 Connect timeout: 8000ms HB interval: 8000ms VQ vote timer interval: 5000ms TLS: Supported Algorithm: Fifty-Fifty split Tie-breaker: Node with lowest node ID Poll timer running: Yes (cast vote) State: Connected TLS active: Yes (client certificate sent) Connected since: 2016-06-24T17:02:35 Echo reply received: 2016-06-24T17:05:15 .fi -Output is split into generic qdevice section and model specific section. -Most of the items are just taken from corosync.conf file. It's good to note +The output is split into a generic qdevice section and a model specific section. +Most of the items are just taken from corosync.conf file. It's helpful to note that the .I Membership node list -what is list of nodes in same membership with current node and +is the membership list of the current node and should match the quorum node list. .I Last poll call -what is timestamp (iso format) of last call of votequorum_qdevice_poll +is the timestamp (in iso format) of the last call to the votequorum_qdevice_poll function. -For model net, it's good to note +For model net, it's good to check the .I Poll timer running -item. Internally, model net supports 3 states. Not voting (then +state. Internally, model net supports 3 states. Not voting (when .I Poll timer running -is No and it means +is No it means that the .B corosync-qnetd -algorithm decides that current node shouldn't get vote), -voting but not cast vote and voting with cast vote. +algorithm decides that the current node shouldn't get a vote), +voting (without cast vote) and voting (with cast vote). .SH SEE ALSO .BR corosync-qnetd (8) .BR corosync-qdevice (8) .SH AUTHOR Jan Friesse .PP diff --git a/man/corosync-qdevice.8 b/man/corosync-qdevice.8 index 6d89051e..0827c5ea 100644 --- a/man/corosync-qdevice.8 +++ b/man/corosync-qdevice.8 @@ -1,317 +1,317 @@ .\"/* .\" * Copyright (C) 2016 Red Hat, Inc. .\" * .\" * All rights reserved. .\" * .\" * Author: Jan Friesse .\" * .\" * 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-QDEVICE 8 2016-06-29 .SH NAME corosync-qdevice \- QDevice daemon .SH SYNOPSIS .B "corosync-qdevice [-dfh] [-S option=value[,option2=value2,...]]" .SH DESCRIPTION .B corosync-qdevice -is daemon running on each node of of cluster and being able to provide configured -number of votes to -quorum subsystem based on third-party arbiter decision. It's primary use -is to allow sustain more node failures than standard quorum would allow. It's -recommended for even-node clusters and very recommended for 2 node cluster. +is a daemon running on each node of a cluster. It provides a configured +number of votes to the +quorum subsystem based on a third-party arbitrator's decision. Its primary use +is to allow a cluster to sustain more node failures than standard quorum rules allow. +It is recommended for clusters with an even number of nodes and highly recommended +for 2 node clusters. .SH OPTIONS .TP .B -d -Forcefully turn on debug information without need to change corosync.conf. +Forcefully turn on debug information without the need to change corosync.conf. .TP .B -f -Do not daemonize and run on foreground. +Do not daemonize, run in the foreground. .TP .B -h -Show short help +Show short help text .TP .B -S -Set advanced settings described in it's own section. This option +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 CONFIGURATION .B corosync-qdevice -reads it's configuration from corosync.conf file. +reads its configuration from corosync.conf file. -Main configuration is within +The main configuration is within .B quorum.device -subdirective. Each model also has it's own configuration within -equally named subdirective. +sub-key. Each model also has its own configuration within a +similarly named sub-key. .TP .B model -Specifies model to be used. This parameter is required. +Specifies the model to be used. This parameter is required. .B corosync-qdevice -is modular and it's able to support multiple different models. Model basically -defines what type of arbiter is used. Currently only +is modular and is able to support multiple different models. The model basically +defines what type of arbitrator is used. Currently only .I net is supported. .TP .B timeout Specifies how often should .B corosync-qdevice -call votequorum_poll function. It's also used by net model to adjust -hearbeat timeout. It's usually not recommended to change this value. +should call the votequorum_poll function. It is also used by the net model to adjust +its hearbeat timeout. It is recommended that you don't change this value. Default is 10000. .TP .B sync_timeout -Specifies how often should +Specifies how often .B corosync-qdevice -call votequorum_poll function during sync phase. It's usually not recommended to change this value. +should call the votequorum_poll function during a sync phase. It is recommended that you don't change this value. Default is 30000. +.TP .B votes -Number of votes provided to cluster by qdevice. Default is (number_of_nodes - 1) or generally -sum(votes per node) - 1. +The number of votes provided to the cluster by qdevice. Default is (number_of_nodes - 1) or generally +sum(votes_per_node) - 1. .PP -Within .B quorum.device.net -subdirective is configuration for model net. +holds the configuration for model 'net'. .TP .B tls Can be one of .I on, off or required -values and specifies if tls should be used. +and specifies if tls should be used. .I on -value means connection should be tried with TLS but it's not fatal -error if server doesn't advertise TLS support and then non tls is used. +means a connection with TLS is attempted first, but if the server doesn't advertise TLS support +then non-TLS will be used. .I off -is used when TLS is not required and it's then not even tried. This is also -only one mode which doesn't need properly initialized NSS database. +is used then TLS is not required and it's then not even tried. This mode is the +only one which doesn't need a properly initialized NSS database. .I required -means TLS is absolutelly required and if server doesn't support TLS, qdevice -exits with error message. Default is on. +means TLS is required and if the server doesn't support TLS, qdevice will +exit with error message. Default is on. .TP .B host -Specifies IP address or host name of qnetd server to be used. This parameter +Specifies the IP address or host name of the qnetd server to be used. This parameter is required. .TP .B port Specifies TCP port of qnetd server. Default is 5403. .TP .B algorithm Decision algorithm. Can be one of the .I ffsplit or -.I lms -values (actually there are also +.I lms. +(actually there are also .I test and .I 2nodelms -, both of them mainly for developers and shouldn't be generally used). Description of -what algorithm means and how algorithms differs is in it's own section. +, both of which are mainly for developers and shouldn't be used for production clusters). For a +description of what each algorithm means and how the algorithms differ see their individual sections. Default value is ffsplit. .TP .B tie-breaker can be one of -.I lowest -, +.I lowest, .I highest -or valid_node_id (number) values. It's used as a fallback if qdevice has to solve two -exactly same quality partitions. +or valid_node_id (number) values. It's used as a fallback if qdevice has to decide between two or more +equal partitions. .I lowest -means partition with lowest node id is choosen. +means the partition with the lowest node id is chosen. .I highest -means partition with highest node is choosen. And valid_node_id means partition -where node with given node id is member is choosen. +means the partition with highest node id is chosen. And valid_node_id means that the partition +containing the node with the given node id is chosen. .TP .B connect_timeout Timeout when .B corosync-qdevice is trying to connect to .B corosync-qnetd host. Default is 0.8 * quorum.sync_timeout. .TP .B force_ip_version can be one of .I 0|4|6 -and allows forcing using given IP version. +and forces the software to use the given IP version. .I 0 -(default value) means IPv6 is prefered and IPv4 should be used as fallback. +(default value) means IPv6 is prefered and IPv4 should be used as a fallback. .PP -Logging configuration is within +Logging configuration is within the .B logging directive. .B corosync-qdevice -parses and supports most of the options with exception to -.B to_logfile -, +parses and supports most of the options with exception of +.B to_logfile, .B logfile and .B logfile_priority. +The .B logger_subsys sub-directive can be also used if .B subsys is set to QDEVICE. .PP For .B corosync-qdevice -to work correctly, +to work correctly, the .B nodelist -directive has to be used and properly configured. Also net model require +directive has to be used and properly configured. Also the net model requires that .B totem.cluster_name -option to be set. +option is set. .SH MODEL NET TLS CONFIGURATION -For model net to make TLS work it's required to create NSS database, import Qnetd -CA certificate, and get/distribute valid client certificate. +For model net to work using TLS, it's necessary to create the NSS database, import Qnetd +CA certificate, and get/distribute a valid client certificate. -If pcs is used following steps are not needed because pcs does them automatically. +If pcs is used (recommended) the following steps are not needed because pcs does them automatically. .B corosync-qdevice-net-certutil -is tool to perform required actions semi-automatically. Please consult help output of -it and its man page. For first time configuration it may make sense to start with +is the tool to perform required actions semi-automatically. Please consult the help output of +it and its man page. For a first time configuration it may make sense to start with the .B -Q option. If TLS is not required just edit corosync.conf file and set .B quorum.device.net.tls to -.I off -value. +.I off. .SH MODEL NET ALGORITHMS -Algorithm is used to change behavior of how +Algorithms are used to change behavior of how .B corosync-qnetd -provides vote to given node/partition. Currently there are two algorithms supported. +provides votes to a given node/partition. Currently there are two algorithms supported. .TP .B ffsplit -Make sense only for clusters with even number of nodes. It provides exactly one -vote to partition with higher number of active nodes. If there are two exactly same partitions, -it provides it's vote to partition where more clients are connected to qnetd -server. If also this number equals, tie-breaker is used. It's able to transition -it's vote if currently active partition partitioned and non-active partition -still has at least 50% of active nodes. Because of this, vote is not provided -if qnetd connection is not active. +This one makes sense only for clusters with even number of nodes. It provides exactly one +vote to the partition with the highest number of active nodes. If there are two exactly similar partitions, +it provides its vote to the partition that has the most clients connected to the qnetd +server. If this number is also equal, then the tie-breaker is used. It is able to transition +its vote if the currently active partition becomes partitioned and a non-active partition +still has at least 50% of the active nodes. Because of this, a vote is not provided +if the qnetd connection is not active. -For use this algorithm it's required to set number of votes per node to 1 (default) -and qdevice number of votes has to be also 1. This is achieved by setting +To use this algorithm it's required to set the number of votes per node to 1 (default) +and the qdevice number of votes has to be also 1. This is achieved by setting .B quorum.device.votes key in corosync.conf file to 1. .TP .B lms Last-man-standing. If the node is the only one left in the cluster that can see the qnetd server then we return a vote. If more than one node can see the qnetd server but some nodes can't -see each other then we divide the cluster up into 'partitions' based on -their ring_id and return a vote to nodes in the partition that contains -a nominated nodeid. (lowest, highest, etc). For LMS to work, number +see each other then the cluster is divided up into 'partitions' based on +their ring_id and this algorithm returns a vote to the largest active partition or, +if there is more than 1 equal partiton, the partition that contains the tie_breaker +node (lowest, highest, etc). For LMS to work, the number of qdevice votes has to be set to default (so just delete .B quorum.device.votes key from corosync.conf). .SH ADVANCED SETTINGS Set by using .B -S -option. At the end of description in braces is default value. Options +option. The default value is shown in parentheses) Options beginning with .B net_ prefix are specific to model net. .TP .B lock_file Lock file location. (/var/run/corosync-qdevice/corosync-qdevice.pid) .TP .B local_socket_file Internal IPC socket file location. (/var/run/corosync-qdevice/corosync-qdevice.sock) .TP .B local_socket_backlog Parameter passed to listen syscall. (10) .TP .B max_cs_try_again -How many times retry to call corosync function which returned CS_ERR_TRY_AGAIN. (10) +How many times to retry the call to a corosync function which has returned CS_ERR_TRY_AGAIN. (10) .TP .B votequorum_device_name -Name used for qdevice register. (Qdevice) +Name used for qdevice registration. (Qdevice) .TP .B ipc_max_clients Maximum allowed simultaneous IPC clients. (10) .TP .B ipc_max_receive_size -Maximum size of message received by IPC client. (4096) +Maximum size of a message received by IPC client. (4096) .TP .B ipc_max_send_size -Maximum size of message allowed to send to IPC client. (65536) +Maximum size of a message allowed to be sent to an IPC client. (65536) .TP .B master_wins Force enable/disable master wins. (default is model) .TP .B net_nss_db_dir NSS database directory. (/etc/corosync/qdevice/net/nssdb) .TP .B net_initial_msg_receive_size Initial (used during connection parameters negotiation) -maximum size of receive buffer for message (maximum +maximum size of the receive buffer for message (maximum allowed message size received from qnetd). (32768) .TP .B net_initial_msg_send_size -Initial (used during connection parameters negotiation) -maximum size of one send buffer (message) to be send to server. (32768) +Initial (used during connection parameter negotiation) +maximum size of one send buffer (message) to be sent to server. (32768) .TP .B net_min_msg_send_size -Minimum required size of one send buffer (message) to be send to server. (32768) +Minimum required size of one send buffer (message) to be sent to server. (32768) .TP .B net_max_msg_receive_size -Maximum allowed size of receive buffer for message sent by server. (16777216) +Maximum allowed size of receive buffer for a message sent by server. (16777216) .TP .B net_max_send_buffers Maximum number of send buffers. (10) .TP .B net_nss_qnetd_cn Canonical name of qnetd server certificate. (Qnetd Server) .TP .B net_nss_client_cert_nickname NSS nickname of qdevice client certificate. (Cluster Cert) .TP .B net_heartbeat_interval_min -Minimal heartbeat timeout accepted by client in ms. (1000) +Minimum heartbeat timeout accepted by client in ms. (1000) .TP .B net_heartbeat_interval_max -Maximal heartbeat timeout accepted by client in ms. (120000) +Maximum heartbeat timeout accepted by client in ms. (120000) .TP .B net_min_connect_timeout -Minimal connection timeout accepted by client in ms. (1000) +Minimum connection timeout accepted by client in ms. (1000) .TP .B net_max_connect_timeout -Maximal connection timeout accepted by client in ms. (120000) +Maximum connection timeout accepted by client in ms. (120000) .TP .B net_test_algorithm_enabled Enable test algorithm. (if built with --enable-debug on, otherwise off) .SH SEE ALSO .BR corosync-qdevice-tool (8) .BR corosync-qdevice-certutil (8) .BR corosync-qnetd (8) .BR corosync.conf (5) .SH AUTHOR Jan Friesse .PP diff --git a/man/corosync-qnetd-certutil.8 b/man/corosync-qnetd-certutil.8 index 878f53bb..d55ac28a 100644 --- a/man/corosync-qnetd-certutil.8 +++ b/man/corosync-qnetd-certutil.8 @@ -1,73 +1,73 @@ .\"/* .\" * Copyright (C) 2016 Red Hat, Inc. .\" * .\" * All rights reserved. .\" * .\" * Author: Jan Friesse .\" * .\" * 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-CERTUTIL 8 2016-06-28 .SH NAME corosync-qnetd-certutil - tool to generate qnetd TLS certificates .SH SYNOPSIS .B "corosync-qnetd-certutil [-i|-s] [-c certificate] [-n cluster_name]" .SH DESCRIPTION .B corosync-qnetd-certutil -is frontend for NSS certutil used for generating QNetd CA, server certificate and -signing cluster certificate used by +is a frontend for the NSS certutil, it is used for generating the QNetd CA (Certificate Authority), +server certificate and signing cluster certificate used by .B corosync-qdevice -model net. +when using the model 'net'. .SH OPTIONS .TP .B -i -Initialize QNetd NSS certificate database and generate QNetd CA and server certificate. -Default directory with database is /etc/corosync/qnetd. This directory has to be -writable by current user. QNetd CA certificate is also exported into file +Initialize the QNetd NSS certificate database and generate the QNetd CA and server certificates. +The default directory for the database is /etc/corosync/qnetd. This directory must be +writeable by the current user. The QNetd CA certificate is also exported into the file /etc/corosync/qnetd/nssdb/qnetd-cacert.crt. .TP .B -s -Sign cluster certificate. It's required to pass name of cluster (equal to -one configured in corosync.conf) and certificate request file. Signed certificate is -stored into file /etc/corosync/qnetd/nssdb/cluster-$ClusterName.crt +Sign the cluster certificate. It is necessary to pass the cluster name (as +configured in corosync.conf) and the certificate request file - see options below. +The signed certificate will be written to the +file /etc/corosync/qnetd/nssdb/cluster-$ClusterName.crt .TP .B -c Certificate request file to sign. .TP .B -n Name of the cluster. .SH NOTES -If qnetd is executed by non root user, /etc/corosync/qnetd and it's subdirectories has to have -set owner (and/or group) to given user. If +If qnetd is executed by a non root user, /etc/corosync/qnetd and its subdirectories must be owned by (or have group access for) the given user. If .B corosync-qnetd-certutil -is executed as root it tries to copy owner and group of /etc/corosync/qnetd to all its created files. +is executed as root it tries to copy the owner and group of /etc/corosync/qnetd to all of the created files. .SH SEE ALSO .BR corosync-qnetd (8) .BR corosync-qdevice (8) .SH AUTHOR Jan Friesse .PP diff --git a/man/corosync-qnetd-tool.8 b/man/corosync-qnetd-tool.8 index a4ab6665..81fb5161 100644 --- a/man/corosync-qnetd-tool.8 +++ b/man/corosync-qnetd-tool.8 @@ -1,129 +1,128 @@ .\"/* .\" * Copyright (C) 2016 Red Hat, Inc. .\" * .\" * All rights reserved. .\" * .\" * Author: Jan Friesse .\" * .\" * 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-TOOL 8 2016-06-23 .SH NAME corosync-qnetd-tool \- corosync-qnetd control interface. .SH SYNOPSIS .B "corosync-qnetd-tool [-Hhlsv] [-c cluster_name] [-p qnetd_ipc_socket_path]" .SH DESCRIPTION .B corosync-qnetd-tool -is frontend to internal corosync-qnetd IPC. It's main purpose is to show important -information about current -.B corosync-qnetd -internal state. +is a frontend to the internal corosync-qnetd IPC. Its main purpose is to show important +information about the current internal state of +.B corosync-qnetd. .SH OPTIONS .TP .B -H -Properly shutdown +Properly shutdown the .B corosync-qnetd process .TP .B -h -Display short usage +Display a short usage text .TP .B -l -List all clients connected to +List all clients connected to the .B corosync-qnetd -process. Output is described in it's own section. +process. The output is described in its own section below. .TP .B -s -Display status of +Display status of the .B corosync-qnetd process. .TP .B -v Display more verbose output for options .B -l and .B -s .TP .B -c -Used only with +Used only with the .B -l -option. By default, information about all clients from all clusters are displayed, with -this option it's possible to filter only to one cluster with given +option. By default, information about all clients from all clusters is displayed, with +this option it's possible to filter information from a single cluster given the .I cluster_name. .TP .B -p -Path to +Path to the .B corosync-qnetd communication socket. .SH LIST COMMAND OUTPUT .nf Cluster "Cluster": Algorithm: Fifty-Fifty split Tie-breaker: Node with lowest node ID Node ID 1: Client address: ::ffff:127.0.0.1:52000 HB interval: 8000ms Configured node list: 1, 2 Ring ID: 1.a00000000021b40 Membership node list: 1, 2 TLS active: Yes (client certificate verified) Vote: No change (ACK) ... .fi -Output contains list of clusters. Each cluster has cluster common options +The output contains a list of clusters. Each cluster has the cluster common options .I Algorithm and .I Tie-breaker -both configured in corosync.conf file. Information about nodes follows. +as configured in the corosync.conf file. Information about nodes follows. .I Client address -is IP address and port of client. +is the IP address and port of the client. .I HB interval -is heartbeat interval between +is the heartbeat interval between .B corosync-qnetd and .B corosync-qdevice client. This option can be configured in corosync.conf. .I Configured node list -is list of nodes configured in corosync.conf. +is the list of nodes configured in corosync.conf. .I Ring ID and .I Membership node list -are self-explaining. +are self-explanatory. .I TLS active -describes if encrypted transport is used between server and client. +describes if an encrypted transport is used between server and client. .I Vote is last vote sent to .B corosync-qdevice -client. Last ACK/NACK vote (if exists) is in parentheses. +client. The last ACK/NACK vote (if it exists) is in parentheses. .SH SEE ALSO .BR corosync-qnetd (8) .BR corosync-qdevice (8) .SH AUTHOR Jan Friesse .PP diff --git a/man/corosync-qnetd.8 b/man/corosync-qnetd.8 index 06d46db1..856e6e18 100644 --- a/man/corosync-qnetd.8 +++ b/man/corosync-qnetd.8 @@ -1,228 +1,227 @@ .\"/* .\" * Copyright (C) 2016 Red Hat, Inc. .\" * .\" * All rights reserved. .\" * .\" * Author: Jan Friesse .\" * .\" * 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 2016-06-29 .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 daemon running outside of cluster and being able to provide vote to +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 (recommended) run as non root user. Connection between +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 TLS with client certificate checking. Communication -protocol between server and client is designed to be very simple and allow backward -compatibility. +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 it's counterpart +and its counterpart .B -6 -are used to force to use only IPv4 or IPv6. Default is to listen on both addresses. +are used to force IPv4 or IPv6 communication. The default is to listen on both address families. .TP .B -d -Turn on debug information. By default priority of messages forwarded into syslog -is not bumped so for most of deployments debug messages are simply thrown. To bump -up priority use +Turn on debug logging. By default the messages sent to syslog are purely operational, this +option sends additional debug messages. For even more detail use the .B -d parameter twice. .TP .B -f -Do not daemonize and run on foreground. +Do not daemonize, run in the foreground. .TP .B -h -Show short help +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 daemon listen on any address (wildcard). +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 -values (default is +(the default is .I on ). .I on -means TLS is enabled but client is not required to start TLS, +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 -requires NSS database to be properly initialized by running a +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 -value. Option make sense only if TLS is enabled. When +.I on/off. +This option only makes sense if TLS is enabled. When .B -c is .I on -client is required to send it's client certificate (default). +a client is required to send its client certificate (default). .TP .B -m -Maximum simultaneous clients. Default is 0 what means no limit. +Maximum simultaneous clients. The default is 0 which means no limit. .TP .B -S -Set advanced settings described in it's own section. This option +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 be running +It's generally recommended to run .B corosync-qnetd -as non root user. If you get package from distribution it's highly -possible packager made hard work for you. If installation is performed -from source code, few steps has to be taken. +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 needed to create unprivileged user/group. Following commands -can be used (execute as root): +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 -Next step is to set correct owner to /etc/corosync/qnetd and /var/run/corosync-qnetd +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 has /var/run directory on tmpfs file system which gets discarded after -reboot. Solution is to use initscript which takes care of /var/run/corosync-qnetd -creating and set correct owner and permissions or for systems with systemd, it's possible -to use tmpfile.d configuration file (installed by default if systemd is enabled during +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 which takes care of the /var/run/corosync-qnetd +creation and sets the correct owner and permissions. For systems with systemd it's possible +to use a tmpfile.d configuration file (installed by default if systemd is enabled during corosync compilation). -Last step is to make sure +The last step is to make sure .B corosync-qnetd -is really executed as unpriviliged user. For initscript it's enough to set -line COROSYNC_QNETD_RUNAS in /etc/(sysconfig|default)/corosync-qnetd file. If file -is not already installed, use one provided in corosync source code -(init/corosync-qnetd.sysconfig.example). For systemd overwrite/copy -corosync-qnetd.service unit file and uncomment/change "User=" directive. +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 it's required to create NSS database. If pcs is used following +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 tool to perform required actions automatically. Just execute: +is the tool to perform required actions. Just run: .nf # corosync-qnetd-certutil -i .fi -If TLS is not required just edit /etc/(sysconfig|default)/corosync-qnetd or -systemd unit file and add parameter +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 -proper place. +in the proper place. .SH ADVANCED SETTINGS -Set by using +Set by the .B -S -option. At the end of description in braces is default value. +option. The default value is shown in parantheses. .TP .B listen_backlog -Parameter passed to listen syscall. (10) +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 send to client. (32768) +Maximum size of one send buffer (message) to be sent to a client. (32768) .TP .B max_client_receive_size -Maximum size of receive buffer for client message (maximum +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 -Minimal heartbeat timeout accepted by server in ms. (1000) +Minimum heartbeat timeout accepted by server in ms. (1000) .TP .B heartbeat_interval_max -Maximal heartbeat timeout accepted by server in ms. (120000) +Maximum heartbeat timeout accepted by server in ms. (120000) .TP .B dpd_enabled Dead peer detection enabled. (on) .TP .B dpd_interval -How often DPD algorithm detects dead peers in ms. (10000) +How often the DPD algorithm detects dead peers in ms. (10000) .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. (10) +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 message received by IPC client. (4096) +Maximum size of a message received by IPC client. (4096) .TP .B ipc_max_send_size -Maximum size of message allowed to send to IPC client. (10485760) +Maximum size of a message sent to an IPC client. (10485760) .SH SEE ALSO .BR corosync-qnetd-tool (8) .BR corosync-qnetd-certutil (8) .BR corosync-qdevice (8) .SH AUTHOR Jan Friesse .PP