diff --git a/doc/sphinx/Pacemaker_Administration/configuring.rst b/doc/sphinx/Pacemaker_Administration/configuring.rst index 70ce349d8a..e455229a57 100644 --- a/doc/sphinx/Pacemaker_Administration/configuring.rst +++ b/doc/sphinx/Pacemaker_Administration/configuring.rst @@ -1,260 +1,260 @@ .. index:: single: configuration single: CIB Configuring Pacemaker --------------------- Pacemaker's configuration, the CIB, is stored in XML format. Cluster administrators have multiple options for modifying the configuration either via the XML, or at a more abstract (and easier for humans to understand) level. Pacemaker reacts to configuration changes as soon as they are saved. Pacemaker's command-line tools and most higher-level tools provide the ability to batch changes together and commit them at once, rather than make a series of small changes, which could cause avoid unnecessary actions as Pacemaker responds to each change individually. Pacemaker tracks revisions to the configuration and will reject any update older than the current revision. Thus, it is a good idea to serialize all changes to the configuration. Avoid attempting simultaneous changes, whether on the same node or different nodes, and whether manually or using some automated configuration tool. .. note:: It is not necessary to update the configuration on all cluster nodes. Pacemaker immediately synchronizes changes to all active members of the cluster. To reduce bandwidth, the cluster only broadcasts the incremental updates that result from your changes and uses checksums to ensure that each copy is consistent. Configuration Using Higher-level Tools ###################################### Most users will benefit from using higher-level tools provided by projects separate from Pacemaker. Popular ones include the crm shell and pcs. [#]_ See those projects' documentation for details on how to configure Pacemaker using them. Configuration Using Pacemaker's Command-Line Tools ################################################## Pacemaker provides lower-level, command-line tools to manage the cluster. Most configuration tasks can be performed with these tools, without needing any XML knowledge. To enable STONITH for example, one could run: .. code-block:: none # crm_attribute --name stonith-enabled --update 1 Or, to check whether **node1** is allowed to run resources, there is: .. code-block:: none # crm_standby --query --node node1 Or, to change the failure threshold of **my-test-rsc**, one can use: .. code-block:: none # crm_resource -r my-test-rsc --set-parameter migration-threshold --parameter-value 3 --meta Examples of using these tools for specific cases will be given throughout this document where appropriate. See the man pages for further details. See :ref:`cibadmin` for how to edit the CIB using XML. See :ref:`crm_shadow` for a way to make a series of changes, then commit them all at once to the live cluster. .. index:: single: configuration; CIB properties single: CIB; properties single: CIB property Working with CIB Properties ___________________________ Although these fields can be written to by the user, in most cases the cluster will overwrite any values specified by the user with the "correct" ones. To change the ones that can be specified by the user, for example ``admin_epoch``, one should use: .. code-block:: none # cibadmin --modify --xml-text '' A complete set of CIB properties will look something like this: .. topic:: XML attributes set for a cib element .. code-block:: xml .. index:: single: configuration; cluster options Querying and Setting Cluster Options ____________________________________ Cluster options can be queried and modified using the ``crm_attribute`` tool. To get the current value of ``cluster-delay``, you can run: .. code-block:: none # crm_attribute --query --name cluster-delay which is more simply written as .. code-block:: none # crm_attribute -G -n cluster-delay If a value is found, you'll see a result like this: .. code-block:: none # crm_attribute -G -n cluster-delay scope=crm_config name=cluster-delay value=60s If no value is found, the tool will display an error: .. code-block:: none # crm_attribute -G -n clusta-deway scope=crm_config name=clusta-deway value=(null) Error performing operation: No such device or address To use a different value (for example, 30 seconds), simply run: .. code-block:: none # crm_attribute --name cluster-delay --update 30s To go back to the cluster's default value, you can delete the value, for example: .. code-block:: none # crm_attribute --name cluster-delay --delete Deleted crm_config option: id=cib-bootstrap-options-cluster-delay name=cluster-delay When Options are Listed More Than Once ______________________________________ If you ever see something like the following, it means that the option you're modifying is present more than once. .. topic:: Deleting an option that is listed twice .. code-block:: none # crm_attribute --name batch-limit --delete Please choose from one of the matches below and supply the 'id' with --id Multiple attributes match name=batch-limit in crm_config: Value: 50 (set=cib-bootstrap-options, id=cib-bootstrap-options-batch-limit) Value: 100 (set=custom, id=custom-batch-limit) In such cases, follow the on-screen instructions to perform the requested action. To determine which value is currently being used by the cluster, refer to the "Rules" chapter of *Pacemaker Explained*. .. index:: single: configuration; remote .. _remote_connection: Connecting from a Remote Machine ################################ It is possible to run configuration commands from a machine that is not part of the cluster. For security reasons, this capability is disabled by default. If you wish to allow remote access, set the ``remote-tls-port`` (encrypted) or ``remote-clear-port`` (unencrypted) CIB properties (attributes of the ``cib`` element). Encrypted communication can be performed keyless (which makes it subject to man-in-the-middle attacks), but a better option is to also use TLS certificates. To enable TLS certificates, it is recommended to first set up your own Certificate Authority (CA) and generate a root CA certificate. Then create a public/private key pair and certificate signing request (CSR) for your server. Use the CA to sign this CSR. Then, create a public/private key pair and CSR for each remote system that you wish to have remote access. Use the CA to sign the CSRs. It is recommended to use a unique certificate for each remote system so they can be revoked if necessary. The server's public/private key pair and signed certificate should be installed to the |PCMK_CONFIG_DIR| directory and owned by ``CIB_user``. Remember that private keys should not be readable by anyone other than their owner. Finally, edit the |PCMK_CONFIG_FILE| file to refer to these credentials: .. code-block:: none PCMK_ca_file="/etc/pacemaker/ca.cert.pem" PCMK_cert_file="/etc/pacemaker/server.cert.pem" PCMK_key_file="/etc/pacemaker/server.key.pem" The administrator's machine simply needs Pacemaker installed. To connect to the cluster, set the following environment variables: * :ref:`CIB_port ` (required) * :ref:`CIB_server ` * :ref:`CIB_user ` * :ref:`CIB_passwd ` * :ref:`CIB_encrypted ` Only the Pacemaker daemon user (|CRM_DAEMON_USER|) may be used as ``CIB_user``. To use TLS certificates, the administrator's machine also needs their public/private key pair, signed client certificate, and root CA certificate. Those must additionally be specified with the following environment variables: -* :ref:`CIB_ca_file ` -* :ref:`CIB_cert_file ` -* :ref:`CIB_key_file ` +* :ref:`CIB_ca_file ` +* :ref:`CIB_cert_file ` +* :ref:`CIB_key_file ` As an example, if **node1** is a cluster node, and the CIB is configured with ``remote-tls-port`` set to 1234, the administrator could read the current cluster configuration using the following commands, and would be prompted for the daemon user's password: .. code-block:: none # export CIB_server=node1; export CIB_port=1234; export CIB_encrypted=true # export CIB_ca_file=/etc/pacemaker/ca.cert.pem # export CIB_cert_file=/etc/pacemaker/admin.cert.pem # export CIB_key_file=/etc/pacemaker/admin.key.pem # cibadmin -Q .. note:: Pacemaker must have been built with PAM support for remote access to work. You can check by running ``pacemakerd --features``. If the output contains **pam**, remote access is supported. *(since 3.0.0; before 3.0.0, in a build without PAM support, all remote connections are accepted without any authentication)* .. rubric:: Footnotes .. [#] For a list, see "Configuration Tools" at https://clusterlabs.org/components.html diff --git a/doc/sphinx/Pacemaker_Administration/options.rst b/doc/sphinx/Pacemaker_Administration/options.rst index 731d17f288..4f2b971483 100644 --- a/doc/sphinx/Pacemaker_Administration/options.rst +++ b/doc/sphinx/Pacemaker_Administration/options.rst @@ -1,178 +1,220 @@ .. index:: client options Client Options -------------- Pacemaker uses several environment variables set on the client side. .. note:: Directory and file paths below may differ on your system depending on your Pacemaker build settings. Check your Pacemaker configuration file to find the correct paths. .. list-table:: **Client-side Environment Variables** :class: longtable :widths: 2 4 5 :header-rows: 1 * - Environment Variable - Default - Description * - .. _CIB_encrypted: .. index:: single: CIB_encrypted single: environment variable; CIB_encrypted CIB_encrypted - true - Whether to encrypt network traffic. Used with :ref:`CIB_port ` for connecting to a remote CIB instance; ignored if :ref:`CIB_port ` is not set. * - .. _CIB_file: .. index:: single: CIB_file single: environment variable; CIB_file CIB_file - - If set, CIB connections are created against the named XML file. Clients read an input CIB from, and write the result CIB to, the named file. Ignored if :ref:`CIB_shadow ` is set. * - .. _CIB_passwd: .. index:: single: CIB_passwd single: environment variable; CIB_passwd CIB_passwd - - :ref:`$CIB_user `'s password. Read from the command line if unset. Used with :ref:`CIB_port ` for connecting to a remote CIB instance; ignored if :ref:`CIB_port ` is not set. * - .. _CIB_port: .. index:: single: CIB_port single: environment variable; CIB_port CIB_port - - If set, CIB connections are created as clients to a remote CIB instance on :ref:`$CIB_server ` via this port. Ignored if :ref:`CIB_shadow ` or :ref:`CIB_file ` is set. * - .. _CIB_server: .. index:: single: CIB_server single: environment variable; CIB_server CIB_server - localhost - The host to connect to. Used with :ref:`CIB_port ` for connecting to a remote CIB instance; ignored if :ref:`CIB_port ` is not set. + * - .. _CIB_ca_file: + + .. index:: + single: CIB_ca_file + single: environment variable; CIB_ca_file + + CIB_ca_file + - + - If this, :ref:`CIB_cert_file `, and + :ref:`CIB_key_file ` are set, remote CIB administration + will be encrypted using X.509 (SSL/TLS) certificates, with this root + certificate for the certificate authority. Used with :ref:`CIB_port + ` for connecting to a remote CIB instance; ignored if + :ref:`CIB_port ` is not set. + * - .. _CIB_cert_file: + + .. index:: + single: CIB_cert_file + single: environment variable; CIB_cert_file + + CIB_cert_file + - + - If this, :ref:`CIB_ca_file `, and + :ref:`CIB_key_file ` are set, remote CIB administration + will be encrypted using X.509 (SSL/TLS) certificates, with this + certificate for the local host. Used with :ref:`CIB_port ` for + connecting to a remote CIB instance; ignored if + :ref:`CIB_port ` is not set. + * - .. _CIB_key_file: + + .. index:: + single: CIB_key_file + single: environment variable; CIB_key_file + + CIB_key_file + - + - If this, :ref:`CIB_ca_file `, and + :ref:`CIB_cert_file ` are set, remote CIB administration + will be encrypted using X.509 (SSL/TLS) certificates, with this + private key for the local host. Used with :ref:`CIB_port ` for + connecting to a remote CIB instance; ignored if + :ref:`CIB_port ` is not set. * - .. _CIB_shadow: .. index:: single: CIB_shadow single: environment variable; CIB_shadow CIB_shadow - - If set, CIB connections are created against a temporary working ("shadow") CIB file called ``shadow.$CIB_shadow`` in :ref:`$CIB_shadow_dir `. Should be set only to the name of a shadow CIB created by :ref:`crm_shadow `. Otherwise, behavior is undefined. * - .. _CIB_shadow_dir: .. index:: single: CIB_shadow_dir single: environment variable; CIB_shadow_dir CIB_shadow_dir - |CRM_CONFIG_DIR| if the current user is ``root`` or |CRM_DAEMON_USER|; otherwise ``$HOME/.cib`` if :ref:`$HOME ` is set; otherwise ``$TMPDIR/.cib`` if :ref:`$TMPDIR ` is set to an absolute path; otherwise ``/tmp/.cib`` - If set, shadow files are created in this directory. Ignored if :ref:`CIB_shadow ` is not set. * - .. _CIB_user: .. index:: single: CIB_user single: environment variable; CIB_user CIB_user - |CRM_DAEMON_USER| if used with :ref:`CIB_port `, or the current effective user otherwise - If used with :ref:`CIB_port `, connect to :ref:`$CIB_server ` as this user. Must be part of the |CRM_DAEMON_GROUP| group on :ref:`$CIB_server `. Otherwise (without :ref:`CIB_port `), this is used only for ACL and display purposes. * - .. _EDITOR: .. index:: single: EDITOR single: environment variable; EDITOR EDITOR - - Text editor to use for editing shadow files. Required for the ``--edit`` command of :ref:`crm_shadow `. * - .. _HOME: .. index:: single: HOME single: environment variable; HOME HOME - Current user's home directory as configured in the passwd database, if an entry exists - Used to create a default :ref:`CIB_shadow_dir ` for non- privileged users. * - .. _PE_fail: .. index:: single: PE_fail single: environment variable; PE_fail PE_fail - 0 - Advanced use only: A dummy graph action with action ID matching this option will be marked as failed. Primarily for developer use with scheduler simulations. * - .. _PS1: .. index:: single: PS1 single: environment variable; PS1 PS1 - - The shell's primary prompt string. Used by :ref:`crm_shadow `: set to indicate that the user is in an interactive shadow CIB session, and checked to determine whether the user is already in an interactive session before creating a new one. * - .. _SHELL: .. index:: single: SHELL single: environment variable; SHELL SHELL - - Absolute path to a shell. Used by :ref:`crm_shadow ` when launching an interactive session. * - .. _TMPDIR: .. index:: single: TMPDIR single: environment variable; TMPDIR TMPDIR - /tmp - Directory for temporary files. If not an absolute path, the default is used instead.