From b7ef3725ad7f1aec8541e7d1a13d37d105310301 Mon Sep 17 00:00:00 2001 From: Tahlia Richardson <3069029+tahliar@users.noreply.github.com> Date: Fri, 10 Jul 2026 17:33:08 +1000 Subject: [PATCH 01/13] Basic migration of topics --- DC-HA-crmsh-introduction | 15 ++ articles/ha-crmsh-introduction.asm.xml | 140 ++++++++++++++ concepts/ha-crmsh-what-is.xml | 167 ++++++++++++++++ concepts/ha-what-is.xml | 12 +- references/ha-crmsh-help-commands.xml | 81 ++++++++ ...ng-configuration-with-interactive-mode.xml | 81 ++++++++ ...ebugging-cluster-configuration-changes.xml | 45 +++++ tasks/ha-crmsh-generating-cluster-diagram.xml | 36 ++++ tasks/ha-crmsh-setting-secret-passwords.xml | 62 ++++++ ...rmsh-testing-with-shadow-configuration.xml | 76 ++++++++ tasks/ha-crmsh-using-cluster-scripts.xml | 179 ++++++++++++++++++ tasks/ha-crmsh-using-shell-scripts.xml | 52 +++++ 12 files changed, 940 insertions(+), 6 deletions(-) create mode 100644 DC-HA-crmsh-introduction create mode 100644 articles/ha-crmsh-introduction.asm.xml create mode 100644 concepts/ha-crmsh-what-is.xml create mode 100644 references/ha-crmsh-help-commands.xml create mode 100644 tasks/ha-crmsh-changing-configuration-with-interactive-mode.xml create mode 100644 tasks/ha-crmsh-debugging-cluster-configuration-changes.xml create mode 100644 tasks/ha-crmsh-generating-cluster-diagram.xml create mode 100644 tasks/ha-crmsh-setting-secret-passwords.xml create mode 100644 tasks/ha-crmsh-testing-with-shadow-configuration.xml create mode 100644 tasks/ha-crmsh-using-cluster-scripts.xml create mode 100644 tasks/ha-crmsh-using-shell-scripts.xml 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..99385c86a --- /dev/null +++ b/articles/ha-crmsh-introduction.asm.xml @@ -0,0 +1,140 @@ + + + %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; + TODO + TODO + + 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 + + + + + TODO + + Requirements: + + TODO + TODO + + + + + + + Help commands + + + + + Using interactive mode + + + + + Using shell scripts + + + + + Using cluster scripts + + + + + + + + + + + + + diff --git a/concepts/ha-crmsh-what-is.xml b/concepts/ha-crmsh-what-is.xml new file mode 100644 index 000000000..e77afeb97 --- /dev/null +++ b/concepts/ha-crmsh-what-is.xml @@ -0,0 +1,167 @@ + + + %entities; +]> + + + + + + What is the &crmshell;? + + + + The &crmshell; (&crmsh;) is a command-line interface for installing, + configuring and managing &ha; clusters. You can run most &crmsh; commands from any node + in the cluster. + + + This section introduces the command-line tool crm. The crm command has several subcommands which manage resources, CIBs, nodes, resource agents, and others. It offers a thorough help system with embedded examples. Events are logged to /var/log/crmsh/crmsh.log. + + + + +
+ Using the &crmshell; + + The crm command itself can be used in the following ways: + + + + Directly + + + Concatenate all subcommands to crm, press and you see the output immediately. For example, enter crm help ra to get about the ra subcommand (resource agents). + + + It is possible to abbreviate subcommands if they are unique. For example, you can shorten status as st and &crmsh; knows what you mean. + + + + + Interactive mode + + + Type crm to enter the internal shell. The prompt changes to crm(live). With help you can get an overview of the available subcommands. As the internal shell has different levels of subcommands, you can enter one by typing this subcommand and press . + + + For example, if you type resource you enter the resource management level. Your prompt changes to crm(live)resource#. To leave the internal shell, use the command quit. If you need to go one level back, use back, up, end, or cd. + + + You can enter the level directly by typing crm and the respective subcommand without any options and press . + + + The internal shell supports also tab completion for subcommands and resources. Type the beginning of a command, press and crm completes the respective object. + + + + + Shell scripts + + + &crmshell; scripts contain subcommands of crm. For more information, see xref linkend="sec-ha-manual-config-crmshellscripts"/. + + + + + Cluster scripts + + + These are a collection of metadata, references to RPM packages, configuration files, and &crmsh; subcommands bundled under a single, yet descriptive name. They are managed through the crm script command. + + Do not confuse them with &crmsh; shell scripts: although both share some common objectives, the &crmshell; scripts only contain subcommands whereas cluster scripts incorporate much more than a simple enumeration of commands. For more information, see xref linkend="sec-ha-manual-config-clusterscripts"/. + + + + + + &crmsh; also supports synchronous command execution. Use the option to activate it. If you have started crm without , you can enable it later with the user preference's wait set to yes (options wait yes). If this option is enabled, crm waits until the transition is finished. Whenever a transaction is started, dots are printed to indicate progress. Synchronous command execution is only applicable for commands like resource start. + +
+ +
+ User privileges and authentication + + 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 on all cluster nodes by using SSH for &crmsh; operations such as + crm cluster init, crm cluster join, and + crm report. They can also make changes to the CIB, + such as adding resources and constraints. + + + + + The CRM owner user (typically the user hacluster, + created by default during the cluster installation). This user can make changes to the CIB, + but has limited privileges for operations that use SSH, such as crm report. + + + Unprivileged users + + The option allows you to run crm and its + subcommands as a regular (unprivileged) user, and to change its ID using + sudo when necessary. For example, the following command sets + hacluster as the privileged user ID: + + &prompt.root;crm options user hacluster + + You must set up /etc/sudoers so that sudo + does not ask for a password. + + + + + + For operations that use SSH, the cluster uses passwordless SSH access for communication + between the nodes. If you set up the cluster with crm cluster init, the + script checks for SSH keys and generates them if they do not already exist. If you set up + the cluster with the &yast; cluster module, 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, but requires additional configuration. + +
+ +
+ For more information + + + +https://crmsh.github.io/ + + + + +https://crmsh.github.io/documentation + + + + +crm help overview + + + + +https://crmsh.github.io/man-5.0/#topics.Introduction.Interface + + + +
+ diff --git a/concepts/ha-what-is.xml b/concepts/ha-what-is.xml index 258951e5d..e32aad696 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 &ha; clusters. You can run most &crmsh; + 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..df5d3f32c --- /dev/null +++ b/references/ha-crmsh-help-commands.xml @@ -0,0 +1,81 @@ + + + %entities; +]> + + + + + + &crmshell; help commands + + + + Help can be accessed in several ways: + + + + + + + + To output the usage of crm and its command line + options: + +&prompt.root;crm --help + + + + To give a list of all available commands: + +&prompt.root;crm help + + + + To access other help sections, not only the command reference: + +&prompt.root;crm help topics + + + + To view the extensive help text of the configure + subcommand: + +&prompt.root;crm configure help + + + + To print the syntax, its usage, and examples of the group + subcommand of configure: + +&prompt.root;crm configure help group + + This is the same: + +&prompt.root;crm help configure group + + + + Almost all output of the help subcommand (do not mix + it up with the option) opens a text viewer. This + text viewer allows you to scroll up or down and read the help text more + comfortably. To leave the text viewer, press the Q key. + + + Use tab completion in Bash and interactive shell + + The &crmsh; supports full tab completion in Bash directly, not only + for the interactive shell. For example, typing crm help + config completes the word + like in the interactive shell. + + + diff --git a/tasks/ha-crmsh-changing-configuration-with-interactive-mode.xml b/tasks/ha-crmsh-changing-configuration-with-interactive-mode.xml new file mode 100644 index 000000000..8f2625823 --- /dev/null +++ b/tasks/ha-crmsh-changing-configuration-with-interactive-mode.xml @@ -0,0 +1,81 @@ + + + %entities; +]> + + + + + Changing configuration with &crmsh;'s interactive mode + + + + TBD + + + + + + crm configure, create resource, add constraints, commit + + + Interactive crm prompt + By using crm without arguments (or with only one sublevel as + argument), the &crmshell; enters the interactive mode. This mode is + indicated by the following prompt: + + crm(live/HOSTNAME) + + For readability reasons, we omit the host name in the interactive crm + prompts in our documentation. We only include the host name if you need + to run the interactive shell on a specific node, like &node1; for example: + + crm(live/&node1;) + + + Interactive as internal shell: + + Type crm to enter the internal shell. The prompt + changes to crm(live). With + help you can get an overview of the available + subcommands. As the internal shell has different levels of + subcommands, you can enter one by typing this + subcommand and press . + + + + For example, if you type resource you enter the + resource management level. Your prompt changes to + crm(live)resource#. To leave the + internal shell, use the command quit. If you need to go + one level back, use back, up, + end, or cd. + + + You can enter the level directly by typing crm and + the respective subcommand without any options and press + . + + + The internal shell supports also tab completion for subcommands and + resources. Type the beginning of a command, press + and crm completes the + respective object. + + + For more information + + + + + + + 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..aa5caa049 --- /dev/null +++ b/tasks/ha-crmsh-debugging-cluster-configuration-changes.xml @@ -0,0 +1,45 @@ + + + %entities; +]> + + + + + Debugging cluster configuration changes + + + + TODO + + + + + + Before loading your configuration changes back into the cluster, it is + recommended to review your changes with ptest. The + ptest command can show a diagram of actions that will + be induced by committing the changes. You need the + graphviz package to display the diagrams. The + following example is a transcript, adding a monitor operation: + +&prompt.root;crm configure +&prompt.crm.conf;show fence-&node2; +primitive fence-&node2; stonith:apcsmart \ + params hostlist="&node2;" +&prompt.crm.conf;monitor fence-&node2; 120m:60s +&prompt.crm.conf;show changed +primitive fence-&node2; stonith:apcsmart \ + params hostlist="&node2;" \ + op monitor interval="120m" timeout="60s" +&prompt.crm.conf;ptest +&prompt.crm.conf;commit + diff --git a/tasks/ha-crmsh-generating-cluster-diagram.xml b/tasks/ha-crmsh-generating-cluster-diagram.xml new file mode 100644 index 000000000..83544e087 --- /dev/null +++ b/tasks/ha-crmsh-generating-cluster-diagram.xml @@ -0,0 +1,36 @@ + + + %entities; +]> + + + + + Generating a cluster diagram + + + + TODO + + + + + + To output a cluster diagram, use the command + crm configure graph. It displays + the current configuration on its current window, therefore requiring + X11. + + + If you prefer Scalable Vector Graphics (SVG), use the following command: + +&prompt.root;crm configure graph dot config.svg svg + diff --git a/tasks/ha-crmsh-setting-secret-passwords.xml b/tasks/ha-crmsh-setting-secret-passwords.xml new file mode 100644 index 000000000..397c16ea4 --- /dev/null +++ b/tasks/ha-crmsh-setting-secret-passwords.xml @@ -0,0 +1,62 @@ + + + %entities; +]> + + + + + Setting secret passwords + + + + Temporary title; there's a better way to put it + + + + + + If your cluster configuration contains sensitive information, such + as passwords, it should be stored in local files. That way, these + parameters will never be logged or leaked in support reports. + + + + Before using secret, run the + show command to get an overview of all your + resources: + + +&prompt.root;crm configure show +primitive mydb mysql \ + params replication_user=admin ... + + + To set a password for the above mydb + resource, use the following commands: + + +&prompt.root;crm resource secret mydb set passwd linux +INFO: syncing /var/lib/heartbeat/lrm/secrets/mydb/passwd to [your node list] + + + You can get the saved password back with: + + +&prompt.root;crm resource secret mydb show passwd +linux + + + The parameters need to be synchronized between nodes; the + crm resource secret command takes care of that. We + highly recommend that you only use this command to manage secret parameters. + + 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..279f6b8e6 --- /dev/null +++ b/tasks/ha-crmsh-testing-with-shadow-configuration.xml @@ -0,0 +1,76 @@ + + + %entities; +]> + + + + + Testing with shadow configuration + + + + A shadow configuration is used to test different configuration scenarios. If you have created several shadow configurations, you can test them one by one to see the effects of your changes. + + + + + + The usual process looks like this: + + + + + Log in as &rootuser; and start the crm + interactive shell: + +&prompt.root;crm configure + + + + Create a new shadow configuration: + +&prompt.crm.conf;cib new myNewConfig +INFO: myNewConfig shadow CIB created + + If you omit the name of the shadow CIB, a temporary name + @tmp@ is created. + + + + + To copy the current live configuration into your shadow + configuration, use the following command, otherwise skip this step: + +crm(myNewConfig)# cib reset myNewConfig + + The previous command makes it easier to modify any existing resources + later. + + + + + Make your changes as usual. After you have created the shadow + configuration, all changes go there. To save all your changes, use the + following command: + +crm(myNewConfig)# commit + + + + If you need the live cluster configuration again, switch back with the + following command: + +crm(myNewConfig)configure# cib use live +&prompt.crm; + + + diff --git a/tasks/ha-crmsh-using-cluster-scripts.xml b/tasks/ha-crmsh-using-cluster-scripts.xml new file mode 100644 index 000000000..e80c527ac --- /dev/null +++ b/tasks/ha-crmsh-using-cluster-scripts.xml @@ -0,0 +1,179 @@ + + + %entities; +]> + + + + + Using &crmsh;'s cluster scripts + + + + Collecting information from all cluster nodes and deploying any + changes is a key cluster administration task. Instead of performing + the same procedures manually on different nodes (which is error-prone), + you can use the &crmsh; cluster scripts. + Do not confuse them with the &crmsh; shell scripts. + + + + + In contrast to &crmsh; shell scripts, cluster scripts performs + additional tasks like: + + + Installing software that is required for a specific task. + + + Creating or modifying any configuration files. + + + Collecting information and reporting potential problems with the + cluster. + + + Deploying the changes to all nodes. + + + + &crmsh; cluster scripts do not replace other tools for managing + clusters—they provide an integrated way to perform the above + tasks across the cluster. Find detailed information at . + + To get a list of all available cluster scripts, run: + &prompt.root;crm script list + + To view the components of a script, use the + show command and the name of the cluster script, + for example: + &prompt.root;crm script show mailto +mailto (Basic) +MailTo + + This is a resource agent for MailTo. It sends email to a sysadmin +whenever a takeover occurs. + +1. Notifies recipients by email in the event of resource takeover + + id (required) (unique) + Identifier for the cluster resource + email (required) + Email address + subject + Subject + + The output of show contains a title, a + short description, and a procedure. Each procedure is divided + into a series of steps, performed in the given order. + Each step contains a list of required and optional parameters, + along with a short description and its default value. + + Each cluster script understands a set of common parameters. + These parameters can be passed to any script: + + + Common parameters + + + + Parameter + Argument + Description + + + + + action + INDEX + If set, only execute a single action (index, as + returned by verify) + + + dry_run + BOOL + If set, simulate execution only (default: no) + + + nodes + LIST + List of nodes to execute the script for + + + port + NUMBER + Port to connect to + + + statefile + FILE + When single-stepping, the state is saved in the given + file + + + sudo + BOOL + If set, crm prompts for a sudo password and uses sudo + where appropriate (default: no) + + + timeout + NUMBER + Execution timeout in seconds (default: 600) + + + user + USER + Run script as the given user + + + +
+ + Before running a cluster script, review the actions that it will + perform and verify its parameters to avoid problems. A cluster script + can potentially perform a series of actions and may fail for + various reasons. Thus, verifying your parameters before + running it helps to avoid problems. + For example, the mailto resource agent + requires a unique identifier and an e-mail address. To verify these + parameters, run: + &prompt.root;crm script verify mailto id=sysadmin email=&exampleuser_plain;@example.org +1. Ensure mail package is installed + + mailx + +2. Configure cluster resources + + primitive sysadmin MailTo + email="tux@example.org" + op start timeout="10" + op stop timeout="10" + op monitor interval="10" timeout="10" + + clone c-sysadmin sysadmin + The verify command prints the steps and replaces + any placeholders with your given parameters. If verify + finds any problems, it reports it. + If everything is OK, replace the verify + command with run: + &prompt.root;crm script run mailto id=sysadmin email=&exampleuser_plain;@example.org +INFO: MailTo +INFO: Nodes: &node1;, &node2; +OK: Ensure mail package is installed +OK: Configure cluster resources + Check whether your resource is integrated into your cluster + with crm status: + &prompt.root;crm status +[...] + Clone Set: c-sysadmin [sysadmin] + Started: [ &node1; &node2; ] + diff --git a/tasks/ha-crmsh-using-shell-scripts.xml b/tasks/ha-crmsh-using-shell-scripts.xml new file mode 100644 index 000000000..36cef1c9b --- /dev/null +++ b/tasks/ha-crmsh-using-shell-scripts.xml @@ -0,0 +1,52 @@ + + + %entities; +]> + + + + + Using &crmsh;'s shell scripts + + + + The &crmsh; shell scripts provide a convenient way to enumerate &crmsh; + subcommands into a file. This makes it easy to comment specific lines or + to replay them later. Keep in mind that a &crmsh; shell script can contain + only &crmsh; subcommands. Any other commands are not + allowed. + + + + + + Before you can use a &crmsh; shell script, create a file with specific + commands. For example, the following file prints the status of the cluster + and gives a list of all nodes: + + + A simple &crmsh; shell script + # A small example file with some crm subcommands +status +node list + + + Any line starting with the hash symbol (#) is a + comment and is ignored. If a line is too long, insert a backslash + (\) at the end and continue in the next line. We + recommend that you indent lines belonging to a certain subcommand to improve + readability. + + + To use this script, use one of the following methods: + &prompt.root;crm -f example.cli +&prompt.root;crm < example.cli + From 76ce0668a6bcc99b13b1a89b02b7c16c18f3acb4 Mon Sep 17 00:00:00 2001 From: Tahlia Richardson <3069029+tahliar@users.noreply.github.com> Date: Tue, 14 Jul 2026 17:59:05 +1000 Subject: [PATCH 02/13] Add cluster status topic --- articles/ha-crmsh-introduction.asm.xml | 2 ++ tasks/ha-crmsh-showing-cluster-status.xml | 29 +++++++++++++++++++++++ 2 files changed, 31 insertions(+) create mode 100644 tasks/ha-crmsh-showing-cluster-status.xml diff --git a/articles/ha-crmsh-introduction.asm.xml b/articles/ha-crmsh-introduction.asm.xml index 99385c86a..76019bbf9 100644 --- a/articles/ha-crmsh-introduction.asm.xml +++ b/articles/ha-crmsh-introduction.asm.xml @@ -25,6 +25,7 @@ + @@ -112,6 +113,7 @@ Help commands + Using interactive mode diff --git a/tasks/ha-crmsh-showing-cluster-status.xml b/tasks/ha-crmsh-showing-cluster-status.xml new file mode 100644 index 000000000..6a4e5fb82 --- /dev/null +++ b/tasks/ha-crmsh-showing-cluster-status.xml @@ -0,0 +1,29 @@ + + + %entities; +]> + + + + + Showing the cluster status + + + + Might switch to a reference topic depending on the content + + + + + + `status full`, `status ops` to also see operations incl. migration threshold + + From 565224d1010e06581c6e6c497eb4ed7e52294d5e Mon Sep 17 00:00:00 2001 From: Tahlia Richardson <3069029+tahliar@users.noreply.github.com> Date: Thu, 16 Jul 2026 16:44:16 +1000 Subject: [PATCH 03/13] Editing --- articles/ha-crmsh-introduction.asm.xml | 12 ++- concepts/ha-crmsh-what-is.xml | 41 +++++++--- references/ha-crmsh-help-commands.xml | 73 +++++++---------- references/ha-crmsh-status-commands.xml | 80 +++++++++++++++++++ tasks/ha-crmsh-showing-cluster-status.xml | 29 ------- ...rmsh-testing-with-shadow-configuration.xml | 56 ++++++------- ...ml => ha-crmsh-using-interactive-mode.xml} | 4 +- 7 files changed, 179 insertions(+), 116 deletions(-) create mode 100644 references/ha-crmsh-status-commands.xml delete mode 100644 tasks/ha-crmsh-showing-cluster-status.xml rename tasks/{ha-crmsh-changing-configuration-with-interactive-mode.xml => ha-crmsh-using-interactive-mode.xml} (95%) diff --git a/articles/ha-crmsh-introduction.asm.xml b/articles/ha-crmsh-introduction.asm.xml index 76019bbf9..22bd74a6d 100644 --- a/articles/ha-crmsh-introduction.asm.xml +++ b/articles/ha-crmsh-introduction.asm.xml @@ -25,8 +25,7 @@ - - + @@ -37,6 +36,7 @@ + @@ -113,8 +113,12 @@ Help commands - - + + + Status commands + + + Using interactive mode diff --git a/concepts/ha-crmsh-what-is.xml b/concepts/ha-crmsh-what-is.xml index e77afeb97..d8fb38e6b 100644 --- a/concepts/ha-crmsh-what-is.xml +++ b/concepts/ha-crmsh-what-is.xml @@ -32,17 +32,14 @@
Using the &crmshell; - The crm command itself can be used in the following ways: + You can use the crm command in multiple ways: Directly - Concatenate all subcommands to crm, press and you see the output immediately. For example, enter crm help ra to get about the ra subcommand (resource agents). - - - It is possible to abbreviate subcommands if they are unique. For example, you can shorten status as st and &crmsh; knows what you mean. + Run a single crm command in full, including a subcommand and parameters, directly in your terminal. @@ -82,13 +79,19 @@ + + Use tab completion in Bash and interactive shell - &crmsh; also supports synchronous command execution. Use the option to activate it. If you have started crm without , you can enable it later with the user preference's wait set to yes (options wait yes). If this option is enabled, crm waits until the transition is finished. Whenever a transaction is started, dots are printed to indicate progress. Synchronous command execution is only applicable for commands like resource start. + The &crmsh; supports full tab completion in Bash directly, not only + for the interactive shell. For example, typing crm help + config completes the word + like in the interactive shell. +
- User privileges and authentication + User privileges Managing a cluster requires sufficient privileges. The following users can run the crm command and its subcommands: @@ -139,27 +142,43 @@
+
+ SSH key authentication + + For operations that use SSH, the cluster uses passwordless SSH access for communication + between the nodes. If you set up the cluster with crm cluster init, the + script checks for SSH keys and generates them if they do not already exist. If you set up + the cluster with the &yast; cluster module, 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, but requires additional configuration. + +
+
For more information -https://crmsh.github.io/ + man crm -https://crmsh.github.io/documentation + crm help overview -crm help overview + -https://crmsh.github.io/man-5.0/#topics.Introduction.Interface + diff --git a/references/ha-crmsh-help-commands.xml b/references/ha-crmsh-help-commands.xml index df5d3f32c..3870adb6f 100644 --- a/references/ha-crmsh-help-commands.xml +++ b/references/ha-crmsh-help-commands.xml @@ -19,63 +19,50 @@ - Help can be accessed in several ways: + The crm command has multiple options for showing help text: - - To output the usage of crm and its command line - options: - -&prompt.root;crm --help + + Show the usage of crm and its command-line options: + +&prompt.user;sudo crm --help - - To give a list of all available commands: - -&prompt.root;crm help + + List the conceptual help topics: + +&prompt.user;sudo crm help topics - - To access other help sections, not only the command reference: - -&prompt.root;crm help topics + + List all the available subcommands: + +&prompt.user;sudo crm help - - To view the extensive help text of the configure - subcommand: + + Show the help text for a subcommand. For example: -&prompt.root;crm configure help +&prompt.user;sudo crm configure help - - To print the syntax, its usage, and examples of the group - subcommand of configure: - -&prompt.root;crm configure help group - - This is the same: - -&prompt.root;crm help configure group + + 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 - - - Almost all output of the help subcommand (do not mix - it up with the option) opens a text viewer. This - text viewer allows you to scroll up or down and read the help text more - comfortably. To leave the text viewer, press the Q key. - - - Use tab completion in Bash and interactive shell - - The &crmsh; supports full tab completion in Bash directly, not only - for the interactive shell. For example, typing crm help - config completes the word - like in the interactive shell. - - + + + 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/tasks/ha-crmsh-showing-cluster-status.xml b/tasks/ha-crmsh-showing-cluster-status.xml deleted file mode 100644 index 6a4e5fb82..000000000 --- a/tasks/ha-crmsh-showing-cluster-status.xml +++ /dev/null @@ -1,29 +0,0 @@ - - - %entities; -]> - - - - - Showing the cluster status - - - - Might switch to a reference topic depending on the content - - - - - - `status full`, `status ops` to also see operations incl. migration threshold - - diff --git a/tasks/ha-crmsh-testing-with-shadow-configuration.xml b/tasks/ha-crmsh-testing-with-shadow-configuration.xml index 279f6b8e6..427431a14 100644 --- a/tasks/ha-crmsh-testing-with-shadow-configuration.xml +++ b/tasks/ha-crmsh-testing-with-shadow-configuration.xml @@ -18,7 +18,7 @@ - A shadow configuration is used to test different configuration scenarios. If you have created several shadow configurations, you can test them one by one to see the effects of your changes. + You can use a shadow configuration to test different configuration scenarios. If you create multiple shadow configurations, you can test them one by one to see the effects of your changes. @@ -28,33 +28,35 @@ - - Log in as &rootuser; and start the crm - interactive shell: - -&prompt.root;crm configure + + Log in either as the &rootuser; user or as a user with sudo privileges. + - - Create a new shadow configuration: - -&prompt.crm.conf;cib new myNewConfig -INFO: myNewConfig shadow CIB created - - If you omit the name of the shadow CIB, a temporary name - @tmp@ is created. - + + Start &crmsh;'s interactive mode: + +&prompt.user;sudo crm configure - - To copy the current live configuration into your shadow - configuration, use the following command, otherwise skip this step: - -crm(myNewConfig)# cib reset myNewConfig - - The previous command makes it easier to modify any existing resources - later. - + + Create a new shadow configuration: + +&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 for the new shadow CIB, a temporary name + @tmp@ is used instead. + + + + + + You can copy the current live configuration into your shadow configuration to make it easier to modify any existing resources later: + +crm(test1)configure# cib reset test1 @@ -62,15 +64,15 @@ INFO: myNewConfig shadow CIB created configuration, all changes go there. To save all your changes, use the following command: -crm(myNewConfig)# commit +crm(test1)configure# commit If you need the live cluster configuration again, switch back with the following command: -crm(myNewConfig)configure# cib use live -&prompt.crm; +crm(test1)configure# cib use live +&prompt.crm.conf; diff --git a/tasks/ha-crmsh-changing-configuration-with-interactive-mode.xml b/tasks/ha-crmsh-using-interactive-mode.xml similarity index 95% rename from tasks/ha-crmsh-changing-configuration-with-interactive-mode.xml rename to tasks/ha-crmsh-using-interactive-mode.xml index 8f2625823..d26a468c3 100644 --- a/tasks/ha-crmsh-changing-configuration-with-interactive-mode.xml +++ b/tasks/ha-crmsh-using-interactive-mode.xml @@ -6,7 +6,7 @@ ]> - - Changing configuration with &crmsh;'s interactive mode + Using &crmsh;'s interactive mode From 9bdae4305901a5e3a6fc61a86bce9ebe70ca8d07 Mon Sep 17 00:00:00 2001 From: Tahlia Richardson <3069029+tahliar@users.noreply.github.com> Date: Fri, 17 Jul 2026 13:45:03 +1000 Subject: [PATCH 04/13] Remove cluster diagram; dotty deprecated --- articles/ha-crmsh-introduction.asm.xml | 2 -- 1 file changed, 2 deletions(-) diff --git a/articles/ha-crmsh-introduction.asm.xml b/articles/ha-crmsh-introduction.asm.xml index 22bd74a6d..13d80fc8d 100644 --- a/articles/ha-crmsh-introduction.asm.xml +++ b/articles/ha-crmsh-introduction.asm.xml @@ -30,7 +30,6 @@ - @@ -135,7 +134,6 @@ - From 1275b9f234ae564f3ecc24d4c22f40b8646949df Mon Sep 17 00:00:00 2001 From: Tahlia Richardson <3069029+tahliar@users.noreply.github.com> Date: Fri, 17 Jul 2026 17:17:34 +1000 Subject: [PATCH 05/13] Editing --- ...rmsh-testing-with-shadow-configuration.xml | 54 +++++++++++-------- 1 file changed, 33 insertions(+), 21 deletions(-) diff --git a/tasks/ha-crmsh-testing-with-shadow-configuration.xml b/tasks/ha-crmsh-testing-with-shadow-configuration.xml index 427431a14..03c797728 100644 --- a/tasks/ha-crmsh-testing-with-shadow-configuration.xml +++ b/tasks/ha-crmsh-testing-with-shadow-configuration.xml @@ -14,7 +14,7 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:trans="http://docbook.org/ns/transclusion"> - Testing with shadow configuration + Testing changes with a shadow configuration @@ -24,9 +24,9 @@ - The usual process looks like this: - - + This example procedure shows the process for creating and using a shadow configuration: + + Log in either as the &rootuser; user or as a user with sudo privileges. @@ -46,33 +46,45 @@ 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 for the new shadow CIB, a temporary name - @tmp@ is used instead. + The prompt changes from live to the name of the shadow configuration. + If you don't specify a name, the temporary name @tmp@ is used instead. - + - - You can copy the current live configuration into your shadow configuration to make it easier to modify any existing resources later: + Make the changes you want to test. These changes will only apply to the shadow + configuration, not to the live configuration. -crm(test1)configure# cib reset test1 - - Make your changes as usual. After you have created the shadow - configuration, all changes go there. To save all your changes, use the - following command: - + + Save the changes to see their effect on the cluster: + crm(test1)configure# commit - - If you need the live cluster configuration again, switch back with the - following command: - + + Switch back to the live configuration: + crm(test1)configure# cib use live &prompt.crm.conf; + + The prompt changes back to live. + + + + + You can switch back to the shadow configuration if you need to use it again later: + +&prompt.crm.conf;cib use test1 + + + + To undo the changes in the shadow configuration, or to update the shadow configuration + to match the latest live configuration, you can run the following command: + +crm(test1)configure# cib reset test1 +INFO: configure.cib.reset: copied live CIB to test1 - + From 5f737298c3d8333cc2f17577fed18da3d1c737ff Mon Sep 17 00:00:00 2001 From: Tahlia Richardson <3069029+tahliar@users.noreply.github.com> Date: Tue, 21 Jul 2026 18:16:48 +1000 Subject: [PATCH 06/13] Editing --- ...ebugging-cluster-configuration-changes.xml | 91 ++++++++++++++----- ...rmsh-testing-with-shadow-configuration.xml | 34 ++++--- 2 files changed, 92 insertions(+), 33 deletions(-) diff --git a/tasks/ha-crmsh-debugging-cluster-configuration-changes.xml b/tasks/ha-crmsh-debugging-cluster-configuration-changes.xml index aa5caa049..4e0eebaf5 100644 --- a/tasks/ha-crmsh-debugging-cluster-configuration-changes.xml +++ b/tasks/ha-crmsh-debugging-cluster-configuration-changes.xml @@ -14,32 +14,81 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:trans="http://docbook.org/ns/transclusion"> - Debugging cluster configuration changes + Reviewing cluster changes before committing - TODO + 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. - - Before loading your configuration changes back into the cluster, it is - recommended to review your changes with ptest. The - ptest command can show a diagram of actions that will - be induced by committing the changes. You need the - graphviz package to display the diagrams. The - following example is a transcript, adding a monitor operation: - -&prompt.root;crm configure -&prompt.crm.conf;show fence-&node2; -primitive fence-&node2; stonith:apcsmart \ - params hostlist="&node2;" -&prompt.crm.conf;monitor fence-&node2; 120m:60s -&prompt.crm.conf;show changed -primitive fence-&node2; stonith:apcsmart \ - params hostlist="&node2;" \ - op monitor interval="120m" timeout="60s" -&prompt.crm.conf;ptest -&prompt.crm.conf;commit + + + + 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 + + + + Generate a report on the changes to the cluster status: + +&prompt.crm.conf;ptest + + This command displays the following information: + + + + + The current cluster status, showing what the cluster looks like before the changes are committed + + + + + A transition summary, listing the actions the cluster will take after the changes are committed + + + + + A revised cluster status, showing what the cluster will look like 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 by exiting interactive mode with quit. + + + + + + For more information + + + crm configure help ptest + + + diff --git a/tasks/ha-crmsh-testing-with-shadow-configuration.xml b/tasks/ha-crmsh-testing-with-shadow-configuration.xml index 03c797728..fe6b60abd 100644 --- a/tasks/ha-crmsh-testing-with-shadow-configuration.xml +++ b/tasks/ha-crmsh-testing-with-shadow-configuration.xml @@ -14,17 +14,20 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:trans="http://docbook.org/ns/transclusion"> - Testing changes with a shadow configuration + Testing cluster changes with a shadow CIB - You can use a shadow configuration to test different configuration scenarios. If you create multiple shadow configurations, you can test them one by one to see the effects of your changes. + 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 configuration: + This example procedure shows the process for creating and using a shadow CIB: @@ -34,26 +37,25 @@ - Start &crmsh;'s interactive mode: + Start &crmsh;'s interactive mode at the configure level: &prompt.user;sudo crm configure - Create a new shadow configuration: + 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 configuration. + 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. These changes will only apply to the shadow - configuration, not to the live configuration. + Make the changes you want to test. @@ -64,7 +66,7 @@ INFO: configure.cib.new: test1 shadow CIB created - Switch back to the live configuration: + Switch back to the live CIB: crm(test1)configure# cib use live &prompt.crm.conf; @@ -74,17 +76,25 @@ INFO: configure.cib.new: test1 shadow CIB created - You can switch back to the shadow configuration if you need to use it again later: + 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 configuration, or to update the shadow configuration - to match the latest live configuration, you can run the following command: + To undo the changes in the shadow CIB, or to update the shadow CIB to match the latest + live CIB, you can 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 + + + From 80ce9d0fb1f6061d3d4570c809f7c1b6cf68c7b0 Mon Sep 17 00:00:00 2001 From: Tahlia Richardson <3069029+tahliar@users.noreply.github.com> Date: Fri, 24 Jul 2026 17:03:26 +1000 Subject: [PATCH 07/13] Editing --- ...ebugging-cluster-configuration-changes.xml | 15 +- ...rmsh-testing-with-shadow-configuration.xml | 16 +- tasks/ha-crmsh-using-cluster-scripts.xml | 224 ++++++++---------- tasks/ha-crmsh-using-shell-scripts.xml | 62 +++-- 4 files changed, 159 insertions(+), 158 deletions(-) diff --git a/tasks/ha-crmsh-debugging-cluster-configuration-changes.xml b/tasks/ha-crmsh-debugging-cluster-configuration-changes.xml index 4e0eebaf5..f20c4690f 100644 --- a/tasks/ha-crmsh-debugging-cluster-configuration-changes.xml +++ b/tasks/ha-crmsh-debugging-cluster-configuration-changes.xml @@ -18,7 +18,9 @@ - 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. + 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. @@ -48,7 +50,7 @@ - Generate a report on the changes to the cluster status: + Show a projection of the changes to the cluster status: &prompt.crm.conf;ptest @@ -57,17 +59,17 @@ - The current cluster status, showing what the cluster looks like before the changes are committed + The current cluster status - A transition summary, listing the actions the cluster will take after the changes are committed + A summary of the actions the cluster will take after the changes are committed - A revised cluster status, showing what the cluster will look like after the changes are committed + The projected cluster status after the changes are committed @@ -78,7 +80,8 @@ &prompt.crm.conf;commit - Alternatively, you can discard the changes by exiting interactive mode with quit. + Alternatively, you can discard the changes before committing them by exiting + interactive mode with quit. diff --git a/tasks/ha-crmsh-testing-with-shadow-configuration.xml b/tasks/ha-crmsh-testing-with-shadow-configuration.xml index fe6b60abd..39aaba430 100644 --- a/tasks/ha-crmsh-testing-with-shadow-configuration.xml +++ b/tasks/ha-crmsh-testing-with-shadow-configuration.xml @@ -68,22 +68,28 @@ INFO: configure.cib.new: test1 shadow CIB created Switch back to the live CIB: -crm(test1)configure# cib use live -&prompt.crm.conf; +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, you can run the following command: + live CIB, run the following command: crm(test1)configure# cib reset test1 INFO: configure.cib.reset: copied live CIB to test1 diff --git a/tasks/ha-crmsh-using-cluster-scripts.xml b/tasks/ha-crmsh-using-cluster-scripts.xml index e80c527ac..4b9ba0a6c 100644 --- a/tasks/ha-crmsh-using-cluster-scripts.xml +++ b/tasks/ha-crmsh-using-cluster-scripts.xml @@ -27,40 +27,61 @@ - In contrast to &crmsh; shell scripts, cluster scripts performs - additional tasks like: - - - Installing software that is required for a specific task. - - - Creating or modifying any configuration files. - - - Collecting information and reporting potential problems with the - cluster. - - - Deploying the changes to all nodes. - - + + Unlike &crmshell; scripts, which can only contain crm subcommands, cluster scripts can also perform additional tasks. For example: + + + + + Installing software that is required for a specific task + + + + + Creating or modifying any configuration files + + + + + Collecting information and reporting potential problems with the cluster + + + + + Deploying the changes to all nodes + + + - &crmsh; cluster scripts do not replace other tools for managing - clusters—they provide an integrated way to perform the above - tasks across the cluster. Find detailed information at . + + Cluster scripts don't replace other tools for managing clusters, but they provide an integrated way to perform the above tasks across the cluster. - To get a list of all available cluster scripts, run: - &prompt.root;crm script list - To view the components of a script, use the - show command and the name of the cluster script, - for example: - &prompt.root;crm script show mailto + + + + Log in either as the &rootuser; user or as a user with sudo privileges. + + + + + Show a list of all available cluster scripts: + +&prompt.user;sudo crm script list + + + + View the components of a script: + +&prompt.user;sudo crm script show SCRIPT + + For example: + +&prompt.user;sudo crm script show mailto mailto (Basic) -MailTo +E-mail - This is a resource agent for MailTo. It sends email to a sysadmin -whenever a takeover occurs. +Notifies recipient by e-mail in the event of a resource takeover. 1. Notifies recipients by email in the event of resource takeover @@ -70,110 +91,71 @@ whenever a takeover occurs. Email address subject Subject - - The output of show contains a title, a - short description, and a procedure. Each procedure is divided - into a series of steps, performed in the given order. - Each step contains a list of required and optional parameters, - along with a short description and its default value. - - Each cluster script understands a set of common parameters. - These parameters can be passed to any script: - - - Common parameters - - - - Parameter - Argument - Description - - - - - action - INDEX - If set, only execute a single action (index, as - returned by verify) - - - dry_run - BOOL - If set, simulate execution only (default: no) - - - nodes - LIST - List of nodes to execute the script for - - - port - NUMBER - Port to connect to - - - statefile - FILE - When single-stepping, the state is saved in the given - file - - - sudo - BOOL - If set, crm prompts for a sudo password and uses sudo - where appropriate (default: no) - - - timeout - NUMBER - Execution timeout in seconds (default: 600) - - - user - USER - Run script as the given user - - - -
- - Before running a cluster script, review the actions that it will - perform and verify its parameters to avoid problems. A cluster script - can potentially perform a series of actions and may fail for - various reasons. Thus, verifying your parameters before - running it helps to avoid problems. - For example, the mailto resource agent - requires a unique identifier and an e-mail address. To verify these - parameters, run: - &prompt.root;crm script verify mailto id=sysadmin email=&exampleuser_plain;@example.org + + The output of show contains a title, a short description, and a procedure. If necessary, each procedure is divided into steps, performed in the given order. Each step contains a list of required and optional parameters, along with a short description and its default value. + + + + + Review the actions the script will perform and verify its parameters: + +&prompt.user;sudo crm script verify SCRIPT PARAMETER=VALUE + + The verify command prints the steps the script will take and replaces any placeholders with your given parameters. If verify finds any problems, it reports them. For example: + +&prompt.user;sudo crm script verify mailto id=sysadmin email=&exampleuser_plain; +ERROR: script.verify: email=&exampleuser_plain; is not a valid email address +&prompt.user;sudo crm script verify mailto id=sysadmin email=&exampleuser_plain;@example.org 1. Ensure mail package is installed mailx 2. Configure cluster resources - primitive sysadmin MailTo + primitive sysadmin ocf:heartbeat:MailTo email="tux@example.org" op start timeout="10" op stop timeout="10" op monitor interval="10" timeout="10" clone c-sysadmin sysadmin - The verify command prints the steps and replaces - any placeholders with your given parameters. If verify - finds any problems, it reports it. - If everything is OK, replace the verify - command with run: - &prompt.root;crm script run mailto id=sysadmin email=&exampleuser_plain;@example.org -INFO: MailTo + + + + If everything is fine, replace verify with run: + +&prompt.user;sudo crm script run SCRIPT PARAMETER=VALUE + + For example: + +&prompt.user;sudo crm script run mailto id=sysadmin email=&exampleuser_plain;@example.org +INFO: E-Mail INFO: Nodes: &node1;, &node2; -OK: Ensure mail package is installed -OK: Configure cluster resources - Check whether your resource is integrated into your cluster - with crm status: - &prompt.root;crm status +INFO: Ensure mail package is installed +INFO: Configure cluster resources + + + + Check whether the resource was added to the cluster: + +&prompt.user;sudo crm status [...] - Clone Set: c-sysadmin [sysadmin] - Started: [ &node1; &node2; ] + * Clone Set: c-sysadmin [sysadmin]: + * Started: [ &node1; &node2; ] + + + + + For more information + + + crm help script + + + + + + + + diff --git a/tasks/ha-crmsh-using-shell-scripts.xml b/tasks/ha-crmsh-using-shell-scripts.xml index 36cef1c9b..6600a1193 100644 --- a/tasks/ha-crmsh-using-shell-scripts.xml +++ b/tasks/ha-crmsh-using-shell-scripts.xml @@ -18,35 +18,45 @@ - The &crmsh; shell scripts provide a convenient way to enumerate &crmsh; - subcommands into a file. This makes it easy to comment specific lines or - to replay them later. Keep in mind that a &crmsh; shell script can contain - only &crmsh; subcommands. Any other commands are not - allowed. + You can use &crmshell; scripts to group multiple &crmsh; subcommands in a single file, + making it easier to rerun them later. A &crmshell; script can only + contain crm subcommands. Any other commands are not allowed. - - Before you can use a &crmsh; shell script, create a file with specific - commands. For example, the following file prints the status of the cluster - and gives a list of all nodes: - - - A simple &crmsh; shell script - # A small example file with some crm subcommands + + + + 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 list - - - Any line starting with the hash symbol (#) is a - comment and is ignored. If a line is too long, insert a backslash - (\) at the end and continue in the next line. We - recommend that you indent lines belonging to a certain subcommand to improve - readability. - - - To use this script, use one of the following methods: - &prompt.root;crm -f example.cli -&prompt.root;crm < example.cli +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 + + From eb3d8968182452406900650d7b9a99d7b925f420 Mon Sep 17 00:00:00 2001 From: Tahlia Richardson <3069029+tahliar@users.noreply.github.com> Date: Tue, 11 Aug 2026 15:36:57 +1000 Subject: [PATCH 08/13] Add snippets --- concepts/ha-crmsh-what-is.xml | 55 ++++----------------- snippets/ha-crmsh-cluster-scripts.xml | 16 ++++++ snippets/ha-crmsh-shell-scripts.xml | 14 ++++++ tasks/ha-crmsh-setting-secret-passwords.xml | 53 +++++++++++--------- tasks/ha-crmsh-using-cluster-scripts.xml | 38 +------------- tasks/ha-crmsh-using-interactive-mode.xml | 12 +++-- tasks/ha-crmsh-using-shell-scripts.xml | 6 +-- 7 files changed, 79 insertions(+), 115 deletions(-) create mode 100644 snippets/ha-crmsh-cluster-scripts.xml create mode 100644 snippets/ha-crmsh-shell-scripts.xml diff --git a/concepts/ha-crmsh-what-is.xml b/concepts/ha-crmsh-what-is.xml index d8fb38e6b..f97cfe933 100644 --- a/concepts/ha-crmsh-what-is.xml +++ b/concepts/ha-crmsh-what-is.xml @@ -36,11 +36,15 @@ - Directly + Command line Run a single crm command in full, including a subcommand and parameters, directly in your terminal. + + The &crmsh; supports full tab completion in Bash directly. For example, typing crm help + config completes the word. + @@ -63,31 +67,16 @@ Shell scripts - - &crmshell; scripts contain subcommands of crm. For more information, see xref linkend="sec-ha-manual-config-crmshellscripts"/. - + Cluster scripts - - These are a collection of metadata, references to RPM packages, configuration files, and &crmsh; subcommands bundled under a single, yet descriptive name. They are managed through the crm script command. - - Do not confuse them with &crmsh; shell scripts: although both share some common objectives, the &crmshell; scripts only contain subcommands whereas cluster scripts incorporate much more than a simple enumeration of commands. For more information, see xref linkend="sec-ha-manual-config-clusterscripts"/. - + - - Use tab completion in Bash and interactive shell - - The &crmsh; supports full tab completion in Bash directly, not only - for the interactive shell. For example, typing crm help - config completes the word - like in the interactive shell. - -
@@ -112,34 +101,8 @@ created by default during the cluster installation). This user can make changes to the CIB, but has limited privileges for operations that use SSH, such as crm report. - - Unprivileged users - - The option allows you to run crm and its - subcommands as a regular (unprivileged) user, and to change its ID using - sudo when necessary. For example, the following command sets - hacluster as the privileged user ID: - - &prompt.root;crm options user hacluster - - You must set up /etc/sudoers so that sudo - does not ask for a password. - - - - For operations that use SSH, the cluster uses passwordless SSH access for communication - between the nodes. If you set up the cluster with crm cluster init, the - script checks for SSH keys and generates them if they do not already exist. If you set up - the cluster with the &yast; cluster module, 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, but requires additional configuration. -
@@ -148,13 +111,13 @@ For operations that use SSH, the cluster uses passwordless SSH access for communication between the nodes. If you set up the cluster with crm cluster init, the script checks for SSH keys and generates them if they do not already exist. If you set up - the cluster with the &yast; cluster module, you must configure the SSH keys yourself. + 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, but requires additional configuration. + if you need to avoid storing SSH keys on the nodes.
diff --git a/snippets/ha-crmsh-cluster-scripts.xml b/snippets/ha-crmsh-cluster-scripts.xml new file mode 100644 index 000000000..274573d95 --- /dev/null +++ b/snippets/ha-crmsh-cluster-scripts.xml @@ -0,0 +1,16 @@ + + + %entities; +]> + + You can use cluster scripts to automate certain tasks. Unlike shell scripts, + which can only contain crm subcommands, cluster scripts + can also perform additional tasks, such as installing required packages, creating or modifying + configuration files, and deploying changes to all nodes. &sleha; comes with preconfigured + cluster scripts that are managed with the crm script command. + 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-setting-secret-passwords.xml b/tasks/ha-crmsh-setting-secret-passwords.xml index 397c16ea4..a36239523 100644 --- a/tasks/ha-crmsh-setting-secret-passwords.xml +++ b/tasks/ha-crmsh-setting-secret-passwords.xml @@ -20,43 +20,50 @@ Temporary title; there's a better way to put it + + If your cluster configuration contains sensitive information, such as passwords, it should be stored in local files. That way, these parameters will never be logged or leaked in support reports. To avoid accidental data exposure. Independent of cib.xml. + - - If your cluster configuration contains sensitive information, such - as passwords, it should be stored in local files. That way, these - parameters will never be logged or leaked in support reports. - - - - Before using secret, run the - show command to get an overview of all your - resources: - -&prompt.root;crm configure show -primitive mydb mysql \ - params replication_user=admin ... - - To set a password for the above mydb + + + + Log in either as the &rootuser; user or as a user with sudo privileges. + + + + + To set a password for the above mydb resource, use the following commands: - - + + &prompt.root;crm resource secret mydb set passwd linux INFO: syncing /var/lib/heartbeat/lrm/secrets/mydb/passwd to [your node list] - - - You can get the saved password back with: - - + + + + You can get the saved password back with: + &prompt.root;crm resource secret mydb show passwd linux + + The parameters need to be synchronized between nodes; the crm resource secret command takes care of that. We highly recommend that you only use this command to manage secret parameters. + + + For more information + + + crm resource help secret + + + diff --git a/tasks/ha-crmsh-using-cluster-scripts.xml b/tasks/ha-crmsh-using-cluster-scripts.xml index 4b9ba0a6c..23c409e96 100644 --- a/tasks/ha-crmsh-using-cluster-scripts.xml +++ b/tasks/ha-crmsh-using-cluster-scripts.xml @@ -17,46 +17,10 @@ Using &crmsh;'s cluster scripts - - Collecting information from all cluster nodes and deploying any - changes is a key cluster administration task. Instead of performing - the same procedures manually on different nodes (which is error-prone), - you can use the &crmsh; cluster scripts. - Do not confuse them with the &crmsh; shell scripts. - + - - Unlike &crmshell; scripts, which can only contain crm subcommands, cluster scripts can also perform additional tasks. For example: - - - - - Installing software that is required for a specific task - - - - - Creating or modifying any configuration files - - - - - Collecting information and reporting potential problems with the cluster - - - - - Deploying the changes to all nodes - - - - - - Cluster scripts don't replace other tools for managing clusters, but they provide an integrated way to perform the above tasks across the cluster. - - diff --git a/tasks/ha-crmsh-using-interactive-mode.xml b/tasks/ha-crmsh-using-interactive-mode.xml index d26a468c3..489d01f38 100644 --- a/tasks/ha-crmsh-using-interactive-mode.xml +++ b/tasks/ha-crmsh-using-interactive-mode.xml @@ -18,7 +18,7 @@ - TBD + By calling crm without arguments, or by calling it with only a sublevel as argument, crm enters the interactive mode. In this mode, it acts as its own command shell, which remembers which sublevel you are currently in and allows for rapid and convenient execution of multiple commands within the same sublevel. This mode also has full tab completion, as well as built-in interactive help and syntax highlighting. @@ -32,13 +32,17 @@ argument), the &crmshell; enters the interactive mode. This mode is indicated by the following prompt: - crm(live/HOSTNAME) +crm(live/HOSTNAME)# For readability reasons, we omit the host name in the interactive crm - prompts in our documentation. We only include the host name if you need + prompts in our documentation: + +crm(live)# + + We only include the host name if you need to run the interactive shell on a specific node, like &node1; for example: - crm(live/&node1;) +crm(live/&node1;)# Interactive as internal shell: diff --git a/tasks/ha-crmsh-using-shell-scripts.xml b/tasks/ha-crmsh-using-shell-scripts.xml index 6600a1193..7aec12d4c 100644 --- a/tasks/ha-crmsh-using-shell-scripts.xml +++ b/tasks/ha-crmsh-using-shell-scripts.xml @@ -17,11 +17,7 @@ Using &crmsh;'s shell scripts - - You can use &crmshell; scripts to group multiple &crmsh; subcommands in a single file, - making it easier to rerun them later. A &crmshell; script can only - contain crm subcommands. Any other commands are not allowed. - + From b895ed2bcbc9e3ee90e4f798ff323eb1c8376307 Mon Sep 17 00:00:00 2001 From: Tahlia Richardson <3069029+tahliar@users.noreply.github.com> Date: Thu, 13 Aug 2026 18:12:52 +1000 Subject: [PATCH 09/13] Editing --- articles/ha-crmsh-introduction.asm.xml | 11 +- concepts/ha-crmsh-what-is.xml | 61 ++++----- concepts/ha-what-is.xml | 6 +- snippets/ha-crmsh-interactive-mode.xml | 18 +++ snippets/ha-crmsh.xml | 14 ++ tasks/ha-crmsh-setting-secret-passwords.xml | 24 ++-- tasks/ha-crmsh-using-interactive-mode.xml | 134 ++++++++++++-------- 7 files changed, 158 insertions(+), 110 deletions(-) create mode 100644 snippets/ha-crmsh-interactive-mode.xml create mode 100644 snippets/ha-crmsh.xml diff --git a/articles/ha-crmsh-introduction.asm.xml b/articles/ha-crmsh-introduction.asm.xml index 13d80fc8d..316f34103 100644 --- a/articles/ha-crmsh-introduction.asm.xml +++ b/articles/ha-crmsh-introduction.asm.xml @@ -71,8 +71,8 @@ &productname; Introduction to the &crmshell; - TODO - TODO + How to install, configure and manage &ha; clusters using the &crmshell; command-line interface + Manage &ha; clusters with the &crmshell; Administration @@ -96,6 +96,13 @@ WHY EFFORT GOAL--> + TODO diff --git a/concepts/ha-crmsh-what-is.xml b/concepts/ha-crmsh-what-is.xml index f97cfe933..f696d8abc 100644 --- a/concepts/ha-crmsh-what-is.xml +++ b/concepts/ha-crmsh-what-is.xml @@ -18,13 +18,12 @@ What is the &crmshell;? + - The &crmshell; (&crmsh;) is a command-line interface for installing, - configuring and managing &ha; clusters. You can run most &crmsh; commands from any node - in the cluster. - - - This section introduces the command-line tool crm. The crm command has several subcommands which manage resources, CIBs, nodes, resource agents, and others. It offers a thorough help system with embedded examples. Events are logged to /var/log/crmsh/crmsh.log. + 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. Events are logged to /var/log/crmsh/crmsh.log. @@ -32,36 +31,25 @@
Using the &crmshell; - You can use the crm command in multiple ways: + You can use the &crmshell; in multiple ways: - Command line + Command line (single-shot) - Run a single crm command in full, including a subcommand and parameters, directly in your terminal. - - - The &crmsh; supports full tab completion in Bash directly. For example, typing crm help - config completes the word. + 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 - - Type crm to enter the internal shell. The prompt changes to crm(live). With help you can get an overview of the available subcommands. As the internal shell has different levels of subcommands, you can enter one by typing this subcommand and press . - - - For example, if you type resource you enter the resource management level. Your prompt changes to crm(live)resource#. To leave the internal shell, use the command quit. If you need to go one level back, use back, up, end, or cd. - - - You can enter the level directly by typing crm and the respective subcommand without any options and press . - - - The internal shell supports also tab completion for subcommands and resources. Type the beginning of a command, press and crm completes the respective object. - + @@ -89,17 +77,17 @@ The &rootuser; user or a user with sudo privileges. These users have - full privileges on all cluster nodes by using SSH for &crmsh; operations such as - crm cluster init, crm cluster join, and - crm report. They can also make changes to the CIB, - such as adding resources and constraints. + 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 (typically the user hacluster, - created by default during the cluster installation). This user can make changes to the CIB, - but has limited privileges for operations that use SSH, such as crm report. + 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. @@ -109,8 +97,8 @@ SSH key authentication For operations that use SSH, the cluster uses passwordless SSH access for communication - between the nodes. If you set up the cluster with crm cluster init, the - script checks for SSH keys and generates them if they do not already exist. If you set up + 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. @@ -134,11 +122,6 @@ crm help overview - - - - - diff --git a/concepts/ha-what-is.xml b/concepts/ha-what-is.xml index e32aad696..fd2421c3f 100644 --- a/concepts/ha-what-is.xml +++ b/concepts/ha-what-is.xml @@ -162,11 +162,7 @@ - - The &crmshell; (&crmsh;) is a command-line interface for - installing, configuring and managing &ha; clusters. You can run most &crmsh; - commands from any node in the cluster. - + 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.xml b/snippets/ha-crmsh.xml new file mode 100644 index 000000000..408aa2927 --- /dev/null +++ b/snippets/ha-crmsh.xml @@ -0,0 +1,14 @@ + + + %entities; +]> + + The &crmshell; (&crmsh;) is a command-line interface for installing, + configuring and managing &ha; clusters. You can run most &crmshell; commands from any node + in the cluster. + diff --git a/tasks/ha-crmsh-setting-secret-passwords.xml b/tasks/ha-crmsh-setting-secret-passwords.xml index a36239523..2b8a55d75 100644 --- a/tasks/ha-crmsh-setting-secret-passwords.xml +++ b/tasks/ha-crmsh-setting-secret-passwords.xml @@ -14,20 +14,17 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:trans="http://docbook.org/ns/transclusion"> - Setting secret passwords + Managing sensitive parameters - Temporary title; there's a better way to put it - - + By default, the &crmshell; obscures passwords in the output of commands like crm configure show. To further obscure sensitive parameters from the raw CIB data, you can use the crm resource secret command. the crm subcommand version of the cibsecret command. If your cluster configuration contains sensitive information, such as passwords, it should be stored in local files. That way, these parameters will never be logged or leaked in support reports. To avoid accidental data exposure. Independent of cib.xml. + Sensitive parameters can be kept in local files rather than CIB in order to prevent accidental data exposure. - - @@ -39,7 +36,6 @@ To set a password for the above mydb resource, use the following commands: - &prompt.root;crm resource secret mydb set passwd linux INFO: syncing /var/lib/heartbeat/lrm/secrets/mydb/passwd to [your node list] @@ -49,15 +45,12 @@ INFO: syncing /var/lib/heartbeat/lrm/secrets/mydb/passwd to [your node list] &prompt.root;crm resource secret mydb show passwd linux + + Node bob is down - you'll need to update it with `cibsecret sync` later + - - The parameters need to be synchronized between nodes; the - crm resource secret command takes care of that. We - highly recommend that you only use this command to manage secret parameters. - - For more information @@ -65,5 +58,10 @@ linux crm resource help secret + + + cibsecret --help + + diff --git a/tasks/ha-crmsh-using-interactive-mode.xml b/tasks/ha-crmsh-using-interactive-mode.xml index 489d01f38..05954d095 100644 --- a/tasks/ha-crmsh-using-interactive-mode.xml +++ b/tasks/ha-crmsh-using-interactive-mode.xml @@ -17,63 +17,95 @@ Using &crmsh;'s interactive mode - - By calling crm without arguments, or by calling it with only a sublevel as argument, crm enters the interactive mode. In this mode, it acts as its own command shell, which remembers which sublevel you are currently in and allows for rapid and convenient execution of multiple commands within the same sublevel. This mode also has full tab completion, as well as built-in interactive help and syntax highlighting. - + - - crm configure, create resource, add constraints, commit - - - Interactive crm prompt - By using crm without arguments (or with only one sublevel as - argument), the &crmshell; enters the interactive mode. This mode is - indicated by the following prompt: - -crm(live/HOSTNAME)# - - For readability reasons, we omit the host name in the interactive crm - prompts in our documentation: - + + + + 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)# - - We only include the host name if you need - to run the interactive shell on a specific node, like &node1; for example: - -crm(live/&node1;)# - - - Interactive as internal shell: + + 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; + + + - Type crm to enter the internal shell. The prompt - changes to crm(live). With - help you can get an overview of the available - subcommands. As the internal shell has different levels of - subcommands, you can enter one by typing this - subcommand and press . + You can navigate interactive mode with the following options: - - - For example, if you type resource you enter the - resource management level. Your prompt changes to - crm(live)resource#. To leave the - internal shell, use the command quit. If you need to go - one level back, use back, up, - end, or cd. - - - You can enter the level directly by typing crm and - the respective subcommand without any options and press - . - - - The internal shell supports also tab completion for subcommands and - resources. Type the beginning of a command, press - and crm completes the - respective object. - + + + + 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. Example: create resource and add constraints + +&prompt.crm;configure +&prompt.crm.conf;primitive vip1 IPaddr2 params ip=&subnetI;.5 +&prompt.crm.conf;location loc-vip-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 From 495c4a5f07fb3e38945a4431766081dd0f26f9ad Mon Sep 17 00:00:00 2001 From: Tahlia Richardson <3069029+tahliar@users.noreply.github.com> Date: Fri, 14 Aug 2026 15:57:57 +1000 Subject: [PATCH 10/13] Add intro abstract --- articles/ha-crmsh-introduction.asm.xml | 24 ++-- concepts/ha-crmsh-what-is.xml | 11 +- concepts/ha-what-is.xml | 6 +- snippets/ha-crmsh.xml | 14 --- ...ha-crmsh-managing-sensitive-parameters.xml | 118 ++++++++++++++++++ tasks/ha-crmsh-setting-secret-passwords.xml | 67 ---------- tasks/ha-crmsh-using-interactive-mode.xml | 15 ++- 7 files changed, 152 insertions(+), 103 deletions(-) delete mode 100644 snippets/ha-crmsh.xml create mode 100644 tasks/ha-crmsh-managing-sensitive-parameters.xml delete mode 100644 tasks/ha-crmsh-setting-secret-passwords.xml diff --git a/articles/ha-crmsh-introduction.asm.xml b/articles/ha-crmsh-introduction.asm.xml index 316f34103..9b369d0d6 100644 --- a/articles/ha-crmsh-introduction.asm.xml +++ b/articles/ha-crmsh-introduction.asm.xml @@ -30,7 +30,7 @@ - + @@ -92,24 +92,16 @@ yes - - - TODO + 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: - TODO - TODO + Access to a cluster node with &rootuser; privileges or &sudo; authorization + Passwordless SSH key authentication between the cluster nodes @@ -141,7 +133,7 @@ - + diff --git a/concepts/ha-crmsh-what-is.xml b/concepts/ha-crmsh-what-is.xml index f696d8abc..d6d6707a2 100644 --- a/concepts/ha-crmsh-what-is.xml +++ b/concepts/ha-crmsh-what-is.xml @@ -18,12 +18,19 @@ 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. Events are logged to /var/log/crmsh/crmsh.log. + examples. You can run most crm commands from any node in the cluster. + + + &crmshell; events are logged to /var/log/crmsh/crmsh.log. diff --git a/concepts/ha-what-is.xml b/concepts/ha-what-is.xml index fd2421c3f..e965e5735 100644 --- a/concepts/ha-what-is.xml +++ b/concepts/ha-what-is.xml @@ -162,7 +162,11 @@ - + + The &crmshell; (&crmsh;) is a command-line interface for + installing, configuring and managing &sleha; clusters. You can run most &crmshell; + commands from any node in the cluster. + diff --git a/snippets/ha-crmsh.xml b/snippets/ha-crmsh.xml deleted file mode 100644 index 408aa2927..000000000 --- a/snippets/ha-crmsh.xml +++ /dev/null @@ -1,14 +0,0 @@ - - - %entities; -]> - - The &crmshell; (&crmsh;) is a command-line interface for installing, - configuring and managing &ha; clusters. You can run most &crmshell; commands from any node - in the cluster. - 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-setting-secret-passwords.xml b/tasks/ha-crmsh-setting-secret-passwords.xml deleted file mode 100644 index 2b8a55d75..000000000 --- a/tasks/ha-crmsh-setting-secret-passwords.xml +++ /dev/null @@ -1,67 +0,0 @@ - - - %entities; -]> - - - - - Managing sensitive parameters - - - - By default, the &crmshell; obscures passwords in the output of commands like crm configure show. To further obscure sensitive parameters from the raw CIB data, you can use the crm resource secret command. the crm subcommand version of the cibsecret command. - If your cluster configuration contains sensitive information, such as passwords, it should be stored in local files. That way, these parameters will never be logged or leaked in support reports. To avoid accidental data exposure. Independent of cib.xml. - Sensitive parameters can be kept in local files rather than CIB in order to prevent accidental data exposure. - - - - - - - - Log in either as the &rootuser; user or as a user with sudo privileges. - - - - - To set a password for the above mydb - resource, use the following commands: - -&prompt.root;crm resource secret mydb set passwd linux -INFO: syncing /var/lib/heartbeat/lrm/secrets/mydb/passwd to [your node list] - - - - You can get the saved password back with: - -&prompt.root;crm resource secret mydb show passwd -linux - - Node bob is down - you'll need to update it with `cibsecret sync` later - - - - - - For more information - - - crm resource help secret - - - - - cibsecret --help - - - - diff --git a/tasks/ha-crmsh-using-interactive-mode.xml b/tasks/ha-crmsh-using-interactive-mode.xml index 05954d095..ae19e82ec 100644 --- a/tasks/ha-crmsh-using-interactive-mode.xml +++ b/tasks/ha-crmsh-using-interactive-mode.xml @@ -82,12 +82,19 @@ - Make your changes. Example: create resource and add constraints + 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-vip-alice vip1 inf: alice +&prompt.crm.conf;location loc-vip1-on-alice vip1 inf: alice &prompt.crm.conf;show changed + @@ -95,7 +102,9 @@ &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. + 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. From b45cc6b5e0e539385d4e75e7f720a19bf2a9cb70 Mon Sep 17 00:00:00 2001 From: Tahlia Richardson <3069029+tahliar@users.noreply.github.com> Date: Fri, 14 Aug 2026 16:06:16 +1000 Subject: [PATCH 11/13] Remove unused file --- tasks/ha-crmsh-generating-cluster-diagram.xml | 36 ------------------- 1 file changed, 36 deletions(-) delete mode 100644 tasks/ha-crmsh-generating-cluster-diagram.xml diff --git a/tasks/ha-crmsh-generating-cluster-diagram.xml b/tasks/ha-crmsh-generating-cluster-diagram.xml deleted file mode 100644 index 83544e087..000000000 --- a/tasks/ha-crmsh-generating-cluster-diagram.xml +++ /dev/null @@ -1,36 +0,0 @@ - - - %entities; -]> - - - - - Generating a cluster diagram - - - - TODO - - - - - - To output a cluster diagram, use the command - crm configure graph. It displays - the current configuration on its current window, therefore requiring - X11. - - - If you prefer Scalable Vector Graphics (SVG), use the following command: - -&prompt.root;crm configure graph dot config.svg svg - From 34aa892d1a8b86747120f425c171ffb40dffdf29 Mon Sep 17 00:00:00 2001 From: Tahlia Richardson <3069029+tahliar@users.noreply.github.com> Date: Thu, 27 Aug 2026 14:51:05 +1000 Subject: [PATCH 12/13] Remove cluster scripts --- articles/ha-crmsh-introduction.asm.xml | 6 -- concepts/ha-crmsh-what-is.xml | 6 -- snippets/ha-crmsh-cluster-scripts.xml | 16 --- tasks/ha-crmsh-using-cluster-scripts.xml | 125 ----------------------- 4 files changed, 153 deletions(-) delete mode 100644 snippets/ha-crmsh-cluster-scripts.xml delete mode 100644 tasks/ha-crmsh-using-cluster-scripts.xml diff --git a/articles/ha-crmsh-introduction.asm.xml b/articles/ha-crmsh-introduction.asm.xml index 9b369d0d6..73c5358d9 100644 --- a/articles/ha-crmsh-introduction.asm.xml +++ b/articles/ha-crmsh-introduction.asm.xml @@ -27,7 +27,6 @@ - @@ -126,11 +125,6 @@ Using shell scripts - - - Using cluster scripts - - diff --git a/concepts/ha-crmsh-what-is.xml b/concepts/ha-crmsh-what-is.xml index d6d6707a2..7b17918b1 100644 --- a/concepts/ha-crmsh-what-is.xml +++ b/concepts/ha-crmsh-what-is.xml @@ -65,12 +65,6 @@ - - Cluster scripts - - - -
diff --git a/snippets/ha-crmsh-cluster-scripts.xml b/snippets/ha-crmsh-cluster-scripts.xml deleted file mode 100644 index 274573d95..000000000 --- a/snippets/ha-crmsh-cluster-scripts.xml +++ /dev/null @@ -1,16 +0,0 @@ - - - %entities; -]> - - You can use cluster scripts to automate certain tasks. Unlike shell scripts, - which can only contain crm subcommands, cluster scripts - can also perform additional tasks, such as installing required packages, creating or modifying - configuration files, and deploying changes to all nodes. &sleha; comes with preconfigured - cluster scripts that are managed with the crm script command. - diff --git a/tasks/ha-crmsh-using-cluster-scripts.xml b/tasks/ha-crmsh-using-cluster-scripts.xml deleted file mode 100644 index 23c409e96..000000000 --- a/tasks/ha-crmsh-using-cluster-scripts.xml +++ /dev/null @@ -1,125 +0,0 @@ - - - %entities; -]> - - - - - Using &crmsh;'s cluster scripts - - - - - - - - - - Log in either as the &rootuser; user or as a user with sudo privileges. - - - - - Show a list of all available cluster scripts: - -&prompt.user;sudo crm script list - - - - View the components of a script: - -&prompt.user;sudo crm script show SCRIPT - - For example: - -&prompt.user;sudo crm script show mailto -mailto (Basic) -E-mail - -Notifies recipient by e-mail in the event of a resource takeover. - -1. Notifies recipients by email in the event of resource takeover - - id (required) (unique) - Identifier for the cluster resource - email (required) - Email address - subject - Subject - - The output of show contains a title, a short description, and a procedure. If necessary, each procedure is divided into steps, performed in the given order. Each step contains a list of required and optional parameters, along with a short description and its default value. - - - - - Review the actions the script will perform and verify its parameters: - -&prompt.user;sudo crm script verify SCRIPT PARAMETER=VALUE - - The verify command prints the steps the script will take and replaces any placeholders with your given parameters. If verify finds any problems, it reports them. For example: - -&prompt.user;sudo crm script verify mailto id=sysadmin email=&exampleuser_plain; -ERROR: script.verify: email=&exampleuser_plain; is not a valid email address -&prompt.user;sudo crm script verify mailto id=sysadmin email=&exampleuser_plain;@example.org -1. Ensure mail package is installed - - mailx - -2. Configure cluster resources - - primitive sysadmin ocf:heartbeat:MailTo - email="tux@example.org" - op start timeout="10" - op stop timeout="10" - op monitor interval="10" timeout="10" - - clone c-sysadmin sysadmin - - - - If everything is fine, replace verify with run: - -&prompt.user;sudo crm script run SCRIPT PARAMETER=VALUE - - For example: - -&prompt.user;sudo crm script run mailto id=sysadmin email=&exampleuser_plain;@example.org -INFO: E-Mail -INFO: Nodes: &node1;, &node2; -INFO: Ensure mail package is installed -INFO: Configure cluster resources - - - - Check whether the resource was added to the cluster: - -&prompt.user;sudo crm status -[...] - * Clone Set: c-sysadmin [sysadmin]: - * Started: [ &node1; &node2; ] - - - - - For more information - - - crm help script - - - - - - - - - From fbbfb71212535c19e421d4ea703740321f978c64 Mon Sep 17 00:00:00 2001 From: Tahlia Richardson <3069029+tahliar@users.noreply.github.com> Date: Thu, 27 Aug 2026 15:03:22 +1000 Subject: [PATCH 13/13] Add crm help cib --- tasks/ha-crmsh-testing-with-shadow-configuration.xml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/tasks/ha-crmsh-testing-with-shadow-configuration.xml b/tasks/ha-crmsh-testing-with-shadow-configuration.xml index 39aaba430..6e40b93bc 100644 --- a/tasks/ha-crmsh-testing-with-shadow-configuration.xml +++ b/tasks/ha-crmsh-testing-with-shadow-configuration.xml @@ -102,5 +102,10 @@ INFO: configure.cib.reset: copied live CIB to test1 crm help shadows + + + crm help cib + +