This is a draft document that was built and uploaded automatically. It may document beta software and be incomplete or even incorrect. Use this document at your own risk.

Jump to content
Introduction to the CRM Shell
SUSE Linux Enterprise High Availability 16.0

Introduction to the CRM Shell

Publication Date: 16 Oct 2026

The CRM Shell (crmsh) is a command-line interface for installing, configuring and managing SUSE Linux Enterprise High Availability clusters. It simplifies complex cluster operations by providing a more readable line-based syntax for interacting with Pacemaker's XML configuration format. This article introduces some of the CRM Shell's basic concepts and usage.

Prerequisites

  • Access to a cluster node with root privileges or sudo authorization

  • Passwordless SSH key authentication between the cluster nodes

1 What is the CRM Shell?

The CRM Shell (crmsh) is a command-line interface for installing, configuring and managing SUSE Linux Enterprise High Availability clusters. It simplifies complex cluster operations by providing a more readable line-based syntax for interacting with Pacemaker's XML configuration format.

The top level of the CRM Shell is the crm command. The crm command includes multiple subcommands to manage resources, CIBs, nodes, resource agents, and others. It also has a thorough help system with embedded examples. You can run most crm commands from any node in the cluster.

CRM Shell events are logged to /var/log/crmsh/crmsh.log.

1.1 Using the CRM Shell

You can use the CRM Shell in multiple ways:

Command line (single-shot)

Run a single crm command in full, including a subcommand and parameters. Tab completion is supported. For example, crm config→| completes the word, and crm configure→|→| lists the available subcommands.

Interactive mode

The CRM Shell's interactive mode is a dedicated, internal command shell that allows you to run multiple commands without needing to repeatedly type the crm prefix. You can also move down a level to a subcommand, such as crm configure, to run multiple commands at the same level. Changes you make in interactive mode are only applied to the live cluster after you commit them, which can be useful when configuring resources that are dependent on one another and require constraints. Interactive mode also supports tab completion.

Shell scripts

You can create CRM Shell scripts to group multiple crmsh subcommands in a single file, making it easier to rerun them later. A shell script can only contain crm subcommands. Any other commands are not allowed.

1.2 User privileges

Managing a cluster requires sufficient privileges. The following users can run the crm command and its subcommands:

  • The root user or a user with sudo privileges. These users have full privileges for crmsh operations such as crm cluster init and crm report. They can also make changes to the CIB, such as adding resources and constraints.

  • The CRM owner user. This is typically the user hacluster, which is created by default if you install the cluster with crm cluster init. This user can make changes to the CIB but has limited privileges for operations that use SSH, such as crm report.

1.3 SSH key authentication

For operations that use SSH, the cluster uses passwordless SSH access for communication between the nodes. If you install the cluster with crm cluster init, the script checks for SSH keys and generates them if they don't already exist. If you install the cluster manually, you must configure the SSH keys yourself.

In most cases, the root or sudo user's SSH keys must exist (or be generated) on the node. Alternatively, a sudo user's SSH keys can exist on a local machine and be passed to the node via SSH agent forwarding. This can be useful if you need to avoid storing SSH keys on the nodes.

1.4 For more information

2 Help commands

The crm command has multiple options for showing help text:

  • Show the usage of crm and its command-line options:

    > sudo crm --help
  • List the conceptual help topics:

    > sudo crm help topics
  • List all the available subcommands:

    > sudo crm help
  • Show the help text for a subcommand. For example:

    > sudo crm configure help
  • Show the syntax, usage, and examples for a command within a subcommand. For example:

    > sudo crm configure help group

    This command also has the same result:

    > sudo crm help configure group

Unlike the --help option, the help subcommand opens a text viewer. The text viewer allows you to scroll up or down and read the output more comfortably. To leave the text viewer, press the Q key.

3 Status commands

The crm command has multiple options for showing information about the cluster:

  • Show the status of the cluster services:

    > sudo crm cluster status
  • Show the status of the cluster, including a summary of the cluster details, a list and status of all the nodes, and a list and status of all the resources:

    > sudo crm status
  • Show the status of the cluster, but with the resources listed under the nodes they're currently running on:

    > sudo crm status bynode
  • Show the status of the cluster, but expanded to also list the primitive resources that are included in resource groups and clone sets:

    > sudo crm status detail
  • Show the status of the cluster, a summary of the resource operations on each node, and the migration threshold of each resource:

    > sudo crm status ops
  • Show the status of the cluster with more information, such as details about the resource operations and a list of inactive resources:

    > sudo crm status full
  • Show additional options:

    > sudo crm help status

