Using the efm utility ===================== Failover Manager provides the ``efm`` utility to assist with cluster management. The RPM installer adds the utility to the ``/usr/edb/efm-5./bin`` directory when you install Failover Manager. efm allow-node -------------- ``efm allow-node
`` Invoke the ``efm allow-node`` command to allow the specified node to join the cluster. When invoking the command, provide the name of the cluster and the IP address of the joining node. This command must be invoked by efm, a member of the efm group, or root. efm disallow-node ----------------- ``efm disallow-node
`` Invoke the ``efm disallow-node`` command to remove the specified node from the allowed hosts list and prevent the node from joining a cluster. Provide the name of the cluster and the address of the node when calling the ``efm disallow-node`` command. This command must be invoked by efm, a member of the efm group, or root. .. Note:: If you removed the node from the cluster and aren't planning to add it again, you can use the :ref:`efm reset-members ` command instead. efm cluster-status ------------------ ``efm cluster-status `` Invoke the ``efm cluster-status`` command to display the status of a Failover Manager cluster. For more information about the status report, see :ref:`Monitoring a Failover Manager cluster ` . efm cluster-status-json ----------------------- ``efm cluster-status-json `` Invoke the ``efm cluster-status-json`` command to display the status of a Failover Manager cluster in JSON format. While the format of the displayed information is different from the display generated by the ``efm cluster-status`` command, the information source is the same. The following example is generated by querying the status of a healthy cluster with three nodes: .. code:: text { "nodes": { "172.16.144.176": { "type": "Witness", "db": "N\/A", "vip": "", "vip_active": false }, "172.16.144.177": { "type": "Primary", "db": "UP", "vip": "", "vip_active : false" "lsnReceive : 0/14001478" "lsn : 0/14001478" "lsnInfo :" }, "172.16.144.180": { "type": "Standby", "db": "UP", "vip": "", "vip_active : false" "lsnReceive : 0/14001478" "lsn : 0/14001478" "lsnInfo :" } }, "allowednodes": [ "172.16.144.177", "172.16.144.160", "172.16.144.180", "172.16.144.176" ], "membershipcoordinator": "172.16.144.177", "failoverpriority": [ "172.16.144.180" ], "minimumstandbys": 0, "missingnodes": [], "messages": [] } efm create-standby ------------------ !!!Note Important information for version 5.0 only: If this command is run on a standby node (the local database is running and is being monitored), you must restart the agent after the command completes. There is a known issue that the agent can be left in an incorrect internal state. If this node is later promoted to primary and the database fails, there may not be a failover due to this state. This does not affect “Idle” nodes (where either the local database is not running or is not being monitored). It has been fixed in the 5.1 release. ``efm create-standby [-prompt] [-slot ] [-waldir ]`` Invoke the ``efm create-standby`` command to create a new standby database on this node. The local agent must be running and there must be a primary agent in the cluster. The command process will: - Connect to local agent to find the current primary database. - Stop the local database and have the local agent become idle (if needed). - Read the current ``synchronous_standby_names`` configuration setting. - If a ``slot`` parameter was specified, contact the primary database to drop a slot with that name if it exists and use create a new slot with this name for the standby to use. - Remove the local data directory. If a ``waldir`` parameter was specified, the current write-ahead log directory will also be removed. - Run ``pg_basebackup`` to create the standby database, using pg_basebackup’s ``--waldir`` parameter if needed. - Set the ``synchronous_standby_names`` configuration setting if needed. - Start the standby database and resume monitoring. If the ``-prompt`` option is specified, the command will output the steps it will take, including the generated ``pg_basebackup`` command, before proceeding. The following agent properties are used: - ``db.service.owner`` specifies the user running the ``pg_basebackup`` command. - ``sudo.user.command`` specifies how the command is run as the above user. - ``db.bin`` specifies the location of ``pg_basebackup`` . - ``db.data.dir`` specifies the target directory. - ``db.port`` specifies the port used to access the primary database. - ``application.name`` specifies the ``application_name`` to use (if set). !!!Note This command was introduced in Failover Manager 5.0. In 5.0 only, the command requires superuser privileges to run. The following example shows the command output when both the ``-prompt`` and ``-slot`` options are specified: .. code:: text # /usr/edb/efm-5.2/bin/efm create-standby efm -slot s2 -prompt Found primary node1 from cluster status. Verify primary address node1 does not match this agents bind address node2 or external address . Will signal local agent to run database stop command and become idle if not already. Will connect to primary on node1 to drop slot s2 if it exists. Will remove the /opt/postgres/data/pg_wal and /opt/postgres/data directories, and run pg_basebackup using the following parameters: - R -D /opt/postgres/data -X stream -S s2 -C ...with connection string: host=node1 port=5432 application_name=node2 Will set synchronous_standby_names to: any 2 ("node1", "node3", "node4") Do you want to continue? [y/N]:y Signalling local agent to stop db and become idle if needed. Replication slot s2 does not exist on primary node1. Removing directories/files and running pg_basebackup. Starting database. Waiting briefly for database to finish startup. Attempting to resume local efm agent monitoring. Resume command successful on local agent. efm encrypt ----------- ``efm encrypt [--from-env]`` Invoke the ``efm encrypt`` command to encrypt the database password before including the password in the cluster properties file. Include the ``--from-env`` option to instruct Failover Manager to use the value specified in the ``EFMPASS`` environment variable and execute without user input. For more information, see :ref:`Encrypting your database password ` . efm promote ----------- ``efm promote cluster_name [-switchover [-sourcenode
][-quiet][-noscripts]`` The ``efm promote`` command instructs Failover Manager to perform a manual failover of standby to primary. Attempt a manual promotion only during a maintenance window for your database cluster and if the status command reports that all standbys in the cluster are up to date with the primary. Include the ``–switchover`` clause to promote a standby node and reconfigure a primary node as a standby node. Include the ``-sourcenode`` keyword, and specify a node address to indicate the node whose recovery settings to copy to the old primary node, which makes it a standby. Include the ``-quiet`` keyword to suppress notifications during the switchover process. Include the ``-noscripts`` keyword to instruct Failover Manager not to invoke fencing or post-promotion scripts. This command must be invoked by efm, a member of the efm group, or root. .. Note:: This command instructs the service to ignore the value specified in the `auto.failover` parameter in the cluster properties file. efm reset-members ----------------- ``efm reset-members `` Invoke the ``efm reset-members`` command to remove cached node addresses from a Failover Manager cluster. Run this command after a node is permanently removed from the cluster to prevent the cluster from trying to connect to the removed node’s address. This will also remove ``DOWN`` nodes after they have failed or have been disconnected from this cluster. Running this command does the following on each node in the cluster: 1. Resets the addresses in the ``.nodes`` file to the current cluster members. This occurs even if the ``stable.nodes.file`` property is set to ``true`` . 2. Updates the Allowed Node host list to include only the current members. 3. Disconnects all agents from each other briefly and then reconnects. Running databases aren’t affected by this operation. After the operation completes, you might need to update the standby priority list. See the :ref:`efm set-priority ` command for more information. efm resume ---------- ``efm resume `` Invoke the ``efm resume`` command to resume monitoring a previously stopped database. This command must be invoked by efm, a member of the efm group, or root. efm set-priority ---------------- ``efm set-priority
`` Invoke the ``efm set-priority`` command to assign a failover priority to a standby node. The value specifies the order in which to use the node in the event of a failover. This command must be invoked by efm, a member of the efm group, or root. Use the priority option to specify the place for the node in the priority list. For example, specify a value of ``1`` to indicate that the node is the primary standby and will be the first node promoted in the event of a failover. A priority value of ``0`` instructs Failover Manager not to promote the standby. efm stop-cluster ---------------- ``efm stop-cluster `` Invoke the ``efm stop-cluster`` command to stop Failover Manager on all nodes. This command instructs Failover Manager to connect to each node on the cluster and instruct the existing members to shut down. The command has no effect on running databases, but when the command completes, there’s no failover protection in place. .. Note:: When you invoke the `efm stop-cluster` command, all authorized node information is removed from the Allowed Node host list. This command must be invoked by efm, a member of the efm group, or root. efm upgrade-conf ---------------- ``efm upgrade-conf [-source ]`` Invoke the ``efm upgrade-conf`` command to copy the configuration files from an existing Failover Manager installation and add parameters required by a Failover Manager installation. Provide the name of the previous cluster when invoking the utility. This command must be invoked with superuser privileges if you’re running Failover Manager in the default mode. For information on the optional ``-source`` flag, or if you’re upgrading from a Failover Manager configuration that doesn’t use sudo, see :ref:`Upgrading Failover Manager in Eager Failover mode ` . efm node-status-json -------------------- ``efm node-status-json `` Invoke the ``efm node-status-json`` command to display the status of a local node in JSON format. A successful execution of this command returns ``0`` as its exit code. In case of a database failure or an agent status becoming IDLE, the command returns ``1`` as exit code. The following is an example output of the ``efm node-status-json`` command: .. code:: text { "type":"Standby", "address":"172.16.144.130", "db":"UP", "vip":"", "vip_active":"false" } efm –help --------- ``efm --help`` Invoke the ``efm --help`` command to display online help for the Failover Manager utility commands.