Adding upstream version 3.1.8.upstream/3.1.8upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 176 insertions, 0 deletions

diff --git a/man/corosync_overview.7 b/man/corosync_overview.7
new file mode 100644
index 0000000..fbe52a1
--- /dev/null
+++ b/man/corosync_overview.7
@@ -0,0 +1,176 @@
+.\"/*
+.\" * Copyright (c) 2005 MontaVista Software, Inc.
+.\" * Copyright (c) 2006-2023 Red Hat, Inc.
+.\" *
+.\" * All rights reserved.
+.\" *
+.\" * Author: Steven Dake (sdake@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 the MontaVista Software, 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_OVERVIEW 7 2018-11-13 "corosync Man Page" "Corosync Cluster Engine Programmer's Manual"
+.SH NAME
+corosync_overview \- Corosync overview
+.SH OVERVIEW
+The corosync project's purpose is to implement and support a production quality
+Revised BSD licensed implementation of a high performance low overhead high
+availability development toolkit.
+
+Faults occur for various reasons:
+.PP
+* Application Faults
+.PP
+* Middleware Faults
+.PP
+* Operating System Faults
+.PP
+* Hardware Faults
+
+The major focus of high availability in the past has been to mask hardware
+faults. Faults in other components of the system have gone unsolved until
+Corosync.  Corosync is designed for applications to replicate their state to
+up to 16 processors.  The processors all contain a replica of the application
+state.
+
+The corosync project provides a group message API called CPG.
+The project developers recommend CPG be used for most applications.  The CPG
+service implements a closed group messaging model presenting extended virtual
+synchrony guarantees.
+
+To manage conditions where the process executing the CPG application exchange
+fails, we provide the Simple Availability Manager (sam) to provide simple
+application restart.
+
+.SH QUICKSTART
+The corosync executive must be configured.  In the directory conf in the
+source distribution are several files that must be copied to the /etc/corosync
+directory.  If corosync is packaged by a distro, this may be complete.
+
+The directory contains the file corosync.conf.  Please read the corosync.conf(5)
+man page for details on the configuration options.  The corosync project will
+work out of the box with the default configuration options, although the
+administrator may desire different options.
+
+The corosync executive uses cryptographic techniques to ensure authenticity
+and privacy of the messages.  In order for corosync to be secure and operate,
+a private key must be generated and shared to all processors.
+
+First generate the key on one of the nodes:
+
+.nf
+unix# corosync-keygen
+Corosync Cluster Engine Authentication key generator.
+Gathering 2048 bits for key from /dev/urandom.
+Writing corosync key to /etc/corosync/authkey.
+.fi
+
+After this operation, a private key will be in the file /etc/corosync/authkey.
+This private key must be copied to every processor in the cluster.  If the
+private key isn't the same for every node, those nodes with nonmatching private
+keys will not be able to join the same configuration.
+
+Copy the key to some security transportable storage or use ssh to transmit the
+key from node to node.  Then install the key with the command:
+
+unix#: install -D --group=0 --owner=0 --mode=0400 /path_to_authkey/authkey /etc/corosync/authkey
+
+If a message "Invalid digest" appears from the corosync executive, the keys
+are not consistent between processors.
+
+Finally run the corosync executive.  If corosync is packaged from a distro, it
+may be set to start on system start.  It may also be turned off by default in
+which case the init script for corosync must be enabled.
+
+.SH USING LIBRARIES
+The corosync libraries have header files which must be included in the
+developer's application.  Once the header file is included, the developer can
+reference the corosync interfaces.
+
+The corosync project recommends that distros place include files in
+/usr/include/corosync.
+
+.SH IPv6
+The corosync project supports both IPv4 and IPv6 network addresses.  When using
+knet as the transport each link should have the same IP family, but different links
+can have different families (eg link 0 could be all IPv4, and link 1 all IPv6).
+When using UDP/UDPU the single link should use the same family on all nodes.
+
+To configure a host for IPv6, use the ifconfig program to add interfaces:
+box20: ifconfig eth0 add fec0::1:a800:4ff:fe00:20/64
+box30: ifconfig eth0 add fec0::1:a800:4ff:fe00:30/64
+
+If the /64 is not specified, a route for the IPv6 network will not be configured
+which will cause significant problems.  Make sure a route is available for
+IPv6 traffic.
+
+.SH ARCHITECTURE
+The corosync libraries are a thin IPC interface to the corosync executive.  The
+corosync executive implements the functionality of the corosync APIs for
+distributed computing.
+
+The corosync executive uses the Totem extended virtual synchrony protocol.  The
+advantage to the end user is excellent performance characteristics and a proven
+protocol with excellent reliability.  This protocol connects the processors
+in a configuration together so they may communicate.
+
+.SH SECURITY
+The corosync executive optionally encrypts and signs all messages sent
+over the network. For more details see
+.B crypto_model,
+.B crypto_hash
+and
+.B crypto_cipher
+options in the
+.BR corosync.conf (5).
+
+If membership messages can be captured by intruders, it is possible to execute
+a denial of service attack on the cluster.  In this scenario, the cluster is
+likely already compromised and a DoS attack is the least of the administration's
+worries.
+
+The security in corosync does not offer perfect forward secrecy because the keys
+are reused.  It may be possible for an intruder to determine the shared key by
+capturing packets in an automated fashion.  No such automated attack has
+been published as of yet.  In this scenario, the cluster is likely already
+compromised to allow the long-term capture of transmitted data.
+
+For security reasons, the corosync executive binary should NEVER
+be setuid or setgid in the filesystem.
+
+.SH BUGS
+None that are known.
+
+.SH "SEE ALSO"
+.BR corosync.conf (5),
+.BR corosync-keygen (8),
+.BR corosync_quorumtool (8),
+.BR corosync_cfgtool (8),
+.BR corosync_cpgtool (8),
+.BR corosync_cmaptool (8),
+.BR cpg_overview (3),
+.BR sam_overview (3)
+.PP