diff --git a/DC-HA-crmsh-introduction b/DC-HA-crmsh-introduction
new file mode 100644
index 000000000..446b15a8d
--- /dev/null
+++ b/DC-HA-crmsh-introduction
@@ -0,0 +1,15 @@
+MAIN="ha-crmsh-introduction.asm.xml"
+SRC_DIR="articles"
+IMG_SRC_DIR="images"
+
+## Profiling
+PROFOS="sleha"
+#PROFCONDITION="PRODUCTNUMBER"
+# Use the STRUCTID if there are several structures in one assembly file
+#STRUCTID="STRUCTURE-ID"
+#PROFARCH="x86_64;zseries;power;aarch64"
+
+DOCBOOK5_RNG_URI="urn:x-suse:rng:v2:geekodoc-flat"
+
+STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns"
+FALLBACK_STYLEROOT="/usr/share/xml/docbook/stylesheet/suse-ns"
diff --git a/articles/ha-crmsh-introduction.asm.xml b/articles/ha-crmsh-introduction.asm.xml
new file mode 100644
index 000000000..73c5358d9
--- /dev/null
+++ b/articles/ha-crmsh-introduction.asm.xml
@@ -0,0 +1,137 @@
+
+
+ %entities;
+]>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Legal Notice
+
+
+ GNU Free Documentation License
+
+
+
+
+
+
+ Introduction to the &crmshell;
+
+ 2026-07-10
+
+
+ Initial version
+
+
+
+
+
+
+ &x86-64;
+ &power;
+ &zseries;
+
+
+ &productname;
+
+ Introduction to the &crmshell;
+ How to install, configure and manage &ha; clusters using the &crmshell; command-line interface
+ Manage &ha; clusters with the &crmshell;
+
+ Administration
+
+
+ Administration
+ Clustering
+ High Availability
+
+ Products & Solutions
+
+
+ https://bugzilla.suse.com/enter_bug.cgi
+ Documentation
+ SUSE Linux Enterprise High Availability &productnumber;
+ tahlia.richardson@suse.com
+
+ yes
+
+
+
+ The &crmshell; (&crmsh;) is a command-line interface for installing, configuring and
+ managing &sleha; clusters. It simplifies complex cluster operations by providing a more
+ readable line-based syntax for interacting with &pace;'s XML configuration format.
+ This article introduces some of the &crmshell;'s basic concepts and usage.
+
+ Requirements:
+
+ Access to a cluster node with &rootuser; privileges or &sudo; authorization
+ Passwordless SSH key authentication between the cluster nodes
+
+
+
+
+
+
+ Help commands
+
+
+
+
+ Status commands
+
+
+
+
+ Using interactive mode
+
+
+
+
+ Using shell scripts
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/concepts/ha-crmsh-what-is.xml b/concepts/ha-crmsh-what-is.xml
new file mode 100644
index 000000000..7b17918b1
--- /dev/null
+++ b/concepts/ha-crmsh-what-is.xml
@@ -0,0 +1,133 @@
+
+
+ %entities;
+]>
+
+
+
+
+
+ What is the &crmshell;?
+
+
+
+ The &crmshell; (&crmsh;) is a command-line interface for installing, configuring and
+ managing &sleha; clusters. It simplifies complex cluster operations by providing a more
+ readable line-based syntax for interacting with &pace;'s XML configuration format.
+
+
+ The top level of the &crmshell; 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.
+
+
+ &crmshell; events are logged to /var/log/crmsh/crmsh.log.
+
+
+
+
+
+ Using the &crmshell;
+
+ You can use the &crmshell; 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
+
+
+
+
+
+ Shell scripts
+
+
+
+
+
+
+
+
+ User privileges
+
+ Managing a cluster requires sufficient privileges. The following users can run the
+ crm command and its subcommands:
+
+
+
+
+ The &rootuser; 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.
+
+
+
+
+
+
+ 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 &rootuser; 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.
+
+
+
+
+ For more information
+
+
+
+ man crm
+
+
+
+
+ crm help overview
+
+
+
+
+
+
+
+
+
+
diff --git a/concepts/ha-what-is.xml b/concepts/ha-what-is.xml
index 258951e5d..e965e5735 100644
--- a/concepts/ha-what-is.xml
+++ b/concepts/ha-what-is.xml
@@ -158,21 +158,21 @@
User-friendly administration tools
- &sleha; includes tools for configuration and administration:
+ &sleha; includes the following tools for configuration and administration:
The &crmshell; (&crmsh;) is a command-line interface for
- installing and setting up &ha; clusters, configuring resources, and performing
- monitoring and administration tasks.
+ installing, configuring and managing &sleha; clusters. You can run most &crmshell;
+ commands from any node in the cluster.
- &hawk; is a Web-based graphical interface for monitoring and
- administration of &ha; clusters. It can be accessed using a Web browser from any
- Linux or non-Linux machine that can connect to the cluster nodes.
+ &hawk; is a Web-based graphical interface for configuring and
+ managing &ha; clusters. You can use &hawk; on any Linux or non-Linux machine with a
+ Web browser and network access to the cluster nodes.
diff --git a/references/ha-crmsh-help-commands.xml b/references/ha-crmsh-help-commands.xml
new file mode 100644
index 000000000..3870adb6f
--- /dev/null
+++ b/references/ha-crmsh-help-commands.xml
@@ -0,0 +1,68 @@
+
+
+ %entities;
+]>
+
+
+
+
+
+ &crmshell; help commands
+
+
+
+ The crm command has multiple options for showing help text:
+
+
+
+
+
+
+
+ Show the usage of crm and its command-line options:
+
+&prompt.user;sudo crm --help
+
+
+
+ List the conceptual help topics:
+
+&prompt.user;sudo crm help topics
+
+
+
+ List all the available subcommands:
+
+&prompt.user;sudo crm help
+
+
+
+ Show the help text for a subcommand. For example:
+
+&prompt.user;sudo crm configure help
+
+
+
+ Show the syntax, usage, and examples for a command within a subcommand. For example:
+
+&prompt.user;sudo crm configure help group
+
+ This command also has the same result:
+
+&prompt.user;sudo crm help configure group
+
+
+
+ Unlike the 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.
+
+
diff --git a/references/ha-crmsh-status-commands.xml b/references/ha-crmsh-status-commands.xml
new file mode 100644
index 000000000..ac61c39d3
--- /dev/null
+++ b/references/ha-crmsh-status-commands.xml
@@ -0,0 +1,80 @@
+
+
+ %entities;
+]>
+
+
+
+
+ &crmshell; status commands
+
+
+
+ The crm command has multiple options for showing information about the cluster:
+
+
+
+
+
+
+
+ Show the status of the cluster services:
+
+&prompt.user;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:
+
+&prompt.user;sudo crm status
+
+
+
+ Show the status of the cluster, but with the resources listed under the nodes they're
+ currently running on:
+
+&prompt.user;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:
+
+&prompt.user;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:
+
+&prompt.user;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:
+
+&prompt.user;sudo crm status full
+
+
+
+ Show additional options:
+
+&prompt.user;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.
+
+
diff --git a/snippets/ha-crmsh-interactive-mode.xml b/snippets/ha-crmsh-interactive-mode.xml
new file mode 100644
index 000000000..904133792
--- /dev/null
+++ b/snippets/ha-crmsh-interactive-mode.xml
@@ -0,0 +1,18 @@
+
+
+ %entities;
+]>
+
+ The &crmshell;'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.
+
diff --git a/snippets/ha-crmsh-shell-scripts.xml b/snippets/ha-crmsh-shell-scripts.xml
new file mode 100644
index 000000000..d75c25f25
--- /dev/null
+++ b/snippets/ha-crmsh-shell-scripts.xml
@@ -0,0 +1,14 @@
+
+
+ %entities;
+]>
+
+ You can create &crmshell; 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.
+
diff --git a/tasks/ha-crmsh-debugging-cluster-configuration-changes.xml b/tasks/ha-crmsh-debugging-cluster-configuration-changes.xml
new file mode 100644
index 000000000..f20c4690f
--- /dev/null
+++ b/tasks/ha-crmsh-debugging-cluster-configuration-changes.xml
@@ -0,0 +1,97 @@
+
+
+ %entities;
+]>
+
+
+
+
+ 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 &rootuser; user or as a user with sudo privileges.
+
+
+
+
+ Start &crmsh;'s interactive mode at the configure level:
+
+&prompt.user;sudo crm configure
+
+
+
+ Make your changes.
+
+
+
+
+ Show a diff of the changes to the cluster configuration:
+
+&prompt.crm.conf;show changed
+
+
+
+ Show a projection of the changes to the cluster status:
+
+&prompt.crm.conf;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:
+
+&prompt.crm.conf;commit
+
+ Alternatively, you can discard the changes before committing them by exiting
+ interactive mode with quit.
+
+
+
+
+
+ For more information
+
+
+ crm configure help ptest
+
+
+
+
diff --git a/tasks/ha-crmsh-managing-sensitive-parameters.xml b/tasks/ha-crmsh-managing-sensitive-parameters.xml
new file mode 100644
index 000000000..cb4596b5c
--- /dev/null
+++ b/tasks/ha-crmsh-managing-sensitive-parameters.xml
@@ -0,0 +1,118 @@
+
+
+ %entities;
+]>
+
+
+
+
+ Managing sensitive parameters
+
+
+
+ By default, the &crmshell; 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 &rootuser; user has permission to
+ read or modify it. This helps to prevent accidental data exposure.
+
+
+
+
+
+
+
+ Log in either as the &rootuser; user or as a user with sudo privileges.
+
+
+
+
+ Check the resource's current parameters:
+
+&prompt.user;sudo crm configure show RESOURCE
+
+
+
+ Hide the value of a sensitive parameter:
+
+
+
+
+ To hide the value of an existing parameter, use the stash command:
+
+&prompt.user;sudo crm resource secret RESOURCE stash PARAMETER
+
+ For example:
+
+&prompt.user;sudo crm resource secret mydb stash passwd
+
+
+
+ To add a new parameter, use the set command:
+
+&prompt.user;sudo crm resource secret RESOURCE set PARAMETER VALUE
+
+ For example:
+
+&prompt.user;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
+ &rootuser; 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:
+
+&prompt.user;sudo cibsecret sync
+
+
+
+ You can view the hidden value with the following command:
+
+&prompt.user;sudo crm resource secret RESOURCE show PARAMETER
+
+ For example:
+
+&prompt.user;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 &pace;'s
+ cibsecret command.
+
+
+
diff --git a/tasks/ha-crmsh-testing-with-shadow-configuration.xml b/tasks/ha-crmsh-testing-with-shadow-configuration.xml
new file mode 100644
index 000000000..6e40b93bc
--- /dev/null
+++ b/tasks/ha-crmsh-testing-with-shadow-configuration.xml
@@ -0,0 +1,111 @@
+
+
+ %entities;
+]>
+
+
+
+
+ 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 &rootuser; user or as a user with sudo privileges.
+
+
+
+
+ Start &crmsh;'s interactive mode at the configure level:
+
+&prompt.user;sudo crm configure
+
+
+
+ Create a new shadow CIB:
+
+&prompt.crm.conf;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.
+
+
+
+
+ To apply the changes from the shadow CIB to the live CIB, run the following command:
+
+&prompt.crm.conf;cib commit test1
+INFO: configure.cib.commit: committed 'test1' shadow CIB to the cluster
+
+
+
+ You can switch back to the shadow CIB if you need to use it again later:
+
+&prompt.crm.conf;cib use test1
+
+
+
+ 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
+
+
+
+
diff --git a/tasks/ha-crmsh-using-interactive-mode.xml b/tasks/ha-crmsh-using-interactive-mode.xml
new file mode 100644
index 000000000..ae19e82ec
--- /dev/null
+++ b/tasks/ha-crmsh-using-interactive-mode.xml
@@ -0,0 +1,126 @@
+
+
+ %entities;
+]>
+
+
+
+
+ Using &crmsh;'s interactive mode
+
+
+
+
+
+
+
+
+
+ Log in either as the &rootuser; user or as a user with sudo privileges.
+
+
+
+
+ Start interactive mode:
+
+&prompt.user;sudo crm
+
+ The prompt changes to crm(live/HOSTNAME)#. However, for better readability
+ we omit the host name in our documentation:
+
+crm(live)#
+
+ Starting a subcommand directly
+
+ You can also start interactive mode directly at the subcommand level. For example:
+
+&prompt.user;sudo crm configure
+&prompt.crm.conf;
+
+
+
+
+ You can navigate interactive mode with the following options:
+
+
+
+
+ List the available subcommands:
+
+&prompt.crm;ls
+
+
+
+ Enter the name of a subcommand to switch to that level. For example:
+
+&prompt.crm;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
+&prompt.crm;
+
+
+
+
+
+ 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
+ &node1;. 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.
+
+
+ Adding a virtual IP address with a location constraint for node &node1;
+&prompt.crm;configure
+&prompt.crm.conf;primitive vip1 IPaddr2 params ip=&subnetI;.5
+&prompt.crm.conf;location loc-vip1-on-alice vip1 inf: alice
+&prompt.crm.conf;show changed
+
+
+
+
+ Commit your changes to apply them to the live cluster:
+
+&prompt.crm.conf;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 &crmshell; will warn you before this happens.
+
+
+
+
+ Exit interactive mode:
+
+&prompt.crm.conf;quit
+
+
+
+
+ For more information
+
+
+
+
+
+
+
diff --git a/tasks/ha-crmsh-using-shell-scripts.xml b/tasks/ha-crmsh-using-shell-scripts.xml
new file mode 100644
index 000000000..7aec12d4c
--- /dev/null
+++ b/tasks/ha-crmsh-using-shell-scripts.xml
@@ -0,0 +1,58 @@
+
+
+ %entities;
+]>
+
+
+
+
+ Using &crmsh;'s shell scripts
+
+
+
+
+
+
+
+
+
+ Log in either as the &rootuser; 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:
+
+&prompt.user;sudo crm -f SCRIPT
+
+ For example, this &crmshell; script is named example.cli:
+
+&prompt.user;sudo crm -f example.cli
+
+
+