If the output is longer than the terminal window, these commands open a text viewer. The text viewer allows you to scroll up or down and read the output more comfortably. To leave the text viewer, press the Q key.

4 Using interactive mode

The CRM Shell's interactive mode is a dedicated, internal command shell that allows you to run multiple commands without needing to repeatedly type the crm prefix. You can also move down a level to a subcommand, such as crm configure, to run multiple commands at the same level. Changes you make in interactive mode are only applied to the live cluster after you commit them, which can be useful when configuring resources that are dependent on one another and require constraints. Interactive mode also supports tab completion.

  1. Log in either as the root user or as a user with sudo privileges.

  2. Start interactive mode:

    > sudo crm

    The prompt changes to crm(live/HOSTNAME)#. However, for better readability we omit the host name in our documentation:

    crm(live)#
    Tip
    Tip: Starting a subcommand directly

    You can also start interactive mode directly at the subcommand level. For example:

    > sudo crm configure
    crm(live)configure# 
  3. You can navigate interactive mode with the following options:

    • List the available subcommands:

      crm(live)# ls
    • Enter the name of a subcommand to switch to that level. For example:

      crm(live)# resource
      crm(live)resource#
    • Switch between subcommands with cd. For example:

      crm(live)resource# cd ../node
      crm(live)node#
    • Go back one level with up or cd:

      crm(live)node# up
      crm(live)# 
  4. Make your changes. This example shows commands for configuring a virtual IP address and adding a location constraint to keep the IP address running on a node named alice. Because both commands are under the crm configure subcommand, you can switch to the configure level to shorten the actual commands you need to type.

    Example 1: Adding a virtual IP address with a location constraint for node alice
    crm(live)# configure
    crm(live)configure# primitive vip1 IPaddr2 params ip=192.168.1.5
    crm(live)configure# location loc-vip1-on-alice vip1 inf: alice
    crm(live)configure# show changed
  5. Commit your changes to apply them to the live cluster:

    crm(live)configure# commit

    You must commit your changes before you exit interactive mode, switch back to the crm level, or switch to another subcommand. The changes will be lost if you don't commit them, but the CRM Shell will warn you before this happens.

  6. Exit interactive mode:

    crm(live)configure# quit

5 Using shell scripts

