From 5ee5d679e185d0ce1a351881b90a13c1460f69db Mon Sep 17 00:00:00 2001 From: Ken Gaillot Date: Wed, 23 Oct 2024 11:02:26 -0500 Subject: [PATCH 1/6] Doc: m4: update Pacemaker URL For older versions, the site will redirect the old URL to the new one. --- m4/version.m4 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/m4/version.m4 b/m4/version.m4 index 96277dfcd20..f49a9f0d478 100644 --- a/m4/version.m4 +++ b/m4/version.m4 @@ -1,2 +1,2 @@ m4_define([VERSION_NUMBER], [2.1.9]) -m4_define([PCMK_URL], [https://ClusterLabs.org/pacemaker/]) +m4_define([PCMK_URL], [https://ClusterLabs.org/projects/pacemaker/]) From e54eac6360f6e94edb3bdd7e8ee1759447402b46 Mon Sep 17 00:00:00 2001 From: Ken Gaillot Date: Wed, 23 Oct 2024 11:04:41 -0500 Subject: [PATCH 2/6] Doc: crm_fencing: drop deprecated documentation The updated website no longer references it. Pacemaker Explained's fencing chapter is sufficient to replace it. --- doc/Makefile.am | 29 +-- doc/crm_fencing.txt | 439 -------------------------------------------- 2 files changed, 3 insertions(+), 465 deletions(-) delete mode 100644 doc/crm_fencing.txt diff --git a/doc/Makefile.am b/doc/Makefile.am index 448d03b867f..308d86d6d70 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,5 +1,5 @@ # -# Copyright 2003-2023 the Pacemaker project contributors +# Copyright 2003-2024 the Pacemaker project contributors # # The version control history for this file may have further details. # @@ -22,22 +22,10 @@ BOOK_FORMATS ?= html \ mibdir = $(datadir)/snmp/mibs dist_mib_DATA = PCMK-MIB.txt -# Deprecated plaintext documents (dynamically converted to HTML) -DEPRECATED_ORIGINAL = crm_fencing.txt -DEPRECATED_GENERATED = -if BUILD_ASCIIDOC -DEPRECATED_GENERATED += $(DEPRECATED_ORIGINAL:%.txt=%.html) -endif -DEPRECATED_ALL = $(DEPRECATED_ORIGINAL) \ - $(DEPRECATED_GENERATED) - -doc_DATA = $(DEPRECATED_ALL) noinst_SCRIPTS = abi-check SUBDIRS = sphinx -EXTRA_DIST = $(DEPRECATED_ORIGINAL) - # toplevel rsync destination for www targets (without trailing slash) RSYNC_DEST ?= sites.clusterlabs.org:/var/www/html @@ -59,21 +47,10 @@ endif # For Makefile debugging .PHONY: vars vars: - @echo DEPRECATED_ORIGINAL=\'$(DEPRECATED_ORIGINAL)\' - @echo DEPRECATED_GENERATED=\'$(DEPRECATED_GENERATED)\' @echo LAST_RELEASE=\'$(LAST_RELEASE)\' @echo TAG=\'$(TAG)\' -.PHONY: deprecated-upload -deprecated-upload: $(DEPRECATED_ALL) - rsync $(RSYNC_OPTS) $(DEPRECATED_ALL) "$(RSYNC_DEST)/$(PACKAGE)/doc/" - -.PHONY: deprecated-clean -deprecated-clean: - -rm -f $(DEPRECATED_GENERATED) - - # Annotated source code as HTML # Cleaning first ensures we don't index unrelated stuff like RPM sources @@ -158,10 +135,10 @@ books-upload: # All online documentation (except ABI compatibility, which is run separately) .PHONY: www -www: clean-local deprecated-upload manhtml-upload global-upload doxygen-upload books-upload +www: clean-local manhtml-upload global-upload doxygen-upload books-upload .PHONY: clean-local -clean-local: global-clean manhtml-clean doxygen-clean abi-clean deprecated-clean +clean-local: global-clean manhtml-clean doxygen-clean abi-clean # "make check" will cause "make all" to be run, which means docs will get built # as a part of running tests if they haven't already. That seems unnecessary, so diff --git a/doc/crm_fencing.txt b/doc/crm_fencing.txt deleted file mode 100644 index 26acde76710..00000000000 --- a/doc/crm_fencing.txt +++ /dev/null @@ -1,439 +0,0 @@ -Fencing and Stonith -=================== -Dejan_Muhamedagic -v0.9 - -Fencing is a very important concept in computer clusters for HA -(High Availability). Unfortunately, given that fencing does not -offer a visible service to users, it is often neglected. - -Fencing may be defined as a method to bring an HA cluster to a -known state. But, what is a "cluster state" after all? To answer -that question we have to see what is in the cluster. - -== Introduction to HA clusters - -Any computer cluster may be loosely defined as a collection of -cooperating computers or nodes. Nodes talk to each other over -communication channels, which are typically standard network -connections, such as Ethernet. - -The main purpose of an HA cluster is to manage user services. -Typical examples of user services are an Apache web server or, -say, a MySQL database. From the user's point of view, the -services do some specific and hopefully useful work when ordered -to do so. To the cluster, however, they are just things which may -be started or stopped. This distinction is important, because the -nature of the service is irrelevant to the cluster. In the -cluster lingo, the user services are known as resources. - -Every resource has a state attached, for instance: "resource r1 -is started on node1". In an HA cluster, such state implies that -"resource r1 is stopped on all nodes but node1", because an HA -cluster must make sure that every resource may be started on at -most one node. - -A collection of resource states and node states is the cluster -state. - -Every node must report every change that happens to resources. -This may happen only for the running resources, because a node -should not start resources unless told so by somebody. That -somebody is the Cluster Resource Manager (CRM) in our case. - -So far so good. But what if, for whatever reason, we cannot -establish with certainty a state of some node or resource? This -is where fencing comes in. With fencing, even when the cluster -doesn't know what is happening on some node, we can make sure -that that node doesn't run any or certain important resources. - -If you wonder how this can happen, there may be many risks -involved with computing: reckless people, power outages, natural -disasters, rodents, thieves, software bugs, just to name a few. -We are sure that at least a few times your computer failed -unpredictably. - -== Fencing - -There are two kinds of fencing: resource level and node level. - -Using the resource level fencing the cluster can make sure that -a node cannot access one or more resources. One typical example -is a SAN, where a fencing operation changes rules on a SAN switch -to deny access from a node. - -The resource level fencing may be achieved using normal resources -on which the resource we want to protect would depend. Such a -resource would simply refuse to start on this node and therefore -resources which depend on it will be unrunnable on the same node -as well. - -The node level fencing makes sure that a node does not run any -resources at all. This is usually done in a very simple, yet -brutal way: the node is simply reset using a power switch. This -may ultimately be necessary because the node may not be -responsive at all. - -The node level fencing is our primary subject below. - -== Node level fencing devices - -Before we get into the configuration details, you need to pick a -fencing device for the node level fencing. There are quite a few -to choose from. If you want to see the list of stonith devices -which are supported just run: - - stonith -L - -Stonith devices may be classified into five categories: - -- UPS (Uninterruptible Power Supply) - -- PDU (Power Distribution Unit) - -- Blade power control devices - -- Lights-out devices - -- Testing devices - -The choice depends mainly on your budget and the kind of -hardware. For instance, if you're running a cluster on a set of -blades, then the power control device in the blade enclosure is -the only candidate for fencing. Of course, this device must be -capable of managing single blade computers. - -The lights-out devices (IBM RSA, HP iLO, Dell DRAC) are becoming -increasingly popular and in future they may even become standard -equipment of of-the-shelf computers. They are, however, inferior -to UPS devices, because they share a power supply with their host -(a cluster node). If a node stays without power, the device -supposed to control it would be just as useless. Even though this -is obvious to us, the cluster manager is not in the know and will -try to fence the node in vain. This will continue forever because -all other resource operations would wait for the fencing/stonith -operation to succeed. - -The testing devices are used exclusively for testing purposes. -They are usually more gentle on the hardware. Once the cluster -goes into production, they must be replaced with real fencing -devices. - -== STONITH (Shoot The Other Node In The Head) - -Stonith is our fencing implementation. It provides the node level -fencing. - -.NB -The stonith and fencing terms are often used -interchangeably here as well as in other texts. - -The stonith subsystem consists of two components: - -- pacemaker-fenced - -- stonith plugins - -=== pacemaker-fenced - -pacemaker-fenced is a daemon which may be accessed by the local processes -or over the network. It accepts commands which correspond to -fencing operations: reset, power-off, and power-on. It may also -check the status of the fencing device. - -pacemaker-fenced runs on every node in the CRM HA cluster. The -pacemaker-fenced instance running on the DC node receives a fencing -request from the CRM. It is up to this and other pacemaker-fenced -programs to carry out the desired fencing operation. - -=== Stonith plugins - -For every supported fencing device there is a stonith plugin -which is capable of controlling that device. A stonith plugin is -the interface to the fencing device. All stonith plugins look the -same to pacemaker-fenced, but are quite different on the other side -reflecting the nature of the fencing device. - -Some plugins support more than one device. A typical example is -ipmilan (or external/ipmi) which implements the IPMI protocol and -can control any device which supports this protocol. - -== CRM stonith configuration - -The fencing configuration consists of one or more stonith -resources. - -A stonith resource is a resource of class stonith and it is -configured just like any other resource. The list of parameters -(attributes) depend on and are specific to a stonith type. Use -the stonith(1) program to see the list: - - $ stonith -t ibmhmc -n - ipaddr - $ stonith -t ipmilan -n - hostname ipaddr port auth priv login password reset_method - -.NB -It is easy to guess the class of a fencing device from -the set of attribute names. - -A short help text is also available: - - $ stonith -t ibmhmc -h - STONITH Device: ibmhmc - IBM Hardware Management Console (HMC) - Use for IBM i5, p5, pSeries and OpenPower systems managed by HMC - Optional parameter name managedsyspat is white-space delimited - list of patterns used to match managed system names; if last - character is '*', all names that begin with the pattern are matched - Optional parameter name password is password for hscroot if - passwordless ssh access to HMC has NOT been setup (to do so, - it is necessary to create a public/private key pair with - empty passphrase - see "Configure the OpenSSH client" in the - redbook for more details) - For more information see - http://publib-b.boulder.ibm.com/redbooks.nsf/RedbookAbstracts/SG247038.html - -.You just said that there is pacemaker-fenced and stonith plugins. What's with these resources now? -************************** -Resources of class stonith are just a representation of stonith -plugins in the CIB. Well, a bit more: apart from the fencing -operations, the stonith resources, just like any other, may be -started and stopped and monitored. The start and stop operations -are a bit of a misnomer: enable and disable would serve better, -but it's too late to change that. So, these two are actually -administrative operations and do not translate to any operation -on the fencing device itself. Monitor, however, does translate to -device status. -************************** - -A dummy stonith resource configuration, which may be used in some -testing scenarios is very simple: - - configure - primitive st-null stonith:null \ - params hostlist="node1 node2" - clone fencing st-null - commit - -.NB -************************** -All configuration examples are in the crm configuration tool -syntax. To apply them, put the sample in a text file, say -sample.txt and run: - - crm < sample.txt - -The configure and commit lines are omitted from further examples. -************************** - -An alternative configuration: - - primitive st-node1 stonith:null \ - params hostlist="node1" - primitive st-node2 stonith:null \ - params hostlist="node2" - location l-st-node1 st-node1 -inf: node1 - location l-st-node2 st-node2 -inf: node2 - -This configuration is perfectly alright as far as the cluster -software is concerned. The only difference to a real world -configuration is that no fencing operation takes place. - -A more realistic, but still only for testing, is the following -external/ssh configuration: - - primitive st-ssh stonith:external/ssh \ - params hostlist="node1 node2" - clone fencing st-ssh - -This one can also reset nodes. As you can see, this configuration -is remarkably similar to the first one which features the null -stonith device. - -.What is this clone thing? -************************** -Clones are a CRM/Pacemaker feature. A clone is basically a -shortcut: instead of defining _n_ identical, yet differently named -resources, a single cloned resource suffices. By far the most -common use of clones is with stonith resources if the stonith -device is accessible from all nodes. -************************** - -The real device configuration is not much different, though some -devices may require more attributes. For instance, an IBM RSA -lights-out device might be configured like this: - - primitive st-ibmrsa-1 stonith:external/ibmrsa-telnet \ - params nodename=node1 ipaddr=192.168.0.101 \ - userid=USERID passwd=PASSW0RD - primitive st-ibmrsa-2 stonith:external/ibmrsa-telnet \ - params nodename=node2 ipaddr=192.168.0.102 \ - userid=USERID passwd=PASSW0RD - # st-ibmrsa-1 can run anywhere but on node1 - location l-st-node1 st-ibmrsa-1 -inf: node1 - # st-ibmrsa-2 can run anywhere but on node2 - location l-st-node2 st-ibmrsa-2 -inf: node2 - -.Why those strange location constraints? -************************** -There is always certain probability that the stonith operation is -going to fail. Hence, a stonith operation on the node which is -the executioner too is not reliable. If the node is reset, then -it cannot send the notification about the fencing operation -outcome. -************************** - -If you haven't already guessed, configuration of a UPS kind of -fencing device is remarkably similar to all we have already -shown. - -All UPS devices employ the same mechanics for fencing. What is, -however, different is how the device itself is accessed. Old UPS -devices, those that were considered professional, used to have -just a serial port, typically connected at 1200baud using a -special serial cable. Many new ones still come equipped with a -serial port, but often they also sport a USB interface or an -Ethernet interface. The kind of connection we may make use of -depends on what the plugin supports. Let's see a few examples for -the APC UPS equipment: - - $ stonith -t apcmaster -h - - STONITH Device: apcmaster - APC MasterSwitch (via telnet) - NOTE: The APC MasterSwitch accepts only one (telnet) - connection/session a time. When one session is active, - subsequent attempts to connect to the MasterSwitch will fail. - For more information see http://www.apc.com/ - List of valid parameter names for apcmaster STONITH device: - ipaddr - login - password - - $ stonith -t apcsmart -h - - STONITH Device: apcsmart - APC Smart UPS - (via serial port - NOT USB!). - Works with higher-end APC UPSes, like - Back-UPS Pro, Smart-UPS, Matrix-UPS, etc. - (Smart-UPS may have to be >= Smart-UPS 700?). - See http://www.networkupstools.org/protocols/apcsmart.html - for protocol compatibility details. - For more information see http://www.apc.com/ - List of valid parameter names for apcsmart STONITH device: - ttydev - hostlist - -The former plugin supports APC UPS with a network port and telnet -protocol. The latter plugin uses the APC SMART protocol over the -serial line which is supported by many different APC UPS product -lines. - -.So, what do I use: clones, constraints, both? -************************** -It depends. Depends on the nature of the fencing device. For -example, if the device cannot serve more than one connection at -the time, then clones won't do. Depends on how many hosts can the -device manage. If it's only one, and that is always the case with -lights-out devices, then again clones are right out. Depends -also on the number of nodes in your cluster: the more nodes the -more desirable to use clones. Finally, it is also a matter of -personal preference. - -In short: if clones are safe to use with your configuration and -if they reduce the configuration, then make cloned stonith -resources. -************************** - -The CRM configuration is left as an exercise to the reader. - -== Monitoring the fencing devices - -Just like any other resource, the stonith class agents also -support the monitor operation. Given that we have often seen -monitor either not configured or configured in a wrong way, we -have decided to devote a section to the matter. - -Monitoring stonith resources, which is actually checking status -of the corresponding fencing devices, is strongly recommended. So -strongly, that we should consider a configuration without it -invalid. - -On the one hand, though an indispensable part of an HA cluster, a -fencing device, being the last line of defense, is used seldom. -Very seldom and preferably never. On the other, for whatever -reason, the power management equipment is known to be rather -fragile on the communication side. Some devices were known to -give up if there was too much broadcast traffic on the wire. Some -cannot handle more than ten or so connections per minute. Some -get confused or depressed if two clients try to connect at the -same time. Most cannot handle more than one session at the time. -The bottom line: try not to exercise your fencing device too -often. It may not like it. Use monitoring regularly, yet -sparingly, say once every couple of hours. The probability that -within those few hours there will be a need for a fencing -operation and that the power switch would fail is usually low. - -== Odd plugins - -Apart from plugins which handle real devices, some stonith -plugins are a bit out of line and deserve special attention. - -=== external/kdumpcheck - -Sometimes, it may be important to get a kernel core dump. This -plugin may be used to check if the dump is in progress. If -that is the case, then it will return true, as if the node has -been fenced, which is actually true given that it cannot run -any resources at the time. kdumpcheck is typically used in -concert with another, real, fencing device. See -README_kdumpcheck.txt for more details. - -=== external/sbd - -This is a self-fencing device. It reacts to a so-called "poison -pill" which may be inserted into a shared disk. On shared storage -connection loss, it also makes the node commit suicide. See -http://www.linux-ha.org/wiki/SBD_Fencing for more details. - -=== meatware - -Strange name and a simple concept. `meatware` requires help from a -human to operate. Whenever invoked, `meatware` logs a CRIT severity -message which should show up on the node's console. The operator -should then make sure that the node is down and issue a -`meatclient(8)` command to tell `meatware` that it's OK to tell the -cluster that it may consider the node dead. See `README.meatware` -for more information. - -=== null - -This one is probably not of much importance to the general -public. It is used in various testing scenarios. `null` is an -imaginary device which always behaves and always claims that it -has shot a node, but never does anything. Sort of a -happy-go-lucky. Do not use it unless you know what you are doing. - -=== suicide - -`suicide` is a software-only device, which can reboot a node it is -running on. It depends on the operating system, so it should be -avoided whenever possible. But it is OK on one-node clusters. -`suicide` and `null` are the only exceptions to the "don't shoot my -host" rule. - -.What about that pacemaker-fenced? You forgot about it, eh? -************************** -The pacemaker-fenced daemon, though it is really the master of ceremony, -requires no configuration itself. All configuration is stored in -the CIB. -************************** - -== Resources - -http://www.linux-ha.org/wiki/STONITH - -https://www.clusterlabs.org/doc/crm_fencing.html - -https://clusterlabs.org/pacemaker/doc/2.1/Pacemaker_Explained/html/ - -http://techthoughts.typepad.com/managing_computers/2007/10/split-brain-quo.html From d118a650701efd43a9e1939675001aa441f41104 Mon Sep 17 00:00:00 2001 From: Ken Gaillot Date: Wed, 23 Oct 2024 11:11:50 -0500 Subject: [PATCH 3/6] Doc: doxygen: add ClusterLabs logo to generated doxygen docs --- doc/Doxyfile.in | 2 +- doc/Makefile.am | 2 ++ doc/clusterlabs-logo-55x55.png | Bin 0 -> 1976 bytes 3 files changed, 3 insertions(+), 1 deletion(-) create mode 100644 doc/clusterlabs-logo-55x55.png diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 7f9720e616c..2cbc093ffc0 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -51,7 +51,7 @@ PROJECT_BRIEF = "Scalable High-Availability cluster resource manager" # and the maximum width should not exceed 200 pixels. Doxygen will copy the logo # to the output directory. -#PROJECT_LOGO = +PROJECT_LOGO = clusterlabs-logo-55x55.png # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path # into which the generated documentation will be written. If a relative path is diff --git a/doc/Makefile.am b/doc/Makefile.am index 308d86d6d70..104cf23fe9c 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -26,6 +26,8 @@ noinst_SCRIPTS = abi-check SUBDIRS = sphinx +EXTRA_DIST = clusterlabs-logo-55x55.png + # toplevel rsync destination for www targets (without trailing slash) RSYNC_DEST ?= sites.clusterlabs.org:/var/www/html diff --git a/doc/clusterlabs-logo-55x55.png b/doc/clusterlabs-logo-55x55.png new file mode 100644 index 0000000000000000000000000000000000000000..cab0249e52d2c3977855c889486596374f7d687a GIT binary patch literal 1976 zcmV;p2S@mcP)`meNwxN{Bz8fPxwYe;y1%tPjG28e;STjS`|UQ6xN&pu}K^ zF(D!-QR0gv3O+y}L}LJBkPse>Ab&!TfDnoZQYo#_ZMWU+j^B4@r(LGAGxrYc7!yx& zc4p4~JKsI$-gD;8TJkT@)4MKM7}jMQ_x9J*n|Zyil(??FX>JV{ z44vxn&8hVYo@H>?2AIz{QULQQ*3bqttiydP?jObdOmG3b1+oLiof;1+1id`xS&Z9L`ul}N}BFn)$OR<526`26UN|C@}{V1<;0waVMe4Z zRj&sXOXtA|87doE&a``{K0%DHPs!4I8WH4dS-7u5uH*~SoKDKBsZG+B?UywtF3W+A zoZQ=(lEsspQ;4rlXJq@i9;vO;b3?Cov4G>CY53i!wCgC2;j59Y)egXInfiD!aDRwj-QG;=nQNIuGk~e zFCM{-1oQPJ4&w4@$D{_nd3zNx17~x&D|#0^-`iP*pWj3O@0g@tQ8$!G2{Wf=V0wx( zp({gm<1x)FcMYcDR@8tvM$>m8J0VfVKy70wcjpGf!EnU31PXil3rNSJhHwczx4Z^8 zgG~vju{t4Z9&VD=4~>#)XigcyelVp;R!tcxHy{Fm|CP}cOrQvILamh)J>327y)ntZ&^k|s>-pr zC0%Uar9Rnq-U*9s**x6NlGaRK)}HD@E}4*>7qZd-U?-7=tv-HPCDq@Y?H0OdREh;0 zl}iKRN5?KJJ((<%n2c>`&8SVrmF4iT^^YDEV`^Yg`+v2{K#QUE&#V76(@jF z;?ppXtXR&kvPNVGZa@*9)ia1^jYf-JnQ#1|pSQf-n}M?|wE&PQY{Z2eKUFOKDjpCa z{b~WKX<*~P8eujVHE6l-F{$tvZl8K9(adtHV@1z^-zeV4b)nbnHhIa5y3e{F4vl~@ z+aQ+`V>AzihRTL?Z9HaFa6?886Ck@%Ct74Tza*wnh-YK#Qqo&I>0%iJIfH&59`qd0 ze{@5)^zS50O1q33UM2G<)+=Dkj{J>tl!D4a-kRK?a?LMKW#mw2pWNM$lGn%AtK4$) z@7*f6d&5Q8cy4(t;5Zm#*94?hBq~m;F_sfFEyU9?o_;YEn~1cF#M81oXTv}4sX9Rv z3pl#g8Khdv4tMhKOS)kx0=(E)P*%(V)NeQ)<4M19&WTU;AH3zp}8v&&V&i zh}?zFRBLa0uL4SPUUO_Y+{wSZI2(RMqp9|~mgDfHn~!cgH3*3v_ Date: Wed, 23 Oct 2024 12:06:32 -0500 Subject: [PATCH 4/6] Build: doc: update destination directory for uploads --- doc/Makefile.am | 14 ++++++++------ doc/sphinx/Makefile.am | 6 +++--- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/doc/Makefile.am b/doc/Makefile.am index 104cf23fe9c..cde87a2fee6 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -64,7 +64,7 @@ global: .PHONY: global-upload global-upload: global - rsync $(RSYNC_OPTS) HTML/ "$(RSYNC_DEST)/$(PACKAGE)/global/$(TAG)/" + rsync $(RSYNC_OPTS) HTML/ "$(RSYNC_DEST)/projects/$(PACKAGE)/global/$(TAG)/" .PHONY: global-clean global-clean: @@ -73,6 +73,8 @@ global-clean: # Man pages as HTML +MANPAGE_DIRS = ../agents ../daemons ../tools + %.8.html: %.8 groff -mandoc `man -w ./$<` -T html > $@ @@ -82,17 +84,17 @@ global-clean: .PHONY: manhtml manhtml: $(MAKE) $(AM_MAKEFLAGS) -C .. all - find ../agents ../daemons ../tools -name "[a-z]*.[78]" \ + find $(MANPAGE_DIRS) daemons ../tools -name "[a-z]*.[78]" \ -exec $(MAKE) $(AM_MAKEFLAGS) \{\}.html \; .PHONY: manhtml-upload manhtml-upload: manhtml - find .. -name "[a-z]*.[78].html" -exec \ - rsync $(RSYNC_OPTS) \{\} "$(RSYNC_DEST)/$(PACKAGE)/man/" \; + find $(MANPAGE_DIRS) -name "[a-z]*.[78].html" -exec \ + rsync $(RSYNC_OPTS) \{\} "$(RSYNC_DEST)/projects/$(PACKAGE)/man/" \; .PHONY: manhtml-clean manhtml-clean: - -find .. -name "[a-z]*.[78].html" -exec rm \{\} \; + -find $(MANPAGE_DIRS) -name "[a-z]*.[78].html" -exec rm \{\} \; # API documentation as HTML @@ -103,7 +105,7 @@ doxygen: Doxyfile .PHONY: doxygen-upload doxygen-upload: doxygen - rsync $(RSYNC_OPTS) api/html/ "$(RSYNC_DEST)/$(PACKAGE)/doxygen/$(TAG)/" + rsync $(RSYNC_OPTS) api/html/ "$(RSYNC_DEST)/projects/$(PACKAGE)/doxygen/$(TAG)/" .PHONY: doxygen-clean doxygen-clean: diff --git a/doc/sphinx/Makefile.am b/doc/sphinx/Makefile.am index 4c152047ba1..7fa9505d867 100644 --- a/doc/sphinx/Makefile.am +++ b/doc/sphinx/Makefile.am @@ -40,7 +40,7 @@ PAPER ?= letterpaper SPHINXFLAGS ?= # toplevel rsync destination for www targets (without trailing slash) -RSYNC_DEST ?= root@www.clusterlabs.org:/var/www/html +RSYNC_DEST ?= sites.clusterlabs.org:/var/www/html # End of useful overrides @@ -83,7 +83,7 @@ RSYNC_OPTS = -rlptvzxS --progress PACKAGE_SERIES=$(shell echo "$(VERSION)" | awk -F. '{ print $$1"."$$2 }') -BOOK_RSYNC_DEST = $(RSYNC_DEST)/$(PACKAGE)/doc/$(PACKAGE_SERIES) +BOOK_RSYNC_DEST = $(RSYNC_DEST)/projects/$(PACKAGE)/doc/$(PACKAGE_SERIES) BOOK = none @@ -171,7 +171,7 @@ if BUILD_SPHINX_DOCS "$(BOOK_RSYNC_DEST)/$$book/"; \ done @rsync $(RSYNC_OPTS) "$(builddir)/build-$(PACKAGE_SERIES).txt" \ - "$(RSYNC_DEST)/$(PACKAGE)/doc" + "$(RSYNC_DEST)/projects/$(PACKAGE)/doc" endif .PHONY: vars From 263d379da263d73e03735aba7d65f841cc9180f4 Mon Sep 17 00:00:00 2001 From: Ken Gaillot Date: Wed, 23 Oct 2024 12:17:12 -0500 Subject: [PATCH 5/6] Build: doc: move rsync variables to an include file --- doc/Makefile.am | 21 +++++++++------------ doc/abi-check.in | 8 ++++---- doc/sphinx/Makefile.am | 15 +++++---------- mk/uploads.mk | 19 +++++++++++++++++++ 4 files changed, 37 insertions(+), 26 deletions(-) create mode 100644 mk/uploads.mk diff --git a/doc/Makefile.am b/doc/Makefile.am index cde87a2fee6..71ebe298bc7 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -8,8 +8,9 @@ # include $(top_srcdir)/mk/common.mk -# Define release-related variables +# Define release- and upload-related variables include $(top_srcdir)/mk/release.mk +include $(top_srcdir)/mk/uploads.mk # What formats to use for book uploads (i.e. "make www"; # use BOOK_FORMATS in sphinx subdirectory to change local builds) @@ -28,13 +29,6 @@ SUBDIRS = sphinx EXTRA_DIST = clusterlabs-logo-55x55.png -# toplevel rsync destination for www targets (without trailing slash) -RSYNC_DEST ?= sites.clusterlabs.org:/var/www/html - -# recursive, preserve symlinks, preserve permissions, verbose, compress, -# don't cross filesystems, sparse, show progress -RSYNC_OPTS = -rlpvzxS --progress - if IS_ASCIIDOC ASCIIDOC_HTML_ARGS = --unsafe --backend=xhtml11 ASCIIDOC_DBOOK_ARGS = -b docbook -d book @@ -51,6 +45,8 @@ endif vars: @echo LAST_RELEASE=\'$(LAST_RELEASE)\' @echo TAG=\'$(TAG)\' + @echo RSYNC_DEST=\'$(RSYNC_DEST)\' + @echo RSYNC_PACKAGE_DEST=\'$(RSYNC_PACKAGE_DEST)\' # Annotated source code as HTML @@ -64,7 +60,7 @@ global: .PHONY: global-upload global-upload: global - rsync $(RSYNC_OPTS) HTML/ "$(RSYNC_DEST)/projects/$(PACKAGE)/global/$(TAG)/" + rsync $(RSYNC_OPTS) HTML/ "$(RSYNC_PACKAGE_DEST)/global/$(TAG)/" .PHONY: global-clean global-clean: @@ -90,7 +86,7 @@ manhtml: .PHONY: manhtml-upload manhtml-upload: manhtml find $(MANPAGE_DIRS) -name "[a-z]*.[78].html" -exec \ - rsync $(RSYNC_OPTS) \{\} "$(RSYNC_DEST)/projects/$(PACKAGE)/man/" \; + rsync $(RSYNC_OPTS) \{\} "$(RSYNC_PACKAGE_DEST)/man/" \; .PHONY: manhtml-clean manhtml-clean: @@ -105,7 +101,7 @@ doxygen: Doxyfile .PHONY: doxygen-upload doxygen-upload: doxygen - rsync $(RSYNC_OPTS) api/html/ "$(RSYNC_DEST)/projects/$(PACKAGE)/doxygen/$(TAG)/" + rsync $(RSYNC_OPTS) api/html/ "$(RSYNC_PACKAGE_DEST)/doxygen/$(TAG)/" .PHONY: doxygen-clean doxygen-clean: @@ -120,7 +116,8 @@ abi: abi-check .PHONY: abi-www abi-www: - export RSYNC_DEST=$(RSYNC_DEST); ./abi-check -u $(PACKAGE) $(LAST_RELEASE) $(TAG) + export RSYNC_PACKAGE_DEST=$(RSYNC_PACKAGE_DEST); \ + ./abi-check -u $(PACKAGE) $(LAST_RELEASE) $(TAG) .PHONY: abi-clean abi-clean: diff --git a/doc/abi-check.in b/doc/abi-check.in index 6b6a8d3d789..754e4d39c19 100755 --- a/doc/abi-check.in +++ b/doc/abi-check.in @@ -1,6 +1,6 @@ #!@BASH_PATH@ # -# Copyright 2011-2023 the Pacemaker project contributors +# Copyright 2011-2024 the Pacemaker project contributors # # The version control history for this file may have further details. # @@ -16,8 +16,8 @@ # upload it to the website. # -# Top-level rsync destination for www targets (without trailing slash) -: ${RSYNC_DEST:=root@www.clusterlabs.org:/var/www/html} +# Top-level rsync destination for package's file uploads (without trailing slash) +: ${RSYNC_PACKAGE_DEST:=sites.clusterlabs.org:/var/www/html/projects/$(PACKAGE)} # If the argument is of form x.y.z, print Pacemaker-x.y.z, # otherwise print the argument (presumably a commit ID) directly @@ -159,6 +159,6 @@ if [ $# -eq 2 ]; then COMPAT_REPORT="compat_reports/${PACKAGE}/${V1}_to_${V2}" if [ $UPLOAD -eq 1 ] && [ -d "$COMPAT_REPORT" ]; then - rsync -azxlSD --progress "$COMPAT_REPORT" "${RSYNC_DEST}/${PACKAGE}/abi/" + rsync -azxlSD --progress "$COMPAT_REPORT" "${RSYNC_PACKAGE_DEST}/abi/" fi fi diff --git a/doc/sphinx/Makefile.am b/doc/sphinx/Makefile.am index 7fa9505d867..9927fa4eb5b 100644 --- a/doc/sphinx/Makefile.am +++ b/doc/sphinx/Makefile.am @@ -8,8 +8,9 @@ # include $(top_srcdir)/mk/common.mk -# Define release-related variables +# Define release- and upload-related variables include $(top_srcdir)/mk/release.mk +include $(top_srcdir)/mk/uploads.mk # Things you might want to override on the command line @@ -39,9 +40,6 @@ PAPER ?= letterpaper # Additional options for sphinx-build SPHINXFLAGS ?= -# toplevel rsync destination for www targets (without trailing slash) -RSYNC_DEST ?= sites.clusterlabs.org:/var/www/html - # End of useful overrides @@ -77,13 +75,9 @@ EXTRA_DIST = $(wildcard */*.rst) $(DOTS) $(SVGS) \ $(STATIC_FILES) \ conf.py.in -# recursive, preserve symlinks/permissions/times, verbose, compress, -# don't cross filesystems, sparse, show progress -RSYNC_OPTS = -rlptvzxS --progress - PACKAGE_SERIES=$(shell echo "$(VERSION)" | awk -F. '{ print $$1"."$$2 }') -BOOK_RSYNC_DEST = $(RSYNC_DEST)/projects/$(PACKAGE)/doc/$(PACKAGE_SERIES) +BOOK_RSYNC_DEST = $(RSYNC_PACKAGE_DEST)/doc/$(PACKAGE_SERIES) BOOK = none @@ -171,7 +165,7 @@ if BUILD_SPHINX_DOCS "$(BOOK_RSYNC_DEST)/$$book/"; \ done @rsync $(RSYNC_OPTS) "$(builddir)/build-$(PACKAGE_SERIES).txt" \ - "$(RSYNC_DEST)/projects/$(PACKAGE)/doc" + "$(RSYNC_PACKAGE_DEST)/doc" endif .PHONY: vars @@ -180,6 +174,7 @@ vars: @echo "PAPER='$(PAPER)'" @echo "SPHINXFLAGS='$(SPHINXFLAGS)'" @echo "RSYNC_DEST='$(RSYNC_DEST)'" + @echo "RSYNC_PACKAGE_DEST='$(RSYNC_PACKAGE_DEST)'" @echo "VERSION='$(VERSION)'" @echo "PACKAGE_SERIES='$(PACKAGE_SERIES)'" diff --git a/mk/uploads.mk b/mk/uploads.mk new file mode 100644 index 00000000000..07808aec4fc --- /dev/null +++ b/mk/uploads.mk @@ -0,0 +1,19 @@ +# +# Copyright 2024 the Pacemaker project contributors +# +# The version control history for this file may have further details. +# +# This source code is licensed under the GNU General Public License version 2 +# or later (GPLv2+) WITHOUT ANY WARRANTY. +# + +# Variables useful for uploading files to a server + +# toplevel rsync destination (without trailing slash) +RSYNC_DEST ?= sites.clusterlabs.org:/var/www/html + +RSYNC_PACKAGE_DEST = $(RSYNC_DEST)/projects/$(PACKAGE) + +# recursive, preserve symlinks, preserve permissions, verbose, compress, +# don't cross filesystems, sparse, show progress +RSYNC_OPTS = -rlpvzxS --progress From 859ef7b2f29f32efa7d85cbae8e8946c8c63382b Mon Sep 17 00:00:00 2001 From: Ken Gaillot Date: Wed, 23 Oct 2024 12:35:31 -0500 Subject: [PATCH 6/6] Doc: Pacemaker Explained: fix broken reference --- doc/sphinx/Pacemaker_Explained/nodes.rst | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/doc/sphinx/Pacemaker_Explained/nodes.rst b/doc/sphinx/Pacemaker_Explained/nodes.rst index e4d25910475..72ef3e019aa 100644 --- a/doc/sphinx/Pacemaker_Explained/nodes.rst +++ b/doc/sphinx/Pacemaker_Explained/nodes.rst @@ -90,7 +90,7 @@ least an ID and a name. A cluster node's ID is defined by the cluster layer Pacemaker Remote nodes are defined by a resource in the ``resources`` section. Remote nodes and guest nodes may optionally have an entry in the ``nodes`` -section, primarily for permanent :ref:`node attributes `. +section, primarily for permanent :ref:`node attributes `. Normally, the user should let the cluster populate the ``nodes`` section automatically. @@ -226,8 +226,6 @@ The ``--type nodes`` indicates that this is a permanent node attribute; -.. _special_node_attributes: - Special node attributes ####################### @@ -238,9 +236,7 @@ special attributes. Some special attributes do not start with ``#``, for historical reasons. Certain special attributes are set automatically by the cluster, should never -be modified directly, and can be used only within :ref:`rules`; these are -listed under -:ref:`built-in node attributes `. +be modified directly, and can be used only within :ref:`rules`. For true/false values, the cluster considers a value of "1", "y", "yes", "on", or "true" (case-insensitively) to be true, "0", "n", "no", "off", "false", or