SUSE Linux Enterprise High Availability 16.0

Introduction to the CRM Shell

Publication Date: 03 Sep 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.

Requirements:

Access to a cluster node with root privileges or sudo authorization
Passwordless SSH key authentication between the cluster nodes

Revision History: Introduction to the CRM Shell

1 What is the CRM Shell? #

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 #

man crm
crm help overview
https://crmsh.github.io/documentation

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.

Log in either as the root user or as a user with sudo privileges.
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: Starting a subcommand directly
You can also start interactive mode directly at the subcommand level. For example:
```
> sudo crm configure
crm(live)configure# 
```
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)# 
```
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
```
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.
Exit interactive mode:
```
crm(live)configure# quit
```

For more information #

https://crmsh.github.io/man-5.0/#topics.Introduction.Interface

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.

Log in either as the root user or as a user with sudo privileges.
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.
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:

Log in either as the root user or as a user with sudo privileges.
Start crmsh's interactive mode at the configure level:
```
> sudo crm configure
```
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.
Make the changes you want to test.
Save the changes to see their effect on the cluster:
```
crm(test1)configure# commit
```
Switch back to the live CIB:
```
crm(test1)configure# cib use live
```
The prompt changes back to live.

(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

(Optional) You can switch back to the shadow CIB if you need to use it again later:
```
crm(live)configure# cib use test1
```
(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.

Log in either as the root user or as a user with sudo privileges.
Start crmsh's interactive mode at the configure level:
```
> sudo crm configure
```
Make your changes.
Show a diff of the changes to the cluster configuration:
```
crm(live)configure# show changed
```
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
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.

Log in either as the root user or as a user with sudo privileges.
Check the resource's current parameters:
```
> sudo crm configure show RESOURCE
```
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.
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
```

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

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

9 Legal Notice #

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled “GNU Free Documentation License”.

For SUSE trademarks, see https://www.suse.com/company/legal/. All other third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates. Asterisks (*) denote third-party trademarks.

All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors, nor the translators shall be held liable for possible errors or the consequences thereof.