diff --git a/doc/Makefile.am b/doc/Makefile.am index 55ce5112b6..d931914af5 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,120 +1,120 @@ # # doc: Pacemaker code # # Copyright (C) 2008 Andrew Beekhof # # This program is free software; you can redistribute it and/or # modify it under the terms of the GNU General Public License # as published by the Free Software Foundation; either version 2 # of the License, or (at your option) any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software # Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. # MAINTAINERCLEANFILES = Makefile.in helpdir = $(datadir)/$(PACKAGE) -ascii = crm_cli.txt crm_fencing.txt +ascii = crm_cli.txt crm_fencing.txt acls.txt help_DATA = crm_cli.txt docbook = Pacemaker_Explained Clusters_from_Scratch doc_DATA = README.hb2openais $(ascii) $(generated_docs) publican_docs = generated_docs = DOCBOOK_FORMATS := html-desktop,txt SVG := $(wildcard */en-US/images/pcmk-*.svg) PNGS = $(SVG:%.svg=%-small.png) $(SVG:%.svg=%.png) $(SVG:%.svg=%-large.png) BRAND_PNGS = publican-clusterlabs/en-US/images/title_logo.png \ publican-clusterlabs/en-US/images/image_left.png \ publican-clusterlabs/en-US/images/image_right.png \ publican-clusterlabs/en-US/images/h1-bg.png graphics: $(PNGS) %.png: %.svg inkscape --file=$< --export-dpi=90 -C --export-png=$@ %-small.png: %.svg inkscape --file=$< --export-dpi=45 -C --export-png=$@ %-large.png: %.svg inkscape --file=$< --export-dpi=180 -C --export-png=$@ XML_FILES := $(wildcard *.xml) PNG_FILES := $(wildcard images/*.png) if BUILD_ASCIIDOC generated_docs += $(ascii:%.txt=%.html) endif if BUILD_DOCBOOK publican_docs += $(docbook) endif EXTRA_DIST = $(docbook:%=%.xml) %.html: %.txt $(ASCIIDOC) --unsafe --backend=xhtml11 $< %.txt: $(wildcard %/en-US/*.xml) @echo Building $* rm -rf $*/publish/* cd $* && $(PUBLICAN) build --publish --langs=all --formats=$(DOCBOOK_FORMATS) touch $@ if BUILD_DOCBOOK docbook_txt = $(docbook:%=%.txt) all-local: $(docbook_txt) */publican.cfg #install-data-local: all-local install-data-local: all-local for book in $(docbook); do \ filelist=`find $$book/publish/* -print`; \ for f in $$filelist; do \ p=`echo $$f | sed s:publish/:: | sed s:Pacemaker/::`; \ if [ -d $$f ]; then \ $(INSTALL) -d 775 $(DESTDIR)$(docdir)/$$p; \ else \ $(INSTALL) -m 644 $$f $(DESTDIR)$(docdir)/$$p; \ fi \ done; \ done endif brand: $(BRAND_PNGS) $(wildcard publican-clusterlabs/en-US/*.xml) cd publican-clusterlabs && publican build --formats=xml --langs=all --publish echo "Installing..." cd publican-clusterlabs && sudo publican install_brand --path=$(datadir)/publican/Common_Content # find publican-clusterlabs -name "*.noarch.rpm" -exec rm -f \{\} \; # cd publican-clusterlabs && $(PUBLICAN) package --binary # find publican-clusterlabs -name "*.noarch.rpm" -exec sudo rpm -Uvh --force \{\} \; www: rm -f $(docbook_txt) make DOCBOOK_FORMATS="pdf,html,html-single,txt,epub" all-local $(generated_docs) $(ascii) echo Uploading current documentation set to clusterlabs.org rsync -rtz --progress $(generated_docs) $(ascii) root@oss.clusterlabs.org:/var/www/html/doc/ if BUILD_DOCBOOK for book in $(docbook); do \ echo Uploading $$book...; \ echo "Generated on `date` from version: $(shell hg id -i -t)" > $$book/publish/build-$(PACKAGE_SERIES).txt; \ rsync -rtz --progress $$book/publish/* root@oss.clusterlabs.org:/var/www/html/doc/; \ done endif clean-local: -rm -rf $(generated_docs) $(docbook_txt) for book in $(docbook); do rm -rf $$book/tmp $$book/publish; done diff --git a/doc/acls.txt b/doc/acls.txt new file mode 100644 index 0000000000..247f0aef76 --- /dev/null +++ b/doc/acls.txt @@ -0,0 +1,200 @@ +Pacemaker Access Control Lists +============================== +Tim Serong + +== Introduction + +The various tools for administering Pacemaker clusters (crm_mon, +crm shell, cibadmin and friends, Python GUI, Hawk) can be used by +the +root+ user, or any user in the +haclient+ group. By default, +these users have full read/write access. Starting with Pacemaker +version 1.1.5, flexible access control lists are introduced to +provide different levels of administration to different users. + +== Prerequisites + +* Users are regular UNIX users, so the same user accounts must + be present on all nodes in the cluster. +* All user accounts must be in the +haclient+ group. +* Pacemaker 1.1.5 or newer must be installed on all cluster nodes. +* The CIB must be configured to use the pacemaker-1.1 or 1.2 schema. + This can be set by running: + + cibadmin --modify --xml-text '' + +* The +enable-acl+ option must be set. If ACLs are not explicitly + enabled, the previous behaviour will be used (i.e. all users in + the +haclient+ group have full access): + + crm configure property enable-acl=true + +* Once this is done, ACLs can be configured as described below. +* Note that the +root+ and +hacluster+ users will always have full + access. +* If nonprivileged users will be using the crm shell and CLI tools + (as opposed to only using Hawk or the Python GUI) they will need + to have +/usr/sbin+ added to their path. + +== Configuring ACLs + +Access control lists consist of an ordered set of access rules. +Each rule allows read or write access or denies access completely +to a part of the CIB. Rules are typically combined to produce a +specific role, then users may be assigned to that role. It is +also possible to configure ACLs directly for individual users. + +ACLs may be configured using the crm shell or the Python GUI. +The shell syntax is documented here. Using the Python GUI should +be reasonably straightforward once the concepts are understood. + +Note that rules are applied from first to last with the first +matching rule being used. This means specific +write+ rules +usually need to be listed before general +read+ rules. Any +permission not explicitly granted is denied by default, but note +that +write+ implies +read+, so there is no need to specicify both +to allow full read/write access. + +=== Minimum Required ACLs + +In order for the various tools to work correctly, a certain minimum +amount of data must be readable by the user invoking the tool. In +general, the safest thing to do is simply allow all users and roles +read access to the entire CIB. + +=== Role Syntax + +An ACL role is a set of rules which describe access rights to +CIB. Rules consist of an access right +read+, +write+, or +deny+ +and a specification denoting part of the configuration to which +the access right applies. The specification can be an XPath or a +combination of tag and id references. If an attribute is appended, +then the specification applies only to that attribute of the matching +element. + +==== Usage + +............... + role rule [rule ...] + + rule :: acl-right cib-spec [attribute:] + + acl-right :: read | write | deny + + cib-spec :: xpath-spec | tag-ref-spec + xpath-spec :: xpath: + tag-ref-spec :: tag: | ref: | tag: ref: +............... + +==== Example Role: Read-only Access + +............... + role monitor \ + read xpath:"/cib" +............... + +This is a single rule which allows read-only access to the entire +CIB. Users with this role will be able to view the status of +the cluster, but not make any changes. + +==== Example Role: ``Operator'' Access + +............... + role operator \ + write xpath:"//crm_config//nvpair[@name='maintenance-mode']" \ + write xpath:"//op_defaults//nvpair[@name='record-pending']" \ + write xpath:"//nodes/node//nvpair[@name='standby']" \ + write xpath:"//resources//nvpair[@name='target-role']" \ + write xpath:"//resources//nvpair[@name='is-managed']" \ + write xpath:"//constraints/rsc_location" \ + read xpath:"/cib" +............... + +These rules specify that users with this role will be able to: + +. Turn maintenance mode on or off +. Change whether pending operations are recorded +. Put any node on standby, and bring any node back online +. Start, stop, promote or demote any resource +. Tell the cluster to manage, or not manage any resource +. Migrate/move resources from node to note +. View the status of the cluster + +Users with this role will not be able to reconfigure resources +(change parameters, operations, etc.) or colocation or ordering +constraints. + +==== Example Role: Full Access + +............... + role administrator \ + write xpath:"/cib" +............... + +This is a single rule which allows rull read-write access to the +entirue CIB. Users with this role will have equivalent access to +the +root+ and +hacluster+ users. + +=== User Syntax + +ACLs can be defined for individual users using the same syntax +as for roles. Alternately, users can simply be assigned a given +role. The latter is considered best practice. + +==== Usage + +............... + user {role:|rule [rule ...]} + + rule :: acl-right cib-spec [attribute:] + + acl-right :: read | write | deny + + cib-spec :: xpath-spec | tag-ref-spec + xpath-spec :: xpath: + tag-ref-spec :: tag: | ref: | tag: ref: +............... + +==== Example + +............... + user alice role:monitor + user bob role:operator +............... + +The above example assigns +alice+ the +monitor+ role and +bob+ the ++operator+ role. + +== Advanced Usage + +Because ACLs can refer to elements and attributes in the CIB in a +very granular way, it is possible to configure very specific rules. +A refinement of the ``operator'' role above would be to allow +manipulation of only a specific resource, for example: + +............... + role bigdb_admin \ + write xpath:"//primitive[@id='bigdb']/meta_attributes/nvpair[@name='target-role']" \ + write xpath:"//primitive[@id='bigdb']/meta_attributes/nvpair[@name='is-managed']" \ + write xpath:"//constraints/rsc_location[@rsc='bigdb']" \ + read ref:"bigdb" \ + read xpath:"//nodes/node" uname \ + read xpath:"//nodes/node" type \ + read xpath:"//crm_config/cluster_property_set" \ + read xpath:"/cib/status" +............... + +The first four rules are specific for the +bigdb+ resource. They +allow modifying the +target-role+ and +is-managed+ meta +attributes which effectively enables users in this role to +stop/start and manage/unmanage the resource. The constraints +write access rule allows moving the resource around. Finally, the +user is granted read access to the resource definition. + +The bottom four rules are the absolute minimum read permissions +necessary for proper operation of various Pacemaker tools, +including `crm_mon` and the shell. This is fine for viewing +cluster status, but there are some tools for which this will +not be sufficient access (notably `ptest`), which is why it is +generally recommened that read access be allowed to the entire +CIB. +