You can create CRM Shell scripts to group multiple crmsh subcommands in a single file, making it easier to rerun them later. A shell script can only contain crm subcommands. Any other commands are not allowed.

  1. Log in either as the root user or as a user with sudo privileges.

  2. Create a file and add the crm subcommands you want to run together. For example, the commands in this file print the status of the cluster and a list of all nodes:

    # A small example file with some crm subcommands
    status
    node show

    Any line starting with the hash symbol (#) is a comment and is ignored.

    If a line is too long, add a backslash (\) at the end and continue in the next line. We recommend indenting lines belonging to a certain subcommand to improve readability.

  3. Run the script:

    > sudo crm -f SCRIPT

    For example, this CRM Shell script is named example.cli:

    > sudo crm -f example.cli

6 Testing cluster changes with a shadow CIB

A shadow CIB, or shadow configuration, is a copy of the live cluster configuration. Changes to a shadow CIB have no effect on the live cluster's resources. You can use a shadow CIB to test different configuration scenarios. You can also create multiple shadow CIBs and test them one by one to see the effects of different changes.

This example procedure shows the process for creating and using a shadow CIB:

  1. Log in either as the root user or as a user with sudo privileges.

  2. Start crmsh's interactive mode at the configure level:

    > sudo crm configure
  3. Create a new shadow CIB:

    crm(live)configure# cib new test1
    INFO: configure.cib.new: test1 shadow CIB created
    crm(test1)configure#

    The prompt changes from live to the name of the shadow CIB. If you don't specify a name, the temporary name @tmp@ is used instead.

  4. Make the changes you want to test.

  5. Save the changes to see their effect on the cluster:

    crm(test1)configure# commit
  6. Switch back to the live CIB:

    crm(test1)configure# cib use live

    The prompt changes back to live.

  7. (Optional) To apply the changes from the shadow CIB to the live CIB, run the following command:

    crm(live)configure# cib commit test1
    INFO: configure.cib.commit: committed 'test1' shadow CIB to the cluster
  8. (Optional) You can switch back to the shadow CIB if you need to use it again later:

    crm(live)configure# cib use test1
  9. (Optional) To undo the changes in the shadow CIB, or to update the shadow CIB to match the latest live CIB, run the following command:

    crm(test1)configure# cib reset test1
    INFO: configure.cib.reset: copied live CIB to test1
For more information
  • crm help shadows

  • crm help cib

7 Reviewing cluster changes before committing

When you make changes to the cluster configuration in crmsh's interactive mode, the changes only apply to the live cluster after you commit them. This procedure shows how to review your changes before you commit them to the live cluster.

  1. Log in either as the root user or as a user with sudo privileges.

  2. Start crmsh's interactive mode at the configure level:

    > sudo crm configure
  3. Make your changes.

  4. Show a diff of the changes to the cluster configuration:

    crm(live)configure# show changed
  5. Show a projection of the changes to the cluster status:

    crm(live)configure# ptest

    This command displays the following information:

    • The current cluster status

    • A summary of the actions the cluster will take after the changes are committed

    • The projected cluster status after the changes are committed

  6. If you're happy with the changes, commit the new configuration:

    crm(live)configure# commit

    Alternatively, you can discard the changes before committing them by exiting interactive mode with quit.

For more information
  • crm configure help ptest

8 Managing sensitive parameters

By default, the CRM Shell obscures passwords in the output of commands like crm configure show. To further obscure sensitive values in the raw CIB data, you can use the crm resource secret command. This command replaces a resource parameter's value with a special string that points to a separate file containing the actual value. The file is not encrypted, but only the root user has permission to read or modify it. This helps to prevent accidental data exposure.

  1. Log in either as the root user or as a user with sudo privileges.

  2. Check the resource's current parameters:

    > sudo crm configure show RESOURCE
  3. Hide the value of a sensitive parameter:

    • To hide the value of an existing parameter, use the stash command:

      > sudo crm resource secret RESOURCE stash PARAMETER

      For example:

      > sudo crm resource secret mydb stash passwd
    • To add a new parameter, use the set command:

      > sudo crm resource secret RESOURCE set PARAMETER VALUE

      For example:

      > sudo crm resource secret mydb set passwd linux

    Both of these commands move the value of the sensitive parameter to a separate file under the /var/lib/ directory. The file is not encrypted, but only the root user has permission to read or modify it.

  4. The cluster automatically synchronizes the change across the other nodes. However, if any nodes are unavailable, you might see the following output:

    Node bob is down - you'll need to update it with `cibsecret sync` later

    When the node is available again, or if you add a new node to the cluster, you must manually synchronize the change:

    > sudo cibsecret sync
  5. You can view the hidden value with the following command:

    > sudo crm resource secret RESOURCE show PARAMETER

    For example:

    > sudo crm resource secret mydb show passwd
For more information
  • crm resource help secret

  • cibsecret --help

Tip

crm resource secret is the crm front end for Pacemaker's cibsecret command.

HA glossary

ACL (access control list)

Access control lists can be used to limit or fine-tune a user's access to the CIB. An ACL consists of an ordered set of access rules. Each rule allows or denies read or write access to a part of the CIB. Rules can be combined into specific roles, and users can be assigned to a role that matches their tasks.

active/active, active/passive

How resources run on the nodes. Active/passive means that resources only run on the active node, but can move to the passive node if the active node fails. Active/active means that all nodes are active at once, and resources can run on (and move to) any node in the cluster.

arbitrator

An arbitrator is a machine running outside the cluster to provide an additional instance for cluster calculations. For example, QNetd provides a vote to help QDevice participate in quorum decisions.

CIB (cluster information base)

An XML representation of the whole cluster configuration and status (cluster options, nodes, resources, constraints, etc.). The CIB manager (pacemaker-based) keeps the CIB synchronized across the cluster nodes and handles requests to modify it.

clone

In the context of a cluster resource, a clone is a resource that can be active on multiple nodes. Any resource can be cloned if its resource agent supports it.

cluster

A high-availability cluster is a group of servers (physical or virtual) designed primarily to secure the highest possible availability of data, applications and services. Not to be confused with a high-performance cluster, which shares the application load to achieve faster results.

Cluster LVM (Cluster logical volume manager)

The term Cluster LVM indicates that LVM is being used in a cluster environment. This requires configuration adjustments to protect the LVM metadata on shared storage.

cluster offline upgrade

If a new product version includes major changes that are backward incompatible, the cluster requires a cluster offline upgrade. You must stop the cluster services on all nodes and upgrade the whole cluster before bringing the nodes back online.

For minor version upgrades, see cluster rolling upgrade.

cluster partition

A cluster partition occurs when communication fails between one or more nodes and the rest of the cluster. The nodes are split into partitions but are still active. They can only communicate with nodes in the same partition and are unaware of the separated nodes. This is known as a split brain scenario.

cluster rolling upgrade

In a cluster rolling upgrade, one cluster node at a time is upgraded while the rest of the cluster is still running. Stop the cluster services on a node, upgrade it, then bring it back online to join the cluster. Continue one by one until all cluster nodes are upgraded.

For major version upgrades, see cluster offline upgrade.

cluster services

The services that run the cluster. Typically this refers to Pacemaker and Corosync, but might also include SBD and QDevice if those services are used.

cluster stack

The ensemble of software technologies and components that make up a cluster.

colocation constraint

A type of resource constraint that specifies which resources can or cannot run together on a node.

concurrency violation

A resource that should be running on only one node in the cluster is running on several nodes.

Corosync

Corosync provides reliable messaging, membership and quorum information about the cluster. This is handled by the Corosync Cluster Engine, a group communication system.

CRM (cluster resource manager)

The management entity responsible for coordinating all non-local interactions in a High Availability cluster. SUSE Linux Enterprise High Availability uses Pacemaker as the CRM. It interacts with several components: local executors on its own node and on the other nodes, non-local CRMs, administrative commands, the fencing functionality, and the membership layer.

crmsh (CRM Shell)

The command-line utility crmsh manages the cluster, nodes and resources.

Csync2

A synchronization tool for replicating configuration files across all nodes in the cluster.

DC (designated coordinator)

The pacemaker-controld daemon is the cluster controller, which coordinates all actions. This daemon has an instance on each cluster node, but only one instance is elected to act as the DC. The DC is elected when the cluster services start, or if the current DC fails or leaves the cluster. The DC decides whether a cluster-wide change must be performed, such as fencing a node or moving resources.

disaster

An unexpected interruption of critical infrastructure caused by nature, humans, hardware failure, or software bugs.

disaster recovery

The process by which a function is restored to the normal, steady state after a disaster.

Disaster Recovery Plan

A strategy to recover from a disaster with the minimum impact on IT infrastructure.

DLM (Distributed Lock Manager)

DLM coordinates accesses to shared resources in a cluster, for example, managing file locking in clustered file systems to increase performance and availability.

DRBD

DRBD® is a block device designed for building High Availability clusters. It replicates data on a primary device to secondary devices in a way that ensures all copies of the data remain identical.

existing cluster

The term existing cluster is used to refer to any cluster that consists of at least one node. An existing cluster has a basic Corosync configuration that defines the communication channels, but does not necessarily have resource configuration yet.

failover

Occurs when a resource or node fails on one machine and the affected resources move to another node.

failover domain

A named subset of cluster nodes that are eligible to run a resource if a node fails.

fencing

Prevents access to a shared resource by isolated or failing cluster members. There are two classes of fencing: resource-level fencing and node-level fencing. Resource-level fencing ensures exclusive access to a resource. Node-level fencing prevents a failed node from accessing shared resources and prevents resources from running on a node with an uncertain status. This is usually done by resetting or powering off the node.

GFS2

Global File System 2 (GFS2) is a shared disk file system for Linux computer clusters. GFS2 allows all nodes to have direct concurrent access to the same shared block storage. GFS2 has no disconnected operating mode, and no client or server roles. All nodes in a GFS2 cluster function as peers. GFS2 supports up to 32 cluster nodes. Using GFS2 in a cluster requires hardware to allow access to the shared storage, and a lock manager to control access to the storage.

group

Resource groups contain multiple resources that need to be located together, started sequentially and stopped in the reverse order.

Hawk (HA Web Konsole)

A user-friendly Web-based interface for monitoring and administering a High Availability cluster from Linux or non-Linux machines. Hawk can be accessed from any machine that can connect to the cluster nodes, using a graphical Web browser.

heuristics

QDevice supports using a set of commands (heuristics) that run locally on start-up of cluster services, cluster membership change, successful connection to the QNetd server, or optionally at regular times. The result is used in calculations to determine which partition should have quorum.

knet (kronosnet)

A network abstraction layer supporting redundancy, security, fault tolerance, and fast fail-over of network links. In SUSE Linux Enterprise High Availability 16, knet is the default transport protocol for the Corosync communication channels.

local cluster

A single cluster in one location (for example, all nodes are located in one data center). Network latency is minimal. Storage is typically accessed synchronously by all nodes.

local executor

The local executor is located between Pacemaker and the resources on each node. Through the pacemaker-execd daemon, Pacemaker can start, stop and monitor resources.

location

In the context of a whole cluster, location can refer to the physical location of nodes (for example, all nodes might be located in the same data center). In the context of a location constraint, location refers to the nodes on which a resource can or cannot run.

location constraint

A type of resource constraint that defines the nodes on which a resource can or cannot run.

meta attribute

Parameters that tell the CRM (cluster resource manager) how to treat a specific resource. For example, you might define a resource's priority or target role.

metro cluster

A single cluster that can stretch over multiple buildings or data centers, with all sites connected by Fibre Channel. Network latency is usually low. Storage is frequently replicated using mirroring or synchronous replication.

network device bonding

Network device bonding combines two or more network interfaces into a single bonded device to increase bandwidth and/or provide redundancy. When using Corosync, the bonded device is not managed by the cluster software. Therefore, the bonded device must be configured on every cluster node that might need to access it.

node

Any server (physical or virtual) that is a member of a cluster.

order constraint

A type of resource constraint that defines the sequence of actions.

Pacemaker

Pacemaker is the CRM (cluster resource manager) in SUSE Linux Enterprise High Availability, or the “brain” that reacts to events occurring in the cluster. Events might be nodes that join or leave the cluster, failure of resources, or scheduled activities such as maintenance, for example. The pacemakerd daemon launches and monitors all other related daemons.

parameters (instance attributes)

Parameters determine which instance of a service the resource controls.

primitive

A primitive resource is the most basic type of cluster resource.

promotable clone

Promotable clones are a special type of clone resource that can be promoted. Active instances of these resources are divided into two states: promoted and unpromoted (also known as “active and passive” or “primary and secondary”).

QDevice

QDevice and QNetd participate in quorum decisions. The corosync-qdevice daemon runs on each cluster node and communicates with QNetd to provide a configurable number of votes, allowing a cluster to sustain more node failures than the standard quorum rules allow.

QNetd

QNetd is an arbitrator that runs outside the cluster. The corosync-qnetd daemon provides a vote to the corosync-qdevice daemon on each node to help it participate in quorum decisions.

quorum

A cluster partition is defined to have quorum (be quorate) if it has the majority of nodes (or “votes”). Quorum distinguishes exactly one partition. This is part of the algorithm to prevent several disconnected partitions or nodes (“split brain”) from proceeding and causing data and service corruption. Quorum is a prerequisite for fencing, which then ensures that quorum is unique.

RA (resource agent)

A script acting as a proxy to manage a resource (for example, to start, stop or monitor a resource). SUSE Linux Enterprise High Availability supports different kinds of resource agents.

ReaR (Relax and Recover)

An administrator tool set for creating disaster recovery images.

resource

Any type of service or application that is known to Pacemaker, for example, an IP address, a file system, or a database. The term resource is also used for DRBD, where it names a set of block devices that use a common connection for replication.

resource constraint

Resource constraints specify which cluster nodes a resource can run on, what order the resources should start in, and which other resources a specific resource is dependent on.

See also colocation constraint, location constraint and order constraint.

resource set

As an alternative format for defining location, colocation or order constraints, you can use resource sets, where primitives are grouped together in one set. When creating a constraint, you can specify multiple resources for the constraint to apply to.

resource template

To help create many resources with similar configurations, you can define a resource template. After being defined, it can be referenced in primitives or in certain types of constraints. If a template is referenced in a primitive, the primitive inherits all operations, instance attributes (parameters), meta attributes and utilization attributes defined in the template.

SBD (STONITH Block Device)

SBD provides a node fencing mechanism through the exchange of messages via shared block storage. Alternatively, it can be used in diskless mode. In either case, it needs a hardware or software watchdog on each node to ensure that misbehaving nodes are really stopped.

scheduler

The scheduler is implemented as pacemaker-schedulerd. When a cluster transition is needed, pacemaker-schedulerd calculates the expected next state of the cluster and determines what actions need to be scheduled to achieve the next state.

split brain

A scenario in which the cluster nodes are divided into two or more groups that do not know about each other (either through a software or hardware failure). STONITH prevents a split-brain scenario from badly affecting the entire cluster. Also known as a partitioned cluster scenario.

The term split brain is also used in DRBD but means that the nodes contain different data.

SPOF (single point of failure)

Any component of a cluster that, if it fails, triggers the failure of the entire cluster.

stickiness

Resource stickiness is a meta attribute that determines how much a resource prefers to stay on its current node.

STONITH

Another term for the fencing mechanism that shuts down a misbehaving node to prevent it from causing trouble in a cluster. In a Pacemaker cluster, node fencing is managed by the fencing subsystem pacemaker-fenced.

switchover

The planned moving of resources to other nodes in a cluster. See also failover.

utilization

Tells the CRM what capacity a certain resource requires from a node.

watchdog

SBD (STONITH Block Device) needs a watchdog on each node to ensure that misbehaving nodes are really stopped. SBD “feeds” the watchdog by regularly writing a service pulse to it. If SBD stops feeding the watchdog, the hardware enforces a system restart. This protects against failures of the SBD process itself, such as becoming stuck on an I/O error.