Page MenuHomeClusterLabs Projects
Files F2822813

No OneTemporary
Actions

View Options

diff --git a/Makefile.am b/Makefile.am
index a90be9b..066859f 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,161 +1,161 @@
# Copyright (c) 2009 Red Hat, Inc.
#
# Authors: Andrew Beekhof
# Steven Dake (sdake@redhat.com)
#
# This software licensed under BSD license, the text of which follows:
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# - Redistributions of source code must retain the above copyright notice,
# this list of conditions and the following disclaimer.
# - Redistributions in binary form must reproduce the above copyright notice,
# this list of conditions and the following disclaimer in the documentation
# and/or other materials provided with the distribution.
# - Neither the name of the MontaVista Software, Inc. nor the names of its
# contributors may be used to endorse or promote products derived from this
# software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
# THE POSSIBILITY OF SUCH DAMAGE.
SPEC = $(PACKAGE_NAME).spec
TARFILE = $(PACKAGE_NAME)-$(VERSION).tar.gz
EXTRA_DIST = autogen.sh conf/booth.conf.example \
$(bootharbitrator_SCRIPTS) $(boothsite_SCRIPTS) \
$(boothnoarch_SCRIPTS)
AUTOMAKE_OPTIONS = foreign
MAINTAINERCLEANFILES = Makefile.in aclocal.m4 configure depcomp \
config.guess config.sub missing install-sh \
autoheader automake autoconf test_lense.sh
dist_doc_DATA = README COPYING
notrans_dist_man8_MANS = docs/boothd.8
boothconfdir = ${BOOTHSYSCONFDIR}
boothconf_DATA = conf/booth.conf.example
boothsitedir = /usr/lib/ocf/resource.d/pacemaker
boothsite_SCRIPTS = script/ocf/booth-site
bootharbitratordir = ${INITDDIR}
bootharbitrator_SCRIPTS = script/lsb/booth-arbitrator
boothnoarchdir = $(datadir)/$(PACKAGE_NAME)
-boothnoarch_SCRIPTS = script/service-still-runnable
+boothnoarch_SCRIPTS = script/service-runnable
TESTS = test/runtests.py
SUBDIRS = src docs
coverity:
cov-build --dir=cov make
cov-analyze --dir cov --concurrency --wait-for-license
cov-format-errors --dir cov
install-exec-local:
$(INSTALL) -d $(DESTDIR)/${boothconfdir}
$(INSTALL) -d $(DESTDIR)/${bootharbitratordir}
$(INSTALL) -d $(DESTDIR)/${boothsitedir}
$(INSTALL) -d $(DESTDIR)/${SOCKETDIR}
install-exec-hook:
ln -sf ${sbindir}/boothd $(DESTDIR)/${sbindir}/booth
uninstall-local:
rmdir $(DESTDIR)/${boothconfdir} || :;
rmdir $(DESTDIR)/${bootharbitratordir} || :;
rmdir $(DESTDIR)/${boothsitedir} || :;
rmdir $(DESTDIR)/${SOCKETDIR} || :;
test: check
lint:
for dir in src; do make -C $$dir lint; done
dist-clean-local:
rm -f autoconf automake autoheader
dist-hook:
echo $(VERSION) > $(distdir)/.tarball-version
## make rpm/srpm section.
$(SPEC): $(SPEC).in
rm -f $@-t $@
date="$(shell LC_ALL=C date "+%a %b %d %Y")" && \
if [ -f .tarball-version ]; then \
gitver="$(shell cat .tarball-version)" && \
rpmver=$$gitver && \
alphatag="" && \
dirty="" && \
numcomm="0"; \
else \
gitver="$(shell git describe --tags --abbrev=4 --match='v*' HEAD 2>/dev/null)" && \
rpmver=`echo $$gitver | sed -e "s/^v//" -e "s/-.*//g"` && \
alphatag=`echo $$gitver | sed -e "s/.*-//" -e "s/^g//"` && \
vtag=`echo $$gitver | sed -e "s/-.*//g"` && \
numcomm=`git rev-list $$vtag..HEAD | wc -l` && \
git update-index --refresh > /dev/null 2>&1 || true && \
dirty=`git diff-index --name-only HEAD 2>/dev/null`; \
fi && \
if [ -n "$$dirty" ]; then dirty="dirty"; else dirty=""; fi && \
if [ "$$numcomm" = "0" ]; then \
sed \
-e "s#@version@#$$rpmver#g" \
-e "s#%glo.*alpha.*##g" \
-e "s#%glo.*numcomm.*##g" \
-e "s#@dirty@#$$dirty#g" \
-e "s#@date@#$$date#g" \
$< > $@-t; \
else \
sed \
-e "s#@version@#$$rpmver#g" \
-e "s#@alphatag@#$$alphatag#g" \
-e "s#@numcomm@#$$numcomm#g" \
-e "s#@dirty@#$$dirty#g" \
-e "s#@date@#$$date#g" \
$< > $@-t; \
fi; \
if [ -z "$$dirty" ]; then sed -i -e "s#%glo.*dirty.*##g" $@-t; fi
chmod a-w $@-t
mv $@-t $@
$(TARFILE):
$(MAKE) dist
RPMBUILDOPTS = --define "_sourcedir $(abs_builddir)" \
--define "_specdir $(abs_builddir)" \
--define "_builddir $(abs_builddir)" \
--define "_srcrpmdir $(abs_builddir)" \
--define "_rpmdir $(abs_builddir)"
srpm: clean
autoreconf -if
$(MAKE) $(SPEC) $(TARFILE)
rpmbuild $(WITH_LIST) $(RPMBUILDOPTS) --nodeps -bs $(SPEC)
rpm: clean
autoreconf -if
$(MAKE) $(SPEC) $(TARFILE)
rpmbuild $(WITH_LIST) $(RPMBUILDOPTS) -ba $(SPEC)
diff --git a/booth.spec.in b/booth.spec.in
index 5309f04..7b4861d 100644
--- a/booth.spec.in
+++ b/booth.spec.in
@@ -1,72 +1,72 @@
%global alphatag @alphatag@
%global numcomm @numcomm@
%global dirty @dirty@
Name: booth
Version: @version@
Release: 1%{?numcomm:.%{numcomm}}%{?alphatag:.%{alphatag}}%{?dirty:.%{dirty}}%{?dist}
Summary: The Booth Cluster Ticket Manager.
Group: System Environment/Daemons
License: GPLv2
URL: http://www.clusterlabs.org
Source0: %{name}-%{version}.tar.gz
BuildRoot: %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)
Provides: booth
Requires: pacemaker
BuildRequires: autoconf automake libtool cluster-glue-libs-devel help2man
%if %{with resource-monitor}
BuildRequires: pacemaker-libs-devel
%endif
%description
Booth manages the ticket which authorizes one of the cluster sites located in
geographically dispersed distances to run certain resources. It is designed to
be an add-on of Pacemaker, which extends Pacemaker to support geographically
distributed clustering.
%prep
%setup -q -n %{name}-%{version}
%build
./autogen.sh
%configure \
--with-initddir=%{_initrddir}
make all
#except check
#%check
#make check
%install
rm -rf %{buildroot}
make install DESTDIR=%{buildroot}
%clean
rm -rf %{buildroot}
%files
%defattr(-,root,root,-)
%doc %{_docdir}/booth/README
%doc %{_docdir}/booth/COPYING
%{_sbindir}/booth
%{_sbindir}/boothd
%config %{_sysconfdir}/booth/booth.conf.example
%{_mandir}/man8/booth.8.gz
%{_mandir}/man8/boothd.8.gz
%dir /usr/lib/ocf/resource.d/pacemaker/
/usr/lib/ocf/resource.d/pacemaker/booth-site
%{_initrddir}/booth-arbitrator
%dir %{_datadir}/booth
-%{_datadir}/booth/service-still-runnable
+%{_datadir}/booth/service-runnable
%changelog
* @date@ Autotools generated version <nobody@nowhere.org> - @version@-1-@numcomm@.@alphatag@.@dirty@
- Autotools generated version
diff --git a/docs/boothd.8.txt b/docs/boothd.8.txt
index 6c782c2..685c9b8 100644
--- a/docs/boothd.8.txt
+++ b/docs/boothd.8.txt
@@ -1,443 +1,443 @@
BOOTHD(8)
===========
:doctype: manpage
NAME
----
boothd - The Booth Cluster Ticket Manager.
SYNOPSIS
--------
*boothd* 'daemon' ['-D'] [-c 'config']
*booth* ['client'] 'list' [-s 'site'] ['-D'] [-c 'config']
*booth* ['client'] 'grant' [-F] [-s 'site'] ['-D'] [-t] 'ticket' [-c 'config']
*booth* ['client'] 'revoke' [-s 'site'] ['-D'] [-t] 'ticket' [-c 'config']
*booth* 'status' ['-D'] [-c 'config']
DESCRIPTION
-----------
Booth manages tickets which authorizes one of the cluster sites
located in geographically dispersed distances to run certain
resources. It is designed to be extend Pacemaker to support
geographically distributed clustering.
It is based on the RAFT protocol, see eg.
<https://ramcloud.stanford.edu/wiki/download/attachments/11370504/raft.pdf>
for details.
SHORT EXAMPLES
--------------
---------------------
# boothd daemon
# booth list
# booth grant -t ticket-nfs
# booth revoke -t ticket-nfs
---------------------
OPTIONS
-------
*-c*::
Configuration to use.
+
Can be a full path to a configuration file, or a short name; in the latter
case, the directory '/etc/booth' and suffix '.conf' are added.
Per default 'booth' is used, which results in the path '/etc/booth/booth.conf'.
+
The configuration name also determines the name of the PID file - for the defaults,
'/var/run/booth/booth.pid'.
*-D*::
Debug output/don't daemonize.
Increases the debug output level; for 'boothd daemon', keeps the process
in the foreground.
*-h*, *--help*::
Give a short usage output.
*-s*::
Site address.
*-t*::
Ticket name.
*-v*, *--version*::
Report version information.
*-S*::
'systemd' mode: don't fork. This is like '-D' but without the debug output.
*-F*::
'immediate grant': Don't wait for unreachable sites to
relinquish the ticket. See the 'Booth ticket management'
section below for more details. Use with caution!
COMMANDS
--------
Whether the binary is called as 'boothd' or 'booth' doesn't matter; the first
argument determines the mode of operation.
*'daemon'*::
Tells 'boothd' to serve a site. The locally configured interfaces are
searched for an IP address that is defined in the configuration.
booth then runs in either /arbitrator/ or /site/ mode.
*'client'*::
Booth clients can list the ticket information (see also 'crm_ticket -L'),
and revoke or grant tickets to a site.
+
In this mode the configuration file is searched for an IP address that is
locally reachable, ie. matches a configured subnet.
This allows to run the client commands on another node in the same cluster, as
long as the config file and the service IP is locally reachable.
+
Example: If the booth service IP is 192.168.55.200, and the local node has
192.168.55.15 configured on an interface, it knows which site it belongs to.
+
Use '-s' to direct client to connect to a different site.
*'status'*::
'boothd' looks for the (locked) PID file and the UDP socket, prints
some output to stdout (for use in shell scripts) and returns
an OCF-compatible return code.
With '-D', a human-readable message is printed to STDERR as well.
CONFIGURATION FILE
------------------
The configuration file must be identical on all sites and
arbitrators.
A minimal file may look like this:
-----------------------
site="192.168.201.100"
site="192.168.202.100"
arbitrator="192.168.203.100"
ticket="ticket-db8"
-----------------------
Comments start with a hash-sign (''#''). Whitespace at the start
and end of the line, and around the ''='', are ignored.
The following key/value pairs are defined:
*'port'*::
The UDP/TCP port to use. Default is '9929'.
*'transport'*::
The transport protocol to use for Raft exchanges.
Currently only UDP is supported.
+
Clients use TCP to communicate with a daemon; Booth
will always bind and listen to both UDP and TCP ports.
*'site'*::
Defines a site Raft member with the given IP. Sites can
acquire tickets. The sites' IP should be managed by the cluster.
*'arbitrator'*::
Defines an arbitrator Raft member with the given IP.
Arbitrators help reach consensus in elections and cannot hold
tickets.
Booth needs at least three members for normal operation. Odd
number of members provides more redundancy.
*'ticket'*::
Registers a ticket. Multiple tickets can be handled by single
Booth instance.
The next items modify per-ticket defaults. Modifications are
inherited by tickets which follow in the configuration file.
All times are in seconds.
*'expire'*::
The lease time for a ticket. After that time the ticket can be
acquired by another site if the ticket holder is not
reachable.
+
'booth' renews a ticket after half the lease time.
*'weights'*::
A comma-separated list of integers that define the weight of individual
Raft members, in the same order as the 'site' and 'arbitrator' lines.
+
Default is '0' for all; this means that the order in the configuration
file defines priority for conflicting requests.
*'acquire-after'*::
Try to acquire a lost ticket _after_ this period passed.
+
This is to allow for some time for the site that lost the ticket
to relinquish the resources, by either stopping them or fencing a
node.
+
A typical delay might be 60 seconds, but ultimately it depends on
the protected resources and the fencing configuration.
*'timeout'*::
After that time 'booth' will re-send packets if there was an insufficient
number of replies. This should be long enough to allow
packets to reach other members.
+
The default is '5' seconds.
*'retries'*::
Defines how many times to retry sending packets before giving
up waiting for acks from other members.
+
Default is 10. Values lower than 3 are illegal.
+
This counts only for a single broadcast; if ticket *renewal* runs
into this limit (because the network was temporarily down), but
the ticket is still valid afterwards, a new renewal run will be
started automatically.
*'site-user'*, *'site-group'*, *'arbitrator-user'*, *'arbitrator-group'*::
These define the credentials 'boothd' will be running with.
+
On a (Pacemaker) site the booth process will have to call 'crm_ticket', so the
default is to use 'hacluster':'haclient'; for an arbitrator this user and group
might not exists, so there we default to 'nobody':'nobody'.
*'before-acquire-handler'*::
If set, this command will be called before 'boothd' tries to
acquire or renew a ticket. On exit code other than 0,
'boothd' cancels the operation.
+
This makes it possible to check whether it is appropriate
to acquire the ticket. For instance, if a service in the
dependency-chain has a failcount of 'INFINITY' on all
available nodes, the service will be unable to run. In that case,
it is of no use to claim the ticket.
+
'boothd' waits synchronously for the result of the handler, so make
sure that the program returns quickly.
+
See below for details about booth specific environment variables
-and the distributed 'service-still-runnable' script.
+and the distributed 'service-runnable' script.
A more verbose example of a configuration file might be
-----------------------
transport = udp
port = 9930
# D-85774
site="192.168.201.100"
# D-90409
site="::ffff:192.168.202.100"
# A-1120
arbitrator="192.168.203.100"
ticket="ticket-db8"
expire = 600
acquire-after = 60
timeout = 10
retries = 5
-----------------------
BOOTH TICKET MANAGEMENT
-----------------------
The booth cluster guarantees that every ticket is owned by only
one site at the time.
Only granted tickets are managed by 'booth'.
Tickets must be initially granted with the 'booth client grant'
command. Once it gets granted, the ticket is managed by the booth
cluster.
If the ticket gets lost, i.e. that the other members of the booth
cluster do not hear from the ticket owner in a sufficiently long
time, one of the remaining sites will acquire the ticket. This is
what is called _ticket failover_.
If the remaining members cannot form a majority, then the ticket
cannot fail over.
A ticket may be revoked at any time with the 'booth client
revoke' command. For revoke to succeed, the site holding the
ticket must be reachable.
Once the ticket is administratively revoked, it is not managed by
the booth cluster anymore. For the booth cluster to start
managing the ticket again, it must be again granted to a site.
The grant operation, in case not all sites are reachable, may get
delayed for the ticket expire time (and, if defined, the
'acquire-after' time). Under certain circumstances, the rest of
the booth members may not know if the ticket is currently granted
at the unreachable site.
This delay is disabled if the '-F' option is specified. In that
case, it is up to the administrator to make sure that the
unreachable site is not holding the ticket.
While the ticket is managed by 'booth', it is dangerous to manage
it manually using either `crm_ticket` command or `crm site
ticket`. Neither of these tools is aware of 'booth' and,
consequently, 'booth' itself may not notice any ticket status
changes.
NOTES
-----
Tickets are not meant to be moved around quickly--a reasonable
'expire' time might be 300 seconds (5 minutes).
'booth' works with both IPv4 and IPv6 addresses.
'booth' renews a ticket before it expires, to account for
possible transmission delays.
The renewal time is calculated as larger of half the 'expire'
time and 'timeout'*'retries'/2. Hence, with small 'expire' values
(eg. 60 seconds) the ticket renewal process will be started just
after the ticket got acquired.
HANDLERS
--------
Currently, there's only one external handler defined (see the 'before-acquire-handler'
configuration item above).
The following data is available as environment variables:
*'BOOTH_TICKET'::
The ticket name, as given in the configuration file. (See 'ticket' item above.)
*'BOOTH_LOCAL'::
The local site name, as defined in 'site'.
*'BOOTH_CONF_PATH'::
The path to the active configuration file.
*'BOOTH_CONF_NAME'::
The configuration name, as used by the '-c' commandline argument.
*'BOOTH_TICKET_EXPIRES'::
When the ticket expires (in seconds since 1.1.1970), or '0'.
FILES
-----
*'/etc/booth/booth.conf'*::
The default configuration file name. See also the '-c' argument.
*'/var/run/booth/'*::
Directory that holds PID/lock files. See also the 'status' command.
RAFT IMPLEMENTATION
-------------------
In essence, every ticket corresponds to a separate Raft cluster.
A ticket is granted _only_ to the Raft _Leader_, but a Leader
needs not grant the ticket to Pacemaker.
SYSTEMD INTEGRATION
-------------------
The 'boothd' 'systemd' unit file should be distributed with booth.
The booth daemon for a site or an arbitrator may be started
through systemd:
-----------
# systemctl enable booth@{configurationname}.service
# systemctl start booth@{configurationname}.service
-----------
The configuration name is required for 'systemctl', even in case
of the default name 'booth'.
EXIT STATUS
-----------
*0*::
Success. For the 'status' command: Daemon running.
*1* (PCMK_OCF_UNKNOWN_ERROR)::
General error code.
*7* (PCMK_OCF_NOT_RUNNING)::
No daemon process for that configuration active.
BUGS
----
Probably.
Please report them on GitHub: <https://github.com/ClusterLabs/booth/issues>
AUTHOR
------
'boothd' was originally written (mostly) by Jiaju Zhang.
Many people have contributed to it.
In 2013 Philipp Marek took over maintainership, followed by Dejan
Muhamedagic.
RESOURCES
---------
GitHub: <https://github.com/ClusterLabs/booth>
Documentation: <http://doc.opensuse.org/products/draft/SLE-HA/SLE-ha-guide_sd_draft/cha.ha.geo.html>
COPYING
-------
Copyright (C) 2011 Jiaju Zhang <jjzhang@suse.de>
Copyright (C) 2013-2014 Philipp Marek <philipp.marek@linbit.com>
Copyright (C) 2014 Dejan Muhamedagic <dmuhamedagic@suse.com>
Free use of this software is
granted under the terms of the GNU General Public License (GPL).
// vim: set ft=asciidoc :
diff --git a/script/service-still-runnable b/script/service-runnable
similarity index 100%
rename from script/service-still-runnable
rename to script/service-runnable

File Metadata

Mime Type
text/x-diff
Expires
Sat, Jan 25, 6:41 AM (1 d, 8 h)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
1321182
Default Alt Text
(19 KB)

Event Timeline