-@end html
-@end ifhtml
-
-@node
-@chapter Getting Started with CFEngine
-
-@node
-@section What does getting started entail?
-
-@sp 1
-
-@i{Choosing your hub.
-Assumptions about your operating system (working package manager)
-Start with no initial CFEngine policies.}
-
-
-@c *****************************************************
-@c * CHAPTER
-@c *****************************************************
-
-@node
-@section Installing CFEngine
-
-
-@menu
-* Installing the software::
-* Upgrading::
-* What is the default configuration - out of the box::
-@end menu
-
-CFEngine is designed to be simple to install in its default configuration. The installation
-process has three phases:
-
-@itemize
-@item Unpacking the software.
-@item Obtaining a license (only for commercial editions).
-@item Adapting policy.
-@end itemize
-
-@node
-@section Installing the software on a new host
-@c @node Installing from software binaries, Upgrading, Installing CFEngine, Installing CFEngine
-@c @section Installing the software on a new host
-
-You should start from a blank system. If you wish to install CFE Nova and you have
-already developed a policy using CFE Community, set aside this policy during the installation process. You will be able
-to integrate it back later.
-
-In the following, @file{} represents either @file{community} or @file{nova}, depending on whether you are installing CFE Community or CFE Nova.
-
-CFEngine is provided in two packages, @file{cfengine-} and @file{cfengine--expansion}. The main software package
-(for each operating system) must be installed on every host. The second package (expansion) is only installed on
-the @i{hub} or @i{policy server}. @b{You should install and set up the hub first}.
-
-The @file{cfengine-} package may be installed on a wide range of supported operating systems, including
-Linux, Solaris, Windows, etc. The @file{cfengine--expansion}
-package currently only supports the following Linux operating systems:
-@example
-Debian
-Ubuntu
-Red Hat
-SuSE
-@end example
-@noindent This means you must have one Linux computer running as your hub.
-No special software is required on other machines in your
-network. CFEngine bundles all dependencies in the binary package.
-
-On a new host, installation follows the following procedure. References to package managers
-assume that additional packages might need to be installed on the policy server, e.g. the Apache
-Web Server, MySQL database, etc. Remember, root privilege is required for the installation.
-
-@enumerate
-@item Verify that the machine's network connection is working and that it can resolve
-names. On the hub, verify that package managers @code{yum},
-@code{zypper} or @code{apt-get} are working (for example by typing @code(apt-get update)). They will be used to
-install a web, database and php server (if not already
-installed). If you are not able to set up a package manager and
-repository on the hub, please look in the Frequently Asked Questions
-below for manual installation.
-
-@item Copy the binary packages to the system. On the hub or policy server:
-
-@noindent CFE Community
-@example
-cfengine-community-3.@var{xxx.[rpm|deb]}
-cfengine-community-expansion-3.@var{xxx.[rpm|deb]}
-@end example
-
-@noindent CFE Nova
-@example
-cfengine-nova-2.@var{xxx.[rpm|deb]}
-cfengine-nova-expansion-2.@var{xxx.[rpm|deb]}
-@end example
-
-@sp 1
-
-@noindent On all other machines:
-
-@noindent CFE Community
-@example
-cfengine-community-3.@var{xxx.[rpm|deb]}
-@end example
-@noindent CFE Nova
-@example
-cfengine-nova-2.@var{xxx.[rpm|deb]}
-@end example
-
-@item Unpack the software:
-@table @i
-@item Red Hat family
-@example
-host# rpm -ihv @var{packages}
-@end example
-
-@item SUSE family
-@example
-host# rpm -ihv @var{packages}
-@end example
-
-@item Debian family
-@example
-host# dpkg --install @var{packages}
-@end example
-
-@end table
-
-@item On the hub, a public key has now been created in @file{/var/cfengine/ppkeys/localhost.pub} as part of the
-package installation. Users of CFE Community may skip to the next step. CFE Nova users: you should send this public key to CFEngine Support as an attachment in the ticket system (@url{https://cfengine.com/otrs/customer.pl}),
-to obtain a license file @file{license.dat}. *** Save the returned license file to @file{/var/cfengine/masterfiles/license.dat}
-on the hub @b{before continuing} ***. See more details for the software licensing here;
-@url{https://cfengine.com/software/Licensing.pdf}
-
-@item The remaining steps apply to all hosts, but you should @b{install the hub or policy server first}.
-Find the hostname or IP address of the hub (policy server), here we assume @samp{123.456.789.123} is the address.
-@verbatim
- hub # /var/cfengine/bin/cf-agent --bootstrap 123.456.789.123
-@end verbatim
-Use the same command on all hosts, i.e. *** do not bootstrap the policy server with a localhost address ***
-If you mistype the address of the hub, we recommend doing the following steps to re-boostrap.
-@verbatim
- hub # /var/cfengine/bin/cf-agent --bootstrap 123.456.789.124
- hub # killall cf-execd cf-serverd cf-monoitord cf-hub
- hub # rm -rf /var/cfengine/inputs/*
- hub # rm -f /var/cfengine/policy_server.dat
- hub # /var/cfengine/bin/cf-agent --bootstrap 123.456.789.123
-@end verbatim
-
-@item The software should now be running.
-
-@end enumerate
-
-@noindent @b{How to assess success in this procedure (CFE Community and CFE Nova):}
-
-@enumerate
-
-@item Look at the process list on the systems with @samp{ps waux | grep cf}.
-You should be able to see @code{cf-execd} running, and eventually other processes from
-the CFEngine suite like @code{cf-monitord} @code{cf-serverd}. For CFE Nova, you should
-also eventually see @code{cf-hub} running on the hub. Note that it may take 5--10 minutes before all the
-processes get started.
-
-@item Look for files in @file{/var/cfengine/inputs} (Unix)
-or @file{C:\Program Files\Cfengine\inputs} (Windows). For CFE Nova users the license
-file will be copied out from the policy server to the clients as part
-of the normal distribution of policy. Each Unix machine should get a
-copy of the @file{license.dat} file in @file{/var/cfengine/inputs}
-(Unix) or @file{C:\Program Files\Cfengine\inputs} (Windows).
-@end enumerate
-
-@noindent @b{How to assess success in this procedure (CFE Nova only):}
-
-@enumerate 3
-@item On the hub, the file @file{/var/cfengine/promise_knowledge.cf} should have been
-created, and should contain data.
-
-@item Finally, try to connect to the web server at port 80 on the hub / policy host.
-You should see a summary page like the one shown in the figure
-below. There should be at least 1 host registered, since the hub will
-pull reports from itself also.
-@end enumerate
-
-@sp 1
-@center @image{summary,15cm,,The front page}
-@center The opening page of the CFEngine Nova Mission Portal.
-@sp 1
-
-
-@node
-@section What is the default configuration?
-
-Following the above procedure, you should have a fully functional
-CFEngine on all clients. However, in the default configuration,
-CFEngine does nothing other than looking after itself, and looking for
-possible policy updates from @file{/var/cfengine/masterfiles}
-on the policy server. On CFE Nova, the policy server is configured to collect data
-from non-policy server machines and generate reports that are
-integrated into the knowledge base.
-
-To alter policies, you need to change the files on the policy hub,
-in the directory @file{/var/cfengine/masterfiles}. To begin with
-most of the policy examples are commented out in these files:
-@sp 1
-@cartouche
-@smallexample
-cdp_inputs/ cfengine.cf failsafe.cf knowledge.cf @b{promises.cf} update.cf
-cdp_lib/ cfengine_stdlib.cf file_change.cf OrionCloud/
-@end smallexample
-@end cartouche
-@sp 1
-To change this, you can go to the main file @file{promises.cf}, and include additional
-pre-made bundles of promises. You should always verify the contents of the bundles
-you include before activating and deploying to new machines.
-
-@i{Remark: this section will and below have to be modified according to what is included in the PolicyBase. Will the update procedure also be included in Community 3.2?}
-
-
-@cartouche
-@verbatim
-bundle agent main
-{
-methods:
-
- any::
-
- "general" usebundle => def;
-
-# "jobs" usebundle => system_scheduling;
-# "security" usebundle => change_management;
-# "security" usebundle => security_files;
-# "windows boxes" usebundle => active_directory;
-
-# windows::
-# "windows boxes" usebundle => software_local;
-# "windows boxes" usebundle => app_baseline;
-# "windows boxes" usebundle => win_services;
-# "windows boxes" usebundle => win_registry;
-# "windows boxes" usebundle => win_emergency;
-
-# !windows::
-# "security" usebundle => system_xinetd;
-# "maintenance" usebundle => garbage_collection;
-}
-@end verbatim
-@end cartouche
-
-@node
-@section Frequently Asked Questions
-
-@node
-@subsection How do I install the prerequisites for the hub manually?
-
-Here is a list of dependencies for the hub to be checked if The Mission Portal displays
-nothing;
-@itemize
-@item Red Hat/CentOS/Fedora
-@example
-httpd, mysql, mysql-server, php, php-bcmath, subversion
-@end example
-@item SUSE
-@example
-apache2, apache2-mod_php5, apache2-prefork, mysql, php5, subversion
-@end example
-@item Debian/Ubuntu
-@example
-apache2, mysql-server, php5
-@end example
-@end itemize
-
-To install all of these, you might want to use @code{yum} on Red Hat/CentOS/Fedora,
-@code{zypper} on SUSE or @code{apt} on Debian/Ubuntu.
-
-@subsection Why do I get a promise failed with the message @code{Can't stat
-/var/cfengine/master_software_updates/SOME-OS} on some hosts?
-
-There is a built-in promise to automatically upgrade the Nova
-binaries. By default, the clients will check for an update package
-every time Nova runs. So if the clients find that there is no source
-directory to download the files from, the message will be displayed.
-
-To fix the problem, simply create an empty directory mentioned in the
-message on the hub.
-@verbatim
- hub # mkdir /var/cfengine/master_software_updates/SOME-OS
-@end verbatim
-
-
-@subsection I did bootstrap the hub @emph{before} obtaining a license file, what should I do?
-
-Four steps need to be followed to correct this minor issue.
-@enumerate
-@item obtain a working license file and copy it to @file{/var/cfengine/masterfiles}
-@verbatim
- hub # cp /tmp/license.dat /var/cfengine/masterfiles
-@end verbatim
-@item killall Nova running processes
-@verbatim
- hub # killall cf-execd cf-serverd cf-monitord cf-hub
-@end verbatim
-@item wipe out @file{/var/cfengine/inputs }
-@verbatim
- hub # rm -rf /var/cfengine/inputs
-@end verbatim
-@item bootstrap the policy hub
-@verbatim
- hub # /var/cfengine/bin/cf-agent --bootstrap 123.456.789.123
-@end verbatim
-@end enumerate
-
-
-@subsection On my hub, I get messages of connection failures to a database. For example, in @code{messages}, I can see something like @code{!! Could not open connection to report database for saving}. What should I do?
-
-This message comes from the @code{cf-hub} process. It is responsible
-for pulling reports from hosts that have contacted the hub to get
-policy updates. When these reports are fetched, they are stored in a
-local MongoDB database on the hub, and connecting to this database is
-what is failing.
-
-Probably, the issue is that the database server is not running on your
-hub. Run the @code{ps}-command to check this.
-@verbatim
- hub # ps -e | grep mongod
- hub #
-@end verbatim
-
-If the @code{mongod} process @emph{is} running, it must be
-misconfigured or in some bad state. Please look at the newest entry in
-@file{/var/log/mongod.log} to diagnose the problem, and contact
-CFEngine Technical Support if necessary.
-
-If the @code{mongod} process @emph{is not} running, please follow the
-steps below.
-@itemize
-@item Run
- hub # @code{/var/cfengine/bin/cf-twin -Kvf failsafe.cf > /tmp/cfout}
-@item Check again if the @code{mongod} is running, if so, the problem
-is probably fixed now.
-@item If @code{mongod} is still not running, please search the output
-file for lines starting as follows.
-
-@verbatim
-...
-nova> -> Making a one-time restart promise for mongod
-...
-...
-nova> -> Executing '/var/cfengine/bin/mongod....
-nova> -> Backgrounding job /var/cfengine/bin/mongod...
-nova> -> Completed execution of /var/cfengine/bin/mongod...
-...
-@end verbatim
-
-If you don't see the first line above, Nova does not try to start
-@code{mongod} --- so check if you bootstrapped your hub correctly. If
-you see all lines, Nova starts @code{mongod}, but the process just
-terminates immideatley after. If so, continue to the next step.
-
-@item Look at the newest entry in @file{/var/log/mongod.log}. It
-should give you more details of why the @code{mongod} process refuses
-to start. The two most common scenarios are described next.
-
-@item If @code{mongod} has been terminated unexpectedly, it might have
-left a lock-file behind that stops it from starting again. Try
-deleteting @file{/var/cfengine/state/mongod.lock} if it exists.
-
-@item If the database is corrupted, you can have @file{mongod} create a new one my moving
-@file{/var/cfengine/state/cf-report.*} out of the way. There are also
-tools and documentation for repairing a database at
-@url{http://www.mongodb.org/}.
-
-Note that almost all of the @code{cfreport} database is completely
-recreated with data collected from clients every six hours, so
-deleting it is normally acceptable. But CFEngine AS or CFEngine Inc
-can not be held responsible for data loss in this respect.
-
-
-@end itemize
-
-@subsection How do I upgrade from community version to Nova?
-
-There is no shortcut for this task. We urge you to set aside your
-current community policy while you install Nova, setup the Nova hub by
-following this/Nova supplement document, and then integrate your existing
-policy to the hub manually, in small testable steps.
-
-CFEngine Nova is compatible with the Community Edition of CFEngine 3, but
-some process files are now managed by CFEngine for user convenience.
-
-@subsection Let's say I'd like to deploy Nova on my Debian/Ubuntu network. Describe this step by step?
-
-Here we go:
-
-@b{Debian/Ubuntu Installation Example:}
-@itemize
-@item @b{Hub(policy-server)}
-@enumerate
-@item Verify that the package manager is working (eg. @code{apt-get update})
-@item Download the Nova and Nova Supplement package
-@item Unpack the software:
-@verbatim
- hub # dpkg --install cfengine-nova_2.0.1-1_x86_64.deb
- hub # dpkg --install cfengine-nova-expansion_2.0.1-1_x86_64.deb
-@end verbatim
-@item Send the file: @code{"/var/cfengine/ppkeys/localhost.pub"} to Cfengine Support (OTRS ticket system)
-@item You will receive a license file: @code{license.dat}
-@item Copy the license file to: @code{"/var/cfengine/masterfiles/license.dat"}
-@item Bootstrap the hub:
-@verbatim
- hub # /var/cfengine/bin/cf-agent --bootstrap
- *** Warning: do not use 127.0.0.1 as the ip address ***
-@end verbatim
-@end enumerate
-@item @b{Clients}
-@enumerate
-@item Verify that the package manager is working (eg. @code{apt-get update})
-@item Download the Nova package
-@item Unpack the software:
-@verbatim
- hub # dpkg --install cfengine-nova_2.0.1-1_x86_64.deb
-@end verbatim
-@item Bootstrap the Client to the hub:
-@verbatim
- client # /var/cfengine/bin/cf-agent --bootstrap
-@end verbatim
-@end enumerate
-@end itemize
-
-To check if the installation went as expected, see @code{"How to assess success in this procedure"} section in the Nova_Supplement Guide.
-
-@bye
diff --git a/docs/guides/Makefile.am b/docs/guides/Makefile.am
deleted file mode 100644
index 647b0eb980..0000000000
--- a/docs/guides/Makefile.am
+++ /dev/null
@@ -1,138 +0,0 @@
-TEX_INCLUDEDIR = ../tex-include
-
-# Syntax errors:
-# SpecialTopic_Vision
-# SpecialTopic_Comparison
-# OrionCloudPack
-
-COMMON_GUIDES = \
- SpecialTopic_Adoption \
- SpecialTopic_Agility \
- SpecialTopic_ApplMgt \
- SpecialTopic_BDMA \
- SpecialTopic_Cloud \
- SpecialTopic_Change \
- SpecialTopic_ContentDrivenPolicies \
- SpecialTopic_DevOps \
- SpecialTopic_DistributedScheduling \
- SpecialTopic_Editing \
- SpecialTopic_Federation \
- SpecialTopic_FIPS \
- SpecialTopic_Hierarchy \
- SpecialTopic_ITIL \
- SpecialTopic_Iteration \
- SpecialTopic_Knowledge \
- SpecialTopic_MenuDrivenConfig \
- SpecialTopic_MissionCritical \
- SpecialTopic_Modules \
- SpecialTopic_Monitoring \
- SpecialTopic_OpenNebula \
- SpecialTopic_Packages \
- SpecialTopic_RBAC \
- SpecialTopic_Reporting \
- SpecialTopic_Rollback \
- SpecialTopic_Scalability \
- SpecialTopic_Scan \
- SpecialTopic_Schedule \
- SpecialTopic_Security \
- SpecialTopic_Teamwork \
- SpecialTopic_Virtualization \
- SpecialTopic_Windows \
- cf3-bestpractice \
- cf3-conceptguide \
- cf3-glossary \
- cf3-quickstart \
- cf3-solutions \
- cf3-tutorial \
- cf3-upgrade \
- cf_Quickref3 \
- CfengineStdLibrary
-
-HTML_ONLY_GUIDES =
-
-PDF_ONLY_GUIDES =
-
-if HAVE_NOVA
--include ../../nova/docs/Makefile.am
-endif
-
-HTML_GUIDES = $(COMMON_GUIDES) $(HTML_ONLY_GUIDES)
-
-PDF_GUIDES = $(COMMON_GUIDES) $(PDF_ONLY_GUIDES)
-
-.PRECIOUS: ../tools/build-solutions-guide
-
-../tools/build-solutions-guide:
- $(MAKE) -C ../tools $(AM_MAKEFLAGS) build-solutions-guide
-
-../tools/build-stdlib:
- $(MAKE) -C ../tools $(AM_MAKEFLAGS) build-stdlib
-
-cf3-solutions.texinfo: cf3-solutions.texinfo.in ../tools/build-solutions-guide
- $(AM_V_GEN)../tools/build-solutions-guide $(top_srcdir)/examples < $< > $@ || (rm -f $@; false)
-
-CfengineStdLibrary.texinfo: ../../masterfiles/libraries/cfengine_stdlib.cf ../tools/build-stdlib
- $(AM_V_GEN)../tools/build-stdlib $(srcdir)/../../masterfiles/libraries/cfengine_stdlib.cf || (rm -f $@; false)
-
-%.html: %.texinfo
- $(AM_V_GEN)$(MAKEINFO) \
- $^ -o $@ \
- -I $(TEX_INCLUDEDIR) \
- --error-limit=0 \
- --html \
- --no-split \
- --no-validate \
- --css-include=cfcomdoc.css
-
-TEXI2PDFFLAGS = -I $(TEX_INCLUDEDIR) --batch $(if $(filter-out 0,$(V)),,--quiet)
-
-%.pdf: %.texinfo
- $(AM_V_GEN)$(srcdir)/../tools/texi2pdfclean $< $(TEXI2PDF) -o $@ $(TEXI2PDFFLAGS)
-
-
-if HTML_DOCS
-html: $(patsubst %,%.html,$(HTML_GUIDES))
-endif
-
-if PDF_DOCS
-pdf: $(patsubst %,%.pdf,$(PDF_GUIDES))
-endif
-
-GUIDEDIR=$(DESTDIR)/$(projdocdir)/guides
-
-dist-guide-%: %
- $(INSTALL_DATA) $^ $(distdir)
- if test -n "`$(srcdir)/../tools/extract-images $^ | sort | uniq`"; then \
- $(INSTALL_DATA) `$(srcdir)/../tools/extract-images $^ | sort | uniq` $(distdir); \
- fi
-
-dist-common: $(patsubst %,dist-guide-%.texinfo,$(COMMON_GUIDES))
-
-if HTML_DOCS
-install-html: html
- $(MKDIR_P) $(GUIDEDIR)/html
- $(INSTALL_DATA) $(patsubst %,%.html,$(HTML_GUIDES)) $(GUIDEDIR)/html
- $(INSTALL_DATA) `$(srcdir)/../tools/extract-images $(patsubst %,%.texinfo,$(HTML_GUIDES)) | sort | uniq` $(GUIDEDIR)/html
-endif
-
-dist-html-only:
-
-if PDF_DOCS
-install-pdf: pdf
- $(MKDIR_P) $(GUIDEDIR)/pdf
- $(INSTALL_DATA) $(patsubst %,%.pdf,$(PDF_GUIDES)) $(GUIDEDIR)/pdf
-endif
-
-if PDF_DOCS
-dist-pdf-only: $(patsubst %,dist-guide-%.texinfo,$(PDF_ONLY_GUIDES))
-else
-dist-pdf-only:
-endif
-
-all: pdf html
-install-data-hook: install-pdf install-html
-dist-hook: dist-pdf-only dist-html-only dist-common
-
-EXTRA_DIST = cf3-solutions.texinfo.in CFEngineFrontPage.pdf NewLogo.pdf cfcomdoc.css
-
-CLEANFILES = cf3-solutions.texinfo $(patsubst %,%.pdf,$(PDF_GUIDES)) $(patsubst %,%.html,$(HTML_GUIDES))
diff --git a/docs/guides/MissionPlan.png b/docs/guides/MissionPlan.png
deleted file mode 100644
index 37cea471d6..0000000000
Binary files a/docs/guides/MissionPlan.png and /dev/null differ
diff --git a/docs/guides/NewLogo.pdf b/docs/guides/NewLogo.pdf
deleted file mode 100644
index cb51106b1d..0000000000
Binary files a/docs/guides/NewLogo.pdf and /dev/null differ
diff --git a/docs/guides/ONarchitecture.png b/docs/guides/ONarchitecture.png
deleted file mode 100644
index 249dd34da4..0000000000
Binary files a/docs/guides/ONarchitecture.png and /dev/null differ
diff --git a/docs/guides/Orion.png b/docs/guides/Orion.png
deleted file mode 100644
index 314dcebb05..0000000000
Binary files a/docs/guides/Orion.png and /dev/null differ
diff --git a/docs/guides/OrionCloudPack.texinfo b/docs/guides/OrionCloudPack.texinfo
deleted file mode 100644
index a2bf653a78..0000000000
--- a/docs/guides/OrionCloudPack.texinfo
+++ /dev/null
@@ -1,632 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename orion-cloud.info
-@settitle The Cfengine Orion Cloud Pack
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title The Cfengine Orion Cloud Pack - EC2
-@subtitle A Cfengine Handbook
-@author Cfengine AS
-
-
-@page
-
-@cartouche
-@quotation
-Get the Cloud under Orion's belt with the Cfengine Orion Cloud Pack.
-
-This document describes the Three Steps you need to bring reliability
-and efficiency to Managed Services running out of the Amazon Cloud.
-Set up and tear down machines as you like, and bring instant
-configuration and compliance, with self-healing to your business.
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2010- Cfengine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@menu
-* Introduction to Orion::
-* Some background on EC2::
-* Prerequisites for setting up Orion::
-* Three steps to the cloud::
-* How do I know that CFEngine is maintaining the system?::
-* Benefits for users running CFEngine Nova::
-* The Cloud Pack Nursury::
-* Orion Support::
-* Orion License::
-* Cultural References to Orion and Cloud::
-@end menu
-
-@node Top
-@top CFEngine-Tutorial
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-
-
-@node Introduction to Orion
-@unnumberedsec Introduction to the CFEngine Orion Cloud Pack
-
-@sp 1
-
-Welcome to the CFEngine Orion Cloud Pack. This version of the package
-has been designed to work specificallgy with the @i{Amazon Elastic
-Compute Cloud}. It allows you to configure a cloud computer or
-`platform instance' to run common services in a reproducible and
-maintainable way and without human intervention.
-
-@sp 1
-@cartouche
-The CFEngine Cloud Pack is not a tool for performing elastic scaling
-of services on demand, rather it is a simple repeatable process for
-speeding up system installation with automatic self-healing, for a
-consistent and compliant outcome.
-@end cartouche
-@sp 1
-
-CFEngine is uniquely suited to work in the Cloud because it is capable
-of install systems and maintaining and repairing them with hands-free
-capabilities that cannot be matched by other software.
-The CFEngine Orion Cloud Pack may also be used on any other non-Cloud systems
-that run the base operating-systems discussed here.
-
-You can thus
-test and learn about CFEngine using disposable Cloud `instances' and
-then use your experience on more permanent hardware elsewhere, if you
-wish. Or, you can simply use the CFEngine Orion Cloud Pack to bring up
-cloud services and configure them to a desired state on demand.
-
-@node Some background on EC2
-@unnumberedsec Some background on EC2
-
-If you are familiar with Amazon Amazon Elastic Compute Cloud (EC2),
-you will find the instructions here straightforward. You can
-choose between these alternative paths:
-@itemize
-@item Do It Yourself: launch your own Amazon Machine Image and install CFEngine
-on your own, then install the Orion Cloud Pack software and continue. If you choose
-this option, your CFEngine policies are only examples and are unsupported.
-
-@item With our Help: use one of our publicly available images, located
-in the Amazon storage area, which has CFEngine Community Edition
-pre-installed for your convenience, then follow the Orion Cloud Pack
-installation procedure to continue. You will then have access to 30
-days of E-mail support from CFEngine, with a maximum of 5 enquires.
-@end itemize
-
-@sp 1
-
-@cartouche
-An Amazon Machine Image or AMI is a pre-configured server designed to
-be launched and available on demand. Each AMI template has a unique
-number of the form @code{ami-XXXXX}. Advanced users may also create
-their own images customized with applications, data and configuration
-settings as desired. The AMIs are the @i{baseline} or starting point
-for Cloud Computing.
-@end cartouche
-
-@page
-
-@node Prerequisites for setting up Orion
-@unnumberedsec Prerequisites for setting up Orion
-@sp 1
-
-To get started in the Cloud, you will need an Amazon Web services
-account and some familiarity with either the web interface or command
-line tools@footnote{This booklet is not meant as an introduction to using the
-Amazon EC2. See the Appendices for references to Cloud Resources.}.
-
-@sp 1
-@cartouche
-You should know something about configuration of
-@i{security groups}. For a start-to-finish guide to launching an AMI
-and setting up the CFEngine Orion Cloud Pack see Appendix A.
-@end cartouche
-
-@sp 1
-@noindent We have published the following AMIs on EC2 storage for your convenience:
-
-@sp 1
-@multitable @columnfractions .33 .33 .33
-@item @tab us-east @tab us-west
-@item Ubuntu Server 9.10 32 @tab ami-XXXXXX @tab ami-XXXXXX
-@item Ubuntu Server 9.10 64 @tab ami-XXXXXX @tab ami-XXXXXX
-@item Centos 5.4 32 @tab ami-XXXXXX @tab ami-XXXXXX
-@item Centos 5.4 64 @tab ami-XXXXXX @tab ami-XXXXXX
-@end multitable
-
-@sp 1
-@noindent You should subscribe to one or more of these. The following
-sections assume that you have already acquired such an instance.
-
-@node Three steps to the cloud
-@unnumberedsec Three steps to the cloud
-
-To use the CFEngine Orion Cloud Pack, there are just three steps:
-@sp 1
-@enumerate
-@item @b{UNPACK}: Copy the CFEngine Orion Cloud Pack to your EC2 instance
-and unpack the files in @file{/var/cfengine/masterfiles}.
-
-@item @b{CUSTOMIZE}: Edit the policy promise examples for your purposes.
-In particular, look at the master file @file{promises.cf}, comment out
-or uncomment the promises you want. The default promises construct a
-PHP enabled webserver. You should also place the IP address of the policy
-server in the @file{policy_server.dat} file, like this:
-@example
-echo "@var{IP-address}" > /var/cfengine/policy_server.dat
-@end example
-This tells CFEngine where to look for the cloud pack. If you are
-running on a single test machine, you can make this localhost
-(127.0.0.1); if you are running several machines, make it the first
-machine where you installed the cloud-pack.
-
-Fill in the @code{policy_server} variable with the appropriate IP
-address in @file{update.cf} and @file{promises.cf}. This guide assumes
-that the single instance your hvae created will be its own policy
-server. However when setting up multiple instances one or more may be
-‘promoted' to be policy servers.
-
-@item @b{ACTIVATE}: Run @code{cf-agent -f /var/cfengine/masterfiles/failsafe.cf'}
-to start CFEngine management.
-@end enumerate
-
-@sp 1
-You now have a running `instance', with services configured and
-maintained by CFEngine.
-
-@node How do I know that CFEngine is maintaining the system?
-@unnumberedsec How do I know that CFEngine is maintaining the system?
-
-Execute @samp{ps aux | grep cf-} to see cf-agent, cf-serverd and
-cf-execd in the process table. To test self repair try stopping the
-web server.
-
-@page
-
-
-
-@node Benefits for users running CFEngine Nova
-@unnumberedsec Additional benefits for users running CFEngine Nova
-
-@sp 1
-
-If you have access to a commercial edition of the CFEngine
-software, such as CFEngine Nova, you will have a number of immediate
-benefits to simplify Cloud Management.
-
-@itemize
-@item @b{Knowledge and monitoring}
-
-Without any further configuration or third party software, you can
-monitor your cloud instances with CFEngine Nova's reporting features.
-You can add special logging and see performance trend analysis,
-integrated into your Nova Knowledge Map.
-
-@sp1
-@center{@image{monitor,10cm,,Monitorng,png}}
-
-@item @b{Compliance reporting}
-
-Not only will
-you see the automatically integrated policy documentation but you will
-be able to trace the behaviour and utilization of your systems over
-the lifetime of the virtual instance.
-
-@item @b{Set up databases using @code{database} promsises}
-
-Most users working in the cloud are running some kind of Model View Controller
-web framework in which a database (like MySQL or PostgreSQL) features
-importantly. With CFEngine Nova, you can also manage the creation of
-databases for the setting up the data services and applications
-inside PHP, Java and other frameworks.
-
-@end itemize
-
-
-
-@page
-@node The Cloud Pack Nursury
-@unnumberedsec The Cloud Pack Contents
-
-
-The files in the Cloud Pack fall into 3 categories: essential set up
-files for getting CFEngine running, examples of pro-active maintenance
-and examples of basic machine installation and setup.
-@sp 1
-@multitable @columnfractions .35 .65
-@item @b{Essential Files} @tab @b{Description}
-@item @file{promises.cf} @tab Main configuration file.
-@item @file{update.cf} @tab Update configuration.
-@item @file{failsafe.cf} @tab Falisafe configuration.
-@item @file{cfengine_stdlib.cf} @tab CFEngine standard library.
-@end multitable
-
-@sp 1
-
-@multitable @columnfractions .35 .65
-@item @b{Maintenance examples} @tab @b{Description}
-@item @file{change_mgt.cf} @tab Implement security tripwire on files/directories.
-@item @file{ensure_ownership.cf} @tab Home directory ownership and permission maintenance.
-@item @file{fix_broken_software.cf} @tab Package installation and permission correction.
-@item @file{garbage_collection.cf} @tab Log rotation and removal.
-@item @file{harden_xinetd.cf} @tab Disable xinetd services specified.
-@item @file{iptables.cf} @tab Secure system with sysctl.conf and iptables.
-@item @file{name_resolution.cf} @tab Edit /etc/resolv.conf to the specified DNS servers
-@end multitable
-
-@sp 1
-
-@multitable @columnfractions .35 .65
-@item @b{System setup examples} @tab @b{Description}
-@item @file{c_cpp_env.cf} @tab Set up C programming environment.
-@item @file{db_mysql.cf} @tab Install and run MySQL
-@item @file{db_postgresql.cf} @tab Install and run PostgreSQL
-@item @file{db_sqllite.cf} @tab Install and run SQLlite
-@item @file{jboss_server.cf} @tab Prepare JAVA environment and run JBOSS.
-@item @file{nagios.cf} @tab Setup NAGIOS monitoring node.
-@item @file{nginx_perlcgi.cf} @tab Setup NGINX webserver perlCGI.
-@item @file{nginx_phpcgi.cf} @tab Setup NGINX webserver phpCGI.
-@item @file{ntp.cf} @tab Setup NTP server and clients.
-@item @file{perl_env.cf} @tab PERL programming language install.
-@item @file{php_webserver.cf} @tab Setup a PHP webserver.
-@item @file{python_env.cf} @tab PYTHON programming install.
-@item @file{ruby_env.cf} @tab Setup ruby on rails environment.
-@item @file{sshd_conf.cf} @tab Ensure sshd config is correct.
-@item @file{tomcat_server.cf} @tab Setup a tomcat server.
-@item @file{varnish.cf} @tab Set up Varnish web accelerator
-@end multitable
-
-
-@page
-@node Orion Support
-@unnumberedsec Orion Support
-
-@sp 1
-Your CFEngine Orion Cloud Pack comes with 30 days of email support to
-help you get started (@code{cloudsupport@@cfengine.com}). Support
-applies to the single individual who is recorded as the purchaser of
-the software, unless otherwise agreed with CFEngine.
-
-On receipt of a query, our engineers will respond
-withing 48 hours on business days for a maximum period of 30 days from
-the date of purchase of the Orion Cloud Pack. Existing users of
-CFEngine Nova will receive support transparently under their existing
-support arrangements.
-
-Support queries may cover issues connected with the use of CFEngine
-Orion Cloud Pack, but not with the use of your Cloud provider. Support
-does not include the development of new solutions or other consulting.
-Users are free to seek Professional Services from CFEngine for such
-matters.
-
-@node Orion License
-@unnumberedsec Orion License
-
-The CFEngine Orion Cloud Pack is not Free or Open Source Software.
-It is provided under a perpetual license as part of the
-CFEngine Cloud Pack (hereby called The Software). The Software may be
-used within a single Internet Domain. If no Internet Domain is
-registered, it may be used within a single legal organization
-possessing a maximum of 1024 computers, or by a single individual with
-up to 250 computers. Multiple licenses may be purchased, as needed.
-
-The Licensee may modify, adapt and create derivative works based upon
-the Software, for use within its organisation and for sharing between
-other consecutive licensees. However, the Licensee shall not
-reproduce, distribute, resell, rent, lease or disclose the Software in
-any manner or form to any other third party not holding a license for
-the Software.
-
-The Licensee may not transfer any of its rights under this agreement
-without the prior and express written consent of CFEngine.
-
-CFEngine does not transfer any copyrights or other intellectual
-property rights relating to the Software to the Licensee. Such rights
-are protected by intellectual property legislation in the United
-States, Europe and other jurisdictions and by international treaty
-provisions. CFEngine and its suppliers retain all rights in the
-Software that are not expressly granted to the Licensee through this
-license.
-
-The Licensee is not allowed to remove, alter or destroy any proprietary,
-trademark or copyright markings or notices placed upon or contained
-within the Software.
-
-To the maximum extent permitted by law, CFEngine disclaims any
-warranty for the Software. The Software, any services and any related
-documentation are provided on an "as is" basis without warranty of any
-kind, whether express or implied, including, but not limited to,
-implied warranties of merchantability, fitness for a particular
-purpose or non-infringement. Hereunder the parties acknowledges that
-CFEngine does not warrant for the performance of any data centre on
-which the Software runs, or the absence of any errors in the Software,
-and that any such errors does not constitute a contractual defect.
-
-The liability of the parties in contract, tort (including negligence)
-or otherwise shall for all incidents during the entire term of 30 days
-from the date of purchase be limited to a half of the fees paid for a
-perpetual license. CFEngine or its suppliers shall not be liable for
-any special, incidental, indirect or consequential damages whatsoever
-(including, without limitation, damages for loss of business profits,
-lost savings, business interruption, loss of business information,
-personal injury, loss of privacy, loss of goodwill or any other
-financial loss) arising out of the use of or inability to use the
-Software, even if advised of the possibility of such damages.
-
-For third-party software that is integrated with or used by
-CFEngine, the current terms of the relevant third party software
-supplier shall apply.
-
-
-
-@page
-@node Cultural References to Orion and Cloud
-@unnumberedsec Cultural References to Orion and Cloud
-
-Orion, the hunter from Greek mythology, was taken by renaissance
-mythologist Natalis Comes to be an allegory for an approaching storm
-cloud.
-
-Better-known today, Orion is the name of one of the most famous and
-studied astronomical constellations in the night sky. It contains the
-three bright stars of Orion's belt (the three steps to the cloud) and
-the @i{Orion M42 Nebula} (a gigantic dust cloud):
-@url{http://en.wikipedia.org/wiki/Orion_Nebula} beneath its belt.
-Now with the CFEngine Orion Cloud Pack, you too can get the Cloud
-under your belt.
-
-The Orion Nebula is, in fact, part of a much larger cloud or nebula in
-the constellation of Orion
-(@url{http://en.wikipedia.org/wiki/Orion_Molecular_Cloud_Complex}). We
-chose the name Orion for our Cloud Pack (apart from the obvious puns)
-because we believe that Cloud Computing is only a stepping stone
-towards what we term @i{Molecular Computing}, in which many
-independent platforms and services bond together to form @i{network
-patterns}. These patterned systems act like molecules with new
-properties, bonded together by @i{promises}. This view follows
-naturally from a description of computing using Promise Theory,
-replacing traditional monolithic and hierarchical systems with a more
-natural form of engineering
-(@url{https://cfengine.com/inside/deepBackground}).
-
-@sp 1
-@center{@image{Orion,9cm,,Orion,png}}
-
-@center{Hubble Image: http://apod.gsfc.nasa.gov/apod/ap051013.html}
-
-
-
-@node EC2 Cloud Command line setup
-@appendix EC2 Cloud command line setup
-
-This Appendix details the creation of an EC2 instance, i.e. the
-pre-requisites for CFEngine installation, using a command-line approach.
-You may also use the web interface.
-
-For greater depth and explanation of all the commands and options see
-the getting started guide:
-@smallexample
-@url{http://docs.amazonwebservices.com/AWSEC2/latest/GettingStartedGuide/}.
-@end smallexample
-
-@sp 2
-@enumerate
-@item Create an amazon web services account and sign up for Amazon Elastic Compute Cloud (EC2) at @url{http://aws.amazon.com/ec2/}.
-
-@item Login and go to the access identifiers page.
-
-@item Create new X.509 certificate.
-
-@item Download the private key file and the X.509 certificate.
-
-@item Download the EC2 api tools:
-@smallexample
-http://developer.amazonwebservices.com/connect/entry.jspa
-?categoryID=88&externalID=351
-@end smallexample
-
-@item Extract the tools into a suitable directory: $dir.
-
-@item Setup EC2 control environment:
-@itemize
- @item Install Java
- @item @code{export EC2_HOME=~/$dir}
- @item @code{export PATH=$PATH:$EC2_HOME/bin}
- @item @code{export EC2_PRIVATE_KEY=pk-KEYNAME.pem}
- @item @code{export EC2_CERT=cert-KEYNAME.pem}
- @item @code{export JAVA_HOME=/path/to/java/}
-@end itemize
-@item Create keys for accessing your instances:
-@itemize
- @item @code{cd $dir}
- @item @code{ec2-add-keypair keyname}
- where 'keyname' is users choice.
- Save output to a file:
-@end itemize
-@itemize
- @item @code{vi $dir/keyname}
- @item paste in key and save.
- @item @code{sudo chmod 600 keyname}
-@end itemize
-@item Choose an Amazon Machine Image (AMI) to launch: e.g. @samp{ami-6d0be204}, an Ubuntu 9.10 server with CFEngine community pre-installed (small instance in us-east region).
-
-
-
-@item @b{Warning billing begins after the next command}. Run the instance:
-@itemize
- @item @code{ec2-run-instances ami-6d0be204 -k keyname}
-
- Note is it possible to launch an instance without specifying a
-key but it will not be accessible via ssh if you do not create one. The selected
-public AMI is an Ubuntu 9.10 i368 server with CFEngine community
-installed.
-@end itemize
-@item Get status of your instance:
-@itemize
- @item @code{ec2-describe-instances}
-
- This will reveal the external URL to your instance similar to:
-
- @code{ec2-xxx-xxx-xxx-xxx.compute-1.amazonaws.com}
-@end itemize
-
-@item Allow ssh:
-@itemize
- @item @code{ec2-authorize default -p 22}
-
- Note this will allow ssh access to all instances in the default security group from anywhere on port 22.
-
- @item Allow http traffic:
- @code{ec2-authorize default -p 80}
-@end itemize
-
-@item Access via ssh:
-@itemize
- @item @code{ssh -i keyname ubuntu@@ec2-xxx-xxx-xxx-xxx.compute-1.amazonaws.com}
-@end itemize
-@end enumerate
-
-
-
-@node EC2 Cloud CFEngine Configuration
-@appendix EC2 Cloud CFEngine Configuration
-
-You will need @code{root} access to the Amazon instance.
-@sp 1
-@enumerate
-@item Copy the CFEngine Orion Cloud Pack to your instance and unpack it:
-@smallexample
-scp -i keyname cloud_pack.tar ubuntu@@ec2-xxx-xxx-xxx-xxx.compute-1.amazonaws.com
-mv cloud_pack.tar /var/cfengine/masterfiles
-cd /var/cfengine/masterfiles
-tar xvf cloud_pack.tar
-@end smallexample
-
-@item Set policy server ip address: e.g.
-
-@code{ifconfig eth0 ...}
-
-@item Copy this IP address to the policy server variable in the @file{update.cf} and
-@file{promises.cf} files.
-
-@item @code{cf-agent -f /var/cfengine/masterfiles/failsafe.cf}
-@end enumerate
-
-@noindent Note billing continues as long as instances are running.
-To terminate an instance:
-
-@itemize
- @item @code{ec2-terminate-instances instance_number}
- The instance number (i-xxxxxxxx) is revealed by running:
- @item @code{ec2-describe-instances}
-@end itemize
-
-
-
-
-@node Integrating the Cloud Pack Futher
-@appendix Integrating the Cloud Pack Futher
-
-The Orion Cloud Pack is delivered in a form that makes it easy to choose the
-services. As you move forward, or want to integrate these methods into a larger
-framework, you can choose to alter the way in which you `call up' these
-methods.
-
-In the Cloud Pack, all bundles are listed in the @code{bundlesequence},
-making them simple to compare and comment out, but we may also re-bundle
-them in a single bundle like this:
-
-@verbatim
-body common control
-{
-bundlesequence => { "update", "main" };
-}
-
-@end verbatim
-
-@noindent To re-bundle, we create a single agent bundle (e.g. called `main') and
-call the bundles as method promises. An advantage of this is to make it easier to
-classify different parts of your configuration in a single location. For instance,
-you might want two groups of servers supporting different platforms, one supporting
-Ruby and one supporting PHP:
-
-@verbatim
-
-bundle agent main
-{
-methods:
-
- group1::
- "environment 1" usebundle => ruby_on_rails;
-
- group2::
- "environment 2" usebundle => php_apache;
-
- any::
- "common" usebundle => fix_broken_software;
- "common" usebundle => garbage_collection;
- "common" usebundle => harden_xinetd;
-}
-
-@end verbatim
-@noindent This approach allows a great control over the execution of the bundles,
-with additional transaction controls, but cannot be considered superior to the simple
-list used in the Cloud Pack. Ultimately this is a question of style.
-
-
-@node Ubuntu quirks
-@appendix Ubuntu quirks
-
-The Ubuntu operating systems does not have a root account you can log onto directly.
-You first log in as the @samp{ubuntu} user, and then type @samp{sudo su} to become
-root.
-
-@bye
diff --git a/docs/guides/SpecialTopic_Adoption.texinfo b/docs/guides/SpecialTopic_Adoption.texinfo
deleted file mode 100644
index e70d6dc158..0000000000
--- a/docs/guides/SpecialTopic_Adoption.texinfo
+++ /dev/null
@@ -1,297 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-adopt.info
-@settitle Adopting Cfengine in Your Organization
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Adopting CFEngine in Your Organization
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-CFEngine is a framework and a methodology with far reaching
-implications for the way you do IT management. The CFEngine approach
-asks you to think in terms of @i{promises} and @i{cooperation} between
-parts; it automates repair and maintenance processes and provides
-simple integrated Knowledge Management.
-
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2009 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@node Top, What does adoption involve?, (dir), (dir)
-@top Adoption
-@menu
-* What does adoption involve?::
-* The Mission Plan::
-* Commercial or Free?::
-* Installation or Pilot::
-* Identifying the Team::
-* Training and Certification::
-* Mission Goal and Knowledge Management::
-* Build::
-* Contact CFEngine::
-@end menu
-
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@node What does adoption involve?, The Mission Plan, Top, Top
-@unnumberedsec What does adoption involve?
-@sp 1
-
-CFEngine is a framework and a methodology with far reaching
-implications for the way you do IT management. The CFEngine approach
-asks you to think in terms of @i{promises} and @i{cooperation} between
-parts; it automates repair and maintenance processes and provides
-simple integrated Knowledge Management.
-
-To use CFEngine effectively, you should spend a little time learning
-about the approach to management, as this will save you a lot of time
-and effort in the long run.
-
-@node The Mission Plan, Commercial or Free?, What does adoption involve?, Top
-@unnumberedsec The Mission Plan
-@sp 1
-
-At CFEngine, we refer to the management of your datacentre as `The
-Mission'. The diagram below shows the main steps in preparing mission
-control. Some training is recommended, and as much planning as you can
-manage in advance. Once a mission is underway, you should expect to
-work by making small corrections to the mission plan, rather than
-large risky changes.
-
-@center @image{MissionPlan,10cm,,Mission Plan,png}
-
-Planning does not mean sitting around a table, or in front of a whiteboard.
-Successful planning is a dialogue between theory and practice. It should include
-test pilots and proof-of-concept implementations.
-
-@node Commercial or Free?, Installation or Pilot, The Mission Plan, Top
-@unnumberedsec Commercial or Free?
-@sp 1
-
-The first decision you should make is whether you will choose a route
-of commercial assistance or manage entirely on your own. You can
-choose different levels of assistance, from just training, to
-consulting, to commercial versions of the software that simplify
-certain processes and offer extended features.
-
-At the very minimum, we recommend that you take a training course
-on CFEngine. Users who don't train often end up using only a fraction
-of the software's potential, and in a sub-optimal way. Think of this
-as an investment in your future.
-
-The advantages of the commercial products include greatly simplified
-set up procedures, continuous monitoring and automatic knowledge
-integration. See the CFEngine Nova Supplement for more information.
-
-@node Installation or Pilot, Identifying the Team, Commercial or Free?, Top
-@unnumberedsec Installation or Pilot
-@sp 1
-
-You are free to download Community Editions of CFEngine at any time to
-test the software. There is a considerable amount of documentation and
-example policy available on the cfengine.com web-site
-to try some simple examples of system management.
-
-If you intend to purchase a significant number of commercial licenses
-for CFEngine software, you can request a pilot process, during which a
-specialist will install and demonstrate the commercial edition on
-site.
-
-@node Identifying the Team, Training and Certification, Installation or Pilot, Top
-@unnumberedsec Identifying the Team
-@sp 1
-
-CFEngine will become a core discipline in your organization, taking
-you from reactive fire-fighting to proactive and strategic
-practices. You should invest in a team that embraces its methods. The
-CFEngine team will become the enabler of business agility, security,
-reliability and standardization.
-
-The CFEngine team needs to have administrator or super-user access
-to systems, and it needs the `headroom' or `slack' to think
-strategically. It needs to build up processes and workflows that
-address quality assurance and minimize the risk of change.
-
-All teams are important centres for knowledge, and you should provide
-incentives to keep the core team strong and in constant dialogue with
-your organization's strategic leadership. Treat your CFEngine team as
-a trusted partner in business.
-
-@node Training and Certification, Mission Goal and Knowledge Management, Identifying the Team, Top
-@unnumberedsec Training and Certification
-@sp 1
-
-Once you have tried the simplest examples using CFEngine, we recommend
-at least three days of in-depth training. We can also arrange more
-in-depth training to qualify as a CFEngine Mission Specialist.
-
-@node Mission Goal and Knowledge Management, Build, Training and Certification, Top
-@unnumberedsec Mission Goal and Knowledge Management
-@sp 1
-
-The main aim of Knowledge Management is to learn from experience, and
-use the accumulated learning to improve the predictability of workflow
-processes. During every mission, there will be unexpected events, and
-an effective team will use knowledge of past and present to respond to
-these unpredictable changes with confidence
-
-The goal of an IT mission is a @i{predictable operational state} that
-lives up to specific policy-determined promises. You need to work out
-what this desired state should be before you can achieve it. No one
-knows this exactly in advance, and most organizations will change
-course over time. However, with good planning and understanding of the
-mission, such adjustments to policy can be small and regular.
-
-@sp 1
-
-@cartouche
-
-Many small changes are less risky than few large changes, and the
-culture of agility keeps everyone on their toes. Using CFEngine to run
-your mission, you will learn to work pro-actively, adjusting the system
-by refining the mission goal rather than reacting to unexpected
-events.
-
-@end cartouche
-
-@sp 1
-To work consistently and predictably, even when understaffed, requires
-a strategy for describing system resources, policy and state.
-CFEngine can help with all of these. See the Special Topics Guide on
-Knowledge Management.
-
-A major component of a successful mission, is documenting
-@i{intentions}. What is the goal, and how does it break down into
-concrete, achievable states? CFEngine can help you in this process,
-with training and Professional Services, but you must establish a
-culture of commitment to the mission and learn how to express these
-commitments in terms of CFEngine @i{promises}.
-
-@node Build, Contact CFEngine, Mission Goal and Knowledge Management, Top
-@unnumberedsec Build, Deploy, Manage, Audit
-@sp 1
-
-The four mission phases are sometimes referred to as
-
-@table @emph
-@item Build
-A mission is based on decisions and resources that need to
-be put assembled or `built' before they can be applied. This is
-the planning phase.
-
-In CFEngine, what you build is a template of proposed promises for the
-machines in an organization such that, if the machines all make and
-keep these promises, the system will function seamlessly as
-planned. This is how it works in a human organization, and this is how
-is works for computers too.
-
-@item Deploy
-Deploying really means launching the policy into production. In
-CFEngine you simply publish your policy (in CFEngine parlance these
-are `promise proposals') and the machines see the new proposals and
-can adjust accordingly. Each machine runs an agent that is capable of
-keeping the system on course and maintaining it over time without
-further assistance.
-
-@item Manage
-Once a decision is made, unplanned events will occur. Such incidents
-traditionally set off alarms and humans rush to make new transactions
-to repair them. Under CFEngine guidance, the autonomous agent manages
-the system, and humans only manage knowledge and have to deal with
-rare events that cannot be dealt with automatically.
-
-@item Audit
-CFEngine performs continuous analysis and correction, and commercial
-editions generate explicit reports on mission status. Users can sit
-back and examine these reports to check mission progress, or examine
-the current state in relation to the knowledge map for the mission.
-
-@end table
-
-@node Contact CFEngine, , Build, Top
-@unnumberedsec Contact CFEngine
-@sp 1
-
-Contact CFEngine today for more information: @code{contact@@CFEngine.com}.
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_Agility.texinfo b/docs/guides/SpecialTopic_Agility.texinfo
deleted file mode 100644
index ce638c2aab..0000000000
--- a/docs/guides/SpecialTopic_Agility.texinfo
+++ /dev/null
@@ -1,1293 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-agility.info
-@settitle Agility in Infrastructure Engineering
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Agility in Infrastructure Engineering
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-
-@cartouche
-@quotation
-Agility is a widely used term in today's fast moving IT industry. It
-reflects a need and a desire to respond quickly to changes in the
-environment. This document explains the management factors that
-affect speed, agility and scale in common scenarios, and what CFEngine can
-do to help you be agile.
-@end quotation
-@end cartouche
-
-@vskip 2cm
-Last updated December 2011
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2011 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@node Top, Understanding Agility, (dir), (dir)
-@top Agility
-
-
-
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-
-
-@menu
-* Understanding Agility::
-* Aspects of CFEngine that bring agility::
-* Agility in your work::
-@end menu
-
-@node Understanding Agility, Aspects of CFEngine that bring agility, Top, Top
-@chapter Understanding Agility
-@sp 1
-
-We intuitively recognize agility as the capability to respond rapidly
-enough and flexibly enough to a difficult challenge. If we imagine an
-animal surviving in the wild, a climber on a rock-face or a wrestler engaged in
-combat, we identify the skills of @i{anticipation}, @i{speed} of response and
-the ability to @i{adapt} or bend without breaking to meet the challenges.
-
-@itemize
-@item Anticipate.
-@item Act.
-@item Adapt.
-@end itemize
-
-In infrastructure management, agility represents the need to handle
-changing demand for service, to repair an absence of service, and to
-improve and deploy new services in response to changes from users and
-market requirements. It is tied to economic, business or work-related
-imperatives by the need to maintain a competitive lead.
-
-The compelling event that our system must respond to might represent
-danger, or merely a self-imposed deadline. In either case, there is
-generally a penalty associated with a lack of agility: a blow, a fall or
-a loss.
-
-
-@menu
-* What make agility possible?::
-* The capacity of a system::
-* Speed::
-* Precision::
-* Comprehension::
-* Efficiency::
-@end menu
-
-@c .....................................................................
-@node What make agility possible?, The capacity of a system, Understanding Agility, Understanding Agility
-@section What make agility possible?
-@sp 1
-
-To understand agility, we have to understand time and the @i{capacity}
-for change. Agility is a relative concept: it's about adapting quickly
-enough, in the right context, with the right measure and in the right
-way. Below, we'll try to gain an @i{engineering} perspective on agility to
-see what enables it and what throttles it.
-
-@sp 1
-@cartouche
-@noindent To respond to a challenge there are four stages that need attention:
-
-@itemize
-@item To comprehend the challenge.
-@item To solve the challenge.
-@item To respond to the challenge.
-@item To confirm or verify the response.
-@end itemize
-@end cartouche
-
-@sp 1
-Each of these phases takes actual clock-time and requires a certain flexibility.
-Our goal is to keep these phases simple and therefore cheap for the long-term.
-Affording the time and flexibility needed is the key to being agile.
-Technology can help with this, if we adopt sound practices.
-@sp 1
-
-@cartouche
-Intuitively, we understand agility to be related to our capacity to
-respond to a situation.
-Let's try to pin this idea down more precisely.
-@end cartouche
-
-@c .....................................................................
-@node The capacity of a system, Speed, What make agility possible?, Understanding Agility
-@section The capacity of a system
-
-The capacity of a system is defined to be its maximum rate of
-change. Most often, this refers to speed of the system response to a
-single request@footnote{Capacity is often loosely referred to as `bandwidth'
-because of its connection to signal propagation in communication
-science, but this is not strictly correct, as bandwidth refers to parallel
-channels.}.
-
-In engineering, capacity is measured in @i{changes per second}, so it
-represents the maximum speed of a system within a single thread of
-activity@footnote{For example, for a single coding frequency, the capacity of
-a communications channel is measured in bits per second, and the
-bandwidth is the number multiplied by the number of parallel
-frequencies.}.
-
-
-@c .....................................................................
-@node Speed, Precision, The capacity of a system, Understanding Agility
-@section Speed
-
-
-Speed is the rate at which change takes place. For a configuration tool like CFEngine,
-speed can be measured either as
-
-@table @i
-@item Clock speed
-The actual elapsed wall-clock time-rate at which work gets done,
-including any breaks and pauses in the schedule.
-
-This depends on how often checks are made, or the interval between them,
- e.g. in CFEngine, the default
-schedule is to verify promises every five minutes.
-
-@item System speed
-The average speed of the system when it is actually busy working on a problem,
-excluding breaks and pauses. For example, once CFEngine has been scheduled
-at the end of a five minute interval, it might take a few seconds to
-make necessary changes.
-@end table
-
-Engineers can try to define an engineering scale of agility
-as the ratio of available speed to required speed and ratio of number
-ways a system can be changed to the number of ways imperatives require
-us to change.
-
-@sp 1
-
-@cartouche
-
-@i{Agility is proportional to both how much speed we can muster compared to what is required,
-and the number of change-capabilities we possess, compared to what
-we need to meet a challenge. In other words: how well equipped are we?
-As engineers, we could write something like this:}
-
-@verbatim
-
- Available speed under control Changes available
- Agility =~ ----------------------------- * -----------------------
- Required speed Changes Required
-@end verbatim
-@end cartouche
-@sp 1
-
-@noindent Although such a scale might be hard to measure and follow in practice,
-the definition makes simple engineering sense@footnote{If available
-speed matches need, and we have the capability to make all required
-changes, then we can claim exactly 100% agility. If we have less than
-required, then we get a smaller number, and if we have excess speed or
-changeability then we can even claim a super-efficiency.}, and brings
-some insight into what we need to think about.
-What it suggests is that agility is a combination of @i{speed} and @i{precision}.
-
-
-What is required speed? It is is the rate of change we have to be
-able to enact in order to achieve and maintain a state (keep a
-promise) that is aligned with our intent. This requires a dependence
-on technology and human processes.
-
-The weakest link in any chain of dependencies limits the speed.
-The weakest link might be a human who doesn't understand what to do, or a
-broken wire or a misconfigured switch, so there are many
-possible failure modes for agility. An organization is an information
-rich @i{society} with complex interplays between Man and Machine; agility
-challenges us to think about these weakest links and try to bolster
-them with CFEngine's technology.
-
-For example:
-
-@itemize
-@item If we think in terms of
-services, it is the Service Level you have to achieve in order to
-comply with a Service Level Agreement.
-
-@item If we think of a support
-ticket, it is the speed we have to work at in order to keep the impact
-of an unpredicted change within acceptable levels.
-@end itemize
-
-What we call `acceptable'
-is a subjective judgement, i.e. a matter for policy to decide. So
-there are many uncertainties and relativisms in such definitions. It would
-be inconceivable to claim any kind of industry standard for these.
-
-@sp 1
-@center @image{agility,12cm}
-@center How agility depends on technology measures.
-@sp 1
-
-
-We can write some scaling laws for the dependencies of agility to see where
-the failure modes might arise.
-@sp 1
-@cartouche
-@i{The speed available to meet a challenge
-is (on average) the maximum speed we can reliably maintain over time
-divided by the number of challenges we have to share between.}
-@verbatim
-
- Expected capacity * reliability
- Average available speed =~ -------------------------------
- Consumers or challenges
-@end verbatim
-@end cartouche
-@sp 1
-This expression says that the rate at which we get work done on average depends
-no only on how we share maximum capacity amongst a number of different consumers,
-clients, processes, etc, but also on how much of the time this capacity is fully
-available, perhaps because systems are down or unavailable.
-
-The appearance of reliability in this expression therefore tells us that maintenance
-of the system, and anticipation of failure will play a key role in agility.
-Remarkably this is usually unexpected for most practitioners, and most of system planning
-goes into first time deployment, rather than maintaining operational state.
-
-
-
-@c .....................................................................
-@node Precision, Comprehension, Speed, Understanding Agility
-@section Precision
-
-Acting quickly is not enough: we also need to be accurate in responding to
-change@footnote{In the 20th century, science learned that there is no such thing as
-determinism -- the idea that you can guarantee an outcome absolutely.
-If you still think in such terms, you will be quickly disappointed.
-The best we can accomplish is to maximize the likelihood of a
-predictable result, relative to the kind of environment in which we
-work.}. We need to be able to:
-
-@sp 1
-@itemize
-@item Model the desired outcome accurately in terms of universal policy coordinates: Why, When, Where, What, How.
-@item Maximize the chance that the promised outcome will be achieved.
-@end itemize
-@sp 1
-
-@noindent Precision is maximized when:
-
-@sp 1
-@itemize
-@item Changes are `precise', i.e. they can be made at a highly granular level, without disturbing areas that are not relevant (few side-effects).
-@item Policy is able to model or describe the desired state accurately, i.e. within the relevant area, the state is within acceptable tolerances.
-@item If any assumptions are hidden, they are describable in terms of the model, not determined by the limitations of the software@footnote{In some other configuration software, assumptions are hard-coded into the tools themselves, making the outcome
-undocumented.}.
-
-@item The agent executes the details of the model quickly and verifiably,
-in a partially unpredictable environment, i.e. it should be fault tolerant.
-@item If the model cannot be implemented, it is possible to determine why
-and decide whether the problem lies in an incorrect assumption or a flaw in the implementation.
-@end itemize
-@sp 1
-
-@cartouche
-CFEngine is a fault tolerant system -- it continues to work on what it
-can even when some parts of its model don't work out as
-expected@footnote{Other systems that claim to be deterministic simply stop with
-error messages. What is the correct behaviour? Clearly, this is a subjective choice. The important thing is that your
-system for change behaves in a predictable way.
-}.
-@end cartouche
-
-
-@c .....................................................................
-@node Comprehension, Efficiency, Precision, Understanding Agility
-@section Comprehension
-
-The next challenge is concerns a human limitation. One of the greatest
-challenges in any organization lies in comprehending the system.
-@sp 1
-@cartouche
-@i{Comprehensibility increases if something is predictable, or steady in its
-behaviour, but it decreases in proportion to the number of things we need
-to think about -- which includes the many different contexts such as environments,
-or groups of machines with different purposes or profiles.}
-@verbatim
- Predictability (Reliability) Predictability
- Comprehensibility =~ ---------------------------- = ----------------
- Contexts Diversity
-@end verbatim
-@end cartouche
-@sp 1
-@noindent Our ability to comprehend behaviour depends on how predictable it is, i.e.
-how well it meets our expectations. For technology, we expect
-behaviour to be as close as possible on our intentions. CFEngine's
-maintenance of promises ensures that this is done with best possible
-effort and a rapid cycle of checking.
-
-To keep the number of contexts to a minimum, CFEngine avoids mixing up
-@i{what} policy is being expressed with @i{how} the promises are
-kept. It uses a declarative language to separate the what from the
-how. This allows ordinary users to see what was intended without
-having to know the meaning of how, as was the case when scripting was
-used to configure systems.
-
-
-@c .....................................................................
-@node Efficiency, , Comprehension, Understanding Agility
-@section Efficiency
-
-Finally, if we think about the efficiency of a configuration, which is
-another way of estimating its simplicity, we are interested in how
-much work it takes to represent our intentions. There are two ways we
-can think about efficiency: the efficiency of the automated process
-and the human efficiency in deploying it.
-
-If the technology has a high overhead, the cost of maintaining
-change is high and efficiency is low:
-@sp 1
-@cartouche
-@i{The efficiency of the technology decreases with the more resources
-it uses, e.g. like memory and CPU. Resources used to run the technology
-itself are pure overhead and take away from the real work of your system.}
-@verbatim
- Resources used
- Resource Efficiency =~ 1 - ---------------
- Total resources
-@end verbatim
-@end cartouche
-@sp 1
-@noindent It is a design goal of CFEngine to maintain minimal overhead in
-all situations. The second aspect of efficiency is how much planning
-or rule-making is needed to manage the relevant issues.
-@sp 1
-@cartouche
-@i{The efficiency of a model decreases when you put more effort into
-managing a certain number of things. If you can manage a large number
-of things with a few simple constraints, that is efficient.}
-@verbatim
- Number of objects affected
- Model Efficiency =~ -------------------------------
- Number of rules and constraints
-@end verbatim
-@end cartouche
-@sp 1
-General patterns play a role too in simplifying, because the reduce the
-number of special rules and constraints down to fewer more generic rules.
-If we make good use of patterns, we can make few rules that cover many
-cases. If there are no discernible patterns, every special case is a
-costly exception. This affects not just the technology cost, but also
-the cognitive cost (i.e. the comprehensibility).
-
-Efficiency therefore plays a role in agility, because it affects the
-cost of change. Greater efficiency generally means greater speed,
-and more greater likelihood for precision.
-
-
-@c *******************************************************************************************
-@node Aspects of CFEngine that bring agility, Agility in your work, Understanding Agility, Top
-@chapter Aspects of CFEngine that bring agility
-@sp 1
-
-We can now summarize some qualities of CFEngine that favour agility:
-@sp 1
-@cartouche
-@enumerate
-@item Ability to express clear intentions about desired outcome (comprehension).
-@item Availability of insight into system performance and state (comprehension).
-
-@item Ability to manage large numbers of hosts and resources with a few generic patterns (efficiency).
-@item Ability to bundle related details into simple containers (comprehension without loss of adaptability).
-
-@item Ability to accurately customize policy down to a low level without programming (adaptability).
-
-@item Ability to recover quickly from faults and failures. The default, parallelized execution framework verifies promises every 5 minutes
-for rapid fault detection and change deployment (clock speed)@footnote{Two related concepts that are frequently referred to are the
-classic reliability measures: Mean Time Before Failure (MTBF) or
-proactive health and Mean Time To Repair (MTTR), speed of
-recovery:
-(i) If we are proactive or quick at recovering from
-minor problems, larger outages can be avoided. Recovery agility plays a
-role in avoiding cascade failure.
-
-(ii) If the time to repair is long, or the repair is inaccurate, this could
-result if more widespread problems. Inaccurate change or repair often leads to
-attempts to `roll-back', causing further problems.
-}
-.
-@item A quick system monitoring/sampling rate -- every 2.5 minutes (Nyquist frequency),
-for automated hands-free response to errors.
-@item Ability to recover cheaply. The lightweight resource footprint of CFEngine that consumes few system resources
-required for actual business (system speed -- low overhead, maximum capacity).
-
-@item Ability to increase number of clients without significant penalty (scalability and easy increase of capacity).
-
-@item A single framework for all devices and operating systems (ease of migrating from one platform to another).
-@end enumerate
-@end cartouche
-
-
-
-
-
-@c .....................................................................
-@menu
-* What agility means in different environments::
-* Separating What from How::
-* Packaging limits agility::
-* How abstraction improves agility::
-* Increasing system capacity - by scaling::
-@end menu
-
-@node What agility means in different environments, Separating What from How, Aspects of CFEngine that bring agility, Aspects of CFEngine that bring agility
-@section What agility means in different environments
-
-Let's examine some example cases where agility plays a role.
-Agility only has meaning relative to an environment, so in the following
-sections, we cite the remarks of CFEngine users (in quotes), and
-their example environments.
-
-Users' expectations for agility can differ dramatically in the present; but if we
-think just a few years down the line, and follow the trends, it seems clear
-that limber systems must prevail in IT's evolutionary jungle.
-
-
-@menu
-* Desktop management::
-* Web shops::
-* Cloud providers::
-* High Performance Computing::
-* Government::
-* Finance::
-* Manufacturing::
-@end menu
-
-@node Desktop management, Web shops, What agility means in different environments, What agility means in different environments
-@subsection Desktop management
-
-"The desktop space can be a very volatile environment, with multiple platforms."
-
-@table @i
-@item Speed:
-
-Speed is
-essential when there is a need to respond to a security threat that
-affects all of the desktop systems; e.g. when dealing with malware
-that requires the distribution of updated @file{virus.dat} files,
-etc. CFEngine can be very helpful by automating the process of
-distributing and restarting the application responsible for virus
-detection and mitigation. Systems that have been breached, need to be
-returned to known and secure state quickly to avoid loss. CFEngine can
-quickly detect and correct host based intrusions using file-scanning
-techniques and can secure hosts for examination, or just repair them
-quickly.
-
-Another case for agility lies in user request processing. For example,
-when a new user joins a workplace and needs resources such as desktop,
-laptop, phone, Internet connection, VPN connection, VM instances,
-etc. Speed is of the essence to minimize employee downtime.
-
-@item Precision:
-
-Desktop environments can involve many different platforms: Windows,
-multiple flavours of Linux and Macintosh, etc. A uniform low-cost way
-of `provisioning' and maintaining all of these, as well as responding
-to common threats is of significant value.
-
-Precision is important to ensure that the resources made available are
-indeed the correct ones. Inaccuracy can be a potential security issue,
-or merely a productivity question.
-
-Precision also comes into play when an enterprise rolls out new
-patches or productivity upgrades. These upgrades need to be uniformly
-and precisely distributed to all of the desktop systems during a given
-change window. By design, desktop clients running CFEngine
-automatically check for changes in system state and can precisely
-propagate desired state. In the case of system restoration due to
-corruption or hardware failure, CFEngine can greatly reduce the time
-needed to return to the most current enterprise build.
-
-@end table
-
-
-@node Web shops, Cloud providers, Desktop management, What agility means in different environments
-@subsection Web shops
-
-Modern web-based companies often base their entire financial
-operations around an active web site. Down-time of the web service is
-mission critical.
-
-@table @i
-@item Speed:
-
-The frequency of maintenance is not usually critical in web shops,
-since configuration changes can be planned to occur over hours rather
-than minutes. During software updates and system repairs, however,
-speed and orchestration are issues, as time lost during upgrades is
-often revenue lost, and a lack of coordination of multiple parts could
-cause effective downtime.
-
-It is therefore easy to scale the management of a web service, as change
-is rarely considered to be time-critical.
-
-Resource availability for the web service is an issue on busy web
-servers, however web services are typically quite slow already and it
-is easy to load balance a web service, so resource efficiency of the
-management software is not usually considered a high priority, until
-the possible savings become significant with thousands of hosts.
-
-Credit card information is subject to PCI-DSS regulation and requires
-a continuous verification for auditing purposes, but these systems are
-often separated from the main web service. Speed of execution can be seen
-as an advantage by some auditors where repairs to security matters and
-detection of breaches are carefully monitored.
-
-
-@item Precision:
-
-The level of customization in a web shop could be quite high, as there
-is a stack of interdependent services including databases and name
-services that have to work seamlessly, and the rate of deployment of
-new versions of the software might be relatively high.
-
-Customization and individuality is a large part of a website's business
-competitiveness. Maintaining precise
-
-@end table
-
-
-@node Cloud providers, High Performance Computing, Web shops, What agility means in different environments
-@subsection Cloud providers
-
-@table @i
-@item Speed:
-The cloud was designed for shorter time-scales, and relatively quick turnover of
-needs. That suggests that configuration will change quite often.
-For Infrastructure-as-a-Service providers and consumers, set up
-and tear-down rates are quite high so efficient and speedy configuration
-is imperative.
-
-@item Precision:
-
-For Software and Platform as a service providers, stability,
-high performance and regulation are key issues, and scaling up and down
-for demand is probably the fastest rate of change.
-
-@end table
-
-
-@node High Performance Computing, Government, Cloud providers, What agility means in different environments
-@subsection High Performance Computing
-
-High Performance clusters are typically found in the oil and gas
-industry, in movie, financial, weather and aviation industries, and
-any other modelling applications where raw computation is used to
-crunch numbers.
-
-@table @i
-@item Speed:
-
-The lightweight footprint of CFEngine is a major benefit here, as
-every CPU cycle and megabyte of memory is precious, so workflow is not
-disrupted.
-
-"A single node in the compute grid being out of sync with the others
-can cause the entire grid to cause failed jobs or otherwise introduce
-unpredictability into the environment, as it may produce results that
-differ from its peers. Thus it is imperative that repairs to an
-incorrect state happen as soon as possible, to minimize the impact of
-these issues."
-
-@item Precision:
-"Precision is exquisitely important in an HPC grid. When making a
-configuration change, due to the homogeneity of the environment, small
-changes can have enormous impacts due to the quantity of affected
-systems. I liken this to the "monoculture" problem in replanted
-forests -- everything is the same, so what would ordinarily be a
-small, easily-contained problem like a fungus outbreak, quickly
-spreads into an uncontrollable disaster. Thus, with HPC systems it is
-imperative that any changes deployed are precise, to ensure that no
-unintended consequences will occur. This is clearly directly related
-to comprehensibility of the environment -- it is difficult or
-impossible to make a precise change when you don't fully comprehend
-the environment."
-
-@end table
-
-
-@node Government, Finance, High Performance Computing, What agility means in different environments
-@subsection Government
-
-@table @i
-@item Speed:
-
-Government is not known for speed.
-
-
-@item Precision:
-
-"Government systems are reviewed and audited under FISMA and so one has
-often thought in terms of the ability to reduce complexity to make the
-problem manageable. Government typically wants the one-size-fits-all
-solution to system management and could benefit from something that
-can manage complexity and diversity while providing some central
-control (I bet you hate that word). The only thing we might have in
-common with finance is auditing but I'm sure the methods and goals are
-completely different. Finance is big money trying to make more big
-money. Government is focused more on compliance with its own
-regulations."
-
-
-@end table
-
-@node Finance, Manufacturing, Government, What agility means in different environments
-@subsection Finance
-
-@table @i
-@item Speed:
-
-One of the key factors in finance is liability. Fear of error, has led
-to very slow processing of change.
-
-High availability in CFEngine is used for continuous auditing and
-security. Passing regulatory frameworks like SOX, SAS-70, ISO 20k, etc
-can depend on this non-intrusive availability. Liability is a major
-concern and significant levels of approval are generally required to
-make changes, with tracking of individual responsibility. Out-of-hours
-change windows are common for making upgrades and making intended
-changes. Scalability of reporting is a key here, but change happens
-slowly.
-
-
-@item Precision:
-
-Security and hence tight control of approved software are major challenges
-in government regulated institutions. Agility has been a low priority
-in the past, but this will have to change as the rest of the world's
-IT services accelerate.
-
-@end table
-
-
-@node Manufacturing, , Finance, What agility means in different environments
-@subsection Manufacturing
-
-SCADA (supervisory control and data acquisition) generally refers to
-industrial control systems (ICS): computer systems that monitor and
-control industrial, infrastructure, or facility-based processes, as
-described below.
-
-@table @i
-@item Speed:
-
-Manufacturing is a curious mix of all the mention areas and more. In
-addition to the above, there is an tool component. The
-tools can design, build, test, track, and ship a physical
-unit. Downtime of any component is measured in missed revenue,
-so speed of detection and repair is crucial.
-
-
-@item Precision:
-
-
-"We need to ensure agility and accuracy of
-reporting. We need to know what is going on at any microsecond of the
-day. One faulty tool can throw a wrench in the whole works. The
-digital equivalent of the steam whistle to stop the line.
-
-From there, all the tool information is fed upstream to servers, from
-there to databases, then reports, that statistical analysis, and so
-on. Each piece needs to move with the product and incorporate it. It
-is a steady chain of events where are all information is liquid and
-relevant.
-
-Not only do you have the security requirements, from virus updates to
-top secret classification, but these tools need to never stop,
-ever. Also, these tools need constant reconfiguration depending on the
-product they are working on: e.g. you can't use the same set of
-procedures on XBox chip as a cellphone memory module. And all the
-tools are different too: one may be a probe to detect microscopic
-fractures in the layers, one tool may just track it's position in
-line. Supply and demand, cost and revenue."
-
-
-
-@end table
-
-
-@c .....................................................................
-@node Separating What from How, Packaging limits agility, What agility means in different environments, Aspects of CFEngine that bring agility
-@section Separating What from How (DevOps)
-@sp 1
-
-If you have to designs a programmatic solution to a challenge, it will
-cost you highly in terms of cognitive investment, testing and clarity
-of purpose to future users. Thinking @i{process} (how) instead of @i{knowledge} (what) is
-a classic carry-over from the era of 2nd Wave industrialization@footnote{See @url{http://www.cfengine.com/blog/sysadmin-3.0-and-the-third-wave}}.
-
-@sp 1
-@cartouche
-Think of CFEngine as an active knowledge management system,
-rather than as a relatively passive programming framework.
-
-For `DevOps': programming is for your application, consider its deployment
-to be part of the documentation.
-@end cartouche
-@sp 1
-
-Many programmatic systems and `APIs' force you to explain how
-something will be accomplished and the statement about `what' the
-outcome will be is left to an implicit assumption. Such systems are
-called imperative systems.
-
-CFEngine is a declarative system. In a declarative system, the reverse
-is true. You begin by writing down What you are trying to accomplish
-and the How is more implicit. The way this is done is by separating
-data from algorithm in the model. CFEngine encourages this with its
-language, but you can go even further by using the tools optimally.
-
-CFEngine allows you to represent raw data as variables, or as
-strings within your policy. For example:
-
-@smallexample
-bundle agent name
-@{
-vars:
-
- "main_server" string => "abc.123.com";
-
- "package_source[ubuntu]" string => "repository.ubuntu.com";
- "package_source[suse]" string => "repository.suse.com";
-
- # Promises that use these data
- #
- # packages:
- # processes:
- # files:
- # services: , etc
-
-@}
-@end smallexample
-
-@noindent By separating `what' data like this out of the details of how
-they are used, it becomes easier to comprehend and locate, and it
-becomes fast to change, and the accuracy of the change is easily
-perceived. Moreover, CFEngine can track the impact of such a change by
-seeing where the data are used.
-
-@cartouche
-CFEngine's knowledge management can tell you which system promises
-depend on which data in a clear manner, so you will know the impact
-of a change to the data.
-@end cartouche
-
-You can also keep data outside your policy in databases, or sources like:
-
-@itemize
-@item LDAP
-@item NIS
-@item DNS
-@item System files
-@end itemize
-
-@noindent For example, reading in data from a system file is very convenient.
-This is what Unix-like system do for passwords and user management.
-
-@smallexample
-@end smallexample
-
-What you might lose when making an input matrix is the @i{why}.
-Is there an explanation that fits all these cases, or does each
-case need a special explanation? We recommend that you include
-as much information as possible about `why'.
-
-
-
-
-
-@c .....................................................................
-@node Packaging limits agility, How abstraction improves agility, Separating What from How, Aspects of CFEngine that bring agility
-@section Packaging limits agility
-@sp 1
-
-
-Atomicity enables agility. Atomicity, or the avoidance of dependency, is a
-key approach to simplicity. Today this is often used to argue to
-packaging of software.
-
-Handling software and system configuration as packages of data makes
-certain processes appear superficially easy, because you get a single object
-to deal with, that has a name and a version number.
-However, to maintain flexibility we should
-not bundle too many features into a package.
-
-@sp 1
-@cartouche
-@i{A tin of
-soup or a microwave meal might be a superficially easy way to make
-dinner, for many scenarios, but the day you get a visitor with special
-dietary requirements (vegetarian or allergic etc) then the
-prepackaging is a major obstacle to adapting: the recipe cannot be
-changed and repackaged without going back to the factory that made
-it. Thus oversimplification generally tends to end up sending up back
-to work around the technology.}
-@end cartouche
-@sp 1
-
-CFEngine's modelling language gives you control over the smallest
-ingredients, but also allows you to package your own containers
-or work with other suppliers' packages. This ensures that
-adaptability is not sacrificed for superficial ease.
-
-For example: your system's package model can cooperate with
-CFEngine make asking CFEngine to promise to work with the
-package manager:
-
-@verbatim
-
-packages:
-
- "apache2";
- "php5";
- "opera";
-
-@end verbatim
-
-@noindent If you need to change what happens under the covers, it
-is very simple to do this in CFEngine. You can copy the details
-of the existing methods, because the details are not hard-coded,
-and you can make your own custom version quickly.
-@verbatim
-
-packages:
-
- "apache2"
-
- package_method => my_special_package_manager_interface;
-
-@end verbatim
-
-
-@c .....................................................................
-@node How abstraction improves agility, Increasing system capacity - by scaling, Packaging limits agility, Aspects of CFEngine that bring agility
-@section How abstraction improves agility
-@sp 1
-
-Abstraction allows us to turn special cases into general patterns. This leads to a compression
-of information, as we can make defaults for the general patterns, which do not have to be
-repeated each time.
-
-Service promises are good example of this@footnote{Service promises,
-as described here, were introduced into version 3.3.0 of CFEngine in
-2012.}, for example:
-
-@verbatim
-services:
-
- "www";
-
-@end verbatim
-@noindent In this promise, all of the details of what happens to turn on the
-web service have been hidden behind this simple identifier @samp{www}.
-This looks easy, but is it simple?
-
-In this case, it is both easy and simple. Let's check why. We have to
-ask the question: how does this abstraction improve speed and precision
-in the long run?
-
-Obviously, it provides short term ease by allowing many complex
-operations to take place with the utterance of just a single
-word@footnote{All good magic stories begin like this.}. But any
-software can pull that smoke and mirrors trick. To be agile, it must
-be possible to understand and change the details of what happens when
-this services is promised. Some tools hard-code processes for this kind
-of statement, requiring an understanding of programming in a
-development language to alter the result. In CFEngine, the definitions
-underlying this are written in the high-level declarative CFEngine
-language, using the same paradigm, and can therefore be altered by the
-users who need the promise, with only a small amount of work.
-
-Thus, simplicity is assured by having consistency of interface
-and low cost barrier to changing the meaning of the definition.
-
-
-@c .....................................................................
-@node Increasing system capacity - by scaling, , How abstraction improves agility, Aspects of CFEngine that bring agility
-@section Increasing system capacity (by scaling)
-
-Capacity in IT infrastructure is increased by increasing machine
-power. Today, at the limit of hardware capacity, this typically means
-increasing the number of machines serving a task. Cloud services have
-increased the speed agility with which resources can be deployed --
-whether public or private cloud --
-but they do not usually provide any customization tools. This is
-where CFEngine brings significant value.
-
-The rapid deployment of new services is assisted by:
-
-@sp 1
-@itemize
-@item Virtualization hypervisor control or private cloud management (libvirt integration).
-@item Rapid, massively-parallelized custom configuration.
-@item Avoidance of network dependencies.
-@end itemize
-@sp 1
-
-Related to capacity is the issue of scaling services for massive available
-capacity.
-
-By scalability we mean the intrinsic capacity of a system to
-handle growth. Growth in a system can occur in three ways: by the volume of input
-the system must handle, in the total size of its infrastructure,
-and by the complexity of the processes within it.
-
-For a system to be called scalable, growth should proceed unhindered,
-i.e. the size and volume of processing may expand without
-significantly affecting the average service level per node.
-
-Although most of us have an intuitive notion of what scalability
-means, a full understanding of it is a very complex issue, mainly
-because there are so many factors to take into account. One factor
-that is often forgotten in considering scalability, is the human
-ability to @i{comprehend} the system as it grows. Limitations of
-comprehension often lead to over-simplification and
-lowest-common-denominator standardization.
-
-Scalability is addressed in a separate document: @i{Scale and Scalability},
-so we shall not discuss it further here.
-
-
-
-
-@c *****************************************************************************
-@node Agility in your work, , Aspects of CFEngine that bring agility, Top
-@chapter Agility in your work
-
-@menu
-* Easy versus simple::
-* How does complexity affect agility?::
-* An effective understanding helps agility::
-* Maximizing business imperatives::
-* What does agility cost?::
-* Who is responsible for agility?::
-@end menu
-
-
-@c .....................................................................
-@node Easy versus simple, How does complexity affect agility?, Agility in your work, Agility in your work
-@section Easy versus simple
-
-@cartouche
-Just as we separate goals from actions, and strategy from tactics,
-so we can separate what is easy from what is simple. Easy brings
-short-term gratification, but simple makes the future cost less.
-@end cartouche
-@sp 1
-
-@i{Easy} is about barriers to adoption. If there is a cost associated with
-moving ahead that makes it hard:
-
-@itemize
-@item A psychological cost
-@item A cognitive cost
-@item It takes too long
-@item It costs too much money
-@end itemize
-
-@i{Simple} is about what happens next. Once you have started, what happens if you
-want to change something?
-
-Total cost of ownership is reduced if a design is simple, as there are
-only a few things to learn in total. Even if those things are hard to
-learn, it is a one-off investment and everything that follows will be easy.
-
-Unlike some tools, with CFEngine, you do not need to program `how' to
-do things, only what you want to happen. This is always done by using the
-same kinds of declarations, based on the same model. You don't
-need to learn new principles and ideas, just more of the same.
-
-
-
-@c .....................................................................
-@node How does complexity affect agility?, An effective understanding helps agility, Easy versus simple, Agility in your work
-@section How does complexity affect agility?
-@sp 1
-
-
-In the past@footnote{Perhaps not just in the past. We are emerging
-from an industrial era of management where mass producing everything
-the same was the cheapest approach to scaling up services. However,
-today personal freedom demands variety and will not tolerate such
-oversimplification.}, it was common to manage change by making
-everything the same. Today, the individualized @i{custom experience}
-is what today's information-society craves. Being forced into a
-single mold is a hindrance to adaptability and therefore to
-agility. To put it another way, in the modern world of commerce, consumers
-rule the roost, and agility is competitive edge in a market of many
-more players than before.
-
-Of course, it is not quite that simple. Today, we live in a culture of
-`ease', and we focus on what can be done easily (low initial
-investment) rather than worrying about long term simplicity (Total
-Cost of Ownership).
-
-At CFEngine, we believe that `easy' answers often suffer from the sin
-of over-simplification, and can lead to risky practices. After all, anyone can make
-something appear superficially easy by papering over a mess, or applying raw
-effort, but this will not necessarily scale up cheaply over time.
-Moreover, making a risky process `too easy' can encourage haste and
-carelessness.
-
-Any problem has an intrinsic complexity, which can be measured by the
-smallest amount of information required to manage it, without loss of control.
-
-
-@sp 1
-@cartouche
-@itemize
-@item @i{Ease} is the absence of a barrier or cost to action.
-
-@item @i{Simplicity} is a strategy for minimizing Total Cost of Ownership.
-@end itemize
-@end cartouche
-@sp 1
-
-Making something truly simple is a very hard problem, but it is an
-investment in future change. What is easy today might be expensive to make easy tomorrow.
-But if something is truly simple, then the work is all up front in learning
-the basics, and does not come
-as an unexpected surprise down the line.
-
-At CFEngine, we believe in agility through simplicity, and so we
-invest continuous research into making our technology genuinely simple for trained
-users. We know that a novice user will not necessarily find CFEngine easy, but
-after a small amount of training, CFEngine will be a tool for life, not just a hurried
-deployment.
-
-Simplicity in CFEngine is addressed in the following ways:
-
-@sp 1
-@itemize
-@item The software has few dependencies that complicate installation and upgrading.
-@item Changes made are atomic and minimize dependencies.
-@item Each host works as an independent entity, reducing communication fragility.
-@item The configuration model is based on Promise Theory -- a very consistent and simple
-approach to modelling autonomous cooperative systems.
-@item All hosts run the same software agents on all operating
-platforms (from mobile phones to mainframes), and understand a single common language of intent, which they can translate into native system calls. So there are few exceptions
-to deal with.
-@item Comprehensive facilities are allowed for making use of patterns and other total-information-reducing tactics.
-@end itemize
-
-@sp 1
-A certain level of complexity might be necessary and desirable -- complexity is relative.
-Some organizations still try to remain agile by avoiding complexity. However, the ability
-to respond to complex scenarios often requires us to dabble with diversity. Avoiding
-it merely creates a lack of agility, as one is held back by the need to
-over-simplify.
-
-
-@c .....................................................................
-@node An effective understanding helps agility, Maximizing business imperatives, How does complexity affect agility?, Agility in your work
-@section An effective understanding helps agility
-@sp 1
-
-All configuration issues, including fitness for purpose, boil down to
-three things: why, what and how. Knowing why we do something is the
-most important way of avoiding error and risk of failure. Simplicity
-then comes from keeping the `what' and the `how' separate, and
-reducing the how to a predictable, repairable transaction. This is
-what CFEngine's @i{convergent promise} technology does.
-
-Knowledge is an antidote to uncertainty. Insight into patterns, brings
-simplicity to the information management, and insight into behaviour
-allows us to estimate impact of change, thus avoiding the risk associated
-with agility.
-
-@cartouche
-In configuration `what' represents transitory knowledge, while `how'
-is often more lasting and can be absorbed into the infrastructure. The
-consistency and repairability of `how' makes it simpler to change what
-without risk.
-@end cartouche
-
-
-
-@c .....................................................................
-@node Maximizing business imperatives, What does agility cost?, An effective understanding helps agility, Agility in your work
-@section Maximizing business imperatives
-
-Agility allows companies and public services to compete and address
-the needs of continuous service improvement. This requires insight
-into IT operations from business and vice versa. Recently, the
-`DevOps' movement in web arenas has emphasized the need for a more
-streamlined approach to integrating business-driven change and IT
-operations. Whatever we choose to call this, and in whatever arena,
-`connecting the dots between business and IT' is a major enabler for
-agility to business imperatives.
-
-Some business issues are inherently complex, e.g. software
-customization and security, because they introduce multifaceted
-conflicts of interest that need to resolved with clear documentation
-about @i{why}.
-
-@sp 1
-@cartouche
-Be careful about choosing a solution because it has a low initial
-outlay cost. Look to the long term cost, or the Total Cost of Ownership
-over the next 5 years.
-
-Many businesses have used the argument: @i{everything is getting cheaper
-so it doesn't matter if my software is inefficient -- I can brute force
-it in a year's time with more memory and a faster CPU.} The flaw in this
-argument is that complexity and scale are also increasing, and you will
-need those savings down the line even more than you do now.
-@end cartouche
-@sp 1
-The ability to model our intentions in a clearly
-understandable way enables insight and understanding; this, in turn,
-allows us to anticipate and comprehend challenges. CFEngine's
-knowledge management features help to make the configuration itself a
-part of the documentation of the system. Instead of relying on command line tools
-to interact, the user documents intentions (as `promises to be kept').
-These promises, and how well they have been kept, can be examined either
-from the original specification or in the Mission Portal.
-
-In the industrial age, the strategy was to supply sufficient force to
-a small problem in order to `control' it by brute force. In systems
-today the scale and complexity are such that no such brute force
-approach can seriously be expected to work. Thus one is reduced to a more even
-state of affairs: learning to work with the environment `as is',
-with clear expectations of what is possible and controlling only certain
-parts on which crucial things depend.
-
-
-@c .....................................................................
-@node What does agility cost?, Who is responsible for agility?, Maximizing business imperatives, Agility in your work
-@section What does agility cost?
-@sp 1
-
-CFEngine is designed to have a low Total Cost of Ownership, by being
-exceptionally lightweight and conceptually simple. The investment in
-CFEngine is a `learning curve' that some find daunting. Indeed, at CFEngine,
-we work on reducing this initial learning curve all the time -- but what
-really saves you in the end is simplicity without over-simplification.
-
-@sp 1
-@cartouche
-At a recent deployment in the banking sector, CFEngine replaced an incumbent software solution
-where 200 machines were required to make the management infrastructure
-scale to the task.
-
-CFEngine replaced this with 3 machines, and a reduced workforce.
-After the replacement the clock-time required for system updates went
-from 45 minutes to 16 seconds.
-@end cartouche
-@sp 1
-
-The total cost of providing for agility can be costly or it
-can be cheap. By design, CFEngine aims to make scale and agility
-inexpensive in the long run.
-
-@c .....................................................................
-@node Who is responsible for agility?, , What does agility cost?, Agility in your work
-@section Who is responsible for agility?
-@sp 1
-
-The bottom line is: you are! Diversity and customization are basic
-freedoms that user-driven services demand in today's world, and having
-the agility to meet changing desires is going to be an increasingly
-important and prominent feature of IT, as we delve
-further into the information-based society.
-
-@sp 1
-@cartouche
-Competitive edge, response to demands, in both private sector and research,
-makes agility the actual product of a not-too-distant tomorrow.
-@end cartouche
-@sp 1
-
-Who or what makes agility a reality? The simple answer to this
-question is everyone and everything. Change is a chain of dependent
-activities and the weakest link in the chain is the limiting
-factor. Often, that is human knowledge, since it is the part of the
-chain that we take most for granted.
-
-CFEngine has been carefully designed to support agile operations for
-the long term, by investing in knowledge management, speed and
-efficiency.
-
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_ApplMgt.texinfo b/docs/guides/SpecialTopic_ApplMgt.texinfo
deleted file mode 100644
index ca56fcc543..0000000000
--- a/docs/guides/SpecialTopic_ApplMgt.texinfo
+++ /dev/null
@@ -1,522 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-appmgt.info
-@settitle Application Management
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Application Management
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-CFEngine is able to install, update and uninstall services and
-applications across all managed nodes in a platform-independent
-manner.
-
-Updating software across all nodes can be made as simple as copying a
-package to a software server. Thereafter, applications can be managed
-and customized using CFEngine.
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2010 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@node Top, What is Application Management?, (dir), (dir)
-@top Application Management
-@menu
-* What is Application Management?::
-* How can CFEngine help?::
-* Package management::
-* Enterprise Software Reporting::
-* Integrated software installation::
-* Customizing applications::
-* Starting and stopping software::
-* Auditing software applications::
-@end menu
-
-
-
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@node What is Application Management?, How can CFEngine help?, Top, Top
-@unnumberedsec What is Application Management?
-@sp 1
-
-Application management concerns the deployment and updating of
-software, as well as customization of for actual use, in other words
-all the activities required to make an application ready for
-use. Initially, software installation packages must be deployed on
-host machines, however, we frequently encounter the need to update software due
-to security flaws, bugs or new features.
-
-It is generally unwise to let every application update itself
-automatically to the newest version from the internet; we want to
-decide which version gets installed and also make sure that the load
-on the network does not impair performance during mass-updates. Equally
-important is making sure certain applications are not present,
-especially when they are known to have security issues.
-
-Using CFEngine, you can verify that the software is in a
-promised state and is properly customized for use.
-
-@node How can CFEngine help?, Package management, What is Application Management?, Top
-@unnumberedsec How can CFEngine help?
-@sp 1
-
-CFEngine assists with application management in a number of ways. Following
-the BDMA lifecycle, we note:
-
-@table @i
-@item Build
-CFEngine can be used to automate the build of packaged software releases
-using standardized or custom package formats.
-@item Deploy
-CFEngine can distribute and install packaged software on any kind of platform.
-@item Manage
-CFEngine can start, stop, restart, monitor, and upgrade, and customize software
-applications.
-@item Audit
-CFEngine can monitor and report on packages and patches installed on systems and their
-versions and status.
-@end table
-
-@node Package management, Enterprise Software Reporting, How can CFEngine help?, Top
-@unnumberedsec Package management
-@sp 1
-
-Application management is simple today on most operating systems due to the
-introduction of @i{package systems}.
-
-All major operating systems now have some sort of package management
-system, e.g. RPM for Linux, and MSI for Windows. However, their
-capabilities and methods vary greatly. Moreover, the packages they need
-to install have to be made available to the hosts that need them and
-the package manager has to be executed at the right time and
-place. This is where CFEngine assists.
-
-Some package managers support online automatic access of online
-repositories and can download data from the network. Others have to
-have packages copied to local storage first. CFEngine can work with
-both types of system to integrate software management.
-@itemize
-@item CFEngine communicates with the system using its own standards
-to utilize the approach suitable for that software system.
-@item Custom software repositories can be made, and CFEngine's
-agents can perform this distribution
-by collecting software packages to local storage and then
-installing from there.
-@end itemize
-
-When software packages are available on local storage, CFEngine
-can check whether they are already installed, and if so, which version
-and architecture are installed. This, in turn, can be verified against
-the policy for the software --- should it indeed be installed, updated or
-removed?
-
-Using the CFEngine standard library, agents know how to talk to the
-native package manager to query information and get the system into
-the desired state.
-
-CFEngine can edit configuration files in real time to ensure that
-applications are customized to local needs at all times.
-
-
-
-@node Enterprise Software Reporting, Integrated software installation, Package management, Top
-@unnumberedsec Enterprise Software Reporting
-@sp 1
-
-In commercial releases of CFEngine, the state of software installation
-is reported centrally and is easily accessible through the Knowledge
-Map.
-
-Commercial editions of CFEngine also support querying Windows machines
-for installed MSI packages and thus allows for easy software
-deployment in heterogeneous Unix and Windows
-environments.
-
-@node Integrated software installation, Customizing applications, Enterprise Software Reporting, Top
-@unnumberedsec Integrated software installation
-@sp 1
-
-CFEngine gives complete freedom to users, so there are many
-ways to design a system that achieves a desired software end-state. Consider
-the following example setup which ensures that one particular
-application is up to date on all hosts. The procedure below is
-very similar to the way that commercial CFEngine editions update.
-
-Rather than using an OS-specific package repository, like yum, we
-create a universal approach using CFEngine's distribution and
-installation promises.
-
-We first look at the example on an RPM system, then we show the
-modifications required to handle Windows instead. The examples
-use body parts from the standard library.
-
-@sp 1
-@center @image{update,10cm,,Updating software.,png}
-@sp 1
-
-
-
-@menu
-* Distributing software packages to client hosts::
-* Stopping and restarting an application for update::
-* Adapting to Windows::
-* Notes on Windows systems::
-@end menu
-
-@node Distributing software packages to client hosts, Stopping and restarting an application for update, Integrated software installation, Integrated software installation
-@unnumberedsubsec Distributing software packages to client hosts
-
-To begin with, we promise that the relevant software packages will be locally
-available to the agents from software servers, i.e. we promise that a
-local copy of all deployed software packages will exist in the
-directory @file{/software_repo} on local storage. The copy will be collected
-and compared against a directory called @file{/master_software_repo}
-on host @code{server.example.org} in this example.
-
-@sp 1
-@cartouche
-We say that this approach is @file{data-driven} because, by placing
-software package data in the central repository, client hosts update
-automatically, as they promise to subscribe to the data.
-@end cartouche
-
-@sp 1
-
-@verbatim
-files:
-
- "/software_repo"
-
- comment => "Copy app1 updates from software server",
- copy_from => remote_cp("/master_software_repo/app1/$(sys.flavour)",
- "server.example.org"),
- depth_search => recurse("inf"),
- classes => if_repaired("newpkg_app1");
-
-@end verbatim
-
-When the agent copies a relevant software package from the software
-server (@code{sys.flavour} is the local operating system), the class
-@code{newpkg_app1} will get defined. This class can act as a trigger
-to stop the application, update it, and start it again.
-
-@node Stopping and restarting an application for update, Adapting to Windows, Distributing software packages to client hosts, Integrated software installation
-@unnumberedsubsec Stopping and restarting an application for update
-
-On some operating systems, software cannot be updated while it is running.
-CFEngine can promise to enure that a program is stopped before update:
-
-@verbatim
-processes:
-
- newpkg_app1::
-
- "app1" signals => { "term", "kill" };
-
-@end verbatim
-
-CFEngine @i{normal ordering}, ensures that @code{processes}
-promises are always run prior to @code{packages} promises, so the
-application will be stopped before updated. Next we promise the
-version of the software we want to install. In this case, any
-version greater than 1.0.0.
-
-@verbatim
-packages:
-
- newpkg_app1::
-
- "app1"
-
- package_policy => "update",
- package_select => ">=",
- package_architectures => { "i586" },
- package_version => "1.0.0",
- package_method => rpm_version("/software_repo"),
- classes => if_else("app1_update", "app1_noupdate");
-@end verbatim
-
-
-By promising carefully what package and version you want, using
-@code{package_policy}, @code{package_select}, and
-@code{package_version}, CFEngine can keep this promise by updating to
-the latest version of the package available in the directory
-repository @file{/software_repo}. If the available versions are all
-`less than' than "1.0.0", an update will not take place. The
-@code{package_version} specification should match the versioning
-format of the software, whatever it is, e.g. you would write something
-like "1.00.00.0" if two digits were used in the two middle version
-number positions.
-
-@sp 1
-@cartouche
-CFEngine automatically adapts its versioning
-to the conventions used by individual package schemas.
-@end cartouche
-@sp 1
-
-To summarize, in order for CFEngine to be able to match installed packages with the
-ones in the directory repository, the same naming convention must be
-applied. That is, the package name, version and architecture must have
-the same format in the list of installed packages as the file names of
-available packages.
-
-From the promise above, we see that CFEngine will interpret
-@code{app1} as the name, @code{1.0.0} as the version and @code{i586}
-as the architecture of the package. Using this while looking at the
-@code{package_name_convention} in the rpm package method, we see that
-CFEngine will look for packages named as @code{app1-X.Y.Z-i586.rpm},
-with X, Y, Z producing the largest version available in the directory
-repository. If an available version is larger than the one installed,
-an update will take place --- the update command is run.
-
-Finally, we set classes from the software update in case we want to
-act differently depending on the outcome.
-
-Replacing the policy @samp{update} with @samp{add} is all that is
-required to install the package (once) instead of updating. Using policy
-@samp{add} will do nothing if the package is already installed, but
-installs the largest version available if it is not. Use
-@code{package_select => "=="} to install the exact version instead of
-the largest.
-
-
-@node Adapting to Windows, Notes on Windows systems, Stopping and restarting an application for update, Integrated software installation
-@unnumberedsubsec Adapting to Windows
-
-@sp 1
-
-To adapt our example to Windows, we change the path to the local
-software repository from @file{/software_repo} to @file{c:\software_repo}, to
-support the Windows path format. Other than that, all we have to
-change is the @code{package_method}, yielding the following.
-
-@verbatim
-
- package_method => msi_version("c:\software_repo"),
-
-@end verbatim
-
-Refer to the @code{msi_version} body in the standard library.
-
-@node Notes on Windows systems, , Adapting to Windows, Integrated software installation
-@unnumberedsubsec Notes on Windows systems
-
-CFEngine implements Windows packaging using the MSI subsystem,
-internally querying the Windows Management Interface for information. However,
-not all Windows systems have the reqired information.
-
-CFEngine relies on the name (lower-cased with spaces replaced by
-hyphen) and version fields found inside the msi packages to look for
-upgrades in the package repository.
-
-Problems can arise when the format of these fields differ from their
-format in the file names. For example, a package file name may be
-@code{7zip-4.65-x86_64.msi}, while the product name in the msi is
-given as @code{7-Zip 4.65 (x64 edition)}, and the version is
-@code{4.65.00.0}.
-
-For the formats to match, we can change the product name to
-@code{7zip} and the version to @code{4.65} in the msi-package. Free
-tools such as @code{InstEd} can both view and change the product name
-and version (Tables->Property->ProductName and ProductVersion).
-
-
-@node Customizing applications, Starting and stopping software, Integrated software installation, Top
-@unnumberedsec Customizing applications
-
-@sp 1
-By definition, we cannot explain how to customize software for all
-cases. For Unix-like systems however, software customization is
-usually a matter of editing a configuration text file. CFEngine can
-edit files, for instance, to add a configuration line to a file, you
-might so something like this:
-
-@verbatim
-bundle agent my_application_customize
-{
-files:
-
- "$(prefix)/config.cf"
-
- comment => "Set the permissions and add a line...",
- perms => mo("0600","root"),
- edit_line => append_if_no_line("My custom setting...");
-}
-
-@end verbatim
-@noindent To set a number of variables inside a file, you might do something like this:
-@verbatim
-bundle agent my_application_customize
-{
-vars:
-
- # want to set these values by the names of their array keys
-
- "rhs[serverhost]" string => "123.456.789.123";
- "rhs[portnumber]" string => "1234";
- "rhs[admin]" string => "admin@example.org";
-
-files:
-
- "$(prefix)/config.cf"
-
- comment => "Add new variables or set existing ones",
- edit_line => set_variable_values("setvars.rhs");
-
-}
-
-@end verbatim
-You can also create file templates with customizable variables using
-the @code{expand_template} method from the standard library.
-
-@node Starting and stopping software, Auditing software applications, Customizing applications, Top
-@unnumberedsec Starting and stopping software
-
-CFEngine is promise or compliance oriented. You promise whether software will be
-running or not running at different times and locations by making
-@code{processes} or @code{services} promises.
-
-To start a service, you might do something like this:
-
-@verbatim
-processes:
-
- "myprocess" restart_class => "start_me";
-
-commands:
-
- start_me::
-
- "/path/to/software"
-
- # ... many security options, etc
-
-@end verbatim
-@noindent or using services
-@verbatim
-services:
-
- windows::
-
- "Dhcp"
- service_policy => "start",
- service_dependencies => { "Alerter", "W32Time" },
- service_method => winmethod;
-
-@end verbatim
-To stop a service, you take one of these approaches:
-
-@verbatim
-processes:
-
- "badprocess"
- signals => { "term", "kill" };
-
- "snmp"
- process_stop => "/etc/init.d/snmp stop";
-
-@end verbatim
-
-
-
-@node Auditing software applications, , Starting and stopping software, Top
-@unnumberedsec Auditing software applications
-
-@sp 1
-Commercial Editions of CFEngine generate reports about installed
-software, showing package names and versions that are installed.
-There is a huge variety in the functionality offered by different
-package systems. The most sophisticated package managers are those
-provided by OpenSuSE Linux and RedHat. These know the difference
-between installation packages and software updates and can keep
-track of installed software transparently. Most package systems
-have fewer functions.
-
-CFEngine tries to make the best of each package system to collect
-information about the state of software. In commercial editions
-you have access to reports on the software installed on each system
-in the network, to the extent permitted by the software subsystems
-on those hosts.
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_BDMA.texinfo b/docs/guides/SpecialTopic_BDMA.texinfo
deleted file mode 100644
index e5977f9dad..0000000000
--- a/docs/guides/SpecialTopic_BDMA.texinfo
+++ /dev/null
@@ -1,335 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-bdma.info
-@settitle BDMA
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title BDMA
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-Build, Deploy, Manage, Audit is a simple and traditional model of the
-IT infrastructure lifecycle, based on human workflows and
-processes. CFEngine's approach to the IT infrastructure is somewhat
-different, but the four pillars of the lifecycle can still be
-addressed in the framework of automation. This guide explains how to
-think about the IT infrastructure lifecycle when using CFEngine.
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2009 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@node Top, What is BDMA?, (dir), (dir)
-@top BDMA
-@menu
-* What is BDMA?::
-* Stem cell hosts::
-* Recommendations for Build::
-* Recommendations for Deploy::
-* Recommendations for Manage::
-* Recommendations for Audit::
-* Summary BDMA workflow::
-@end menu
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@node What is BDMA?, Stem cell hosts, Top, Top
-@unnumberedsec What is BDMA?
-@sp 1
-
-The four mission phases are sometimes referred to as
-
-@table @emph
-@item Build
-A mission is based on decisions and resources that need to
-be put assembled or `built' before they can be applied. This is
-the planning phase.
-
-In CFEngine, what you build is a template of proposed promises for the
-machines in an organization such that, if the machines all make and
-keep these promises, the system will function seamlessly as
-planned. This is how it works in a human organization, and this is how
-is works for computers too.
-
-@item Deploy
-Deploying really means launching the policy into production. In
-CFEngine you simply publish your policy (in CFEngine parlance these
-are `promise proposals') and the machines see the new proposals and
-can adjust accordingly. Each machine runs an agent that is capable of
-keeping the system on course and maintaining it over time without
-further assistance.
-
-@item Manage
-Once a decision is made, unplanned events will occur. Such incidents
-traditionally set off alarms and humans rush to make new transactions
-to repair them. Under CFEngine guidance, the autonomous agent manages
-the system, and humans only manage knowledge and have to deal with
-rare events that cannot be dealt with automatically.
-
-@item Audit
-CFEngine performs continuous analysis and correction, and commercial
-editions generate explicit reports on mission status. Users can sit
-back and examine these reports to check mission progress, or examine
-the current state in relation to the knowledge map for the mission.
-
-@end table
-
-@image{BDMA_model,12cm,,,,png}
-
-
-@node Stem cell hosts, Recommendations for Build, What is BDMA?, Top
-@unnumberedsec Stem cell hosts
-@sp 1
-At CFEngine we talk about stem cell hosts. A stem cell host is a generic
-foundation of software that is the @i{necessary and sufficient} basis for
-any future purpose. To make a finished system from this stem cell host,
-you only have to `differentiate' the system from this generic basis by running CFEngine.
-
-Differentiation of hosts involves adding or subtracting software packages,
-and/or configuring the basic system. This strategy is cost effective,
-as you do not have to maintain more than one base-line `image' for
-each operating system; rather, you use CFEngine to implement and
-maintain the morphology of the differences. Stem cell hosts are
-normally built using PXE services by booting and installing automatically
-from the network.
-
-@node Recommendations for Build, Recommendations for Deploy, Stem cell hosts, Top
-@unnumberedsec Recommendations for Build
-@sp 1
-There are many approaches to building complete systems.
-When you use CFEngine, you should try to progress from
-thinking only about putting bytes on disks, to planning
-a long term set of promises to keep.
-
-@itemize
-@item What services do you want to support?
-@item What promises do you want to keep concerning these services?
-@item Are these promises sustainable and convergently implementable?
-@item Formulate proposed intentions in the form of CFEngine promises.
-@item Discuss the impact of these in your team of CFEngine Mission Specialists (more than one pair of eyes).
-@end itemize
-
-It is worth spending extra time in the build planning to simplify
-your system as much as possible. A clear formulation here will save
-time both in maintenance and training later, as employees come and go.
-The better you understand your intentions, the simpler the system will be.
-
-We cannot emphasize enough the value of the promise discipline. If you can
-formulate your requirements as promises to be kept, you have identified not only
-what, where, when and how, but also who is responsible and affected by every promise.
-
-Building systems is resource intensive. CFEngine works well with @b{rPath}, allowing optimized
-build that can shave off many minutes from the build time for machines. CFEngine can then take over where
-rPath leaves off, performing surgically precise customization.
-
-@node Recommendations for Deploy, Recommendations for Manage, Recommendations for Build, Top
-@unnumberedsec Recommendations for Deploy
-@sp 1
-
-Deploying a policy is a potentially dangerous operation, as it will
-lead to change, with associated risk. Side-effects are common, and
-often result from incomplete planning. (See the CFEngine Special
-Topics Guide on @i{Change Management}).
-
-The following sequence forms a checklist for deploying successful policy change:
-@enumerate
-@item Discuss the impact of changes in the team.
-@item Commit the changes to promises in version control, e.g. subversion.
-@item Make a change in the CFEngine input files.
-@item Run the configuration through @samp{cf-promises --inform} to check for problems.
-@item Move the policy to a test system.
-@item Try running the configuration in dry-run model: @samp{cf-agent --dry-run}
-@item Try running the policy once on a single system, being observant of unexpected behaviour.
-@item Try running the policy on a small number of systems.
-@item Construct a test environment and examine the effect of these promises in practice.
-@item Move the policy to the production environment.
-@item If possible, test on one or a few machines before releasing for general use.
-@end enumerate
-
-CFEngine recommends a process of many small incremental changes, rather than large
-high-risk deployments.
-
-CFEngine allows you to apply changes at a much finer level of granularity than
-any package based management system, thus it complements basic package management with
-its deployment and real time repair (see next section).
-
-
-@node Recommendations for Manage, Recommendations for Audit, Recommendations for Deploy, Top
-@unnumberedsec Recommendations for Manage
-@sp 1
-
-Managing systems is an almost trivial task with CFEngine. Once a model
-for desired state has been created, you just sit back and watch. You
-should be ready for `hands free' operation. No one should make changes
-to the system by hand. All changes should follow the deployment
-strategy above.
-
-All that remains to do is wait for email alerts from CFEngine and to
-browse reports about the system state. In CFEngine Nova, these reports
-are generated automatically and integrated into the system knowledge
-base.
-
-Most email alerts from CFEngine are information only. It is possible
-(but not recommended) to make CFEngine very verbose about its
-operations. It is common to look for confirmation early in the phase
-of adopting CFEngine, as trust in the software is building. Eventually
-users turn off the verbosity and the default is for CFEngine to send
-as little email or output as possible.
-
-@cartouche
-Consider a single line E-mail, in confirmation of a change, arriving
-from 1000 computers in a single day. Learning to trust the software
-saves unnecessary communication and needless human involvement.
-The Nova Mission Portal makes notification and alerting largely
-unnecessary.
-@end cartouche
-
-@node Recommendations for Audit, Summary BDMA workflow, Recommendations for Manage, Top
-@unnumberedsec Recommendations for Audit
-@sp 1
-
-Auditing systems is a continuous process when using CFEngine
-Nova. Report data are collected on a continuous and distributed
-basis. These data are then collected from each distributed location
-according to a schedule of your choosing to collate and integrate the
-reports from all systems.
-
-The reports CFEngine provides are meant to offer simple summaries of
-the kind of information administrators need about their environment,
-avoiding unnecessary detail.
-
-@table @emph
-@item Available patches report
-Patches already installed on system if available.
-@item Classes report
-User defined classes observed on the system -- inventory data.
-@item Compliance report
-Total summary of host compliance, all promises aggregated over time.
-@item File_changes report
-Latest observed changes to system files with time discovered.
-@item File_diffs report
-Latest observed differences to system files, in a simple diff format.
-@item Hashes report
-File hash values measured (change detection).
-@item Installed patches report
-Patches not yet installed, but published by vendor if available.
-@item Installed software report
-Software already installed on system if available.
-@item Lastseen report
-Time and frequency of communications with peers, host reliability.
-@item Micro-audit report
-Generated by CFEngine self-auditing. This report is not aggregated.
-@item Monitor summary report
-Pseudo-real-time measurement of time series data.
-@item Performance report
-Time cost of verifying system promises.
-@item Promise report
-Per-promise average compliance report over time.
-@item Promises not kept report
-Promises that were recently un-kept.
-@item Promises repaired report
-Promises that were recently kept by repairing system state.
-@item Setuid report
-Known setuid programs found on system.
-@item Variables report
-Current variable values expanded on different hosts.
-@end table
-
-@node Summary BDMA workflow, , Recommendations for Audit, Top
-@unnumberedsec Summary BDMA workflow
-@sp 1
-
-@enumerate
-@item Define a stem cell host template
-@item Set up PXE network booting and kickstart / jumpstart OS tools with CFEngine integrated
-@item Get CFEngine running and updating on all hosts, but making no system changes.
-@item Define a service catalogue.
-@item Discuss and formulate a policy increment, thinking convergence at all times
-@item Publish (deploy) the policy.
-@item Follow emails and reports in the CFEngine Knowledge Map (Manage).
-@item Adjust policy if necessary, following procedures for change management (Manage)
-@item View reports (or enjoy the silence) to audit system state.
-@end enumerate
-
-CFEngine works well with package based management software. Users of
-rPath, for example, can achieve substantially improved efficiency in
-the build phase. CFEngine takes over where package based systems leave
-off, providing an unprecedented level of control `hands free'.
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_Change.texinfo b/docs/guides/SpecialTopic_Change.texinfo
deleted file mode 100644
index 7e54311e37..0000000000
--- a/docs/guides/SpecialTopic_Change.texinfo
+++ /dev/null
@@ -1,634 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-change.info
-@settitle Change Management and Incident Repair
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Change Management and Incident Repair
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-Change Management is about the planning and implementation
-of intended changes to an IT system, as well as the detection,
-documentation and possible repair of unintended changes.
-Change Management involves the assessment of current system state,
-the planning, testing and quality assurance cycles, and
-scheduling of improvements.
-
-This guide explains change management in the
-framework of CFEngine's self-healing automation.
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2009, updated 2011 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-
-
-
-@node Top, What is change management?, (dir), (dir)
-@top Change Management
-@menu
-* What is change management?::
-* Regulation - authorized and unauthorized change::
-* Intended and unintended change::
-* How fast should changes be made?::
-* Partially centralized change::
-* The decision point::
-* Promises about change vs state::
-* Promises about change::
-* Change management and knowledge management::
-* Non-destructive change::
-* Change and convergence::
-* The change decision process or release management::
-* Deploying policy changes::
-@end menu
-
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@node What is change management?, Regulation - authorized and unauthorized change, Top, Top
-@unnumberedsec What is change management?
-@sp 1
-Change Management is about the planning and implementation
-of intended changes to an IT system, as well as the detection,
-documentation and possible repair of unintended changes.
-Change Management involves the assessment of current system state,
-the planning, testing and quality assurance cycles, and
-scheduling of improvements.
-
-There are many accounts of change management in the industry. Often
-these make assumptions about the management framework being used. In
-the context of CFEngine automation, some of these approaches are
-considered antiquated. This guide explains change management in the
-framework of CFEngine's self-healing automation.
-
-@node Regulation - authorized and unauthorized change, Intended and unintended change, What is change management?, Top
-@unnumberedsec Regulation: authorized and unauthorized change
-@sp 1
-
-It is common to speak of @i{authorized} and @i{unauthorized} change in
-the IT industry. Many organizations think in these authoritarian terms
-and use management techniques designed for a slower-moving
-world. Today's e-commerce companies usually have much more agile and
-dynamical processes for change.
-
-The purpose of change regulation is to minimize the risk of actions
-taken by humans, i.e. to avoid human error. This approach makes sense
-in low-tech companies that have environments where change is only
-about long-term wear and tear or intended modifications to
-infrastructure (like a adding new building, or fitting a new gasket on
-a car). In today's IT-driven organizations, problems arise a thousand
-or more times faster than that, and a new approach is needed.
-
-Procedures for change, based on legacy regulative methods are incorporated
-into popular frameworks for human management, such as ITIL. They begin
-by making a formal Request For Change (RFC), which is processed by
-management in order to secure permission to exercise a change during
-an allocated time-window. In some cases, an ordinary repair such as
-restarting a server could take weeks to process, as mandatory Root
-Cause Analysis (RCA) is undertaken. The Mean Time To Repair (MTTR) is
-dominated by internal bureaucracy.
-
-Today's IT-based organizations, experience unintended change too quickly
-for such a process however, and there is a real risk of lost revenues
-from not repairing issues quickly. As many organizations are fearful
-of litigation or management reprisals, preferring to err on the side of
-caution, it is necessary to evaluate the best strategy for avoiding
-exposure to risk.
-To use automation effectively, it makes sense to separate change management
-into two phases:
-@itemize
-@item Change of policy itself - which defines desired state.
-
-Policy has a strategic impact, and its change deserves a process that includes
-expert opinions, staged testing and ultimately a phased deployment
-during a controllable time-window.
-
-@item Change that brings systems into compliance with policy.
-
-Once policy is frozen for a period of time, any unintended changes
-must be considered infractions (non-compliance), and repairs should be made according
-to what has already been decided. This should happen without delay,
-rather than starting a new process to delay action. The ethical issue
-is now turned on its head: execessive caution in fixing what has
-already been decided may be seen as prevarication and even negligence.
-
-@end itemize
-
-@cartouche
-The CFEngine way of managing change is to migrate systems through
-states of @i{stable equilibrium}. One should not believe that systems
-continue flawlessly because no intended changes are made. Change
-management with CFEngine should be about planning one stable state
-after another, but expecting run-time errors. The rate at which you
-move through revisions of stable policy depends on your needs.
-The rate at which compliance is repaired should be `as soon as possible'.
-
-To use an analogy: if policy changes are like take-off and landing,
-then a period of stable operations is like a smooth flight, on course
-to the correct destination. If unintended changes happen to change
-that, like the weather, immediate course corrections should be made to
-avoid loss.
-@end cartouche
-
-
-@node Intended and unintended change, How fast should changes be made?, Regulation - authorized and unauthorized change, Top
-@unnumberedsec Intended and unintended change
-@sp 1
-
-To institue a rational approach to change management, i.e. one that is
-suited to business's operational time-scales, we need to think about
-separating change into two the categories implied above: change by
-design and change by fate. It is desirable to exercise due diligence
-in the design of a system's intended state, but we must be ready to
-quickly repair faults that might disrupt business services. We need
-to distinguish:
-@itemize
-@item Purposeful change of an intended policy (planning).
-@item Change in the actual system state and behaviour (implementation and maintenance).
-@end itemize
-What is intended and what actually happens should not be confused.
-It is impossible to `lock down' or fully control changes made to
-computer systems, without switching them off. A mandatory level of risk
-must be anticipated.
-
-
-@cartouche
-It is by defining a desired operational state that one can avoid re-processing
-every since repair to a system.
-@end cartouche
-
-@node How fast should changes be made?, Partially centralized change, Intended and unintended change, Top
-@unnumberedsec How fast should changes be made?
-@sp 1
-
-Time scales are crucially important in engineering, and deserve equal
-importance in IT management. Ask yourself: how do you know if
-something is changing or not? You've probably heard catchetisms such
-as:
-
-@itemize
-@item A watched kettle never boils.
-@item Tempus fugit (time flies).
-@end itemize
-
-These phrases capture the idea that, if we expect to see change at a
-certain rate, it is possible to miss changes that occur at either a
-faster or slower rate. When we manage a @i{dynamical} process, we have
-to attend to the system at the same rate as change takes place.
-
-
-If there is a process changing the system once a day, then to keep the
-system aligned with its desired state, there must be a corrective
-process that repairs this once per day (the Mean Time To Repair or
-MTTR should be the same as the Mean Time Before Failure MTBF), else
-the system will experience significant deviations from policy. In the
-worst case, this could result in security leaks or loss of
-revenue. This is not the full story of course: there will always be
-some delay between error and repair (actual time to repair). To
-minimize the impact of lost compliance and deviations from intended
-state, changes should be made before serious consequences can ensue
-that require more significant repairs@footnote{For example, suppose a
-process runs out of control and starts filling up logs with error
-messages -- the disk might fill up and cause a much more serious
-problem, such as a total system failure with crash, is this were left unattended.}.
-
-Thus, mean time to repair is not a metric that should be used to
-define ideal time to repair. The ideal time should be that which
-minimizes the risk of losses to operations, and therefore revenues.
-
-The advantage of CFEngine's two-phase approach to change is that
-approved changes can be made a quickly as possible, without
-significant use of resources. CFEngine's lightweight agents can
-run every five minutes to achieve a tight alignment with operational
-and business goals.
-
-@sp 1
-@cartouche
-In information theory, Nyquist's theorem says that, in order to properly
-track (and potentially correct) a process that happens at rate @math{R},
-one must sample the system at twice this rate @math{2R}.
-In CFEngine, we have chosen a repair resolution of 5 minutes for configuration
-sampling, because measurements show that many system characteristics have
-auto-correlations times of 10-20 minutes@footnote{Nyquist's
-theorem is the main reason why CD-players sample at 44kHz in order to cover the
-audible spectrum of 22kHz for most young people. Even though hearing deteriorates
-with age, and most people cannot hear this well, it provides a quality margin.}.
-@end cartouche
-
-@node Partially centralized change, The decision point, How fast should changes be made?, Top
-@unnumberedsec Partially centralized change
-@sp 1
-
-It is not necessary to assume a central model of authority to manage
-change. Indeed, many CFEngine users have highly devolved organizations
-with many decision makers. Federated regions of an organization can
-maintain independent policies, aligned with different cultures if
-necessary.
-
-@sp 1
-@cartouche
-What may be problematic is to have teams that are not aligned, so that
-there are @i{conficting intentions}. In this case, one individual
-might instigate a change that conflicts with another. This often
-happens in `hit'n'run system administration', where there is no concerted
-plan or modus operandi.
-@end cartouche
-
-@sp 1
-To keep federated teams aligned with common criteria for policy,
-strong communication is required. For this we provide access to
-information through the Mission Portal. This shows the policy itself
-in different regions, as well as reports about the compliance of
-systems. Users can also exchange messages about their intentions,
-through policy comments and personal logs in the system.
-
-
-@node The decision point, Promises about change vs state, Partially centralized change, Top
-@unnumberedsec The decision point
-@sp 1
-
-
-By making all changes through a single point of control and
-verification, you avoid@footnote{Promise theory tells us that
-coordination requires mutual agreement between all agents that work in
-a coordinated way on common resources. Every decision necessarily
-comes from a single point of origin (but there could be many of these,
-making non-overlapping decisions); consistency only starts to go
-wrong when intentions about common resources conflict.} the
-problem of multiple intentions, because all intentions will be
-clear to see. CFEngine works with promises, because a promise
-is simply the expression of an intention.
-
-@image{arch,15cm,,The CFEngine architecture,png}
-
-If you work in a federated environment, then each distinct region of
-policy can have its own policy server or hub. These will not conflict,
-unless a host subscribes to updates from more than one hub.
-
-@node Promises about change vs state, Promises about change, The decision point, Top
-@unnumberedsec Promises about change vs state
-@sp 1
-
-CFEngine works by keeping promises, so think about how promises
-apply to change.
-
-You could promise to @i{make} a change, but that is a very weak
-promise because it would be kept by a single transitory event (the
-moment at which the change is made) and then it would go away. To
-have control over your system at all times you need to make promises
-about @i{state}, because state is something that persists for long
-times, and thus the promise persists.
-
-When we care about the state of a system, we make promises that describe
-that state at all times, because we know that there might be other
-forces for change that can bring about unintended states. If we intend the
-state of the system to persist, we should promise that.
-Thinking always about periods of stable equilbrium will minimize issues
-with non-compliance.
-
-@sp 1
-@cartouche
-To make a change of state, you should think about @i{changing the promises}
-that describe your desired state, not about @i{promising to make a change} of state.
-@end cartouche
-@sp 1
-
-An analogy: think of change management as navigation though a sea of possible
-states. If you promise changes, you promise to alter course relative
-to your current state, e.g. turn left, turn right, alter heading by 10
-degrees to starboard, etc. However, you are now vulnerable to things
-you don't know about. Winds and currents blow you off course and can
-lead to unintended changes that invalidate these course corrections,
-if you have not promised to monitor and avoid them. That is why
-modern navigators use @i{beacons}.
-
-In CFEngine, a beacon is a promise of desired end-state (the end of
-your journey). It's the place you want to be -- and the journey
-doesn't interest you. Navigators used fixed stars, lighthouses and
-now artificial radio signals to guide ships and planes on their
-intended course at all times, because beacons promise absolute desired
-location, not relative instructions to get there. CFEngine uses
-promises in the same way, to guide systems to their desired outcomes,
-not merely a script of relative corrections. So CFEngine works somewhat like a
-system auto-pilot.
-
-@node Promises about change, Change management and knowledge management, Promises about change vs state, Top
-@unnumberedsec Promises about change
-@sp 1
-
-To help you think of change in terms of promises, consider the following
-promises made during change management, with CFEngine examples.
-@table @i
-
-@item You promise a desired state for your system (beacon).
-
-@verbatim
-packages:
-
- "apache"
-
- comment => "Ensure Apache webserver installed",
- package_policy => "add",
- package_method => yum;
-
-processes:
-
- "apache"
-
- comment => "Ensure apache webserver running",
- restart_class => restart_apache;
-
-@end verbatim
-
-@item You change a promise you have made about state to promise a new desired state.
-
-You edit @file{promises.cf} and track the changes using a change management repository
-like Subversion or CVS.
-
-@item A third party promises a change and we promise to accept that change.
-
-@verbatim
-packages:
-
- "apache"
-
- comment => "Ensure Apache webserver up to date",
- package_policy => "update",
- package_method => yum;
-
-@end verbatim
-
-@item We promise to monitor unintended changes.
-
-@verbatim
-
-files:
-
- "/usr" -> "Security team"
-
- changes => detect_all_change,
- depth_search => recurse("inf");
-
-@end verbatim
-
-@item We promise two conflicting outcomes (a validation error to be corrected).
-
-Conflicts of intention are easy to see when they are mediated by CFEngine.
-@verbatim
-
-files:
-
- "/etc/passwd" -> "Security team"
- perms => owner("root");
-
- "/etc/passwd" -> "Security team"
- perms => owner("mark");
-
-@end verbatim
-
-
-@end table
-
-Perhaps you can think of more promises for your own organization. CFEngine encourages
-promise thinking because it promotes stable expectations about the system. Let us
-underline what traditional approaches ignore about change management:
-
-@sp 1
-@cartouche
-If you have made no promise about your system state, you should not be
-surprised by anything that happens there. You cannot assume that no
-change will happen.
-@end cartouche
-@sp 1
-
-@node Change management and knowledge management, Non-destructive change, Promises about change, Top
-@unnumberedsec Change management and knowledge management
-@sp 1
-
-The decision to manage change is an economic trade-off. The more
-promises we make about state, the higher the cost of keeping them. You
-have to decide how much you are willing to spend on navigating change.
-
-CFEngine makes desired state cheap, but the true cost of change
-management is not implementation but the cost of @i{changing
-knowledge}, i.e. losing track of your place within your intentions. If
-your system behaviour is dominated by changing external currents that
-you ignore, you will constantly be fighting to steer reactively.
-
-Knowledge Management is necessary to maintain a guidance system that
-makes course programming reliable and effective. CFEngine allows you
-to document all of your intentions as promises to be kept. CFEngine
-Nova additionally provides a continuously updated knowledge map as
-part of its `auto-pilot navigation' facilities, based on what we
-promise and what it discovers about the environment impacting on
-systems. Hence, it tracks both promised state, and unintended changes.
-
-Lack of knowledge about your system is the cause of unexpected
-side-effects and unpleasant surprises. The key to predictability in
-system operations is CFEngine's core principle of @i{convergence}.
-CFEngine Missions Specialists always think @i{convergence}.
-
-@node Non-destructive change, Change and convergence, Change management and knowledge management, Top
-@unnumberedsec Non-destructive change
-@sp 1
-
-The IT industry, for the most part, has not really progressed beyond
-the idea of baselining systems. In the traditional conception of
-change management you start by baselining, i.e. establishing a known
-starting configuration. Then you generally assume that you are the
-only source of change. If something goes wrong you do not try to
-repair the fault, but merely start again, destroying and rebuilding.
-
-In fact, all kinds of things change beyond our control all the
-time. Bugs emerge, items are stolen, things get broken by accident and
-external circumstances conspire to confound the order we would like to
-preserve. The suggestion that only authorized people actually make
-changes is simply wrong.
-
-@sp 1
-@center @image{demolish,8cm,,Rollback,png}
-@sp 1
-
-In reality, circumstances are part of the picture, as well as changing
-inventory and releases. CFEngine uses the idea of ``convergence''
-(see figure below) to ensure desired state, independently of where you
-start from. In this way of thinking, the configuration details might
-be changing in a quite unpredictable way, and it is our job to
-continuously monitor and repair this general dilapidation. Rather than
-assuming a constant state in between changes, CFEngine assumes a
-constant ``ideal state'' or @emph{goal} to be achieved at all
-times.
-
-@node Change and convergence, The change decision process or release management, Non-destructive change, Top
-@unnumberedsec Change and convergence
-@sp 1
-
-Change requires action, and implementation is the most dangerous part
-of change, as it leads to consquences that a difficult to predict, especially
-if you have incomplete knowledge of your environment.
-
-Reliabilty and dependability on promises requires you to think about
-the convergence of all change operations. Many change procedures fail
-because they are built in a highly fragile manner (left hand figure):
-you require exact knowledge of where you start from, and you have a recipe
-that (if applied once and only once) will take you to the desired end state.
-
-@sp 1
-@center @image{convergence,12cm,,Rollback,png}
-@sp 1
-Such a procedure cannot maintain the desired state, without
-demolishing it and rebuilding it from scratch.
-With CFEngine you focus on the end state (right hand figure), not
-where you start from. Every change, action or recipe may be
-repeated a infinite number of times@footnote{Some writers like to call this
-property idempotence.} without adverse consquences,
-because every action will only bring you to the desired state, no matter
-where you start from.
-
-@node The change decision process or release management, Deploying policy changes, Change and convergence, Top
-@unnumberedsec The change decision process or release management
-@sp 1
-
-The process of managing intended changes is often called @i{release
-management}. A @emph{release} is a collection of authorized changes
-to the promises of desired state for a system.
-
-A release is traditionally a larger umbrella under which many smaller
-changes are made. Changes are assembled into @emph{releases} and then
-they are `rolled out'.
-
-@sp 1
-@cartouche
-At CFEngine we encourage many small, incremental changes above
-large risky changes, as every change has unexpected consequences,
-and small changes minimize risk. (See the Special Topics Guide
-on BDMA.)
-@end cartouche
-@sp 1
-
-Release management is about the
-designing, testing and scheduling the release, i.e. everything to do with
-the release process except the explicit implementation of it.
-
-New releases are usually made in response to the occurrence of
-unintended changes, called @emph{incidents} (incident management). An
-incident is an event that leads to unintended behaviour. The root
-cause of many incidents is often called a @emph{problem} (problem
-management). One goal of CFEngine is to plan pro-actively to handle
-incidents automatically, thus taking them off the list of things to
-worry about. Changes can introduce new incidents, so it is important
-to test changes to promises in advance.
-
-@enumerate
-@item Formulate proposed intentions in the form of promises.
-@item Discuss the impact of these in your team of CFEngine Mission Specialists (more than one pair of eyes).
-@item Construct a test environment and examine the effect of these promises in practice.
-@item Commit the changes to promises in version control, e.g. subversion.
-@item Deploy promises changes into live environment on a small number of machines.
-@item Finally deploy to all machines.
-@end enumerate
-At each stage, we make careful, low-risk incursions on the system and
-see how it responds. Note that some side-effects could take days to
-emerge, so the schedule for change should account for the expected impact.
-
-
-@node Deploying policy changes, , The change decision process or release management, Top
-@unnumberedsec Deploying policy changes
-@sp 1
-
-The following sequence forms a checklist for deploying successful policy change:
-@enumerate
-@item Discuss the impact of changes in the team.
-@item Construct a test environment and examine the effect of these promises in practice.
-@item Make a change in the CFEngine input files.
-@item Run the configuration through @samp{cf-promises --inform} to check for problems.
-@item Commit the tested changes to promises in version control, e.g. subversion.
-@item Move the policy to a test system.
-@item Try running the configuration in dry-run model: @samp{cf-agent --dry-run}
-@item Try running the policy once on a single system, being observant of unexpected behaviour.
-@item Try running the policy on a small number of systems.
-@item Move the policy to the production environment.
-@item If possible, test on one or a few machines before releasing for general use.
-@end enumerate
-
-@noindent Be aware of the differences in your environment. A decision will not necessarily work everywhere
-in the same way.
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_Cloud.texinfo b/docs/guides/SpecialTopic_Cloud.texinfo
deleted file mode 100644
index 20893bc3fa..0000000000
--- a/docs/guides/SpecialTopic_Cloud.texinfo
+++ /dev/null
@@ -1,314 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-cloud.info
-@settitle Cloud
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Cloud Computing and Managed Services
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-Cloud Computing is a new economic approach to computer resource management
- in which computers can be created and retired on demand. The challenges
-of managing this increasingly dynamic environment are considerable. CFEngine
-Nova brings scalable assurances about compliance and performance.
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2010 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Iteration:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-
-
-@node Top, What is Cloud Computing?, (dir), (dir)
-@top Cloud Computing
-@menu
-* What is Cloud Computing?::
-* Is Cloud Computing for everything and everyone?::
-* How does CFEngine enable Cloud Computing?::
-* Permanent infra-structure with vibrant change::
-* How does Cloud relate to virtualization?::
-* Isn't virtualization inefficient?::
-* Challenges for Cloud Computing::
-* What if I change my mind about Cloud Computing?::
-* The future - molecular computing::
-@end menu
-
-
-@end ifnottex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@node What is Cloud Computing?, Is Cloud Computing for everything and everyone?, Top, Top
-@unnumberedsec What is Cloud Computing?
-
-
-Cloud Computing refers to the commoditization of
-computing, i.e. a world in which computers may be borrowed on demand
-from a resource pool, like renting a car or loaning a book from the
-library. The term `Cloud' comes from a model of the Internet, where
-the precise details of how everything fits together are fuzzy. In a
-strongly networked environment, it might matter less where objects are
-physically located.
-
-Commoditization of computers is an important strategy for business
-because it has the potential to eliminate a lot of the investment
-overhead for equipment during times of rapid change, as well as to
-recycle no-longer needed resources and save on redundant investment. You may think of
-Cloud Computing as `Recycle-able Computing' -- a world in which you can
-use something for a short time and then discard it, without fear of waste.
-
-@node Is Cloud Computing for everything and everyone?, How does CFEngine enable Cloud Computing?, What is Cloud Computing?, Top
-@unnumberedsec Is Cloud Computing for everything and everyone?
-
-Cloud Computing does for computers what the database did for
-information. Instead of having to keep reams of paper physically on
-site, databases allowed us to virtualize the information and care less
-about where the data were stored. Today we can call up a resource
-easily and cheaply from a database, and have someone else manage the
-service for us. Cloud computing allows us to dial up a new
-computer, like a book from the library, and then return it to the pool
-for others to use when we are done. It frees us from thinking about
-the specific location of the host, and we can appoint someone to
-manage this abstraction for us.
-
-Of course, this has negative aspects too. In a security environment,
-you do indeed want to know exactly where your resources are. If you
-are storing diamonds, you want a bank not a library, and you want to
-know exactly where the physical objects are. The same is true for
-valuable data and computers.
-
-Cloud Computing might be popular in the contemporary press, but it should be seen
-in clear terms as one strategy of several for managing resources efficiently.
-Some people still buy books, cars and dig wells, while others loan books, rent
-cars and get water from the water authority. Different economic models
-have different applications.
-
-@node How does CFEngine enable Cloud Computing?, Permanent infra-structure with vibrant change, Is Cloud Computing for everything and everyone?, Top
-@unnumberedsec How does CFEngine enable Cloud Computing?
-
-CFEngine has technology that can quickly bring machines, either real
-or virtual, from an uninitiated state to a fully working and customized
-state in seconds or minutes, without any human intervention.
-It can thus turn a generic resource into a specialized managed
-service on demand. CFEngine makes it extremely cheap to rebuild
-systems from scratch. This is exactly what a vibrant recycling
-regime needs to work efficiently.
-
-@node Permanent infra-structure with vibrant change, How does Cloud relate to virtualization?, How does CFEngine enable Cloud Computing?, Top
-@unnumberedsec Permanent infra-structure with vibrant change
-
-Not all your computers should be disposable. Certain key
-infrastructure items like DNS servers, directory servers, databases,
-etc are part of a permanent infrastructure. What you need there is
-unwavering stability, not agility and impermanence.
-
-CFEngine's lightweight repair capabilities are not only suitable for
-building machines quickly, but also for maintaining their state over
-time. It only pays to `rent services' (either from yourself or from a third
-party cloud provider) if you use the service infrequently, or your needs
-are constantly changing. The lack of permanence of cloud services can
-itself become an overhead if what you really need is constancy and security.
-
-The overhead of investment in physical infrastructure is cheap if that
-one term investment will last you for a long time, unchanged.
-For that reason, cloud services will never solve everyone's needs
-all the time. It is merely one product of choice.
-
-
-@node How does Cloud relate to virtualization?, Isn't virtualization inefficient?, Permanent infra-structure with vibrant change, Top
-@unnumberedsec How does Cloud relate to virtualization?
-
-Virtualization is the tool that makes Cloud Computing practical.
-Every time a physical machine needs to be deployed or retired, it
-requires the physical presence of a human. To deploy or recycle a
-physical machine, somehow usually has to touch the box.
-
-To deploy and tear down a virtual machine, however, no one needs to
-touch anything literally. Machines can be installed, moved and
-retired on command, using the physical computers as the host
-for a purely software process. Virtualization turns computer deployment
-into a software application.
-
-CFEngine can help to manage the deployment of virtual machines, by
-working on the physical host directly. It can also run on every
-virtual machine to manage them in a seamless process in which no one
-needs to think about what kind of machine software is running on.
-CFEngine can bring stability to the hosts or the virtual guests, or it
-can keep virtual machines running without the need to
-reboot@footnote{Rebooting a virtual machine in the cloud often means
-losing all of its special properties, so one needs to be ready
-to rebuild in case of catastrophe.}.
-
-
-@node Isn't virtualization inefficient?, Challenges for Cloud Computing, How does Cloud relate to virtualization?, Top
-@unnumberedsec Isn't virtualization inefficient?
-
-Virtualized computers run as software simulations, adding an extra
-layer of overhead. Using virtual machines is thus not as fast or
-processor-efficient as using real machines, however the processing
-overhead is written off in different ways.
-
-About 70-80% of the electrical power used by a computer is wasted just
-by turning it on. Only the remaining 20% go to solving real
-problems. However, most computers are very under-utilized (2-5%), so
-that many more machines than necessary are switched on at any one
-moment, compounding the cost of merely being switched on with an
-additional cost of cooling. This expense costs datacentres money
-every day. By squeezing 5-10 virtual machines into a single physical
-host container, one has a net saving of electrical power and man-power and
-often indistinguishable performance.
-
-Virtualization is a form of packaging, which enables service providers
-to separate services more easily with a `Chinese Wall' barrier.
-This is useful when dealing with services belonging to different companies
-or different users on the same physical host. The packaging aspect
-of virtual machines is therefore a form of `information management'.
-
-
-@node Challenges for Cloud Computing, What if I change my mind about Cloud Computing?, Isn't virtualization inefficient?, Top
-@unnumberedsec Challenges for Cloud Computing
-
-Dealing with scale, rapid change and impermanence could quickly lead
-to a processing overhead for humans, i.e. in the management of the
-cloud computers. In order to cope, some models force an
-oversimplification onto the user, forcing them to make do with second
-best (a `cheap rental').
-
-However, the requirements of computing are getting more complicated,
-not less. Even as this new economic management of resources comes
-into focus, companies are having to deal with increasing legislation
-about privacy, security, compliance with audits, and more. CFEngine
-addresses this challenge by integrating transparency of process
-and business goals into its scalable approach to continuous maintenance.
-
-The approach used by CFEngine is to:
-@sp 1
-@itemize
-@item Help to bring comprehension to the scope of the problem (Knowledge Management and Model-based Desired State Computing).
-@item Help to implement change quickly and cheaply (through Lightweight Automation).
-@item Help to bring measurable assurance about the state of compliance with policy (continuous maintenance).
-@end itemize
-@sp 1
-CFEngine's model promise-based computing provides both a language of
-assurance for keeping promises, and a measuring stick against which
-compliance can be measured. It is not necessary to make ad hoc
-judgements; every statement about the system can be documented and
-woven into a narrative about the system that can be understood
-both by technicians and management stakeholders.
-
-
-@itemize
-Deployment and maintaining real or virtual machines
-
-Instant Managed services from `stem cell' hosts
-
-Modelling the required properties of all machines and
-allowing non-experts insight into that model to see how
-their business goals are being handled.
-
-Focus on outcomes rather than implementation.
-
-Bring systems from any state into compliance.
-
-@end itemize
-
-@node What if I change my mind about Cloud Computing?, The future - molecular computing, Challenges for Cloud Computing, Top
-@unnumberedsec What if I change my mind about Cloud Computing?
-
-CFEngine can be used in a public or in a private cloud, and it can be
-used on local servers, desktops and even mobile devices. CFEngine is
-designed to be simple and lightweight, but powerful in its concepts
-and capabilities. It out-performs most other management software and
-imposes fewer limitations. If you want to move a service or a
-server-role, it is a simple matter to do so. CFEngine will continue
-to manage the service no matter what the underlying resource model.
-
-
-@node The future - molecular computing, , What if I change my mind about Cloud Computing?, Top
-@unnumberedsec The future - molecular computing
-
-At CFEngine, we believe that Cloud Computing is just a rehearsal for a
-real change in the way computing services are managed. In the future,
-the capabilities that assured management of recycle-able parts bring
-to services will allow atomic services to be combined into new and
-complex fabrics of functionality. The chemistry of these services will
-enable businesses and other organizations to express unique functions
-by combining a standard set of elementary parts. CFEngine's role in
-such a fabric would be the same as today: bringing self-maintaining,
-knowledge-based management to an infrastructure where users are free
-to make the most of shared pools.
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_ContentDrivenPolicies.texinfo b/docs/guides/SpecialTopic_ContentDrivenPolicies.texinfo
deleted file mode 100644
index e2be156063..0000000000
--- a/docs/guides/SpecialTopic_ContentDrivenPolicies.texinfo
+++ /dev/null
@@ -1,197 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-cdp.info
-@settitle Content-Driven Policies
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Content-Driven Policies
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-This document describes simplified policy writing using Content-Driven
-Policies in CFEngine Nova.
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2010- CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@node Top, What is a Content-Driven Policy?, (dir), (dir)
-@top Content-Driven Policies
-@menu
-* What is a Content-Driven Policy?::
-* Why should I use Content-Driven Policies?::
-* How do Content-Driven Policies work in detail?::
-* Can I make my own Content-Diven Policies?::
-@end menu
-
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@node What is a Content-Driven Policy?, Why should I use Content-Driven Policies?, Top, Top
-@unnumberedsec What is a Content-Driven Policy?
-
-@sp 1
-
-A Content-Driven Policy is a text file with lines containing
-semi-colon separated fields, like a spreadsheet or tabular file. Each line in the file is
-parsed and results in a specific type of promise being made, depending on which type the
-Content-Driven Policy is. The @samp{services} Content-Driven Policy is
-shown below.
-
-@sp 1
-@smallexample
-# masterfiles/cdp_inputs/service_list.txt
-
-Dnscache;stop;fix;windows
-ALG;start;warn;windows
-RemoteRegistry;start;fix;Windows_Server_2008
-
-@end smallexample
-@sp 1
-
-The meaning of the fields are different depending of the policy type,
-but explained in the file header. With these three lines, we ensure
-the correct status of three services on all our Windows machines and
-are given specialized reports on the outcome. The Content-Driven
-Policy services report is shown below.
-
-@image{cdp_services_report,15cm}
-
-@node Why should I use Content-Driven Policies?, How do Content-Driven Policies work in detail?, What is a Content-Driven Policy?, Top
-@unnumberedsec Why should I use Content-Driven Policies?
-
-@sp 1
-As seen in the example above, Content-Driven Policies are easy to write
-and maintain, especially for users not very familiar with the CFEngine
-language. They are designed to capture the essence of a specific,
-popular use of CFEngine, and make it easier. For example, the services
-Content-Driven Policy above has the following equivalent in the CFEngine
-language.
-
-@smallexample
-
-bundle agent service_example
-@{
-services:
-
- "Dnscache"
- comment => "Check services status of Dnscache",
- handle => "srv_Dnscache_windows",
- service_policy => "stop",
- service_method => force_deps,
- action => policy("fix"),
- ifvarclass => "windows";
-
- "ALG"
- comment => "Check services status of ALG",
- handle => "srv_ALG_windows",
- service_policy => "start",
- service_method => force_deps,
- action => policy("warn"),
- ifvarclass => "windows";
-
- "RemoteRegistry"
- comment => "Check services status of ALG",
- handle => "srv_ALG_windows",
- service_policy => "start",
- service_method => force_deps,
- action => policy("fix"),
- ifvarclass => "Windows_Server_2008";
-
-@}
-
-@end smallexample
-
-Writing this policy is clearly more time-consuming and error-prone. On
-the other hand, it allows for much more flexibility than Content-Driven
-Policies, when that is needed.
-
-CFEngine provides Content-Driven Policies to cover mainstream
-management tasks like the following.
-
-@itemize
-@item File change/difference management
-@item Service management
-@item Database management
-@item Application / script management
-@end itemize
-
-@node How do Content-Driven Policies work in detail?, Can I make my own Content-Diven Policies?, Why should I use Content-Driven Policies?, Top
-@unnumberedsec How do Content-Driven Policies work in detail?
-@sp 1
-
-The text files in @code{masterfiles/cdp_inputs/}
-(e.g. @samp{registry_list.txt}) are parsed into CFEngine lists by
-corresponding @code{cdp_*} files in @code{masterfiles/}
-(e.g. @samp{cdp_registry.cf}). It is the latter set of files that
-actually implement the policies in the text files.
-
-The Knowledge Map contains reports specifically designed to match the
-Content-Driven Policies.
-
-@node Can I make my own Content-Diven Policies?, , How do Content-Driven Policies work in detail?, Top
-@unnumberedsec Can I make my own Content-Diven Policies?
-@sp 1
-
-It is possible to mimic the structure of the existing Content-Driven
-Policies to implement new ones, for new purposes.
-
-However, CFEngine AS will be creating more of these best-practice
-policies. Thus, making a feature request at CFEngine Support may
-result in your proposal being developed and supported by professionals
-at CFEngine AS. Furthermore, Knowledge Map reports currently need to
-be developed induvidually by CFEngine AS.
-
-@bye
diff --git a/docs/guides/SpecialTopic_DevOps.texinfo b/docs/guides/SpecialTopic_DevOps.texinfo
deleted file mode 100644
index b8306581f3..0000000000
--- a/docs/guides/SpecialTopic_DevOps.texinfo
+++ /dev/null
@@ -1,551 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-devops.info
-@settitle CFEngine for `DevOps'
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title CFEngine for `DevOps' and Cloud Developers
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-Today's Cloud model is about managing re-usable infrastructure
-resources; DevOps extends this to manage and customize application
-resources. CFEngine handles
-deployment, customization and repair at all levels from the operating
-platform to the business applications.
-
-CFEngine has the sophistication to enable precise integration
-of software systems, and the responsiveness to determine the state of
-systems within a few minutes in massive cloud-scale deployments. It
-runs on everything from handhelds, to smartphones, to individual servers
-to datacentres, to mainframes and clouds.
-@end quotation
-@end cartouche
-
-@vskip 2cm
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2011 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-
-
-
-@node Top, What is DevOps? , (dir), (dir)
-@top Cfengine for Devops
-@menu
-* What is DevOps? ::
-* Why is DevOps happening now? ::
-* Should Web and IT management be closely related?::
-* How do we make controlled change faster?::
-* What role does CFEngine play in DevOps?::
-* Getting used to declarative expression::
-* Using CFEngine to integrate software components::
-* Cloud computing is a rehearsal::
-@end menu
-
-
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@node What is DevOps? , Why is DevOps happening now? , Top, Top
-@unnumberedsec What is DevOps?
-@sp 1
-DevOps is a term coined by Patrick Debois in 2009, from an
-amalgamation of Development and Operations. It expresses a
-change in the way companies are thinking about IT -- a change from segregated
-IT infrastructure to highly integrated platforms.
-Leading the way is a group of highly innovative Web-based companies
-whose businesses depend on very specific arrangements of
-infrastructure. It is about giving software developers more influence
-over the IT infrastructure their applications run on, and allowing
-change at the same speed as agile development teams.
-
-@node Why is DevOps happening now? , Should Web and IT management be closely related?, What is DevOps? , Top
-@unnumberedsec Why is DevOps happening now?
-@sp 1
-
-The proliferation of Free and Open Source
-software has put powerful software components in the hands of a
-broader range of developers than ever before -- and businesses
-everywhere are exploiting this software by adapting it and combining
-it is a wealth of mutations. This blurs the line between what used to
-be development and what used to be the system administrator's domain (operations).
-We have entered an age analogous to that of hobby electronics for IT
-systems, where we can order off-the-shelf components and build cool
-new applications from them anywhere.
-
-After 20 years of scepticism, business and Free Open Source software have
-made friends and are working together creatively for the benefit of
-willing consumers.
-With this basic premise of agility, companies working in this area
-naturally embrace a rapid innovation cycle, meaning a fast release
-cycle too. Traditional IT management methods can be perceived as too
-slow in such an environment. An important part of DevOps is that it
-naturally encompasses the idea of business integration -- or IT
-for a purpose.
-
-@node Should Web and IT management be closely related?, How do we make controlled change faster?, Why is DevOps happening now? , Top
-@unnumberedsec Should Web and IT management be closely related?
-@sp 1
-
-Web frameworks have seen the rise of languages like PHP, Java, Python
-and Ruby, all of which offer frameworks for fast deployment.
-Languages that work well for application development are not well
-suited to managing infrastructure however: they focus too much on low
-level details that one would like to suppress. The fact that
-programmers already know the languages does not change this.
-
-An important principle for robustness and stability of systems is weak
-coupling between components. This brings flexibility rather than brittle
-fragility. Giving programmers direct control over
-infrastructure from their applications risks insufficient separation
-in which infrastructure management becomes a second-class citizen run
-by amateurs who just want to get code out there and don't properly
-understand the implications. The System Administrator role exists for
-a reason.
-
-Should we use the web and HTTP for everything just because we
-know it? We suggest not. HTTP is an inefficient protocol
-for operations. It was designed for 1:1 communication with centralized
-certificate verification, not for decentralized 1000000:1
-communication, as testified by the extensive need for load balancers
-in web farms.
-
-At CFEngine, we believe in lightweight management -- made as simple
-as possible, but no simpler.
-
-@node How do we make controlled change faster?, What role does CFEngine play in DevOps?, Should Web and IT management be closely related?, Top
-@unnumberedsec How do we make controlled change faster?
-@sp 1
-
-It is important to be able to make changes quickly. Automation can
-implement change quickly if humans can get their acts together. Human
-IT processes and best practices (e.g. ITIL, COBIT, etc) tend to over
-bureaucratize change, leading to unnecessary overhead which frustrates
-agile companies.
-
-To be confident and efficient (`less haste more speed'), there needs
-to be a model for the system that everyone agrees on. Models compress
-information and cache understanding, meaning we have less to talk
-about@footnote{Consider, for example, US versus Norwegian legal
-systems. In Norway more details are codified into federal law. This
-means that there is less to talk about in court and legal proceedings
-are much more quickly resolved as there is less need to reinvent
-interpretations on the fly.}. Finally, models allow us to make
-predictions, so they aid understanding and help us to avoid mistake.
-
-@cartouche
-CFEngine's promise model offers a flexible approach to weakly-coupled
-autonomous resource configuration. It simultaneously allows efficient,
-convergent, and repeatable implementation, and a simple definition of
-@i{compliance} with requirements@footnote{For an explanation of convergence,
-see the Special Topics Guide on Change Management and Incident Repair.}. All web-based companies using credit
-cards will know about the need for PCI-DSS compliance, for instance.
-And US-traded companies will know about Sarbanes-Oxley (SOX).
-@end cartouche
-
-
-@node What role does CFEngine play in DevOps?, Getting used to declarative expression, How do we make controlled change faster?, Top
-@unnumberedsec What role does CFEngine play in DevOps?
-@sp 1
-
-The challenges for IT management today are about increasing complexity (driven
-by the circuitry of online applications) and increasing scale.
-
-CFEngine is not a programming language, but a documentation language
-for system state that has the pleasant side effect of enforcing that
-state on a continuous basis. It gets away from the idea of `build
-automation' to complete lifecycle management. It's continuity is a
-natural partner for a rapid development environment, as mistakes can be
-quickly fixed on the fly with minimal impact on the system.
-
-CFEngine's wins are that it is massively scalable, very low impact and rich in functionality.
-It will not break at a few hundred machines or choke off network communications with
-overhead. It will fix practically any well-defined problem within 5 minutes, bringing dependability and
-agility.
-
-Knowledge, business integration - metrics
-
-The advantage CFEngine brings is that users can have clear expectations about their
-systems at all times. Today's programmers are more sophisticated than script monkeys.
-
-@node Getting used to declarative expression, Using CFEngine to integrate software components, What role does CFEngine play in DevOps?, Top
-@unnumberedsec Getting used to declarative expression
-@sp 1
-
-CFEngine uses a pragmatic mixture of the declarative (functional) and
-imperative to represent configurations. Programmers are taught mainly
-imperative programming today, so a declarative approach could seem like
-a barrier to adoption. The principles are very simple however, and easy for
-developers to grasp.
-
-In spite of the focus on readability for documenting @i{intent},
-all the familiar structures of imperative programming are, in fact, available
-in CFEngine, just optimized for clarity.
-
-@cartouche
-The main goals of CFEngine are @i{convergence to a desired state}, @i{repeatability}
-and @i{clear intentions}.
-@end cartouche
-
-@menu
-* Expressing actions or tasks in CFEngine::
-* Expressing conditionals in CFEngine::
-* Expressing loops in CFEngine::
-* Expressing subroutines in CFEngine::
-@end menu
-
-@node Expressing actions or tasks in CFEngine, Expressing conditionals in CFEngine, Getting used to declarative expression, Getting used to declarative expression
-@unnumberedsubsec Expressing actions or tasks in CFEngine
-@sp 1
-
-Most of the actionable items have builtin operational support,
-which is designed to be convergent and safely repeatable.
-To keep declarations clear, CFEngine organizes similar
-operations into chapters in a simple separation of concerns.
-
-@example
-files:
- @var{"affected object" ...details....}
-
-processes:
- @var{"affected object" ...details....}
-
-@end example
-@noindent In general, many such promises and types are collected into bundles, so
-that the form is
-@cartouche
-@example
- bundle agent SomeUserDefinedName
- @{
- type_of_promise:
-
- @var{"affected object/promiser"
-
- body of the promise/details}
-
- ...
- @}
-@end example
-@end cartouche
-@node Expressing conditionals in CFEngine, Expressing loops in CFEngine, Expressing actions or tasks in CFEngine, Getting used to declarative expression
-@unnumberedsubsec Expressing conditionals in CFEngine
-@sp 1
-
-CFEngine uses the idea of contexts (also called classes or class-contexts@footnote{
-The term classes was originally used but has since been overloaded with connotations from
-Object Orientation, etc, making the term confusing.}) to address declarations to
-certain environments. The contexts or classes are written as a prefix, a bit like a
-target in a Makefile. They represent known properties of the environment.
-@cartouche
-@example
- bundle agent SomeUserDefinedName
- @{
- type_of_promise:
-
- @b{property::}
-
- @i{make one promise...}
-
- @b{!property::}
-
- @i{make a different promise...}
- @}
-
-@end example
-@end cartouche
-@noindent This is the mechanism by which all decisions are made in CFEngine. Class contexts
-are evaluated by @code{cf-agent} and are cached so that they can be used at any time.
-
-How do we know if the property has been evaluated or not? CFEngine evaluates certain
-hard-classes by default. In addition, you can probe as many more as you like, as
-separate promises.
-@verbatim
- classes:
-
- "cached_result" expression => fileexists("/some/file");
- "bigger" and => { isgreaterthan("1","0"), "cached_result" };
-
-@end verbatim
-This is different from a programming language where you generally make these tests
-in-line when you need them. In CFEngine the chance that you need the same test multiple
-times is greater, so the determination is separated entirely from the usage.
-
-To go from @i{if-then-else} thinking to using classes, you just need to thihnk about
-classes as booleans:
-@example
-bundle agent Name
-@{
-classes:
-
- "cached_result" expression => fileexists("/some/file");
- "bigger" and => @{ isgreaterthan("1","0"), "cached_result" @};
-
-reports:
-
- @b{bigger::}
- "Bigger is true....";
-
- @b{cached_result&!bigger::}
- "Mathematics seems to be awry...";
-
- # may also be written @b{cached_result.!bigger::}
-
-@}
-@end example
-These results can then be extended and reused efficiently.
-The class definitions can be hidden away and suitably meaningful class names
-replace a lot of redundant syntax.
-
-All the information about class contexts is evaluated at the end-host,
-in a decentralized manner avoiding clogging of network communications
-that befuddles many centralized approaches. This keeps CFEngine execution
-very fast and with a low overhead.
-
-@node Expressing loops in CFEngine, Expressing subroutines in CFEngine, Expressing conditionals in CFEngine, Getting used to declarative expression
-@unnumberedsubsec Expressing loops in CFEngine
-@sp 1
-
-Lists and loops go hand in hand, and they are a very effective way of reducing
-syntax and simplifying the expression of intent. Saying `do this to all the following'
-is generally easier to comprehend than `do this to the first, do this to the next,...' and
-so on, because our brains are wired to see patterns.
-
-Thus, loops are as useful for configuration as for programming. We
-only want to simplify the syntax once again to hide redundant words
-like `foreach'. To do this, CFEngine makes loops implicit. If you
-use a scalar variable reference @samp{$(mylist)} to a list variable
-@samp{@@(mylist)}, CFEngine assumes you want to iterate over each
-case.
-@verbatim
-vars:
- "my_list" slist => { "one", "two", "three" };
-
-files:
- "/tmp/file_$(my_list)"
- create => "true";
-
-@end verbatim
-@noindent The above evaluates to three promises:
-@example
-files:
-
- "/tmp/file_one"
- create => "true";
-
- "/tmp/file_two"
- create => "true";
-
- "/tmp/file_three"
- create => "true";
-
-@end example
-@noindent Similarly the following
-@verbatim
-bundle agent x
-{
-vars:
- "hi" string => "Hello";
- "list1" slist => { "a", "b", "c" };
- "list2" slist => { "1", "2", "3", "4" };
- "list3" slist => { "x", "y", "z" };
-
-reports:
- !silly_non_existent_context::
- "$(hi) $(list1) $(list2) $(list3)";
-}
-@end verbatim
-@noindent Results in:
-@smallexample
-R: Hello a 1 x
-R: Hello b 1 x
-R: Hello c 1 x
-R: Hello a 2 x
-R: Hello b 2 x
-R: Hello c 2 x
-R: Hello a 3 x
-R: Hello b 3 x
-R: Hello c 3 x
-R: Hello a 4 x
-R: Hello b 4 x
-R: Hello c 4 x
-R: Hello a 1 y
-R: Hello b 1 y
-R: Hello c 1 y
-R: Hello a 2 y
-R: Hello b 2 y
-R: Hello c 2 y
-R: Hello a 3 y
-R: Hello b 3 y
-R: Hello c 3 y
-R: Hello a 4 y
-R: Hello b 4 y
-R: Hello c 4 y
-R: Hello a 1 z
-R: Hello b 1 z
-R: Hello c 1 z
-R: Hello a 2 z
-R: Hello b 2 z
-R: Hello c 2 z
-R: Hello a 3 z
-R: Hello b 3 z
-R: Hello c 3 z
-R: Hello a 4 z
-R: Hello b 4 z
-R: Hello c 4 z
-@end smallexample
-
-@node Expressing subroutines in CFEngine, , Expressing loops in CFEngine, Getting used to declarative expression
-@unnumberedsubsec Expressing subroutines in CFEngine
-@sp 1
-Subroutines are used for both expressing and reusing parameterizable
-chunks of code, and for naming chunks for better management of intention.
-In CFEngine you define these as @code{methods}. A method is simply a bundle
-of promises, possibly with parameters. To call a method, you make a
-method-use-bundle promise. In this example, we call a bundle called @code{subtest}
-which accepts a parameter from its calling bundle.
-
-@verbatim
-body common control
-{
-# Master execution list
-bundlesequence => { "testbundle" };
-}
-
-###########################################
-
-bundle agent testbundle
-{
-vars:
- "userlist" slist => { "one", "two", "three" };
-
-methods:
- "any" usebundle => subtest("$(userlist)");
-}
-
-###########################################
-
-bundle agent subtest(user)
-{
-commands:
- "/bin/echo Fix $(user)";
-}
-
-@end verbatim
-@noindent The use of methods brings multi-dimensional patterns
-to convergent configuration management.
-
-@node Using CFEngine to integrate software components, Cloud computing is a rehearsal, Getting used to declarative expression, Top
-@unnumberedsec Using CFEngine to integrate software components
-@sp 1
-
-Integration of software components may be addressed with a variety
-of approaches and techniques:
-
-@itemize
-@item Standard template methods from the COPBL community library (`out of the box'
-solutions).
-@item Customized, personalized configurations.
-@item Package management for software dependencies.
-@item File management - copying, editing, permissions, etc.
-@item Process management - starting, stopping, restarting.
-@item Security.
-@item Monitoring performance and change.
-@end itemize
-
-@noindent Needless to say, all of these are easily achievable with 5 minute repair accuracy
-using our CFEngine framework.
-
-@node Cloud computing is a rehearsal, , Using CFEngine to integrate software components, Top
-@unnumberedsec Cloud computing is a rehearsal
-@sp 1
-
-We have barely made a dent in CFEngine in this Short Topics Guide.
-Let us end by noting briefly that DevOps and Cloud Computing are
-merely rehearsals for what is to come next: molecular computing in
-which we synthesize complex clusters of components based on higher
-level rule based schemas.
-
-In this future version of IT, knowledge management will be the key
-challenge for understanding how to build systems. We fully expect the
-APIs of the future virtualized infrastructure to be promise oriented,
-and for CFEngine to remain a viable approach to configuration after
-other frameworks have become outmoded.
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_DistributedScheduling.texinfo b/docs/guides/SpecialTopic_DistributedScheduling.texinfo
deleted file mode 100644
index e1d9d06e72..0000000000
--- a/docs/guides/SpecialTopic_DistributedScheduling.texinfo
+++ /dev/null
@@ -1,611 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-distsched.info
-@settitle Distributed Scheduling
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Distributed Scheduling and Workflows
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-Distributed scheduling is about tying together jobs to create a
-workflow across multiple machines. It introduces a level of fragility
-into system automation. Using CFEngine promises, we can create self-healing
-workflows, but we recommend minimizing dependencies. This document shows how
-to build workflows using CFEngine primitives.
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2010 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@node top, What is distributed scheduling?, (dir), (dir)
-@top CFEngine-Tutorial
-@menu
-* What is distributed scheduling?::
-* Coordinating dispatch::
-* Job scheduling and periodic maintenance::
-* Fancy distributed encapsulation::
-* More links in the chain::
-* Self-healing workflows::
-* Long workflow chains::
-* Summary of Distributed Scheduling::
-@end menu
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-
-
-@node What is distributed scheduling?, Coordinating dispatch, top, top
-@unnumberedsec What is distributed scheduling?
-
-@sp 1
-Scheduling refers to the execution of non-interactive processes or
-tasks (usually called `jobs') at designated times and places around a
-network of computers (see the Special Topics Guide on Scheduling).
-Distributed Scheduling refers to the chaining of different jobs into a
-coordinated workflow that spans several computers. For example, you
-schedule a processing job on @code{machine1} and @code{machine2}, and
-when these are finished you need to schedule a job on @code{machine3}.
-This is distributed scheduling.
-
-
-@node Coordinating dispatch, Job scheduling and periodic maintenance, What is distributed scheduling?, top
-@unnumberedsec Coordinating dispatch
-
-Dispatch is the term used for starting actually the execution of a job
-that has been scheduled. There are two ways to achieve distributed
-job scheduling:
-@itemize
-@item Centralized dispatch of jobs.
-@item Peer to peer signalling with local dispatch of jobs.
-@end itemize
-There are pros and cons to centralization. Centralization makes
-consistency easy to determine, but it creates bottlenecks in
-processing and allows one machine to see all
-information. Decentralization provides an automatic and natural
-load-balancing of job dispatch, and it allows machines to
-reveal information on a `need to know' basis.
-
-CFEngine is a naturally decentralized system, and only policy
-definition is usually centralized, but you can set up practically any
-architecture you like, in a secure fashion.
-
-@node Job scheduling and periodic maintenance, Fancy distributed encapsulation, Coordinating dispatch, top
-@unnumberedsec Job scheduling and periodic maintenance
-
-You promise to execute tasks or keep promises at distributed
-places and times:
-
-@itemize
-@item You tell CFEngine @i{what} and @i{how} with the details of a promise.
-@item You tell CFEngine @i{where} and @i{when} promises should be kept, using @i{classes}.
-@end itemize
-
-CFEngine is designed principally to maintain desired state on a continuous
-basis.
-There are three cases for job scheduling:
-@itemize
-@item Unique jobs run once and only once.
-@item Standard jobs run sporadically on demand.
-@item Standard jobs run on a regular schedule.
-@end itemize
-This list transfers to workflow processes too. If one job needs to
-follow after another (because it depends on it for something), we can
-ask if this workflow is a standard and regular occurrence, or a one-off phenomenon.
-
-@menu
-* One-off workflows::
-* Regular workflows::
-@end menu
-
-@node One-off workflows, Regular workflows, Job scheduling and periodic maintenance, Job scheduling and periodic maintenance
-@unnumberedsubsec One-off workflows
-
-In CFEngine, you code a one-off workflow by specifying the space-time coordinates
-of the event that starts it. For example, if you want a job to be run a 16:45 on Monday
-24th January 2012, you would make a class corresponding to this time, and place the
-promise of a job (or jobs) in this class. Let's look at some examples of this, in which
-host1 executes a command called @file{my_job}, and host2 follows up with a bundle of
-promises afterwards.
-
-The simplest case is to schedule the exact times.
-@verbatim
-bundle agent workflow_one
-{
-methods:
-
- Host2.Day24.January.Year2012.Hr16.Min50_55::
-
- "any" usebundle => do_my_job_bundle;
-
-commands:
-
- Host1.Day24.January.Year2012.Hr16.Min45_50::
-
- "/usr/local/bin/my_job";
-
-}
-@end verbatim
-Host1 runs its task at 16:45, and Host2 excutes its part in the
-workflow five minutes later. The advantage of this approach is that no
-direct communication is required between Host1 and Host2. The
-disadvantage is that you, as the orchestrator, have to guess how long
-the jobs will take. Moreover Host2 doesn't know for certain whether
-host1 succeeded in carrying out its job, so it might be a fruitless
-act.
-
-We can change this by signalling between the processes. Whether not you consider
-this an improvement or not depends on what you value highest: avoidance of
-communication or certainty of outcome. In this version, we increase the certainty
-of control by asking the predecessor or upstream host for confirmation of success
-if the job was carried out.
-@verbatim
-bundle agent workflow_one
-{
-classes:
-
- Host2::
-
- "succeeded" expression => remoteclassesmatching
- (
- "did.*", # get classes matching
- "Host1", # from this server
- "no", # encrypt comms?
- "hostX" # prefix
- );
-methods:
-
- Host2.hostX_did_my_job
-
- "any" usebundle => do_my_job_bundle;
-
-commands:
-
- Host1.Day24.January.Year2012.Hr16.Min45_50::
-
- "/usr/local/bin/my_job",
- classes => state_repaired("did_my_job");
-}
-@end verbatim
-In this example, the methods promise runs on Host2 and the commands promise runs
-one Host1 as before. Now, host 1 sets a signal class @samp{did_my_job}
-when it carries out the job, and Host2 collects it by contacting the @code{cf-serverd}
-on Host1. Assuming that Host1 has agreed to let Host2 know this information, by granting
-access to it, Host2 can inherit this class, with a prefix of its own choosing. Thus
-is transforms the class @samp{did_my_job} on Host1 into @samp{hostX_did_my_job} on Host2.
-
-The advantage of this method is that the second job will only be started if the first
-completed, and we don't have to know how long the job took. The disadvantage of this is that
-we have to exchange some network information, and this has a small network cost, and requires
-some extra configuration on the server side to grant access to this context information:
-
-@verbatim
-bundle server access_rules
-{
-access:
-
- "did_my_job"
-
- resource_type => "context",
- admit => { "Host2" };
-}
-
-@end verbatim
-
-
-@node Regular workflows, , One-off workflows, Job scheduling and periodic maintenance
-@unnumberedsubsec Regular workflows
-
-To make a job happen at a specific time, we used a very specific time
-classifier @samp{Day24.January.Year2012.Hr16.Min45_50}. If we now want
-to make this workflow into a regular occurrence, repeating at some
-interval we have two options:
-
-@itemize
-@item We repeat this at the same time each week, day, hour, etc.
-@item We don't care about the precise time, we only care about the interval between executions.
-@end itemize
-The checking of promises in CFEngine is controlled by @i{classes} and
-by @i{ifelapsed locks}, which may be used for these two cases
-respectively. If nothing else is specified, CFEngine runs every 5
-minutes and reconsiders the state of all its active promises. To be
-specific about the time, we just alter which promises are active at
-different times. Classes (as used already) allow us to anchor a
-promise to a particular region of time and space. Locks, on the other
-hand, allow us to say that a promise will only be rechecked if a certain
-time has elapsed since the last time.
-
-So, to make a promise repeat, we simply have to be less specific about the time.
-Let us make the promise on Host1 apply every day between 16:00:00 (4 pm) and 16:59:59,
-and add an ifelapsed lock saying that we do not want to consider rechecking more often
-tha once every 100 minutes (more than 1 hour). Now we have a workflow process
-that starts at 16:00 hours each day and runs only once each day.
-
-@verbatim
-bundle agent workflow_one
-{
-classes:
-
- Host2::
-
- "succeeded" expression => remoteclassesmatching(
- "did.*",
- "Host1",
- "no",
- "hostX"
- );
-methods:
-
- Host2.hostX_did_my_job
-
- "any" usebundle => do_my_job_bundle;
-
-commands:
-
- Host1.Hr16::
-
- "/usr/local/bin/my_job",
- action => if_elapsed("100"),
- classes => state_repaired("did_my_job");
-
-
-@end verbatim
-
-@node Fancy distributed encapsulation, More links in the chain, Job scheduling and periodic maintenance, top
-@unnumberedsec Fancy distributed encapsulation
-
-We could try to be fancy about distributed scheduling, packaging
-it into a reusable structure. This may or may not be a good idea, depending
-on your aesthetics. The following example, from the community unit tests,
-shows how we might proceed.
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { job_chain("Hr16.Min10_15") };
-}
-
-########################################################
-
-bundle common g
-{
-vars:
-
- # Define the name of the signal passed between hosts
-
- "signal" string => "pack_a_name";
-}
-
-########################################################
-
-bundle agent job_chain(time)
-{
-vars:
-
- # Define the names of the two parties
-
- "client" string => "downstream.exampe.org";
- "server" string => "upstream.example.org";
-
-classes:
-
- # derive some classes from the names defined in variables
-
- "client_primed" expression => classmatch(canonify("$(client)")),
- ifvarclass => "$(time)";
-
- "server_primed" expression => classmatch(canonify("$(server)")),
- ifvarclass => "$(time)";
-
- client_primed::
-
- "succeeded" expression => remoteclassesmatching(
- "$(g.signal)",
- "$(server)",
- "yes",
- "hostX"
- );
-methods:
-
- client_primed::
-
- "downstream" usebundle => do_job("Starting local follow-up job"),
- action => if_elapsed("5"),
- ifvarclass => "hostX_$(g.signal)";
-
- server_primed::
-
- "upstream" usebundle => do_job("Starting remote job"),
- action => if_elapsed("5"),
- classes => state_repaired("$(g.signal)");
-
-reports:
-
- !succeeded::
-
- "Server communication failed",
-
- ifvarclass => "$(time)";
-}
-
-#########################################################
-
-bundle agent do_job(job)
-{
-commands:
-
- # do whatever...
-
- "/bin/echo $(job)";
-}
-
-#########################################################
-# Server config
-#########################################################
-
-body server control
-{
-allowconnects => { "127.0.0.1" , "::1" };
-allowallconnects => { "127.0.0.1" , "::1" };
-trustkeysfrom => { "127.0.0.1" , "::1" };
-allowusers => { "mark" };
-}
-
-#########################################################
-
-bundle server access_rules()
-{
-access:
-
- "$(g.signal)"
-
- resource_type => "context",
- admit => { "127.0.0.1" };
-}
-
-@end verbatim
-
-@node More links in the chain, Self-healing workflows, Fancy distributed encapsulation, top
-@unnumberedsec More links in the chain
-
-In the examples above, we only had two hosts cooperating about
-jobs. In general, it is not a good idea to link together many
-different hosts unless there is a good reason for doing so. In HPC or
-Grid environments, where distributed jobs are more common and results
-are combined from many sub-tasks, one typically uses some more
-specialized middleware to accomplish this kind of cooperation. Such
-software makes compromises of its own, but is generally better suited
-to the specialized task for which it was written than a tool like
-CFEngine (whose main design criteria are to be secure and generic).
-
-Nevertheless, there are some tricks left in CFEngine for distributed
-scheduling if we want to trigger a number of follow-ups from a single job, or
-aggregate a number of jobs to drive a single follow-up (see figure).
-
-@sp 1
-@center @image{schedule_patterns,5cm,,Rollback,png}
-@sp 1
-
-@menu
-* Aggregation of multiple jobs::
-* Triggering multiple follow-ups::
-@end menu
-
-@node Aggregation of multiple jobs, Triggering multiple follow-ups, More links in the chain, More links in the chain
-@unnumberedsubsec Aggregation of multiple jobs
-
-When aggregating jobs, we must combine their exit status using AND or OR.
-The most common case it that we require all the prerequisites in place in order to
-generate the final result, i.e. trigger the followup only if all of the prerequisites
-succeeded.
-@verbatim
-bundle agent workflow_one
-{
-vars:
-
- "n" slist => { "2", "3", "4" };
-
-classes:
-
- "succeeded$(n)" expression => remoteclassesmatching(
- "did.*",
- "Host$(n)",
- "no",
- "hostX"
- ),
- ifvarclass => "Host$(n)";
-methods:
-
- Host2.Host3.Host4.hostX_did_my_job
-
- "any" usebundle => do_my_job_bundle;
-
-commands:
-
- Host1.Hr16::
-
- "/usr/local/bin/my_job",
- action => if_elapsed("100"),
- classes => state_repaired("did_my_job");
-@end verbatim
-@noindent This example shows an all-or-nothing result. The follow-up job
-will only be executed if all three jobs finish within the same 5
-minute time-frame. There is no error handling or recovery except to schedule the whole
-thing again.
-
-Triggering from one or more predecessors, i.e. combining with OR, looks similar,
-we just have to change the class expression:
-@verbatim
-...
-
-methods:
-
- (Host2|Host3|Host4).hostX_did_my_job
-
- "any" usebundle => do_my_job_bundle;
-
-...
-@end verbatim
-
-
-@node Triggering multiple follow-ups, , Aggregation of multiple jobs, More links in the chain
-@unnumberedsubsec Triggering multiple follow-ups
-
-The converse scenario is to trigger a number of jobs from a single pre-requisite.
-This is simply a case of listing the jobs under the trigger classes.
-@verbatim
-bundle agent workflow_one
-{
-classes:
-
- Host2::
-
- "succeeded" expression => remoteclassesmatching(
- "did.*",
- "Host1",
- "no",
- "hostX"
- );
-methods:
-
- Host2.hostX_did_my_job
-
- "any" usebundle => do_my_job_bundle1;
- "any" usebundle => do_my_job_bundle2;
- "any" usebundle => do_my_job_bundle3;
-
-commands:
-
- Host1.Hr16::
-
- "/usr/local/bin/my_job",
- action => if_elapsed("100"),
- classes => state_repaired("did_my_job");
-
-@end verbatim
-
-
-@node Self-healing workflows, Long workflow chains, More links in the chain, top
-@unnumberedsec Self-healing workflows
-
-To apply CFEngine's self-healing concepts to workflow scheduling, we
-can imagine the concept of a convergent workflow, i.e. one that, if we
-repeat everything a sufficient number of times, will eventually lead
-to the result. The outcome of the chained sequence of jobs must have
-an outcome that is repeatably achievable and which will eventually be
-achieved if we try a sufficient number of times. Using CFEngine this
-is a natural outcome -- however, most system designers do not think in
-terms of repeatable sustainable outcomes and fault-tolerance.
-
-Beware however, one-off jobs @i{cannot} be made convergent, because
-they only have a single chance to succeed. It is a question of
-business process design whether you design workflows to be sustainable
-and repeatable, or whether you trust the outcome of a single shot
-process. Using the persistent classes in CFEngine together with the
-if-elapsed locks to send signals between hosts, it is simple and
-automatic to make convergent self-healing workflows.
-
-
-@node Long workflow chains, Summary of Distributed Scheduling, Self-healing workflows, top
-@unnumberedsec Long workflow chains
-
-Long workflow chains are those which involve more than one trigger.
-These can be created by repeating the pattern above several times.
-Note however, that each link in the chain introduces a new level of
-uncertainty and potential failure. In general, we would not recommend
-creating workflows with long chains.
-
-@node Summary of Distributed Scheduling, , Long workflow chains, top
-@unnumberedsec Summary of Distributed Scheduling
-
-Distributed scheduling is about tying together jobs to create a
-workflow across multiple machines. It introduces a level of fragility
-into system automation. Using CFEngine promises, we can create self-healing
-workflows, but we recommend minimizing dependencies. This document shows how
-to build workflows using CFEngine primitives.
-
-
-
-
-
-
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
diff --git a/docs/guides/SpecialTopic_Editing.texinfo b/docs/guides/SpecialTopic_Editing.texinfo
deleted file mode 100644
index 036cd3d5ab..0000000000
--- a/docs/guides/SpecialTopic_Editing.texinfo
+++ /dev/null
@@ -1,1047 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-editing.info
-@settitle Promising and Editing File Content
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Promising and Editing File Content
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-The ability to edit files convergently is a popular and widely used
-aspect of CFEngine. This document proposes some best practices for
-managing file content.
-
-The examples contained here assume the inclusion of the standard COPBL
-library as an input.
-@end quotation
-@end cartouche
-
-@vskip 2cm
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2010 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-
-
-
-@node Top, From boiler-plates to convergent file editing, (dir), (dir)
-@top Editing
-@menu
-* From boiler-plates to convergent file editing::
-* Why is file editing difficult?::
-* What does file editing involve?::
-* Three approaches to managing files::
-* Constructing files from promises::
-* Editing bundles::
-* Choosing an approach to file editing::
-* Pitfalls to watch out for in file editing::
-@end menu
-
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@c *********************************************************************
-
-@node From boiler-plates to convergent file editing, Why is file editing difficult?, Top, Top
-@unnumberedsec From boiler-plates to convergent file editing
-@sp 1
-
-Many configuration management systems allow you to determine
-configuration file content to some extent, usually by over-writing
-files with boiler-plate (template) files. This approach works for some
-cases, but it is a blunt and inflexible instrument, which forces you
-to take over the ownership of the file `all or nothing' and determine
-its entire content yourself. This is more than is necessary or
-desirable in general.
-
-Other approaches to file editing us search and replace, e.g. with the
-long-standing Unix tools @file{awk} and @file{sed}. Adding a user to a
-structured file such as the password file, only if the user is not
-already defined, is a more complex operation.
-
-Cfengine allows you to model both whole files and parts of files, in any
-format, and promise that these fragments will satisfy certain promises
-about their state. This is potentially different from more common templating
-approaches to file management in which pre-adjusted copies of files
-are generated for all recipients at a single location and then
-distributed.
-
-
-The most important thing about making changes to files is that the
-result end up being predictable. There are three ways to approach this
-problem. You should choose the simplest approach that solves your
-problem and try not to be prejudiced by what you have done before.
-
-
-
-
-
-
-
-@c *********************************************************************
-
-
-@node Why is file editing difficult?, What does file editing involve?, From boiler-plates to convergent file editing, Top
-@unnumberedsec Why is file editing difficult?
-@sp 1
-
-File content is not made up of simple data objects like permission flags or
-process tables: files contain compound, ordered structures (known as
-grammars) and they cannot always be determined from a single source of
-information. To determine the outcome of a file we have to adopt either
-a fully deterministic approach, or live with a partial approximation.
-
-Some approaches to file editing try to `know' the intended format of a
-file, by hardcoding it. If the file then fails to follow this format,
-the algorithms might break. CFEngine gives you generic tools to be
-able to handle files in any line-based format, without the need to
-hard-code specialist knowledge about file formats.
-
-@cartouche
-Remember that all changes are adapted to your local context and implemented at the final
-destination by @code{cf-agent}.
-@end cartouche
-
-
-@c *********************************************************************
-
-@node What does file editing involve?, Three approaches to managing files, Why is file editing difficult?, Top
-@unnumberedsec What does file editing involve?
-@sp 1
-
-There are several ways
-to approach desired state management of file contents:
-
-@sp 1
-@enumerate
-@item Copy a finished file template to the desired location, completely overwriting existing content.
-@item Copy and adapt an almost finished template, filling in variables or macros to yield a desired content.
-@item Make corrections to whatever the existing state of the file might be.
-@end enumerate
-@sp 1
-There are advantages and disadvantages with each of these approaches and the best approach depends on
-the type of situation you need to describe.
-
-@sp 1
-@multitable @columnfractions .5 .5
-@item @b{For the approach} @tab @b{Against the approach}
-@item 1. Deterministic. @tab Hard to specialize the result and the source must still be maintained by hand.
-@item 2. Deterministic. @tab Limited specialization and must come from a single source, again maintained by hand.
-@item 3. Non-deterministic/partial model. @tab Full power to customize file even with multiple managers.
-@end multitable
-@sp 1
-
-
-Approaches 1 and 2 are best for situations where very few variations
-of a file are needed in different circumstances. Approach 3 is best
-when you need to customize a file significantly, especially when you don't know the
-full details of the file you are starting from. Approach 3 is generally required
-when adapting configuration files provided by a third party, since the basic
-content is determined by them.
-
-
-
-@c *********************************************************************
-
-
-@node Three approaches to managing files, Constructing files from promises, What does file editing involve?, Top
-@unnumberedsec Three approaches to managing files
-
-
-@menu
-* Copying a finished file template into place::
-* Contextual adaptation of a file template::
-* Example file template::
-* Combining copy with template expansion::
-* Making delta changes to someone else's file::
-@end menu
-
-@node Copying a finished file template into place, Contextual adaptation of a file template, Three approaches to managing files, Three approaches to managing files
-@unnumberedsubsec Copying a finished file template into place
-
-Use this approach if a simple substution of data will solve the problem in all contexts.
-
-@enumerate
-@item Maintain the content of the file in a version controlled repository.
-@item Check out the file into a staging area.
-@item Copy the file into place.
-@end enumerate
-
-@cartouche
-@verbatim
-bundle agent something
-{
-files:
-
- "/important/file"
-
- copy_from => secure_cp("/repository/important_file_template","svn-host");
-}
-@end verbatim
-@end cartouche
-
-@c *********************************************************************
-
-
-@node Contextual adaptation of a file template, Example file template, Copying a finished file template into place, Three approaches to managing files
-@unnumberedsubsec Contextual adaptation of a file template
-
-There are several approaches here:
-@enumerate
-@item Encode the boiler-plate template directly in the CFEngine configuration, and have full use of the power of the CFEngine language to adapt it.
-@item Keep a separate boiler-plate file and edit/adapt it.
-@item Copy a template from a repository then edit/adapt it.
-@item Copy a generic template with embedded variables that can be expanded like macro-substitution.
-@end enumerate
-@noindent Choose the approach that you consider to be simplest and most reliable for the purpose you need.
-Don't use templating, for instance, simply because it is what you are used to, or you might waste a lot
-of time and effort maintaining data that you don't need to.
-
-To expand a template file on a local disk:
-@cartouche
-@verbatim
-bundle agent templating
-{
-files:
-
- "/home/mark/tmp/file_based_on_template"
-
- create => "true",
- edit_line => expand_template("/tmp/source_template");
-}
-@end verbatim
-@end cartouche
-@noindent As of CFEngine version 3.3.0 you can also use a new templating file format
-and write:
-@cartouche
-@verbatim
-bundle agent templating
-{
-files:
-
- "/home/mark/tmp/file_based_on_template"
-
- create => "true",
- edit_template => "/tmp/source_template";
-}
-@end verbatim
-@end cartouche
-
-
-@noindent For example, the source template file might look like this, with
-embedded CFEngine variables:
-@example
-mail_relay = $(sys.fqhost)
-important_user = $(mybundle.variable)
-#...
-@end example
-@noindent These variables will be filled in by CFEngine assuming they are defined
-within your CFEngine configuration.
-
-If you use the new @code{edit_template} promise, you can embed directives to CFEngine
-context-classes and mark out regions of a file to be treated as an iteratable
-block.
-
-@cartouche
-@verbatim
-#This is a template file /templates/input.tmpl
-
-These lines apply to anyone
-
-[%CFEngine solaris.Monday:: %]
-Everything after here applies only to solaris on Mondays
-until overridden...
-
-[%CFEngine linux:: %]
-Everything after here now applies now to linux only.
-
-[%CFEngine BEGIN %]
-This is a block of text
-That contains list variables: $(some.list)
-With text before and after.
-[%CFEngine END %]
-
-nameserver $(some.list)
-@end verbatim
-@end cartouche
-@sp 1
-@noindent For example: if we use this template in a promise:
-@sp 1
-@cartouche
-@verbatim
-bundle agent test
-{
-vars:
- "var" slist => { "1", "2", "3"};
-
-files:
- "/tmp/expander"
- create => "true",
- edit_template => "/templates/input.tmpl";
-}
-
-@end verbatim
-@end cartouche
-@noindent The result would look like this, on a linux host:
-@sp 1
-@verbatim
-#This is a template file /templates/input.tmpl
-
-These lines apply to anyone
-Everything after here now applies now to linux only.
-This is a block of text
-That contains list variables: 1
-With text before and after.
-This is a block of text
-That contains list variables: 2
-With text before and after.
-This is a block of text
-That contains list variables: 3
-With text before and after.
-nameserver 1
-nameserver 2
-nameserver 3
-@end verbatim
-@sp 1
-
-@node Example file template, Combining copy with template expansion, Contextual adaptation of a file template, Three approaches to managing files
-@unnumberedsubsec Example file template
-
-@sp 1
-@verbatim
-[%CFEngine any:: %]
-
- ServerAdmin $(stage_file.params[apache_mail_address][1])
- DocumentRoot /var/www/htdocs
- ServerName $(stage_file.params[apache_server_name][1])
- AddHandler cgi-script cgi
- ErrorLog /var/log/httpd/error.log
- AddType application/x-x509-ca-cert .crt
- AddType application/x-pkcs7-crl .crl
- SSLEngine off
- CustomLog /var/log/httpd/access.log
-
-
-[%CFEngine webservers_prod:: %]
-[%CFEngine BEGIN %]
-
- ServerAdmin $(stage_file.params[apache_mail_address][1])
- DocumentRoot /var/www/htdocs
- ServerName $(stage_file.params[apache_server_name][1])
- AddHandler cgi-script cgi
- ErrorLog /var/log/httpd/error.log
- AddType application/x-x509-ca-cert .crt
- AddType application/x-pkcs7-crl .crl
- SSLEngine on
- SSLCertificateFile $(stage_file.params[apache_ssl_crt][1])
- SSLCertificateKeyFile $(stage_file.params[apache_ssl_key][1])
- CustomLog /var/log/httpd/access.log
-
-[%CFEngine END %]
-
-@end verbatim
-
-@node Combining copy with template expansion, Making delta changes to someone else's file, Example file template, Three approaches to managing files
-@unnumberedsubsec Combining copy with template expansion
-
-What about getting your template to the end-host? To convergently
-copy a file from a source and then edit it, use the following
-construction with a staging file.
-@cartouche
-@verbatim
-bundle agent master
-{
-files:
- "$(final_destination)"
- create => "true",
- edit_line => fix_file("$(staging_file)"),
- edit_defaults => empty,
- perms => mo("644","root"),
- action => if_elapsed("60");
-}
-
-bundle edit_line fix_file(f)
-{
-insert_lines:
- "$(f)"
- insert_type => "file";
- # expand_scalars => "true" ;
-
-replace_patterns:
- "searchstring"
- replace_with => value("replacestring");
-}
-
-@end verbatim
-@end cartouche
-
-@c *********************************************************************
-
-@node Making delta changes to someone else's file, , Combining copy with template expansion, Three approaches to managing files
-@unnumberedsubsec Making delta changes to someone else's file
-
-Edit a file with multiple promises about its state, when you do not want
-to determine the entire content of the file, or if it is unsafe to
-make unilateral changes, e.g. because its contents are also
-being managed from another source like a software package manager.
-
-For modifying a file, you have access to the full power of text editing
-promises. This is a powerful framework.
-
-@cartouche
-@verbatim
-# Resolve conf edit
-
-body common control
-{
-bundlesequence => { "g", resolver(@(g.searchlist),@(g.nameservers)) };
-inputs => { "cfengine_stdlib.cf" };
-}
-
-bundle common g # global
-{
-vars:
- "searchlist" slist => { "example.com", "cfengine.com" };
- "nameservers" slist => { "10.1.1.10", "10.3.2.16", "8.8.8.8" };
-
-classes:
- "am_name_server"
- expression => reglist("@(nameservers)","$(sys.ipv4[eth1])");
-}
-
-bundle agent resolver(s,n)
-{
-files:
- "$(sys.resolv)" # test on "/tmp/resolv.conf" #
- create => "true",
- edit_line => doresolv("@(this.s)","@(this.n)"),
- edit_defaults => empty;
-}
-
-# For your private library ......................
-
-bundle edit_line doresolv(s,n)
-{
-insert_lines:
- "search $(s)";
- "nameserver $(n)";
-delete_lines:
- # To clean out junk
- "nameserver .*| search .*" not_matching => "true";
-}
-@end verbatim
-@end cartouche
-
-
-
-
-
-@c *********************************************************************
-
-
-@node Constructing files from promises, Editing bundles, Three approaches to managing files, Top
-@unnumberedsec Constructing files from promises
-@sp 1
-
-Making finished templates for files and filling in the blanks using variables
-is a flexble approach in many cases, but it is not flexible enough for all
-cases. A very flexible approach, but one that requires more thought, is to build
-a final result (desired end-state) from a set of promises about what the file
-should contain. This might or might not include templates in the sense of complete
-files that are read in.
-
-@cartouche
-If you are using CFEngine 3.3 or later, you have the option of using @code{edit_template}
-and its embedded language constructs to keep decisions and loops inside templates. Let's
-set aside that for a while and look at the alternatives, placing the data entirely
-within bundles of `edit'-promises.
-@end cartouche
-
-There is language support for this kind of editing in the standard
-library, and you can store data and template components within a
-CFEngine configuration itself, or as a separate file. For example:
-
-@verbatim
-#
-
-body common control
-{
-bundlesequence => { "main" };
-inputs => { "LapTop/cfengine/copbl/cfengine_stdlib.cf" };
-}
-
-#
-
-bundle common data
-{
-vars:
- "person" string => "Mary";
- "animal" string => "a little lamb";
-}
-
-#
-
-bundle agent main
-{
-files:
- "/tmp/my_result"
- create => "true",
- edit_line => expand_template("/tmp/my_template_source"),
- edit_defaults => empty;
-}
-
-@end verbatim
-@noindent Suppose the file @file{my_template_source} contains the following
-text:
-
-@smallexample
- This is a file template containing variables to expand
-
- e.g $(data.person) had $(data.animal)
-@end smallexample
-@sp 1
-@noindent Then we would have the file content:
-@sp 1
-@smallexample
-host$ more /tmp/my_result
- This is a file template containing variables to expand
-
- e.g Mary had a little lamb
-@end smallexample
-
-@menu
-* Adding a line here and there::
-* Lists inline::
-@end menu
-
-@node Adding a line here and there, Lists inline, Constructing files from promises, Constructing files from promises
-@unnumberedsubsec Adding a line here and there
-
-
-@noindent A simple file like this could also be defined in-line, without a separate template file:
-@verbatim
-#
-
-body common control
-{
-bundlesequence => { "main" };
-inputs => { "LapTop/cfengine/copbl/cfengine_stdlib.cf" };
-}
-
-#
-
-bundle common data
-{
-vars:
- "person" string => "Mary";
- "animal" string => "a little lamb";
-}
-
-#
-
-bundle agent main
-{
-vars:
- "content" string =>
- "This is a file template containing variables to expand
-e.g $(data.person) had $(data.animal)";
-
-files:
-
- "/tmp/my_result"
- create => "true",
- edit_line => append_if_no_line("$(content)"),
- edit_defaults => empty;
-}
-
-@end verbatim
-
-
-@node Lists inline, , Adding a line here and there, Constructing files from promises
-@unnumberedsubsec Lists inline
-
-
-@sp 1
-Here is a more complicated example, that includes list expansion. List expansion (iteration)
-adds some trickiness because it is an ordered process, which needs to be anchored somehow.
-@verbatim
-#
-
-body common control
-{
-bundlesequence => { "main" };
-inputs => { "LapTop/cfengine/copbl/cfengine_stdlib.cf" };
-}
-
-#
-
-bundle common data
-{
-vars:
-
- "person" string => "Mary";
- "animal" string => "a little lamb";
-
- "mylist" slist => { "one", "two", "three" };
- "clocks" slist => { "five", "six", "seven" };
-
- # or read the list from a file with readstringlist()
-
-}
-
-#
-
-bundle agent main
-{
-files:
-
-
- "/tmp/my_result"
-
- create => "true",
- edit_line => my_expand_template,
- edit_defaults => empty;
-}
-
-#
-
-bundle edit_line my_expand_template
-{
-vars:
-
- # import the lists, due to current limitation
-
- "mylist" slist => { @(data.mylist) };
- "clocks" string => join(", ","data.clocks");
- "other" string => "eight";
-
-insert_lines:
-
- "
- This is a file template containing variables to expand
-
- e.g $(data.person) had $(data.animal)
-
- and it said:
- ";
-
- "
- $(mylist) o'clock ";
- "
- ROCK!
- $(clocks) o'clock, $(other) o'clock
- ";
-
- " ROCK!
- The end.
- "
-
- insert_type => "preserve_block"; # So we keep duplicate line
-}
-
-@end verbatim
-This results in a file output containing:
-@smallexample
-host$ ~/LapTop/cfengine/core/src/cf-agent -f ./test.cf -K
-host$ more /tmp/my_result
-
- This is a file template containing variables to expand
-
- e.g Mary had a little lamb
-
- and it said:
-
- one o'clock
- two o'clock
- three o'clock
- ROCK!
- five, six, seven o'clock, eight o'clock
- ROCK!
- The end.
-
-@end smallexample
-
-Splitting this example into several promises seems unnecessary and inconvenient, so we could use a special
-function @code{join()} to make pre-expand the scalar list and insert it as a single object:
-
-@verbatim
-#
-
-body common control
-{
-bundlesequence => { "main" };
-inputs => { "LapTop/cfengine/copbl/cfengine_stdlib.cf" };
-}
-
-#
-
-bundle common data
-{
-vars:
-
- "person" string => "Mary";
- "animal" string => "a little lamb";
-
- "mylist" slist => { "one", "two", "three", "" };
- "clocks" slist => { "five", "six", "seven" };
-
- # or read the list from a file with readstringlist()
-
-}
-
-#
-
-bundle agent main
-{
-files:
-
-
- "/tmp/my_result"
-
- create => "true",
- edit_line => my_expand_template,
- edit_defaults => empty;
-}
-
-#
-
-bundle edit_line my_expand_template
-{
-vars:
-
- # import the lists, due to current limitation
-
- "mylist" string => join(" o'clock$(const.n) ","data.mylist");
- "clocks" string => join(", ","data.clocks");
- "other" string => "eight";
-
-insert_lines:
-
- "
- This is a file template containing variables to expand
-
- e.g $(data.person) had $(data.animal)
-
- and it said:
-
- $(mylist)
- ROCK!
- $(clocks) o'clock, $(other) o'clock
- ROCK!
- The end.
- "
-
- insert_type => "preserve_block"; # So we keep duplicate line
-}
-
-@end verbatim
-Finally, since this is now entirely contained within a single set of quotes (i.e. there is a single
-promiser), we could replace the in-line template with one read from a file:
-@verbatim
-#
-
-body common control
-{
-bundlesequence => { "main" };
-inputs => { "LapTop/cfengine/copbl/cfengine_stdlib.cf" };
-}
-
-#
-
-bundle common data
-{
-vars:
-
- "person" string => "Mary";
- "animal" string => "a little lamb";
-
- "mylist" slist => { "one", "two", "three", "" };
- "clocks" slist => { "five", "six", "seven" };
-
- # or read the list from a file with readstringlist()
-
-}
-
-#
-
-bundle agent main
-{
-files:
-
-
- "/tmp/my_result"
-
- create => "true",
- edit_line => my_expand_template,
- edit_defaults => empty;
-}
-
-#
-
-bundle edit_line my_expand_template
-{
-vars:
-
- # import the lists, due to current limitation
-
- "mylist" string => join(" o'clock$(const.n) ","data.mylist");
- "clocks" string => join(", ","data.clocks");
- "other" string => "eight";
-
-insert_lines:
-
- "/tmp/my_template_source"
- expand_scalars => "true",
- insert_type => "file";
-}
-
-@end verbatim
-@noindent
-
-
-
-@c *********************************************************************
-
-@node Editing bundles, Choosing an approach to file editing, Constructing files from promises, Top
-@unnumberedsec Editing bundles
-
-Unlike other aspects of configuration, promising the content of a single
-file object involves possibly many promises about the atoms within the file.
-Thus we need to be able to state bundles of promises for what happens inside
-a file and tie it (like a body-template) to the @code{files} promise.
-This is done using an @code{edit_line =>} or @code{edit_xml =>} constraint@footnote{At the time of writing
-only @code{edit_line} is implemented.}, for
-instance:
-
-@verbatim
-files:
-
- "/etc/passwd"
-
- create => "true",
-
- # other constraints on file container ...
-
- edit_line => mybundle("one","two","three");
-@end verbatim
-
-Editing bundles are defined like other bundles for the agent, except that they have a type
-given by the left hand side of the constraint (just like body templates):
-
-@verbatim
-bundle edit_line mybundle(arg1,arg2,arg3)
-{
-insert_lines:
-
- "newuser:x:1111:110:A new user:/home/newuser:/bin/bash";
- "$(arg1):x:$(arg2):110:$(arg3):/home/$(arg1):/bin/bash";
-}
-@end verbatim
-
-
-
-@menu
-* Standard library methods for simple editing::
-* Expressing expand_template as promises::
-@end menu
-
-@node Standard library methods for simple editing, Expressing expand_template as promises, Editing bundles, Editing bundles
-@unnumberedsubsec Standard library methods for simple editing
-
-You may choose to write your own editing bundles for specific purposes; you can also use
-ready-made templates from the standard library for a lot of purposes. If you follow the
-guidelines for choosing an approach to editing below, you will be able to re-use standard
-methods in perhaps most cases. Using standard library code keeps your own intentions clear
-and easily communicable.
-For example, to insert hello into a file at the end once only:
-@verbatim
-files:
-
- "/tmp/test_insert"
-
- create => "true",
- edit_line => append_if_no_line("hello"),
-edit_defaults => empty;
-
-@end verbatim
-Or to set the shell for a user
-@verbatim
-files:
-
- "/etc/passwd"
- create => "true",
- edit_line => set_user_field("mark","7","/my/favourite/shell");
-
-@end verbatim
-
-Some other examples of the standard editing methods are:
-
-@verbatim
- append_groups_starting(v)
- append_if_no_line(str)
- append_if_no_lines(list)
- append_user_field(group,field,allusers)
- append_users_starting(v)
- comment_lines_containing(regex,comment)
- edit_line comment_lines_matching(regex,comment)
- delete_lines_matching(regex)
- expand_template(templatefile)
- insert_lines(lines)
- resolvconf(search,list)
- set_user_field(user,field,val)
- set_variable_values(v)
- set_variable_values2(v)
- uncomment_lines_containing(regex,comment)
- uncomment_lines_matching(regex,comment)
- warn_lines_matching(regex)
-@end verbatim
-
-You find these in the documentation for the COPBL.
-
-
-@c *********************************************************************
-
-
-@node Expressing expand_template as promises, , Standard library methods for simple editing, Editing bundles
-@unnumberedsubsec Expressing @code{expand_template} as promises
-
-As on CFEngine 3.3.0, CFEngine has a new template mechanism to make it
-easier to encode complex file templates. These templates map simply to @code{edit_line} bundles
-in the following way.
-
-@itemize
-@item Each line in a template maps to a separate @code{insert_lines} promise unless it is grouped with @samp{[%CFEngine BEGIN %]} and @samp{[%CFEngine END %]} tags.
-@item Each multi-line group, marked with @samp{[%CFEngine BEGIN %]} and @samp{[%CFEngine END %]} tags maps to a multi-line @code{insert_lines} promise, with @code{insert_type => "preserve_block"}.
-@item Each line that expresses a context-class: @samp{[%CFEngine @var{classexpression}:: %]} maps to a normal
-class expression in a bundle.
-@end itemize
-
-The order of lines in the template is preserved within each block, or if @code{edit_defaults} is used
-to empty the resulting generated file before editing: e.g. with the standard library method:
-
-@verbatim
-
- "/tmp/expander"
-
- create => "true",
- edit_template => "/home/a10004/input.dat",
- edit_defaults => empty;
-
-@end verbatim
-
-
-@node Choosing an approach to file editing, Pitfalls to watch out for in file editing, Editing bundles, Top
-@unnumberedsec Choosing an approach to file editing
-
-There are two decisions to make when choosing how to manage file content:
-
-@table @i
-@item How can the desired content be constructed from the necessary source(s)?
-Is there more than one source of infromation that needs to be merged?
-
-@item Do the contents need to be adapted to the specific environment?
-Is there context-specific information in the file?
-@end table
-
-@cartouche
-Use the simplest approach that requires the smallest number of promises to solve the
-problem.
-@end cartouche
-
-@node Pitfalls to watch out for in file editing, , Choosing an approach to file editing, Top
-@unnumberedsec Pitfalls to watch out for in file editing
-
-File editing is different from most other kinds of configuration
-promise because it is fundamentally an order dependent configuration
-process. Files contain non-regular grammars. CFEngine attempts to simplify
-the problem by using models for the file structure, essentially factoring out
-as much of the context dependence as possible.
-
-Order dependence increases the fragility of maintainence, so you should do what you can to minimize it.
-
-@itemize
-@item Try to use substitution within a known template if order is important.
-@end itemize
-
-The simplest kinds of files for configuration are line-based, with no special order. For such
-cases, simple line insertions are usually enough to configure files.
-
-The increasing introduction of XML for configuration is a major headache for configuration
-management.
-
-@ifhtml
-@html
-
-@contents
-@end html
-
-
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_FIPS.texinfo b/docs/guides/SpecialTopic_FIPS.texinfo
deleted file mode 100644
index 17ef6bdbb8..0000000000
--- a/docs/guides/SpecialTopic_FIPS.texinfo
+++ /dev/null
@@ -1,150 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-fips.info
-@settitle FIPS certification
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title FIPS validated cryptography in CFEngine
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-The FIPS 140-2 validation for approved cryptographic modules is a current
-government requirement in the USA. This document explains the use of
-FIPS 140-2 validated modules in commercial CFEngine versions.
-
-FIPS 140-3 is underway and will supercede FIPS 140-2 at some unknown time in the future.
-
-QA: MB,NP,CR
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} July 2010 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-
-@iftex
-@contents
-@end iftex
-
-
-@unnumberedsec What is FIPS 140-2?
-@sp 1
-
-FIPS 140-2 is a standard published by the National Institute of
-Standards and Technology (NIST)[1]. NIST also established the
-Cryptographic Module Validation Program (CMVP)[2] that validates
-cryptographic modules to the FIPS 140-2 standard. Vendors seek
-validation for their cryptographic modules in order to provide
-assurance that their encryption solutions are properly implemented
-to an accepted standard.
-
-A cryptographic module that has already been issued a FIPS 140-2
-validation certificate may be incorporated or embedded into
-another product. [3]
-
-In order to use a validated cryptographic module and attest FIPS 140-2
-validation, the new product must:
-@itemize
-@item Reference the certificate number of the validated module,
-@item Must not alter the original validated module.
-@item Must adhere to the documented security policy for the validated module.
-@end itemize
-
-
-@unnumberedsec What is the certificate number?
-@sp 1
-
-CFEngine attests to NIST certificate number 1111.
-
-These validations were not initiated by CFEngine, but any user of
-this Open Source software module can use them provided we follow the
-instructions in the security policy.
-
-@unnumberedsec Declaration from CFEngine
-@sp 1
-
-The current FIPS 140-2 Crypto Policy Officer for CFEngine resides
-at CFEngine AS/Inc headquarters. The security officer attests that
-packages provided by CFEngine, on the customer download site
-software.CFEngine.com, whose names contain the term FIPS in upper or
-lower case have been compiled according to the security policy for
-certificate 1111 [5]. CFEngine packages, marked FIPS, have been built
-from source code located at:
-
-@url{http://www.openssl.org/source/openssl-fips-1.2.tar.gz}
-
-@noindent according to the security policy documented in [6].
-CFEngine can provide compliant software on all Unix-like platforms,
-but not currently on Windows.
-
-
-@unnumberedsec Algorithms
-@sp 1
-
-CFEngine uses OpenSSL encryption code from the libcrypto library. It
-does not use any SSL or TLS specific modules. CFEngine uses RSA
-encryption for authentication. Commercial versions of CFEngine use
-AES-256 symmetric encryption with a random session key for transport.
-
-@unnumberedsec Future policy
-@sp 1
-
-It is CFEngine's policy to obtain a private validation of the
-OpenSSL crypto module at some time in the next two years for the principal
-purpose of branding. This is a long process and does not alter the
-specification of the software in any way.
-
-@page
-@unnumberedsec References
-@sp 1
-
-@enumerate
-@item Security policy 1111:
-
-@item @url{http://csrc.nist.gov/groups/STM/cmvp/standards.html}
-
-@item @url{http://csrc.nist.gov/groups/STM/cmvp/index.html}
-
-@item @url{http://csrc.nist.gov/groups/STM/cmvp/documents/CMVPFAQ.pdf}
-
-@item @url{http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/140val-all.htm#1111}
-
-@item @url{http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/140crt/140crt1111.pdf}
-@item @url{http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/140sp/140sp1111.pdf}
-
-
-@end enumerate
-
-@bye
-
-
diff --git a/docs/guides/SpecialTopic_Federation.texinfo b/docs/guides/SpecialTopic_Federation.texinfo
deleted file mode 100644
index 89a5030368..0000000000
--- a/docs/guides/SpecialTopic_Federation.texinfo
+++ /dev/null
@@ -1,593 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-federation.info
-@settitle Orchestration
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Federation and Organizational Complexity
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-Each business or organization has a necessary and sufficient level of
-complexity for its tasks: too complex and resources are wasted due to
-vlack of comprehension, too simple and the business is not being served
-properly. Complexity often arises when organizations merge because
-leaders attempt to reorganize hierarchically. This ST Guide explains
-strategies that are suited to cope with complexity, and how best to
-organize a CFEngine configuration.
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2010 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Iteration:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-
-@node Top, What is organizational complexity?, (dir), (dir)
-@top Federation
-@menu
-* What is organizational complexity?::
-* What is federation?::
-* Coordination::
-* The Authority Paradox::
-* The social contract::
-* Service oriented federation::
-* Each part disconnected providing services::
-* Disconnected parts inheriting a single baseline::
-* Handling multiple sources::
-* Global assurance::
-* Merging and dividing enterprises::
-* Why federation does not reduce predictabilty::
-* The benefits of federated management::
-@end menu
-
-@end ifnottex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@node What is organizational complexity?, What is federation?, Top, Top
-@unnumberedsec What is organizational complexity?
-
-Complexity is a measure of the amount of information needed to explain
-something. It implies a `mental cost' (and therefore a time and
-monetary cost) to comprehend a pattern of structure and behaviour.
-
-The term organization has two distinct meanings in English: it can be
-intended as a euphemism for an @i{institution} or a business, and it
-can be intended to mean an ordered @i{structural pattern} (i.e. the
-state of being organized). To avoid confusion, we shall refer to
-businesses and public institutions as enterprises, and use the term
-organization to mean an architectural pattern with a certain level of
-complexity.
-
-Organizational Complexity is therefore the amount of information, and
-hence cost, needed to manage an enterprise or system. In information
-science, the complexity of a system is commonly defined as the length
-of the shortest document that fully describes it. A complex system
-requires a long document to capture its workings; a simple system
-requires only a short document.
-
-
-@node What is federation?, Coordination, What is organizational complexity?, Top
-@unnumberedsec What is federation?
-
-A federation is a pattern of organization obtained by merging a number
-of initially independent parts. The implication is that the resulting
-organization is not a singular rigid unit, but rather a more loosely
-coupled collective of autonomous parts.
-
-Federation is a natural structure for any enterprise that has parts
-with fundamentally different functions or orgins. It can also be a
-stepping stone on the way from a set of independent actors to a state
-of unified integration.
-
-@sp 1
-@cartouche
-Companies that merge or acquire other companies, as well as
-companies that reorganize to outsource tasks are natural candidates
-for federated management.
-@end cartouche
-@sp 1
-
-Promise theory predicts that a federated organization is naturally
-@i{service oriented}, with two main architectures:
-@itemize
-@item The different parts of the collective bind together
-by promising each other services.
-
-
-@item The parts offer services to external parties, but are bound
-together by promising to coordinate with a central entity.
-
-@end itemize
-
-@node Coordination, The Authority Paradox, What is federation?, Top
-@unnumberedsec Coordination, hierarchy and centralization
-
-Federated parts of an enterprise are said to be coordinated by an
-entity, if they receive common information from it. Merely delivering
-services (i.e. keeping promises) to a common entity does not lead to
-coordination. Think of an orchestra. The conductor does not bring
-about any coordination simply by listening, but rather by providing
-common signals to the federated agents. On the other hand, the
-conductor is a bottleneck who throttles the productivity of the
-federated agents. If the agents rely too much on the conductor, or are
-discouraged from acting independently, the amplification of effort is lost.
-
-@center @image{coordination,12cm,,,png}
-@center Coordination implies common knowledge.
-@sp 1
-The need for coordination is often exaggerated in human organizations
--- it comes from an unrealistic desire to absolutely determine the
-outcome of decisions. Realistically, it is only a means to bring
-consistency to distributed parts.
-
-
-@sp 1
-@cartouche
-In ITIL and current IT parlance, a central hub containing coordination
-information is called a Configuration Management Database (CMDB). The
-term CMDB refers to a range of quite different approaches to
-coordinating information that will not be discussed here.
-In Object Orientation, the term @i{inheritance} is used to signify the
-use of common information by federated parts.
-@end cartouche
-@sp 1
-
-It is possible for federated parts to inherit coordinating information
-from more than one source, just as it is possible for someone to have
-two different jobs. In that case, one must be careful to avoid
-conflicting directions. As organizational complexity grows, the
-possibility of conflicting direction and expectation also grows unless strict principles
-are adhered to.
-
-Promise Theory tells us that such conflicts can only be resolved by a
-party receiving information, not by the parties sending it. This leads
-to the model known as `voluntary cooperation' used by CFEngine, which
-implies that each federated part must effectively choose which inputs it is
-willing to use from external parties.
-
-
-
-@node The Authority Paradox, The social contract, Coordination, Top
-@unnumberedsec The Authority Paradox
-
-For some, the idea that an organization should be built on voluntary
-cooperation sounds wrong. However, no matter how much we might crave
-certainty of outcome, making demands on the compliance of federated parts
-does nothing to improve that certainty; indeed, it can
-have the reverse effect. The confusion lies in a misunderstanding of desired
-authority over the actual power to change, i.e. in what is intended or desired and
-what is actually possible. Promise Theory resolves this confusion
-by building a model based directly on the agents that can effect change.
-
-Authority is about who, in an enterprise, may decide what is
-intended. Most people perceive authority through hierarchies or
-`chains of command' in which the top of the hierarchical pyramid is
-the master, and the layers below must follow: those at the top are
-more powerful than those on the bottom. This is a cultural
-prejudice. However this perception is, at best misleading, and in fact
-is incorrect.
-
-Humans have been organizing things into hierarchies for most of
-recorded history. We have a deeply held notion that favours
-hierarchies as an organizational form. It is worth examining why. In
-early times the upper echelons of hierarchy were the strong and the
-educated, served by a relatively unspecialised workforce. They wielded
-their power by guile and by violent force, and the lower layers cowered
-in fear. From Kings and leaders to middle managers and class-system
-underdogs, institutions and government, documents and tables of
-contents, everywhere we look we see hierarchical structures.
-
-@sp 1
-@center @image{brainbrawn,8cm,,,png}
-@sp 1
-@center The authority paradox
-@sp 1
-
-Today, education and peaceful society turns the reality of the power
-hierarchy upside down: the true specialists are at the bottom of the
-hierarchy, closer to the levers and the expertise to effect change.
-Today `low level' means more specialised, not less educated. Low
-level experts are held together by relatively unspecialised `managers'
-who serve mainly as coordinators and communications links. However,
-the culture and perception of authority from the top remains today.
-
-These changes create a paradox in modern systems. The leadership of
-intent is assumed to come from above, but the real power to act is
-down below. This necessitates the binding together of organizations
-by a social contract of @i{voluntary cooperation}.
-
-The same is true in computer systems. Most system designs assume
-that the point of command will be placed at the top of an
-organizational tree, and that every part of the system (represented in
-the branches and leaves) will follow the commands made from the top.
-This turns out to be a poor model because, in reality, the top has
-neither the knowledge nor the proximity to enforce changes below.
-
-No central management of either enterprise or computers can force
-individual agents to comply with their wishes, without their low level
-consent. The perception of authority is thus only a
-fiction@footnote{Think of an orchestra. The real expertise lies in the
-players (below). The conductor (above) offers coordination and
-guidance, but has no real power to create music. Music is possible
-because each player has his/her own copy of the script, and can work
-autonomously, with only a little guidance.}.
-
-
-
-
-@node The social contract, Service oriented federation, The Authority Paradox, Top
-@unnumberedsec The social contract
-
-Social contracts lie at the heart of all human and computer
-organizations. For computers these contracts may be as simple as
-`access control settings', nonetheless there are human politics behind
-them. Most enterprises struggle more with their internal sociology
-(or politics) than with their technological solutions.
-
-When an organization is formed by merging independent parts, this is
-especially important. The loss of identity and the feeling of loss of
-autonomy by these parts can fuel a breakdown of the social contract --
-i.e. a loss of loss of voluntary cooperation. In terms of system
-management, it therefore makes sense to preserve as much of the
-identity and autonomy of the parts as possible.
-
-From an information perspective, this is also the lowest cost solution.
-The expertise to run the merged entity already exists within
-it@footnote{At least we may assume this.}, and the proximity to make
-change is automatic, so to increase the organizational distance
-between decision, expertise and change will at best lead to increased
-overhead and at worst lead to the disconnection of decision making from
-expertise.
-
-@sp 1
-@cartouche
-Low level autonomy is a cost saving strategy that reduces the overhead
-of management and improves the link between expertise and action.
-@end cartouche
-
-
-@node Service oriented federation, Each part disconnected providing services, The social contract, Top
-@unnumberedsec Service oriented federation
-
-Service oriented means business oriented.
-Let us now consider what this means for IT configuration. In
-particular, how should a CFEngine configuration be structured for an
-efficient organization? In the examples below, we shall adopt a
-service oriented view, in which an enterprise is organized as a set of
-federated entities, some of whom depend on each other for services.
-
-
-
-@node Each part disconnected providing services, Disconnected parts inheriting a single baseline, Service oriented federation, Top
-@unnumberedsec Each part disconnected, providing services
-
-Each federated entity manages its own @file{promises.cf} file. Each has, in effect, its
-own independent CFEngine configuration.
-
-@sp 1
-@center @image{fed1,12cm,,,pdf}
-@center Independent configurations - complete autonomy
-
-The configuration may still use resources provided by other entities' machines, but
-the other entities have no influence on the set of promises used to maintain any given one.
-
-
-
-
-
-@node Disconnected parts inheriting a single baseline, Handling multiple sources, Each part disconnected providing services, Top
-@unnumberedsec Disconnected parts inheriting a single baseline
-
-A more common model for federation is to have a baseline constitution
-for all the parts of the enterprise defined by an umbrella
-organization. We can refer to this as a `global infrastructure'
-service.
-
-Traditionally (i.e. hierarchically) one would think of this global
-entity as being superior to the other entities, i.e. making them
-subordinate, but this is not necessary, nor correct according to the
-reality. The role of the global service is rather to provide a point
-of consistent coordination, or centralized expertise to the others.
-Compliance with the proposals of the global coordinator will be
-assured if it plays a valuable roles.
-
-@sp 1
-@cartouche
-Since the real power to change still lies in the hands of the
-federated entities, the global infrastructure unit must build
-a social contract with them to assure that its wishes are
-complied with. This goal is attended to by making the global
-entity a valued service for the federated entities. If the
-global service is perceived as being of no value, it will be
-ignored.
-@end cartouche
-@sp 1
-
-@noindent The next step from full autonomy is thus to use methods that
-have been defined by an enterprise-wide global infrastructure service.
-
-@sp 1
-@center @image{fed2,10cm,,,png}
-@center Independent configurations using a common baseline
-@sp 1
-
-
-@cartouche
-@verbatim
-
-#
-# Federated promises.cf
-#
-
- bundle agent main
- {
- files:
-
- "$(sys.workdir)/inputs/baseline.cf"
-
- copy_from => remote_cp(
- "/masterfiles/baseline.cf",
- "central_service.example.com"
- );
- methods:
-
- # Inherit the baseline constitution
-
- "baseline" usebundle => company_baseline;
-
- # All other local promises here ....
- }
-
-@end verbatim
-@end cartouche
-@sp 1
-
-The CFEngine code snippet above represents the CFEngine configuration
-for any of the hosts in one of the federated departments. The
-configuration is extremely simple. It begins by downloading the
-@file{baseline.cf} configuration, provided by the global
-infrastructure service, and then goes on to promise to use this as a
-`method'. Finally, the major part of the configuration is the set of
-special promises determined by the department itself. Federation is thus
-technically trivial. The difficulties are rather conceptual and
-sociological.
-
-Let us remark on the likelihood for conflict. Although the source of
-the baseline is external, CFEngine configuration promises are always
-implemented by the federated departments themselves, none are (or can
-be) implemented by any external party such as the infrastructure
-service. Thus, it is the responsibility of federated departments to
-ensure that there are no conflicts between the baseline and their own
-promises. Moreover, as the parts have no power to change the baseline, but
-have agreed to follow it, the logical outcome must be that their own
-special promises must not conflict with the global infrastructure
-proposal. So all requirements are met without the need for central enforcement.
-
-
-@node Handling multiple sources, Global assurance, Disconnected parts inheriting a single baseline, Top
-@unnumberedsec Handling multiple sources
-
-Consider briefly the case in which there is more than one entity
-offering promise proposals. If a part of the federation serves two
-masters (see department 3 in the figure below), i.e. it promises to
-implement the wishes of two external sources, then those sources must
-either agree one hundred percent in their proposals, or they must not
-overlap at all. Since these `masters' may or may not be coordinated,
-it is up to the federated entity (department 3) to make the decision
-about which of the sources to obey.
-
-@sp 1
-@center @image{fed3,12cm,,,png}
-@center Multiple inheritance can lead to incorrect expectations.
-@sp 1
-
-The possiblity of conflict is easily handled in this architecture,
-because it recognizes that the federated entity must be the final
-arbiter of confict.
-
-
-@node Global assurance, Merging and dividing enterprises, Handling multiple sources, Top
-@unnumberedsec Global assurance
-
-The lack of a hierarchy has not made information chaotic and
-disorganized. It has only provided a simple means of
-scalability and conflict resolution.
-
-So what makes a federation different from a collection of completely
-independent enterprises? The answer to this question us usually
-some minimum set of common promises that all parts of the federation
-must keep: a baseline constitution.
-
-Now, since the real power lies in the leaves of the organizational
-tree, but the designated authority lies at the root, the root needs to
-monitor the behaviour of the federated entities to ensure that this
-baseline constition is being complied with. This can be handled by
-performing an audit of the whole federation according to a single
-standard@footnote{Think, once again, about the orchestra. The
-conductor observes the behaviour of each autonomous player to
-determine whether the orchestra is playing together and is playing the
-same piece of music.}.
-
-
-@sp 1
-@cartouche
-CFEngine allows single-point-of-coodination monitoring of hosts
-by a variety of mechanisms, so that compliance can be assured.
-@end cartouche
-
-
-@node Merging and dividing enterprises, Why federation does not reduce predictabilty, Global assurance, Top
-@unnumberedsec Merging and dividing enterprises
-
-Autonomy makes the merging and division of enterprise systems trivial.
-It is the way to enable out-sourcing and in-sourcing.
-
-Imagine trying to combine two cups of coffee. Now try combining two
-combine two buildings or houses of cards. Coffee mixes easily because
-it is not full of dependencies (bonds) between its parts. Buildings
-are not fluid: at best one can build bridges between them, and try to
-build something else around them and then take them apart. The same
-applies to any system, whether human, software or mechanical.
-
-To merge two systems or enterprises, it will be much simpler if they
-are fluid to begin with -- i.e. they are basically composed of
-autonomous parts, loosely coupled, not rigidly joined together. Hierarchical
-organization is rigid, like a house of cards. Service-oriented
-systems are loosely coupled. By keeping the internal organization of
-systems as far as possible like independent service atoms, you
-facilitate reorganization by merging and division.
-
-@node Why federation does not reduce predictabilty, The benefits of federated management, Merging and dividing enterprises, Top
-@unnumberedsec Why federation does not reduce predictabilty
-
-The fear that many traditionalists have of federated management is
-that they cannot be certain of the outcome unless they have absolute
-authority. This fear is misplaced however. Certainty of outcome does
-not depend on whether authority is federated or not: there are many
-reasons why outcomes fail to be realized, including misunderstandings, accidents, force
-majeur and simple disagreements.
-
-Certain knowledge can only be obtained by observing the results
-directly@footnote{This is why society needs a police force to monitor
-and respond to those who do not obey proposed law -- whether they have
-promised to or not. This is the role of CFEngine.}, and repairing the
-system if promises have not been kept.
-Trying to enforce rules and command from above is an expensive and
-often ineffective way to manage systems, like swimming against the
-current. Trust in the federated system reduces the cost of verifying
-one's assumptions.
-
-Hierarchies are sometimes used for oversight. Just as a conductor
-takes care of the big picture for his orchestra, so managers in a
-hierarchy can use their position to coordinate the larger picture for
-their subordinates. However, like the orchestra, the manager should
-not think that he has a real influence on the outcome. As long as each
-player has the script and the instruments, the music can go on for
-quite some time without its conductor. The role of a manager is one of
-advice.
-
-@sp 1
-@cartouche
-Rules of thumb for scalable management:
-
-@itemize
-@item Use autonomy to scale: proximity to the affected area
-avoids unnecessary dependency and transport of materials.
-Trust costs less.
-
-@item If you need to enforce a common baseline (or constitution) for all,
-then arrange this as a service, not as a punitive force. Use local
-caching and the principal of convergence to a desired state
-(idempotence) to provide assurance without the cost of monitoring.
-
-@item Trust lowers costs.
-@end itemize
-@end cartouche
-
-@node The benefits of federated management, , Why federation does not reduce predictabilty, Top
-@unnumberedsec The benefits of federated management
-
-Hierarchy is familiar, but not essential. A hierarchy is only a
-so-called `spanning tree' for a more general network of relationships.
-It may be thought of as one possible point of view, amongst many --
-one way of traversing a network of relationships.
-
-A federated organization is automatically specialized into departments,
-each of which knows its requirements best.
-
-One could take an enterprise and divide it into
-skill-areas or departments, then divide each department into
-geopgraphical teams. Conversely, we could divide the enterprise by
-country first and subdivide each country into regions, then divide
-these into skills. There is no unique way to traverse the
-enterprise. In truth, it is not a hierarchy, but a network of
-relationships.
-
-If the federated teams or clusters in an enterprise have sufficient
-autonomy, both in resources and intended authority, then they don't
-need to communicate with or wait for other parts to do their jobs.
-Forcing that communication, due to lack of trust, will add overhead
-and increase costs, without improving the certainty of outcome.
-
-Promise Theory tells us that organization by autonomy automatically
-indentifies the parts of a system that can operate independently --
-i.e., the essential `atoms' of the system. Thus, it is a method for
-identifying the raw material building blocks from which everything
-else can be built. Starting with these available raw materials, it
-encourages a rational approach to design of systems that are efficient
-and service oriented.
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_Hierarchy.texinfo b/docs/guides/SpecialTopic_Hierarchy.texinfo
deleted file mode 100644
index eae1675cd5..0000000000
--- a/docs/guides/SpecialTopic_Hierarchy.texinfo
+++ /dev/null
@@ -1,616 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-hierarchy.info
-@settitle Hierarchies
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Hierarchies: Authority, Structure and Inheritance
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-Using hierarchies is one way of distributing the load from a single CFEngine
-policy server. They are also useful when an organization has different types
-of machine classes. These classes can be based on location or on function,
-and oftentimes the distinction of machine class will also be reflected in
-differences in configuration.
-
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2010 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Iteration:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@node Top, What is a hierarchy?, (dir), (dir)
-@top Hierarchies
-
-@menu
-* What is a hierarchy?::
-* How hierarchy compares to sets::
-* Classes are sets::
-* For and against hierarchies::
-* Inheritance and its forms::
-* Expressing is-a or has-a::
-* How to organize your organization::
-* Applications of hierarchy::
-@end menu
-
-@end ifnottex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@node What is a hierarchy?, How hierarchy compares to sets, Top, Top
-@unnumberedsec What is a hierarchy?
-
-A hierarchy is an organizational structure with tree-like branches. In
-a hierarchy, parts of the system belong to other parts, like
-collections of boxes inside other boxes. Each time you move, you
-either ascend or descend to a different level with respect to the
-root. Hierarchies are called @i{Directed Acyclic Graphs} (DAG) in
-mathematics (see figure below (a) and (b)).
-
-@sp 1
-@center @image{networks,10cm,,Network organizational structures.,png}
-@sp 1
-
-@noindent Hierarchies are often associated with @i{authority}, as
-we use hierarchies to organize human `chains of command'. In this
-case, a hierarchy typically has multiple levels, as in (b). You might
-interpret this diagram as showing a single point of top level
-management, then satellite areas of middle management each with their
-own clusters of slaves (leaf nodes). When drawing hierarchies, the root of the tree is
-placed at the top or centre of the picture and is considered to be
-@i{authoritative}, i.e. more important than the `leaves'. Each leaf
-node is then subject to the control of the root in a @i{top down}
-manner.
-
-
-The opposite of a hierarchy is a @code{mesh} or web (figure (c)),
-which has no special or privileged node -- nodes are simply connected
-by some kind of relationship. In mesh organization, each individual
-has an area of responsibility and they talk on demand to other nodes,
-without any particular ranking. If you move in a mesh, you cannot
-easily measure how far you are away from a given point, as their might
-be more than one way of getting there.
-
-Mesh architectures are often robust to failure as there can be multiple
-`peer to peer' routes for passing messages or information.
-
-@cartouche
-Top-down is is a cultural prejudice or `norm', as most human societies work in this
-way. However it is not a necessity. A network service is bottom-up -- there
-it is the leaves which drive requests that end at a single central server.
-Hierarchies are special cases of @i{networks}, and (as all special cases) they are fragile,
-because the have top-down redundancy, but not bottom-up redundancy.
-We say that hierarchies have a Single Point of Faliure at the root,
-as failure at that point will disconnect the network.
-
-@sp 1
-@center @image{nettolerance,6cm,,Network organizational structures.,png}
-@end cartouche
-
-@sp 1
-
-
-
-@node How hierarchy compares to sets, Classes are sets, What is a hierarchy?, Top
-@unnumberedsec How hierarchy compares to sets
-
-@sp 1
-
-Some languages (like Object Oriented languages) are designed to
-enforce hierarchies. CFEngine is not one of these. In CFEngine you can
-build a hierarchy if you want to, but you can also build any other
-kind of network. The parts of your system can also work with complete
-autonomy if that is what you want. CFEngine does not push a model onto you.
-
-@noindent Consider this example of CFEngine classes. It expresses a tree
-structure.
-@verbatim
-classes:
-
- # Conceptual hierarchy
-
- "top" or => { "middle_1", "middle_2", "middle_3" };
- "middle_1" or => { "slave_1", "slave_2", "slave_3" };
- "middle_2" or => { "slave_4", "slave_5", "slave_6" };
-
-@end verbatim
-This example is contrived. The core classes that CFEngine cares about
-are the slaves, since CFEngine is a bottom-up system. The definition
-of the middle and top classes are @i{aggregations} of clusters of
-basic member attributes.
-
-Consider this example of a geographically distributed organization,
-with finance, engineering and legal departments in three countries.
-@verbatim
-# Hierarchy
-
- "headquarters" or => { "usa", "uk", "norway" };
- "department" or => { "finance", "engineering", "legal" };
-
-@end verbatim
-@noindent We can express the full hierarchy like this:
-@verbatim
-usa.finance
-usa.engineering
-usa.legal
-uk.finance
-uk.engineering
-uk.legal
-norway.finance
-norway.engineering
-norway.legal
-@end verbatim
-@noindent In this notation, the dot looks like `member' because the
-departments are smaller than the countries and are contained within them.
-You might feel that this model is upside down and that one should consider
-the finance department to be a unified global entity, with branches in
-three different countries. In that case, you would write
-@verbatim
-finance.uk
-finance.usa
-finance.norway
-@end verbatim
-
-This highlights the fact that we often want to slice and dice organizations
-in different ways, and attending too closely to a single hierarchical model
-prevents that.
-The key is to notice that the `.' (dot) operator is really an intersection
-of sets (AND)@footnote{It is a commutative operator, which is why it makes sense
-to write both @code{usa.finance} and @code{finance.usa}.}, and that this is
-a much more flexible notion than hierarchy.
-
-@node Classes are sets, For and against hierarchies, How hierarchy compares to sets, Top
-@unnumberedsec Classes are sets
-
-@quotation
-@i{`Sets, sets, sets ... all you ever think about it sets!'@*}
-@*
--- Anonymous
-@end quotation
-
-
-Underlying hierarchies and networks is the concept of @i{sets}. A set
-or @i{collection} of something is just a number of instances that
-satisfy some property. For example, the @i{set of all Windows
-machines}, or the @i{set of times between 2 and 3 o'clock}. Sets can
-be thought of as networks in which the elements are all joined to each
-other by a common relationship `in the same set as'.
-
-The name of a set can be thought of as a property that characterizes
-the members, and as such it behaves like an abstract box or container for the members.
-Containment in classes is the basis for hierarchies in Object Orientation, for instance.
-
-We often write subset membership using a membership `.' character, e.g. if @samp{linux}
-is the set of hosts with property `linux', then a subset (or sub-class) of these
-hosts is `debian' (see figure). The class @i{64 bit hosts} is not a subset of
-linux, as part of it lies outside. It is a subset of @i{hosts}.
-
-@example
-linux.debian
-linux @i{AND} debian
-linux @i{intersect} debian
-@end example
-
-@center @image{intersect,5cm,,Overlapping sets.,png}
-
-Sets can be made hierarchical when every subset is contained entirely by one and
-only one parent set, and in turn contains zero or more whole subsets which it
-does not share with any other. The problem with hierarchical sets is
-that they are too restrictive. If you design them incorrectly in the
-first place, you shut parts of the organization inside a box that
-prevents other parts from accessing them.
-
-CFEngine works only with sets. It does not assume that sets never overlap.
-Indeed, it encourages you to use as many overlapping sets as possible to
-create optimum, simple categories to address the parts of your organization.
-This gives us great power. We can for instance extract the list of all English
-speaking entities from the definitions about our organization, by adding a
-defintion of set @i{union} (OR or @samp{|}) and @i{intersection} (AND or @samp{.}):
-@verbatim
-# Hierarchy
-
- "headquarters" or => { "usa", "uk", "norway" };
- "department" or => { "finance", "engineering", "legal" };
-
- "english_speaking" expression => "(usa|uk).!legal";
-
-@end verbatim
-@noindent Thus the English speakers are those entities belonging to
-the USA `AND' the UK, excepting presumably the legal department.
-
-
-@node For and against hierarchies, Inheritance and its forms, Classes are sets, Top
-@unnumberedsec For and against hierarchies
-
-@sp 1
-Hierarchies are good at bringing consistency. They are bad at scaling.
-They bring consistency because the root node acts as a single point of
-authority, i.e. the network speaks with a single voice. The scale
-poorly because they funnel communication to a single point of failure
-and processing so that the weakest link is the most authoratative
-node.
-
-The Internet was designed by smart engineers to @i{not} be a hierarchy
-so that it would be robust to failure of single nodes. Since then,
-incorrigable humans have done their best to make it hierarchical from
-the viewpoint of the Domain Name Service (DNS) classification, so that
-organizational identifiers seem to fall into simple tree-like
-hierarchies.
-
-Because the idea of hierarchy is so prevalent, it is many peoples' first
-instinct to build hierarchical organizations. At CFEngine we believe that
-the idea is over-used, and causes as many problems as it brings solutions,
-so CFEngine does not encourage it.
-
-This document tries to show how to use hierarchy sensibly and usefully to
-simplify rather than to enforce authority.
-
-@node Inheritance and its forms, Expressing is-a or has-a, For and against hierarchies, Top
-@unnumberedsec Inheritance and its forms
-
-@sp 1
-Perhaps the most popular application of hierarchy is to use the
-property of having a single-point of definition to avoid maintaining
-the same information in more than one place. @i{This is an efficiency}.
-Inheritance is expressed in different ways:
-
-@itemize
-@item Special subset @i{extends} base set properties, emphasizing that the
-leaf builds on, or adds the root in order to extend it.
-@item Special subset @i{inherits} base set properties, emphasizing that
-the leaf is a consumer of the root and does not necessarily offer any more.
-@item Special subset @i{depends on}, emphasizing that the root is a single
-point of failure for the leaf.
-@end itemize
-These are basically equivalent expressions of the same thing. No
-matter how we choose to express this, inheritance is a client-server
-relationship in which a single source is feeding a number of possible
-users.
-
-@sp 1
-@cartouche
-In Promise Theory, we consider this to be a use-promise (service) relationship.
-A single point promises information, and a number of leaf-nodes promise to use it.
-@end cartouche
-@sp 1
-
-@sp 1
-@center @image{inherit,10cm,,Network organizational structures.,png}
-@sp 1
-The figure shows how we maintain common information in a `base' or server.
-Then the users or consumers of the information are so-called derived classes.
-
-We can use the notion of inheritance at different levels within CFEngine.
-These are a matter of using the global scope with bundle names.
-
-@table @i
-@item Inheritance of classes/sets
-We can aggregate smaller classes into larger ones (yielding multiple
-inheritance of class attributes):
-@verbatim
-classes:
-
- "group_name" or => {
- "base_class_1",
- "base_class_2",
- "base_class_3"
- };
-
-@end verbatim
-Note that CFEngine naturally forms a bottom-up hierarchy, never a top-down hierarchy.
-
-@item Inheritance of class definitions
-CFEngine divides its promises into bundles that have private classes
-and variables. Bundles called `common bundles' define @i{global classes},
-so they are automatically inherited by all other bundles.
-
-@item Inheritance of variable definitions
-
-Variables in CFEngine are globally accessible, but you must say
-what bundle you are talking about by writing @samp{$(bundle.scalar)}
-or @samp{@@(bundle.list)}. If you omit the `bundle', it is assumed
-that the variable is in the current bundle.
-
-@verbatim
-bundle agent child_bundle(parameter)
-{
-vars:
-
- "extend_list" slist => { "extension", @(foreign.list) },
- policy => "ifdefined";
-
-reports:
-
- "Inherit parameter value $(parameter)";
- "Inherit foreign scalar value $(foreign.scalar)";
-
-}
-@end verbatim
-The policy @code{ifdefined} means that CFEngine will ignore
-the foreign list if it does not exist. This means you can
-include a number of lists from other bundles to extend
-the behviour of your own, if they are provided.
-
-@item Inheritance of bundles
-Bundles cannot really be merged like sets, but since they
-make promises you can @i{use} them.
-
-@verbatim
-bundle agent child_bundle
-{
-methods:
-
- "extend_method" use => base_bundle(parameter1,parameter2);
-
-}
-@end verbatim
-
-A bundle can only be used if it exists, so we can also talk about
-plug-ins for bundles. In CFEngine, you include entire bundles either
-in the the @code{bundlesequence}, or as @code{methods}.
-
-Normally you have to know exactly which bundles are going to exist in
-advance, as CFEngine considers missing code to be a security issue and
-will signal an error for missing bundles. This is the default
-behaviour, but we can override it using the following @code{body agent
-control} promises.
-@table @code
-@item ignore_missing_bundles
-Skip over any bundles listed in the @code{bundlesequence} constraint and continue
-without error.
-@item ignore_missing_inputs
-Skip over any input files listed in the @code{inputs} contraint and continue
-without error.
-@end table
-
-@end table
-
-
-@cartouche
-Be aware of the security implications of inheritance. Because of the assumption of
-authority, by promising to use the inheritance, you have subordinated your input
-to the source -- or voluntarily given up the right to say no to whatever you
-have subscribed to. You have implicity @i{trusted} them.
-@end cartouche
-
-
-@node Expressing is-a or has-a, How to organize your organization, Inheritance and its forms, Top
-@unnumberedsec Expressing `is a' or `has a'
-
-Let us re-emphasize for the record that CFEngine is not intended to be
-an object oriented system. At CFEngine we do not believe that Object
-Orientation is a good way to think about complex architectures.
-
-That said, all object-oriented class relationships are expressable as
-set relationships, as sets are the basis of all computing. We can therefore
-understand relationships like `is a' and `has a' in CFEngine, even if they
-are not the recommended way of thinking.
-
-For example, if we say that @code{debian} `is a' (kind of)
-@code{linux}, or conversely that @code{linux} `has a' (subtype called)
-@code{debian}, then we are expression @i{container} promises. We mean
-that @code{debian} is a subset of @code{linux}, and this means. In
-concrete terms @code{debian} might or might not extend @code{linux},
-or vice versa. When `objects' get as complicated as operating systems
-it does not really make sense to speak so simplistically.
-
-If we want to say that a host `is a' server, we can code this as membership
-in the set of servers:
-
-@verbatim
-classes:
-
- "servers" or => { "host1", "host2" };
-
-processes:
-
- servers:: # the next rules `extend' or add to the class servers
-
- "..."
-
-@end verbatim
-
-
-
-@node How to organize your organization, Applications of hierarchy, Expressing is-a or has-a, Top
-@unnumberedsec How to organize your organization
-
-Faced with the choice of how to classify systems, where does one
-begin? This is the dilemma that programmers face when designing new
-software, and if they make the wrong choices for their class
-hierarchy, it can cost a lot of work to redesign everything again from
-the beginning. This is why inheritance and strict class hierarchies
-are a very fragile way of organizing something. Using a patchwork of
-sets, CFEngine potentially avoids this problem -- but you can still
-make a mess -- it seems to be programmed into us to put systems into
-hierarchy-like `container' categories anyway, and this can end with
-confusion.
-
-The keyt issue is: how tdo we slice and dice the cake into the largest
-pieces? In other words, what is that basic paradigm that you use to partition your
-system operations? Some alternatives include:
-
-@itemize
-@item Geographically (by site or country)
-@item By business department (sales, accounting, research)
-@item By security zone (private, DMZ, public, etc)
-@item By operating system (solaris, linux, darwin)
-@item By customer or client (e.g. for managed services)
-@item By task, service or role in the network (webservers, dns, workstations)
-@end itemize
-
-However, you choose to begin, you can further subdivide these major categories
-by simply ANDing with other categories.
-
-
-
-@node Applications of hierarchy, , How to organize your organization, Top
-@unnumberedsec Applications of hierarchy
-
-When a small organization uses CFEngine, machines are often configured by
-"what they do" or "what they have" (@i{e.g.,} they "are a webserver" or they
-"have ntp-based time synchronization"). These attributes are best expressed
-using CFEngine classes (and class promises), so that the @code{.cf} files
-can simply express configuration options based on "has-a" or "is-a" options.
-
-
-For example:
-
-@verbatim
-bundle agent maintain_servers
-{
-classes:
- "has_dhcpd" or => { classmatch("ipv4_10_\d+_\d+_1") };
- "has_httpd" or => { "www_example_com" };
- "has_sshd" or => { "any" };
-
-processes:
- has_dhcpd::
- "dhcpd" restart_class => "start_dhcpd";
-
- has_httpd::
- "httpd" restart_class => "start_httpd";
-
- has_sshd::
- "sshd" restart_class => "start_sshd";
-
-commands:
- freebsd.start_dhcpd::
- "/usr/local/etc/rc.d/isc-dhcpd.sh start";
-
- start_httpd::
- "/usr/local/sbin/apachectl start";
-
- freebsd.start_sshd::
- "/etc/rc.d/sshd start";
-
- linux.start_sshd::
- "/etc/init.d/ssh start";
-}
-@end verbatim
-
-@noindent As you can see, the #1 machine on every net-10 subnet has the dhcp
-server for that subnet, the machine @code{www.example.com} has a web server,
-and every machine has an ssh server.
-
-But what happens when we want to maintain configuration information
-differently for different regions, or different IP addresses? Our usage of
-classes can get complicated, and can obscure the the details of what you want
-CFEngine to maintain. For example, if we want to maintain both internal and
-external webservers for different parts of a larger corporation, we might see
-something like this:
-
-@verbatim
-files:
- internal.has_httpd.nyc::
- # Files maintained for internal webserver in New York
-
- external.has_httpd.nyc::
- # Files maintained for external webserver in New York
-
- internal.has_httpd.london::
- # Files maintained for internal webserver in London
-
- external.has_httpd.london::
- # Files maintained for external webserver in London
-
- internal.has_httpd.tokyo::
- # Files maintained for internal webserver in Tokyo
-
- external.has_httpd.tokyo::
- # Files maintained for external webserver in Tokyo
-@end verbatim
-
-@noindent When you compound this by ading more services, locations, and finer
-and finer discriminations, the configuration files can rapidly grow so
-complicated as to obfuscate the intentions.
-
-To be sure, having classes like @code{nyc}, @code{london}, and @code{tokyo}
-can be very useful when using CFEngine to centrally administer a large
-network of computers, but there are other ways of doing this that make
-maintenance easier and the logic more apparent.
-
-1) Copying files to local machines
-2) Symlinks
-3) Local changes $(site_local)
-4) Machine naming -> classes
-5) Using dist classes to select from a set of machines, not just query them
- in order; also splayclass
-6) Versioning, RPM/SVN for distro, vs CFEngine
-7) updating with cf-agent -DUpdateNow
-
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_ITIL.texinfo b/docs/guides/SpecialTopic_ITIL.texinfo
deleted file mode 100644
index 96891bf396..0000000000
--- a/docs/guides/SpecialTopic_ITIL.texinfo
+++ /dev/null
@@ -1,1376 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-itil.info
-@settitle ITIL
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title CFEngine and ITIL
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-The IT Infrastructure Library (ITIL) is a set of human management practices
-surrounding IT infrastructure that are designed to bring quality assurance
-and continuous improvement to organizations.
-
-ITIL has emerged as a de-facto set of ideas about service management.
-Many of ITIL's ideas are rooted in and old fashioned view of the
-service desk and human remediation. This document explains how to
-accomplish the major goals of ITIL, in the automated framework of
-CFEngine.
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2009 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@node Top, What it ITIL?, (dir), (dir)
-@top ITIL
-@menu
-* What it ITIL?::
-* ITIL history and versions::
-* Basics::
-* Version 2::
-* Version 3::
-* Service orientation and ITIL::
-* CFEngine in ITIL clothes?::
-* ITIL processes::
-* Which ITIL processes apply to CFEngine?::
-* Using CFEngine to implement ITIL objectives::
-* How can CFEngine or promises help an enterprise::
-* What is maintenance?::
-* ITIL and CFEngine Summary::
-* ITIL glossary::
-@end menu
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@node What it ITIL?, ITIL history and versions, Top, Top
-@unnumberedsec What it ITIL?
-@sp 1
-
-The IT Infrastructure Library (ITIL) is a set of human management practices
-surrounding IT infrastructure that are designed to bring quality assurance
-and continuous improvement to organizations.
-ITIL has emerged as a de-facto set of ideas about service management.
-Many of ITIL's ideas are rooted in and legacy views of the service desk
-and human remediation. This document explains how to accomplish the
-major goals of ITIL, in the automated framework of CFEngine.
-
-More concretely, the IT Infrastructure Library (ITIL) is a collection
-of books, in which ``best practices'' for IT Service Management (ITSM)
-are described. Today, ITIL can be seen as a de-facto standard in the
-discipline of ITSM, for which it provides guidelines by its current
-core titles Service Strategy, Service Design, Service Transition,
-Service Operation and Continual Service Improvement. ITIL follows the
-principle of process-oriented management of IT services.
-
-In effect, the responsibilities for specific IT management decisions
-can be shared between different organizational units as the management
-processes span the entire IT organization independent from its
-organizational partition. Whether this means a centralization or
-decentralization of IT management in the end, depends on the concrete
-instances of ITIL processes in the respective scenario.
-
-
-@sp 1
-@node ITIL history and versions, Basics, What it ITIL?, Top
-@unnumberedsec ITIL history and versions
-@sp 1
-
-ITIL has its roots in the early 1990s, and since then was subject to
-numerous improvements and enhancements. Today, the most popular
-release of ITIL is given by the books of ITIL version 2 (often
-referred to as ITILv2), while the British OGC (Office of Government
-Commerce), owner and publisher of ITIL, is currently promoting ITIL
-version 3 (ITILv3) under the device "`ITIL Reloaded"'. A further ITIL
-version has already been planned, owing to perceived problems with
-version 3.
-
-ITILv3 is not just an improved version of the ITILv2 books, but rather
-comes with a completely renewed structure, new sets of processes and a
-different scope with respect to the issue of IT strategies,
-IT-business-alignment and continual improvement. In the following, we
-run through the basics of both versions, highlighting commonalities
-and differences.
-
-@sp 1
-@node Basics, Version 2, ITIL history and versions, Top
-@unnumberedsec Basics
-@sp 1
-
-ITIL is an attempt to implement the @i{Deming Quality Circle} as a
-model for continual quality improvement. Quality relates to the
-provided IT services as well as the management processes deployed to
-manage these services. Continual improvement in ITIL means to follow
-the method of Plan-Do-Check-Act:
-
-@table @b
-@item Plan
-Plan the provision of high-quality IT services, i.e. set up the required management processes for the delivery and support of these services, define measurable goals and the course of action in order to fulfill them.
-@item Do
- Put the plans into action.
-@item Check
- Measure all relevant performance indicators, and quantify the achieved quality compared to the quality objectives. Check for potentials of improvement.
-@item Act
- In response to the measured quality, start activities for future improvements. This step leads into the Plan phase again.
-@end table
-
-@sp 1
-@node Version 2, Version 3, Basics, Top
-@unnumberedsec Version 2
-@sp 1
-
-Although ITIL version 3 was released during the summer of 2007,
-it is its predecessor that has achieved great acceptance amongst
-IT service providers all over the world. Also due to the fact that the
-International ISO/IEC 20000 standard emerged from those
-basic principles and processes coming from ITILv2, it is this version
-experiencing the biggest distribution and popularity.
-
-The core modules of ITIL version 2 are the books entitled Service
-Support and Service Delivery. While the Service Support processes
-(e.g. Incident Management, Change Management) aim at supporting
-day-to-day IT service operation, the Service Delivery processes
-(e.g. Service Level Management, Capacity Management, Financial
-Management) are supposed to cover IT service planning like resource
-and quality planning, as well as strategies for customer relationships
-or dealing with unpredictable situations.
-
-@sp 1
-@node Version 3, Service orientation and ITIL, Version 2, Top
-@unnumberedsec Version 3
-@sp 1
-
-In 2007, version 2 was replaced by its successor version 3, aimed at
-covering the entire service life cycle from a management
-perspective and striving for a more substantiated idea of IT business alignment.
-Many version 2 processes and ideas have been recycled
-and extended by various additional processes and principles. The five
-service life cycle stages accordant to versin 3 are:
-
-@enumerate
-@item Service Strategy: Common strategies and principles for customer-oriented, business-driven service delivery and management
-@item Service Design: Principles and processes for the stage of designing new or changed IT services
-@item Service Transition: Principles and processes to ensure quality-oriented implementation of new or changed services into the operational environment
-@item Service Operation: Principles and processes for supporting service operation
-@item Continual Service Improvement: Methods for planning and achieving service improvements at regular intervals
-@end enumerate
-
-@sp 1
-@node Service orientation and ITIL, CFEngine in ITIL clothes?, Version 3, Top
-@unnumberedsec Service orientation and ITIL
-
-Why service and process orientation? What is ITIL trying to do? As we
-mentioned in the introduction, the `top down hierarchical' control
-view of human organization fell from favour in business research in
-the 1980s and service oriented autonomy was identified as a new
-paradigm for levelling organizations -- getting rid of deep
-hierarchies that hinder communication and open up communication
-directly.
-
-If we look at ITIL through the eyeglass of a hierarchical organization,
-some of its procedures could be seen as restrictive, throttling
-scalable freedoms. We do not believe
-that this is their intention. Rather ITIL's guidelines try to make a
-predictable and reliable face for business and IT operations so that
-customers feel confidence, without choking the creative process that
-lies behind the design of new services.
-
-@sp 1
-@node CFEngine in ITIL clothes?, ITIL processes, Service orientation and ITIL, Top
-@unnumberedsec CFEngine in ITIL clothes?
-@sp 1
-
-CFEngine users are interested in the ability to manage, i.e. cope with
-system configuration in a way that enables a business or other
-organization to do its work effectively. They don't want
-human procedures because this is what CFEngine is supposed to
-eliminate. To be able to use ITIL to help in this task, we have to first
-think of the process of setting up as a number of services. What
-services are these? We have to think a little sideways to see the
-relationship.
-
-@table @b
-@item Service Management
-Providing a sensible configuration policy, responding to discovered problems or the needs of end-users.
-@item Change Management
-A minor edit of the configuration policy, with appropriate quality controls. Or a change that comes
-from a completely different source, outside the scope of intended change.
-@item Release Management
-A new configuration policy, consisting of many changes. This could be a major and disruptive change so it should be planned carefully.
-@item Capacity Management
-Having enough resources for cfservd to answer all queries in a network. Having enough people and machines to support the processes of deploying and following CFEngine's progress.
-@end table
-
-@sp 1
-@node ITIL processes, Which ITIL processes apply to CFEngine?, CFEngine in ITIL clothes?, Top
-@unnumberedsec ITIL processes
-@sp 1
-
-The following management processes are in scope of ITILv3:
-
-@itemize
-@item Service Level Management: Management of Service Level Agreements (Alas), i.e. service level and quality promises.
-@item Service Catalogue Management: deciding on the services that will be provided and how they
-are advertised to users.
-@item Capacity Management: Planning and provision of adequate business, service and resource capacities.
-@item Availability Management: Resource provision and monitoring of service, from a customer viewpoint.
-@item Continuity Management: Development of strategies for dealing with potential disasters.
-@item Information Security Management: Ensuring a minimum level of information security throughout the IT organization.
-@item Supplier Management: Maintaining supplier relationships.
-@item Transition Planning and Support: Ensuring that new or changed services are deployed into the operational environment with the minimal impact on existing services
-@item Asset and Configuration Management: Management of IT assets and Configuration Items.
-@item Release Management: Planning, building, testing and rolling out hardware and software configurations.
-@item Change Management: Assessment of current state, authorization and scheduling of improvements.
-@item Service Validation and Testing: ensuring that services meet their specifications.
-@item Knowledge Management: organizing and integrating experience and methodology for future reference.
-@item Incident Management: responding to deviations from acceptable service.
-@item Event Management: Efficient handling of service requests and complaints.
-@item Problem Management: Problem identification by trend analysis of incidents.
-@item Request Fulfillment: Fulfilling customer service requests.
-@item Access Management: Management of access rights to information, services and resources.
-@end itemize
-
-@menu
-* Service Strategy::
-* Service Design::
-* Service Operation::
-* Continual Service Improvement::
-@end menu
-
-@node Service Strategy, Service Design, ITIL processes, ITIL processes
-@unnumberedsubsec Service Strategy
-
-Service strategy is about deciding what services you want to
-formalize. In other words, what parts of your system administration tasks can you
-wrap in procedural formalities to ensure that they are carried out most excellently?
-
-@node Service Design, Service Operation, Service Strategy, ITIL processes
-@unnumberedsubsec Service Design
-
-Service design is about deciding what will be delivered, when it will be delivered,
-how quickly the service will respond to the needs of its clients etc. This stage is probably
-something of a mental barrier to those who are not used to service-oriented thinking.
-
-@node Service Operation, Continual Service Improvement, Service Design, ITIL processes
-@unnumberedsubsec Service Operation
-
-How shall we support service operation? What resources do we need to provide, both human
-and computer? Can we be certain of having these resources at all times, or is there
-resource sharing taking place? If services are chained into ``supply chains'', remember that
-each link of the chain is a possible delay, and a possible misunderstanding. Successfully running
-services can be more complex at task than we expect, and this is why it is useful to
-formalize them in an ITIL fashion.
-
-@node Continual Service Improvement, , Service Operation, ITIL processes
-@unnumberedsubsec Continual Service Improvement
-
-Continual improvement is quite self-explanatory. We are obviously
-interested in learning from our mistakes and improving the quality and
-efficiency by which we respond to service requests. But it is
-necessary to think carefully about when and where to introduce this
-aspect of management. How often should we revise out plans and change
-procedures? If this is too often, the overhead of managing the quality
-becomes one of the main barriers to quality itself! Continual has to mean regular
-on a time-scale that is representative for the service being provided, e.g.
-reviews once per week, once per month? No one can tell you about your needs.
-You have to decide this from local needs.
-
-@sp 1
-@unnumberedsec Tool Support
-@sp 1
-
-In the field of tool support for IT Service Management accordant to
-ITIL, various white papers and studies have been published. In
-addition, there are papers available from BMC, HP, IBM and other
-vendors that describe specific (commercial) solutions. Generally, the
-market for tools is growing rapidly, since ITIL increasingly gains
-attention especially in large and medium-size enterprises. Today, it
-is already hard to keep track of the variety of functionalities
-different tools provide. This makes it even more difficult to approach
-this topic in a way satisfactory to the entire researchers', vendors'
-and practitioners' community.
-
-That is why this document follows a different approach: Instead of thinking
-of ever new tools and computer-aided solutions for ITIL-compliant IT Service
-Management, this book analyses how the existing and well-established
-technologies used for traditional systems administration can
-fit into an ITIL-driven IT management environment, and it guides
-potential practitioners in integrating a respective tool suite -- namely
-CFEngine -- with ITIL and its processes.
-
-To avoid any misunderstanding: We do not argue that CFEngine --
-originally invented for configuring distributed hosts -- may be
-deployed as a comprehensive solution for automating ITIL, but what we
-believe is CFEngine and its more recent innovations can @emph{bridge
-the gap} between the technology of distributed systems management and
-business-driven IT Service Management.
-To make the case we must show:
-
-@enumerate
-@item How ITIL terminology relates to the terminology of CFEngine and hence
-to a traditional system administrator's language, and
-@item Which parts (processes and activities) of
-ITIL can be (partially) supported by CFEngine, and how.
-@end enumerate
-
-
-
-@sp 1
-@node Which ITIL processes apply to CFEngine?, Using CFEngine to implement ITIL objectives, ITIL processes, Top
-@unnumberedsec Which ITIL processes apply to CFEngine?
-@sp 1
-
-@image{itilfcaps,14cm,,FCAPS and ITIL,png}
-
-In version 2, ITIL divides itself into @emph{service
-support} and @emph{service delivery}. For
-instance, service support might mean having a number of CFEngine
-experts who can diagnose problems, or who have sufficient knowledge
-about CFEngine to solve problems using the software. It could also
-mean having appropriate tools and mechanisms in place to carry out the
-tasks. Service delivery is about how these people make their knowledge
-available through formal processes, how available are they and how
-much work can they cope with? CFEngine enables a few persons to
-perform a lot of work very cheaply, but we should not forget to track our performance
-and quality for the process of continual improvement.
-
-Service support is composed of a number of issues:
-@itemize
-@item Incident management: collecting and dealing with incidents.
-@item Problem management: root cause analysis and designing long term countermeasures.
-@item Configuration management: maintaining information about hardware and software and
-their interrelationships.
-@item Change management: implementing major sequenced changes in the infrastructure.
-@item Release management: planning and implementing major ``product'' changes.
-@end itemize
-Although the difference between change management and release
-management is not completely clear in ITIL, we can think of a release
-as a change in the nature of the service, while change management
-deals with alterations possibly still within the scope of the same release.
-Thus is release is a more major change.
-
-Service delivery, on the other hand, is dissected as follows:
-@itemize
-@item Service Level Management
-@item Problem management
-@item Configuration management
-@item Change management
-@item Release management
-@end itemize
-These issues are somewhat clearer once we understand the usage of the
-terms ``problem'', ``service'' and ``configuration''. Once again, it
-is important that we don't mix up configuration management in ITIL
-with configuration management as used in a Unix parlance.
-
-The notion of system administration in the sense of Unix does not
-exist in ITIL. In the world of business, reinvented through the eyes
-of ITIL's mentors, system administration and all its functions are
-wrapped in a model of service provision.
-
-@menu
-* ITIL Configuration Management (CM)::
-* CMDB Asset Management::
-* Change management in the enterprise::
-* Change management vs convergence::
-* Release management::
-* Incident and problem management::
-* Service Level Management (SLM)::
-@end menu
-
-@node ITIL Configuration Management (CM), CMDB Asset Management, Which ITIL processes apply to CFEngine?, Which ITIL processes apply to CFEngine?
-@unnumberedsubsec ITIL Configuration Management (CM)
-@sp 1
-
-Perhaps the most obvious example is the term configuration management.
-
-@table @b
-@item Configuration Management
-The process (and life-cycle) responsible for maintaining information
-about configuration items (CI) required to deliver an IT service,
-including their relationships.
-@end table
-
-As we see, this is comparable to our intuitive idea of ``asset
-management'', but with ``relationships'' between the items
-included. ITIL also defines ``Asset Management'' as ``a process
-responsible for tracking and reporting the value of financially valuable assets''
-and is a component of ITIL Configuration Management.
-
-In the CFEngine world, configuration management involves planning,
-deciding, implementing (``base-lining'') and verifying (``auditing'')
-the inventory. It also involves maintaining the security and privacy
-of the data, so that only authorized changes can be made and private
-assets are not made public.
-
-In this document we shall try not to mix the ITIL concept with the
-more prosaic system administration notion of a configuration which
-includes the current state of software configuration on the
-individual computers and routers in a network.
-
-Since CFEngine is a completely distributed system that deals with
-individual devices on a one-by-one basis, we must interpret this asset
-management at two levels:
-
-@itemize
-@item The local assets of an individual device at the level of virtual
-structures and containers within it: files, attributes, software packages,
-virtual machines, processes etc. This is the traditional domain of automation
-for CFEngine's autonomic agent.
-
-@item The collective assets of a network of such devices.
-@end itemize
-Since a single host can be thought of as a network of assets connected
-through virtual pathways, it really isn't such a huge leap to see the
-whole network in a similar light. This is especially true when many of the
-basic resources are already shared objects, such as shared storage.
-
-@node CMDB Asset Management, Change management in the enterprise, ITIL Configuration Management (CM), Which ITIL processes apply to CFEngine?
-@unnumberedsubsec CMDB Asset Management
-@sp 1
-
-Why bother to collect an inventory of this kind? Is it bureaucracy
-gone mad, or do we need it for insurance purposes? Both of these
-things are of course possibilities.
-
-The data in an ITIL Configuration Management Database (CMDB) can be
-used for planning the future and for knowing how to respond to
-incidents, in other words for service level management (SLM) and for
-capacity planning. An organization needs to know what resources it
-has to know whether its can deliver on its promises.
-Moreover, for finance and insurance it is clearly a sound policy to have a database of
-assets.
-
-For continuity management, risk analysis and redundancy assessment we
-need to know how much equipment is in use and how much can be brought
-in at a moment's notice to solve a business problem. These are a few
-of the reasons why we need to keep track of assets.
-
-@sp 1
-@cartouche
-CFEngine does not subscribe the the ITIL notion of a CMDB. Instead
-we have a semantic Knowledge Map and distributed knowledge for
-scalable analysis of the system.
-@end cartouche
-
-@node Change management in the enterprise, Change management vs convergence, CMDB Asset Management, Which ITIL processes apply to CFEngine?
-@unnumberedsubsec Change management in the enterprise
-@sp 1
-
-If we make changes to a technical installation, or even a business
-process, this can affect the service that customers experience.
-Major changes to service delivery are often written into service level
-agreements since they could result in major disruptions.
-Details of changes need to be known by a help-desk and service personnel.
-
-The decision to make a change is more than a single person should
-usually make alone (see the CFEngine Special Topics Guide on @i{Change
-Management}). ITIL recommends an advisory board for changes.
-
-@node Change management vs convergence, Release management, Change management in the enterprise, Which ITIL processes apply to CFEngine?
-@unnumberedsubsec Change management vs convergence
-@sp 1
-
-We should be especially careful here to decide what we mean by
-change. ITIL assumes a traditional model of change management that
-CFEngine does not necessarily need. ITIL's ideas apply to the management of
-CFEngine's configuration, not specifically to the way in which CFEngine carries out its
-automated manipulations of the system.
-
-In traditional idea of change management you start by ``base-lining'' a
-system, or establishing a known starting configuration. Then you
-assume that things only change when you actively implement a change,
-such as ``rolling out a new version'' or committing a release. This,
-of course, is very optimistic.
-
-In most cases all kinds of things change beyond our control. Items are
-stolen, things get broken by accident and external circumstances
-conspire to confound the order we would like to preserve. The idea
-that only authorized people make changes is nonsense.
-
-CFEngine takes a different view. It thinks that changes in
-circumstances are part of the picture, as well as changes in inventory
-and releases. It deals with the idea of ``convergence''. In this way
-of thinking, the configuration details might be changing at random in
-a quite unpredictable way, and it is our job to continuously monitor
-and repair general dilapidation. Rather than assuming a constant state
-in between changes, CFEngine assumes a constant ``ideal state'' or
-@emph{goal} to be achieved between changes. An important thing to realize about including
-changes of external circumstances is that you cannot ``roll back''
-circumstances to an earlier state -- they are beyond our control.
-
-@node Release management, Incident and problem management, Change management vs convergence, Which ITIL processes apply to CFEngine?
-@unnumberedsubsec Release management
-@sp 1
-
-A @emph{release} in ITIL is a collection of authorized changes to a system.
-One part of Change Management is therefore @emph{Release Management}.
-A release is generally a larger umbrella under which many smaller
-changes are made. It is major change.
-Changes are assembled into @emph{releases} and then they are rolled out.
-
-In fact release management, as described by ITIL, has nothing to do
-with change management. It is rather about the management of
-designing, testing and scheduling the release, i.e. everything to do with
-the release process except the explicit implementation of it.
-@emph{Deployment} or @emph{rollout} describe the physical movement of
-configuration items as part of a release process.
-
-@node Incident and problem management, Service Level Management (SLM), Release management, Which ITIL processes apply to CFEngine?
-@unnumberedsubsec Incident and problem management
-@sp 1
-ITIL distinguishes between @emph{incidents} and @emph{problems}. An incident is
-an event that might be problematic, but in general would observe
-incidents over some length of time and then diagnose @emph{problems} based
-on this experience.
-
-@table @i
-@item Incident
-An event or occurrence that demands a response.
-@end table
-
-One goal of CFEngine is to plan pro-actively to handle incidents
-automatically, thus taking them off the list of things to worry about.
-
-@table @i
-@item Problem
-A pattern of consequence arising from certain incidents that is detrimental
-to the system. It is often a negative trend that needs to be addressed.
-@end table
-
-
-Changes can introduce new incidents.
-An integrated way to make the tracking of cause and effect easier is
-clearly helpful. If we are the cause of our own problems, we are in
-trouble!
-
-@node Service Level Management (SLM), , Incident and problem management, Which ITIL processes apply to CFEngine?
-@unnumberedsubsec Service Level Management (SLM)
-@sp 1
-Also loosely referred to as Quality of Service. This is the
-process of making sure that Service Level Promises are kept,
-or Service Level Agreements (SLA) are adhered to.
-We must assess the impact of changes on the ability to deliver
-on promises.
-
-
-@node Using CFEngine to implement ITIL objectives, How can CFEngine or promises help an enterprise, Which ITIL processes apply to CFEngine?, Top
-@unnumberedsec Using CFEngine to implement ITIL objectives
-@sp 1
-
-How does CFEngine fit into the management of a service organization?
-There are several ways:
-@itemize
-@item It offers a rapid detection and repair of faults that help to avoid formal incidents.
-@item It simplifies the deployment (release) of services.
-@item Allows resources to be understood and planned better.
-@end itemize
-These properties allow for greater @emph{predictability}
-of system services and therefore they contribute to customer confidence.
-
-
-Any tool for assisting with change management lies somewhere between
-ITIL's notion of change management and the infrastructure itself. It
-must essentially be part of both (see figure). This applies
-to CFEngine too.
-
-
-@image{cfinf,14cm,,CFEngine is both infrastructure and a part responsible for infrastructure.,png}
-
-CFEngine can manage itself as well as other resources: itself, its
-software, its policy and the resulting plans for the configuration of
-the system. In other words, CFEngine is itself part of the infrastructure
-that we might change.
-
-@node How can CFEngine or promises help an enterprise, What is maintenance?, Using CFEngine to implement ITIL objectives, Top
-@unnumberedsec How can CFEngine or promises help an enterprise
-@sp 1
-
-Traditional methods of managing IT infrastructure involve working from
-crisis to crisis -- waiting for `incidents' to occur and then initiating fire
-suppression responses or, if there is time, proactive changes. With CFEngine,
-these can be combined and made into a management @emph{service}, with
-continuous service quality.
-
-CFEngine can assist with:
-@enumerate
-@item Maintenance assurance.
-@item Reporting for auditing.
-@item Change management.
-@item Security verification.
-@end enumerate
-
-Promise theory comes with a couple of principles:
-@enumerate
-@item Separation of concerns.
-@item Fundamental attention to autonomy of parts.
-@end enumerate
-
-Other approaches to discussing organization talk about the separation
-of concerns, so why is promise theory special? Object Orientation
-(OO) is an obvious example. Promise theory is in fact quite different to
-object orientation (which is a misnomer).
-
-Object orientation asks users to model abstract classes (roles) long
-before actual objects with these properties exist. It does not provide
-a way to model the instantiated objects that later belong to those
-classes. It is mainly a form of information structure
-modelling. Object orientation models only abstract patterns, not
-concrete organizations.
-
-Promise theory on the other hand considers only actual existing objects
-(which it calls agents) and makes no presumptions that any
-two of these will be similar. Any patterns that might emerge can be
-exploited, but they are not imposed at the outset. Promise theory's
-insistence on autonomy of agents is an extreme viewpoint from which
-any other can be built (just as atoms are a basic building block from which
-any substance can be built) so there is no loss of generality by making
-this assumption.
-
-In other words, OO is a design methodology with a philosophy, whereas
-promises are a model for an arbitrary existing system.
-
-@node What is maintenance?, ITIL and CFEngine Summary, How can CFEngine or promises help an enterprise, Top
-@unnumberedsec What is maintenance?
-@sp 1
-
-Maintenance is a process that ITIL does not formally spend any time
-on explicitly, but it is central to real-world quality control.
-
-Imagine that you decide to paint your house. Release 1 is going to be
-white and it is going to last for 6 years. Then release 2 is going to
-be pink. We manage our painting service and produce release
-1 with all of the care and quality we expect. Job done? No.
-
-It would be wrong for us to assume that the house will stay this fine
-colour for 6 years. Wind, rain and sunshine will spoil the paint over
-time and we shall need to touch up and even repaint certain areas in
-white to maintain release 1 for the full six years. Then when it is time
-for release 2, the same kind of maintenance will be required for that too.
-
-Unless we read between the lines, it would seem that ITIL's answer to
-this is to wait for a crisis to take place (an incident). We then
-mobilize some kind of response team. But how serious an incident do we
-require and what kind of incident response is required? A graffiti artist?
-A lightening strike? A bird anoints the paint-work? CFEngine is
-like the gardener who patrols the grounds constantly plucking weeds,
-before the flower beds are overrun. Call it continual improvement if
-you like: the important thing is that the process your be pro-active
-and not too expensive.
-
-Maintenance is necessary because we do not control all of the
-changes that take place in a system. There is always some kind of
-``weather'' that we have to work against. CFEngine is about this
-process of Maintenance. We call it ``convergence'' to the ideal state,
-where the ideal state is the specified version release.
-Keep this in mind as you read about ITIL change management.
-
-
-@node ITIL and CFEngine Summary, , What is maintenance?, Top
-@unnumberedsec ITIL and CFEngine Summary
-@sp 1
-
-ITIL is about processes designed mainly for humans in a workplace. It
-represents a service oriented view of an organization, and as such is
-more scalable than hierarchical views of management. CFEngine is also
-a service oriented technology, thus there is some overlap of concepts.
-Indeed CFEngine is a good tool for implementing and assisting in
-certain ITIL processes, but we believe that no automation system can
-really support what ITIL is about.
-
-@image{topic,15cm,,ITIL terminology,png}
-
-@node ITIL glossary, , Top, Top
-@appendix ITIL glossary
-
-This section lists some of the many terms from ITIL, especially the ISO/IEC 20000
-version of the text, and offers some comments and translations into common CFEngine
-terminology.
-
-@menu
-* Active Monitoring::
-* Availability::
-* Alert::
-* Audit ::
-* Baseline::
-* Benchmark ::
-* Capability::
-* Change record::
-* Chronological Analysis::
-* Configuration::
-* Configuration Item (CI)::
-* Configuration Management Database (CMDB)::
-* Document::
-* Emergency Change::
-* Error::
-* Event::
-* Exception::
-* Failure::
-* Incident::
-* Monitoring::
-* Passive Monitoring::
-* Policy::
-* Proactive Monitoring::
-* Problem::
-* Promise::
-* Reactive Monitoring::
-* Record::
-* Recovery::
-* Remediation::
-* Repair::
-* Release::
-* Request for Change::
-* Abandon Autonomy?::
-* Resilience::
-* Restoration::
-* Role::
-* Service desk::
-* Service Level Agreement::
-* Service Management::
-* Warning::
-@end menu
-
-@node Active Monitoring, Availability, ITIL glossary, ITIL glossary
-@unnumberedsec Active Monitoring
-
-Monitoring of a configuration item or IT service that uses automated regular checks to discover the current status.
-
-@cartouche
-CFEngine performs programmed checks of all of its promises each time cfagent is started.
-Cfagent is, in a sense, an active monitor for a set of promises that are described in its
-configuration file.
-@end cartouche
-
-@node Availability, Alert, Active Monitoring, ITIL glossary
-@unnumberedsec Availability
-
-The ability of a component or service to perform its required function.
-
-Availability = Hours operational / Agreed service hours
-
-
-@cartouche
-Availability or intermittency in CFEngine refers to the responsiveness of
-hosts in a network when remotely connecting to cfservd.
-
-Intermittency = Successful~ attempts / Total Attempts
-
-@end cartouche
-This is a measurement that cfagent automatically makes.
-
-@node Alert, Audit , Availability, ITIL glossary
-@unnumberedsec Alert
-
-A warning that a threshold has been reached, something has changed or a failure has occurred.
-
-
-@cartouche
-A CFEngine alert fits this description quite well.
-Most alerts are user-defined, but a few are side effects of certain configuration
-rules.
-@end cartouche
-
-@node Audit , Baseline, Alert, ITIL glossary
-@unnumberedsec Audit
-
-
-A formal inspection and verification to check whether a standard or
-set of guidelines is being followed.
-
-
-
-
-@cartouche
-CFEngine's notion of an audit is more like the notion from system
-accounting. However, the data generated by this extra logging
-information could be collected and used in a more detailed examination
-of CFEngine's operations, suitable for use in a formal inspection
-(e.g. for compliance).
-@end cartouche
-
-
-@node Baseline, Benchmark , Audit , ITIL glossary
-@unnumberedsec Baseline
-
-
-A snapshot of the state of a service or an individual configuration
-item at a point in time
-
-
-@cartouche
-In CFEngine parlance, we refer to this as an initial state or
-configuration. In principle a CFEngine initial state does not have to
-be a known-base line, since the changes we make will not generally be
-relative to an existing configuration. CFEngine encourages users to
-define the final state (regardless of initial state).
-@end cartouche
-
-
-@node Benchmark , Capability, Baseline, ITIL glossary
-@unnumberedsec Benchmark
-
-The recorded state of something at a specific point in time.
-
-
-@cartouche
-CFEngine does not use this term in any of its documentation, though
-our general understanding of a ``benchmark'' is that of a standardized
-performance measurement under special conditions. CFEngine regularly
-records state and performance data in a variety of ways, for example
-when making file copies.
-@end cartouche
-
-@node Capability, Change record, Benchmark , ITIL glossary
-@unnumberedsec Capability
-
-The ability of someone or something to carry out an activity.
-
-
-@cartouche
-CFEngine does not use this concept specifically. The notion of a capability
-is terminology used in role-based access control.
-@end cartouche
-
-@node Change record, Chronological Analysis, Capability, ITIL glossary
-@unnumberedsec Change record
-
-A record containing details of which configuration items are affected
-and how they are affected by an authorized change.
-
-
-
-@cartouche
-CFEngine's default modus operandi is to @emph{not} record changes made
-to a system unless requested by the user. Changes can be written as
-log entries or audit entries by switching on reporting.@end cartouche
-
-An ``inform'' promise means that cf-agent promises to notify the
-changes to its standard output (which is usually sent by email or
-printed on a console output). A ``syslog'' promise implies that
-cfagent will log the message to the system log daemon. Both of the
-foregoing messages give only a simple message of actual changes. An
-``audit'' promise is a promise to record extensive details about the
-process that cfagent undergoes in its checking of other promises.
-
-
-@node Chronological Analysis, Configuration, Change record, ITIL glossary
-@unnumberedsec Chronological Analysis
-
-An analysis based on the timeline of recorded events (used to help identify possible causes of problems).
-
-
-
-@cartouche
-A timeline analysis could easily be carried out based on audit
-information, system logs and cfenvd behavioural records.
-@end cartouche
-
-@node Configuration, Configuration Item (CI), Chronological Analysis, ITIL glossary
-@unnumberedsec Configuration
-
-A group of configuration items (CI) that work together to deliver an IT service.
-
-@cartouche
-A configuration is the current state of resources on a system. This is, in
-principle, different from the state we would like to achieve, or what has
-been promised.
-@end cartouche
-
-@node Configuration Item (CI), Configuration Management Database (CMDB), Configuration, ITIL glossary
-@unnumberedsec Configuration Item (CI)
-
-A component of an infrastructure which is or will be under the control
-of configuration management.
-
-
-@cartouche
-A configuration item is any object making a promise
-in CFEngine. We often speak of the promise object, or ``promiser''.@end cartouche
-
-@node Configuration Management Database (CMDB), Document, Configuration Item (CI), ITIL glossary
-@unnumberedsec Configuration Management Database (CMDB)
-
-Database containing all the relevant details of each configuration
-item and details of the important relationships between them.
-
-
-@cartouche
-
-CFEngine has no asset database except for its own list of
-promises. The only relationships is cares about are those which are
-explicitly coded as promises. In the future, CFEngine 3 is likely
-to extend the notion of promises to allow more general records of the
-CMDB kind, but only to the extent that they can be verified autonomically.
-@end cartouche
-
-@node Document, Emergency Change, Configuration Management Database (CMDB), ITIL glossary
-@unnumberedsec Document
-
-Information and its supporting medium.
-
-
-
-@cartouche
-ITIL originally considered a document to be only a container for
-information. In version 3 it considers also the medium on which
-the data are recorded, i.e. both the file and the filesystem on which it resides.@end cartouche
-
-@node Emergency Change, Error, Document, ITIL glossary
-@unnumberedsec Emergency Change
-
-A change that must be introduced as soon as possible -- for example to
-solve a major incident or to implement a critical security patch.
-
-
-
-@cartouche
-CFEngine has no specific concept for this.
-@end cartouche
-
-@node Error, Event, Emergency Change, ITIL glossary
-@unnumberedsec Error
-
-A design flaw or malfunction that causes a failure.
-
-
-
-@cartouche
-CFEngine often uses the term configuration error to mean a deviation of
-a configuration from its promised state. The ITIL meaning of the term would
-translated into ``bug in the CFEngine software'' or ``bug in the
-promised configuration''.
-@end cartouche
-
-
-@node Event, Exception, Error, ITIL glossary
-@unnumberedsec Event
-
-A change of state that has significance for the management of a
-configuration item or IT service.
-
-
-
-@cartouche
-The same basic definition applies to CFEngine also, but CFEngine makes
-all such events into @emph{classes}, since its approach to observing
-the environment is to measure and then classify it into approximate
-expected states. CFEngine class attributes (usually from cfenvd) may
-be considered as event notifications as they change.
-@end cartouche
-
-@node Exception, Failure, Event, ITIL glossary
-@unnumberedsec Exception, Failure, Event, Summary
-
-An @b{event} that is generated when a service or device is currently operating abnormally.
-
-
-
-@cartouche
-A state in which configuration policy is violated (could lead to a
-warning or an automated correction).
-@end cartouche
-
-
-@node Failure, Incident, Exception, ITIL glossary
-@unnumberedsec Failure
-
-Loss of ability to operate to specification or to deliver the required output.
-
-
-
-@cartouche
-ITIL's idea of a failure is something that prevents a promise from being kept.
-CFEngine's autonomy model means that it is unlikely for such a failure
-to occur, since promises are only allowed to be made about resources for which
-we have all privileges. Occasionally, environmental issues might interfere and
-lead to failure.
-@end cartouche
-
-@node Incident, Monitoring, Failure, ITIL glossary
-@unnumberedsec Incident
-
-Any event that is not expected in normal operations and which might
-cause a degradation of service quality.
-
-
-
-@cartouche
-CFEngine's philosophy of convergence gives us only one option for
-interpreting this term, namely as a temporary deviation from promised
-behaviour. A deviation must be temporary if CFEngine is operating
-continually, since it will repair any problem on its next invocation
-round. Events which do not impact promises made by CFEngine are of no
-interest to CFEngine, since autonomy means it cannot be responsible
-for anything beyond its own promises.
-@end cartouche
-
-@node Monitoring, Passive Monitoring, Incident, ITIL glossary
-@unnumberedsec Monitoring
-
-Repeated observation of a configuration item, IT service or process in
-order to detect events and ensure that the current status is known.
-
-
-
-@cartouche
-CFEngine incorporates a number of different kinds of monitoring, including monitoring of kept
-configuration-promises and passive monitoring of behaviour.
-@end cartouche
-
-@node Passive Monitoring, Policy, Monitoring, ITIL glossary
-@unnumberedsec Passive Monitoring
-
-Monitoring of a configuration item or IT service that relies on an alert or notification to discover the current status.
-
-
-
-@cartouche
-Cfenvd is CFEngine's passive monitoring component. It observes system
-related behaviour and learns about it. It assumes that there is likely
-to be a weekly periodicity in the data in order to best handle its
-statistical inference.
-@end cartouche
-
-@node Policy, Proactive Monitoring, Passive Monitoring, ITIL glossary
-@unnumberedsec Policy
-
-Formally documented management expectations and intentions. Policies
-are used to direct decisions, and to ensure consistent and appropriate
-development and implementation of processes, standards, roles,
-activities, IT infrastructures, etc.
-
-
-@cartouche
-CFEngine's configuration policy is an automatable set of promises
-about the static and runtime state of a computer. Roles are identified
-by the kinds of behaviour exhibited by resources in a network. We say
-that a number of resources (hosts or smaller configuration objects)
-play a specific promised role if they make identical promises. Any resource can
-play a number of roles. Decisions in CFEngine are made entirely on the basis
-of the result of monitoring a host environment.
-@end cartouche
-
-@node Proactive Monitoring, Problem, Policy, ITIL glossary
-@unnumberedsec Proactive Monitoring, Problem, Policy, Summary
-
-Monitoring that looks for patterns of events to predict possible future failures.
-
-
-
-@cartouche
-All CFEngine monitoring is pro-active in the sense that it can lead to automated follow-up actions.
-@end cartouche
-
-@node Problem, Promise, Proactive Monitoring, ITIL glossary
-@unnumberedsec Problem
-
-Unknown underlying cause of one or more incidents.
-
-
-
-@cartouche
-A repeated deviation from policy that suggests a change of policy or
-specific counter-measures. A promise needs to be reconsidered or new promises
-are required.
-@end cartouche
-
-@node Promise, Reactive Monitoring, Problem, ITIL glossary
-@unnumberedsec Promise, Reactive Monitoring, Problem, Summary
-
-ITIL does not define this term, although promises are deployed in
-various ways -- for instance in terms of cooperation, communication
-interfaces within or between processes or contractual relationships as
-defined by Service Level Agreements, Operational Level Agreements and
-Underpinning Contracts.
-
-
-
-@cartouche
-A promise in CFEngine is a single rule in the CFEngine language. The promiser is the resource
-whose properties are described, and the promisee is implicitly the CFEngine monitor.
-@end cartouche
-
-@node Reactive Monitoring, Record, Promise, ITIL glossary
-@unnumberedsec Reactive Monitoring
-
-Monitoring that takes action in response to an event -- for example
-submitting a batch job when the previous job completes, or logging an
-incident when an error occurs.
-
-
-
-@cartouche
-The concept of reactive monitoring is unclear because the duration of an event and the speed of
-a response are undefined. In a sense, all CFEngine monitoring is potentially reactive. It is possible
-to attach actions which keep promises to any observable condition discernable by CFEngine's monitor.
-CFEngine is not usually considered event driven however, since it does not react ``as soon as possible''
-but at programmed intervals.
-@end cartouche
-
-@node Record, Recovery, Reactive Monitoring, ITIL glossary
-@unnumberedsec Record
-
-Information in readable form that is maintained by the service provider about operations.
-
-
-
-@cartouche
-A log entry or database item.
-@end cartouche
-
-@node Recovery, Remediation, Record, ITIL glossary
-@unnumberedsec Recovery
-
-Returning a Configuration Item or an IT service to a working
-state. Recovering of an IT service often includes recovering data to a
-known consistent state.
-
-
-
-@cartouche
-All CFEngine promises refer to the state of a system that is desired. The promises are
-automatically enforced, hence CFEngine recovers a system (in principle) on every invocation.
-CFEngine always returns to a known state, due to the property of ``convergence''. There is no
-distinction between the concepts of repair, recovery or remediation.
-@end cartouche
-
-@node Remediation, Repair, Recovery, ITIL glossary
-@unnumberedsec Remediation
-
-Recovery to a known state after a failed change or release.
-
-
-
-@cartouche
-All CFEngine promises refer to the state of a system that is desired. The promises are
-automatically enforced, hence CFEngine recovers a system (in principle) on every invocation.
-CFEngine always returns to a known state, due to the property of ``convergence''. There is no
-distinction between the concepts of repair, recovery or remediation.
-
-However, this concept is like the notion of ``rollback'' which often involves a more
-significant restoration of a system from backup. This is discussed later.
-@end cartouche
-
-@node Repair, Release, Remediation, ITIL glossary
-@unnumberedsec Repair
-
-The replacement or correction of a failed configuration item.
-
-
-
-@cartouche
-All CFEngine promises refer to the state of a system that is desired. The promises are
-automatically enforced, hence CFEngine recovers a system (in principle) on every invocation.
-CFEngine always returns to a known state, due to the property of ``convergence''. There is no
-distinction between the concepts of repair, recovery or remediation.@end cartouche
-
-@node Release, Request for Change, Repair, ITIL glossary
-@unnumberedsec Release, Request for Change, Repair, Summary
-
-A collection of new or changed configuration items that are introduced together.
-
-
-
-@cartouche
-An instantiation of the entire CFEngine system under a specific
-version of a policy, i.e. a specific set of promises.
-@end cartouche
-
-@node Request for Change, Abandon Autonomy?, Release, ITIL glossary
-@unnumberedsec Request for Change
-
-A form to be completed requesting the need for change. This is to be followed up.
-
-
-
-@cartouche
-This has no counterpart in CFEngine. It is part of human communication
-which coordinates autonomous machines. Clearly autonomous computers do not
-listen to change requests from other computers, but when machines cooperate
-in clusters or groups they take suggestions from the collaborative process.
-An RFC in an ITIL sense is part of an organizational process that goes beyond
- CFEngine's level of jurisdiction. This is an example of what ITIL adds to
-the autonomous CFEngine model.
-@end cartouche
-
-
-@node Abandon Autonomy?, Resilience, Request for Change, ITIL glossary
-@unnumberedsec Abandon Autonomy?
-
-Why not simply abandon autonomy of machines if this seems to interfere
-with the need for organizational change? There are good reasons why
-autonomy is the correct model for resources. Autonomy reduces the risk to a
-resource of attack, mistake and error propagation.
-
-ITIL's processes exist precisely to minimize the risk of negative
-impact of change, so the goals are entirely compatible. When an organization
-discusses a change it examines information from possible several autonomous
-systems and discusses how they will change their pattern of collaboration.
-There is no point in this process at which it is necessary for one of the
-systems to give up its autonomy.
-
-
-@node Resilience, Restoration, Abandon Autonomy?, ITIL glossary
-@unnumberedsec Resilience
-
-The ability of a configuration item or IT service to resist failure or to recover quickly following a failure.
-
-
-
-@cartouche
-CFEngine's purpose is to make a system resilient to unpredictable change.@end cartouche
-
-@node Restoration, Role, Resilience, ITIL glossary
-@unnumberedsec Restoration
-
-Actions taken to return an IT service to the users after repair and recovery from an incident.
-
-
-
-@cartouche
-All CFEngine promises refer to the state of a system that is desired. The promises are
-automatically enforced, hence CFEngine recovers a system (in principle) on every invocation.
-CFEngine always returns to a known state, due to the property of ``convergence''. There is no
-distinction between the concepts of repair, recovery or remediation.
-
-However, this concept seems to suggest a more catastrophic failure
-which often involves a more significant restoration of a system from
-backup. This is discussed later.
-@end cartouche
-
-@node Role, Service desk, Restoration, ITIL glossary
-@unnumberedsec Role
-
-A set of responsibilities, activities and authorities granted to a person or a team. Roles are defined in processes.
-
-
-
-@cartouche
-A role in CFEngine is a class of agents that make the same kind of promise. The type
-of role played by the class is determined by the nature of the promise they make. e.g.
-a promise to run a web server would naturally lead to the role ``web server''.
-@end cartouche
-
-@node Service desk, Service Level Agreement, Role, ITIL glossary
-@unnumberedsec Service desk
-
-Interface between users and service provider.
-
-
-
-@cartouche
-A help desk. This is not formally part of CFEngine's tool set.
-@end cartouche
-
-@node Service Level Agreement, Service Management, Service desk, ITIL glossary
-@unnumberedsec Service Level Agreement
-
-A written agreement between the service provider that documents agreed
-services, levels and penalties for non-compliance.
-
-
-
-@cartouche
-An agreement assumes a set of promises that propose behaviour and an
-acceptance of those promises by the client. If we assume that the
-users are satisfied with out policies, then an SLA can be
-interpreted as a combination of a configuration policy
-(configuration service promises), and the CFEngine execution
-schedule.
-@end cartouche
-
-
-@node Service Management, Warning, Service Level Agreement, ITIL glossary
-@unnumberedsec Service Management
-
- The management of services.
-
-@node Warning, , Service Management, ITIL glossary
-@unnumberedsec Warning
-
-An @b{event} that is generated when a service or device is approaching its threshold.
-
-
-
-@cartouche
-A message generated in place of a correction to system state when a deviation from policy is detected.
-Note that CFEngine is not based on fixed thresholds. All ``thresholds'' for action or warning
-are defined as a matter of policy.
-@end cartouche
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_Iteration.texinfo b/docs/guides/SpecialTopic_Iteration.texinfo
deleted file mode 100644
index 6b6ef778c5..0000000000
--- a/docs/guides/SpecialTopic_Iteration.texinfo
+++ /dev/null
@@ -1,597 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-iterate.info
-@settitle Iteration in CFEngine
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Iteration, Explored and Explained
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-Iteration is about repeating operations in a list.
-
-In CFEngine it is the process by which a list variuable is expanded
-into its component parts -- a powerful and much-used idiom in
-CFEngine. It enables a level of abstraction that can save the system
-maintainer the job of repetitive specification of similar promises
-with slight differences, and can save time and ease readability of
-configuration files.
-
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2010 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Iteration:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@node Top, What is Iteration?, (dir), (dir)
-@top Iteration
-@menu
-* What is Iteration?::
-* Iterated promises::
-* Iterating across multiple lists::
-* Iterating over nested lists::
-* Fixing Iterating across nested lists::
-* Iterating revisted::
-* Nesting promises workaround::
-* Power::
-* Summary of iteration::
-@end menu
-@end ifnottex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-
-
-@node What is Iteration?, Iterated promises, Top, Top
-@unnumberedsec What is iteration?
-
-@sp 1
-
-Iteration is about repeating operations in a list. In CFEngine,
-iteration is used to make a number of related promises, that fall into
-a pattern based on elements of a list. This is what would correspond
-to something like this pseudo-code in an imperative language:
-
-@quotation
-@i{ foreach item in list}@*
- @i{make promise}@*
-@i{end}
-@end quotation
-
-@noindent In CFEngine, we do not write loops; rather, they are implicit.
-Suppose @samp{@@(list)} is a list variable (the @samp{@@} means list). If we
-refer to this identifier using a scalar reference @samp{$(list)}, then
-CFEngine understands this to mean, take each scalar item in the list and
-repeat the current promise, replacing the instance with elements of the list
-in turn.
-
-@node Iterated promises, Iterating across multiple lists, What is Iteration?, Top
-@unnumberedsec Iterated promises
-
-Consider the following set of promises to report on the values of four
-separate monitor values:
-
-@verbatim
-bundle agent no_iteration
-{
-reports:
- cfengine_3::
- "mon.value_rootprocs is $(mon.value_rootprocs)";
- "mon.value_otherprocs is $(mon.value_otherprocs)";
- "mon.value_diskfree is $(mon.value_diskfree)";
- "mon.value_loadavg is $(mon.value_loadavg)";
-}
-@end verbatim
-
-What we did was create four distinct reports, where each report announces
-which monitor variable it will be reporting, and the follows with the actual
-value of that monitor variable. For simple reports, this is perfectly
-adequate and straightforward, but it lacks abstraction and repeatability.
-Suppose we wanted to add a variable to report, we'd need a new report
-promise. If we wanted to change the wording of the reports, we'd possibly
-have to edit four promises, and this can be time consuming and error-prone.
-
-Consider instead the following example, which generates exactly the same reports:
-
-@verbatim
-bundle agent iteration1
-{
-vars:
- "monvars" slist => {
- "rootprocs",
- "otherprocs",
- "diskfree",
- "loadavg"
- };
-
-reports:
-
- cfengine_3::
-
- "mon.value_$(monvars) is $(mon.value_$(monvars))";
-}
-@end verbatim
-
-What we have done is to first specify a list variable @code{monvars}, and then
-iterate over the values contained in that list by referencing the list
-variable @i{as a scalar}. In CFEngine, simply referring to a list variable
-as a scalar automatically iterates over that variable.
-
-Note that in terms of raw "lines of code", neither example shows an advantage
-(and in fact, the reports that are created by the iteration in this second
-example are @i{identical} to the reports in the first example).
-
-However, we already have a gain in maintainer efficiency. By changing the
-single report format, we automatically change all the reports. And we have
-separated the semantics of the reports from the list of monitoring variables.
-
-Admittedly, this is a simple example, but if you understand this one, we can
-continue with more compelling examples.
-
-@node Iterating across multiple lists, Iterating over nested lists, Iterated promises, Top
-@unnumberedsec Iterating across multiple lists
-
-@sp 1
-Although iteration is a powerful concept in and of itself, CFEngine can
-iterate across multiple lists simultaneously. In the previous example, we
-looked at the current values of four monitor variables, but since CFEngine
-also gives us access to the averaged values and the standard deviation, how
-would we create a series of reports that listed all three statistical
-components of each variable? The answer is simply to do another iteration:
-
-@verbatim
-bundle agent iteration2
-{
-vars:
- "stats" slist => { "value", "av", "dev" };
-
- "monvars" slist => {
- "rootprocs",
- "otherprocs",
- "diskfree",
- "loadavg"
- };
-reports:
-
- cfengine_3::
- "mon.$(stats)_$(monvars) is $(mon.$(stats)_$(monvars))";
-}
-@end verbatim
-
-Through the addition of a new list called @code{stats}, we can now iterate
-over both it and the @code{monvars} list in the same promise. The reports
-that we thus generate will report on @code{value_rootprocs},
-@code{av_rootprocs}, and @code{dev_rootprocs}, followed next by
-@code{value_otherprocs}, @code{av_otherprocs}, etc, ending finally with
-@code{dev_loadavg}. The leftward lists are iterated over completely before
-going to the next value in the rightward lists.
-
-@node Iterating over nested lists, Fixing Iterating across nested lists, Iterating across multiple lists, Top
-@unnumberedsec Iterating over nested lists
-
-Recall that CFEngine iterates over complete promise units, not small parts of
-a promise. Let's look at an example that could show a common misunderstanding.
-
-If you look at the monitor variables that are described in the CFEngine
-Reference Guide, you'll notice that some variables reference the number of
-packets @i{in} and @i{out} of a host. So you might be
-tempted to do the following, which might not do what you expect.
-
-@verbatim
-bundle agent iteration3a
-{
-vars:
- "stats" slist => { "value", "av", "dev" };
- "inout" slist => { "in", "out" };
-
- "monvars" slist => {
- "rootprocs", "otherprocs",
- "diskfree",
- "loadavg",
- "smtp_$(inout)", #
- "www_$(inout)", # look here
- "wwws_$(inout)" #
- };
-
-reports:
- cfengine_3::
- "mon.$(stats)_$(monvars) is $(mon.$(stats)_$(monvars))";
-}
-@end verbatim
-@noindent What this says is, for each value in @samp{$(inout)}, define @samp{monvars}
-to be a variable. There are thus two attempts to defined the single name @samp{monvars}
-as a list with two different right-hand-sides (one for `in' and one for `out').
-This will result in the error:
-
-@smallexample
- !! Redefinition of variable "monvars" (embedded list in RHS) in context "iteration3a"
- !! Redefinition of variable "monvars" (embedded list in RHS) in context "iteration3a"
-@end smallexample
-
-Whenever a promise contains an iteration (that is, when the promise string or
-any of its attributes contain a scalar reference to a list variable), that
-promise is automatically re-stated with successive values from the list. So
-the example above is exactly the same as if we had said the following:
-
-@verbatim
-bundle agent iteration3b
-{
-vars:
- "stats" slist => { "value", "av", "dev" };
-
- "monvars" slist => {
- "rootprocs", "otherprocs",
- "diskfree",
- "loadavg",
- "smtp_in",
- "www_in", "wwws_in"
- };
-
- "monvars" slist => {
- "rootprocs", "otherprocs",
- "diskfree",
- "loadavg",
- "smtp_out",
- "www_out", "wwws_out"
- };
-
-reports:
- cfengine_3::
- "mon.$(stats)_$(monvars) is $(mon.$(stats)_$(monvars))";
-}
-@end verbatim
-
-Notice that the promise is repeated twice, but the only thing that is
-different is the @i{right hand side} of the promise -- the contents of the
-list, expanded using iteration over the @code{inout} list variable. Not only
-will this not do what we want, it will generate an error, because the second
-promise on the variable @code{monvars} will overwrite the value promised in
-the first promise! All that we will see in the reports are the @i{second}
-definition of the @code{monvars} list.
-
-@node Fixing Iterating across nested lists, Iterating revisted, Iterating over nested lists, Top
-@unnumberedsec Fixing Iterating across nested lists
-
-@verbatim
-bundle agent iteration3c
-{
-vars:
- "stats" slist => { "value", "av", "dev" };
- "inout" slist => { "in", "out" };
-
- "monvars_$(inout)" slist => {
- "smtp_$(inout)", #
- "www_$(inout)", # look here
- "wwws_$(inout)" #
- };
-
-reports:
- cfengine_3::
- "mon.$(stats)_$(monvars_in) is $(mon.$(stats)_$(monvars_in))";
- "mon.$(stats)_$(monvars_out) is $(mon.$(stats)_$(monvars_out))";
-}
-
-@end verbatim
-CFEngine does not allow an unlimited level of nesting, for reasons of
-efficiency and readability, and adding further levels of nesting
-will start to work against you. Note that we had to explicitly refer to the
-two variables that we created: @code{$(monvars_in)} and
-@code{$(monvars_out)}, and specifying more will get very messy very quickly.
-However, the next sections show an easier-to-read workaround.
-
-@node Iterating revisted, Nesting promises workaround, Fixing Iterating across nested lists, Top
-@unnumberedsec Iterating across multiple lists, revisted
-
-When a list variable is referenced as a scalar variable (that is, when
-the list variable is referenced as @code{$(list)}) instead of as a
-list (using @code{@@(list)}), CFEngine assumes that it should
-substitute each scalar from the list in turn, and thus iterate over
-the list elements using a loop.
-
-If more than one list variable is referenced in this manner in a
-single promise, each list variable is iterated over, so that every
-possible combination of scalar components is represented. Consider
-the following example.
-
-In this example, note that the @code{letters} list is
-referenced in both the left-hand and right-hand side of the promise,
-the @code{digits} list is referenced only in the left-hand side, and
-the @code{symbols} list is only referenced in the left-hand side:
-
-
-@verbatim
-bundle agent iteration4a
-{
-vars:
- "letters" slist => { "a", "b" };
- "digits" slist => { "1", "2" };
- "symbols" slist => { "@", "#" };
-
-commands:
- "/bin/echo ${letters}, ${digits}+${digits}, "
- args => "${letters} and ${symbols}'";
-}
-@end verbatim
-
-Like a backwards-reading odometer, the left-most variable cycles the fastest
-and the right-most list cycles the slowest. Most importantly, no matter how
-many times or places a list variable is referenced as a scalar in a single
-promise, each combination of values is visited @i{only once}, regardless of
-whether the iteration variable is in the lefthand side or the righthand side
-of a promise or both.
-
-The example above is exactly equivalent to this (much more) verbose set of
-promises. As you can see, there are @code{2*2*2 = 8} promises generated,
-which contains every possible comination of elements from the lists
-@code{letters}, @code{digits}, and @code{symbols}:
-
-@verbatim
-bundle agent iteration4b
-{
-commands:
- "/bin/echo a, 1+1, "
- args => "a and @";
- "/bin/echo b, 1+1, "
- args => "b and @";
- "/bin/echo a, 2+2, "
- args => "a and @";
- "/bin/echo b, 2+2, "
- args => "b and @";
- "/bin/echo a, 1+1, "
- args => "a and #";
- "/bin/echo b, 1+1, "
- args => "b and #";
- "/bin/echo a, 2+2, "
- args => "a and #";
- "/bin/echo b, 2+2, "
- args => "b and #";
-}
-@end verbatim
-
-@node Nesting promises workaround, Power, Iterating revisted, Top
-@unnumberedsec Nesting promises workaround
-
-Recall the problem of nesting iterations, we can now see how to repair
-our error. The key is to ensure that there is a distinct and unique
-promise created for every combination of iterated variables that we
-want to use. Here is how to solve the problem of listing the input
-and output packet counts:
-
-@verbatim
-bundle agent iteration5a
-{
-vars:
- "stats" slist => { "value", "av", "dev" };
- "inout" slist => { "in", "out" };
- "io_names" slist => { "smtp", "www", "wwws" };
- "io_vars[$(io_names)_$(inout)]" int => "0";
- "monvars" slist => {
- "rootprocs", "otherprocs",
- "diskfree",
- "loadavg",
- getindices("io_vars")
- };
-
-reports:
- cfengine_3::
- "mon.$(stats)_$(monvars) is $(mon.$(stats)_$(monvars))";
-}
-@end verbatim
-
-@noindent The output of this is
-@smallexample
-R: mon.value_rootprocs is $(mon.value_rootprocs)
-R: mon.av_rootprocs is $(mon.av_rootprocs)
-R: mon.dev_rootprocs is $(mon.dev_rootprocs)
-R: mon.value_otherprocs is $(mon.value_otherprocs)
-R: mon.av_otherprocs is $(mon.av_otherprocs)
-R: mon.dev_otherprocs is $(mon.dev_otherprocs)
-R: mon.value_diskfree is $(mon.value_diskfree)
-R: mon.av_diskfree is $(mon.av_diskfree)
-R: mon.dev_diskfree is $(mon.dev_diskfree)
-R: mon.value_loadavg is $(mon.value_loadavg)
-R: mon.av_loadavg is $(mon.av_loadavg)
-R: mon.dev_loadavg is $(mon.dev_loadavg)
-R: mon.value_wwws_in is $(mon.value_wwws_in)
-R: mon.av_wwws_in is $(mon.av_wwws_in)
-R: mon.dev_wwws_in is $(mon.dev_wwws_in)
-R: mon.value_www_out is $(mon.value_www_out)
-R: mon.av_www_out is $(mon.av_www_out)
-R: mon.dev_www_out is $(mon.dev_www_out)
-R: mon.value_www_in is $(mon.value_www_in)
-R: mon.av_www_in is $(mon.av_www_in)
-R: mon.dev_www_in is $(mon.dev_www_in)
-R: mon.value_smtp_in is $(mon.value_smtp_in)
-R: mon.av_smtp_in is $(mon.av_smtp_in)
-R: mon.dev_smtp_in is $(mon.dev_smtp_in)
-R: mon.value_wwws_out is $(mon.value_wwws_out)
-R: mon.av_wwws_out is $(mon.av_wwws_out)
-R: mon.dev_wwws_out is $(mon.dev_wwws_out)
-R: mon.value_smtp_out is $(mon.value_smtp_out)
-R: mon.av_smtp_out is $(mon.av_smtp_out)
-R: mon.dev_smtp_out is $(mon.dev_smtp_out)
-@end smallexample
-
-In this case, all we are doing is creating an array called @code{io_vars}.
-Note that the indices of the elements of the array are iterated from @i{two}
-lists, so in this case we'll have @code{2*3 = 6} elements in the array,
-covering all the combinations of the two lists @code{inout} and
-@code{inout-names}.
-
-The values of the array elements can be whatever we like. In this case, we're
-making all the values @code{0}, because we don't care what the actual values
-are -- we only care about the @i{keys} of the array. We add the list of the
-keys to the @code{monvars} list by using the return value from
-@code{getindices("io_vars")}.
-
-Looking at the example above, you might just as easily be tempted to do the
-following:
-
-@verbatim
-bundle agent iteration5b
-{
-vars:
- "stats" slist => { "value", "av", "dev" };
- "inout" slist => { "in", "out" };
- "io_names" slist => { "smtp", "www", "wwws" };
- "io_vars[$(io_names)_$(inout)]" string => "$(io_names)_$(inout)";
- "monvars" slist => {
- "rootprocs", "otherprocs",
- "diskfree",
- "loadavg",
- @(io_vars)
- };
-
-reports:
- cfengine_3::
- "mon.$(stats)_$(monvars) is $(mon.$(stats)_$(monvars))";
-}
-@end verbatim
-@noindent However, this is wrong.
-We cannot use @code{@@(io_vars)}, because @code{io_vars} is not a
-@i{list}, it is an @i{array}! You can only use the @code{@@} dereferencing
-sigil on lists.
-
-@node Power, Summary of iteration, Nesting promises workaround, Top
-@unnumberedsec The power of iteration in CFEngine
-
-Iteration and abstraction are power tools in CFEngine. In closing, consider
-the following simple and straightforward example, where we report on all of
-the monitoring variables available to us in CFEngine:
-
-@verbatim
-bundle agent iteration6
-{
-vars:
- "stats" slist => {"value", "av", "dev"};
-
- "inout" slist => {"in", "out"};
- "io_names" slist => {
- "netbiosns", "netbiosdgm", "netbiosssn",
- "irc",
- "cfengine",
- "nfsd",
- "smtp",
- "www", "wwws",
- "ftp",
- "ssh",
- "dns",
- "icmp", "udp",
- "tcpsyn", "tcpack", "tcpfin", "tcpmisc"
- };
- "io_vars[$(io_names)_$(inout)]" string => "$(io_names)_$(inout)";
-
- "n" slist => {"0", "1", "2", "3"};
- "n_names" slist => {
- "temp",
- "cpu"
- };
- "n_vars[$(n_names)$(n)]" string => "$(n_names)$(n)";
-
- "monvars" slist => {
- "rootprocs", "otherprocs",
- "diskfree",
- "loadavg",
- "webaccess", "weberrors",
- "syslog",
- "messages",
- getindices("io_vars"),
- getindices("n_vars")
- };
-
-reports:
- cfengine_3::
- "mon.$(stats)_$(monvars) is $(mon.$(stats)_$(monvars))";
-}
-@end verbatim
-
-In this example, we create a two arrays (@code{io_vars} and @code{n_vars}),
-and a number of lists (but the most important ones are @code{stats} and
-@code{monvars}). We have but a single report promise, but it iterates over
-these latter two lists. With only a single reports promise and intelligent
-use of lists and arrays, we are able to report on every one of the
-@code{3*(8+2*18+4*2)==156} monitor variables. And to change the format of
-every report, we will only have a single statement to change.
-
-@node Summary of iteration, , Power, Top
-@unnumberedsec Summary of iteration
-
-Used judiciously and intelligently, iterators are a powerful way of
-expressing patterns. They enable you to abstract out the concepts
-from the nitty-gritty details, and to specify, in very few lines,
-complex combinations of elements. Perhaps more importantly, they ease
-the burden of maintainability, by making short work of
-repetitive problems.
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_Knowledge.texinfo b/docs/guides/SpecialTopic_Knowledge.texinfo
deleted file mode 100644
index ca39659210..0000000000
--- a/docs/guides/SpecialTopic_Knowledge.texinfo
+++ /dev/null
@@ -1,998 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-knowledge.info
-@settitle Implementing Knowledge Management
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Implementing Knowledge Management
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-Everyone agrees that Knowledge Management is important, but few
-really appreciate what it means to manage knowledge, or how to
-begin. CFEngine's application area is principally operational, but it
-provides tools for integrating with business development and
-organizational management.
-
-This short guide suggests how to begin implementing a knowledge
-management strategy using CFEngine Nova as a centrepiece for integrating
-data from many different sources.
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2009 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-
-
-@node Top, What is knowledge management?, (dir), (dir)
-@top Knowledge
-@menu
-* What is knowledge management?::
-* Risk and uncertainty::
-* How should you begin?::
-* The CFEngine Knowledge map::
-* Pitfalls to avoid::
-* Using the Knowledge Map::
-* Types of information::
-* Example company_knowledge.cf::
-* Knowledge transfer::
-* How does CFEngine Nova help?::
-* Knowledge Management Objectives::
-@end menu
-
-
-
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-
-
-@node What is knowledge management?, Risk and uncertainty, Top, Top
-@unnumberedsec What is knowledge management?
-
-@sp 1
-
-Everyone agrees that Knowledge Management is important, but
-few really appreciate what it means to manage knowledge, or how to
-begin. Ironically perhaps, even learning institutions (so-called knowledge
-based industries) like schools and universities often do not do a good
-job of this. Having a wealth of knowledge is not the same as knowing
-how to foster and protect it. Most organizations take their
-knowledge for granted.
-
-In the worst case, poorly run organizations end up as collections of
-individuals, each of whom possesses knowledge and experience,
-but none of whom knows anything about the others' roles. This scenario presents a
-high risk for the continuity of the organization, since taking out
-even a single player could cripple a key work process.
-
-The end result is that many organizations are caught in a poverty trap
-of knowledge: they spend their time reacting to emergencies cultivated
-by a lack of confidence and certainty, and they are too busy patching over holes that
-they never have time to learn enough to escape the pattern.
-
-
-@cartouche
-The Third Wave of configuration management emphasizes the role of knowledge
-in coping with the diversity and adaptability that modern organizations crave.
-This document is a beginning towards thinking about IT management in a new way:
-as a knowledge resource, or a set of insight-driven intentions that are
-maintained by smart machinery. This vision is about rehumanizing System Administration
-through a proper division of labour between Man and Machine.
-@end cartouche
-
-@node Risk and uncertainty, How should you begin?, What is knowledge management?, Top
-@unnumberedsec Risk and uncertainty
-
-@sp 1
-
-Knowledge exists to reduce our uncertainty about the world. We don't
-generally learn in order to get smart, or to be experts; rather we
-learn by necessity and feel smart when there are no remaining
-surprises. Experts are people who can answer questions they already
-know the answer to; they are supposedly extra-ordinary. Innovators are
-people who can solve new problems -- they are even rarer.
-
-The main aim of knowledge management is not to make everyone an
-expert, but to improve the predictability of workflow processes so
-that we can respond to unpredictable changes in the environment with
-greater confidence, without losing the feeling of control over
-the situations we find ourselves in.
-To do that, we have to make the connections between the appropriate
-parts to that we can always obtain the answers.
-
-@node How should you begin?, The CFEngine Knowledge map, Risk and uncertainty, Top
-@unnumberedsec How should you begin?
-
-@sp 1
-The road to maturity can be seen as stepping through one or more of
-the following progressions:
-
-@sp 1
-@itemize
-@item Data --> Information --> Knowledge --> Wisdom (DIKW)
-
-@item Objectives --> Results
-
-@item Intentions --> Promises --> Assessments
-@end itemize
-@sp 1
-
-@image{dikw,12cm,,DIKW,png}
-
-Each of these sequences represents an increasing level of commitment.
-You need to have data to interpret them as information. You need to
-have goals or objectives in order to realize them and see results. You
-need to have intentions to make promises, and so on. Ask yourself:
-does everyone in your team know your business goals, and how to
-translate their efforts into progess?
-
-
-
-
-
-
-
-
-
-@node The CFEngine Knowledge map, Pitfalls to avoid, How should you begin?, Top
-@unnumberedsec The CFEngine Knowledge map
-
-Maps guide us to where we need to get to from where we are (even when we don't
-fully understand where we are). A map places us in the context or a larger
-picture and helps us to find our way.
-The Knowledge map is a part of the CFEngine Mission Portal,
-which in turn is provided with CFEngine Enterprise Edition.
-Significant instrumentation of the software, user process and policy analysis
-are provided in these editions in order to make Knowledge mining as transparent
-to the user as possible.
-
-@cartouche
-Our first task in Knowledge Management is to create a map of the knowledge
-landscape in which we work.
-@end cartouche
-
-CFEngine contains a tool @code{cf-know} for creating a map called a
-Topic Map, that forms to basis of our approach to documentation.
-Further, CFEngine Enterprise Editions, starting with Nova help fill in
-the landscape of this map automatically.
-
-To build a map, you will need data (hence the beginning of the DIKW chain).
-To use a map, you need an objective or an intention, hence the others.
-
-Ask yourself: what are the places in this map, and what are the paths between them?
-This is a question every organization needs to ask itself.
-
-@sp 1
-@node Pitfalls to avoid, Using the Knowledge Map, The CFEngine Knowledge map, Top
-@unnumberedsec Pitfalls to avoid
-
-@sp 1
-
-CFEngine does a lot of work for you, but you need to do something to help
-yourself too. As with all information, garbage in leads to garbage out.
-Your organization should create documents and references
-to capture its internal knowledge. If you are doing this well, it should not be
-a major task.
-
-Knowledge gets out of control when you don't standardize ideas,
-concepts and procedures. By standardizing topics and concepts, you
-prevent an explosion of redundancy -- only then can you see
-the signal in the noise. Standardization minimizes the number of things
-you have to deal with. Be careful though, if you go too far, standardization
-can become a straightjacket, preventing you from clear and free expression.
-Too much standardization and you will be stuck in a rut.
-
-@cartouche
-Dedicate yourself to a culture of simplicity, but not of
-over-simplification (which often backfires). Always work to avoid
-special cases and exceptions, unless they can be rigorously justified.
-@end cartouche
-
-This is a question of economics: is it worth the cost of maintaining a
-special case? CFEngine's is designed to make it a lot easier and
-cheaper to manage exceptions, so you needn't worry too much. Just
-don't go mad.
-
-Simplification is the hardest thing you will ever do. Anyone can make
-something more complicated, but it takes real work to simplify
-something@footnote{This is a general statement of the second law of
-thermodynamics -- entropy tends to increase. If we want to reduce it
-locally, we have to expend a lot of effort.}. Einstein's famous quote
-captures this: @i{You should always make everything as simple as
-possible, but no simpler.}
-
-
-
-@node Using the Knowledge Map, Types of information, Pitfalls to avoid, Top
-@unnumberedsec Using the Knowledge Map
-
-CFEngine's exploration of knowledge management is still in its infancy
--- we are learning constantly about how to use state of the art
-technologies and techniques. This is still very much an experimental area
-that we continue to improve upon.
-
-Let's look at the current state of the smart index which we call the
-(Copernicus) Knowledge Map. If you go to the Mission Portal Library and
-search for a topic, you will land in the Knowledge Map. You will immediately
-see a graphical image and number of tabs that contain various different
-renditions of the information.
-
-Presently, these are called:
-@itemize
-@item Map - a visual view of a small neighbourhood of the closest related topics
-that places the search topic in the context of closely related items. The search
-topic might not be a the centre of this little universe, as other topics can
-be more important. The size of the plantary balls is an indication of the topic's
-connectedness in the web.
-@item Leads - an explanation with full text for the nearest neighbours of the search topic.
-@item References - Actual document links or remarks made about the search topic.
-@item Same context - Other topics discussed in the same context.
-@end itemize
-
-@menu
-* Knowledge map example 1::
-* Knowledge map example 2::
-@end menu
-
-@node Knowledge map example 1, Knowledge map example 2, Using the Knowledge Map, Using the Knowledge Map
-@unnumberedsubsec Knowledge map example 1
-
-You enter the knowledge map by searching, or being referred there by a link in
-the Mission Portal. Suppose we enter @samp{webserver} into the search field.
-CFEngine searches for matching topics in its index, and returns references in
-different contexts. The context `any' represents an unspecific reference to the topic
-name:
-
-@image{km1,12cm,,DIKW,png}
-
-Suppose we click on the first of these in any context; this leads us to a special
-landing page about that particular topic which contains the four tabs mentioned above.
-By default we end up in the graphical view. This gives an immediate impression of
-roughly where CFEngine considers this topic to lie in the scope of its knowledge.
-However, its value is rather limited.
-@image{km2,12cm,,DIKW,png}
-
-The next step is to walk through the tabs to `drill down' to actual
-content. The second tab points us to the `brainstorming' value of the
-associative links -- now with explanations in text. If we select
-another tab we arrive at further leads for assisted thinking: these
-associative-thinking pointers can guide you to matters that are
-related and provide context for the current topic.
-
-@image{km3,12cm,,DIKW,png}
-
-
-
-Leads are helpful if you didn't really know what you were
-looking for in the first place -- and you would like some explanation
-of what it what you guessed.
-
-
-If we select one of these, we go the landing page for that new topic in the advertised
-context.
-
-@image{km4,12cm,,DIKW,png}
-
-
-Note that several topics might be highlighted
-in yellow on a page -- if they have been named, or if they are topics of special importance in
-this local cluster (meaning that they are highly referred to).
-
-In this view we are able to see, at a glance, that this somewhat
-Byzantine string is the name of a file, and that is pertains only to
-certain operating systems. Walking through the tabs again, we see
-both where we came from and where we can go from here, with
-more detailed explanations.
-
-@image{km5,12cm,,DIKW,png}
-
-So far the map has only shown us topics -- or named subjects
-categorized by their context. This gives us a kind of compass for
-knowing what the topic is about, but it tells us little about the
-subject itself. The third tab points us to actual expansive
-information about the topic, if any is known. This might be information
-from the documentation, external links or commentary and remarks made in
-policy.
-
-@cartouche
-If there are no references to external information, this tab does not appear.
-Let's choose one of these references; now we are taken to a new topic
-altogether, where we see a new view of the system information.
-@end cartouche
-
-@image{km6,12cm,,DIKW,png}
-
-Because the topic name is categorized in the context of `promises', we
-know that (although this is the name of a file and it refers to
-RedHat-like operating systems) that this is also the object of a
-promise. The references page contains a link that then points us to
-actual information about this promise. The textual comment that was attributed
-to the promise in the policy itself, and a link to the promise's definiton.
-Clicking on the defintion link takes us the the promise-viewer.
-
-@image{km7,12cm,,DIKW,png}
-
-The Copernicus Knowledge Map view will take you a while to get used to -- use it
-to help you think about matters, and see how they fit together into a systematic
-overview of your environment.
-
-
-@node Knowledge map example 2, , Knowledge map example 1, Using the Knowledge Map
-@unnumberedsubsec Knowledge map example 2
-
-Let's look at another example. Suppose we enter @samp{vital signs} as
-the search text, and go to the leads. We find a long list of other
-topics. CFEngine says that `vital signs' generalizes, or is an
-umbrella concept, for these other concepts.
-
-@image{km8,12cm,,DIKW,png}
-
- One of these
-concepts is a class context that represents an anomaly
-detected by CFEngine @samp{loadavg_high_dev2}.
-Clicking on this, we see the
-significance of this concept quite easily from its relationship
-to other concepts:
-
-@image{km9,12cm,,DIKW,png}
-
-The load average being high might be an anomaly, but we also see that it
-refers to system performance, as does a whole bunch of other concepts.
-
-@cartouche
-The value of the semantic indexing is that it is information a casual user
-can actually learn from. By providing context and leads for further thinking,
-the Mission Portal becomes an quasi-intelligent assistant for working on
-the system.
-@end cartouche
-
-@node Types of information, Example company_knowledge.cf, Using the Knowledge Map, Top
-@unnumberedsec Types of information
-
-@sp 1
-
-There are many kinds of information that contribute to a strategy for
-managing knowledge. The ability to learn from past mistakes demands
-that we look both forwards and backwards, while realizing that
-knowledge grows older and less useful the older it gets.
-For instance, what is known about the past? What
-is current? How can we track these things? Information comes in
-logically different categories as well as different types. Data have
-different sources, and are about different epochs. We need to unify
-and integrate these in Knowledge Management.
-
-@table @i
-
-@item Conceptual information (Always)
-
-Conceptual information is knowledge of a general nature that defines
-basic terms and concepts that describe the operational area of the
-organization. e.g. background theory, compliance requirements, frameworks, license
-expiry documents. Contracts and agreements.
-
-This information comes from the wider culture of the enterprise. It is often
-treated poorly as our modern culture has an unreasonable suspicion of anything that
-seems `academic'.
-
-@item System observations (Past)
-
-Recording what has actually happened in the organization. This includes
-the IT system, but also the business services and workflows, e.g.
-changes, transactions, logs, incidents, events, performance values (Key
-Performance Indicators), audits, security scans, etc. This includes
-what it traditionally called system monitoring.
-
-This comes from probing and monitoring human-computer processes.
-
-@item Enterprise process documentation (Now)
-
-These documents are about business internals, recipes, manuals and
-how-tos. They allow individuals to work autonomously without constant
-supervision, because they all have a copy of the script. This
-information is about @i{orchestration} of parts. In an orchestra each
-player can manage to play his or her part with only minimal advice
-from a conductor because they each have a copy of their music. Their
-music is their process documentation.
-
-This is closely related to policy and comes from internal management bodies.
-
-@item Policy (Future)
-
-Here are the promises and intentions of the IT mission. Documents of
-all degrees of technicality form policy. They contain the decisions
-you have made for steering the mission under all possible
-contingencies.
-
-Policy is informed by all of the above, and usually changes in
-response to recurring `problems' identified in the observations. It
-originates from internal management.
-
-@end table
-
-
-
-
-@sp 1
-@unnumberedsec Stories and narratives
-
-In the foregoing section, we saw how leads in the Knowledge Map's
-semantic index could help us to see immediate relationships between
-system issues. The next question is: what about connections that are less
-immediate or obvious?
-
-In future releases you will be able to ask the agent to brainstorm for you
-about topics, telling any stories is knows about topics. A story is a
-simply a path through the web of connected information that follows
-some kind of connectness. Most interesting stories have a thread of
-cause and effect. CFEngine attempts to reason forth narratives that
-might be sensible or which might offer some kind of insight. This is
-not usually a directly useful revelation, but more often a thought
-provoking stimulus for a human to take further.
-
-Machine intelligence is never a substitute for the real thing, at least
-not in our present day technologies, but it can be a useful amplifier of
-`leads' to get a smart human thinking about the right things.
-Most CFEngine stories relate to policy, and they are generated automatically
-by the knowledge engine, so you will not get any stories until you have
-something interesting in your policy.
-
-Stories will be usable from the command-line, or as a tab within the
-Mission Portal. The command line is useful for interactive
-thinking:
-
-A story can be quite simple:
-@cartouche
-@smallexample
-atlas$ src/cf-know --tell-me-about ftpusers
-F: "ftpusers" seems to affect "any::/etc/ftpusers" (with 50 % probability)
-
- "ftpusers" (in any),
- see also "/etc/ftpusers" (in any),
-@end smallexample
-@end cartouche
-@noindent Other stories could be more involved:
-@cartouche
-@smallexample
-cf-know --tell-me-about anomalies::cpu0_high_dev2
-
-F: "anomalies::cpu0_high_dev2"
-seems to affect "any::performance" (with 100 % probability)
-
- "cpu0_high_dev2" (in anomalies),
- is a special case of "vital signs" (in any),
- which is a generalization of "users_high_dev1" (in anomalies),
- and this (users_high_dev1) is a special case of "performance" (in any)
-
-(Note also that performance, which was mentioned, is a generalization of
-"anomalies::users_high_dev1")
-
-@end smallexample
-@end cartouche
-
-@noindent Stories can also be quite spurious, because knowledge itself can be spurious.
-For instance, some guesses might be quite wrong as the system gets the wrong end of the stick,
-so to speak, as it uses general patterns and these patterns always have exceptions:
-@cartouche
-@smallexample
-atlas$ src/cf-know --tell-me-about operating_systems::suse
-
-F: "operating_systems::suse" seems to affect "any::gnu/linux" (with 100 % probability)
-
- "suse" (in operating_systems),
- is a special case of "linux" (in any),
- and this (linux) seems to refer to "gnu/linux" (in any)
-
-F: "operating_systems::suse" seems to affect "any::unitedlinux" (with 100 % probability)
-
- "suse" (in operating_systems),
- is a special case of "linux" (in any),
- and this (linux) seems to refer to "unitedlinux" (in any)
-
-@end smallexample
-@end cartouche
-@noindent Or:
-@cartouche
-@smallexample
-atlas$ src/cf-know --tell-me-about functions
-
-F: "any::functions" seems to affect "any::arrays" (with 100 % probability)
-
- "functions" (in any),
- seems to refer to "functions which read" (in any),
- which seems to refer to "functions which read arrays" (in any),
- and this (functions which read arrays) seems to be referred to in "arrays" (in any)
-
-F: "any::functions" seems to affect "any::expression" (with 100 % probability)
-
- "functions" (in any),
- seems to refer to "functions which read" (in any),
- which seems to refer to "functions which read classes" (in any),
- which seems to be referred to in "class" (in data_types),
- which seems to refer to "a cfengine class expression" (in any),
- and this (a cfengine class expression) seems to be referred to in "expression"
-(in any)
-...
-@end smallexample
-@end cartouche
-
-As you can see, the story generator looks for causative connections between the things
-that it knows about. Some topics are from the documentation, and some from your
-configuration policy.
-
-@cartouche
-@smallexample
-F: "any::functions" seems to affect "any::readrealarray" (with 100 % probability)
-
- "functions" (in any),
- seems to refer to "functions which read" (in any),
- which seems to be referred to in "class" (in data_types),
- which seems to be referred to in "functions which return" (in any),
- which seems to refer to "functions which return real" (in any),
- which seems to be referred to in "real" (in vars_promises),
- and this (real) seems to refer to "readrealarray" (in any)
-
-(Note also that readrealarray, which was mentioned, seems to refer to
-"any::functions which read classes")
-(Note also that readrealarray, which was mentioned, seems to refer to
-"any::functions which return class")
-@end smallexample
-@end cartouche
-
-@sp 1
-@unnumberedsec Creating your own map
-
-@sp 1
-CFEngine provides a lot of knowledge about your system out of the box, that includes a domain
-model about the space of IT management, and an automated analysis of the deployed policy.
-Below are some notes about how this is built, and things you can do to improve the information
-by adding knowledge that cannot be discovered automatically.
-@enumerate
-
-@item You begin by documenting your intentions by creating a CFEngine automation policy, i.e. bundles of promises.
-
-@item You add comments, handles, promisees etc to your policy to full explain your intentions.
-
-@item You can assign each host in your network to a special class that represents its
-physical location, using @code{classes:} promises. You should then collect
-such classes into a topic context called @samp{locations::} in the @file{company_knowledge.cf} file.
-
-@item CFEngine runs @code{cf-promises -r} to build a decompsition of your
-current policy.
-
-@item CFEngine runs @code{cf-know -bf enterprise_build.cf} to build the knowledge map.
-
-@item You may create enterprise process documents and written policies for your
-organization, which you will link into the knowledge map.
-
-@item CFEngine Nova creates the Knowledge Map which includes
-a conceptual framework for IT management, and which integrates with
-the CFEngine software documentation.
-
-@item You may now extend the basic knowledge map with more of your
-own special documentation by placing references and
-additional concepts into the file @file{company_knowledge.cf}, on the policy server.
-
-@end enumerate
-
-@unnumberedsec Documenting goals
-
-Business goals are shown in the Goals app (and service catalogue) in the Mission Portal of CFEngine Enterprise
-for each hub. To document the fact that a promise or bundle contributes to a business goal,
-you must do two things:
-
-@enumerate
-@item Document the goal (see below under the example @file{company_knowledge.cf} file). e.g.
-@verbatim
-topics:
-
- goals::
- "goal 1" comment => "Do good things";
- "goal 2" comment => "Be first";
- "goal 3" comment => "Be best";
-
-@end verbatim
-@item Make the goal a promisee of the promise concerned.
-
-@verbatim
-methods:
-
- "security" -> { goal_1, goal_2 }
-
- comment => "Basic change management",
- usebundle => change_management;
- "maintenance"
- comment => "Perform log rotation",
- usebundle => garbage_collection;
-@end verbatim
-
-@end enumerate
-
-@unnumberedsec Documenting locations
-
-To document the location of a host, make sure that it is placed inside a class that represents its address:
-
-@verbatim
-classes:
-
- "london" or => { "host1", "host2" };
- "alexandria" or => { "host3", "host4", "host5" };
-
-@end verbatim
-@noindent Then designate these classes as locations in the knowledge map:
-@verbatim
-topics:
-
- locations::
-
- "london" comment => "29 Market Street, London XW4, third on the left";
- "alexandria" comment => "Secret chamber, discovered by Indiana Jones";
-
-@end verbatim
-
-@node Example company_knowledge.cf, Knowledge transfer, Types of information, Top
-@unnumberedsec Example @file{company_knowledge.cf}
-
-@smallexample
-
-bundle knowledge company_knowledge
-@{
-things:
-
- regions::
-
- "Americas" comment => "USA, Latin America and Canada";
-
- "EMEA" comment => "Europe, The Middle-East and Africa";
-
- "APAC" comment => "Asia and the Pacific countries";
-
- countries::
-
- "USA";
-
- "Germany";
-
- "UK" synonyms => @{ "Great Britain" @},
- is_located_in => @{ "EMEA", "Europe" @};
-
- "Netherlands" synonyms => @{ "Holland" @},
- is_located_in => @{ "EMEA", "Europe" @};
-
- "Singapore" is_located_in => @{ "APAC", "Asia" @};
-
- site_locations::
-
- # Use this for the names of
-
- "London_1" is_located_in => @{ "London", "UK" @};
- "New_Jersey" is_located_in => @{ "USA" @};
-
- routers::
-
- "oslo-hub-p6 " comment => "Cisco xyz router, 3rd floor machine room, 6 Penny Street";
- "oslo-hub-trunk" comment => "Cisco BGP router, floor machine room";
- "nyc-hub-456" comment => "Juniper 123 router, 3rd floor machine room";
-
- networks::
-
- "192.23.45.0/24"
- comment => "Secure network, zone 0. Single octet for corporate offices",
- is_connected_to => @{ "oslo-hub-123" @};
-
- "192.12.74.0/23" comment => "Zone 1, double octet for the London office developer network",
- is_connected_to => @{ "oslo-hub-123" @};
-
- "192.12.74.0/23"
- comment => "Secure, single octet for the NYC office",
- is_connected_to => @{ "nyc-hub-456" @};
-
-
-#######
-
-topics:
-
- company::
-
- "ED" comment => "Exceptional Devices Ltd";
-
- ED::
-
- "EGC" comment => "Enterprise grid computing",
- association => a("develops stuff within",
- "ED",
- "contains its engineering unit");
-
- "EBC" comment => "Enterprise business computing",
- association => a("handles business services within",
- "ED",
- "contains its business unit");
-
- "ED terminology" comment => "Internal company nomenclature";
-
- ED_terminology::
-
- "interactive job" comment => "Interactive software running in the grid";
-
- "apps" comment => "Software applications",
- association => a("are also referred to as",
- "interactive jobs",
- "are also referred to as");
-
- "business services" comment => "Support services for sales";
-
-########################
-# GOALS as topics
-########################
-
- goals::
-
- "goal 1" comment => "The company mission depends on reliability to our customers";
- "goal 2" comment => "Should be running recent versions of key software";
- "goal 3" comment => "The company must be compliant with Sarbanes Oxley act.";
- "goal 4" comment => "Comply with US Export restrictions for class D countries";
-
-
-#######
-# Documents below
-#######
-
-occurrences:
-
- # Fill in company references here
-
- work_shifts::
-
- "http://www.example.com/shifts_and_rotas.ods"
- represents => @{ "Spreadsheet" @};
-
-
- current_projects::
-
- "http://www.example.com/scope_of_work.html"
- represents => @{ "SOW" @};
-
-
- software_licenses::
-
- "This CFEngine software license expires $(sys.expires)"
- representation => "literal",
- represents => @{ "CFEngine Nova" @};
-
-@}
-
-@end smallexample
-
-@sp 1
-@unnumberedsec What other special documents should an organization have?
-
-@sp 1
-CFEngine cannot produce everything you need for your library of knowledge.
-There cannot be hard and fast rules about this. Here are some suggestions:
-
-@itemize
-@item A policy on human roles and responsibilities, to avoid gaps in and unecessary doubling of effort.
-@item A risk/security policy.
-@item A standardization and procedure manual.
-@item Incident logs of matters not detected and repaired by CFEngine.
-@item Repair logs of matters not detected and repaired by CFEngine.
-@item Requests for change (RFC) logs.
-@item Promises in your organization that are not just for CFEngine to keep, documenting intentions.
-@item A policy on Knowledge Retention and Business Continuity.
-@end itemize
-
-@sp 1
-@cartouche
-Hint: a simple way to have a log is to use a tickets system like OTRS or a moderated mailing list, and to email
-new entries. Something like a Mailman archive allows then tracking and integration.
-@end cartouche
-@sp 1
-
-@node Knowledge transfer, How does CFEngine Nova help?, Example company_knowledge.cf, Top
-@unnumberedsec Knowledge transfer
-
-@sp 1
-
-Passing on knowledge to others could be considered a `best
-practice'. Alas, this is not as easy as it sounds. There are plenty
-of strategies to achieve knowledge transfer:
-
-@itemize
-@item Reading
-@item Taking courses
-@item Research
-@item Repetition
-@item Job swapping and promotion
-@end itemize
-
-@noindent These are just a few. However, this list is old news, and
-these items alone will not lead to knowledge transfer.
-
-One of the most important @i{barriers} to knowledge transfer is that
-individuals refuse to learn new things. A lack of dynamism in a
-company or organization establishes patterns of habit that are hard to
-break. The longer they last, the more likely they are to continue.
-
-Promise theory makes clear that, even if all staff promise
-to write excellent documentation, they do not necessarily promise
-to read each others' documents. Transfer requires a commitment both
-to send and to receive.
-
-
-@cartouche
-@itemize
-@item The final step to managing knowledge is to foster a culture
-of knowledge acquisition, retention and transfer.
-
-@item Knowledge transfer requires a commitment by all parties
-@itemize
-@item to learn outside of their box.
-
-@item to pass on their expertise to others.
-@end itemize
-@end itemize
-@end cartouche
-
-Communication skills are clearly important, but this is a serious flaw
-in the idea. Written communication skills are not as common as we
-might think. This means it is hard for the writer, and also for the
-reader.
-
-The solution taken by CFEngine is to reduce the problem of
-documentation to one of coding notes and relationships. This requires
-only minor writing skills. The technology can then assemble these notes
-using intelligent algorithms and present the result in an organized form
-with visual aids. You should pay special attention to the syntax items:
-
-@verbatim
- comment =>
- handle =>
- depends_on =>
-
- -> { promisees }
-
-@end verbatim
-
-
-You need to foster a culture of using information, in order for it
-to become assimilated as knowledge. Unused information will perish.
-
-
-@node How does CFEngine Nova help?, Knowledge Management Objectives, Knowledge transfer, Top
-@unnumberedsec How does CFEngine Nova help?
-
-@itemize
-@item CFEngine assists knowledge management by providing tools for integration
-of knowledge sources.
-
-@item A formal structure for encoding policy at relationships at a functional level
-
-@item Technical syntax makes annotation easy for IT workers, and CFEngine can construct
-the surrounding story using intelligent algorithms.
-@end itemize
-
-
-
-
-
-@node Knowledge Management Objectives, , How does CFEngine Nova help?, Top
-@unnumberedsec Knowledge Management Objectives
-
-As a manifesto for us as developers at CFEngine, as well as for you as
-users of the software, and as infrastructure engineers, it is helpful
-to make a list of questions that we would like to be able to answer
-using enterprise software. The following list is not to be regarded
-as a set of features in CFEngine, but rather as a set of challenges
-to be addressed in different ways.
-
-@itemize
-
-@item Tell me about the promise(s).
-@item Tell me what happened to Y.
-@item Tell me about security.
-@item Tell me about performance.
-@item Tell me about compliance.
-@item Where are the resource problems?
-@item Where is the greatest/least activity?
-@item How much spare capacity do I have?
-@item Where are things changing fastest?
-
-@item When do I need to think about X?
-@item What do I need to know about X?
-@item What are the most important things that happened?
-
-@item Why is this here?
-@item What can I do about X?
-@item Who changed X last?
-@item When can I expect X?
-@item Where can I find X?
-@item What things affect X?
-@item What promises have been made about X?
-@item What stories lead to conclusion X?
-
-@end itemize
-
-
-
-
-
-
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_MenuDrivenConfig.texinfo b/docs/guides/SpecialTopic_MenuDrivenConfig.texinfo
deleted file mode 100644
index 67991619f3..0000000000
--- a/docs/guides/SpecialTopic_MenuDrivenConfig.texinfo
+++ /dev/null
@@ -1,440 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-menus.info
-@settitle Menu Driven Configuration
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Menu Driven Configuration
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-Efficient organizations strive for simplicity and clockwork repetitive
-procedures to extend and streamline their operations, but
-over-simplification can lead to limitation and can get in the way of
-progress. In this short guide, we consider how to use CFEngine's agile
-framework to structure a simple menu-like approach to organizing
-systems for predictable productivity.
-
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2010 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Iteration:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-
-@node Top, What is menu-driven configuration, (dir), (dir)
-@top Menu Driven Configuration
-@menu
-* What is menu-driven configuration::
-* How do you create menus with CFEngine::
-* How do I select from menus::
-* How do I nest menus and make dependencies::
-* Strong and weak dependency::
-* How do I see what machines keep which promises::
-* Can I see a score-card of compliance::
-* Should I use menu driven configuration::
-@end menu
-
-@end ifnottex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@node What is menu-driven configuration, How do you create menus with CFEngine, Top, Top
-@unnumberedsec What is menu-driven configuration?
-
-@sp 1
-A menu is a list of simple choices. The purpose of a menu is to hide
-the detailed breakdown of how those choices are implemented. A menu
-item uses a single name to represent all the processes needed to bring
-about the result. Naming things is an important aspect of knowledge
-management.
-
-Menus work well as long as the choices you are presented with are
-sufficient to cover your needs. If a menu is too short, it will force
-you to choose sub-optimally, leading to an oversimplification of
-your issues. This can lead to frustration and compromise.
-
-CFEngine does not force pre-determined menus onto you, rather it
-allows you to make your own from building block operations. This
-document explains how to simplify your interface to complex
-configuration decisions by organizing it according to what amounts to
-a number of context dependent menus -- i.e. menus that automatically
-adapt to the environments in which they are run.
-
-@sp 1
-@cartouche
-Once menus have been defined, they can be presented simply in any kind of
-interface, including custom graphical user interfaces.
-@end cartouche
-@sp 1
-
-@node How do you create menus with CFEngine, How do I select from menus, What is menu-driven configuration, Top
-@unnumberedsec How do you create menus with CFEngine?
-
-@sp 1
-
-A menu is a list of delegated methods. To create a menu, you need to
-be able to name complex methods. CFEngine does this by grouping
-promises into @i{bundles}. You must then present these bundles in some
-kind of list for different machines in your environement to select
-from. CFEngine has two mechanisms for presenting a bundle of lists.
-
-@itemize
-@item The first approach is to use the @code{bundlesequence} as your menu. This is the master
-execution list that CFEngine uses to process work. You `choose' promise bundles there by
-commenting out the ones you don't want to use:
-
-@verbatim
-body common control
-{
-bundlesequence => {
- "common_stuff",
-# "change_management",
-# "garbage_collection",
-# "harden_xinetd",
-# "my_firewall",
- "php_apache",
-# "j_def", "jboss_account", "jboss_server",
-# "ruby_on_rails",
-# "tomcat_server",
-# "db_mysql",
-# "db_postgresql",
- };
-}
-@end verbatim
-
-@noindent The advantage of the bundlesequence is that it provides a @i{definite ordering} of
-the bundles. In the example above, the order doesn't matter much. The
-disadvantage of this bundlesequence is that it is hard to adapt it to
-more than one environment -- it is like a `set taster menu'. Every
-machine using this configuration will get what it's given. That is too
-heavy-handed for more sophisticated environments.
-
-@item The second approach is to use @code{methods} promises to embed bundles in a master-bundle,
-in the manner of subroutines.
-
-@verbatim
-body common control
-{
-bundlesequence => {
- "common_stuff",
- "main",
- };
-
-}
-
-bundle agent main
-{
-methods:
-
- context1:: # Menu for context 1
- "course2" usebundle => php_apache;
-
- context2:: # Menu for context 2
- "course2" usebundle => j_def;
- "course2" usebundle => jboss_account;
- "course2" usebundle => jboss_server;
-
- any:: # Menu items for everyone
- "course1" usebundle => changemanagement;
-
-}
-@end verbatim
-@noindent In this example, we've just pointed the master bundlesequence to a `main' subroutine
-(like in a C program) and we list the bundles we want to combine into menus in order, in different
-contexts. So in context 1, machines see a PHP menu; in context 2, they see a Java menu. Both of them
-get a common `dessert' of change management.
-
-This `method' approach makes light work of adaptation, but while the
-order is preserved in most cases, you cannot guarantee that CFEngine
-will execute the bundles in the written order, because other
-`transaction constraints' (including CFEngine's convergent algorithms)
-can interfere. In many cases ordering is less important than we have been taught to
-think, but if you truly need strong ordering then there are mechanisms to ensure
-the strict order of keeping promises.
-@end itemize
-
-
-@node How do I select from menus, How do I nest menus and make dependencies, How do you create menus with CFEngine, Top
-@unnumberedsec How do I select from menus?
-
-Because CFEngine is a distributed system, every machine running
-CFEngine can make its own choices. You can suggest a menu for
-different classes of machines, that operate in different contexts.
-
-A machine selects a menu choice by virtue of being in a context that
-has been defined. For instance, you might make separate menu choices based
-on operating system:
-
-@verbatim
-bundle agent main
-{
-methods:
-
- ubuntu:: # Menu for context 1
- "course2" usebundle => php_apache;
-
- solaris:: # Menu for context 2
- "course2" usebundle => j_def;
- "course2" usebundle => jboss_account;
- "course2" usebundle => jboss_server;
-
- any:: # Menu items for everyone
- "course1" usebundle => changemanagement;
-
-}
-@end verbatim
-
-@noindent Alternatively, you might choose based on other context information, such
-as the time of day, or membership in some abstract group:
-
-@verbatim
-bundle agent main
-{
-methods:
-
- Hr16.Min45:: # Menu for context 1
- "course2" usebundle => backup_system;
-
- mygroup:: # Menu for context 2
- "course2" usebundle => attach_storage_devices;
-
-}
-@end verbatim
-
-The expressions like @samp{Hr16.Min45} are called `class expressions'
-because they classify different contexts or scenarios, and CFEngine
-knows how to keep promises only in the correct context. This is how
-you select from a menu -- by correctly identifying the context a
-system belongs to and describing the menu of promise-bundles that apply to it.
-
-@node How do I nest menus and make dependencies, Strong and weak dependency, How do I select from menus, Top
-@unnumberedsec How do I nest menus and make dependencies?
-
-@sp 1
-Recursion is the term used to express a hierarchy of levels of description.
-When a promise depends on something else, which in turn depends on a third
-promise being kept, we say that there is nesting or recursion.
-
-A dependency (something we depend on to keep a promise) is often used as
-a strategy for hiding detail. You push details into `black boxes' on which
-you depend, and in doing so simpify the view for yourself. This is the menu
-idea once again. So when you pick a menu item in the restaurant, the kitchen
-breaks down your choice into a sub-menu of promises required to deliver your
-selection, and so on down the chain.
-
-CFEngine allows bundles of promises to depend on other promises by
-writing those promises inside the bundles. A bundle can even rely on
-bundles of promises by using the @code{methods} approach
-recursively. So, for example you could make a general menu choice
-`setup_server', which depends on bundles `setup_general'
-and `setup_solaris' and `setup_linux'.
-
-@verbatim
-bundle agent main
-{
-methods: # bulk dependency by bundle
- linux::
- "linux machines" usebundle => setup_linux;
- solaris::
- "sun machines" usebundle => setup_solaris;
- any::
- "all" usebundle => setup_general;
-
-files:
- # other promises
-}
-
-#
-
-bundle agent setup_general
-{
-commands: # Dependenc on individual promise
- Hr06::
- "/usr/local/bin/do_backup"
- comment => "Command dependence";
-}
-
-bundle agent setup_linux
-{
-packages:
- ubuntu:: # Dependence on software
- "apache2"
- package_policy => "add",
- package_method => "yum";
-
-}
-
-# other bundles ...
-@end verbatim
-
-Notice how each `menu level' simplifies the appearance of the problem by
-hiding details in the lower levels. This is the way you make components
-in systems and delegate responsibility for different tasks to different
-bundle maintainers.
-
-
-@node Strong and weak dependency, How do I see what machines keep which promises, How do I nest menus and make dependencies, Top
-@unnumberedsec Strong and weak dependency
-
-@sp 1
-
-Weak dependency means that you `outsource' tasks that you will
-eventually make use of, i.e. you depend on the outcomes but you don't
-have to wait for the result. This kind of dependence brings
-flexibility and allows delegation.
-
-Strong dependency means that you are completely dependent on getting the
-result from somewhere else before you can continue. This kind of
-dependence creates fragile or `brittle' systems. If part of the system
-breaks, then everything breaks. It leads to `single points of failure'.
-
-We recommend avoiding strong dependency when designing systems. Whenever
-possible, a system should survive the temporary loss of a part, and
-should continue in a sensible and predictable manner.
-
-
-@node How do I see what machines keep which promises, Can I see a score-card of compliance, Strong and weak dependency, Top
-@unnumberedsec How do I see what machines keep which promises?
-
-@sp 1
-Once you have arranged your system promises in nested bundles to handle all of the
-dependences, you no longer have a complete overview of the system. This is the challenge
-of menu hierarchies -- hierarchy simplifies for individuals by offloading
-responsibility, but it makes it harder for anyone to get a total overview.
-
-To get back to the total overview, you can use CFEngine's Knowledge Map.
-
-@image{knowledge_bundle,15cm}
-
-The knowledge map renders all of the relationships between promises as
-a lexicon and visual map. It allows you to see the total set of
-promises and bundles either as a generic flat network, or as a
-hierarchy. It also allows you to search for issues within the
-total network. The knowledge map puts back what the hierarchy
-takes away, by allowing you to construct your own view of the system.
-
-If there are dependences they may be seen as a graphical representation
-of issues. The lower image in this figure shows the direct dependences
-of the `grant_reports' promises, i.e. all those that might be affected
-by a change, and all those on which this promise depends.
-
-@image{impact,15cm}
-
-
-@node Can I see a score-card of compliance, Should I use menu driven configuration, How do I see what machines keep which promises, Top
-@unnumberedsec Can I see a score-card of compliance?
-
-@sp 1
-One reason people make lists is to be able to tick off the
-menu items to know when a job is complete. CFEngine allows
-you to measure whether all of the menu-promises have been
-kept, by viewing reports tied into the knowledge map.
-
-There is one crucial difference between system configuration
-and menus at a restaurant though: the order of the items in
-the menu does not always have to be preserved, and in fact it is very
-inefficient to use the menu as a strictly ordered list.
-Computer configuration can benefit greatly from parallel execution,
-and CFEngine is designed to parallelize tasks for greater efficiency.
-
-@cartouche
-We advise against designing systems that base their outcome on a
-strict ordering of promises. Although traditional programming methods
-teach us to think in terms of imperative ordering, you will succeed
-more effectively if you avoid it.
-@end cartouche
-
-
-@node Should I use menu driven configuration, , Can I see a score-card of compliance, Top
-@unnumberedsec Should I use menu driven configuration?
-
-@sp 1
-A menu driven approach is a good way of modelling a complex
-environment, with delegation. It is a form of knowledge management.
-It allows you to view your system through a kind of compliance
-scorecard.
-
-The idea of nesting layers of menus is similar to what has been
-advocated by Object Oriented programming languages for several
-years. However, OO also shows how you can go too far in creating deep
-and complex hierarchies that become impossible to understand. If you
-create too many levels, you invite inefficiency and complexity.
-
-We recommend keeping system organization simple, and avoiding
-dependence whenever it does not provide a compelling and tangible
-benefit.
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_MissionCritical.texinfo b/docs/guides/SpecialTopic_MissionCritical.texinfo
deleted file mode 100644
index 683d6d6358..0000000000
--- a/docs/guides/SpecialTopic_MissionCritical.texinfo
+++ /dev/null
@@ -1,804 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-critical.info
-@settitle CFEngine for Mission Critical Operations
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title CFEngine for Mission Critical Operations (draft)
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-As IT services dominate the operations of an increasing number of industries,
-many companies now view all online services as mission critical. Today, mission critical
-no longer just means the protection of human lives, but the protection of crucial
-operational assets.
-
-By making a fully redundant architecture for information
-updates, it is possible to make reliable promises about availability
-of status information. Users get reliable and predictable insight,
-with fault recovery times of only a few minutes in case of failure --
-something that cannot easily be matched by push-based centralization.
-
-This guide explains how to set up redundant hub availability for a single Nova
-star network.
-@end quotation
-@end cartouche
-
-@vskip 2cm
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2011 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-
-@node Top, What are Mission Critical Operations?, (dir), (dir)
-@top CFEngine for Mission Critical Operations
-@menu
-* What are Mission Critical Operations?::
-* Factors affecting Risk::
-* Model-based planning for stability::
-* Key terminology for Mission Critical Systems::
-* Strategy for Mission Critical Operations::
-* How CFEngine contributes to reducing mission risks::
-* High availability access to the Mission Portal::
-* Redundant hub architecture::
-* How do I make a change in mission-critical infrastructure?::
-* Separating Policy Changes from ad-hoc Changes::
-* Appendix 1::
-* Appendix 2::
-@end menu
-
-
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@node What are Mission Critical Operations?, Factors affecting Risk, Top, Top
-@unnumberedsec What are Mission Critical Operations?
-@sp 1
-
-Mission Critical operation refers to the use and management of systems
-where the availability and correctness of a system has to be ensured
-at all times. A mission is said to be critical when any noticable
-failure in the system would cause a signifiant loss to some
-stakeholder.
-
-Risk for mission critical systems deals with issues like monetary
-losses (e.g. in time critical trading applications) or, in the worst
-case, even the loss of human life (transport systems).
-
-What makes a system robust in a mission critical setting depends on a
-number of factors. This Special Topics Guide discusses the role of
-CFEngine in a mission critical environment.
-
-@node Factors affecting Risk, Model-based planning for stability, What are Mission Critical Operations?, Top
-@unnumberedsec Factors affecting Risk
-@sp 1
-
-Risk is about predictability. The ability to predict the behaviour of
-a system depends both on the complexity of the system itself and the
-environment around it, since interaction with the environment is what
-usually provokes failures (the environment is the most unpredictable
-element of any system, since it is the part over which we have little
-control).
-
-The cost of predicting and avoiding failures can be prohibitive in a
-purely manual regime but automated systems can do a lot to reduce
-costs. CFEngine can play a key role here in reducing the cost of
-maintaining system state, even in a rapidly changing environment.
-
-@sp 1
-@itemize
-@item Planning for eventualities.
-@item Verifying system correctness with sufficient frequency.
-@end itemize
-@sp 1
-
-@cartouche
-The key observation for dealing with mission criticality is that
-systems are dynamical entities. Most software systems only manage
-the static setup of hosts. CFEngine manages both the static
-resources and the run-time state.
-@end cartouche
-
-@node Model-based planning for stability, Key terminology for Mission Critical Systems, Factors affecting Risk, Top
-@unnumberedsec Model-based planning for stability
-@sp 1
-
-The key to handling mission criticality is to build a model of your
-critical scenario that is based on a prediction of behaviour. In
-science and engineering, this is something one does all the time
-(e.g. wind-tunnel studies), but in Computer Engineering, the methods
-of modelling are still quite undeveloped.
-In the nuclear power industry and space programmes, for instance,
-it is common to use formalized fault-analysis to avoid and secure
-against error.
-
-The purpose of a model is to describe expectations. If a model is
-sufficiently well conceived, it should be possible to identify key
-causal factors in the mission that bring about critical behaviour.
-
-@sp 1
-@cartouche
-CFEngine's methodology is based on the idea of promises: a promise
-being something that aims to alter our expectations of outcome in a
-postive way.
-@end cartouche
-@sp 1
-
-In CFEngine, you make promises about the factors that underpin the
-stability of your system, and CFEngine's task is to work on your
-behalf to keep those promises. Promises cannot be guaranteed `kept' at
-all times, especially in time-critical situations (such a guarantee
-would require infinite resources to maintain), but a known schedule of
-verification and repair allows us to bring a level of predictability
-to a system, within certain tolerances. This is a best-effort engineering
-definition of predictability.
-
-Examples of promises that you might want to include in a
-foundation for a mission critical system are things that
-bring trusted stability, e.g.
-@itemize
-@item Check that key processes and applications are running.
-@item Automated garbage collection that prevents a system from
-choking on its own biproducts.
-@item Scan for rootkits (security breaches) every few hours.
-@end itemize
-
-The economic aspect of mission criticality is key: the
-loss of a key application or subsystem for even a minute could result
-in loss of significant revenues in an online company, or the loss
-of flight systems for a few seconds could result in a plane losing
-control and crashing.
-
-
-@node Key terminology for Mission Critical Systems, Strategy for Mission Critical Operations, Model-based planning for stability, Top
-@unnumberedsec Key terminology for Mission Critical Systems
-@sp 1
-
-
-@table @i
-
-@item Mean Time Before Failure (MTBF)
-The average measured time between faults occurring on a system.
-Although this is a well established measurement in the theory of
-faults and errors, estimating this quantity is not without its challenges.
-
-
-@item Mean Time To Repair (MTTR)
-The average time it takes to repair a system after a failure has occurred.
-The type or meaning of repairs is not specified.
-
-@item Sampling frequency
-The rate at which we interact with the system in order to measure or
-repair it. According to Nyquist's theorem, we have to sample a system
-twice as fast as the rate at which we expect to detect an important change.
-
-@item Single point of failure
-Any point in the design of a system that would lead to complete
-failure if destroyed. There might be several `single points of failure'
-in a system. Single refers to the fact that it only takes the failure
-of one of these to cause the total breakdown of the system.
-For example, the axel, or a tyre on a car would be examples of single points
-of failure for the `driving system'.
-
-@end table
-
-
-
-
-@node Strategy for Mission Critical Operations, How CFEngine contributes to reducing mission risks, Key terminology for Mission Critical Systems, Top
-@unnumberedsec Strategy for Mission Critical Operations
-@sp 1
-
-There are many aspects to thinking about complete reliability of systems.
-
-@cartouche
-The main goal of any system is to seek predictability. Having clear
-and accurate expectations of a system helps to steer it in a low-risk direction.
-@end cartouche
-
-@noindent Usually these fall into a mixture of two categories:
-
-@table @i
-
-@item Redundancy
-Elimination of `single points of failure' when failure strikes.
-@item Avoidance
-Proactive maintainence to keep the system in a zone of low risk.
-@item Certainty of knowledge
-Knowing accurately what is going in a system can enable correct decisions
-to be made more quickly when something unexpected happens.
-@end table
-
-@noindent It is impossible to discuss a comprehensive list of points for ensuring
-reliability, but a few general principles come to mind:
-@itemize
-@item Maximize Mean Time Before Failure
-@item Minimize Mean Time To Repair
-@item Maximize the relevance of information from the system
-to mission goals.
-@item Separate procedures for handling change into those for intended change (planned changes to the mission) and unintended change (changes that should not happen in an ideal world), falling into two cases: expected (for which we have written policy to repair) and unexpected (incidents that are handled manually).
-
-@item Certainty about information returned by the system, with multiple confirmation.
-
-@item Graceful failure modes: failover servers, backups, automatic elasticity (e.g. cloud technology)
-
-@item Peak load handling. (Also called Long Tail events.)
-
-
-@item Design for self-correction (negative feedback controllers).
-This includes, low-impact of management overhead on the mission system to avoid
-cascade failure.
-
-@end itemize
-
-
-
-
-
-@node How CFEngine contributes to reducing mission risks, High availability access to the Mission Portal, Strategy for Mission Critical Operations, Top
-@unnumberedsec How CFEngine contributes to reducing mission risks
-@sp 1
-
-@itemize
-@item Automated monitoring and repair according to a policy model.
-
-@item Providing up to date knowledge about the system
-
-@item Automatic restoration of compliance with policy, with MTTR 2.5 minutes by default.
-
-@item Accuracy of knowledge: all data include running estimates of the certainty
-of the data.
-
-@item Automatic updates of statistics about the system, with continuous updating
-for accurate and up to date information with context
-
-@item Independence of infrastructure dependencies (network/cmdb)
-CFengine will continue to work even if the network communications
-are impaired.
-
-@end itemize
-
-
-@node High availability access to the Mission Portal, Redundant hub architecture, How CFEngine contributes to reducing mission risks, Top
-@unnumberedsec High availability access to the Mission Portal
-@sp 1
-
-CFEngine is designed to be a system that is resilient to failure.
-That, in fact, is the opposite of a high availability system,
-where failures are not supposed to occur at all.
-
-The Mission Portal has a role to play in Mission Criticality,
-as it is a single source of information, collected,
-categorized and calibrated for system engineers. Being a single
-source website, it is can also be regarded as a single point of
-failure from the point of view of a mission critical application.
-
-@cartouche
-The information in the mission portal is largely status information
-about systems. The content of the Mission Portal database is not in
-any way deterministic for the configured state of your IT system -- it
-is only a report of actual state, not a template for intended state. If the Mission
-Portal is `down' or unavailable, it does not in any way imply that the
-actual distributed system is down or that there is any fault.
-@end cartouche
-
-
-@menu
-* Setting up redundant monitoring hubs::
-@end menu
-
-@node Setting up redundant monitoring hubs, , High availability access to the Mission Portal, High availability access to the Mission Portal
-@unnumberedsubsec Setting up redundant monitoring hubs
-
-If information and insight into your IT system are indeed Mission
-Critical for you, it is possible to create a high availability access
-to the mission information in the portal.
-In general, we recommend a small amount of professional services to
-help set up such a system, as there are several details that need to
-be taken into account.
-
-The CFEngine star-network `hub' is the report aggregator for the CFEngine commercial edition (Nova/Enterprise).
-CFEngine commercial editions support multiple hubs for redundancy
-during reporting. By making a cluster of three (or more) hubs, you
-can ensure that reports will always be available and up to date, at
-the time-resolution promised by CFEngine.
-
-To set up redundant hubs, you will need three physical computers, or
-at least three virtual machines on different physical computers.
-The idea is to use the underlying technology of the MongoDB database
-to provide a replicated data store. If a single database server goes down
-a secondary replica can take over the role. The commercial editions
-of CFEngine interface with this database through @code{cf-hub},
-and this process can be made aware of the underlying replica technology
-in the database. The architecture is intended to be as simple as possible
-for the CFEngine user to employ.
-
-@sp 1
-@itemize
-
-@item Install each of the three systems with the Nova extension package for
-policy hubs.
-
-@item The MongoDB backend needs to be set up specially before standard bootstrapping
-of nodes in an high availability managed network. Alternatively, if you have already bootstrapped
-hosts, you can manually establish hub redundancy with a little database infrastructure work
-and some additional CFEngine configuration.
-
-To do this, configure the Mongo database to set up a minimal replica set. This underlying
-mechanism for automatic failover. For example, a configuration like the following should
-be typed into the mongo client on one of the hub machines. Text like the following
-example can be pasted directly into the mongo shell.
-
-@verbatim
-host$ mongo
-
-db.runCommand({"replSetInitiate" : {
-"_id" : "CFEngineNova",
-"members" : [
-{
-"_id" : 1,
-"host" : "10.10.10.1:27017"
-},
-{
-"_id" : 2,
-"host" : "10.10.10.2:27017"
-},
-{
-"_id" : 3,
-"host" : "10.10.10.3:27017"
-}
-]}})
-
-@end verbatim
-
-To bootstrap the Mongo DB replication you should follow the procedure
-from the @i{MongoDB Definitive Guide, O'Reilly}. An example is shown below,
-assuming the three IP addresses for the hubs have IP addresses
-10.10.10.1, 10.10.10.2, 10.10.10.2, we would arrange for the following
-CFEngine pseudo-code to be executed before bootstrapping any of the
-hubs:
-@verbatim
-
-commands:
-
- 10_10_10_1::
-
- /var/cfengine/bin/mongod --fork \
- --logpath /var/log/mongod.log \
- --dbpath $(sys.workdir)/state \
- --replSet CFEngineNova/10.10.10.2:27017
-
- 10._10_10_2|10_10_10_3::
-
- /var/cfengine/bin/mongod --fork \
- --logpath /var/log/mongod.log \
- --dbpath $(sys.workdir)/state \
- --replSet CFEngineNova/10.10.10.1:27017
-
-@end verbatim
-Although we write the above in CFEngine pseudo-code, these steps need to be
-carried out before boostrapping hosts, as the Mongo services need to
-be initialized before anything can be written to the database, and the
-bootstrapping of the license initialization writes information to be
-stored in Mongo. During a single hub installation, these steps
-can be automated, but bootstrapping the replication prevents
-a fully automated installation.
-
-
-@item Copy the public and private key from the licensed hub, along with the
-@file{license.dat} file to the secondary hubs.
-All hubs will share the same public-private key pair and license file.
-
-@item Start the @code{cf-hub} on each of the three machines.
-
-@end itemize
-
-@sp 1
-Next, we'll run through the operation and failure modes of the symmetric hubs.
-The arrangement of the hubs is shown schematically in the figure below.
-@sp 1
-@center @image{redundhubs,9cm,,,png}
-@sp 1
-@center Fig 1. Only one master hub at a time collects data in a symmetric cluster.
-@sp 1
-
-@node Redundant hub architecture, How do I make a change in mission-critical infrastructure?, High availability access to the Mission Portal, Top
-@unnumberedsec Redundant hub architecture
-
-To set up redundancy, you create three hubs, each running a Mongo
-database server and a @code{cf-hub} process will play the role of a
-virtual cluster. All three hosts make promises to one another to
-coordinate their data. The Mongo replica sub-system promises its own
-coordination independently. We essentially make three completely
-symmetrical hub hosts, with different IP addresses.
-
-@enumerate
-@item Set up three completely symmetrical hosts, with identical public-private key pairs.
-That is, generate a key pair only for one of the hubs and then copy those keys to
-@file{/var/cfengine/ppkeys/localhost.pub} and @file{/var/cfengine/ppkeys/localhost.priv}
-on the other two hosts. This must be done manually to bootstrap
-the hub redundancy.
-
-@item The underlying Mongo database infrastructure binds together these hosts into a small cluster called a replica set.
-
-
-A voting mechanism selects a `hub_master' from this set, which is going to be the active hub.
-
-@item Each host is configured to copy the public keys from all the
-others, so that they all converge on the same set of keys. The
-following snippet shows the main principles involved in a replica
-setup.
-
-@verbatim
-vars:
-
- "hub_hosts" slist => { "hub1", "hub2", "hub3" };
-
-files:
-
- am_policy_hub::
-
- "$(sys.workdir)/ppkeys"
- comment => "All hubs converge knowledge of client keys",
- copy_from => secure_cp("$(sys.workdir)/ppkeys","$(hub_hosts)"),
- depth_search => recurse("inf");
-
-@end verbatim
-
-@item For optimization we set up a policy that rewrites the IP address in @file{policy_server.dat},
-to point existing clients away from a hub that is no longer responding, to the current master
-or primary. Clients will initially pick up these changes by failing over, as in the previous point.
-
-@verbatim
-files:
-
- am_hub_master::
-
- "$(sys.workdir)/policy_server.dat"
- comment => "Point clients to the current hub master",
- edit_line => append_if_no_line("$(sys.hub_master)")
- edit_defaults => empty;
-
-@end verbatim
-
-
-@item To make the redundany hubs double as redundant policy servers, we make sure that
-the copying of policy in @file{update.cf} uses the replicas as failover servers
-for policy updates. This means that changes to policy should always be copied to
-@file{/var/cfengine/masterfiles} on all three hub hosts.
-
-@verbatim
-body copy_from update_copy
-{
-...
-servers => { $(sys.policy_server), "hub3", "hub2", "hub1" };
-...
-}
-@end verbatim
-The policy server variable will point to one of these hubs. If a hub
-host, doubling in its role as policy server, fails for some reason,
-the clients will all fail over to the next hub, and updates will
-continue. By the time this happens, we can expect the main policy will have been
-adjusted by the edit in the previous point, and clients will be pointed to a new
-primary. It does not matter that hosts appear twice in the list; we
-could, for instance place @code{hub1} last in the list if we assume
-that hub1 is the initial primary, so as to minimize the wait due to a
-double-failover.
-
-
-@end enumerate
-
-@sp 1
-@cartouche
-With this configuration, all the hubs promise to synchronize their keys,
-and share `last seen' client host data with each other in order to symmetrize.
-However, only one of the hubs actually collected reports from the clients.
-This is the host that is elected by the MongoDB replica-set vote.
-@end cartouche
-@sp 1
-
-With the approach taken above we can be sure that data are being collected redundantly
-without duplication of network overhead.
-
-Note that the standard Nova configuration files contains example
-configurations for the replica set configuration. Integrating all the
-settings can require extensive modifications, as mentioned above.
-
-
-@menu
-* Features of hub/policy server redundancy::
-* Variables and classes for hubs::
-@end menu
-
-@node Features of hub/policy server redundancy, Variables and classes for hubs, Redundant hub architecture, Redundant hub architecture
-@unnumberedsubsec Features of hub/policy server redundancy
-
-The Nova starburst hub configuration supports the following properties:
-@itemize
-@item Redundant availability of policy changes, with automatic failover.
-@item Redundant responsibility for report collection from managed hosts, with automatic reassignment of hub master.
-@item Redundant availability for the Mission Portal console, with about 15 second changeover.
-@item Fault tolerance of all parts of CFEngine to complete network failure.
-@end itemize
-
-@node Variables and classes for hubs, , Features of hub/policy server redundancy, Redundant hub architecture
-@unnumberedsubsec Variables and classes for hubs
-
-CFEngine Nova/Enterprise supports special classes to help write policy
-for managing the hub infrastructure.
-@verbatim
-
-am_policy_hub
-am_hub_master
-
-@end verbatim
-
-The variable @samp{$(sys.hubmaster)} is also available @i{on hosts that are
-hubs}, and points to that host currently voted into the role of hub master.
-
-@sp 1
-
-@cartouche
-Setting up redundant hubs might be best done with some professional
-service assistance. Although it is quite simple, it changes the
-bootstrapping procedure in the beginning of a Nova/Enterprise
-deployment.
-@end cartouche
-
-
-@node How do I make a change in mission-critical infrastructure?, Separating Policy Changes from ad-hoc Changes, Redundant hub architecture, Top
-@unnumberedsec How do I make a change in mission-critical infrastructure?
-@sp 1
-
-To make changes in a mission critical environment, you publish a fully
-tested, risk-assessed policy to @file{/var/cfengine/masterfiles} on
-all three of the hubs in the cluster. The policy on all hubs should be
-the synchronized. It might be worth setting up a promise to verify
-that the contents of these directories are the same between all hubs,
-since unsychronized policies could cause serious issues.
-
-@verbatim
-vars:
-
- "hubs" slist => { "hub1", "hub2", "hub3" };
-
-files:
-
- "$(sys.workdir)/masterfiles"
-
- copy_from => secure_cp("$(sys.workdir)/masterfiles","$(hubs)"),
- action => warn;
-
-@end verbatim
-
-All changes to a mission critical system should be classified
-according to the level of risk to the mission. Changes fall into
-different categories.
-
-@itemize
-@item Regular routine maintenance to the system (preplanned).
-@item Course or goal corrections to policy (replanned).
-@item Unforeseen repairs (unplanned).
-@end itemize
-
-In each case, we recommend that changes be made using CFEngine's
-hands-free automation. Humans should never be the instruments of
-change. By using CFEngine, you can get a documented and predictable
-handle on change, using technology designed for stability with agility.
-
-CFEngine has the ability to change entire systems of thousands of
-hosts within a timeframe of 5 to 10 minutes.
-
-@node Separating Policy Changes from ad-hoc Changes, Appendix 1, How do I make a change in mission-critical infrastructure?, Top
-@unnumberedsec Separating Policy Changes from @i{ad-hoc} Changes
-@sp 1
-
-In mission critical environments, there are often struct processes for
-approving change. Unintelligently applied, such rules can do more harm
-than good -- i.e. when the process for approving changes causes
-greater risk to the survival of the mission than not acting at all does. It
-is important to separate changes into categories that allow the
-minimization of risk. If we take the categories in the previous
-section:
-
-@table @i
-@item Regular routine maintenance to the system (preplanned).
-Changes here have alredy gone through risk assessment, and root cause has been
-deemed understood or irrelevant. These changes should be automated and implemented
-in the minimum time. e.g. restarting a web server that crashed or was stopped accidentally.
-
-@item Course or goal corrections to policy (replanned).
-This is a change in the mission plan and requires significant impact analysis
-for each change. Although many businesses are concerned about liabilities, the
-real aim of this analysis is to mitigate loss.
-
-@item Unforeseen repairs (unplanned).
-These changes are usually discovered and repaired manually. Once some kind
-of root cause analysis is performed to the required level, there should be
-an analysis of how to automate the prevention of this kind of change in the
-future.
-
-@end table
-
-
-@sp 2
-@cartouche
-
-This is a partially finished Special Topics Guide, in which additional material
-can be expected at a later date. It is made available in its current
-form for your convenience.
-
-@end cartouche
-
-
-@page
-@node Appendix 1, Appendix 2, Separating Policy Changes from ad-hoc Changes, Top
-@unnumberedsec Appendix MongoDB access from the command line.
-
-
-
-
-@cartouche
-@b{Using more than one hub at a time}:
-If you want to be able to perform queries on any one of the redundant
-hosts, not only the master, then it's necessary to set a flag on each
-of the running mongo servers (master and slave):
-@verbatim
-host$ mongo
-
-rs.slaveOk();
-@end verbatim
-This ensures that updates are synchonrized for querying.
-e.g. In this example we see the first query fail, and the second
-succeed after setting the flag:
-@verbatim
-CFEngineNova:SECONDARY> use cfreport
-switched to db cfreport
-
-CFEngineNova:SECONDARY> db.notebook.find();
-error: { "$err" : "not master and slaveok=false", "code" : 13435 }
-
-CFEngineNova:SECONDARY> db.notebook.find();
-CFEngineNova:SECONDARY> rs.slaveOk();
-not master and slaveok=false
-CFEngineNova:SECONDARY> db.notebook.find();
-{ "_id" : ObjectId("4e5cd788d5d6b92c00000000"),
-"_kh" : "SHA=9e9ad21d192fa...1635",
-"_rD" : "0 : 10.10.160.115", "_t" : 1, "n" : [
- {
- "u" : "admin",
- "m" : "This machine is a web server",
- "d" : 319944880
- }
-] }
-
-@end verbatim
-@end cartouche
-
-
-
-@page
-@node Appendix 2, , Appendix 1, Top
-@unnumberedsec Appendix Shutting down Mongo with replication
-
-
-Anytime you shutdown mongo, it will automatically failover. You can~t
-specifically tell which node to become primary, but you can use
-replFreeze and replSetStepDown to alter which is eligible to become
-primary (small difference).
-
-Basically we would freeze a node from becoming primary, then tell the
-primary to step down, which leaves only one node (see
-@url{http://www.mongodb.org/display/DOCS/Forcing+a+Member+to+be+Primary} for
-a good explanation).
-
-However, failover is the easy part. The other half to the action is
-that all client will receive a new policy_server.dat based on the new
-primary. This will create quite a flux in the system for a bit as it
-reconfigure. This will take 10-20 minutes for everyone to stabilize. I
-would reserve a full failover for when the primary will be down for an
-extended period of time.
-
-Since the outages you have are fairly quick, I would just shutdown
-mongo/cfengine (or freeze) the secondaries to prevent a
-failover. Shutting them down would prevent all client from getting new
-files, but that shouldn~t be an issue.
-
-If you freeze the secondaries, and leave CFE runnning, the clients
-will update from the secondaries (they will get a license error).
-
-To freeze the secondaries:
-
-On any node:
-@verbatim
-# mongo -host `IP OF THE SECONDARY' # or login to the node and run plain ´mongo¡.
-> rs.status() # this will show the status of the replicaSet
-> rs.freeze(seconds) # how many seconds before the host can become primary.
-> exit
-@end verbatim
-
-Set the freeze for several hours (for four hours -
-@samp{rs.freeze(14400)}). Then shutdown cfengine on the primary as normal
-(@code{/etc/init.d/cfengine3 stop}). When you are done with the change, bring
-up cfengine (@code{cf-agent -f failsafe.cf}), then set the freeze time for 0
-seconds to unfreeze it (@samp{rs.freeze(0)}).
-
-
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_Modules.texinfo b/docs/guides/SpecialTopic_Modules.texinfo
deleted file mode 100644
index 29446e3692..0000000000
--- a/docs/guides/SpecialTopic_Modules.texinfo
+++ /dev/null
@@ -1,1774 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-orchestrate.info
-@settitle Modularizing and Orchestrating System Policy
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Modularizing and Orchestrating System Policy
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-CFEngine is a descriptive framework for promising system state. It has
-a language interface and a graphical interface, and supports a number
-of levels of expression and abstraction.
-
-Ordering of operations is less important than you probably think. We
-are taught to think of computing as an linear sequence of steps, but
-this ignores a crucial fact about distributed systems: that many parts
-are independent of each other and exist in parallel. Nevertheless
-there are cases of strong inter-dependency where order and modularity
-are important.
-
-This guide explains the many freedoms within CFEngine's Promise Model
-for modularizing, ordering and making black, grey and white boxes. This allows us to
-retain all of the important advantages of promises (autonomy,
-convergence, atomicity etc) that lead to scalable predictability in
-huge networks.
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2009 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-
-
-@node Top, What is modularity?, (dir), (dir)
-@top Orchestration
-
-@menu
-* What is modularity?::
-* What is orchestration?::
-* How does CFEngine deal with modularity and orchestration?::
-* Levels of policy abstraction::
-* Is CFEngine patch or package oriented?::
-* High level services in CFEngine::
-* Hiding details::
-* Black grey and white box encapsulation in CFEngine::
-* Bulk operations are handled by repeating patterns over lists::
-* Ordering operations in CFEngine::
-* Bundle ordering::
-* Overriding order::
-* Distributed Orchestration between hosts with CFEngine Enterprise::
-@end menu
-
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-
-
-@node What is modularity?, What is orchestration?, Top, Top
-@unnumberedsec What is modularity?
-
-@sp 1
-Modularity is the ability to separate concerns within a total process, and hide
-the details of the different concerns in different containers. In CFEngine, this is a
-@i{service oriented view}, in which different aspects of a problem are
-separated and turned into generic components that offer a service. We
-often talk about black boxes, grey boxes or white boxes depending on
-the extent to which the user of a service can see the details within
-the containers.
-
-@node What is orchestration?, How does CFEngine deal with modularity and orchestration?, What is modularity?, Top
-@unnumberedsec What is orchestration?
-
-@sp 1
-Orchestration is the ability to coordinate many different processes in
-time and space, around a system, so that the sum of those processes
-yields a harmonious result through cooperation.
-
-Orchestration is not about centralized control, though this is common
-misperception. An orchestra does not manage to play a symphony
-because the conductor pulls every player's strings or blows every
-trumpet in person, but rather because each @i{autonomous} player has a
-copy of the script, knows what to do, and can use just the little
-additional information from the conductor to access a viewpoint that
-is not available to an individual. An orchestra is a weakly coupled
-expert system in which the management (conductor) provides a service
-to the players.
-
-CFEngine works like an orchestra -- this is why is scales so well.
-Each computer is an autonomous entity, getting its script and a few
-occasional pieces of information from the policy server (conductor).
-The coupling between the agents is weak -- there is slack that makes
-the behaviour robust to minor errors in communication or timing.
-
-@node How does CFEngine deal with modularity and orchestration?, Levels of policy abstraction, What is orchestration?, Top
-@unnumberedsec How does CFEngine deal with modularity and orchestration?
-
-Promise Theory provides simple principles for hiding details: agents are
-considered to reveal a kind of @i{service interface} to peers, that is
-advertised by making a promise to someone. We assume an agent exerts
-best effort in keeping its promises. Orchestration requires a promise
-to coordinate and the promise to use that coordination service.
-These basic ideas are built into CFEngine.
-
-CFEngine provides containers called @i{bundles} for creating modular
-parts. Bundles can be independent (and therefore parallelizable)
-or they can be dependent (in which case the sequence in which they
-verify their promises matters).
-
-In a computer centre with many different machines, there is an
-additional dimension to orchestration -- multiple orchestras. Each
-machine has a number of resources that need to be orchestrated, and
-the different machines themselves might also need to cooperate because
-they provide services to one another. The principles are the same in
-both cases, but the confusion between them is typically the reason why
-large systems do not scale well.
-
-@node Levels of policy abstraction, Is CFEngine patch or package oriented?, How does CFEngine deal with modularity and orchestration?, Top
-@unnumberedsec Levels of policy abstraction
-
-CFEngine offers a number of layers of abstraction. The most fundamental atom
-in CFEngine is the promise. Promises can be made about many system issues,
-and you described in what context promises are to be kept.
-
-@table @i
-@item Menu level
-At this high level, a user `selects' from a set of pre-defined `services' (or bundles in CFEngine parlance).
-In commercial editions, users may view the set of services as a Service Catalogue, from which each
-host selects its roles. The selection is not made by every host, rather one places hosts into roles that
-will keep certain promises, just as different voices in an orchestra are assigned certain parts to play.
-
-@cartouche
-@smallexample
-bundle agent service_catalogue # menu
-@{
-methods:
- any:: # selected by everyone
- "everyone" usebundle => @b{time_management},
- comment => "Ensure clocks are synchronized";
- "everyone" usebundle => garbage_collection,
- comment => "Clear junk and rotate logs";
-
- mailservers:: # selected by hosts in class
- "mail server" -> @{ "goal_3", "goal_1", "goal_2" @}
- usebundle => @b{app_mail_postfix},
- comment => "The mail delivery agent";
- "mail server" -> goal_3,
- usebundle => @b{app_mail_imap},
- comment => "The mail reading service";
- "mail server" -> goal_3,
- usebundle => @b{app_mail_mailman},
- comment => "The mailing list handler";
-@}
-@end smallexample
-@end cartouche
-
-The resulting menu of services can be browsed in the Mission Portal interface.
-@float
-@sp 1
-@center @image{service_catalogue,15cm,,iso,png}
-@center A human-readable Service Catalogue generated from technical specifications
-@center shows what goals are being attended to automatically
-@sp 1
-@end float
-
-
-@item Bundle level
-At this level, users can switch on and off predefined features, or re-use
-standard methods, e.g. for editing files:
-
-@cartouche
-@verbatim
-body common control
-{
-bundlesequence => {
- webserver("on"),
- dns("on"),
- security_set("on"),
- ftp("off")
- };
-}
-@end verbatim
-@end cartouche
-The set of bundles that can be selected from is extensible by the user.
-
-@item Promise level
-This is the most detailed level of configuration, and gives full
-@i{convergent} promise behaviour to the user. At this promise level,
-you can specificy every detail of promise-keeping behaviour, and
-combine promises together, reusing bundles and methods from standard
-libraries, or creating your own.
-
-@cartouche
-@smallexample
-bundle agent addpasswd
-@{
-vars:
-
- # want to set these values by the names of their array keys
-
- "pwd[mark]" string => "mark:x:1000:100:Mark B:/home/mark:/bin/bash";
- "pwd[fred]" string => "fred:x:1001:100:Right Said:/home/fred:/bin/bash";
- "pwd[jane]" string => "jane:x:1002:100:Jane Doe:/home/jane:/bin/bash";
-
-files:
-
- "/etc/passwd" # Use standard library functions
- create => "true",
- comment => "Ensure listed users are present",
- perms => mog("644","root","root"),
- edit_line => append_users_starting("addpasswd.pwd");
-
-@}
-@end smallexample
-@end cartouche
-
-@item Spread-sheet level (data-driven)
-
-CFEngine commercial editions support a kind of spreadsheet. In a spreadsheet
-approach, you create only the data to be inserted into predefined
-promises. The data are entered in tabular form, and may be browsed in
-the web interface. This form of entry is preferred in some
-environments, especially on the Windows platform.
-
-
-@end table
-
-
-
-
-@node Is CFEngine patch or package oriented?, High level services in CFEngine, Levels of policy abstraction, Top
-@unnumberedsec Is CFEngine patch-oriented or package-oriented?
-
-Some system management products are patching systems. They package lumps
-of software and configuration along with scripts. If something goes wrong
-they simply update or replace the package with a new one. This is a patching
-model of system installation, but it is not a good model for repair as it nearly
-always leads to interruption of service or even requires a reboot.
-
-Installation of packages overwrites too much data in one go to be an effective model
-of simple repair@footnote{Sometimes it is desirable to reinstall an entire package, but normally this is only true
-for software upgrades. CFEngine has an interface for working in concert with local
-package managers (RPM,DEB,MSI, etc).}. It can be both ineffecient and destructive. CFEngine manages addressable
-entities at the lowest possible level so that ultra-fine-grained repair can be
-performed with no interruption of service, e.g. altering a field within a line in a file,
-or restarting one process, or altering one bit of a flag in each file in a set of directories.
-The power to express sophisticated patterns is what makes CFEngine's approach both
-non-intrusive and robust.
-
-@node High level services in CFEngine, Hiding details, Is CFEngine patch or package oriented?, Top
-@unnumberedsec High level services in CFEngine
-
-CFEngine is designed to handle high level simplicity (without
-sacrificing low level capability) by working with configuration
-@i{patterns}, after all configuration is all about promising
-consistent patterns of system @i{state} in the resources of the
-system. Lists, for instance, are a particularly common kind of
-pattern: @i{for each of the following... make a similar promise}.
-There are several ways to organize patterns, using containers, lists
-and associative arrays. Let's look at how to configure a number of
-application services.
-
-
-At the simplest or highest level, we can turn services into "genes"
-to switch on and off on your basic "stem cell" machines.
-
-@verbatim
-body agent control
-{
-bundlesequence => {
- webserver("on"),
- dns("on"),
- security_set("on"),
- ftp("off")
- };
-}
-@end verbatim
-
-This obviously looks simple, but this kind of simplicity is cheating
-as we are hiding @i{all} the details of what is going to happen -- we
-don't know if they are hard-coded, or whether we can decide
-ourselves. Anyone can play that game! The true test is whether we can
-retain the power to decide the low-level details without having to
-program in a low level language like Ruby, Python or Perl. Let's peel
-back some of the layers, knowing that we can hide as many of the
-details as we like.
-
-
-A simple, but low level approach to deploying a service, that veteran
-users will recognize, is the following. This is a simple example of
-orchestration between a promise to raise a signal about a missing process and
-another promise to restart said process once its absence has been
-discovered and signalled.
-
-@verbatim
-bundle agent application_services
-{
-processes:
-
- "sshd" restart_class => "start_ssh";
- "httpd" restart_class => "start_spache";
-
-commands:
-
- start_ssh::
- "/etc/init.d/sshd restart";
-
- start_apache::
- "/etc/init.d/apache restart";
-
-}
-@end verbatim
-
-But the first thing we see is that there is a repeated pattern, so we could
-rewrite this as a single promise for a list of services, at the cost of a loss
-of transparency. However, this is the power of abstraction.
-
-@page
-@verbatim
-bundle agent application_services
-{
-vars:
-
- "service" slist => { "ssh", "apache", "mysql" };
-
- #
- # Apply the following promises to this list...
- #
-
-services:
-
- "$(service)";
-
-}
-@end verbatim
-
-@node Hiding details, Black grey and white box encapsulation in CFEngine, High level services in CFEngine, Top
-@unnumberedsec Hiding details
-
-Resource abstraction, or hiding system specific details inside a kind of
-grey-box, is just another service as far as CFEngine is concerned -- and we
-generally map services to bundles.
-
-Many system variables are discovered automatically by CFEngine and provided
-"out of the box", e.g. the location of the filesystem table might be @code{/etc/fstab},
-or @code{/etc/vfstab} or even @code{/etc/filesystems}, but CFEngine allows you to
-refer simply to @code{$(sys.fstab)}. Soft-coded abstraction needs cannot
-be discovered by the system however.
-So how do we create this mythical resource abstraction layer? It is
-simple. Elsewhere we have defined basic settings.
-
-@page
-@verbatim
-bundle common res # abstraction layer
-{
-vars:
-
- solaris::
-
- "cfg_file[ssh]" string => "/etc/sshd_config";
- "daemon[ssh] " string => "sshd";
- "start[ssh] " string => "/etc/init.d/sshd restart";
-
- linux.SuSE::
-
- "cfg_file[ssh]" string => "/etc/ssh/sshd_config";
- "daemon[ssh] " string => "sshd";
- "start[ssh] " string => "/etc/init.d/sshd restart";
-
- default::
-
- "cfg_file[ssh]" string => "/etc/sshd_config";
- "daemon[ssh] " string => "sshd";
- "start[ssh] " string => "/etc/init.d/sshd restart";
-
-classes:
-
- "default" and => { "!SuSE", "solaris" };
-}
-@end verbatim
-
-
-Some of the attempts to recreate a CFEngine-like tool try to hard code
-many decisions, meaning that minor changes in operating system versions
-require basic recoding of the software. CFEngine does not make decisions
-for you without your permission.
-
-
-@node Black grey and white box encapsulation in CFEngine, Bulk operations are handled by repeating patterns over lists, Hiding details, Top
-@unnumberedsec Black, grey and white box encapsulation in CFEngine
-
-CFEngine's ability to abstract system decisions as promises also
-applies to bundles of promises. After all, we can package promises
-as bumper compendia for grouping together related matters in
-a single package. Naturally, CFEngine never abandons its insistence
-on convergence, merely for the sake of making things look
-simple. Using CFEngine, you can create convergent orchestration.
-
-@verbatim
-bundle agent services
-{
-vars:
- "service" slist => { "dhcp", "ntp", "sshd" };
-methods:
- "any" usebundle => fix_service("$(service)"),
- comment => "Make sure the basic application services are running";
-}
-@end verbatim
-The code above is all you really want to see. The rest can be hidden in libraries that
-you rarely look at. In CFEngine, we want the intentions to shine forth and the
-low level details to be clear on inspection, but hidden from view.
-
-We can naturally modularize the packaged bundle of fully convergent
-promises and keep it as library code for reuse. Notice that
-CFEngine adds comments in the code that follow processes through
-execution, allowing you to see the full intentions behind the
-promises in logs and error messages. In commercial versions, you can
-trace these comments to see your process details.
-
-@verbatim
-bundle agent fix_service(service)
-{
-files:
-
- "$(res.cfg_file[$(service)])"
-
- #
- # reserved_word => use std templates, e.g. cp(), p(), or roll your own
- #
- copy_from => cp("$(g.masterfiles)/$(service)","policy_host.mydomain"),
- perms => p("0600","root","root"),
- classes => define("$(service)_restart", "failed"),
- comment => "Copy a stock configuration file template from repository";
-
-processes:
-
- "$(res.daemon[$(service)])"
-
- restart_class => canonify("$(service)_restart"),
- comment => "Check that the server process is running...";
-
-commands:
-
- "$(res.start[$(service)])"
-
- comment => "Method for starting this service",
- ifvarclass => canonify("$(service)_restart");
-
-}
-
-@end verbatim
-
-@node Bulk operations are handled by repeating patterns over lists, Ordering operations in CFEngine, Black grey and white box encapsulation in CFEngine, Top
-@unnumberedsec Bulk operations are handled by repeating patterns over lists
-
-
-The power of CFEngine is to be able to handle lists of similar
-patterns in a powerful way. You can also wrap the whole experience in
-a method-bundle, and we can extend this kind of pattern to
-implement other interfaces, all without low level programming.
-
-@page
-@verbatim
-#
-# Remove certain services from xinetd - for system hardening
-#
-
-bundle agent linux_harden_methods
-{
-vars:
-
- "services" slist => {
- "chargen",
- "chargen-udp",
- "cups-lpd",
- "finger",
- "rlogin",
- "rsh",
- "talk",
- "telnet",
- "tftp"
- };
-methods:
-
- #
- # for each $(services) in @(services) do disable_xinetd($(services))
- #
-
- "any" usebundle => disable_xinetd("$(services)");
-}
-@end verbatim
-
-
-
-In the library of generic templates, we may keep one or more methods for implementing
-service disablement. For example, this simple interface to Linux's @code{chkconfig}
-is one approach, which need not be hard-coded in Ruby using Cfeninge.
-
-@verbatim
-#
-# For the standard library
-#
-
-bundle agent disable_xinetd(name)
-{
-vars:
- "status"
-
- string => execresult("/sbin/chkconfig --list $(name)", "useshell");
-
-classes:
- "on" expression => regcmp(".*on","$(status)");
- "off" expression => regcmp(".*off","$(status)");
-
-commands:
- on::
- "/sbin/chkconfig $(name) off",
- comment => "disable $(name) service";
-
-reports:
- on::
- "disable $(name) service.";
- off::
- "$(name) has been already disabled. Don't need to perform the action.";
-
-}
-@end verbatim
-
-@node Ordering operations in CFEngine, Bundle ordering, Bulk operations are handled by repeating patterns over lists, Top
-@unnumberedsec Ordering operations in CFEngine
-
-Ordering of operations is less important than you probably
-think. We are taught to think of computing as an linear sequence of
-steps, but this ignores a crucial fact about distributed systems: that
-many parts are independent of each other and exist in parallel.
-
-Nevertheless there are sometimes cases of strong inter-dependency
-(that we strive to avoid, as they lead to most of the difficulties of
-system management) where order @i{is} important. In re-designing
-CFEngine, we have taken a pragmatic approach to ordering. Essentially,
-CFEngine takes care of ordering for you for most cases -- and you can
-override the order in three ways:
-
-@itemize
-@item CFEngine checks promises of the same type in the order in which they are defined, unless overridden
-@item Bulk ordering of composite promises (called bundles) is handled using an overall list using the bundlesequence (replaces the actionsequence in previous CFEngines)
-@item Dependency coupling through dynamic classes, may be used to guarantee ordering in the few cases
-where this is required, as in the example below:
-@end itemize
-
-@node Bundle ordering, Overriding order, Ordering operations in CFEngine, Top
-@unnumberedsec Bundle ordering
-
-There are two methods, working at different levels.
-At the top-most level there is the master @code{bundlesequence}
-
-@sp 1
-@verbatim
-body common control
-{
-bundlesequence => { "bundle_one", "bundle_two", "bundle_three" };
-}
-@end verbatim
-@sp 1
-@noindent For simple cases this is good enough, but the main
-purpose of the bundlesequence is to easily be able to switch on
-or off bundles by commenting them out.
-
-A more flexible way of ordering bundles is to wrap the ordered process
-in a master-bundle. Then you can create new sequences of bundles
-(parameterized in more sophisticated ways) using @code{methods}
-promises. Methods promises are simply promises to re-use bundles,
-possibly with different parameters.
-
-The default behaviour is to retain the order of these promises; the effect
-is to `execute' these bundles in the assumed order:
-@sp 1
-@verbatim
-bundle agent a_bundle_subsequence
-{
-methods:
- classes::
- "any" usebundle => bundle_one("something");
- "any" usebundle => bundle_two("something");
- "any" usebundle => bundle_three("something");
-
-}
-@end verbatim
-@sp 1
-@noindent Alternatively, the same effect can be achieved as follows.
-@sp 1
-@verbatim
-bundle agent a_bundle_subsequence
-{
-methods:
- classes::
- "any" usebundle => generic_bundle("something","one");
- "any" usebundle => generic_bundle("something","two");
- "any" usebundle => generic_bundle("something","three");
-
-}
-@end verbatim
-@sp 1
-@noindent Or ultimately:
-@sp 1
-@verbatim
-bundle agent a_bundle_subsequence
-{
-vars:
- "list" slist => { "one", "two", "three"};
-
-methods:
- classes::
- "any" usebundle => generic_bundle("something","$(list)");
-
-}
-@end verbatim
-
-
-@page
-@node Overriding order, Distributed Orchestration between hosts with CFEngine Enterprise, Bundle ordering, Top
-@unnumberedsec Overriding order
-
-CFEngine is designed to handle non-deterministic events, such as
-anomalies and unexpected changes to system state, so it needs to
-adapt. For this, there is no deterministic solution and approximate
-methods are required. Nevertheless, it is possible to make CFEngine
-sort out dependent orderings, even when confounded by humans, as in
-this example:
-
-@verbatim
-bundle agent order
-
-{
-vars:
-
- "list" slist => { "three", "four" };
-
-commands:
-
- ok_later::
- "/bin/echo five";
-
- any::
-
- "/bin/echo one" classes => define("ok_later");
- "/bin/echo two";
- "/bin/echo $(list)";
-
-}
-
-@end verbatim
-
-@noindent The output of which becomes:
-@verbatim
-Q: ".../bin/echo one": one
-Q: ".../bin/echo two": two
-Q: ".../bin/echo three": three
-Q: ".../bin/echo four": four
-Q: ".../bin/echo five": five
-@end verbatim
-
-
-
-@node Distributed Orchestration between hosts with CFEngine Enterprise, , Overriding order, Top
-@unnumberedsec Distributed Orchestration between hosts with CFEngine Enterprise
-
-CFEngine Enterprise edition adds many powerful features to CFEngine, including
-a decentralized approach to coordinating activities across multiple
-hosts. Some tools try to approach this by centralizing data from the
-network in a single location, but this has two problems:
-
-@itemize
-@item It leads to a bottleneck by design that throttles performance seriously.
-@item It relies on the network being available.
-@end itemize
-
-With CFEngine Nova there are are both decentralized network approaches
-to this problem, and probabilistic methods that do not require the network
-at all.
-
-@menu
-* Basic communication methods for orchestration::
-* Run job or reboot only if n out m systems are running::
-* The self-healing chain - inverse Dominoes::
-* A Domino sequence::
-* A Chinese Dragon::
-@end menu
-
-@node Basic communication methods for orchestration, Run job or reboot only if n out m systems are running, Distributed Orchestration between hosts with CFEngine Enterprise, Distributed Orchestration between hosts with CFEngine Enterprise
-@unnumberedsubsec Basic communication methods for orchestration
-
-The two examples below illustrate the basic syntax constructions for
-communication using systems. We can pass class data and variable data between
-systems in a peer to peer fashion, or through an Enterprise hub. You can
-run these with a server and an agent just on localhost to illustrate the
-principles.
-
-In this first example, three persistent classes, with names following
-a known pattern are defined on a remote system (by the agent). The
-server bundle then grants access to these using an access
-promise. Finally, a function call to @code{remoteclassesmatching}
-imports the classes, with a prefix to the local system.
-
-@verbatim
-
-body common control
-{
-bundlesequence => { "overture" };
-inputs => { "cfengine_stdlib.cf" };
-}
-
-body server control
-
-{
-allowconnects => { "127.0.0.1" , "::1",};
-allowallconnects => { "127.0.0.1" , "::1", };
-trustkeysfrom => { "127.0.0.1" , "::1",};
-}
-
-#######################################################
-
-bundle agent overture
-{
-classes:
- "extended_context"
- expression => remoteclassesmatching(".*did.*","127.0.0.1","yes","got");
-
-files:
-
- "/etc/passwd"
- create => "true",
- classes => set_outcome_classes;
-
-
-reports:
-
- got_did_task_one::
- "task 1 complete";
-
- extended_context.got_did_task_two::
- "task 2 complete";
-
- extended_context.got_did_task_three::
- "task 3 complete";
-
-}
-
-body classes set_outcome_classes
-{
-promise_kept => { "did_task_one","did_task_two", "did_task_three" };
-promise_repaired => { "did_task_one","did_task_two", "did_task_three" };
-#cancel_kept => { "did_task_one" };
-persist_time => "10";
-}
-
-bundle server access_rules()
-{
-access:
-
- "did.*"
- resource_type => "context",
- admit => { "127.0.0.1" };
-
-}
-
-@end verbatim
-@noindent The output of this, on success is simply:
-@smallexample
-
-R: task 1 complete
-R: task 2 complete
-R: task 3 complete
-
-@end smallexample
-
-
-@noindent In this second example, we pass actual variable data between hosts.
-The generic peer function @code{remotescalar} can address any other host
-running @code{cf-serverd}. The abbreviated interface @code{hubknowledge}
-assumes that it should get data from a hub.
-
-Both these functions ask for an identifier; it is up to the server to interpret
-what this means and to return a value of its choosing. If the identifier matches
-a persistent scalar variable (such as is used to count distributed processes in CFEngine
-Enterprise) then this will be returned preferentially. If no such variable is found,
-then the server will look for a literal string in a server bundle with a handle that
-matches the requested object.
-
-
-
-@verbatim
-
-body common control
-{
-bundlesequence => { "overture" };
-inputs => { "cfengine_stdlib.cf" };
-}
-
-body server control
-
-{
-allowconnects => { "127.0.0.1" , "::1",};
-allowallconnects => { "127.0.0.1" , "::1", };
-trustkeysfrom => { "127.0.0.1" , "::1",};
-}
-
-#######################################################
-
-bundle agent overture
-{
-vars:
-
- "remote" string => remotescalar("test_scalar","127.0.0.1","yes");
-
- "know" string => hubknowledge("test_scalar");
-
- "count_getty" string => hubknowledge("count_getty");
-
-processes:
-
- # Use the enumerated library body to count hosts running getty
-
- "getty"
-
- comment => "Count this host if a job is matched",
- classes => enumerate("count_getty");
-
-reports:
-
- !elsewhere::
-
- "GOT remote scalar $(remote)";
- "GOT knowedge scalar $(know)";
- "GOT persistent scalar $(xyz)";
-
-}
-
-#######################################################
-
-bundle server access_rules()
-{
-access:
-
- "value of my test_scalar, can expand variables here - $(sys.host)"
- handle => "test_scalar",
- comment => "Grant access to contents of test_scalar VAR",
- resource_type => "literal",
- admit => { "127.0.0.1" };
-
- "XYZ"
- resource_type => "variable",
- handle => "XYZ",
- admit => { "127.0.0.1" };
-
-}
-@end verbatim
-
-@noindent You can run this example on a single host, running the server, the agent and the hub (if you have Enterprise CFEngine).
-The output will be something like this:
-@smallexample
-
-host$ ./cf-agent -f ~/test.cf -K
-R: GOT remote scalar value of my test_scalar, can expand variables here - cflu-10004
-R: GOT knowedge scalar value of my test_scalar, can expand variables here - cflu-10004
-R: GOT persistent scalar 1
-
-@end smallexample
-
-
-
-@node Run job or reboot only if n out m systems are running, The self-healing chain - inverse Dominoes, Basic communication methods for orchestration, Distributed Orchestration between hosts with CFEngine Enterprise
-@unnumberedsubsec Run job or reboot only if n out m systems are running
-
-
-The ability to base local promises on global knowledge seems
-superficially attractive in some cases. As a strategy this way of
-thinking requires a lot of caution. We have to assume that all
-knowledge gathered about an environment is subject to errors,
-latencies and a dozen other uncertainties that make any snapshot of
-remotely assessed current state subject to considerable healthy
-suspicion. This is not a weakness of CFEngine -- in fact CFEngine has
-mechanisms that make it as reliable as you are likely to find in any
-technology -- rather it is a fundamental limitation of distributed
-systems, and it is strongly dependent on the architectures you build.
-
-In the following example, we show how you can make certain decisions
-based on global, uncertain knowledge, allowing for the fact that the
-information is uncertain. In other words, we aim to err on the safe
-side. In this case we ask how could we reboot systems after an upgrade
-only if doing so would not jeopardize a Service Level Agreement to have
-at least 20 machines running at all times. Since the globally
-counted instances of a running process cannot be greater than the actual
-number, this particular problem satisfies the constraint of erring
-on the side of caution.
-
-@verbatim
-############################################################
-#
-# Keep a special promise only if at least n or m hosts
-# keep a specific promise
-#
-# This method works with Enterprise CFEngine
-#
-# If you want to test this on localhost, just edit /etc/hosts
-# to add host1 host2 host3 host4 as aliases to localhost
-#
-############################################################
-
-body common control
-{
-bundlesequence => { "n_of_m_symphony" };
-inputs => { "cfengine_stdlib.cf" };
-}
-
-############################################################
-
-bundle agent n_of_m_symphony
-{
-vars:
-
- "count_compliant_hosts" string => hubknowledge("running_myprocess");
-
-classes:
-
- "reboot" expression => isgreaterthan("$(count_compliant_hosts)","20");
-
-processes:
-
- "myprocess"
-
- comment => "Count this host if a job is matched",
- classes => enumerate("running_myprocess");
-
-commands:
-
- reboot::
-
- "/bin/shutdown now";
-}
-
-
-#######################################################
-
-bundle server access_rules()
-{
-access:
-
- "value of my test_scalar, can expand variables here - $(sys.host)"
- handle => "test_scalar",
- comment => "Grant access to contents of test_scalar VAR",
- resource_type => "literal",
- admit => { "127.0.0.1" };
-
- "running_myprocess"
- resource_type => "variable",
- admit => { "127.0.0.1" };
-
-}
-
-@end verbatim
-
-
-
-
-
-@node The self-healing chain - inverse Dominoes, A Domino sequence, Run job or reboot only if n out m systems are running, Distributed Orchestration between hosts with CFEngine Enterprise
-@unnumberedsubsec The self-healing chain - inverse Dominoes
-
-
-A self-healing chain is the opposite of a dominoe event. If a part of
-the chain is `down', it will be revived. If these events depend on one
-another, then the resuscitation of this part which cause all of the
-subsequent parts to be repaired too.
-
-Let's start with the more common case of the independently repairable
-services, such as one might find in a multi-tier architecture:
-database, web-servers, applications etc.
-
-The following example can be run on a multiple hosts or on a single
-host, using the aliases described in the example. It illustrates
-coordination through the use of CFEngine's @code{remoteclasses}
-function in the Enterprise edition to get confirmation of the
-self-healing structure. In fact, the verification of the self-healing
-is optional if one trusts the underlying system.
-
-@verbatim
-############################################################
-#
-# The self-healing tower: Anti-Dominoes
-#
-# This method works with CFEngine Enterprise
-#
-# If you want to test this on localhost, just edit /etc/hosts
-# to add host1 host2 host3 host4 as aliases to localhost
-#
-############################################################
-
-body common control
-{
-bundlesequence => { "weak_dependency_symphony" };
-inputs => { "cfengine_stdlib.cf" };
-}
-
-body server control
-{
-allowconnects => { "127.0.0.1" , "::1", @(def.acl) };
-allowallconnects => { "127.0.0.1" , "::1", @(def.acl) };
-}
-
-############################################################
-
-bundle agent weak_dependency_symphony
-{
-methods:
-
- # We have to seed the beginning by creating the tower
- # /tmp/tower_localhost
-
- host1::
- "tower" usebundle => tier1,
- classes => publish_ok("ok_O");
-
- host2::
- "tower" usebundle => tier2,
- classes => publish_ok("ok_1");
-
- host3::
- "tower" usebundle => tier3,
- classes => publish_ok("ok_2");
-
- host4::
- "tower" usebundle => tier4,
- classes => publish_ok("ok_f");
-
-classes:
-
- ok_O:: # Wait for the methods, report on host1 only
-
- "check1" expression => remoteclassesmatching("ok.*","host2","yes","a");
- "check2" expression => remoteclassesmatching("ok.*","host3","yes","a");
- "check3" expression => remoteclassesmatching("ok.*","host4","yes","a");
-
-reports:
-
- ok_O::
- "tier 1 is ok";
- a_ok_1::
- "tier 2 is ok";
- a_ok_2::
- "tier 3 is ok";
- a_ok_f::
- "tier 4 is ok";
-
- ok_O&a_ok_1&a_ok_2&a_ok_f::
- "The Tower is standing";
-
- !(ok_O&a_ok_1&a_ok_2&a_ok_f)::
- "The Tower is down";
-}
-
-############################################################
-
-bundle agent tier1
-{
-files:
-
- "/tmp/something_to_do_1"
- create => "true";
-}
-
-bundle agent tier2
-{
-files:
-
- "/tmp/something_to_do_2"
- create => "true";
-}
-
-bundle agent tier3
-{
-files:
-
- "/tmp/something_to_do_3"
- create => "true";
-
-}
-
-bundle agent tier4
-{
-files:
-
- "/tmp/something_to_do_4"
- create => "true";
-}
-
-############################################################
-
-
-bundle server access_rules()
-{
-access:
-
- "ok.*"
- resource_type => "context",
- admit => { "127.0.0.1" };
-
-}
-
-############################################################
-
-body classes publish_ok(x)
-{
-promise_repaired => { "$(x)" };
-promise_kept => { "$(x)" };
-cancel_notkept => { "$(x)" };
-persist_time => "2";
-}
-
-@end verbatim
-
-@noindent If we execute this simple test on a single host, or allow it to be executed on distributed
-hosts, the chain forms and quickly stands up the system into a tower of dependencies.
-@verbatim
-host$ ~/LapTop/cfengine/core/src/cf-agent -f ~/orchestrate/self-healing-chain.cf -K
-R: tier 1 is ok
-R: tier 2 is ok
-R: tier 3 is ok
-R: tier 4 is ok
-R: The Tower is standing
-@end verbatim
-If we break the tower, by giving it an impossible promise to keep, e.g. changing the name
-of the directory in tier 3 to something that cannot be created@footnote{For this illustration,
-we run in non-privileged mode and choose a directory name we do not have permission to create.},
-then tier 3 will fail and the output looks like this:
-@verbatim
-host$ ~/LapTop/cfengine/core/src/cf-agent -f ~/orchestrate/self-healing-chain.cf -K
-Unable to make directories to /xtmp/something_to_do_3
- !!! System reports error for cf_mkdir: "Permission denied"
-R: tier 1 is ok
-R: tier 2 is ok
-R: tier 4 is ok
-R: The Tower is down
-@end verbatim
-@noindent Clearly, whatever tier 3 is really supposed to do, any promise failure
-would result in the same behaviour. If we then correct the policy to make it repairable, the output
-heals quickly:
-@verbatim
-host$ ~/LapTop/cfengine/core/src/cf-agent -f ~/orchestrate/self-healing-chain.cf -K
-R: tier 1 is ok
-R: tier 2 is ok
-R: tier 4 is ok
-R: The Tower is down
-R: tier 3 is ok
-R: The Tower is standing
-@end verbatim
-
-
-
-@node A Domino sequence, A Chinese Dragon, The self-healing chain - inverse Dominoes, Distributed Orchestration between hosts with CFEngine Enterprise
-@unnumberedsubsec A Domino sequence
-
-
-A different kind of orchestration is a domino cascade, that starts
-from some initial trigger, and causes a change in one host that causes
-a change in the next, etc. These examples show how this can easily be
-carried out by CFEngine. Dominio cascades can be done with Community
-or Enterprise editions, but are limited to single machines in each
-step.
-
-The basic principle is shown below@footnote{This example has deliberately been
-made general enough to demonstrate on a single host with several aliases. If each
-host can be guaranteed to have a unique name and address, we could simplify
-the @code{hand_over} wrapper}.
-
-@i{Note: to simulate this on a single host, start the server and agent
-with this same file as input, and make aliases to localhost in @file{/etc/hosts}
-as described in the example.}
-
-@verbatim
-############################################################
-#
-# Dominoes
-#
-# This method works with either Community of Enterprise
-#
-# If you want to test this on localhost, just edit /etc/hosts
-# to add host1 host2 host3 host4 as aliases to localhost
-#
-############################################################
-
-body common control
-{
-bundlesequence => { "dominoes_symphony" };
-inputs => { "cfengine_stdlib.cf" };
-}
-
-############################################################
-
-bundle agent dominoes_symphony
-{
-methods:
-
- # We have to seed the beginning by creating the dominoes
- # /tmp/dominoes_localhost
-
- host1::
- "dominoes" usebundle => hand_over("localhost","host1","overture");
-
- host2::
- "dominoes" usebundle => hand_over("host1","host2","first_movement");
-
- host3::
- "dominoes" usebundle => hand_over("host2","host3","second_movement");
-
- host4::
- "dominoes" usebundle => hand_over("host3","host4","final_movement"),
- classes => if_ok("finale");
-
-reports:
-
- finale::
-
- "The visitors book of the Dominoes method"
- printfile => visitors_book("/tmp/dominoes_host4");
-
-}
-
-############################################################
-
-bundle agent hand_over(predecessor,myalias,method)
-{
-
- # This is a wrapper for the orchestration
-
-files:
-
- "/tmp/tip_the_dominoes"
-
- comment => "Wait for our cue or relay/conductor baton",
- copy_from => secure_cp("/tmp/dominoes_$(predecessor)","$(predecessor)"),
- classes => if_repaired("cue_action");
-
-methods:
-
- cue_action::
-
- "the music happens"
-
- comment => "One off activity",
- usebundle => $(method),
- classes => if_ok("pass_the_stick");
-
-files:
-
- pass_the_stick::
-
- "/tmp/tip_the_dominoes"
- comment => "Add our signature to the dominoes's tail",
- edit_line => append_if_no_line("Knocked over $(myalias) and did: $(method)");
-
- "/tmp/dominoes_$(myalias)"
-
- comment => "Dominoes in position to be beamed up by next agent",
- copy_from => local_cp("/tmp/tip_the_dominoes");
-
-}
-
-############################################################
-
-bundle agent overture
-{
-reports:
-
- !xyz::
-
- "Singing the overture...";
-}
-
-bundle agent first_movement
-{
-reports:
-
- !xyz::
-
- "Singing the first adagio...";
-}
-
-bundle agent second_movement
-{
-reports:
-
- !xyz::
-
- "Singing second allegro...";
-
-}
-
-bundle agent final_movement
-{
-reports:
-
- !xyz::
-
- "Trumpets for the finale";
-
-}
-
-############################################################
-
-
-bundle server access_rules()
-{
-access:
-
- "/tmp"
-
- admit => { "127.0.0.1" };
-
- "did.*"
- resource_type => "context",
- admit => { "127.0.0.1" };
-
-}
-
-
-body printfile visitors_book(file)
-{
-file_to_print => "$(file)";
-number_of_lines => "10";
-}
-
-
-@end verbatim
-@noindent When executed, this produces output only on the final host
-in the chain, showing the correct ordering out operations. The
-sequence also passes a file from host to host as a coordination
-token, like a baton in a relay race, and each host signs this
-so that the final host has a log of eery host involved in the
-cascade.
-
-@verbatim
-R: Singing the overture...
-R: Singing the first adagio...
-R: Singing second allegro...
-R: Trumpets for the finale
-
-R: The visitors book of the Dominoes method
-R: Knocked over host1 and did: overture
-R: Knocked over host2 and did: first_movement
-R: Knocked over host3 and did: second_movement
-R: Knocked over host4 and did: final_movement
-
-@end verbatim
-
-The average time for such a cascade to complete will be half the
-length of the chain multiplied by the run-interval, if normal cf-execd
-splaytime is used. Without any splaying, the average time will be the
-run interval multiplied by the chain length. The completion time
-could be increased by using cf-runagent.
-
-
-@node A Chinese Dragon, , A Domino sequence, Distributed Orchestration between hosts with CFEngine Enterprise
-@unnumberedsubsec A Chinese Dragon star pattern
-
-The Chinese dragon darts back and forth between different hosts,
-forming a chain of events, and leaving a trail behind it. This pattern
-is much like the Domino pattern, except that it follows a star. The
-orchestrated sequence of events follows the dragon from its lair to
-the first satellite host, then back to its lair to record the journey,
-then out to the next satellite, then back to its lair, etc.
-
-A prototypical application for this kind of pattern is taking servers, one by one,
-off a load balancer (in the dragon's lair) and then upgrading them, before
-reinstating them and moving on to the next host.
-
-
-@verbatim
-############################################################
-#
-# Chinese Dragon Dancing on a Star
-#
-# This method works with either Community or Enterprise.
-# and uses named signals
-#
-# If you want to test this on localhost, just edit /etc/hosts
-# to add host1 host2 host3 host4 as aliases to localhost
-#
-############################################################
-
-body common control
-{
-bundlesequence => { "dragon_symphony" };
-inputs => { "cfengine_stdlib.cf" };
-}
-
-############################################################
-
-bundle agent dragon_symphony
-{
-methods:
-
- # We have to seed the beginning by creating the dragon
- # /tmp/dragon_localhost
-
- "dragon" usebundle => visit("localhost","host1","chapter1");
-
- "dragon" usebundle => visit("host1","host2","chapter2");
-
- "dragon" usebundle => visit("host2","host3","chapter3");
-
- "dragon" usebundle => visit("host3","host4","chapter4"),
- classes => if_ok("finale");
-
-reports:
-
- finale::
-
- "The dragon is slain:"
- printfile => visitors_book("/tmp/shoo_dragon_host4");
-}
-
-############################################################
-# Define the
-############################################################
-
-bundle agent chapter1(x)
-{
-# Do something significant here
-
-reports:
-
- host1::
- " ----> Breathing fire on $(x)";
-}
-
-################################
-
-bundle agent chapter2(x)
-{
-# Do something significant here
-
-reports:
-
- host2::
- " ----> Breathing fire on $(x)";
-
-}
-
-################################
-
-bundle agent chapter3(x)
-{
-# Do something significant here
-
-reports:
-
- host3::
- " ----> Breathing fire on $(x)";
-
-}
-
-################################
-
-bundle agent chapter4(x)
-{
-# Do something significant here
-
-reports:
-
- host4::
- " ----> Breathing fire on $(x)";
-
-}
-
-############################################################
-# Orchestration wrappers
-############################################################
-
-bundle agent visit(predecessor,satellite,method)
-{
-
- # This is a wrapper for the orchestration will be acted on
- # first by the dragon's lair and then by the satellite
-
-vars:
-
- "dragons_lair" string => "host0";
-
-files:
-
- # We start in the dragon's lair ..
-
- "/tmp/unleash_dragon"
-
- comment => "Unleash the dragon",
- rename => to("/tmp/enter_the_dragon"),
- classes => if_repaired("dispatch_dragon_$(satellite)"),
- ifvarclass => "$(dragons_lair)";
-
- # if we are the dragon's lair, welcome the dragon back, shooed from the satellite
-
- "/tmp/enter_the_dragon"
-
- comment => "Returning from a visit to a satellite",
- copy_from => secure_cp("/tmp/shoo_dragon_$(predecessor)","$(predecessor)"),
- classes => if_repaired("dispatch_dragon_$(satellite)"),
- ifvarclass => "$(dragons_lair)";
-
- # If we are a satellite, receive the dragon from its lair
-
- "/tmp/enter_the_dragon"
- comment => "Wait for our cue or relay/conductor baton",
- copy_from => secure_cp("/tmp/dragon_$(satellite)","$(dragons_lair)"),
- classes => if_repaired("cue_action_on_$(satellite)"),
- ifvarclass => "$(satellite)";
-
-methods:
-
- "check in at home"
- comment => "Edit the load balancer?",
- usebundle => switch_satellite(" -> Send dragon to $(satellite)"),
- classes => if_repaired("send_the_dragon_to_$(satellite)"),
- ifvarclass => "dispatch_dragon_$(satellite)";
-
- "dragon visits"
- comment => "One off activity that the nodes carry out while the dragon visits",
- usebundle => $(method)("$(satellite)"),
- classes => if_repaired("send_the_dragon_back_from_$(satellite)"),
- ifvarclass => "cue_action_on_$(satellite)";
-
-
-files:
-
- # hub/lair hub signs the book too and schedules the dragon for next satellite
-
- "/tmp/dragon_$(satellite)"
- create => "true",
- comment => "Add our signature to the dragon's tail",
- edit_line => sign_visitor_book("Dragon returned from $(predecessor)"),
- ifvarclass => "send_the_dragon_to_$(satellite)";
-
- # Satellite signs the book and shoos dragon for hub to collect
-
- "/tmp/shoo_dragon_$(satellite)"
- create => "true",
- comment => "Add our signature to the dragon's tail",
- edit_line => sign_visitor_book("Dragon visited $(satellite) and did: $(method)"),
- ifvarclass => "send_the_dragon_back_from_$(satellite)";
-
-reports:
-
- !xyz::
-
- "Done $(satellite)";
-
-}
-
-############################################################
-
-bundle agent switch_satellite(name)
-{
-files:
-
- "/tmp/enter_the_dragon"
- comment => "Add our signature to the dragon's tail",
- edit_line => append_if_no_line("Switch new dragon's target $(name)");
-
-reports:
-
- !xyz::
- " X Switching new dragon's target $(name)";
-}
-
-
-############################################################
-
-bundle edit_line sign_visitor_book(s)
-{
-insert_lines:
-
- "/tmp/enter_the_dragon"
- comment => "Import the current visitor's book",
- insert_type => "file";
-
- "$(s)" comment => "Append this string to the visitor's book";
-}
-
-############################################################
-
-
-bundle server access_rules()
-{
-access:
-
- "/tmp"
-
- admit => { "127.0.0.1" };
-
- "did.*"
- resource_type => "context",
- admit => { "127.0.0.1" };
-
-}
-
-############################################################
-
-body printfile visitors_book(file)
-{
-file_to_print => "$(file)";
-number_of_lines => "100";
-}
-
-@end verbatim
-
-
-
-Let's test it on a single host, equipped with aliases to the see entire flow.
-
-@noindent Without the trigger, this simply yields
-@verbatim
-R: Done host1
-R: Done host2
-R: Done host3
-R: Done host4
-@end verbatim
-
-@verbatim
-host$ touch /tmp/unleash_dragon
-
-host$ ~/LapTop/cfengine/core/src/cf-agent -f ~/orchestrate/dragon.cf -K
-R: X Switching new dragon's target -> Send dragon to host1
-R: Done host1
-R: Done host2
-R: Done host3
-R: Done host4
-
-host$ ~/LapTop/cfengine/core/src/cf-agent -f ~/orchestrate/dragon.cf -K
-R: ----> Breathing fire on host1
-R: Done host1
-R: X Switching new dragon's target -> Send dragon to host2
-R: Done host2
-R: Done host3
-R: Done host4
-host$
-
-host$ ~/LapTop/cfengine/core/src/cf-agent -f ~/orchestrate/dragon.cf -K
-R: ----> Breathing fire on host1
-R: Done host1
-R: X Switching new dragon's target -> Send dragon to host2
-R: ----> Breathing fire on host2
-R: Done host2
-R: X Switching new dragon's target -> Send dragon to host3
-R: Done host3
-R: Done host4
-
-host$ ~/LapTop/cfengine/core/src/cf-agent -f ~/orchestrate/dragon.cf -K
-R: ----> Breathing fire on host1
-R: Done host1
-R: X Switching new dragon's target -> Send dragon to host2
-R: ----> Breathing fire on host2
-R: Done host2
-R: X Switching new dragon's target -> Send dragon to host3
-R: ----> Breathing fire on host3
-R: Done host3
-R: X Switching new dragon's target -> Send dragon to host4
-R: Done host4
-host$ ~/LapTop/cfengine/core/src/cf-agent -f ~/orchestrate/dragon.cf -K
-R: ----> Breathing fire on host1
-R: Done host1
-R: X Switching new dragon's target -> Send dragon to host2
-R: ----> Breathing fire on host2
-R: Done host2
-R: X Switching new dragon's target -> Send dragon to host3
-R: ----> Breathing fire on host3
-R: Done host3
-R: X Switching new dragon's target -> Send dragon to host4
-R: ----> Breathing fire on host4
-R: Done host4
-
-R: The dragon is slain:
-R: Switch new dragon's target -> Send dragon to host1
-R: Dragon returned from localhost
-R: Dragon visited host1 and did: chapter1
-R: Switch new dragon's target -> Send dragon to host2
-R: Dragon returned from host1
-R: Dragon visited host2 and did: chapter2
-R: Switch new dragon's target -> Send dragon to host3
-R: Dragon returned from host2
-R: Dragon visited host3 and did: chapter3
-R: Switch new dragon's target -> Send dragon to host4
-R: Dragon returned from host3
-R: Dragon visited host4 and did: chapter4
-
-@end verbatim
-
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_Monitoring.texinfo b/docs/guides/SpecialTopic_Monitoring.texinfo
deleted file mode 100644
index b4c0f173c3..0000000000
--- a/docs/guides/SpecialTopic_Monitoring.texinfo
+++ /dev/null
@@ -1,1063 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-@c
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-monitoring.info
-@settitle Monitoring with CFEngine
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Monitoring with CFEngine
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-CFEngine fulfils an unusual role as a management system, closing the
-loop between measurement or monitoring of resources and change
-management. CFEngine learns the normal behaviour of a system using
-smart lightweight algorithm, and builds a statistical view of what
-is normal behaviuour. Policy may then me measured against this normal
-state to provide @i{relativistic} reporting of state, and the detection
-of anomalies.
-
-A significant capability of CFEngine Nova over previous versions of
-CFEngine, as well as other monitoring software, is the existence of
-lightweight extensible probes, based on Perl Compatible Regular
-Expressions. These probes can extract and store data in an efficient
-and non-intrusive manner. Reports can be integrated into the Nova Knowledge Map
-and anomalies are automatically detected by CFEngine's self-learning
-algorithms.
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2010-11 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@node Top, Monitoring introduction, (dir), (dir)
-@top Measurement and Monitoring
-
-@menu
-* Monitoring introduction::
-* Monitoring customization::
-@end menu
-
-
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@node Monitoring introduction, Monitoring customization, Top, Top
-@chapter Monitoring introduction
-
-@menu
-* What is monitoring?::
-* What are the goals of monitoring?::
-* What does monitoring software do?::
-* Monitoring in CFEngine::
-* Visualization of monitoring in CFEngine::
-* Standard measured variables::
-* Estimate of the level of normality::
-* Variables::
-* Entropy::
-* Persistent classes for alert conditions::
-@end menu
-
-@node What is monitoring?, What are the goals of monitoring?, Monitoring introduction, Monitoring introduction
-@unnumberedsec What is monitoring?
-
-The world of IT management is replete with monitoring
-software. Monitoring is considered to be a major part of management,
-and it plays a kind of `feel good' role to engineers even when it
-often reveals little useful information. Users are often fiercely
-loyal to certain monitoring solutions, However, most monitoring systems have
-some key problems:
-
-@itemize
-@item Many monitoring systems are so heavy weight that they lead to
- a system large overhead.
-
-@item Scalability of monitoring solutions is often poor, both in terms
-of system resource consumption and comprehensability of the data collected.
-@end itemize
-One might argue that these problems can be traced back to the overly ambitious
-nature of what they try to achieve.
-
-Some common or popular monitoring solutions include:
-@itemize
-@item HP OpenView
-@item Nagios
-@item Munin
-@item Zenoss
-@item Ganglia
-@item collectd
-@end itemize
-
-@node What are the goals of monitoring?, What does monitoring software do?, What is monitoring?, Monitoring introduction
-@unnumberedsec What are the goals of monitoring?
-
-Few montioring systems yield accurate or even very clear results about
-systems, and yet we feel reassured by moving traces. We monitor
-systems first and foremost out of a desire for knowledge. If that
-seems like a trivial statement, you should examine your own
-motivations carefully -- what is it you really want from a monitoring
-solution? Accurate data, or some basic reassurance?
-
-As scientific instruments, most monitoring software is rather poorly
-constructed. The devices are rarely calibrated, the results are
-presented without context, sorted according to arbitrary thresholds,
-and it is unclear what delay there was between the sampling of the
-system and the presentation of the data. That makes the data values
-and the traces almost useless - but not quite. What users really see
-in monitoring is patterns of change. Monitoring software forms a
-bridge between actual data about the system and the habits of the
-human brain.
-
-
-@node What does monitoring software do?, Monitoring in CFEngine, What are the goals of monitoring?, Monitoring introduction
-@unnumberedsec What does monitoring software do?
-
-Typically, monitoring software samples data from systems through a number of
-probes and presents the data in some graphical form. A few systems can also
-perform statistical analysis and even look-ahead forecasting of the data.
-Much monitoring software is based on the Simple Network Management
-Protocol (SNMP) which is an active probe regime usually run from a
-centralized network manager.
-
-The simple fact of the matter is that most monitoring software
-simple presents a rough visualization of the raw data to users
-as either a set of alarms (loggable messages) or as a moving time-series,
-analogous to a hospital vital-signs monitor (EEG or ECG).
-
-If one is cynical, it might be said that some monitoring systems waste
-users' time by producing moving graphs with a level of detail that is
-utterly inappropriate. Users then sit transfixed to these moving
-traces, watching for any insignificant change -- and, because there is
-no context or history to meaure the changes against, every change
-appears to be interesting.
-
-
-@node Monitoring in CFEngine, Visualization of monitoring in CFEngine, What does monitoring software do?, Monitoring introduction
-@unnumberedsec Monitoring in CFEngine
-
-
-In CFEngine, there is @code{cf-monitord}, which runs as a local agent
-on every computer. This daemon wakes up every couple of minutes and
-samples data for a number of variables without using the network. The
-data are then stored in an embedded database on the localhost, using a
-smart algorithm that prevents the datasize from growing endlessly.
-CFEngine uses a model of system behaviour based on the findings of
-research about how computers behave in a network. The model reveals
-strong weekly patterns in most measurable data, or no pattern
-whatsoever. This knowledge can be used to compress the data by a large
-factor and enables @code{cf-monitord} to carry out a real time
-statistical analysis of the normal behaviour that is updated over
-time.
-
-CFEngine was not written to replace other monitoring systems,
-but to achieve rather concrete goals. In order to achieve these
-goals, CFEngine does not monitor as often as other systems,
-and it presents results rather differently.
-
-The goals of monitoring in CFEngine are:
-
-@itemize
-@item To not waste users' time with insignificant changes, but provide
-meaningful updates at a rate that is defensible based on the rate of
-change of the system.
-@item To provide meaningful information that is placed in
-the context of what is normal.
-@item To reveal trends and patterns at a glance.
-
-@item To scale to tens of thousands of hosts without placing a significant
-burden on the hosts being monitored.
-@item To be as hands-free in configuration as possible, but allow customization.
-
-
-@item To provide a feedback mechanism for system policy so that systems can
-respond directly to conditions that are detected.
-@end itemize
-
-The information returned by @code{cf-monitord} comes in a number of forms:
-
-@itemize
-@item As visual, plottable graphs.
-@item As CFEngine classes that are passed to @code{cf-agent} and may be used to generate
-alarms or automatic responses.
-@end itemize
-
-@sp 1
-@center @image{timeseries,15cm}
-@sp 1
-@center A graphical rendering of a 100 x load average pattern collected by a host.
-@sp 1
-
-
-
-@node Visualization of monitoring in CFEngine, Standard measured variables, Monitoring in CFEngine, Monitoring introduction
-@unnumberedsec Visualization of monitoring in CFEngine
-
-The CFEngine community edition provides limited support for
-visualization. The @code{cf-report} command can be used to generate
-files that can be plotted with other free software. So far this is not
-well documented, since the process requires special knowledge of some
-less-well known Open Source tools (see Reference Manual, reporter
-control promises).
-
-However, in the commercial edition of CFEngine (Nova/Enterprise), much effort has been put into making the centralized
-collection and visualization of these data straightforward and
-powerful so that all of the learned information about a network
-may be seen and analysed from a single location.
-
-
-Any model of fluctuating values is based on the idea that the changing
-signal has a basic separation of signal and noise. The variability of
-the signal is generally characterized by a probability distribution
-which often peaks about the mean value. Some tools and many papers
-assume that the distribution of fluctuations is Gaussian. This is
-almost never the case in real computer systems.
-
-CFEngine plots the following values together to provide
-an interpretive context for the data:
-
-@itemize
-@item The last sampled value (@samp{value}). This is the actual `current value'. This is the orange
-line in the figure above.
-@item The rolling average of the data for each 5 minute interval of the week (@samp{av}). This represents
-the best estimate of what is normal. This is the green line in the figure above.
-@item An envelope of on standard deviation above (red vertical bars) and below (green vertical bars) the average
-to show the envelope of normal `variation' (@samp{dev}).
-@end itemize
-
-@cartouche
-Note: it is a common misconception that the mean and standard deviation only
-apply to Gaussian statistical models. This is not true, although it is true that
-these quantities have a special significance for these distributions. You may think
-of the rolling mean as a representative average value that represents what is approximately
-`normal'. The standard deviation plays the role of an approximate estimate of the uncertainty
-in the value of the mean. These values should be treated as heuristics, not as absolute truths
-in any reasonable statistical interpretation of the data.
-@end cartouche
-
-@c -------------------------------------------------------------------------------
-@c SECTION
-@c -------------------------------------------------------------------------------
-
-@node Standard measured variables, Estimate of the level of normality, Visualization of monitoring in CFEngine, Monitoring introduction
-@unnumberedsec Standard measured variables
-
-When CFEngine detects an anomaly, it classified the current statistical
-state of the system into a number of classes.
-
-CFEngine classifies anomalies by whether the currently measured state of
-the system is higher or lower than the average for the current time of
-week. The amount of deviation is based on an estimate of the `standard
-deviation'. The precise definition of the average and standard
-deviations is complex, and is discussed in the paper "M. Burgess,
-Probabilistic anomaly detection in distributed computer
-networks", (submitted to Science of Computer Programming, and available
-on the web).
-
-The list of measured attributes is currently fixed to the following:
-
-
-The first part of the string is from the list:
-
-@table @code
-@item users
-The number of different users that appear in the process table of the system.
-@item rootprocs
-The nunmber of current processes started by root/Administrator.
-@item userprocs
-The number of current processes started by non-privileged users.
-@item diskfree
-The amount of disk free on root file system.
-@item loadavg
-The load average of the system (actually multiplied by 100).
-@end table
-Socket counts of network services distinguish between incoming and outgoing
-sockets (to a service or from a client).
-@table @code
-@item netbiosns
-Registers traffic to/from port 137.
-@item netbiosdgm
-Registers traffic to/from port 138.
-@item netbiosssn
-Registers traffic to/from port 139.
-@item irc
-Registers traffic to/from port 194.
-@item CFEngine
-Registers traffic to/from port 5308.
-@item nfsd
-Registers traffic to/from port 2049.
-@item smtp
-Registers traffic to/from port 25.
-@item www
-Registers traffic to/from port 80.
-@item ftp
-Registers traffic to/from port 21.
-@item ssh
-Registers traffic to/from port 22.
-@item wwws
-Registers traffic to/from port 443.
-@end table
-
-If you have tcpdump program installed in a standard location, then the monitor can be confugured to
-collect data about the network flows to your host.
-
-@table @code
-@item icmp
-Traffic belonging to the ICMP protocol (ping etc).
-@item dns
-Traffic to port 53, the Domain Name Service (usually a special case of UDP).
-@item udp
-Miscellaneous UDP traffic that is not related to DNS.
-@item tcpsyn
-Registers TCP packets with SYN flag set.
-@item tcpack
-Registers TCP packets with ACK flag set.
-@item tcpfin
-Registers TCP packers with FIN flag set.
-@item misc
-Registers all other packets, not covered above.
-@end table
-
-
-@node Estimate of the level of normality, Variables, Standard measured variables, Monitoring introduction
-@unnumberedsec Estimate of the level of normality
-
-When @code{cf-monitord} has accurate knowledge of statistics, it classifies
-the current state into 3 levels:
-
-@cindex normal
-@cindex dev1
-@cindex dev2
-@cindex anomaly
-@cindex microanomaly
-
-@table @code
-@item normal
-means that the current level is less
-than one standard deviation above normal.
-@item dev1
-means that the
-current level is at least one standard deviation about the average.
-
-@item dev2
-means that the current level is at least two standard
-deviations about the average.
-
-@item anomaly
-means that the current level is more than 3 standard deviations above average.
-
-@end table
-
-@noindent
-Each of these charaxterizations assumes that there are good data
-available. The @file{cf-monitord} evaluates its data and decides whether or
-not the data are too noisy to be really useful. If the data are too
-noisy but the level @i{appears} to be more than two standard deviations
-above aaverage, then the category @code{microanomaly} is used.
-
-Here are some example classes:
-
-@smallexample
-userprocs_high_dev2
-userprocs_low_dev1
-www_in_high_anomaly
-smtp_out_high_dev2
-@end smallexample
-
-@noindent A complete list of standard metrics
-@cindex Anomalies
-Base classes:
-@smallexample
- users
- rootprocs
- otherprocs
- diskfree
- loadavg
- netbiosns_in
- netbiosns_out
- netbiosdgm_in
- netbiosdgm_out
- netbiosssn_in
- netbiosssn_out
- irc_in
- irc_out
- CFEngine_in
- CFEngine_out
- nfsd_in
- nfsd_out
- smtp_in
- smtp_out
- www_in
- www_out
- ftp_in
- ftp_out
- ssh_in
- ssh_out
- wwws_in
- wwws_out
- icmp_in
- icmp_out
- udp_in
- udp_out
- dns_in
- dns_out
- tcpsyn_in
- tcpsyn_out
- tcpack_in
- tcpack_out
- tcpfin_in
- tcpfin_out
- tcpmisc_in
- tcpmisc_out
-@end smallexample
-Suffixes:
-@smallexample
-_high_microanomaly
-_low_microanomaly
-
-_high_dev1
-_low_dev1
-
-_high_dev2
-_low_dev2
-
-_high_anomaly
-_low_anomaly
-
-_high_ldt
-_low_ldt
-@end smallexample
-
-
-@node Variables, Entropy, Estimate of the level of normality, Monitoring introduction
-@unnumberedsec Variables
-
-The @code{cf-monitord} sets variables which cache the values that were valid at the
-time of the anomaly's occurrance. These are of the same form as above.
-@smallexample
-value_rootprocs
-average_rootprocs
-stddev_rootprocs
-
-value_nsfd_in
-average_nfsd_in
-stddev_nfsd_in
-@end smallexample
-The Leap Detection Test buffer is called
-@smallexample
-ldtbuf_users
-ldtbuf_otherprocs
-@end smallexample
-etc.
-
-@menu
-* Entropy::
-@end menu
-
-@node Entropy, Persistent classes for alert conditions, Variables, Monitoring introduction
-@unnumberedsec Entropy
-
-For network related data, CFEngine evaluates the entropy in the
-currently measured sample of measurements, with respect to the
-different IP addresses of the sources. You can use these to predicate
-the appearance of an anomaly, e.g.
-@cindex Entropy
-@smallexample
- entropy_www_in_high
- entropy_smtp_in_low
-@end smallexample
-
-For example, if you only want to know when a huge amount of SMTP traffic arrives from a
-single IP source, you would label your anomaly response:
-@smallexample
-entropy_smtp_in_low.smtp_in_high_anomaly::
-@end smallexample
-@noindent
-since the entropy is low when the majority of traffic
-comes from only a small number of IP addresses (e.g. one). The entropy is maximal
-when activity comes equally from several different sources.
-
-
-
-@node Persistent classes for alert conditions, , Entropy, Monitoring introduction
-@unnumberedsec Persistent classes for alert conditions
-
-
-Another application for alerts is to pass signals from one invocation of the CFEngine agent to
-another by persistent, shared memory. For example, suppose a
-short-lived anomaly event triggers a class that relates to a security
-alert. The event class might be too short-lived to be followed up by
-cfagent in full. One could thus set a long term class that would
-trigger up several follow-up checks. A persistent class could also be
-used to exclude an operation for an interval of time.
-
-Persistent class memory can be added through a system alert functions
-to give timer behaviour. For example, consider setting a class that
-acts like a non-resettable timer. It is defined for exactly 10 minutes
-before expiring.
-
-@verbatim
-body classes example
- {
- persist_time => "10";
- }
-
-body classes example
- {
- timer_policy => "reset";
- }
-
-@end verbatim
-
-
-
-
-@node Monitoring customization, , Monitoring introduction, Top
-@chapter Monitoring customization
-
-@menu
-* What are measurements?::
-* measurements promises::
-* Scanning log files for patterns::
-* FTP::
-* DNS::
-* Email::
-* Milter::
-* Breakin::
-* Threshold monitoring::
-* Summary Monitoring::
-@end menu
-
-@node What are measurements?, measurements promises, Monitoring customization, Monitoring customization
-@unnumberedsec What are measurements?
-
-@sp 1
-Measurement promises perform sampling of system variables, and
-scanning of files and probes, at regular controllable intervals in
-order to present an efficient overview of actual changes taking place over time.
-
-
-@node measurements promises, Scanning log files for patterns, What are measurements?, Monitoring customization
-@unnumberedsec @code{measurements} promises
-@sp 1
-
-In CFEngine Nova and above, you can extract data from the
-system in sophisticated ways from files or pipes, using Perl
-Compatible Regular Expressions to match text. The @code{cf-monitord}
-agent is responsible for processing measurement promises.
-
-In this example, we count lines matching a pattern in a file.
-You might want to scan a log for instances of a particular
-message and trace this number over time.
-
-
-@node Scanning log files for patterns, FTP, measurements promises, Monitoring customization
-@unnumberedsec Scanning log files for patterns
-@sp 1
-
-You will have to scan the log file for each separate summary
-you want to keep, so you win a lot of efficiency by lumping
-together mulitple patterns in a longer regular expressions.
-
-Be careful however about the trade-off. Disk access is certainly the
-most expensive computing resource, but a smart filesystem might do good caching.
-
-Regular expression processing, on the other hand, is CPU expensive, so
-if you have very long or complex patterns to match, you will begin
-to eat up CPU time too.
-
-At the end of the day, you should probably do some tests to find a good
-balance. One goal of CFEngine is to minimally impact your system performance,
-but it is possible to write promises that have the opposite effect. Check
-your work!
-
-@verbatim
-
-bundle monitor watch
-{
-measurements:
-
- "/home/mark/tmp/file"
-
- handle => "line_counter",
- stream_type => "file",
- data_type => "counter",
- match_value => scan_log("MYLINE.*"),
- history_type => "log",
- action => sample_rate("0");
-
-}
-
-##########################################################
-
-body match_value scan_log(line)
-{
-select_line_matching => "$(line)";
-track_growing_file => "true";
-}
-
-body action sample_rate(x)
-{
-ifelapsed => "$(x)";
-expireafter => "10";
-}
-@end verbatim
-
-@node FTP, DNS, Scanning log files for patterns, Monitoring customization
-@unnumberedsec Scanning syslog for FTP statistics
-@sp 1
-
-There are many things that you can set CFEngine at monitoring. For example,
-CFEngine can automtically collect information about the number of socket-level
-connections made to the ftp server, but you might want more detailed
-statistics. For example, you might want to track the volume of data sent
-and received, or the number of failed logins. Here are a collection of
-monitoring promises for doing just that.
-
-Note that the ftp logs are maintained by syslog, so it is necessary to match
-only those lines which correspond to the appropriate service. We also assume
-that the specific messages are sent to @file{/var/log/messages}, while your
-configuration may specify otherwise. Likewise, your operating systems's
-version of ftp may issue messages with a slightly different format than ours
-
-@verbatim
-
-bundle monitor watch_ftp
-{
-vars:
- "dir" slist => { "get", "put" };
-
-measurements:
-
- "/var/log/messages"
-
- handle => "ftp_bytes_${dir}",
- stream_type => "file",
- data_type => "int",
- match_value => extract_log(".*ftpd\[.*", ".*${dir} .* = (\d+) bytes.*"),
- history_type => "log",
- action => sample_rate("0");
-
- "/var/log/messages"
-
- handle => "ftp_failed_login",
- stream_type => "file",
- data_type => "counter",
- match_value => scan_log(".*ftpd\[.*", ".*FTP LOGIN FAILED.*"),
- history_type => "log",
- action => sample_rate("0");
-
- "/var/log/messages"
-
- handle => "ftp_failed_anonymous_login",
- stream_type => "file",
- data_type => "counter",
- match_value => scan_log(".*ftpd\[.*", ".*ANONYMOUS FTP LOGIN REFUSED.*"),
- history_type => "log",
- action => sample_rate("0");
-
-}
-
-##########################################################
-
-body match_value scan_log(line)
-{
-select_line_matching => "$(line)";
-track_growing_file => "true";
-}
-
-body match_value extract_log(line, extract)
-{
-select_line_matching => "$(line)";
-extraction_regex => "$(extract)";
-track_growing_file => "true";
-}
-
-body action sample_rate(x)
-{
-ifelapsed => "$(x)";
-expireafter => "10";
-}
-@end verbatim
-
-@node DNS, Email, FTP, Monitoring customization
-@unnumberedsec Scanning DNS logs for query statistics
-@sp 1
-
-Another thing you might want to do is monitor the types of queries that your
-DNS server is being given. One possible reason for this is to test for
-unusual behavior. For example, suddenly seeing a surge in @samp{MX} requests
-might indicate that your system is being targeted by spammers (or that one of
-your users is sending spam). If you are thinking of converting to IPv6, you
-might want to compare the number of @samp{A} requests to @samp{AAAA} and
-@samp{A6} requests to see how effective your IPv6 implementation is.
-
-Because DNS logs are directly maintained by @samp{bind} or @samp{named} (and
-do not go through syslog), the parsing can be simpler. However, you @i{do}
-need to configure DNS to log query requests to the appropriate log file. In
-our case, we use @file{/var/log/named/queries}.
-
-@verbatim
-
-bundle monitor watch_dns
-{
-vars:
- "query_type" slist => { "A", "AAAA", "A6", "CNAME", "MX", "NS",
- "PTR", "SOA", "TXT", "SRV", "ANY" };
-measurements:
- "/var/log/named/queries"
- handle => "DNS_$(query_type)_counter",
- stream_type => "file",
- data_type => "counter",
- match_value => scan_log(".* IN $(query_type).*"),
- history_type => "log",
- action => sample_rate("0");
-}
-
-##########################################################
-
-body match_value scan_log(line)
-{
-select_line_matching => "$(line)";
-track_growing_file => "true";
-}
-
-body action sample_rate(x)
-{
-ifelapsed => "$(x)";
-expireafter => "10";
-}
-@end verbatim
-
-@node Email, Milter, DNS, Monitoring customization
-@unnumberedsec Scanning syslog for email statistics
-@sp 1
-
-Email is another syslog-based facility that you may want to use CFEngine to
-monitor. There are a number of volumetric data that are of interest. For
-example, the number of messages sent and received, the number of messages
-that have been deferred (a large number might indicate networking problems or
-spam bounces), and the number of spam messages that have been
-detected and removed by the assorted spam filters.
-
-The samples below assume that there is a separate logfile for email (called
-@file{/var/log/maillog}) and that a few of the standard sendmail rulesets
-have been enabled (see
-@samp{http://www.sendmail.org/~ca/email/relayingdenied.html} for details).
-As with any syslog-generated file, you need to check for the appropriate
-service, and in this case we are lumping local messages (sent through
-@samp{sm-mta}) and remote messages (sent through @samp{sendmail}) into a
-single count. Your mileage may of course vary.
-
-If you use one or more sendmail "milters", each of these will also output
-their own syslog messages, and you may choose to track the volume of
-rejections on a per-filter basis.
-
-@verbatim
-
-bundle monitor watch_email
-{
-vars:
- "sendmail" string => ".*(sendmail|sm-mta)\[.*";
-
- "action" slist => { "Sent", "Deferred" };
-
-measurements:
-
- "/var/log/maillog"
-
- handle => "spam_rejected",
- stream_type => "file",
- data_type => "counter",
- # This matches 3 kinds of rulesets: check_mail,
- # check_rcpt, and check_relay
- match_value => scan_log("$(sendmail)ruleset=check_(mail|rcpt|relay).*"),
- history_type => "log",
- action => sample_rate("0");
-
- "/var/log/maillog"
-
- handle => canonify("mail_$(action)",
- stream_type => "file",
- data_type => "counter",
- match_value => scan_log("$(sendmail)stat=$(action) .*"),
- history_type => "log",
- action => sample_rate("0");
-
-}
-
-##########################################################
-
-body match_value scan_log(line)
-{
-select_line_matching => "$(line)";
-track_growing_file => "true";
-}
-
-body action sample_rate(x)
-{
-ifelapsed => "$(x)";
-expireafter => "10";
-}
-@end verbatim
-
-@node Milter, Breakin, Email, Monitoring customization
-@unnumberedsec Scanning syslog for email milter failures
-@sp 1
-
-Milters are relatively new in sendmail, and some have problems. You can also
-use monitoring to detect certain types of failure modes. For example, if a
-milter is running (that is, there is a process present) but it does not
-respond correctly, sendmail will log an entry like this in syslog (where
-@samp{xyzzy} is the name of the milter in question):
-
-@verbatim
-Milter (xyzzy): to error state
-@end verbatim
-
-A small number of these messages is no big deal, since sometimes the milter
-has temporary problems or simply encounters an email message that it finds
-confounding. But a larger value of these messages usually indicates that the
-milter is in a broken state, and should be restarted.
-
-You can use @samp{cf-monitord} to check for the number of these kinds of
-messages, and use the soft classes that it creates to change how
-@samp{cf-agent} operates. For example, here we will restart any milter
-which is showing a high number of failure-mode messages:
-
-@verbatim
-bundle monitor watch_milter
-{
-vars:
- "milter" slist => { "dcc", "bogom", "greylist" };
-
-measurements:
-
- "/var/log/maillog"
-
- handle => "${milter}_errors",
- stream_type => "file",
- data_type => "counter",
- match_value => scan_log(".*Milter (${milter}): to error state"),
- history_type => "log",
- action => sample_rate("0");
-}
-
-bundle agent fix_milter
-{
-vars:
- "m[dcc]" string => "/var/dcc/libexec/start-dccm";
- "m[bogom]" string => "/usr/local/etc/rc.d/milter-bogom.sh restart";
- "m[greylist]" string => "/usr/local/etc/rc.d/milter-greylist restart";
-
-commands:
- "$(m[$(watch_milter.milter)])"
- ifvarclass => "$(watch_milter.milter)_high";
-}
-@end verbatim
-
-
-@node Breakin, Threshold monitoring, Milter, Monitoring customization
-@unnumberedsec Scanning syslog for breakin attempts
-@sp 1
-
-A lot of script-kiddies will probe your site for vulnerabilities, using
-dictionaries of account/password combinations, looking for unguarded accounts
-or accouts with default passwords. Most of these scans are harmless, because
-a well-maintained site will not use the default passwords that these hackers
-seek to exploit.
-
-However, knowing that you are being scanned is a good thing, and CFEngine can
-help you find that out. Because @samp{sshd} logs it's message through
-@samp{syslog}, we again need to filter lines based on the service name. On
-our system, authorization messages are routed to @file{/var/log/auth.log},
-and we would monitor it like this:
-
-@verbatim
-bundle monitor watch_breakin_attempts
-{
-measurements:
- "/var/log/auth.log"
- # This is likely what you'll see when a script kiddie probes
- # your system
-
- handle => "ssh_username_probe",
- stream_type => "file",
- data_type => "counter",
- match_value => scan_log(".*sshd\[.*Invalid user.*"),
- history_type => "log",
- action => sample_rate("0");
-
- "/var/log/auth.log"
- # As scary as this looks, it may just be because someone's DNS
- # records are misconfigured - but you should double check!
-
- handle => "ssh_reverse_map_problem",
- stream_type => "file",
- data_type => "counter",
- match_value => scan_log(".*sshd\[.*POSSIBLE BREAK-IN ATTEMPT!.*"),
- history_type => "log",
- action => sample_rate("0");
-
- "/var/log/auth.log"
- # Someone is trying to log in to an account that is locked
- # out in the sshd config file
-
- handle => "ssh_denygroups",
- stream_type => "file",
- data_type => "counter",
- match_value => scan_log(".*sshd\[.*group is listed in DenyGroups.*"),
- history_type => "log",
- action => sample_rate("0");
-
- "/var/log/auth.log"
- # This is more a configuration error in /etc/passwd than a
- # breakin attempt...
-
- handle => "ssh_no_shell",
- stream_type => "file",
- data_type => "counter",
- match_value => scan_log(".*sshd\[.*because shell \S+ does not exist.*"),
- history_type => "log",
- action => sample_rate("0");
-
- "/var/log/auth.log"
- # These errors usually indicate a problem authenticating to your
- # IMAP or POP3 server
-
- handle => "ssh_pam_error",
- stream_type => "file",
- data_type => "counter",
- match_value => scan_log(".*sshd\[.*error: PAM: authentication error.*"),
- history_type => "log",
- action => sample_rate("0");
-
- "/var/log/auth.log"
- # These errors usually indicate that you haven't rebuilt your
- # database after changing /etc/login.conf - maybe you should
- # include a rule to do this command: cap_mkdb /etc/login.conf
-
- handle => "ssh_pam_error",
- stream_type => "file",
- data_type => "counter",
- match_value => scan_log(".*sshd\[.*login_getclass: unknown class.*"),
- history_type => "log",
- action => sample_rate("0");
-}
-
-@end verbatim
-
-
-See the CFEngine Nova documentation for more possibilities of measurement
-promises.
-
-
-
-@node Threshold monitoring, Summary Monitoring, Breakin, Monitoring customization
-@unnumberedsec Threshold monitoring
-
-@verbatim
-vars:
-
- "probes" slist => { "www", "smtp", "ssh" };
-
-classes:
-
- "$(probes)_threshold" expression => isgreaterthan("$(mon.$(probes))","50");
-
-reports:
-
- "Help $(probes)!" ifvarclass => "$(probes)_threshold";
-
-@end verbatim
-
-
-
-
-@node Summary Monitoring, , Threshold monitoring, Monitoring customization
-@unnumberedsec Summary Monitoring
-
-
-There are endless possibilities for monitoring with CFEngine
-Nova. This document has suggested a few.
-
-
-
-
-
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_NovaReportArch.texinfo b/docs/guides/SpecialTopic_NovaReportArch.texinfo
deleted file mode 100644
index 0d53050eee..0000000000
--- a/docs/guides/SpecialTopic_NovaReportArch.texinfo
+++ /dev/null
@@ -1,205 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-novareportarch.info
-@settitle The Nova Report Architecture
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title The Nova Report Architecture
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-In the default set-up, CFEngine Nova is a star network and uses
-bidirectional communication on port @code{5308} between the policy hub
-and client hosts.
-
-However, Nova does not require network at all --- you can manage and
-track your systems with a usb-stick if you wish.
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2011 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@node reportarch
-@top The Nova Report Architecture
-@menu
-@end menu
-
-
-
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-
-
-@node What is Open Nebula, How can CFEngine work with Open Nebula, Top, Top
-@unnumberedsec What is Open Nebula?
-
-Open Nebula is an Open Source framework for Cloud Computing that aims
-to become an industry standard. The project is designed to be scalable
-and offer compatbility with Amazon EC2 the Open Cloud Computing
-Interface (OCCI). Open Nebula is used as a cloud controller in a
-number of large private clouds.
-
-
-@node How can CFEngine work with Open Nebula, Example Setup, What is Open Nebula, Top
-@unnumberedsec How can CFEngine work with Open Nebula?
-
-CFEngine is a lifecycle management tool that can be integrated with a
-Cloud Computing framework in a number of ways. Of the four phases of the computer lifecycle,
-Open Nebula and CFEngine will play different roles.
-@table @i
-@item Build
-Open Nebula focuses on building virtual machines in a managed framework, based on pre-built
-images. CFEngine can further customize these images through package of customized installation
-measures.
-@item Deploy
-Open Nebula provides manual controls to bring up and tear down generic virtualized machines
-containing a baseline of software. CFEngine can further deploy patches and updates to these basic
-images without needing to take down a machine.
-@item Manage
-One a machine is running, CFEngine can manage it exactly like any other physical computer.
-@item Audit/Report
-CFEngine's local agents can extract information and learn system trends and characteristics
-over time. These may be collected in CFEngine's reporting interface or Mission Portal.
-@end table
-
-@sp 1
-@cartouche
-Open Nebula's focus is on managing the deployment and recycling of the computing infrastucture.
-CFEngine picks up where Open Nebula leaves off and manages the dynamic lifecycle of software,
-applications and runtime state.
-@end cartouche
-
-@sp 1
-
-@node Example Setup, Installation and dependancy configuration, How can CFEngine work with Open Nebula, Top
-@unnumberedsec Example Setup
-
-@sp 1
-
-This guide is based on an example setup provding a framework to
-demonstrate how CFEngine can be used to automate Open Nebula
-configuration. The following assumptions serve as an example and
-should be altered to fit your needs:
-
-@sp 1
-
-@itemize
- @item
- All physical hosts are running Ubnutu, KVM and CFEngine 3.
- @item
- All physical hosts are on the same network.
- @item
- The CFEngine policy hub is running on the Open nebula front end.
- @item
- NFS will be used to share virtual machine images between hosts.
-@end itemize
-
-@sp 1
-
-Open nebula requires a single front-end machine and one or more node
-controllers. The front end is a management machine that is used to
-monitor and issue commands to the node controllers. Node controllers
-provide virtual machine resources. The promises that follow
-concentrate on the configuration of the front-end and a single
-cluster-node. In order to increase the capacity of your private cloud
-we can simply classify a new physical machine as another cluster-node.
-
-@center @image{ONarchitecture,5in,,,png}
-
-@node Installation and dependancy configuration, NFS config for shared image repository, Example Setup, Top
-@unnumberedsec Installation and dependancy configuration
-
-@sp 1
-
-First we can classify the physical machines in this case by IP address:
-@sp 1
-@verbatim
-classes:
- "front_end" or => {"192.168.1.2"};
- "node_controllers" or => {"192.168.1.3"};
-@end verbatim
-@sp 1
-@noindent If we want multiple node controllers then we can instead setup an slist variable
- IP addresses of intended node controllers. This will allow the
-"onehost create" command to execution each new node controller in turn
-reducing redundancy in the policy file for example:
-@sp 1
-@verbatim
-vars:
- "node_controller" slist => { "192.168.1.3", "192.168.1.4", "192.168.1.5" };
-
-commands:
- "/usr/bin/onehost create $(node_controller) im_kvm vmm_kvm tm_nfs",
- contain => oneadmin;
-
-
-classes:
-
- "policy_host" or => {
- classmatch(canonify("ipv4_$(node_controller)")),
- classmatch(canonify("$(node_controller)"))
- };
-@end verbatim
-@sp 1
-@noindent To install the dependancies for each physical machine we can define these in a list and use the CFEngine standard library package promises to install them:
-@sp 1
-@verbatim
-vars:
-
-"front_end_deps" slist => {
- "libcurl3",
- "libmysqlclient16",
- "libruby1.8",
- "libsqlite3-ruby",
- "libsqlite3-ruby1.8",
- "libxmlrpc-c3",
- "libxmlrpc-core-c3",
- "mysql-common",
- "ruby",
- "ruby1.8",
- "nfs-kernel-server"
- };
-"cluster_node_deps" slist => {
- "ruby",
- "kvm",
- "libvirt-bin",
- "ubuntu-vm-builder",
- "nfs-client",
- "kvm-pxe"
- };
-@end verbatim
-@sp 1
-@noindent Promises to perform dependency installation:
-@sp 1
-@verbatim
-packages:
-
-front_end::
- "$(front_end_deps)"
-
- comment => "Install open nebula front end dependencies",
- package_policy => "add",
- package_method => generic,
- classes => if_ok("ensure_opennebula_running");
-
-node_controller::
- "$(node_controller_deps)"
- comment => "Install open nebula node controller dependencies",
- package_policy => "add",
- package_method => generic;
-@end verbatim
-@sp 1
-@noindent The additional line in the front end dependancy installation promise, assuming a successful installation, will ensure the Open Nebula daemon is running at all times:
-@sp 1
-@verbatim
-front_end::
-
-ensure_opennebula_running::
- ".*oned.*",
- restart_class => "start_oned";
-@end verbatim
-@sp 1
-@noindent Resulting in:
-@sp 1
-@verbatim
-commands:
-
-start_oned::
- "/usr/bin/one start",
- comment => "Execute the opennebula daemon",
- contain => oneadmin;
-@end verbatim
-@sp 1
-@noindent Since we will be using Open Nebula version 2 we must manually supply the package:
-@sp 1
-@verbatim
-commands:
-
-front_end.!opennebula_installed::
- "/usr/bin/dpkg -i /root/opennebula_2.0-1_i386.deb",
- comment => "install opennebula package if it isnt already";
-@end verbatim
-@sp 1
-@noindent This promise points to the Open Nebula package file in /root/. To prevent repeated installation we can do a check to see if Open Nebula has already been installed by classifying a successful installation as having the oned.conf file in existence:
-@sp 1
-@verbatim
-classes:
-
- "opennebula_installed" or => {fileexists("/etc/one/oned.conf")};
-@end verbatim
-@sp 1
-@noindent Open nebula requires a privileged user "oneadmin" to issue commands. In order to have CFEngine perform these commands with the correct privileges we can use the contain body by appending the following to commands promises:
-@sp 1
-@verbatim
- contain => oneadmin
-@end verbatim
-@sp 1
-@noindent This will in turn apply owner and group permissions of the oneadmin user:
-
-@verbatim
-body contain oneadmin
-{
-exec_owner => "oneadmin";
-exec_group => "oneadmin";
-}
-@end verbatim
-
-@node NFS config for shared image repository, Open Nebula environment configuration, Installation and dependancy configuration, Top
-@unnumberedsec NFS config for shared image repository
-
-@sp 1
-
-If not present append the NFS export directory stored in the corresponding variable (including a new line):
-@verbatim
-
-vars:
-
-"nfs_export_dir"
-
- slist =>
- {
- "/var/lib/one 192.168.1.2/255.255.255.0(rw,sync,no_subtree_check)",
- ""
- };
-
-files:
-
-"/etc/exports",
- edit_line => append_if_no_lines($(nfs_export_dir)),
- comment => "export nfs image repo";
-@end verbatim
-To ensure the NFS service remains available:
-@verbatim
-processes:
-
-ensure_nfs_running::
- ".*nfsd.*",
- restart_class => "start_nfs";
-@end verbatim
-If this is found to be false then we classify:
-@verbatim
-start_nfs::
- "service nfs-kernel-server restart",
- comment => "restart nfs";
-@end verbatim
-@noindent In order to ensure the share is mounted on all node controllers we can use the NFS promise:
-
-@verbatim
-storage:
-
-cluster_node::
-"/var/lib/one",
- mount => nfs("192.168.1.2","/var/lib/one"),
- comment => "mount image repo from front end";
-@end verbatim
-Next we will create a directory to hold our virtual machine images:
-@verbatim
-"/var/lib/one/images/.",
- comment => "create dir in image repo share",
- perms => mog("644", "oneadmin", "oneadmin"),
- create => "true";
-@end verbatim
-
-@node Open Nebula environment configuration, Network configuration, NFS config for shared image repository, Top
-@unnumberedsec Open Nebula environment configuration
-
-Create the oneadmin bashrc file containing the ONE_XMLRPC environment variable with appropriate permissions:
-@verbatim
-files:
- front_end::
- "/var/lib/one/.bashrc"
- comment => "setup oneadmin env",
- perms => mog("644", "oneadmin", "oneadmin"),
- create => "true",
- edit_line => append_if_no_line(
- "export ONE_XMLRPC=http://localhost:2633/RPC2");
-@end verbatim
-We also need to create the one_auth file:
-@verbatim
-files:
- front_end::
- "/var/lib/one/.one/one_auth",
- comment => "create open nebula auth file",
- perms => mog("644", "oneadmin", "oneadmin"),
- create => "true",
- edit_line => append_if_no_line("username:password");
-@end verbatim
-Finally password-less authentication for the oneadmin user:
-
-Add key to autorized_keys file:
-@verbatim
-files:
- front_end::
- "/var/lib/one/.ssh/authorized_keys",
- comment => "copy sshkey to authorized",
- perms => mog("644", "oneadmin", "oneadmin"),
- copy_from => local_cp("/var/lib/one/.ssh/id_rsa.pub");
-@end verbatim
-Disable known hosts prompt:
-@verbatim
-front_end::
-"/var/lib/one/.ssh/config",
- comment => "disable strict host key checking",
- perms => mog("644", "oneadmin", "oneadmin"),
- create => "true",
- edit_line => append_if_no_line("Host *
- StrictHostKeyChecking no");
-@end verbatim
-Now on the node controller(s) we need to add the oneadmin group and
-user with the same uid and gid as the front end and add the oneadmin
-user to the libvertd group:
-@verbatim
-files:
- node_controller::
- "/etc/passwd",
- comment => "add oneadmin user to node controller",
- edit_line => append_if_no_line("oneadmin:x:999:999::/srv/cloud/one:/bin/bash");
-
- "/etc/group",
- comment => "add oneadmin group to node controller",
- edit_line => append_if_no_line("oneadmin:x:999:");
-
- "/etc/group",
- comment =>"add oneadmin to libvirtd group",
- edit_line => append_user_field("libvirtd","4","oneadmin");
-@end verbatim
-Now that the user environment is configured we can register our node controller with the front end:
-@verbatim
-files:
- front_end::
- "/usr/bin/onehost create 192.168.1.2 im_kvm vmm_kvm tm_nfs",
- contain => oneadmin;
-@end verbatim
-@node Network configuration, Virtual machine template configuration, Open Nebula environment configuration, Top
-@unnumberedsec Network configuration
-
-Before we can create virtual networks we must configure our node controller interfaces. In this example we will bridge a virtual interface (vbr0) with eth0. First we define the contents of the interfaces file in a variable:
-@verbatim
-vars:
-"interfaces_contents" slist => {
- "auto lo",
- "iface lo inet loopback",
- "auto vbr0",
- "iface vbr0 inet static",
- "address 192.168.1.2",
- "netmask 255.255.255.0",
- "network 192.168.1.0",
- "broadcast 192.168.1.255",
- "gateway 192.168.1.1",
- "dns-nameservers 192.168.1.1",
- "bridge_ports eth0",
- "bridge_stp off",
- "bridge_maxwait 0",
- "bridge_fd 0"
- };
-@end verbatim
-@noindent Next we edit the interfaces file to include our new settings:
-@verbatim
-files:
-node_controller::
-"/etc/network/interfaces",
- comment => "ensure bridge for open nebula vm networks",
- edit_line => append_if_no_lines($(interfaces_contents)),
- create => "true",
- perms => mog("644", "root", "root");
-@end verbatim
-And restart networking:
-@verbatim
-commands:
- restart_networking::
-
- "/etc/init.d/networking restart",
- comment => "restart networking";
-@end verbatim
-Now we have configured the network bridge we can create an Open Nebula
-virtual network file and submit it to the system. The contents of the
-virtual network template file could be defined as a variable as we
-have seen before but in this case it is passed as a parameter to the
-append promise body:
-@verbatim
-"/var/lib/one/network.template",
- comment => "create lan template",
- create => "true",
- perms => mog("644", "oneadmin", "oneadmin"),
- edit_line => append_if_no_line("NAME = \"VM LAN\"
-TYPE = FIXED
-BRIDGE = vbr0
-LEASES = [IP=192.168.1.100]");
-@end verbatim
-The network template only deals with fixed ip addresses and provides only one lease. Obviously this should be altered to suite your requirements. Now we have a template we can register it with open nebula:
-@verbatim
-commands:
- front_end::
- "/usr/bin/onevnet create /var/lib/one/network.template",
- contain => oneadmin;
-
-@end verbatim
-
-@node Virtual machine template configuration, Open Nebula Commands, Network configuration, Top
-@unnumberedsec Virtual machine template configuration
-
-@noindent This follows the same pattern as virtual network setup. First we create the template file:
-@verbatim
-files:
-
- "/var/lib/one/vm.template",
- comment => "create vm template",
- create => "true",
- perms => mog("644", "oneadmin", "oneadmin"),
- edit_line => append_if_no_line("NAME = ubuntu-10.04-i386
-CPU = 0.1
-MEMORY = 256
-DISK = [
- source = \"/var/lib/one/images/open_nebula.img\",
- target = \"vda\",
- readonly = \"no\" ]
-DISK = [
- type = \"swap\",
- size = 1024,
- target = \"vdb\"]
-
-NIC = [ NETWORK = \"VM LAN\" ]
-INPUT = [ TYPE = \"mouse\", BUS = \"ps2\" ]
-GRAPHICS = [TYPE = \"vnc\", LISTEN = \"localhost\", PORT = 5910]
-");
-@end verbatim
-@noindent Now we can launch the virtual machine defined in its template file:
-@verbatim
-commands:
- front_end::
- "/usr/bin/onevm create /var/lib/one/vm.template",
- contain => oneadmin;
-@end verbatim
-@noindent If we increase the leases in our network template each time the onevm create command is issued a new virtual machine will be launched up to the number of available leases.
-
-@node Open Nebula Commands, Virtual machine configuration, Virtual machine template configuration, Top
-@unnumberedsec Open Nebula Commands
-
-It should be noted that commands, particularly those that are Open
-Nebula specific, will be run each time cf-agent is executed. Since this
-goes against the idea of convergence it is necessary to add some
-additional classification. One method is to create a 'stamp' file
-after a particular command is successfully executed. If this file
-exists then (or if its time stamp is older/newer than some value) the
-machines classified as having to run the command loose that class
-preventing future execution.
-
-@node Virtual machine configuration, Open Nebula Summary, Open Nebula Commands, Top
-@unnumberedsec Virtual machine configuration
-
-With CFEngine preinstalled in our virtual machine image we can
-configure our generic image to the required specification on the
-fly. For community edition we will need to exchange keys and define
-access rules to the virtual machine can collect the policy files. with
-CFEngine nova this step is even simpler as we can set a start up
-script to issue the bootstrap command so the new vm automatically
-registers with the policy hub.
-
-Once registration is complete we can define a new class based on the
-ip of our virtual machine. In this example that is 192.168.1.100 so we
-can create a class with a meaningful name:
-@verbatim
-"webserver" or => {"192_168_1_100"};
-@end verbatim
-@noindent Now we have define webserver we can simply apply promises to it as if it was any other machine for example:
-
-@menu
-* Webserver in Open Nebula::
-@end menu
-
-@node Webserver in Open Nebula, , Virtual machine configuration, Virtual machine configuration
-@unnumberedsubsec Webserver in Open Nebula
-
-First we install apache:
-
-@verbatim
-packages:
- webserver::
-
- "apache2",
- comment => "install apache2 on webserver vm",
- package_policy => "add",
- package_method => generic,
- classes => if_ok("ensure_apache_running");
-@end verbatim
-@noindent Next we ensure it is running
-@verbatim
-processes:
- ensure_apache_running::
-
- ".*apache2.*"
- restart_class => "start_apache";
-@end verbatim
-@noindent If not, the service is restarted
-@verbatim
-commands:
- start_apache::
-
- "/etc/init.d/apache2 restart";
-@end verbatim
-@noindent Finally we can copy some content into the document root on our new virtual webserver:
-@verbatim
-files:
- "/var/www"
-
- perms => system("744"),
- copy_from => uu_scp("/root/webserver_site_files","192.168.1.6"),
- depth_search => recurse("inf"),
- action => u_immediate;
-@end verbatim
-
-@node Open Nebula Summary, , Virtual machine configuration, Top
-@unnumberedsec Open Nebula Summary
-
-Now we have a convergent self-repairing, Open Nebula powered private
-cloud! The main benefits in combining CFEngine and Open Nebula are the
-facility to increase infrastructure capacity just by connecting a new
-node controller to the network, and then allowing CFEngine to
-configure and maintain it over time. Finally, there is the hands-free
-configuration of generic virtual machine images to an arbitrary
-specification, without touching the virtual
-machine itself.
-
-There is a vast array of configuration options and choices to be made
-in an Open Nebula setup, as with CFEngine. This flexibility is one of
-its strengths. This guide demonstrates only a small subset of possible
-configuration choices aiming to provide a starting point for more
-comprehensive setups.
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_Packages.texinfo b/docs/guides/SpecialTopic_Packages.texinfo
deleted file mode 100644
index 71e5b26db1..0000000000
--- a/docs/guides/SpecialTopic_Packages.texinfo
+++ /dev/null
@@ -1,559 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-packages.info
-@settitle Package Management
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Package Management
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-CFEngine interfaces with operating system package management systems
-to offer best-effort convergent maintenance of software packages.
-Package management can be subtle, due to the diverse behaviours of
-different package managers.
-@end quotation
-@end cartouche
-
-@vskip 2cm
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2011 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-
-
-@node Top, What is package management?, (dir), (dir)
-@top Package management
-
-@menu
-* What is package management?::
-* Strengths and weaknesses of package management::
-* What does CFEngine bring to package management?::
-* Package promises::
-* How CFEngine compares package versions::
-* Example package promises::
-* Package management next steps::
-@end menu
-
-
-
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@node What is package management?, Strengths and weaknesses of package management, Top, Top
-@unnumberedsec What is package management?
-@sp 1
-Package management is about managing software inventory. It includes
-ensuring that software is installed on computers, and in the correct
-versions. It includes patching and upgrading. Each operating system generally
-has its own approved package manager and software source. Usually this
-is supplied by the operating system provider.
-
-Some package managers allow users to create their own software
-packages providing a uniform way of deploying software to systems.
-Packaging software is common on GNU/Linux, where well-known package formats include RPM
-and deb.
-
-
-@node Strengths and weaknesses of package management, What does CFEngine bring to package management?, What is package management?, Top
-@unnumberedsec Strengths and weaknesses of package management
-@sp 1
-
-Packages were introduced to bring a rational approach to handling software dependencies.
-By dividing up applications and libraries into packages, one can share code efficiently
-and assign the responsibility of updating and versioning to different maintainers.
-
-Package management is not a substitute for configuration
-management. It only delivers preconfigured files into a specific
-location. Packaged software cannot be customized to local needs
-without post-installation adaptation.
-
-
-@node What does CFEngine bring to package management?, Package promises, Strengths and weaknesses of package management, Top
-@unnumberedsec What does CFEngine bring to package management?
-@sp 1
-
-CFEngine does not try to fight against package mangers, but rather
-work with them. CFEngine integrates the idea of convergent
-maintenance with package installation, so that one can be certain
-of maintaining a desired state.
-
-Package managers do not usually have the
-intelligence to be able to verify the actual state of software
-configuration. Rather they assume that once a package is installed,
-it will remain in a good state until an update is required.
-
-If one reinstalls a package, changes get blown away in favour of the
-original matrix. Package installation is thus a `destructive'
-installation mechanism. It overwrites whatever currently exists with a
-prefabricated (and therefore approximate) version of what you
-need. For generic software this is exactly what is required. However,
-for complex software such as web services, this is entirely
-insufficient to result in a working system.
-
-CFEngine brings convergent methods to package management, and allows surgically
-precise customizations to be applied and maintained even after multiple
-package upgrades.
-
-
-
-@node Package promises, How CFEngine compares package versions, What does CFEngine bring to package management?, Top
-@unnumberedsec Package promises
-@sp 1
-
-To manage software, you write @code{packages} promises, analogous to any other kind of
-promise in CFEngine. It makes sense to use lists to install packages if you
-don't need to make complex specifications about versions. Keep it simple and
-package management will be a simple matter.
-
-@cartouche
-@verbatim
- vars:
- "match_package" slist => {
- "apache2",
- "apache2-mod_php5",
- "apache2-prefork",
- "php5"
- };
- packages:
-
- "$(match_package)"
- package_policy => "add",
- package_method => yum;
-
-@end verbatim
-@end cartouche
-
-Many users elect to install a basic `stem cell' image for all machines
-in their environment, and then customize each machine to a specific
-purpose by adding or subtracting packages from this stem cell starting
-state. CFEngine can be used together with other tools like
-@code{Cobbler} or @code{rPath} to accomplish this in a comfortable way
-in your environment. If you are working in the cloud, this is the
-default approach to management. You begin from a basic image and then
-customize it by either hardening or extending the software inventory.
-
-@node How CFEngine compares package versions, Example package promises, Package promises, Top
-@unnumberedsec How CFEngine compares package versions
-@sp 1
-
-Cfengine uses a model for packages that is generic enough to support all the known
-package managers. It classifies packages into
-
-@table @i
-@item Name
-The name of the packet is usually the name of the software itself, e.g. @samp{cfengine}.
-@item Version
-Versions of a particular piece of software are described in wildly
-different ways, causing a lot of confusion. For instance, a common
-model is to use major version number, minor version number and patch
-release number, e.g. 3.1.5. However, many maintainers slap on their
-own additions, such as 3.1.5-2 or 3.1.5-2.el5. Because these models
-are operating system, software and release specific, you have to know
-the versioning numbers used on your operating systems and refer to
-them properly. CFEngine cannot reliabily guess these things for you.
-
-@item Architecture
-The architecture describes the hardware platform for execution, e.g.
-@samp{x86_64} or @samp{i586}. This is important when package managers
-store multiple architectures in the same repository.
-@end table
-
-
-
-@node Example package promises, Package management next steps, How CFEngine compares package versions, Top
-@unnumberedsec Example package promises
-@sp 1
-
-Let's look at some example cases to explain the behaviour of the interaction between CFEngine and
-the package managers.
-
-
-
-@menu
-* Install latest package version example::
-* Install specific package version example::
-* Uprading to a newer package version example::
-@end menu
-
-@node Install latest package version example, Install specific package version example, Example package promises, Example package promises
-@unnumberedsubsec Install latest package version example
-@sp 1
-
-
-Suppose there is a older version of @code{wget} installed on your machine.
-@cartouche
-@verbatim
-redhat$ rpm -q wget
-wget-1.10.2-7.el5
-@end verbatim
-@end cartouche
-@sp 1
-@noindent Now suppose you'd like to upgrade the package to the latest version available in a repository by using @code{yum}.
-We make a promise such the following;
-@verbatim
-bundle agent test001
-{
- packages:
- redhat::
- "wget"
- package_policy => "addupdate",
- package_method => yum,
- package_select => ">=",
- package_version => "1.11.4-2.el5_4.1",
- package_architectures => { "x86_64" };
-
-}
-@end verbatim
-@sp 1
-@noindent Now run this bundle:
-@cartouche
-@verbatim
-redhat$ /var/cfengine/bin/cf-agent -f /tmp/test.cf -K
-
-redhat$ rpm -q wget
-wget-1.11.4-2.el5_4.1
-@end verbatim
-@end cartouche
-@sp 1
-@noindent If there is no @code{wget} installed, CFE will install the lastest one for you.
-@verbatim
-redhat$ rpm -e wget
-redhat$ rpm -q wget
-package wget is not installed
-redhat$ /var/cfengine/bin/cf-agent -f /tmp/test.cf -K
-redhat$ rpm -q wget
-wget-1.11.4-2.el5_4.1
-@end verbatim
-
-@node Install specific package version example, Uprading to a newer package version example, Install latest package version example, Example package promises
-@unnumberedsubsec Install specific package version example
-@sp 1
-
-To install a specific version, we can just adapt the promise.
-This example will use RPM as the YUM repository doesn't support multi-version packages.
-@verbatim
-bundle agent test002
-{
- packages:
- redhat::
- "wget"
- package_policy => "addupdate",
- package_method => rpm_version("/root"),
- package_select => "==",
- package_version => "1.10.2-7.el5",
- package_architectures => { "x86_64" };
-
-}
-@end verbatim
-@sp 1
-@noindent Now see before and after:
-@cartouche
-@verbatim
-redhat$ ls -l /root
--rw-r--r-- 1 root root 595422 Apr 4 2007 wget-1.10.2-7.el5.x86_64.rpm
--rw-r--r-- 1 root root 596335 Nov 5 2009 wget-1.11.4-2.el5_4.1.x86_64.rpm
-
-redhat$ rpm -q wget
-package wget is not installed
-
-redhat$ /var/cfengine/bin/cf-agent -f /tmp/test.cf -K
-
-redhat$ rpm -q wget
-wget-1.10.2-7.el5
-@end verbatim
-@end cartouche
-@sp 1
-@noindent To upgrade the package to a newer version, just change @samp{package_version} to a version you'd like;
-@verbatim
-bundle agent test003
-{
- packages:
- redhat::
- "wget"
- package_policy => "addupdate",
- package_method => rpm_version("/root"),
- package_select => "==",
- package_version => "1.11.4-2.el5_4.1",
- package_architectures => { "x86_64" };
-
-}
-@end verbatim
-@sp 1
-@noindent Now see the result:
-@cartouche
-@verbatim
-redhat$ rpm -q wget
-wget-1.10.2-7.el5
-
-redhat$ /var/cfengine/bin/cf-agent -f /tmp/test.cf -K
-
-redhat$ rpm -q wget
-wget-1.11.4-2.el5_4.1
-@end verbatim
-@end cartouche
-
-@sp 1
-@noindent Here is an example for Ubuntu, which supports both the APT and DPKG interfaces.
-
-@verbatim
-bundle agent test004
-{
- packages:
- ubuntu::
- "wget"
- package_policy => "addupdate",
- package_method => apt,
- package_select => ">=",
- package_version => "1.12-1.1ubuntu2.1",
- package_architectures => { "*" };
-}
-@end verbatim
-@sp 1
-@noindent Before and after:
-@cartouche
-@verbatim
-ubuntu$ dpkg -l | grep wget
-ii wget 1.10.2-3ubuntu1.2 retrieves files from the web
-
-ubuntu$ /var/cfengine/bin/cf-agent -f /tmp/test.cf -K
-
-ubuntu$ dpkg -l | grep wget
-ii wget 1.12-1.1ubuntu2.1 retrieves files from the web
-@end verbatim
-@end cartouche
-@sp 1
-@noindent Similarly, we can use the "dpkg" interface to install specific version of the software.
-
-@verbatim
-bundle agent test005
-{
- packages:
- ubuntu::
- "wget"
- package_policy => "addupdate",
- package_method => dpkg("/root"),
- package_select => "==",
- package_version => "1.10.2-3ubuntu1.2",
- package_architectures => { "*" };
-}
-@end verbatim
-@sp 1
-@noindent Before and after:
-@cartouche
-@verbatim
-ubuntu$ dpkg -l | grep wget
-
-ubuntu$ /var/cfengine/bin/cf-agent -f /tmp/test.cf -K
-
-ubuntu$ dpkg -l | grep wget
-ii wget 1.10.2-3ubuntu1.2 retrieves files from the web
-@end verbatim
-@end cartouche
-@node Uprading to a newer package version example, , Install specific package version example, Example package promises
-@unnumberedsubsec Uprading to a newer package version example
-@sp 1
-
-
-To upgrade to a newer version of apackage, we simply assign a newer version to package_version
-and change the policy to include updating.
-@verbatim
-bundle agent test006
-{
- packages:
- ubuntu::
- "wget"
- package_policy => "addupdate",
- package_method => dpkg("/root"),
- package_select => "==",
- package_version => "1.12-1.1ubuntu2.1",
- package_architectures => { "*" };
-}
-@end verbatim
-@sp 1
-@noindent Before and after the keeping of this promise:
-@cartouche
-@verbatim
-ubuntu$ dpkg -l | grep wget
-ii wget 1.10.2-3ubuntu1.2 retrieves files from the web
-ubuntu$ cf-agent -f /tmp/test.cf -K
-ubuntu$ dpkg -l | grep wget
-ii wget 1.12-1.1ubuntu2.1 retrieves files from the web
-@end verbatim
-@end cartouche
-@sp 1
-@noindent Here is an example using the @code{zypper} package manager:
-@verbatim
-bundle agent test007
-{
- packages:
- SuSE::
- "tcpdump"
- package_policy => "addupdate",
- package_method => zypper,
- package_select => ">=",
- package_version => "4.1.1-1.11",
- package_architectures => { "x86_64" };
-}
-@end verbatim
-@sp 1
-@noindent Before and after running the agent:
-@cartouche
-@verbatim
-suse$ rpm -q tcpdump
-tcpdump-4.0.0-2.1.x86_64
-
-suse$ /var/cfengine/bin/cf-agent -f /tmp/test.cf -K
-
-suse$ rpm -q tcpdump
-tcpdump-4.1.1-1.11.x86_64
-@end verbatim
-@end cartouche
-@sp 1
-@noindent Finally, since SuSE uses RPM as a native format so we can use @samp{package_method rpm()} from above.
-@verbatim
-bundle agent test008
-{
- packages:
- SuSE::
- "tcpdump"
- package_policy => "addupdate",
- package_method => rpm_version("/root"),
- package_select => "==",
- package_version => "4.0.0-2.1",
- package_architectures => { "x86_64" };
-}
-@end verbatim
-@cartouche
-@verbatim
-suse$ ls -l /root
--rw-r--r-- 1 root root 571158 2009-10-19 20:36 tcpdump-4.0.0-2.1.x86_64.rpm
--rw-r--r-- 1 root root 318279 2010-07-05 23:37 tcpdump-4.1.1-1.11.x86_64.rpm
-
-suse$ rpm -q tcpdump
-package tcpdump is not installed
-
-suse$ /var/cfengine/bin/cf-agent -f /tmp/test.cf -K
-
-suse$ rpm -q tcpdump
-tcpdump-4.0.0-2.1.x86_64
-@end verbatim
-@end cartouche
-@sp 1
-@noindent Changing to a new version:
-@verbatim
-bundle agent test009
-{
- packages:
- SuSE::
- "tcpdump"
- package_policy => "addupdate",
- package_method => rpm_version("/root"),
- package_select => "==",
- package_version => "4.1.1-1.11",
- package_architectures => { "x86_64" };
-}
-@end verbatim
-@sp 1
-
-@noindent Before and after:
-@cartouche
-@verbatim
-suse$ rpm -q tcpdump
-tcpdump-4.0.0-2.1.x86_64
-
-suse$ /var/cfengine/bin/cf-agent -f /tmp/test.cf -K
-
-suse$ rpm -q tcpdump
-tcpdump-4.1.1-1.11.x86_64
-@end verbatim
-@end cartouche
-
-
-
-@node Package management next steps, , Example package promises, Top
-@unnumberedsec Package management next steps
-
-The CFEngine standard library contains package manager methods for all
-major operating systems and managers. Check out the reference
-documentation too to learn about extended features of package
-integration. Visit also the community forum to hear about reach
-experiences.
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_RBAC.texinfo b/docs/guides/SpecialTopic_RBAC.texinfo
deleted file mode 100644
index 55ee2b7f02..0000000000
--- a/docs/guides/SpecialTopic_RBAC.texinfo
+++ /dev/null
@@ -1,679 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-rbac.info
-@settitle Role Based Access Control and CFEngine
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Role Based Access Control and CFEngine
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine
-
-
-@page
-
-@cartouche
-@quotation
-Role Based Access Control (RBAC) is a well known paradigm for granting
-privileged access to remote command systems. The paradigm of RBAC does
-not apply directly to CFEngine because CFEngine is an autonomous
-system that does not grant change privileges to external
-users. Role-based read-privileges can be granted through the CFEngine
-Nova Mission portal.
-
-This document is aimed at security experts who are trying to
-understand transference of privilege in a CFEngine managed system.
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2011 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Iteration:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-
-
-
-@node Top, What is Role Based Access Control?, (dir), (dir)
-@top RBAC
-@menu
-* What is Role Based Access Control?::
-* The risks of RBAC::
-* CFEngine's approach to privilege::
-* The chain of privilege in CFEngine::
-* The role of centralized push and pull in RBAC::
-* No need for any centralization in CFEngine::
-* The risk from centralized trusted hosts::
-* The Policy Dispatch Point::
-* The right to edit and publish policy::
-* The bowtie process::
-* Granting the right to switch on special pre-defined policies::
-@end menu
-
-
-@end ifnottex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@node What is Role Based Access Control?, The risks of RBAC, Top, Top
-@unnumberedsec What is Role Based Access Control?
-
-Role Based Access Control (RBAC) describes a set of promises made by a host
-to grant privileged access to the system. In this regard, RBAC is no
-different from any other form of access control, however, it is
-normally used to grant the privilege to execute certain commands that
-make changes to the system -- thus it involves @i{write} or @i{change}
-privilege.
-
-The term @i{role}-based is used because users are often classified
-into managerial roles that are each assigned different levels of privilege
-with regard to the kind of tasks they need to perform.
-
-Role Based Access Control is used when remote users request access to
-a privileged service from some kind of service-agent running on a host.
-For example, the password on the Unix root account is a simple RBAC system where
-access is granted to execute any command with unlimited privilege, to
-any user who knows the root password.
-
-@sp 1
-@center @image{rbac,10cm}
-@sp 1
-@center RBAC is about remote action privilege
-@sp 1
-
-
-@node The risks of RBAC, CFEngine's approach to privilege, What is Role Based Access Control?, Top
-@unnumberedsec The risks of RBAC
-
-Granting privilege to execute commands has obvious risks. The
-implementation of restricted access is usually handled in one of a
-number of different ways. The term RBAC does not explain, in itself,
-which of these models will be used.
-
-Two common alternatives may be distinguished:
-
-@table @i
-@item Arbitrary commands may be executed by privileged individuals (trusted user model).
-
-This is a high risk privilege granting system, where arbitrary change privileges are granted to
-users.
-
-@item Pre-defined privileged operations may be made accessible to certain individuals/roles (Clark-Wilson model).
-
-This is a lower risk system, where users are only allowed privilege while executing very specific
-pre-defined activities (e.g. the right to initiate a backup).
-
-@end table
-
-@node CFEngine's approach to privilege, The chain of privilege in CFEngine, The risks of RBAC, Top
-@unnumberedsec CFEngine's approach to privilege
-
-
-CFEngine handles privileged access somewhat differently. To see why, it is important
-to understand what CFEngine is not:
-@itemize
-@item CFEngine is not a service agent that grants remote change access to systems.
-@item CFEngine is not a remote-control for system operations@footnote{Many provisioning and management systems are indeed
-effectively remote execution agents and thus RBAC is more relevant to them.}.
-@end itemize
-CFEngine is intended for autonomous hands-free operation, and thus the
-issue of remote access almost never arises directly.
-In CFEngine it is expressly forbidden for a
-part of CFEngine to receive commands from external parties. In a
-limited sense, CFEngine can be configured to listen for requests for
-classes that label the context for extraordinary, predefined
-policies; these can then be activated by certain users (@code{roles}
-promises), providing a version of the second form of RBAC above. We shall return to this
-below.
-
-@cartouche
-By design it is not possible to send instructions to CFEngine that have
-not been pre-approved by the host administrator and promised as
-policy. Ultimately the local host administrator can veto any proposals
-for change in any configuration system (e.g. by unplugging the network).
-
-In CFEngine this is made a central tenet of the management model.
-@end cartouche
-
-From a security perspective, the elimination of remote command access
-presents a huge simplification to security, without loss of
-functionality. The risk of executing privileged commands on the system is
-exchanged for a right to submit policy changes. Thus the access control
-becomes a matter of @i{who is allowed to approve policy for dissemination} to the system.
-
-@node The chain of privilege in CFEngine, The role of centralized push and pull in RBAC, CFEngine's approach to privilege, Top
-@unnumberedsec The chain of privilege in CFEngine
-
-Even though CFEngine is not in the business of granting privilege for command execution, there
-are security implications to using CFEngine and thus we should
-examine the chain of influence from user to host to understand the implications.
-
-In normal usage, users work as follows:
-
-@itemize
-@item A user edits a CFEngine input file.
-@item The input file determines a promise proposal, or template for policy.
-@item Someone publishes the policy for dissemination to interested parties.
-@item Interested parties (hosts running CFEngine) may choose to download these new propsals
-from trusted sources. These sources are defined in the existing policy which may always
-be vetoed by a local administrator.
-
-@item CFEngine will execute the new policies with the maximum privilege granted to it.
-This privilege can be altered:
-@itemize
-@item By virtue of the privilege with the CFEngine itself runs.
-@item By the privilege accorded to a promise as a matter of its own policy.
-@end itemize
-@end itemize
-When planning for the security of system changes, one should assume that any promise
-written in a CFEngine policy will be enforced with maximum privilege.
-
-@node The role of centralized push and pull in RBAC, No need for any centralization in CFEngine, The chain of privilege in CFEngine, Top
-@unnumberedsec The role of centralized push and pull in RBAC
-
-Centralization is a strategy of collecting resources into a single location. A central resource
-often becomes authoritative for a collection of hosts. Centralization has
-positive and negative aspects
-
-@itemize
-@item As a single point of direction, it simplifies the coordination of multiple agents (like a conductor in an orchestra).
-@item It can be a single point of failure, and a bottleneck for operations. Becauses centralization concentrates effort,
-brute force must be used by a hub when scaling to many hosts around a centralized strategy.
-@end itemize
-
-@sp 1
-@cartouche
-In terms of privilege, the implications of centralization are significantly
-different for @i{push} and @i{pull} based systems (see the figures below).
-@end cartouche
-@sp 1
-
-Let us first consider the general problem, without reference to CFEngine.
-@sp 1
-@center @image{central_push,9cm}
-@center Pushing out requires distributed RBAC control (read/write).
-@sp 1
-A @i{push} is defined to be either
-@itemize
-@item The involuntary transmission of data to hosts
-from a hub, or
-@item The remote execution of commands from the hub to the hosts.
-@end itemize
-We see easily from the figures below that configuration of adequate access control
-requires access control configuration to be implemented on every managed host.
-If the hosts require different levels of access in different zones, for instance,
-this requires a distributed configuration control of the RBAC system itself across
-the affected hosts. There is thus a burden to setting up RBAC.
-
-@cartouche
-One configures a system for a @i{push}
-system just as one configures a system against attack from outside. In configuration
-terms, push is indistinguishable from an attack.
-@end cartouche
-
-Pull-based management is fundamentally different. In a pull model, hosts
-download public information (their policy) from a trusted source.
-@sp 1
-@center @image{central_pull,10cm}
-@center Pulling updates requires only centralized RBAC control for change,
-@center but not for the update itself (read only).
-@sp 1
-There is no need for access control on the hosts anymore, since they
-are only reading information voluntarily. They may simply reject all attempts
-to send them data, in favour of their voluntary decision to download
-updates.
-
-Moving from push to pull-based configuration simplifies the number
-of independent points of configuration from @math{N} to 1, and the location
-of access control information is simplified from @math{N} separate models
-to a single model at the hub. The hub can decide which hosts
-will have access to which policy proposals, so there is no loss
-of privacy: the security model's definition is fully centralized (single point of definition for consistency).
-
-@cartouche
-@itemize
-@item Push-based approaches have centralized execution, but distributed RBAC configuration of the management setting.
-Multiple, inconsistent pushes from different hubs can even lead to distributed inconsistency that cannot be detected from
-any single location.
-
-@item Pull-based approaches have distributed execution, but a single point of security configuration.
-Inconsistent pulls are impossible, as there is a single point of definition.
-@end itemize
-@end cartouche
-At CFEngine, we strongly believe that pull-based systems are superior
-for most purposes, because pull's distributed operation reduces the
-risk of the bottleneck, while the centralized definition of access
-rights reduces the risk of error.
-
-In all further sections, we assume CFEngine's pull-based model.
-
-
-
-@node No need for any centralization in CFEngine, The risk from centralized trusted hosts, The role of centralized push and pull in RBAC, Top
-@unnumberedsec No need for any centralization in CFEngine
-
-Before continuing, it is important to emphasize that CFEngine has no
-technological @i{need} for centralization. The decision to centralize
-management is a policy decision. Every host can, if desired, be configured as an
-independent device, with its own policy, making no contact with any
-external host. CFEngine is thus ideal for embedded systems and
-environments with partial connectivity, such as ships and submarines.
-Nevertheless, centralized management is often chosen for its simple
-coordination of decision making. What is important to realize is that
-centralized decision-making is a convenient fiction for managers --
-no remote party can truly decide the state of a host.
-
-@cartouche
-The owner of a machine always has the privilege to make changes to it.
-Push-based models of management that pretend to control hosts absolutely
-are simply misleading, as they exist by the good grace of end systems.
-@end cartouche
-
-In the remainder of this Special Topics Guide, we shall assume the
-common model of centralized management, because that is the
-context in which RBAC is relevant.
-
-
-
-@node The risk from centralized trusted hosts, The Policy Dispatch Point, No need for any centralization in CFEngine, Top
-@unnumberedsec The risk from centralized trusted hosts
-
-Centralization has implications for risk@footnote{A single point of
-definition could also be a single point of failure. In CFEngine, a
-central policy hub is not a point of failure, because each agent
-caches all the resources it needs to maintain systems according to its
-current model. At worst, the loss of a hub would mean a delay to
-updates.}. Gaining malicious control of a trusted source could have a
-significant impact on all the hosts that subscribe to updates from it.
-
-The risk, in this case, is precisely the same as that for a push-based system that executes
-certain commands. However, the task of defending a single trusted
-host is (at least psychologically) simpler than that of defending all
-the hosts in the network@footnote{User who are adept at automated
-configuration might disagree, as automation makes it easy to harden
-all hosts equally well. Network policies such as firewalls, etc, are
-however, simpler to manage for a single host.}.
-
-The risk of propagating a bad change (i.e. an unfortunate mistake) is also no
-different between push and pull. A bad decision is simply a bad
-decision. The antidote to human errors is to conduct policy reviews, i.e. use
-more pairs of eyes, or `dual-key' solutions.
-
-@cartouche
-Centralize the writing of policy, within a local region to obtain
-straightforward consistency. Don't overcentralize, or you will oversimplfy.
-One size rarely fits all (see the @i{Special Topics Guide on Federation and Organizational Complexity}).
-RBAC then becomes an issue of: who should
-have the right to edit and publish changes to policy?
-@end cartouche
-
-@node The Policy Dispatch Point, The right to edit and publish policy, The risk from centralized trusted hosts, Top
-@unnumberedsec The Policy Dispatch Point
-
-The burden of security is now localized entirely at the Policy Dispatch Point.
-It becomes the responsibility of this `role' (policy dispatcher) to ensure
-that the desired state is in fact the one that is promised. This happens
-in two practical steps:
-
-@itemize
-@item Editing of an SVN repository of working proposals (access to change respository).
-@item Merging of changes into the actual published policy (bowtie process).
-@end itemize
-
-Where the highest levels of paranoia are justified, no host should
-receive automatic updates of policy without explicit human inspection
-and policy review. This is equivalent to allowing no RBAC privileges.
-
-@node The right to edit and publish policy, The bowtie process, The Policy Dispatch Point, Top
-@unnumberedsec The right to edit and publish policy
-
-Let's recap' for a moment. The CFEngine agent runs with maximum
-system privilege (root/Administrator), and makes its decisions based
-on a set of promise proposals that come from some trusted source,
-e.g. the owner of the machine, or some central policy decision point.
-Once a set of proposals has been published, we simply call these `the policy'. The agent on
-each host reads these proposals and picks out those that are relevant
-to the current context (`here and now') for each host. The agent then
-tries to keep these promises, by making any necessary changes to the
-system. For most common usages of CFEngine, the effect is that
-anything that is in the published policy is executed with up to
-maximum privilege.
-
-This means the following:
-
-@table @i
-@item Any user who can edit the actual source policy has control over a host.
-
-The policy should not be writable by any unauthorized user, in any location
-where it will be picked up as part of the policy-appoved process for updating
-policy@footnote{Note that the decision to collect policy updates from somewhere is
-itself a policy decision in CFEngine, so users should always think carefully
-about these decisions.}.
-
-@item Any user who can cause a new version of the policy to be published for immediate use has privileged access.
-
-RBAC now means limiting access to the files that define policy.
-
-@item If policy is automatically checked out of a repository, commit access to the respository can give privileged access.
-
-There should be a process of approval for changes made to policy. This should be a human
-process, because ultimately a human must be responsible for publishing a policy. In this situation, RBAC now
-consists of granting access to make commits to the repository.
-
-@end table
-
-The conclusion of this section is that only a small number of highly trusted individuals
-should be able to alter policy themselves.
-
-
-
-Distributed coordination. RBAC is a poor tool for delegating tasks alone, because if multiple
-individuals with access rights are not coordinated in their promises, the result will merely be
-a conflict.
-
-@node The bowtie process, Granting the right to switch on special pre-defined policies, The right to edit and publish policy, Top
-@unnumberedsec The bowtie process
-
-Promise theory allows us to model the collaborative security
-implications of this (see the figure of the bow-tie structure). A
-simple method of delegating is the following.
-
-@enumerate
-@item Delegate responsibility for different issues to admin teams 1,2,3, etc.
-@item Make each of these teams responsible for version control of their own
-configuration rules.
-@item Make an intermediate agent responsible for collating and vetting the rules, checking for
-irregularities and conflicts. This agent must promise to disallow rules by
-one team that are the responsibility of another team. The agent could be a
-layer of software, but a cheaper and more manageable solution is the make this
-another group of one or more humans.
-
-@item Make the resulting collated configuration version controlled. Publish
-approved promises for all hosts to download from a trusted source.
-
-
-@end enumerate
-
-A review procedure for policy-promises is a good solution if you want
-to delegate responsibility for different parts of a policy to
-different sources. Human judgement as the `arbiter' is irreplaceable,
-but tools can be added to make conflicts easier to detect.
-
-Promise theory underlines that, if a host or computing device accepts
-policy from any source, then it is alone and entirely responsible for
-this decision. The ultimate responsibility for the published version
-policy is the vetting agent. This creates a shallow hierarchy, but
-there is no reason why this formal body could not be comprised of
-representatives from the multiple teams.
-
-The figure below shows how a number of policy authoring teams can work together
-safely and securely to write the policy for a number of hosts, by vetting through
-a checkpoint, in a classic `bow-tie' formation.
-
-@image{delegate,15cm,,Delegation of responsibility requires vetting access,png}
-
-
-@node Granting the right to switch on special pre-defined policies, , The bowtie process, Top
-@unnumberedsec Granting the right to switch on special pre-defined policies
-
-CFEngine offers one technological convenience that is relevant to RBAC.
-In the Clark-Wilson security model, non-privileged users can be
-granted limited privilege to execute predefined commands that are
-locked down to specific actions. The Unix @code{ps} and @code{passwd}
-commands are examples of this, for example.
-
-Most users do not need to touch CFEngine at all, because policy is
-checked very regularly and promises are enforced with 5 minute
-intervals. In other words, for most users, just waiting will fix anny
-problem. In some cases, there are extraordinary promises or tasks that
-one does not want implemented without human oversight. In that
-instance, one places the relevant promises in a context that is not normally
-active. Users can then activate those sleeping promises by defining the
-context class manually.
-@verbatim
-bundle agent mybundle
-{
-files:
-
- extraordindary::
-
- # ... promises ...
-}
-@end verbatim
-Privileged users who have access to the system do not need RBAC to do this
-as they already have all credentials they need, and can achieve the same thing
-by running the agent with a defined class, e.g.
-
-@verbatim
-
-host# cf-agent -D extraordinary
-
-@end verbatim
-However, it is also possible to grant access to these parts of a CFEngine policy that are normally
-switched off by using @code{cf-serverd} to mediate privilege to execute the agent with this class
-active. For example, setting:
-
-@verbatim
-bundle server access_rules()
-{
-roles:
-
- # Allow mark
-
- "extraordinary" authorize => { "mark", "sally" };
-}
-
-@end verbatim
-and running:
-@verbatim
-
-host# cf-runagent -H special_host -D extraordinary
-
-@end verbatim
-would achieve the same effect without granting any rights to change
-the policy.
-
-In this example CFEngine promises to grant permission to users
-@samp{mark} and @samp{sally} to remotely activate classes matching the regular
-expression @samp{extraordinary} when using the @code{cf-runagent} to
-activate CFEngine. In this way one can implement a form of Role Based
-Access Control (RBAC) for unprivileged users, provided users do not
-have privileged access on the host directly. User identity is based on
-trusted CFEngine keys created by the user and exchanged with the
-server.
-
-
-@unnumberedsec RBAC-filtered read-access in CFEngine Nova
-
-CFEngine Nova 2.2.0 introduces Role Based Access Control (RBAC) for all
-reports and promises shown in the Mission Portal. This does not cover
-access control for making policy changes, but displaying reports.
-
-RBAC can be globally switched on or off in the Mission Portal settings.
-
-@unnumberedsec Authentication
-
-User-authentication is carried out when users log in to the Mission
-Portal. This is done by requiring a user name and password, which is
-checked against the following possible sources.
-
-@itemize
-@item Internally defined in the Mission Portal
-@item LDAP
-@item Acitive Directory
-@end itemize
-
-The selection between these options are available in the Mission
-Portal settings.
-
-
-@unnumberedsec Authorization
-
-The information a user is authorized to see is determined from his
-role memberships. A user may be member of an arbitrary number of
-roles, each which may grant and deny access to certain
-information.
-
-The effective permissions of a user is the cumulative set of
-permission granted or denied by his roles, and is used to filter the
-information displayed in the following standard way.
-
-@itemize
-@item Create a union of the granted access for the roles.
-@item Override with the rules that deny access for the roles.
-@item If left unspecified, access is denied.
-@end itemize
-
-
-@unnumberedsec Entities filtered
-
-RBAC is supported on the @emph{host} and @emph{promise bundle} level,
-each applying to different parts of the Mission Portal. Both these
-entities are atomic with respect to RBAC --- either a user can see
-everything they contain, or nothing of it.
-
-Access to a host is required to see any information about it, e.g. all
-its reports (Engineering->Reports), host page, and compliance
-category. If a user is not allowed access to a host, the Mission
-Portal would look the same as if the host was not bootstrapped to that
-hub.
-
-Information about the running policy is also available in the Mission
-Portal, either through the Promise Finder at the Engineering page, or
-by clicking a promise handle from one of the reports. The searchable
-promises in the Promise Finder and information pages about promises
-and bundles are filtered in the same manner as the hosts, but defined
-based on promise bundles instead. The Policy Editor is not covered by
-RBAC --- access to the policy source repository allows the user to see
-the whole policy. Some version control systems can be configured to
-only allow users to access sub-directories of the policy, which may
-help in this case.
-
-Note that the host and promise filtering is independent --- no attempt
-is made to try to infer which promises a role should have access to
-based on the hosts it has access to or vice versa.
-
-
-@unnumberedsec Defining roles
-
-From the above discussion, we see that a role is defined as reporting
-access to a set of hosts and promise bundles from the Mission Portal
-and REST API. This does not give any rights with respect to changing
-the content or execution of the policy. It should not be confused with
-the @code{roles} promise-type that can be used by @code{cf-runagent}
-and @code{cf-serverd}.
-
-In order to scale, both entities are
-defined as a set of @emph{regular expressions} to allow and
-deny.
-
-Access to hosts is defined by regular expressions on @emph{classes},
-not the hostname, ip, or any other name. This is done to ensure
-maximum scalability. Classes can be arbitrarily defined in the
-CFEngine policy language, so this incurs no loss of flexibility, but
-ensures distributed computation.
-
-In contrast to users, a role definition and membership can only be
-obtained from the internal Mission Portal database. This means that
-any roles must be defined through the Mission Portal web interface,
-and can not be obtained from e.g. LDAP at this time. The rationale is
-that querying complex LDAP structures for role membership is too
-inefficient and error-prone. This may change in future releases, if
-requested. Note that the @emph{possible members} of a role can be
-obtained from other sources, as described in @samp{Authentication}
-above. However, assigning possible members to roles must be done
-through the Mission Portal user-interface.
-
-A sample definition of the role @samp{lob_a} is shown below.
-
-@center @image{role-define-loba,12cm,,Defining a role,png}
-
-Only members of the @samp{admin} role has the ability to manipulate
-roles and their memberships.
-
-After defining the role itself, the next step is to make the
-designated users members of the role, using the Mission Portal.
-
-
-
-@unnumberedsec Limitations
-
-@itemize
-
-@item Notes added in the Mission Portal are not filtered: they can be
-seen by all users (including notes added to any host page).
-
-@item The Knowledge Map is only available for members of the
-@samp{admin} role when RBAC is switched on.
-
-@item Running @code{cf-report} from the command-line on the hub will
-bypass all RBAC checks.
-
-@end itemize
-
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_Reporting.texinfo b/docs/guides/SpecialTopic_Reporting.texinfo
deleted file mode 100644
index afa2b05a13..0000000000
--- a/docs/guides/SpecialTopic_Reporting.texinfo
+++ /dev/null
@@ -1,890 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-reporting.info
-@settitle Reporting
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Monitoring and Reporting
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-A significant capability of CFEngine Nova over previous versions of
-CFEngine is the existence of automated system reporting. CFEngine collects
-history, state and change data about computers and ties them together.
-
-The CFEngine strategy is to replace conventional CMDBs with a more
-scalable and flexible approach to information mining over the coming
-years. Commercial versions of CFEngine are designed to bring state of
-the art methods to the problem of information management for IT
-operations.
-
-Users of CFEngine's Community Edition can use in-built logging and
-reporting functions to simulate some aspects of these reports, by applying
-simple principles with work and ingenuity.
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2009 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-
-
-@node Top, What are monitoring and reporting?, (dir), (dir)
-@top Reporting
-@menu
-* What are monitoring and reporting?::
-* Should monitoring and configuration be separate?::
-* Reporting in CFEngine::
-* Standard reports in CFEngine::
-* CFEngine output levels::
-* Creating custom reports -- all versions::
-* Including data in reports::
-* Creating custom logs::
-* Redirecting output to logs::
-* Change auditing - the all seeing eye::
-* Cheaper options - tripwires::
-* Commerical edition measurements promises::
-* Hub reporting::
-* Mission Portal access to the hub::
-* Command line access to the hub::
-* Example command hub searches ::
-@end menu
-
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@node What are monitoring and reporting?, Should monitoring and configuration be separate?, Top, Top
-@unnumberedsec What are monitoring and reporting?
-
-@sp 1
-Monitoring is the sampling of system variables at regular intervals in
-order to present an overview of actual changes taking place over time.
-Monitoring data are often presented as extensive views of moving-line
-time series. Monitoring has the ability to detect anomalous behaviour
-by comparing past and present.
-
-The term @i{reporting} is usually taken to mean the creation of short
-summaries of specific system properties suitable for
-management. System reports describe both promises about the system,
-such as compliance, discovered changes and faults.
-
-The challenge of both these activities is to compare @i{intended} or
-@i{promised}, behaviour with the @i{actual} observed behaviour of the
-system.
-
-@node Should monitoring and configuration be separate?, Reporting in CFEngine, What are monitoring and reporting?, Top
-@unnumberedsec Should monitoring and configuration be separate?
-
-@sp 1
-The traditional view of IT operations is that configuration,
-monitoring and reporting are three different things that should not be
-joined. Traditionally, all three have been independent centralized
-processes. This view has emerged historically, but it has a major
-problem. Humans are needed to glue these parts back together.
-
-Monitoring as an independent activity is inherently non-scalable.
-When numbers of hosts grow beyond a few thousands, centralized
-monitoring schemes fail to manage the information. Tying configuration
-(and therefore repair) to monitoring at the host level is essential
-for the effective management of large and distributed data facilities.
-CFEngine foresaw this need in 1998, with its Computer Immunology
-initiative, and continues to develop this strategy.
-
-CFEngine's approach is to focus on scalability. The commercial editions
-of CFEngine provide what meaningful information they can in a manner that
-can be scaled to tens of thousands of machines.
-
-
-@node Reporting in CFEngine, Standard reports in CFEngine, Should monitoring and configuration be separate?, Top
-@unnumberedsec Reporting in CFEngine
-@sp 1
-
-@cartouche
-If you have regular reporting needs, we recommend using our commercially supported
-version of CFEngine (CFEngine Nova or above), as you will save considerable time
-and resources in programming, and you will have access to the latest developments
-through the software subscription.
-@end cartouche
-
-No promises made in CFEngine imply automatic aggregation of data to a central
-location. In commercial CFEngine versions, e.g. CFEngine Nova, an optimized
-aggregation of standardized reports is provided, but the ultimate decision to
-aggregate must be yours.
-
-Monitoring and reporting capabilities in CFEngine depend on the
-software version include:
-
-@itemize
-@item @b{Community Edition:} Basic output to file or logs may be customized on a per-promise basis. Users can design their own log and report formats, but data processing and extraction from CFEngine's embedded databases must be scripted by the user.
-
-@item @b{Nova:} In addition to community features, Nova/Enterprise provides automated extraction of
-data from CFEngine's self-learning agents, and the generation of a
-standard set of reports in text, HTML or XML formats. Nova summarizes
-distributed data and provides simple compression and aggregation of
-these summaries. Finally summaries are tied into a knowledge map or
-semantic index for browsing by IT operations. Command line tools in
-@code{cf-report} are also available for Nova users to browse network-wide data.
-
-@ignore
-@item @b{Constellation:} In addition to Nova features, Constellation performs
-additional data extraction from the collected reports. It analyses correlations
-and provides reverse look up of system attributes based on searchable expressions.
-At this level, CFEngine exceeds other industry CMDB solutions in both reporting
-and configuration.
-@end ignore
-
-@end itemize
-
-@node Standard reports in CFEngine, CFEngine output levels, Reporting in CFEngine, Top
-@unnumberedsec Standard reports in CFEngine
-
-The following list of reports are only available in full in commercial editions of
-CFEngine. Some sample reports are provided in the Community Edition.
-@table @emph
-@item Available patches report
-Patches already installed on system if available.
-@item Classes report
-User defined classes observed on the system -- inventory data.
-@item Compliance report
-Total summary of host compliance, all promises aggregated over time.
-@item File_changes report
-Latest observed changes to system files with time discovered.
-@item File_diffs report
-Latest observed differences to system files, in a simple diff format.
-@item Hashes report
-File hash values measured (change detection).
-@item Installed patches report
-Patches not yet installed, but published by vendor if available.
-@item Installed software report
-Software already installed on system if available.
-@item Lastseen report
-Time and frequency of communications with peers, host reliability.
-@item Micro-audit report
-Generated by CFEngine self-auditing. This report is not aggregated.
-@item Monitor summary report
-Pseudo-real-time measurement of time series data.
-@item Performance report
-Time cost of verifying system promises.
-@item Promise report
-Per-promise average compliance report over time.
-@item Promises not kept report
-Promises that were recently un-kept.
-@item Promises repaired report
-Promises that were recently kept by repairing system state.
-@item Setuid report
-Known setuid programs found on system.
-@item Variables report
-Current variable values expanded on different hosts.
-@end table
-
-@node CFEngine output levels, Creating custom reports -- all versions, Standard reports in CFEngine, Top
-@unnumberedsec CFEngine output levels
-@sp 1
-
-CFEngine's default behaviour is to report to the console (known as
-standard output). It's default behaviour is to report nothing except
-errors that are judged to be of a critical nature.
-
-By using CFEngine with the inform flag:
-@verbatim
-# cf-agent -I
-# cf-agent --inform
-@end verbatim
-@noindent you can alter the default to report on action items (actual changes)
-and warnings.
-
-By using CFEngine with the verbose flag:
-@verbatim
-# cf-agent -v
-# cf-agent --verbose
-@end verbatim
-@noindent you can alter the default to report all of its thought-processes.
-You should not interpret a message that only appears in CFEngine's
-verbose mode as an actual error, only as information that might be relevant
-to decisions being made by the agent.
-
-@node Creating custom reports -- all versions, Including data in reports, CFEngine output levels, Top
-@unnumberedsec Creating custom reports -- all versions
-@sp 1
-
-CFEngine allows you to use @code{reports} promises to
-make reports of your own. A simple example of this is shown below.
-
-@verbatim
-body common control
-{
-bundlesequence => { "test" };
-}
-
-#
-
-bundle agent test
-{
-reports:
-
- cfengine_3::
-
- "$(sys.date),This is a report"
- report_to_file => "/tmp/test_log";
-}
-
-@end verbatim
-
-
-@noindent We can apply this idea to make more useful custom
-reports. In this example, the agent tests for certain software
-package and creates a simple HTML file of existing software.
-
-@verbatim
-body common control
-{
-bundlesequence => { "test" };
-}
-
-#
-
-bundle agent test
-{
-vars:
-
- "software" slist => { "gpg", "zip", "rsync" };
-
-classes:
-
- "no_report" expression => fileexists("/tmp/report.html");
- "have_$(software)" expression => fileexists("/usr/bin/$(software)");
-
-reports:
-
- no_report::
-
- "
-
- Name of this host is: $(sys.host)
- Type of this host is: $(sys.os)
- "
-
- report_to_file => "/tmp/report.html";
-
- #
-
- "
- Host has software $(software)
- "
-
- ifvarclass => "have_$(software)",
- report_to_file => "/tmp/report.html";
-
- #
-
- "
-
- "
- report_to_file => "/tmp/report.html";
-
-}
-@end verbatim
-
-@noindent The outcome of this promise is a file called @file{/tmp/report.html}
-containing output like this:
-
-@verbatim
-
- Name of this host is: atlas
- Type of this host is: linux
-
- Host has software gpg
-
- Host has software zip
-
- Host has software rsync
-
-
-@end verbatim
-
-The mechanism shown above, can clearly be used to create a wide
-variety of report formats, but it requires a lot of coding and
-maintenance by the user.
-
-@cartouche
-CFEngine Nova simplifies this kind of report generation by enabling
-and updating many out-of-the-box reports directly from the
-@code{cf-report} agent.
-@end cartouche
-
-@node Including data in reports, Creating custom logs, Creating custom reports -- all versions, Top
-@unnumberedsec Including data in reports
-
-CFEngine generates information internally that you might want to use
-in reports. For example, the agent @code{cf-agent}
-interfaces with the local light-weight monitoring
-agent @code{cf-monitord} so that system state can be reported simply:
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "report" };
-}
-
-###########################################################
-
-bundle agent report
-
-{
-reports:
-
- linux::
-
- "/etc/passwd except $(const.n)"
-
- showstate => { "otherprocs", "rootprocs" };
-
-}
-
-@end verbatim
-
-@noindent A corollary to this is that you can get CFEngine to report
-system anomalies.
-
-@verbatim
-reports:
-
- rootprocs_high_dev2::
-
- "RootProc anomaly high 2 dev on $(mon.host) at approx $(mon.env_time)
- measured value $(mon.value_rootprocs)
- average $(mon.average_rootprocs) pm $(mon.stddev_rootprocs)"
-
- showstate => { "rootprocs" };
-
- entropy_www_in_high&anomaly_hosts.www_in_high_anomaly::
-
- "High entropy incoming www anomaly on $(mon.host) at $(mon.env_time)
- measured value $(mon.value_www_in)
- average $(mon.average_www_in) pm $(mon.stddev_www_in)"
-
- showstate => { "incoming.www" };
-
-@end verbatim
-
-@noindent This produces standard output of the form:
-
-@cartouche
-@verbatim
-R: State of otherprocs peaked at Tue Dec 1 12:12:21 2009
-
-R: The peak measured state was q = 98:
-R: Frequency: [kjournald] |** (2/98)
-R: Frequency: [pdflush] |** (2/98)
-R: Frequency: /var/cfengine/bin/cf-execd|** (2/98)
-R: Frequency: COMMAND |* (1/98)
-R: Frequency: init [5] |* (1/98)
-R: Frequency: [kthreadd] |* (1/98)
-R: Frequency: [migration/0] |* (1/98)
-R: Frequency: [ksoftirqd/0] |* (1/98)
-R: Frequency: [events/0] |* (1/98)
-R: Frequency: [khelper] |* (1/98)
-R: Frequency: [kintegrityd/0] |* (1/98)
-@end verbatim
-@end cartouche
-
-
-
-@noindent Finally, you can quote lines from files in your data
-for convenience.
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "report" };
-}
-
-###########################################################
-
-bundle agent report
-
-{
-reports:
-
- linux::
-
- "/etc/passwd except $(const.n)"
-
- printfile => pr("/etc/passwd","5");
-
-}
-
-######################################################################
-
-body printfile pr(file,lines)
-
-{
-file_to_print => "$(file)";
-number_of_lines => "$(lines)";
-}
-
-@end verbatim
-
-@noindent This produces output of the form
-
-@cartouche
-@verbatim
-R: /etc/passwd except
-R: at:x:25:25:Batch jobs daemon:/var/spool/atjobs:/bin/bash
-R: avahi:x:103:105:User for Avahi:/var/run/avahi-daemon:/bin/false
-R: beagleindex:x:104:106:User for Beagle indexing:/var/cache/beagle:/bin/bash
-R: bin:x:1:1:bin:/bin:/bin/bash
-R: daemon:x:2:2:Daemon:/sbin:/bin/bash
-@end verbatim
-@end cartouche
-
-@node Creating custom logs, Redirecting output to logs, Including data in reports, Top
-@unnumberedsec Creating custom logs
-@sp 1
-
-Logs can be attached to any promise. In this example, an executed shell command
-logs a message to the standard output. CFEngine recognizes the @code{stdout}
-filename for Standard Output, in the Unix/C standard manner.
-
-@verbatim
-bundle agent test
-{
-commands:
-
- "/tmp/myjob",
-
- action => logme("executor");
-
-}
-
-############################################
-
-body action logme(x)
-{
-log_repaired => "stdout";
-logstring => " -> Started the $(x) (success)";
-}
-@end verbatim
-
-@noindent In this next example, a file creation promise
-logs different outcomes (success or failure) to different
-log files.
-
-
-@verbatim
-body common control
-{
-bundlesequence => { "test" };
-}
-
-bundle agent test
-{
-vars:
-
- "software" slist => { "/root/xyz", "/tmp/xyz" };
-
-files:
-
- "$(software)"
-
- create => "true",
- action => logme("$(software)");
-
-}
-
-#
-
-body action logme(x)
-{
-log_kept => "/tmp/private_keptlog.log";
-log_failed => "/tmp/private_faillog.log";
-log_repaired => "/tmp/private_replog.log";
-log_string => "$(sys.date) $(x) promise status";
-}
-
-@end verbatim
-
-
-@noindent This generates three different logs with outputs in of the form:
-
-@cartouche
-@verbatim
-atlas$ more /tmp/private_keptlog.log
-Sun Dec 6 11:58:16 2009 /tmp/xyz promise status
-Sun Dec 6 11:58:43 2009 /tmp/xyz promise status
-@end verbatim
-@end cartouche
-
-
-@node Redirecting output to logs, Change auditing - the all seeing eye, Creating custom logs, Top
-@unnumberedsec Redirecting output to logs
-@sp 1
-
-CFEngine interfaces with the system logging tools in different ways.
-Syslog is the default log for Unix-like systems, while the event
-logger is the default on Windows. You may choose to copy a fixed
-level of CFEngine's standard screen messaging to the system logger
-on a per-promise basis.
-
-@verbatim
-body common control
-{
-bundlesequence => { "one" };
-}
-
-
-bundle agent one
-{
-files:
-
- "/tmp/xyz"
-
- create => "true",
- action => log;
-}
-
-body action log
-{
-log_level => "inform";
-}
-@end verbatim
-
-
-
-
-@node Change auditing - the all seeing eye, Cheaper options - tripwires, Redirecting output to logs, Top
-@unnumberedsec Change auditing - the all seeing eye
-
-@sp 1
-
-Total auditing of a system is a surprisingly difficult thing to do,
-and it is extremely resource intensive. The followers of an audit
-trail are often paranoid by nature and are seldom satisfied with the
-level of detail they find. However, the times we really need an audit
-are rare, but the cost is ever present. The price of certainty is high.
-
-@cartouche
-Spend a moment considering this: if you want to describe every change
-of state that happens on a computer, then you need to remember old
-state and compare it to new state. Then you have to record the
-differences. So you need more than the entire size of your computer's
-normal resources to do this. Your storage efficiency will always be
-less than 50% and your processing efficiency will be less than 50% on
-every audited item. Is this worth the effort? Perhaps your resources
-would be better spent keeping targeted backups and simply rebuilding
-contaminated systems.
-@end cartouche
-
-Switch on auditing like this:
-
-@verbatim
-body agent control
-{
-auditing => "true";
-}
-
-@end verbatim
-
-If you decide to go for full auditing, CFEngine will not collect and
-centralize the reports as they will be too large for this to be a
-scalable operation. Still, you can view them in a web browser on the
-local host, or copy them manually to a suitable location.
-
-@node Cheaper options - tripwires, Commerical edition measurements promises, Change auditing - the all seeing eye, Top
-@unnumberedsec Cheaper options - tripwires
-
-Doing a change detection scan is a convergent process, but it can
-still detect changes and present the data in a compressed format
-that is often more convenient than auditing. The result is less precise,
-but there is a trade-off between precision and cost.
-
-To make a change tripwire, you use a @file{files} promise, something like this:
-
-@verbatim
-body common control
-{
-bundlesequence => { "testbundle" };
-}
-#
-
-bundle agent testbundle
-
-{
-files:
-
- "/home/mark/tmp" -> "me"
- changes => scan_files,
- depth_search => recurse("inf");
-}
-
-# library code ...
-
-body changes scan_files
-{
-report_changes => "all";
-update_hashes => "true";
-}
-
-body depth_search recurse(d)
-{
-depth => "$(d)";
-}
-@end verbatim
-
-In CFEngine Nova, reports of the following form are generated when these promises
-are kept by the agent:
-
-@cartouche
-@verbatim
-Change detected File change
-Sat Dec 5 18:27:44 2009 group for /tmp/testfile changed 100 -> 0
-Sat Dec 5 18:27:44 2009 /tmp/testfile
-Sat Dec 5 18:20:45 2009 /tmp/testfile
-@end verbatim
-@end cartouche
-
-@noindent These reports are generated automatically in CFEngine Nova,
-and are integrated into the web browsable knowledge map. Community
-edition users have to extract the data and create these themselves.
-
-
-@node Commerical edition measurements promises, Hub reporting, Cheaper options - tripwires, Top
-@unnumberedsec Commercial edition measurements promises
-@sp 1
-
-In commercial versions of CFEngine, you can extract data from the
-system in more sophisticated ways from files or pipes, using Perl
-Compatible Regular Expressions to match text. The @code{cf-monitord}
-agent is responsible for processing measurement promises.
-
-In this example, we count lines matching a pattern in a file.
-You might want to scan a log for instances of a particular
-message and trace this number over time.
-
-@verbatim
-bundle monitor watch
-{
-measurements:
-
- "/tmp/file"
-
- handle => "line_counter",
- stream_type => "file",
- data_type => "counter",
- match_value => scanlines("MYLINE.*"),
- history_type => "log";
-
-}
-
-#
-
-body match_value scanlines(x)
-{
-select_line_matching => "^$(x)$";
-}
-
-@end verbatim
-
-See the CFEngine Nova documentation for more possibilities of measurement
-promises.
-
-
-
-@node Hub reporting, Mission Portal access to the hub, Commerical edition measurements promises, Top
-@unnumberedsec Hub Reporting
-
-In the commercial editions of CFEngine much more extensive and searchable
-reporting is available.
-
-
-
-@node Mission Portal access to the hub, Command line access to the hub, Hub reporting, Top
-@unnumberedsec Mission Portal access to the hub
-
-The preferred approach to querying information on a hub
-is to use the web interface in the Mission Portal.
-This gives the greatest flexibility in both search
-and presentation of data. Given the extensiveness of
-the Mission Portal user interface, the details are
-covered in a separate document.
-
-
-@node Command line access to the hub, Example command hub searches , Mission Portal access to the hub, Top
-@unnumberedsec Command line access to the hub
-
-Users with login access to the hub can also use the command line tool
-@code{cf-report} to extract a limited view of the data.
-Currently supported reports include:
-
-@table @code
-@item compliance
-The percentage total compliance log for all hosts.
-@item dead-clients
-Shows a list of client hosts that have not made incoming requests within the standard
-time horizon (default 15 minutes).
-@item file_changes
-The change log
-@item file_diffs
-The change details for text files.
-@item last-seen
-Show the last time hosts connnected to the hub
-@item promises
-Compliance by promise, labelled by promise-handle.
-@item setuid
-The list of setuid/setgid root files detected on the system.
-@item software
-The installed software base of the system.
-@item summary
-A summary of how many hosts are compliant within a given set of search parameters.
-@item vars
-The values of variables set on hosts.
-@end table
-
-@noindent Some special command line options are supported in the commercial versions.
-
-@table @samp
-@item --query-hub
-or @samp{-q} Query hub database interactively. This option is the entry point
-for querying the hub data with @code{cf-report}, and must always be specified.
-
-@item --show name
-Select the name of the report from the above list.
-
-@item --promise-handle
-or @samp{-p regex}. For promise compliance report, this defines a
-regular expression to search for promises of a specific name. Specify a promise-handle to look up
-
-@item --hostkey
-or @samp{-k hashkey}.
-Specify a particular host to query for data, using the unique host-key.
-
-@item --class-regex
-or @samp{-c regex} - Specify a class regular expression to search for
-
-@item --filter
-or @samp{-F regex} - Specify a name regular expression for filtering results
-@end table
-
-@node Example command hub searches , , Command line access to the hub, Top
-@unnumberedsec Example command hub searches
-
-If only a host-key is specified, CFEngine returns with the last known location and identity
-of the host. (Note that, in the following examples, the SHA keys are reduced for readability).
-@verbatim
-
-host# cf-report -q --hostkey SHA=bd6dfcc2...
- -> Hostname: hub.test.cfengine.com
- -> Recent IP Addresses: 10.0.0.29
-
-@end verbatim
-To dump all values from all hosts:
-@verbatim
-
-cf-report -q --show promises
-cf-report --query-hub --show promises
-
-@end verbatim
-@noindent You can select a single host for a particular report:
-@verbatim
-cf-report -q --hostkey SHA=c40fb732c6e5... --show vars
-@end verbatim
-@noindent Or you can select a CFEngine class of hosts that will be selected to report
-@verbatim
-cf-report -q --show summary --class-regex linux
-cf-report -q --show summary --class-regex SuSE
-cf-report -q --show summary --class-regex NewYork
-@end verbatim
-@noindent Here are some examples using filters to 'grep' out certain items:
-@verbatim
-
-cf-report -q --hostkey SHA=c40fb732c6... --show vars --filter date
-
-cf-report -q --filter "mail.*" --hostkey SHA=bd6dfccb1a... --show setuid
-
-cf-report -q --show promises -p knowledge_files_db_stamp
-
-@end verbatim
-
-
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_Rollback.texinfo b/docs/guides/SpecialTopic_Rollback.texinfo
deleted file mode 100644
index e05028a9d3..0000000000
--- a/docs/guides/SpecialTopic_Rollback.texinfo
+++ /dev/null
@@ -1,467 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-rollback.info
-@settitle Rollout and Rollback
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Rollout and Rollback
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-Rollback is supposed to be like the `Undo' button in a text editor,
-and there is a tendency to equate rollback with the ability to `undo'
-any kind of system change. However, `all changes are not made equal'.
-
-In system administration, in particular, the idea of rollback has been
-borrowed loosely for talking about system change management, which is
-a problem of much higher risk and complexity. This handbook explains
-the limitations of transaction thinking for system administration, and
-presents an alternative in the CFEngine framework.
-
-The expectations for rollback are considerable: a magic bullet for undoing
-mistakes and the unforeseen failures of incomplete planning. The
-reality is different however. Rollback is not always
-possible and can even lead to worse problems.
-
-CFEngine takes an alternative approach, using `convergence' as its
-approach to ensure not just one-time patching, but continuous,
-repeatable desired state migration.
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2009 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@node top, What is rollback?, (dir), (dir)
-@top Rollback
-@menu
-* What is rollback?::
-* Like revision control?::
-* Limitations of rollback in system administration::
-* ITIL release management::
-* Why is relying on rollback not a good strategy?::
-* Don't shoot the messenger::
-* An alternative way to plan changes::
-* How does CFEngine convergence help?::
-* `Resetting' -- a case where rollback works?::
-* Appendix - Did you know?::
-@end menu
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-
-
-@node What is rollback?, Like revision control?, top, top
-@unnumberedsec What is rollback?
-
-@sp 1
-
-Rollback is a term that originates from the world of @i{Transaction
-Processing}, e.g in databases. It arises in the context of trying to
-guarantee data integrity during @i{intended changes to data} (e.g. during copy or
-write operations to a database or a disk).
-
-Accurate change of data can fail for a variety of unpredictable
-environmental reasons, so the idea is to preserve the integrity of
-data during change by arranging them into predictable chunks called
-@i{transactions}. If an error occurs during the copying of a single
-data transaction, e.g. because it was interrupted or there was a
-failure, then the change should be such that we are able to scrap
-the affected transaction and try it again until the intention
-succeeds.
-
-The idea is a simple variation of error-correction methods in signal
-transmission, where detection of an error mandates dropping a packet
-and retransmitting it. Ultimately this goes back to Shannon
-communication theory.
-
-@node Like revision control?, Limitations of rollback in system administration, What is rollback?, top
-@unnumberedsec Like revision control?
-
-The idea has been used in other contexts too. Revision control
-systems (CVS, Subversion, etc) use the same idea to keep a record of
-what @i{intended changes} have been made in source code or other
-documents. In theory, if you intentionally commit a change that you
-don't like, you can `back out' by reversing a `commit' operation and
-going back to a previous version before it becomes irreversible.
-
-This idea works well if you only ever want to undo the last atomic
-transaction in a sequence of deliberate changes, however there are
-limitations. If two or more persons make changes to data in parallel,
-you might not know what the last transaction was, or even that another
-transaction has taken place when trying to undo a change.
-
-Similarly, you might want to undo changes that you made a few
-transactions ago, in which case you would need to undo all the changes
-from that point to the current point. At that point, it is more
-efficient to make a `new' revision that takes away the offending text,
-rather than undoing everything that happened since.
-
-Revsion control can also fail. Your last change might have already been
-changed with or without your knowledge and simply reversing what you
-changed will not be possible.
-For example, consider the file:
-
-@smallexample
-one
-two
-three
-@end smallexample
-
-@noindent User 1 commits new lines in a single transaction:
-
-@smallexample
-one
-two
-three
-seven
-eight
-@end smallexample
-
-@noindent Then another user transforms all the lines in a single transaction:
-
-@smallexample
-#one
-#two
-#three
-#seven
-#eight
-@end smallexample
-
-@noindent User 1 now realizes that the lines were incorrect and tries
-to undo his transaction, deleting two lines `seven' and `eight' at the
-end of the file, but now there are no such lines to be found where
-they were expected, and the rollback fails without a graceful exit. Now
-the system is in an unknown state, not merely an imperfect one.
-
-The resolution to this problem is not to try reversing changes, but to
-reanalyze the file contents and move forward. As long as changes are
-small and simple, re-analysis will be a simple matter and moving
-forward will be the simplest option with the least upheaval to the
-system.
-
-@sp 1
-@cartouche
-You cannot change the past, only the future.
-@end cartouche
-
-@node Limitations of rollback in system administration, ITIL release management, Like revision control?, top
-@unnumberedsec Limitations of rollback in system administration
-
-The term roll-back has been adopted (actually misappropriated)
-in the context of IT management to mean `undo of changes during system
-upgrades'. However, system upgrade is usually a very complex sequence
-of @i{intended} transactions and @i{unintended} side effects, some of
-which are a result of planned intentions and some of which are caused by
-third parties. It is quite difficult to isolate and serialize system
-changes in live operating environments, because planned changes
-generally get interleaved with unplanned ones.
-
-The concept of rollback therefore has practical limitations: the main
-ones being that it requires @i{isolation} and @i{serialization} of all
-change processing. If people or machines are working at the same time
-on shared data, or if there is distributed work going on, this is
-likely to break the @i{single point of change} condition required to
-make transactions integral -- i.e. to make rollback possbile.
-
-@sp 1
-@cartouche
-Unix's single user mode was defined for the purpose of assisting in
-transactional changes during maintenance, by locking non-root users
-out of the system, but in todays environments it is not practical to
-shut down a system for making changes.
-@end cartouche
-@sp 1
-
-@node ITIL release management, Why is relying on rollback not a good strategy?, Limitations of rollback in system administration, top
-@unnumberedsec ITIL release management
-
-The idea of rollback is seductive and has also been introduced into
-human practices in the hope of making processes impervious to error.
-The IT Infrastructure Library (ITIL) is a self-proclaimed set of best
-practices for IT management. It borrows some ideas about transaction
-integrity for human management processes.
-
-Once again, the idea is to break up changes into chunks (ITIL calls
-these chunks `releases') and verify that each release is error-free
-before fully committing to it. If something goes wrong, you `roll
-back' by throwing away the last chunk and try again. In order to
-succeed, each chunk must be a separate entity and its integrity must
-be verified before the change is accepted so that there are no
-unforeseen consequences of a potential error.
-
-@node Why is relying on rollback not a good strategy?, Don't shoot the messenger, ITIL release management, top
-@unnumberedsec Why is relying on rollback not a good strategy?
-
-Gaining full control of a system requires complete mastery of every
-aspect of the environment. This is unrealistic when multiple agents
-are involved.
-
-@node Don't shoot the messenger, An alternative way to plan changes, Why is relying on rollback not a good strategy?, top
-@unnumberedsec Don't shoot the messenger
-
-When you make a mistake, either with a policy decision or its
-implementation, and a user comes pointing a finger because the system
-is broken, someone is going to ask: what was the last change that was
-made that `caused' this problem? Now roll back to that version to fix
-the problem (usually in an urgent voice)!
-
-Stop right there and think again. True, it is possible that a single
-change was the origin of a chain of events resulting in the problems
-you have, but it is not true that going back to the previous version
-of that incident will repair the problem. If you open the door to your
-submarine while deep under water, closing it alone will not help get
-rid of the unwanted water.
-
-Whenever you make a mistake, you should expect to undertake a clean-up
-operation that deals with all of the consequences of the
-error. Tracking changes can help you to map out what needs to be
-repaired, but you cannot turn back time.
-
-One approach is a destructive one: stop the system and go back to a
-checkpoint date on the filesystem. If you do that, you will lose all
-your data and changes since the checkpoint, and it might still be too
-late for your mission critical operation.
-
-A less destructive way is to contain the problem by preventing more
-damage from occurring, then create a new policy to automatically clean up.
-That way, if the same problem should happen again, you will have
-already planned your exit strategy.
-
-@node An alternative way to plan changes, How does CFEngine convergence help?, Don't shoot the messenger, top
-@unnumberedsec An alternative way to plan changes
-
-
-@noindent Reliable rollback is an intractable problem in most modern
-datacentres, but many systems claim that they can do it without
-addressing the consequences of loss or downtime. In short, relying on
-the ability to roll back makes for a fragile strategy.
-
-A better approach to error correction is planned avoidance of mistakes, and
-assuming that unplanned changes will occur. You know
-that there is a risk of error, so minimize the error by planning a
-multitude of tiny changes rather than fewer big releases.
-
-@sp 1
-@itemize
-@item Make small incremental changes.
-@item Test in a test environment.
-@item Test in a runtime environment on the smallest possible set of machines.
-@item Make no other planned changes until you are sure the change resulted in the
-behaviour you expected.
-@item Expand the scope of the change gradually, as your confidence grows, until
-all machines are covered.
-@end itemize
-@sp 1
-Notice that a human must be responsible for each expansion of scope.
-Always plan based on the desired state -- i.e. not where you think you
-are starting from, but where you want to get to. That is the only
-fixed point on which to base a policy.
-
-CFEngine can deal with the error correction against unplanned changes,
-but only humans can manage @i{intentions}.
-
-@sp 2
-@cartouche
-WHY CAN WE DO THIS NOW? Previously the technology for making reliable
-changes was poor and was based on transaction thinking, and it was
-important to minimize the disruptive operations in a few
-`roll-outs'. This is no longer true with CFEngine. It is both
-inexpensive and even @i{recommended} to make a large number of small
-impact changes to respond to your needs. In this way you should
-minimize the risk through small increments and testing. Moreover,
-because CFEngine does @i{not} assume or rely on transactional
-integrity, it is less prone to failures during change implementation.
-@end cartouche
-@sp 2
-
-@node How does CFEngine convergence help?, `Resetting' -- a case where rollback works?, An alternative way to plan changes, top
-@unnumberedsec How does CFEngine @i{convergence} help?
-
-CFEngine's change management model is not based on transactions, it is
-based on a concept of convergence to a known end-state. In
-transaction management, you need to know where you started from and
-the complete history of the system in order to know where you will end
-up. No one has this information reliably. The alternative is
-CFEngine's convergence principle. Convergence, works like a sink,
-drawing the system down towards the desired state, no matter where you
-start from.
-
-@center @image{convergence,12cm,,Rollback,png}
-
-Each promise in CFEngine is engineered in this way. We promise end
-results, not changes. CFEngine calculates the
-necessary steps and implementing them (many times if necessary) to avoid
-failure.
-
-If you make small changes to policy (small modifications to promises),
-then you will not make big mistakes that need to be undone. The main
-reason for failure is that our initial assumptions about the environment
-were incorrect.
-
-@sp 1
-@itemize
-
-@item Plan for changes in a real environment. Base your projections on
-what happens in the live system, not in the lab.
-
-@item Test on the smallest possible set and expand from there.
-
-@item Watch over changes and their later impact on the network as
-they are made by CFEngine to see if any of your initial assumptions were wrong.
-
-@item If there was a mistake, change your policy again to correct the mistake (moving forwards).
-
-@end itemize
-@sp 1
-
-Using CFEngine, you should always be thinking of moving forwards, even
-if you circle back to an earlier policy. Do not try to go back and
-undo changes, think of going forwards and minimizing the repercussions
-of errors. If mistakes are made, go forward again with promises that clean
-up and repair.
-
-@node `Resetting' -- a case where rollback works?, Appendix - Did you know?, How does CFEngine convergence help?, top
-@unnumberedsec `Resetting' -- a case where rollback works?
-
-Some environments consider `rollback' to mean, stopping destroying and
-rebuilding systems from a frozen image. This is something different
-from an undo operation on a running system. It applies the idea of
-transactions only to the design of each `roll out' release and
-turns a blind eye to what happens once a machine is taken into service.
-
-Resetting a machine by destroying and re-building is indeed a transaction
-that will roll us back to the initial state, but it is a misleading
-form of integrity because you also undo all of the intended changes
-that happen as part of the system's function: run-time state.
-
-If you are willing to sacrifice run-time data then you can @i{reset}
-a system, i.e. sacrifice or destroy it and build a new one with the
-same original specification. However, you must be clear about what
-is being lost:
-
-@sp 1
-@itemize
-@item The system must be taken out of service.
-
-@item Any run-time data must either be lost, or should be considered
-`possibly contaminated' by the change that was introduced. Either way,
-you need to make a decision about how to recover them.
-@end itemize
-@sp 1
-
-@cartouche
-`Reset' is what nature does when it makes mistakes: it lets unsuccessful
-instances or copies die and falls back to a copy.
-@end cartouche
-@sp 1
-
-CFEngine helps here too. If you really want this kind of radical reset
-and you don't mind losing runtime data, CFEngine will help you to
-reconstruct the system in a predictable policy-compliant way.
-
-@node Appendix - Did you know?, , `Resetting' -- a case where rollback works?, top
-@unnumberedsec Appendix - Did you know?
-
-Here are some features that can help you to recover with CFEngine's
-non-destructive error correction approach:
-
-@itemize
-@item In @code{files} promises, you can use the @code{changes} attribute
-to detect and log unexpected change in our system. This can help you
-to correlate changes in policy with unexpected consequences so that you
-can plan your clean-up.
-
-@item When CFEngine changes or renames a file it keeps a backup of the file
-before the change, of the form @file{filename.@var{suffix}}, where the
-@var{suffix} is by default: @file{.cfsaved}, @file{.cfdisabled}, @file{.cfedited},
-@file{.cfmoved}.
-
-@item Normally only one level of backup is kept, i.e. the next change
-will overwrite this file. If you specify @code{copy_backup =>
-"timestamp";} or @code{edit_backup => "timestamp";} then CFEngine will
-keep multiple versions with time-stamps to keep a complete history.
-
-@item If you specify a @code{repository} directory in a @code{files}
-promise, CFEngine will move all such backup files to a single
-location, rather than leaving them in the same directory, next
-to the original files.
-
-@end itemize
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
diff --git a/docs/guides/SpecialTopic_Scalability.texinfo b/docs/guides/SpecialTopic_Scalability.texinfo
deleted file mode 100644
index 6c90ad585e..0000000000
--- a/docs/guides/SpecialTopic_Scalability.texinfo
+++ /dev/null
@@ -1,1415 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-scale.info
-@settitle Scale and Scalability
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Scale and Scalability (draft)
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-How large a system can CFEngine manage before special measures are
-required to make it work? CFEngine is a flexible system with no fixed
-architecture, that can be adapted to service any number of machines,
-by adjusting the architecture. This document describes the most common
-architectures in use today.
-
-Several risk factors are associated with managing huge systems,
-including loss of control under failures of the human-computer
-system. Strategies for avoiding these failure modes are discussed.
-
-Scaling gracefully is not just about handling volumes of machines,
-but also about comprehensibility and manageability
-to human engineers.
-@end quotation
-@end cartouche
-
-@vskip 2cm
-This is an incomplete draft document. Last updated October 2011.
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2010,2011 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@node Top, Principles of scalability, (dir), (dir)
-@top Scalability
-
-
-
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-
-@node What is scheduling?, How can CFEngine help?, Top, Top
-@unnumberedsec What is scheduling?
-
-@sp 1
-
-Scheduling refers to the execution of non-interactive processes or
-tasks (usually called `jobs') at designated times and places around a
-network of computers. On a given computer, jobs might be run
-sequentially in a queue, one after the other, or they might be run in
-parallel.
-Jobs can also be started by triggers when sensors see certain system
-activity. CFEngine supports a full range of features for customizing
-hands-free scheduling.
-
-@node How can CFEngine help?, Define jobs with basic profile information , What is scheduling?, Top
-@unnumberedsec How can CFEngine help?
-
-CFEngine is able to schedule processes or jobs across all managed
-nodes, in a platform independent manner. This eliminates the
-distributed configuration of shedulers like cron. The time resolution
-for this depends on the frequency with with the cf-agent is scheduled
-to run. A normal recommendation is that cf-agent runs every 5 minutes,
-which is sufficiently often for most batch scheduling requirements.
-
-@node Define jobs with basic profile information , Chaining jobs together, How can CFEngine help?, Top
-@unnumberedsec Define jobs with basic profile information
-
-Jobs are scheduled using CFEngine as @code{commands} promises.
-To determine the conditions under which a job should be promised
-one uses @code{classes}.
-
-@verbatim
- bundle agent batch_jobs
- {
- commands:
-
- # Always run job on these three hosts
-
- host1||host2||host3::
-
- "/usr/local/bin/my_special_job $(sys.host)"
-
- comment => "Run the cluster task for this host";
- }
-@end verbatim
-
-@noindent To limit the job to a special time, we use time-classes:
-
-@verbatim
- bundle agent batch_jobs
- {
- commands:
-
- # Run job on all hosts at 13:05pm
-
- Hr13.Min00_05::
-
- "/usr/local/bin/my_special_job $(sys.host)"
-
- comment => "Run the cluster task for this host";
- }
-@end verbatim
-
-
-@noindent To combine, location and time coordinates, simply join the classes:
-
-@verbatim
- bundle agent batch_jobs
- {
- commands:
-
- # Run job on all hosts at 13:05pm
-
- (host1||host2||host3).Hr13.Min00_05::
-
- "/usr/local/bin/my_special_job $(sys.host)"
-
- comment => "Run the cluster task for this host";
- }
-@end verbatim
-
-@node Chaining jobs together, Calendars , Define jobs with basic profile information , Top
-@unnumberedsec Chaining jobs together
-
-Creating a managed process by chaining jobs together is also done
-using classes. To chain jobs into a sequence, you simply set a
-class if when the predecessor completes, and predicate the
-antecedant on that class:
-
-@verbatim
-
- bundle agent order
- {
- commands:
-
- # Dummy jobs to illustrate chaining
-
- Monday.Hr12.Min30_35::
-
- "/bin/echo Job one" classes => if_else("success","failure");
-
- success::
-
- "/bin/echo Next job";
-
- failure::
-
- "/bin/echo Error condition?";
-
- }
-
-@end verbatim
-
-@node Calendars , Logging execution, Chaining jobs together, Top
-@unnumberedsec Calendars
-
-You can define classes based on any combination of events in
-CFEngine, and in this way build up special calendars.
-
-@verbatim
- bundle agent jobs
- {
- classes:
-
- "holiday" or => {
- "July.Day4",
- "May.(Day1|Day2|Day3|Day4|Day5|Day6).Monday",
- "December.Day25"
- };
-
- commands:
-
- !holidays::
-
- "/usr/local/bin/my_special_job $(sys.host)"
-
- comment => "Run the cluster task for this host",
- action => if_elapsed("240");
- }
-@end verbatim
-
-@noindent Avoiding weekends is a simple matter, as is testing
-to see if the target system fulfills the requirements for the job:
-
-@verbatim
- bundle agent batch_jobs
- {
- classes:
-
- "weekend" expression => "Saturday|Sunday";
-
- "have_update_db" expression => fileexists("/usr/bin/updatedb");
-
- commands:
-
- (host1||host2||host3).!weekend::
-
- "/usr/local/bin/my_special_job $(sys.host)"
-
- comment => "Run the cluster task for this host every six hours",
- action => if_elapsed("240");
-
- have_locate_db.Hr01::
-
- "/usr/bin/updatedb"
-
- comment => "Update the locate db at 1 a.m. each night, if exists",
- action => if_elapsed("240");
- }
-@end verbatim
-
-@noindent Here are some other calendar ideas:
-
-@verbatim
-classes:
-
-"LunchAndTeaBreaks" expression => "!(Saturday|Sunday).(Hr12|Hr10|Hr15)";
-
-"NightShift" or => { "Hr22", "Hr23", "Night" };
-
-"ConferenceDays" or => { "Day26", "Day27", "Day29", "Day30" };
-
-"TimeSlices" or => { "Min01", "Min02", "Min03", "Min10_15"
- "Min33", "Min34", "Min35" };
-
-"Exception" not => "Hr12.Min15_20";
-
-@end verbatim
-
-@node Logging execution, Scheduling by Sensing Events and Patterns, Calendars , Top
-@unnumberedsec Logging execution
-
-@noindent There are many ways to log events in CFEngine.
-
-@verbatim
- bundle agent test
- {
- commands:
-
- "/usr/local/myjob"
-
- action => logme("myjob");
- }
-
-
- body action logme(x)
- {
- log_repaired => "/tmp/private_$(x)_keptlog.log";
- log_string => "$(sys.date) $(x) promised job succeeded";
- }
-
-@end verbatim
-
-@noindent This results in a log file @file{/tmp/private_myjob_keptlog.log}
-which contains data of the form:
-
-@smallexample
-Sat Aug 22 11:11:01 2009 myjob promised job succeeded
-Sat Aug 22 11:11:01 2009 myjob promised job succeeded
-@end smallexample
-
-@node Scheduling by Sensing Events and Patterns, Working with Unix cron, Logging execution, Top
-@unnumberedsec Scheduling by Sensing Events and Patterns
-
-@noindent Any measurable event on a system can trigger a response from
-cf-agent.
-
-
-
-@verbatim
- bundle agent test
- {
- commands:
-
- special_event::
-
- "/usr/local/open_help_ticket args";
- }
-
-@end verbatim
-
-For example, the monitoring agent @code{cf-monitord} sets system classes
-based events that are classified as anomalies on the system, as well as
-custom defined observations.
-
-
-@node Working with Unix cron, Commands promises, Scheduling by Sensing Events and Patterns, Top
-@unnumberedsec Working with Unix @code{cron}.
-
-One of CFEngine's strengths is its use of classes to identify systems
-from a single file or set of files. This allows you to have a single,
-central CFEngine file which contains all the `cron' jobs on your
-system without losing any of the fine control which cron affords
-you.
-
-One way to achieve this is to set up a regular cron job on every
-system which executes @code{cf-agent} at frequent intervals. Each
-time @code{cf-agent} is started, it evaluates time classes and
-executes the shell commands defined in its configuration file.
-CFEngine's time classes are much more powerful than
-@code{cron}'s time specification possibilities, and they add control
-over location too.
-
-@sp 1
-@cartouche
-DO I NEED TO USE CRON? No. With CFEngine's @code{cf-execd} you don't
-need to use cron at all -- CFEngine can schedule itself. Whether you choose
-to run @code{cf-execd} in daemon mode, or in wrapper mode is entirely
-up to you.
-@end cartouche
-@sp 1
-
-@node Commands promises, Splaying host times, Working with Unix cron, Top
-@unnumberedsec Commands promises
-
-CFEngine commands promises have the general form:
-
-@smallexample
-
-@var{promise-type}:
-
- @var{time-based classes::}
-
- @var{Promise}
-
-@end smallexample
-
-@noindent For example:
-
-@verbatim
-bundle agent example
-{
-commands:
-
-# Exec during every first quarter-hour after noon
-
- Hr12.Q1::
-
- "/path/myscript -arg1 -arg2";
-
-# Exec during any second quarter-hour
-
- Q2::
-
- "/path/otherscript";
-
-# Exec during the intervals 00:10 through 00:15 and 12:45 through 12:55
-# (English says ``and'', but logic says ``if this interval or that is true''
-
- Hr00.Min10_15||Hr12.Min45_55::
-
- "/path/amongstourscripts";
-
-}
-
-@end verbatim
-
-@noindent If you want to get fancy, you can set parameters for the
-execution of the script by building a container for it that traps its
-output and privileges (this applies to root only, since only root has
-this power to change privilege).
-
-@verbatim
-bundle agent example
-{
-commands:
-
-# Exec on the first quarter after noon
-
- Hr12.Q1::
-
- "/path/myscript -arg1 -arg2",
-
- contain => my_custom_jail("nobody","true");
-}
-
-# ...
-
-body contain my_custom_jail(owner,devnull)
-{
-exec_owner => "$(owner)"; # run with this setuid
-no_output => "$(devnull)"; # like > /dev/null 2>&1
-umask => "77"; # set process umask
-}
-
-@end verbatim
-The @samp{contain}ment body provides a safe and flexible environment in which
-to embed scripts.
-
-The time resolution of the classes is limited by how often you execute
-CFEngine either using cron or @code{cf-execd}. Five minutes is the
-recommended scheduling interval.
-
-@node Splaying host times, Choosing a scheduling interval, Commands promises, Top
-@unnumberedsec Splaying host times
-
-In a network of thousands of computers, many agents could start
-executing and downloading resources from a server at the same time.
-For instance, if a thousand cf-agents all suddenly wanted to copy a
-file from a master source simultaneously this would lead to a big load
-on the server. We can prevent this from happening by introducing a
-time delay which is unique for each host and not longer than some
-given interval; @code{cf-execd} uses a hashing algorithm to generate
-a number
-between zero and a maximum value in minutes which you define, like
-this:
-
-@verbatim
-
-body executor control
-
-{
-splaytime => "10"; # Minutes
-}
-
-@end verbatim
-
-
-
-@node Choosing a scheduling interval, Appendix - Did you know?, Splaying host times, Top
-@unnumberedsec Choosing a scheduling interval
-
-How often should you call your global CFEngine configuration? There
-are several
-things to think about:
-
-@itemize @bullet
-
-@item
-How much fine control do you need? Running cron jobs once each hour is
-usually enough for most tasks, but you might need to exercise finer
-control for a few special tasks.
-
-@item
-Are you going to verify the entire CFEngine configuration file
-or just selected promises?
-
-@end itemize
-
-CFEngine has an intelligent locking and timeout policy which should be
-sufficient to handle hanging shell commands from previous crons so that
-no overlap can take place.
-
-@node Appendix - Did you know?, , Choosing a scheduling interval, Top
-@unnumberedsec Appendix - Did you know?
-
-Here are some features that can help you with CFEngine's
-scheduling capabilities:
-
-@itemize
-@item Batch jobs can be made to run in parallel by using @code{background => "true"}
-in an @code{action} body.
-
-@item You can limit the frequency with which a batch job is executed with or without
-specifying an actual time of execution using the @code{ifelapsed} settings.
-Then a job will only be started if a certain number of minutes have elapsed since it
-was last started.
-
-@item You can make sure that jobs have not crashed or run out of control using
-the @code{expireafter} settings. Then a job that seems to have been
-running for too long will expire after a defined number of minutes and
-will be killed and restarted.
-
-@item The monitor agent @code{cf-monitord} can watch over special processes
-and monitor their resource usage, e.g. memory or CPU usage and report on these
-in CFEngine Nova.
-
-@item You can arrange for jobs to run in a `sandbox' or `jail', running
-as a special user, in a special directory without access to system resources.
-Thus system security can be addressed when running foreign applications.
-
-@end itemize
-
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_Security.texinfo b/docs/guides/SpecialTopic_Security.texinfo
deleted file mode 100644
index d98fcb63ad..0000000000
--- a/docs/guides/SpecialTopic_Security.texinfo
+++ /dev/null
@@ -1,736 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-security.info
-@settitle Architecture and Security
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title CFEngine Architecture and Security
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-
-This document describes an overview of the design principles and architecure used by CFEngine.
-
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} July 2010 CFEngine AS
-
-@end titlepage
-
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Iteration:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@node Top, Architecture Principles, (dir), (dir)
-@top Security
-@end ifnottex
-
-
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@menu
-* Architecture Principles::
-* Security Principles::
-* Communication Security::
-@end menu
-
-@node Architecture Principles, Security Principles, Top, Top
-@chapter Architecture Principles
-
-CFEngine is agent based software. It resides on and runs processes on
-each individual computer under its management. That means you do not
-need to grant any security credentials for login to CFEngine. Instead, for
-normal operation, CFEngine runs in privileged `root' or
-`Administrator' mode to get access to system resources and makes these
-available safely to authorized enquiries.
-
-A CFEngine installation is thus required on every machine you want to
-manage: client and server, desktop or blade. Typically, you will
-single out one machine to be a @i{policy server} or @i{hub}. In very
-large networks of many thousands of machines, you might need several
-policy servers, i.e. several hubs.
-
-
-Any piece of software has two different architectures, which should not be confused:
-
-@itemize
-@item The information flow that results in decisions (weak coupling).
-@item The software or service dependence graph (strong coupling).
-@end itemize
-
-Information flow is about how users determine what promises the
-software should keep; this is entirely informational and once
-decisions are made they can be stored (cached) for an indefinite
-time. The dependence graph explains what services or resources are
-required by the software in order to keep its promises. This is a
-strong dependency because the software is unable to function without
-the availability of these resources at all times. Systems are robust
-if they are only weakly coupled. Strong dependence introduced
-@i{fragility} of design.
-
-In many software products these two separate models are identical in
-design and implementation. However, Promise Theory maintains their
-independence and CFEngine makes no assumptions about the kind of
-information flows that should be set up.
-
-@sp 1
-@cartouche
-CFEngine takes host autonomy as its guiding
-architectural principle. Agents are functionally independent of one another
-and only weak couplings can be promised.
-@end cartouche
-
-@sp 1
-The implication of this principle is that CFEngine is robust to
-failures of communication (e.g. network connectivity) and that each
-host is responsible for maintaining its own state. This affects the
-security and scalability of the solution.
-
-@menu
-* Single point of coordination::
-* Policy information flow::
-* Robustness to failure::
-* Distributed execution and federation::
-@end menu
-
-@node Single point of coordination, Policy information flow, Architecture Principles, Architecture Principles
-@section Single point of coordination
-
-The default CFEngine Nova architecture uses a single hub or policy
-server to publish changes of policy and to aggregate knowledge about
-the environment, but you can set up as many as you like to manage
-different parts of your organization independently. The CFEngine
-technology is not centralized by nature. Most users choose to
-centralize updating of policy and report aggregation for convenience
-however.
-
-@sp 1
-@center @image{hub,10cm,,The front page,png}
-@center Figure: A policy server or `hub' is implemented in CFEngine Nova
-@center as a simple solution that will scale for most sites `out of the box'.
-@sp 1
-
-If you operate CFEngine Nova in its default mode, the hub acts as a
-server from which every other client machine can access policy
-updates. It also acts as a collector, aggregating summary information
-from each machine and weaving it into a knowledge map about the datacenter.
-
-For a single hub configuration, the figure below shows a normal
-process approach to managing policy. Policy is edited and developed at
-a Policy Definition Point, outside of normal production
-environment. This can be done using the specialized editor embedded
-in CFEngine Nova, or it can be done using any text editor of your choice.
-
-@node Policy information flow, Robustness to failure, Single point of coordination, Architecture Principles
-@section Policy information flow
-
-Edits are made in conjunction with a version control
-repository@footnote{CFEngine supports integration with Subversion
-through its Mission Portal, but any versioning system can of course be
-used.}, which should be used to document the @i{reasons} for changes
-to policy@footnote{CFEngine and version control will document @i{what}
-the changes are, but what is usually missing from user documentation
-is an explanation of the reasonsing behind the change. This is most
-valuable when trying to diagnose and debug changes later.}. When a
-change has been tested and approved, it will be copied manually to the
-policy dispatch point on one or more distribution servers. All other
-machines will then download policy updates from that single location according
-to their own schedule.
-
-@sp 1
-@image{arch,15cm,,The front page}
-@center Figure: Policy coordinated from a central root location
-@center is implemented in a distributed manner at every leaf node.
-@sp 1
-
-@node Robustness to failure, Distributed execution and federation, Policy information flow, Architecture Principles
-@section Robustness to failure
-
-If an agent receives a policy proposal that is badly formed or in some
-way non-executable, it switches to a failover strategy to recover. It will
-continue in this mode until a new policy proposal is available that can be
-executed.
-
-The CFEngine agent clones itself to avoid limitations of operating systems
-like Windows, where programs and disk files cannot be altered while in use.
-When new software updates are available, CFEngine can update itself from
-a suitable source, and restart its own services. Should the new version be corrupt,
-the twin will still be the old working version, hence the software will be able
-to recover as soon as a new valid version is available.
-
-@node Distributed execution and federation, , Robustness to failure, Architecture Principles
-@section Distributed execution and federation
-
-Each agent runs independently of others, unless it promises to
-acquire services from other hosts. Thus all processing capacity and
-decision-making computation takes place on the end nodes of the
-communication graph. There is no apriori need for agents to collect
-data from any source outside themselves, though this is a highly
-convenient strategy. CFEngine's use of the network may be called opportunistic.
-
-Each agent is the ultimate arbiter of whether or not to accept
-information from external sources. This makes CFEngine ideal for use
-in federated architectures, where attention to local requirements is
-paramount for whatever reason. Federation is typically a recommended
-strategy when the cost of avoiding local specialization outweighs the
-price of having local policy-makers. Universities and large companies
-(e.g. formed through acquisition) are typical candidates for federated
-management. Federation is facilitated by an essentially `service
-oriented architecture'@footnote{NB. CFEngine does not use web services
-as part of its technology, so this should not be construed to mean SOA.}, i.e. a weak coupling.
-
-
-@node Security Principles, Communication Security, Architecture Principles, Top
-@chapter Security Principles
-
-@menu
-* What is security?::
-* The principles of CFEngine security::
-* Communications::
-@end menu
-
-@node What is security?, The principles of CFEngine security, Security Principles, Security Principles
-@section What is security?
-@sp 1
-
-The concept of security, while various in its interpretation and
-intented use, is related to a feeling of safety. No system is
-completely safe from every threat, thus no system can promise complete
-security. Security is ultimately defined by a model, an attitude, and
-a policy. It involves a set of compromises called a @i{trust model}
-that determines where you draw the line in the sand between trusted
-and risky.
-
-@node The principles of CFEngine security, Communications, What is security?, Security Principles
-@section The principles of CFEngine security
-
-CFEngine adheres to the following design principles:
-
-@enumerate
-@item It shall be, by design, impossible to send policy-altering data to
-a CFEngine agent. Each host shall retain its right to veto policy suggestions
-at all times. This is called the Voluntary Cooperation Model.
-
-@item CFEngine will support the encyrption of data transmitted over the network.
-
-@item Each host shall continue to function, as
-far as possible, without the need for communication with other hosts.
-
-@item CFEngine will use a lightweight peer model for key trust (like
-the Secure Shell). No centralized certificate authority shall be
-used. SSL and TLS shall not be used.
-
-@item CFEngine shall always provide safe defaults, that grant no access to other
-hosts.
-@end enumerate
-
-@node Communications, , The principles of CFEngine security, Security Principles
-@section Communications
-
-CFEngine uses a simple, private protocol that is based on (but not
-identical to) that used by OpenSSH (the free version of the Secure
-Shel). It is based on mutual, bi-directional challenge-reponse using
-an autonomous Public Key Infrastructure.
-
-@itemize
-@item Authentication by Public Key is mandatory.
-@item Encryption of data transfer is optional.
-@end itemize
-
-@node Communication Security, , Security Principles, Top
-@chapter Communication Security
-
-
-@menu
-* TCP wrappers::
-* The connection sequence::
-* Encyption algorithms::
-* Remote communication::
-* Authentication::
-* Security FAQ::
-* CFEngine and Firewalls::
-* Tamperproof data and distributed monitoring::
-@end menu
-
-@node TCP wrappers, The connection sequence, Communication Security, Communication Security
-@section TCP wrappers
-
-The right to connect to the server is the first line of defence.
-CFEngine has built into it the equivalent of the `TCP wrappers'
-software to deny non-authorized hosts the ability to connect to the
-server at all.
-
-@node The connection sequence, Encyption algorithms, TCP wrappers, Communication Security
-@section The connection sequence
-
-@enumerate
-
-@item A client attempts to connect to port 5308
-@item Server examines IP address of connection and applies rules from
-@verbatim
-allowconnects
-allowallconnects
-denyconnects
-@end verbatim
-@item If host is allowed to connect, read max 2048 bytes to look for valid hail
-
-@item Client sends its hostname, username and public key to server
-@item Server checks whether public key is known
-@itemize
-@item If known, host and user are confirmed, go to access control
-@item If unknown, use trustkeysfrom rules to check whether we should accept the client's asserted identity
-@end itemize
-@item If not in trustkeysfrom list, break connection
-@item If willing to trust, go to further checks
-
-@item If skipverify is set, ignore reverse DNS lookup checks else check asserted identity by reverse DNS lookup
-@item If fails break off
-@item Check user ID is in allowusers
-@item If fails break off
-@item Go to file access control
-
-@item Process admit first then deny
-@item Mapping of root privilege on server is governed by @code{maproot}. If this is false, only resources owned by the authenticated user name may be transmitted.
-@item If @code{ifencrypted} is set, access is denied to non-encrypted connections.
-@item Symbolic links to files are not honoured by the server when computing access.
-@item Access control is evaluated by the rules:
-@itemize
-@item First admit rule that matches wins
-@item All other admit rules are ignored
-@item No admit rule means you're denied!
-@item Then look at deny rules (overrides admit)
-@item First deny rule that matches wins
-@item All other deny rules are ignored
-@item No deny rule means you're admitted
-@end itemize
-@end enumerate
-
-@node Encyption algorithms, Remote communication, The connection sequence, Communication Security
-@section Encryption algorithms
-
-CFEngine Community Edition uses RSA 2048 public key encryption for
-authentication. These are generated by the @samp{cf-key} command.
-It generates a 128 bit random Blowfish encryption key for data
-transmission. Challenge response is verified by an MD5 hash.
-
-Commercial Editions of CFEngine use the same RSA 2048 key for
-authentication, and then AES 256 with a 256 bit random key for data
-transmission. The latter is validated for FIPS 140-2 government use in
-the United States of America. Challenge response is verified by a SHA256
-hash.
-
-
-@node Remote communication, Authentication, Encyption algorithms, Communication Security
-@section Remote communication
-
-The concept of voluntary cooperation used by CFEngine places restrictions
-on how files can be copied between hosts. CFEngine allows only `pull'
-(download) but not `push' (upload). Users cannot force an agent to
-perform an operation against local policy.
-
-To allow remote copying between two systems each
-of the system must explicitly grant access before the operation can
-take place.
-
-
-
-
-@c =========================================================================0
-@node Authentication, Security FAQ, Remote communication, Communication Security
-@section Authentication
-
-Authentication is about making sure users are who they say you
-are. Traditionally, there are two approaches: the trusted third
-party (arbiter of the truth) approach, and the challenge-response
-approach. The Trust Third Party decides whether two individuals who
-want to authenticate should trust each other. This is the model used
-in the Web.
-
-The challenge-response approach allows each individual to decide
-personally whether to trust the other. This is the approach used by
-CFEngine. Its model is based in the Secure Shell (OpenSSH).
-
-
-Two machines authenticate each other in a @i{public key exchange}
-process. For key exchange between client and server, the server has to
-decide if it will trust the client by using the @code{trustkeysfrom}
-directive. The @code{trustkeysfrom} directive allows the server to accept
-keys from one or more machines.
-
-On the client-side the client also has to specify if it will trust key
-from the server by using the trustkey directive. The @code{trustkey}
-directive in @code{copy_from} allows a client to decide whether to
-accept keys from a server. The CFEngine authentication model is based
-on the @code{ssh} scheme, however unlike @code{ssh}, CFEngine
-authentication is not interactive and the keys are generated by
-@code{cf-key} program instead of @samp{ssh key-gen} program. Key
-acceptance is accomplished in CFEngine using trust-key method. Once
-the keys have been exchange the trust settings are irrelevant.
-
-
-@node Security FAQ, CFEngine and Firewalls, Authentication, Communication Security
-@section Security FAQ
-
-
-@itemize @bullet
-@item @i{ Doesn't opening a port on a machine on the inside of the firewall make
-it vulnerable to both Denial of Service and buffer overflow attacks?}
-
-Buffer overflow attacks are extremely unlikely in CFEngine by
-design. The likelihood of a bug in CFEngine should be compared to the
-likelihood of a bug existing in the firewall itself.
-
-Denial of Service attacks can be mitigated by careful
-configuration. @code{cf-serverd} reads a fixed number of bytes from the
-input stream before deciding whether to drop a connection from a
-remote host, so it is not possible to buffer overflow attack before
-rejection of an invalid host IP.
-
-Another possibility is to use a standard VPN to the inside of the
-firewall. That way one is concerned first and foremost with the
-vulnerabilities of the VPN software.
-
-@item @i{Doesn't opening the firewall
-compromise the integrity of the policy information by allowing an
-attacker the chance to alter it?}
-
-The CFEngine security model, as well
-as the design of the server, disallows the uploading of
-information. No message sent over the CFEngine channel can alter data
-on the server. (This assumes that buffer overflows are impossible.)
-
-@item @i{Couldn't an IP spoofer gain access to data from the policy
-server that it should not be able to access?}
-
-Assuming that buffer overflow attacks and DOS attacks are highly
-improbable, the main worry with opening a port is that intruders will
-be able to gain access to unauthorized data. If the firewall is
-configured to open only connections from the policy mirror, then an
-attacker must spoof the IP of the policy attacker. This requires
-access to another host in the DMZ and is non-trivial. However, suppose
-the attacker succeeds then the worst he/she can do is to download
-information that is available to the policy-mirror. But that
-information is already available in the DMZ since the data have been
-exported as part of the policy, thus there is no breach of
-security. (Security must be understood to be a breach of the terms of
-policy that has been decided.)
-
-@item @i{ What happens if the policy mirror is invaded by an attacker?}
-
-If an attacker gains root access to the mirror, he/she will be able to
-affect the policy distributed to any host. The
-policy-mirror has no access to alter any information on the policy
-source host. Note that this is consistent with the firewall security
-model of trusted/untrusted regions. The firewall does not mitigate the
-responsibility of security every host in a network regardless of which
-side of the firewall it is connected.
-@end itemize
-
-
-@c ----------------------------------------------------
-@menu
-* CFEngine and Firewalls::
-@end menu
-
-@node CFEngine and Firewalls, Tamperproof data and distributed monitoring, Security FAQ, Communication Security
-@section CFEngine and Firewalls
-
-
-Some users want to use CFEngine's remote copying mechanism through a
-firewall, in particular to update the CFEngine policy on hosts inside
-a DMZ (so-called de-militarized zone). In making a risk assessment, it
-is important to see the firewall security model together with the
-CFEngine security model. CFEngine's security record is better than
-most firewalls, but Firewalls are nearly always trusted because they
-are `security products'.
-
-Any piece of software that traverses a firewall can, in principle,
-weaken the security of the barrier. On the other hand, a strong piece
-or software might have better security than the firewall
-itself. Consider the example in the figure;
-
-@image{firewall,10cm,,A CFEngine host outside a firewall,png}
-
-
-We label the regions inside and outside of the firewall as the ``secure
-area" and ``Demilitarized Zone" for convenience. It should be
-understood that the areas inside a firewall is not necessarily secure
-in any sense of the word unless the firewall configuration is
-understood together with all other security measures.
-
-Our problem is to copy files from the ``secure'' source machine to hosts
-in the DMZ, in order to send them their configuration policy
-updates. There are two ways of getting files through the firewall:
-
-@itemize @bullet
-@item An automated CFEngine solution, i.e., pull from outside to inside the secure area.
-@item A manual push to the outside of the wall from the inside.
-@end itemize
-
-One of the
-main aims of a firewall is to prevent hosts outside the secure area
-from opening connections to hosts in the secure area. If we want
-@code{cfagent} processes on the outside of the firewall to receive updated policies
-from the inside of the firewall, information has to traverse the
-firewall.
-
-@c ------------------------------
-@menu
-* CFEngine trust model::
-* Policy Mirror in the DMZ::
-* Pulling through a wormhole::
-@end menu
-
-
-
-
-@node CFEngine trust model, Policy Mirror in the DMZ, CFEngine and Firewalls, CFEngine and Firewalls
-@subsection CFEngine trust model
-
-CFEngine's trust model is fundamentally at odds with the external
-firewall concept. CFEngine says: ``I am my own boss. I don't trust
-anyone to push me data.'' The firewall says: ``I only trust things
-that are behind me.'' The firewall thinks it is being secure if it
-pushes data from behind itself to the DMZ. CFEngine thinks it is being
-secure if it makes the decision to pull the data autonomously, without
-any orders from some potentially unknown machine. One of these
-mechanisms has to give if firewalls are to co-exist with CFEngine.
-
-
-From the firewall's viewpoint, push and pull are different: a push
-requires only an outgoing connection from a trusted source to an
-untrusted destination; a pull necessarily requires an untrusted
-connection being opened to a trusted server within the secure area.
-For some firewall administrators, the latter is simply unacceptable
-(because they are conditioned to trust their firewall). But it is
-important to evaluate the actual risk. We have a few observations
-about the latter to offer at this point:
-
-@itemize @bullet
-@item It is not the aim of this note to advocate any one method of
-update. You must decide for yourself. The aim here is only to evaluate
-the security implications. Exporting data from the secure area to the
-DMZ automatically downgrades the privacy of the information.
-
-@item The CFEngine security model assumes that the security of every host
-will be taken seriously. A firewall should never be used as a
-substitute for host security.
-
-@item Knowing about CFEngine but not your firewall or your secure network, it is only possible
-to say here that it seems, to us, safe to open a hole in a firewall to
-download data from a host of our choice, but we would not accept data
-from just any host on your company network on trust. It would be
-ludicrous to suggest that an arbitrary employee's machine is more
-secure than an inaccessible host in the DMZ.
-@end itemize
-
-@c ----------------------------------------
-@node Policy Mirror in the DMZ, Pulling through a wormhole, CFEngine trust model, CFEngine and Firewalls
-@subsection Policy Mirror in the DMZ
-
-By creating a policy mirror in the DMZ, these issues can be worked around. This is
-the recommended way to copy files, so that normal CFEngine pull
-methods can then be used by all other hosts in the DMZ, using the
-mirror as their source. The policy mirror host should be as secure as
-possible, with preferably few or no other services running that might
-allow an attacker to compromise it. In this configuration, you are
-using the mirror host as an envoi of the secure region in the DMZ.
-
-Any method of pushing a new version of policy can be chosen in
-principle: CVS, FTP, RSYNC, SCP. The security disadvantage of the push
-method is that it opens a port on the policy-mirror, and therefore the
-same vulnerability is now present on the mirror, except that now you
-have to trust the security of another piece of software too. Since
-this is not a CFEngine port, no guarantees can be made about what
-access attackers will get to the mirror host.
-
-@c ----------------------------------------
-@node Pulling through a wormhole, , Policy Mirror in the DMZ, CFEngine and Firewalls
-@subsection Pulling through a wormhole
-
-Suppose you are allowed to open a hole in your firewall to a single
-policy host on the inside. To distribute files to hosts that are
-outside the firewall it is only necessary to open a single tunnel
-through the firewall from the policy-mirror to the CFEngine service
-port on the source machine. Connections from any other host will still
-be denied by the firewall. This minimizes the risk of any problems
-caused by attackers.
-
-To open a tunnel through the firewall, you need to alter
-the filter rules. A firewall blocks access at the network
-level. Configuring the opening of a single port is
-straightforward. We present some sample rules below, but make sure
-you seek the guidance of an expert if necessary.
-
-Cisco IOS rules look like this
-@smallexample
-ip access-group 100 in
-access-list 100 permit tcp mirror host source eq 5308
-access-list 100 deny ip any any
-@end smallexample
-Linux @code{iptables} rules might look something like this:
-@smallexample
-iptables -N newchain
-iptables -A newchain -p tcp -s mirror-ip 5308 -j ACCEPT
-iptables -A newchain -j DENY
-@end smallexample
-
-Once a new copy of the policy is downloaded by CFEngine to the policy
-mirror, other clients in the DMZ can download that copy from the
-mirror. The security of other hosts in the DMZ is dependent on the
-security of the policy mirror.
-
-
-
-@node Tamperproof data and distributed monitoring, , CFEngine and Firewalls, Communication Security
-@section Tamperproof data and distributed monitoring
-
-Message digests are supposed to be unbreakable, tamperproof
-technologies, but of course everything can be broken by a sufficiently
-determined attacker. Suppose someone wanted to edit a file and alter
-the CFEngine checksum database to cover their tracks. If they had
-broken into your system, this is potentially easy to do. How can we
-detect whether this has happened or not?
-
-A simple solution to this problem is to use another checksum-based
-operation to copy the database to a completely different host. By using
-a copy operation based on a checksum value, we can also remotely detect
-a change in the checksum database itself.
-
-Consider the following code:
-
-@verbatim
-
-bundle agent change_management
-{
-vars:
-
- "watch_files" slist => {
- "/etc/passwd",
- "/etc/shadow",
- "/etc/group",
- "/etc/services"
- };
-
- "neighbours" slist => peers("/var/cfengine/inputs/hostlist","#.*",4),
- comment => "Partition the network into groups";
-
-files:
-
- "$(watch_files)"
-
- comment => "Change detection on the above",
- changes => detect_diff_content;
-
- #######################################################################
- # Redundant cross monitoring .......................................
- #######################################################################
-
- "$(sys.workdir)/nw/$(neighbours)_checksum_digests.db"
-
- comment => "Watching our peers remote hash tables for changes - cross check",
- copy_from => remote_cp("$(sys.workdir)/checksum_digests.db","$(neighbours)"),
- depends_on => { "grant_hash_tables" },
- action => neighbourwatch("File changes observed on $(neighbours)");
-
-@end verbatim
-
-
-It works by building a list of neighbours for each host. The function
-@code{peers} can be used for this. Using a file which contains a list
-of all hosts running CFEngine, we create a list of hosts to copy
-databases . Each host in the network therefore takes on the
-responsibility to watch over its neighbours.
-
-In theory, all four neighbours should signal this change. If an
-attacker had detailed knowledge of the system, he or she might be able
-to subvert one or two of these before the change was detected, but it
-is unlikely that all four could be covered up. At any rate, this
-approach maximizes the chances of change detection.
-
-Consider what happens if an attacker changes a file an
-edits the checksum database. Each of the four hosts that has been
-designated a neighbour will attempt to update their own copy of the
-database. If the database has been tampered with, they will detect a
-change in the checksums of the remote copy versus the
-original. The file will therefore be copied.
-
-It is not a big problem that others have a copy of your checksum
-database. They cannot see the contents of your files from this. A
-possibly greater problem is that this configuration will unleash an
-avalanche of messages if a change is detected. This makes messages
-visible at least.
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
diff --git a/docs/guides/SpecialTopic_Teamwork.texinfo b/docs/guides/SpecialTopic_Teamwork.texinfo
deleted file mode 100644
index 385a934237..0000000000
--- a/docs/guides/SpecialTopic_Teamwork.texinfo
+++ /dev/null
@@ -1,277 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-teams.info
-@settitle Teamwork
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Teams and Delegation
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-Team work is a collaboration between individuals with different
-skills. It is key element in decentralized organization -- both for
-humans and computers.
-
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2009 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@node Top, What is team-work?, (dir), (dir)
-@top Teams
-@menu
-* What is team-work?::
-* Creative roles::
-* Delegating roles in a collaboration::
-@end menu
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@node What is team-work?, Creative roles, Top, Top
-@unnumberedsec What is team-work?
-@sp 1
-
-Team work is a collaboration between individuals with different
-skills. It is key element in decentralized organization -- both for
-humans and computers.
-
-Teams exist for efficiency (divide and conquer by skill) and also
-because because humans need continual motivation and emotional support
-which sustains work-flow and adds creativity to work.
-
-The team-aspect of management is often overlooked in favour of
-top-down hierarchical design (do what the boss tells you). CFEngine
-does not force us into hierarchical systems however;
-the team analogy is more appropriate for CFEngine's
-model of voluntary cooperation.
-
-@image{hierarchy,12cm,,Hierarchy has long traditions but modern thinking favours teams.,png}
-
-IT management is complex, so it makes sense to delegate
-responsibility for different issues. An organization will generally
-consist of many groups and teams already, each with their own special
-needs and each craving its own autonomy. CFEngine and promise theory
-were designed for precisely this kind of environment. CFEngine allows
-cooperation and sharing without allowing central managers to ride
-roughshod over local needs.
-
-Teams thrive by discussion and interaction within the framework of a
-policy or vision, allowing variation and arriving at a consensus when
-necessary. Success in a team depends on a combination of abilities
-working together not undermining one another. Conflicts in the
-promises made by team members reveal design problems in the group. An
-analysis of promises (CFEngine's model of collaboration) is a
-significant tool for understanding and enabling teams.
-
-@sp 1
-@cartouche
-Team work and policy design for inter-host cooperation are closely
-related. Use promises as a tool to explain to the individuals in a team
-which individual is responsible for what role, and to what extent.
-@end cartouche
-@sp 1
-
-@node Creative roles, Delegating roles in a collaboration, What is team-work?, Top
-@unnumberedsec Creative roles
-@sp 1
-
-M. Belbin, a researcher in teamwork has identified nine abilities or
-roles (kinds of promise) to be played in a team collaboration (regardless
-of how many people there are in the team):
-
-@enumerate
-@item Plant -- a creative ``ideas'' person who solves problems.
-
-@item Shaper -- this is a dynamic member of the team who thrives on
-pressure and has the drive and courage to overcome obstacles.
-
-@item Specialist -- someone who brings specialist knowledge to the group.
-
-@item Implementer -- a practical thinker who is rooted in reality and can turn ideas into
-practice (who sometimes frustrates more imaginative high flying
-visionaries).
-
-
-@item Resource Investigator -- an enabler, or someone who knows where to
-find the help the team needs regardless of whether the help is
-physical, financial or human. This person is good at networking.
-
-
-@item Chairman/Co-ordinator -- an arbitrator who makes sure that
-everyone gets their say and can contribute.
-
-@item Monitor-Evaluator -- is a dispassionate, discerning member who can
-judge progress and achievement accurately during the process.
-
-
-@item Team Worker -- someone concerned with the team's inter-personal
-relationships and who is sensitive to the atmosphere of the group.
-
-
-
-@item Completer/Finisher -- someone critical and analytical who looks after the details of
-presentation and spots potential flaws and gaps. The completer is
-a quality control person.
-@end enumerate
-
-His model leaves little room for technical workflow arguments. It is
-entirely concerned with the creative process. This is probably
-significant. We should ask ourselves: how can we use the freedom to
-organize into specialized teams to maximize human creativity, while
-passing hard work over to machines. Solving this problem is what
-CFEngine is about.
-
-
-@node Delegating roles in a collaboration, , Creative roles, Top
-@unnumberedsec Delegating roles in a collaboration
-@sp 1
-
-We need to delegate responsiblity to divide and conquer a problem, both when
-designing policy for computers and when making work schedules for humans. But how
-can we be certain different parties will not interfere with one
-anothers' responsibilities? The bottom line is that we cannot be certain
-without oversight and coordination.
-
-Promise theory shows that coordination needs a single
-point of coordination to be the arbiter of correctness in any collaborative
-process: a so-called `checkpoint' or `team leader', like passport
-control at an airport. This checkpoint has to examine each
-contribution to the team and look for conflicts.
-
-For humans, this might be a matter of communication by meeting. CFEngine,
-on the other hand, has no built-in meta-access control mechanism which
-can decide who may write policy rules. To create such a mechanism,
-there would have to be a monitor which could identify users, and an
-authority mechanism that would disallow certain users to write rules
-of certain types about certain objects on certain hosts.
-
-CFEngine Community Edition has @code{roles} promises, which offer a
-partial solution, but it does not address the core issue which is that
-collaboration in change requires freedom to act, not restriction.
-Delegation therefore requires trust. CFEngine Nova/Enterprise
-has `hubs' which can be coordinate large numbers of
-hosts. Coordination can also be pre-arranged as policy, so that
-everyone has their own copy of the script. This is how an orchestra
-scales, for instance.
-
-To keep matters as simple as possible, CFEngine avoids this kind of
-technical coordination as much as possible and proposes a different
-approach, using policy along with a social contract between
-the collaborating teams. Promise theory allows us to model the collaborative security
-implications of this (see the figure of the bow-tie structure). A
-simple method of delegating is the following.
-
-@enumerate
-@item Delegate responsibility for different issues to admin teams 1,2,3, etc.
-@item Make each of these teams responsible for version control of their own
-configuration rules.
-@item Make an intermediate agent responsible for collating and vetting the rules, checking for
-irregularities and conflicts. This agent must promise to disallow rules by
-one team that are the responsibility of another team. The agent could be a
-layer of software, but a cheaper and more manageable solution is the make this
-another group of one or more humans.
-
-@item Make the resulting collated configuration version controlled. Publish
-approved promises for all hosts to download from a trusted source.
-
-
-@end enumerate
-
-A review procedure for policy-promises is a good solution if you want
-to delegate responsibility for different parts of a policy to
-different sources. Human judgement as the `arbiter' is irreplaceable,
-but tools can be added to make conflicts easier to detect.
-
-Promise theory underlines that, if a host or computing device accepts
-policy from any source, then it is alone and entirely responsible for
-this decision. The ultimate responsibility for the published version
-policy is the vetting agent. This creates a shallow hierarchy, but
-there is no reason why this formal body could not be comprised of
-representatives from the multiple teams.
-
-The figure below shows how a number of policy authoring teams can work together
-safely and securely to write the policy for a number of hosts, by vetting through
-a checkpoint, in a classic `bow-tie' formation.
-
-@image{delegate,15cm,,Delegation of responsibility requires vetting access,png}
-
-
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_Virtualization.texinfo b/docs/guides/SpecialTopic_Virtualization.texinfo
deleted file mode 100644
index 1b7528ad4b..0000000000
--- a/docs/guides/SpecialTopic_Virtualization.texinfo
+++ /dev/null
@@ -1,525 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-virt.info
-@settitle Virtualization and Cloud Support in CFEngine
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Virtualization and Cloud Support in CFEngine
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-CFEngine Nova integrates simply with existing frameworks for
-virtualization and cloud computing, allowing you to apply convergent
-`self-healing' methods to the deployment and management of virtual
-machines running anywhere.
-
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2010 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-
-@node Top, What are virtualization and cloud computing?, (dir), (dir)
-@top Virtualization
-
-@ifnottex
-@menu
-* What are virtualization and cloud computing?::
-* Why build virtualization support into CFEngine?::
-* What can CFEngine do with virtual machines?::
-* Guest environments promises::
-* Virtualization types supported::
-* Distinct states::
-* Example deployment::
-* Virtualized host examples::
-* Virtual network example::
-@end menu
-
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@node What are virtualization and cloud computing?, Why build virtualization support into CFEngine?, Top, Top
-@unnumberedsec What are virtualization and cloud computing?
-@sp 1
-
-Virtualization refers to the ability to run multiple host instances on
-a single physical node. Cloud computing typically refers to what is
-called `platform as a service', or deployment of virtual machines on
-demand, often as an online service.
-
-In this document, virtualization support refers specifically to
-hypervisor technologies supported by the open source library layer @i{libvirt}
-project, which includes interfaces for Xen, KVM, Vmware-ESX, and more.
-CFEngine thus integrates freely with other tools based on this library, such
-as @i{virsh} and the @i{Virtual Manager} graphical user interface.
-
-
-@node Why build virtualization support into CFEngine?, What can CFEngine do with virtual machines?, What are virtualization and cloud computing?, Top
-@unnumberedsec Why build virtualization support into CFEngine?
-@sp 1
-
-Virtualization engines (usually called supervisors or hypervisors) are
-seeing an explosion of development. They exist as a number of projects
-in various stages of maturity. The libvirt project was designed as
-an integration layer based on an XML specification.
-
-The tools for management are still quite primitive and require much
-manual work. CFEngine has a unique role to play in maintaining desired
-state in virtual machine systems.
-
-In the cloud, virtual machines may be rented from remote commercial
-providers, and managed as disposable resources. Convergent or
-`self-healing' maintenance is an essential method for managing
-machines that are geographically remote and awkward to access, e.g.
-machines in other time-zones that it is impractical to monitor by
-legacy methods.
-
-
-@node What can CFEngine do with virtual machines?, Guest environments promises, Why build virtualization support into CFEngine?, Top
-@unnumberedsec What can CFEngine do with virtual machines?
-@sp 1
-
-The simple answer is: anything that @i{libvirt} can do, with added
-convergence to a desired state: that means, creating, destroying and
-starting and stopping machines. By starting virtual machines through
-CFEngine, you can be sure that a given `virtual guest' is running on
-one and only one physical host, thus avoiding conflicts that are
-difficult to detect with centralized systems.
-
-CFEngine does not support everything that libvirt does -- it offers a
-simplified interface that is meant for robustness, stability and
-hands-free repeatability.
-
-@sp 1
-@cartouche
-CFEngine does not use libvirt's TLS based web communication layer. It
-manages every host as an independent entity, in typical CFEngine
-fashion, using CFEngine's own distributed cooperation to provide thje
-implicit communication. CFEngine does not currently support so-called
-`live migration' of virtual machines.
-@end cartouche
-@sp 1
-
-@node Guest environments promises, Virtualization types supported, What can CFEngine do with virtual machines?, Top
-@unnumberedsec Guest environments promises
-@sp 1
-
-A virtual machine is one example of what CFEngine calls an
-`guest_environment'. You can promise to create (and host) an guest environment
-with certain attributes, just as you can promise to host a file or a
-process. Here is a simple example:
-
-@verbatim
-body common control
-{
-bundlesequence => { "my_vm_cloud" };
-}
-
-#######################################################
-
-bundle agent my_vm_cloud
-{
-guest_environments:
-
- "myUbuntu" # the running instance name, defined in XML
-
- environment_resources => virt_xml,
- environment_type => "xen",
- environment_host => "my_physical_computer", # ipv4_10_1_2_3
- environment_state => "create";
-}
-
-#######################################################
-
-body environment_resources virt_xml
-{
-env_spec_file => "/srv/xen/centos5-libvirt-create.xml";
-}
-
-@end verbatim
-
-@itemize
-@item The promiser (in this case @samp{myUbuntu}) is the name of the virtual
-machine. This should be a unique identifier, as we need to be able to
-refer to machines uniquely.
-
-@item The guest environment host is the name of the computer that
-is the host for the virtual machine.
-
-@item Normally when we want to ensure something on a machine, we use classes
-to decide where the promise will be made. For guest environments, however,
-we need to make promises about the uniqueness of the machine. When you
-make a machine instance you normally want it to be running on one and
-only one host. So you want @i{every} machine to make a promise. On the
-guest environment's host, you want to promise that the guest environment is
-running, and on every other machine you want to promise that it is
-not. In CFEngine, you simply include a unique class belonging to host
-in the promise using @code{environment_host} and CFEngine assumes that
-rest. Unique classes might include
-@itemize
-@item Hostname class e.g. @code{myhost_CFEngine_com}
-@item IP address class e.g. @code{ipv4_123_456_789_123}
-@end itemize
-@end itemize
-
-An alternative way to write this example is to quote the XML
-specification in CFEngine directly. This has a few advantages: you can
-re-use the data and use it as a template, filling in
-CFEngine-variables. You can thus adapt the configuration using
-CFEngine's classes.
-
-@page
-@verbatim
-bundle agent my_vm_cloud
-{
-guest_environments:
-
- "myUbuntu" # the running instance name, defined in XML
- environment_resources => virt_xml("$(this.promiser)"),
- environment_type => "xen",
- environment_host => "myphysicalcomputer";
- environment_state => "create"
-}
-
-#######################################################
-
-body environment_resources virt_xml(host)
-{
-env_spec_file =>
-
-"
- $(host)
-
- linux
- /var/lib/xen/install/vmlinuz-ubuntu10.4-x86_64
- /var/lib/xen/install/initrd-vmlinuz-ubuntu10.4-x86_64
- kickstart=http://example.com/myguest.ks
-
- 131072
- 1
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-";
-}
-@end verbatim
-
-You should consult the libvirt documentation for the details of the XML specification.
-
-
-@node Virtualization types supported, Distinct states, Guest environments promises, Top
-@unnumberedsec Virtualization types supported
-@sp 1
-
-CFEngine currently supports virtualization only through libvirt, so it supports
-those technologies that libvirt supports. Currently this includes most popular
-technologies. You must choose the type of monitor that is to be responsible for
-keeping the guest environment promise. In CFEngine, you should choose between a
-machine environment or network environment of the following types:
-@table @code
-@item xen
-A Xen hypervisor virtual domain.
-@item kvm
-A KVM hypervisor virtual domain.
-@item esx
-A VMware hypervisor virtual domain.
-@item test
-The libvirt test-hypervisor virtual domain.
-@item xen_net
-A Xen hypervisor virtual network.
-@item kvm_net
-A KVM hypervisor virtual network
-@item esx_net
-An ESX/VMWare hypervisor virtual network.
-@item test_net
-The test hypervisor virtual network.
-@item zone
-A Solaris zone (future development)
-@item ec2
-An Amazon EC2 instance (future development)
-@item eucalyptus
-A Eucalyptus instance (future development)
-@end table
-
-
-Once again, you must consult the libvirt documentation for details.
-
-@node Distinct states, Example deployment, Virtualization types supported, Top
-@unnumberedsec Distinct states
-@sp 1
-
-Libvirt recognizes a number of distinct states are transliterated into CFEngine
-as
-@table @code
-@item create
-Build and start an guest environment.
-@item delete
-Halt and remove runtime resources associated with an guest environment.
-@item running
-An existing guest environment is in a running state.
-@item suspended
-An existing guest environment is in a `paused' state.
-@item down
-An existing guest environment is in a halted state.
-@end table
-The default promised state is for a machine to be running
-wherever the @code{environment_host} class is true, and
-suspended or down elsewhere.
-
-
-
-@node Example deployment, Virtualized host examples, Distinct states, Top
-@unnumberedsec Example deployment
-@sp 1
-
-Prerequisites: you need to make a `disk image' for the machine, or a
-virtual disk of blocks that can be allocated. This image does not have to
-contain any data, it will simply as a block device for the VM. You
-can then install it by booting the machine from a network image, like a
-PXE/kickstart installation.
-
-If you want to allocate disk blocks as the file grows, you can create
-a file with a hole. The following command will creates a file of
-2048MB, but the actual data blocks are allocated in a lazy fashion:
-
-@verbatim
-
-# dd if=/dev/zero of=/srv/xen/my.img oflag=direct bs=1M seek=2047 count=1
-
-@end verbatim
-To reserve all the data blocks right away:
-@verbatim
-
-# dd if=/dev/zero of=/srv/xen/my.img oflag=direct bs=1M count=2048
-
-@end verbatim
-
-Libvirt uses an XML file format that cannot be circumvented. CFEngine
-promises to honour the promises that are expressed in this file, as in
-the examples above. You need to find out about this file format from
-the libvirt website. To get CFEngine to honour these promises, you
-point it to the specification that it should promise using
-@code{spec_file}.
-
-You need to set up a network for virtual machines to communicate with
-the outside world. This can also be done with CFEngine, using the
-network promise types to build a bridge into a virtual network.
-
-Then just run CFEngine to start, stop or manage the guest environments on
-each localhost. Run in verbose mode to see how CFEngine maintains the states
-convergently.
-@verbatim
-# cf-agent -v
-@end verbatim
-
-
-@appendix Virtualization Examples
-
-@node Virtualized host examples, Virtual network example, Example deployment, Top
-@unnumberedsec Virtualized host examples
-
-@verbatim
-
-#######################################################
-
-body common control
-{
-bundlesequence => {"my_vm_cloud"};
-}
-
-#######################################################
-
-bundle agent my_vm_cloud
-{
-guest_environments:
-
- linux::
-
- "bishwa-kvm1"
- comment => "Keep this vm suspended",
- environment_resources => myresources,
- environment_type => "kvm",
- environment_state => "suspended",
- environment_host => "ubuntu";
-
- "bishwa-kvm2"
-
- comment => "Keep this vm running",
- environment_resources => myresources,
- environment_type => "kvm",
- environment_state => "running",
- environment_host => "ubuntu";
-
- "bishwa-kvm3"
- comment => "Power down this VM",
- environment_resources => myresources,
- environment_type => "kvm",
- environment_state => "down",
- environment_host => "ubuntu";
-
- "bishwa-kvm4"
-
- comment => "Delete this VM",
- environment_resources => myresources,
- environment_type => "kvm",
- environment_state => "delete",
- environment_host => "ubuntu";
-
- "bishwa-kvm5"
- comment => "Keep this vm running",
- environment_resources => myresources,
- environment_type => "kvm",
- environment_state => "running",
- environment_host => "ubuntu";
-
-}
-
-
-#######################################################
-
-body environment_resources myresources
-{
-env_cpus => "2";
-#env_memory => "512"; # in KB
-#env_disk => "2048"; # in MB
-}
-
-
-@end verbatim
-
-
-@node Virtual network example, , Virtualized host examples, Top
-@unnumberedsec Virtual network example
-
-@verbatim
-
-body common control
-{
-bundlesequence => {"my_vm_cloud"};
-}
-
-#####################################################
-
-bundle agent my_vm_cloud
-{
-guest_environments:
-
-linux::
-
-"cfvrnet1"
-comment => "Create a virtual network from given xml file",
-environment_resources => virt_xml("$(this.promiser)"),
-environment_type => "kvm_net",
-environment_state => "create",
-environment_host => "ubuntu";
-}
-
-#####################################################
-body environment_resources virt_xml(name)
-{
-
- env_spec_file =>"
- "
-
- $(name)
-
-
-
-
-
-
-
-
- ";
-}
-
-@end verbatim
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/SpecialTopic_Vision.texinfo b/docs/guides/SpecialTopic_Vision.texinfo
deleted file mode 100644
index 9bb5e56faf..0000000000
--- a/docs/guides/SpecialTopic_Vision.texinfo
+++ /dev/null
@@ -1,273 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename st-vision.info
-@settitle Vision
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title The Vision
-@subtitle A CFEngine Special Topics Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-This is an internal note that intends to provide a quick summary of CFEngine
-concepts.
-
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2010 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Iteration:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@node Top
-@top Federation
-
-
-@end ifnottex
-
-@ifhtml
-@html
-
-@c end html
-@c @end ifhtml
-
-
-
-@c acls
-
-@c registry
-
-@c Event log
-
-@c policy sharing with Unix - bundles at least.
-
-@node System requirements, Installation, Top, Top
-@unnumberedsec System requirements
-@sp 1
-
-CFEngine Enterprise, being so lightweight, works equally well on Windows
-clients as on Windows servers. Both native 32-bit/x86 (package name
-@code{i686}) and 64-bit/x64 (package name @code{x86_64}) packages are
-available to customers. It is important that you select the
-@code{x86_64} package if you are running 64-bit Windows.
-
-Of Windows client operating systems, anything from Windows XP SP2 and
-newer is supported. On the server side, Windows Server 2003 and newer
-is supported.
-
-CFEngine Enterprise communicates bi-directionally on port @code{5308}, so
-make sure that this port is open for outgoing and incoming @code{TCP}
-connections.
-
-All software dependencies are bundled with the CFEngine Enterprise
-package. The total disk consumption is about 70 @code{MB}, and the
-memory usage is less than 30 @code{MB}.
-
-@node Installation, Testing policies locally, System requirements, Top
-@unnumberedsec Installation
-@sp 1
-
-The installation and set-up procedure on Windows is not different than
-that for other operating systems CFE Enterprise runs on, so the CFE Enterprise getting
-started document available at @url{http://software.cfengine.com}
-applies to the Windows version as well.
-
-The Windows @code{msi}-packages will get silently installed (no
-prompts) to @code{Cfengine} under your program files directory
-(e.g. @code{C:\Program Files\Cfengine} on English Windows
-versions). It is important that the installer is run with
-Administrative priviliges. To ensure this, open a @code{Command
-Prompt} in Administrative mode and run @samp{msiexec -i
-cfengine-nova-VERSION-ARCH.msi} (replace @code{VERSION} and
-@code{ARCH} appropriately).
-
-If you are just going to test your policies on a Windows host, it is
-more efficient to not bootstrap to a policy server, but run the
-policies locally just after you create them. You can install the license
-with the @code{cf-key -l} command -- you will need to copy over the
-licensed public key as advised by @code{cf-key -l}.@footnote{Avaliable
-in CFEngine Enterprise 3.0 and beyond. Run @code{cf-key -l
-C:\path\to\license.dat} and follow the instructions.}
-
-Eventually, when you are done testing and want to bootstrap a Windows
-host to a policy server, please run the following command (against a
-Linux-based policy server, as advised in the CFE Enterprise getting
-started document). If we assume the policy server's IP address is
-'123.456.789.123', you need to run the following command to bootstrap
-the Windows host.
-
-@verbatim
- C:\Program Files\Cfengine\bin\cf-agent.exe --bootstrap 123.456.789.123
-@end verbatim
-
-
-@node Testing policies locally, Windows registry management, Installation, Top
-@unnumberedsec Testing policies locally
-
-Create a new text file @code{Cfengine\inputs\promises.cf} and input
-the following text using your favourite text editor.
-
-@verbatim
-body common control
-{
-bundlesequence => { "test" };
-inputs => { "cfengine_stdlib.cf" };
-}
-
-bundle agent test
-{
-reports:
-windows::
- "Hello, Windows!";
-}
-@end verbatim
-
-Now, go to your terminal (e.g. Command Prompt) and navigate to
-@code{Cfengine\bin} under program files. Run @code{cf-promises.exe}. It
-should generate no output, which indicates correct syntax and license.
-
-To execute the policy, run @code{cf-agent.exe -K}. You should see the
-following output.
-
-@center @image{winhello,8cm,, Windows output,png}
-
-We now have a basic skeleton policy that we can test our Windows
-promises with. These can later be integrated at the policy hub to
-ensure that they are run on all Windows systems. We will assume this
-general skeleton for the rest of this document, modifying the contents
-of the @code{test} bundle only.
-
-
-@node Windows registry management, Windows service management, Testing policies locally, Top
-@unnumberedsec Windows registry management
-
-CFEngine Enterprise supports fine-grained management of the Windows
-registry. These promises are encapsulated under the @code{databases:}
-promise type.
-
-
-@unnumberedsubsec Creating values
-
-Let us modify our skeleton bundle to contain the following.
-
-@verbatim
-...
-bundle agent test
-{
-databases:
-
- "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog\Security"
-
- database_operation => "create",
- database_rows => { "MaxSize,REG_DWORD,84017152", "Retention,REG_DWORD,0"},
- database_type => "ms_registry",
- comment => "Ensure eventlog size is in accordance with standards";
-}
-@end verbatim
-
-Now, we again run @code{cf-promises.exe} to ensure the syntax is
-correct, followed by @code{cf-agent.exe -KI}. Note that we added the
-@code{-I} option which tells @code{cf-agent.exe} to notify us on the
-existing state of the system and any actions done to ensure the
-desired state. The output should look like the following.
-
-@center @image{winreg-create,13cm,,Windows registry create output,png}
-
-When we run @code{cf-agent.exe} twice, the second run will do nothing
-because the first run has already corrected the value. This is
-convergence --- CFEngine is ensuring the desired state.
-
-
-@unnumberedsubsec Removing values
-
-In order to remove values instead, we just need to adjust the policy
-slightly, resulting in the following bundle.
-
-@verbatim
-...
-bundle agent test
-{
-databases:
-
- "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog\Security"
-
- database_operation => "delete",
- database_columns => { "value1", "value2"},
- database_type => "ms_registry",
- comment => "Remove stray values generated by an application";
-}
-@end verbatim
-
-Now, if you create @samp{value1} and @samp{value2} in the key above,
-@code{cf-agent.exe} should show the following output.
-
-@center @image{winreg-delete,13cm,,Windows registry delete output,png}
-
-
-At the time of writing, CFE Enterprise supports the @code{REG_DWORD} (double
-word), @code{REG_SZ} (string) and @code{REG_EXPAND_SZ} (expandable
-string) data types, as given in the middle field of the
-@code{database_rows} list elements. See the
-@uref{http://cfengine.com/manuals/cf3-Reference.html#database_005frows-in-databases,CFEngine
-reference manual} for an updated list of supported data types.
-
-Also note the @code{registryvalue()} function which can be used to
-read out value data from the registry and act upon it. Examples of its
-use are also available in the
-@uref{http://cfengine.com/manuals/cf3-Reference.html#Function-registryvalue,CFEngine
-reference manual}.
-
-
-@node Windows service management, File and folder permissions, Windows registry management, Top
-@unnumberedsec Windows service management
-
-CFEngine Enterprise can maintain complete control of the state of all
-Windows services. For example, services prone to security issues or
-errors can easily be given a disabled state.
-
-@center @image{winservice-disabled_policy,8cm,,Disabled Windows service,png}
-
-A service can also be given a running state, in which case CFEngine
-Enterprise ensures that it is running, and starts it if it is not, with
-parameters if desired. More advanced policy options are also
-available, including support for starting and stopping dependencies,
-and configuring when the services should be started (e.g. only when
-they are being used).
-
-Note that the name of a service in Windows may be different from its
-``Display name''. CFEngine Enterprise policies use the name, not the display
-name, due to the need of uniqueness.
-
-@center @image{winservice-properties_name,7cm,,Windows service name and Display name,png}
-
-A complete example of a service management bundle is show below.
-
-@verbatim
-...
-bundle agent test
-{
-services:
-
-windows::
- "W32Time"
- service_policy => "start",
- service_method => bootstart,
- comment => "Ensure important services are running and starting at boot";
-
-Windows_Server_2008::
- "RemoteRegistry"
- service_policy => "disable",
- service_method => force_deps,
- comment => "Disable services that create security issues";
-
-}
-@end verbatim
-
-This example ensures that the Windows Time service is running on all
-Windows hosts, and that Remote registry is disabled on all Windows
-2008 servers.
-
-
-@node File and folder permissions, Windows-aware features in CFE Enterprise, Windows service management, Top
-@unnumberedsec File and folder permissions
-
-CFEngine Enterprise can ensure the permissions or Access Control Lists
-(@code{ACLs}) of your Windows systems are correctly set. Windows
-@code{ACLs} are a complex topic by itself, with support for more than
-ten different permission bits and inheritance. CFE Enterprise supports all of
-this, but we will just cover the basics in this document.
-
-The following policy will ensure strict permissions on a directory
-@samp{C:\Secret} and a file @samp{C:\Secret\file.txt}.
-
-@verbatim
-...
-
-bundle agent test
-{
-vars:
- "acl_secret_dir" slist => { "user:Administrator:rwx:allow",
- "group:Administrators:rx:allow" };
- "acl_secret_file" slist => { "user:Administrator:rw:allow" };
-
-files:
-
-windows::
- "C:\Secret",
- acl => ntfs( "@(acl_secret_dir)" ),
- depth_search => include_base,
- perms => owner( "Administrator" );
-
- "C:\Secret\file.txt",
- acl => ntfs( "@(acl_secret_file)" ),
- perms => owner( "Administrator" );
-}
-@end verbatim
-
-The @uref{http://cfengine.com/manuals/cf3-Reference.html#acl-in-files,
-CFEngine reference manual} contains a description of all the available
-@code{ACL} options. Also refer to the the CFEngine Enterprise Owner's manual
-for a more in-depth discussion of the @code{ACL} options available.
-
-@node Windows-aware features in CFE Enterprise, Windows special variables, File and folder permissions, Top
-@unnumberedsec Windows-aware features in CFE Enterprise
-
-CFEngine Enterprise integrates with the Windows operating system in multiple
-ways.
-
-The CFEngine scheduler in CFE Enterprise (@code{cf-execd}) runs as a Windows
-service. This means it runs in the background and starts with Windows,
-before any user logs in. It can be configured, started and stopped
-from the ``Services'' listing in Windows, just like any other Windows
-service.
-
-Event logs are the Windows counterpart to syslog from Unix. The main
-difference is that event logs aim to group similar log messages,
-giving each group an event id. The following event ids are defined in
-CFEngine Enterprise, allowing categorisation of the log message based on its
-type. The CFE Enterprise event logs can be found under the ``System'' logs.
-
-@multitable @columnfractions .4 .2 .2
-@headitem Description @tab Event ID @tab Type
-@item Promise kept @tab 100 @tab Information
-@item Promise repaired @tab 101 @tab Information
-@item Promise not repaired due warn only policy @tab 102 @tab Error
-@item Promise not repaired due to error @tab 103 @tab Error
-@item Report promise @tab 104 @tab Information
-@item Generic information @tab 105 @tab Information
-@item Generic verbose @tab 106 @tab Information
-@item Generic warning @tab 107 @tab Warning
-@item Generic error @tab 108 @tab Error
-@end multitable
-
-@center @image{winevent-notkept-storage,10cm,,Promise not kept in Event Viewer,png}
-
-By default, only promise not repaired and generic error events are
-logged to avoid flooding the Event Log. You can turn on verbose
-logging to log all messages, like the following example.
-
-
-@verbatim
-
-body common control
-{
-inputs => { "cfengine_stdlib.cf" };
-bundlesequence => { "main" };
-}
-
-bundle agent main
-{
-files:
-"C:\test.txt"
- create => "true",
- action => log_verbose;
-}
-
-@end verbatim
-
-@node Windows special variables, Windows hard classes, Windows-aware features in CFE Enterprise, Top
-@unnumberedsec Windows special variables
-Three new special variables have been added to the Windows version of
-CFEngine Enterprise.
-
-@itemize
-
-@item @code{sys.windir} contains the Windows directory,
-e.g. ``C:\WINDOWS''.
-
-@item @code{sys.winsysdir} contains the Windows system directory,
-e.g. ``C:\WINDOWS\system32''.
-
-@item @code{sys.winprogdir} contains the program files directory,
-e.g. ``C:\Program Files''.
-
-@end itemize
-
-Note that these variables are not statically coded, but retrieved from
-the current system. For example, @code{sys.winprogdir} is often
-different on Windows versions in distinct languages.
-
-
-@node Windows hard classes, Notes on windows policies, Windows special variables, Top
-@unnumberedsec Windows hard classes
-The Windows version of CFEngine Enterprise defines hard classes to pinpoint
-the exact version of Windows that it is running on, the service pack
-version and if it's a server or workstation.
-
-First of all, the class @code{windows} is defined on all Windows
-platforms. For Windows workstations, such as Windows XP,
-@code{WinWorkstation} is defined. On Windows servers, such as Windows
-Server 2003, @code{WinServer} is defined. In addition, if the server
-is a domain controller, @code{DomainController} is defined. Note that
-if @code{DomainController} is defined, then @code{WinServer} is also
-defined, for natural reasons.
-
-The class @code{Service_Pack_X_Y} is defined according to the service
-pack version. For example, at the time of writing,
-@code{Service_Pack_3_0} is set on an updated Windows XP operating
-system.
-
-To allow taking specific actions on different Windows versions, one
-of the following hard classes is defined.
-
-@itemize
-@item @code{Windows_7}
-@item @code{Windows_Server_2008_R2}
-@item @code{Windows_Server_2008}
-@item @code{Windows_Vista}
-@item @code{Windows_Server_2003_R2}
-@item @code{Windows_Home_Server}
-@item @code{Windows_Server_2003}
-@item @code{Windows_XP_Professional_x64_Edition}
-@item @code{Windows_XP}
-@item @code{Windows_2000}
-@end itemize
-
-Note that all defined hard classes for a given system is shown by
-running @code{cf-promises -v}.
-
-
-@node Notes on windows policies, , Windows hard classes, Top
-@unnumberedsec Notes on windows policies
-A potential problem source when writing policies for windows is that
-paths to executables often contain spaces. This makes it impossible
-for CFEngine to know where the executable ends and the parameters to
-it starts. To solve this, we place escaped quotes around the
-executable. Windows share paths (double backslashes) also need
-escaping.
-
-Additionally, Windows does not support that processes start themselves
-in in the background (i.e. fork off a child process in the Unix
-world). The result is that CFEngine is always waiting for the commands
-to finish execution before checking the next promise. To avoid this,
-use the background attribute in the action body-part.
-
-Both these things are demonstrated in the following example.
-
-@verbatim
-
-body common control
-{
-inputs => { "cfengine_stdlib.cf" };
-bundlesequence => { "main" };
-}
-
-bundle agent main
-{
-commands:
-
-"\"C:\Program Files\Some Dir\program name.bat\" --silent --batch"
- action => in_shell_bg;
-
-"\"\\\\computer\share path\my program.exe\" /some args";
-}
-
-@end verbatim
-
-Finally, one should note that Windows lacks support for certain
-features that are utilised in Unix versions of CFEngine. These include
-symbolic links, file groups, user and group identifiers.
-
-Thus, the parts of promises containing these features will be
-ignored. For example, the @code{getgid()} function does not return
-anything on Windows. The
-@uref{http://cfengine.com/manuals/cf3-Reference.html,CFEngine
-reference manual} documents exactly which promises are ignored and
-not. Also, @code{cf-agent.exe} from CFEngine Enterprise prints warning messages
-on ignored attributes when run in verbose mode (@code{cf-agent.exe -Kv}).
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/agility.png b/docs/guides/agility.png
deleted file mode 100644
index 9559037e0c..0000000000
Binary files a/docs/guides/agility.png and /dev/null differ
diff --git a/docs/guides/arch.png b/docs/guides/arch.png
deleted file mode 100644
index 4655faa541..0000000000
Binary files a/docs/guides/arch.png and /dev/null differ
diff --git a/docs/guides/body_bundle.png b/docs/guides/body_bundle.png
deleted file mode 100644
index 79bdfdce61..0000000000
Binary files a/docs/guides/body_bundle.png and /dev/null differ
diff --git a/docs/guides/boxes.png b/docs/guides/boxes.png
deleted file mode 100644
index b79075443b..0000000000
Binary files a/docs/guides/boxes.png and /dev/null differ
diff --git a/docs/guides/brainbrawn.png b/docs/guides/brainbrawn.png
deleted file mode 100644
index 1cc2e06263..0000000000
Binary files a/docs/guides/brainbrawn.png and /dev/null differ
diff --git a/docs/guides/bval.png b/docs/guides/bval.png
deleted file mode 100644
index fdbcebc8b1..0000000000
Binary files a/docs/guides/bval.png and /dev/null differ
diff --git a/docs/guides/cdp_reports_generate.png b/docs/guides/cdp_reports_generate.png
deleted file mode 100644
index f4c21ab38b..0000000000
Binary files a/docs/guides/cdp_reports_generate.png and /dev/null differ
diff --git a/docs/guides/cdp_services_report.png b/docs/guides/cdp_services_report.png
deleted file mode 100644
index b38974f820..0000000000
Binary files a/docs/guides/cdp_services_report.png and /dev/null differ
diff --git a/docs/guides/central_pull.png b/docs/guides/central_pull.png
deleted file mode 100644
index 01a1d00fa6..0000000000
Binary files a/docs/guides/central_pull.png and /dev/null differ
diff --git a/docs/guides/central_push.png b/docs/guides/central_push.png
deleted file mode 100644
index 2139f1ed73..0000000000
Binary files a/docs/guides/central_push.png and /dev/null differ
diff --git a/docs/guides/cf-Compliance.texinfo b/docs/guides/cf-Compliance.texinfo
deleted file mode 100644
index 06bcf36b66..0000000000
--- a/docs/guides/cf-Compliance.texinfo
+++ /dev/null
@@ -1,123 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{NewLogo}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename cf-Compliance.info
-@settitle Compliance management using cfengine
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Compliance management using CFEngine
-@subtitle A CFEngine AS workbork
-@author CFEngine.com
-
-@c @smallbook
-
-@page
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2008 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@node Top, ISO standards and International Law, (dir), (dir)
-@top CFEngine-Modularization
-@end ifnottex
-
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@c **********************************************************************
-@c CHAPTER
-@c **********************************************************************
-
-
-@menu
-* Best practices::
-* The Promise Matrix::
-* Things to remember when writing promises::
-@end menu
-
-@c **********************************************************************
-@node Best practices, The Promise Matrix, Top, Top
-@chapter Best practices
-
-Who decides best practice? Who gets to say what is best for whom and
-under what circumstances? In many cases this is an ad hoc individual,
-or perhaps (worse) a committee, more concerned with concensus building
-that practicality.
-
-We would like to begin by saying that we don't believe in the concept
-of @i{best} practice, however perhaps we can refer to Pretty Good
-Practice, i.e. Useful Experience. That is the spirit in which we present our
-thoughts in this document.
-
-@c **********************************************************************
-@node The Promise Matrix, Things to remember when writing promises, Best practices, Top
-@chapter The Promise Matrix
-
-Let us oversimplify just a little to describe what we believe is the basic
-problem.
-
-The management of a distributed system can be thought of as the
-population of a matrix (table) of `things to do' versus `where to do
-them', i.e. on which machines to execute which processes. This
-matrix is what is sometimes referred to as orchestration, or choreography:
-
-@image{matrix1,12cm,,The Matrix,png}
-
-The CFEngine version of this is more general and more powerful. To
-begin with, we describe promises which are not just tasks, but
-maintainance processes. Then, instead of individual machines, we are
-able to put together any kind of (possibly overlapping) set of
-machines into a `class'.
-
-@image{matrix2,12cm,,The Matrix,png}
-
-@menu
-* Avoid hierarchical arrangements::
-* Defining effective classes::
-* Classifying machines::
-* Bundling under a class::
-@end menu
-
-@node Avoid hierarchical arrangements, Defining effective classes, The Promise Matrix, The Promise Matrix
-@section Avoid hierarchical arrangements
-
-Hierarchies are a bad way to model organizations. Even though history
-has favoured hierarchical organization, almost no real organization is
-trul hierarchical. Indeed, strict hierarchies tend to fail in most
-cases because they force things into a tree of isolated
-leaf-categories. Networks (like the internet) are successful because
-they can branch like trees, but allow cross connected and overlapping
-membership of categories.
-
-Our first advice is:
-
-@itemize
-@item Create the classes that you need to represent your organization.
-
-Put out of your mind all thoughs about hierarchy and Object
-Orientation. If they are natural, they will emerge by themselves. If
-they are not, they will just get in your way. If you try to be strict
-in categorization, you will just end up making more exceptions to the
-rule than the rule itself.
-
-@item Use many classes with descriptive names.
-
-This is how you model and understand cooperation in your organization.
-
-@end itemize
-
-Many clients have a significant fraction of their total configuration
-dedicated to defining appropriate classes.
-
-
-@node Defining effective classes, Classifying machines, Avoid hierarchical arrangements, The Promise Matrix
-@section Defining effective classes
-
-One idea for best practice is this: we want to make the smallest
-number of classes that cover an organization. This sounds like a nice
-obsessive-compulsion for optimization, and it appeals to nit-pickers;
-however we advise against exessive optimization. Comfort and pedagogy
-are more important characteristics to nurture.
-
-@enumerate
-
-@item The main thing we want to avoid is having to maintain the same
-information in many locations. If we can, we would like to have a
-little raw information and use logic and @i{reasoning} to derive
-classes from these. Fortunately CFEngine does a lot of reasoning in
-advance, providing you with a rich list of classes on which to base
-decisions.
-
-@item Remember also that you can define your own classes by testing the
-system with functions like @code{fileexists()}, @code{filesexist},
-@code{hashmatch()}, etc., which detect conformance with particular
-patterns.
-
-@item A lot of information is contained in lists. Make use of existing
-lists in databases like NIS, LDAP and SQL databases. The may be accessed
-by special functions like @code{ldaplist}, @code{hostinnetgroup}.
-
-@item There are two strategies to making lists, much like `allow' and `deny'
-strategies in access control security.
-
-@itemize
-@item Specify the individual entities.
-@item Specify the exceptions to a general rule.
-@end itemize
-
-There are general classes (all encompassing) like @samp{any}, and @samp{solaris}.
-Then there are specific classes like the name of a host, or the IP address.
-
-@end enumerate
-
-
-@node Classifying machines, Bundling under a class, Defining effective classes, The Promise Matrix
-@section Classifying machines
-
-There are different approaches to classifying machines:
-
-@itemize
-@item By IP address, or subnet.
-
-This seems simple but does not easily capture today's distributed organizations.
-
-@item By netgroup or LDAP list.
-
-This has the advantage of being managed by a specialist in the organization, so it
-makes use of knowledge about the organization.
-
-@end itemize
-
-
-@node Bundling under a class, , Classifying machines, The Promise Matrix
-@section Bundling under a class -- making use of patterns
-
-
-CFEngine's ability to define methods based on parameterized bundles of
-code is a powerful way to reduce the total number of specific promises
-into generic patters. Whenever possible, we recommend writing
-generic promises and re-using them by iterating over lists,
-or applying parameter sets to different classes, e.g.
-
-@verbatim
-
- domain_01::
-
- "dep1" slist => { "c:\WINDOWS\system32\msiexec.exe" };
-
- "dep2" slist => { "c:\WINDOWS\system32\msiexec.exe", "c:\Program Files\cf_dummy1" };
-
- "dep3" slist => { "c:\WINDOWS\system32\msiexec.exe", "c:\Program Files\cf_dummy1", "c:\Program Files\cf_dummy2" };
-
-
- domain_02::
-
- "dep1" slist => { "c:\WINDOWS\system32\msiexec.exe" };
-
- "dep2" slist => { "c:\WINDOWS\system32\msiexec.exe", "c:\Program Files\cf_dummy2" };
-
-methods:
-
- # perform the actual installation with dependency checking
-
- domain_01::
-
- "any" usebundle => install_software("cf_dummy1.msi","cf_dummy1",@(Trial1.dep1));
- "any" usebundle => install_software("cf_dummy2.msi","cf_dummy2",@(Trial1.dep2));
- "any" usebundle => install_software("cf_dummy3.msi","cf_dummy3",@(Trial1.dep3));
-
- domain_02::
-
- "any" usebundle => install_software("cf_dummy2.msi","cf_dummy2",@(Trial1.dep1));
- "any" usebundle => install_software("cf_dummy1.msi","cf_dummy1",@(Trial1.dep2));
-
-@end verbatim
-
-
-@c **********************************************************************
-@node Things to remember when writing promises, , The Promise Matrix, Top
-@chapter Things to remember when writing promises
-
-
-
-
-When writing promises, get into the habit of giving every promise a comment
-that explains its intention.
-
-Also, give related promises @i{handles}, or labels that can be used to
-refer to them by.
-
-@verbatim
-
-files:
-
- "/var/cfengine/inputs"
-
- handle => "update_policy",
-
- perms => system("600"),
- copy_from => mycopy("$(master_location)","$(policy_server)"),
- depth_search => recurse("inf"),
- file_select => input_files,
- action => immediate;
-
-@end verbatim
-If a promise affects another promise in some way, you can make the affected
-promise one of the promisees, like this:
-
-@verbatim
-
-access:
-
- "/master/CFEngine/inputs" -> { "update_policy", "other_promisee" },
-
- handle => "serve_updates",
-
- admit => { "217.77.34.*" };
-
-@end verbatim
-
-Conversely, if a promise might depend on another in some (even indirect) way, document this too.
-
-@verbatim
-
-files:
-
- "/var/cfengine/inputs"
-
- handle => "update_policy",
- depends_on => {"serve_updates"},
-
- perms => system("600"),
- copy_from => mycopy("$(master_location)","$(policy_server)"),
- depth_search => recurse("inf"),
- file_select => input_files,
- action => immediate;
-
-
-@end verbatim
-
-Get into the habit of adding the cause-effect lines of influence.
-Enterprise editions of CFEngine will track the dependencies between these
-promises and map out impact analyses.
-
-
-@c =========================================================================
-@c @node Index, , CFEngine Methods, Top
-@c @unnumbered Concept Index
-@c @printindex cp
-@c =========================================================================
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@contents
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/cf-copernicus.texinfo b/docs/guides/cf-copernicus.texinfo
deleted file mode 100644
index f97246049a..0000000000
--- a/docs/guides/cf-copernicus.texinfo
+++ /dev/null
@@ -1,258 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{NewLogo}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename cf-copernicus.info
-@settitle Copernicus Hints
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Copernicus Hints
-@subtitle A CFEngine AS reference
-@author CFEngine AS
-
-@c @smallbook
-
-
-@page
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2008 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-@ifnottex
-@node Top, Introduction, (dir), (dir)
-@top CFEngine-Reference
-@end ifnottex
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@c **********************************************************************
-@c CHAPTER
-@c **********************************************************************
-
-@menu
-* Introduction::
-* The content::
-* Graphs::
-* Improve Copernicus::
-@end menu
-
-@node Introduction, The content, Top, Top
-@chapter Introduction
-
-
-Copernicus is CFEngine's knowledge integration tool, proving
-semantically linked access to our extended documentation for support
-customers. Copernicus is really just CFEngine 3 in disguise. The
-website is powered by CFEngine 3's knowledge agent @code{cf-know}. Only
-the content is proprietary -- and even then we encourage you to
-help develop it by sending us suggestions for improvement.
-
-Copernicus was made famous for his heliocentric view of the
-universe, placing the sun at the centre and seeing the
-planets orbit around it.
-
-@image{copernicus-planets,10cm,,The heliocentric solar system,png}
-
-CFEngine's Copernicus is a simplified implentation of ISO standard
-Topic Maps, in which every page is based around a topic. It places
-a given topic of interest in the centre of focus and shows what other
-concepts are closely related to it. Just click on a concept to see
-how it relates to nearby concepts and to find references to the
-documentation.
-
-The best way to use the topic map is simply to explore for a while
-and use the search field to short-cut to relevant topics.
-
-@itemize
-@item Orange links point to concepts
-@item Red links point to documents.
-@end itemize
-
-@c **********************************************************************
-@c CHAPTER
-@c **********************************************************************
-
-@node The content, Graphs, Introduction, Top
-@chapter The content
-
-@menu
-* Topics::
-* Types::
-* Associations::
-* Occurrences::
-* Searching::
-@end menu
-
-@node Topics, Types, The content, The content
-@section Topics
-
-A topic is any subject that we want to talk about or represent.
-
-Strictly speaking, the term topic refers to the object or node in
-the topic map that represents the subject being referred to. However,
-there is a one-to-one relationship between topics and
-subjects, with every topic representing a single subject and every
-subject being represented by just one topic. To a certain degree,
-therefore, the two terms can be used interchangeably
-
-@image{NewCopernicus,10cm,,A typical topic page,png}
-
-@node Types, Associations, Topics, The content
-@section Types
-
-Topics can be categorized according to their type. In a topic map, any
-given topic is an instance of zero or more topic types. This
-corresponds to the categorization inherent in the use of multiple
-indexes in a book (index of names, index of works, index of places,
-etc.).
-
-Types are used mainly to disambiguate topics of the same namin
-different contexts.
-
-@node Associations, Occurrences, Types, The content
-@section Associations
-
-
-An association is a semantic relationship between two topics.
-The associative distance between topics is what defines the
-solar system of a topic in Copernicus. Associations are what
-links ideas together in the knowledge base, e.g.
-
-@smallexample
-is implemented by
-is an example of
-is an aspect/component of
-was a feature added in
-@end smallexample
-
-
-@node Occurrences, Searching, Associations, The content
-@section Occurrences
-
-An occurrence of a topic is a piece of information about
-it. This is normally the reason for using the topic map
-in the first place -- to arrive at an actual document, or
-occurrence of the topic. In CFEngine occurrences can be
-short literal explanations, or the can be red URL pointers
-to documentation.
-
-An occurrence pointer will lead you some some text that
-says something about the topic.
-
-@node Searching, , Occurrences, The content
-@section Searching
-
-The search field at the top right hand corner of the header may be
-used to enter Perl Compatible Regular Expressions to match topic name
-fragments. Searches are case insensitive. Do not enter more than one
-keyword at a time, the expression should match only a single name,
-e.g.
-
-@smallexample
-web
-web server
-web.*module.*
-apache
-@end smallexample
-
-@c **********************************************************************
-@c CHAPTER
-@c **********************************************************************
-
-@node Graphs, Improve Copernicus, The content, Top
-@chapter Graphs
-
-Copernicus provides some graphical representations of topic space,
-showing approximately 30 of the closest related topics. This magic
-number 30 is one of the Dunbar numbers and represents the number of
-working relationships humans can typically maintain.
-
-@image{NewCopernicusGraph,10cm,,A graphical view of related topics,png}
-
-
-The graphics are not a complete represenation of the topic map but
-are designed to provoke associative thought. You can reach all of
-the links by going to the Associations section of a topic page (assuming
-there are associations).
-
-The graphical aspects of copernicus are being developed as part of our
-research into knowledge management. Users can expect future
-improvements to the analysis and navigation features.
-
-
-@node Improve Copernicus, , Graphs, Top
-@chapter Improve Copernicus
-
-Entering the expert knowledge in Copernicus is a huge and
-time-consuming task. Help us to improve the knowledge base by sending
-us your wishes and suggestions. Every `stupid question' and smart
-lateral thought that you send us can help someone to find what they
-need more quickly.
-
-We are constantly researching and analysing the data we have and
-the patterns of usage we observe. All of this will lead to
-a more sophisticated experience in the coming years.
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@contents
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
diff --git a/docs/guides/cf3-bestpractice.texinfo b/docs/guides/cf3-bestpractice.texinfo
deleted file mode 100644
index 72cc67ad8a..0000000000
--- a/docs/guides/cf3-bestpractice.texinfo
+++ /dev/null
@@ -1,1455 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename cf3-bestpractice.info
-@settitle CFEngine 3 Best Practices
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title CFEngine 3 Best Practices
-@subtitle A CFEngine Handbook
-@author CFEngine AS
-
-@c @smallbook
-
-
-@page
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2008- CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@node Top, Policy Style Guide, (dir), (dir)
-@top CFEngine-Best-Practices
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@c **********************************************************************
-@c CHAPTER
-@c **********************************************************************
-
-@menu
-* Policy Style Guide::
-* Policy Dos and Don'ts::
-* Common Workflows ::
-* Quality Assurance around CFEngine::
-@end menu
-
-
-@c **********************************************************************
-
-@node Policy Style Guide, Policy Dos and Don'ts, Top, Top
-@chapter Policy Style Guide
-
-@c ....................................
-@menu
-* Arranging files::
-* Where to define variables and classes::
-* How to choose and name bundles::
-* How to decide when to make a bundle::
-* When to use a paramaterized bundle or method ::
-* When should classes be in common bundles::
-* When should variables be in common bundles::
-* When should variables be in local bundles::
-@end menu
-
-@node Arranging files, Where to define variables and classes, Policy Style Guide, Policy Style Guide
-@section Arranging files
-
-Base your files on high level services as you do with bundles,
-@xref{How to choose and name bundles}. The purpose of breaking up
-policy into files is to limit the scope of the policy to manageable
-amounts, making it easier to understand. It will only be easier to
-understand if the casual user can immediately locate promises from the
-name of the file.
-
-You can place related files in subdirectories of the inputs to localize them.
-This also makes updating more efficient, as fewer objects need to be
-checked.
-
-@cartouche
-The Enterprise Knowledge base allows you to search for
-promises, but everything will make more sense if promises are found in
-an intuitive place.
-@end cartouche
-
-@node Where to define variables and classes, How to choose and name bundles, Arranging files, Policy Style Guide
-@section Where to define variables and classes
-
-@cartouche
-Note that all CFEngine variables are globally accessable, by using their
-fully qualified name :@code{$(bundle.variable)}, or @code{@@(bundle.variable)},
-so placing variables in one place or another does not affect their accessability.
-@end cartouche
-
-Variables should be defined as close to the place where they are used as possible.
-The user will expect to find variables defined:
-
-@itemize
-@item In the current bundle, first and foremost.
-@item In some common bundle for generic, global data.
-@end itemize
-
-@noindent Variables that define global aspects of configuration, e.g.
-
-@itemize
-@item Well known path names, e.g. document root.
-@item Site specific data, e.g. the email address of the support unit.
-@end itemize
-@noindent can be defined in @code{common} bundles. This places them
-in a neutral context.
-
-The only reason to define a variable far from its place of use would
-be when writing generically re-usable methods and passing data as
-parameters, @xref{When to use a paramaterized bundle or method}.
-However, re-usability can make rules harder to understand.
-
-@node How to choose and name bundles, How to decide when to make a bundle, Where to define variables and classes, Policy Style Guide
-@section How to choose and name bundles
-
-Use the name of a bundle to represent a meaningful aspect of system adminstration,
-We recommend using a two or three-part name, that explains the context, general subject heading and
-special instance. Names should be service oriented and should guide non-experts to understand
-what they are about.
-e.g.
-@itemize
-@item app_mail_postfix
-@item app_mail_mailman
-@item app_web_apache
-@item app_web_squid
-@item app_web_php
-@item app_db_mysql
-@item garbage_collection
-@item security_check_files
-@item security_check_processes
-@item system_name_resolution
-@item system_xinetd
-@item system_root_password
-@item system_processes
-@item system_files
-@item win_active_directory
-@item win_registry
-@item win_services
-@end itemize
-
-@node How to decide when to make a bundle, When to use a paramaterized bundle or method , How to choose and name bundles, Policy Style Guide
-@section How to decide when to make a bundle
-
-Put things into a single bundle if:
-@itemize
-@item They belong to the same conceptual aspect of system administration.
-@item They do not need to be switched on or off independently.
-@end itemize
-
-
-Put things into different bundles if:
-
-@itemize
-@item All of the promises in one bundle need to the checked
-before all of the promises in another bundle.
-
-@item You need to re-use the promises with different parameters.
-@end itemize
-
-In general, keep the number of bundles to a minimum.
-This is a knowledge management issue. Clarity comes from differentiation,
-but only if the number of things is small.
-
-
-
-
-@node When to use a paramaterized bundle or method , When should classes be in common bundles, How to decide when to make a bundle, Policy Style Guide
-@section When to use a paramaterized bundle or method
-
-If you need to arrange for a @i{managed convergent collection} or
-@i{sequence} of promises that will occur for a list of (multiple) names or
-promisers, then use a bundle to simplify the code.
-
-Write the promises, which may or may not be ordered, using a parameter for the
-different names, then call the method passing the list of names as a parameter
-to reduce the amount of code.
-
-@smallexample
-
-bundle agent testbundle
-@{
-vars:
-
- "userlist" slist => @{ "mark", "jeang", "jonhenrik", "thomas", "eben" @};
-
-methods:
-
- "any" @b{usebundle => subtest("$(userlist)")};
-
-@}
-
-###########################################
-
-bundle agent subtest(@b{user})
-
-@{
-commands:
-
- "/bin/echo Fix @b{$(user)}";
-
-files:
-
- "/home/@b{$(user)}/."
-
- create => "true";
-
-reports:
-
- linux::
-
- "Finished doing stuff for @b{$(user)}";
-@}
-
-@end smallexample
-
-
-
-@node When should classes be in common bundles, When should variables be in common bundles, When to use a paramaterized bundle or method , Policy Style Guide
-@section When should classes be in @code{common} bundles?
-
-@itemize
-@item When you need to use them in multiple bundles (because classes defined
-in @code{common} bundles have global scope).
-@end itemize
-
-@cartouche
-
-Note, if you are converting from CFEngine 2 you should know the following.
-In CFEngine 2, all classes were global and it was common to define all classes
-in a big unmanageable list. That meant that there was a chance of
-class name collisions. CFEngine 3 has both local and global classes, allowing you
-to limit the scope of classes and define them more in context.
-
-@end cartouche
-
-@node When should variables be in common bundles, When should variables be in local bundles, When should classes be in common bundles, Policy Style Guide
-@section When should variables be in @code{common} bundles?
-
-@itemize
-@item For rationality, if the variable does not belong to any particular
-bundle, because it is used elsewhere.
-(Qualified variable names e.g. @code{$(mybundle.myname)}are always
-globally accessible, so this is a cosmetic issue.)
-@end itemize
-
-@node When should variables be in local bundles, , When should variables be in common bundles, Policy Style Guide
-@section When should variables be in local bundles?
-
-@itemize
-@item If they are not needed outside the bundles.
-@item If they are used for iteration (without qualified scope).
-@item If they are tied to a specific aspect of system maintenance represented
-by the bundle, so that accessing @code{$(bundle.var)} adds clarity.
-@end itemize
-
-@c **********************************************************************
-@c CHAPTER
-@c **********************************************************************
-
-@node Policy Dos and Don'ts, Common Workflows , Policy Style Guide, Top
-@chapter Policy Dos and Don'ts
-
-This chapter lists a number of recommended practices.
-
-
-
-@menu
-* Never do::
-* Avoid::
-* Recommended::
-* Always do::
-@end menu
-
-@node Never do, Avoid, Policy Dos and Don'ts, Policy Dos and Don'ts
-@section Never do
-
-@menu
-* Never change system policy when humans are absent::
-* Never embed simple shell commands::
-* Never manage more than one cron job::
-@end menu
-
-
-@node Never change system policy when humans are absent, Never embed simple shell commands, Never do, Never do
-@subsection Never change system policy when humans are absent
-
-Never make system changes when humans are unavailable, e.g. just before
-going offline for the weekend. No matter how careful you have been, mistakes
-can be made and you need to have at least 24 hours experience with a running
-policy to lend it your trust.
-
-
-
-@node Never embed simple shell commands, Never manage more than one cron job, Never change system policy when humans are absent, Never do
-@subsection Never embed simple shell commands
-
-
-Do not embed simple shell commands with CFEngine @code{commands} promises, like this:
-
-@smallexample
-
-commands:
-
- # Don't do this!
-
- "/bin/rm -r /tmp/xyz*";
- "/bin/mkdir /tmp/abcd";
-
-@end smallexample
-
-@b{WHY?} Embedded shell commands like this cannot be managed by CFEngine,
-so none of the protections that CFEngine offers can be applied to the process.
-Moreover, this starts a new process, adding to the burden on the system.
-
-Most importantly, this approach works like a covert channel, making changes
-that are not directly visible to CFEngine.
-
-
-@node Never manage more than one cron job, , Never embed simple shell commands, Never do
-@subsection Never manage more than one cron job
-
-When you run CFEngine, there is no reason to maintain separate cron
-jobs. Instead, use CFEngine's time classes to work like a user
-interface for cron. This allows you to have a single, central
-CFEngine file which contains all the cron jobs on your system without
-losing any of the fine control which cron affords you. All of the
-usual advantages apply:
-@itemize @bullet
-
-@item
-It is easier to keep track of what cron jobs are running on the
-system when you have everything in one place.
-
-@item
-You can use all of your carefully crafted groups and user-defined
-classes to identify which host should run which programs.
-@end itemize
-
-@b{WHY?} This gives you a single point of definition for batch jobs.
-It encapsulates jobs under CFEngine's tutelage, for improved control
-and security. Finally, CFEngine can collate and summarize the outputs
-from multiple scripts in a rational monitoring process.
-
-
-
-@c **********************************************************************
-@node Avoid, Recommended, Never do, Policy Dos and Don'ts
-@section Avoid
-
-@menu
-* Avoid writing custom scripts::
-* Avoid running CFEngine without lock protection::
-@end menu
-
-@node Avoid writing custom scripts, Avoid running CFEngine without lock protection, Avoid, Avoid
-@subsection Avoid writing custom scripts
-
-Do not spend your time writing scripts to embed within CFEngine. If
-you are doing this, you are not using the potential of CFEngine and
-you are not benefitting from the protections and efficiencies that
-CFEngine offers. Custom scripts should be for your specific business
-operations, not for system maintenance.
-
-If you are tempted to use scripts to achieve your needs, consider
-using @code{methods}, and if necessary consult with support personnel
-for advice.
-
-
-@node Avoid running CFEngine without lock protection, , Avoid writing custom scripts, Avoid
-@subsection avoid running CFEngine without lock protection
-
-CFEngine's adaptive locking is an important system protection. You
-should not run CFEngine continuously without this protection, e.g. by
-running with the @samp{-K} flag set, of by setting @code{ifelapsed} to
-zero for a promise.
-
-@b{WHY?} System inconsistencies can result and unnecessary resources
-will be consumed.
-
-
-
-@c **********************************************************************
-@node Recommended, Always do, Avoid, Policy Dos and Don'ts
-@section Recommended (Try to)
-
-@menu
-* Try to combine tests and operations during file searches::
-* Try to make many small changes::
-@end menu
-
-@node Try to combine tests and operations during file searches, Try to make many small changes, Recommended, Recommended
-@subsection Try to combine tests and operations during file searches
-
-Searching through files on a disk is one of the most time consuming
-operations for a computer. If you have to do it, make sure that
-you are getting the most for your CPU-cycles and combine operations
-in a single promise. This allows CFEngine to optimize the resource use
-of the system.
-
-@smallexample
-
-files:
-
- "$(site)/app/webroot/img/inside/extmans"
- comment => "Copy the images for the private html documents",
-@b{ copy_from => cp("$(kbase)"),
- perms => p("root","644"),
- file_select => by_name(".*.png"),
- depth_search => recurse("1"),}
- action => ifelapsed("60");
-
-@end smallexample
-
-
-
-@node Try to make many small changes, , Try to combine tests and operations during file searches, Recommended
-@subsection Try to make many small changes
-
-Changes to policy should always be part of a serious and considered
-plan. They should not be @emph{ad hoc}. That said, consideration of
-changes should not be so time-consuming that it cripples human
-resources, or leads to change-avoidance because it seems daunting.
-
-It is better to make many small changes than few large changes. Large
-changes involve many interdependencies, which make them fragile to
-unexpected contingencies. The risk of large changes is high. The risk
-of small changes is low.
-
-CFEngine makes it easy to make small changes frequently, without
-operational repercussions. As long as humans are on hand during the
-change to observe possible side-effects this.
-
-
-@c **********************************************************************
-@node Always do, , Recommended, Policy Dos and Don'ts
-@section Always do
-
-
-@menu
-* Always document promises::
-* Always keep coding to a minimum::
-* Always use lists to make the same promise about multiple objects::
-* Always use existing templates::
-* Always use the system variables for system resources::
-* Always use variables as pointers to paths and servers::
-@end menu
-
-@node Always document promises, Always keep coding to a minimum, Always do, Always do
-@subsection Always document promises
-
-Always add comment attributes to your promises to explain the intention.
-
-@smallexample
-
-files:
-
- # This is a throw-away comment, below is a full-bodied promise
-
- "/tmp/testfile" # promiser
-
- @b{comment => "This is for keeps...", # Live comment}
- create => "true", # Constraint 1
- perms => p("612"); # Constraint 2
-
-@end smallexample
-
-If a promise has a stakeholder that is worthy of special mention, then
-use the promisee fields to add the name of this person.
-
-@smallexample
-
-files:
-
- "/tmp/testfile" -> @{ "stakeholder@@company.com" @},
-
- @b{comment => "This is for keeps...", # Live comment}
- create => "true", # Constraint 1
- perms => p("612"); # Constraint 2
-
-@end smallexample
-
-If a promise depends on another promise being run before it, use the
-@code{depends_on} fields to document the handle of the other prior promise.
-This allows tracing of the impact chain.
-
-
-@smallexample
-
-files:
-
- "/tmp"
-
- @b{handle => "make_temp",}
- comment => "This is for keeps...", # Live comment
- create => "true", # Constraint 1
- perms => p("612"); # Constraint 2
-
-
- "/tmp/testfile"
-
- @b{depends_on => @{ "make_temp" @},}
- comment => "This is for keeps...", # Live comment
- create => "true", # Constraint 1
- perms => p("612"); # Constraint 2
-
-@end smallexample
-
-
-@node Always keep coding to a minimum, Always use lists to make the same promise about multiple objects, Always document promises, Always do
-@subsection Always keep coding to a minimum
-
-If you are coming to CFEngine from another scripting langauge, you
-will probably be tempted to add a lot of `logic' to your CFEngine
-program, testing whether things are true and trying to control the
-order of things. This is not necessary. You should think of each
-promise as being a self-contained `nugget' that requires little
-additional coding. The more coding you add, the more fragile
-a configuration becomes.
-
-The hardest part of using CFEngine for programmers is letting go
-of the reins.
-
-
-@node Always use lists to make the same promise about multiple objects, Always use existing templates, Always keep coding to a minimum, Always do
-@subsection Always use lists to make the same promise about multiple objects
-
-If you have a number of system resources that all make the same
-promise, then use lists to iterate over the resources in a single
-promise, rather than coding the same promise many times.
-
-@smallexample
-vars:
-
- "watch_files" slist => @{
- "/etc/passwd",
- "/etc/shadow",
- "/etc/group",
- "/etc/services"
- @};
-files:
-
- "$(watch_files)"
-
- comment => "Change detection on the above",
- changes => change_management_trip_wire;
-
-@end smallexample
-
-
-@node Always use existing templates, Always use the system variables for system resources, Always use lists to make the same promise about multiple objects, Always do
-@subsection Always use existing templates
-
-Familiarize yourself with the current @code{CFEngine_stdlib.cf} file in the
-software distribution. This contains many body templates, e.g.
-
-@smallexample
-local_cp() remote_cp() secure_cp() if_elapsed() recurse()
-@end smallexample
-
-@noindent Use these pre-existing body templates whenever possible, rather
-than inventing new ones. For example:
-
-@smallexample
-
-bundle agent update
-@{
-files:
-
- "/path/to/copy"
-
- comment => "Update the policy files from the master",
- perms => u_p("600"),
- copy_from => @b{local_cp}("$(master_location)","localhost"),
- depth_search => @b{recurse}("inf");
-
-@}
-@end smallexample
-
-@b{WHY?} The comprehensibility of your code to consultants and new
-employees is enhanced by standardization of practice. If the global
-CFEngine community uses the same set of idioms, then communicating
-policy will be simpler.
-
-
-@node Always use the system variables for system resources, Always use variables as pointers to paths and servers, Always use existing templates, Always do
-@subsection Always use the system variables for system resources
-
-CFEngine provides indirection (pointers) to particular resources,
-through its @samp{sys} variable context. These variables adapt
-to the operating system and user id under which CFEngine is run.
-Your policy will be more readily portable and you will need to
-code fewer exceptions if you use CFEngine's automatically adapting
-primitives, e.g. instead of writing @file{/etc/resolv.conf} for the
-name-service configuration file, use @code{$(sys.resolv)}.
-
-@smallexample
-
-files:
-
- "@b{$(sys.resolv)}"
-
- comment => "Add lines to the resolver configuration",
- create => "true",
- edit_line => resolver,
- edit_defaults => std_edits;
-
-@end smallexample
-
-
-@node Always use variables as pointers to paths and servers, , Always use the system variables for system resources, Always do
-@subsection Always use variables as pointers to paths and servers
-
-You should avoid coding paths and names of resources directly in
-promises. Use instead a local or possible global variable to point to
-the resource instead. This brings consistency to the coding, often
-shortens the references, and provides a @i{single point of definition}
-for change.
-
-
-@smallexample
-
-bundle agent update
-@{
-vars:
-
- # A standard location for the source point (single point of definition)
-
- "master_location" string => "@b{$(sys.workdir)}/masterfiles";
-
-files:
-
- "$(sys.workdir)/inputs"
-
- comment => "Update the policy files from the master",
- perms => u_p("600"),
- copy_from => u_cp("@b{$(master_location)}","localhost"),
- depth_search => recurse("inf");
-
-@}
-
-@end smallexample
-
-
-@node Common Workflows , Quality Assurance around CFEngine, Policy Dos and Don'ts, Top
-@chapter Common Workflows
-
-This chapter concerns `workflow processes' that should typically be
-dealt with on systems. A workflow process is represented by a
-@i{promise bundle} in CFEngine. None of the proposals here should be
-considered mandatory in any sense, but they do represent the norm.
-
-We refer users to the CFEngine solutions guide for implementation details of
-specific solutions.
-
-@c **********************************************************************
-@menu
-* Anomaly Monitoring::
-* Batch Jobs::
-* Garbage Collection::
-* Knowledge Updating::
-* Name Service::
-* Policy Distribution::
-* Services::
-* Security::
-* Software Management::
-@end menu
-
-@node Anomaly Monitoring, Batch Jobs, Common Workflows , Common Workflows
-@section Anomaly Monitoring
-
-@noindent @b{Purpose:}
-
-The purpose of anomaly monitoring is to understand the stability
-of a system, both in terms of its run-time performance and its
-architectural structure. Sudden changes on a system can be separated
-from the normal slow variations.
-
-@noindent @b{Remarks:}
-
-Anomaly detection is enabled and performed by the @code{cf-monitord} daemon.
-Reporting of anomalies is not automatic however. Alerts must be promised
-explicitly. This is normally handled by a @code{reports} promise.
-
-Change detection of the file system is handled by @code{files}
-promises in @code{cf-agent}.
-
-@noindent @b{Example:}
-
-@smallexample
-
-bundle agent anomalies
-@{
-vars:
-
- "sysdir" string => "/tmp";
- "files" slist => @{ "passwd", "shadow" @};
-
-classes:
-
- "no_$(files)" not => fileexists("$(sysdir)/$(files)");
-
-files:
-
- # backup
-
- "/var/cfengine/inputs/$(files)"
-
- copy_from => emergency_save("$(sysdir)/$(files)");
-
- # restore
-
- "/tmp/$(files)"
-
- copy_from => emergency_save("/var/cfengine/inputs/$(files)"),
- ifvarclass => "no_$(files)";
-
-reports:
-
- rootprocs_high_dev2::
-
- "RootProc anomaly high 2 dev on $(mon.host) at $(mon.env_time)
- measured value $(mon.value_rootprocs) av $(mon.average_rootprocs)
- pm $(mon.stddev_rootprocs)"
-
- showstate => @{ "rootprocs" @};
-
- entropy_www_in_high&anomaly_hosts.www_in_high_anomaly::
-
- "HIGH ENTROPY Incoming www anomaly high anomaly dev!! on $(mon.host)
- - measured value $(mon.value_www_in) av $(mon.average_www_in) pm
- $(mon.stddev_www_in)"
-
- showstate => @{ "incoming.www" @};
-
- entropy_www_in_low.anomaly_hosts.www_in_high_anomaly::
-
- "LOW ENTROPY Incoming www anomaly high anomaly dev!! on $(mon.host)
- at $(mon.env_time)
- - measured value $(svalue_www_in) av $(average_www_in) pm $(stddev_www_in)"
-
- showstate => @{ "incoming.www" @};
-
- # etc.
-
-@}
-
-@end smallexample
-
-
-@c **********************************************************************
-@node Batch Jobs, Garbage Collection, Anomaly Monitoring, Common Workflows
-@section Batch Jobs
-
-
-@noindent @b{Purpose:}
-
-Batch jobs are run on systems in order to perform basic house keeping functions such
-as updating databases or executing business related tasks.
-
-@noindent @b{Remarks:}
-
-Batch jobs should not be run every time CFEngine runs, so you need to limit the
-execution of each one carefully, using:
-
-@itemize
-@item Classes
-Classes for time and location.
-@item Locks
-The @code{ifelapsed} parameter determined how much time has to have elapsed
-before the job can be executed again.
-@end itemize
-
-@noindent @b{Example:}
-
-
-@smallexample
-
-bundle agent example
-@{
-commands:
-
- # Exec on the first quarter after noon on Mondays
-
- Hr12.Q1.Monday::
-
- "/path/myscript -arg1 -arg2";
-
- # Exec every second quarter past hour, every day
-
- Q2::
-
- "/path/otherscript";
-
-@}
-
-@end smallexample
-
-
-@c **********************************************************************
-@node Garbage Collection, Knowledge Updating, Batch Jobs, Common Workflows
-@section Garbage Collection
-
-@noindent @b{Purpose:}
-
-Garbage collection is required on systems to prevent temporary or
-antiquated files from consuming all available storage resources. It is
-impossible for a system to survive in the long term without throwing
-some data away.
-
-@noindent @b{Remarks:}
-
-Needless to say, care should be exercised when deleting anything from the system.
-There are many strategies to select carefully what is to be deleted.
-The @code{file_select} constraint is your friend.
-
-@noindent @b{Example:}
-
-@smallexample
-
-
-bundle agent garbage_collection
-@{
-files:
-
- "$(sys.workdir)/outputs"
-
- comment => "Garbage collection of any output files",
- delete => tidy,
- @b{file_select => days_old("3")},
- depth_search => recurse("inf");
-
- "/tmp"
-
- comment => "Garbage collection of any temporary files",
- delete => tidy,
- @b{file_select => days_old("3")},
- depth_search => recurse("inf");
-
-@}
-
-@end smallexample
-
-@c **********************************************************************
-@node Knowledge Updating, Name Service, Garbage Collection, Common Workflows
-@section Knowledge Updating
-
-@noindent @b{Purpose:}
-@noindent @b{Remarks:}
-@noindent @b{Example:}
-
-@c **********************************************************************
-@node Name Service, Policy Distribution, Knowledge Updating, Common Workflows
-@section Name Service
-
-@noindent @b{Purpose:}
-Every computer needs to know how to perform name directory lookups in the Domain
-Name Service. On Unix systems this requires it to manage the @file{/etc/resolv.conf}
-file.
-
-@noindent @b{Remarks:}
-
-Always use the @code{$(sys.resolv)} variable to refer to the file.
-
-@noindent @b{Example:}
-
-@smallexample
-bundle agent name_resolution
-
-@{
-files:
-
- "$(sys.resolv)" # test on "/tmp/resolv.conf" #
-
- comment => "Add lines to the resolver configuration",
- create => "true",
- edit_line => resolver,
- edit_defaults => std_edits;
-
-@}
-
-bundle edit_line resolver
-
-@{
-delete_lines:
-
- "search.*";
- "nameserver 80.65.58.31";
-
-insert_lines:
-
- "search CFEngine.com" location => start;
- "nameserver 212.112.166.18";
- "nameserver 212.112.166.22";
-@}
-
-
-@end smallexample
-
-@c **********************************************************************
-@node Policy Distribution, Services, Name Service, Common Workflows
-@section Policy Distribution
-
-
-@noindent @b{Purpose:}
-
-In a centralized model of policy suggestion, policy updates are downloaded
-from a single point of definition, from one or more policy servers.
-Maintaining this flow of communication from `central command' is what maintains
-that centralized command.
-
-@noindent @b{Remarks:}
-It is not mandatory to centralize management, but usually there needs to
-be some automated process.
-
-@noindent @b{Example:}
-
-@smallexample
-
-vars:
-
- "master_location" string => "/var/cfengine/masterfiles";
-
- "policy_server" slist => @{ "62.109.39.150" @},
- comment => "IP address to locate your policy host.";
-
-files:
-
- "/var/cfengine/inputs"
-
- handle => "update_policy",
- perms => system("600"),
- copy_from => u_scp("$(master_location)",@@(policy_server)),
- depth_search => recurse("inf"),
- file_select => input_files,
- action => immediate;
-
-@end smallexample
-
-@c **********************************************************************
-@node Services, Security, Policy Distribution, Common Workflows
-@section Services
-
-
-@noindent @b{Purpose:}
-Keeping services up and running, or taking down services that should not be
-running is both a matter of productivity and security.
-
-@noindent @b{Remarks:}
-@noindent @b{Example:}
-
-@smallexample
-
-bundle agent services
-@{
-vars:
- "serlist" slist => @{ "dhcp", "ntp", "sshd" @};
-
- "sindex" int => readstringarray
- (
- "service",
- "$(g.workdir)/inputs/fixservices-array",
- "#[^\n]*",
- ":",
- "10",
- "4000"
- );
-
-methods:
-
- "any" usebundle => fixservice
- (
- "$(service[$(serlist)][0])",
- "$(service[$(serlist)][1])",
- "$(service[$(serlist)][2])",
- "$(service[$(serlist)][3])",
- "$(service[$(serlist)][4])"
- );
-@}
-
-bundle agent fixservice(service,tfiles,mfiles,procs,restart)
-@{
-files:
-
- "$(tfiles)"
- perms => system("0600","root","root"),
- copy_from => mycopy("$(g.masterfiles)/config/$(mfiles)","$(g.phost)"),
- classes => cdefine( "$(service)_restart", "failed");
-
-processes:
-
- "$(procs)"
-
- restart_class => canonify("$(service)_restart");
-
-commands:
-
- "$(restart)"
-
- ifvarclass => canonify("$(service)_restart");
-@}
-
-@end smallexample
-
-@c **********************************************************************
-@node Security, Software Management, Services, Common Workflows
-@section Security
-
-@noindent @b{Purpose:}
-Security is a vast topic. You need to start with a security policy
-and then translate this into promises about the system. For instance
-you might promise file permissions and access rules. You might promise
-change monitoring or anomaly detection.
-
-@noindent @b{Remarks:}
-This is an open ended topic. Security should be discussed as a
-human process, since most breaches come from within the system.
-CFEngine can then be used to implement hardening measures, and
-monitoring of important assets.
-
-@noindent @b{Example:}
-
-
-@smallexample
-vars:
-
- "system_files" slist => @{
- "/etc/passwd",
- "/etc/group",
- "/etc/services"
- @};
-
- "secret_files" slist => @{
- "/etc/shadow"
- @};
-
-files:
-
-
- "$(secret_files)"
-
- comment => "Check permissions are secret on the above",
- perms => mo("o-rwx","root");
-
- "$(system_files)"
-
- comment => "Check permissions are correct on the above",
- perms => mo("644","root");
-
-
-@end smallexample
-
-@c **********************************************************************
-@node Software Management, , Security, Common Workflows
-@section Software Management
-
-@noindent @b{Purpose:}
-Installing software and updating
-
-These days most systems have some kind of package based management
-system. These vary in their intelligence from self-updating robots to
-simple dumb file repositories. CFEngine can manage the installation
-and subsequent customization/configuration.
-
-@noindent @b{Remarks:}
-Installing software from some kind of source is only the first step.
-Thereafter, special settings must be harmonized with security policies
-and operational requirements.
-
-
-@noindent @b{Example:}
-
-@smallexample
-
-vars:
-
- "match_package" slist => @{
- "apache2",
- "apache2-mod_php5",
- "apache2-prefork",
- "php5"
- @};
-
-packages:
-
- "$(match_package)"
-
- package_policy => "add",
- package_method => yum,
- classes => ok("software_ok");
-
-@end smallexample
-
-
-@c **********************************************************************
-@c CHAPTER
-@c **********************************************************************
-
-
-@node Quality Assurance around CFEngine, , Common Workflows , Top
-@chapter Quality Assurance around CFEngine
-
-A powerful tool like CFEngine can do great good, or cause enormous
-damage if used carelessly. It is essential to have a strict
-discipline when making changes. This is a human quality assurance
-process.
-
-Your general rule of thumb should be: make small changes, not big releases.
-
-
-@menu
-* Policy changes::
-* The policy decision flow::
-* Configuration version control and rollback::
-* Delegating responsibility::
-@end menu
-
-@node Policy changes, The policy decision flow, Quality Assurance around CFEngine, Quality Assurance around CFEngine
-@section Policy changes
-
-Changes to policy should always be part of a serious and considered
-plan. They should not be @emph{ad hoc}. That said, consideration of
-changes should not be so time-consuming that it cripples human
-resources, or leads to change-avoidance because it seems daunting.
-
-It is better to make many small changes than few large changes. Large
-changes involve many interdependencies, which make them fragile to
-unexpected contingencies. The risk of large changes is high. The risk
-of small changes is low.
-
-CFEngine makes it easy to make small changes frequently, without
-operational repercussions. As long as humans are on hand during the
-change to observe possible side-effects this.
-
-Consider the following issues in quality assurance:
-@itemize
-@item Create a schedule and policy for major changes.
-@item Plan to acquire the complete set of components for release.
-@item Assign human roles as well as machine roles for changes.
-@item Label new policy release items uniquely for tracking.
-@item Always document the policy changes using the comment fields.
-@item Test prior to releasing into the production environment.
-@item Test in the production environment on a small number of machines whenever possible.
-@end itemize
-
-
-@image{cfengine-bdma,10cm,,The policy lifecycle,png}
-
-
-There are four commonly cited phases in managing systems, summarized
-as follows (see figure):
-
-@itemize
-@item Build
-@item Deploy
-@item Manage
-@item Audit
-@end itemize
-
-These separate phases originate with a model of system management
-based on transactional changes. CFEngine's conception of management
-is some different, as transaction processing is not a good model for
-system management, but we can use this template to see how
-CFEngine works differently.
-
-@table @emph
-@item Build
-A system is based on a number of decisions and resources that need to
-be `built' before they can be implemented. Building the trusted
-foundations of a system are the key to guiding its development. You
-don't need to decide every detail, just enough to build trust and
-predictability into your system.
-
-In CFEngine, what you build is a template of proposed promises for the
-machines in an organization such that, if the machines all make and
-keep these promises, the system will function seamlessly as
-planned. This is how it works in a human organization, and this is how
-is works for computers too.
-
-@item Deploy
-Deploying really means implementing the policy that was already
-decided. In transaction systems, one tries to push out changes one by
-one, hence `deploying' the decision. In CFEngine you simply publish
-your policy (in CFEngine parlance these are `promise proposals') and
-the machines see the new proposals and can adjust accordingly. Each
-machine runs an agent that is capable of implementing policies and
-maintaining them over time without further assistance.
-
-@item Manage
-Once a decision is made, unplanned events will occur. Such
-incidents usually set off alarms and humans rush to make new transactions
-to repair them. In CFEngine, the autonous agent manages the system,
-and you only have to deal with rare events that cannot be dealt with
-automatically.
-
-@item Audit
-In traditional configuration systems, the outcome is far from clear
-after a one-shot transaction, so one audits the system
-to determine to discover what actually happened. In CFEngine, changes
-are not just initiated once, but locally audited and maintained.
-Decision outcomes are assured by design in CFEngine and maintained
-automatically, so the main worry is managing conflicting
-intentions. Users can sit back and examine regular reports of
-compliance generated by the agents, without having to arrange
-for new `roll out' transactions.
-
-@end table
-
-@cartouche
-@emph{ROLL-OUT and ROLL-BACK? You should not think of CFEngine with a
-roll-out system, i.e. one that attempts to force out absolute changes
-and perhaps reverse them in case of error. Roll-out and roll-back are
-theoretically flawed concepts that only sometimes work in practice.
-With CFEngine, you publish a sequences of policy revisions, always
-moving forward (because like it or not, time only goes in one
-direction). All of the desired-state changes are managed locally by
-each individual computer, and continuously repaired to ensure on-going
-compliance with policy. }
-@end cartouche
-
-@node The policy decision flow, Configuration version control and rollback, Policy changes, Quality Assurance around CFEngine
-@section The policy decision flow
-
-CFEngine does not make many absolute choices. Almost everything about
-its behaviour is matter of policy and can be changed. However, a
-structure for use, like the following, is recommended (see figure).
-
-In order to keep operations as simple as possible, CFEngine maintains
-a private working directory on each machine referred to in
-documentation as WORKDIR and in policy by the variable
-@code{$(sys.workdir)}. By default, this is located at
-@file{/var/cfengine} or @file{C:\var\CFEngine}. It contains everything
-CFEngine needs to run.
-
-The figure below shows how decisions flow through the parts of a system.
-
-@image{arch,15cm,,The CFEngine architecture,png}
-
-
-@itemize
-@item
-It makes sense to have a single point of coordination. Decisions are
-therefore usually made in a single location (the Policy Definition
-Point). The history of decisions and changes can be tracked by a
-version control system of your choice (e.g. SubVersion).
-
-@item
-Decisions are made by editing CFEngine's policy file
-@file{promises.cf} on one of its included children. This process is
-carried out off-line.
-
-@item
-Once decisions have been formalized and coded, this new policy is
-copied @emph{manually} (a human decision) to a @emph{decision
-distribution point}, which by default is located in the directory
-@file{/var/cfengine/masterfiles} on all policy distribution servers.
-
-In this introduction, we shall assume that there is only one central
-policy distribution server, a specially-appointed server which is
-referred to simple as the @code{policy server}.
-
-
-@item
-Every client machine contacts the policy server and downloads these
-updates. The policy server can be replicated if the number of clients
-is very large, but we shall assume here that there is only one policy
-server.
-@end itemize
-
-Once a client machine has a copy of the policy, it extracts only those
-promise proposals that are relevant to it, and implements any changes
-without human assistance. This is how CFEngine manages change.
-
-@cartouche
-
-@emph{WHY DO THIS? CFEngine tries to minimize dependencies by decoupling
-processes. By following this pull-based architecture, CFEngine will
-tolerate network outages and will recover from deployment errors
-easily. By placing the burden of responsibility for decision at the
-top, and for implementation at the bottom, we avoid needless fragility
-and keep two independent quality assurance processes apart.}
-
-@end cartouche
-
-
-
-@c ***********************************************************
-@node Configuration version control and rollback, Delegating responsibility, The policy decision flow, Quality Assurance around CFEngine
-@section Version control and rollback
-
-
-
-CFEngine does not provide specific tools for versioning promise
-specifications. It is recommended to use a tool such as subversion for
-this. CFEngine does allow you to track changes and keep versions of
-non-trivial changes, such as file content changes.
-
-Subversion maintains revision numbers on files. It is useful to be
-able to refer to version names or numbers also in CFEngine. A version
-string can be added to files as follows:
-@smallexample
-body common control
-@{
-version => 1.2.3
-@}
-
-@end smallexample
-This defines the version number of a set of configuration files
-which is referred to in reference messages from CFEngine.
-
-
-When CFEngine saves a current version of a file that it is modifying
-or replacing, by default such files are given a new extension and
-remain within the same directory which they were
-encountered. Alternatively, one can specify a repository directory to
-which such files can be moved instead. The repository location is
-specified in the @code{control} section:
-@smallexample
-
-body agent control
-@{
-default_respository => "/var/cfengine/repository";
-@}
-
-@end smallexample
-Files moved to the repository are given names reflecting their full path, with slashes replaced
-by underscore characters. For some, this creates a clearer overview of the
-changes that have occurred.
-
-
-
-@c ***********************************************************
-@node Delegating responsibility, , Configuration version control and rollback, Quality Assurance around CFEngine
-@section Delegating responsibility
-
-In a large organization, you delegate responsibility for different
-issues to different teams. CFEngine has no meta-access control
-mechanism which can decide who may write policy rules on what
-issue. To create such a mechanism, there would have to be a monitor
-which could identify users, and an authority mechanism that would
-disallow certain users to write rules of certain types about certain
-objects on certain hosts. Although it is @emph{possible} to create such
-a system, it would be both technically difficult, very cumbersome
-to use and would add a whole new level of complexity to policy and
-potential error to the configuration process.
-
-To keep matters as simple as possible, we avoid this and propose a
-different approach. Promise theory (CFEngine's basis) reveals a
-straightforward answer to model the security implications of this (see
-the figure of the bow-tie structure). A simple method of delegating is
-the following.
-
-@enumerate
-@item Delegate responsibility for different issues to admin teams 1,2,3, etc.
-@item Make each of these teams responsible for version control of their own
-configuration rules.
-@item Make an intermediate agent responsible for collating and vetting the rules, checking for
-irregularities and conflicts. This agent must promise to disallow rules by
-one team that are the responsibility of another team. The agent could be a
-layer of software, but a cheaper and more manageable solution is the make this
-another group of one or more humans.
-
-@item Make the resulting collated configuration version controlled. Publish
-approved promises for all hosts to download from a trusted source.
-
-@end enumerate
-
-A review procedure for policy promises is a good
-solution if you want to delegate responsibility for different parts of
-a policy to different sources. Human judgement is irreplaceable, and tools
-can be added to make conflicts easier to detect.
-
-Promise theory underlines that, if a host of computing device accepts
-policy from any source, then it is alone and entirely responsible for
-this decision. The ultimate responsibility for the published version
-policy is the vetting agent. This creates a shallow hierarchy, but
-there is no reason why this formal body could not be comprised of
-representatives from the multiple teams.
-
-@center @image{delegate,13cm,,Delegation of responsibility requires vetting access,png}
-
-@cartouche
-
-Run several CFEngines? Another way to delegate CFEngine control for
-users that only require limited privileges would be to run several
-agents as non-root users. This only works however if the tasks
-delegated are very self-contained and require no special privilege.
-
-@end cartouche
-
-
-@c =========================================================================
-@c @node Index, , CFEngine Methods, Top
-@c @unnumbered Concept Index
-@c @printindex cp
-@c =========================================================================
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/cf3-conceptguide.texinfo b/docs/guides/cf3-conceptguide.texinfo
deleted file mode 100644
index 3c15ac8f32..0000000000
--- a/docs/guides/cf3-conceptguide.texinfo
+++ /dev/null
@@ -1,2505 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename cf3-conceptguide.info
-@settitle CFEngine 3 Concept Guide
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title CFEngine 3 Concept Guide
-@subtitle A CFEngine AS workbook
-@author CFEngine AS
-
-@c @smallbook
-
-
-@page
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2011 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@node Top, Introduction - System automation, (dir), (dir)
-@top CFEngine Concepts
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@c **********************************************************************
-@c CHAPTER
-@c **********************************************************************
-
-@i{This document is an abbreviated version of the CFEngine tutorial (http://cfengine.com/manuals/cf3-tutorial.html).}
-
-@c **********************************************************************
-@menu
-* Introduction - System automation::
-* The components of CFEngine::
-* Bodies and bundles::
-* A simple crash course in concepts::
-* Knowledge Management::
-@end menu
-
-@node Introduction - System automation, The components of CFEngine, Top, Top
-@chapter Introduction - System automation
-
-@menu
-* Managing diverse and challenging environments seamlessly and invisibly::
-* Managing expectations - a theory of promises::
-* Why automation?::
-* How do you view CFEngine::
-@end menu
-
-@node Managing diverse and challenging environments seamlessly and invisibly, Managing expectations - a theory of promises, Introduction - System automation, Introduction - System automation
-@section Managing diverse and challenging environments seamlessly and invisibly
-
-CFEngine was designed to enable scalable configuration management, for
-the
-whole system life-cycle, in any kind of environment.
-Almost every other system for configuration assumes that there will be
-a reliable network in place and that changes will be pushed out
-top-down from an authoritative node. Those systems are useless in
-environments like
-
-@itemize
-@item Mobile systems with partial or unreliable connectivity (e.g. a
-submarine).
-@item Systems where bandwidths are very low (e.g. a satellite or space
-probe).
-@item Systems where computing power is very low (e.g. ad hoc sensors
-or kitchen appliances).
-@end itemize
-
-CFEngine does not need reliable infrastructure. It works
-opportunistically in almost any environment, using few resources. It
-has few software dependencies. So, not only does it work in all of the
-traditional fixed-plan scenarios, but it is capable of working in
-totally ad hoc deployment: a temporary incident room, a submarine
-drifting on and off line, a satellite or a robot explorer.
-
-One could argue `well I don't need that kind of system, because my
-network is reliable'. However, your network is not as reliable as you
-think, and mobility is an increasingly important topic. Even with a
-very strong redundant network, the services that support the network
-can be paralyzed by any of a number of failed dependencies or
-mishaps. It is crucial in a modern pervasive environment that systems
-remain available, fault tolerant and as far as possible independent of
-external requirements. This is how to build scalable and reliable
-services.
-
-@cartouche
-CFEngine works in all the places you think it should, and all the new
-places you haven't even thought of yet. How do we know? Because it
-is based on almost 20 years of careful research and experience.
-@end cartouche
-
-
-@c --------------------------------------------------------------
-@node Managing expectations - a theory of promises, Why automation?, Managing diverse and challenging environments seamlessly and invisibly, Introduction - System automation
-@section Managing expectations - a theory of promises
-
-One of the hardest things in management is to make everyone aware of
-their roles and tasks, and to be able to rely on others to do the same.
-@i{Trust} is an economic time-saver. If you can't trust you have to
-verify,
-and that is expensive.
-
-To improve trust we make promises. A promise is the documentation of an
-intention to act or behave in some manner. This is what we need to
-learn to
-trust systems, no matter whether they are machines or humans.
-
-One CFEngine user once said to me, that the thing that had helped him
-the most in deploying CFEngine was its design based around voluntary
-cooperation. ``Our main problems were not technical but political --
-getting everyone to agree in all of our departments around the
-world''. This was because, for all the technology, it is people who
-make the decisions and people need to feel that the system is
-empowering rather than disempowering them.
-
-@cartouche
-
-CFEngine works on a simple notion of promises. Everything in
-CFEngine can be thought of as a promise to be kept by different
-resources in the system.
-
-Combining promises with patterns to describe where and when
-promises should apply is what CFEngine is all about.
-
-@end cartouche
-
-
-@c --------------------------------------------------------------
-@node Why automation?, How do you view CFEngine, Managing expectations - a theory of promises, Introduction - System automation
-@section Why automation?
-
-
-Humans are good at making decisions and awful at reliable
-implementation. Machines are pitiful at making decisions and very
-good at reliable implementation. It makes sense to let each side do
-the job that they are good at.
-
-The main problem in managing systems is a loss of self-discipline.
-Discipline
-does not imply that orders have to be barked from a central command. It
-only requires that every part of the system knows its job and carries
-it out seamlessly and flawlessly.
-
-Skilled workers tend to think that it is enough to be smart. In fact
-this is wrong: smart people tend to be problem solvers and will
-happily solve the same problem many times, wasting time and
-effort. Moreover, human intervention is often based on panic and lack
-of understanding so every time someone logs onto a system by hand,
-they jeopardize everyone's understanding of the system. Only the
-self-discipline of stable procedures leads to predictability.
-
-Ad hoc changes are bad because:
-@itemize
-@item Others have no idea what happened.
-@item There is no record of changes or intentions.
-@item A scar is left from the change.
-@end itemize
-
-
-People often rile against automation saying that it dehumanizes their
-work. In fact the opposite is true: forcing humans to do the work of
-machines, in repetitive and reliable ways is what dehumanizes people.
-The only way to make progress with a bad habit is to recognize it and
-be willing to abandon the habit.
-
-
-@c --------------------------------------------------------------
-@node How do you view CFEngine, , Why automation?, Introduction - System automation
-@section How do @i{you} view CFEngine?
-
-CFEngine is a framework. It is not so complex, but it is certainly
-extensive.
-Often when trying to describe CFEngine, it seems that there is too
-much to
-tell and it is hard to convey in a simple way what the software can do.
-The picture below shows a few ways in which you can think of CFEngine.
-
-@center @image{boxes,12cm,,CFEngine application areas,png}
-
-For many users, CFEngine is simply a configuration tool --
-i.e. software for deploying and patching systems according to a
-policy. Policy is described using promises -- indeed, every statement
-in CFEngine 3 is a promise to be kept at some time or location. More
-than this, however, CFEngine is not like most automation tools that
-`roll out' an image of some software once and hope for the best. Every
-promise that you make in CFEngine is continuously verified and
-maintained. It is not a one-off operation, but an encapsulated process
-that repairs itself should anything deviate from the policy.
-
-That clearly places CFEngine in the realm of automation, which often
-begs the question: so it's just another scripting language? Certainly
-CFEngine contains a powerful scripting language, but it is not like
-any other. CFEngine is not a low level language like Perl, Python or
-Ruby; it is a language of promises, in which you express very high
-level intentions about the system and the inner details figure out the
-algorithms needed to implement the result.
-
-Above all, CFEngine is aimed to promote human understanding of complex
-processes. Its promises are easily documentable using comments that
-the system remembers and reminds us about in error reporting. It hides
-irrelevant and transitory details of implementation so that the
-@i{intentions} behind the promises are highlighted for all to see.
-This means that the knowledge of your organization can be encoded into
-the CFEngine language.
-
-@cartouche
-@i{WHY DOES KNOWLEDGE MATTER? 1. Technical descriptions are hard to remember. You might understand
-your configuration decisions when you are writing them, but a few
-months later when something goes wrong, you will probably have forgotten
-what you were thinking. That costs you time and effort to diagnose.
-2. Organizations are fragile to the loss
-of those individuals who code policy. If they leave, often there is
-no one left who can understand or fix the system. Only with proper
-documentation is it possible to immunize against loss.}
-@end cartouche
-
-
-
-
-
-@c *****************************************************
-@c * CHAPTER
-@c *****************************************************
-
-@node The components of CFEngine, Bodies and bundles, Introduction - System automation, Top
-@chapter The components of CFEngine
-
-CFEngine comprises a number of components. In this chapter we'll
-consider how to
-build them and what they are for.
-
-
-@menu
-* The players::
-* About the CFEngine architecture::
-* The policy decision flow::
-@end menu
-
-
-@node The players, About the CFEngine architecture, The components of CFEngine, The components of CFEngine
-@section The players
-
-A CFEngine system is something like an orchestra.
-It is composed of any number of computers (players), each of which has
-its
-own copy of the music and knows what to play. It might or might not have
-a conductor to help coordinate the individual parts -- that's up to you.
-
-CFEngine's software agents are independent components that run on each individual computer. They can
-communicate if they need to, as depicted in the figure below. This means
-you don't have to arrange risky login credentials to run your network
--- and if something goes wrong with the communications network,
-CFEngine is where it needs to be to repair or protect the system
-during the outage.
-
-@image{components,10cm,,CFEngine components,png}
-
-If the network is not working, CFEngine just skips these parts and
-continues
-with what it can do. It is fault tolerant and opportunistic.
-
-@table @emph
-
-@item cf-promises
-The promise verifier and compiler. This is used to pre-check a set of
-configuration promises before attempting to execute.
-
-@item cf-agent
-
-This is the instigator of change. The agent is the part of CFEngine
-that manipulates
-system resources.
-
-@item cf-serverd
-
-The server is able to share files and receive requests to execute
-existing policy on an individual machine. It is not possible to send
-(push) new information to CFEngine from outside.
-
-@item cf-execd
-
-This is a scheduling daemon (which can either supplement or replace
-@code{cron}). It also works as a wrapper, executing and collecting the
-output of @code{cf-agent} and E-mailing it if necessary to a system
-account.
-
-@item cf-runagent
-
-This is a helper program that can talk to @code{cf-serverd} and
-request that it execute @code{cf-agent} with its existing policy. It
-can thus be used to simulate a push of changes to CFEngine hosts, if
-their policy includes that they check for updates.
-
-@item cf-report
-
-This generates summary and other reports in a variety of formats for
-export or integration with other systems.
-
-@item cf-know
-
-This agent can generate an ISO standard Topic Map from a number of
-promises about system knowledge. It is used for rendering documentation
-as a `semantic web'.
-
-@end table
-
-
-
-@c -------------------------------------------------------------------------
-@node About the CFEngine architecture, The policy decision flow, The players, The components of CFEngine
-@section About the CFEngine architecture
-
-This section explains how CFEngine will operate autonomously in a
-network, under your guidance. If your site is large (thousands of
-servers) you should spend some time discussing with CFEngine experts
-how to tune this description to your environment as @emph{scale}
-requires you to have more infrastructure, and a potentially more
-complicated configuration. The essence of any CFEngine deployment
-is the same.
-
-
-
-There are four commonly cited phases in managing systems, summarized
-as follows:
-
-@itemize
-@item Build
-@item Deploy
-@item Manage
-@item Audit
-@end itemize
-
-These separate phases originate with a model of system management
-based on transactional changes. CFEngine's conception of management
-is somewhat different, as transaction processing is not a good model for
-system management, but we can use this template to see how
-CFEngine works differently.
-
-@table @emph
-@item Build
-A system is based on a number of decisions and resources that need to
-be `built' before they can be implemented. Building the trusted
-foundations of a system is the key to guiding its development. You
-don't need to decide every detail, just enough to build trust and
-predictability into your system.
-
-In CFEngine, what you build is a template of proposed promises for the
-machines in an organization such that, if the machines all make and
-keep these promises, the system will function seamlessly as
-planned. This is how it works in a human organization, and this is how
-is works for computers too.
-
-@item Deploy
-Deploying really means implementing the policy that was already
-decided. In transaction systems, one tries to push out changes one by
-one, hence `deploying' the decision. In CFEngine you simply publish
-your policy (in CFEngine parlance these are `promise proposals') and
-the machines see the new proposals and can adjust accordingly. Each
-machine runs an agent that is capable of implementing policies and
-maintaining them over time without further assistance.
-
-@item Manage
-Once a decision is made, unplanned events will occur. Such
-incidents traditionally set off alarms and humans rush to make new
-transactions
-to repair them. In CFEngine, the autonomous agent manages the system,
-and you only have to deal with rare events that cannot be dealt with
-automatically.
-
-@item Audit
-In traditional configuration systems, the outcome is far from clear
-after a one-shot transaction, so one audits the system
-to determine what actually happened. In CFEngine, changes
-are not just initiated once, but locally audited and maintained.
-Decision outcomes are assured by design in CFEngine and maintained
-automatically, so the main worry is managing conflicting
-intentions. Users can sit back and examine regular reports of
-compliance generated by the agents, without having to arrange
-for new `roll out' transactions.
-
-@end table
-
-@cartouche
-@emph{ROLL-OUT and ROLL-BACK? You should not think of CFEngine as a
-roll-out system, i.e. one that attempts to force out absolute changes
-and perhaps reverse them in case of error. Roll-out and roll-back are
-theoretically flawed concepts that only sometimes work in practice.
-With CFEngine, you publish a sequence of policy revisions, always
-moving forward (because like it or not, time only goes in one
-direction). All of the desired-state changes are managed locally by
-each individual computer, and continuously repaired to ensure on-going
-compliance with policy. }
-@end cartouche
-
-
-@c ------------------------------------------------------------------
-@node The policy decision flow, , About the CFEngine architecture, The components of CFEngine
-@section The policy decision flow
-
-CFEngine does not make absolute choices for you, like other
-tools. Almost everything about its behavior is matter of policy and
-can be changed. However, a structure for use, like the following, is
-recommended (see the following figure).
-
-In order to keep operations as simple as possible, CFEngine maintains
-a private working directory on each machine referred to in
-documentation as WORKDIR and in policy by the variable
-@code{$(sys.workdir)}. By default, this is located at
-@file{/var/cfengine} or @file{C:\var\CFEngine}. It contains everything
-CFEngine needs to run.
-
-The figure below shows how decisions flow through the parts of a system.
-
-@image{arch,15cm,,The CFEngine architecture,png}
-
-
-@itemize
-@item
-It makes sense to have a single point of coordination. Decisions are
-therefore usually made in a single location (the Policy Definition
-Point). The history of decisions and changes can be tracked by a
-version control system of your choice (e.g. Subversion, CVS, etc.).
-
-@item
-Decisions are made by editing CFEngine's policy file
-@file{promises.cf} (or one of its included sub-files). This process is
-carried out off-line.
-
-@item
-Once decisions have been formalized and coded, this new policy is
-copied @emph{manually} (a human decision) to a @emph{decision
-distribution point}, which by default is located in the directory
-@file{/var/cfengine/masterfiles} on all policy distribution servers.
-
-In this introduction, we shall assume that there is only one central
-policy distribution server, a specially-appointed server which is
-referred to simple as the @code{policy server}.
-
-
-@item
-Every client machine contacts the policy server and downloads these
-updates. The policy server can be replicated if the number of clients
-is very large, but we shall assume here that there is only one policy
-server.
-@end itemize
-
-Once a client machine has a copy of the policy, it extracts only those
-promise proposals that are relevant to it, and implements any changes
-without human assistance. This is how CFEngine manages change.
-
-@cartouche
-
-@emph{WHY DO THIS? CFEngine tries to minimize dependencies by decoupling
-processes. By following this pull-based architecture, CFEngine will
-tolerate network outages and will recover from deployment errors
-easily. By placing the burden of responsibility for decision at the
-top, and for implementation at the bottom, we avoid needless fragility
-and keep two independent quality assurance processes apart.}
-
-@end cartouche
-
-
-
-@c *****************************************************
-@c * CHAPTER
-@c *****************************************************
-
-@node Bodies and bundles, A simple crash course in concepts, The components of CFEngine, Top
-@chapter Bodies and bundles
-
-To emphasize the fact that CFEngine is not an imperative programming
-language, and to keep closely to the nomenclature of Promise Theory,
-CFEngine uses two concepts throughout: bundles and bodies.
-
-
-@menu
-* Bodies::
-* Bundles::
-* A simple syntax pattern::
-@end menu
-
-@node Bodies, Bundles, Bodies and bundles, Bodies and bundles
-@section Bodies
-
-Promises are the fundamental statements in CFEngine. Promises are the policy atoms.
-If there is no promise, nothing happens.
-
-However, promises can become quite complicated and readability becomes
-an issue, so it is useful to have a way of breaking them down into independent
-components. The structure of a promise is this:
-
-@table @i
-@item Promiser
-This is the object that formally makes the promise. It is always the @i{affected object},
-since objects can only make promises about their own state or behavior in CFEngine.
-
-@item Promisee (optional)
-This is a possible stakeholder, someone who is interested in the outcome of the
-promise. It is used as documentation, and it is used for reasoning in the commercial
-CFEngine product.
-
-@item Promise body
-Everything else about a promise is defined in the body of the promise.
-We use this word in the sense of `body of a contract' or the `body of a document'
-(like @code{}) tags in HTML, for example.
-
-A promise body is a list of declarations of the following form:
-
-@verbatim
-CFEngine_attribute_type => user_defined_value or template
-@end verbatim
-
-@end table
-
-@menu
-* Body parts::
-* Control bodies::
-@end menu
-
-@node Body parts, Control bodies, Bodies, Bodies
-@subsection Body parts
-
-The CFEngine reserved word @code{body} is used to define
-@i{parameterized templates} for bodies to hide the details of complex
-promise specifications. For complex body lists, you must fill in a
-body declaration as an `attachment' to the promise, e.g.
-
-@verbatim
-files:
-
- "/tmp/promiser" # Promiser
-
- perms => myexample; # The body is just one line,
- # but needs an attachment
-
-@end verbatim
-The attachment is declared like this, with a `type' that matches the left
-hand side of the declaration in the promise:
-@verbatim
-body perms myexample
-{
-mode => "644";
-owners => { "mark", "sarah", "angel" };
-groups => { "users", "sysadmins", "mythical_beasts" };
-}
-@end verbatim
-The structure is this:
-
-@sp 1
-@cartouche
-@smallexample
-
- @var{promiser}
-
- @b{LVALUE} => @var{RVALUE}
-
-..
-
-body @b{LVALUE} @var{RVALUE}
-@{
-@b{LVALUE} => @var{RVALUE};
-@b{LVALUE} => @var{RVALUE};
-@}
-@end smallexample
-@end cartouche
-@sp 1
-
-Another way of looking at it is this:
-
-@sp 1
-@cartouche
-@smallexample
-
- @var{promiser}
-
- @b{CFEngine_word} => @var{user_defined_value}
-
-..
-
- body @b{CFEngine_word} @var{user_defined_value}
- @{
- @b{CFEngine_word} => @var{user_defined_value};
- @b{CFEngine_word} => @var{user_defined_value};
- ...
- @}
-
-@end smallexample
-@end cartouche
-@sp 1
-
-Body attachments are required items. You cannot choose to put the
-attachments in-line. This is a lesson that was learned from CFEngine
-2. Readability is quickly lost if too many details are placed in-line.
-
-@center @image{body_bundle,10cm}
-
-@node Control bodies, , Body parts, Bodies
-@subsection Control bodies
-
-Some promises in CFEngine are implicit and hard-coded into the program.
-For example, the fact that CFEngine looks for a number of files to read and
-execute them in a sequence cannot be changed.
-However, you can change the behavior of such promises by setting control
-parameters. These are formally parts of the `promise body', so we use the body structure to set them. Each agent, (CFEngine software component) has a special body whose name is @code{control}, used for setting these parameters. For cf-agent and cf-serverd we can have:
-
-@verbatim
-body agent control
-{
-bundlesequence => { "test" };
-}
-@end verbatim
-
-@verbatim
-body server control
-{
-allowconnects => { "127.0.0.1" , "::1", @(def.acl) };
-}
-@end verbatim
-
-
-@node Bundles, A simple syntax pattern, Bodies, Bodies and bundles
-@section Bundles
-
-A bundle is a simple concept. A bundle is merely a collection of promises
-in a `sub-routine-like' container. The purpose of bundles is to allow
-you greater flexibility to break down the contents of your policies and
-give them names. Bundles also allow you to re-use promise code by
-parameterizing it.
-
-Like bodies, bundles also have `types'. Bundles belong to the agent that
-is used to keep the promises in the bundle. So @code{cf-agent} has bundles
-declared as
-
-@verbatim
-bundle agent my_name
-{
-}
-@end verbatim
-
-@noindent The @code{cf-serverd} program has bundles declared as:
-@verbatim
-bundle server my_name
-{
-}
-@end verbatim
-@noindent and so on.
-
-
-
-@menu
-* Bundle scope::
-@end menu
-
-@node Bundle scope, , Bundles, Bundles
-@subsection Bundle scope
-
-Variables and classes defined inside bundles are not directly visible outside.
-All variables in CFEngine are globally accessible, however if you refer to a variable
-by @samp{$(unqualified)}, then it is assumed to belong to the current bundle. To
-access any other (scalar) variable, you must qualify the name using the name of
-the bundle in which it is defined:
-@samp{$(bundle_name.qualified)}.
-
-Some promise types, like @code{var}, @code{classes} may be made
-by any agent. These are called @code{common} promises. Bundles of type @code{common}
-are special. They may contain common promises.
-Classes defined in common bundles have global scope.
-
-@node A simple syntax pattern, , Bundles, Bodies and bundles
-@section A simple syntax pattern
-
-The syntax of CFEngine follows a simple pattern in all cases and has a few simple rules:
-
-@itemize
-@item CFEngine built-in words, and identifiers of your choosing (the names
-of variables, bundles, body templates and classes) may only contain
-the usual alphanumeric and underscore characters (@samp{a-zA-Z0-9_}).
-
-@item All other `literal' data must be quoted.
-
-@item Declarations of promise bundles
-in the form:
-@example
-bundle @var{agent-type} identifier
-@{
-...
-@}
-@end example
-
-@item Declarations of promise body-parts in the form:
-@example
-body constraint_type template_identifier
-@{
-...
-@}
-@end example
-matching and expanding on a reference inside a promise
-of the form
-@samp{constraint_type => template_identifier}.
-
-
-@item CFEngine uses many `constraint expressions'
-as part of the body of a promise. These take the form: left-hand-side (cfengine word)
-@samp{=>} right-hand-side (user defined data). This can take several forms:
-
-@verbatim
-cfengine_word => user_defined_template(parameters)
- user_defined_template
- builtin_function()
- "quoted literal scalar"
- { list }
-@end verbatim
-In each of these cases, the right hand side is a user choice.
-@end itemize
-
-Once you have learned this pattern,
-it will make sense anywhere in the program. The figure below illustrates
-this pattern. Some words are reserved by CFEngine, and are used as types or categories
-for talking about promises. Other words (in blue) are to be defined by you.
-Look at the examples and try to identify these patterns yourself.
-
-@image{cfengineword,14cm}
-
-
-@c *****************************************************
-@c * CHAPTER
-@c *****************************************************
-@node A simple crash course in concepts, Knowledge Management, Bodies and bundles, Top
-@chapter A simple crash course in concepts
-
-
-@menu
-* Rules are promises::
-* Best practice for writing promises::
-@c * Containers::
-* Decisions::
-* Types in CFEngine 3::
-* Datatypes in CFEngine 3::
-* Variables::
-* Loops::
-* The main promise types::
-* Test a promise?::
-@end menu
-
-@node Rules are promises, Best practice for writing promises, A simple crash course in concepts, A simple crash course in concepts
-@section Rules are promises
-
-Everything in CFEngine 3 can be interpreted as a promise. Promises can
-be made about all kinds of different subjects, from file attributes,
-to the execution of commands, to access control decisions and
-knowledge relationships.
-
-This simple but powerful idea allows a very practical uniformity in
-CFEngine syntax. There is only one grammatical form for statements in
-the language that you need to know and it looks generically like this:
-
-@smallexample
-
-type:
-
-classes::
-
- "promiser" -> @{ "promisee1", "promisee2", ... @}
-
- attribute_1 => value_1,
- attribute_2 => value_2,
- ...
- attribute_n => value_n;
-
-@end smallexample
-
-@noindent
-We speak of a promiser (the abstract object making the promise), the
-promisee is the abstract object to whom the promise is made, and then
-there is a list of associations that we call the `body' of the
-promise, which together with the promiser-type tells us what it is all
-about.
-
-@cartouche
-The promiser is always the object
-affected by the promise.
-@end cartouche
-
-Not all of these elements are necessary every time. Some promises
-contain a lot of implicit behavior. In other cases we might want to
-be much more explicit. For example, the simplest reports promise
-looks like this:
-
-@smallexample
-
-reports:
-
-"hello world";
-
-@end smallexample
-
-And the simplest commands promise looks like this
-
-@smallexample
-
-commands:
-
-"/bin/echo hello world";
-
-@end smallexample
-
-@noindent
-This promise has default attributes for everything except the
-`promiser', i.e. the
-command string that promises to execute.
-A more complex promise contains many attributes:
-
-@smallexample
-
-# Promise type
-files:
-
-# promiser -> promisee (no curly braces needed if only one)
-"/home/mark/tmp/test_plain" -> "system blue team",
-
- # attribute => value
- comment => "This comment follows the rule for knowledge integration",
- perms => owner("@@(usernames)"),
- create => "true";
-
-@end smallexample
-The list of promisees is not used by CFEngine except for
-documentation, just
-as the comment attribute (which can be added to any promise) has no
-actual function
-other than to provide more information to the user in error tracing
-and auditing.
-
-You see several kinds of object in this example. All literal strings
-(e.g. @code{"true"}) in CFEngine 3 must be quoted. This provides
-absolute consistency and makes type-checking easy and error-correction
-powerful. All function-like objects (e.g. @code{users("..")}) are
-either built-in
-special functions or parameterized templates which contain the `meat'
-of the right hand
-side.
-
-The words @code{commands}, and @code{files} are built-in promise
-types. Promise types generally belong each to a particular component
-of CFEngine, as the components are designed to keep different kinds of
-promises. A few types, such as @code{vars}, @code{classes} and
-@code{reports} are common to all the different component bundles. You
-will find a full list of the promise types that can be made by the
-different components in the reference manual.
-
-
-@c -----------------------------------------------------------------------
-@c @node Best practice for writing promises, Containers, Rules are promises, A simple crash course in concepts
-@node Best practice for writing promises, Decisions, Rules are promises, A simple crash course in concepts
-@section Best practice for writing promises
-
-When writing promises, get into the habit of giving every promise a comment
-that explains its intention.
-
-Also, give related promises @i{handles}, or labels that can be used to
-refer to them by.
-
-@verbatim
-
-files:
-
- "/var/cfengine/inputs"
-
- handle => "update_policy",
- comment => "Update the configuration from a master server",
-
- perms => system("600"),
- copy_from => mycopy("$(master_location)","$(policy_server)"),
- depth_search => recurse("inf"),
- file_select => input_files,
- action => immediate;
-
-@end verbatim
-If a promise affects another promise in some way, you can make the affected
-promise one of the promisees, like this:
-
-@verbatim
-
-access:
-
- "/master/cfengine/inputs" -> { "update_policy", "other_promisee" },
-
- comment => "Grant access to policy to our clients",
- handle => "serve_updates",
-
- admit => { "217.77.34.*" };
-
-@end verbatim
-
-Conversely, if a promise might depend on another in some (even indirect) way, document this too.
-
-@verbatim
-
-files:
-
- "/var/cfengine/inputs"
-
- comment => "Update the configuration from a master server",
- handle => "update_policy",
-
- depends_on => {"serve_updates"},
-
- perms => system("600"),
- copy_from => mycopy("$(master_location)","$(policy_server)"),
- depth_search => recurse("inf"),
- file_select => input_files,
- action => immediate;
-
-
-@end verbatim
-
-Get into the habit of adding the cause-effect lines of influence.
-Enterprise editions of CFEngine will track the dependencies between these
-promises and map out impact analyses.
-
-@c -----------------------------------------------------------------------
-@c @node Containers, Decisions, Best practice for writing promises, A simple crash course in concepts
-@c @section Containers
-
-
-@c CFEngine allows you to group multiple promise statements into containers called bundles.
-@c @smallexample
-
-@c bundle agent identifier
-
-@c @{
-@c commands:
-@c
-@c "/bin/echo These commands are a silly way to use CFEngine";
-@c "/bin/ls -l";
-@c "/bin/echo But they illustrate a point";
-
-@c @}
-
-@c @end smallexample
-
-@c Bundles serve two purposes: they allow us to collect related promises under a
-@c single heading, like a subroutine, and they allow us to mix configuration for different
-@c parts of CFEngine in the same file. The type of a bundle is the name of the component
-@c of CFEngine for which it is intended.
-
-@c For instance, we can make a self-contained example agent-server
-@c configuration by labeling the bundles:
-
-@c @smallexample
-
-@c #
-@c # Not a complete example
-@c #
-
-@c bundle agent testbundle
-
-@c @{
-@c files:
-
-@c "/home/mark/tmp/testcopy"
-
-@c comment => "Throwaway example...",
-@c copy_from => mycopy("/home/mark/LapTop/words","127.0.0.1"),
-@c perms => system,
-@c depth_search => recurse("inf");
-
-@c @}
-
-@c #
-
-@c bundle server access_rules
-
-@c @{
-@c access:
-
-@c "/home/mark/LapTop"
-
-@c admit => @{ "127.0.0.1" @};
-@c @}
-
-@c @end smallexample
-
-@c Another type of container in CFEngine 3 is a `body' part. Body parts
-@c exist to hide complex parameter information in reusable containers.
-@c The right hand side of some attribute assignments use body containers
-@c to reduce the amount of in-line information and preserve readability.
-@c You cannot choose where to use bodies: either they are used or they
-@c are not used for a particular kind of attribute. What you can choose, however, is
-@c the name and number of parameters for the body; and you can make as many of them as you like:
-@c For example:
-
-@c @smallexample
-
-@c body copy_from mycopy(from,server)
-
-@c @{
-@c source => "$(from)";
-@c servers => @{ "$(server)" @};
-@c copy_backup => "true";
-
-@c special_class::
-
-@c purge => "true";
-@c @}
-
-@c @end smallexample
-
-@c Notice also that classes can be used in bodies as well as parameters so that
-@c you can hide environmental adaptations in these bodies also. The classes used
-@c here are effectively ANDed with the classes under which the calling promise
-@c is defined.
-
-
-@c ------------------------------------------------------------------
-@c @node Decisions, Types in CFEngine 3, Containers, A simple crash course in concepts
-@node Decisions, Types in CFEngine 3, Best practice for writing promises, A simple crash course in concepts
-@section Decisions
-
-CFEngine decisions are made behind the scenes and the results of
-certain true/false propositions are cached in Booleans referred to as
-`classes'. There are no if-then-else statements in CFEngine; all
-decisions are made with classes.
-
-CFEngine runs on every computer individually and each time it wakes up
-the underlying generic agent platform discovers and classifies
-properties of the environment or context in which it runs. This
-information
-is effectively cached and may be used to make decisions about
-configuration.
-
-Classes fall into hard (discovered) and soft (user-defined) types. A
-single hard class can be one of several things:
-
-@itemize @bullet
-
-@item The name of an operating system architecture e.g.
-@code{ultrix}, @code{sun4}, etc.
-
-@item The unqualified name of a particular host. If your system
-returns a fully
-qualified domain name for your host, CFEngine truncates it at the
-first dot. Note: @code{www.sales.company.com} and
-@code{www.research.company.com} have the same unqualified name -- @code{www}.
-
-@item The name of a user-defined group of hosts.
-
-@item A day of the week (in the form @code{Monday, Tuesday,
-Wednesday, ..}).
-
-@item An hour of the day, current time zone (in the form @code{Hr00,
-Hr01 ... Hr23}).
-
-@item An hour of the day GMT (in the form @code{GMT_Hr00, GMT_Hr01 ...
-GMT_Hr23}).
-This is consistent the world over, in case you need virtual
-simultaneity of change
-coordination.
-
-@item Minutes in the hour (in the form @code{Min00, Min17 ... Min45}).
-
-@item A five minute interval in the hour (in the form @code{Min00_05,
-Min05_10 ... Min55_00})
-
-@item The quarter-hour (in the form @code{Q1, Q2, Q3, Q4}).
-
-@item A day of the month (in the form @code{Day1, Day2, ... Day31}).
-
-@item A month (in the form @code{January, February, ... December}).
-
-@item A year (in the form @code{Yr1997, Yr2004}).
-
-@item A shift in @code{Night,Morning,Afternoon,Evening}, which fall
-into six hour blocks
-starting at 00:00 hours.
-
-@item A `lifecycle index', which is the year number modulo 3 (used in
-long term resource memory).
-
-@item An arbitrary user-defined string.
-
-@item The IP address octets of any active interface (in the form
-@code{@w{ipv4_192_0_0_1}},
-@code{@w{ipv4_192_0_0}}, @code{@w{ipv4_192_0}}, @code{@w{ipv4_192}}).
-
-@end itemize
-
-@c chew end Hard classes
-
-To see all of the classes define on a particular host, run
-
-@smallexample
-host# cf-promises -v
-@end smallexample
-as a privileged user. Note that some of the classes are set only
-if a trusted link can be established with cfenvd, i.e. if both
-are running with privilege, and the @file{/var/cfengine/state/env_data}
-file is secure. More information about classes can be found in
-connection with
-@code{allclasses}.
-
-User-defined or soft classes are defined in bundles. Bundles of type
-@code{common} yield classes that are global in scope, whereas in all
-other bundle types classes are local. Soft classes are evaluated when
-the
-bundle is evaluated. They can be based on test functions or simply from
-other classes:
-
-@verbatim
-
-bundle agent myclasses
-{
-classes:
-
-"solinus" expression => "linux||solaris";
-
-# List form useful for including functions
-
-"alt_class" or => { "linux", "solaris", fileexists("/etc/fstab") };
-
-"oth_class" and => { fileexists("/etc/shadow"), fileexists("/etc/
-passwd") };
-
-reports:
-
-alt_class::
-
- # This will only report "Boo!" on linux, solaris, or any system
- # on which the file /etc/fstab exists
- "Boo!";
-}
-
-@end verbatim
-
-@noindent Classes may be combined with the operators listed here in order
-from highest to lowest precedence:
-
-@table @samp
-@item ()
-The parenthesis group operator.
-@item !
-The NOT operator.
-@item .
-The AND operator.
-@item &
-The AND operator (alternative).
-@item |
-The OR operator.
-@item ||
-The OR operator (alternative).
-@end table
-
-@noindent
-So the following expression would be only true on Mondays or Wednesdays
-from 2:00pm to 2:59pm on Windows XP systems:
-
-@example
-
-(Monday|Wednesday).Hr14.WinXP::
-
-@end example
-
-@noindent Consider the following more advanced example. Promises in bundles
-of type @samp{common} are global in scope -- all other promises are local to
-the scope of their bundle.
-
-
-@verbatim
-
-body common control
-{
-bundlesequence => { "g","ls_1", "ls_2" };
-}
-
-#################################
-
-bundle common g
-{
-classes:
-
-# The promise "zero" is always satisfied , and is global in scope
-"zero" expression => "any";
-
-}
-
-#################################
-
-bundle agent ls_1
-{
-classes:
-
-# The promise "one" is always satisfied , and is local in scope to ls_1
-"one" expression => "any";
-}
-
-#################################
-
-bundle agent ls_2
-{
-classes:
-
-# The promise "two" is always satisfied , and is local in scope to ls_2
-"two" expression => "any";
-
-reports:
-
-zero.!one.two::
-
- # This report @b{will} be generated
- "Success";
-}
-
-@end verbatim
-
-Here we see that class @samp{zero} is global while classes @samp{one}
-and @samp{two} are local.
-The report `Success' result is therefore true because only @samp{zero}
-and @samp{two} are in scope in the @samp{ls_2} bundle (and the class
-expression for bundle @samp{ls_2} requires that both @samp{zero} and
-@samp{two} be true and that @samp{one} not be true).
-
-CFEngine is controlled by a series of locks which prevent it from
-checking promises too often, and which prevent it from spending too
-long trying to verify promises it already verified recently. The locks
-work in such a way that you can start several CFEngine processes
-simultaneously without them interfering with each other. You can
-control two things about each kind of action in the action sequence:
-
-@table @samp
-
-@item ifelapsed
-The minimum time (in minutes) which should have passed since the last time
-that promise was verified. It will not be executed again until
-this amount of time has elapsed.
-(Default time is 1 minute.)
-
-@item expireafter
-The maximum amount (in minutes) of time cf-agent should wait for an old
-instantiation to finish before killing it
-and starting again. (Default time is 120 minutes.)
-
-@end table
-
-@noindent
-You can set these values either globally (for all
-actions) or for each action separately. If you
-set global and local values, the local values override
-the global ones. All times are written in units
-of @emph{minutes}. Global setting is in the control body:
-
-@verbatim
-
-body agent control
-{
-ifelapsed => "60"; # one hour
-}
-
-@end verbatim
-
-@noindent
-or locally in the transaction bodies:
-
-
-@verbatim
-
-body action example
-{
-ifelapsed => "90"; # 1.5 hours
-}
-
-@end verbatim
-
-These locks do not prevent the whole of cf-agent from running, only
-atomic promise checks. Several different atoms can be run concurrently
-by different cf-agents. The locks ensure that atoms will never be
-started by two cf-agents at the same time, or too soon after a
-verification, causing contention and wasting CPU cycles.
-
-
-@c -----------------------------------------------------------------------
-@node Types in CFEngine 3, Datatypes in CFEngine 3, Decisions, A simple crash course in concepts
-@section Types in CFEngine 3
-
-A key difference in CFEngine 3 compared to earlier versions is the
-presence of types. Types are a mechanism for associating
-values and checking consistency in a language. Once again, there is a
-simple pattern to types in CFEngine.
-
-The principle is very simple: types exist in order to match like a
-plug-socket relationship. In the examples above, you can see two places
-where types are used to match templates:
-
-@itemize
-@item Matching bundles to components:
-@smallexample
-
-bundle TYPE name # matches TYPE to running agent
-@{
-@}
-
-@end smallexample
-
-@item Match bodies templates to lvalues in @code{lvalues => rvalue} constraints:
-
-@smallexample
-
-body TYPE name # matches TYPE => name in promise
-@{
-@}
-
-@end smallexample
-@end itemize
-
-
-@c -----------------------------------------------------------------------
-@node Datatypes in CFEngine 3, Variables, Types in CFEngine 3, A simple crash course in concepts
-@section Datatypes in CFEngine 3
-
-CFEngine variables have two meta-types: scalars and lists. A scalar is a single value,
-a list is a collection of scalars. Each scalar may have one of three types:
-@code{string}, @code{int} or @code{real}. Typing is dynamic, so these are
-interchangeable in many instances. However arguments to special functions check legal
-type for consistency.
-
-Integer constants may use suffixes to represent large numbers.
-
-@itemize
- @item 'k'
- = value times 1000.
-
- @item 'K'
- = value times 1024.
-
- @item 'm'
- = value times 1000^2
- @item 'M'
- = value times 1024^2
- @item 'g'
- = value times 1000^3
- @item 'G'
- = value times 1024^3
-
- @item '%'
- meaning percent, in limited contexts
-
- @item 'inf'
- = a constant representing an unlimited value.
-@end itemize
-
-
-@c --------------------------------------------------------------------
-@node Variables, Loops, Datatypes in CFEngine 3, A simple crash course in concepts
-@section Variables
-
-Variables (or "variable definitions") are also promises -- the promise to
-represent their values. We can write these in
-any promise bundle. CFEngine recognizes two variable object types: scalars and
-lists (lists contain 0 or more objects)@footnote{Arrays can be scalars or lists of the RHS (rvalues). An array is really just a pattern in the names of the LHS (lvalues), not a separate type.}, as well as
-three data-types (string, integer and real). Typing in CFEngine is
-dynamic, as in
-Perl and other scripting languages. Thus variables of any data-type
-may be used as strings.
-
-
-@menu
-* Scalar variable expansion::
-* List variable substitution and expansion::
-* Special list value cf_null::
-* Arrays in CFEngine 3::
-@end menu
-
-@node Scalar variable expansion, List variable substitution and expansion, Variables, Variables
-@subsection Scalar variable expansion
-
-Scalar variables hold a single value. The are declared as follows:
-
-@smallexample
-bundle @i{} name
-@{
-vars:
-
-"my_scalar" string => "String contents...";
- "my_int" int => "1234";
- "my_real" real => "567.89";
-
-@}
-
-@end smallexample
-
-The @samp{@i{}} indicates that any kind of bundle applies here.
-Scalar variables are referenced by @samp{$(name)} (or
-@samp{$@{name@}}) and they represent
-a single value at a time.
-
-@itemize
-@item Scalars that are written without a context, e.g. @samp{$(myvar)}
-are local to the current bundle.
-
-@item Scalars are globally available everywhere provided one
-uses the context to verify them e.g. @samp{$(context.myvar)}
-may be written to access the variable `myvar' in bundle `context'.
-@end itemize
-
-
-@c -----------------------------------------------------------------------
-@node List variable substitution and expansion, Special list value cf_null, Scalar variable expansion, Variables
-@subsection List variable substitution and expansion
-
-List variables hold several values. The are declared as follows:
-
-@smallexample
-bundle @i{} name
-@{
-vars:
-
- "my_slist" slist => @{ "list", "of", "strings" @};
- "my_ilist" ilist => @{ "1234", "5678" @};
- "my_rlist" rlist => @{ "567.89" @};
-
-@}
-
-@end smallexample
-An entire list is referred to with the at symbol @samp{@@}, but it does
-not usually make sense to use this reference in a string. For instance
-@smallexample
-
-reports:
-
- cfengine_3::
-
- "My list is @@(my_slist)";
-
-@end smallexample
-@noindent means nothing and cannot be expanded (it does not generate an
-error, but instead inserts the text @@(my_slist) into the string); but if
-we use the scalar reference to a list variable, CFEngine will iterate over
-the values in
-the list essentially making this into a list of promises.
-
-@noindent To summarize:
-@itemize
-
-@item Scalar references to @i{local} list variables imply iteration,
-e.g.
-suppose we have local list variable @samp{@@(list)}, then the
-scalar @samp{$(list)} implies an iteration over every value of the
-list.
-
-
-@item Lists can be passed in their entirety in any context
-where a list is expected as @samp{@@(list)}., e.g.
-
-@verbatim
-
-vars:
-
-"longlist" slist => { @(shortlist), "plus", "plus" };
-
-"shortlist" slist => { "you", "me" };
-
-@end verbatim
-
-The declaration order does not matter -- CFEngine will execute the promise
-to assign the variable @samp{@@(shortlist)} before the promise to assign the
-variable @samp{@@(longlist)}.
-
-@item Only local lists can be expanded directly. Thus @samp{$(list)}
-can be expanded but not @samp{$(context.list)}. Global
-list references have to be mapped into a local context if you want to
-use them for iteration.
-@end itemize
-
-Instead of doing this in some
-arbitrary way, with possibility of name collisions, CFEngine
-asks you to make this explicit. There are two possible approaches.
-
-The first uses parameterization to map a global list into a local
-context.
-@verbatim
-
-#
-# Show access of external lists.
-#
-# - to pass lists globally, use a parameter to dereference them
-#
-
-body common control
-{
-bundlesequence => { hardening(@(va.tmpdirs)) };
-}
-
-#########################################################
-
-bundle common va
-{
-vars:
-
- "tmpdirs" slist => { "/tmp", "/var/tmp", "/usr/tmp" };
-
-}
-
-##########################################################
-
-bundle agent hardening(x)
-{
-classes:
-
- "ok" expression => "any";
-
-vars:
-
- "other" slist => { "/tmp", "/var/tmp" };
-
-reports:
-
- ok::
-
- "Do $(x)";
- "Other: $(other)";
-}
-
-@end verbatim
-
-This alternative uses a direct `short-circuit' approach to map the global
-list into the local context.
-
-@verbatim
-#
-# Show access of external lists.
-#
-
-body common control
-{
-bundlesequence => { hardening };
-}
-
-#########################################################
-
-bundle common va
-{
-vars:
-
- "tmpdirs" slist => { "/tmp", "/var/tmp", "/usr/tmp" };
-
-}
-
-##########################################################
-
-bundle agent hardening
-{
-classes:
-
- "ok" expression => "any";
-
-vars:
-
- "other" slist => { "/tmp", "/var/tmp" };
- "x" slist => { @(va.tmpdirs) };
-
-reports:
-
- ok::
-
- "Do $(x)";
- "Other: $(other)";
-}
-@end verbatim
-
-
-@c -----------------------------------------------------------------------
-@node Special list value cf_null, Arrays in CFEngine 3, List variable substitution and expansion, Variables
-@subsection Special list value @code{cf_null}
-
-As of CFEngine core version 3.1.0, the value @samp{cf_null} may be used as a NULL
-value within lists. This value is ignored in list variable expansion.
-
-@verbatim
-
-vars:
-
- "empty_list" slist => { "cf_null" };
-
-@end verbatim
-
-
-@c -----------------------------------------------------------------------
-@node Arrays in CFEngine 3, , Special list value cf_null, Variables
-@subsection Arrays in CFEngine 3
-
-Array variables are written with @samp{[} and @samp{]} brackets, e.g.
-
-@verbatim
-
-bundle agent example
-
-{
-vars:
-
- "component" slist => { "cf-monitord", "cf-serverd", "cf-execd" };
-
- "array[cf-monitord]" string => "The monitor";
- "array[cf-serverd]" string => "The server";
- "array[cf-execd]" string => "The executor, not executioner";
-
-commands:
-
- "/bin/echo $(component) is"
-
- args => "$(array[$(component)])";
-
-}
-
-@end verbatim
-
-Arrays are associative and may be of type scalar or list. Enumerated
-arrays are simply treated as a special case of associative arrays, since
-there are no numerical loops in CFEngine. Special functions exist to
-extract lists of keys from array variables for iteration purposes.
-
-Thus one could have written the example above in the form of the
-following example:
-
-@verbatim
-
-bundle agent array
-
-{
-vars:
-
- "v[index_1]" string => "value_1";
- "v[index_2]" string => "value_2";
-
- "parameter_name" slist => getindices("v");
-
-reports:
-
- Yr2008::
-
- "Found index: $(parameter_name)";
-
-}
-
-@end verbatim
-
-
-@c ------------------------------------------------------------------
-@node Loops, The main promise types, Variables, A simple crash course in concepts
-@section Loops
-If you are looking for loops in CFEngine then we need to reprogram you
-a little, as you are thinking like a programmer! CFEngine is not a
-programming language that is meant to give you low level control, but
-rather a set of declarations that embody processes. It's the difference
-between the gears on a bicycle and the automated transmission in a
-transporter.
-
-Loops are executed implicitly in CFEngine, but there is no visible
-mechanism for it -- because that would steal attention from the
-intention of the promises. The way to express them is through lists.
-
-Loops are really a way to iterate a variable over a list. Try the
-following.
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-vars:
-
-# This is a list
-
-"component" slist => { "cf-monitord", "cf-serverd", "cf-execd" };
-
-# This is an associative array
-
-"array[cf-monitord]" string => "The monitor";
-"array[cf-serverd]" string => "The server";
-"array[cf-execd]" string => "The executor, not executionist";
-
-reports:
-
-cfengine_3::
-
-"$(component) is $(array[$(component)])";
-
-}
-
-@end verbatim
-The output looks something like this:
-@smallexample
-
-/var/cfengine/bin/cf-agent -f ./unit_loops.cf -K
-
-R: cf-monitord is The monitor
-R: cf-serverd is The server
-R: cf-execd is The executor, not executionist
-
-@end smallexample
-You see from this that, if we refer to a list variable using the
-scalar reference
-operator @samp{$()}, CFEngine interprets this to mean ``please iterate
-over all
-values of the list''. Thus, we have effectively a `foreach' loop, without the
-attendant syntax.
-
-@c ---------------------------------------------------------------------------
-@node The main promise types, Test a promise?, Loops, A simple crash course in concepts
-@section The main promise types
-
-@noindent The following promise types may be used in any bundle:
-@table @code
-@item vars
-A promise to be a variable, representing a value.
-@item classes
-A promise to be a class representing a state of the system.
-@item reports
-A promise to report a message.
-@end table
-
-@noindent These additional promise types may be used only in agent bundles
-@table @code
-@item commands
-A promise to execute a command.
-@item databases
-A promise to configure a database.
-@item files
-A promise to configure a file, including its existence, attributes and
-contents.
-@item interfaces
-A promise to configure a network interface.
-@item methods
-A promise to take on a whole bundle of other promises.
-@item packages
-A promise to install a package.
-@item storage
-A promise to verify attached storage.
-@end table
-
-@noindent These promise types belong to other components:
-@table @code
-@item access
-A promise to grant or deny access to file objects in @code{cf-serverd}.
-@item measurements
-A promise to measure or sample data from the system, for monitoring or
-reporting in @code{cf-monitord} (CFEngine Nova and above).
-@item roles
-A promise to allow certain users to activate certain classes when
-executing @code{cf-agent} remotely, in @code{cf-serverd}.
-@item topics
-A promise to associate knowledge with a name, and possibly other
-topics, in @code{cf-know}.
-@item occurrences
-A promise to point or refer to a knowledge resource, in @code{cf-know}.
-@end table
-
-
-@c ---------------------------------------------------------------------------
-@node Test a promise?, , The main promise types, A simple crash course in concepts
-@section Test a promise?
-
-If you are impatient to get hands-on experience, now might be a good time to take a break from Concepts and try out your first promises (@url{http://cfengine.com/manuals/cf3-tutorial.html#First-promises}. Still, since knowledge management is an integral part of CFEngine, we strongly recommend to read the following section on this very issue sooner rather than later.
-
-@c *****************************************************
-@c * CHAPTER
-@c *****************************************************
-@node Knowledge Management, , A simple crash course in concepts, Top
-@chapter Knowledge Management
-
-
-A unique aspect of CFEngine, that is fully developed in the commercial
-editions of the software, its ability to enable integrated knowledge
-management as part of an automation process, and to use its configuration
-technology as a `semantic' documentation engine.
-
-@image{topicmap,15cm,,,png}
-
-Knowledge management is the challenge of our times. Organizations
-frequently waste significant effort re-learning old lessons because they have
-not been documented and entered into posterity. Now you can alleviate
-this problem with some simple rules of thumb and even build
-sophisticated index-databases of documents.
-
-
-@menu
-* Promises and Knowledge::
-* The basics of knowledge::
-* Annotating promises::
-* A promise model of topic maps::
-* What topic maps offer::
-* The nuts and bolts of topic maps::
-* Example of topics promises::
-* Modeling configuration promises as topic maps::
-@end menu
-
-@node Promises and Knowledge, The basics of knowledge, Knowledge Management, Knowledge Management
-@section Promises and Knowledge
-
-The learning curve for configuration management systems has been the
-brunt of frequent criticism over the years. Users are expected to either
-confront the informational complexity of systems at a detailed level, or
-abandon the idea of fine control altogether. This has led either to
-information overload or over-simplification. The ability to cope with
-information complexity is therefore fundamental to IT management
-
-CFEngine introduced the @emph{promise model} for configuration in
-order to flatten out this learning curve. It can lead to
-simplifications in use, because a lot of the thinking has been done
-already and is encapsulated into the model. One of its special
-properties is that it is both a model for system behaviour and a model
-for knowledge representation (this is what declarative languages seek
-to be, of course). More specifically, it incorporated a subset of the
-ISO standard for `Topic Maps', an open technology for semantic
-indexing of information resources. By bringing together these two
-technologies (which are highly compatible), we end up with a seamless
-front-end for sewing together and browsing system information.
-
-Knowledge management is a field of research in its own right, and it
-covers a multitude of issues both human and technological. Most would
-agree that knowledge is composed of facts and relationships and that
-there is a need both for clear definitions and semantic context to
-interpret knowledge properly; but how do we attach @emph{meaning} to
-raw information without ambiguity?
-
-Knowledge has quite a lot in common with configuration: what after all
-is
-knowledge but a configuration of ideas in our minds, or on some
-representation medium (paper, silicon etc). It is a coded pattern,
-preferably one that we can agree on and share with others. Both
-knowledge and configuration management are about describing patterns.
-A simple knowledge model can be used to represent a policy or
-configuration; conversely, a simple model of policy configuration can
-manufacture a knowledge structure just as it might manufacture
-a filesystem or a set of services.
-
-
-@node The basics of knowledge, Annotating promises, Promises and Knowledge, Knowledge Management
-@section The basics of knowledge
-
-Knowledge only truly begins when we write things down:
-
-@itemize
-@item The act of formulating something in writing brings a discipline
-of thought than often lends clarity to an idea.
-@item You never confront an idea fully until you try to put it into
-language.
-@item Any written record that is kept allows others to read it and
-pass on the knowledge.
-@end itemize
-
-The trouble is that writing is something people don't like to do, and
-few are very good at. To an engineer, it can feel like a waste of
-time, especially during a busy day, to break off from the doing to
-write about the doing. Also, writing requires a spurt of creative
-thinking and engineers are often more comfortable with manipulating
-technical patterns and notations than writing fluent linguistic
-formulations that seem overtly long-winded.
-
-CFEngine tries to bridge this gap by making documentation simple and
-part of the technical configuration. CFEngine's knowledge agent then
-uses AI and network science algorithms to construct a readable
-documentation from these technical annotations. It can do this because
-a lot of thought has already gone into the meaning of the promise
-model.
-
-@node Annotating promises, A promise model of topic maps, The basics of knowledge, Knowledge Management
-@section Annotating promises
-
-The beginning of knowledge is to annotate the technical specifications.
-Remember that the point of a promise is to convey an @i{intention}.
-When writing promises, get into the habit of giving every promise a
-comment that explains its intention. Also, expect to give special
-promises
-@i{handles}, or helpful labels that can be used to refer to them in
-other
-promise statements. A handle could be something dumb like `xyz', but
-you should
-try to use more meaningful titles to help make references clear.
-
-@verbatim
-
-files:
-
-"/var/cfengine/inputs"
-
- handle => "update_policy",
- comment => "Update the CFEngine input files from the policy server",
- perms => system("600"),
- copy_from => rcp("$(master_location)","$(policy_server)"),
-depth_search => recurse("inf"),
-file_select => input_files,
- action => immediate;
-
-@end verbatim
-@noindent If a promise affects another promise in some way, you can
-make the affected one
-promise one of the promisees, like this:
-
-@verbatim
-
-access:
-
-"/master/CFEngine/inputs" -> { "update_policy", "other_promisee" },
-
-handle => "serve_updates",
- admit => { "217.77.34.*" };
-
-@end verbatim
-
-@noindent Conversely, if a promise might depend on another in some
-(even indirect) way, document this too.
-
-@verbatim
-
-files:
-
-"/var/cfengine/inputs"
-
- handle => "update_policy",
- comment => "Update the CFEngine input files from the policy
-server",
- depends_on => { "serve_updates" },
- perms => system("600"),
- copy_from => rcp("$(master_location)","$(policy_server)"),
-depth_search => recurse("inf"),
-file_select => input_files,
- action => immediate;
-
-@end verbatim
-
-@noindent This use of annotation is the first level of documentation
-in CFEngine.
-The annotations are used internally by CFEngine to provide meaningful
-error messages with context and to compute dependencies that reveal
-the existence of process chains. These can be turned into a topic map
-for browsing the policy relationships in a web browser, using
-@code{cf-know}.
-
-
-@cartouche
-The CFEngine Knowledge Map is only available in commercial editions
-of the software, where the necessary support to set up and maintain
-this technology can be provided.
-@end cartouche
-
-
-@node A promise model of topic maps, What topic maps offer, Annotating promises, Knowledge Management
-@section A promise model of topic maps
-
-CFEngine's model of promises can also be used to promise information
-and its relevance in different contexts. The Knowledge agent @code{cf-know}
-understands three kinds of promise.
-
-@table @code
-@item topics:
-A topic is merely a string that can be associated with another string. It represents a `subject to be talked about'.
-Like other promise types, you can use contexts, which are formed from other topics expressions to limit the scope of
-the current topic promise.
-@item things:
-Things are a simplified interface to topics, that were introduced to make it easier
-for users to contribute knowledge about more concrete `things', or less abstract ideas.
-A challenge with knowledge management is the abstract and technical nature of the models
-one must use to represent it. Things attempt to make that task easier.
-@item occurrences:
-An occurrence is a reference to a document or a piece of text that actually represents
-knowledge content about the topic concerned. Occurrences are generally URLs or strings
-explaining things or topics.
-@end table
-
-@node What topic maps offer, The nuts and bolts of topic maps, A promise model of topic maps, Knowledge Management
-@section What topic maps offer
-
-CFEngine is capable of automating the documentation of a policy, using basic annotations provided above, as a
-knowledge map. They require very little effort from the user. If you
-are using the Community Edition of CFEngine, you can develop a topic
-map, but we do not support the backend technology without a
-commercial license. In either case, once you become familiar with the
-use of Topic Maps, you will want to extend your knowledge manually to
-incorporate things like:
-
-@itemize
-@item Local (high level) policy documents
-@item Related databases, such as CMDBs
-@end itemize
-
-@noindent So let us spend a while showing how to encode knowledge in
-topic maps
-using @code{cf-know}.
-
-The kind of result you can expect is shown in the pictures below. The
-example figures show typical pages generated by the knowledge agent
-@code{cf-know}. The first of these shows how we use the technology to
-power the web knowledge base in the commercial CFEngine product.
-
-In this use, all of the data are based on documentation for
-the CFEngine software, and most of the relationships are manually
-entered.
-
-For a second example, consider how CFEngine can generate such a
-knowledge map analysis of its own configuration (self-analysis). The
-data in the images below describe the CFEngine configuration
-promises. One such page is generated, for instance, for each policy
-promise, and pages are generated for reports from different computers
-etc. You can also create you own `topic pages' for any local
-(enterprise) information that you have.
-
-In this example, the promise has been given the promise-handle
-@code{update_policy}, and the associations and the lower graph shows
-how this promise relates to other promises through its documented
-dependencies (these are documented from the promisees and
-@code{depends_on} attributes of other promises.).
-
-The example page shows two figures, one above the other.
-The upper figure shows the thirty nearest topics (of any kind) that
-are related to this one.
-Here the relationships are unspecific. This diagram can reveal
-pathways to related information
-that are often unexpected, and illustrates relationships that broaden
-one's understanding
-of the place the current promise occupies within the whole.
-
-Although the graphical illustrations are just renderings of
-semantic associations shown more fully in text, they are useful for
-visualizing
-several levels of depth in the associative network. This can be
-surprisingly useful for brainstorming and reasoning alike. In
-particular, one can see the other promises that could be affected if
-we were to make a change to the current promise. Such impact analyses
-can be crucial to planning change and release management of policy.
-
-
-
-@cartouche
-
-A knowledge base is a slightly improved implementation of a Topic Map which is an ISO
-standard technology. A topic map works like an index that can point to
-many different kinds of external resources, and may contain simple
-text and images internally. So you use it to bind together documents
-of any kind. A CFEngine knowledge base is not a new document format, it
-is an overlay map that joins ideas and resources together, and
-displays relationships.
-
-@end cartouche
-
-
-
-
-@node The nuts and bolts of topic maps, Example of topics promises, What topic maps offer, Knowledge Management
-@section The nuts and bolts of topic maps
-
-
-@menu
-* Topic map definitions::
-@end menu
-
-@node Topic map definitions, , The nuts and bolts of topic maps, The nuts and bolts of topic maps
-@subsection Topic map definitions
-
-Topic maps are really electronic indices, but they form and work like
-webs.
-A topic is the technical representation of a `subject', i.e. anything
-you might want
-to discuss, abstract or physical e.g. an item of `abstract
-knowledge', which probably has a number of concrete exemplars. It
-might be a person, a machine, a quality, etc.
-
-Topics can be classified into boxes called @emph{topic-types} so that
-related
-things can be collated and unrelated things can be separated, e.g.
-types allow us to distinguish between @code{rmdir} the Unix utility
-and @code{rmdir} the Unix system-call.
-
-Each typed topic can further point to a number of references or
-exemplars called @emph{occurrences}. For instance, an occurrence of
-the topic `computer' might include books, web documents, database
-entries, physical manifestations, or any other information. An
-occurrence is a reference that exemplifies the abstract
-topic. Occurrence references are like the page numbers in an
-index.
-
-
-A book index typically has `see also' references which point from one
-topic to another.
-Topic Maps allow one to define any kind of @emph{association} between
-topics. Unlike an ordinary index, a topic map has a rich (potentially
-infinite) variety of cross reference types.
-For instance,
-@smallexample
-topic_1 ``is a kind of'' topic_2
-topic_1 ``is improved by'' topic 2
-topic_1 ``solves the problem of'' topic_2
-@end smallexample
-
-@noindent The topic map model thus has three levels of containers:
-
-@table @emph
-@item Contexts
-The box into which we classify a topic to disambiguate different
-topics with the same name (`in the context of')@footnote{Here, CFEngine differs from the topic map standard in allowing contexts
-to be overlapping sets, rather than mutually exclusive `types'.
-CFEngine is guided by Promise Theory in this respect in order to enable
-distributed cooperation and the development of a free and emergent ontology.}.
-
-@item Topics/Things
-The representation of a subject (an index term).
-
-@item Occurrence Types
-A term that explains how an actual document occurrence relates
-to the topic is claims to say something about. e.g. (tutorial, manual,
-or
-example, definition, photo-album etc).
-
-@item Occurrences
-Specific information resources: these are pointers to the actual
-documents
-that we want to read (like page numbers in an index).
-@end table
-
-
-Contexts map conveniently into CFEngine classes.
-Topics map conveniently into promisers.
-Occurrences also map to promisers of a different type.
-These three label different levels of granularity of meaning. Contexts
-represent a set of topics that might be relevant, which in turn encompass a set of
-occurrences of resources that contain actual information about the topics in that context. The primacy of topics in this
-stems from their ability to form networks by @emph{association}.
-
-The classic approach to information modeling is to build a
-hierarchical decomposition of non-overlapping objects. Data are
-manipulated into non-overlapping containers which often prove
-to be overly restrictive. Topic maps allow us to avoid the kinds of
-mistakes that have led to monstrosities like the Common Information
-Model (CIM) with its @emph{thousands} of strictly non-overlapping type
-categories.
-
-Each topic allows us to effectively `shine a light' onto the
-occurrences of information that highlight the concepts pertinent to
-the topic somehow.
-
-
-@node Example of topics promises, Modeling configuration promises as topic maps, The nuts and bolts of topic maps, Knowledge Management
-@section Example of topics promises
-
-You can use @code{cf-know} to render a topic map either as text (for
-command line
-use) or as HTML (for web rendering). We begin with the text rendering
-as it requires less
-infrastructure. You will just need a database.
-
-Try typing in the following knowledge promises:
-
-@smallexample
-
-body common control
-@{
-bundlesequence => @{ "tm" @};
-@}
-
-###################################################
-
-bundle knowledge tm
-@{
-topics:
-
-
-"server" comment => "Common name for a computer in a desktop";
-"desktop" comment => "Common name for a computer for end users";
-
-programs:: # context of programs
-
-"httpd" comment => "A web service process";
-"named" comment => "A name service process";
-
-services::
-
-"WWW" comment => "World Wide Web service",
- association => a("is implemented by",
- "programs::httpd",
- "implements");
-
- # if we don't specify a context, it is "any"
-
-"WWW" association => a("looks up addresses with",
- "named",
- "serves addresses to");
-
-occurrences:
-
-httpd::
- "http://www.apache.org"
- represents => @{ "website" @};
-
-@}
-
-###################################################
-
-body association a(f,name,b)
-
-@{
-forward_relationship => "$(f)";
-backward_relationship => "$(b)";
-associates => @{ $(name) @};
-@}
-@end smallexample
-
-@noindent The simplified things interface is similar, but uses fixed relations:
-
-@verbatim
-bundle knowledge company_knowledge
-{
-things:
- regions::
-
- "EMEA" comment => "Europe, The Middle-East and Africa";
- "APAC" comment => "Asia and the Pacific countries";
-
- countries::
- "UK" synonyms => { "Great Britain" },
- is_located_in => { "EMEA", "Europe" };
-
- "Netherlands" synonyms => { "Holland" },
- is_located_in => { "EMEA", "Europe" };
-
- "Singapore" is_located_in => { "APAC", "Asia" };
-
- locations::
- "London_1" is_located_in => { "London", "UK" };
- "New_Jersey" is_located_in => { "USA" };
-
- networks::
-
- "192.23.45.0/24" comment => "Secure network, zone 0. Single octet for corporate offices",
- is_connected_to => { "oslo-hub-123" };
-
-@end verbatim
-
-@menu
-* Analyzing and indexing the policy::
-* cf-know::
-@end menu
-
-@node Analyzing and indexing the policy, cf-know, Example of topics promises, Example of topics promises
-@subsection Analyzing and indexing the policy
-
-CFEngine can analyze the promises you have made, index and cross
-reference them using the command:
-
-@verbatim
-# cf-promises -r
-@end verbatim
-Normally, the default policy in Nova/Enterprise will perform this
-command each time the policy is changed.
-
-@node cf-know, , Analyzing and indexing the policy, Example of topics promises
-@subsection @code{cf-know}
-
-CFEngine's knowledge agent @code{cf-know} allows you to make promises
-about knowledge and its inter-relationships. It is not specifically a
-generic topic map language: rather it provides a powerful configuration
-language for managing a knowledge base that can be compiled into a
-topic map.
-
-To build a topic map from a set of knowledge promises in @file{knowledge.cf}, you would write:
-
-@verbatim
-# cf-know -b -f ./knowledge.cf
-@end verbatim
-
-The syntax of this file is hinted at below.
-The full ISO standard topic map model is too rich to be a useful tool
-for system knowledge management. However, this is where powerful
-configuration management can help to simplify the process: encoding a
-topic map is a complex problem in configuration, which is exactly what
-CFEngine is for. CFEngine's topic map promises have the following
-form:
-
-@smallexample
-
-bundle knowledge example
-@{
-topics:
-
-topic_type_context:: # canonical container
-
-"Topic name" # short topic name
-
- comment => "Use this for a longer description",
- association => a("forward assoc to","Other topic","backward assoc");
-
- "Other topic";
-
-occurrences:
-
-Topic_name:: # Topic
-
- "http://www.example.org/document.xyz" # URI to instance
-
- represents => @{ "Definition", "Tutorial"@}; # sub-types
-@}
-
-@end smallexample
-The association body templates look like this:
-@verbatim
-
-body association a(f,name,b)
-{
-forward_relationship => "$(f)";
-backward_relationship => "$(b)";
-associates => { $(name) };
-}
-
-@end verbatim
-
-
-
-@cartouche
-
-Promise theory adds a clear structure to the topic map ontology, which
-is highly beneficial as experience shows that weak conceptual models
-lead to poor knowledge maps.
-
-@end cartouche
-
-
-@node Modeling configuration promises as topic maps, , Example of topics promises, Knowledge Management
-@section Modeling configuration promises as topic maps
-
-We can model topic maps as promises within CFEngine; the
-question then remains as to how to use topic maps to model
-configurations so that CFEngine users can navigate the documented
-promises using a web browser and be able to see all of the
-relationships between otherwise isolated and fragmentary rules. This
-will form the basis of a semantic Configuration Management Database
-(sCMDB) for the CFEngine software. The key to making these ends meet
-is to see the configuration of the topic map as a number öf promises
-made in the abstract space of topics and the turning each promise into
-a meta-promise that models the configuration as a topic with attendant
-associations. Consider the following CFEngine promise.
-
-@verbatim
-
-bundle agent update
-{
-files:
-
-any::
-
-``/var/cfengine/inputs'' -> { ``policy_team'', ''dependent'' },
-
- comment => ``Check policy updates from source'',
- perms => true,
- mode => 600,
- copy_from => true,
- copy_source => /policy/masterfiles,
- compare => digest,
- depth_search => true,
- depth => inf,
- ifelapsed => 1;
-
-}
-@end verbatim
-
-This system configuration promise can be mapped by CFEngine into a
-number of other promise proposals intended for the @code{cf-know}
-agent. Suppressing some of the details, we have:
-
-@verbatim
-
-type_files::
-
-"/var/cfengine/inputs"
- association => a("promise made in bundle","update","bundle
-contains promise");
-"/var/cfengine/inputs"
- association => a("specifies body type","perms","is specified in");
-"/var/cfengine/inputs"
- association => a("specifies body type","mode","is specified in");
-"/var/cfengine/inputs"
- association => a("specifies body type","copy_from","is specified
-in");
-
-# etc ...
-
-occurrences:
-
-_var_CFEngine_inputs::
-
- "promise_output_common.html#promise__var_CFEngine_inputs_update_cf_13"
- represents => { "promise definition" };
-
-@end verbatim
-Note that in this mapping, the actual promise (viewed as a real world
-entity) is an occurrence of the topic `promise'; at the same time each
-promise could be discussed as a different topic allowing
-meta-modeling of the entity-relation model in the real-world
-data. Conversely the topics themselves become configuration items or
-`promisers' in the promise model. The effect is to create a navigable
-semantic web for traversing the policy; this documents the structure
-and intention of the policy using a small ontology of standard
-concepts and can be extended indefinitely by human domain experts.
-
-
-
-
-
-@chapter More...
-
-@cartouche
-
-You will find extensive help, examples and documentation as part of
-the commercial CFEngine support. Visit the website @url{http://www.cfengine.com} for more
-details.
-
-@end cartouche
-
-@noindent Need help getting started?
-@itemize
-@item CFEngine Installation: @url{http://cfengine.com/manuals/cf3-installation.html}
-@item Get started, first promises: @url{http://cfengine.com/manuals/cf3-tutorial.html#First-promises}
-@end itemize
-
-@noindent For a complete overview:
-@itemize
-@item Tutorial: @url{http://cfengine.com/manuals/cf3-tutorial.html}
-@item Reference manual: @url{http://cfengine.com/manuals/cf3-Reference.html}
-@end itemize
-
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
diff --git a/docs/guides/cf3-enterprise.texinfo b/docs/guides/cf3-enterprise.texinfo
deleted file mode 100644
index 933f34c84c..0000000000
--- a/docs/guides/cf3-enterprise.texinfo
+++ /dev/null
@@ -1,3602 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename cf3-enterprise.info
-@settitle CFEngine and Enterprise Processes
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title CFEngine and Enterprise Processes
-@subtitle A CFEngine AS workbook
-@author CFEngine AS
-
-@c @smallbook
-
-
-@page
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2008- CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@node Top, Enterprise integration, (dir), (dir)
-@top CFEngine-Enterprise-Manual
-@end ifnottex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-@iftex
-@contents
-@end iftex
-
-@c **********************************************************************
-@c CHAPTER
-@c **********************************************************************
-
-
-@menu
-* Enterprise integration::
-* CFEngine past and present::
-* ITIL past and present::
-* A meeting of mind-sets::
-* Using CFEngine to implement ITIL objectives::
-* Summary::
-* ITIL glossary::
-@end menu
-
-@c **********************************************************************
-@node Enterprise integration, CFEngine past and present, Top, Top
-@chapter Enterprise Integration
-
-@menu
-* Business alignment::
-* ITIL introduced::
-* Business processes and goals::
-* About Promises::
-* Is automation worthwhile?::
-@end menu
-
-@c **********************************************************************
-@node Business alignment, ITIL introduced, Enterprise integration, Enterprise integration
-@section Business alignment
-
-The goal of most IT installations is to work as a support
-infrastructure for some other primary activity, such as the running of
-a business or other organization. Even if the primary activity is the
-design of computer systems, or the writing of software, the supporting
-infrastructure is a tool whose management is in principle separate
-from the main business goals. As organizations become larger, the
-management of the IT system and other ancillary activities frequently
-become isolated from ``front line'' activities.
-
-IT infrastructure is an enabler, so it is important to ensure that it
-succeeds in this task. How do we do this? This document is about how
-to make CFEngine-management best support primary business or organizational
-processes.
-
-We write this document in the light to two trends: the demotion of
-system administration as a job description and the rise of service
-oriented thinking to replace it, along with monolithic design
-philosophy of systems. Service orientation is not so much a
-technological innovation as it is a different kind of social
-structure. It is a move away from hierarchy as the main model of
-organization, toward generalized network structure. In computer
-parlance, service orientation is essentially a peer to peer
-structure. There are no automatic kings or commanders in chief, only
-peers who need help from other peers. If such key positions arise,
-they emerge naturally by necessity, not by presumption.
-
-For example, in the 1960s factory work in the United Kingdom was
-organized hierarchically with powerful unions attending to a dutiful
-``separation of concerns'', much like an idealized object oriented
-system. To build a ship, one would have to ask the management to ask
-panel producers for panels, then when they were finished they would
-send the message back up the hierarchy so that management would
-schedule the welders to arrive, then the painters and so on. Much
-delay and inefficiency was caused by this organizational bureaucratic
-structure.
-
-Although this behaviour persists to a lesser extent, today we use more
-direct communication between the parts that need to connect and so
-save much time and overhead. This service oriented thinking can be
-applied to computing services, their organization and even the support
-of those computing services. The service model can be applied at all
-levels.
-
-In the late 1980s it was realized that a service oriented view of
-management could profitably be formalized so as to be of benefit to
-all organizations. This began the Information Technology
-Infrastructure Library, building on the experience of leaders in
-government and industry, including organizations such as the British
-Broadcasting Corporation, the office of Government Commerce and others.
-
-@c **********************************************************************
-@node ITIL introduced, Business processes and goals, Business alignment, Enterprise integration
-@section ITIL introduced
-
-The IT Infrastructure Library (ITIL) has emerged as a de-facto set
-of ideas about service delivery. It is not based on any theoretical
-model or design criteria. It is rather a set of self-proclaimed @emph{best
-practices} compiled by representatives from government and industry.
-As such its claims can be discussed, but we shall not do so here.
-We shall refer to ITIL because it has become a popular set of
-guidelines for all manner of IT organizations, and because it promotes
-the idea of IT-business @emph{alignment}.
-
-ITIL was an important source of concepts and processes documented in
-the following British and ISO standards:
-
-@itemize
-@item BS 15000
-@item ISO/IEC 20000 (successor of BS 15000)
-@end itemize
-
-ITIL now encompasses various books and courses and has its own
-qualification scheme allowing for a certification of Service Managers
- or IT staff.
-
-The key concepts of ITIL include @emph{service and process orientation}, and
-service orientation is an important model for system organization
-because it can encompass everything from the monolithic hierarchical
-systems of yesteryear to modern day peer to peer architectures which
-better mirror a free-market economic business interaction. It can be
-applied to computer-provided services (e.g. web services, or even
-configuration operations like CFEngine) or it can be applied to human
-services and operations such as help desks and support. This makes it
-an important centre-piece in the discussion.
-
-ITIL has its own particular terminology for discussing service related
-matters. To relate these to the use of a technology such as CFEngine
-we need to understand the words and how they are used. ITIL uses many
-terms and phrases in a different way to system
-administrators.
-
-The verb ``to manage'' originally meant ``to cope''. Only more recently
-has strategic thinking changed it into a transitive verb: something that
-we do to systems, like driving a car, or flying a plane.
-
-Today the term ``management'' signifies the introduction of a
-bureaucratic level of governance, to control and verify the workings
-of a system. The terminology this has come about mainly because
-the people who wrote ITIL live in that kind of world and understand
-things through these eyes. Ironically, computer engineers now speak
-of ``self-management'' and ``autonomics'' to recover the original
-idea of systems that can cope.
-
-In this document we have two principal aims:
-@itemize
-@item To explain a number of
-patterns for using CFEngine to allow systems to cope with business
-needs.
-
-@item To demystify ITIL for technicians and
-engineers who do not naturally respond to business-speak,
-relating CFEngine's capabilities (both the technical aspects that are
-well known and the non-technical aspects of instrumentation and
-reporting that are less well known) to the goals of ITIL.
-@end itemize
-
-
-@c **********************************************************************
-@node Business processes and goals, About Promises, ITIL introduced, Enterprise integration
-@section Business processes and goals
-
-What do we need to make a business? Do we need a demand for a
-``product'', a workflow to implement it, a supply (chain)
-mechanism for selling it to a market? It turns out that the service
-abstraction is a paradigm that fits all enterprises without too much
-shoe-horning.
-
-Businesses have probably many goals in their grand designs: they have
-high level visions, notions of secure and best practices, sometimes
-even ethical policies. All of these can be couched in the language of
-promises to behave in some way.
-
-Now, we can ask: what does it mean to align an IT infrastructure to
-this business goal to provide @i{S}? First, for IT systems to have any
-impact on the business goal at all, the business must rely on the IT
-system in some way. This could either be directly, in the manner of an
-e-commerce web-site, or it might be indirectly, for instance by
-providing drawing and modelling software in an architect's office. In
-either case there is a workflow in which an IT system plays an
-intermediary role in the workflow process.
-
-In fact, it does not matter whether this is an IT system, a human being
-or a steam-powered engine. What is key is that there is a technology
-playing an intermediate role in the performance of a service.
-We can display this as the workflow diagram shown by
-the dotted lines in the figure.
-The business @i{B} would like to provide service @i{S} to its customer @i{C};
-in actuality this requires the help of intermediary @i{I}.
-
-@image{intermediate,10cm,,Intermediate agent,png}
-
-Inserting an intermediate agent into a business process. The dotted
-lines show a work flow path. The arc shows a promise the business
-would like to make to the end customer -- but promise theory says that
-it cannot if it does not have direct contact.
-
-Promise theory has several implications, and one of them is that an
-agent cannot promise something @emph{with confidence} to an agent it is
-not directly in contact with. This is because agents can only vouch
-for their own behaviour. They cannot promise what an intermediate
-agent would do. This has implications for the business.
-
-Suppose a business want to make a promise to its customer, but knows
-that it must rely on intermediaries (the IT department for example) to
-do so. Promise theory tells us that the business representative making
-the promise requires promises from every intermediate agent in the
-chain, and each of the agents in that chain require promises from down
-the chain too.
-
-It is beyond the scope of this document to explain all of those
-promises. What CFEngine allows a business to do is to automate many
-of those promises -- or make them @emph{autonomic} (self-managing).
-
-@menu
-* Teams control structures and collaboration::
-@end menu
-
-@c **********************************************************************
-@node Teams control structures and collaboration, , Business processes and goals, Business processes and goals
-@subsection Teams and collaboration
-
-Humans are poor at reliable, repetitive work but they are infinitely
-superior at creative work and decision-making. Modern theory on
-success in business rejects the classic views of management with
-militarized or bureaucratized chains of command and
-control in favour of more human-creative
-structures. Creative and adaptive workflow requires high level of
-decentralization and autonomy, while at the same time protecting the
-core values of the organization.
-
-Team work is a key element in decentralized organization -- both for
-humans and computers. IT departments are often organized in this way,
-for instance. Teams do not exist because they maximize production of
-every individual, nor do they make an organization more predictable or
-controllable. They exist because humans need continual motivation and
-emotional support -- and indirectly this sustains workflow and adds
-creativity to a business. One often overlooks the team-aspect of
-coping when considering computer management, in favour of hierarchical
-design. CFEngine does not force us into hierarchical systems however,
-so we should not discard the smaller team idea too soon.
-
-@image{hierarchy,10cm,,Hierarchy has long traditions but modern thinking favours teams.,png}
-
-CFEngine is complex enough for it to make sense to delegate
-responsibility for different issues. An organization will generally
-consist of many groups and teams already, each with their own special
-needs and each craving its own autonomy. CFEngine and promise theory
-were designed for precisely this kind of environment. CFEngine allows
-cooperation and sharing without allowing central managers to ride
-roughshod over local needs.
-
-Teams thrive by discussion and interaction within the framework of a
-policy or vision, allowing variation and arriving at a consensus when
-necessary. Success in a team depends on a combination of abilities
-working together not undermining one another. Conflicts in the
-promises made by team members reveal design problems in the group. An
-analysis of promises (CFEngine's model of collaboration) is a
-significant tool for understanding and enabling businesses.
-
-M. Belbin a researcher in teamwork has identified nine abilities or
-roles (kinds of promise) to be played in a team collaboration:
-
-@enumerate
-@item Plant -- a creative ``ideas'' person who solves problems.
-
-@item Shaper -- this is a dynamic member of the team who thrives on
-pressure and has the drive and courage to overcome obstacles.
-
-@item Specialist -- someone who brings specialist knowledge to the group.
-
-@item Implementer -- a practical thinker who is rooted in reality and can turn ideas into
-practice (who sometimes frustrates more imaginative high flying
-visionaries).
-
-
-@item Resource Investigator -- an enabler, or someone who knows where to
-find the help the team needs regardless of whether the help is
-physical, financial or human. This person is good at networking.
-
-
-@item Chairman/Co-ordinator -- an arbitrator who makes sure that
-everyone gets their say and can contribute.
-
-@item Monitor-Evaluator -- is a dispassionate, discerning member who can
-judge progress and achievement accurately during the process.
-
-
-@item Team Worker -- someone concerned with the team's inter-personal
-relationships and who is sensitive to the atmosphere of the group.
-
-
-
-@item Completer/Finisher -- someone critical and analytical who looks after the details of
-presentation and spots potential flaws and gaps. The completer is
-a quality control person.
-@end enumerate
-
-His model has little room for technical workflow arguments. It is
-entirely concerned with the creative process. This is probably
-significant. We should ask ourselves: how can we use the freedom to
-organize into specialized teams to maximize human creativity, while
-passing hard work over to machines. Solving this problem is what
-CFEngine is about.
-
-
-@node About Promises, Is automation worthwhile?, Business processes and goals, Enterprise integration
-@section About Promises
-
-@menu
-* A theory::
-* Basic definitions::
-@end menu
-
-@c **********************************************************************
-@node A theory, Basic definitions, About Promises, About Promises
-@subsection A theory for ITIL
-
-ITIL has no theory to back it up, so we have to look elsewhere for a
-motivation of its practices. Promise theory is an attempt to do just
-this for a service oriented model in which peers make promises to one
-another. So it ought to work for ITIL also.
-The advantage of promise theory is that it helps us to see how
-CFEngine can be used, because promises provide a simple
-picture of how CFEngine works.
-
-@cartouche
-Think of CFEngine as a general tool for automatically making sure that promises are kept.
-@end cartouche
-
-The popular service concept fails to capture one thing very clearly, namely the
-distinction between making a promise and keeping a promise. A
-service implies that something will be provided but it does not
-specify when.
-
-Suppose we ask a security company to protect our assets. The company
-might promise to deploy guards, or alarm technology, or it could
-simply promise that you will be safe without explaining how the
-promise will be kept. The promise does not necessarily imply any
-action required to maintain this state of safety, but we still pay the
-company for the service to keep this promise anyway. Trust plays an
-important role, of course.
-
-Promise theory helps us to understand services in all forms by forcing
-us to think carefully about the concept of @emph{autonomy}. Autonomy
-implies several things: for instance, privacy of information,
-independence of decision and responsibility for one's own
-behaviour. The concept of autonomy is like a filter that makes us
-think carefully about things that we often take for granted. It
-is a good discipline, forcing us to confront what we think we know
-about systems.
-
-The agents of promises are humans, computers or any entity that can be
-associated with a promise even if by association with its owner or
-designer. They are said to be autonomous if they cannot be forced to
-make any promises about their behaviour by an outside agent. A useful
-principle for understanding systems is the maximal @emph{separation of
-concerns} and promises help us to separate independent issues.
-
-Separation of concerns is only half the story however. Promises are
-also about describing how the parts of a system work together, just as
-in team-work. Promises provide the glue that allows completely
-autonomous parts to form an organization. We are not allowed to think
-about ``control'' or ``command'', only about voluntary cooperation.
-Keep these ideas in mind when reading this document.
-
-@c **********************************************************************
-@node Basic definitions, , A theory, About Promises
-@subsection Basic promise definitions
-
-We can use the language of promises to make clearer definitions.
-@itemize
-@item @emph{Service}: a promise to act or provide a resource.
-The promise is made from a `server' agent @i{S} to one or more external agents
-which we call the clients.
-
-@item @emph{Agreement}: a mutual acceptance of knowledge by two agents (``the agents agree'').
-The knowledge that is agreed to is called the body of the
-agreement. Note that the term ``agreement'' is sometimes used
-incorrectly to mean ``contract''. Agreement is often
-signified by signing the body, or some equivalent declaration. In
-promise theory an agreement is a pair of @emph{use-promises} between two
-parties to acknowledge acceptance of the agreement body.
-
-@item @emph{Contract}: a bilateral bundle of proposed promises between two agents,
-intended to serve as the body of an agreement.
-
-@item @emph{Service Level Agreement} An agreement between two parties whose body
-describes a contract for service delivery and consumption.
-@end itemize
-
-
-Service Level Agreements (SLA) are now a well-known part of the
-customer-business scenario.
-How are promises different from Service Level Agreements (SLA)?
-Promises are more primitive than agreements. Agreements bind two
-parties to a collection of bilateral decisions that have been made in
-advance. An agreement implies an existing infrastructure on which to
-agree. A promise on the other hand is an entirely autonomous
-statement about agents' behaviour (ad hoc). Showing only the promises in a
-system does not imply any agreement between the parties, only
-indications about their likely behaviours.
-
-In other words, seeing the promises that have been made, an external
-observer could calculate effective service levels that have been
-promised without any agreement taking place. Promises are therefore
-more fundamental than agreements to the predictability of the system.
-
-
-@c **********************************************************************
-@node Is automation worthwhile?, , About Promises, Enterprise integration
-@section Is automation worthwhile?
-
-Process automation is an investment which has its own cost. The
-benefits are not merely saved manpower but improved consistency or
-certainty of process. Automation provides an automatic quality assurance.
-
-A simple argument against automation goes like this: if I can fix it
-in five minutes then it is not worth automating, unless the automation
-takes less time than that.
-
-The argument is simplistic. Before dismissing automation, one should
-ask questions like this:
-@itemize
-@item How many of these five minute periods occur in the long run?
-@item How much time was needed to diagnose each of them?
-@item Could the problems have been avoided altogether by proactive maintenance?
-@end itemize
-One of the benefits of automation is in prevention, another is in
-documenting institutional learning by codifying the processes
-required for the avoidance of incidents. A tool like CFEngine which
-separates intention (promises) from action makes this kind of
-documentation highly readable and allows the learning to penetrate the
-workflow processes directly.
-
-@c **********************************************************************
-@node CFEngine past and present, ITIL past and present, Enterprise integration, Top
-@chapter CFEngine past and present
-
-
-CFEngine is a free software package for automating the installation
-and maintenance of networked computers. The project began in 1993 and
-it has been in widespread use since 1995. CFEngine is available for all major
-Unix and Unix-like operating systems, and it will also run under
-NT-derived Windows operating systems via the Cygwin Unix-compatibility
-environment/libraries.
-
-CFEngine scales easily from a single host to tens of thousands of
-hosts. As of this writing, the largest installations we know of
-regulate around 50,000 machines under a common administration.
-CFEngine can manage many aspects of system configuration and
-maintenance, including the following:
-
-@itemize
-@item Performing post-installation tasks such as configuring the network interface.
-@item Editing system configuration files and other files.
-@item Creating symbolic links.
-@item Checking and correcting file permissions and ownership.
-@item Deleting unwanted files.
-@item Compressing selected files.
-@item Distributing files within a network.
-@item Automatically mount NFS file systems.
-@item Verifying the presence and integrity of important files and file systems.
-@item Executing commands and scripts.
-@item Applying security-related patches and similar system corrections.
-@item Managing system server processes.
-@end itemize
-
-CFEngine's purpose is to implement policy-based configuration
-management. In practical terms, this means that CFEngine greatly
-simplifies the tasks of system configuration and maintenance. For
-example, to customize a particular system, it is no longer necessary
-to write a program which performs each required action in a procedural
-language like Perl or your favorite shell. Instead, you write a much
-simpler policy description that documents @emph{how} you want your
-hosts to be configured. The CFEngine software determines what needs to
-be done in terms of implementation and/or remediation from this
-specification. Such policy descriptions are also used to ensure that
-the system remains configured as the system administrator wishes over
-time.
-
-Here is a brief example of such a policy description which verifies and
-installs a number of packages in a convergent way:
-
-@smallexample
-
-body common control
-{
-bundlesequence => { "packages" };
-}
-
-#############################################
-
-bundle agent packages
-{
-vars:
-
- "match_package" slist => {
- "apache2",
- "apache2-mod_php5",
- "apache2-prefork",
- "php5"
- };
-packages:
-
- "$(match_package)"
-
- package_policy => "add",
- package_method => yum;
-
-}
-
-@end smallexample
-
-This simple configuration is divided into four stanzas, each
-introduced by a colon-terminated keyword, specifically
-@code{control:}, @code{files:}, @code{copy:} and @code{tidy:}. The
-@code{control} stanza defines a list of directories which we've named
-@var{tmpdirs} which we'll use later (in the @code{tidy} stanza).
-
-The @code{files} stanza specifies that all of the files in the
-directory @file{/usr/local/bin} should be owned by user root and
-group bin and have the file mode 755. When CFEngine runs with this
-configuration description it will correct any ownership and/or
-permissions which deviate from these specifications. Thus, this
-stanza serves to implement a policy about the proper ownerships and
-permissions for the executables in the local binaries directory.
-
-The @code{copy} stanza prescribes different configurations for Linux
-and Solaris systems. On Solaris systems, files in @file{/etc/pam.d}
-will be updated with those in the directory @file{/config/pam/solaris} on a master server when the latter are newer. On
-Linux systems, only the file @file{/etc/pam.d/common-auth} is updated
-from the PAM master configuration because the Linux systems in
-question use the PAM include file mechanism to propagate this file's
-stacks to all of the PAM-enabled services. Note, however, that both of
-these specifications implement the same underlying system
-configuration maintenance policy: update the relevant PAM
-configuration files from the master server if necessary.
-
-The final, @code{tidy} stanza illustrates the use of implicit
-looping. The single directive in the example applies to each of the
-directories in the @var{tmpdirs} list. For each directory, CFEngine
-will delete all items in the directory or any of its subdirectories
-which have not been accessed in seven days (including ones where the
-filename begins with a period). Like the other directives in this
-sample configuration file, this stanza implements a policy: items in
-temporary directories which have not been used within a week will be
-deleted.
-
-All CFEngine configuration descriptions are variations on these an
-similar themes, albeit more elaborate ones. Before turning to more
-details about the technical aspects of using CFEngine, a brief
-consideration of the most important underlying and guiding theoretical
-concepts is in order.
-
-@menu
-* Fundamental Concepts::
-* CFEngine Components::
-@end menu
-
-@c **********************************************************************
-@node Fundamental Concepts, CFEngine Components, CFEngine past and present, CFEngine past and present
-@section Fundamental CFEngine Concepts
-
-As we've stated, CFEngine operates on hosts in order to bring their
-configurations in line with the specified policies.
-We need to define some terms.
-
-@table @i
-@item Host
-A host is a single computer that runs an operating system like Unix,
-Linux or Windows. We will sometimes talk about machines too, and
-a host can also be a virtual machine supported by an environment VMWare or Xen/Linux.
-
-@item Policy
-This is a specification of what we want a host to be like, or how
-we want it to behave. A policy is essentially a piece of
-documentation that describes technical details and
-characteristics. CFEngine implements policies that are specified via
-directives of the sort we just considered.
-
-@item Configuration
-The configuration of a host is the actual state of its resources, e.g.
-the permissions and contents of files, the inventory of software installed, etc. It
-is the `state of affairs' on a particular host at a given time.
-@end table
-
-What are we aiming for with CFEngine? The answer is: @emph{policy
-conformant configuration}. We want to formulate a specification of not
-just one host, but usually many, including how they all interact,
-perhaps to solve a business problem; then we want to leave the
-details, implementation and maintenance to a robot agent:
-@code{cfagent}.
-
-Humans are good at understanding input and thinking up solutions but they
-not very reliable at implementation: @emph{doing} things reliably. Machines and
-software agents are good at carrying out tasks reliably, but are not
-good at understanding or finding actual solutions. With CFEngine, you
-let the distinct parts of your human-computer organization concentrate
-on what they are each good at.
-
-CFEngine can also produce reports about systems for monitoring the
-performance and compliance with policies. This is an important aspect
-of business integration as service providers want to know whether they
-are delivering what they have promised, and whether their money has been
-spent wisely.
-
-@node CFEngine seen from an ITIL perspective
-@section CFEngine seen from an ITIL perspective
-
-The figure below shows the three cornerstones of CFEngine and how they relate to one another.
-
-@image{cfengine-schematic,10cm,,The key aspects of CFEngine from an ITIL perspective,png}
-
-@itemize
-@item @code{cf-agent} is the engine for configuration management. It takes
-a policy (expressed in promises) and ensures continuously that promises are kept.
-
-@item @code{cf-monitord} is the lightweight monitoring agent, that observes the states
-of the system that can not be specified by policy, i.e. performance aspects that are determined
-by the environment in which a system is placed.
-
-@item @code{cf-know} is the knowledge agent which builds a semantic web-overview of
-the policy and state of the system, using topic maps.
-@end itemize
-
-This triumvirate of components exchanges information in all directions to build
-a complete, reflective, policy-based management framework.
-
-The @i{convergent automation} that CFEngine provides, along with its model of
-promises, provides an immediate ITIL process loop for @i{incident management},
-repairing deviations from a given release of policy.
-
-What CFEngine tries to achieve is the separation of design from implementation,
-in much the way that style-sheets do this for web browsers. The CFEngine policy
-is a (probably incomplete) specification of all machines' configurations,
-and the @code{cf-agent} is an implementation engine. When intention and action
-have been separated, all that is really left for humans to govern is @i{knowledge}.
-
-Policy is, of course, knowledge about our @i{intentions} for the
-system. Monitoring data are knowledge about the state of the system
-that we have not directly planned for. Knowledge about unforeseen
-events helps us to inform the next revision of policy, and builds up
-historical records about system behaviour. Thus, the information
-about actual happenings feeding back into new @i{releases} of policy is
-what ÃÂTIL refers to as @i{problem management}.
-
-In this way, CFEngine supports the process of knowledge management `DIKW',
-from Data to Information to Knowledge to Wisdom.
-
-
-
-@node How is CFEngine different from a classical CMDB?
-@section How is CFEngine different from a classical CMDB?
-
-One of ITIL's central requirements is the Configuration Managment
-Database or CMDB. According to ITIL this database is built up of
-inventory information and relationships. The database starts out as
-an archive of collected information but at some point it stops being a
-record of obvservation and starts becoming an authoratative template
-for defining and `imaging' systems.
-
-The CFEngine view is that a database is only ever a report cache. It
-is never the authoratative source of a configuration, because a ER
-data model does not provide an expressive enough language for
-describing a system. CFEngine has its own policy language, with
-special properties and optimizations for the authoratative intentions
-of the system. Thus @code{cf-agent} reads policy, written in the
-CFEngine language, and implements it. Then the agent itself, in
-concert with other components like @code{cf-monitord} reports back on
-what really happened, and this is cached in a database (which might be
-called a CMDB). This is the separation of duties that CFEngine holds
-to.
-
-One important difference is that relationships do not have to be
-data-mined from the database. They can be coded directly in policy,
-and thus they too can be authoratative, not merely guessed.
-
-
-@menu
-* Promises actions operations::
-* Convergence::
-* Classes and Declarations From One to Many Hosts::
-* Voluntary Cooperation::
-* Scalability::
-@end menu
-
-@node Promises actions operations, Convergence, Fundamental Concepts, Fundamental Concepts
-@section Promises, Actions and Operations
-
-CFEngine's philosophy fits quite well with the service oriented
-approach to computing.
-
-A CFEngine policy can be thought of as a list of promises which the
-system makes to some auditor about its configuration. Most of the
-these promises involve the possibility of @emph{change} to make a host
-fulfills its policy promises. We call such changes @emph{actions} or
-@emph{operations}. As you probably already guessed, the auditor in this
-scenario is part of CFEngine itself. Cfagent is also the mechanic
-or surgeon that performs the operations on the system, if it does not
-meet its promises.
-
-By describing its operation in this manner, we can think of configuration
-management as a service that is provided, a service that is intimately
-connected with monitoring and maintenance, and which can be ``bought''
-on demand without necessarily subordinating a system to a central authority.
-
-@table @i
-@item Operation
-A unit of change is called an operation. CFEngine deals with changes to
-a system, and operations are embedded into the basic sentences of a
-CFEngine policy. They tell us @emph{how} policy constrains a host,
-in other words, how we will prevent a host from running away.
-@end table
-
-For example, in the software package promise above,
-
-@smallexample
-
-packages:
-
- "$(match_package)"
-
- package_policy => "add",
- package_method => yum;
-
-@end smallexample
-
-There are implicit operations (actions) in this declaration: specifically, the
-operations that will change the packages if/when they do not conform to this
-simple specification.
-
-@node Convergence, Classes and Declarations From One to Many Hosts, Promises actions operations, Fundamental Concepts
-@subsection Convergence
-
-A key property of CFEngine is convergence. This is an important characteristic
-that distinguishes it from general computer languages. It is a property that
-helps to prevent systems from diverging: running away in an uncontrollable
-fashion.
-
-@table @i
-@item Convergence
-An operation is convergent if it always brings the configuration of a
-host closer to its ideal, policy-conformant state and has no effect if
-the host is already in that state. We shall sometimes call it a
-``correct state'' or a ``healthy state,'' using the metaphor that a
-badly configured host is suffering from a kind of sickness.
-@end table
-
-Here is an example used during the editing of an ASCII file:
-
-@smallexample
-
-insert:
-
- "@var{Important configuration line}";
-
-@end smallexample
-This operation tells CFEngine to insert the given text (by default at the end of a
-file), only if it is not already there. The policy-conformant configuration is
-therefore that the line is present, and once that is achieved nothing
-more will be done. We say that the operation @code{insert}
-is @i{convergent}.
-
-Don't underestimate the value of convergence. It provides you with
-stability. Because CFEngine's language interface strongly discourages
-you from doing anything non-convergent, it also help to prevent
-mistakes. The price is that you will have to learn to think in a
-convergent way---and that is new for most people who come to CFEngine for
-the first time.
-
-@c **********************************************************************
-@node Classes and Declarations From One to Many Hosts, Voluntary Cooperation, Convergence, Fundamental Concepts
-@subsection One or Many Hosts
-
-One of the features that makes CFEngine policies readable is the
-ability to hide away all of the complex decision-making that
-needs to be performed by the agent. To realize this ambition, CFEngine
-uses a @emph{declarative} language to express policy.
-
-
-A declarative language is simply a structured list of sentences (in
-the case of CFEngine, it is a list of policy promises). It is stated
-in no particular order; it describes a final goal that is to be
-achieved. The details of how one gets there are left implicit: to be
-evaluated and implemented by the engine that interprets the
-specification. This is in contrast to @emph{procedural} or
-@emph{imperative} languages, such as shell or Perl which micro-manage
-every step along the way.
-
-In an imperative language, one focuses on the procedure. In a declarative
-language, one focuses on the intention, or the presumed result.
-
-One example of this is the use of classes in CFEngine. Classes are a
-way of making decisions, without writing many ``if-then-else''
-clauses. A class is an identified which has the value ``true'' when a
-particular test is true. It is a Boolean variable; if you like it
-caches the result of an ``if'' test. The benefit of classes is that
-all of the testing can be hidden away in the bowels of CFEngine, and
-only the results need be visible if or when they are needed.
-
-@table @i
-@item Classes
-A class is a way of slicing up and mapping out the complex environment
-of one or more hosts into regions that can then be referred to by a
-symbol or name. They describe scope: @emph{where} something is to
-be constrained.
-@end table
-
-For example, the class @code{debian} is true if and only if cfagent is
-running on a host that has Debian Linux as its operating system.
-
-@node Voluntary Cooperation, Scalability, Classes and Declarations From One to Many Hosts, Fundamental Concepts
-@subsection Voluntary Cooperation
-
-It is a fundamental property of CFEngine components that every host
-retains its individual autonomy. A host can always opt out of CFEngine-based governance if its administrator wants to.
-This principle leads to a fundamental design and implementation decision:
-
-
-@table @i
-@item Autonomy
-No CFEngine component is capable of receiving information that it
-has not explicitly asked for itself, nor can it be advised or commanded
-by an outside agent without requesting such advice.
-@end table
-
-It is important to understand what this means. It does not mean that
-centralized control of hosts cannot be achieved. Centralized control
-is the way that most users choose to use CFEngine. Indeed, all you have
-to do to achieve centralized control is to make a policy decision for
-all your hosts to fetch policy specifications from a central authority.
-
-Autonomy does mean that if your environment has some small groups or
-sub-cultures with special needs, it is possible for them to retain
-their special identity. No one claiming to be their self-appointed
-authority can ride rough shod over their local decisions.
-
-@emph{Where does policy come from then?}
-Each host works from a policy specification that CFEngine expects to
-find in a local directory (usually @file{/var/cfengine/inputs} on a
-Unix-like host). If you want your host to be controlled from some
-central manager or authority, then your policy must contain
-bootstrapping specifications that say: ``@emph{it is my decision that
-I should download and follow the policy specification located
-at the central manager}.''
-
-Each host can turn this policy decision off at any time.
-This is a key part of the CFEngine security model.
-
-
-@c **********************************************************************
-@node Scalability, , Voluntary Cooperation, Fundamental Concepts
-@subsection Scalability
-
-CFEngine's scalability is at least as good as any other system,
-because it allows for maximal distribution of
-workload.
-
-@table @i
-@item Scalable distributed action
-Each host is responsible for carrying out checks and maintenance
-on/for itself, based on its local copy of policy.
-@end table
-
-This does not mean that you are immune from making bad decisions.
-For example, network services can always be a bottleneck if you ask 10,000 hosts
-to fetch something from one place at the same time.
-
-The fact that each CFEngine agent keeps a local copy of policy (regardless
-of whether it was written locally or inherited from a central
-authority) means that CFEngine will continue to function even if
-network communications are down.
-
-@node CFEngine Components, , Fundamental Concepts, CFEngine past and present
-@section CFEngine Components
-
-The CFEngine software consists of a number of components: separate
-programs that work together (see figure). The components differ
-between version 1 and version 2. We shall only discuss CFEngine 2
-here, as CFEngine version 1 is no longer supported, and you are strongly
-advised to use version 2. In addition, CFEngine version 3 is being
-developed at the time of writing, but this will take a number of years
-before it can fully replace version 2. It will incorporate the state
-of the art in Network and System Administration research, building on all
-the lessons learned from versions 1 and 2.
-
-The components of CFEngine are:
-
-
-@itemize
-@item @code{cfagent}: Interprets policy promises and implements them in a convergent manner.
-The agent can use data generated by the statistical monitoring engine @code{cfenvd} and
-it can fetch data from @code{cfservd} running on local or remote hosts.
-
-@item @code{cfexecd}: Is a scheduler and wrapper which executes @code{cfagent} and logs
-its output (optionally sending a summary via email). It can be run in
-daemon (standalone) mode, or it can be run from @code{cron}
-on a Unix-like system.
-
-@item @code{cfservd}: A server daemon that serves file data. It can also be configured
-to start @code{cfagent} immediately on receipt of a connection from @code{cfrun}. No
-actual data can be passed to this daemon.
-
-@item @code{cfrun}: A helper application that polls hosts and asks them to run @code{cfagent}
-if they agree.
-
-@item @code{cfenvd}: A statistical state monitor that collects statistics
-about resource usage on each host for anomaly detection purposes. The information is
-made available to the agent in the form of CFEngine classes so that the agent can check for and respond
-to anomalies dynamically.
-
-@item @code{cfkey}: Generates public-private key pairs on a host. You normally run this
-program only once, as part of the CFEngine software installation process.
-
-@item @code{cfshow}: Displays the @code{cfagent} database contents in ASCII format, should you ever
-become interested in its internal memory.
-
-@item @code{cfenvgraph}: Dumps @code{cfenvd}'s statistical database contents in a form
-that can be used to plot graphs showing the normal behavior of a host in its
-environment.
-@end itemize
-
-@image{cfdiag,10cm,,CFEngine Components and the Connections Between Them,png}
-
-This figure illustrates the relationships among CFEngine
-components on different hosts. On a given system, @code{cfagent} may
-be started by the @code{cfexecd} daemon; the latter also handles
-logging during @code{cfagent} runs. In addition, operations such as
-file copying between hosts are initiated by @code{cfagent} on the
-local system, and they rely on the @code{cfservd} daemon on the remote
-system to obtain remote data.
-
-
-@c **********************************************************************
-@node ITIL past and present, A meeting of mind-sets, CFEngine past and present, Top
-@chapter ITIL past and present
-
-
-The IT Infrastructure Library (ITIL) is a collection of books, in which
-``best practices'' for IT Service Management (ITSM) are described. Today,
-ITIL can be seen as a de-facto standard in the discipline of ITSM, for
-which it provides guidelines by its current core titles Service
-Strategy, Service Design, Service Transition, Service Operation and
-Continual Service Improvement. ITIL follows the principle of
-process-oriented management of IT services.
-
-In effect, the responsibilities for specific IT management decisions
-can be shared between different organizational units as the management
-processes span the entire IT organization independent from its
-organizational partition. Whether this means a centralization or
-decentralization of IT management in the end, depends on the concrete
-instances of ITIL processes in the respective scenario.
-
-
-@menu
-* ITIL and its versions::
-* Foundations::
-* Tool Support::
-@end menu
-
-@c **********************************************************************
-@node ITIL and its versions, Foundations, ITIL past and present, ITIL past and present
-@section ITIL and its versions
-
-ITIL has its roots in the early 1990s, and
-since then was subject to numerous improvements and enhancements.
-Today, the most popular release of ITIL is given by the books of ITIL version 2 (often referred to as ITILv2),
-while the British OGC (Office of Government Commerce), owner and publisher
-of ITIL, is currently promoting ITIL version 3 (ITILv3) under the device "`ITIL Reloaded"'.
-
-It is important to understand that ITILv3 is not just an improved version of
-the ITILv2 books, but rather comes with a completely renewed structure,
-new sets of processes and a different scope with respect to the issue of
-IT strategies, IT-business-alignment and continual improvement. That is why, in the following,
-we run through the basics of both versions, highlighting commonalities
-and differences.
-
-
-@menu
-* ITIL Important Foundations::
-* ITILv2 Service Support and Service Delivery::
-* ITILv3 Management from the Service Life Cycle Perspective::
-@end menu
-
-@node ITIL Important Foundations, ITILv2 Service Support and Service Delivery, ITIL and its versions, ITIL and its versions
-@subsection ITIL: Important Foundations
-
-It is the paradigm of process-oriented IT Service Management
-that ITIL is based on. In addition, ITIL uses the Deming quality
-circle as a model for continual quality improvement, where quality both
-relates to the provided IT services as well as the management processes
-deployed to manage these services. Continual improvement as to ITIL means
-to follow the method of Plan-Do-Check-Act:
-
-@itemize
-@item Plan: Plan the provision of high-quality IT services, set up the required management processes for the delivery and support of these services, define measurable goals and the course of action in order to fulfill them.
-@item Do: Put the plans into action.
-@item Check: Measure all relevant performance indicators, and quantify the achieved quality compared to the quality objectives. Check for potentials of improvement.
-@item Act: In response to the measured quality, start activities for future improvements. This step leads into the Plan phase again.
-@end itemize
-
-@c **********************************************************************
-@node ITILv2 Service Support and Service Delivery, ITILv3 Management from the Service Life Cycle Perspective, ITIL Important Foundations, ITIL and its versions
-@subsection ITILv2 Service Support and Service Delivery
-
-
-Although ITILv3 has been released during the summer of the year 2007,
-it is its predecessor that has achieved great acceptance amongst
-IT service providers all over the world. And due to the fact that the
-International ISO/IEC 20000 standard has emerged from the
-basic principles and processes coming from ITILv2, it is this version
-experiencing the biggest distribution and popularity.
-
-The core modules of ITILv2 are the books entitled Service Support
-and Service Delivery. While the Service Support
-processes (e.g. Incident Management, Change Management) aim at
-supporting day-to-day IT service operation, the Service Delivery
-processes (e.g. Service Level Management, Capacity Management,
-Financial Management) are supposed to cover IT service planning like
-resource and quality planning, as well as strategies for customer
-relationships or dealing with unpredictable situations.
-
-@c **********************************************************************
-@node ITILv3 Management from the Service Life Cycle Perspective, , ITILv2 Service Support and Service Delivery, ITIL and its versions
-@subsection ITILv3 Management from the Service Life Cycle Perspective
-
-In 2007, ITILv2 has been replaced by its successor ITILv3, aimed at
-covering the entire service life cycle from a management
-perspective and striving for a more substantiated idea of IT business alignment.
-Many of the ITILv2 processes and ideas have been recycled
-and extended by various additional processes and principles. The five
-service life cycle stages accordant to ITILv3 are:
-
-@enumerate
-@item Service Strategy: Common strategies and principles for customer-oriented, business-driven service delivery and management
-@item Service Design: Principles and processes for the stage of designing new or changed IT services
-@item Service Transition: Principles and processes to ensure quality-oriented implementation of new or changed services into the operational environment
-@item Service Operation: Principles and processes for supporting service operation
-@item Continual Service Improvement: Methods for planning and achieving service improvements at regular intervals
-@end enumerate
-
-The ITILv3 framework is sometimes reduced to the four Ps.
-
-@itemize
-@item Products (tools)
-@item People (humans)
-@item Partners (cooperation between parts of the organization)
-@item Processes (execution and verification)
-@end itemize
-
-
-@c **********************************************************************
-@node Foundations, Tool Support, ITIL and its versions, ITIL past and present
-@section Service orientation and ITIL
-
-Why service and process orientation? What is ITIL trying to do? As we mentioned
-in the introduction, the `military' control view of human organization fell from
-favour in business research in the 1980s and service oriented autonomy
-was identified as a new paradigm for levelling organizations --
-getting rid of deep hierarchies that hinder communication and open up
-communication directly.
-
-
-If one is cynical, one can interpret the signs of CEOs nervously
-trying to put back some of the military thinking into process
-management -- with definitions of authority and chains of
-responsibility, but these chains are short and whenever ITIL says
-``committee'', promise theory would say that all we need is a single
-agent (a human or computer) and the internal details of it don't
-matter. We should probably not think too literally about ITIL's choice
-of words, which after all were born from a particular kind of
-corporate culture and will not appeal to everyone.
-
-If we look at ITIL through the eyeglass of a hierarchical organization,
-some of its procedures could be seen as restrictive, throttling
-scalable freedoms. We do not believe
-that this is their intention. Rather ITIL's guidelines try to make a
-predictable and reliable face for business and IT operations so that
-customers feel confidence, without choking the creative process that
-lies behind the design of new services.
-
-@menu
-* CFEngine in ITIL clothes?::
-* ITIL processes::
-* Service Strategy::
-* Service Design::
-* Service Operation::
-* Continual Service Improvement::
-@end menu
-
-@c **********************************************************************
-@node CFEngine in ITIL clothes?, ITIL processes, Foundations, Foundations
-@subsection CFEngine in ITIL clothes?
-
-CFEngine users are interested in the ability to manage, i.e. cope with
-system configuration in a way that enables a business or other
-organization to do its work effectively. They don't want reams of
-human management because this is what CFEngine is supposed to
-remove. To be able to use ITIL to help in this task, we have to first
-think of the process of setting up as a number of services. What
-services are these? We have to think a little sideways to see the
-relationship.
-
-@itemize
-@item Service - providing a sensible configuration policy, responding to discovered problems or the needs of end-users.
-@item Change - an edit of the configuration policy, with appropriate quality controls.
-@item Release - a new configuration policy, consisting of many changes. A new version of CFEngine? This could be a major and disruptive change so it should be planned carefully.
-@item Capacity - having enough resources for cfservd to answer all queries in a network. Having enough people to support the processes of deploying and following CFEngine's progress.
-@end itemize
-
-You should keep this kind of thinking in mind, and train yourself to see every part
-of a task in ``ITIL clothes''.
-
-@c **********************************************************************
-@node ITIL processes, Service Strategy, CFEngine in ITIL clothes?, Foundations
-@subsection ITIL processes
-
-The following management processes are in scope of ITILv3:
-
-@itemize
-@item Service Level Management: Management of Service Level Agreements (Alas), i.e. service level and quality promises.
-@item Service Catalogue Management: deciding on the services that will be provided and how they
-are advertised to users.
-@item Capacity Management: Planning and provision of adequate business, service and resource capacities.
-@item Availability Management: Resource provision and monitoring of service, from a customer viewpoint.
-@item Continuity Management: Development of strategies for dealing with potential disasters.
-@item Information Security Management: Ensuring a minimum level of information security throughout the IT organization.
-@item Supplier Management: Maintaining supplier relationships.
-@item Transition Planning and Support: Ensuring that new or changed services are deployed into the operational environment with the minimal impact on existing services
-@item Asset and Configuration Management: Management of IT assets and Configuration Items.
-@item Release Management: Planning, building, testing and rolling out hardware and software configurations.
-@item Change Management: Assessment of current state, authorization and scheduling of improvements.
-@item Service Validation and Testing: ensuring that services meet their specifications.
-@item Knowledge Management: organizing and integrating experience and methodology for future reference.
-@item Incident Management: responding to deviations from acceptable service.
-@item Event Management: Efficient handling of service requests and complaints.
-@item Problem Management: Problem identification by trend analysis of incidents.
-@item Request Fulfillment: Fulfilling customer service requests.
-@item Access Management: Management of access rights to information, services and resources.
-@end itemize
-
-@c **********************************************************************
-@node Service Strategy, Service Design, ITIL processes, Foundations
-@subsection Service Strategy
-
-Service strategy is about deciding what services you want to
-formalize. In other words, what parts of your system administration tasks can you
-wrap in procedural formalities to ensure that they are carried out most excellently?
-
-@c **********************************************************************
-@node Service Design, Service Operation, Service Strategy, Foundations
-@subsection Service Design
-
-Service design is about deciding what will be delivered, when it will be delivered,
-how quickly the service will respond to the needs of its clients etc. This stage is probably
-something of a mental barrier to those who are not used to service-oriented thinking.
-
-@c **********************************************************************
-@node Service Operation, Continual Service Improvement, Service Design, Foundations
-@subsection Service Operation
-
-How shall we support service operation? What resources do we need to provide, both human
-and computer? Can we be certain of having these resources at all times, or is there
-resource sharing taking place? If services are chained into ``supply chains'', remember that
-each link of the chain is a possible delay, and a possible misunderstanding. Successfully running
-services can be more complex at task than we expect, and this is why it is useful to
-formalize them in an ITIL fashion.
-
-@c **********************************************************************
-@node Continual Service Improvement, , Service Operation, Foundations
-@subsection Continual Service Improvement
-
-Continual improvement is quite self-explanatory. We are obviously
-interested in learning from our mistakes and improving the quality and
-efficiency by which we respond to service requests. But it is
-necessary to think carefully about when and where to introduce this
-aspect of management. How often should we revise out plans and change
-procedures? If this is too often, the overhead of managing the quality
-becomes one of the main barriers to quality itself! Continual has to mean regular
-on a time-scale that is representative for the service being provided, e.g.
-reviews once per week, once per month? No one can tell you about your needs.
-You have to decide this from local needs.
-
-@c **********************************************************************
-@node Tool Support, , Foundations, ITIL past and present
-@section Tool Support
-
-In the field of tool support for IT Service Management accordant to
-ITIL, various white papers and studies have been published. In
-addition, there are papers available from BMC, HP, IBM and other
-vendors that describe specific (commercial) solutions. Generally, the
-market for tools is growing rapidly, since ITIL increasingly gains
-attention especially in large and medium-size enterprises. Today, it
-is already hard to keep track of the variety of functionalities
-different tools provide. This makes it even more difficult to approach
-this topic in a way satisfactory to the entire researchers', vendors'
-and practitioners' community.
-
-That is why this document follows a different approach: Instead of thinking
-of ever new tools and computer-aided solutions for ITIL-compliant IT Service
-Management, this book analyses how the existing and well-established
-technologies used for traditional systems administration can
-fit into an ITIL-driven IT management environment, and it guides
-potential practitioners in integrating a respective tool suite -- namely
-CFEngine -- with ITIL and its processes.
-
-To avoid any misunderstanding: We do not argue that CFEngine --
-originally invented for configuring distributed hosts -- may be
-deployed as a comprehensive solution for automating ITIL, but what we
-believe is CFEngine and its more recent innovations can @emph{bridge
-the gap} between the technology of distributed systems management and
-business-driven IT Service Management.
-To make the case we must show:
-
-@enumerate
-@item How ITIL terminology relates to the terminology of CFEngine and hence
-to a traditional system administrator's language, and
-@item Which parts (processes and activities) of
-ITIL can be (partially) supported by CFEngine, and how.
-@end enumerate
-
-These are the main goals of the subsequent chapters.
-
-
-
-@c **********************************************************************
-@node A meeting of mind-sets, Using CFEngine to implement ITIL objectives, ITIL past and present, Top
-@chapter ITIL and CFEngine comparison
-
-To summarize the results of the previous chapters, it can be said that
-the goals of ITIL and the purpose of CFEngine are quite different:
-ITIL gives recommendatory guidance in process- and service- oriented
-IT Service Management, while CFEngine provides a powerful solution
-framework for a variety of common network and systems administration
-tasks. In other words:
-
-@enumerate
-@item The scope of ITIL is much broader than traditional systems administration, but: Portions of systems administration and configuration management tasks take place in the context of certain ITIL processes.
-
-@item CFEngine was not designed to replace ITSM tools like trouble ticket systems (TTS), workflow management or CMDBs, but: in the more technical areas of IT Service Management, CFEngine is able to support ITIL processes in their activities.
-@end enumerate
-
-@image{scope2,10cm,,Scope of ITIL and CFEngine,png}
-
-The goal of this document is to give an overview on how CFEngine can
-be used to support selected IT Service Management tasks according to
-ITIL.
-
-
-@menu
-* Which ITIL processes apply to CFEngine?::
-* ITIL terminology::
-@end menu
-
-@c **********************************************************************
-@node Which ITIL processes apply to CFEngine?, ITIL terminology, A meeting of mind-sets, A meeting of mind-sets
-@section Which ITIL processes apply to CFEngine?
-
-@image{itilfcaps,10cm,,FCAPS and ITIL,png}
-
-In version 2, ITIL divides itself into @emph{service
-support} and @emph{service delivery}. For
-instance, service support might mean having a number of CFEngine
-experts who can diagnose problems, or who have sufficient knowledge
-about CFEngine to solve problems using the software. It could also
-mean having appropriate tools and mechanisms in place to carry out the
-tasks. Service delivery is about how these people make their knowledge
-available through formal processes, how available are they and how
-much work can they cope with? CFEngine enables a few persons to
-perform a lot of work very cheaply, but we should not forget to track our performance
-and quality for the process of continual improvement.
-
-Service support is composed of a number of issues:
-@itemize
-@item Incident management: collecting and dealing with incidents.
-@item Problem management: root cause analysis and designing long term countermeasures.
-@item Configuration management: maintaining information about hardware and software and
-their interrelationships.
-@item Change management: implementing major sequenced changes in the infrastructure.
-@item Release management: planning and implementing major ``product'' changes.
-@end itemize
-Although the difference between change management and release
-management is not completely clear in ITIL, we can think of a release
-as a change in the nature of the service, while change management
-deals with alterations possibly still within the scope of the same release.
-Thus is release is a more major change.
-
-Service delivery, on the other hand, is dissected as follows:
-@itemize
-@item Service Level Management
-@item Problem management
-@item Configuration management
-@item Change management
-@item Release management
-@end itemize
-These issues are somewhat clearer once we understand the usage of the
-terms ``problem'', ``service'' and ``configuration''. Once again, it
-is important that we don't mix up configuration management in ITIL
-with configuration management as used in a Unix parlance.
-
-The notion of system administration in the sense of Unix does not
-exist in ITIL. In the world of business, reinvented through the eyes
-of ITIL's mentors, system administration and all its functions are
-wrapped in a model of service provision.
-
-
-@menu
-* Configuration Management CM::
-* Asset Management what is it used for?::
-* Change management::
-* Change management vs convergence::
-* Release management::
-* Incident and problem management::
-* Service Level Management SLM::
-@end menu
-
-@c **********************************************************************
-@node Configuration Management CM, Asset Management what is it used for?, Which ITIL processes apply to CFEngine?, Which ITIL processes apply to CFEngine?
-@subsection ITIL Configuration Management (CM)
-
-Perhaps the most obvious example is the term configuration management.
-
-@table @i
-@item Configuration Management
-The process (and life-cycle) responsible for maintaining information
-about configuration items (CI) required to deliver an IT service,
-including their relationships.
-@end table
-
-As we see, this is comparable to our intuitive idea of ``asset
-management'', but with ``relationships'' between the items
-included. ITIL also defines ``Asset Management'' as ``a process
-responsible for tracking and reporting the value of financially valuable assets''
-and is a component of ITIL Configuration Management.
-
-In the CFEngine world, configuration management involves planning,
-deciding, implementing (``base-lining'') and verifying (``auditing'')
-the inventory. It also involves maintaining the security and privacy
-of the data, so that only authorized changes can be made and private
-assets are not made public.
-
-In this document we shall try not to mix the ITIL concept with the
-more prosaic system administration notion of a configuration which
-includes the current state of software configuration on the
-individual computers and routers in a network.
-
-Since CFEngine is a completely distributed system that deals with
-individual devices on a one-by-one basis, we must interpret this asset
-management at two levels:
-
-@itemize
-@item The local assets of an individual device at the level of virtual
-structures and containers within it: files, attributes, software packages,
-virtual machines, processes etc. This is the traditional domain of automation
-for CFEngine's autonomic agent.
-
-@item The collective assets of a network of such devices.
-@end itemize
-Since a single host can be thought of as a network of assets connected
-through virtual pathways, it really isn't such a huge leap to see the
-whole network in a similar light. This is especially true when many of the
-basic resources are already shared objects, such as shared storage.
-
-
-@c *******************************************************************'
-@node Asset Management what is it used for?, Change management, Configuration Management CM, Which ITIL processes apply to CFEngine?
-@subsection CMDB Asset Management
-
-Why bother to collect an inventory of this kind? Is it bureaucracy
-gone mad, or do we need it for insurance purposes? Both of these
-things are of course possibilities.
-
-The data in an ITIL Configuration Management Database (CMDB) can be
-used for planning the future and for knowing how to respond to
-incidents, in other words for service level management (SLM) and for
-capacity planning. An organization needs to know what resources it
-has to know whether its can deliver on its promises.
-Moreover, for finance and insurance it is clearly a sound policy to have a database of
-assets.
-
-For continuity management, risk analysis and redundancy assessment we
-need to know how much equipment is in use and how much can be brought
-in at a moment's notice to solve a business problem. These are a few
-of the reasons why we need to keep track of assets.
-
-@c ***********************************************************
-@node Change management, Change management vs convergence, Asset Management what is it used for?, Which ITIL processes apply to CFEngine?
-@subsection Change management in the enterprise
-
-If we make changes to a technical installation, or even a business
-process, this can affect the service that customers experience.
-Major changes to service delivery are often written into service level
-agreements since they could result in major disruptions.
-Details of changes need to be known by a help-desk and service personnel.
-
-
-The decision to make a change is more than a single person
-should usually. It requires consultation at different levels
-of process. An advisory board for changes takes on this role,
-whether it is an informal board that communicates electronically
-or a physical committee ``with six or more legs and no brain''.
-
-@c ***********************************************************
-@node Change management vs convergence, Release management, Change management, Which ITIL processes apply to CFEngine?
-@subsection Change management vs convergence
-
-We should be especially careful here to decide what we mean by
-change. ITIL assumes a traditional model of change management that
-CFEngine does not need. ITIL's ideas apply to the management of
-CFEngine's configuration, not the way in which CFEngine carries out its
-work.
-
-In traditional idea of change management you start by ``base-lining'' a
-system, or establishing a known starting configuration. Then you
-assume that things only change when you actively implement a change,
-such as ``rolling out a new version'' or committing a release. This,
-of course, is very optimistic.
-
-In most cases all kinds of things change beyond our control. Items are
-stolen, things get broken by accident and external circumstances
-conspire to confound the order we would like to preserve. The idea
-that only authorized people make changes is nonsense.
-
-CFEngine takes a different view. It thinks that changes in
-circumstances are part of the picture, as well as changes in inventory
-and releases. It deals with the idea of ``convergence''. In this way
-of thinking, the configuration details might be changing at random in
-a quite unpredictable way, and it is our job to continuously monitor
-and repair general dilapidation. Rather than assuming a constant state
-in between changes, CFEngine assumes a constant ``ideal state'' or
-@emph{goal} to be achieved between changes. An important thing to realize about including
-changes of external circumstances is that you cannot ``roll back''
-circumstances to an earlier state -- they are beyond our control.
-
-@c ***********************************************************
-@node Release management, Incident and problem management, Change management vs convergence, Which ITIL processes apply to CFEngine?
-@subsection Release management
-
-A @emph{release} is a collection of authorized changes to a system.
-One part of Change Management is therefore @emph{Release Management}.
-A release is generally a larger umbrella under which many smaller
-changes are made. It is major change.
-Changes are assembled into @emph{releases} and then they are rolled out.
-
-In fact release management, as described by ITIL, has nothing to do
-with change management. It is rather about the management of
-designing, testing and scheduling the release, i.e. everything to do with
-the release process except the explicit implementation of it.
-@emph{Deployment} or @emph{rollout} describe the physical movement of
-configuration items as part of a release process.
-
-
-
-@node Incident and problem management, Service Level Management SLM, Release management, Which ITIL processes apply to CFEngine?
-@subsection Incident and problem management
-
-ITIL distinguishes between @emph{incidents} and @emph{problems}. An incident is
-an event that might be problematic, but in general would observe
-incidents over some length of time and then diagnose @emph{problems} based
-on this experience.
-
-@table @i
-@item Incident
-An event or occurrence that demands a response.
-@end table
-
-One goal of CFEngine is to plan pro-actively to handle incidents
-automatically, thus taking them off the list of things to worry about.
-
-@table @i
-@item Problem
-A pattern of consequence arising from certain incidents that is detrimental
-to the system. It is often a negative trend that needs to be addressed.
-@end table
-
-
-Changes can introduce new incidents.
-An integrated way to make the tracking of cause and effect easier is
-clearly helpful. If we are the cause of our own problems, we are in
-trouble!
-
-
-@c ***********************************************************
-@node Service Level Management SLM, , Incident and problem management, Which ITIL processes apply to CFEngine?
-@subsection Service Level Management (SLM)
-
-Also loosely referred to as Quality of Service. This is the
-process of making sure that Service Level Promises are kept,
-or Service Level Agreements (SLA) are adhered to.
-We must assess the impact of changes on the ability to deliver
-on promises.
-
-
-@node ITIL terminology, , Which ITIL processes apply to CFEngine?, A meeting of mind-sets
-@section ITIL terminology
-
-Like many other areas of wishful standardization, ITIL elevates itself
-to a state of importance by using multitude of acronyms and
-specialized terms. Not all of these are as intuitive as one might
-hope for and many simply seem beyond necessity. However, to understand
-the writing, we need to know a few of them and also understand how
-they differ from similar terms in system administration and the world
-of CFEngine. In the appendix, we list with comments about the most important
-of these terms. The figure shows a scatter-plot of these terms.
-
-
-@image{topic,10cm,,ITIL terminology,png}
-
-@c ***********************************************************
-@node Using CFEngine to implement ITIL objectives, Summary, A meeting of mind-sets, Top
-@chapter Using CFEngine to implement ITIL objectives
-
-How does CFEngine fit into the management of a service organization?
-There are several ways:
-@itemize
-@item It offers a rapid detection and repair of faults that help to avoid formal incidents.
-@item It simplifies the deployment (release) of services.
-@item Allows resources to be understood and planned better.
-@end itemize
-These properties allow for greater @emph{predictability}
-of system services and therefore they contribute to customer confidence.
-
-
-@menu
-* Infrastructure or management?::
-* How can CFEngine or promises help?::
-* What is maintenance?::
-* Incident Management vs Maintenance::
-* Rollout and installation::
-* Change Management in ITIL::
-* Release Management in ITIL::
-* Configuration version control and rollback::
-* Availability and Capacity Management::
-@end menu
-
-@node Infrastructure or management?, How can CFEngine or promises help?, Using CFEngine to implement ITIL objectives, Using CFEngine to implement ITIL objectives
-@section Infrastructure or management?
-
-Any tool for assisting with change management lies somewhere between
-ITIL's notion of change management and the infrastructure itself. It
-must essentially be part of both (see figure). This applies
-to CFEngine too.
-
-
-@image{cfinf,10cm,,CFEngine is both infrastructure and a part responsible for infrastructure.,png}
-
-
-CFEngine can manage itself as well as other resources: itself, its
-software, its policy and the resulting plans for the configuration of
-the system. In other words, CFEngine is itself part of the infrastructure
-that we might change.
-
-@c ***********************************************************
-@node How can CFEngine or promises help?, What is maintenance?, Infrastructure or management?, Using CFEngine to implement ITIL objectives
-@section How can CFEngine or promises help an enterprise
-
-@menu
-* Traditions::
-* Modelling of policy::
-* Uniformity::
-@end menu
-
-@c ***********************************************************
-@node Traditions, Modelling of policy, How can CFEngine or promises help?, How can CFEngine or promises help?
-@subsection Traditional IT Management
-
-Traditional methods of managing IT infrastructure involve working from
-crisis to crisis -- waiting for `incidents' to occur and then initiating fire
-suppression responses or, if there is time, proactive changes. With CFEngine,
-these can be combined and made into a management @emph{service}, with
-continuous service quality.
-
-CFEngine can assist with:
-@enumerate
-@item Maintenance assurance.
-@item Reporting for auditing.
-@item Change management.
-@item Security verification.
-@end enumerate
-
-Promise theory comes with a couple of principles:
-@enumerate
-@item Separation of concerns.
-@item Fundamental attention to autonomy of parts.
-@end enumerate
-
-@c ***********************************************************
-@node Modelling of policy, Uniformity, Traditions, How can CFEngine or promises help?
-@subsection Modelling policy
-
-Other approaches to discussing organization talk about the separation
-of concerns, so why is promise theory special? Object Orientation
-(OO) is an obvious example. Promise theory is in fact quite different to
-object orientation (which is a misnomer).
-
-Object orientation asks users to model abstract classes (roles) long
-before actual objects with these properties exist. It does not provide
-a way to model the instantiated objects that later belong to those
-classes. It is mainly a form of information structure
-modelling. Object orientation models only abstract patterns, not
-concrete organizations.
-
-Promise theory on the other hand considers only actual existing objects
-(which it calls agents) and makes no presumptions that any
-two of these will be similar. Any patterns that might emerge can be
-exploited, but they are not imposed at the outset. Promise theory's
-insistence on autonomy of agents is an extreme viewpoint from which
-any other can be built (just as atoms are a basic building block from which
-any substance can be built) so there is no loss of generality by making
-this assumption.
-
-In other words, OO is a design methodology with a philosophy, whereas
-promises are a model for an arbitrary existing system.
-
-@node Uniformity, , Modelling of policy, How can CFEngine or promises help?
-@subsection Uniformity
-
-The traditional production-line paradigm for management of IT systems
-involves reducing the number of variations -- often simply making
-all systems identical for mass-production. However, as quoted at the
-beginning of chapter 2, the purpose of advanced technology is to
-enable us to cope with variation. CFEngine makes managing variations simple.
-Some organizations might simply want to have a uniform configuration on
-all their hardware, but what does this mean if the basic hardware is
-different?
-
-In CFEngine we understand that ``similar'' should be based on how
-systems behave not what their disk images look like. Two systems that
-make the same promises ought to behave in the same way, if the promises
-are at a high enough level. But what if two different operating systems
-promised to never have a file called @code{/etc/passwd}? A windows machine
-would not care too much, but a Unix system would be paralyzed.
-
-Promises and system configuration are related: configuration affects
-behaviour and behaviour is what we promise. Clearly we cannot expect
-very high level promises to be simply translated into configurations
-however. The fact that we make promises about system configuration
-says nothing certain about the promise that results from changing
-it. That depends on many other factors. Thus we must be careful to think about
-what a promise means.
-
-@table @i
-@item Fundamental assumption
-The basic assumption of configuration management is that a specific
-configuration determines the resulting behaviour of a system. This
-assumption is completely unproven, and is sometimes obviously false.
-At best there is a correlation between configuration and
-behaviour. This is what makes IT management challenging. The things we
-can change do not necessarily give us the control we would like.
-@end table
-
-
-@c ***********************************************************
-@node What is maintenance?, Incident Management vs Maintenance, How can CFEngine or promises help?, Using CFEngine to implement ITIL objectives
-@section What is maintenance?
-
-Maintenance is a process that ITIL does not formally spend any time
-on explicitly, but it is central to real-world quality control.
-
-Imagine that you decide to paint your house. Release 1 is going to be
-white and it is going to last for 6 years. Then release 2 is going to
-be pink. We manage our painting service and produce release
-1 with all of the care and quality we expect. Job done? No.
-
-It would be wrong for us to assume that the house will stay this fine
-colour for 6 years. Wind, rain and sunshine will spoil the paint over
-time and we shall need to touch up and even repaint certain areas in
-white to maintain release 1 for the full six years. Then when it is time
-for release 2, the same kind of maintenance will be required for that too.
-
-Unless we read between the lines, it would seem that ITIL's answer to
-this is to wait for a crisis to take place (an incident). We then
-mobilize some kind of response team. But how serious an incident do we
-require and what kind of incident response is required? A graffiti artist?
-A lightening strike? A bird anoints the paint-work? CFEngine is
-like the gardener who patrols the grounds constantly plucking weeds,
-before the flower beds are overrun. Call it continual improvement if
-you like: the important thing is that the process your be pro-active
-and not too expensive.
-
-Maintenance is necessary because we do not control all of the
-changes that take place in a system. There is always some kind of
-``weather'' that we have to work against. CFEngine is about this
-process of Maintenance. We call it ``convergence'' to the ideal state,
-where the ideal state is the specified version release.
-Keep this in mind as you read about ITIL change management.
-
-@c ***********************************************************
-@node Incident Management vs Maintenance, Rollout and installation, What is maintenance?, Using CFEngine to implement ITIL objectives
-@section Incident Management vs Maintenance
-
-CFEngine employs the idea of continual maintenance (we paint the fence
-on a regular basis to protect it). ITIL, on the other hand, moves from
-release to release (this year we paint the fence red, next year green)
-and does not recognize the effect of gradual entropic decay of state
-(the fence's colour fades gradually due to the harsh
-environment). Instead ITIL deals with events (graffiti and tagging of
-the fence) which must be corrected. While it is true that these
-incidents are maintenance, the repairs are more costly to initiate if
-they occur as exceptional events than if we are used to repainting the
-fence on a regular basis.
-
-
-@image{cf_evm,10cm,,An exemplary Event Management process on the basis of ITIL V3,png}
-
-The figures above show ITIL processes for the handling of
-events and incidents. They show the aspects of dealing with events that are
-mainly human oriented, and those events in shaded boxes that can be automated
-using CFEngine.
-
-In the figure above we see that there must be a basic monitor at
-the top of the process chain which is responsible for observing
-events. This fits well with the view of promise theory in which a
-neutral observer is required to measure the state of different
-component agents in the system. Not all events are necessarily
-relevant or interesting so we can filter these based on a
-policy. CFEngine's event monitors come from two sources: cfagent (for
-monitoring the state of promises which are being managed - e.g. the
-proverbial colour of the fence) and cfenvd (for passively monitoring
-the environment - e.g. the brightness of the sunshine or the amount of
-rainfall impacting on the fence).
-
-@itemize
-@item CFEngine filters events through its
-class interface. All events observed in CFEngine are @emph{classified}
-and made available to the environment.
-
-@item CFEngine logs events by routing messages to email or to syslog (by asking
-@code{inform=true} or @code{syslog=true} or @code{audit=true}).
-
-@item The daemon @code{cfenvd} auto-correlates events. The tool @code{cfbrain}
-will cross correlate events, further classifying the outcomes as part of the
-environment.
-
-@item Events can be triggered by attaching promises to event-driven classes
-in the cfagent configuration. e.g.
-
-@smallexample
-
-processes:
-
- www_in_high_anomaly::
-
- ``apache'' signal=term
-
-alerts:
-
- www_in_high_anomaly::
-
- ShowState(www.in)
-
-@end smallexample
-For more devastating incidents, we can arrange for more information to
-be output. An incident is really only an event of some special
-significance. Diagnosing an incident requires either human
-intervention or pre-cached insight on the part of the promises we
-make. If we can make a specific promise then the diagnosis that this promise
-has not been kept can easily be turned into a specific repair. For example,
-
-We might note a sudden burst of smtp traffic, or a sudden decrease in free disk space.
-These events can be anticipated if one knows a benign cause, such as email
-was shutdown for maintenance, or the host is a new mail-server that has never seen
-traffic before.
-
-@end itemize
-
-@image{cf_im,10cm,,An exemplary Incident Management process on the basis of ITIL V3,png}
-
-@c ***********************************************************
-@node Rollout and installation, Change Management in ITIL, Incident Management vs Maintenance, Using CFEngine to implement ITIL objectives
-@section Rollout and installation
-
-When setting up hosts, ITIL actually makes a techical recommendation.
-This is unusual for ITIL as it generally does not get mixed up in the
-details of management, only the processes. ITIL recommends
-``base-lining'' systems from a @emph{gold server}, i.e. a system that is
-thought to be ``perfect'' enough to act as a model for all other
-systems. Once a server has been base-lined from the golden image,
-various customizations can be made relative to this known state. ITIL
-sees this as a way of achieving consistency.
-
-We believe that ITIL exceeds its technical competence in making this a
-recommendation. True enough, this has traditionally been a way of
-performing a rollout, but the approach has been superceded by better
-technology. The gold server approach is not the recommended CFEngine
-way. In fact a golden-image approach wastes a fundamental flexibility
-that CFEngine offers, namely the possibility to allow @emph{variations} (see
-the quote by Alvin Toffler at the start of chapter 2).
-
-When we baseline a system from a gold-server, we are planning to make all
-hosts basically the same. However, this is neither necessary nor cost-saving
-if you use CFEngine.
-
-CFEngine places no restrictions on the approach used to roll out
-hosts. Rather than requiring you to start from a known state, it
-allows you to specify the @emph{final} state for any initial
-state. This means you can migrate hosts gradually to a policy state
-without having to reinstall them. We can consider the end result of a
-CFEngine policy process to be ``the release''. In CFEngine this is
-equivalent to a sufficiently comprehensive configuration policy.
-
-The message here is that CFEngine allows you to achieve predictable
-results without the need for a gold server. Nevertheless, it is helpful
-to begin a system based on a reliable substrate. It is like making a good
-sandwich: it helps to have a perfect piece of bread to build on, but it's what
-you put on top that is most important. You just need to know what you are starting
-with, and then most things can be fixed to satisfaction.
-We recommend:
-
-@itemize
-@item Start with some kind of standard image to start (a predictable substrate).
-
-It is does not necessarily matter what it is as long as it behaves predictably.
-e.g. install from known DVD, or install from net-boot or even from a gold server.
-
-@item Customize the basic working system using CFEngine.
-There are two possible approaches to this:
-
-i) Copy constant ``gold'' overlays or patches into place from a trusted source
-to customize the system.
-
-@itemize
-@item Add more operating system packages.
-@item Insert special files (config, data etc).
-@item Run post-processing scripts.
-@end itemize
-
-ii) Edit system directly with CFEngine
-@itemize
-@item Documented automatically by cfagent promises.
-@item Can always customize after that too (phase 3)!
-@end itemize
-@end itemize
-
-
-
-@menu
-* Customize by constant fixed overlay::
-* Overlay an expandable template::
-* Direct customization::
-@end menu
-
-@c ***********************************************************
-@node Customize by constant fixed overlay, Overlay an expandable template, Rollout and installation, Rollout and installation
-@subsection Customize by constant/fixed ``gold'' overlay
-
-The first alternative is to install a fixed patch to a system
-from a known gold-server.
-The basic pattern is this:
-
-
-@smallexample
-copy:
-
- /source/file
-
- dest=/dest/file
- server=gold_server
-@end smallexample
-
-In this example, we simply install a new file into a known location.
-This is the simplest way of customizing a host, but it lacks flexibility.
-
-@c ***********************************************************
-@node Overlay an expandable template, Direct customization, Customize by constant fixed overlay, Rollout and installation
-@subsection Overlay an expandable template with CFEngine
-
-A more sophisticated approach is to download a parameterized template
-from a repository or gold server. This template contains context
-dependent variables that can be expanded in situ by CFEngine. There
-are two stages to this: first we copy the template to a temporary
-location, then we edit the final file location, insert the template
-and expand its variables. By following this procedure, the result
-satisfies CFEngine's principles of @emph{convergence}.
-
-
-@smallexample
-copy:
-
-/source/file
- dest=/tmp/file
- server=gold_server
-
-editfiles:
-
-@{ /dest/file
-
-EmptyEntireFilePlease
-InsertFile ``/tmp/file''
-ExpandVariables
-@}
-@end smallexample
-
-
-@c ***********************************************************
-@node Direct customization, , Overlay an expandable template, Rollout and installation
-@subsection Direct customization by CFEngine
-
-A final approach to customization is to apply direct
-editing operations to implement the required customization.
-
-@smallexample
-editfiles:
-
-@{ /dest/file
-
-ReplaceAll ``X'' With ``Y''
-AppendIfNoSuchLine ``ABC''
-@}
-@end smallexample
-
-This approach is useful for small corrections, that require
-unsophisticated editing, but it becomes quickly cumbersome
-for more complex tasks.
-
-
-@node Change Management in ITIL, Release Management in ITIL, Rollout and installation, Using CFEngine to implement ITIL objectives
-@section Change Management in ITIL
-
-ITIL proposes that there should be an integrated approach to change and
-configuration management. Clearly changes to a system result in new
-configurations. However, changes can also be unplanned involuntary
-faults (ITIL discusses these as @emph{incidents}).
-
-
-ITIL does not want unplanned changes, however we know that they happen.
-CFEngine does not elevate deviations from policy to the level of an
-incident normally, it simply fixes problems immediately. However, we do not
-alway have enough information about changes to allow CFEngine to make repairs,
-so we need a way of monitoring for unexpected change.
-
-
-Change management in CFEngine is a subtle topic, because CFEngine does
-not fully subscribe to the model of change that ITIL does. In CFEngine's
-view of the world, all changes are changes no matter how or why they
-occur. In ITIL's world view, there are planned changes, there are
-releases and there are ``incidents''.
-
-ITIL therefore distinguishes between planned and unplanned changes that
-affect service delivery. CFEngine on the other hand cares only about
-what promises have been made about the system and whether or not these
-have been kept.
-
-CFEngine can detect changes because it effectively performs a constant
-audit of the system's promises. We should understand CFEngine's change
-detection in two ways: changes that impact the performance or quality
-of services
-
-@itemize
-@item with respect to the quality of the system configuration service (i.e. CFEngine's service)
-@item with respect to the quality of services supported by the system configurations (e.g. other services
-like web services)
-@end itemize
-To CFEngine, changes only matter if they impact the promises that have
-been codified as policy. Even events that CFEngine calls ``anomalies'',
-detected and classified continuously, are only considered
-interesting if policy determines them to be restricted, thus every
-single state change can be considered either ``within tolerances''
-(insignificant) or ``out of tolerance'' (significant). ITIL is only a
-heuristic set of guidelines and is not technically sophisticated
-enough to be able to make this kind of distinction.
-
-Let's make an approximate mapping between ITIL concepts and CFEngine change
-and the comment critically on it.
-
-@table @i
-@item ITIL
- CFEngine
-@item Incident
-Promise not kept
-@item Change
-Configuration version/content update
-@item Release
-Policy change
-@end table
-
-@menu
-* Software packaging::
-* Rollback or remediation::
-* Monitoring file changes::
-* Hashes and Message Digests::
-* Computing hashes::
-* Neighbourhood watch and tampering::
-@end menu
-
-@c ***********************************************************
-@node Software packaging, Rollback or remediation, Change Management in ITIL, Change Management in ITIL
-@subsection Software packaging in ITIL
-
-ITIL considers releases to be entire integrated systems that are
-versioned. Most operating systems work at a smaller level of
-granularity than this. Software version control using package
-managers to version individual software packages. Although such
-package managers resolve dependencies, they do not version
-entire conglomerates of software. Software comes in large
-packages for two main reasons:
-
-@itemize
-@item Operating system installation (all or nothing).
-@item Functional role adaptation (specialized workstation).
-@end itemize
-Different organizational roles require different ITIL services
-to support them, and hence different software to deliver them.
-
-CFEngine deals with versioned data management in two ways:
-@itemize
-@item File copying from master source (by date-stamp or checksum).
-@item Package installation and verification (using local package managers).
-@end itemize
-Package managers handle the installation and update of packages
-easily, but they do not always add institutional adaptational
-control in a way that can be tied into a classification of
-hosts in an organization's network. CFEngine can use its
-classification of hosts to customize further. We simply
-attach relevant clusters of packages to different classes
-of host to ensure that specific workstations are
-properly adapted to service their tasks.
-
-Not all software comes in operating system (vendor/provider)
-approved packages, but CFEngine can also handle software
-that is zipped, tar-ed or bundled in any other manner.
-
-The following example policies illustrates some of the @code{copy} rule type's capabilities,
- including some of the options we just considered:
-
-
-@smallexample
-
-control:
- DefaultCopyType = ( mtime )
- SplayTime = ( 15 )
- sourcehost = ( source.CFEngine.org )
-
-copy:
-# Copy dat/doc files if not too big
- /usr/local/data dest=/archive/data
- include=*.dat include=*.doc exclude=test.*
- recurse=inf backup=false size<500m
-
-# Retrieve configuration file from master
- /depot/hosts.deny server=$(sourcehost)
- dest=/etc/hosts.deny owner=root group=0 mode=644
- backup=off force=on timestamps=keep
-
-# Transmit shadow password file encrypted
- /depot/shadow server=\$(sourcehost) dest=/etc/shadow
- owner=0 group=0 mode=600 encrypt=true
-@end smallexample
-
-
-The first rule specifies that @file{.dat} and @file{.doc} files within the
-@file{/usr/local/data} directory tree be copied to @file{/archive/data},
-provided that the source files have been modified more recently then
-their counterpart in the target directory and that they are smaller than 500 MB. In addition, files having
-the name @file{test} are also excluded. Existing files will be overwritten without being saved.
-
-The second rule unconditionally replaces the local
-@file{/etc/hosts.deny} file with one from the system
-@code{source.CFEngine.org}, retaining the timestamps from the source
-file. This rule also specifies the ownership and mode for the target
-file.
-
-The third rule is similar to the second one, retrieving another file
-from the same remote system. In this case, however, the file will be
-copied only when the remote file is more recent than the local
-copy. When the file is copied, the previous version will be retained,
-and the file contents will be encrypted at it is transmitted across
-the network.
-
-
-CFEngine can also automate software package management and
-installation. Policies for these items are specified in the @code{packages} stanza. Here are some examples:
-
-
-@smallexample
-
-control: # Define package manager \& install command
- linux:: DefaultPkgMgr = ( rpm )
- redhat:: RPMInstallCommand = ( "/usr/sbin/up2date %s" )
- suse:: RPMInstallCommand = ( "/usr/sbin/yast2 -i %s" )
-
-packages:
- nagios version=2.4 cmp=ge
- pstree action=install
-@end smallexample
-
-
-The settings in the @code{control} section specify the package
-management software that is in use as well as the command used to
-install a software package. These directives illustrate the use of
-operating system-based classes within policies for defining a
-different installation command for different Linux distributions.
-
-In the @code{packages} stanza, the first rule checks whether Nagios is
-installed. A warning will be generated if the package is not present
-at all or if the installed version is earlier than version 2.4. The
-second rule checks for the @code{pstree} package, and installs it if
-it is not present on the system.
-
-The following parameterized method-promise installs
-its first argument in the prefixed location given by the second
-argument. It collects the tar file, unpacks it, configures and
-compiles it, then tidies its files.
-
-
-@smallexample
-
-#
-# Build GNU sources and install
-#
-
-control:
-
- actionsequence = ( methods )
-
-methods:
-
- InstallTar(CFEngine-2.1.0b7,/local/gnu)
-
- action=cf.install
- returnvars=null
- returnclasses=null
- server=localhost
-
-@end smallexample
-
-
-We must install the method in the trusted modules directory (normally
-@code{/var/cfengine/modules} or WORKDIR/modules).
-
-
-@smallexample
-
-#
-# cf.install
-#
-
-control:
-
- MethodName = ( InstallTar )
- MethodParameters = ( filename prefix )
- path = ( /usr/local/gnu/bin )
- TrustedWorkDir = ( /tmp )
- TrustedSources = ( /depot )
- TrustedSourceServer = ( localhost )
-
- actionsequence = ( copy editfiles shellcommands tidy )
-
-copy:
-
- $(TrustedSources)/$(filename).tar.gz
- dest=$(TrustedWorkDir)/$(filename).tar.gz
- server=$(TrustedSourceServer)
-
-shellcommands:
-
- "$(path)/tar zxf $(filename).tar.gz" chdir=$(TrustedWorkDir)
-
- "$(TrustedWorkDir)/$(filename)/configure --prefix=$(prefix)"
- chdir=$(TrustedWorkDir)/$(filename)
- define=okay
-
- okay::
-
- "$(path)/make"
- chdir=$(TrustedWorkDir)/$(filename)
-
-tidy:
-
- $(TrustedWorkDir) pattern=$(filename) r=inf rmdirs=true age=0
-
-@end smallexample
-
-@c ***********************************************************
-@node Rollback or remediation, Monitoring file changes, Software packaging, Change Management in ITIL
-@subsection Rollback or remediation
-
-The ability to go back to an earlier ``release'' or state is often
-referred to as rollback. ITIL calls it remediation. The notion is
-closely connected with process management, and both ITIL and
-traditional management techniques value this by default. It is assumed
-practice.
-
-CFEngine does not encourage rollback however. Why not? Because it
-required destructive intervention and CFEngine's model is based on
-on-the-fly change. To go back to a previous state, a system must be
-stopped, reinitialized (perhaps from backup) and restarted. This
-requires service to stop and all run-time state is lost.
-
-CFEngine's approach to this would be to revert @emph{policy} to its
-previous state. The system would then roll into its desired state (as
-if going forwards). Nothing would be restored from separate backup
-media (see figure).
-
-@image{roll-forward,15cm,,Move from one fixed point to another and back.,png}
-
-The difference here is the assumption about how and when changes
-occur. A sequence of step by step transitions sounds innocent, but it
-is unstable to unexpected changes. ITIL and many other change
-management models assumes that no unauthorized changes occur between
-releases. If they do, they are handled as incidents. By separating
-releases from incidental changes, we get led into thinking that
-we can in fact revert by destructive intervention.
-
-In fact reversion has inevitable consequences. We must make a choice.
-
-@itemize
-@item Revert entire state, except we lose runtime state.
-
-In this case, we essential revert the entire system from a back up of
-its saved state. (Some virtual machines can save runtime state for
-resumption, but this can become stale, e.g. for network connections,
-as it is meaningless to rollback part of a dialogue.) This operation
-results in catastrophic change.
-
-@item Revert managed state, on the fly.
-
-This is CFEngine's default behaviour. To go back to a previous state,
-simply change the policy back to a previous version. This will not
-necessarily revert the entire state of the system, but everything that
-is covered by policy will be reverted.
-@end itemize
-
-Some tools allow you to rollback without reverting from
-backup. CFEngine disallows this on principle as it requires
-human judgement to perform correctly. It cannot be automated without
-uncertain results. In fact CFEngine
-retains the necessary information to allow managed changes to be
-reversed to some extent. The point however is that one can only
-guarantee the content of managed objects, so simply reversing a change
-will not necessarily take us back to the same state -- so we consider this
-to be fundamentally too risky.
-
-@c ***********************************************************
-@node Monitoring file changes, Hashes and Message Digests, Rollback or remediation, Change Management in ITIL
-@subsection Monitoring file changes
-
-CFEngine can monitor absolute and relative states
-of a system. A simple way to measure relative change is
-to use a database of checksums.
-
-@smallexample
-control:
-
- ChecksumUpdates = ( true )
- ChecksumPurge = ( true )
-
-files:
-
- /my/important/files
-
- recurse=inf
- checksum=md5
- owner=root,daemon
- group=0,1,4
-@end smallexample
-
-
-Change monitoring is about detecting when stored data, or other
-measurable aspects of a computer system change. A change detection
-system is not normally concerned with the reason for a change, but if
-you are monitoring for change then we shall take it for granted
-somehow that you are expecting to find changes that you didn't plan
-for yourself.
-
-@c ***********************************************************
-@node Hashes and Message Digests, Computing hashes, Monitoring file changes, Change Management in ITIL
-@subsection Hashes and Message Digests
-
-The most important bulk of information on a computer is its filesystem
-data. Change detection for filesystems uses a technique made famous in
-the program Tripwire, which collects a ``snapshot" of the system in the
-form of a database of file checksums (cryptographic hashes) and
-permissions and rechecked the system against this database at regular
-intervals. Tripwire examines files, and looks for change in their
-contents or their attributes. This is a very simple (even simplistic)
-view of change. If a legitimate change is made to the system, such a
-system responds to this as a potential threat. Databases must then be
-altered, or rebuilt.
-
-A cryptographic hash (also called a @i{digest}) is an algorithm that
-reads (digests) a file and computes a single number (the hash value)
-that is based on the contents. If so much as a single bit in the file
-changes then the value of the hash will change. You can compute
-hash values manually, for example:
-
-@smallexample
-
-host$ openssl md5 CFEngine-2.2.4a.tar.gz
-MD5(CFEngine-2.2.4a.tar.gz)= 6d2b31c4814354c65cbf780522ba6661
-
-@end smallexample
-
-There are several kinds of hash function. The most common ones are MD5
-and SHA1. Recently both of the algorithms that create these hashes
-have been superceded by the newer SHA2. CFEngine supports MD5 and SHA1
-and it will support SHA2 as soon as the OpenSSL library supports an
-interface to the new algorithm.
-
-@c ***********************************************************
-@node Computing hashes, Neighbourhood watch and tampering, Hashes and Message Digests, Change Management in ITIL
-@subsection Computing hashes or digests
-
-CFEngine has adopted something like the Tripwire model, but with a few
-provisoes. Tripwire assumes that all change is unauthorized (it makes
-an incident out of any observed change). CFEngine cannot reasonably take this viewpoint. CFEngine expects
-systems to change dynamically, so it allows users to define a policy
-for what changes are considered to be okay.
-
-Integrity checks on files whose contents are supposed to be static are
-a good way to detect tampering with the system, from whatever
-source. Running MD5 or SHA1 checksums of files regularly provides us
-with a way of determining even the smallest changes to file contents.
-
-To use the checksum based change detection we first ask CFEngine to
-collect MD5 hash data for specified files. Here is an excerpt from a
-CFEngine configuration program that would check the /usr/local
-filesystem for file changes. Note that it excludes files such as log
-files that we therefore allow to change (log files are supposed to
-change):
-
-@smallexample
-files:
-
- /usr/local owner=root,bin,man
- mode=o-w # check permissions separately
- r=inf
- checksum=best # switch on change detection
- action=warnall
- ignore=logs
- exclude=*.log
-
- # repeat for other files or directories
-
-@end smallexample
-
-The first time we run this, CFEngine collects data and treats all files
-as ``unchanged''. It builds a database of the checksums. The next time the
-rule is checked, cfagent recomputes the checksums and compares the new values
-to the `reference' values stored in the database. If no change has occurred,
-the two should match. If they differ, then the file as changed and a warning
-is issued.
-
-@smallexample
-cf:nexus: !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-cf:nexus: SECURITY ALERT: Checksum (md5) for /etc/passwd changed!
-cf:nexus: !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@end smallexample
-
-This message is designed to be visible. If you do not want the embracing
-rows of `!' characters, then this control directive turns them off:
-
-@smallexample
-control:
-
- Exclamation = ( off )
-@end smallexample
-The next question to ask is: what happens if the change that was
-detected is actually okay (which is almost always the case in practice).
-If you activate this option:
-@smallexample
-control:
-
- ChecksumUpdates = ( on )
-@end smallexample
-Then, as soon as a change has been detected, the database is updated
-and the message will not be repeated. If this is set to @code{off},
-which is the default, then warning messages will be printed each time
-the rule is checked.
-
-New files are automatically detected, as they are not in the database.
-If you want to be notified when files are deleted, then set the option
-
-@smallexample
-control:
-
- ChecksumPurge = ( on )
-@end smallexample
-
-@c ***********************************************************
-@node Neighbourhood watch and tampering, , Computing hashes, Change Management in ITIL
-@subsection Neighbourhood watch and tampering
-
-Message digests are supposed to be unbreakable, tamperproof
-technologies, but of course everything can be broken by a sufficiently
-determined attacker. Suppose someone wanted to edit a file and alter
-the CFEngine checksum database to cover their tracks. If they had
-broken into your system, this is potentially easy to do. How can we
-detect whether this has happened or not?
-
-A simple solution to this problem is to use another checksum-based
-operation to copy the database to a completely different host. By using
-a copy operation based on a checksum value, we can also remotely detect
-a change in the checksum database itself.
-
-Consider the following code:
-
-@smallexample
-# Neighbourhood watch
-
-control:
-
- allpeers = (
- SelectPartitionNeighbours(/path/hostlist,\#,random,4)
- )
-
-copy:
-
- /var/cfengine/checksum\_digests.db
-
- dest=/safekeep/chkdb_$(this)
- type=checksum
- server=$(allpeers)
- inform=true # warn of copy
- backup=timestamp
- define=tampering
-
-alert:
-
- tampering::
-
- 'Digest tampering detected on a peer'
-@end smallexample
-
-
-It works by building a list of neighbours for each host. The function
-@smallexample
-SelectPartitionNeighbours
-@end smallexample
-can be used for this. Using a file which
-contains a list of all hosts running CFEngine (e.g. the @code{cfrun.hosts} file),
-we create a list of hosts to copy databases it from. Each host in the
-network therefore takes on the responsibility to watch over its neighbours.
-
-The copy rule attempts to copy the database to some file in a safekeeping
-directory. We label the destination file with @code{$(this)} which becomes
-the name of the server from which the file was collected. Finally, we backup
-any successful copies using a timestamp to retain a complete record of all changes
-on the remote host. Each time a change is detected, a copy will be kept of the
-old. The rule contains triggers to issue alerts and warnings also just to make
-sure the message will be heard.
-
-In theory, all four neighbours should signal this change. If an attacker
-had detailed knowledge of the system, he or she might be able to subvert
-one or two of these before the change was detected, but it is unlikely that
-all four could be covered up. At any rate, this approach maximizes the
-chances of change detection.
-
-Finally, in order to make this copy, you must, of course, grant access to the
-database in @code{cfservd.conf}.
-
-
-@smallexample
-# cfservd.conf
-
-admit:
-
-any::
-
- /var/cfengine/checksum_digests.db mydomain.tld
-@end smallexample
-
-
-Let us now consider what happens if an attacker changes a file an edits
-the checksum database. Each of the four hosts that has been designated
-a neighbour will attempt to update their own copy of the database. If the
-database has been tampered with, they will detect a change in the md5
-checksums of the remote copy versus the original. The file will therefore
-be copied.
-
-It is not a big problem that others have a copy of your checksum
-database. They cannot see the contents of your files from this. A
-possibly greater problem is that this configuration will unleash an
-avalanche of messages if a change is detected. This makes messages visible at least.
-
-
-
-
-@c ***********************************************************
-@node Release Management in ITIL, Configuration version control and rollback, Change Management in ITIL, Using CFEngine to implement ITIL objectives
-@section Release Management in ITIL
-
-Release management, as defined by ITIL (section 9 of BS15000-2), is a
-management function rather than a machine implementation
-operation. It includes all aspects of designing, planning and scheduling
-changes, but does not include the implementation.
-
-CFEngine can help with the final stages of software release
-management, namely deployment of software components and
-configuration. However, the bulk of this item concerns the human
-process of decision-making.
-
-@itemize
-@item Creating a schedule and policy for releases.
-@item Acquiring of completing the components for release.
-@item Assigning roles for responsibility.
-@item Labelling release items uniquely for tracking.
-@item Documentation updates.
-@item Testing prior to release.
-@end itemize
-CFEngine is not a tool for assisting in this kind of process. Some
-kind of process planning tool and revision control system could work
-for this.
-
-CFEngine has features that can be considered in the context of this
-work, however.
-
-@itemize
-@item packages
-
-@item files
-
-@item copy
-
-@end itemize
-
-ITIL frequently works with the idea of a @emph{baseline state}
-While CFEngine has no problem working with the idea of a baseline configuration,
-it is designed to exceed this assumption of maintenance from release to release.
-ITIL does not adequately address the need for on-the-fly maintenance; it only
-models large-jump changes, not error corrections. CFEngine, on the other hand, makes
-no distinction between a large and a small change, thus users of CFEngine must make
-a value judgement about the nature of such changes.
-
-
-@c ***********************************************************
-@node Configuration version control and rollback, Availability and Capacity Management, Release Management in ITIL, Using CFEngine to implement ITIL objectives
-@section Version control and rollback
-
-
-
-CFEngine does not provide specific tools for versioning configuration
-specifications. It is rather recommended to use a tool such as subversion
-for this.
-
-Subversion maintains its own revision numbers that are not
-visible to CFEngine however.
-It is useful to be able to refer to version numbers also
-in CFEngine. From software release 2.2.2 a version string
-can be added to files as follows:
-@smallexample
-control:
-
-cfinputs_version = ( 1.2.3 )
-Auditing = ( on )
-
-@end smallexample
-This
-defines the version number of a set of configuration files
-which is referred to in auditing and error messages.
-
-
-When CFEngine saves the current
-version of a file that it is modifying or replacing, by default such
-files are given a new extension and remain within the same directory
-which they were encountered. Alternatively, one can specify a
-repository directory to which such files can be moved instead. The
-repository location is specified in the @code{control} section:
-@smallexample
-control:
- Repository = ( /var/spool/CFEngine )
-@end smallexample
-Files moved to the repository are given names reflecting their full path, with slashes replaced
-by underscore characters. For some, this creates a clearer overview of the
-changes that have occurred.
-
-The repository is used by @code{disable}, @code{editfiles}, @code{links}, and @code{copy} rule types;
-@code{copy} and @code{disable} allow you to override repository use or to specify an alternate
-repository directory via their @code{repository} option.
-
-
-You should never edit the production version of a policy directly, but rather edit a
-separate development area and publish the changes once tested. The ITIL change management
-process is applicable to this human change (much more relevant that the machine changes
-made by CFEngine itself.).
-
-
-@menu
-* Delegating responsibility to multiple groups::
-@end menu
-
-@c ***********************************************************
-@node Delegating responsibility to multiple groups, , Configuration version control and rollback, Configuration version control and rollback
-@subsection Delegating responsibility
-
-CFEngine has no meta-access control mechanism which can decide who may
-write policy rules. To create such a mechanism, there would have to be
-a monitor which could identify users, and an authority mechanism that
-would disallow certain users to write rules of certain types about
-certain objects on certain hosts. Clearly it is @emph{possible}
-to create such a system, but it would be both technically
-difficult, very cumbersome to use and would add a whole new level
-of complexity to policy and potential error to the configuration process.
-
-To keep matters as simple as possible, CFEngine avoids this and
-proposes a different approach. Promise theory allows us to model the
-security implications of this (see the figure of the bow-tie
-structure). A simple method of delegating is the following.
-
-@enumerate
-@item Delegate responsibility for different issues to admin teams 1,2,3, etc.
-@item Make each of these teams responsible for version control of their own
-configuration rules.
-@item Make an intermediate agent responsible for collating and vetting the rules, checking for
-irregularities and conflicts. This agent must promise to disallow rules by
-one team that are the responsibility of another team. The agent could be a
-layer of software, but a cheaper and more manageable solution is the make this
-another group of one or more humans.
-
-@item Make the resulting collated configuration version controlled. Publish
-approved promises for all hosts to download from a trusted source.
-
-
-@end enumerate
-
-A review procedure for policy promises is a good
-solution if you want to delegate responsibility for different parts of
-a policy to different sources. Human judgement is irreplaceable, and tools
-can be added to make conflicts easier to detect.
-
-Promise theory underlines that, if a host of computing device accepts
-policy from any source, then it is alone and entirely responsible for
-this decision. The ultimate responsibility for the published version
-policy is the vetting agent. This creates a shallow hierarchy, but
-there is no reason why this formal body could not be comprised of
-representatives from the multiple teams.
-
-@image{delegate,10cm,,Delegation of responsibility requires vetting access,png}
-
-
-@c ***********************************************************
-@node Availability and Capacity Management, , Configuration version control and rollback, Using CFEngine to implement ITIL objectives
-@section Availability and Capacity Management
-
-CFEngine records all manner of information about the behaviour of computers during
-its efforts to keep promises. These data offer the potential of mining for building
-up a picture of the behaviour of an entire datacentre or organization, perhaps even
-multiple domains.
-
-CFEngine's environment daemon further collects patterns of environmental influence
-of hosts in a resource non-intensive manner.
-These data contain much information to enable capacity planning.
-
-We should add a warning however. Capacity planning requires a considerable
-amount of data and analysis, as well as a sound and critical judgement of the
-data. Resource and performance management are such complex issues that
-no simple recipe or checklist can replace the judgement of an experienced
-engineer. However, CFEngine can supply data to such an engineer.
-
-@enumerate
-@item Performance measurements (@code{cfshow -p}) allow the average throughput of a server in terms
-of time to completion of service. If service times are too long, this is an indication
-(but not proof) that hardware should be upgraded.
-
-@item Activity levels are graphed per service. These indicate the level of traffic
-coming into the different servers. Evidence of a ceiling limit on the throughput (clipping
-in the time-series) can show insufficient throughput.
-
-@item Distribution graphs of fluctuations about the mean can also show evidence
-of ceiling limits. Asymmetric distributions show when the majority of
-service requests tend to bunch at a high level (probable stress on
-server) or at a low level (over dimensioned server).
-@end enumerate
-
-The level of technical understanding to make sound judgements based on
-these data goes somewhat beyond the scope of this document. This
-motivates us to create better tools for CFEngine that can make these
-analyses more accessible to users. However, this must be deferred for another
-occasion.
-
-
-@c ***********************************************************
-@node Summary, ITIL glossary, Using CFEngine to implement ITIL objectives, Top
-@chapter Summary
-
-We have described the basics of CFEngine and ITIL and shown a number
-of areas where the two can be integrated.
-
-
-@itemize
-@item CFEngine users can benefit from the disciplines that ITIL brings.
-@item ITIL can benefit from the predictability that CFEngine brings.
-@end itemize
-
-
-
-
-
-@menu
-* How we wrote this document::
-* Road-map for adoption::
-@end menu
-
-@c ***********************************************************
-@node How we wrote this document, Road-map for adoption, Summary, Summary
-@section How we wrote this document, Promise concepts voluntary cooperation, Summary, Summary
-
-
-So, if ITIL is so great, did we use it to manage the process of
-writing this document? Authoring a document and authoring a policy
-have much in common, so let us spend a moment to examine the process
-of checks and balances that we have used to produce this text.
-
-The answer to our question is both yes and no, and while this might
-sound rather unhelpful, we suggest that it is in fact a significant
-answer; indeed it is the @emph{right} answer in response to any
-question about best practices because such recipes must always be
-applied to a specific context.
-
-There are sensible and ridiculous ways to implement a set of
-recommendations. ITIL users should expect to adapt its generalized
-ideas to each set of special circumstances. To do this here, we have
-used the parts of ITIL that make particular sense for authoring, and
-we have also used CFEngine's model of promises or voluntary
-cooperation to understand how to implement them.
-
-For example, ITIL suggests forming committees for discussing and
-deciding change. A committee is a cumbersome device when the total
-number of people involved in the entire process is two. Nevertheless,
-the role of the committee is relevant (i.e. the promises it makes to
-bring the process to completion), and this is where promise theory
-helps us to make sense of the ``dumb rules''. We have multiple opinions
-and multiple pairs of eyes for quality control as well as for inspiration.
-
-@menu
-* ITIL concepts for authoring::
-* Promise concepts voluntary cooperation::
-@end menu
-
-@node ITIL concepts for authoring, Promise concepts voluntary cooperation, How we wrote this document, How we wrote this document
-@subsection ITIL concepts for authoring, Promise concepts voluntary cooperation, Summary, Summary
-
-Several parts of ITIL are quite relevant to authoring.
-
-@itemize
-@item @emph{Service management.} A document provides an information service to its clients (the readers).
-It promises to be accurate to within reasonable limits.
-
-@item @emph{Release management.} Each version of our document can be considered a release
-which undergoes a continual improvement cycle, constantly being evaluated and
-changed in accordance with events and incidents that occur.
-
-@item @emph{Incidents.} An incident is something that impacts on the service. An incident
-could be the discovery of an error in the text. It could be a disagreement between
-the authors or a misunderstanding on the part of the reader. There have been many incidental
-changes based on discussions in our teams.
-
-@item @emph{Impact.} The impact of the incident is the potential damage caused by the incident,
-or the usefulness of the discovery. Incidents are not necessarily negative events. They
-can be events which point out improvements.
-
-@item @emph{Request for change.} One of the authors asks to make changes to the text.
-
-@item @emph{Change management.} Each identified change can be evaluated for its potential
-impact (benefit or confusion). If there are many changes to be made, priority can be
-assigned to them. When should the changes be implemented?
-
-@end itemize
-
-@c ***********************************************************
-@node Promise concepts voluntary cooperation, , ITIL concepts for authoring, How we wrote this document
-@subsection Promising voluntary cooperation, Road-map for adoption, Summary, Summary
-
-
-What does promise theory say about collaborative authoring?
-
-First of all, it begins by saying that each individual in the process
-of authoring has independent knowledge and should be represented as a
-separate agent. It tells us that promises to cooperate will be needed
-to integrate the information.
-
-However, more than that, promises tell us that each section of the
-text is an ``agent'' which can change or behave independently. In
-other words, we can manage the parts independently, but again we need
-to promise to coordinate those parts. So promise theory asks us first
-to identify the agents (the topics in the document) that will be
-interacting and then find out what promises they need to make to carry
-out their function.
-
-Because of the individual nature of the parts, we can associate an
-individual author to each. To bring them together we need a further
-agent or individual to collate independent ideas and policy sources
-into a single coherent whole. Thus promises shows us a basic
-``bow-tie'' structure for integrating and correlating independent
-sources and then making the results available to independent users
-(see figure). This is not the only solution to the
-problem of vetting that promises predicts, but it is the simplest
-one. Also it is the approach that ITIL approves -- making a someone
-responsible for the job.
-
-We emphasize that promise theory does not tell us the specifics of how
-to implement solutions, it only tells us what elements are needed and
-how they should interact. So we might implement agents as people, as
-different computers, or as different user accounts within the same computer.
-As long as the elements can keep the necessary promises, it does not matter.
-
-
-So how did we write our document? In fact we did not use a very
-strict ITIL-like change management process when writing the first
-versions of our document. Such a process could have strangled our work
-in the creative stage and doubled the time it took to write. Rather, we worked
-in an @emph{ad hoc} way by voluntary cooperation. Each of us promised
-to write about certain topics and work on the text independently. We
-worked as autonomous agents, and we used Subversion (a version control
-and sharing system) to keep the working document. Subversion is itself
-a third agent which promises to accept changes one at a time from
-either of the two authors and then make these changes available again
-to both authors. This agent performs no vetting or control other than
-ordering the changes.
-
-The authors have to promise to one another to resolve any conflicts or
-disagreements, but promises do not suggest how this might take place.
-(ITIL, on the other hand, does offer suggestions for this resolution process).
-
-ITIL seems to work best once a service is up and running, or once a
-basic version of a document exists. It does not say so much about the
-creative act, except to think of it as a release.
-
-What ITIL is weak at is parallelization of effort. ITIL's processes are
-serialized processing models. In our first creative versions, we
-converged in parallel onto an approximate result, each working
-separately. This is very efficient but it can lead to duplication of
-work or inconsistency. Serialization is needed to resolve consistency
-issues precisely, but it leads to unnecessary waiting in some cases.
-
-
-@node Road-map for adoption, , How we wrote this document, Summary
-@section Road-map for adoption
-
-Below we indicate a checklist of ITIL compliant steps for using CFEngine
-in a machine life-cycle.
-
-
-@enumerate
-@item Set up cfagent running at scheduled interval X. This is the Service Level Agreement.
-
-@item Set up versioning of policy.
-
-@item Set up delegation of authorship.
-
-@item Run cfenvd for passive monitoring. Run cfagent for active monitoring.
-
-@end enumerate
-
-Release:
-
-@enumerate
-
-@item Select installation medium e.g. DVD, net-boot with hooks to CFEngine.
-
-@item Start with essential promises, and formulate the configuration policy.
-
-@item Use ITIL processes for deciding and refining configuration promises.
-
-@item Evaluation and monitoring of promises using cfagent and cfenvd.
-
-@item Use cfagent for monitor changes using cryptographic checksums.
-
-@item Develop recovery plans. Use CFEngine to automate backup of data and
-automate the duplication of servers for load balancing and redundancy.
-
-@end enumerate
-
-
-
-
-@c --------------------------------------------------------------------
-
-@node ITIL glossary, , Summary, Top
-@chapter ITIL glossary
-
-This section lists some of the many terms from ITIL, especially the ISO/IEC 20000
-version of the text, and offers some comments and translations into common CFEngine
-terminology.
-
-
-
-@menu
-* Active Monitoring::
-* Availability::
-* Alert::
-* Audit ::
-* Baseline::
-* Benchmark ::
-* Capability::
-* Change record::
-* Chronological Analysis::
-* Configuration::
-* Configuration Item (CI)::
-* Configuration Management Database CMDB ::
-* Document::
-* Emergency Change::
-* Error::
-* Event::
-* Exception::
-* Failure::
-* Incident::
-* Monitoring::
-* Passive Monitoring::
-* Policy::
-* Proactive Monitoring::
-* Problem::
-* Promise::
-* Reactive Monitoring::
-* Record::
-* Recovery::
-* Remediation::
-* Repair::
-* Release::
-* Request for Change::
-* Resilience::
-* Restoration::
-* Role::
-* Service desk::
-* Service Level Agreement::
-* Service Management::
-* Warning::
-@end menu
-
-@node Active Monitoring, Availability, ITIL glossary, ITIL glossary
-@section Active Monitoring
-
-Monitoring of a configuration item or IT service that uses automated regular checks to discover the current status.
-
-@cartouche
-CFEngine performs programmed checks of all of its promises each time cfagent is started.
-Cfagent is, in a sense, an active monitor for a set of promises that are described in its
-configuration file.
-@end cartouche
-
-@node Availability, Alert, Active Monitoring, ITIL glossary
-@section Availability
-
-The ability of a component or service to perform its required function.
-
-Availability = Hours operational / Agreed service hours
-
-
-@cartouche
-Availability or intermittency in CFEngine refers to the responsiveness of
-hosts in a network when remotely connecting to cfservd.
-
-Intermittency = Successful~ attempts / Total Attempts
-
-@end cartouche
-This is a measurement that cfagent automatically makes.
-
-@node Alert, Audit , Availability, ITIL glossary
-@section Alert
-
-A warning that a threshold has been reached, something has changed or a failure has occurred.
-
-
-@cartouche
-A CFEngine alert fits this description quite well.
-Most alerts are user-defined, but a few are side effects of certain configuration
-rules.
-@end cartouche
-
-@node Audit , Baseline, Alert, ITIL glossary
-@section Audit
-
-
-A formal inspection and verification to check whether a standard or
-set of guidelines is being followed.
-
-
-
-
-@cartouche
-CFEngine's notion of an audit is more like the notion from system
-accounting. However, the data generated by this extra logging
-information could be collected and used in a more detailed examination
-of CFEngine's operations, suitable for use in a formal inspection
-(e.g. for compliance).
-@end cartouche
-
-
-@node Baseline, Benchmark , Audit , ITIL glossary
-@section Baseline
-
-
-A snapshot of the state of a service or an individual configuration
-item at a point in time
-
-
-@cartouche
-In CFEngine parlance, we refer to this as an initial state or
-configuration. In principle a CFEngine initial state does not have to
-be a known-base line, since the changes we make will not generally be
-relative to an existing configuration. CFEngine encourages users to
-define the final state (regardless of initial state).
-@end cartouche
-
-
-@node Benchmark , Capability, Baseline, ITIL glossary
-@section Benchmark
-
-The recorded state of something at a specific point in time.
-
-
-@cartouche
-CFEngine does not use this term in any of its documentation, though
-our general understanding of a ``benchmark'' is that of a standardized
-performance measurement under special conditions. CFEngine regularly
-records state and performance data in a variety of ways, for example
-when making file copies.
-@end cartouche
-
-@node Capability, Change record, Benchmark , ITIL glossary
-@section Capability
-
-The ability of someone or something to carry out an activity.
-
-
-@cartouche
-CFEngine does not use this concept specifically. The notion of a capability
-is terminology used in role-based access control.
-@end cartouche
-
-@node Change record, Chronological Analysis, Capability, ITIL glossary
-@section Change record
-
-A record containing details of which configuration items are affected
-and how they are affected by an authorized change.
-
-
-
-@cartouche
-CFEngine's default modus operandi is to @emph{not} record changes made
-to a system unless requested by the user. Changes can be written as
-log entries or audit entries by switching on reporting.@end cartouche
-
-Consider a typical CFEngine promise (to ensure that a destination file
-is a copy of a source). Three levels of change recording can be
-added in CFEngine 2:
-@smallexample
-
-copy:
-
- /source/file dest=/destination/file
-
- inform=true
- syslog=true
- audit=true
-@end smallexample
-An ``inform'' promise means that cfagent promises to notify the
-changes to its standard output (which is usually sent by email or
-printed on a console output). A ``syslog'' promise implies that
-cfagent will log the message to the system log daemon. Both of the
-foregoing messages give only a simple message of actual changes. An
-``audit'' promise is a promise to record extensive details about the
-process that cfagent undergoes in its checking of other promises.
-
-
-@node Chronological Analysis, Configuration, Change record, ITIL glossary
-@section Chronological Analysis
-
-An analysis based on the timeline of recorded events (used to help identify possible causes of problems).
-
-
-
-@cartouche
-A timeline analysis could easily be carried out based on audit
-information, system logs and cfenvd behavioural records.
-@end cartouche
-
-@node Configuration, Configuration Item (CI), Chronological Analysis, ITIL glossary
-@section Configuration
-
-A group of configuration items (CI) that work together to deliver an IT service.
-
-@cartouche
-A configuration is the current state of resources on a system. This is, in
-principle, different from the state we would like to achieve, or what has
-been promised.
-@end cartouche
-
-@node Configuration Item (CI), Configuration Management Database CMDB , Configuration, ITIL glossary
-@section Configuration Item (CI)
-
-A component of an infrastructure which is or will be under the control
-of configuration management.
-
-
-@cartouche
-A configuration item is any object making a promise
-in CFEngine. We often speak of the promise object, or ``promiser''.@end cartouche
-
-@node Configuration Management Database CMDB , Document, Configuration Item (CI), ITIL glossary
-@section Configuration Management Database (CMDB)
-
-Database containing all the relevant details of each configuration
-item and details of the important relationships between them.
-
-
-@cartouche
-
-CFEngine has no asset database except for its own list of
-promises. The only relationships is cares about are those which are
-explicitly coded as promises. In the future, CFEngine 3 is likely
-to extend the notion of promises to allow more general records of the
-CMDB kind, but only to the extent that they can be verified autonomically.
-@end cartouche
-
-@node Document, Emergency Change, Configuration Management Database CMDB , ITIL glossary
-@section Document
-
-Information and its supporting medium.
-
-
-
-@cartouche
-ITIL originally considered a document to be only a container for
-information. In version 3 it considers also the medium on which
-the data are recorded, i.e. both the file and the filesystem on which it resides.@end cartouche
-
-@node Emergency Change, Error, Document, ITIL glossary
-@section Emergency Change
-
-A change that must be introduced as soon as possible -- for example to
-solve a major incident or to implement a critical security patch.
-
-
-
-@cartouche
-CFEngine has no specific concept for this.
-@end cartouche
-
-@node Error, Event, Emergency Change, ITIL glossary
-@section Error
-
-A design flaw or malfunction that causes a failure.
-
-
-
-@cartouche
-CFEngine often uses the term configuration error to mean a deviation of
-a configuration from its promised state. The ITIL meaning of the term would
-translated into ``bug in the CFEngine software'' or ``bug in the
-promised configuration''.
-@end cartouche
-
-
-@node Event, Exception, Error, ITIL glossary
-@section Event
-
-A change of state that has significance for the management of a
-configuration item or IT service.
-
-
-
-@cartouche
-The same basic definition applies to CFEngine also, but CFEngine makes
-all such events into @emph{classes}, since its approach to observing
-the environment is to measure and then classify it into approximate
-expected states. CFEngine class attributes (usually from cfenvd) may
-be considered as event notifications as they change.
-@end cartouche
-
-@node Exception, Failure, Event, ITIL glossary
-@section Exception, Failure, Event, Summary
-
-An @b{event} that is generated when a service or device is currently operating abnormally.
-
-
-
-@cartouche
-A state in which configuration policy is violated (could lead to a
-warning or an automated correction).
-@end cartouche
-
-
-@node Failure, Incident, Exception, ITIL glossary
-@section Failure
-
-Loss of ability to operate to specification or to deliver the required output.
-
-
-
-@cartouche
-ITIL's idea of a failure is something that prevents a promise from being kept.
-CFEngine's autonomy model means that it is unlikely for such a failure
-to occur, since promises are only allowed to be made about resources for which
-we have all privileges. Occasionally, environmental issues might interfere and
-lead to failure.
-@end cartouche
-
-@node Incident, Monitoring, Failure, ITIL glossary
-@section Incident
-
-Any event that is not expected in normal operations and which might
-cause a degradation of service quality.
-
-
-
-@cartouche
-CFEngine's philosophy of convergence gives us only one option for
-interpreting this term, namely as a temporary deviation from promised
-behaviour. A deviation must be temporary if CFEngine is operating
-continually, since it will repair any problem on its next invocation
-round. Events which do not impact promises made by CFEngine are of no
-interest to CFEngine, since autonomy means it cannot be responsible
-for anything beyond its own promises.
-@end cartouche
-
-@node Monitoring, Passive Monitoring, Incident, ITIL glossary
-@section Monitoring
-
-Repeated observation of a configuration item, IT service or process in
-order to detect events and ensure that the current status is known.
-
-
-
-@cartouche
-CFEngine incorporates a number of different kinds of monitoring, including monitoring of kept
-configuration-promises and passive monitoring of behaviour.
-@end cartouche
-
-@node Passive Monitoring, Policy, Monitoring, ITIL glossary
-@section Passive Monitoring
-
-Monitoring of a configuration item or IT service that relies on an alert or notification to discover the current status.
-
-
-
-@cartouche
-Cfenvd is CFEngine's passive monitoring component. It observes system
-related behaviour and learns about it. It assumes that there is likely
-to be a weekly periodicity in the data in order to best handle its
-statistical inference.
-@end cartouche
-
-@node Policy, Proactive Monitoring, Passive Monitoring, ITIL glossary
-@section Policy
-
-Formally documented management expectations and intentions. Policies
-are used to direct decisions, and to ensure consistent and appropriate
-development and implementation of processes, standards, roles,
-activities, IT infrastructures, etc.
-
-
-@cartouche
-CFEngine's configuration policy is an automatable set of promises
-about the static and runtime state of a computer. Roles are identified
-by the kinds of behaviour exhibited by resources in a network. We say
-that a number of resources (hosts or smaller configuration objects)
-play a specific promised role if they make identical promises. Any resource can
-play a number of roles. Decisions in CFEngine are made entirely on the basis
-of the result of monitoring a host environment.
-@end cartouche
-
-@node Proactive Monitoring, Problem, Policy, ITIL glossary
-@section Proactive Monitoring, Problem, Policy, Summary
-
-Monitoring that looks for patterns of events to predict possible future failures.
-
-
-
-@cartouche
-All CFEngine monitoring is pro-active in the sense that it can lead to automated follow-up actions.
-@end cartouche
-
-@node Problem, Promise, Proactive Monitoring, ITIL glossary
-@section Problem
-
-Unknown underlying cause of one or more incidents.
-
-
-
-@cartouche
-A repeated deviation from policy that suggests a change of policy or
-specific counter-measures. A promise needs to be reconsidered or new promises
-are required.
-@end cartouche
-
-@node Promise, Reactive Monitoring, Problem, ITIL glossary
-@section Promise, Reactive Monitoring, Problem, Summary
-
-ITIL does not define this term, although promises are deployed in
-various ways -- for instance in terms of cooperation, communication
-interfaces within or between processes or contractual relationships as
-defined by Service Level Agreements, Operational Level Agreements and
-Underpinning Contracts.
-
-
-
-@cartouche
-A promise in CFEngine is a single rule in the CFEngine language. The promiser is the resource
-whose properties are described, and the promisee is implicitly the CFEngine monitor.
-@end cartouche
-
-@node Reactive Monitoring, Record, Promise, ITIL glossary
-@section Reactive Monitoring
-
-Monitoring that takes action in response to an event -- for example
-submitting a batch job when the previous job completes, or logging an
-incident when an error occurs.
-
-
-
-@cartouche
-The concept of reactive monitoring is unclear because the duration of an event and the speed of
-a response are undefined. In a sense, all CFEngine monitoring is potentially reactive. It is possible
-to attach actions which keep promises to any observable condition discernable by CFEngine's monitor.
-CFEngine is not usually considered event driven however, since it does not react ``as soon as possible''
-but at programmed intervals.
-@end cartouche
-
-@node Record, Recovery, Reactive Monitoring, ITIL glossary
-@section Record
-
-Information in readable form that is maintained by the service provider about operations.
-
-
-
-@cartouche
-A log entry or database item.
-@end cartouche
-
-@node Recovery, Remediation, Record, ITIL glossary
-@section Recovery
-
-Returning a Configuration Item or an IT service to a working
-state. Recovering of an IT service often includes recovering data to a
-known consistent state.
-
-
-
-@cartouche
-All CFEngine promises refer to the state of a system that is desired. The promises are
-automatically enforced, hence CFEngine recovers a system (in principle) on every invocation.
-CFEngine always returns to a known state, due to the property of ``convergence''. There is no
-distinction between the concepts of repair, recovery or remediation.
-@end cartouche
-
-@node Remediation, Repair, Recovery, ITIL glossary
-@section Remediation
-
-Recovery to a known state after a failed change or release.
-
-
-
-@cartouche
-All CFEngine promises refer to the state of a system that is desired. The promises are
-automatically enforced, hence CFEngine recovers a system (in principle) on every invocation.
-CFEngine always returns to a known state, due to the property of ``convergence''. There is no
-distinction between the concepts of repair, recovery or remediation.
-
-However, this concept is like the notion of ``rollback'' which often involves a more
-significant restoration of a system from backup. This is discussed later.
-@end cartouche
-
-@node Repair, Release, Remediation, ITIL glossary
-@section Repair
-
-The replacement or correction of a failed configuration item.
-
-
-
-@cartouche
-All CFEngine promises refer to the state of a system that is desired. The promises are
-automatically enforced, hence CFEngine recovers a system (in principle) on every invocation.
-CFEngine always returns to a known state, due to the property of ``convergence''. There is no
-distinction between the concepts of repair, recovery or remediation.@end cartouche
-
-@node Release, Request for Change, Repair, ITIL glossary
-@section Release, Request for Change, Repair, Summary
-
-A collection of new or changed configuration items that are introduced together.
-
-
-
-@cartouche
-An instantiation of the entire CFEngine system under a specific
-version of a policy, i.e. a specific set of promises.
-@end cartouche
-
-@node Request for Change, Resilience, Release, ITIL glossary
-@section Request for Change
-
-A form to be completed requesting the need for change. This is to be followed up.
-
-
-
-@cartouche
-This has no counterpart in CFEngine. It is part of human communication
-which coordinates autonomous machines. Clearly autonomous computers do not
-listen to change requests from other computers, but when machines cooperate
-in clusters or groups they take suggestions from the collaborative process.
-An RFC in an ITIL sense is part of an organizational process that goes beyond
- CFEngine's level of jurisdiction. This is an example of what ITIL adds to
-the autonomous CFEngine model.
-@end cartouche
-
-@menu
-* Abandon Autonomy?::
-@end menu
-
-@node Abandon Autonomy?, , Request for Change, Request for Change
-@subsection Abandon Autonomy?
-
-Why not simply abandon autonomy of machines if this seems to interfere
-with the need for organizational change? There are good reasons why
-autonomy is the correct model for resources. Autonomy reduces the risk to a
-resource of attack, mistake and error propagation.
-
-ITIL's processes exist precisely to minimize the risk of negative
-impact of change, so the goals are entirely compatible. When an organization
-discusses a change it examines information from possible several autonomous
-systems and discusses how they will change their pattern of collaboration.
-There is no point in this process at which it is necessary for one of the
-systems to give up its autonomy.
-
-
-@node Resilience, Restoration, Request for Change, ITIL glossary
-@section Resilience
-
-The ability of a configuration item or IT service to resist failure or to recover quickly following a failure.
-
-
-
-@cartouche
-CFEngine's purpose is to make a system resilient to unpredictable change.@end cartouche
-
-@node Restoration, Role, Resilience, ITIL glossary
-@section Restoration
-
-Actions taken to return an IT service to the users after repair and recovery from an incident.
-
-
-
-@cartouche
-All CFEngine promises refer to the state of a system that is desired. The promises are
-automatically enforced, hence CFEngine recovers a system (in principle) on every invocation.
-CFEngine always returns to a known state, due to the property of ``convergence''. There is no
-distinction between the concepts of repair, recovery or remediation.
-
-However, this concept seems to suggest a more catastrophic failure
-which often involves a more significant restoration of a system from
-backup. This is discussed later.
-@end cartouche
-
-@node Role, Service desk, Restoration, ITIL glossary
-@section Role
-
-A set of responsibilities, activities and authorities granted to a person or a team. Roles are defined in processes.
-
-
-
-@cartouche
-A role in CFEngine is a class of agents that make the same kind of promise. The type
-of role played by the class is determined by the nature of the promise they make. e.g.
-a promise to run a web server would naturally lead to the role ``web server''.
-@end cartouche
-
-@node Service desk, Service Level Agreement, Role, ITIL glossary
-@section Service desk
-
-Interface between users and service provider.
-
-
-
-@cartouche
-A help desk. This is not formally part of CFEngine's tool set.
-@end cartouche
-
-@node Service Level Agreement, Service Management, Service desk, ITIL glossary
-@section Service Level Agreement
-
-A written agreement between the service provider that documents agreed
-services, levels and penalties for non-compliance.
-
-
-
-@cartouche
-An agreement assumes a set of promises that propose behaviour and an
-acceptance of those promises by the client. If we assume that the
-users are satisfied with out policies, then an SLA can be
-interpreted as a combination of a configuration policy
-(configuration service promises), and the CFEngine execution
-schedule.
-@end cartouche
-
-
-@node Service Management, Warning, Service Level Agreement, ITIL glossary
-@section Service Management
-
- The management of services.
-
-
-
-@cartouche
-Same.@end cartouche
-
-@node Warning, , Service Management, ITIL glossary
-@section Warning
-
-An @b{event} that is generated when a service or device is approaching its threshold.
-
-
-
-@cartouche
-A message generated in place of a correction to system state when a deviation from policy is detected.
-Note that CFEngine is not based on fixed thresholds. All ``thresholds'' for action or warning
-are defined as a matter of policy.
-@end cartouche
-
-
-
-
-
-@c =========================================================================
-@c @node Index, , CFEngine Methods, Top
-@c @unnumbered Concept Index
-@c @printindex cp
-@c =========================================================================
-
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/cf3-glossary.texinfo b/docs/guides/cf3-glossary.texinfo
deleted file mode 100644
index d815119c56..0000000000
--- a/docs/guides/cf3-glossary.texinfo
+++ /dev/null
@@ -1,274 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename cf3-glossary.info
-@settitle CFEngine Glossary
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title CFEngine Glossary
-@subtitle A CFEngine Handbook
-@author CFEngine AS
-
-@c @smallbook
-
-
-@page
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2009- CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@node Top, , (dir), (dir)
-@top CFEngine Glossary
-@end ifnottex
-
-@table @emph
-
-@item Agent
-A piece of software that runs independently and automatically to carry out a task (think software robot).
-Inn CFEngine, the agent is called @code{cf-agent} and is responsible for making changes to computers.
-
-@item Amber host
-A host that has repaired more than 20% of its scheduled promises in the past 5 minutes.
-(See yellow host.)
-
-@item Body
-A promise body is the description of exactly what is promised (as
-opposed to what/who is making the promise). The term `body' is used in
-the CFEngine syntax to mean a small template that can be used to
-contribute as part of a larger promise body.
-
-@item Bundle
-In CFEngine, a bundle refers to a collection of promises that has a name.
-
-@item CDP
-Content Driven Policy. A way of simplifying the way users provide
-information to CFEngine about policy by hiding the overhead of policy
-coding. A CDP is a set of promises that is designed to solve a
-particular task in a standard way. Users provide only a little data in
-the form of a simple spreadsheet of data in a table.
-
-@item CFEngine
-The name of the CFEngine Company, as well as the name of the Software. CFEngine comes from
-a contraction of `ConFiguration Engine'.
-
-@item CFEngine 3.x
-Major version 3 of the CFEngine software, started in 2008 and going up
-to the present day. This comes in several @emph{editions}, both Open Source and Commercial.
-
-@item CFEngine Community Edition
-Free and Open Source edition of the CFEngine software, published under the GPL3 license,
-and optionally under the COSL license.
-
-@item CFEngine Community Open Promise-Body Library
-A collection of standard definitions that is open to the user community for comment and standardization.
-
-@item CFEngine Enterprise
-Refers to commercial (paid) editions of the CFEngine software, published under the COSL license. CFEngine Nova was renamed to CFEngine Enterprise in version 2.2 (2012).
-
-@item CFEngine Nova
-The first enterprise edition of CFEngine, that automatically creates a simple `star network'
-mangement model for hosts in an environment. Was renamed to CFEngine Enterprise in version 2.2 (2012).
-
-@item ChangeLog
-A file used to describe the changes made since the last version of the software.
-
-@item CMDB
-A Configuration Management Database. A term coined as part of the IT Infrastructure Library (ITIL)
-as an outgrowth of an inventory database.
-
-@item CMS
-Content Management System. A kind of editor for maintaining something (often web pages).
-
-@item Code branch
-The development of software is a branching process. At certain times,
-the software code splits into different versions following different
-paths. Each path needs to be maintained separately for a while. This
-often happens when a release is made, because one wants to freeze the
-development of a public release (allowing nevertheless for some minor
-bugfixes), while continuing to add features to a branch leading to
-future versions.
-
-@item COPBL
-CFEngine Community Open Promise-Body Library (abbrev: CFEngine standard library).
-A collection of standard definitions.
-
-@item COSL license
-The Commercial Open Source License used for the CFEngine
-
-@item CSS
-Cascading Style Sheets. Part of Web technology used to describe page design.
-
-
-@item Diff
-A `diff' is a report (originally that generated by the UNIX @code{diff} command) that
-details the differences between two files. The term is often used as slang meaning a file comparison.
-
-@item GPL3
-The GNU Public License, version 3.
-
-@item Green Host
-A host for which more than 80% of all promises are kept.
-
-@item GUI
-Graphical User Interface.
-
-@item Host
-UNIX terminology for a computer the runs `guest programs'. In practice, `host'
-is a synonym for `computer'.
-
-@item Hub
-A host that works as a
-single point of management in a local `star-network'. The term hub is
-sometimes used to mean policy distribution server. In CFEngine Enterprise a
-separate software component, @code{cf-hub}, does report collection from all CFEngine
-managed hosts. The
-term hub means the centre of a wheel, from which multiple spokes
-emerge.
-
-@item Knowledge Map
-A master index of all the information known about a CFEngine managed environment, represented as
-a set of web pages with an interactive interface based on a `semantic web'. The CFEngine Mission Portal provides a
-web-based interface for browsing this knowledge map index.
-
-@item Mission
-The mission refers to the raison d'\hat etre of an organization. CFEngine's
-task is to support this mission by keeping a set of promises for its IT infrastructure.
-
-@item Mission Portal
-The name given to the user interface used in commercial CFEngine editions, where
-all reports and progress summaries are kept.
-
-@item Modular license
-A license granting partial functionality to an Enterprise Edition of CFEngine.
-
-@item LDAP
-The Lightweight Directory Access Protocol. A kind of `phone book' service providing information
-about persons and computers in an organization.
-
-@item Libraries
-A library generally refers to collection of standardized CFEngine code
-that can be reused in different scenarios and environments. This might
-be bundles of promises, or reusable body-parts.
-
-@item Packages
-Software binaries or executable files. The CFEngine company compiles and tests software
-into packages suitable for different platforms.
-
-@item Platforms
-This usually refers to an operating system type, e.g. Linux (in its many flavours), or
-Windows, etc. Platforms are described using short identifiers, e.g. RH5, REL5, SuSE 11, SLES, etc.
-
-@item Knowledge Map
-Content portal containing datacentre information, privately managed
-knowledge resources and CFEngine documentation.
-
-@item PCI compliance
-Payment Card Industry Data Security Standard (PCI DSS) is a set of
-requirements designed to ensure that ALL companies that process, store
-or transmit credit card information maintain a secure environment.
-
-@item Promise
-The CFEngine software manages every intended system outcome as `promises' to be kept.
-A CFEngine Promise corresponds roughly to a rule in other software products, but importantly
-promises are always things that can be kept and repaired continuously, on a real time basis,
-not just once at install-time.
-
-@item Policy
-A policy is a set of intentions about the system, coded as a list of
-promises. A policy is not a standard, but the result of specific
-organizational management decisions.
-
-@item Semantic web
-A form of web content in which hyperlinks always explain the meaning of the
-information they point to, in relation to the
-subject of interest. Semantic web technologies include RDF, Topic Maps etc.
-
-@item Server
-A term used in many different ways, riddled with confusion. A server
-is strictly a piece of software that runs on some computer in
-order to perform a service, e.g. a web server is a program that
-makes a computer part of the World Wide Web. For historical reasons,
-certain computers are referred to as servers, especially when kept in
-datacentres because such computers often run services. In CFEngine, @code{cf-serverd}
-is a software component that serves files from one computer to another.
-All computers are recommended to run @code{cf-serverd}, making all computers CFEngine servers,
-whether they are laptops, phones or datacentre computers.
-
-@item Service Catalogue
-A kind of directory of `services' provided in an environment. The concept of a service
-could be anything from a human help desk to a machine controlled email subsystem.
-In the CFEngine Mission Portal, the service catalogue (for maintenance) treats promise-bundles of promises as low-level
-maintenance services, and relates these to high level business goals.
-
-@item SOX Compliance
-Sarbanes-Oxley Act compliance. An audited accolade for financial data security
-required by all companies on the New York stock exchange.
-
-@item Standard library
-The CFEngine Standard library is a collection of standardized definitions (see COPBL).
-
-@item Template
-A template is an incomplete piece of CFEngine code, with blanks to fill in. It is often
-a policy fragment that can be re-used in different scenarios. This is often used interchangeably
-with the term `library'.
-
-@item UI
-User interface.
-
-@item Yellow host.
-See amber host.
-
-@end table
-
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/cf3-installation.texinfo b/docs/guides/cf3-installation.texinfo
deleted file mode 100644
index cd0274b33d..0000000000
--- a/docs/guides/cf3-installation.texinfo
+++ /dev/null
@@ -1,277 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename cf3-installation.info
-@settitle CFEngine Installation Guide
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title CFEngine Installation Guide
-@subtitle A CFEngine Handbook
-@author CFEngine AS
-
-
-@page
-
-@cartouche
-@quotation
-This short guide explains how to install the software and get it running.
-@end quotation
-@end cartouche
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2011- CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@node Top, CFEngine Installation Guide, (dir), (dir)
-@top CFEngine Installation Guide
-@end ifnottex
-
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@c **********************************************************************
-@c CHAPTER
-@c **********************************************************************
-
-
-
-@c **********************************************************************
-@menu
-* System automation::
-* The components of CFEngine::
-* Bodies and bundles::
-* First promises::
-* A simple crash course in concepts::
-* Using CFEngine as a front-end for cron::
-* Network services::
-* Knowledge Management::
-@end menu
-
-@node System automation, The components of CFEngine, Top, Top
-@chapter System automation
-
-
-@menu
-* Managing diverse and challenging environments seamlessly and invisibly::
-* Managing expectations - a theory of promises::
-* Why automation?::
-* Scaling up::
-* How do you view CFEngine::
-@end menu
-
-@node Managing diverse and challenging environments seamlessly and invisibly, Managing expectations - a theory of promises, System automation, System automation
-@section Managing diverse and challenging environments seamlessly and invisibly
-
-The future is never far away.
-Our dream of a future in which smart computing devices are embedded into
-the very fabric of our environment has crept slowly into being. Today,
-smart operating systems like Linux and Windows are used on embedded devices
-and mobile phones.
-Mark Weiser of Xerox PARC once wrote:
-
-@quotation
-@i{"The most profound technologies are those that disappear. They weave
-themselves into the fabric of every day life until they are
-indistinguishable from it."}
-@end quotation
-
-Today many are talking about Cloud Computing as another manifestation
-of this dream, in which computing service is not only everywhere, but
-nowhere -- or more correctly, spread out across the planet in
-data centers, instead of our offices and homes. This is one aspect of
-making computing into something we take for granted. At the
-foundations of any such technology are the tools required to implement
-mass configuration with surgical precision. CFEngine is such a tool.
-
-CFEngine was designed to enable scalable configuration management, for
-the
-whole system life-cycle, in any kind of environment.
-Almost every other system for configuration assumes that there will be
-a reliable network in place and that changes will be pushed out
-top-down from an authoritative node. Those systems are useless in
-environments like
-
-@itemize
-@item Mobile systems with partial or unreliable connectivity (e.g. a
-submarine).
-@item Systems where bandwidths are very low (e.g. a satellite or space
-probe).
-@item Systems where computing power is very low (e.g. ad hoc sensors
-or kitchen appliances).
-@end itemize
-
-CFEngine does not need reliable infrastructure. It works
-opportunistically in almost any environment, using few resources. It
-has few software dependencies. So, not only does it work in all of the
-traditional fixed-plan scenarios, but it is capable of working in
-totally ad hoc deployment: an temporary incident room, a submarine
-drifting on and off line, a satellite or a robot explorer.
-
-One could argue `well I don't need that kind of system, because my
-network is reliable'. However, your network is not as reliable as you
-think, and mobility is an increasingly important topic. Even with a
-very strong redundant network, the services that support the network
-can be paralyzed by any of a number of failed dependencies or
-mishaps. It is crucial in a modern pervasive environment that systems
-remain available, fault tolerant and as far as possible independent of
-external requirements. This is how to build scalable and reliable
-services.
-
-@cartouche
-CFEngine works in all the places you think it should, and all the new
-places you haven't even thought of yet. How do we know? Because it
-is based on almost 20 years of careful research and experience.
-@end cartouche
-
-
-@node Managing expectations - a theory of promises, Why automation?, Managing diverse and challenging environments seamlessly and invisibly, System automation
-@section Managing expectations - a theory of promises
-
-One of the hardest things in management is to make everyone aware of
-their roles and tasks, and to be able to rely on others to do the same.
-@i{Trust} is an economic time-saver. If you can't trust you have to
-verify,
-and that is expensive.
-
-To improve trust we make promises. A promise is the documentation of an
-intention to act or behave in some manner. This is what we need to
-learn to
-trust systems, no matter whether they are machines or humans.
-
-One CFEngine user once said to me, that the thing that had helped him
-the most in deploying CFEngine was its design based around voluntary
-cooperation. ``Our main problems were not technical but political --
-getting everyone to agree in all of our departments around the
-world''. This was because, for all the technology, it is people who
-make the decisions and people need to feel that the system is
-empowering rather than disempowering them.
-
-@cartouche
-
-CFEngine works on a simple notion of promises. Everything in
-CFEngine can be thought of as a promise to be kept by different
-resources in the system.
-
-Combining promises with patterns to describe where and when
-promises should apply is what CFEngine is all about.
-
-@end cartouche
-
-
-@node Why automation?, Scaling up, Managing expectations - a theory of promises, System automation
-@section Why automation?
-
-
-Humans are good at making decisions and awful at reliable
-implementation. Machines are pitiful at making decisions and very
-good at reliable implementation. It makes sense to let each side do
-the job that they are good at.
-
-The main problem in managing systems is a loss of self-discipline.
-Discipline
-does not imply that order have to be barked from a central command. It
-only requires that every part of the system knows its job and carries
-is out seamlessly and flawlessly.
-
-Skilled workers tend to think that it is enough to be smart. In fact
-this is wrong: smart people tend to be problem solvers and will
-happily solve the same problem many times, wasting time and
-effort. Moreover, human intervention is often based on panic and lack
-of understanding so every time someone logs onto a system by hand,
-they jeopardize everyone's understanding of the system. Only the
-self-discipline of stable procedures leads to predictability.
-
-Ad hoc changes are bad because:
-@itemize
-@item Others have no idea what happened.
-@item There is no record of changes or intentions.
-@item A scar is left from the change.
-@end itemize
-
-
-People often rile against automation saying that it dehumanizes their
-work. In fact the opposite is true: forcing humans to do the work of
-machines, in repetitive and reliable ways is what dehumanizes people.
-The only way to make progress with a bad habit is to recognize it and
-be willing to abandon the habit.
-
-
-@node Scaling up, How do you view CFEngine, Why automation?, System automation
-@section Scaling up
-
-In the past, the only way to scale up system numbers was to make all
-systems identical. This is no longer true.
-
-In the late 1960s journalist and futurist Alvin Toffler sketched a
-pretty compelling vision of the western world and its post-industrial
-future. His book Future Shock, which appeared in 1970, was really a
-reaction to the cold-war fears about a communist industrial state in
-which mass production made everything and everyone identical and
-indistinguishable. His book was really a rebuttal to all those who
-argued that industrialization and mass production implied that
-everything had to be exactly the same, and I recommend reading it - it
-is very well written and has many lessons for us today. But from his
-rather long diatribe, I wrote down a single sentence which for me sums
-up the lesson that we have failed to learn:
-
-@quotation
-@i{"As technology becomes more sophisticated, the cost of introducing
-variations declines."}
-@end quotation
-
-In other words, any half-decent technology for mass production would
-help us to be more sophisticated and multifaceted, not less.
-In an age when you can get business cards printed on demand from an
-ATM at the airport, and personalized coffee mugs in the blink of an
-eye, there is no reason to perpetuate the myth that massive
-infrastructure requires monolithic replication, and yet people still
-do. Network engineers do, and system administrators do. They even say
-that this is essential for scalability.
-
-The importance of Toffler's message was that the economics of mass
-production are not at odds with the economics of adaptation, but 40
-years later, we are still re-learning that lesson.
-
-
-@node How do you view CFEngine, , Scaling up, System automation
-@section How do @i{you} view CFEngine?
-
-CFEngine is a framework. It is not so complex, but it is certainly
-extensive.
-Often when trying to describe CFEngine, it seems that there is too
-much to
-tell and it is hard to convey in a simple way what the software can do.
-The picture below shows a few ways in which you can think of CFEngine.
-
-@center @image{boxes,13cm,,CFEngine application areas,png}
-
-For many users, CFEngine is simply a configuration tool --
-i.e. software for deploying and patching systems according to a
-policy. Policy is described using promises -- indeed, every statement
-in CFEngine 3 is a promise to be kept at some time or location. More
-than this, however, CFEngine is not like most automation tools that
-`roll out' an image of some software once and hope for the best. Every
-promise that you make in CFEngine is continuously verified and
-maintained. It is not a one-off operation, but an encapsulated process
-that repairs itself should anything deviate from the policy.
-
-That clearly places CFEngine in the realm of automation, which often
-begs the question: so it's just another scripting language? Certainly
-CFEngine contains a powerful scripting language, but it is not like
-any other. CFEngine is not a low level language like Perl, Python or
-Ruby; it is a language of promises, in which you express very high
-level intentions about the system and the inner details figure out the
-algorithms needed to implement the result. We'll return to this below.
-
-For many, CFEngine is a tool for implementing security hardening
-procedures on systems, and monitoring them continuously thereafter.
-This is certainly a major application area. CFEngine has a reputation
-for being reliable and secure. That is because its basic design is
-secure: it is not possible to send information about policy to
-CFEngine from outside the system. If access has been granted, it is
-only possible to send a few simple protocol requests of limited length
-to the server. This makes the design safer than most firewalls.
-Most servers fail security tests because it is possible to send
-data to them.
-
-
-The ability to describe almost any kind of policy for a system means
-that we can suggest promises that a system should make and comply
-with. Thus CFEngine can also be thought of as a compliance engine.
-It is easily used to comply with frameworks like SOX, `EUROSOX' (the
-EU 8th Data Directive), ITIL and standards like ISO 17799, ISO 20000,
-etc.
-
-Finally, although CFEngine was not initially conceived for monitoring,
-it
-contains one of the most flexible and lightweight monitoring engines
-around. You can extract data about system configuration, usage,
-resources and log data and turn this into readable reports. CFEngine's
-ability to discover and extract information about the system, combined
-with its reporting means that you can turn the system into a simple
-Configuration Management Database. In the Community edition,
-monitoring is a zero-touch background process. With CFEngine
-commercial extensions, there is almost no limit to the kind of
-monitoring promises you can make, and without the embarrassing resource
-spikes that many monitoring systems produce.
-
-Above all, CFEngine is aimed to promote human understanding of complex
-processes. Its promises are easily documentable using comments that
-the system remembers and reminds us about in error reporting. It hides
-irrelevant and transitory details of implementation so that the
-@i{intentions} behind the promises are highlighted for all to see.
-This means that the knowledge of your organization can be encoded into
-the CFEngine language.
-
-@cartouche
-@i{WHY DOES KNOWLEDGE MATTER? There are two reasons: the first is that
-technical descriptions are hard to remember. You might understand
-your configuration decisions when you are writing them, but a few
-months later when something goes wrong, you will probably have forgotten
-what you were thinking. That costs you time and effort to diagnose.
-The second reason is that organizations are fragile to the loss
-of those individuals who code policy. If they leave, often there is
-no one left who can understand or fix the system. Only with proper
-documentation is it possible to immunize against loss.}
-@end cartouche
-
-
-
-
-
-@c *****************************************************
-@c * CHAPTER
-@c *****************************************************
-
-@node The components of CFEngine, Bodies and bundles, System automation, Top
-@chapter The components of CFEngine
-
-CFEngine comprises a number of components. In this chapter we'll
-consider how to
-build them and what they are for.
-
-
-@menu
-* Installation::
-* Work directory::
-* The players::
-* About the CFEngine architecture::
-* The policy decision flow::
-* Getting started with the Community Edition::
-@end menu
-
-@node Installation, Work directory, The components of CFEngine, The components of CFEngine
-@section Installation
-
-
-To install CFEngine, you will need a few packages. You require:
-
-@table @r
-@item @b{OpenSSL}
-Open source Secure Sockets Layer for encryption.@*URL: @url{http://www.openssl.org
-}
-@item @b{Tokyo Cabinet} (version 1.4.42 or later)
-Lightweight flat-file database system.@*URL: @url{http://fallabs.com/tokyocabinet/}
-@item @b{PCRE}
-Perl Compatible Regular Expression library.@*URL: @url{http://www.pcre.org/}
-
-@item
-On Windows machines, you need to install the basic Cygwin DLL from
-@url{http://www.cygwin.com}
-in order to build CFEngine Community.
-@end table
-
-Additional functionality (some of which is available only in
-commercial extensions) also becomes available if other libraries are
-present, e.g. OpenLDAP, client libraries for MySQL and PostgreSQL,
-etc. It is possible to run CFEngine without these, but related
-functionality will be missing.
-
-Unless you have purchased ready-to-run binaries, or are using a
-package distribution, you will need to compile CFEngine. For this you
-will also need a build environment with @code{gcc}, @code{flex},
-and @code{bison}.
-
-@noindent
-The preferred method of installation is then
-
-@smallexample
-tar zxf CFEngine-x.x.x.tar.gz
-cd CFEngine-x.x.x
-./configure
-make
-make install
-@end smallexample
-
-@noindent
-This results in binaries being installed in @file{/var/cfengine/bin}.
-
-
-@node Work directory, The players, Installation, The components of CFEngine
-@section The work directory
-
-CFEngine keeps a work space directory for its own use. The default
-location for this is @file{/var/cfengine} when run as the root user, and
-@code{~/.cfagent} for other users.
-
-
-@w{}
-@smallexample
-/var/cfengine
-/var/cfengine/bin
-/var/cfengine/inputs
-/var/cfengine/outputs
-@end smallexample
-@c chew end Work directory
-
-A trusted cache of the input files must now be maintained in the
-@file{inputs} subdirectory. When CFEngine is invoked by the scheduler,
-it expects to read only from this directory. It is up to the user to
-keep this cache updated, on each host (this is arranged by the default
-configuration files).
-
-Unlike CFEngine 2, CFEngine 3 does not recognize the
-@code{CF-INPUTS} environment variable.
-
-The @file{outputs} directory is now a record of spooled run-reports.
-These
-are often mailed to the administrator by @code{cf-execd}, or can be
-copied
-to another central location and viewed in an alternative browser.
-
-
-
-@node The players, About the CFEngine architecture, Work directory, The components of CFEngine
-@section The players
-
-A CFEngine system is something like an orchestra.
-It is composed of any number of computers (players), each of which has
-its
-own copy of the music and knows what to play. It might or might not have
-a conductor to help coordinate the individual parts -- that's up to you.
-
-CFEngine's software agents run on each individual computer but can
-communicate if they need to, as depicted the figure below. This means
-you don't have to arrange risky login credentials to run your network
--- and if something goes wrong with the communications network,
-CFEngine is where it needs to be to repair or protect the system
-during the outage.
-
-@image{components,10cm,,CFEngine components,png}
-
-If the network is not working, CFEngine just skips these parts and
-continues
-with what it can do. It is fault tolerant and opportunistic.
-
-@table @emph
-
-@item cf-promises
-The promise verifier and compiler. This is used to pre-check a set of
-configuration promises before attempting to execute.
-
-@item cf-agent
-
-This is the instigator of change. The agent is the part of CFEngine
-that manipulates
-system resources.
-
-@item cf-serverd
-
-The server is able to share files and receive requests to execute
-existing policy on an individual machine. It is not possible to send
-(push) new information to CFEngine from outside.
-
-@item cf-execd
-
-This is a scheduling daemon (which can either supplement or replace
-@code{cron}). It also works as a wrapper, executing and collecting the
-output of @code{cf-agent} and E-mailing it if necessary to a system
-account.
-
-@item cf-runagent
-
-This is a helper program that can talk to @code{cf-serverd} and
-request that it execute @code{cf-agent} with its existing policy. It
-can thus be used to simulate a push of changes to CFEngine hosts, if
-their policy includes that they check for updates.
-
-@item cf-report
-
-This generates summary and other reports in a variety of formats for
-export or integration with other systems.
-
-@item cf-know
-
-This agent can generate an ISO standard Topic Map from a number of
-promises about system knowledge. It is used for rendering documentation
-as a `semantic web'.
-
-@end table
-
-
-
-
-
-
-@node About the CFEngine architecture, The policy decision flow, The players, The components of CFEngine
-@section About the CFEngine architecture
-
-This section explains how CFEngine will operate autonomously in a
-network, under your guidance. If your site is large (thousands of
-servers) you should spend some time discussing with CFEngine experts
-how to tune this description to your environment as @emph{scale}
-requires you to have more infrastructure, and a potentially more
-complicated configuration. The essence of any CFEngine deployment
-is the same.
-
-
-
-There are four commonly cited phases in managing systems, summarized
-as follows:
-
-@itemize
-@item Build
-@item Deploy
-@item Manage
-@item Audit
-@end itemize
-
-These separate phases originate with a model of system management
-based on transactional changes. CFEngine's conception of management
-is somewhat different, as transaction processing is not a good model for
-system management, but we can use this template to see how
-CFEngine works differently.
-
-@table @emph
-@item Build
-A system is based on a number of decisions and resources that need to
-be `built' before they can be implemented. Building the trusted
-foundations of a system is the key to guiding its development. You
-don't need to decide every detail, just enough to build trust and
-predictability into your system.
-
-In CFEngine, what you build is a template of proposed promises for the
-machines in an organization such that, if the machines all make and
-keep these promises, the system will function seamlessly as
-planned. This is how it works in a human organization, and this is how
-is works for computers too.
-
-@item Deploy
-Deploying really means implementing the policy that was already
-decided. In transaction systems, one tries to push out changes one by
-one, hence `deploying' the decision. In CFEngine you simply publish
-your policy (in CFEngine parlance these are `promise proposals') and
-the machines see the new proposals and can adjust accordingly. Each
-machine runs an agent that is capable of implementing policies and
-maintaining them over time without further assistance.
-
-@item Manage
-Once a decision is made, unplanned events will occur. Such
-incidents traditionally set off alarms and humans rush to make new
-transactions
-to repair them. In CFEngine, the autonomous agent manages the system,
-and you only have to deal with rare events that cannot be dealt with
-automatically.
-
-@item Audit
-In traditional configuration systems, the outcome is far from clear
-after a one-shot transaction, so one audits the system
-to determine to discover what actually happened. In CFEngine, changes
-are not just initiated once, but locally audited and maintained.
-Decision outcomes are assured by design in CFEngine and maintained
-automatically, so the main worry is managing conflicting
-intentions. Users can sit back and examine regular reports of
-compliance generated by the agents, without having to arrange
-for new `roll out' transactions.
-
-@end table
-
-@cartouche
-@emph{ROLL-OUT and ROLL-BACK? You should not think of CFEngine as a
-roll-out system, i.e. one that attempts to force out absolute changes
-and perhaps reverse them in case of error. Roll-out and roll-back are
-theoretically flawed concepts that only sometimes work in practice.
-With CFEngine, you publish a sequences of policy revisions, always
-moving forward (because like it or not, time only goes in one
-direction). All of the desired-state changes are managed locally by
-each individual computer, and continuously repaired to ensure on-going
-compliance with policy. }
-@end cartouche
-
-@node The policy decision flow, Getting started with the Community Edition, About the CFEngine architecture, The components of CFEngine
-@section The policy decision flow
-
-CFEngine does not make absolute choices for you, like other
-tools. Almost everything about its behaviour is matter of policy and
-can be changed. However, a structure for use, like the following, is
-recommended (see the following figure).
-
-In order to keep operations as simple as possible, CFEngine maintains
-a private working directory on each machine referred to in
-documentation as WORKDIR and in policy by the variable
-@code{$(sys.workdir)}. By default, this is located at
-@file{/var/cfengine} or @file{C:\var\CFEngine}. It contains everything
-CFEngine needs to run.
-
-The figure below shows how decisions flow through the parts of a system.
-
-@image{arch,15cm,,The CFEngine architecture,png}
-
-
-@itemize
-@item
-It makes sense to have a single point of coordination. Decisions are
-therefore usually made in a single location (the Policy Definition
-Point). The history of decisions and changes can be tracked by a
-version control system of your choice (e.g. Subversion, CVS, etc.).
-
-@item
-Decisions are made by editing CFEngine's policy file
-@file{promises.cf} (or one of its included sub-files). This process is
-carried out off-line.
-
-@item
-Once decisions have been formalized and coded, this new policy is
-copied @emph{manually} (a human decision) to a @emph{decision
-distribution point}, which by default is located in the directory
-@file{/var/cfengine/masterfiles} on all policy distribution servers.
-
-In this introduction, we shall assume that there is only one central
-policy distribution server, a specially-appointed server which is
-referred to simple as the @code{policy server}.
-
-
-@item
-Every client machine contacts the policy server and downloads these
-updates. The policy server can be replicated if the number of clients
-is very large, but we shall assume here that there is only one policy
-server.
-@end itemize
-
-Once a client machine has a copy of the policy, it extracts only those
-promise proposals that are relevant to it, and implements any changes
-without human assistance. This is how CFEngine manages change.
-
-@cartouche
-
-@emph{WHY DO THIS? CFEngine tries to minimize dependencies by decoupling
-processes. By following this pull-based architecture, CFEngine will
-tolerate network outages and will recover from deployment errors
-easily. By placing the burden of responsibility for decision at the
-top, and for implementation at the bottom, we avoid needless fragility
-and keep two independent quality assurance processes apart.}
-
-@end cartouche
-
-
-@node Getting started with the Community Edition, , The policy decision flow, The components of CFEngine
-@section Getting started with the Community Edition
-
-The quickest way to get started with CFEngine is to download and install binary packages, available from @url{http://cfengine.com/inside/myspace}. Installing and bootstrapping these is a trivial operation, putting you two steps away from testing your first CFEngine policies.
-
-@cartouche
-Note: There is a bug in Community 3.3.0 where the default policy files are not copied to @code{/var/cfengine/masterfiles} upon bootstrap. Workaround consists in manually copying these files before bootstrapping:
-@verbatim
-cp /var/cfengine/share/CoreBase/*.cf /var/cfengine/masterfiles/
-@end verbatim
-This will be corrected in a bugfix release coming soon.
-@end cartouche
-
-This procedure applies to all hosts, but you should bootstrap the hub (policy server) first. Find the hostname or IP address of the hub, here we assume the address is '123.456.789.123' (do not bootstrap with a localhost address).
-@verbatim
-
- host# /var/cfengine/bin/cf-agent --bootstrap 123.456.789.123
-
-@end verbatim
-
-CFEngine will output diagnostic information upon bootstrap (written to command line and syslog; cf-agent will also return a value: ERROR: 1, SUCCESS: 0). Error messages will be displayed if bootstrapping failed, pursue these to get and indication of what went wrong and correct accordingly. If all is well you should see the following in the output:
-
-@verbatim
-
--> Bootstrap to 123.456.789.123 completed successfully
-
-@end verbatim
-
-As an alternative to installing binary packages, the following steps outline the procedure when you have built from source (available from @url{http://cfengine.com/source_code}). You will then need to copy the distributed policy files that were installed in
-@file{/var/cfengine/share/CoreBase/} to a policy distribution point, like
-this:
-
-@enumerate
-@item Decide on your policy server.
-
-@item Become root or Administrator on that server.
-
-@item Create the policy source directory and populate the cache:
-@smallexample
- host# /var/cfengine/bin/cf-key
- host# cp /var/cfengine/share/CoreBase/*.cf /var/cfengine/masterfiles/
- host# /var/cfengine/bin/cf-agent --bootstrap 123.456.789.123
-@end smallexample
-@end enumerate
-
-@sp 1
-CFEngine should be up and running on your system after the bootstrap. It will copy its default policy files into @file{/var/cfengine/masterfiles} on the hub (policy server) provided that the directory is empty (fresh install). This directory is the definition point for your policy, meaning that clients will contact the hub and copy these files to their @file{/var/cfengine/inputs} directory. Note that the policy hub also works as a client against itself, so it too will copy from @file{/var/cfengine/masterfiles} to @file{/var/cfengine/inputs}. You should browse the files in @file{/var/cfengine/masterfiles} to see what they contain, and perhaps make some alterations to adapt to your environment.
-
-To see which CFEngine processes are running:
-
-@smallexample
-
-host# ps waux | grep cf-
-
-@end smallexample
-
-Note: If you have manually configured a different location for the
-CFEngine work directory,
-you will need to adapt these lines above to replace @file{/var/
-CFEngine} with the path
-you have configured; e.g. Debian based packages feel that @file{/var/
-lib/CFEngine}
-is the right location for this.
-
-
-@c *****************************************************
-@c * CHAPTER
-@c *****************************************************
-
-@node Bodies and bundles, First promises, The components of CFEngine, Top
-@chapter Bodies and bundles
-
-To emphasize the fact that CFEngine is not an imperative programming
-language, and to keep closely to the nomenclature of Promise Theory,
-CFEngine uses two concepts throughout: bundles and bodies.
-
-
-@menu
-* Bodies::
-* Bundles::
-* A simple syntax pattern::
-@end menu
-
-@node Bodies, Bundles, Bodies and bundles, Bodies and bundles
-@section Bodies
-
-Promises are the fundamental statements in CFEngine. Promises are the policy atoms.
-If there is no promise, nothing happens.
-
-However, promises can become quite complicated and readability becomes
-an issue, so it is useful to have a way of breaking them down into independent
-components. The structure of a promise is this:
-
-@table @i
-@item Promiser
-This is the object that formally makes the promise. It is always the @i{affected object},
-since objects can only make promises about their own state or behavior in CFEngine.
-
-@item Promisee (optional)
-This is a possible stakeholder, someone who is interested in the outcome of the
-promise. It is used as documentation, and it is used for reasoning in the commercial
-CFEngine product.
-
-@item Promise body
-Everything else about a promise is defined in the body of the promise.
-We use this word in the sense of `body of a contract' or the `body of a document'
-(like @code{}) tags in HTML, for example.
-
-A promise body is a list of declarations of the following form:
-
-@verbatim
-CFEngine_attribute_type => user_defined_value or template
-@end verbatim
-
-@end table
-
-@menu
-* Body parts::
-* Control bodies::
-@end menu
-
-@node Body parts, Control bodies, Bodies, Bodies
-@subsection Body parts
-
-The CFEngine reserved word @code{body} is used to define
-@i{parameterized templates} for bodies to hide the details of complex
-promise specifications. For complex body lists, you must fill in a
-body declaration as an `attachment' to the promise, e.g.
-
-@verbatim
-files:
-
- "/tmp/promiser" # Promiser
-
- perms => myexample; # The body is just one line,
- # but needs an attachment
-
-@end verbatim
-The attachment is declared like this, with a `type' that matches the left
-hand side of the declaration in the promise:
-@verbatim
-body perms myexample
-{
-mode => "644";
-owners => { "mark", "sarah", "angel" };
-groups => { "users", "sysadmins", "mythical_beasts" };
-}
-@end verbatim
-The structure is this:
-
-@sp 1
-@cartouche
-@smallexample
-
- @var{promiser}
-
- @b{LVALUE} => @var{RVALUE}
-
-..
-
-body @b{LVALUE} @var{RVALUE}
-@{
-@b{LVALUE} => @var{RVALUE};
-@b{LVALUE} => @var{RVALUE};
-@}
-@end smallexample
-@end cartouche
-@sp 1
-
-Another way of looking at it is this:
-
-@sp 1
-@cartouche
-@smallexample
-
- @var{promiser}
-
- @b{CFEngine_word} => @var{user_defined_value}
-
-..
-
- body @b{CFEngine_word} @var{user_defined_value}
- @{
- @b{CFEngine_word} => @var{user_defined_value};
- @b{CFEngine_word} => @var{user_defined_value};
- ...
- @}
-
-@end smallexample
-@end cartouche
-@sp 1
-
-Body attachments are required items. You cannot choose to put the
-attachments in-line. This is a lesson that was learned from CFEngine
-2. Readability is quickly lost if too many details are placed in-line.
-
-@center @image{body_bundle,10cm}
-
-@node Control bodies, , Body parts, Bodies
-@subsection Control bodies
-
-Some promises in CFEngine are implicit. They are hard-coded into the program.
-For example, the fact that CFEngine looks for a number of files to read and
-will execute them in a sequence is hard coded. You cannot change this.
-However, you can change the behavior of such promises by setting control
-parameters. These are formally parts of the `promise body' for these hard-coded
-promises, so we use the body structure to set them. Each agent has a special
-body whose name is @code{control}; e.g.
-
-@verbatim
-body agent control
-{
-bundlesequence => { "test" };
-}
-@end verbatim
-
-
-@node Bundles, A simple syntax pattern, Bodies, Bodies and bundles
-@section Bundles
-
-A bundle is a simple concept. A bundle is merely a collection of promises
-in a `sub-routine-like' container. The purpose of bundles is to allow
-you greater flexibility to break down the contents of your policies and
-give them names. Bundles also allow you to re-use promise code by
-parameterizing it.
-
-Like bodies, bundles also have `types'. Bundles belong to the agent that
-is used to keep the promises in the bundle. So @code{cf-agent} has bundles
-declared as
-
-@verbatim
-bundle agent my_name
-{
-}
-@end verbatim
-
-@noindent The @code{cf-serverd} program has bundles declared as:
-@verbatim
-bundle server my_name
-{
-}
-@end verbatim
-@noindent and so on.
-
-
-
-@menu
-* Bundle scope::
-@end menu
-
-@node Bundle scope, , Bundles, Bundles
-@subsection Bundle scope
-
-Variables and classes defined inside bundles are not directly visible outside.
-All variables in CFEngine are globally accessible, however if you refer to a variable
-by @samp{$(unqualified)}, then it is assumed to belong to the current bundle. To
-access any other (scalar) variable, you must qualify the name using the name of
-the bundle in which it is defined:
-@samp{$(bundle_name.qualified)}.
-
-Some promise types, like @code{var}, @code{classes} may be made
-by any agent. These are called @code{common} promises. Bundles of type @code{common}
-are special. They may contain common promises.
-Classes defined in common bundles have global scope.
-
-@node A simple syntax pattern, , Bundles, Bodies and bundles
-@section A simple syntax pattern
-
-The syntax of CFEngine follows a simple pattern in all cases. Once you have learned this pattern,
-it will make sense anywhere in the program. The figure below illustrates
-this pattern. Some words are reserved by CFEngine, and are used as types or categories
-for talking about promises. Other words (in blue) are to be defined by you.
-Look at the examples and try to identify these patterns yourself.
-
-@image{cfengineword,14cm}
-
-
-@c *****************************************************
-@c * CHAPTER
-@c *****************************************************
-
-@node First promises, A simple crash course in concepts, Bodies and bundles, Top
-@chapter How to execute and test a CFEngine policy
-
-
-You do not need root privilege to use CFEngine. Most experiments can
-be safely tested as an ordinary user. You should spend some time
-experimenting with small examples before setting out to configure a
-system. To do that you should log onto your system as a regular
-unprivileged user and set up:
-
-@smallexample
-host$ /var/cfengine/bin/cf-key
-host$ cp /var/cfengine/bin/cf-* ~/.cfagent/bin
-@end smallexample
-
-@noindent CFEngine wants to see copies of its binaries in its
-work directory. For a regular user this lies in @file{~/.cfagent}
-rather than @file{/var/cfengine}. You should now be ready to go.
-
-@c ........................................................................
-
-@menu
-* Hello world::
-* Checking a file::
-* Changing a password::
-* The update bundle - provisioning::
-* Reporting::
-* cf-execd::
-@end menu
-
-@node Hello world, Checking a file, First promises, First promises
-@section Hello world
-
-Here is the simplest `Hello world' program in CFEngine 3:
-
-@verbatim
-
-# Every policy must have a bundlesequence
-
-body common control
-{
-bundlesequence => { "test" };
-}
-
-#
-
-bundle agent test
-{
-reports: # This is a promise type
-
- cfengine_3:: # This is a class context (the promise will only
- # be kept on a CFEngine_3 system)
-
- "Hello world"; # This is a simple promise (it generates a report
- # that says "Hello world")
-}
-
-@end verbatim
-
-@noindent Type this in to a file, e.g. @samp{emacs ~/test.cf}. Then
-check
-the syntax like this
-@smallexample
-/var/cfengine/bin/cf-promises -f ~/test.cf
-@end smallexample
-If all is well there should be no output.
-Now execute as follows:
-@smallexample
-/var/cfengine/bin/cf-agent -f ~/test.cf
-@end smallexample
-You should see this:
-@smallexample
-R: Hello world
-@end smallexample
-The @samp{R:} tells you this is the output from a report (as opposed
-to a log @samp{L:}, or the quoted output of some embedded program
-@samp{Q:}).
-
-
-@noindent This is not a typical CFEngine program, primarily because
-CFEngine is not
-normally meant to print messages except in exceptional circumstances.
-As a starter
-however, it is reassuring to see some output.
-
-If you repeat the command immediately nothing will happen. But if you
-wait
-a minute, it will work again. Run the command in verbose mode (use the
-@code{-v} or the @code{--verbose} switch) to see why:
-
-@smallexample
-/var/cfengine/bin/cf-agent --verbose -f ~/test.cf
-@end smallexample
-Now you will see:
-@smallexample
-cf3> =========================================================
-cf3> reports in bundle hello (1)
-cf3> =========================================================
-cf3>
-cf3> XX Nothing promised here [lock.hello.reports..Hello_worl] (0/1
-minutes elapsed)
-cf3>
-@end smallexample
-This tells you that CFEngine believes it is too soon to try to keep
-this promise
-again. The time it sets on this is determined by the @code{ifelapsed}
-parameter, which
-can be set individually for every promise. You can also ask CFEngine
-to ignore these
-locks using the @samp{-K} option.
-
-Before the `Hello world' string, you see the class expression
-@samp{cfengine_3::}. This is how CFEngine makes decisions. The
-promise to print the message will only apply if this condition is
-true. To see that this class is true for the execution, look at the
-verbose output from the command you just typed. You will see something
-like this:
-
-@smallexample
-Defined Classes = ( any verbose_mode Tuesday Hr08 Morning Min48
-Min45_50 Q4 Hr08_Q4 Day7 July Yr2009 Lcycle_2 GMT_Hr6 linux atlas
-undefined_domain 64_bit linux_2_6_27_23_0_1_default x86_64
-linux_x86_64 linux_x86_64_2_6_27_23_0_1_default
-linux_x86_64_2_6_27_23_0_1_default__1_SMP_2009_05_26_17_02_05__0400
-compiled_on_linux_gnu localhost_localdomain localhost net_iface_lo
-net_iface_wlan0 ipv4_192_168_1_100 ipv4_192_168_1 ipv4_192_168
-ipv4_192 fe80__21c_bfff_fe6e_70ef CFEngine_3_0_2b4 CFEngine_3_0
-@b{CFEngine_3} SuSE lsb_compliant suse suse_n/a suse_11_1 suse_11
-agent )
-@end smallexample
-i.e. a list of all the currently defined classes. Any one of these
-classes
-(or a combination) could have been used to label the promise.
-That is the way CFEngine points to which promises will be kept in which
-scenarios.
-
-A final thing to note: if you try to process this using the
-@samp{cf-promises -r} command, you will see something like this:
-
-@smallexample
-atlas$ ~/LapTop/CFEngine3/trunk/src/cf-promises -r -f ~/test.cf
-Summarizing promises as text to ~/test.cf.txt
-Summarizing promises as html to ~/test.cf.html
-@end smallexample
-
-@noindent The @samp{-r} option produces a report. Examine the files
-produced:
-
-@smallexample
-cat ~/test.cf.txt
-firefox ~/test.cf.html
-@end smallexample
-
-You will see a summary of how CFEngine interprets the files, either in
-HTML or text. All the CFEngine components will produce debugging file
-with an expanded view when using this option
-(e.g. for the configuration file named @file{promise_output_agent.h},
-they will create the files @file{promise_output_agent.html} and
-@file{promise_output_agent.txt}).
-
-
-
-
-@c ---------------------------------------------------------------------------
-@node Checking a file, Changing a password, Hello world, First promises
-@section Checking a file
-
-Type in the following example:
-
-@verbatim
-
-body common control
-{
-bundlesequence => { "test" };
-inputs => { "cfengine_stdlib.cf" };
-}
-
-bundle agent test
-{
-files:
-
-# This is a throw-away comment, below is a full-bodied promise
-
-"/tmp/testfile" # promiser
-
- comment => "This is for keeps...", # Live comment
- create => "true", # Constraint 1
- perms => m("612"); # Constraint 2, rw---x-w-
-
-}
-
-@end verbatim
-
-In the CFEngine Community Open Promise-Body Library (CFEngine_stdlib.cf) is a library of
-definitions that can be obtained from the CFEngine website. It should be
-included in the @file{inputs} directory and input as above.
-Within that file, the template @samp{m} is defined:
-@verbatim
-# This is a trivial body template, which makes parameterizing
-# the promise body tidier and re-usable
-
-body perms m(x)
-{
-mode => "$(x)";
-}
-
-@end verbatim
-This example shows how additional attributes are added to the body of
-the promise. The right hand side of the @code{perms} declaration is a
-template which we have called @samp{m()}, which uses a parameter. The
-template is defined below the bundle of promises that uses it, showing
-how we can create re-usable sets of parameters. In this case, the
-example is trivial, but we have barely begun. When things get more
-sophisticated, we shall hide a huge amount of detail in these
-parameters, thus keeping the main promise uncluttered and its
-intention clear.
-
-@cartouche
-
-In every `promise constraint' of the form @samp{left-hand-side =>
-right-hand-side}, the left hand side is a CFEngine reserved word, and
-the right hand side is a decision you make, possibly expressed in
-terms of standard templates.
-
-@end cartouche
-
-Now execute @code{cf-agent} with this promise:
-@smallexample
-@b{host$} /var/cfengine/bin/cf-agent -f /tmp/test.cf -I
--> Object /tmp/testfile had permission 600, changed it to 612
-
-@b{host$} ls -l /tmp/testfile
--rw---x-w- 1 mark users 33 2009-06-30 06:06 /tmp/testfile
-@end smallexample
-The @samp{-I} flag tells CFEngine to `inform' us about changes only.
-This provides a digestible amount of output that is more than the
-default (which is to only report un-fixable problems or explicit
-reports). We see that CFEngine creates the file as ordered, and sets
-the permissions appropriately. Now try to change the permissions:
-@smallexample
-@b{host$} chmod 400 /tmp/testfile
-
-@b{host$} ls -l /tmp/testfile
--r-------- 1 mark users 33 2009-06-30 06:06 /tmp/testfile
-
-@b{host$} /var/cfengine/bin/cf-agent -f /tmp/test.cf -I
--> Object /tmp/testfile had permission 400, changed it to 612
-
-@b{host$} ls -l /tmp/testfile
--rw---x-w- 1 mark users 33 2009-06-30 06:06 /tmp/testfile
-@end smallexample
-Once again, remember the comment about locking and @code{ifelapsed}
-from the previous example.
-
-
-Notice that this promise does not have a class expression like
-@code{cfengine_3::}.
-The default class @code{any::} applies if nothing is stated, which means
-`anytime, anyplace, anywhere'.
-
-
-
-@c ---------------------------------------------------------------------------
-@node Changing a password, The update bundle - provisioning, Checking a file, First promises
-@section Changing a password
-
-To change root password of a system, we need to edit a file. A file is
-a complex object -- once open there is a new world of possible
-promises to make about its contents. CFEngine has bundles of promises
-that are specially for editing. Make a copy of a shadow file and copy
-it to @file{/tmp} so that you can play with it.
-@verbatim
-
-body common control
-{
-bundlesequence => { "test" };
-inputs => { "cfengine_stdlib.cf" };
-}
-
-bundle agent test
-{
-files:
-
-"/tmp/shadow"
- comment => "Set the root password",
- edit_line => set_user_field("root",2,"xyajd673j.ajhfu");
-
-}
-@end verbatim
-This is all we need to see on first inspection to understand the
-promise that is being
-made.
-
-
-
-@node The update bundle - provisioning, Reporting, Changing a password, First promises
-@section The update bundle - provisioning
-
-The default CFEngine configuration contains a bundle of promises that
-copies the CFEngine binaries into the cache directory and copies
-the policy files from the server into the default location. This example
-is for local copying from file to file on the filesystem. Later, when we
-set up a server component, you will be able to copy from a remote host.
-This is a simple example of system provisioning, with automated update.
-
-@verbatim
-
-bundle agent update
-{
-vars:
-
-# A standard location for the source point
-"master_location" string => "/var/cfengine/masterfiles";
-
-files:
-
-"/var/cfengine/inputs"
-
- comment => "Update the policy files from the master",
- perms => u_m("600"),
- copy_from => u_cp("$(master_location)","localhost"),
- depth_search => u_recurse("inf");
-}
-
-@end verbatim
-These promises contain several attributes in their bodies that we have
-not seen yet. The @code{copy_from} attribute tells CFEngine how to
-source
-(copy) a file from a master location. The @code{depth_search} tells it
-to search recursively through the sub-directories and their files.
-
-Try changing the source files and executing the agent.
-
-Again there are library reusable templates:
-@verbatim
-
-body perms u_m(p)
-{
-mode => "$(p)";
-}
-
-#
-
-body copy_from u_cp(from,server)
-{
-servers => { "$(server)", "failover.example.org" };
-source => "$(from)";
-compare => "digest";
-}
-
-#
-
-body depth_search u_recurse(d)
-{
-depth => "$(d)";
-exclude_dirs => { "\.X11", ".*kde.*", "logs", "log" };
-}
-
-@end verbatim
-
-@noindent Here is an exercise: try using the reference manual to look up
-the elements in this example. See if you can understand all the parts.
-
-
-@node Reporting, cf-execd, The update bundle - provisioning, First promises
-@section Reporting
-
-CFEngine contains a report generator called @file{cf-report}. It is
-configured
-using control parameters described in the next chapter. Try:
-
-@verbatim
-host$ /var/cfengine/bin/cf-report
-host$ ls ~/.cfagent/reports
-host$ mywebbrowser ~/.cfagent/reports/performance.html
-@end verbatim
-
-Most of these reports will be blank at the start, until you have run
-CFEngine
-on some significant promises.
-
-@node cf-execd, , Reporting, First promises
-@section @code{cf-execd}
-
-CFEngine contains a service for running the agent with its default
-configuration in @file{WORKDIR/inputs/promises.cf} called the
-exec-daemon. If you execute the binary directly it will go into the
-background and execute @file{cf-agent} every five minutes by default,
-with its default policy.
-
-You can try running it in the foreground:
-
-@verbatim
-host$ /var/cfengine/bin/cf-execd -F
-@end verbatim
-
-When you run CFEngine like this, any output that comes from CFEngine
-is collected
-and placed in @file{WORKDIR/outputs}. If you have configured an email
-address and
-your host is running an SMTP service, then it will be sent as email.
-To configure
-this you would add a control body to the @file{promises.cf} file
-
-@verbatim
-body executor control
-
-{
-splaytime => "1";
-mailto => "cfengine_mail@example.org";
-smtpserver => "localhost";
-mailmaxlines => "30";
-}
-
-@end verbatim
-These other lines change different aspects of the hard-wired behavior
-of the
-executor, e.g. a load-balancing time delay before execution of the
-agent, a mail address,
-the name or IP address of an SMTP (mail) service, and the maximum
-number of lines
-of output to be included in any email sent.
-
-You should start to see a pattern in the way CFEngine is configured.
-In the next
-chapter, we'll look at these general matters.
-
-
-
-
-@c --------------------------------------------------------------------------
-@node A simple crash course in concepts, Using CFEngine as a front-end for cron, First promises, Top
-@chapter A simple crash course in concepts
-
-
-@menu
-* Rules are promises::
-* Control promises::
-* Variables::
-* Decisions::
-* Loops::
-* The main promise types::
-@end menu
-
-@node Rules are promises, Control promises, A simple crash course in concepts, A simple crash course in concepts
-@section Rules are promises
-
-Everything in CFEngine 3 can be interpreted as a promise. Promises can
-be made about all kinds of different subjects, from file attributes,
-to the execution of commands, to access control decisions and
-knowledge relationships.
-
-This simple but powerful idea allows a very practical uniformity in
-CFEngine syntax. There is only one grammatical form for statements in
-the language that you need to know and it looks generically like this:
-
-@smallexample
-
-type:
-
-classes::
-
- "promiser" -> @{ "promisee1", "promisee2", ... @}
-
- attribute_1 => value_1,
- attribute_2 => value_2,
- ...
- attribute_n => value_n;
-
-@end smallexample
-
-@noindent
-We speak of a promiser (the abstract object making the promise), the
-promisee is the abstract object to whom the promise is made, and then
-there is a list of associations that we call the `body' of the
-promise, which together with the promiser-type tells us what it is all
-about.
-
-@cartouche
-The promiser is always the object
-affected by the promise.
-@end cartouche
-
-Not all of these elements are necessary every time. Some promises
-contain a lot of implicit behavior. In other cases we might want to
-be much more explicit. For example, the simplest reports promise
-looks like this:
-
-@smallexample
-
-reports:
-
-"hello world";
-
-@end smallexample
-
-And the simplest commands promise looks like this
-
-@smallexample
-
-commands:
-
-"/bin/echo hello world";
-
-@end smallexample
-
-@noindent
-This promise has default attributes for everything except the
-`promiser', i.e. the
-command string that promises to execute.
-A more complex promise contains many attributes:
-
-@smallexample
-
-# Promise type
-files:
-
-# promiser -> promisee (no curly braces needed if only one)
-"/home/mark/tmp/test_plain" -> "system blue team",
-
- # attribute => value
- comment => "This comment follows the rule for knowledge integration",
- perms => owner("@@(usernames)"),
- create => "true";
-
-@end smallexample
-The list of promisees is not used by CFEngine except for
-documentation, just
-as the comment attribute (which can be added to any promise) has no
-actual function
-other than to provide more information to the user in error tracing
-and auditing.
-
-You see several kinds of object in this example. All literal strings
-(e.g. @code{"true"}) in CFEngine 3 must be quoted. This provides
-absolute consistency and makes type-checking easy and error-correction
-powerful. All function-like objects (e.g. @code{users("..")}) are
-either built-in
-special functions or parameterized templates which contain the `meat'
-of the right hand
-side.
-
-
-@node Control promises, Variables, Rules are promises, A simple crash course in concepts
-@section Control promises
-
-Certain promises that CFEngine components make are hard-wired into their
-code. For example, the promise to email output to an appropriate
-address, or the promise to wait until a certain time has elapsed before
-checking a promise again (@code{ifelapsed}). Although these promises are
-hard-wired, their behavior can be changed. In CFEngine, behavior is
-always
-constrained by the promise body. Thus hard-wired behavior is altered by
-changing the control body for each. You can find these alterable
-parameters
-in the reference manual.
-
-The most important bundle is the @code{common} bundle, that is read by
-all components of CFEngine. It contains the list of promise bundles
-that should be read in and examined for promise suggestions. From the
-@file{promises.cf} file:
-
-@verbatim
-
-body common control
-{
-bundlesequence => {
- "update",
- "garbage_collection",
- "main",
- "cfengine"
- };
-
-inputs => {
- "update.cf",
- "site.cf",
- "library.cf"
- };
-}
-
-#######################################################
-
-body agent control
-{
-# if default runtime is 5 mins we need this for long jobs
-ifelapsed => "15";
-}
-
-#######################################################
-
-body monitor control
-{
-forgetrate => "0.7";
-histograms => "true";
-}
-
-#######################################################
-
-body executor control
-
-{
-splaytime => "1";
-mailto => "cfengine_mail@example.org";
-smtpserver => "localhost";
-mailmaxlines => "30";
-}
-
-#######################################################
-
-body runagent control
-{
-hosts => {
- "127.0.0.1"
- # , "myhost.example.com:5308", ...
- };
-
-}
-
-#######################################################
-
-body server control
-
-{
-allowconnects => { "127.0.0.1" , "::1" };
-allowallconnects => { "127.0.0.1" , "::1" };
-trustkeysfrom => { "127.0.0.1" , "::1" };
-
-# Make updates and runs happen in one
-
-cfruncommand => "$(sys.workdir)/bin/cf-agent -f failsafe.cf &&
-$(sys.workdir)/bin/cf-agent";
-allowusers => { "root" };
-}
-
-@end verbatim
-
-
-@node Variables, Decisions, Control promises, A simple crash course in concepts
-@section Variables
-
-Variables (or "variable definitions") are also promises -- the promise to
-represent their values. We can write these in
-any promise bundle. CFEngine recognizes two object types: scalars and
-lists (lists contain 0 or more objects), as well as
-three data-types (string, integer and real). Typing in CFEngine is
-dynamic, as in
-Perl and other scripting languages. Thus variables of any data-type
-may be used as strings.
-
-
-@menu
-* Scalar variable expansion::
-* List variables::
-* List variable substitution and expansion::
-@end menu
-
-@node Scalar variable expansion, List variables, Variables, Variables
-@subsection Scalar variables
-
-Scalar variables hold a single value. The are declared as follows:
-
-@smallexample
-bundle @i{} name
-@{
-vars:
-
-"my_scalar" string => "String contents...";
- "my_int" int => "1234";
- "my_real" real => "567.89";
-
-@}
-
-@end smallexample
-
-The @samp{@i{}} indicates that any kind of bundle applies here.
-Scalar variables are referenced by @samp{$(name)} (or
-@samp{$@{name@}}) and they represent
-a single value at a time.
-
-@itemize
-@item Scalars that are written without a context, e.g. @samp{$(myvar)}
-are local to the current bundle.
-
-@item Scalars are globally available everywhere provided one
-uses the context to verify them e.g. @samp{$(context.myvar)}
-may be written to access the variable `myvar' in bundle `context'.
-@end itemize
-
-@c -----------------------------------------------------------------------
-@node List variables, List variable substitution and expansion, Scalar variable expansion, Variables
-@subsection List variables
-
-List variables hold several values. The are declared as follows:
-
-@smallexample
-bundle @i{} name
-@{
-vars:
-
- "my_slist" slist => @{ "list", "of", "strings" @};
- "my_ilist" ilist => @{ "1234", "5678" @};
- "my_rlist" rlist => @{ "567.89" @};
-
-@}
-
-@end smallexample
-An entire list is referred to with the at symbol @samp{@@}, but it does
-not usually make sense to use this reference in a string. For instance
-@smallexample
-
-reports:
-
- cfengine_3::
-
- "My list is @@(my_slist)";
-
-@end smallexample
-@noindent means nothing and cannot be expanded (it does not generate an
-error, but instead inserts the text @@(my_slist) into the string); but if
-we use the scalar reference to a list variable, CFEngine will iterate over
-the values in
-the list essentially making this into a list of promises.
-
-@noindent To summarize:
-@itemize
-
-@item Scalar references to @i{local} list variables imply iteration,
-e.g.
-suppose we have local list variable @samp{@@(list)}, then the
-scalar @samp{$(list)} implies an iteration over every value of the
-list.
-
-
-@item Lists can be passed in their entirety in any context
-where a list is expected as @samp{@@(list)}., e.g.
-
-@verbatim
-
-vars:
-
-"longlist" slist => { @(shortlist), "plus", "plus" };
-
-"shortlist" slist => { "you", "me" };
-
-@end verbatim
-
-The declaration order does not matter -- CFEngine will execute the promise
-to assign the variable @samp{@@(shortlist)} before the promise to assign the
-variable @samp{@@(longlist)}.
-
-@item Only local lists can be expanded directly. Thus @samp{$(list)}
-can be expanded but not @samp{$(context.list)}. Global
-list references have to be mapped into a local context if you want to
-use them for iteration. See the reference manual for more information.
-
-@end itemize
-
-@c -----------------------------------------------------------------------
-@node List variable substitution and expansion, , List variables, Variables
-@subsection Associative arrays
-
-Associative array variables also hold several values. The are declared
-as follows:
-
-@smallexample
-bundle @i{} name
-@{
-vars:
-
- "switches[mellow]" int => "1";
- "switches[relaxed]" int => "1";
- "off_keys" slist => @{ "red", "grouchy", "coarse", "febrile" @};
- "switches[$(off_keys)]" int => "0";
-
-@}
-
-@end smallexample
-
-See the reference manual for information on the @samp{getindices} function
-and other details of associative arrays.
-
-@node Decisions, Loops, Variables, A simple crash course in concepts
-@section Decisions
-
-CFEngine decisions are made behind the scenes and the results of
-certain true/false propositions are cached in Booleans referred to as
-`classes'. There are no if-then-else statements in CFEngine; all
-decisions are made with classes.
-
-CFEngine runs on every computer individually and each time it wakes up
-the underlying generic agent platform discovers and classifies
-properties of the environment or context in which it runs. This
-information
-is effectively cached and may be used to make decisions about
-configuration.
-
-Classes fall into hard (discovered) and soft (user-defined) types. A
-single hard class can be one of several things:
-
-@itemize @bullet
-
-@item The name of an operating system architecture e.g.
-@code{ultrix}, @code{sun4}, etc.
-
-@item The unqualified name of a particular host. If your system
-returns a fully
-qualified domain name for your host, CFEngine truncates it at the
-first dot. Note: @code{www.sales.company.com} and
-@code{www.research.company.com} have the same unqualified name -- @code{www}.
-
-@item The name of a user-defined group of hosts.
-
-@item A day of the week (in the form @code{Monday, Tuesday,
-Wednesday, ..}).
-
-@item An hour of the day, current time zone (in the form @code{Hr00,
-Hr01 ... Hr23}).
-
-@item An hour of the day GMT (in the form @code{GMT_Hr00, GMT_Hr01 ...
-GMT_Hr23}).
-This is consistent the world over, in case you need virtual
-simultaneity of change
-coordination.
-
-@item Minutes in the hour (in the form @code{Min00, Min17 ... Min45}).
-
-@item A five minute interval in the hour (in the form @code{Min00_05,
-Min05_10 ... Min55_00})
-
-@item The quarter-hour (in the form @code{Q1, Q2, Q3, Q4}).
-
-@item A day of the month (in the form @code{Day1, Day2, ... Day31}).
-
-@item A month (in the form @code{January, February, ... December}).
-
-@item A year (in the form @code{Yr1997, Yr2004}).
-
-@item A shift in @code{Night,Morning,Afternoon,Evening}, which fall
-into six hour blocks
-starting at 00:00 hours.
-
-@item A `lifecycle index', which is the year number modulo 3 (used in
-long term resource memory).
-
-@item An arbitrary user-defined string.
-
-@item The IP address octets of any active interface (in the form
-@code{@w{ipv4_192_0_0_1}},
-@code{@w{ipv4_192_0_0}}, @code{@w{ipv4_192_0}}, @code{@w{ipv4_192}}).
-
-@end itemize
-
-@c chew end Hard classes
-
-To see all of the classes define on a particular host, run
-
-@smallexample
-host# cf-promises -v
-@end smallexample
-as a privileged user. Note that some of the classes are set only
-if a trusted link can be established with cfenvd, i.e. if both
-are running with privilege, and the @file{/var/cfengine/state/env_data}
-file is secure. More information about classes can be found in
-connection with
-@code{allclasses}.
-
-User-defined or soft classes are defined in bundles. Bundles of type
-@code{common} yield classes that are global in scope, whereas in all
-other bundle types classes are local. Soft classes are evaluated when
-the
-bundle is evaluated. They can be based on test functions or simply from
-other classes:
-
-@verbatim
-
-bundle agent myclasses
-{
-classes:
-
-"solinus" expression => "linux||solaris";
-
-# List form useful for including functions
-
-"alt_class" or => { "linux", "solaris", fileexists("/etc/fstab") };
-
-"oth_class" and => { fileexists("/etc/shadow"), fileexists("/etc/
-passwd") };
-
-reports:
-
-alt_class::
-
- # This will only report "Boo!" on linux, solaris, or any system
- # on which the file /etc/fstab exists
- "Boo!";
-}
-
-@end verbatim
-
-@noindent Classes may be combined with the operators listed here in order
-from highest to lowest precedence:
-
-@table @samp
-@item ()
-The parenthesis group operator.
-@item !
-The NOT operator.
-@item .
-The AND operator.
-@item &
-The AND operator (alternative).
-@item |
-The OR operator.
-@item ||
-The OR operator (alternative).
-@end table
-
-@noindent
-So the following expression would be only true on Mondays or Wednesdays
-from 2:00pm to 2:59pm on Windows XP systems:
-
-@example
-
-(Monday|Wednesday).Hr14.WinXP::
-
-@end example
-
-@noindent Consider the following more advanced example. Promises in bundles
-of type @samp{common} are global in scope -- all other promises are local to
-the scope of their bundle.
-
-
-@verbatim
-
-body common control
-{
-bundlesequence => { "g","ls_1", "ls_2" };
-}
-
-#################################
-
-bundle common g
-{
-classes:
-
-# The promise "zero" is always satisfied , and is global in scope
-"zero" expression => "any";
-
-}
-
-#################################
-
-bundle agent ls_1
-{
-classes:
-
-# The promise "one" is always satisfied , and is local in scope to ls_1
-"one" expression => "any";
-}
-
-#################################
-
-bundle agent ls_2
-{
-classes:
-
-# The promise "two" is always satisfied , and is local in scope to ls_2
-"two" expression => "any";
-
-reports:
-
-zero.!one.two::
-
- # This report @b{will} be generated
- "Success";
-}
-
-@end verbatim
-
-Here we see that class @samp{zero} is global while classes @samp{one}
-and @samp{two} are local.
-The report `Success' result is therefore true because only @samp{zero}
-and @samp{two} are in scope in the @samp{ls_2} bundle (and the class
-expression for bundle @samp{ls_2} requires that both @samp{zero} and
-@samp{two} be true and that @samp{one} not be true).
-
-
-
-
-@node Loops, The main promise types, Decisions, A simple crash course in concepts
-@section Loops
-If you are looking for loops in CFEngine then we need to reprogram you
-a little, as you are thinking like a programmer! CFEngine is not a
-programming language that is meant to give you low level control, but
-rather a set of declarations that embody processes. It's the difference
-between the gears on a bicycle and the automated transmission in a
-transporter.
-
-Loops are executed implicitly in CFEngine, but there is no visible
-mechanism for it -- because that would steal attention from the
-intention of the promises. The way to express them is through lists.
-
-Loops are really a way to iterate a variable over a list. Try the
-following.
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-vars:
-
-# This is a list
-
-"component" slist => { "cf-monitord", "cf-serverd", "cf-execd" };
-
-# This is an associative array
-
-"array[cf-monitord]" string => "The monitor";
-"array[cf-serverd]" string => "The server";
-"array[cf-execd]" string => "The executor, not executionist";
-
-reports:
-
-cfengine_3::
-
-"$(component) is $(array[$(component)])";
-
-}
-
-@end verbatim
-The output looks something like this:
-@smallexample
-
-/var/cfengine/bin/cf-agent -f ./unit_loops.cf -K
-
-R: cf-monitord is The monitor
-R: cf-serverd is The server
-R: cf-execd is The executor, not executionist
-
-@end smallexample
-You see from this that, if we refer to a list variable using the
-scalar reference
-operator @samp{$()}, CFEngine interprets this to mean ``please iterate
-over all
-values of the list''. Thus, we have effectively a `foreach' loop, without the
-attendant syntax.
-
-@c ---------------------------------------------------------------------------
-@node The main promise types, , Loops, A simple crash course in concepts
-@section The main promise types
-
-@noindent The following promise types may be used in any bundle:
-@table @code
-@item vars
-A promise to be a variable, representing a value.
-@item classes
-A promise to be a class representing a state of the system.
-@item reports
-A promise to report a message.
-@end table
-
-@noindent These additional promise types may be used only in agent bundles
-@table @code
-@item commands
-A promise to execute a command.
-@item databases
-A promise to configure a database.
-@item files
-A promise to configure a file, including its existence, attributes and
-contents.
-@item interfaces
-A promise to configure a network interface.
-@item methods
-A promise to take on a whole bundle of other promises.
-@item packages
-A promise to install a package.
-@item storage
-A promise to verify attached storage.
-@end table
-
-@noindent These promise types belong to other components:
-@table @code
-@item access
-A promise to grant or deny access to file objects in @code{cf-serverd}.
-@item measurements
-A promise to measure or sample data from the system, for monitoring or
-reporting in @code{cf-monitord} (CFEngine Nova and above).
-@item roles
-A promise to allow certain users to activate certain classes when
-executing @code{cf-agent} remotely, in @code{cf-serverd}.
-@item topics
-A promise to associate knowledge with a name, and possibly other
-topics, in @code{cf-know}.
-@item occurrences
-A promise to point or refer to a knowledge resource, in @code{cf-know}.
-@end table
-
-@node Using CFEngine as a front-end for cron, Network services, A simple crash course in concepts, Top
-@chapter Using CFEngine as a front-end or replacement for cron
-
-
-@menu
-* Do I need cron?::
-* The single cron job approach::
-* Structuring commands promises::
-* Splaying host times::
-* Building flexible time classes::
-* Scheduling interval::
-@end menu
-
-@node Do I need cron?, The single cron job approach, Using CFEngine as a front-end for cron, Using CFEngine as a front-end for cron
-@section Do I need cron?
-
-The Unix cron command is a useful beast, but a dumb one. One of
-CFEngine's strengths is its use of classes to identify systems from a
-single file or set of files. Many administrators think that it would
-be nice if the cron daemon also worked in this way. One possible way
-of setting up cron from a global configuration would be to use the
-CFEngine file editing capability to edit each cron file
-separately. That would be missing an obvious opportunity however.
-
-A much better way is to use CFEngine's time classes to work like a
-user interface for cron. This allows you to have a single, central
-CFEngine file which contains all the cron jobs on your system without
-losing any of the fine control which cron affords you. All of the
-usual advantages apply:
-@itemize @bullet
-
-@item
-It is easier to keep track of what cron jobs are running on the
-system when you have everything in one place.
-
-@item
-You can use all of your carefully crafted groups and user-defined
-classes to identify which host should run which programs.
-@end itemize
-@cindex Cron jobs, controlling with CFEngine
-
-The central idea behind this scheme is to set up a regular cron job on
-every system which executes @code{cf-agent} at frequent intervals. Each time
-@code{cf-agent} is started, it evaluates time classes and executes the
-shell commands defined in its configuration file. In this way we use
-@code{cf-agent} as a wrapper for the cron scripts, so that we can use
-CFEngine's classes to control jobs for multiple hosts. CFEngine's time
-classes are at least as powerful as @code{cron}'s time specification
-possibilities, and they add control over location too. This does not
-restrict you in any way, @xref{Building flexible time classes}. The
-only price is the overhead of parsing the CFEngine configuration file
-which is insignificant.
-
-@cartouche
-DO I NEED TO USE CRON? No. With CFEngine's @code{cf-execd} you don't
-@i{have} to use cron -- CFEngine can schedule itself. Whether you
-choose to run @code{cf-execd} in daemon mode, or in wrapper mode is
-entirely up to you. In the commercial versions of CFEngine, the exec
-daemon has sophisticated features for reliability. In the Community
-Edition, you might feel comfortable having something independent
-watching over CFEngine, especially during binary updates during which
-live programs can die from faults.
-@end cartouche
-
-@node The single cron job approach, Structuring commands promises, Do I need cron?, Using CFEngine as a front-end for cron
-@section The single cron job approach
-
-To be more concrete, imagine installing the following @file{crontab}
-file onto every host on your network:
-
-@cartouche
-@smallexample
-#
-# Global Cron file
-#
-*/5 * * * * /var/cfengine/bin/cf-execd -F
-
-@end smallexample
-@end cartouche
-
-@noindent
-
-@c -------------------------------------------------------------------------------
-@c SECTION
-@c -------------------------------------------------------------------------------
-
-@node Structuring commands promises, Splaying host times, The single cron job approach, Using CFEngine as a front-end for cron
-@section Structuring commands promises
-
-The structure of a promise bundle needs to reflect your policy for
-running jobs on the system. You need to switch on relevant tasks and
-switch off unwanted tasks depending on the time of day. This can be
-done by placing individual actions under classes which restrict the
-times at
-which they are executed,
-
-@smallexample
-
-@var{promise-type}:
-
- @var{time-based classes::}
-
- @var{Promise}
-
-@end smallexample
-
-@noindent For example:
-
-@verbatim
-bundle agent example
-{
-commands:
-
-# Exec during the first quarter-hour after noon
-
- Hr12.Q1::
-
- "/path/myscript -arg1 -arg2";
-
-# Exec during any second quarter-hour
-
- Q2::
-
- "/path/otherscript";
-
-# Exec during the intervals 00:10 through 00:15 and 12:45 through 12:55
-# (English says ``and'', but logic says ``if this interval or that is true''
-
- Hr00.Min10_15||Hr12.Min45_55::
-
- "/path/amongstourscripts";
-
-}
-
-@end verbatim
-
-@noindent If you want to get fancy, you can set parameters for the
-execution of the script
-by building a container for it that traps its output and privileges
-(this applies to root only,
-since only root has this power to change privilege).
-
-@verbatim
-bundle agent example
-{
-commands:
-
-# Exec on the first quarter after noon
-
- Hr12.Q1::
-
- "/path/myscript -arg1 -arg2",
-
- contain => jail("nobody","true");
-}
-
-# ...
-
-body contain jail(owner,devnull)
-{
-exec_owner => "$(owner)"; # run with this setuid
-no_output => "$(devnull)"; # like > /dev/null 2>&1
-umask => "77"; # set process umask
-}
-
-@end verbatim
-The @samp{contain}ment body provides a safe and flexible environment in which
-to embed scripts.
-
-The time resolution of the classes is limited by how often you execute
-CFEngine
-either using cron or @code{cf-execd}. Five minutes is the recommended
-scheduling interval.
-
-@c -------------------------------------------------------------------------------
-@c SECTION
-@c -------------------------------------------------------------------------------
-
-@node Splaying host times, Building flexible time classes, Structuring commands promises, Using CFEngine as a front-end for cron
-@section Splaying host times
-
-In a network of thousands of computers, many agents could start
-executing and downloading resources from a server at the same time.
-For instance, if a thousand cf-agents all suddenly wanted to copy a
-file from a master source simultaneously this would lead to a big load
-on the server. We can prevent this from happening by introducing a
-time delay which is unique for each host and not longer than some
-given interval; @code{cf-execd} uses a hashing algorithm to generate
-a number
-between zero and a maximum value in minutes which you define, like
-this:
-
-@verbatim
-
-body executor control
-
-{
-splaytime => "10"; # Minutes
-}
-
-@end verbatim
-
-@noindent
-If this number is non-zero, @code{cf-execd} goes to sleep after
-parsing its configuration file and reading the clock. Every machine's
-@code{cf-execd} will go to sleep for a different length of time, which
-is no longer than the time specified.
-
-A hashing algorithm, based on the fully qualified name of the host, is
-used to compute a unique time for hosts. The shorter the interval, the
-more clustered the hosts will be. The longer the interval, the lighter
-the load on your servers. This `splaying' of the run times will
-lighten the load on servers, even if they come from domains not under
-your control but have a similar cron policy.
-
-
-@c -------------------------------------------------------------------------------
-@c SECTION
-@c -------------------------------------------------------------------------------
-
-@node Building flexible time classes, Scheduling interval, Splaying host times, Using CFEngine as a front-end for cron
-@section Building flexible time classes
-
-Each time CFEngine is run, it reads the system clock and defines
-classes based on the time and date (see reference manual).
-
-Time classes based on the precise minute at which cfagent started are
-unlikely to be directly useful in policy (except in the
-@code{cf-execd} schedule). Many things could conspire to delay the
-precise time
-at which cfagent were started. The real purpose in being able to
-detect the precise start time is to define composite classes which
-refer to arbitrary intervals of time. To do this, we use the
-@code{group} or @code{classes} action to create an alias for a group
-of time values.
-@cindex Grouping time values
-@cindex @code{groups} and time intervals
-Here are some creative examples:
-
-@smallexample
-
-classes: # synonym groups:
-
-"LunchAndTeaBreaks" expression => "!(Saturday|Sunday).(Hr12|Hr10|Hr15)";
-
-"NightShift" or => @{ "Hr22", "Hr23", "Night" @};
-
-"ConferenceDays" or => @{ "Day26", "Day27", "Day29", "Day30" @};
-
-"TimeSlices" or => @{ "Min01", "Min02", "Min03", "Min10_15"
- "Min33", "Min34", "Min35" @};
-
-"Exception" not => "Hr12.Min15_20";
-
-@end smallexample
-@noindent
-In the first three examples, the left hand sides of the assignments are
-effectively the ORed result of the right hand side. Thus if any
-classes in the braces is defined, the left hand side class
-will become defined. This provides a flexible and readable way of
-specifying intervals of time within a program, without having to
-use @samp{|} and @samp{.} operators everywhere.
-
-@c -------------------------------------------------------------------------------
-@c SECTION
-@c -------------------------------------------------------------------------------
-
-@node Scheduling interval, , Building flexible time classes, Using CFEngine as a front-end for cron
-@section Choosing a scheduling interval
-
-How often should you call your global CFEngine configuration? There
-are several
-things to think about:
-
-@itemize @bullet
-
-@item
-How much fine control do you need? Running cron jobs once each hour is
-usually enough for most tasks, but you might need to exercise finer
-control for a few special tasks.
-
-@item
-Are you going to verify the entire CFEngine configuration file
-or just selected promises?
-
-@end itemize
-
-CFEngine has an intelligent locking and timeout policy which should be
-sufficient to handle hanging shell commands from previous crons so that
-no overlap can take place.
-
-
-
-@node Network services, Knowledge Management, Using CFEngine as a front-end for cron, Top
-@chapter Network services
-
-@c ---------------------------------------------------------------------------
-
-
-This chapter describes how you can set up a CFEngine network service
-to handle
-remote file distribution and remote execution of CFEngine without having
-to open your hosts to possible attack using the @code{rsh} protocols.
-
-
-@menu
-* What services?::
-* How services work::
-* Remote access explained::
-@end menu
-
-@node What services?, How services work, Network services, Network services
-@section CFEngine network services
-
-By starting the daemon called @code{cf-serverd}, you can set up a line
-of
-communication between hosts, allowing them to exchange files across
-the network or execute CFEngine remotely on another system.
-CFEngine network services are built around the following components:
-
-@table @code
-
-@item cf-agent
-The configuration engine's only contact with the network is via
-remote copy requests. It does not and cannot grant any access to a
-system from the network. It is only able request access to files from
-the
-server component.
-
-@item cf-serverd
-A daemon which acts as both a file server and a remote-@code{cf-agent}
-executor. This daemon authenticates requests from the network and
-processes them according to rules specified in the server control body
-and server bundles containing @code{access} promises.
-
-@item cf-runagent
-This is a simple initiation program which can be used
-to run @code{cf-agent} on a number of remote hosts. It cannot
-be used to tell @code{cf-agent} what to do, it can only ask @code{cf-
-serverd}
-on the remote host to run the @code{cf-agent} with its existing
-configuration.
-Privileges can be granted to users to provide a kind of Role Based
-Access Control (RBAC)
-to certain parts of the existing policy.
-
-@end table
-
-@noindent
-With these components you have everything you need to do effective
-distribution of resources (provisioning) of systems.
-
-
-@c -------------------------------------------------------------------------------
-@c SECTION
-@c -------------------------------------------------------------------------------
-
-@node How services work, Remote access explained, What services?, Network services
-@section How services work
-
-
-@c ...........................................
-@c SUBSECTION
-@c ...........................................
-
-
-@menu
-* Remote file distribution::
-* Remote execution of cfagent::
-@end menu
-
-@node Remote file distribution, Remote execution of cfagent, How services work, How services work
-@subsection Remote file distribution
-
-This section describes how you can set up @code{cf-serverd} as a
-remote file
-server which can result in the distribution of files to client hosts in
-a secure a reliable manner.
-
-An important difference between CFEngine and other systems has to do
-with the way files are distributed. CFEngine uses a `pull' rather
-than a `push' model for distributing network files. A majority of
-systems (probably) for instance, works by forcing an image of the
-files on one server machine onto all clients. This happens in the manner
-of an attack -- indeed the recipients are often required to open various
-ports and accept whatever they get. CFEngine will not support this kind
-of technology as a matter of principle.
-
-With the `push' approach files get changed when the distributor wishes
-it and the clients have no choice but to live with the consequences.
-CFEngine, on the other hand, works by @i{voluntary cooperation}. Hosts
-are allowed to remain in control of their defenses and protect
-themselves against attacks and pushes if they want to.
-
-In fact, CFEngine cannot (by design) force its will onto other hosts,
-nor can it be forced. In order to distribute it can at best signal
-all machines and ask them to collect files if they are willing. In other
-words, CFEngine simulates a `push' model by polling each client and
-running the local CFEngine configuration script giving the host the
-chance to `pull' any updated files from the remote server, but leaving
-it up to the client machine to decide whether or not it wants to
-update.
-
-Also, in contrast to programs like @code{rdist} which distribute files
-over many hosts, CFEngine does not require any general @code{root}
-access to a system using the @file{.rhosts} file or the
-@file{/etc/hosts.equiv} file. It is sufficient to run the daemon as
-root. You can not run it by adding it to the @file{/etc/inetd.conf}
-file on your system however.
-@cindex @file{/etc/inetd.conf} file and CFEngine
-The restricted functionality of the daemon protects your system from
-attempts to execute general commands as the root user using @code{rsh}.
-
-To remotely access files on a server you use a @code{copy_from}
-attribute
-in a @file{files} promise:
-
-@verbatim
-bundle agent example
-{
-files:
-
-"/var/cfengine/inputs"
-
- perms => m("600"),
- copy_from => remote_cp("$(master_location)","localhost"),
- depth_search => recurse("inf"),
- action => immediate;
-
-}
-
-# Library template
-
-body copy_from remote_cp(from,server)
-{
-servers => { "$(server)" };
-source => "$(from)";
-compare => "mtime";
-}
-
-@end verbatim
-@noindent
-Assuming that the @code{cf-serverd} daemon is running on @var{server-
-host}, @code{cf-agent}
-will make contact with the daemon and attempt to obtain information
-about the file. During this process, CFEngine verifies that the system
-clocks of the two hosts are reasonably synchronized. If they are not,
-it will not permit remote copying unless @code{denybadclocks} is false
-in the server control body.
-
-If @code{cf-agent} determines that a file needs to be updated from a
-remote
-server it begins copying the remote file to a new file on the same
-filesystem as the destination-file. This file has the suffix
-@file{.cfnew}.
-
-Only when the file has been successfully collected will @code{cf-
-agent} make a
-copy of the old file, (see @code{repository} in the Reference manual),
-and rename the new file into place. This behavior is designed to avoid
-race-conditions which can occur during network connections and indeed
-any operations which take some time. If files were simply copied
-directly to their new destinations it is conceivable that a network
-error could interrupt the transfer leaving a corrupted file in place.
-@code{cf-agent} places a timeout of a few seconds on network
-connections to
-avoid hanging processes.
-
-Normally the daemon sleeps, waiting for connections from the network.
-Such a connection may be initiated by a request for remote files from a
-running @code{cf-agent} program on another host, or it might be
-initiated by
-the program @code{cf-runagent} which simply asks the
-host running the daemon to run @code{cf-agent} or @code{cf-execd}
-program locally.
-
-@c ...........................................
-@c SUBSECTION
-@c ...........................................
-
-@node Remote execution of cfagent, , Remote file distribution, How services work
-@subsection Remote execution of @code{cf-agent}
-
-Occasionally you will want to run @code{cf-agent} immediately in order
-to implement a change in configuration as quickly as possible on one
-or more hosts. It would then be inconvenient to have to log onto every
-host in order to do this manually.
-
-If your scheduling interval is often enough, this should be
-unnecessary since CFEngine will already have run by the time you
-manage to log on -- and the parallelism means that an entire network
-can be altered in minutes without the delay of waiting for centralized
-control.
-
-But you might want to send a special signal, e.g. run policy with a
-special class activated on just a few machines. Then a better way is
-to issue a simple command which contacts the remote host and runs
-@code{cf-agent} with role based access control, providing the
-immediate output on your own screen:
-
-@smallexample
-
-host$ cf-runagent -H @var{remote-host} -v
-
-@var{output....}
-
-@end smallexample
-
-@itemize @bullet
-
-@item
-You avoid having to log in on a remote host in order to reconfigure
-it.
-
-@item
-Users other than root can run @code{cf-agent} to fix any problems with
-the system, with access granted to individuals and classes.
-
-@end itemize
-
-A potential disadvantage with any such system is that malicious users
-might be able to run @code{cf-agent} on remote hosts. The fact that
-non-root users can execute @code{cf-agent} is not a problem in itself,
-after all the most malicious thing they would be able to do would be
-to check the system configuration and repair any problems. No one can
-tell @code{cf-agent} what to do using the @code{cf-runagent} program, it is only
-possible to run an existing configuration. But a more serious concern
-is that malicious users might try to run @code{cf-agent} repeatedly
-(so-called `Denial of Service' attack) so that a system became
-burdened with running @code{cf-agent} constantly.
-To protect against this, the server uses the same @code{ifelapsed} locks
-to complement access controls.
-
-@node Remote access explained, , How services work, Network services
-@section Remote access explained
-
-
-@menu
-* Server connection::
-* Remote access troubleshooting::
-* Key exchange::
-* Time windows::
-* Other users than root::
-* Encryption::
-@end menu
-
-@node Server connection, Remote access troubleshooting, Remote access explained, Remote access explained
-@subsection Server connection
-
-In order to connect to the CFEngine server you need
-@table @emph
-@item A public-private key pair.
-To create a key pair, run
-@smallexample
-cf-key
-@end smallexample
-@item An IP (v4 or v6) address.
-You must be online with a configured network address.
-@item A client program
-Both @code{cf-agent} and @code{cf-runagent} are clients that can connect
-to the server.
-
-@item Permission to connect to the server, and
-The server control body must grant access to your computer and public
-key by name or IP address, by listing it in one of the lists (see
-below).
-
-@item Your public key must be trusted by the server, and you must
-trust the server's public key
-
-By mutually trusting each others' keys, client and server agree
-to use that key as a sufficient identifier for the computer.
-
-@item Permission to access something
-
-Your host name or IP address must be mentioned in an @code{access}
-promise inside a server bundle, made by the file that you are
-trying to access.
-@end table
-
-If all of the above criteria are met, connection will be established
-and data will be transferred between client and server. The client can
-only send short requests, following the CFEngine protocol. The server
-can return data in a variety of forms, usually files, but sometimes
-console output.
-
-
-@node Remote access troubleshooting, Key exchange, Server connection, Remote access explained
-@subsection Remote access troubleshooting
-
-When setting up @code{cf-serverd}, you might see the error message
-
-@verbatim
-Unspecified server refusal
-@end verbatim
-
-This means that @code{cf-serverd} is unable or is unwilling to
-authenticate the connection from your client machine. The message is
-generic: it is deliberately non-specific so that anyone attempting to
-attack or exploit the service will not be given information which
-might be useful to them. There is a simple checklist for curing this
-problem:
-
-@enumerate
-@item
-Make sure that the domain variable is set in the configuration files
-read by both client
-and server; alternatively use @code{skipidentify} and
-@code{skipverify} to decouple DNS from the
-the authentication.
-
-@item
-Make sure that you have granted access to your client in the server body
-
-@smallexample
-
-body server control
-@{
-allowconnects => @{ "127.0.0.1" , "::1" @var{...etc} @};
-allowallconnects => @{ "127.0.0.1" , "::1" @var{...etc} @};
-trustkeysfrom => @{ "127.0.0.1" , "::1" @var{...etc} @};
-@}
-
-@end smallexample
-
-@item
-Make sure you have created valid keys for the hosts using @code{cf-key}.
-@item
-If you are using secure copy, make sure that you have created a key
-file and that you have distributed and installed it to all
-participating hosts in your cluster.
-@end enumerate
-
-@noindent Always remember that you can run CFEngine in verbose or
-debugging modes to see how the authentication takes place:
-
-@verbatim
-cf-agent -v
-cf-serverd -v
-@end verbatim
-
-@code{cf-agent} reports that access is denied regardless of the nature
-of the error, to avoid giving away information which might be used by
-an attacker. To find out the real reason for a denial, use verbose
-@samp{-v} or
-even debugging mode @samp{-d2}.
-
-
-@node Key exchange, Time windows, Remote access troubleshooting, Remote access explained
-@subsection Key exchange
-
-The key exchange model used by CFEngine is based on that used by
-OpenSSH. It is a peer to peer exchange model, not a central
-certificate authority model. This means that there are no scalability
-bottlenecks (at least by design, though you might introduce your own
-if you go for an overly centralized architecture).
-
-The problem of key distribution is the conundrum of every public key
-infrastructure. Key exchange is handled automatically by CFEngine and
-all you
-need to do is to decide which keys to trust.
-
-When public keys are offered to a server, they could be accepted
-automatically on trust because no one is available to make a decision
-about them. This would lead to a race to be the first to submit a key
-claiming identity.
-
-Even with DNS checks for correct name/IP address correlation (turned
-off with @code{skipverify}), it might be possible to submit a false
-key to a server.
-
-The server @code{cf-serverd} blocks the acceptance of unknown keys by
-default. In order to accept such a new key, the IP address of the
-presumed client must be listed in the @code{trustkeysfrom} stanza.
-Once a key
-has been accepted, it will never be replaced with a new key, thus no
-more trust is offered or required.
-
-Once you have arranged for the right to connect to the server, you
-must decide which hosts will have access to which files. This is done
-with @code{access} rules.
-
-@verbatim
-
-bundle server access_rules()
-
-{
-access:
-
-"/path/file"
-
- admit => { "127.0.0.1", "127.0.0.2", "127.0.0.3" },
- deny => { "192.*" };
-}
-
-@end verbatim
-
-On the client side, i.e. @code{cf-runagent} and @code{cf-agent}, there
-are three issues:
-
-@enumerate
-@item
-Choosing which server to connect to.
-@item
-Trusting the identity of any previously unknown servers, i.e. trusting
-the server's public key to be its and no one else's. (The issues here
-are
-the same as for the server.)
-@item
-Choosing whether data transfers should be encrypted (with
-@code{encrypt}).
-@end enumerate
-
-Because there are two clients for connecting to @code{cf-serverd}
-(@code{cf-agent} and @code{cf-runagent}), there are also two ways on
-managing trust of server keys by a client. One is an automated option,
-setting the option
-@code{trustkey} in a @code{copy_from} stanza, e.g.
-
-@verbatim
-
-body copy_from example
- {
- # .. other settings ..
- trustkey => "true";
- }
-
-@end verbatim
-
-Another way is to run @code{cf-runagent} in interactive mode. When you
-run @code{cf-runagent}, unknown
-server keys are offered to you interactively (as with @code{ssh}) for
-you to
-accept or deny manually:
-
-@smallexample
-
-WARNING - You do not have a public key from host ubik.iu.hio.no =
-128.39.74.25
- Do you want to accept one on trust? (yes/no)
--->
-
-@end smallexample
-
-@node Time windows, Other users than root, Key exchange, Remote access explained
-@subsection Time windows (races)
-
-Once public keys have been exchanged from client to server and from
-server to client, the issue of trust is solved according to public key
-authentication schemes. You only need to worry about trust when one side
-of a connection has never seen the other side before.
-
-Often you will have a central server and many client satellites. Then
-the best way to transfer all the keys is to set the @code{trustkey}
-flags on server and clients sides to coincide with a time at which you
-know that @code{cf-agent} will be run, and when a spoofer is unlikely
-to be able to interfere.
-
-This is a once-only task, and the chance of an attacker being able to
-spoof a key-transfer is small. It would require skill and
-inside-information about the exchange procedure, which would tend to
-imply that the trust model was already broken.
-
-Another approach would be to run @code{cf-runagent} against all the
-hosts
-in the group from the central server and accept the keys one by one,
-by hand, though there is little to be gained from this.
-
-Trusting a host for key exchange is unavoidable. There is no clever
-way to avoid it. Even transferring the files manually by diskette, and
-examining every serial number of the computers you have, the host has
-to trust the information you are giving it. It is all based on
-assertion. You can make it almost impossible for keys to be faked
-or attacked, but you cannot make it absolutely impossible. Security is
-about managing reasonable levels of risk, not about magic.
-
-All security is based on a moment of trust at some point in
-time. Cryptographic key methods only remove the need for a repeat of
-the trust decision. After the first exchange, trust is no longer needed,
-because they keys allow identity to be actually verified.
-
-Even if you leave the trust options switched on, you are not blindly
-trusting the hosts you know about. The only potential insecurity lies
-in any new keys that you have not thought about. If you use wildcards
-or IP prefixes in the trust rules, then other hosts might be able to
-spoof their way in on trust because you have left open a hole for them
-to exploit. That is why it is recommended to return the system to the
-default state of zero trust immediately after key transfer, by
-commenting out the trust options.
-
-
-It is possible, though somewhat laborious to transfer the keys out of
-band, by copying @file{/var/cfengine/ppkeys/localhost.pub} to
-@code{/var/cfengine/ppkeys/user-aaa.bbb.ccc.mmm} (assuming IPv4) on
-another host. e.g.
-
-@smallexample
-
-localhost.pub -> root-128.39.74.71.pub
-
-@end smallexample
-
-This would be a silly way to transfer keys between nearby hosts that you
-control yourself, but if transferring to long distance, remote hosts
-it might be an easier way to manage trust.
-
-@node Other users than root, Encryption, Time windows, Remote access explained
-@subsection Other users than root
-
-CFEngine normally runs as user "root" (except on Windows which does
-not normally have a root user), i.e. a privileged administrator. If
-other users
-are to be granted access to the system, they must also generate a key
-and go through the same process. In addition, the users must be added
-to the server configuration file.
-
-@node Encryption, , Other users than root, Remote access explained
-@subsection Encryption
-
-CFEngine provides encryption for keeping file contents private during
-transfer. It is assumed that users will use this judiciously. There is
-nothing to be gained by encrypting the transfer of public files --
-overt use of encryption just contributes to global warming, burning
-unnecessary CPU cycles without offering any security.
-
-The main role for encryption in configuration management is for
-authentication. CFEngine always uses encrypted for authentication, so
-none of the encryption settings affect the security of authentication.
-
-
-
-
-@node Knowledge Management, , Network services, Top
-@chapter Knowledge Management
-
-
-A unique aspect of CFEngine, that is fully developed in the commercial
-editions of the software, its ability to enable integrated knowledge
-management as part of an automation process, and to use its configuration
-technology as a `semantic' documentation engine.
-
-@image{topicmap,15cm,,,png}
-
-Knowledge management is the challenge of our times. Organizations
-frequently waste significant effort re-learning old lessons because they have
-not been documented and entered into posterity. Now you can alleviate
-this problem with some simple rules of thumb and even build
-sophisticated index-databases of documents.
-
-
-@menu
-* Promises and Knowledge::
-* The basics of knowledge::
-* Annotating promises::
-* A promise model of topic maps::
-* What topic maps offer::
-* The nuts and bolts of topic maps::
-* Example of topics promises::
-* Modeling configuration promises as topic maps::
-@end menu
-
-@node Promises and Knowledge, The basics of knowledge, Knowledge Management, Knowledge Management
-@section Promises and Knowledge
-
-The learning curve for configuration management systems has been the
-brunt of frequent criticism over the years. Users are expected to either
-confront the informational complexity of systems at a detailed level, or
-abandon the idea of fine control altogether. This has led either to
-information overload or over-simplification. The ability to cope with
-information complexity is therefore fundamental to IT management
-
-CFEngine introduced the @emph{promise model} for configuration in
-order to flatten out this learning curve. It can lead to
-simplifications in use, because a lot of the thinking has been done
-already and is encapsulated into the model. One of its special
-properties is that it is both a model for system behavior and a model
-for knowledge representation (this is what declarative languages seek
-to be, of course). More specifically, it incorporated a subset of the
-ISO standard for `Topic Maps', an open technology for semantic
-indexing of information resources. By bringing together these two
-technologies (which are highly compatible), we end up with a seamless
-front-end for sewing together and browsing system information.
-
-Knowledge management is a field of research in its own right, and it
-covers a multitude of issues both human and technological. Most would
-agree that knowledge is composed of facts and relationships and that
-there is a need both for clear definitions and semantic context to
-interpret knowledge properly; but how do we attach @emph{meaning} to
-raw information without ambiguity?
-
-Knowledge has quite a lot in common with configuration: what after all
-is
-knowledge but a configuration of ideas in our minds, or on some
-representation medium (paper, silicon etc). It is a coded pattern,
-preferably one that we can agree on and share with others. Both
-knowledge and configuration management are about describing patterns.
-A simple knowledge model can be used to represent a policy or
-configuration; conversely, a simple model of policy configuration can
-manufacture a knowledge structure just as it might manufacture
-a filesystem or a set of services.
-
-
-@node The basics of knowledge, Annotating promises, Promises and Knowledge, Knowledge Management
-@section The basics of knowledge
-
-Knowledge only truly begins when we write things down:
-
-@itemize
-@item The act of formulating something in writing brings a discipline
-of thought than often lends clarity to an idea.
-@item You never confront an idea fully until you try to put it into
-language.
-@item Any written record that is kept allows others to read it and
-pass on the knowledge.
-@end itemize
-
-The trouble is that writing is something people don't like to do, and
-few are very good at. To an engineer, it can feel like a waste of
-time, especially during a busy day, to break off from the doing to
-write about the doing. Also, writing requires a spurt of creative
-thinking and engineers are often more comfortable with manipulating
-technical patterns and notations than writing fluent linguistic
-formulations that seem overtly long-winded.
-
-CFEngine tries to bridge this gap by making documentation simple and
-part of the technical configuration. CFEngine's knowledge agent then
-uses AI and network science algorithms to construct a readable
-documentation from these technical annotations. It can do this because
-a lot of thought has already gone into the meaning of the promise
-model.
-
-@node Annotating promises, A promise model of topic maps, The basics of knowledge, Knowledge Management
-@section Annotating promises
-
-The beginning of knowledge is to annotate the technical specifications.
-Remember that the point of a promise is to convey an @i{intention}.
-When writing promises, get into the habit of giving every promise a
-comment that explains its intention. Also, expect to give special
-promises
-@i{handles}, or helpful labels that can be used to refer to them by in
-other
-promise statements. A handle could be something dumb like `xyz', but
-you should
-try to use more meaningful titles to help make references clear.
-
-@verbatim
-
-files:
-
-"/var/cfengine/inputs"
-
- handle => "update_policy",
- comment => "Update the CFEngine input files from the policy server",
- perms => system("600"),
- copy_from => rcp("$(master_location)","$(policy_server)"),
-depth_search => recurse("inf"),
-file_select => input_files,
- action => immediate;
-
-@end verbatim
-@noindent If a promise affects another promise in some way, you can
-make the affected one
-promise one of the promisees, like this:
-
-@verbatim
-
-access:
-
-"/master/CFEngine/inputs" -> { "update_policy", "other_promisee" },
-
-handle => "serve_updates",
- admit => { "217.77.34.*" };
-
-@end verbatim
-
-@noindent Conversely, if a promise might depend on another in some
-(even indirect) way, document this too.
-
-@verbatim
-
-files:
-
-"/var/cfengine/inputs"
-
- handle => "update_policy",
- comment => "Update the CFEngine input files from the policy
-server",
- depends_on => { "serve_updates" },
- perms => system("600"),
- copy_from => rcp("$(master_location)","$(policy_server)"),
-depth_search => recurse("inf"),
-file_select => input_files,
- action => immediate;
-
-@end verbatim
-
-@noindent This use of annotation is the first level of documentation
-in CFEngine.
-The annotations are used internally by CFEngine to provide meaningful
-error messages with context and to compute dependencies that reveal
-the existence of process chains. These can be turned into a topic map
-for browsing the policy relationships is a web browser, using
-@code{cf-know}.
-
-
-@cartouche
-The CFEngine Knowledge Map is only available in commercial editions
-of the software, where the necessary support to set up and maintain
-this technology can be provided.
-@end cartouche
-
-
-@node A promise model of topic maps, What topic maps offer, Annotating promises, Knowledge Management
-@section A promise model of topic maps
-
-CFEngine's model of promises can also be used to promise information
-and its relevance in different contexts. The Knowledge agent @code{cf-know}
-understands three kinds of promise.
-
-@table @code
-@item topics:
-A topic is merely a string that can be associated with another string. It represents a `subject to be talked about'.
-Like other promise types, you can use contexts, which are formed from other topics expressions to limit the scope of
-the current topic promise.
-@item things:
-Things are a simplified interface to topics, that were introduced to make it easier
-for users to contribute knowledge about more concrete `things', or less abstract ideas.
-A challenge with knowledge management is the abstract and technical nature of the models
-one must use to represent it. Things attempt to make that task easier.
-@item occurrences:
-An occurrence is a reference to a document or a piece of text that actually represents
-knowledge content about the topic concerned. Occurrences are generally URLs or strings
-explaining things or topics.
-@end table
-
-@node What topic maps offer, The nuts and bolts of topic maps, A promise model of topic maps, Knowledge Management
-@section What topic maps offer
-
-CFEngine is capable of automating the documentation of a policy, using basic annotations provided above, as a
-knowledge map. They require very little effort from the user. If you
-are using the Community Edition of CFEngine, you can develop a topic
-map, but we do not support the backend technology without a
-commercial license. In either case, once you become familiar with the
-use of Topic Maps, you will want to extend your knowledge manually to
-incorporate things like:
-
-@itemize
-@item Local (high level) policy documents
-@item Related databases, such as CMDBs
-@end itemize
-
-@noindent So let us spend a while showing how to encode knowledge in
-topic maps
-using @code{cf-know}.
-
-The kind of result you can expect is shown in the pictures below. The
-example figures show typical pages generated by the knowledge agent
-@code{cf-know}. The first of these shows how we use the technology to
-power the web knowledge base in the commercial CFEngine product.
-
-In this use, all of the data are based on documentation for
-the CFEngine software, and most of the relationships are manually
-entered.
-
-For a second example, consider how CFEngine can generate such a
-knowledge map analysis of its own configuration (self-analysis). The
-data in the images below describe the CFEngine configuration
-promises. One such page is generated, for instance, for each policy
-promise, and pages are generated for reports from different computers
-etc. You can also create you own `topic pages' for any local
-(enterprise) information that you have.
-
-In this example, the promise has been given the promise-handle
-@code{update_policy}, and the associations and the lower graph shows
-how this promise relates to other promises through its documented
-dependencies (these are documented from the promisees and
-@code{depends_on} attributes of other promises.).
-
-The example page shows two figures, one above the other.
-The upper figure shows the thirty nearest topics (of any kind) that
-are related to this one.
-Here the relationships are unspecific. This diagram can reveal
-pathways to related information
-that are often unexpected, and illustrates relationships that broaden
-one's understanding
-of the place the current promise occupies within the whole.
-
-Although the graphical illustrations are just renderings of
-semantic associations shown more fully in text, they are useful for
-visualizing
-several levels of depth in the associative network. This can be
-surprisingly useful for brainstorming and reasoning alike. In
-particular, one can see the other promises that could be affected if
-we were to make a change to the current promise. Such impact analyses
-can be crucial to planning change and release management of policy.
-
-
-
-@cartouche
-
-A knowledge base is a slightly improved implementation of a Topic Map which is an ISO
-standard technology. A topic map works like an index that can point to
-many different kinds of external resources, and may contain simple
-text and images internally. So you use it to bind together documents
-of any kind. A CFEngine knowledge base is not a new document format, it
-is an overlay map that joins ideas and resources together, and
-displays relationships.
-
-@end cartouche
-
-
-
-
-@node The nuts and bolts of topic maps, Example of topics promises, What topic maps offer, Knowledge Management
-@section The nuts and bolts of topic maps
-
-
-@menu
-* Topic map definitions::
-@end menu
-
-@node Topic map definitions, , The nuts and bolts of topic maps, The nuts and bolts of topic maps
-@subsection Topic map definitions
-
-Topic maps are really electronic indices, but they form and work like
-webs.
-A topic is the technical representation of a `subject', i.e. anything
-you might want
-to discuss, abstract or physical e.g. an item of `abstract
-knowledge', which probably has a number of concrete exemplars. It
-might be a person, a machine, a quality, etc.
-
-Topics can be classified into boxes called @emph{topic-types} so that
-related
-things can be collated and unrelated things can be separated, e.g.
-types allow us to distinguish between @code{rmdir} the Unix utility
-and @code{rmdir} the Unix system-call.
-
-Each typed topic can further point to a number of references or
-exemplars called @emph{occurrences}. For instance, an occurrence of
-the topic `computer' might include books, web documents, database
-entries, physical manifestations, or any other information. An
-occurrence is a reference that exemplifies the abstract
-topic. Occurrence references are like the page numbers in an
-index.
-
-
-A book index typically has `see also' references which point from one
-topic to another.
-Topic Maps allow one to define any kind of @emph{association} between
-topics. Unlike an ordinary index, a topic map has a rich (potentially
-infinite) variety of cross reference types.
-For instance,
-@smallexample
-topic_1 ``is a kind of'' topic_2
-topic_1 ``is improved by'' topic 2
-topic_1 ``solves the problem of'' topic_2
-@end smallexample
-
-@noindent The topic map model thus has three levels of containers:
-
-@table @emph
-@item Contexts
-The box into which we classify a topic to disambiguate different
-topics with the same name (`in the context of')@footnote{Here, CFEngine differs from the topic map standard in allowing contexts
-to be overlapping sets, rather than mutually exclusive `types'.
-CFEngine is guided by Promise Theory in this respect in order to enable
-distributed cooperation and the development of a free and emergent ontology.}.
-
-@item Topics/Things
-The representation of a subject (an index term).
-
-@item Occurrence Types
-A term that explains how an actual document occurrence relates
-to the topic is claims to say something about. e.g. (tutorial, manual,
-or
-example, definition, photo-album etc).
-
-@item Occurrences
-Specific information resources: these are pointers to the actual
-documents
-that we want to read (like page numbers in an index).
-@end table
-
-
-Contexts map conveniently into CFEngine classes.
-Topics map conveniently into promisers.
-Occurrences also map to promisers of a different type.
-These three label different levels of granularity of meaning. Contexts
-represent a set of topics that might be relevant, which in turn encompass a set of
-occurrences of resources that contain actual information about the topics in that context. The primacy of topics in this
-stems from their ability to form networks by @emph{association}.
-
-The classic approach to information modeling is to build a
-hierarchical decomposition of non-overlapping objects. Data are
-manipulated into non-overlapping containers which often prove
-to be overly restrictive. Topic maps allow us to avoid the kinds of
-mistakes that have led to monstrosities like the Common Information
-Model (CIM) with its @emph{thousands} of strictly non-overlapping type
-categories.
-
-Each topic allows us to effectively `shine a light' onto the
-occurrences of information that highlight the concepts pertinent to
-the topic somehow.
-
-
-@node Example of topics promises, Modeling configuration promises as topic maps, The nuts and bolts of topic maps, Knowledge Management
-@section Example of topics promises
-
-You can use @code{cf-know} to render a topic map either as text (for
-command line
-use) or as HTML (for web rendering). We begin with the text rendering
-as it requires less
-infrastructure. You will just need a database.
-
-Try typing in the following knowledge promises:
-
-@smallexample
-
-body common control
-@{
-bundlesequence => @{ "tm" @};
-@}
-
-###################################################
-
-bundle knowledge tm
-@{
-topics:
-
-
-"server" comment => "Common name for a computer in a desktop";
-"desktop" comment => "Common name for a computer for end users";
-
-programs:: # context of programs
-
-"httpd" comment => "A web service process";
-"named" comment => "A name service process";
-
-services::
-
-"WWW" comment => "World Wide Web service",
- association => a("is implemented by",
- "programs::httpd",
- "implements");
-
- # if we don't specify a context, it is "any"
-
-"WWW" association => a("looks up addresses with",
- "named",
- "serves addresses to");
-
-occurrences:
-
-httpd::
- "http://www.apache.org"
- represents => @{ "website" @};
-
-@}
-
-###################################################
-
-body association a(f,name,b)
-
-@{
-forward_relationship => "$(f)";
-backward_relationship => "$(b)";
-associates => @{ $(name) @};
-@}
-@end smallexample
-
-@noindent The simplified things interface is similar, but uses fixed relations:
-
-@verbatim
-bundle knowledge company_knowledge
-{
-things:
- regions::
-
- "EMEA" comment => "Europe, The Middle-East and Africa";
- "APAC" comment => "Asia and the Pacific countries";
-
- countries::
- "UK" synonyms => { "Great Britain" },
- is_located_in => { "EMEA", "Europe" };
-
- "Netherlands" synonyms => { "Holland" },
- is_located_in => { "EMEA", "Europe" };
-
- "Singapore" is_located_in => { "APAC", "Asia" };
-
- locations::
- "London_1" is_located_in => { "London", "UK" };
- "New_Jersey" is_located_in => { "USA" };
-
- networks::
-
- "192.23.45.0/24" comment => "Secure network, zone 0. Single octet for corporate offices",
- is_connected_to => { "oslo-hub-123" };
-
-@end verbatim
-
-@menu
-* Analyzing and indexing the policy::
-* cf-know::
-@end menu
-
-@node Analyzing and indexing the policy, cf-know, Example of topics promises, Example of topics promises
-@subsection Analyzing and indexing the policy
-
-CFEngine can analyze the promises you have made, index and cross
-reference them using the command:
-
-@verbatim
-# cf-promises -r
-@end verbatim
-Normally, the default policy in Nova/Enterprise will perform this
-command each time the policy is changed.
-
-@node cf-know, , Analyzing and indexing the policy, Example of topics promises
-@subsection @code{cf-know}
-
-CFEngine's knowledge agent @code{cf-know} allows you to make promises
-about knowledge and its inter-relationships. It is not specifically a
-generic topic map language: rather it provides a powerful configuration
-language for managing a knowledge base that can be compiled into a
-topic map.
-
-To build a topic map from a set of knowledge promises in @file{knowledge.cf}, you would write:
-
-@verbatim
-# cf-know -b -f ./knowledge.cf
-@end verbatim
-
-The syntax of this file is hinted at below.
-The full ISO standard topic map model is too rich to be a useful tool
-for system knowledge management. However, this is where powerful
-configuration management can help to simplify the process: encoding a
-topic map is a complex problem in configuration, which is exactly what
-CFEngine is for. CFEngine's topic map promises have the following
-form:
-
-@smallexample
-
-bundle knowledge example
-@{
-topics:
-
-topic_type_context:: # canonical container
-
-"Topic name" # short topic name
-
- comment => "Use this for a longer description",
- association => a("forward assoc to","Other topic","backward assoc");
-
- "Other topic";
-
-occurrences:
-
-Topic_name:: # Topic
-
- "http://www.example.org/document.xyz" # URI to instance
-
- represents => @{ "Definition", "Tutorial"@}; # sub-types
-@}
-
-@end smallexample
-The association body templates look like this:
-@verbatim
-
-body association a(f,name,b)
-{
-forward_relationship => "$(f)";
-backward_relationship => "$(b)";
-associates => { $(name) };
-}
-
-@end verbatim
-
-
-
-@cartouche
-
-Promise theory adds a clear structure to the topic map ontology, which
-is highly beneficial as experience shows that weak conceptual models
-lead to poor knowledge maps.
-
-@end cartouche
-
-
-@node Modeling configuration promises as topic maps, , Example of topics promises, Knowledge Management
-@section Modeling configuration promises as topic maps
-
-We can model topic maps as promises within CFEngine; the
-question then remains as to how to use topic maps to model
-configurations so that CFEngine users can navigate the documented
-promises using a web browser and be able to see all of the
-relationships between otherwise isolated and fragmentary rules. This
-will form the basis of a semantic Configuration Management Database
-(sCMDB) for the CFEngine software. The key to making these ends meet
-is to see the configuration of the topic map as a number öf promises
-made in the abstract space of topics and the turning each promise into
-a meta-promise that models the configuration as a topic with attendant
-associations. Consider the following CFEngine promise.
-
-@verbatim
-
-bundle agent update
-{
-files:
-
-any::
-
-``/var/cfengine/inputs'' -> { ``policy_team'', ''dependent'' },
-
- comment => ``Check policy updates from source'',
- perms => true,
- mode => 600,
- copy_from => true,
- copy_source => /policy/masterfiles,
- compare => digest,
- depth_search => true,
- depth => inf,
- ifelapsed => 1;
-
-}
-@end verbatim
-
-This system configuration promise can be mapped by CFEngine into a
-number of other promise proposals intended for the @code{cf-know}
-agent. Suppressing some of the details, we have:
-
-@verbatim
-
-type_files::
-
-"/var/cfengine/inputs"
- association => a("promise made in bundle","update","bundle
-contains promise");
-"/var/cfengine/inputs"
- association => a("specifies body type","perms","is specified in");
-"/var/cfengine/inputs"
- association => a("specifies body type","mode","is specified in");
-"/var/cfengine/inputs"
- association => a("specifies body type","copy_from","is specified
-in");
-
-# etc ...
-
-occurrences:
-
-_var_CFEngine_inputs::
-
- "promise_output_common.html#promise__var_CFEngine_inputs_update_cf_13"
- represents => { "promise definition" };
-
-@end verbatim
-Note that in this mapping, the actual promise (viewed as a real world
-entity) is an occurrence of the topic `promise'; at the same time each
-promise could be discussed as a different topic allowing
-meta-modeling of the entity-relation model in the real-world
-data. Conversely the topics themselves become configuration items or
-`promisers' in the promise model. The effect is to create a navigable
-semantic web for traversing the policy; this documents the structure
-and intention of the policy using a small ontology of standard
-concepts and can be extended indefinitely by human domain experts.
-
-
-
-
-
-@chapter More...
-
-@cartouche
-
-You will find extensive help, examples and documentation as part of
-the commercial
-CFEngine support. Visit the website @url{http://www.cfengine.com} for more
-details.
-
-@end cartouche
-
-
-
-
-@c ========================================================================
-@c @node Index, , CFEngine Methods, Top
-@c @unnumbered Concept Index
-@c @printindex cp
-@c ========================================================================
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
diff --git a/docs/guides/cf3-upgrade.texinfo b/docs/guides/cf3-upgrade.texinfo
deleted file mode 100644
index 5ebf1f161b..0000000000
--- a/docs/guides/cf3-upgrade.texinfo
+++ /dev/null
@@ -1,2389 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename cf3-upgrade.info
-@settitle Upgrading from CFEngine 2 to 3
-@setchapternewpage odd
-@c %** end of header
-
-@titlepage
-@title Upgrading from CFEngine 2 to 3
-@subtitle A CFEngine Handbook
-@author CFEngine AS
-
-@c @smallbook
-
-
-@page
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2009- CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-@ifnottex
-@node Top, General remarks and expectations, (dir), (dir)
-@top CFEngine-Best-Practices
-@end ifnottex
-@iftex
-@contents
-@end iftex
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-
-@c **********************************************************************
-@c CHAPTER
-@c **********************************************************************
-
-@menu
-* General remarks and expectations::
-@c * Automated translation with cfconvert::
-* Conversion Strategy::
-* Translation Codebook::
-@end menu
-
-@c @node General remarks and expectations, Automated translation with cfconvert, Top, Top
-@node General remarks and expectations, Conversion Strategy, Top, Top
-@chapter General remarks and expectations
-
-This document concerns the translation of system configuration
-policies from the legacy CFEngine 2 language to the new CFEngine 3
-promise language. CFEngine 3 is a new language that was designed with
-careful research to satisfy the needs of system configuration in a
-@i{convergent} fashion.
-
-
-@menu
-* On the translation of policies::
-* On best practices::
-* Completely new features::
-@end menu
-
-@node On the translation of policies, On best practices, General remarks and expectations, General remarks and expectations
-@section On the translation of policies
-
-Translating one language directly into another rarely makes sense.
-Every language has its quirks and idioms that make some formulations
-more natural than others.
-
-In migrating from CFEngine 2 to CFEngine 3, you will see that the
-novelty is more of a dialect than an unrelated language. The
-underlying parameterization of the promises is the same, and you will
-recognize the main features, even if they are inflected with an
-`accent'.
-
-This suggests that translation might be easy. However, we don't want
-you to trivialize this translation, as there are new mechanisms in
-CFEngine 3 that bring new benefits, and this means that simple and
-direct translation can be a poor choice that misses the opportunity
-for improvement. In this guide the principles for translation are
-simply as follows:
-
-@itemize
-@item We make as direct a translation as possible,
-sometimes offering alternatives that better illustrate CFEngine 3 paradigms.
-
-@item We use standardized templates from the
-@i{CFEngine Community Open Promise-Body Library} to simplify
-the translation. However, readers should understand that
-in every `constraint' expression in CFEngine, of the form,
-@verbatim
-
- LHS => RHS
-
-@end verbatim
-@noindent the left hand side is always a pre-defined CFEngine word,
-and the right hand side is always a user-defined term. In other words,
-if you don't like the choices we have made, you can make your own
-choices on the right hand side.
-@end itemize
-
-
-@node On best practices, Completely new features, On the translation of policies, General remarks and expectations
-@section On `best practices'
-
-There are new features in CFEngine 3 that we strongly recommend you
-use. Perhaps the most useful practice is to make use of the standard
-library of template parts for promise bodies and bundles, called te
-@i{CFEngine Community Open Promise-Body Library}. This is available
-from the CFEngine website. By standardizing simple template
-names, you will be able to communicate more effectively with others,
-and facilitate knowledge efficiency in your organization.
-
-Another feature is the ability to annotate or comment promises in a
-way that follows the promise through its lifecycle. This is part of
-the strategy of integrated knowledge management (see the Special
-Topics Guide on this subject).
-
-@cartouche
-@verbatim
-
-files:
-
- "/etc/passwd" -> "stakeholder"
-
- comment => "Verify the integrity of the password file to change",
- content => detect_all_changes;
-
-@end verbatim
-@end cartouche
-When a promise has a comment, this comment will be used to mark logs
-entries and error messages, providing context to these events for
-effective knowledge management.
-
-You can give each promise a name, if you like, to make it easy to refer to
-or search for. We call this the promise `handle'.
-
-@cartouche
-@verbatim
-
-files:
-
- "/etc/passwd" -> "stakeholder"
-
- handle => "passwd_change",
- comment => "Verify the integrity of the password file to change",
- content => detect_all_changes;
-
-@end verbatim
-@end cartouche
-You can use this handle to document relationships between promises.
-For example, consider this hypothetical promise:
-@cartouche
-@verbatim
-
-files:
-
- "/etc/group"
-
- handle => "group_change",
- comment => "Add new users to the user groups",
- depends_on => { "passwd_change", "other_promise" },
- edit_line => fix_groups;
-
-@end verbatim
-@end cartouche
-In CFEngine Nova and other commercial editions of the software,
-this documentation is automatically turned into browsable system
-documentation.
-
-@node Completely new features, , On best practices, General remarks and expectations
-@section Completely new features
-
-The CFEngine 3 Community Edition has many new features over CFEngine
-2, and CFEngine Nova and the other commercial editions have many
-features over the Community Edition. You can write promises in the
-Community Edition for any of the commercial features without error --
-these will just not be functional in the Community Edition. This makes it
-easy to upgrade (or downgrade) freely.
-
-New features in CFEngine 3 Community Edition include:
-
-@itemize
-@item All the components of CFEngine are now configurable and they read
-the same configuration file or files. In other words, you no longer have to
-maintain a separate input file for the server and the agent -- self-contained
-configurations can be made for all parts of the system in one.
-
-@item Promises now have containers called @i{promise bundles}. There is no analogue
-of promise bundles in CFEngine 2, so you will need to sort through your
-promises and divide them into suitable bundles yourself, making sure to
-give each a sensible name.
-
-@item Powerful pattern matching and expression features that simplify the promises
-by allowing a consistent promises to be made from a whole set of objects according to
-a programmed pattern.
-
-@item Consistent use of Perl Compatible Regular Expressions for text matching.
-
-@item Array and list handling functions allow powerful associative patterns.
-
-@item Basic tools for Knowledge Management integrated with the configuration
-technology.
-
-@item Generic package management.
-
-@item Role based access control for remote activation of special promises.
-
-@end itemize
-
-
-New features in CFEngine Nova include:
-
-@itemize
-
-@item Automated Knowledge Management and analysis
-
-@item Database management promises.
-
-@item LDAP integration.
-
-@item Extended and integrated lightweight monitoring capabilities.
-
-@item Service and virtualization abstractions.
-
-@item Full native Windows support and promise types.
-
-@end itemize
-
-@c #################################################################
-
-@c @node Automated translation with cfconvert, Translation Codebook, General remarks and expectations, Top
-@c @chapter Automated translation with @code{cfconvert}
-@node Conversion Strategy, Translation Codebook, General remarks and expectations, Top
-@chapter Conversion Strategy
-
-@c CFEngine offers a commercial core transformation program, @code{cfconvert}, that performs a reasonable translation of CFEngine 2 code into CFEngine 3 code. The output of this program should work with either the Community Edition or Enterprise level editions of the software.
-
-@c The software may be obtained with a one-time closed-source license, that includes maintainence in case of problems. This can be combined with Professional Services from CFEngine if necessary to provide a `best effort' conversion.
-
-
-@menu
-@c * Automatic Conversion Strategy::
-* Converting by module::
-* Assembling a compilable file set::
-* Validating the conversion::
-* Optimizing the configuration::
-@end menu
-
-@c @node Automatic Conversion Strategy, Converting by module, Automated translation with cfconvert, Automated translation with cfconvert
-@c @section Automatic Conversion Strategy
-
-@c No software can make a complete, `ready to go' translation of a configuration policy, as there are several decisions to be made when converting, as well as knowledge management features to be added. Below we offer recommendations for conversion using the @code{cfconvert} program.
-
-@c To begin conversion, we assume that you have a @file{cfagent.conf} master file that possibly includes a number of imported files, and that there are variables and classes defined throughout these.
-
-@c @menu
-@c * How long will it take to convert?::
-@c * One chunk at a time::
-@c @end menu
-
-@c @node How long will it take to convert?, One chunk at a time, Automatic Conversion Strategy, Automatic Conversion Strategy
-@c @subsection How long will it take to convert?
-
-@c If you are focused on the task, and you do not intend to re-organize the configuration dramatically, you can expect to be able to create a compilable version of a CFEngine configuration in the space of an hour.
-
-@c Filling in blanks, checking the correctness of the result and documenting it fully will take longer. It could take hours or days, depending on how many lines of code you have to convert. This is a tedious process, but one that will be a one-off burden and will bring great value to your operations. The conversion utility can shave off hundred of hours of manual labour from a hand-coded conversion.
-
-@c @node One chunk at a time, , How long will it take to convert?, Automatic Conversion Strategy
-@c @subsection One chunk at a time
-
-@c You can convert as much or as little of a configuration as you like in one go. The simplest conversion approach is to feed the whole configuration to @code{cfconvert} in one bite.
-
-@c @sp 1
-@c @verbatim
-@c host# export CFINPUTS=`pwd`
-@c host# cfconvert
-@c @end verbatim
-@c @sp 1
-@c The converted output is written to a sub-directory @file{cf_conversion}.
-
-@c @smallexample
-
-@c CFEngine Conversion Utility (beta)
-
-@c -> Matrix from /usr/local/sbin/cfconvert
-@c -> INPUTS from . /CFEngineProjects/Test_Client/CFEngine_2_config/
-@c -> OUTPUTS at /tmp/cf_conversion_output
-@c -> Commencing pre-scan for common environment
-@c -> Pre-scan complete
-@c -> Scanning for recognizable control settings
-@c -> > convert control setting EmailMaxLines
-@c -> > convert control setting cfinputs_version
-@c -> > convert control setting smtpserver
-@c -> > convert control setting Inform
-@c -> > convert control setting AddInstallables
-@c -> > convert control setting workdir
-@c -> > convert control setting Syslog
-@c -> > convert control setting moduledirectory
-@c -> > convert control setting moduledirectory
-@c -> Start main promise bundle
-@c -> Import files detected
-@c -> delta-Transformation of "cfagent.global.conf"
-@c -> delta-Transformation of "cfagent.freebsd.conf"
-@c -> delta-Transformation of "cfagent.ntp.conf"
-@c -> delta-Transformation of "cfagent.named.conf"
-@c -> delta-Transformation of "cfagent.perfsonarServers.conf"
-@c -> delta-Transformation of "cfagent.perfsonar.conf"
-@c -> delta-Transformation of "cfagent.owmesh.conf"
-@c -> delta-Transformation of "cfagent.owamp.conf"
-@c -> delta-Transformation of "cfagent.perfsonarBUOY.conf"
-@c -> delta-Transformation of "cfagent.syslog.conf"
-@c -> delta-Transformation of "cfagent.bwctl.conf"
-@c -> delta-Transformation of "cfagent.perfsonarBUOY.conf"
-@c -> delta-Transformation of "cfagent.syslog.conf"
-@c -> delta-Transformation of "cfagent.pinger.conf"
-@c -> delta-Transformation of "cfagent.perfsonarBUOY.conf"
-@c -> delta-Transformation of "cfagent.owmesh.conf"
-@c -> delta-Transformation of "cfagent.perfsonarBUOY.conf"
-@c -> delta-Transformation of "cfagent.owmesh.conf"
-@c -> delta-Transformation of "cfagent.LSRegistration.conf"
-@c -> delta-Transformation of "cfagent.freebsd.i386.packages"
-@c -> Converting cfservd.cf
-@c -> Writing promises.cf
-@c -> 11238 lines of core transformed
-
-@c @end smallexample
-
-@node Converting by module, Assembling a compilable file set, Conversion Strategy, Conversion Strategy
-@section Converting by module
-
-To optimize the translation, you should think about the modularity of
-your code. First, look at how your CFEngine 2 configuration is
-modularized and consider how you want your final CFEngine 3
-configuration to be modularized. CFEngine 3 has `promise bundles' as
-modular entities (like subroutines or methods in other languages).
-The typical procedure is to take each file and convert it into
-a separate bundle. This makes each module into a separate entity
-in the integrated knowledge management.
-
-There are potentially many ways to cut the cake, however. You can organize your
-configuration, by operating system, by service, by geography,
-etc. We recommend that you make separate bundles for each `issue',
-`service' or slice of the system that you are managing. Bundles should
-`bundle together' related promises.
-
-
-@node Assembling a compilable file set, Validating the conversion, Converting by module, Conversion Strategy
-@section Assembling a compilable file set
-
-The next step is to move as quickly as possible to a compilable
-CFEngine 3 configuration. You will be tweaking and perfecting this
-basic file set for ever more, but the sooner you have a syntactically
-valid file, the sooner you will benefit from the CFEngine tools.
-
-@enumerate
-@item Start by copying the Community Open Promise Body Library from the www.CFEngine.org
-website into the @file{CFEngine3} directory. We will base the converted
-configuration on these industry standard templates.
-
-@item Now create the new master configuration file
-@file{CFEngine3/promises.cf}. This will replace the
-@file{CFEngine2/cfagent.conf} file.
-
-Suppose you start with a top level @code{cfagent.conf} that is organized
-as in the example below,
-
-@sp 1
-
-@cartouche
-@verbatim
-
-control:
-
- # ....
-
-import:
-
- any::
-
- cfagent.global.conf
-
- freebsd::
-
- cfagent.freebsd.conf
-
- 123.456.789::
-
- cfagent.usa.conf
-
- MailServers::
-
- cfagent.email.conf
-
-@end verbatim
-@end cartouche
-
-@sp 1
-This file is typically converted to something of the following form.
-@sp 1
-
-
-@verbatim
-
-body agent control
-{
-# this is where control settings will go
-}
-
-body executor control
-{
-# this is where control settings will go
-}
-
-#####################################################
-
-body common control
-{
-# Keep the bundlesequence simple
-
-bundlesequence => { "g", "main" };
-
-# The equivalent of imports
-
-inputs => {
- "cfagent.freebsd.cf",
- "cfagent.usa.conf",
- "cfagent.email.conf",
- # ...
- "cfengine_stdlib.cf"
- };
-}
-
-#####################################################
-
-bundle common g
-{
-vars:
-
- "localroot" string => "/a/b/c";
- "cfsrvhost" string => "198.129.252.125";
- "masterBuild" string => "/usr/local/CFEngine_export/RELEASE/build";
-
-classes:
-
- # ...
-
-}
-
-#####################################################
-
-bundle agent main
-{
-methods:
-
- any::
- "any" usebundle => global_stuff;
-
- freebsd::
- "any" usebundle => freebsd_stuff;
-
- MailServers::
- "any" usebundle => mail_stuff;
-
-
-}
-@end verbatim
-
-
-@item Compare these two control files above.
-Notice that there is no @code{actionsequence} in the CFEngine 3
-configuration. CFEngine 3 can determine an order more automatically
-using a best-effort heuristic algorithm.@footnote{Some scheduling
-tools talk about `sorting of dependencies' to determine order, but
-this is not possible in a dynamic environment, since you don't know
-which dependencies will be in play until after the sort.} All we need
-to do is include the different bundles in the basic order that we want
-and CFEngine will do the rest.
-
-@end enumerate
-
-
-@node Validating the conversion, Optimizing the configuration, Assembling a compilable file set, Conversion Strategy
-@section Validating the conversion
-
-Validating the conversion is potentially an arduous process and
-the work is not over yet. Because CFEngine 3 uses body templates to
-simplify the appearence of promises, and promote the reusability of
-code, the conversion requires us to create these. @c The @code{cfconvert} utility attempts to construct best-effort proposal for these. If it is possible to convert using standard body templates, nothing more is needed. However, some translations require custom templates; the conversion utility creates a proposal and leaves the custom body or bundle in-line (in comment form) to allow you to compare the CFEngine 2 and CFEngine 3 versions of the promises more easily. For example:
-
-@c @verbatim
-@c "/etc/somefile" # -> { "optional_promisee_list" },
-
-@c comment => "...",
-@c # handle => "...",
-@c # depends_on => { "..." ...},
-
-@c perms => mog("0440","root","wheel"),
-@c copy_from => remote_cp("$(master)/etc/somefile","$(cfsrvhost)"),
-
-@c # More accurate translation requires custom coding..
-@c # body copy_from custom_body
-@c # {
-@c # servers => { "$(master)/etc/somefile"},
-@c # trustkey => "false";
-@c # compare => "digest";
-@c # }
-@c
-@c action => if_elapsed("60");
-
-@c @end verbatim
-@c It is up to you to decide whether you want to use the commented proposal. In some cases there is no solution in terms of standard bodies, and you must use the commented proposal or some version of it. In that case, you should copy the commented text to a location outside the current promise bundle, e.g. by pasting it into a separate library file, and there uncomment it. Don't forget to ensure that the file is included in the @code{inputs} lists.
-
-@c Any items that the conversion program does not know how to convert will also be commented out for manual attention.
-
-To complete the conversion, you will need to:
-
-@enumerate
-@item Check that the intention of the converted promise matches the orginal.
-@item Check that variable references are ok - global ones can be referenced with def.varname (if they are defined in the bundle common def)
-@item Insert comments
-@item Simplifying repeated patterns using lists.
-@item Run through cf-promises
-@end enumerate
-
-
-
-
-@node Optimizing the configuration, , Validating the conversion, Conversion Strategy
-@section Optimizing the configuration
-
-You could optimize by not importing files that you don't need on all systems.
-This reduces memory and processing time. To do this, you can adapt the
-@file{inputs} and @file{bundlesequence} of the converted file appropriately.
-
-
-@c **********************************************************************
-@c CHAPTER
-@c **********************************************************************
-
-@node Translation Codebook, , Conversion Strategy, Top
-@chapter Translation Codebook
-
-@c .................................................................
-@menu
-* upgrading from CFEngine 2 acl::
-* upgrading from CFEngine 2 admit::
-* upgrading from CFEngine 2 alerts::
-* upgrading from CFEngine 2 binservers::
-* upgrading from CFEngine 2 broadcast::
-* upgrading from CFEngine 2 control::
-* upgrading from CFEngine 2 classes::
-* upgrading from CFEngine 2 copy::
-* upgrading from CFEngine 2 defaultroute::
-* upgrading from CFEngine 2 deny::
-* upgrading from CFEngine 2 disks::
-* upgrading from CFEngine 2 directories::
-* upgrading from CFEngine 2 disable::
-* upgrading from CFEngine 2 editfiles::
-* upgrading from CFEngine 2 files::
-* upgrading from CFEngine 2 filters::
-* upgrading from CFEngine 2 groups::
-* upgrading from CFEngine 2 homeservers::
-* upgrading from CFEngine 2 ignore::
-* upgrading from CFEngine 2 import::
-* upgrading from CFEngine 2 interfaces::
-* upgrading from CFEngine 2 links::
-* upgrading from CFEngine 2 mailserver::
-* upgrading from CFEngine 2 methods::
-* upgrading from CFEngine 2 miscmounts::
-* upgrading from CFEngine 2 mountables::
-* upgrading from CFEngine 2 processes::
-* upgrading from CFEngine 2 packages::
-* upgrading from CFEngine 2 rename::
-* upgrading from CFEngine 2 required::
-* upgrading from CFEngine 2 resolve::
-* upgrading from CFEngine 2 scli::
-* upgrading from CFEngine 2 shellcommands::
-* upgrading from CFEngine 2 strategies::
-* upgrading from CFEngine 2 tidy::
-* upgrading from CFEngine 2 unmount ::
-@end menu
-
-@node upgrading from CFEngine 2 acl, upgrading from CFEngine 2 admit, Translation Codebook, Translation Codebook
-@section upgrading from CFEngine 2 @samp{acl}
-
-File Access Control Lists have been completely re-implemented in
-CFEngine 3. They are only available now in the commercial version of
-CFEngine, but with the benefit a unifying, platform-independent (least
-common denominator) model (in addition to system specific models) for
-Posix, Solaris, Linux, Windows and other ACL models.
-
-@verbatim
-
-files:
-
- /some/path
-
- acl=myacl
- action=fixall
-
-########################################
-
-acl:
-
- { myacl
-
- fstype:posix
- method:overwrite
- mask:*:rwx
- user:*:rwx
- group:*:r-x
- other:*:r
- user:www:=rwx
- user:mark:=rwx
- default_mask:=rwx
- default_user:=rwx
- default_group:=r
- default_other:=r
- }
-
-@end verbatim
-
-In CFEngine Nova, this would become approximately:
-
-@cartouche
-@verbatim
-
-bundle agent acls
-
-{
-files:
-
- "/some/path"
-
- acl => myacl;
-}
-
-#########################################
-
-body acl myacl
-
-{
-acl_method => "overwrite";
-acl_type => "posix";
-acl_directory_inherit => "specify";
-
-aces => {
- "mask:rwx",
- "user:*:rwx",
- "group:*:r,-x",
- "all:r",
- "user:www:=rwx",
- "user:mark:=rwx"
- };
-
-specify_inherit_aces =>
- {
- "mask:=rwx",
- "user:*:=rwx",
- "group:*:=r",
- "all:=r"
- };
-}
-
-@end verbatim
-@end cartouche
-
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 admit, upgrading from CFEngine 2 alerts, upgrading from CFEngine 2 acl, Translation Codebook
-@section upgrading from CFEngine 2 @samp{admit}
-
-The admit declarations belong to the server configuration.
-@verbatim
-admit: # or grant:
-
- /export/nexus/local/gnu/bin/CFEngine *.example.com
- /export/waldo/local/gnu/bin/CFEngine *.example.com
-
- /export/nexus/local *.example.com
- /export/nexus/ud dax.example.com
- /export/nexus/u4 dax.example.com dump-truck.example.com
- /etc *.example.com
-
-@end verbatim
-
-@noindent These are translated as @code{access} promises:
-@cartouche
-@smallformat
-@verbatim
-
-bundle server rules
-{
-access:
-
- "/export/nexus/local/gnu/bin/CFEngine" admit => { ".*.example.com" };
- "/export/waldo/local/gnu/bin/CFEngine" admit => { ".*.example.com" }
-
- "/export/nexus/local" admit => { ".*.example.com" };
- "/export/nexus/ud" admit => { "dax.example.com"};
- "/export/nexus/u4" admit => { "dax.example.com", "dump-truck.example.com" };
- "/etc" admit => { ".*.example.com" };
-}
-@end verbatim
-@end smallformat
-@end cartouche
-
-
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 alerts, upgrading from CFEngine 2 binservers, upgrading from CFEngine 2 admit, Translation Codebook
-@section upgrading from CFEngine 2 @samp{alerts}
-
-In CFEngine 2, the term for reporting was `alert'. This seemed too reactionary.
-
-@verbatim
-
-alerts:
-
- myclass::
-
- "Reminder: say hello every hour"
-
- ifelapsed=60
-
- nfsd_in_high_dev2::
-
- "High NFS server access rate 2dev at $(host)"
-
- ShowState(incoming.nfs)
-
-@end verbatim
-In CFEngine 3, you would write:
-@cartouche
-@verbatim
-
-reports:
-
- myclass::
-
- "Reminder: say hello every hour"
-
- action => ifelapsed("60");
-
- nfsd_in_high_dev2::
-
- "High NFS server access rate 2dev at $(host)"
-
- showstate => { "incoming.nfs" };
-
-@end verbatim
-@end cartouche
-CFEngine 3 extends the possiblities for messaging considerably.
-CFEngine Nova generates many standard reports automatically.
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 binservers, upgrading from CFEngine 2 broadcast, upgrading from CFEngine 2 alerts, Translation Codebook
-@section upgrading from CFEngine 2 @samp{binservers}
-
-The CFEngine Mount Model has been deprecated in version 3. The introduction of the
-automounter largely superceded the use of this model, and while it is still possible
-to use CFEngine as a static automounter, there is no longer any need for an explicit
-definition of its parts, as simple pattern matching combined with mount promises
-suffices to solve this problem, @xref{upgrading from CFEngine 2 miscmounts}.
-
-@verbatim
-control:
-
- site = ( mysite )
-
- MountPattern = ( /$(site)/$(host) )
- HomePattern = ( home? )
-
- actionsequence =
- (
- mountall
- mountinfo
- addmounts
- mountall
- )
-
-mountables:
-
- any::
-
- serv1:/mysite/serv1/home1
- serv1:/mysite/serv1/home2
- serv1:/mysite/serv1/local
- serv3:/mysite/serv3/local1
- serv3:/mysite/serv3/local2
- serv4:/mysite/serv4/homeA
- serv4:/mysite/serv4/homeB
-
-binservers:
-
- group1::
-
- serv1 serv2
-
- group2::
-
- serv3
-
-@end verbatim
-@noindent In CFEngine 3, you might write this:
-
-@cartouche
-@smallformat
-@verbatim
-
-storage:
-
- group1::
-
- "/mysite/serv1/local" mount => nfs("serv1","/mysite/serv1/local");
-
- group2::
-
- "/mysite/serv3/local1" mount => nfs("serv3","/mysite/serv3/local1");
- "/mysite/serv3/local2" mount => nfs("serv3","/mysite/serv3/local2");
-
- # Or use lists to iterate this
-
-@end verbatim
-@end smallformat
-@end cartouche
-
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 broadcast, upgrading from CFEngine 2 control, upgrading from CFEngine 2 binservers, Translation Codebook
-@section upgrading from CFEngine 2 @samp{broadcast}
-
-This is deprecated in CFEngine 3.
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 control, upgrading from CFEngine 2 classes, upgrading from CFEngine 2 broadcast, Translation Codebook
-@section upgrading from CFEngine 2 @samp{control}
-
-In CFEngine 2, the @code{control} part has two muddled functions:
-
-@itemize
-@item Setting parameters that control the internal behaviour of CFEngine.
-
- These are details that adjust the behaviour of promises that are hard-coded
-into CFEngine. Thus, they belong formally in @code{body} declarations according to
-the CFEngine 3 promise model.
-
-@item Defining user variables (macros).
-
-These are actual user-defined promises (the promise that a certain name
-will represent a certain value). They are thus represented as @code{vars}
-promises in CFEngine 3.
-@end itemize
-Note that there is no @code{actionsequence} in CFEngine 3. It is no longer needed
-and can be ignored.
-
-The following CFEngine 2 code
-@verbatim
-control:
-
- Access = ( root ) # Only root should run this
-
- site = ( iu )
- domain = ( iu.hio.no )
- sysadm = ( CFEngine@example.com )
- smtpserver = ( smtp@example.com )
-
- # Welcome to Norway...!
-
- timezone = ( MET CET )
-
- #
- # Where backup files (for copy/tidy) are kept
- #
-
- Repository = ( /var/spool/CFEngine )
-
- SplayTime = ( 4 )
-
- OutputPrefix = ( "cf:$(host)" )
-
- IfElapsed = ( 15 )
- ExpireAfter = ( 240 )
-
-
- SensibleSize = ( 1000 )
- SensibleCount = ( 2 )
- EditfileSize = ( 40000 )
-
- cfbin = ( /var/cfengine/bin )
- gnu = ( "/local/gnu" )
- ftp = ( /local/iu/ftp )
-
-@end verbatim
-@noindent translates in CFEngine 3 into several pieces:
-@cartouche
-@verbatim
-# Hard-coded promise parameters, common to all parts
-
-body common control
-{
-bundlesequence => { "global_promises" };
-}
-
-# Hard-coded promise parameters for cf-agent
-
-body agent control
-{
-default_repository => "/var/spool/CFEngine";
-ifelapsed => "15";
-expireafter => "240";
-sensiblesize => "1000";
-sensiblecount => "2";
-editfilesize => "40000";
-}
-
-# Hard-coded promise parameters for cf-execd
-
-body executor control
-{
-splaytime => "4";
-mailto => "cfengine@example.com";
-smtpserver => "smtp.example.com";
-}
-
-# User defined promises common to all parts
-
-bundle common global_promises
-{
-vars:
-
- "cfbin" string => "/var/cfengine/bin";
- "gnu" string => "/local/gnu";
- "ftp" string => "/local/iu/ftp";
-
-}
-
-@end verbatim
-@end cartouche
-Note that @code{vars} promises that are declared @samp{common} are
-seen by all bundles and all agents. It is also possible to have
-variables in @samp{agent} or @samp{server} bundles that are seen only by
-those parts of CFEngine.
-
-Control information from the @file{cfservd.conf} file goes naturally into
-a control body:
-
-@verbatim
-control:
-
- cfrunCommand = ( "/var/cfengine/bin/cfagent" )
- AllowConnectionsFrom = ( 127.0.0.1 ::1 )
- AllowMultipleConnectionsFrom = ( 127.0.0.1 ::1 )
- TrustKeysFrom = ( 127.0.0.1 ::1 )
- AllowUsers = ( root mark )
-
-@end verbatim
-@noindent becomes:
-@cartouche
-@smallformat
-@verbatim
-
-body server control
-
-{
-allowconnects => { "127.0.0.1" , "::1" };
-allowallconnects => { "127.0.0.1" , "::1" };
-trustkeysfrom => { "127.0.0.1" , "::1" };
-cfruncommand =>
- "$(sys.workdir)/bin/cf-agent -f failsafe.cf && $(sys.workdir)/bin/cf-agent";
-allowusers => { "mark", "root" };
-}
-
-@end verbatim
-@end smallformat
-@end cartouche
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 classes, upgrading from CFEngine 2 copy, upgrading from CFEngine 2 control, Translation Codebook
-@section upgrading from CFEngine 2 @samp{classes}
-
-@verbatim
-
-classes: # same as groups
-
- Setup_SSH_OK = ( '/usr/bin/test -f /etc/ssh2/ssh2_config' )
- science = ( saga tor odin )
- notthis = ( !this )
- ip_in_range_1 = ( IPRange(129.0.0.1-15) )
- ip_in_range_2 = ( IPRange(129.0.0.1/24) )
- compute_nodes = ( HostRange(cpu-,1-32) )
- science = ( +science-allhosts )
- physics_theory = ( +@physics-theory-sun4 dirac feynman schwinger )
- group1 = ( +mynetgroup -specialhost -otherhost )
- group2 = ( +bignetgroup -smallnetgroup )
- SpecialTimes = ( Hr00 Monday Day1 )
-
-@end verbatim
-These promises translate into CFEngine 3 as:
-@cartouche
-@smallformat
-@verbatim
-
-classes:
-
- "Setup_SSH_OK" expression => fileexists("/etc/ssh2/ssh2_config");
- "science" or => { "saga", "tor", "odin" };
- "notthis" expression => "!this";
- "ip_in_range" expression => iprange("129.0.0.1-15");
- "ip_in_range" expression => iprange("129.0.0.1/24");
- "compute_nodes" expression => hostrange("cpu-","1-32");
- "science" expression => hostinnetgroup("science-allhosts");
-
- "physics_theory" or => {
- hostinnetgroup("physics-theory-sun4",
- "dirac",
- "feynman",
- "schwinger"
- };
-
- "group1" and => {
- hostinnetgroup("mynetgroup"),
- "!specialhost",
- "!otherhost
- };
-
- "helper" expression => hostinnetgroup(smallnetgroup");
- "group2" and => { hostinnetgroup("bignetgroup"), "!helper" };
- "SpecialTimes" or => { "Hr00", "Monday", "Day1" };
-
-@end verbatim
-@end smallformat
-@end cartouche
-
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 copy, upgrading from CFEngine 2 defaultroute, upgrading from CFEngine 2 classes, Translation Codebook
-@section upgrading from CFEngine 2 @samp{copy}
-
-
-Copying of files from one location to another had the following form in CFEngine 2:
-@smallformat
-@verbatim
-
-copy:
-
- /masterfiles/hosts.deny dest=/etc/hosts.deny mode=644 server=nexus
-
- !(dax|cube|sigmund)::
-
- /masterfiles/hosts.allow dest=/etc/hosts.allow mode=644 server=nexus
-
- 128_39_89.!securehosts::
-
- /masterfiles/ssh_banner_message_89 dest=/etc/ssh2/ssh_banner_message
- mode=644 owner=root group=root
- encrypt=true
-
-@end verbatim
-@end smallformat
-
-In CFEngine 3, beware that the order of the source and destination have been reversed
-to follow the general principle in CFEngine 3 that the affected object (in this case the
-destination) is always the first object in the promise (the promiser).
-
-@cartouche
-@smallformat
-@verbatim
-
-files:
-
- "/etc/hosts.deny"
- copy_from => remote_cp("/masterfiles/hosts.deny","nexus"),
- perms => m("644");
-
- #
-
- !(dax|cube|sigmund)::
-
- "/etc/hosts.allow"
- copy_from => remote_cp("/masterfiles/hosts.allow","nexus"),
- perms => m("644");
-
- #
-
- 128_39_89.!securehosts::
-
- "/etc/ssh2/ssh_banner_message"
- copy_from => secure_cp("/masterfiles/ssh_banner_message_89")
- perms => mog("644","root","root");
-
-@end verbatim
-@end smallformat
-@end cartouche
-
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 defaultroute, upgrading from CFEngine 2 deny, upgrading from CFEngine 2 copy, Translation Codebook
-@section upgrading from CFEngine 2 @samp{defaultroute}
-
-This function is deprecated in CFEngine 3. Today it can normally be implemented by editing
-a file.
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 deny, upgrading from CFEngine 2 disks, upgrading from CFEngine 2 defaultroute, Translation Codebook
-@section upgrading from CFEngine 2 @samp{deny}
-
-@verbatim
-
-deny:
-
- $(public)/special *.moneyworld.com
-
-@end verbatim
-@noindent becomes:
-@cartouche
-@verbatim
-access:
-
- "$(public)/special"
-
- deny => { "*.moneyworld.com" };
-
-@end verbatim
-@end cartouche
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 disks, upgrading from CFEngine 2 directories, upgrading from CFEngine 2 deny, Translation Codebook
-@section upgrading from CFEngine 2 @samp{disks}
-
-@verbatim
-
-disks:
-
- /usr
-
- freespace=10%
-
-@end verbatim
-
-@noindent becomes
-@cartouche
-@verbatim
-
-storage:
-
- "/usr"
-
- volume => min_free_space("10%");
-
-@end verbatim
-@end cartouche
-
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 directories, upgrading from CFEngine 2 disable, upgrading from CFEngine 2 disks, Translation Codebook
-@section upgrading from CFEngine 2 @samp{directories}
-
-@verbatim
-
-directories:
-
- /usr/local/bin
-
- mode=755
- owner=root
- group=wheel
-@end verbatim
-
-@noindent becomes
-@cartouche
-@verbatim
-
-files:
-
- "/usr/local/bin/."
-
- create => "true",
- perms => mog("755","root","wheel");
-
-@end verbatim
-@end cartouche
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 disable, upgrading from CFEngine 2 editfiles, upgrading from CFEngine 2 directories, Translation Codebook
-@section upgrading from CFEngine 2 @samp{disable}
-
-Disabling files has many meanings in CFEngine 2. It covers log rotation as well as file disablement.
-@verbatim
-
-disable:
-
- /usr/bin/rsh
- /var/log/xferlog rotate=3
- /local/etc/fingerdir/userdata rotate=empty
-
-@end verbatim
-
-@cartouche
-@verbatim
-
-files:
-
- "/usr/bin/rsh" rename => disable;
-
- "/var/log/xferlog"
- rename => rotate("3");
-
- "/local/etc/fingerdir/userdata"
- rename => rotate("0");
-
-@end verbatim
-@end cartouche
-
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 editfiles, upgrading from CFEngine 2 files, upgrading from CFEngine 2 disable, Translation Codebook
-@section upgrading from CFEngine 2 @samp{editfiles}
-
-
-
-File editing is a complex subject. A few examples are provided.
-@smallformat
-@verbatim
-
-editfiles:
-
- !rom21X::
-
- { /etc/ssh2/sshd2_config
-
- ReplaceAll "PrintMotd.*yes" With "PrintMotd no"
- ReplaceAll ".*Ssh1Compatibility.*yes.*" With "Ssh1Compatibility no"
- AppendIfNoSuchLine "Ssh1Compatibility no"
- HashCommentLinesMatching ".*Sshd1Path.*"
- DeleteLinesMatching ".*PasswordAuthentication.*"
- DeleteLinesMatching ".*PubkeyAuthentication.*"
- DeleteLinesMatching ".*AllowCshrcSourcingWithSubsystems.*"
- }
-
-
-@end verbatim
-@end smallformat
-
-@cartouche
-@smallformat
-@verbatim
-
-files:
-
- !rom21X::
-
- "/etc/ssh2/sshd2_config"
-
- edit_line => ssh_config;
-
-
-# ..
-
-bundle edit_line ssh_config
-{
-replace_patterns:
-
- "PrintMotd.*yes"
- replace_with => all("PrintMotd no");
-
- ".*Ssh1Compatibility.*yes.*"
- replace_with => value("Ssh1Compatibility no");
-
- ".*Sshd1Path.*"
- replace_with => comment("#");
-
-delete_lines:
-
- ".*PasswordAuthentication.*";
- ".*PubkeyAuthentication.*";
- ".*AllowCshrcSourcingWithSubsystems.*";
-
-insert_lines:
-
- "Ssh1Compatibility no";
-}
-
-@end verbatim
-@end smallformat
-@end cartouche
-
-
-
-@smallformat
-@verbatim
-
-editfiles:
-
- { /etc/shells
-
- AppendIfNoSuchLine "/bin/tcsh"
- AppendIfNoSuchLine "/bin/bash"
- AppendIfNoSuchLine "/local/gnu/bin/bash"
- }
-
-
-@end verbatim
-@end smallformat
-
-
-@cartouche
-@smallformat
-@verbatim
-
-vars:
-
- "lines" slist => { "/bin/tcsh", "/bin/bash", "/local/gnu/bin/bash" };
-
-files:
-
- "/etc/shells"
-
- edit_line => append_if_no_lines(@(lines));
-
-
-@end verbatim
-@end smallformat
-@end cartouche
-
-or an alternative solution
-@cartouche
-@smallformat
-@verbatim
-
-files:
-
- "/etc/shells"
-
- edit_line => shells;
-
-# ..
-
-bundle edit_line shells
-{
-insert_lines:
-
- "/bin/tcsh";
- "/bin/bash";
- "/local/gnu/bin/bash";
-}
-
-
-@end verbatim
-@end smallformat
-@end cartouche
-
-
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 files, upgrading from CFEngine 2 filters, upgrading from CFEngine 2 editfiles, Translation Codebook
-@section upgrading from CFEngine 2 @samp{files}
-
-The @code{files} action in CFEngine 2 was mostly about permissions. In CFEngine 3, all file
-related operations are collected under this banner.
-
-@smallformat
-@verbatim
-
-files:
-
- PrimeServers::
-
- /local/dns/pz
-
- owner=dns
- mode=644
- action=fixall
- recurse=1
- exclude=Fixserial
-
- /local/dns/pz/Fixserial
- m=755
- action=fixplain
-
- NameServers::
-
- /local/logs/admin
-
- o=dns
- m=644
- act=fixplain
-
- /local/logs/security
-
- o=dns
- m=644
- act=fixplain
-
- /local/logs/updates
-
- o=dns
- m=644
- act=fixplain
-
- /local/logs/xfer o=dns m=644 act=fixplain
-
- #
- # Make sure anonymous ftp areas have the correct
- # protection, or logins won't be able to read files
- #
-
- $(ftp)/pub mode=644 o=root g=other act=fixall
- $(ftp)/pub mode=644 act=fixall r=inf
-
- $(ftp)/etc mode=111 o=root g=other act=fixdirs
- $(ftp)/usr/bin/ls mode=111 o=root g=other act=fixall
- $(ftp)/dev mode=555 o=root g=other act=fixall
- $(ftp)/usr mode=555 o=root g=other act=fixdirs
-
-
-@end verbatim
-@end smallformat
-@noindent may be translated into:
-@cartouche
-@smallformat
-@verbatim
-
-vars:
-
- "ns_files" slist => {
- "/local/logs/admin",
- "/local/logs/security",
- "/local/logs/updates",
- "/local/logs/xfer"
- };
-files:
-
- PrimeServers::
-
- "/local/dns/pz"
-
- perms => mo("644","dns")
- depth_search => recurse("1"),
- file_select => exclude("FixSerial");
-
- "/local/dns/pz/FixSerial"
-
- perms => m("755"),
- file_select => plain;
-
- NameServers::
-
- "$(ns_files)"
-
- perms => mo("644","dns"),
- file_select => plain;
-
- #
- # Make sure anonymous ftp areas have the correct
- # protection, or logins won't be able to read files
- #
-
- "$(ftp)/pub"
- perms => mog("644","root","other");
-
- "$(ftp)/pub"
- perms => m("644"),
- depth_search => recurse("inf");
-
- "$(ftp)/etc" perms => mog("111","root","other");
- "$(ftp)/usr/bin/ls" perms => mog("111","root","other");
- "$(ftp)/dev" perms => mog("555","root","other");
- "$(ftp)/usr" perms => mog("555","root","other");
-
-@end verbatim
-@end smallformat
-@end cartouche
-
-
-
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 filters, upgrading from CFEngine 2 groups, upgrading from CFEngine 2 files, Translation Codebook
-@section upgrading from CFEngine 2 @samp{filters}
-
-Filters have been redefined as `select' body templates. Filters exist for processes
-and files in CFEngine 2. These translate into keywords @code{process_select}
-and @code{file_select}.
-
-@smallformat
-@verbatim
-
-filters:
-
- { testfilteralias
-
- Owner: "mark"
- Group: "cfengine"
- Type: "dir|link"
-
- Result: "Type|(Owner.Group)" # Both owner AND group required correct
- }
-
-@end verbatim
-@end smallformat
-@noindent becomes
-
-@cartouche
-@smallformat
-@verbatim
-
-body file_select testfilteralias
-
-{
-search_owners => { "mark" };
-search_groups => { "cfengine" };
-file_types => { "dir","symlink" };
-
-file_result => "file_types|(owners.groups)";
-}
-
-@end verbatim
-@end smallformat
-@end cartouche
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 groups, upgrading from CFEngine 2 homeservers, upgrading from CFEngine 2 filters, Translation Codebook
-@section upgrading from CFEngine 2 @samp{groups}
-
-Groups are a synonym for classes,
-see @xref{upgrading from CFEngine 2 classes}.
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 homeservers, upgrading from CFEngine 2 ignore, upgrading from CFEngine 2 groups, Translation Codebook
-@section upgrading from CFEngine 2 @samp{homeservers}
-
-The CFEngine Mount Model has been deprecated in version 3. The introduction of the
-automounter largely superceded the use of this model, and while it is still possible
-to use CFEngine as a static automounter, there is no longer any need for an explicit
-definition of its parts, as simple pattern matching combined with mount promises
-suffices to solve this problem, @xref{upgrading from CFEngine 2 miscmounts}.
-
-
-@smallformat
-@verbatim
-control:
-
- site = ( mysite )
-
- MountPattern = ( /$(site)/$(host) )
- HomePattern = ( home? )
-
- actionsequence =
- (
- mountall
- mountinfo
- addmounts
- mountall
- )
-
-mountables:
-
- any::
-
- serv1:/mysite/serv1/home1
- serv1:/mysite/serv1/home2
- serv1:/mysite/serv1/local
- serv3:/mysite/serv3/local1
- serv3:/mysite/serv3/local2
- serv4:/mysite/serv4/homeA
- serv4:/mysite/serv4/homeB
-
-homeservers:
-
- group1::
-
- serv1 serv2
-
- group2::
-
- serv4
-
-@end verbatim
-@end smallformat
-In CFEngine 3, you might write this:
-
-@cartouche
-@smallformat
-@verbatim
-
-storage:
-
- group1::
-
- "/mysite/serv1/home1" mount => nfs("serv1","/mysite/serv1/home1");
- "/mysite/serv1/home2" mount => nfs("serv1","/mysite/serv1/home2");
-
- group2::
-
- "/mysite/serv4/homeA" mount => nfs("serv4","/mysite/serv3/homeA");
- "/mysite/serv4/homeB" mount => nfs("serv4","/mysite/serv3/homeB");
-
-@end verbatim
-@end smallformat
-@end cartouche
-
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 ignore, upgrading from CFEngine 2 import, upgrading from CFEngine 2 homeservers, Translation Codebook
-@section upgrading from CFEngine 2 @samp{ignore}
-
-Ignore is used in CFEngine 2 to skip directories or filenames during
-searches. CFEngine 3 does not have a global list for this, but uses
-local lists analogous to the @samp{ignore=} attributes.
-
-To make a global list in CFEngine 3, you can simply define a list of names and attach it to any promise
-in the program. Instead of CFEngine 2:
-
-@smallformat
-@verbatim
-
-ignore:
-
- one
- two
- three
-
-@end verbatim
-@end smallformat
-@noindent we use:
-@cartouche
-@smallformat
-@verbatim
-
-bundle common defs
-{
-vars:
-
- "ignore_list" slist => { "one", "two", "three" };
-}
-
-# ...
-
-bundle agent filestuff
-{
-files:
-
- "/mypath"
-
- depth_search => recurse_ignore("inf",@(defs.ignore_list));
-}
-
-@end verbatim
-@end smallformat
-@end cartouche
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 import, upgrading from CFEngine 2 interfaces, upgrading from CFEngine 2 ignore, Translation Codebook
-@section upgrading from CFEngine 2 @samp{import}
-
-@verbatim
-import:
-
- one.cf
- two.cf
- three.cf
-
-@end verbatim
-@noindent becomes
-@cartouche
-@verbatim
-bundle common control
-{
-inputs => { "one.cf", "two.cf", "three.cf" };
-}
-@end verbatim
-@end cartouche
-
-In CFEngine 3, file imports are no longer order sensitive in the manner of CFEngine 2.
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 interfaces, upgrading from CFEngine 2 links, upgrading from CFEngine 2 import, Translation Codebook
-@section upgrading from CFEngine 2 @samp{interfaces}
-
-This promise type has been temporarily placed on hold, pending
-future developments. Interface management has become much
-simpler since the early days of CFEngine, but this will eventually
-include routing promises for network management.
-
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 links, upgrading from CFEngine 2 mailserver, upgrading from CFEngine 2 interfaces, Translation Codebook
-@section upgrading from CFEngine 2 @samp{links}
-
-
-Linking files in CFEngine 2:
-
-@verbatim
-
-links:
-
- nexus::
-
- /etc/rsyncd.conf -> /local/etc/rsyncd.conf
-
-
-@end verbatim
-
-In CFEngine 3 this becomes
-@cartouche
-@verbatim
-
-files:
-
- nexus::
-
- "/etc/rsyncd.conf"
-
- link_from => ln_s("/local/etc/rsyncd.conf");
-
-@end verbatim
-@end cartouche
-Linking directories of multiple children:
-@verbatim
-
-links:
-
- /usr/local/bin +> /usr/local/lib/perl/bin
- /opt +>! /local
-
-
-@end verbatim
-
-In CFEngine 3 this becomes
-@cartouche
-@verbatim
-
-files:
-
- "/usr/local/lib/perl/bin" => linkchildren("/usr/local/bin");
- "/local" => linkchildren("/opt");
-
-@end verbatim
-@noindent Or alternatively, use recursive copy with @code{linkcopy_patterns => @{ ".*" @}}
-@end cartouche
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 mailserver, upgrading from CFEngine 2 methods, upgrading from CFEngine 2 links, Translation Codebook
-@section upgrading from CFEngine 2 @samp{mailserver}
-
-This section has been deprecated in CFEngine 3. It can be handled by @code{mount} promises.
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 methods, upgrading from CFEngine 2 miscmounts, upgrading from CFEngine 2 mailserver, Translation Codebook
-@section upgrading from CFEngine 2 @samp{methods}
-
-
-In CFEngine 2, methods were experimental. Methods are ways of making
-subroutines of CFEngine code. They were executed as separate programs following a
-special protocol, and could be activated remotely.
-
-There is no direct mapping between methods in CFEngine 2 and CFEngine
-3. In CFEngine 3, methods are simply bundles of promises that are
-executed as a group. These bundles can be parameterized and re-used.
-They are what methods should have been in CFEngine 2. Remote methods,
-are not implemented in CFEngine 3. Instead CFEngine Nova provides the
-means for agents to share data remotely by `voluntary cooperation'.
-
-@smallformat
-@verbatim
-# cfagent.conf
-
-control:
-
-actionsequence = ( methods )
-
-#################################################
-
-methods:
-
- SimpleMethod(null)
-
- action=cf.simple
- returnvars=null
- returnclasses=null
- server=localhost
-
-@end verbatim
-@end smallformat
-and
-@smallformat
-@verbatim
-# cf.simple
-
-control:
-
- MethodName = ( SimpleMethod )
- MethodParameters = ( null )
- actionsequence = ( timezone )
-
-classes:
-
- dummy = ( any )
-
- ####################################################
-
-alerts:
-
- dummy::
-
- "This simple method does nothing"
-
- ReturnVariables(void)
- ReturnClasses(void)
-@end verbatim
-@end smallformat
-This can be achieved more simply in CFEngine 3 as:
-
-@cartouche
-@verbatim
-bundle agent parent
-{
-methods:
-
- "some_id" usebundle => SimpleMethod;
-
-#...
-}
-
-bundle agent SimpleMethod
-{
-classes:
-
- "dummy" expression => "any";
-
-reports:
-
- dummy::
-
- "This simple method does nothing";
-}
-@end verbatim
-@end cartouche
-
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 miscmounts, upgrading from CFEngine 2 mountables, upgrading from CFEngine 2 methods, Translation Codebook
-@section upgrading from CFEngine 2 @samp{miscmounts}
-
-
-@smallformat
-@verbatim
-
-miscmounts:
-
- host:/foo /mnt/foo
-
- myserver:/$(site)/libraryserver/data1
- /mnt/data1 ro
-
- # consistent syntax
-
- myserver:/$(site)/libraryserver/data2
- /mnt/data2 mode=ro
-
-
-@end verbatim
-@end smallformat
-
-@cartouche
-@smallformat
-@verbatim
-
-storage:
-
- "/foot" mount => nfs("host","/foo");
-
- "/$(site)/libraryserver/data1"
-
- mount => nfs_p("myserver","/$(site)/libraryserver/data1","ro");
-
- "/$(site)/libraryserver/data2"
-
- mount => nfs_p("myserver","/$(site)/libraryserver/data2","ro");
-
-
-@end verbatim
-@end smallformat
-@end cartouche
-
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 mountables, upgrading from CFEngine 2 processes, upgrading from CFEngine 2 miscmounts, Translation Codebook
-@section upgrading from CFEngine 2 @samp{mountables}
-
-This list has been deprecated in CFEngine 3, see @xref{upgrading from CFEngine 2 miscmounts}.
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 processes, upgrading from CFEngine 2 packages, upgrading from CFEngine 2 mountables, Translation Codebook
-@section upgrading from CFEngine 2 @samp{processes}
-
-In CFEngine 2 process promises were muddled with commands that were used to restart
-processes that were not running. The led to inconsistency in the handling of commands.
-CFEngine 3 separates commands to restart processes so that the full range of
-promise attributes can be applied during process start control.
-@verbatim
-
-processes:
-
- "inetd"
-
- signal=hup
-
- "bootp"
-
- signal=kill
- exclude=rpc.bootparamd
-
- "cfservd"
-
- restart "/usr/local/sbin/cfservd"
- useshell=false
-
- # matches=>6 warn number of matches is greater than or equal to 6
- # matches=1 warn if not exactly 1 matching process
- # matches=<2 warn if there are less than or equal to 2 matching processes
-
-@end verbatim
-@noindent Translates to:
-@cartouche
-@verbatim
-
-processes:
-
- "inetd"
- signals => { "hup" };
-
- "bootp"
- signals => { "kill" },
- process_select => exclude_procs(".*rpc.bootparamd.*");
-
-
- "cf-serverd"
- restart_class => "start_cfserverd";
-
- # process_count => check_range(cfserv,6,inf); warn number of matches is greater than or equal to 6
- # process_count => check_range(cfserv,1,1); warn if not exactly 1 matching process
- # process_count => check_range(cfserv,0,2); warn if there are less than or equal to 2 matching processes
-
-commands:
-
- start_cfserverd::
-
- "/usr/local/sbin/cf-serverd";
-
-reports:
-
- cfserv_out_of_range::
-
- "cf-serverd is out of control!!";
-
-@end verbatim
-@end cartouche
-We can make use of lists to simplify the checking of multiple processes:
-@verbatim
-
-processes:
-
- Syslogdhup::
-
- "Syslogd" signal=hup
-
- any::
-
- "snmp" signal=kill
- "powerd" signal=kill
- "mibiisa" signal=kill
-
-@end verbatim
-becomes:
-@cartouche
-@verbatim
-
-vars:
-
- "kill_list" slist => { "snmp", "powerd", "mibiisa" };
-
-processes:
-
- Syslogdhup::
-
- "Syslogd" signals => { "hup" };
-
- any::
-
- "$(kill_list)" signals => { "kill" };
-
-@end verbatim
-@end cartouche
-Lists can also be used to simplify process starting. The following script
-@smallformat
-@verbatim
-
-processes:
-
- "named" restart "/local/sbin/named -u dns"
- useshell=false
- inform=true
-
- "cfservd" restart "/var/cfengine/bin/cfservd"
- "cfenvd" restart "/var/cfengine/bin/cfenvd"
- "cfexecd" restart "/var/cfengine/bin/cfexecd"
-
-@end verbatim
-@end smallformat
-@noindent would translate more efficiently into:
-@cartouche
-@smallformat
-@verbatim
-vars:
-
- "daemons" slist => { "cf-monitord", "cf-serverd", "cf-execd" };
-
-processes:
-
- "named" restart_class => "restart_named";
-
- "$(daemons)" restart_class => canonify("start_$(component)");
-
-commands:
-
- "/bin/echo /var/cfengine/bin/$(component)"
- ifvarclass => canonify("start_$(component)");
-
- restart_named::
-
- "/local/sbin/named -u dns"
- action => inform;
-
-@end verbatim
-@end smallformat
-@end cartouche
-
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 packages, upgrading from CFEngine 2 rename, upgrading from CFEngine 2 processes, Translation Codebook
-@section upgrading from CFEngine 2 @samp{packages}
-
-Package handling in CFEngine 3 is far superior and more flexible than in CFEngine 2.
-There are many ways to code packages promises. Here is a simple way to code
-specific lists of versioned packages. In CFEngine 2 one might write:
-
-@smallformat
-@verbatim
-
-packages:
-
- autoconf-2.13.000227_6 version=2.13.000227_6 cmp=ge action=install
- automake-1.9.6_3 version=1.9.6_3 cmp=ge action=install
- gmake-3.81_3 version=3.81_3 cmp=ge action=install
- help2man-1.36.4_2 version=1.36.4_2 cmp=ge action=install
- mysql-server-5.0.67 version=5.0.67 cmp=ge elsedefine=InstallMySQL
-
- # ...
-
-@end verbatim
-@end smallformat
-@noindent This could be translated efficiently using an associative array:
-@cartouche
-@smallformat
-@verbatim
-vars:
-
- "v[autoconf-2.13.000227_6]" string => "2.13.000227_6"
- "v[automake-1.9.6_3]" string => "1.9.6_3"
- "v[gmake-3.81_3]" string => "3.81_3"
- "v[help2man-1.36.4_2]" string => "1.36.4_2"
-
- # ...
-
- "packages" slist => getindices("v");
-
-packages:
-
- "$(packages)"
-
- package_policy => "add",
- package_method => freebsd,
- package_select => ">=",
- package_version => "$(v[$(package)])";
-
-@end verbatim
-@end smallformat
-@end cartouche
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 rename, upgrading from CFEngine 2 required, upgrading from CFEngine 2 packages, Translation Codebook
-@section upgrading from CFEngine 2 @samp{rename}
-
-This is an alias, see @xref{upgrading from CFEngine 2 disable}.
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 required, upgrading from CFEngine 2 resolve, upgrading from CFEngine 2 rename, Translation Codebook
-@section upgrading from CFEngine 2 @samp{required}
-
-This is an alias, see @xref{upgrading from CFEngine 2 disks}.
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 resolve, upgrading from CFEngine 2 scli, upgrading from CFEngine 2 required, Translation Codebook
-@section upgrading from CFEngine 2 @samp{resolve}
-
-The special resolver configuration in CFEngine 2 has been deprecated in favour of using
-straightforward editing commands to manage the resolver file. The special variable
-@code{$(sys.resolv)} points to the system's current resolver configuration file.
-Thus the CFEngine 2 configuration:
-@smallformat
-@verbatim
-
-resolve:
-
- "search iu.hio.no CFEngine.com"
- 128.39.89.10
- 158.36.85.10
- 129.241.1.99
-
-@end verbatim
-@end smallformat
-@noindent may be translated as:
-@cartouche
-@smallformat
-@verbatim
-
-vars:
-
- "r" slist => { "128.39.89.10", "158.36.85.10", "129.241.1.99" };
-
-files:
-
- "$(sys.resolv)"
-
- edit_line => resolvconf("iu.hio.no CFEngine.com",@(mybundle.r));
- # edit_default => empty;
-
-@end verbatim
-@end smallformat
-@end cartouche
-
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 scli, upgrading from CFEngine 2 shellcommands, upgrading from CFEngine 2 resolve, Translation Codebook
-@section upgrading from CFEngine 2 @samp{scli}
-
-SCLI (SNMP Command Line Interface) promises are deprecated in CFEngine
-3. There are no plans to integrate CFEngine directly with SNMP.
-
-Users of CFEngine Nova can use the generic @code{measurement} promises
-to encapsulate SNMP monitoring into the CFEngine framework if
-necessary.
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 shellcommands, upgrading from CFEngine 2 strategies, upgrading from CFEngine 2 scli, Translation Codebook
-@section upgrading from CFEngine 2 @samp{shellcommands}
-
-Shellcommands scheduled the execution of scripts and programs external
-to the CFEngine framework in CFEngine 2. The following examples
-
-@verbatim
-shellcommands:
-
- nexus::
-
- "/usr/sbin/shareall"
-
- ifelapsed=240
-
- cube.nfs_update::
-
- "/etc/init.d/nfs-server restart > /dev/null 2>&1"
-
-@end verbatim
-@noindent may be translated as:
-
-@cartouche
-@verbatim
-commands:
-
- nexus::
-
- "/usr/sbin/shareall"
-
- action => ifelapsed("240");
-
- cube.nfs_update::
- "/etc/init.d/nfs-server restart > /dev/null 2>&1"
-
- contain => in_shell;
-
-@end verbatim
-@end cartouche
-
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 strategies, upgrading from CFEngine 2 tidy, upgrading from CFEngine 2 shellcommands, Translation Codebook
-@section upgrading from CFEngine 2 @samp{strategies}
-
-Strategies in CFEngine 2 define probabilistic classes.
-This has become part of a @code{classes} promise is CFEngine 3.
-
-@verbatim
-strategies:
-
- { spread_load
-
- percent_10: "1"
- percent_30: "3"
- precent_60: "6"
- }
-
-@end verbatim
-@noindent translates as:
-@cartouche
-@verbatim
-
-classes:
-
- "percent" dist => { "10", "30", "60" };
-
-@end verbatim
-@end cartouche
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 tidy, upgrading from CFEngine 2 unmount , upgrading from CFEngine 2 strategies, Translation Codebook
-@section upgrading from CFEngine 2 @samp{tidy}
-
-@verbatim
-
-tidy:
-
- /tmp/ pattern=* recurse=inf age=1
- /var/tmp pattern=* recurse=inf age=2
- / pattern=core r=1 a=0
- /etc pattern=core r=1 a=0
-
-@end verbatim
-@noindent This may be translated into the following:
-@cartouche
-@verbatim
-
-files:
-
- "/tmp"
-
- depth_search => recurse("1"),
- file_select => name_age(".*","1");
-
- "/var/tmp"
-
- depth_search => recurse("inf"),
- file_select => name_age(".*","2");
-
- "/"
- depth_search => recurse("1"),
- file_select => name_age("core","0");
-
- "/etc"
- depth_search => recurse("1"),
- file_select => name_age("core","0");
-
-@end verbatim
-@end cartouche
-
-@page
-@c .................................................................
-@node upgrading from CFEngine 2 unmount , , upgrading from CFEngine 2 tidy, Translation Codebook
-@section upgrading from CFEngine 2 @samp{unmount}
-
-@verbatim
-
-unmount:
-
- /mnt
-@end verbatim
-
-@noindent Translates to:
-
-@cartouche
-@verbatim
-
-storage:
-
- "/mnt" mount => unmount;
-
-@end verbatim
-@end cartouche
-
-@c =========================================================================
-@c @node Index, , CFEngine Methods, Top
-@c @unnumbered Concept Index
-@c @printindex cp
-@c =========================================================================
-
-@ifhtml
-@html
-
-@contents
-@end html
-@end ifhtml
-
-@ifhtml
-@html
-
-
-@end html
-@end ifhtml
-
-@bye
-
diff --git a/docs/guides/cf_Quickref3.texinfo b/docs/guides/cf_Quickref3.texinfo
deleted file mode 100644
index 01e385c275..0000000000
--- a/docs/guides/cf_Quickref3.texinfo
+++ /dev/null
@@ -1,569 +0,0 @@
-\input texinfo-altfont
-\input texinfo-logo
-\input texinfo
-@selectaltfont{cmbright}
-@setlogo{CFEngineFrontPage}
-@c *********************************************************************
-@c
-@c This is a TEXINFO file. It generates both TEX documentation and
-@c the "on line" documentation "info" files.
-@c
-@c The file is structured like a programming language. Each chapter
-@c starts with a chapter comment.
-@c
-@c Menus list the subsections so that an online info-reader can parse
-@c the file hierarchically.
-@c
-@c ***********************************************************************
-@c %** start of header
-@setfilename cf-QuickRef3.info
-@settitle Quick Reference Guide for CFEngine 3
-@c @setchapternewpage odd
-@c %** end of header
-
-@smallbook
-@titlepage
-@title Quick Reference Guide for CFEngine 3
-@subtitle A CFEngine AS workbook
-@author CFEngine AS
-
-@page
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2012 CFEngine AS
-
-@end titlepage
-
-
-@c *************************** File begins here ************************
-
-@ifnottex
-@node Top, Command reference, (dir), (dir)
-@top CFEngine-Reference
-@end ifnottex
-
-@ifinfo
-@dircategory CFEngine Training
-@direntry
-* CFEngine Modularization:
- CFEngine is a language based tool specifically
- designed for configuring and maintaining
- Unix-like operating systems attached
- to a TCP/IP network.
-@end direntry
-@end ifinfo
-
-
-@ifhtml
-@html
-
-@end html
-@end ifhtml
-@iftex
-@contents
-@end iftex
-@node The Purpose Of This Handbook
-@chapter The Purpose Of This Handbook
-
-@sp 1
-
-CFEngine is built on promises. Promises were chosen as the model for CFEngine's
-configuration language, because they represent an expression of intention.
-
-If you are using custom scripts to manage your systems, you are using
-@i{recipes}. Take a look at any cookbook and you will see that all
-recipes look the same: take flour, eggs, butter, sugar ... and you
-know nothing because you can make a hundred things from these steps.
-If you don't make clear your intention, it is very hard to know what
-the recipe is supposed to be: is it a cake, a waffle, a pastry?
-
-The same is true in system administration. Recipes are not merely
-scripts, they encapsulate knowledge and experience. Their value is
-in communicating @i{desired outcomes} or states.
-
-This library of standard components is like a cookbook that tells you
-only how to make basics well. It gives these basic skills names and
-therefore gives you a common vocabulary -- you will put together these
-basics in creative ways to build your systems.
-
-@sp 2
-
-@cartouche
-
-Please contribute to this guide by helping to develop a repertoire of
-basic skills and names. This collection should be comprehensive but
-parsimonious. Basics are only basics if they are few and carefully
-thought out. This is a work in progress and your experience is welcome.
-
-This library will be moderated by CFEngine, and contributions and discussions
-ca n be made to the help-cfengine@@cfengine.org mailing list.
-
-@end cartouche
-
-
-
-
-
diff --git a/docs/guides/promise_page.png b/docs/guides/promise_page.png
deleted file mode 100644
index faff956db3..0000000000
Binary files a/docs/guides/promise_page.png and /dev/null differ
diff --git a/docs/guides/qs1.png b/docs/guides/qs1.png
deleted file mode 100644
index 708c27dfea..0000000000
Binary files a/docs/guides/qs1.png and /dev/null differ
diff --git a/docs/guides/qs2.png b/docs/guides/qs2.png
deleted file mode 100644
index 72ed30ef78..0000000000
Binary files a/docs/guides/qs2.png and /dev/null differ
diff --git a/docs/guides/rbac.png b/docs/guides/rbac.png
deleted file mode 100644
index 2f13877114..0000000000
Binary files a/docs/guides/rbac.png and /dev/null differ
diff --git a/docs/guides/redundhubs.png b/docs/guides/redundhubs.png
deleted file mode 100644
index efac20cdbd..0000000000
Binary files a/docs/guides/redundhubs.png and /dev/null differ
diff --git a/docs/guides/role-define-loba.png b/docs/guides/role-define-loba.png
deleted file mode 100644
index 61bee7f602..0000000000
Binary files a/docs/guides/role-define-loba.png and /dev/null differ
diff --git a/docs/guides/roll-forward.png b/docs/guides/roll-forward.png
deleted file mode 100644
index 7b641c58e1..0000000000
Binary files a/docs/guides/roll-forward.png and /dev/null differ
diff --git a/docs/guides/savefiledlg.png b/docs/guides/savefiledlg.png
deleted file mode 100644
index 942fea4071..0000000000
Binary files a/docs/guides/savefiledlg.png and /dev/null differ
diff --git a/docs/guides/schedule_patterns.png b/docs/guides/schedule_patterns.png
deleted file mode 100644
index 05010d9470..0000000000
Binary files a/docs/guides/schedule_patterns.png and /dev/null differ
diff --git a/docs/guides/scope2.png b/docs/guides/scope2.png
deleted file mode 100644
index 4f43f9e47d..0000000000
Binary files a/docs/guides/scope2.png and /dev/null differ
diff --git a/docs/guides/service_catalogue.png b/docs/guides/service_catalogue.png
deleted file mode 100644
index 3cdda02e43..0000000000
Binary files a/docs/guides/service_catalogue.png and /dev/null differ
diff --git a/docs/guides/setuid.png b/docs/guides/setuid.png
deleted file mode 100644
index 2cb431ee72..0000000000
Binary files a/docs/guides/setuid.png and /dev/null differ
diff --git a/docs/guides/software.png b/docs/guides/software.png
deleted file mode 100644
index b7e39b07d2..0000000000
Binary files a/docs/guides/software.png and /dev/null differ
diff --git a/docs/guides/status.png b/docs/guides/status.png
deleted file mode 100644
index 1e98e3103e..0000000000
Binary files a/docs/guides/status.png and /dev/null differ
diff --git a/docs/guides/summary.png b/docs/guides/summary.png
deleted file mode 100644
index 65ab91adfb..0000000000
Binary files a/docs/guides/summary.png and /dev/null differ
diff --git a/docs/guides/timeseries.png b/docs/guides/timeseries.png
deleted file mode 100644
index c11ea8b9a4..0000000000
Binary files a/docs/guides/timeseries.png and /dev/null differ
diff --git a/docs/guides/topic.png b/docs/guides/topic.png
deleted file mode 100644
index 9bcef12502..0000000000
Binary files a/docs/guides/topic.png and /dev/null differ
diff --git a/docs/guides/topicmap.png b/docs/guides/topicmap.png
deleted file mode 100644
index 4b28e9a99b..0000000000
Binary files a/docs/guides/topicmap.png and /dev/null differ
diff --git a/docs/guides/trends.png b/docs/guides/trends.png
deleted file mode 100644
index 0e55249fe4..0000000000
Binary files a/docs/guides/trends.png and /dev/null differ
diff --git a/docs/guides/update.png b/docs/guides/update.png
deleted file mode 100644
index c67b1c04cf..0000000000
Binary files a/docs/guides/update.png and /dev/null differ
diff --git a/docs/guides/updatedialog.png b/docs/guides/updatedialog.png
deleted file mode 100644
index aca7f06b9a..0000000000
Binary files a/docs/guides/updatedialog.png and /dev/null differ
diff --git a/docs/guides/views.png b/docs/guides/views.png
deleted file mode 100644
index f5fc7d6d38..0000000000
Binary files a/docs/guides/views.png and /dev/null differ
diff --git a/docs/guides/weakest.png b/docs/guides/weakest.png
deleted file mode 100644
index 72e56ab3a6..0000000000
Binary files a/docs/guides/weakest.png and /dev/null differ
diff --git a/docs/guides/winevent-notkept-storage.png b/docs/guides/winevent-notkept-storage.png
deleted file mode 100644
index 0aaf43ceb6..0000000000
Binary files a/docs/guides/winevent-notkept-storage.png and /dev/null differ
diff --git a/docs/guides/winevent-repaired-acl-closeup.png b/docs/guides/winevent-repaired-acl-closeup.png
deleted file mode 100644
index 31213a5d02..0000000000
Binary files a/docs/guides/winevent-repaired-acl-closeup.png and /dev/null differ
diff --git a/docs/guides/winhello.png b/docs/guides/winhello.png
deleted file mode 100644
index e6ff026505..0000000000
Binary files a/docs/guides/winhello.png and /dev/null differ
diff --git a/docs/guides/winreg-create.png b/docs/guides/winreg-create.png
deleted file mode 100644
index a1b5af79b5..0000000000
Binary files a/docs/guides/winreg-create.png and /dev/null differ
diff --git a/docs/guides/winreg-delete.png b/docs/guides/winreg-delete.png
deleted file mode 100644
index 131031fe3c..0000000000
Binary files a/docs/guides/winreg-delete.png and /dev/null differ
diff --git a/docs/guides/winservice-disabled_policy.png b/docs/guides/winservice-disabled_policy.png
deleted file mode 100644
index 68ff61cd07..0000000000
Binary files a/docs/guides/winservice-disabled_policy.png and /dev/null differ
diff --git a/docs/guides/winservice-properties_name.png b/docs/guides/winservice-properties_name.png
deleted file mode 100644
index 86e4126621..0000000000
Binary files a/docs/guides/winservice-properties_name.png and /dev/null differ
diff --git a/docs/reference/CFEngineFrontPage.pdf b/docs/reference/CFEngineFrontPage.pdf
deleted file mode 100644
index 26e35bee2f..0000000000
Binary files a/docs/reference/CFEngineFrontPage.pdf and /dev/null differ
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
deleted file mode 100644
index f2df697100..0000000000
--- a/docs/reference/Makefile.am
+++ /dev/null
@@ -1,65 +0,0 @@
-TEX_INCLUDEDIR=$(srcdir)/../tex-include
-
-.PRECIOUS: ../../cf-gendoc/cf-gendoc
-
-../../cf-gendoc/cf-gendoc:
- $(MAKE) -C ../../cf-gendoc $(AM_MAKEFLAGS) cf-gendoc
-
-cf3-Reference.texinfo: ../../cf-gendoc/cf-gendoc \
- generate_manual.cf \
- $(filter-out cf3-Reference.texinfo,$(wildcard *.texinfo)) \
- $(wildcard */*.texinfo)
- $(AM_V_GEN)../../cf-gendoc/cf-gendoc -i . -o $@
-
-%.html: %.texinfo
- $(AM_V_GEN)$(MAKEINFO) \
- $^ -o $@ \
- -I $(TEX_INCLUDEDIR) \
- --error-limit=0 \
- --html \
- --css-include=../guides/cfcomdoc.css \
- --no-split
-
-TEXI2PDFFLAGS = -I $(TEX_INCLUDEDIR) --batch $(if $(filter-out 0,$(V)),,--quiet)
-
-%.pdf: %.texinfo
- $(AM_V_GEN)$(srcdir)/../tools/texi2pdfclean $^ $(TEXI2PDF) -o $@ $(TEXI2PDFFLAGS)
-
-
-if HTML_DOCS
-html: cf3-Reference.html
-endif
-
-if PDF_DOCS
-pdf: cf3-Reference.pdf
-endif
-
-REFDIR=$(DESTDIR)/$(projdocdir)/reference
-
-dist-reference-%: %
- $(MKDIR_P) $(distdir)/$^
- $(INSTALL_DATA) $(subst *,\*,$(wildcard $(srcdir)/$^/*.texinfo)) $(distdir)/$^
-
-dist-reference: $(addprefix dist-reference-,bodyparts bundletypes control functions promises varcontexts vars)
- $(INSTALL_DATA) $(filter-out cf3-Reference.texinfo,$(wildcard $(srcdir)/*.texinfo)) $(distdir)
-
-if HTML_DOCS
-install-html: html
- $(MKDIR_P) $(REFDIR)/html
- $(INSTALL_DATA) cf3-Reference.html $(REFDIR)/html
- $(INSTALL_DATA) `$(srcdir)/../tools/extract-images cf3-Reference.texinfo | sort | uniq` $(REFDIR)/html
-endif
-
-if PDF_DOCS
-install-pdf: pdf
- $(MKDIR_P) $(REFDIR)/pdf
- $(INSTALL_DATA) cf3-Reference.pdf $(REFDIR)/pdf
-endif
-
-all: html pdf
-install-data-hook: install-html install-pdf
-dist-hook: dist-reference
-
-EXTRA_DIST = CFEngineFrontPage.pdf NewLogo.pdf filelogic.png generate_manual.cf
-
-CLEANFILES = cf3-Reference.html cf3-Reference.pdf cf3-Reference.texinfo
diff --git a/docs/reference/NewLogo.pdf b/docs/reference/NewLogo.pdf
deleted file mode 100644
index cb51106b1d..0000000000
Binary files a/docs/reference/NewLogo.pdf and /dev/null differ
diff --git a/docs/reference/bodyparts/abortbundleclasses_example.texinfo b/docs/reference/bodyparts/abortbundleclasses_example.texinfo
deleted file mode 100644
index f90d56bdd3..0000000000
--- a/docs/reference/bodyparts/abortbundleclasses_example.texinfo
+++ /dev/null
@@ -1,56 +0,0 @@
-
-This example shows how to use the feature to validate input to a method bundle.
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "testbundle" };
-version => "1.2.3";
-}
-
-###########################################
-
-body agent control
-
-{
-abortbundleclasses => { "invalid.*" };
-}
-
-###########################################
-
-bundle agent testbundle
-{
-vars:
-
- "userlist" slist => { "xyz", "mark", "jeang", "jonhenrik", "thomas", "eben" };
-
-methods:
-
- "any" usebundle => subtest("$(userlist)");
-
-}
-
-###########################################
-
-bundle agent subtest(user)
-
-{
-classes:
-
- "invalid" not => regcmp("[a-z]{4}","$(user)");
-
-reports:
-
- !invalid::
-
- "User name $(user) is valid at exactly 4 letters";
-
- # abortbundleclasses will prevent this from being evaluated
- invalid::
-
- "User name $(user) is invalid";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/abortbundleclasses_notes.texinfo b/docs/reference/bodyparts/abortbundleclasses_notes.texinfo
deleted file mode 100644
index 32aabca394..0000000000
--- a/docs/reference/bodyparts/abortbundleclasses_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-A list of regular expressions for classes, or class expressions that
-@code{cf-agent} will watch out for. If any of these classes becomes
-defined, it will cause the current bundle to be aborted. This may be
-used for validation, for example.
diff --git a/docs/reference/bodyparts/abortclasses_example.texinfo b/docs/reference/bodyparts/abortclasses_example.texinfo
deleted file mode 100644
index 7695ab502a..0000000000
--- a/docs/reference/bodyparts/abortclasses_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
- body agent control
-
- {
- abortclasses => { "danger.*", "should_not_continue" };
- }
-
-@end verbatim
diff --git a/docs/reference/bodyparts/abortclasses_notes.texinfo b/docs/reference/bodyparts/abortclasses_notes.texinfo
deleted file mode 100644
index 9dd158d160..0000000000
--- a/docs/reference/bodyparts/abortclasses_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-
-A list of class regular expressions that @code{cf-agent} will watch
-out for. If any matching class becomes defined, it will cause the
-current execution of @code{cf-agent} to be aborted. This may be used
-for validation, for example. To handle class expressions, simply create
-an alias for the expression with a single name.
diff --git a/docs/reference/bodyparts/aces_example.texinfo b/docs/reference/bodyparts/aces_example.texinfo
deleted file mode 100644
index b5c7d9585e..0000000000
--- a/docs/reference/bodyparts/aces_example.texinfo
+++ /dev/null
@@ -1,19 +0,0 @@
-
-@verbatim
-
-body acl template
-
-{
-acl_method => "overwrite";
-acl_type => "posix";
-acl_default => "access";
-
-aces => {
- "user:*:r(wwx),-r:allow",
- "group:*:+rw:allow",
- "mask:x:allow",
- "all:r"
- };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/aces_notes.texinfo b/docs/reference/bodyparts/aces_notes.texinfo
deleted file mode 100644
index 3ece242fc9..0000000000
--- a/docs/reference/bodyparts/aces_notes.texinfo
+++ /dev/null
@@ -1,87 +0,0 @@
-
-POSIX ACL are available in CFEngine Community starting with
-3.4.0. NTFS ACL are available with CFEngine Nova or above. Form of
-the permissions is:
-
-@cartouche
-@smallexample
- aces => @{
- "@var{user:uid:mode[:perm_type]}", ...,
- "@var{group:gid:mode[:perm_type]}", ...,
- "@var{all:mode[:perm_type]}"
- @};
-@end smallexample
-@end cartouche
-
-@itemize
-@item @code{user} indicates that the line applies to a user specified
- by the user identitfier @code{uid}. @code{mode} is the permission
- mode string.
-
-@item @code{group} indicates that the line applies to a group specified
- by the group identitfier @code{gid}. @code{mode} is the permission
- mode string.
-
-@item @code{all} indicates that the line applies to every
- user. @code{mode} is the permission mode string.
-
-@item @code{uid} is a valid user identifier for the system and
- cannot be empty. However, @code{uid} can be set to * as a synonym
- for the entity that owns the file system object (e.g. user:*:r).
-
-@item @code{gid} is a valid group identifier for the system and
- cannot be empty. However, in some acl types, @code{gid} can be set
- to * to indicate a special group (e.g. in POSIX this refers to the
- file group).
-
-@item @code{mode} is one or more strings
- @code{op}|@code{perms}|(@code{nperms}); a concatenation of @code{op},
- @code{perms} and optionally (@code{nperms}), see below, separated
- with commas (e.g. +rx,-w(s)). @code{mode} is parsed from left to
- right.
-@c TODO: include support for @code{fullaccess}, @code{noaccess},
-@c and @code{remove}
-
-@item @code{op} specifies the operation on any existing permissions,
- if the defined ACE already exists. @code{op} can be =, empty, + or
- -. = or empty sets the permissions to the ACE as stated, + adds and
- - removes the permissions from any existing ACE.
- @c TODO: what to do if + or - is used when ACE does not exist?
-
-@item @code{nperms} (optional) specifies file system specific
- (native) permissions. Only valid if @code{acl_type} is
- defined. @code{nperms} will only be enforced if the file object is
- stored on a file system supporting the acl type set in
- @code{acl_type} (e.g. @code{nperms} will be ignored if
- @code{acl_type:}@code{ntfs} and the object is stored on a file system
- not supporting ntfs ACLs). Valid values for @code{nperms} varies with
- different ACL types, and is defined in subsequent sections.
-
-@item @code{perm_type} (optional) can be set to either @code{allow} or
- @code{deny}, and defaults to @code{allow}. @code{deny} is only valid
- if @code{acl_type} is set to an ACL type that support deny
- permissions. A @code{deny} ACE will only be enforced if the file
- object is stored on a file system supporting the acl type set in
- @code{acl_type}.
-@end itemize
-
-@code{gperms} (generic permissions) is a concatenation of zero or more
-of the characters shown in the table below. If left empty,
-none of the permissions are set.
-@c TODO: Should be allowed to set no permissions (empty perms?)
-
-
-@multitable @columnfractions .05 .2 .30 .35
-@headitem Flag @tab Description @tab Semantics on file @tab Semantics on directory
-
-@item @code{r} @tab Read @tab Read data, permissions, attributes @tab Read
-directory contents, permissions, attributes
-@item @code{w} @tab Write @tab Write data @tab Create, delete, rename subobjects
-@item @code{x} @tab Execute @tab Execute file @tab Access subobjects
-@end multitable
-
-
-Note that the @code{r} permission is not neccessary to read an object's
-permissions and attributes in all file systems (e.g. in POSIX, having
-@code{x} on its containing directory is sufficient).
-
diff --git a/docs/reference/bodyparts/acl_directory_inherit_example.texinfo b/docs/reference/bodyparts/acl_directory_inherit_example.texinfo
deleted file mode 100644
index 2754639781..0000000000
--- a/docs/reference/bodyparts/acl_directory_inherit_example.texinfo
+++ /dev/null
@@ -1,19 +0,0 @@
-
-@verbatim
-
-body acl template
-
-{
-acl_method => "overwrite";
-acl_type => "posix";
-acl_default => "access";
-
-aces => {
- "user:*:rwx:allow",
- "group:*:+rw:allow",
- "mask:rx:allow",
- "all:r"
- };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/acl_directory_inherit_notes.texinfo b/docs/reference/bodyparts/acl_directory_inherit_notes.texinfo
deleted file mode 100644
index 117b31f07e..0000000000
--- a/docs/reference/bodyparts/acl_directory_inherit_notes.texinfo
+++ /dev/null
@@ -1,14 +0,0 @@
-
-
-
-Directories have ACLs associated with them, but they also have the
-ability to inherit an ACL to sub-objects created within them. POSIX
-calls the former ACL type "access ACL" and the latter "default ACL",
-and we will use the same terminology.
-
-The constraint @code{acl_default} gives control over the
-default ACL of directories. The default ACL can be left unchanged
-(@code{nochange}), empty (@code{clear}), or be explicitly specified
-(@code{specify}). In addition, the default ACL can be set equal to the
-directory's access ACL (@code{parent}). This has the effect that child
-objects of the directory gets the same access ACL as the directory.
diff --git a/docs/reference/bodyparts/acl_method_example.texinfo b/docs/reference/bodyparts/acl_method_example.texinfo
deleted file mode 100644
index 41fe4fefaa..0000000000
--- a/docs/reference/bodyparts/acl_method_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-body acl template
-
-{
-acl_method => "overwrite";
-acl_type => "posix";
-aces => { "user:*:rw:allow", "group:*:+r:allow", "all:"};
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/acl_method_notes.texinfo b/docs/reference/bodyparts/acl_method_notes.texinfo
deleted file mode 100644
index c58c522079..0000000000
--- a/docs/reference/bodyparts/acl_method_notes.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-
-When defining an ACL, we can either use an existing ACL as the
-starting point, or state all entries of the ACL. If we just care about
-one entry, say that the superuser has full access, the @code{method}
-constraint can be set to @code{append}, which is the default. This has
-the effect that all the existing ACL entries that are not mentioned
-will be left unchanged. On the other hand, if @code{method} is set to
-@code{overwrite}, the resulting ACL will only contain the mentioned
-entries. When doing this, it is important to check that all the
-required ACL entries are set, e.g. owning user, group and all in Posix
-ACLs.
diff --git a/docs/reference/bodyparts/acl_type_example.texinfo b/docs/reference/bodyparts/acl_type_example.texinfo
deleted file mode 100644
index de9d438554..0000000000
--- a/docs/reference/bodyparts/acl_type_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-body acl template
-
-{
-acl_type => "ntfs";
-aces => { "user:Administrator:rwx(po)", "user:Auditor:r(o)"};
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/acl_type_notes.texinfo b/docs/reference/bodyparts/acl_type_notes.texinfo
deleted file mode 100644
index 71960752cc..0000000000
--- a/docs/reference/bodyparts/acl_type_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-ACLs are supported on multiple platforms, which may have different
-sets of available permission flags. By using the constraint
-@code{acl_type}, we can specify which platform, or ACL API, we are
-targeting with the ACL. The default, @code{generic}, is designed to
-work on all supported platforms. However, if very specific permission
-flags are required, like ``Take Ownership'' on the NTFS platform, we
-must set @code{acl_type} to indicate the target platform. Currently,
-the supported values are @code{posix} and @code{ntfs}.
diff --git a/docs/reference/bodyparts/action_example.texinfo b/docs/reference/bodyparts/action_example.texinfo
deleted file mode 100644
index d76ae10bbc..0000000000
--- a/docs/reference/bodyparts/action_example.texinfo
+++ /dev/null
@@ -1,45 +0,0 @@
-
-The following example shows a simple use of transaction control,
-causing the promise to be verified as a separate background process.
-
-@verbatim
-
-body action background
-
-{
-action_policy => "warn";
-}
-
-@end verbatim
-In the following example, the action includes the definition of a class
-based on the actions that were performed.
-@verbatim
-bundle edit_line MarkNRoot
- {
- insert_lines:
-
- !pw_loaded::
-
- "/etc/passwd"
-
- insert_type => "file",
- action => defineclass("pw_loaded");
-
- delete_lines:
-
- pw_loaded::
-
- "(mark|root):.*" not_matching => "true";
-
- }
-
-########################################################
-
-body action defineclass(c)
-{
-promise_repaired => { "$(c)" };
-persist_time => "0";
-}
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/action_notes.texinfo b/docs/reference/bodyparts/action_notes.texinfo
deleted file mode 100644
index fb5b278bf3..0000000000
--- a/docs/reference/bodyparts/action_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-The @code{action} settings allow general transaction control to be
-implemented on promise verification. Action bodies place limits on how
-often to verify the promise and what classes to raise in the case that
-the promise can or cannot be kept.
-
diff --git a/docs/reference/bodyparts/action_policy_example.texinfo b/docs/reference/bodyparts/action_policy_example.texinfo
deleted file mode 100644
index cafb88fbcc..0000000000
--- a/docs/reference/bodyparts/action_policy_example.texinfo
+++ /dev/null
@@ -1,13 +0,0 @@
-
-The following example shows a simple use of transaction control,
-causing the promise to be verified as a separate background process.
-
-@verbatim
-
-body action background
-
-{
-action_policy => "warn";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/action_policy_notes.texinfo b/docs/reference/bodyparts/action_policy_notes.texinfo
deleted file mode 100644
index 576fa8cdc6..0000000000
--- a/docs/reference/bodyparts/action_policy_notes.texinfo
+++ /dev/null
@@ -1,77 +0,0 @@
-
-The @code{action} settings allow general transaction control to be
-implemented on promise verification. Action bodies place limits on how
-often to verify the promise and what classes to raise in the case that
-the promise can or cannot be kept.
-
-Note that actions can be added to sub-bundles like methods and editing
-bundles, and that promises within these do not inherit action settings
-at higher levels. Thus, in the following example there are two levels
-of action setting:
-
-@verbatim
-########################################################
-#
-# Warn if line matched
-#
-########################################################
-
-body common control
-
-{
-bundlesequence => { "testbundle" };
-}
-
-########################################################
-
-bundle agent testbundle
-
-{
-files:
-
- "/var/cfengine/inputs/.*"
-
- edit_line => DeleteLinesMatching(".*cfenvd.*"),
- action => WarnOnly;
-}
-
-########################################################
-
-bundle edit_line DeleteLinesMatching(regex)
- {
- delete_lines:
-
- "$(regex)" action => WarnOnly;
-
- }
-
-########################################################
-
-body action WarnOnly
-{
-action_policy => "warn";
-}
-@end verbatim
-
-The @code{action} setting for the @code{files} promise means that file
-edits will not be committed to disk, only warned about. This is a master-level
-promise that overrides anything that happens during the editing. The
-@code{action} setting for the edit bundle means that the internal
-memory modelling of the file will only warn about changes rather than
-committing them to the memory model. This makes little difference to the
-end result, but it means that CFEngine will report
-
-@smallexample
-Need to delete line - ... - but only a warning was promised
-@end smallexample
-
-@noindent Instead of
-
-@smallexample
-Deleting the prpomised line ...
-Need to save file - but only a warning was promised
-@end smallexample
-
-@noindent In either case, no changes will be made to the disk, but the messages
-given by @code{cf-agent} will differ.
-
diff --git a/docs/reference/bodyparts/addclasses_example.texinfo b/docs/reference/bodyparts/addclasses_example.texinfo
deleted file mode 100644
index 519676db11..0000000000
--- a/docs/reference/bodyparts/addclasses_example.texinfo
+++ /dev/null
@@ -1,16 +0,0 @@
-
-Add classes adds global, literal classes. The only predicates available during the control
-section are hard-classes.
-
-@verbatim
-
-any::
-
- addclasses => { "My_Organization" }
-
-solaris::
-
- addclasses => { "some_solaris_alive", "running_on_sunshine" };
-
-
-@end verbatim
diff --git a/docs/reference/bodyparts/addclasses_notes.texinfo b/docs/reference/bodyparts/addclasses_notes.texinfo
deleted file mode 100644
index 1125743da0..0000000000
--- a/docs/reference/bodyparts/addclasses_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-Another place to make global aliases for system hardclasses. Classes
-here are added unqeuivocally to the system. If classes are used to
-predicate definition, then they must be defined in terms of global
-hard classes.
-
diff --git a/docs/reference/bodyparts/admit_example.texinfo b/docs/reference/bodyparts/admit_example.texinfo
deleted file mode 100644
index 8b23da008f..0000000000
--- a/docs/reference/bodyparts/admit_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-access:
-
- "/home/mark/LapTop"
-
- admit => { "127.0.0.1", "192.168.0.1/24", ".*\.domain\.tld" };
-
-@end verbatim
diff --git a/docs/reference/bodyparts/admit_notes.texinfo b/docs/reference/bodyparts/admit_notes.texinfo
deleted file mode 100644
index 4d9006356c..0000000000
--- a/docs/reference/bodyparts/admit_notes.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-Admit promises grant access to file objects on the server. Arguments
-may be IP addresses or hostnames, provided DNS name resolution is
-active. In order to reach this stage, a client must first have passed
-all of the standard connection tests in the control body.
-
-The lists may contain network addresses in CIDR notation or regular
-expressions to match the IP address or name of the connecting host.
diff --git a/docs/reference/bodyparts/agent_expireafter_example.texinfo b/docs/reference/bodyparts/agent_expireafter_example.texinfo
deleted file mode 100644
index 80e8bb49e7..0000000000
--- a/docs/reference/bodyparts/agent_expireafter_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body executor control
-{
-agent_expireafter => "120";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/agent_expireafter_notes.texinfo b/docs/reference/bodyparts/agent_expireafter_notes.texinfo
deleted file mode 100644
index 2fee7099c6..0000000000
--- a/docs/reference/bodyparts/agent_expireafter_notes.texinfo
+++ /dev/null
@@ -1,19 +0,0 @@
-@noindent Sets a maximum time on any run of the command in @code{exec_command}.
-If no data is received from the pipe opened to the process created with
-@code{exec_command} after the time has elapsed, the process gets killed.
-
-@noindent Note that if you have long-running jobs, they may get killed
-with this setting. Therefore, you should ensure it is higher than any run of
-@code{cf-agent} that you want to leave alone. Alternatively, you can make
-your jobs output something to STDOUT at least as often as this threshold.
-This will reset the timer.
-
-@noindent The setting will effectively allow you to set a threshold on the
-number of simultaneous agents that are running. For example, if you set it to
-@code{120} and you are using a 5-minute agent schedule, a maximum of
-120 / 5 = 24 agents should be enforced.
-
-@noindent @b{Default value}:@*
-@*
-
-The default value is 10080 minutes (one week).
diff --git a/docs/reference/bodyparts/agentaccess_example.texinfo b/docs/reference/bodyparts/agentaccess_example.texinfo
deleted file mode 100644
index 249e379b6b..0000000000
--- a/docs/reference/bodyparts/agentaccess_example.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@verbatim
-
- agentaccess => { "mark", "root", "sudo" };
-
-@end verbatim
diff --git a/docs/reference/bodyparts/agentaccess_notes.texinfo b/docs/reference/bodyparts/agentaccess_notes.texinfo
deleted file mode 100644
index f46fa6516e..0000000000
--- a/docs/reference/bodyparts/agentaccess_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-A list of user names that will be allowed to attempt execution of the
-current configuration. This is mainly a sanity check rather than a
-security measure.
-
diff --git a/docs/reference/bodyparts/agentfacility_example.texinfo b/docs/reference/bodyparts/agentfacility_example.texinfo
deleted file mode 100644
index e8f1645891..0000000000
--- a/docs/reference/bodyparts/agentfacility_example.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@verbatim
-
-agentfacility => "LOG_USER";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/agentfacility_notes.texinfo b/docs/reference/bodyparts/agentfacility_notes.texinfo
deleted file mode 100644
index 61cafc466a..0000000000
--- a/docs/reference/bodyparts/agentfacility_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Sets the agent's syslog facility level. See the manual pages for
-syslog. This is ignored on Windows, as CFEngine Nova creates event logs.
-
diff --git a/docs/reference/bodyparts/allclassesreport_example.texinfo b/docs/reference/bodyparts/allclassesreport_example.texinfo
deleted file mode 100644
index 1655d4e996..0000000000
--- a/docs/reference/bodyparts/allclassesreport_example.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-@verbatim
-body agent control
-{
-allclassesreport => "true";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/allclassesreport_notes.texinfo b/docs/reference/bodyparts/allclassesreport_notes.texinfo
deleted file mode 100644
index 4822e943ae..0000000000
--- a/docs/reference/bodyparts/allclassesreport_notes.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@i{History}: Was introduced in 3.2.0, Nova 2.1.0 (2011)
-
-
-This option determines whether state/allclasses.txt file is written to
-disk during agent execution. This functionality is retained only for
-CFEngine 2 compatibility as more convenient facilities exist in
-CFEngine 3 language to achieve similar results.
-
-This option is turned off by default.
diff --git a/docs/reference/bodyparts/allow_blank_fields_example.texinfo b/docs/reference/bodyparts/allow_blank_fields_example.texinfo
deleted file mode 100644
index 5a8000d815..0000000000
--- a/docs/reference/bodyparts/allow_blank_fields_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body edit_field example
-{
-# ...
-allow_blank_fields => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/allow_blank_fields_notes.texinfo b/docs/reference/bodyparts/allow_blank_fields_notes.texinfo
deleted file mode 100644
index 8f95f21da2..0000000000
--- a/docs/reference/bodyparts/allow_blank_fields_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-
-When editing a file using the field or column model, blank fields, especially
-at the start and end are generally discarded. If this is set to true, CFEngine
-will retain the blank fields and print the appropriate number of field separators.
-
-
diff --git a/docs/reference/bodyparts/allowallconnects_example.texinfo b/docs/reference/bodyparts/allowallconnects_example.texinfo
deleted file mode 100644
index 9760c54319..0000000000
--- a/docs/reference/bodyparts/allowallconnects_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-allowallconnects => {
- "127.0.0.1",
- "::1",
- "200\.1\.10\..*",
- "host\.domain\.tld",
- "host[0-9]+\.domain\.com"
- };
-
-@end verbatim
diff --git a/docs/reference/bodyparts/allowallconnects_notes.texinfo b/docs/reference/bodyparts/allowallconnects_notes.texinfo
deleted file mode 100644
index 398181f320..0000000000
--- a/docs/reference/bodyparts/allowallconnects_notes.texinfo
+++ /dev/null
@@ -1,16 +0,0 @@
-
-This list of regular expressions matches hosts that are allowed to
-connect an umlimited number of times up to the maximum connection
-limit. Without this, a host may only connect once (which is a very
-strong constraint, as the host must wait for the TCP FIN_WAIT to
-expire before reconnection can be attempted).
-
-In CFEngine 2 this corresponds to @code{AllowMultipleConnectionsFrom}.
-
-Note that @code{127.0.0.1} is a regular expression (i.e., ``127 any character
-0 any character 0 any character 1''), but this will only match the IP address
-@code{127.0.0.1}. Take care with IP addresses and domain names, as the
-hostname regular expression @code{www.domain.com} will potentially match more
-than one hostname (e.g., @code{wwwxdomain.com}, in addition to the desired
-hostname @code{www.domain.com}).
-
diff --git a/docs/reference/bodyparts/allowconnects_example.texinfo b/docs/reference/bodyparts/allowconnects_example.texinfo
deleted file mode 100644
index 059ccbd03e..0000000000
--- a/docs/reference/bodyparts/allowconnects_example.texinfo
+++ /dev/null
@@ -1,13 +0,0 @@
-
-@verbatim
-
-allowconnects => {
- "127.0.0.1",
- "::1",
- "200\.1\.10\..*",
- "host\.domain\.tld",
- "host[0-9]+\.domain\.com"
- };
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/allowconnects_notes.texinfo b/docs/reference/bodyparts/allowconnects_notes.texinfo
deleted file mode 100644
index 0d53e03253..0000000000
--- a/docs/reference/bodyparts/allowconnects_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-If a client's identity matches an entry in this list it is granted to
-permission to send data to the server port. Clients who are not in this
-list may not connect or send data to the server.
-
-See also the warning about regular expressions in @code{allowallconnects}.
diff --git a/docs/reference/bodyparts/allowusers_example.texinfo b/docs/reference/bodyparts/allowusers_example.texinfo
deleted file mode 100644
index 2bb13eeead..0000000000
--- a/docs/reference/bodyparts/allowusers_example.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-
-@verbatim
-
-allowusers => { "cfengine", "root" };
-
-@end verbatim
diff --git a/docs/reference/bodyparts/allowusers_notes.texinfo b/docs/reference/bodyparts/allowusers_notes.texinfo
deleted file mode 100644
index 05550c1277..0000000000
--- a/docs/reference/bodyparts/allowusers_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-The usernames listed in this list are those asserted as public key
-identities during client-server connections. These may or may not
-correspond to system identities on the server-side system.
-
diff --git a/docs/reference/bodyparts/alwaysvalidate_example.texinfo b/docs/reference/bodyparts/alwaysvalidate_example.texinfo
deleted file mode 100644
index 8a6cb42a92..0000000000
--- a/docs/reference/bodyparts/alwaysvalidate_example.texinfo
+++ /dev/null
@@ -1,13 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-Min00_05::
-
- # revalidate once per hour, regardless of change in configuration
-
- alwaysvalidate => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/alwaysvalidate_notes.texinfo b/docs/reference/bodyparts/alwaysvalidate_notes.texinfo
deleted file mode 100644
index 761af2b453..0000000000
--- a/docs/reference/bodyparts/alwaysvalidate_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-@i{History}: Was introduced in version 3.1.2,Nova 2.0.1 (2010)
-
-The agents @code{cf-agent}, and @code{cfserverd} etc can run @code{cf-promises} to validate
-inputs before attempting to execute a configuration. As of version 3.1.2 core, this only
-happens if the configuration file has changed to save CPU cycles. When this attribute is set,
-@code{cf-agent} will force a revalidation of the input.
diff --git a/docs/reference/bodyparts/and_example.texinfo b/docs/reference/bodyparts/and_example.texinfo
deleted file mode 100644
index fffad2e7dd..0000000000
--- a/docs/reference/bodyparts/and_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-@verbatim
-
-classes:
-
- "compound_class" and => { classmatch("host[0-9].*"), "Monday", "Hr02" };
-
-@end verbatim
diff --git a/docs/reference/bodyparts/and_notes.texinfo b/docs/reference/bodyparts/and_notes.texinfo
deleted file mode 100644
index 01ca3a3197..0000000000
--- a/docs/reference/bodyparts/and_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-If an expression contains a mixture of different object types that
-need to be ANDed together, this list form is more convenient than
-providing an expression. If all of the class expressions listed in the
-RHS match, then the class on the LHS is defined.
diff --git a/docs/reference/bodyparts/args_example.texinfo b/docs/reference/bodyparts/args_example.texinfo
deleted file mode 100644
index f50d618f19..0000000000
--- a/docs/reference/bodyparts/args_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-commands:
-
- "/bin/echo one"
-
- args => "two three";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/args_notes.texinfo b/docs/reference/bodyparts/args_notes.texinfo
deleted file mode 100644
index 86f045e046..0000000000
--- a/docs/reference/bodyparts/args_notes.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-Sometimes it is convenient to separate the arguments to a command from
-the command itself. The final arguments are the concatenation with one
-space. So in the example above the command would be
-
-@verbatim
-
- /bin/echo one two three
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/associates_example.texinfo b/docs/reference/bodyparts/associates_example.texinfo
deleted file mode 100644
index 967b064fa1..0000000000
--- a/docs/reference/bodyparts/associates_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-
-@verbatim
-
-body association example(literal,scalar,list)
-
-{
-#...
-associates => { "literal", $(scalar), @(list)};
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/associates_notes.texinfo b/docs/reference/bodyparts/associates_notes.texinfo
deleted file mode 100644
index c24badf443..0000000000
--- a/docs/reference/bodyparts/associates_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-An element of an association which is a list of topics to which the
-current topic is associated.
diff --git a/docs/reference/bodyparts/atime_example.texinfo b/docs/reference/bodyparts/atime_example.texinfo
deleted file mode 100644
index 41d12a7942..0000000000
--- a/docs/reference/bodyparts/atime_example.texinfo
+++ /dev/null
@@ -1,20 +0,0 @@
-
-@verbatim
-body file_select used_recently
-{
-
-# files accessed within the last hour
-atime => irange(ago(0,0,0,1,0,0),now);
-file_result => "atime";
-}
-
-
-body file_select not_used_much
-
-{
-# files not accessed since 00:00 1st Jan 2000 (in the local timezime)
-atime => irange(on(2000,1,1,0,0,0),now);
-file_result => "!atime";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/atime_notes.texinfo b/docs/reference/bodyparts/atime_notes.texinfo
deleted file mode 100644
index 882112c770..0000000000
--- a/docs/reference/bodyparts/atime_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-A range of times during which a file was accessed can be specified in
-a @code{file_select} body. (Like file filters in CFEngine 2.)
-
diff --git a/docs/reference/bodyparts/attribute_value_example.texinfo b/docs/reference/bodyparts/attribute_value_example.texinfo
deleted file mode 100644
index 0e1ec83cdc..0000000000
--- a/docs/reference/bodyparts/attribute_value_example.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-@verbatim
-
-body attribute_value example(s)
-{
-attribute_value => "$(s)";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/attribute_value_notes.texinfo b/docs/reference/bodyparts/attribute_value_notes.texinfo
deleted file mode 100644
index e69de29bb2..0000000000
diff --git a/docs/reference/bodyparts/audit_example.texinfo b/docs/reference/bodyparts/audit_example.texinfo
deleted file mode 100644
index a19730ee28..0000000000
--- a/docs/reference/bodyparts/audit_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-body action example
-{
-# ...
-
-audit => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/audit_notes.texinfo b/docs/reference/bodyparts/audit_notes.texinfo
deleted file mode 100644
index 03b7e13738..0000000000
--- a/docs/reference/bodyparts/audit_notes.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-
-If this is set, CFEngine will perform auditing on this specific
-promise. This means that all details surrounding the verification of
-the current promise will be recorded in the audit database. The
-database may be inspected with @code{cf-report}, or @code{cfshow} in
-CFEngine 2.
-
diff --git a/docs/reference/bodyparts/auditing_example.texinfo b/docs/reference/bodyparts/auditing_example.texinfo
deleted file mode 100644
index e337dd7773..0000000000
--- a/docs/reference/bodyparts/auditing_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-auditing => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/auditing_notes.texinfo b/docs/reference/bodyparts/auditing_notes.texinfo
deleted file mode 100644
index cb46ab8b3a..0000000000
--- a/docs/reference/bodyparts/auditing_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-
-If this is set, CFEngine will perform auditing on promises in the
-current configuration. This means that all details surrounding the
-verification of the current promise will be recorded in the audit
-database. The database may be inspected with @code{cf-report}, or
-@code{cfshow} in CFEngine 2.
diff --git a/docs/reference/bodyparts/authorize_example.texinfo b/docs/reference/bodyparts/authorize_example.texinfo
deleted file mode 100644
index a76c177167..0000000000
--- a/docs/reference/bodyparts/authorize_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-
-@verbatim
-
-roles:
-
- ".*" authorize => { "mark", "marks_friend" };
-
-@end verbatim
diff --git a/docs/reference/bodyparts/authorize_notes.texinfo b/docs/reference/bodyparts/authorize_notes.texinfo
deleted file mode 100644
index f76bb20c45..0000000000
--- a/docs/reference/bodyparts/authorize_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-Part of Role Based Access Control (RBAC) in CFEngine. The users listed
-in this section are granted access to set certain classes by using the
-remote @code{cf-runagent}. The user-names will refer to public key
-identities already trusted on the system.
diff --git a/docs/reference/bodyparts/background_children_example.texinfo b/docs/reference/bodyparts/background_children_example.texinfo
deleted file mode 100644
index 4aa17805c5..0000000000
--- a/docs/reference/bodyparts/background_children_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body runagent control
-{
-background_children => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/background_children_notes.texinfo b/docs/reference/bodyparts/background_children_notes.texinfo
deleted file mode 100644
index 88b1de1877..0000000000
--- a/docs/reference/bodyparts/background_children_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-Causes the runagent to attempt parallelized connections to the servers.
diff --git a/docs/reference/bodyparts/background_example.texinfo b/docs/reference/bodyparts/background_example.texinfo
deleted file mode 100644
index 05977fe86c..0000000000
--- a/docs/reference/bodyparts/background_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body action example
-{
-background => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/background_notes.texinfo b/docs/reference/bodyparts/background_notes.texinfo
deleted file mode 100644
index d23bed88a6..0000000000
--- a/docs/reference/bodyparts/background_notes.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-If possible, perform the verification of the current promise in the background.
-This is advantageous only if the verification might take a significant
-amount of time, e.g. in remote copying of filesystem/disk scans.
-
-On the windows version of CFEngine Nova, this can be useful if we
-don't want to wait for a particular command to finish execution before
-checking the next promise. This is particular for the windows platform
-because there is no way that a program can start itself in the
-background here (i.e. fork off a child process). However, file
-operations can not be performed in the background on windows.
diff --git a/docs/reference/bodyparts/before_after_example.texinfo b/docs/reference/bodyparts/before_after_example.texinfo
deleted file mode 100644
index 7f618545b1..0000000000
--- a/docs/reference/bodyparts/before_after_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-body location append
-
-{
-#...
-before_after => "before";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/before_after_notes.texinfo b/docs/reference/bodyparts/before_after_notes.texinfo
deleted file mode 100644
index 58115da65f..0000000000
--- a/docs/reference/bodyparts/before_after_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Determines whether an edit will occur before or after the currently
-matched line.
diff --git a/docs/reference/bodyparts/binarypaddingchar_example.texinfo b/docs/reference/bodyparts/binarypaddingchar_example.texinfo
deleted file mode 100644
index 10ca46b487..0000000000
--- a/docs/reference/bodyparts/binarypaddingchar_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-binarypaddingchar => "#";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/binarypaddingchar_notes.texinfo b/docs/reference/bodyparts/binarypaddingchar_notes.texinfo
deleted file mode 100644
index 18efaea6af..0000000000
--- a/docs/reference/bodyparts/binarypaddingchar_notes.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-When editing binary files, it can be dangerous to replace a text
-string with one that is longer or shorter as byte references and jumps
-would be destroyed. CFEngine will therefore not allow replacements that
-are larger in size than the original, but shorter strings can be padded
-out to the same length.
-
-@noindent @b{Default value}:@*
-
-The @code{binarypaddingchar} defaults to the empty string (i.e., no padding)
diff --git a/docs/reference/bodyparts/bindtointerface_example.texinfo b/docs/reference/bodyparts/bindtointerface_example.texinfo
deleted file mode 100644
index 00444f240e..0000000000
--- a/docs/reference/bodyparts/bindtointerface_example.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-
-@verbatim
-
-bindtointerface => "192.168.1.1";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/bindtointerface_notes.texinfo b/docs/reference/bodyparts/bindtointerface_notes.texinfo
deleted file mode 100644
index 432b17cc21..0000000000
--- a/docs/reference/bodyparts/bindtointerface_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-On multi-homed hosts, the server and client can bind
-to a specific interface for server traffic. The IP address
-of the interface must be given as the argument, not the device name.
diff --git a/docs/reference/bodyparts/bsdflags_example.texinfo b/docs/reference/bodyparts/bsdflags_example.texinfo
deleted file mode 100644
index 1052df74a3..0000000000
--- a/docs/reference/bodyparts/bsdflags_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-body perms example
-
-{
-bsdflags => { "uappnd","uchg","uunlnk","nodump",
- "opaque","sappnd","schg","sunlnk" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/bsdflags_notes.texinfo b/docs/reference/bodyparts/bsdflags_notes.texinfo
deleted file mode 100644
index 7f3c63382f..0000000000
--- a/docs/reference/bodyparts/bsdflags_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-The BSD Unices (FreeBSD, OpenBSD, NetBSD) and MacOSX have additional
-filesystem flags which can be set. Refer to the BSD @code{chflags}
-documentation for this.
diff --git a/docs/reference/bodyparts/build_xpath_example.texinfo b/docs/reference/bodyparts/build_xpath_example.texinfo
deleted file mode 100644
index 1bde002bd5..0000000000
--- a/docs/reference/bodyparts/build_xpath_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body build_xpath example(s)
- {
- build_xpath => "$(s)";
- }
-
-@end verbatim
diff --git a/docs/reference/bodyparts/build_xpath_notes.texinfo b/docs/reference/bodyparts/build_xpath_notes.texinfo
deleted file mode 100644
index ac35b3fbde..0000000000
--- a/docs/reference/bodyparts/build_xpath_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-Please note that when @code{build_xpath} is defined as an attribute, within
-an @code{edit_xml} promise body, the tree described by the specified XPath will
-be verified and built BEFORE other @code{edit_xml} promises within same promise
-body. Therefore, the file will not be empty during the execution of such promises.
diff --git a/docs/reference/bodyparts/bundle_return_value_index_example.texinfo b/docs/reference/bodyparts/bundle_return_value_index_example.texinfo
deleted file mode 100644
index 515a0f3bb4..0000000000
--- a/docs/reference/bodyparts/bundle_return_value_index_example.texinfo
+++ /dev/null
@@ -1,40 +0,0 @@
-
-@verbatim
-body common control
-{
-bundlesequence => { "test" };
-}
-
-
-bundle agent test
-{
-methods:
-
- "any" usebundle => child,
- useresult => "my_return_var";
-
-
-reports:
-
- cfengine_3::
-
- "My return was: \"$(my_return_var[1])\" and \"$(my_return_var[2])\"";
-
-}
-
-bundle agent child
-{
-reports:
-
- cfengine_3::
-
- # Map these indices into the useresult namespace
-
- "this is a return value"
- bundle_return_value_index => "1";
-
- "this is another return value"
- bundle_return_value_index => "2";
-
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/bundle_return_value_index_notes.texinfo b/docs/reference/bodyparts/bundle_return_value_index_notes.texinfo
deleted file mode 100644
index c5639439c0..0000000000
--- a/docs/reference/bodyparts/bundle_return_value_index_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-@i{History}: Was introduced in 3.4.0 (2012)
-
-It is currently believed that only scalar return values make sense, hence
-return values are limited to scalars.
diff --git a/docs/reference/bodyparts/bundlesequence_example.texinfo b/docs/reference/bodyparts/bundlesequence_example.texinfo
deleted file mode 100644
index 473eb67ae7..0000000000
--- a/docs/reference/bodyparts/bundlesequence_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-body common control
-
-{
-bundlesequence => {
- update("policy_host.domain.tld"),
- "main",
- "cfengine2"
- };
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/bundlesequence_notes.texinfo b/docs/reference/bodyparts/bundlesequence_notes.texinfo
deleted file mode 100644
index fcba2418e5..0000000000
--- a/docs/reference/bodyparts/bundlesequence_notes.texinfo
+++ /dev/null
@@ -1,57 +0,0 @@
-
-The @code{bundlesequence} determines which of the compiled bundles
-will be executed and in what order they will be executed. The list
-refers to the names of bundles (which might be parameterized
-function-like objects).
-
-The order in which you execute bundles can affect the outcome of your
-promises. In general you should always define variables before you use them.
-
-The @code{bundlesequence} is like a genetic makeup of a machine. The bundles
-act like characteristics of the systems. If you want different systems to have
-different bundlesequences, distinguish them with classes:
-
-@verbatim
-webservers::
-
- bundlesequence => { "main", "web" };
-
-others::
-
- bundlesequence => { "main", "otherstuff" };
-
-@end verbatim
-
-If you want to add a basic common sequence to all sequences, then use
-global variable lists to do this:
-
-@verbatim
-body common control
-{
-webservers::
-
- bundlesequence => { @(g.bs), "web" };
-
-others::
-
- bundlesequence => { @(g.bs), "otherstuff" };
-
-}
-
-bundle common g
-{
-vars:
-
- "bs" slist => { "main", "basic_stuff" };
-}
-
-@end verbatim
-
-@noindent @b{Default value}:@*
-@*
-
-There is no default value for @code{bundlesequence}, and the absence of a
-@code{bundlesequence} will cause a compilation error. A bundlesequence may
-also be specified using the @code{-b} or @code{--bundlesequence} command line
-option.
-
diff --git a/docs/reference/bodyparts/call_collect_interval_example.texinfo b/docs/reference/bodyparts/call_collect_interval_example.texinfo
deleted file mode 100644
index 7714c02bb8..0000000000
--- a/docs/reference/bodyparts/call_collect_interval_example.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@verbatim
-
-call_collect_interval => "5";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/call_collect_interval_notes.texinfo b/docs/reference/bodyparts/call_collect_interval_notes.texinfo
deleted file mode 100644
index d930543e0d..0000000000
--- a/docs/reference/bodyparts/call_collect_interval_notes.texinfo
+++ /dev/null
@@ -1,89 +0,0 @@
-
-@i{History}: Was introduced in 3.4.0, Enterprise 3.0.0 (2012)
-
-If option time is set, it causes the server daemon to peer with a policy
-hub by attempting a connection at regular intervals of the value of the
-parameter in minutes.
-
-This feature is designed to allow Enterprise report collection from
-hosts that are not directly addressable from a hub data-aggregation
-process. For example, if some of the clients of a policy hub are
-behind a network address translator then the hub is not able to open a
-channel to address them directly. The effect is to place a `collect
-call' with the policy hub.
-
-If this option is set, the client's cf-serverd will `peer' with the
-server daemon on a policy hub. This means that, cf-serverd on an
-unreachable (e.g. NATed) host will attempt to report in to the
-cf-serverd on its assigned policy hub and offer it a short time window
-in which to download reports over the established connection. The
-effect is to establish a temporary secure tunnel between hosts,
-initiated from the satellite host end. The connection is made in such
-a way that host autonomy is not compromised. Either hub may refuse or
-decline to play their role at any time, in the usual way (avoiding DOS
-attacks). Normal access controls must be set for communication in both
-directions.
-
-Collect calling cannot be as efficient as data collection by the
-cf-hub, as the hub is not able to load balance. Hosts that use this
-approach should exclude themselves from the cf-hub data collection.
-
-The sequence of events is this:
-
-@itemize
-@item Satellite cf-serverd connects to its registered policy hub
-@item The satellite indentifies itself to authentication and access control
-and sends a collect-call `pull' request to the hub
-@item The hub might honour this, if the access control grants access.
-@item If access is granted, the hub has @code{collect_window} seconds
-to initiate a query to the satellite for its reports.
-@item The policy hub indentifies itself to authentication and access control
-and sends a query request to the hub to collect the reports.
-@item When finished the satellite closes the tunnel.
-@end itemize
-
-The full configuration would look something like this
-@verbatim
-
-#########################################################
-# Server config
-#########################################################
-
-body server control
-
-{
-allowconnects => { "10.10.10" , "::1" };
-allowallconnects => { "10.10.10" , "::1" };
-trustkeysfrom => { "10.10.10" , "::1" };
-
-call_collect_interval => "5";
-}
-
-#########################################################
-
-bundle server access_rules()
-
-{
-access:
-
- policy_hub::
-
- "collect_calls"
- resource_type => "query",
- admit => { "10.10.10" }; # the apparent NAT address of the satellite
-
- satellite_hosts::
-
- "delta"
- comment => "Grant access to cfengine hub to collect report deltas",
- resource_type => "query",
- admit => { "policy_hub" };
-
- "full"
- comment => "Grant access to cfengine hub to collect full report dump",
- resource_type => "query",
- admit => { "policy_hub" };
-}
-
-
-@end verbatim
diff --git a/docs/reference/bodyparts/cancel_kept_example.texinfo b/docs/reference/bodyparts/cancel_kept_example.texinfo
deleted file mode 100644
index 28f2f473bb..0000000000
--- a/docs/reference/bodyparts/cancel_kept_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body classes example
-{
-cancel_kept => { "success", "kaplah" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/cancel_kept_notes.texinfo b/docs/reference/bodyparts/cancel_kept_notes.texinfo
deleted file mode 100644
index 617c8ca37f..0000000000
--- a/docs/reference/bodyparts/cancel_kept_notes.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-If the promise was already kept and nothing was done, cancel (undefine) any of
-the listed classes so that they are no longer defined.
-
-Note that any strings passed to this list are automatically
-canonified, so it is unecessary to call a canonify function on such inputs.
-
-@b{History}: This attribute was introduced in CFEngine version 3.0.4 (2010)
diff --git a/docs/reference/bodyparts/cancel_notkept_example.texinfo b/docs/reference/bodyparts/cancel_notkept_example.texinfo
deleted file mode 100644
index c79671fbd2..0000000000
--- a/docs/reference/bodyparts/cancel_notkept_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body classes example
-{
-cancel_notkept => { "failure" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/cancel_notkept_notes.texinfo b/docs/reference/bodyparts/cancel_notkept_notes.texinfo
deleted file mode 100644
index ad6086232c..0000000000
--- a/docs/reference/bodyparts/cancel_notkept_notes.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-If the promise was not kept but nothing could be done, cancel (undefine)
-any of the listed classes so that they are no longer defined.
-
-Note that any strings passed to this list are automatically
-canonified, so it is unecessary to call a canonify function on such inputs.
-
-@b{History}: This attribute was introduced in CFEngine version 3.0.4 (2010)
diff --git a/docs/reference/bodyparts/cancel_repaired_example.texinfo b/docs/reference/bodyparts/cancel_repaired_example.texinfo
deleted file mode 100644
index fcd791683d..0000000000
--- a/docs/reference/bodyparts/cancel_repaired_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body classes example
-{
-cancel_repaired => { "change_happened" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/cancel_repaired_notes.texinfo b/docs/reference/bodyparts/cancel_repaired_notes.texinfo
deleted file mode 100644
index 5c7a168188..0000000000
--- a/docs/reference/bodyparts/cancel_repaired_notes.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-If the promise was repaired and changes were made to the system,
-cancel (undefine) any of the listed classes so that they are no longer defined.
-
-Note that any strings passed to this list are automatically
-canonified, so it is unecessary to call a canonify function on such inputs.
-
-@b{History}: This attribute was introduced in CFEngine version 3.0.4 (2010)
diff --git a/docs/reference/bodyparts/cfruncommand_example.texinfo b/docs/reference/bodyparts/cfruncommand_example.texinfo
deleted file mode 100644
index 420def7ad7..0000000000
--- a/docs/reference/bodyparts/cfruncommand_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-body server control
-
-{
-cfruncommand => "/var/cfengine/bin/cf-agent";
-}
-
-
-@end verbatim
diff --git a/docs/reference/bodyparts/cfruncommand_notes.texinfo b/docs/reference/bodyparts/cfruncommand_notes.texinfo
deleted file mode 100644
index 83147fcc52..0000000000
--- a/docs/reference/bodyparts/cfruncommand_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-It is normal for this to point to the location of @code{cf-agent} but
-it could also point to the @code{cf-execd}, or even another program or
-shell command at your own risk.
diff --git a/docs/reference/bodyparts/chdir_example.texinfo b/docs/reference/bodyparts/chdir_example.texinfo
deleted file mode 100644
index 371641de8e..0000000000
--- a/docs/reference/bodyparts/chdir_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body contain example
-
-{
-chdir => "/containment/directory";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/chdir_notes.texinfo b/docs/reference/bodyparts/chdir_notes.texinfo
deleted file mode 100644
index 43d273fe7f..0000000000
--- a/docs/reference/bodyparts/chdir_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-This command has the effect of placing the running command into a current working
-directory equal to the parameter given, i.e. it works like the @samp{cd} shell command.
diff --git a/docs/reference/bodyparts/check_foreign_example.texinfo b/docs/reference/bodyparts/check_foreign_example.texinfo
deleted file mode 100644
index 632f562818..0000000000
--- a/docs/reference/bodyparts/check_foreign_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-body volume example
-
-{
-#..
-check_foreign => "false";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/check_foreign_notes.texinfo b/docs/reference/bodyparts/check_foreign_notes.texinfo
deleted file mode 100644
index 12780bb4e2..0000000000
--- a/docs/reference/bodyparts/check_foreign_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-CFEngine will not normally perform sanity checks on filesystems which
-are not local to the host. If @code{true} it will ignore a partition's
-network location and ask the current host to verify storage located
-physically on other systems.
diff --git a/docs/reference/bodyparts/check_root_example.texinfo b/docs/reference/bodyparts/check_root_example.texinfo
deleted file mode 100644
index ba7d82537e..0000000000
--- a/docs/reference/bodyparts/check_root_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body copy_from example
-{
-check_root => "true";
-}
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/check_root_notes.texinfo b/docs/reference/bodyparts/check_root_notes.texinfo
deleted file mode 100644
index 49bfd864b1..0000000000
--- a/docs/reference/bodyparts/check_root_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-When copying files recursively (by depth search), this flag determines
-whether the permissions of the root directory should be set from the
-root of the source. The default is to check only copied file objects
-and subdirectories within this root (false).
diff --git a/docs/reference/bodyparts/checksum_alert_time_example.texinfo b/docs/reference/bodyparts/checksum_alert_time_example.texinfo
deleted file mode 100644
index 55bbd391ad..0000000000
--- a/docs/reference/bodyparts/checksum_alert_time_example.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-@verbatim
-body agent control
-{
-checksum_alert_time => "30";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/checksum_alert_time_notes.texinfo b/docs/reference/bodyparts/checksum_alert_time_notes.texinfo
deleted file mode 100644
index c8b202879d..0000000000
--- a/docs/reference/bodyparts/checksum_alert_time_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-When checksum changes trigger an alert, this is registered as a persistent class.
-This value determines the longevity of that class.
diff --git a/docs/reference/bodyparts/childlibpath_example.texinfo b/docs/reference/bodyparts/childlibpath_example.texinfo
deleted file mode 100644
index 8e2a7cd9a9..0000000000
--- a/docs/reference/bodyparts/childlibpath_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-childlibpath => "/usr/local/lib:/usr/local/gnu/lib";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/childlibpath_notes.texinfo b/docs/reference/bodyparts/childlibpath_notes.texinfo
deleted file mode 100644
index b85ffe56bf..0000000000
--- a/docs/reference/bodyparts/childlibpath_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-This string may be used to set the internal @code{LD_LIBRARY_PATH}
-environment of the agent.
diff --git a/docs/reference/bodyparts/chroot_example.texinfo b/docs/reference/bodyparts/chroot_example.texinfo
deleted file mode 100644
index 41f9de40b6..0000000000
--- a/docs/reference/bodyparts/chroot_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body contain example
-
-{
-chroot => "/private/path";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/chroot_notes.texinfo b/docs/reference/bodyparts/chroot_notes.texinfo
deleted file mode 100644
index ee9b474765..0000000000
--- a/docs/reference/bodyparts/chroot_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Sets the path of the directory that will be experienced as the top-most
-root directory for the process. In security parlance, this creates
-a `sandbox' for the process. Windows does not support this feature.
diff --git a/docs/reference/bodyparts/collapse_destination_dir_example.texinfo b/docs/reference/bodyparts/collapse_destination_dir_example.texinfo
deleted file mode 100644
index ad3e891e92..0000000000
--- a/docs/reference/bodyparts/collapse_destination_dir_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-body copy_from mycopy(from,server)
-
-{
-source => "$(from)";
-servers => { "$(server)" };
-collapse_destination_dir => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/collapse_destination_dir_notes.texinfo b/docs/reference/bodyparts/collapse_destination_dir_notes.texinfo
deleted file mode 100644
index 55a63c1f3a..0000000000
--- a/docs/reference/bodyparts/collapse_destination_dir_notes.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-Under normal operations, recursive copies cause CFEngine to track subdirectories
-of files. So, for instance, if we copy recurively from @file{src} to @file{dest},
-then @file{src/subdir/file} will map to @file{dest/subdir/file}.
-
-By setting this option to @samp{true}, the promiser destination
-directory promises to aggregate files searched from all subdirectories
-into itself, i.e. a single destination directory.
diff --git a/docs/reference/bodyparts/collect_window_example.texinfo b/docs/reference/bodyparts/collect_window_example.texinfo
deleted file mode 100644
index 3fb7f6ca07..0000000000
--- a/docs/reference/bodyparts/collect_window_example.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@verbatim
-
-collect_window => "15";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/collect_window_notes.texinfo b/docs/reference/bodyparts/collect_window_notes.texinfo
deleted file mode 100644
index e6adaf2212..0000000000
--- a/docs/reference/bodyparts/collect_window_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-@i{History}: Was introduced in 3.4.0, Enterprise 3.0.0 (2012)
-
-The time is measured in seconds, default value 10s.
diff --git a/docs/reference/bodyparts/command_example.texinfo b/docs/reference/bodyparts/command_example.texinfo
deleted file mode 100644
index a669784ec0..0000000000
--- a/docs/reference/bodyparts/command_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-body process_select example
-
-{
-command => "cf-.*";
-
-process_result => "command";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/command_notes.texinfo b/docs/reference/bodyparts/command_notes.texinfo
deleted file mode 100644
index ba47c46455..0000000000
--- a/docs/reference/bodyparts/command_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-This expression should match the entire @code{COMMAND} field of the
-process table (not just a fragment). This field is usually the last
-field on the line and thus starts with the first non-space character
-and ends with the end of line.
diff --git a/docs/reference/bodyparts/comment_example.texinfo b/docs/reference/bodyparts/comment_example.texinfo
deleted file mode 100644
index f461ba9719..0000000000
--- a/docs/reference/bodyparts/comment_example.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@verbatim
-
-comment => "This comment follows the data for reference ...",
-
-@end verbatim
diff --git a/docs/reference/bodyparts/comment_notes.texinfo b/docs/reference/bodyparts/comment_notes.texinfo
deleted file mode 100644
index 766ef18bd6..0000000000
--- a/docs/reference/bodyparts/comment_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Comments written in code follow the program, they are not merely discarded.
-They appear in reports and error messages.
diff --git a/docs/reference/bodyparts/compare_example.texinfo b/docs/reference/bodyparts/compare_example.texinfo
deleted file mode 100644
index 053eb84dbd..0000000000
--- a/docs/reference/bodyparts/compare_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-
-@verbatim
-
-body copy_from example
-
-{
-compare => "digest";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/compare_notes.texinfo b/docs/reference/bodyparts/compare_notes.texinfo
deleted file mode 100644
index 1889c7a724..0000000000
--- a/docs/reference/bodyparts/compare_notes.texinfo
+++ /dev/null
@@ -1,43 +0,0 @@
-
-The default copy method is @samp{mtime} (modification time), meaning that
-the source file is copied to the destination (promiser) file, if the
-source file has been modified more recently than the destination.
-
-The different options are:
-@itemize
-@item
-@code{mtime} CFEngine copies the file if the modification time of the source
-file is more recent than that of the promised file
-
-@item
-@code{ctime} CFEngine copies the file if the creation time of the source file
-is more recent than that of the promised file
-
-@item
-@code{atime} CFEngine copies the file if the modification time or creation
-time of the source file is more recent than that of the promised file. If the
-times are equal, a byte-for-bye comparison is done on the files to determine
-if it needs to be copied.
-
-@item
-@code{exists} CFEngine copies the file if the promised file does not already
-exist.
-
-@item
-@code{binary} CFEngine copies the file if they are both plain files and a
-byte-for-byte comparison determines that they are different. If both are not
-plain files, CFEngine reverts to comparing the @code{mtime} and @code{ctime}
-of the files. If the source file is on a different machine (i.e., network
-copy), then @code{hash} is used instead to reduce network bandwidth.
-
-@item
-@code{hash} CFEngine copies the file if they are both plain files and a
-message digest comparison indicates that the files are different. In
-Enterprise versions of CFEngine version 3.1.0 and later, SHA256 is used as a
-message digest hash to conform with FIPS; in older Enterprise versions of
-CFEngine and all Community versions, MD5 is used.
-
-@item
-@code{digest} a synonym for @code{hash}
-
-@end itemize
diff --git a/docs/reference/bodyparts/copy_backup_example.texinfo b/docs/reference/bodyparts/copy_backup_example.texinfo
deleted file mode 100644
index 7adbf1a838..0000000000
--- a/docs/reference/bodyparts/copy_backup_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body copy_from example
-{
-copy_backup => "timestamp";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/copy_backup_notes.texinfo b/docs/reference/bodyparts/copy_backup_notes.texinfo
deleted file mode 100644
index 75d733b1cc..0000000000
--- a/docs/reference/bodyparts/copy_backup_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-Determines whether a backup of the previous version is kept on the
-system. This should be viewed in connection with the system repository,
-since a defined repository affects the location at which the backup
-is stored. See
-@ref{default_repository in agent, ,default_repository} and
-@ref{repository in files, ,repository} for further details.
diff --git a/docs/reference/bodyparts/copy_patterns_example.texinfo b/docs/reference/bodyparts/copy_patterns_example.texinfo
deleted file mode 100644
index 010ec796fe..0000000000
--- a/docs/reference/bodyparts/copy_patterns_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body link_from example
-{
-copy_patterns => { "special_node1", "/path/special_node2" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/copy_patterns_notes.texinfo b/docs/reference/bodyparts/copy_patterns_notes.texinfo
deleted file mode 100644
index edae69024c..0000000000
--- a/docs/reference/bodyparts/copy_patterns_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-During the linking of files, it is sometimes useful to buffer changes
-with an actual copy, especially if the link is to an emphemeral file
-system. This list of patterns matches files that arise during a
-linking policy. A positive match means that the file should be copied
-and updated by modification time.
diff --git a/docs/reference/bodyparts/copy_size_example.texinfo b/docs/reference/bodyparts/copy_size_example.texinfo
deleted file mode 100644
index b05a6c82ce..0000000000
--- a/docs/reference/bodyparts/copy_size_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body copy_from example
-{
-copy_size => irange("0","50000");
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/copy_size_notes.texinfo b/docs/reference/bodyparts/copy_size_notes.texinfo
deleted file mode 100644
index e6bac7c9f0..0000000000
--- a/docs/reference/bodyparts/copy_size_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-The use of the irange function is optional. Ranges may also be
-specified as a comma separated numbers.
diff --git a/docs/reference/bodyparts/copylink_patterns_example.texinfo b/docs/reference/bodyparts/copylink_patterns_example.texinfo
deleted file mode 100644
index 2fe2b1b3fd..0000000000
--- a/docs/reference/bodyparts/copylink_patterns_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body copy_from example
-{
-copylink_patterns => { "special_node1", "other_node.*" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/copylink_patterns_notes.texinfo b/docs/reference/bodyparts/copylink_patterns_notes.texinfo
deleted file mode 100644
index c252a3a74b..0000000000
--- a/docs/reference/bodyparts/copylink_patterns_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-
-The matches are performed on the last node of the filename, i.e. the
-file without its path. As windows does not support symbolic links,
-this feature is not available there.
diff --git a/docs/reference/bodyparts/create_example.texinfo b/docs/reference/bodyparts/create_example.texinfo
deleted file mode 100644
index 7dde34afe7..0000000000
--- a/docs/reference/bodyparts/create_example.texinfo
+++ /dev/null
@@ -1,15 +0,0 @@
-
-@verbatim
-
-files:
-
- "/path/plain_file"
-
- create => "true";
-
- "/path/dir/."
-
- create => "true";
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/create_notes.texinfo b/docs/reference/bodyparts/create_notes.texinfo
deleted file mode 100644
index ff30058d86..0000000000
--- a/docs/reference/bodyparts/create_notes.texinfo
+++ /dev/null
@@ -1,18 +0,0 @@
-
-
-Directories are created by using the @samp{/.} to signify a directory type.
-Note that, if no permissions are specified, mode 600 is chosen for a file,
-and mode 755 is chosen for a directory. If you cannot accept these defaults,
-you @i{should} specify permissions.
-
-Note that technically, @samp{/.} is a regular expression. However, it is
-used as a special case meaning "directory". See the @b{filenames and regular
-expressions} near the beginning of the section on
-@ref{files in agent promises, ,files promises} for a more complete discussion.
-
-@b{Note:} In general, you should not use @code{create} with
-@ref{copy_from in files, ,copy_from} or @ref{link_from in files, ,link_from}
-in files promises. These latter attributes automatically
-create the promised file, and using @code{create} may actually prevent the
-copy or link promise from being kept (since @code{create} acts first, which
-may affect file comparison or linking operations).
diff --git a/docs/reference/bodyparts/csv2xml_example.texinfo b/docs/reference/bodyparts/csv2xml_example.texinfo
deleted file mode 100644
index a7732ac387..0000000000
--- a/docs/reference/bodyparts/csv2xml_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body reporter control
-{
-csv2xml => { "myreport.csv", "custom_report.csv" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/csv2xml_notes.texinfo b/docs/reference/bodyparts/csv2xml_notes.texinfo
deleted file mode 100644
index ac234050fd..0000000000
--- a/docs/reference/bodyparts/csv2xml_notes.texinfo
+++ /dev/null
@@ -1,14 +0,0 @@
-
-CSV files are easy to generate in CFEngine from individual promise logging functions.
-XML is not easily generated due to its hierarchical structure. This function allows
-@code{cf-report} to convert a CSV file into pidgin XML for convenience. The schema
-has the general form:
-
-@verbatim
-
-
-
-@end verbatim
diff --git a/docs/reference/bodyparts/ctime_example.texinfo b/docs/reference/bodyparts/ctime_example.texinfo
deleted file mode 100644
index 83ee006369..0000000000
--- a/docs/reference/bodyparts/ctime_example.texinfo
+++ /dev/null
@@ -1,13 +0,0 @@
-
-
-@verbatim
-
-body files_select example
-{
-ctime => irange(ago(1,0,0,0,0,0),now);
-file_result => "ctime";
-}
-
-@end verbatim
-
-
diff --git a/docs/reference/bodyparts/ctime_notes.texinfo b/docs/reference/bodyparts/ctime_notes.texinfo
deleted file mode 100644
index 2995b4414f..0000000000
--- a/docs/reference/bodyparts/ctime_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-The file's change time refers to both modification of content and attributes
-such as permissions. On windows, @code{ctime} refers to creation time.
diff --git a/docs/reference/bodyparts/data_type_example.texinfo b/docs/reference/bodyparts/data_type_example.texinfo
deleted file mode 100644
index 009058a78e..0000000000
--- a/docs/reference/bodyparts/data_type_example.texinfo
+++ /dev/null
@@ -1,17 +0,0 @@
-
-@verbatim
-
- "/bin/df"
-
- handle => "free_disk_watch",
- stream_type => "pipe",
-
- data_type => "slist",
-
- history_type => "static",
- units => "device",
- match_value => file_systems,
- action => sample_min(10,15);
-
-
-@end verbatim
diff --git a/docs/reference/bodyparts/data_type_notes.texinfo b/docs/reference/bodyparts/data_type_notes.texinfo
deleted file mode 100644
index 4e55eac83c..0000000000
--- a/docs/reference/bodyparts/data_type_notes.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-When CFEngine (Nova) observes data, such as the attached partitions in
-the example above, the datatype determines how that data will be
-handled. Integer and real values, counters etc., are recorded as
-time-series if the history type is `weekly', or as single values
-otherwise. If multiple items are matched by an observation,
-e.g. several lines in a file match the given regular expression,
-then these can be made into a list by choosing @code{slist}, else
-the first matching item will be selected.
-
diff --git a/docs/reference/bodyparts/database_columns_example.texinfo b/docs/reference/bodyparts/database_columns_example.texinfo
deleted file mode 100644
index e688dd200b..0000000000
--- a/docs/reference/bodyparts/database_columns_example.texinfo
+++ /dev/null
@@ -1,18 +0,0 @@
-
-@verbatim
-
- "cf_topic_maps/topics"
-
- database_operation => "create",
- database_type => "sql",
- database_columns => {
- "topic_name,varchar,256",
- "topic_comment,varchar,1024",
- "topic_id,varchar,256",
- "topic_type,varchar,256",
- "topic_extra,varchar,26"
- },
-
- database_server => myserver;
-
-@end verbatim
diff --git a/docs/reference/bodyparts/database_columns_notes.texinfo b/docs/reference/bodyparts/database_columns_notes.texinfo
deleted file mode 100644
index 7d0ba7cae8..0000000000
--- a/docs/reference/bodyparts/database_columns_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-Columns are a list of tuplets (@var{Name,type,size}). Array items are triplets, and fixed size data elements are doublets.
diff --git a/docs/reference/bodyparts/database_operation_example.texinfo b/docs/reference/bodyparts/database_operation_example.texinfo
deleted file mode 100644
index 11eae7936c..0000000000
--- a/docs/reference/bodyparts/database_operation_example.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@verbatim
-
-database_operation => "create";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/database_operation_notes.texinfo b/docs/reference/bodyparts/database_operation_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/bodyparts/database_operation_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/bodyparts/database_rows_example.texinfo b/docs/reference/bodyparts/database_rows_example.texinfo
deleted file mode 100644
index d659a90783..0000000000
--- a/docs/reference/bodyparts/database_rows_example.texinfo
+++ /dev/null
@@ -1,20 +0,0 @@
-
-@verbatim
-
-bundle agent databases
-
-{
-databases:
-
- windows::
-
- # Regsitry has (value,data) pairs in "keys" which are directories
-
- "HKEY_LOCAL_MACHINE\SOFTWARE\CFEngine AS\CFEngine"
-
- database_operation => "create",
- database_rows => { "value1,REG_SZ,new value 1", "value2,REG_DWORD,12345"} ,
- database_type => "ms_registry";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/database_rows_notes.texinfo b/docs/reference/bodyparts/database_rows_notes.texinfo
deleted file mode 100644
index b55b9049d1..0000000000
--- a/docs/reference/bodyparts/database_rows_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-This constraint is used only in adding data to database columns. Rows are considered to be
-instances of individual columns.
-
-In the case of the system registry on Windows, the rows represent data on data-value pairs.
-The currently supported types (the middle field) for the Windows registry are @code{REG_SZ} (string),
-@code{REG_EXPAND_SZ} (expandable string) and @code{REG_DWORD} (double word).
diff --git a/docs/reference/bodyparts/database_type_example.texinfo b/docs/reference/bodyparts/database_type_example.texinfo
deleted file mode 100644
index 4b861d430a..0000000000
--- a/docs/reference/bodyparts/database_type_example.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@verbatim
-
-database_type => "ms_registry";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/database_type_notes.texinfo b/docs/reference/bodyparts/database_type_notes.texinfo
deleted file mode 100644
index e69de29bb2..0000000000
diff --git a/docs/reference/bodyparts/db_server_connection_db_example.texinfo b/docs/reference/bodyparts/db_server_connection_db_example.texinfo
deleted file mode 100644
index 7a631f8c06..0000000000
--- a/docs/reference/bodyparts/db_server_connection_db_example.texinfo
+++ /dev/null
@@ -1,15 +0,0 @@
-
-@verbatim
-
-body database_server myserver(x)
-{
-db_server_owner => "$(x)";
-db_server_password => "";
-db_server_host => "localhost";
-db_server_type => "$(mysql)";
-db_server_connection_db => "$(x)";
-}
-
-@end verbatim
-
-@noindent where @samp{x} is currently @code{mysql} or @code{postgres}.
diff --git a/docs/reference/bodyparts/db_server_connection_db_notes.texinfo b/docs/reference/bodyparts/db_server_connection_db_notes.texinfo
deleted file mode 100644
index aa1fec9764..0000000000
--- a/docs/reference/bodyparts/db_server_connection_db_notes.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-In order to create a database on a database server (all of which
-practice voluntary cooperation), one has to be able to connect
-to the server, however, without an existing database this is not allowed.
-Thus, database servers provide a default database that can be connected
-to in order to thereafter create new databases. These are called
-@code{postgres} and @code{mysql} for their respective database servers.
-
-For the knowledge agent, this setting is made in the control body,
-for database verification promises, it is made in the
-@code{database_server} body.
diff --git a/docs/reference/bodyparts/db_server_host_example.texinfo b/docs/reference/bodyparts/db_server_host_example.texinfo
deleted file mode 100644
index e1542b8d02..0000000000
--- a/docs/reference/bodyparts/db_server_host_example.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@verbatim
-
-db_server_host => "sqlserv.example.org";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/db_server_host_notes.texinfo b/docs/reference/bodyparts/db_server_host_notes.texinfo
deleted file mode 100644
index a507e5ba47..0000000000
--- a/docs/reference/bodyparts/db_server_host_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-Hostname or IP address of the server.
diff --git a/docs/reference/bodyparts/db_server_owner_example.texinfo b/docs/reference/bodyparts/db_server_owner_example.texinfo
deleted file mode 100644
index 18419641d1..0000000000
--- a/docs/reference/bodyparts/db_server_owner_example.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@verbatim
-
-db_server_owner => "mark";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/db_server_owner_notes.texinfo b/docs/reference/bodyparts/db_server_owner_notes.texinfo
deleted file mode 100644
index e69de29bb2..0000000000
diff --git a/docs/reference/bodyparts/db_server_password_example.texinfo b/docs/reference/bodyparts/db_server_password_example.texinfo
deleted file mode 100644
index 3a28c29c8c..0000000000
--- a/docs/reference/bodyparts/db_server_password_example.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@verbatim
-
-db_server_password => "xyz.1234";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/db_server_password_notes.texinfo b/docs/reference/bodyparts/db_server_password_notes.texinfo
deleted file mode 100644
index e69de29bb2..0000000000
diff --git a/docs/reference/bodyparts/db_server_type_example.texinfo b/docs/reference/bodyparts/db_server_type_example.texinfo
deleted file mode 100644
index 063faf73a6..0000000000
--- a/docs/reference/bodyparts/db_server_type_example.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@verbatim
-
-db_server_type => "postgres";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/db_server_type_notes.texinfo b/docs/reference/bodyparts/db_server_type_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/bodyparts/db_server_type_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/bodyparts/default_repository_example.texinfo b/docs/reference/bodyparts/default_repository_example.texinfo
deleted file mode 100644
index 390a47f4dc..0000000000
--- a/docs/reference/bodyparts/default_repository_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-default_repository => "/var/cfengine/repository";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/default_repository_notes.texinfo b/docs/reference/bodyparts/default_repository_notes.texinfo
deleted file mode 100644
index c3af8a854b..0000000000
--- a/docs/reference/bodyparts/default_repository_notes.texinfo
+++ /dev/null
@@ -1,13 +0,0 @@
-
-If defined the default repository is the location where versions of
-files altered by CFEngine are stored. This should be understood in
-relation to the policy for @samp{backup} in copying, editing etc. If
-the backups are time-stamped, this becomes effective a version control
-repository. See also @ref{repository in files, ,repository} for a way
-to locally override the global repository.
-
-Note that when a repository is specified, the files are stored using the
-canonified directory name of the original file, concatenated with the name of
-the file. So, for example, @file{/usr/local/etc/postfix.conf} would ordinarily
-be stored in an alternative repository as
-@file{_usr_local_etc_postfix.conf.cfsaved}.
diff --git a/docs/reference/bodyparts/default_timeout_example.texinfo b/docs/reference/bodyparts/default_timeout_example.texinfo
deleted file mode 100644
index 805d9d92ea..0000000000
--- a/docs/reference/bodyparts/default_timeout_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-default_timeout => "10";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/default_timeout_notes.texinfo b/docs/reference/bodyparts/default_timeout_notes.texinfo
deleted file mode 100644
index e8428adab3..0000000000
--- a/docs/reference/bodyparts/default_timeout_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-The time is in seconds. It is not a guaranteed number, since it
-depends on system behaviour. under Linux, the kernel version plays a
-role, since not all system calls seem to respect the signals.
-
diff --git a/docs/reference/bodyparts/defaultcopytype_example.texinfo b/docs/reference/bodyparts/defaultcopytype_example.texinfo
deleted file mode 100644
index f487cef689..0000000000
--- a/docs/reference/bodyparts/defaultcopytype_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-#...
-defaultcopytype => "digest";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/defaultcopytype_notes.texinfo b/docs/reference/bodyparts/defaultcopytype_notes.texinfo
deleted file mode 100644
index bfa7bf01f7..0000000000
--- a/docs/reference/bodyparts/defaultcopytype_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Sets the global default policy for comparing source and image in copy transactions.
-
diff --git a/docs/reference/bodyparts/delete_if_contains_from_list_example.texinfo b/docs/reference/bodyparts/delete_if_contains_from_list_example.texinfo
deleted file mode 100644
index c465a268cb..0000000000
--- a/docs/reference/bodyparts/delete_if_contains_from_list_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body delete_select example(s)
-{
-delete_if_contains_from_list => { @(s) };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/delete_if_contains_from_list_notes.texinfo b/docs/reference/bodyparts/delete_if_contains_from_list_notes.texinfo
deleted file mode 100644
index 7cbb0da0d3..0000000000
--- a/docs/reference/bodyparts/delete_if_contains_from_list_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-
-Delete lines from a file if they contain the sub-strings listed.
-Note that this determination is made only on promised lines (that is, this
-attribute modifies the selection criteria, it does not make the initial
-selection).
diff --git a/docs/reference/bodyparts/delete_if_match_from_list_example.texinfo b/docs/reference/bodyparts/delete_if_match_from_list_example.texinfo
deleted file mode 100644
index abef80c702..0000000000
--- a/docs/reference/bodyparts/delete_if_match_from_list_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body delete_select example(s)
-{
-delete_if_match_from_list => { @(s) };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/delete_if_match_from_list_notes.texinfo b/docs/reference/bodyparts/delete_if_match_from_list_notes.texinfo
deleted file mode 100644
index b8538d3ba3..0000000000
--- a/docs/reference/bodyparts/delete_if_match_from_list_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-Delete lines from a file if the lines @i{completely} match any of
-the regular expressions listed (that is, the regular expression
-is anchored, @pxref{Anchored vs. unanchored regular expressions}).
-
-Note that the ``match'' determination is made only on promised lines (that is, this
-attribute modifies the selection criteria, it does not make the initial
-selection).
-
diff --git a/docs/reference/bodyparts/delete_if_not_contains_from_list_example.texinfo b/docs/reference/bodyparts/delete_if_not_contains_from_list_example.texinfo
deleted file mode 100644
index 198edfffbd..0000000000
--- a/docs/reference/bodyparts/delete_if_not_contains_from_list_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body delete_select discard(s)
-{
-delete_if_not_contains_from_list => { "substring1", "substring2" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/delete_if_not_contains_from_list_notes.texinfo b/docs/reference/bodyparts/delete_if_not_contains_from_list_notes.texinfo
deleted file mode 100644
index db8f4c5f8f..0000000000
--- a/docs/reference/bodyparts/delete_if_not_contains_from_list_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-Delete lines from the file which do not contain the sub-strings listed.
-Note that this determination is made only on promised lines (that is, this
-attribute modifies the selection criteria, it does not make the initial
-selection).
diff --git a/docs/reference/bodyparts/delete_if_not_match_from_list_example.texinfo b/docs/reference/bodyparts/delete_if_not_match_from_list_example.texinfo
deleted file mode 100644
index 216a1fc59a..0000000000
--- a/docs/reference/bodyparts/delete_if_not_match_from_list_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body delete_select example(s)
-{
-delete_if_not_match_from_list => { @(s) };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/delete_if_not_match_from_list_notes.texinfo b/docs/reference/bodyparts/delete_if_not_match_from_list_notes.texinfo
deleted file mode 100644
index 36357bde5c..0000000000
--- a/docs/reference/bodyparts/delete_if_not_match_from_list_notes.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-Delete lines from a file unless the lines @i{completely} match any of
-the regular expressions listed (that is, the regular expressions
-are anchored, @pxref{Anchored vs. unanchored regular expressions}).
-
-Note that the ``match'' determination is made only on promised lines (that is, this
-attribute modifies the selection criteria, it does not make the initial
-selection).
diff --git a/docs/reference/bodyparts/delete_if_not_startwith_from_list_example.texinfo b/docs/reference/bodyparts/delete_if_not_startwith_from_list_example.texinfo
deleted file mode 100644
index 3bf32a574c..0000000000
--- a/docs/reference/bodyparts/delete_if_not_startwith_from_list_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body delete_select example(s)
-{
-delete_if_not_startwith_from_list => { @(s) };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/delete_if_not_startwith_from_list_notes.texinfo b/docs/reference/bodyparts/delete_if_not_startwith_from_list_notes.texinfo
deleted file mode 100644
index 7c01af0315..0000000000
--- a/docs/reference/bodyparts/delete_if_not_startwith_from_list_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-Delete lines from a file unless they start with the sub-strings in the list
-given. Note that this determination is made only on promised lines (that is,
-this attribute modifies the selection criteria, it does not make the initial
-selection).
diff --git a/docs/reference/bodyparts/delete_if_startwith_from_list_example.texinfo b/docs/reference/bodyparts/delete_if_startwith_from_list_example.texinfo
deleted file mode 100644
index 8422531d8b..0000000000
--- a/docs/reference/bodyparts/delete_if_startwith_from_list_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body delete_select example(s)
-{
-delete_if_startwith_from_list => { @(s) };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/delete_if_startwith_from_list_notes.texinfo b/docs/reference/bodyparts/delete_if_startwith_from_list_notes.texinfo
deleted file mode 100644
index 4cf1654900..0000000000
--- a/docs/reference/bodyparts/delete_if_startwith_from_list_notes.texinfo
+++ /dev/null
@@ -1,33 +0,0 @@
-
-Delete lines from a file if they begin with the sub-strings listed.
-Note that this determination is made only on promised lines (that is, this
-attribute modifies the selection criteria, it does not make the initial
-selection). Therefore, if the file contains the following lines:
-
-@verbatim
-start alpha igniter
-start beta igniter
-init alpha burner
-init beta burner
-stop beta igniter
-stop alpha igniter
-stop alpha burner
-@end verbatim
-
-Then the following promise initially selects the four lines containing
-@samp{alpha}, but is moderated by the @code{delete_select} attribute. Thus,
-the promise will delete only the first and third lines of the file:
-
-@verbatim
-bundle edit_line alpha
-{
-delete_lines:
- ".*alpha.*"
- delete_select => starters;
-}
-
-body delete_select starters
-{
- delete_if_startwith_from_list => { "begin", "start", "init" };
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/deny_example.texinfo b/docs/reference/bodyparts/deny_example.texinfo
deleted file mode 100644
index 7e2b1a1199..0000000000
--- a/docs/reference/bodyparts/deny_example.texinfo
+++ /dev/null
@@ -1,16 +0,0 @@
-
-
-@verbatim
-
-bundle server access_rules()
-
-{
-access:
-
- "/path"
-
- admit => { ".*\.example\.org" },
- deny => { "badhost_1\.example\.org", "badhost_1\.example\.org" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/deny_notes.texinfo b/docs/reference/bodyparts/deny_notes.texinfo
deleted file mode 100644
index 1c62ccf165..0000000000
--- a/docs/reference/bodyparts/deny_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-Denial is for special exceptions. A better strategy is always to grant
-on a need to know basis. A security policy based on exceptions is a
-weak one.
-
-Note that only regular expressions or exact matches are allowed in this
-list, as non-specific matches are too greedy for denial.
diff --git a/docs/reference/bodyparts/denybadclocks_example.texinfo b/docs/reference/bodyparts/denybadclocks_example.texinfo
deleted file mode 100644
index 9f3e4f20db..0000000000
--- a/docs/reference/bodyparts/denybadclocks_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body server control
-{
-#..
-denybadclocks => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/denybadclocks_notes.texinfo b/docs/reference/bodyparts/denybadclocks_notes.texinfo
deleted file mode 100644
index b12a45f223..0000000000
--- a/docs/reference/bodyparts/denybadclocks_notes.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-A possible form of attack on the fileserver is to request files based
-on time by setting the clocks incorrectly. This option prevents
-connections from clients whose clocks are drifting too far from the
-server clock (where "too far" is currently defined as "more than an hour
-off"). This serves as a warning about clock asynchronization
-and also a protection against Denial of Service attempts based on
-clock corruption.
diff --git a/docs/reference/bodyparts/denyconnects_example.texinfo b/docs/reference/bodyparts/denyconnects_example.texinfo
deleted file mode 100644
index 2799efb927..0000000000
--- a/docs/reference/bodyparts/denyconnects_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-
-@verbatim
-body server control
-{
-denyconnects => { "badhost\.domain\.evil", "host3\.domain\.com" };
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/denyconnects_notes.texinfo b/docs/reference/bodyparts/denyconnects_notes.texinfo
deleted file mode 100644
index 8dfad71d76..0000000000
--- a/docs/reference/bodyparts/denyconnects_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-Hosts or IP addresses that are explicitly denied access. This should
-only be used in special circumstances. One should never grant generic
-access to everything and then deny special cases. Since the default
-server behaviour is to grant no access to anything, this list is
-unnecessary unless you have already granted access to some set of
-hosts using a generic pattern, to which you intend to make an exception.
-
-See also the warning about regular expressions in @code{allowallconnects}.
diff --git a/docs/reference/bodyparts/depends_on_example.texinfo b/docs/reference/bodyparts/depends_on_example.texinfo
deleted file mode 100644
index 7199b06c38..0000000000
--- a/docs/reference/bodyparts/depends_on_example.texinfo
+++ /dev/null
@@ -1,24 +0,0 @@
-
-@verbatim
-
-body common control
-{
-bundlesequence => { "one" };
-}
-
-bundle agent one
-{
-reports:
-
- cfengine_3::
-
- "two"
- depends_on => { "handle_one" };
-
- "one"
- handle => "handle_one";
-
-}
-
-
-@end verbatim
diff --git a/docs/reference/bodyparts/depends_on_notes.texinfo b/docs/reference/bodyparts/depends_on_notes.texinfo
deleted file mode 100644
index 086f4ccc8e..0000000000
--- a/docs/reference/bodyparts/depends_on_notes.texinfo
+++ /dev/null
@@ -1,15 +0,0 @@
-
-This is a list of promise handles for whom this promise is a
-promisee. In other words, we acknowledge that this promise will be
-affected by the list of promises whose handles are specified.
-
-It has the effect of partially ordering promises.
-
-As of version 3.4.0, promise this feature is active and may be
-considered a short-hand for setting classes. If one promise depends on
-a list of others, it will not be verified unless the dependent
-promises have already been verified and kept: i.e. as long as the
-dependent promises are either kept or repaired the dependee can be
-verified.
-
-Handles in other namespaces may be referred to by @var{namespace:handle}.
diff --git a/docs/reference/bodyparts/depth_example.texinfo b/docs/reference/bodyparts/depth_example.texinfo
deleted file mode 100644
index 0be22615ef..0000000000
--- a/docs/reference/bodyparts/depth_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body depth_search example
-{
-depth => "inf";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/depth_notes.texinfo b/docs/reference/bodyparts/depth_notes.texinfo
deleted file mode 100644
index a075174e97..0000000000
--- a/docs/reference/bodyparts/depth_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-This was previous called `recurse' in earlier versions of CFEngine.
-Note that the value @samp{inf} may be used for an unlimited value.
-
-When searching recursively from a directory, the parent directory is
-not part of the search. It is only the anchor point. To alter the parent,
-a separate non-recursive promise should be made.
diff --git a/docs/reference/bodyparts/dirlinks_example.texinfo b/docs/reference/bodyparts/dirlinks_example.texinfo
deleted file mode 100644
index 1a04b61388..0000000000
--- a/docs/reference/bodyparts/dirlinks_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body delete example
-{
-dirlinks => "keep";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/dirlinks_notes.texinfo b/docs/reference/bodyparts/dirlinks_notes.texinfo
deleted file mode 100644
index e7921a3d46..0000000000
--- a/docs/reference/bodyparts/dirlinks_notes.texinfo
+++ /dev/null
@@ -1,18 +0,0 @@
-
-Links to directories are normally removed just like any other link or
-file objects. By keeping directory links, you preserve the logical
-directory structure of the file system so that a link to a directory
-is not removed but is treated as a directory to be descended into.
-
-The value @code{keep} instructs CFEngine not to remove directory links.
-The values @code{delete} and @code{tidy} are synonymous, and instruct
-CFEngine to remove directory links.
-
-@noindent @b{Default value} (only if body is present):@*
-@*
-
-The default value only has significance if there is a @code{delete} body
-present. If there is no @code{delete} body, then files (and directory links)
-are @b{not} deleted.
-
-@code{dirlinks => delete}
diff --git a/docs/reference/bodyparts/disable_example.texinfo b/docs/reference/bodyparts/disable_example.texinfo
deleted file mode 100644
index 43dee7b08a..0000000000
--- a/docs/reference/bodyparts/disable_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body rename example
-{
-disable => "true";
-disable_suffix => ".nuked";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/disable_mode_example.texinfo b/docs/reference/bodyparts/disable_mode_example.texinfo
deleted file mode 100644
index 7a6d431041..0000000000
--- a/docs/reference/bodyparts/disable_mode_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-
-@verbatim
-
-body rename example
-{
-disable_mode => "0600";
-}
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/disable_mode_notes.texinfo b/docs/reference/bodyparts/disable_mode_notes.texinfo
deleted file mode 100644
index da2c16e949..0000000000
--- a/docs/reference/bodyparts/disable_mode_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-To disable an executable it is not enough to rename it, you should also remove the
-executable flag.
-
diff --git a/docs/reference/bodyparts/disable_notes.texinfo b/docs/reference/bodyparts/disable_notes.texinfo
deleted file mode 100644
index bf4cb3717f..0000000000
--- a/docs/reference/bodyparts/disable_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Disabling a file means making is impotent in the context in which it
-has an effect. For executables this means preventing execution, for an
-information file it means making the file unreadable.
diff --git a/docs/reference/bodyparts/disable_suffix_example.texinfo b/docs/reference/bodyparts/disable_suffix_example.texinfo
deleted file mode 100644
index 9a3dc812cd..0000000000
--- a/docs/reference/bodyparts/disable_suffix_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-
-@verbatim
-
-body rename example
-{
-disable => "true";
-disable_suffix => ".nuked";
-}
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/disable_suffix_notes.texinfo b/docs/reference/bodyparts/disable_suffix_notes.texinfo
deleted file mode 100644
index 96a7d29149..0000000000
--- a/docs/reference/bodyparts/disable_suffix_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-To make disabled files in a particular manner, use this string suffix.
-The default value is @file{.cf-disabled}.
diff --git a/docs/reference/bodyparts/dist_example.texinfo b/docs/reference/bodyparts/dist_example.texinfo
deleted file mode 100644
index b8d9b7dbd7..0000000000
--- a/docs/reference/bodyparts/dist_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-classes:
-
- "my_dist"
-
- dist => { "10", "20", "40", "50" };
-
-@end verbatim
diff --git a/docs/reference/bodyparts/dist_notes.texinfo b/docs/reference/bodyparts/dist_notes.texinfo
deleted file mode 100644
index 20e17e2662..0000000000
--- a/docs/reference/bodyparts/dist_notes.texinfo
+++ /dev/null
@@ -1,15 +0,0 @@
-
-Assign one generic class (always) and one additional class, randomly weighted
-on a probability distribution. The sum of @code{10+20+40+50 = 120} in the
-example above, so in generating a distribution, CFEngine picks a number
-between @code{1-120}. This will generate the following classes:
-
-@smallexample
-my_dist (always)
-my_dist_10 (10/120 of the time)
-my_dist_20 (20/120 of the time)
-my_dist_40 (40/120 of the time)
-my_dist_50 (50/120 of the time)
-@end smallexample
-
-This was previous called a @samp{strategy} in CFEngine 2.
diff --git a/docs/reference/bodyparts/domain_example.texinfo b/docs/reference/bodyparts/domain_example.texinfo
deleted file mode 100644
index c40d2ec7af..0000000000
--- a/docs/reference/bodyparts/domain_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body common control
-{
-domain => "example.org";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/domain_notes.texinfo b/docs/reference/bodyparts/domain_notes.texinfo
deleted file mode 100644
index 9bde773b1f..0000000000
--- a/docs/reference/bodyparts/domain_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-There is no standard, universal or reliable way of determining the
-DNS domain name of a host, so it can be set explicitly to simplify
-discovery and name-lookup.
-
diff --git a/docs/reference/bodyparts/dryrun_example.texinfo b/docs/reference/bodyparts/dryrun_example.texinfo
deleted file mode 100644
index 0bda0465c3..0000000000
--- a/docs/reference/bodyparts/dryrun_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-dryrun => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/dryrun_notes.texinfo b/docs/reference/bodyparts/dryrun_notes.texinfo
deleted file mode 100644
index 011ec54480..0000000000
--- a/docs/reference/bodyparts/dryrun_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-If set in the configuration, CFEngine makes no changes to a
-system, only reports what it needs to do.
diff --git a/docs/reference/bodyparts/dynamicaddresses_example.texinfo b/docs/reference/bodyparts/dynamicaddresses_example.texinfo
deleted file mode 100644
index f69d1a60a5..0000000000
--- a/docs/reference/bodyparts/dynamicaddresses_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body server control
-{
-dynamicaddresses => { "dhcp_.*" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/dynamicaddresses_notes.texinfo b/docs/reference/bodyparts/dynamicaddresses_notes.texinfo
deleted file mode 100644
index 37ccf70402..0000000000
--- a/docs/reference/bodyparts/dynamicaddresses_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-The addresses or hostnames here are expected to have non-permanent
-address-name bindings, we must therefor work harder to determine
-whether hosts credentials are trusted by looking for existing public
-keys in files that do not match the current hostname or IP.
-
-@b{This feature has been deprecated since 3.1.0.} This is now handled transparently.
diff --git a/docs/reference/bodyparts/edit_backup_example.texinfo b/docs/reference/bodyparts/edit_backup_example.texinfo
deleted file mode 100644
index 04c7256ccb..0000000000
--- a/docs/reference/bodyparts/edit_backup_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body edit_defaults example
-{
-edit_backup => "timestamp";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/edit_backup_notes.texinfo b/docs/reference/bodyparts/edit_backup_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/bodyparts/edit_backup_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/bodyparts/edit_fstab_example.texinfo b/docs/reference/bodyparts/edit_fstab_example.texinfo
deleted file mode 100644
index 49573e1912..0000000000
--- a/docs/reference/bodyparts/edit_fstab_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body mount example
-{
-edit_fstab => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/edit_fstab_notes.texinfo b/docs/reference/bodyparts/edit_fstab_notes.texinfo
deleted file mode 100644
index f19e1bdef5..0000000000
--- a/docs/reference/bodyparts/edit_fstab_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-The default behaviour is to not place edits in the file system table.
diff --git a/docs/reference/bodyparts/edit_template_example.texinfo b/docs/reference/bodyparts/edit_template_example.texinfo
deleted file mode 100644
index e4d3b86f26..0000000000
--- a/docs/reference/bodyparts/edit_template_example.texinfo
+++ /dev/null
@@ -1,56 +0,0 @@
-
-
-@verbatim
-#This is a template file /templates/input.tmpl
-
-These lines apply to anyone
-
-[%CFEngine solaris.Monday:: %]
-Everything after here applies only to solaris on Mondays
-until overridden...
-
-[%CFEngine linux:: %]
-Everything after here now applies now to linux only.
-
-[%CFEngine BEGIN %]
-This is a block of text
-That contains list variables: $(some.list)
-With text before and after.
-[%CFEngine END %]
-
-nameserver $(some.list)
-@end verbatim
-
-For example:
-
-@verbatim
-[%CFEngine any:: %]
-
- ServerAdmin $(stage_file.params[apache_mail_address][1])
- DocumentRoot /var/www/htdocs
- ServerName $(stage_file.params[apache_server_name][1])
- AddHandler cgi-script cgi
- ErrorLog /var/log/httpd/error.log
- AddType application/x-x509-ca-cert .crt
- AddType application/x-pkcs7-crl .crl
- SSLEngine off
- CustomLog /var/log/httpd/access.log
-
-
-[%CFEngine webservers_prod:: %]
-[%CFEngine BEGIN %]
-
- ServerAdmin $(stage_file.params[apache_mail_address][1])
- DocumentRoot /var/www/htdocs
- ServerName $(stage_file.params[apache_server_name][1])
- AddHandler cgi-script cgi
- ErrorLog /var/log/httpd/error.log
- AddType application/x-x509-ca-cert .crt
- AddType application/x-pkcs7-crl .crl
- SSLEngine on
- SSLCertificateFile $(stage_file.params[apache_ssl_crt][1])
- SSLCertificateKeyFile $(stage_file.params[apache_ssl_key][1])
- CustomLog /var/log/httpd/access.log
-
-[%CFEngine END %]
-@end verbatim
diff --git a/docs/reference/bodyparts/edit_template_notes.texinfo b/docs/reference/bodyparts/edit_template_notes.texinfo
deleted file mode 100644
index efea0e704c..0000000000
--- a/docs/reference/bodyparts/edit_template_notes.texinfo
+++ /dev/null
@@ -1,26 +0,0 @@
-
-@i{History}: Was introduced in 3.3.0, Nova 2.2.0 (2012)
-
-The template format uses inline tags to mark regions and classes.
-Each line represents an @code{insert_lines} promise, unless the promises
-are grouped into a block using:
-
-@verbatim
-[%CFEngine BEGIN %]
-...
-[%CFEngine END %]
-@end verbatim
-
-@noindent Variables, scalars and list variables are expanded within each
-promise; so, if lines are grouped into a block, the whole block is repeated
-when lists are expanded (see the Special Topics Guide on editing).
-
-If a class-context modified is used:
-
-@verbatim
-[%CFEngine class-expression:: %]
-@end verbatim
-@noindent then the lines that follow are only inserted if the context
-matches the agent's current context. This allows conditional insertion.
-
-
diff --git a/docs/reference/bodyparts/editbinaryfilesize_example.texinfo b/docs/reference/bodyparts/editbinaryfilesize_example.texinfo
deleted file mode 100644
index 68d894ebbd..0000000000
--- a/docs/reference/bodyparts/editbinaryfilesize_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body agent control
-{
-edibinaryfilesize => "10M";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/editbinaryfilesize_notes.texinfo b/docs/reference/bodyparts/editbinaryfilesize_notes.texinfo
deleted file mode 100644
index c521936064..0000000000
--- a/docs/reference/bodyparts/editbinaryfilesize_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-The global setting for the file-editing safety-net for binary files (this
-value may be overridden on a per-promise basis with @code{max_file_size},
-@xref{edit_defaults in files}. The default value for @code{editbinaryfilesize}
-is @code{100k}. Note the use of special units is allowed,
-@xref{Datatypes in CFEngine 3}, for a list of permissible suffixes.
-
-When setting limits, the limit on editing binary files should generally be
-set higher than for text files.
diff --git a/docs/reference/bodyparts/editfilesize_example.texinfo b/docs/reference/bodyparts/editfilesize_example.texinfo
deleted file mode 100644
index e6b473f5d1..0000000000
--- a/docs/reference/bodyparts/editfilesize_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-editfilesize => "120k";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/editfilesize_notes.texinfo b/docs/reference/bodyparts/editfilesize_notes.texinfo
deleted file mode 100644
index e5e0591135..0000000000
--- a/docs/reference/bodyparts/editfilesize_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-The global setting for the file-editing safety-net (this value may be
-overridden on a per-promise basis with @code{max_file_size},
-@xref{edit_defaults in files}. Note the use of special units is
-allowed, @xref{Datatypes in CFEngine 3}, for a list of permissible
-suffixes.
diff --git a/docs/reference/bodyparts/empty_file_before_editing_example.texinfo b/docs/reference/bodyparts/empty_file_before_editing_example.texinfo
deleted file mode 100644
index a8f350753c..0000000000
--- a/docs/reference/bodyparts/empty_file_before_editing_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body edit_defaults example
-{
-empty_file_before_editing => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/empty_file_before_editing_notes.texinfo b/docs/reference/bodyparts/empty_file_before_editing_notes.texinfo
deleted file mode 100644
index 6ea31ca7d0..0000000000
--- a/docs/reference/bodyparts/empty_file_before_editing_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Emptying a file before reconstructing its contents according to a
-fixed recipe allows an ordered procedure to be convergent.
-
diff --git a/docs/reference/bodyparts/encrypt_example.texinfo b/docs/reference/bodyparts/encrypt_example.texinfo
deleted file mode 100644
index 06b8c4dbf0..0000000000
--- a/docs/reference/bodyparts/encrypt_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body copy_from example
-{
-servers => { "remote-host.example.org" };
-encrypt => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/encrypt_notes.texinfo b/docs/reference/bodyparts/encrypt_notes.texinfo
deleted file mode 100644
index 753f43723c..0000000000
--- a/docs/reference/bodyparts/encrypt_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Client connections are encrypted with using a Blowfish randomly
-generated session key. The intial connection is encrypted using the
-public/private keys for the client and server hosts.
diff --git a/docs/reference/bodyparts/env_addresses_example.texinfo b/docs/reference/bodyparts/env_addresses_example.texinfo
deleted file mode 100644
index 01dea3a51e..0000000000
--- a/docs/reference/bodyparts/env_addresses_example.texinfo
+++ /dev/null
@@ -1,18 +0,0 @@
-
-@verbatim
-
-body environment_interface vnet(primary)
-{
-env_name => "$(this.promiser)";
-env_addresses => { "$(primary)" };
-
-host1::
-
- env_network => "default_vnet1";
-
-host2::
-
- env_network => "default_vnet2";
-
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/env_addresses_notes.texinfo b/docs/reference/bodyparts/env_addresses_notes.texinfo
deleted file mode 100644
index da1f6b7811..0000000000
--- a/docs/reference/bodyparts/env_addresses_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-The IP addresses of the virtual machine can be overridden here at run time.
diff --git a/docs/reference/bodyparts/env_baseline_example.texinfo b/docs/reference/bodyparts/env_baseline_example.texinfo
deleted file mode 100644
index ee7b25f879..0000000000
--- a/docs/reference/bodyparts/env_baseline_example.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@verbatim
-
-env_baseline => "/path/to/image";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/env_baseline_notes.texinfo b/docs/reference/bodyparts/env_baseline_notes.texinfo
deleted file mode 100644
index 383030dc63..0000000000
--- a/docs/reference/bodyparts/env_baseline_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-This function is for future development.
diff --git a/docs/reference/bodyparts/env_cpus_example.texinfo b/docs/reference/bodyparts/env_cpus_example.texinfo
deleted file mode 100644
index b0e69ed6a1..0000000000
--- a/docs/reference/bodyparts/env_cpus_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-body environment_resources my_environment
-{
-env_cpus => "2";
-env_memory => "512"; # in KB
-env_disk => "1024"; # in MB
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/env_cpus_notes.texinfo b/docs/reference/bodyparts/env_cpus_notes.texinfo
deleted file mode 100644
index d808d093b8..0000000000
--- a/docs/reference/bodyparts/env_cpus_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-The maximum number of cores or processors in the physical environment will
-set a natural limit on this value.
-
-This attribute conflicts with @code{env_spec}.
diff --git a/docs/reference/bodyparts/env_disk_example.texinfo b/docs/reference/bodyparts/env_disk_example.texinfo
deleted file mode 100644
index b0e69ed6a1..0000000000
--- a/docs/reference/bodyparts/env_disk_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-body environment_resources my_environment
-{
-env_cpus => "2";
-env_memory => "512"; # in KB
-env_disk => "1024"; # in MB
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/env_disk_notes.texinfo b/docs/reference/bodyparts/env_disk_notes.texinfo
deleted file mode 100644
index 1374df7af2..0000000000
--- a/docs/reference/bodyparts/env_disk_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-This parameter is currently unsupported, for future extension.
-
-This attribute conflicts with @code{env_spec}.
diff --git a/docs/reference/bodyparts/env_memory_example.texinfo b/docs/reference/bodyparts/env_memory_example.texinfo
deleted file mode 100644
index b0e69ed6a1..0000000000
--- a/docs/reference/bodyparts/env_memory_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-body environment_resources my_environment
-{
-env_cpus => "2";
-env_memory => "512"; # in KB
-env_disk => "1024"; # in MB
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/env_memory_notes.texinfo b/docs/reference/bodyparts/env_memory_notes.texinfo
deleted file mode 100644
index d81c40bcfd..0000000000
--- a/docs/reference/bodyparts/env_memory_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-The maximum amount of memory in the physical environment will set a
-natural limit on this value.
-
-This attribute conflicts with @code{env_spec}.
diff --git a/docs/reference/bodyparts/env_name_example.texinfo b/docs/reference/bodyparts/env_name_example.texinfo
deleted file mode 100644
index 29b04c5783..0000000000
--- a/docs/reference/bodyparts/env_name_example.texinfo
+++ /dev/null
@@ -1,14 +0,0 @@
-
-@verbatim
-body environment_interface vnet(primary)
-{
-env_name => "$(this.promiser)";
-env_addresses => { "$(primary)" };
-
-host1::
- env_network => "default_vnet1";
-
-host2::
- env_network => "default_vnet2";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/env_name_notes.texinfo b/docs/reference/bodyparts/env_name_notes.texinfo
deleted file mode 100644
index db7565626f..0000000000
--- a/docs/reference/bodyparts/env_name_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-The `hostname' of a virtual guest may or may not be the same as the identifier used
-as `promiser' by the virtualization manager.
diff --git a/docs/reference/bodyparts/env_network_example.texinfo b/docs/reference/bodyparts/env_network_example.texinfo
deleted file mode 100644
index c31a408ed0..0000000000
--- a/docs/reference/bodyparts/env_network_example.texinfo
+++ /dev/null
@@ -1,16 +0,0 @@
-
-@verbatim
-
-body environment_interface vnet(primary)
- {
- env_name => "$(this.promiser)";
- env_addresses => { "$(primary)" };
-
- host1::
- env_network => "default_vnet1";
-
- host2::
- env_network => "default_vnet2";
- }
-
-@end verbatim
diff --git a/docs/reference/bodyparts/env_network_notes.texinfo b/docs/reference/bodyparts/env_network_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/bodyparts/env_network_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/bodyparts/env_spec_example.texinfo b/docs/reference/bodyparts/env_spec_example.texinfo
deleted file mode 100644
index 4d4f8edc65..0000000000
--- a/docs/reference/bodyparts/env_spec_example.texinfo
+++ /dev/null
@@ -1,35 +0,0 @@
-
-
-@verbatim
-body environment_resources virt_xml(host)
-{
-env_spec =>
-
-"
- $(host)
-
- linux
- /var/lib/xen/install/vmlinuz-ubuntu10.4-x86_64
- /var/lib/xen/install/initrd-vmlinuz-ubuntu10.4-x86_64
- kickstart=http://example.com/myguest.ks
-
- 131072
- 1
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/env_spec_file_example.texinfo b/docs/reference/bodyparts/env_spec_file_example.texinfo
deleted file mode 100644
index fec4cd39b3..0000000000
--- a/docs/reference/bodyparts/env_spec_file_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@i{History}: Was introduced in 3.4.0a1.c535c6a097c8aa07c1c64382cf13dd813e0f2730, Nova 2.2.0.a1.ad619af71703946872e65ff63d3f69e862e0ef43 (2012)
-
-
-@verbatim
-
-Fill me in (.//bodyparts/env_spec_file_example.texinfo)
-""
-@end verbatim
diff --git a/docs/reference/bodyparts/env_spec_file_notes.texinfo b/docs/reference/bodyparts/env_spec_file_notes.texinfo
deleted file mode 100644
index 69fdf45a98..0000000000
--- a/docs/reference/bodyparts/env_spec_file_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@i{History}: Was introduced in 3.4.0a1.c535c6a097c8aa07c1c64382cf13dd813e0f2730, Nova 2.2.0.a1.ad619af71703946872e65ff63d3f69e862e0ef43 (2012)
-
-
-@verbatim
-
-Fill me in (.//bodyparts/env_spec_file_notes.texinfo)
-""
-@end verbatim
diff --git a/docs/reference/bodyparts/env_spec_notes.texinfo b/docs/reference/bodyparts/env_spec_notes.texinfo
deleted file mode 100644
index f8373b95b1..0000000000
--- a/docs/reference/bodyparts/env_spec_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-The preferred way to specify the resources of an environment on creation,
-i.e. when @code{envrionment_state} is @samp{create}.
-
-This attibute conflicts with @code{env_cpus}, @code{env_memory} and
-@code{env_disk}.
-
-@i{History}: Was introduced in version 3.1.0b1,Nova 2.0.0b1 (2010)
-
-
diff --git a/docs/reference/bodyparts/environment_example.texinfo b/docs/reference/bodyparts/environment_example.texinfo
deleted file mode 100644
index eba9bd5b6b..0000000000
--- a/docs/reference/bodyparts/environment_example.texinfo
+++ /dev/null
@@ -1,20 +0,0 @@
-
-@verbatim
-
-body common control
-{
-bundlesequence => { "one" };
-}
-
-body agent control
-{
-environment => { "A=123", "B=456", "PGK_PATH=/tmp"};
-}
-
-bundle agent one
-{
-commands:
-
- "/usr/bin/env";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/environment_host_example.texinfo b/docs/reference/bodyparts/environment_host_example.texinfo
deleted file mode 100644
index 1f0c16fa62..0000000000
--- a/docs/reference/bodyparts/environment_host_example.texinfo
+++ /dev/null
@@ -1,15 +0,0 @@
-
-@verbatim
-
-guest_environments:
-
- linux::
-
- "host1"
- comment => "Keep this vm suspended",
- environment_resources => myresources,
- environment_type => "kvm",
- environment_state => "suspended",
- environment_host => "ubuntu";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/environment_host_notes.texinfo b/docs/reference/bodyparts/environment_host_notes.texinfo
deleted file mode 100644
index f23be9e442..0000000000
--- a/docs/reference/bodyparts/environment_host_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-The promise will only apply to the machine with this class set. Thus,
-CFEngine must be running locally on the hypervisor for the promise to
-take effect.
-
-This attribute is required.
-
-@i{History}: this feature was introduced in Nova 2.0.0 (2010), Community 3.3.0 (2012)
-
diff --git a/docs/reference/bodyparts/environment_notes.texinfo b/docs/reference/bodyparts/environment_notes.texinfo
deleted file mode 100644
index 3a0f88c604..0000000000
--- a/docs/reference/bodyparts/environment_notes.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-This may be used to set the runtime environment of the agent process. The values of environment variables
-are inherited by child commands. Some interactive programs insist on values being set, e.g.
-
-@verbatim
-
-# Required by apt-cache, debian
-
-environment => { "LANG=C"};
-
-@end verbatim
diff --git a/docs/reference/bodyparts/environment_state_example.texinfo b/docs/reference/bodyparts/environment_state_example.texinfo
deleted file mode 100644
index f36122e79e..0000000000
--- a/docs/reference/bodyparts/environment_state_example.texinfo
+++ /dev/null
@@ -1,16 +0,0 @@
-
-@verbatim
-
-guest_environments:
-
- linux::
-
- "bishwa-kvm1"
- comment => "Keep this vm suspended",
- environment_resources => myresources,
- environment_type => "kvm",
- environment_state => "suspended",
- environment_host => "ubuntu";
-
-
-@end verbatim
diff --git a/docs/reference/bodyparts/environment_state_notes.texinfo b/docs/reference/bodyparts/environment_state_notes.texinfo
deleted file mode 100644
index 6477748b3f..0000000000
--- a/docs/reference/bodyparts/environment_state_notes.texinfo
+++ /dev/null
@@ -1,21 +0,0 @@
-
-The allowed states have the following convergent semantics.
-
-@table @samp
-@item create
-The guest machine is allocated, installed and left in a running state.
-
-@item delete
-The guest machine is shut down and de-allocated but no files are removed.
-
-@item running
-The guest machine is in a running state, if it previously exists.
-
-@item suspended
-The guest exists in a suspended state or a shutdown state. If the guest
-is running, it is suspended, else it is ignored.
-
-@item down
-The guest machine is shut down, but not de-allocated.
-
-@end table
diff --git a/docs/reference/bodyparts/environment_type_example.texinfo b/docs/reference/bodyparts/environment_type_example.texinfo
deleted file mode 100644
index 121d2f44ff..0000000000
--- a/docs/reference/bodyparts/environment_type_example.texinfo
+++ /dev/null
@@ -1,25 +0,0 @@
-
-@verbatim
-bundle agent my_vm_cloud
-{
-guest_environments:
-
- scope::
-
- "vguest1"
-
- environment_resources => my_environment_template,
- environment_interface => vnet("eth0,192.168.1.100/24"),
- environment_type => "test",
- environment_state => "create",
- environment_host => "atlas";
-
- "vguest2"
-
- environment_resources => my_environment_template,
- environment_interface => vnet("eth0,192.168.1.101/24"),
- environment_type => "test",
- environment_state => "delete",
- environment_host => "atlas";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/environment_type_notes.texinfo b/docs/reference/bodyparts/environment_type_notes.texinfo
deleted file mode 100644
index 964fed8097..0000000000
--- a/docs/reference/bodyparts/environment_type_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-The currently supported types are those supported by @i{libvirt}.
-More will be added as time goes on.
diff --git a/docs/reference/bodyparts/error_bars_example.texinfo b/docs/reference/bodyparts/error_bars_example.texinfo
deleted file mode 100644
index baaafb4d46..0000000000
--- a/docs/reference/bodyparts/error_bars_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body reporter control
-{
-error_bars => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/error_bars_notes.texinfo b/docs/reference/bodyparts/error_bars_notes.texinfo
deleted file mode 100644
index 683a634412..0000000000
--- a/docs/reference/bodyparts/error_bars_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-
-The default is to produce error bars. Without error bars from
-CFEngine's machine learning data there is no way to assess
-the significance of an observation about the system, i.e. whether
-it is normal or anomalous.
diff --git a/docs/reference/bodyparts/exclamation_example.texinfo b/docs/reference/bodyparts/exclamation_example.texinfo
deleted file mode 100644
index 6380c02eb4..0000000000
--- a/docs/reference/bodyparts/exclamation_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-exclamation => "false";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/exclamation_notes.texinfo b/docs/reference/bodyparts/exclamation_notes.texinfo
deleted file mode 100644
index 17cd4fa79b..0000000000
--- a/docs/reference/bodyparts/exclamation_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-This affects only the output format of warnings.
-
diff --git a/docs/reference/bodyparts/exclude_dirs_example.texinfo b/docs/reference/bodyparts/exclude_dirs_example.texinfo
deleted file mode 100644
index 15f6cd2e97..0000000000
--- a/docs/reference/bodyparts/exclude_dirs_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body depth_search
-{
-# no dot directories
-exclude_dirs => { "\..*" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/exclude_dirs_notes.texinfo b/docs/reference/bodyparts/exclude_dirs_notes.texinfo
deleted file mode 100644
index 2158fdc9a2..0000000000
--- a/docs/reference/bodyparts/exclude_dirs_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Directory names are treated specially when searching recursively through a
-file system.
diff --git a/docs/reference/bodyparts/exclude_hosts_example.texinfo b/docs/reference/bodyparts/exclude_hosts_example.texinfo
deleted file mode 100644
index 177fd22569..0000000000
--- a/docs/reference/bodyparts/exclude_hosts_example.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-@verbatim
-body hub control
-{
-exclude_hosts => { "192.168.12.21", "10.10", "10.12.*" };
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/exclude_hosts_notes.texinfo b/docs/reference/bodyparts/exclude_hosts_notes.texinfo
deleted file mode 100644
index 7f43f39e3c..0000000000
--- a/docs/reference/bodyparts/exclude_hosts_notes.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@i{History}: Was introduced in 3.3.0, Nova 2.1.1 (2011)
-
-In commercial CFEngine editions, this list of IP addresses will not be
-queried for reports by @code{cf-hub}, even though they are in the
-last-seen database.
-
-The lists may contain network addresses in CIDR notation or regular
-expressions to match the IP address. However, host names are currently
-not supported.
diff --git a/docs/reference/bodyparts/exec_command_example.texinfo b/docs/reference/bodyparts/exec_command_example.texinfo
deleted file mode 100644
index 882fd16a8e..0000000000
--- a/docs/reference/bodyparts/exec_command_example.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@verbatim
-
-exec_command => "$(sys.workdir)/bin/cf-agent -f failsafe.cf && $(sys.workdir)/bin/cf-agent";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/exec_command_notes.texinfo b/docs/reference/bodyparts/exec_command_notes.texinfo
deleted file mode 100644
index 58e40cf1c9..0000000000
--- a/docs/reference/bodyparts/exec_command_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-The command is run in a shell encapsulation so pipes and shell symbols
-may be used if desired. Unlike, CFEngine 2, CFEngine 3 does not
-automatically run a separate update sequence before its normal
-run. This can be handled using the approach in the example above.
diff --git a/docs/reference/bodyparts/exec_group_example.texinfo b/docs/reference/bodyparts/exec_group_example.texinfo
deleted file mode 100644
index 06c0e9a6e3..0000000000
--- a/docs/reference/bodyparts/exec_group_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body contain example
-{
-exec_group => "nogroup";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/exec_group_notes.texinfo b/docs/reference/bodyparts/exec_group_notes.texinfo
deleted file mode 100644
index c4a15e4ca3..0000000000
--- a/docs/reference/bodyparts/exec_group_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-This is part of the restriction of privilege for child processes when
-running @code{cf-agent} as the root group, or a group with
-privileges. It is ignored on windows, as processes do not have any
-groups associated with them.
diff --git a/docs/reference/bodyparts/exec_owner_example.texinfo b/docs/reference/bodyparts/exec_owner_example.texinfo
deleted file mode 100644
index 79274aa2d0..0000000000
--- a/docs/reference/bodyparts/exec_owner_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body contain example
-{
-exec_owner => "mysql_user";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/exec_owner_notes.texinfo b/docs/reference/bodyparts/exec_owner_notes.texinfo
deleted file mode 100644
index 5abe9f4f59..0000000000
--- a/docs/reference/bodyparts/exec_owner_notes.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-This is part of the restriction of privilege for child processes when
-running @code{cf-agent} as the root user, or a user with privileges.
-
-Windows requires the clear text password for the user account to run
-under. Keeping this in CFEngine policies could be a security
-hazard. Therefore, this option is not yet implemented on windows
-versions of CFEngine.
diff --git a/docs/reference/bodyparts/exec_program_example.texinfo b/docs/reference/bodyparts/exec_program_example.texinfo
deleted file mode 100644
index 39db9eb515..0000000000
--- a/docs/reference/bodyparts/exec_program_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-
-@verbatim
-
-body file_select example
-{
-exec_program => "/path/test_program $(this.promiser)";
-file_result => "exec_program";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/exec_program_notes.texinfo b/docs/reference/bodyparts/exec_program_notes.texinfo
deleted file mode 100644
index 964292df6c..0000000000
--- a/docs/reference/bodyparts/exec_program_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-This is part of the customizable file search criteria.
-If the user-defined program returns exit status 0, the file is considered matched.
diff --git a/docs/reference/bodyparts/exec_regex_example.texinfo b/docs/reference/bodyparts/exec_regex_example.texinfo
deleted file mode 100644
index 772dccc82e..0000000000
--- a/docs/reference/bodyparts/exec_regex_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-body file_select example
-{
-exec_regex => "SPECIAL_LINE: .*";
-exec_program => "/path/test_program $(this.promiser)";
-file_result => "exec_program.exec_regex";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/exec_regex_notes.texinfo b/docs/reference/bodyparts/exec_regex_notes.texinfo
deleted file mode 100644
index f0332341cc..0000000000
--- a/docs/reference/bodyparts/exec_regex_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-The regular expression must be used in conjunction with the @code{exec_program} test.
-In this way the program must both return exit status 0 and its
-output must match the regular expression. The entire output must
-be matched (that is, as if the regex is anchored, @pxref{Anchored
-vs. unanchored regular expressions}).
diff --git a/docs/reference/bodyparts/exec_timeout_example.texinfo b/docs/reference/bodyparts/exec_timeout_example.texinfo
deleted file mode 100644
index 6d30b80c73..0000000000
--- a/docs/reference/bodyparts/exec_timeout_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body contain example
-{
-exec_timeout => "30";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/exec_timeout_notes.texinfo b/docs/reference/bodyparts/exec_timeout_notes.texinfo
deleted file mode 100644
index 3ddc22de73..0000000000
--- a/docs/reference/bodyparts/exec_timeout_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Attempt to time-out after this number of seconds. This cannot be guaranteed as not all
-commands are willing to be interrupted in case of failure.
diff --git a/docs/reference/bodyparts/execcommand_example.texinfo b/docs/reference/bodyparts/execcommand_example.texinfo
deleted file mode 100644
index 3decf89700..0000000000
--- a/docs/reference/bodyparts/execcommand_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body executor control
-{
-execcommand => "/var/cfengine/bin/cf-agent";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/execcommand_notes.texinfo b/docs/reference/bodyparts/execcommand_notes.texinfo
deleted file mode 100644
index abfe3f657a..0000000000
--- a/docs/reference/bodyparts/execcommand_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-The default value for the @code{execcommand} is @file{WORKDIR/bin/cf-agent}.
diff --git a/docs/reference/bodyparts/executorfacility_example.texinfo b/docs/reference/bodyparts/executorfacility_example.texinfo
deleted file mode 100644
index c698c610f7..0000000000
--- a/docs/reference/bodyparts/executorfacility_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body executor control
-{
-executorfacility => "LOG_USER";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/executorfacility_notes.texinfo b/docs/reference/bodyparts/executorfacility_notes.texinfo
deleted file mode 100644
index b0ef8323e0..0000000000
--- a/docs/reference/bodyparts/executorfacility_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-See the syslog manual pages.
diff --git a/docs/reference/bodyparts/expand_scalars_example.texinfo b/docs/reference/bodyparts/expand_scalars_example.texinfo
deleted file mode 100644
index 7803e5e66d..0000000000
--- a/docs/reference/bodyparts/expand_scalars_example.texinfo
+++ /dev/null
@@ -1,37 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "testbundle" };
-}
-
-########################################################
-
-bundle agent testbundle
-
-{
-files:
-
- "/home/mark/tmp/file_based_on_template"
-
- create => "true",
- edit_line => ExpandMeFrom("/tmp/source_template");
-
-
-}
-
-########################################################
-
-bundle edit_line ExpandMeFrom(template)
-{
-insert_lines:
-
- "$(template)"
-
- insert_type => "file",
- expand_scalars => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/expand_scalars_notes.texinfo b/docs/reference/bodyparts/expand_scalars_notes.texinfo
deleted file mode 100644
index 1ef6af6054..0000000000
--- a/docs/reference/bodyparts/expand_scalars_notes.texinfo
+++ /dev/null
@@ -1,13 +0,0 @@
-
-A way of incorporating templates with variable expansion into file
-operations. Variables should be named and scoped appropriately for the
-bundle in which this promise is made. i.e. you should qualify the variables
-with the bundle in which they are defined:
-
-@verbatim
-$(bundle.variable)
-$(sys.host)
-$(mon.www_in)
-@end verbatim
-
-In CFEngine 2 @code{editfiles} this was called @samp{ExpandVariables}.
diff --git a/docs/reference/bodyparts/expireafter_example.texinfo b/docs/reference/bodyparts/expireafter_example.texinfo
deleted file mode 100644
index d6ac4d3ddb..0000000000
--- a/docs/reference/bodyparts/expireafter_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-@verbatim
-body action example
-{
-ifelapsed => "120"; # 2 hours
-expireafter => "240"; # 4 hours
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/expireafter_notes.texinfo b/docs/reference/bodyparts/expireafter_notes.texinfo
deleted file mode 100644
index e3d39170c7..0000000000
--- a/docs/reference/bodyparts/expireafter_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-The locking time after which CFEngine will attempt to kill and restart
-its attempt to keep a promise.
diff --git a/docs/reference/bodyparts/export_zenoss_example.texinfo b/docs/reference/bodyparts/export_zenoss_example.texinfo
deleted file mode 100644
index d139024fc8..0000000000
--- a/docs/reference/bodyparts/export_zenoss_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-body hub control
-{
-am_policy_hub::
-
- export_zenoss => "/var/www/reports/summary.z";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/export_zenoss_notes.texinfo b/docs/reference/bodyparts/export_zenoss_notes.texinfo
deleted file mode 100644
index 6b43c85c8e..0000000000
--- a/docs/reference/bodyparts/export_zenoss_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-@i{History}: Was introduced in version 3.1.0b1,Nova 2.0.0b1 (2010)
-
-For integration with the Zenoss monitoring software.
diff --git a/docs/reference/bodyparts/expression_example.texinfo b/docs/reference/bodyparts/expression_example.texinfo
deleted file mode 100644
index dc1535a237..0000000000
--- a/docs/reference/bodyparts/expression_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-@verbatim
-
-classes:
-
- "class_name" expression => "solaris|(linux.specialclass)";
- "has_toor" expression => userexists("toor");
-
-@end verbatim
diff --git a/docs/reference/bodyparts/expression_notes.texinfo b/docs/reference/bodyparts/expression_notes.texinfo
deleted file mode 100644
index 6e3b177e02..0000000000
--- a/docs/reference/bodyparts/expression_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-A way of aliasing class combinations.
-
diff --git a/docs/reference/bodyparts/extend_fields_example.texinfo b/docs/reference/bodyparts/extend_fields_example.texinfo
deleted file mode 100644
index 29c732020d..0000000000
--- a/docs/reference/bodyparts/extend_fields_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body edit_field example
-{
-extend_fields => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/extend_fields_notes.texinfo b/docs/reference/bodyparts/extend_fields_notes.texinfo
deleted file mode 100644
index 0c52a30b49..0000000000
--- a/docs/reference/bodyparts/extend_fields_notes.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-If a user specifies a field that does not exist, because there are not
-so many fields, this allows the number of fields to be extended.
-Without this setting, CFEngine will issue an error if a non-existent field
-is referenced.
-Blank fields in a tabular file can be eliminated or kept depending
-in this setting. If in doubt, set this to true.
-
diff --git a/docs/reference/bodyparts/extraction_regex_example.texinfo b/docs/reference/bodyparts/extraction_regex_example.texinfo
deleted file mode 100644
index 0045903319..0000000000
--- a/docs/reference/bodyparts/extraction_regex_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body match_value free_memory
-{
-select_line_matching => "MemFree:.*";
-extraction_regex => "MemFree:\s+([0-9]+).*";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/extraction_regex_notes.texinfo b/docs/reference/bodyparts/extraction_regex_notes.texinfo
deleted file mode 100644
index d6fe6010bf..0000000000
--- a/docs/reference/bodyparts/extraction_regex_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-A single parenthesized backreference should be given to lift the value to be measured out of the text stream.
-The regular expression may match a partial string (that is, it is unanchored
-@pxref{Anchored vs. unanchored regular expressions}).
diff --git a/docs/reference/bodyparts/failed_returncodes_example.texinfo b/docs/reference/bodyparts/failed_returncodes_example.texinfo
deleted file mode 100644
index e631985f94..0000000000
--- a/docs/reference/bodyparts/failed_returncodes_example.texinfo
+++ /dev/null
@@ -1,33 +0,0 @@
-@verbatim
-body common control
-{
-bundlesequence => { "cmdtest" };
-}
-
-bundle agent cmdtest
-{
-files:
-"/tmp/test"
- copy_from => copy("/etc/passwd");
-
-
-"/tmp/test"
- classes => example,
- transformer => "/bin/grep -q lkajfo999999 $(this.promiser)";
-
-reports:
-wasfailed::
- "The files-promise failed!";
-}
-
-body classes example
-{
-failed_returncodes => { "1" };
-repair_failed => { "wasfailed" };
-}
-
-body copy_from copy(file)
-{
-source => "$(file)";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/failed_returncodes_notes.texinfo b/docs/reference/bodyparts/failed_returncodes_notes.texinfo
deleted file mode 100644
index 006f932a5a..0000000000
--- a/docs/reference/bodyparts/failed_returncodes_notes.texinfo
+++ /dev/null
@@ -1,26 +0,0 @@
-
-A list of integer return codes indicating that a command-related
-promise has failed. This can in turn be used to define classes using
-the @code{promise_repaired} attribute, or merely alter the total
-compliance statistics.
-
-Currently, the attribute has impact on the following command-related
-promises.
-
-@itemize
-@item All promises of type @code{commands:}
-@item @code{files}-promises containing a @code{transformer}-attribute
-@item The package manager change command in @code{packages}-promises
-(e.g. the command for add, remove, etc.)
-@end itemize
-
-
-If none of the attributes @code{kept_returncodes}, @code{repaired_returncodes},
-or @code{failed_returncodes} are set, the default is to consider a
-return code zero as promise repaired, and nonzero as promise failed.
-
-Note that the return codes may overlap, so multiple classes may be set
-from one return code. In Unix systems the possible return codes are
-usually in the range from 0 to 255.
-
-@i{History}: Was introduced in version 3.1.3, Nova 2.0.2 (2010)
diff --git a/docs/reference/bodyparts/field_operation_example.texinfo b/docs/reference/bodyparts/field_operation_example.texinfo
deleted file mode 100644
index b25edf2845..0000000000
--- a/docs/reference/bodyparts/field_operation_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body edit_field example
-{
-field_operation => "append";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/field_operation_notes.texinfo b/docs/reference/bodyparts/field_operation_notes.texinfo
deleted file mode 100644
index 5c7e1f9874..0000000000
--- a/docs/reference/bodyparts/field_operation_notes.texinfo
+++ /dev/null
@@ -1,20 +0,0 @@
-
-The method by which to edit a field in multi-field/column editing
-of tabular files. The methods mean:
-
-@samp{append} - append the specified value to the end of the field/column, separating
- (potentially) multiple values with @samp{value_separator}
-
-@samp{prepend} - prepend the specified value at the beginning of the field/column,
- separating (potentially) multiple values with @samp{value_separator}
-
-@samp{alphanum} - insert the specified value into the field/column, keeping all the
- values (separated by @samp{value_separator}) in alphanumerically sorted order)
-
-@samp{set} - replace the entire field/column with the specified value
-
-@samp{delete} - delete the specified value (if present) in the specified field/column
-
-@noindent @b{Default value}:@*
-
-append
diff --git a/docs/reference/bodyparts/field_separator_example.texinfo b/docs/reference/bodyparts/field_separator_example.texinfo
deleted file mode 100644
index dce93b8be6..0000000000
--- a/docs/reference/bodyparts/field_separator_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body edit_field example
-{
-field_separator => ":";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/field_separator_notes.texinfo b/docs/reference/bodyparts/field_separator_notes.texinfo
deleted file mode 100644
index fdc43d4fce..0000000000
--- a/docs/reference/bodyparts/field_separator_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Most tabular files are separated by simple characters, but by allowing
-a general regular expression one can make creative use of this model to
-edit all kinds of line-based text files.
diff --git a/docs/reference/bodyparts/field_value_example.texinfo b/docs/reference/bodyparts/field_value_example.texinfo
deleted file mode 100644
index 0f32dbeb85..0000000000
--- a/docs/reference/bodyparts/field_value_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body edit_field example(s)
-{
-field_value => "$(s)";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/field_value_notes.texinfo b/docs/reference/bodyparts/field_value_notes.texinfo
deleted file mode 100644
index 0e0f67dbaa..0000000000
--- a/docs/reference/bodyparts/field_value_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Set a field to a constant value, e.g. reset the value to a constant
-default, empty the field, or set it fixed list.
diff --git a/docs/reference/bodyparts/file_result_example.texinfo b/docs/reference/bodyparts/file_result_example.texinfo
deleted file mode 100644
index 14c1cd8bf1..0000000000
--- a/docs/reference/bodyparts/file_result_example.texinfo
+++ /dev/null
@@ -1,21 +0,0 @@
-
-@verbatim
-
-body file_select year_or_less
-
-{
-mtime => irange(ago(1,0,0,0,0,0),now);
-file_result => "mtime";
-}
-
-body file_select my_pdf_files_morethan1dayold
-
-{
-mtime => irange(ago(0,0,1,0,0,0),now);
-leaf_name => { ".*\.pdf" , ".*\.fdf" };
-search_owners => { "mark" };
-
-file_result => "owner.leaf_name.!mtime";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/file_result_notes.texinfo b/docs/reference/bodyparts/file_result_notes.texinfo
deleted file mode 100644
index dd3a70dc83..0000000000
--- a/docs/reference/bodyparts/file_result_notes.texinfo
+++ /dev/null
@@ -1,31 +0,0 @@
-
-Sets the criteria for file selection outcome during file searches. The
-syntax is the same as for a class expression, since the file selection
-is a classification of the file-search in the same way that system
-classes are a classification of the abstract host-search (that is, you
-may specify a boolean expression involving any of the file-matching
-components). In this way, you
-may specify arbitrarily complex file-matching parameters, such as what is
-shown above, "is owned by
-mark, has the extension '.pdf' or '.fdf', and whose modification time is not
-between 1 day ago and now (that is, it is older than 1 day)".
-
-Items in the boolean expression in @code{file_result} must be from the
-following list:
-
-@itemize
-@item leaf_name
-@item path_name
-@item file_types
-@item mode
-@item size
-@item owner
-@item group
-@item atime
-@item ctime
-@item mtime
-@item issymlinkto
-@item exec_regex
-@item exec_program
-@item bsdflags
-@end itemize
diff --git a/docs/reference/bodyparts/file_to_print_example.texinfo b/docs/reference/bodyparts/file_to_print_example.texinfo
deleted file mode 100644
index 008c890a7f..0000000000
--- a/docs/reference/bodyparts/file_to_print_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body printfile example
-{
-file_to_print => "/etc/motd";
-number_of_lines => "10";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/file_to_print_notes.texinfo b/docs/reference/bodyparts/file_to_print_notes.texinfo
deleted file mode 100644
index 00f7a6858d..0000000000
--- a/docs/reference/bodyparts/file_to_print_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Include part of a file in a report.
-
diff --git a/docs/reference/bodyparts/file_types_example.texinfo b/docs/reference/bodyparts/file_types_example.texinfo
deleted file mode 100644
index 70bf82adad..0000000000
--- a/docs/reference/bodyparts/file_types_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-body file_select filter
-{
-file_types => { "plain","symlink" };
-
-file_result => "file_types";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/file_types_notes.texinfo b/docs/reference/bodyparts/file_types_notes.texinfo
deleted file mode 100644
index 9361547658..0000000000
--- a/docs/reference/bodyparts/file_types_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-File types vary in details between operating systems. The main POSIX
-types are provided here as menu options, with @samp{reg} being a synonym for
-@samp{plain} (meaning, in both cases, not one of the "special" file types).
diff --git a/docs/reference/bodyparts/files_auto_define_example.texinfo b/docs/reference/bodyparts/files_auto_define_example.texinfo
deleted file mode 100644
index 7d9800365d..0000000000
--- a/docs/reference/bodyparts/files_auto_define_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-files_auto_define => { "/etc/syslog\.c.*", "/etc/passwd" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/files_auto_define_notes.texinfo b/docs/reference/bodyparts/files_auto_define_notes.texinfo
deleted file mode 100644
index 767193ab18..0000000000
--- a/docs/reference/bodyparts/files_auto_define_notes.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-
-Classes are automatically defined by the files that are copied. The
-file is named according to the prefixed `canonization' of the file
-name. Canonization means that non-identifier characters are converted
-into underscores. Thus @file{/etc/passwd} would canonize to
-@samp{_etc_passwd}. The prefix @samp{auto_} is added to clarify the
-origin of the class. Thus in the example the copying of
-@file{/etc/passwd} would lead to the class @samp{auto__etc_passwd}
-being defined automatically.
-
diff --git a/docs/reference/bodyparts/files_single_copy_example.texinfo b/docs/reference/bodyparts/files_single_copy_example.texinfo
deleted file mode 100644
index 32ea935b1a..0000000000
--- a/docs/reference/bodyparts/files_single_copy_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-files_single_copy => { "/etc/.*", "/special/file" };
-}
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/files_single_copy_notes.texinfo b/docs/reference/bodyparts/files_single_copy_notes.texinfo
deleted file mode 100644
index 8b2b75fb38..0000000000
--- a/docs/reference/bodyparts/files_single_copy_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-This list of regular expressions will ensure that files matching the
-patterns of the list are never copied from more than one source during
-a single run of @code{cf-agent}. This may be considered a protection
-against accidential overlap of copies from diverse remote sources, or
-as a first-come-first-served disambiguation tool for lazy-evaluation
-of overlapping file-copy promises.
diff --git a/docs/reference/bodyparts/filetypes_example.texinfo b/docs/reference/bodyparts/filetypes_example.texinfo
deleted file mode 100644
index decfee4145..0000000000
--- a/docs/reference/bodyparts/filetypes_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-@verbatim
-
-body file_select
-{
-filetypes => { "plain", "symlink" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/filetypes_notes.texinfo b/docs/reference/bodyparts/filetypes_notes.texinfo
deleted file mode 100644
index 139597f9cb..0000000000
--- a/docs/reference/bodyparts/filetypes_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-
diff --git a/docs/reference/bodyparts/findertype_example.texinfo b/docs/reference/bodyparts/findertype_example.texinfo
deleted file mode 100644
index b5c43c1a2e..0000000000
--- a/docs/reference/bodyparts/findertype_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body copy_from example
-{
-findertype => "MacOSX";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/findertype_notes.texinfo b/docs/reference/bodyparts/findertype_notes.texinfo
deleted file mode 100644
index 473272908c..0000000000
--- a/docs/reference/bodyparts/findertype_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-This applies only to the Macintosh OSX variants.
diff --git a/docs/reference/bodyparts/fips_mode_example.texinfo b/docs/reference/bodyparts/fips_mode_example.texinfo
deleted file mode 100644
index e732b91903..0000000000
--- a/docs/reference/bodyparts/fips_mode_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body common control
-{
-fips_mode => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/fips_mode_notes.texinfo b/docs/reference/bodyparts/fips_mode_notes.texinfo
deleted file mode 100644
index 06a9a460ed..0000000000
--- a/docs/reference/bodyparts/fips_mode_notes.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-Appears as of Nova 2.0.
-If CFEngine commercial editions this value may be set to avoid the use
-of old deprecated algorithms that are no longer FIPS 140-2 compliant.
-If not set, there is some degree of compatibility with older versions and
-algorithms. During an upgrade, setting this parameter can cause a lot of
-recomputation of checksums etc. Government bodies starting with Nova 2.0
-or higher should set this to @samp{true} from the start.
diff --git a/docs/reference/bodyparts/first_last_example.texinfo b/docs/reference/bodyparts/first_last_example.texinfo
deleted file mode 100644
index cb82864edf..0000000000
--- a/docs/reference/bodyparts/first_last_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body location example
-{
-first_last => "last";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/first_last_notes.texinfo b/docs/reference/bodyparts/first_last_notes.texinfo
deleted file mode 100644
index 4dedb86684..0000000000
--- a/docs/reference/bodyparts/first_last_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-In multiple matches, decide whether the first or last occurrence of
-the matching pattern in the case affected by the change. In principle
-this could be generalized to more cases but this seems like a fragile
-quality to evaluate, and only these two cases are deemed of
-reproducible significance.
diff --git a/docs/reference/bodyparts/force_ipv4_example.texinfo b/docs/reference/bodyparts/force_ipv4_example.texinfo
deleted file mode 100644
index 0f5e09d7a0..0000000000
--- a/docs/reference/bodyparts/force_ipv4_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body copy_from example
-{
-force_ipv4 => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/force_ipv4_notes.texinfo b/docs/reference/bodyparts/force_ipv4_notes.texinfo
deleted file mode 100644
index 3ba8cde077..0000000000
--- a/docs/reference/bodyparts/force_ipv4_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-IPv6 should be harmless to most users unless you have a partially
-or misconfigured setup.
-
diff --git a/docs/reference/bodyparts/force_update_example.texinfo b/docs/reference/bodyparts/force_update_example.texinfo
deleted file mode 100644
index b60188ad93..0000000000
--- a/docs/reference/bodyparts/force_update_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body copy_from example
-{
-force_update => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/force_update_notes.texinfo b/docs/reference/bodyparts/force_update_notes.texinfo
deleted file mode 100644
index a421f5be9e..0000000000
--- a/docs/reference/bodyparts/force_update_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-Warning: this is a non-convergent operation. Although the end point
-might stabilize in content, the operation will never quiesce. Use of
-this feature is not recommended except in exceptional circumstances
-since it creates a busy-dependency. If the copy is a network copy,
-the system will be disturbed by network disruptions.
diff --git a/docs/reference/bodyparts/forgetrate_example.texinfo b/docs/reference/bodyparts/forgetrate_example.texinfo
deleted file mode 100644
index 18eb8eda34..0000000000
--- a/docs/reference/bodyparts/forgetrate_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body monitor control
-{
-forgetrate => "0.7";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/forgetrate_notes.texinfo b/docs/reference/bodyparts/forgetrate_notes.texinfo
deleted file mode 100644
index e1de8c0397..0000000000
--- a/docs/reference/bodyparts/forgetrate_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-Configurable settings for the machine-learning algorithm that
-tracks system behaviour. This is only for expert users. This parameter
-effectively determines (together with the monitoring rate) how
-quickly CFEngine forgets its previous history.
diff --git a/docs/reference/bodyparts/forward_relationship_example.texinfo b/docs/reference/bodyparts/forward_relationship_example.texinfo
deleted file mode 100644
index 8187b62bfb..0000000000
--- a/docs/reference/bodyparts/forward_relationship_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body association example
-{
-forward_relation => "is bigger than";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/forward_relationship_notes.texinfo b/docs/reference/bodyparts/forward_relationship_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/bodyparts/forward_relationship_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/bodyparts/freespace_example.texinfo b/docs/reference/bodyparts/freespace_example.texinfo
deleted file mode 100644
index b4bfb462e4..0000000000
--- a/docs/reference/bodyparts/freespace_example.texinfo
+++ /dev/null
@@ -1,14 +0,0 @@
-
-@verbatim
-
-body volume example1
-{
-freespace => "10%";
-}
-
-body volume example2
-{
-freespace => "50M";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/freespace_notes.texinfo b/docs/reference/bodyparts/freespace_notes.texinfo
deleted file mode 100644
index 37bd4e2368..0000000000
--- a/docs/reference/bodyparts/freespace_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-The amount of freespace that is promised on a storage device. Once
-this promise is found not to be kept (that is, if the free space falls below
-the promised value), warnings are generated. You may also
-want to use the results of this promise to control other promises,
-@xref{classes in *}.
diff --git a/docs/reference/bodyparts/fullencryption_example.texinfo b/docs/reference/bodyparts/fullencryption_example.texinfo
deleted file mode 100644
index ba91956201..0000000000
--- a/docs/reference/bodyparts/fullencryption_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-fullencryption => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/fullencryption_notes.texinfo b/docs/reference/bodyparts/fullencryption_notes.texinfo
deleted file mode 100644
index 35dab41e4b..0000000000
--- a/docs/reference/bodyparts/fullencryption_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-If true this encrypts all levels of the queries to the server during
-file transfers. The default is to not encrypt all aspects, since this
-can slow down transfer and basically only contributes to global
-warming for most users.
diff --git a/docs/reference/bodyparts/goal_categories_example.texinfo b/docs/reference/bodyparts/goal_categories_example.texinfo
deleted file mode 100644
index 6eef5f783d..0000000000
--- a/docs/reference/bodyparts/goal_categories_example.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-@verbatim
-body common control
-{
-goal_categories => { "goals", "targets", "milestones" };
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/goal_categories_notes.texinfo b/docs/reference/bodyparts/goal_categories_notes.texinfo
deleted file mode 100644
index b2df3d32be..0000000000
--- a/docs/reference/bodyparts/goal_categories_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@i{History}: Was introduced in version 3.1.5, Nova 2.1 (2011)
-
-Goal categories are the parent classes used when searching for goals in the knowledge map.
-This is mostly for internal use in the Knowledge Map, but is a generic part of policy
-so it appears in the common body.
diff --git a/docs/reference/bodyparts/goal_patterns_example.texinfo b/docs/reference/bodyparts/goal_patterns_example.texinfo
deleted file mode 100644
index 4a52a00e4a..0000000000
--- a/docs/reference/bodyparts/goal_patterns_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-
-@verbatim
-
-body common control
-{
-goal_patterns => { "goal_.*", "target.*" };
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/goal_patterns_notes.texinfo b/docs/reference/bodyparts/goal_patterns_notes.texinfo
deleted file mode 100644
index 45187f14cf..0000000000
--- a/docs/reference/bodyparts/goal_patterns_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@i{History}: Was introduced in version 3.1.5, Nova 2.1.0 (2011)
-
-Used as identifier to mark business and organizational goals in
-commercial versions of CFEngine. CFEngine uses this to match
-promisees that represent business goals in promises.
diff --git a/docs/reference/bodyparts/groups_example.texinfo b/docs/reference/bodyparts/groups_example.texinfo
deleted file mode 100644
index 90c73fed92..0000000000
--- a/docs/reference/bodyparts/groups_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-
-@verbatim
-body perms example
-{
-groups => { "users", "administrators" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/groups_notes.texinfo b/docs/reference/bodyparts/groups_notes.texinfo
deleted file mode 100644
index 01a664b126..0000000000
--- a/docs/reference/bodyparts/groups_notes.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-The first named group is the list is the defaul that will be
-configured if the file does not match an element of the list. The
-reserved word @samp{none} may be used to match files that are not
-owned by a registered group. On windows, files do not have file groups
-associated with them and thus this attribute is ignored.
-
-ACLs may be used in place for this.
diff --git a/docs/reference/bodyparts/handle_example.texinfo b/docs/reference/bodyparts/handle_example.texinfo
deleted file mode 100644
index 1dea9e0067..0000000000
--- a/docs/reference/bodyparts/handle_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-access:
-
- "/source"
-
- handle => "update_rule",
- admit => { "127.0.0.1" };
-
-@end verbatim
diff --git a/docs/reference/bodyparts/handle_notes.texinfo b/docs/reference/bodyparts/handle_notes.texinfo
deleted file mode 100644
index a6a472d929..0000000000
--- a/docs/reference/bodyparts/handle_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-A promise handle is like a `goto' label. It allows you to refer to a
-promise as the promisee of @code{depends_on} client of another
-promise. Handles are essential for mapping dependencies and performing
-impact analyses. In Enterprise versions of CFEngine, promise handles
-can also be used in @code{outputs} promises, @xref{outputs in agent
-promises}.
-
-Handles may consist of regular indentifier characters. CFEngine automatically `canonifies' the names of handles to conform to this standard. Caution: if the handle name is based on a variable, and the variable fails to expand, the handle will be based on the name of the variable rather than its content.
diff --git a/docs/reference/bodyparts/hash_example.texinfo b/docs/reference/bodyparts/hash_example.texinfo
deleted file mode 100644
index dcdb747e23..0000000000
--- a/docs/reference/bodyparts/hash_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body changes example
-{
-hash => "md5";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/hash_notes.texinfo b/docs/reference/bodyparts/hash_notes.texinfo
deleted file mode 100644
index 69a675a18c..0000000000
--- a/docs/reference/bodyparts/hash_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-The @code{best} option cross correlates the best two available
-algorithms known in the OpenSSL library.
-
diff --git a/docs/reference/bodyparts/hashpurge_example.texinfo b/docs/reference/bodyparts/hashpurge_example.texinfo
deleted file mode 100644
index 90c3753bdd..0000000000
--- a/docs/reference/bodyparts/hashpurge_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body agent control
-{
-hashpurge => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/hashpurge_notes.texinfo b/docs/reference/bodyparts/hashpurge_notes.texinfo
deleted file mode 100644
index f115f5cd94..0000000000
--- a/docs/reference/bodyparts/hashpurge_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Looking for files that are not present relative to the change
-management database also provides warnings about file deletions.
-
diff --git a/docs/reference/bodyparts/hashupdates_example.texinfo b/docs/reference/bodyparts/hashupdates_example.texinfo
deleted file mode 100644
index 278a8aa4fb..0000000000
--- a/docs/reference/bodyparts/hashupdates_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-
-@verbatim
-body agent control
-{
-hashupdates => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/hashupdates_notes.texinfo b/docs/reference/bodyparts/hashupdates_notes.texinfo
deleted file mode 100644
index c382819837..0000000000
--- a/docs/reference/bodyparts/hashupdates_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-If @samp{true} the stored reference value is updated as soon as a warning
-message has been given. As most changes are benign (package updates etc)
-this is a common setting.
diff --git a/docs/reference/bodyparts/histograms_example.texinfo b/docs/reference/bodyparts/histograms_example.texinfo
deleted file mode 100644
index e8236b597f..0000000000
--- a/docs/reference/bodyparts/histograms_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body monitor control
-{
-histograms => "true";
-}
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/histograms_notes.texinfo b/docs/reference/bodyparts/histograms_notes.texinfo
deleted file mode 100644
index 2c46571df7..0000000000
--- a/docs/reference/bodyparts/histograms_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-@code{cf-monitord} now always keeps histograms information, so this
-option is a no-op kept for backward compatibility. It used to cause
-CFEngine to learn the conformally transformed distributions of
-fluctuations about the mean.
diff --git a/docs/reference/bodyparts/history_type_example.texinfo b/docs/reference/bodyparts/history_type_example.texinfo
deleted file mode 100644
index 2645a0bc8f..0000000000
--- a/docs/reference/bodyparts/history_type_example.texinfo
+++ /dev/null
@@ -1,13 +0,0 @@
-
-@verbatim
-
- "/proc/meminfo"
-
- handle => "free_memory_watch",
- stream_type => "file",
- data_type => "int",
- history_type => "weekly",
- units => "kB",
- match_value => free_memory;
-
-@end verbatim
diff --git a/docs/reference/bodyparts/history_type_notes.texinfo b/docs/reference/bodyparts/history_type_notes.texinfo
deleted file mode 100644
index f21d69e66c..0000000000
--- a/docs/reference/bodyparts/history_type_notes.texinfo
+++ /dev/null
@@ -1,17 +0,0 @@
-
-@table @samp
-@item scalar
-A single value, with compressed statistics is retained. The value of the
-data is not expected to change much for the lifetime of the daemon (and so
-will be sampled less often by @samp{cf-monitord}).
-
-@item static
-A synonym for `scalar'.
-
-@item log
-The measured value is logged as an infinite time-series in
-@samp{$(sys.workdir)/state}.
-
-@item weekly
-A standard CFEngine two-dimensional time average (over a weekly period) is retained.
-@end table
diff --git a/docs/reference/bodyparts/host_licenses_paid_example.texinfo b/docs/reference/bodyparts/host_licenses_paid_example.texinfo
deleted file mode 100644
index bec1dbf854..0000000000
--- a/docs/reference/bodyparts/host_licenses_paid_example.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-@verbatim
-body common control
-{
-host_licenses_paid => "1000";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/host_licenses_paid_notes.texinfo b/docs/reference/bodyparts/host_licenses_paid_notes.texinfo
deleted file mode 100644
index ca9091598e..0000000000
--- a/docs/reference/bodyparts/host_licenses_paid_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-Licensees of the commercial CFEngine releases have to make a promise
-in acceptance of contract terms by setting this value to the number of licenses
-they have paid for. This is tallied with the number of licenses granted.
-This declaration should be placed in all separate configuration files, e.g.
-@file{failsafe.cf}, @file{promises.cf}.
diff --git a/docs/reference/bodyparts/hostnamekeys_example.texinfo b/docs/reference/bodyparts/hostnamekeys_example.texinfo
deleted file mode 100644
index 7bed4a71ba..0000000000
--- a/docs/reference/bodyparts/hostnamekeys_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body server control
-{
-hostnamekeys => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/hostnamekeys_notes.texinfo b/docs/reference/bodyparts/hostnamekeys_notes.texinfo
deleted file mode 100644
index 49c7ff2c99..0000000000
--- a/docs/reference/bodyparts/hostnamekeys_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-Client side choice to base key associations on host names rather than IP address.
-This is useful for hosts with dynamic addresses.
-
-@b{This feature has been deprecated since 3.1.0.} Host identification is now handled
-transparently.
-
diff --git a/docs/reference/bodyparts/hosts_example.texinfo b/docs/reference/bodyparts/hosts_example.texinfo
deleted file mode 100644
index 489c5eca98..0000000000
--- a/docs/reference/bodyparts/hosts_example.texinfo
+++ /dev/null
@@ -1,14 +0,0 @@
-
-
-@verbatim
-
-body runagent control
-{
-network1::
- hosts => { "host1.example.org", "host2", "host3" };
-
-network2::
- hosts => { "host1.example.com", "host2", "host3" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/hosts_notes.texinfo b/docs/reference/bodyparts/hosts_notes.texinfo
deleted file mode 100644
index 85b0a14d0a..0000000000
--- a/docs/reference/bodyparts/hosts_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-The complete list of contactable hosts. The values may be either
-numerical IP addresses or DNS names, optionally suffixed by a @samp{:}
-and a port number. If no port number is given, the default CFEngine
-port 5308 is assumed.
diff --git a/docs/reference/bodyparts/hub_schedule_example.texinfo b/docs/reference/bodyparts/hub_schedule_example.texinfo
deleted file mode 100644
index 873c971c85..0000000000
--- a/docs/reference/bodyparts/hub_schedule_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body hub control
-{
-hub_schedule => { "Min00", "Min30", "(Evening|Night).Min45_50" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/hub_schedule_notes.texinfo b/docs/reference/bodyparts/hub_schedule_notes.texinfo
deleted file mode 100644
index 1466394bb5..0000000000
--- a/docs/reference/bodyparts/hub_schedule_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-@i{History}: Was introduced in version 3.1.0b1,Nova 2.0.0b1 (2010)
-
diff --git a/docs/reference/bodyparts/if_match_regex_example.texinfo b/docs/reference/bodyparts/if_match_regex_example.texinfo
deleted file mode 100644
index 90bb99429e..0000000000
--- a/docs/reference/bodyparts/if_match_regex_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-
-@verbatim
-bundle agent mymethod(a,b)
-{
-defaults:
-
- "a" string => "AAAAAAAAA", if_match_regex => "";
- "b" string => "BBBBBBBBB", if_match_regex => "";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/if_match_regex_notes.texinfo b/docs/reference/bodyparts/if_match_regex_notes.texinfo
deleted file mode 100644
index 0bc294fdb5..0000000000
--- a/docs/reference/bodyparts/if_match_regex_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@i{History}: Was introduced in 3.4.0, Enterprise 3.0.0 (2012)
-
-If a parameter or variable is already defined in the current context and
-the value matches this regular expression, it will be deemed invalid and
-replaced with the default value.
diff --git a/docs/reference/bodyparts/ifelapsed_example.texinfo b/docs/reference/bodyparts/ifelapsed_example.texinfo
deleted file mode 100644
index b703c61229..0000000000
--- a/docs/reference/bodyparts/ifelapsed_example.texinfo
+++ /dev/null
@@ -1,20 +0,0 @@
-
-
-@verbatim
-
-#local
-
-body action example
-{
-ifelapsed => "120"; # 2 hours
-expireafter => "240"; # 4 hours
-}
-
-# global
-
-body agent control
-{
-ifelapsed => "180"; # 3 hours
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/ifelapsed_notes.texinfo b/docs/reference/bodyparts/ifelapsed_notes.texinfo
deleted file mode 100644
index d768311d37..0000000000
--- a/docs/reference/bodyparts/ifelapsed_notes.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-This overrides the global settings. Promises which take a long time to
-verify should usually be protected with a long value for this
-parameter. This serves as a resource `spam' protection. A CFEngine
-check could easily run every 5 minutes provided resource intensive
-operations are not performed on every run. Using time classes like
-@code{Hr12} etc., is one part of this strategy; using @code{ifelapsed}
-is another which is not tied to a specific time.
diff --git a/docs/reference/bodyparts/ifencrypted_example.texinfo b/docs/reference/bodyparts/ifencrypted_example.texinfo
deleted file mode 100644
index 3350c488f8..0000000000
--- a/docs/reference/bodyparts/ifencrypted_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-access:
-
- "/path/file"
-
- admit => { ".*\.example\.org" },
- ifencrypted => "true";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/ifencrypted_notes.texinfo b/docs/reference/bodyparts/ifencrypted_notes.texinfo
deleted file mode 100644
index 7ca530a9a0..0000000000
--- a/docs/reference/bodyparts/ifencrypted_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-If this flag is true a client cannot access the file object unless
-its connection is encrypted.
-
diff --git a/docs/reference/bodyparts/ifvarclass_example.texinfo b/docs/reference/bodyparts/ifvarclass_example.texinfo
deleted file mode 100644
index 6b5c587aed..0000000000
--- a/docs/reference/bodyparts/ifvarclass_example.texinfo
+++ /dev/null
@@ -1,35 +0,0 @@
-
-The generic example has the form:
-@example
-
-@var{promise-type}:
-
- "@var{promiser}"
-
- ifvarclass => "$(program)_running|($(program)_notfound&Hr12)";
-
-@end example
-
-@noindent A specific example would be:
-
-@verbatim
-
-bundle agent example
-
-{
-commands:
-
- any::
-
- "/bin/echo This is linux"
-
- ifvarclass => "linux";
-
-
- "/bin/echo This is solaris"
-
- ifvarclass => "solaris";
-
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/ifvarclass_notes.texinfo b/docs/reference/bodyparts/ifvarclass_notes.texinfo
deleted file mode 100644
index bdccba21df..0000000000
--- a/docs/reference/bodyparts/ifvarclass_notes.texinfo
+++ /dev/null
@@ -1,32 +0,0 @@
-
-This is an additional class expression that will be evaluated after
-the @samp{@var{class}::} classes have selected promises. It is
-provided in order to enable a channel between variables and classes.
-The result is thus the logical AND of the ordinary classes and the
-variable classes.
-
-This function is provided so that one can form expressions that link
-variables and classes, e.g.
-
-@verbatim
-# Check that all components are running
-
-vars:
-
- "component" slist => { "cf-monitord", "cf-serverd" };
-
-processes:
-
- "$(component)" restart_class => canonify("start_$(component)");
-
-commands:
-
- "/var/cfengine/bin/$(component)"
-
- ifvarclass => canonify("start_$(component)");
-
-@end verbatim
-
-Notice that the function @code{canonify()} is provided to convert a
-general variable input into a string composed only of legal
-characters, using the same algorithm that CFEngine uses.
diff --git a/docs/reference/bodyparts/ignore_missing_bundles_example.texinfo b/docs/reference/bodyparts/ignore_missing_bundles_example.texinfo
deleted file mode 100644
index 3b2fe9b79a..0000000000
--- a/docs/reference/bodyparts/ignore_missing_bundles_example.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-@verbatim
-ignore_missing_bundles => "true";
-@end verbatim
diff --git a/docs/reference/bodyparts/ignore_missing_bundles_notes.texinfo b/docs/reference/bodyparts/ignore_missing_bundles_notes.texinfo
deleted file mode 100644
index 87ae4d836b..0000000000
--- a/docs/reference/bodyparts/ignore_missing_bundles_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-This authorizes the bundlesequence to contain possibly "nonexistent" pluggable modules.
-It defaults to false, whereupon undefined bundles cause a fatal error in parsing,
-and a transition to failsafe mode.
-
diff --git a/docs/reference/bodyparts/ignore_missing_inputs.example.texinfo b/docs/reference/bodyparts/ignore_missing_inputs.example.texinfo
deleted file mode 100644
index 6d8719d214..0000000000
--- a/docs/reference/bodyparts/ignore_missing_inputs.example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-body common control
-{
-ignore_missing_inputs => "true";
-
-inputs => { "include1.cf", "might_exist.cf" };
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/ignore_missing_inputs.notes.texinfo b/docs/reference/bodyparts/ignore_missing_inputs.notes.texinfo
deleted file mode 100644
index 529bb5f729..0000000000
--- a/docs/reference/bodyparts/ignore_missing_inputs.notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-If this is set to true, CFEngine will not balk at missing input files,
-but will ignore them and continue. This allows one to authorize
-pluggable modules that can be called up as @code{methods}.
diff --git a/docs/reference/bodyparts/ignore_missing_inputs_example.texinfo b/docs/reference/bodyparts/ignore_missing_inputs_example.texinfo
deleted file mode 100644
index 45835b30c0..0000000000
--- a/docs/reference/bodyparts/ignore_missing_inputs_example.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@verbatim
-
-ignore_missing_inputs => "true";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/ignore_missing_inputs_notes.texinfo b/docs/reference/bodyparts/ignore_missing_inputs_notes.texinfo
deleted file mode 100644
index 25ea5178d1..0000000000
--- a/docs/reference/bodyparts/ignore_missing_inputs_notes.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-The inputs lists determines which files are parsed by CFEngine. Normally
-stringent security checks are made on input files to prevent abuse of the
-system by unauthorized users. Sometimes however, it is appropriate to consider
-the automatic plug-in of modules that might or might not exist. This option
-permits CFEngine to list possible files that might not exist and continue
-`best effort' with those that do exist. The default of all Booleans is false,
-so the normal behaviour is to signal an error if an input is not found.
diff --git a/docs/reference/bodyparts/ilist_example.texinfo b/docs/reference/bodyparts/ilist_example.texinfo
deleted file mode 100644
index 0b5e71dcc3..0000000000
--- a/docs/reference/bodyparts/ilist_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-vars:
-
- "variable_id"
-
- ilist => { "10", "11", "12" };
-
-@end verbatim
diff --git a/docs/reference/bodyparts/ilist_notes.texinfo b/docs/reference/bodyparts/ilist_notes.texinfo
deleted file mode 100644
index a16822fe1f..0000000000
--- a/docs/reference/bodyparts/ilist_notes.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-Integer lists are lists of strings that are expected to be treated as integers.
-The typing in CFEngine is dynamic, so the variable types are interchangable,
-but when you declare a variable to be type @code{ilist}, CFEngine verifies that
-each value you assign to it looks like an integer (e.g., @samp{3},
-@samp{-17}, @samp{16K}, etc).
-
-Some functions return @code{ilist}s (@pxref{Introduction to functions}),
-and an @code{ilist} may contain the values copied from another @code{slist},
-@code{rlist}, or @code{ilist} (@pxref{List variable substitution and expansion},
-@pxref{policy in vars}).
diff --git a/docs/reference/bodyparts/in_range_define_example.texinfo b/docs/reference/bodyparts/in_range_define_example.texinfo
deleted file mode 100644
index a89da4135e..0000000000
--- a/docs/reference/bodyparts/in_range_define_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body process_count example
-{
-in_range_define => { "class1", "class2" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/in_range_define_notes.texinfo b/docs/reference/bodyparts/in_range_define_notes.texinfo
deleted file mode 100644
index b159e0ffe8..0000000000
--- a/docs/reference/bodyparts/in_range_define_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Classes are defined if the processes that are found in the process table satisfy the
-promised process count, i.e. if the promise about the number of processes matching
-the other criteria is kept.
diff --git a/docs/reference/bodyparts/include_basedir_example.texinfo b/docs/reference/bodyparts/include_basedir_example.texinfo
deleted file mode 100644
index 6c64a1e521..0000000000
--- a/docs/reference/bodyparts/include_basedir_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body depth_search example
-{
-include_basedir => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/include_basedir_notes.texinfo b/docs/reference/bodyparts/include_basedir_notes.texinfo
deleted file mode 100644
index 3034769e8f..0000000000
--- a/docs/reference/bodyparts/include_basedir_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-When checking files recursively (with @code{depth_search}) the promiser
-is a directory. This parameter determines whether that initial directory
-should be considered part of the promise or simply a boundary which marks
-the edge of the search. If true, the promiser directory will also promise
-the same attributes as the files inside it.
diff --git a/docs/reference/bodyparts/include_dirs_example.texinfo b/docs/reference/bodyparts/include_dirs_example.texinfo
deleted file mode 100644
index 7c8364149e..0000000000
--- a/docs/reference/bodyparts/include_dirs_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body depth_search example
-{
-include_dirs => { "subdir1", "subdir2", "pattern.*" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/include_dirs_notes.texinfo b/docs/reference/bodyparts/include_dirs_notes.texinfo
deleted file mode 100644
index a216f045c2..0000000000
--- a/docs/reference/bodyparts/include_dirs_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-This is the complement of @code{exclude_dirs}.
diff --git a/docs/reference/bodyparts/include_end_delimiter_example.texinfo b/docs/reference/bodyparts/include_end_delimiter_example.texinfo
deleted file mode 100644
index 2c980f84d4..0000000000
--- a/docs/reference/bodyparts/include_end_delimiter_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-body select_region BracketSection(x)
-{
-select_start => "$(x) \{";
-select_end => "}";
-include_end_delimiter => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/include_end_delimiter_notes.texinfo b/docs/reference/bodyparts/include_end_delimiter_notes.texinfo
deleted file mode 100644
index f87c83547a..0000000000
--- a/docs/reference/bodyparts/include_end_delimiter_notes.texinfo
+++ /dev/null
@@ -1,28 +0,0 @@
-
-In a sectioned file, the line that marks the end of a section is not
-normally included in the defined region (that is, it is recognized as a
-delimiter, but it is not included as one of the lines available for editing).
-Setting this option to true makes it included. e.g. in this example
-
-@verbatim
-/var/log/mail.log {
- monthly
- missingok
- notifempty
- rotate 7
- }
-@end verbatim
-@noindent the section does not normally include the line containing @samp{@}}.
-By setting @code{include_end_delimiter} to @samp{true}it would be possible
-for example, to delete the entire section, including the section trailer. If
-however @code{include_end_delimiter} is @samp{false}, the @i{contents} of
-the section could be deleted, but the header would be unaffected by any
-@code{delete_lines} promises.
-
-The use of @code{include_start_delimiter} and @code{include_end_delimiter}
-depend on the type of sections you are dealing with, and what you want to do
-with them. Note that sections can be bounded at both the start and end (as
-in the example above) or just at the start (as in the sample shown in
-@code{include_start_delimiter}).
-
-@b{History}: This attribute was introduced in CFEngine version 3.0.5 (2010)
diff --git a/docs/reference/bodyparts/include_start_delimiter_example.texinfo b/docs/reference/bodyparts/include_start_delimiter_example.texinfo
deleted file mode 100644
index 5171d03301..0000000000
--- a/docs/reference/bodyparts/include_start_delimiter_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-body select_region MySection(x)
-{
-select_start => "\[$(x)\]";
-select_end => "\[.*\]";
-include_start_delimiter => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/include_start_delimiter_notes.texinfo b/docs/reference/bodyparts/include_start_delimiter_notes.texinfo
deleted file mode 100644
index 5c476158a7..0000000000
--- a/docs/reference/bodyparts/include_start_delimiter_notes.texinfo
+++ /dev/null
@@ -1,21 +0,0 @@
-
-In a sectioned file, the line that marks the opening of a section is not
-normally included in the defined region (that is, it is recognized as a
-delimiter, but it is not included as one of the lines available for editing).
-Setting this option to true makes it included. e.g. in this example
-
-@verbatim
-[My section]
-one
-two
-three
-@end verbatim
-@noindent the section does not normally include the line @samp{[My section]}.
-By setting @code{include_start_delimiter} to @samp{true}it would be possible
-for example, to delete the entire section, including the section header. If
-however @code{include_start_delimiter} is @samp{false}, the @i{contents} of
-the section could be deleted, but the header would be unaffected by any
-@code{delete_lines} promises. See the next section on
-@code{include_start_delimiter} for further details.
-
-@b{History}: This attribute was introduced in CFEngine version 3.0.5 (2010)
diff --git a/docs/reference/bodyparts/inform_example.texinfo b/docs/reference/bodyparts/inform_example.texinfo
deleted file mode 100644
index f45aa6a766..0000000000
--- a/docs/reference/bodyparts/inform_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-inform => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/inform_notes.texinfo b/docs/reference/bodyparts/inform_notes.texinfo
deleted file mode 100644
index d4df8a1aea..0000000000
--- a/docs/reference/bodyparts/inform_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-Equivalent to (and when present, overrides) the command line option @samp{-I}.
-Sets the default output level `permanently' within the class context indicated.
-
-Every promiser makes an implicit default promise to use output settings declared
-using @code{outputs} promises.
diff --git a/docs/reference/bodyparts/inherit_aces_example.texinfo b/docs/reference/bodyparts/inherit_aces_example.texinfo
deleted file mode 100644
index f93ce87b0f..0000000000
--- a/docs/reference/bodyparts/inherit_aces_example.texinfo
+++ /dev/null
@@ -1,28 +0,0 @@
-
-@verbatim
-
-body acl template
-
-{
-acl_method => "overwrite";
-
-acl_type => "specify";
-
-acl_default => "access";
-
-aces => {
- "user:*:r(wwx),-r:allow",
- "group:*:+rw:allow",
- "mask:x:allow",
- "all:r"
- };
-
-default_aces => {
- "user:*:r(wwx),-r:allow",
- "group:*:+rw:allow",
- "mask:x:allow",
- "all:r"
- };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/inherit_aces_notes.texinfo b/docs/reference/bodyparts/inherit_aces_notes.texinfo
deleted file mode 100644
index a12879ebd5..0000000000
--- a/docs/reference/bodyparts/inherit_aces_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-See notes for @code{aces}.
diff --git a/docs/reference/bodyparts/inherit_example.texinfo b/docs/reference/bodyparts/inherit_example.texinfo
deleted file mode 100644
index 3cc4f028e4..0000000000
--- a/docs/reference/bodyparts/inherit_example.texinfo
+++ /dev/null
@@ -1,17 +0,0 @@
-
-
-@verbatim
-bundle agent name
-{
-methods:
-
- "group name" usebundle => my_method,
- inherit => "true";
-}
-
-
-body edit_defaults example
-{
-inherit => "true";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/inherit_notes.texinfo b/docs/reference/bodyparts/inherit_notes.texinfo
deleted file mode 100644
index 8a4fff2c5d..0000000000
--- a/docs/reference/bodyparts/inherit_notes.texinfo
+++ /dev/null
@@ -1,13 +0,0 @@
-
-@i{History}: Was introduced in 3.4.0, Enterprise 3.0.0 (2012)
-
-@noindent @b{Default value}: false
-
-The @code{inherit} constraint can be added to the CFEngine code in two
-places: for @code{edit_defaults} and in @code{methods} promises. If
-set to true, it causes the child-bundle named in the promise to
-inherit (only) the classes of the parent bundle. Inheriting the
-variables is unnecessary as the child can always access the parent's
-variables by a qualified reference using its bundle name,
-e.g. @samp{$(bundle.variable)}.
-
diff --git a/docs/reference/bodyparts/inputs_example.texinfo b/docs/reference/bodyparts/inputs_example.texinfo
deleted file mode 100644
index 094cc48319..0000000000
--- a/docs/reference/bodyparts/inputs_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-body common control
-{
-inputs => {
- "update.cf",
- "library.cf"
- };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/inputs_notes.texinfo b/docs/reference/bodyparts/inputs_notes.texinfo
deleted file mode 100644
index 8466841803..0000000000
--- a/docs/reference/bodyparts/inputs_notes.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-The filenames specified are all assumed to be in the same directory as the
-file which references them (this is usually @code{$(sys.workdir)/inputs}, but
-may be overridden by the @code{-f} or @code{--file} command line option.
-
-@noindent @b{Default value}:@*
-@*
-
-There is no default value. If no filenames are specified, no other filenames
-will be included in the compilation process.
-
diff --git a/docs/reference/bodyparts/insert_if_contains_from_list_example.texinfo b/docs/reference/bodyparts/insert_if_contains_from_list_example.texinfo
deleted file mode 100644
index 89246116e4..0000000000
--- a/docs/reference/bodyparts/insert_if_contains_from_list_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body insert_select example
-{
-insert_if_contains_from_list => { "find_me_1", "find_me_2" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/insert_if_contains_from_list_notes.texinfo b/docs/reference/bodyparts/insert_if_contains_from_list_notes.texinfo
deleted file mode 100644
index 5707f61d1f..0000000000
--- a/docs/reference/bodyparts/insert_if_contains_from_list_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-The list contains literal strings to search for in the secondary file (the file
-being read via the @code{insert_type} attribute, not the main file being edited).
-If the string is found in a line of the file, that line from the secondary
-file will be inserted at the present location in the primary file.
-
-@code{insert_if_contains_from_list} is ignored unless @code{insert_type} is @code{file}
-(@pxref{insert_type in insert_lines}),
-or the promiser is a multi-line block.
diff --git a/docs/reference/bodyparts/insert_if_match_from_list_example.texinfo b/docs/reference/bodyparts/insert_if_match_from_list_example.texinfo
deleted file mode 100644
index 22ea821726..0000000000
--- a/docs/reference/bodyparts/insert_if_match_from_list_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-
-@verbatim
-
-body insert_select example
-{
-insert_if_match_from_list => { ".*find_.*_1.*", ".*find_.*_2.*" };
-}
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/insert_if_match_from_list_notes.texinfo b/docs/reference/bodyparts/insert_if_match_from_list_notes.texinfo
deleted file mode 100644
index 126e8054b0..0000000000
--- a/docs/reference/bodyparts/insert_if_match_from_list_notes.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-The list contains literal strings to search for in the secondary file
-(the file being read via the @code{insert_type} attribute, not the
-main file being edited). If the regex matches a @i{complete} line of
-the file, that line from the secondary file will be inserted at the
-present location in the primary file. That is, the regex's in the
-list are anchored, @pxref{Anchored vs. unanchored regular expressions}).
-
-@code{insert_if_match_from_list} is ignored unless @code{insert_type}
-is @code{file}, @pxref{insert_type in insert_lines}), or the promiser
-is a multi-line block.
-
diff --git a/docs/reference/bodyparts/insert_if_not_contains_from_list_example.texinfo b/docs/reference/bodyparts/insert_if_not_contains_from_list_example.texinfo
deleted file mode 100644
index fb919c4744..0000000000
--- a/docs/reference/bodyparts/insert_if_not_contains_from_list_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-
-@verbatim
-
-body insert_select example
-{
-insert_if_not_contains_from_list => { "find_me_1", "find_me_2" };
-}
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/insert_if_not_contains_from_list_notes.texinfo b/docs/reference/bodyparts/insert_if_not_contains_from_list_notes.texinfo
deleted file mode 100644
index 558f910ce2..0000000000
--- a/docs/reference/bodyparts/insert_if_not_contains_from_list_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-The complement of @code{insert_if_contains_from_list}. If the line is @i{not}
-found in the secondary file, it is inserted into the file being edited.
-
-@code{insert_if_not_contains_from_list} is ignored unless @code{insert_type} is @code{file}
-(@pxref{insert_type in insert_lines}),
-or the promiser is a multi-line block.
diff --git a/docs/reference/bodyparts/insert_if_not_match_from_list_example.texinfo b/docs/reference/bodyparts/insert_if_not_match_from_list_example.texinfo
deleted file mode 100644
index e3f4e7a6c4..0000000000
--- a/docs/reference/bodyparts/insert_if_not_match_from_list_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-
-@verbatim
-
-body insert_select example
-{
-insert_if_not_match_from_list => { ".*find_.*_1.*", ".*find_.*_2.*" };
-}
-
-@end verbatim
-
-
diff --git a/docs/reference/bodyparts/insert_if_not_match_from_list_notes.texinfo b/docs/reference/bodyparts/insert_if_not_match_from_list_notes.texinfo
deleted file mode 100644
index bb43391968..0000000000
--- a/docs/reference/bodyparts/insert_if_not_match_from_list_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-The complement of @code{insert_if_match_from_list}. If the line does @i{not}
-match a line in the secondary file, it is inserted into the file being edited.
-
-@code{insert_if_not_match_from_list} is ignored unless @code{insert_type} is @code{file}
-(@pxref{insert_type in insert_lines}),
-or the promiser is a multi-line block.
diff --git a/docs/reference/bodyparts/insert_if_not_startwith_from_list_example.texinfo b/docs/reference/bodyparts/insert_if_not_startwith_from_list_example.texinfo
deleted file mode 100644
index 0d233971ce..0000000000
--- a/docs/reference/bodyparts/insert_if_not_startwith_from_list_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-
-@verbatim
-
-body insert_select example
-{
-insert_if_not_startwith_from_list => { "find_me_1", "find_me_2" };
-}
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/insert_if_not_startwith_from_list_notes.texinfo b/docs/reference/bodyparts/insert_if_not_startwith_from_list_notes.texinfo
deleted file mode 100644
index f3bdde6630..0000000000
--- a/docs/reference/bodyparts/insert_if_not_startwith_from_list_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-The complement of @code{insert_if_startwith_from_list}. If the start of a
-line does @i{not} match one of the strings, that line is inserted into the
-file being edited.
-
-@code{insert_if_not_startswith_from_list} is ignored unless @code{insert_type} is @code{file}
-(@pxref{insert_type in insert_lines}),
-or the promiser is a multi-line block.
-
diff --git a/docs/reference/bodyparts/insert_if_startwith_from_list_example.texinfo b/docs/reference/bodyparts/insert_if_startwith_from_list_example.texinfo
deleted file mode 100644
index 8c8cd27c75..0000000000
--- a/docs/reference/bodyparts/insert_if_startwith_from_list_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-
-@verbatim
-
-body insert_select example
-{
-insert_if_startwith_from_list => { "find_me_1", "find_me_2" };
-}
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/insert_if_startwith_from_list_notes.texinfo b/docs/reference/bodyparts/insert_if_startwith_from_list_notes.texinfo
deleted file mode 100644
index e315407e74..0000000000
--- a/docs/reference/bodyparts/insert_if_startwith_from_list_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-The list contains literal strings to search for in the secondary
-file (the file being read via the @code{insert_type} attribute, not
-the main file being edited). If a string with matching starting
-characters is found, then that line from the secondary file will
-be inserted at the present location in the primary file.
-
-@code{insert_if_startswith_from_list} is ignored unless @code{insert_type} is @code{file}
-(@pxref{insert_type in insert_lines}),
-or the promiser is a multi-line block.
diff --git a/docs/reference/bodyparts/insert_type_example.texinfo b/docs/reference/bodyparts/insert_type_example.texinfo
deleted file mode 100644
index 900c712e8d..0000000000
--- a/docs/reference/bodyparts/insert_type_example.texinfo
+++ /dev/null
@@ -1,32 +0,0 @@
-
-@verbatim
-bundle edit_line lynryd_skynyrd
-{
- vars:
- "keepers" slist => { "Won't you give me", "Gimme three steps" };
-
- insert_lines:
-
- "And you'll never see me no more"
- insert_type => "literal"; # the default
-
- "/song/lyrics"
- insert_type => "file", # read selected lines from /song/lyrics
- insert_select => keep("@{keepers}");
-}
-
-body insert_select keep(s)
-{
-insert_if_startwith_from_list => { "@(s)" };
-}
-
-@end verbatim
-
-This will ensure that the following lines are inserted into the promised file:
-
-@verbatim
-And you'll never see me no more
-Gimme three steps, Mister
-Gimme three steps towards the door
-Gimme three steps
-@end verbatim
diff --git a/docs/reference/bodyparts/insert_type_notes.texinfo b/docs/reference/bodyparts/insert_type_notes.texinfo
deleted file mode 100644
index 8c7a447c48..0000000000
--- a/docs/reference/bodyparts/insert_type_notes.texinfo
+++ /dev/null
@@ -1,23 +0,0 @@
-
-The default is to treat the promiser as a literal string of convergent
-lines (the values @code{literal} and @code{string} are synonymonous).
-
-The default behaviour assumes that multi-line entries are not ordered
-specifically, and should be treated as a collection of lines of text
-and not as a single unbroken object.
-
-If the option @samp{preserve_block} is used, then CFEngine will not
-break up multiple lines into individual, non-ordered objects, so that
-the block of text will be preserved. Even if some of the lines in the block
-already exist, they will be added again as a coherent block. Thus if
-you suspect that some stray / conflicting lines might be present they
-should be cleaned up with @code{delete_lines} first.
-
-The value @code{file} is used to tell CFEngine that the string is
-non-literal and should be interpreted as a filename from which to
-import lines, see @ref{insert_select in insert_lines,
-,insert_select}. Inserted files assume non-@samp{preserve_block}
-semantics. An equivalent files setting that does preserve the
-ordering of lines in the file is called @code{file_preserve_block}. This
-was added in CFEngine Core 3.5.x.
-
diff --git a/docs/reference/bodyparts/int_example.texinfo b/docs/reference/bodyparts/int_example.texinfo
deleted file mode 100644
index 0c01b4fc97..0000000000
--- a/docs/reference/bodyparts/int_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-vars:
-
- "scalar" int => "16k";
-
- "ran" int => randomint(4,88);
-
- "dim_array" int => readstringarray("array_name","/etc/passwd","#[^\n]*",":",10,4000);
-
-@end verbatim
diff --git a/docs/reference/bodyparts/int_notes.texinfo b/docs/reference/bodyparts/int_notes.texinfo
deleted file mode 100644
index 6d464730cd..0000000000
--- a/docs/reference/bodyparts/int_notes.texinfo
+++ /dev/null
@@ -1,29 +0,0 @@
-Int variables are strings that are expected to be used as integer numbers. The
-typing in CFEngine is dynamic, so the variable types are interchangable, but
-when you declare a variable to be type @code{int}, CFEngine verifies that
-the value you assign to it looks like an integer (e.g., @samp{3},
-@samp{-17}, @samp{16K}, etc).
-
-Integer values may use suffices @samp{k}, @samp{K}, @samp{m}, @samp{M}, etc.,
-but must only have an integer numeric part (so @samp{1.5M} is not allowed).
-
-@table @samp
-
-@item k
-The value multipled by 1000.
-@item K
-The value multipled by 1024.
-@item m
-The value multipled by 1000 * 1000.
-@item M
-The value multipled by 1024 * 1024.
-@item g
-The value multipled by 1000 * 1000 * 1000.
-@item G
-The value multipled by 1024 * 1024 * 1024.
-@item %
-A percentage between 1 and 100 - mainly for use in a storage context.
-
-@end table
-
-The value @samp{inf} may also be used to represent an unlimited positive value.
diff --git a/docs/reference/bodyparts/intermittency_example.texinfo b/docs/reference/bodyparts/intermittency_example.texinfo
deleted file mode 100644
index e69de29bb2..0000000000
diff --git a/docs/reference/bodyparts/intermittency_notes.texinfo b/docs/reference/bodyparts/intermittency_notes.texinfo
deleted file mode 100644
index e69de29bb2..0000000000
diff --git a/docs/reference/bodyparts/ipv4_address_example.texinfo b/docs/reference/bodyparts/ipv4_address_example.texinfo
deleted file mode 100644
index d53159c0aa..0000000000
--- a/docs/reference/bodyparts/ipv4_address_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body tcp_ip example
-{
-ipv4_address => "123.456.789.001";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/ipv4_address_notes.texinfo b/docs/reference/bodyparts/ipv4_address_notes.texinfo
deleted file mode 100644
index f40416b418..0000000000
--- a/docs/reference/bodyparts/ipv4_address_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-The address will be checked and if necessary set. Today few hosts will
-be managed in this way: address management will be handled by other services
-like DHCP.
diff --git a/docs/reference/bodyparts/ipv4_netmask_example.texinfo b/docs/reference/bodyparts/ipv4_netmask_example.texinfo
deleted file mode 100644
index 958db0f491..0000000000
--- a/docs/reference/bodyparts/ipv4_netmask_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-
-@verbatim
-
-body tcp_ip example
-{
-ipv4_netmask => "255.255.254.0";
-}
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/ipv4_netmask_notes.texinfo b/docs/reference/bodyparts/ipv4_netmask_notes.texinfo
deleted file mode 100644
index 2afbbbd800..0000000000
--- a/docs/reference/bodyparts/ipv4_netmask_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-In many cases the CIDR form of address will show the netmask as @samp{/23}, but
-this offers and `old style' alternative.
diff --git a/docs/reference/bodyparts/ipv6_address_example.texinfo b/docs/reference/bodyparts/ipv6_address_example.texinfo
deleted file mode 100644
index c587f1f360..0000000000
--- a/docs/reference/bodyparts/ipv6_address_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-@verbatim
-
- "eth0"
-
- ipv6_address => "2001:700:700:3:211:63ff:feeb:5d18/64";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/ipv6_address_notes.texinfo b/docs/reference/bodyparts/ipv6_address_notes.texinfo
deleted file mode 100644
index e69de29bb2..0000000000
diff --git a/docs/reference/bodyparts/issymlinkto_example.texinfo b/docs/reference/bodyparts/issymlinkto_example.texinfo
deleted file mode 100644
index 5885e26bfb..0000000000
--- a/docs/reference/bodyparts/issymlinkto_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body file_select example
-{
-issymlinkto => { "/etc/[^/]*", "/etc/init\.d/[a-z0-9]*" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/issymlinkto_notes.texinfo b/docs/reference/bodyparts/issymlinkto_notes.texinfo
deleted file mode 100644
index 09f502bd60..0000000000
--- a/docs/reference/bodyparts/issymlinkto_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-A list of regular expressions. If the file is a symbolic link which
-points to files matched by one of these expressions, the file will be
-selected. As windows does not support symbolic links, this attribute
-is not applicable there.
diff --git a/docs/reference/bodyparts/kept_returncodes_example.texinfo b/docs/reference/bodyparts/kept_returncodes_example.texinfo
deleted file mode 100644
index 4231a6f961..0000000000
--- a/docs/reference/bodyparts/kept_returncodes_example.texinfo
+++ /dev/null
@@ -1,18 +0,0 @@
-@verbatim
-bundle agent cmdtest
-{
-commands:
- "/bin/false"
- classes => example;
-
-reports:
-waskept::
- "The command-promise was kept!";
-}
-
-body classes example
-{
-kept_returncodes => { "0", "1" };
-promise_kept => { "waskept" };
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/kept_returncodes_notes.texinfo b/docs/reference/bodyparts/kept_returncodes_notes.texinfo
deleted file mode 100644
index f002adb7d7..0000000000
--- a/docs/reference/bodyparts/kept_returncodes_notes.texinfo
+++ /dev/null
@@ -1,26 +0,0 @@
-
-A list of integer return codes indicating that a command-related
-promise has been kept. This can in turn be used to define classes
-using the @code{promise_kept} attribute, or merely alter the total
-compliance statistics.
-
-Currently, the attribute has impact on the following command-related
-promises.
-
-@itemize
-@item All promises of type @code{commands:}
-@item @code{files}-promises containing a @code{transformer}-attribute
-@item The package manager change command in @code{packages}-promises
-(e.g. the command for add, remove, etc.)
-@end itemize
-
-
-If none of the attributes @code{kept_returncodes}, @code{repaired_returncodes},
-or @code{failed_returncodes} are set, the default is to consider a
-return code zero as promise repaired, and nonzero as promise failed.
-
-Note that the return codes may overlap, so multiple classes may be set
-from one return code. In Unix systems the possible return codes are
-usually in the range from 0 to 255.
-
-@i{History}: Was introduced in version 3.1.3, Nova 2.0.2 (2010)
diff --git a/docs/reference/bodyparts/keycacheTTL_example.texinfo b/docs/reference/bodyparts/keycacheTTL_example.texinfo
deleted file mode 100644
index b0b928e7f6..0000000000
--- a/docs/reference/bodyparts/keycacheTTL_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@i{History}: Was introduced in version 3.1.0b1,Nova 2.0.0b1 (2010)
-
-
-@verbatim
-
-body server control
-{
-keycacheTTL => "24";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/keycacheTTL_notes.texinfo b/docs/reference/bodyparts/keycacheTTL_notes.texinfo
deleted file mode 100644
index 1466394bb5..0000000000
--- a/docs/reference/bodyparts/keycacheTTL_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-@i{History}: Was introduced in version 3.1.0b1,Nova 2.0.0b1 (2010)
-
diff --git a/docs/reference/bodyparts/lastseen_example.texinfo b/docs/reference/bodyparts/lastseen_example.texinfo
deleted file mode 100644
index 246bf9dd91..0000000000
--- a/docs/reference/bodyparts/lastseen_example.texinfo
+++ /dev/null
@@ -1,21 +0,0 @@
-
-In control:
-@verbatim
-
-body agent control
-{
-lastseen => "false";
-}
-
-@end verbatim
-
-See also in reports:
-@verbatim
-
-reports:
-
- "Comment"
-
- lastseen => "10";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/lastseen_notes.texinfo b/docs/reference/bodyparts/lastseen_notes.texinfo
deleted file mode 100644
index 677fc38ffd..0000000000
--- a/docs/reference/bodyparts/lastseen_notes.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-In reports: after this time (hours) has passed, CFEngine will begin to
-warn about the host being overdue. After the @code{lastseenexpireafter} expiry time, hosts
-will be purged from this host's database (default is a week).
-
-In control: determines whether CFEngine will records last seen
-intermittency profiles (reliability diagnostics) in
-@file{WORKDIR/lastseen}. This generates a separate file for each each
-host that connects to the current host. For central hubs this can
-result is a huge number of files.
diff --git a/docs/reference/bodyparts/lastseenexpireafter_example.texinfo b/docs/reference/bodyparts/lastseenexpireafter_example.texinfo
deleted file mode 100644
index f7abb41a61..0000000000
--- a/docs/reference/bodyparts/lastseenexpireafter_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body common control
-{
-lastseenexpireafter => "72";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/lastseenexpireafter_notes.texinfo b/docs/reference/bodyparts/lastseenexpireafter_notes.texinfo
deleted file mode 100644
index a1e2d9554b..0000000000
--- a/docs/reference/bodyparts/lastseenexpireafter_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-Default time is one week.
diff --git a/docs/reference/bodyparts/leaf_name_example.texinfo b/docs/reference/bodyparts/leaf_name_example.texinfo
deleted file mode 100644
index d796a48fe6..0000000000
--- a/docs/reference/bodyparts/leaf_name_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body file_select example
-{
-leaf_name => { "S[0-9]+[a-zA-Z]+", "K[0-9]+[a-zA-Z]+" };
-file_result => "leaf_name";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/leaf_name_notes.texinfo b/docs/reference/bodyparts/leaf_name_notes.texinfo
deleted file mode 100644
index 1d68bf79d1..0000000000
--- a/docs/reference/bodyparts/leaf_name_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-This pattern matches only the node name of the file, not its path.
diff --git a/docs/reference/bodyparts/link_children_example.texinfo b/docs/reference/bodyparts/link_children_example.texinfo
deleted file mode 100644
index 5c619db8ed..0000000000
--- a/docs/reference/bodyparts/link_children_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body link_from example
-{
-link_children => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/link_children_notes.texinfo b/docs/reference/bodyparts/link_children_notes.texinfo
deleted file mode 100644
index ae0d49667d..0000000000
--- a/docs/reference/bodyparts/link_children_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-If the promiser is a directory, instead of copying the children, link them to the
-source.
diff --git a/docs/reference/bodyparts/link_type_example.texinfo b/docs/reference/bodyparts/link_type_example.texinfo
deleted file mode 100644
index 9328f7154b..0000000000
--- a/docs/reference/bodyparts/link_type_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body link_from example
-{
-link_type => "symlink";
-source => "/tmp/source";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/link_type_notes.texinfo b/docs/reference/bodyparts/link_type_notes.texinfo
deleted file mode 100644
index 7f6e981fd9..0000000000
--- a/docs/reference/bodyparts/link_type_notes.texinfo
+++ /dev/null
@@ -1,13 +0,0 @@
-
-What kind of link should be used to link files. Users are advised to
-be wary of `hard links' (see Unix manual pages for the @samp{ln}
-command). The behaviour of non-symbolic links is often precarious and
-unpredictable. However, hard links are the only supported type by
-windows.
-
-Note that @samp{symlink} is synonymous with @samp{absolute} links, which
-are different from @samp{relative} links. Although all of these are symbolic
-links, the nomenclature here is defined such that @samp{symlink} and
-@samp{absolute} are equivalent . When verifying a link, choosing
-`relative' means that the link @i{must} be relative to the source, so
-relative and absolute links are mutually exclusive.
diff --git a/docs/reference/bodyparts/linkcopy_patterns_example.texinfo b/docs/reference/bodyparts/linkcopy_patterns_example.texinfo
deleted file mode 100644
index c1f949821a..0000000000
--- a/docs/reference/bodyparts/linkcopy_patterns_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-body copy_from mycopy(from)
-
-{
-source => "$(from)";
-linkcopy_patterns => { ".*" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/linkcopy_patterns_notes.texinfo b/docs/reference/bodyparts/linkcopy_patterns_notes.texinfo
deleted file mode 100644
index 8045920a31..0000000000
--- a/docs/reference/bodyparts/linkcopy_patterns_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-The pattern matches the last node filename (i.e. without the absolute
-path). Windows only supports hard links, see @code{link_type}.
-
-
diff --git a/docs/reference/bodyparts/listen_example.texinfo b/docs/reference/bodyparts/listen_example.texinfo
deleted file mode 100644
index 90a4d35dad..0000000000
--- a/docs/reference/bodyparts/listen_example.texinfo
+++ /dev/null
@@ -1,14 +0,0 @@
-
-@verbatim
-
-body server control
-{
-
- listening_host_context::
- listen => "true";
-
- !listening_host_context::
- listen => "false";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/listen_notes.texinfo b/docs/reference/bodyparts/listen_notes.texinfo
deleted file mode 100644
index 79a98d3a97..0000000000
--- a/docs/reference/bodyparts/listen_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@i{History}: Was introduced in 3.4.0, Enterprise 3.0 (2012)
-
-This attribute allows to disable @code{cf-serverd} from listening on any port. Should be used in conjunction with @code{call_collect_interval}.
-
-This setting only applies to CFEngine clients, the policy hub will not be affected. Changing this setting requires a restart of @code{cf-serverd} for the change to take effect.
diff --git a/docs/reference/bodyparts/log_failed_example.texinfo b/docs/reference/bodyparts/log_failed_example.texinfo
deleted file mode 100644
index 48fb5a505e..0000000000
--- a/docs/reference/bodyparts/log_failed_example.texinfo
+++ /dev/null
@@ -1,28 +0,0 @@
-
-@verbatim
-
-bundle agent test
-{
-vars:
-
- "software" slist => { "/root/xyz", "/tmp/xyz" };
-
-files:
-
- "$(software)"
-
- create => "true",
- action => logme("$(software)");
-
-}
-
-
-body action logme(x)
-{
-log_kept => "/tmp/private_keptlog.log";
-log_failed => "/tmp/private_faillog.log";
-log_repaired => "/tmp/private_replog.log";
-log_string => "$(sys.date) $(x) promise status";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/log_failed_notes.texinfo b/docs/reference/bodyparts/log_failed_notes.texinfo
deleted file mode 100644
index e8684b5d29..0000000000
--- a/docs/reference/bodyparts/log_failed_notes.texinfo
+++ /dev/null
@@ -1,21 +0,0 @@
-
-If this option is specified together with @code{log_string}, the
-current promise will log promise-kept status using the log string to
-this named file. If these log names are absent, the default logging
-destination for the log string is syslog, but only for non-kept
-promises. Only the @code{log_string} is affected by this setting. Other messages
-destined for logging are sent to syslog.
-
-It is intended that named file logs should be different for the three
-cases: promise kept, promise not kept and promise repaired.
-This string should be the full path to a text file which will contain
-the log, of one of the following special values:
-
-@table @samp
-@item stdout
-Send the log message to the standard output, prefixed with an @samp{L:} to indicate a log message.
-@item udp_syslog
-Attempt to connect to the @code{syslog_server} defined in @samp{body common control} and log the message there,
-assuming the server is configured to receive the request.
-@end table
-
diff --git a/docs/reference/bodyparts/log_file_growing_example.texinfo b/docs/reference/bodyparts/log_file_growing_example.texinfo
deleted file mode 100644
index fcab81be65..0000000000
--- a/docs/reference/bodyparts/log_file_growing_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-
-@verbatim
-
-body match_value example
-{
-select_line_matching => "Expression match.* whole line";
-log_file_growing => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/log_file_growing_notes.texinfo b/docs/reference/bodyparts/log_file_growing_notes.texinfo
deleted file mode 100644
index 51b8188eca..0000000000
--- a/docs/reference/bodyparts/log_file_growing_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-If true, CFEngine behaves like @samp{tail -f}, sampling the recent
-entries in the file relative to the last measurement. If the file size
-is less than the position remembered at the end of the last
-measurement, @code{cf-monitord} assumes that the file has been
-truncated and starts again from the beginning.
diff --git a/docs/reference/bodyparts/log_kept.example.texinfo b/docs/reference/bodyparts/log_kept.example.texinfo
deleted file mode 100644
index 9884886c28..0000000000
--- a/docs/reference/bodyparts/log_kept.example.texinfo
+++ /dev/null
@@ -1,29 +0,0 @@
-
-@verbatim
-
-bundle agent test
-{
-vars:
-
- "software" slist => { "/root/xyz", "/tmp/xyz" };
-
-files:
-
- "$(software)"
-
- create => "true",
- action => logme("$(software)");
-
-}
-
-
-body action logme(x)
-{
-log_kept => "/tmp/private_keptlog.log";
-log_failed => "/tmp/private_faillog.log";
-log_repaired => "/tmp/private_replog.log";
-log_string => "$(sys.date) $(x) promise status";
-}
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/log_kept_example.texinfo b/docs/reference/bodyparts/log_kept_example.texinfo
deleted file mode 100644
index ae41734c90..0000000000
--- a/docs/reference/bodyparts/log_kept_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-body action logme(x)
-{
-log_kept => "/tmp/private_keptlog.log";
-log_failed => "/tmp/private_faillog.log";
-log_repaired => "/tmp/private_replog.log";
-log_string => "$(sys.date) $(x) promise status";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/log_kept_notes.texinfo b/docs/reference/bodyparts/log_kept_notes.texinfo
deleted file mode 100644
index 7182e03648..0000000000
--- a/docs/reference/bodyparts/log_kept_notes.texinfo
+++ /dev/null
@@ -1,22 +0,0 @@
-
-If this option is specified together with @code{log_string}, the
-current promise will log promise-kept status using the log string to
-this named file. If these log names are absent, the default logging
-destination for the log string is syslog, but only for non-kept
-promises. Only the @code{log_string} is affected by this setting. Other messages
-destined for logging are sent to syslog.
-
-It is intended that named file logs should be different for the three
-cases: promise kept, promise not kept and promise repaired.
-
-This string should be the full path to a text file which will contain
-the log, of one of the following special values:
-
-@table @samp
-@item stdout
-Send the log message to the standard output, prefixed with an @samp{L:} to indicate a log message.
-@item udp_syslog
-Attempt to connect to the @code{syslog_server} defined in @samp{body common control} and log the message there,
-assuming the server is configured to receive the request.
-@end table
-
diff --git a/docs/reference/bodyparts/log_level_example.texinfo b/docs/reference/bodyparts/log_level_example.texinfo
deleted file mode 100644
index bf1daceff7..0000000000
--- a/docs/reference/bodyparts/log_level_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body action example
-{
-log_level => "inform";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/log_level_notes.texinfo b/docs/reference/bodyparts/log_level_notes.texinfo
deleted file mode 100644
index e14ff6daa2..0000000000
--- a/docs/reference/bodyparts/log_level_notes.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-Use this as an alternative to auditing to use the syslog mechanism to centralize
-or manage messaging from CFEngine. A backup of these messages will still be
-kept in @file{WORKDIR/outputs} if you are using @code{cf-execd}.
-
-On native Windows version of CFEngine (Nova or above), using
-@samp{verbose} will include a message when the promise is kept or
-repaired in the event log.
diff --git a/docs/reference/bodyparts/log_priority_example.texinfo b/docs/reference/bodyparts/log_priority_example.texinfo
deleted file mode 100644
index 08155d1a2c..0000000000
--- a/docs/reference/bodyparts/log_priority_example.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-@verbatim
-body action low_priority
-{
-log_priority => "info";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/log_priority_notes.texinfo b/docs/reference/bodyparts/log_priority_notes.texinfo
deleted file mode 100644
index f05dc6f23f..0000000000
--- a/docs/reference/bodyparts/log_priority_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-This determines the importance of messages from CFEngine.
diff --git a/docs/reference/bodyparts/log_repaired_example.texinfo b/docs/reference/bodyparts/log_repaired_example.texinfo
deleted file mode 100644
index f7c4469e17..0000000000
--- a/docs/reference/bodyparts/log_repaired_example.texinfo
+++ /dev/null
@@ -1,32 +0,0 @@
-
-@verbatim
-
-bundle agent test
-{
-vars:
-
- "software" slist => { "/root/xyz", "/tmp/xyz" };
-
-files:
-
- "$(software)"
-
- create => "true",
- action => logme("$(software)");
-
-}
-
-body action logme(x)
-{
-log_kept => "/tmp/private_keptlog.log";
-log_failed => "/tmp/private_faillog.log";
-log_repaired => "/tmp/private_replog.log";
-log_string => "$(sys.date) $(x) promise status";
-}
-
-body action immediate_syslog(x)
-{
-log_repaired => "udp_syslog"; # Nova and above
-log_string => "CFEngine repaired promise $(this.handle) - $(x)";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/log_repaired_notes.texinfo b/docs/reference/bodyparts/log_repaired_notes.texinfo
deleted file mode 100644
index 404bbf2cf9..0000000000
--- a/docs/reference/bodyparts/log_repaired_notes.texinfo
+++ /dev/null
@@ -1,13 +0,0 @@
-
-This may be the name of a log to which the @code{log_string} is written if a promise is repaired.
-It should be the full path to a text file which will contain the log, of one of the following special
-values:
-
-@table @samp
-@item stdout
-Send the log message to the standard output, prefixed with an @samp{L:} to indicate a log message.
-@item udp_syslog
-Attempt to connect to the @code{syslog_server} defined in @samp{body common control} and log the message there,
-assuming the server is configured to receive the request.
-@end table
-
diff --git a/docs/reference/bodyparts/log_string_example.texinfo b/docs/reference/bodyparts/log_string_example.texinfo
deleted file mode 100644
index 095ca39bb9..0000000000
--- a/docs/reference/bodyparts/log_string_example.texinfo
+++ /dev/null
@@ -1,18 +0,0 @@
-
-@example
-
-@var{promise-type}:
-
- "promiser"
-
- attr => "value",
- action => log_me("checked $(this.promiser) in promise $(this.handle)");
-
-# ..
-
-body action log_me(s)
-@{
-log_string => "$(s)";
-@}
-
-@end example
diff --git a/docs/reference/bodyparts/log_string_notes.texinfo b/docs/reference/bodyparts/log_string_notes.texinfo
deleted file mode 100644
index 10e83e7b3e..0000000000
--- a/docs/reference/bodyparts/log_string_notes.texinfo
+++ /dev/null
@@ -1,15 +0,0 @@
-
-The @code{log_string} works together with @code{log_repair},
-@code{log_kept} etc, to define a string for logging to one of the named
-files depending on promise outcome, or to standard output of the log file
-is stipulared as @samp{stdout}. Log strings on standard output are denoted
-by an @samp{L:} prefix.
-
-Note that @code{log_string} does not interact with @code{log_level},
-which is about regular system output messages.
-
-Hint: the promise handle @samp{$(this.handle)} can be a useful
-referent in a log message, indicating the origin of the message. In
-CFEngine Nova and above, every promise has a default handle (which is based o
-the filename and line number - specifying your own handle will probably be
-more mnemonic)..
diff --git a/docs/reference/bodyparts/logallconnections_example.texinfo b/docs/reference/bodyparts/logallconnections_example.texinfo
deleted file mode 100644
index 178f9b9e29..0000000000
--- a/docs/reference/bodyparts/logallconnections_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body server control
-{
-logallconnections => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/logallconnections_notes.texinfo b/docs/reference/bodyparts/logallconnections_notes.texinfo
deleted file mode 100644
index 8ff469aefd..0000000000
--- a/docs/reference/bodyparts/logallconnections_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-If set, the server will record connection attempts in syslog.
-
diff --git a/docs/reference/bodyparts/logencryptedtransfers_example.texinfo b/docs/reference/bodyparts/logencryptedtransfers_example.texinfo
deleted file mode 100644
index 601b9c21e5..0000000000
--- a/docs/reference/bodyparts/logencryptedtransfers_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body server control
-{
-logencryptedtransfers => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/logencryptedtransfers_notes.texinfo b/docs/reference/bodyparts/logencryptedtransfers_notes.texinfo
deleted file mode 100644
index 1029386df8..0000000000
--- a/docs/reference/bodyparts/logencryptedtransfers_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-If true the server will log all transfers of files which the server
-requires to encrypted in order to grant access (see
-@code{ifencrypted}) to syslog. These files are deemed to be
-particularly sensitive.
diff --git a/docs/reference/bodyparts/mailfrom_example.texinfo b/docs/reference/bodyparts/mailfrom_example.texinfo
deleted file mode 100644
index 6626f00a77..0000000000
--- a/docs/reference/bodyparts/mailfrom_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body executor control
-{
-mailfrom => "mrcfengine@example.org";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/mailfrom_notes.texinfo b/docs/reference/bodyparts/mailfrom_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/bodyparts/mailfrom_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/bodyparts/mailmaxlines_example.texinfo b/docs/reference/bodyparts/mailmaxlines_example.texinfo
deleted file mode 100644
index 4fb5213813..0000000000
--- a/docs/reference/bodyparts/mailmaxlines_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body executor control
-{
-mailmaxlines => "100";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/mailmaxlines_notes.texinfo b/docs/reference/bodyparts/mailmaxlines_notes.texinfo
deleted file mode 100644
index 8f8f55fb90..0000000000
--- a/docs/reference/bodyparts/mailmaxlines_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-This limit prevents anomalously large outputs from clogging up a
-system administrator's mailbox. The output is truncated in the email
-report, but the complete original transcript is stored in
-@file{WORKDIR/outputs/*} where it can be viewed on demand.
-A reference to the appropriate file is given.
diff --git a/docs/reference/bodyparts/mailto_example.texinfo b/docs/reference/bodyparts/mailto_example.texinfo
deleted file mode 100644
index bf896f65f1..0000000000
--- a/docs/reference/bodyparts/mailto_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body executor control
-{
-mailto => "cfengine_alias@example.org";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/mailto_notes.texinfo b/docs/reference/bodyparts/mailto_notes.texinfo
deleted file mode 100644
index 48a3d1cc8a..0000000000
--- a/docs/reference/bodyparts/mailto_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-The address to whom email is sent if an smtp host is configured.
diff --git a/docs/reference/bodyparts/maproot_example.texinfo b/docs/reference/bodyparts/maproot_example.texinfo
deleted file mode 100644
index c96e27eba7..0000000000
--- a/docs/reference/bodyparts/maproot_example.texinfo
+++ /dev/null
@@ -1,15 +0,0 @@
-
-@verbatim
-
-access:
-
- "/home"
-
- admit => { "backup_host.example.org" },
- ifencrypted => "true",
-
- # Backup needs to have access to all users
-
- maproot => { "backup_host.example.org" };
-
-@end verbatim
diff --git a/docs/reference/bodyparts/maproot_notes.texinfo b/docs/reference/bodyparts/maproot_notes.texinfo
deleted file mode 100644
index c6231458a1..0000000000
--- a/docs/reference/bodyparts/maproot_notes.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-Normally users authenticated by the server are granted access only to
-files owned by them and no-one else.
-Even if the @code{cf-serverd} process runs with root privileges on the
-server side of a client-server connection, the client is not automatically
-granted access to download files owned by non-privileged users. If @code{maproot}
-is true then remote @code{root} users are granted access to all files.
-
-A typical case where mapping is important is in making backups of many
-user files. On the Windows @code{cf-serverd}, @code{maproot} is
-required to read files if the connecting user does not own the file on
-the server.
diff --git a/docs/reference/bodyparts/match_range_example.texinfo b/docs/reference/bodyparts/match_range_example.texinfo
deleted file mode 100644
index a2b1573f96..0000000000
--- a/docs/reference/bodyparts/match_range_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body process_count example
-{
-match_range => irange("10","50");
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/match_range_notes.texinfo b/docs/reference/bodyparts/match_range_notes.texinfo
deleted file mode 100644
index 5a705ef97a..0000000000
--- a/docs/reference/bodyparts/match_range_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-This is a numerical range for the number of occurrences of the
-process in the process table. As long as it falls within the specified
-limits, the promise is considered kept.
diff --git a/docs/reference/bodyparts/max_children_example.texinfo b/docs/reference/bodyparts/max_children_example.texinfo
deleted file mode 100644
index 1674f93634..0000000000
--- a/docs/reference/bodyparts/max_children_example.texinfo
+++ /dev/null
@@ -1,17 +0,0 @@
-
-@verbatim
-
-body runagent control
-{
-max_children => "10";
-}
-
-# or
-
-body agent control
-{
-max_children => "10";
-}
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/max_children_notes.texinfo b/docs/reference/bodyparts/max_children_notes.texinfo
deleted file mode 100644
index 0041d04938..0000000000
--- a/docs/reference/bodyparts/max_children_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-For the run-agent this represents the maximum number of forked
-background processes allowed when parallelizing connections to
-servers. For the agent it represents the number of background jobs
-allowed concurrently. Background jobs often lead to contention of
-the disk resources slowing down tasks considerably; there is thus a law
-of diminishing returns.
diff --git a/docs/reference/bodyparts/max_file_size_example.texinfo b/docs/reference/bodyparts/max_file_size_example.texinfo
deleted file mode 100644
index 58a25b8fea..0000000000
--- a/docs/reference/bodyparts/max_file_size_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body edit_defaults example
-{
-max_file_size => "50K";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/max_file_size_notes.texinfo b/docs/reference/bodyparts/max_file_size_notes.texinfo
deleted file mode 100644
index 5959d3629d..0000000000
--- a/docs/reference/bodyparts/max_file_size_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-A local, per-file sanity check to make sure the file editing is sensible.
-If this is set to zero, the check is disabled and any size may be edited.
-The default value of @code{max_file_size} is determined by the global
-control body setting, @xref{editfilesize in agent}, whose default value is
-@code{100k}.
diff --git a/docs/reference/bodyparts/maxconnections_example.texinfo b/docs/reference/bodyparts/maxconnections_example.texinfo
deleted file mode 100644
index 92830d3fc9..0000000000
--- a/docs/reference/bodyparts/maxconnections_example.texinfo
+++ /dev/null
@@ -1,18 +0,0 @@
-
-@verbatim
-
-# client side
-
-body agent control
-{
-maxconnections => "1000";
-}
-
-# server side
-
-body server control
-{
-maxconnections => "1000";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/maxconnections_notes.texinfo b/docs/reference/bodyparts/maxconnections_notes.texinfo
deleted file mode 100644
index 624f1b54a3..0000000000
--- a/docs/reference/bodyparts/maxconnections_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Watch out for kernel limitations for maximum numbers of open file descriptors
-which can limit this.
diff --git a/docs/reference/bodyparts/measurement_class_example.texinfo b/docs/reference/bodyparts/measurement_class_example.texinfo
deleted file mode 100644
index e277fbdae8..0000000000
--- a/docs/reference/bodyparts/measurement_class_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-
-body action measure
-{
-measurement_class => "$(this.promiser) long job scan of /usr";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/measurement_class_notes.texinfo b/docs/reference/bodyparts/measurement_class_notes.texinfo
deleted file mode 100644
index 8d411134f8..0000000000
--- a/docs/reference/bodyparts/measurement_class_notes.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-By setting this string you switch on performance measurement for the
-current promise, and also give the measurement a name. The identifier forms a
-partial identity for optional performance scanning of promises of the form:
-
-@example
-@var{ID:promise-type:promiser}.
-@end example
-
-These can be seen identifying using @code{cf-report}, e.g. in the
-generated file @file{performance.html}.
diff --git a/docs/reference/bodyparts/meta_example.texinfo b/docs/reference/bodyparts/meta_example.texinfo
deleted file mode 100644
index 8389dab738..0000000000
--- a/docs/reference/bodyparts/meta_example.texinfo
+++ /dev/null
@@ -1,13 +0,0 @@
-
-@verbatim
-
-files:
-
- "/etc/special_file"
-
- comment => "Special file is a requirement. Talk to Fred X.",
- create => "true",
-
- meta => { "owner=John", "version=2.0" };
-
-@end verbatim
diff --git a/docs/reference/bodyparts/meta_notes.texinfo b/docs/reference/bodyparts/meta_notes.texinfo
deleted file mode 100644
index c4b9e3bb98..0000000000
--- a/docs/reference/bodyparts/meta_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@i{History}: Was introduced in 3.3.0, Nova 2.2.0 (2012)
-
-Attending to knowledge management, it is sometimes convenient to
-attach meta-data of a more technical nature to policy. It may be
-used for arbitrary key=value strings for example.
diff --git a/docs/reference/bodyparts/mode_example.texinfo b/docs/reference/bodyparts/mode_example.texinfo
deleted file mode 100644
index 22eb23a7fd..0000000000
--- a/docs/reference/bodyparts/mode_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body perms example
-{
-mode => "a+rx,o+w";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/mode_notes.texinfo b/docs/reference/bodyparts/mode_notes.texinfo
deleted file mode 100644
index fa74027547..0000000000
--- a/docs/reference/bodyparts/mode_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-The mode string may be symbolic or numerical, like @code{chmod}. This
-is ignored on windows, as the permission model uses ACLs. ACLs are
-supported by CFEngine Nova.
diff --git a/docs/reference/bodyparts/module_example.texinfo b/docs/reference/bodyparts/module_example.texinfo
deleted file mode 100644
index b3862939de..0000000000
--- a/docs/reference/bodyparts/module_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-commands:
-
- "/masterfiles/user_script"
-
- module => "true";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/module_notes.texinfo b/docs/reference/bodyparts/module_notes.texinfo
deleted file mode 100644
index 9d64a8bd45..0000000000
--- a/docs/reference/bodyparts/module_notes.texinfo
+++ /dev/null
@@ -1,149 +0,0 @@
-
-If true, the module protocol is supported for this script, i.e. it is
-treated as a user module. A plug-in module may be written in any
-language, it can return any output you like, but lines which begin
-with a @samp{+} sign are treated as classes to be defined (like
-@option{-D}), while lines which begin with a @samp{-} sign are treated
-as classes to be undefined (like @option{-N}). Lines starting with
-@samp{=} are scalar variables to be defined, and lines beginning with
-@samp{@@} are lists. Any other lines of output are cited by
-@code{cf-agent} as being erroneous, so you should normally make your
-module completely silent. Here is an example written in shell:
-
-@smallexample
-#!/bin/sh
-/bin/echo "@@mylist= @{ \"one\", \"two\", \"three\" @}"
-/bin/echo "=myscalar= scalar val"
-/bin/echo "+module_class"
-@end smallexample
-And here is an example using it:
-@verbatim
-body common control
- {
- any::
-
- bundlesequence => {
- def,
- modtest
- };
- }
-
-###################################################################
-
-bundle agent def
-
-{
-commands:
-
- "$(sys.workdir)/modules/module_name" module => "true";
-
-reports:
-
- #
- # Each module forms a private context with its name as id
- #
-
- module_class::
-
- "Module set variable $(module_name.myscalar)";
-
-}
-
-###################################################################
-
-bundle agent modtest
-
-{
-vars:
-
- "mylist" slist => { @(module_name.mylist) };
-
-reports:
-
- module_class::
-
- "Module set variable $(mylist)";
-
-}
-
-@end verbatim
-Here is an example module written in perl.
-
-@smallexample
-#!/usr/bin/perl
-#
-# module:myplugin
-#
-
- # lots of computation....
-
-if (@var{special-condition})
- @{
- print "+specialclass";
- @}
-
-@end smallexample
-
-If your module is ``simple'' and is best expressed as a shell command, then
-we suggest that you @i{expose} the class being defined in the command being
-executed (making it easier to see what classes are used when reading the
-promises file). For example, the promises could read as follows (the two
-@code{echo} commands are to ensure that the shell always exits with a
-successful execution of a command):
-
-@verbatim
-bundle agent sendmail
-{
-commands:
- # This next module checks a specific failure mode of dcc, namely
- # more than 3 error states since the last time we ran cf-agent
- is_mailhost::
- "/bin/test `/usr/bin/tail -100 /var/log/maillog | /usr/bin/grep 'Milter (dcc): to error state' | /usr/bin/wc -l` -gt 3 && echo '+start_dccm' || echo
-''"
- contain => shell_command,
- module => "true";
-
- start_dccm::
- "/var/dcc/libexec/start-dccm"
- contain => not_paranoid;
-}
-
-body contain shell_command
-{
- useshell => "useshell";
-}
-
-body contain not_paranoid
-{
- useshell => "noshell";
- exec_owner => "root";
- umask => "22";
-}
-
-@end verbatim
-
-Modules inherit the environment variables from cfagent and accept arguments, just
-as a regular command does.
-
-@smallexample
-#!/bin/sh
-#
-# module:myplugin
-#
-
-/bin/echo $*
-
-@end smallexample
-
-Modules define variables in @code{cf-agent} by outputting strings of the form
-
-@smallexample
-
-=@var{variablename}=@var{value}
-
-@end smallexample
-
-These variables end up in a context which has the same name as the module.
-When the @code{$(allclasses)} variable becomes too large to manipulate conveniently,
-you can access the complete list of currently defined classes in the file
-@file{/var/cfengine/state/allclasses}.
diff --git a/docs/reference/bodyparts/monitorfacility_example.texinfo b/docs/reference/bodyparts/monitorfacility_example.texinfo
deleted file mode 100644
index 6e8d594726..0000000000
--- a/docs/reference/bodyparts/monitorfacility_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body monitor control
-{
-monitorfacility => "LOG_USER";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/monitorfacility_notes.texinfo b/docs/reference/bodyparts/monitorfacility_notes.texinfo
deleted file mode 100644
index b8bcc400fd..0000000000
--- a/docs/reference/bodyparts/monitorfacility_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-See notes for syslog.
diff --git a/docs/reference/bodyparts/mount_options_example.texinfo b/docs/reference/bodyparts/mount_options_example.texinfo
deleted file mode 100644
index 81cc88f17f..0000000000
--- a/docs/reference/bodyparts/mount_options_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-@verbatim
-body mount example
-{
-mount_options => { "rw", "acls" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/mount_options_notes.texinfo b/docs/reference/bodyparts/mount_options_notes.texinfo
deleted file mode 100644
index 6075c258cb..0000000000
--- a/docs/reference/bodyparts/mount_options_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-This list is concatenated in a form appropriate for the filesystem. The options must be
-legal options for the system mount commands.
diff --git a/docs/reference/bodyparts/mount_server_example.texinfo b/docs/reference/bodyparts/mount_server_example.texinfo
deleted file mode 100644
index ec6f0a0ea1..0000000000
--- a/docs/reference/bodyparts/mount_server_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body mount example
-{
-mount_server => "nfs_host.example.org";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/mount_server_notes.texinfo b/docs/reference/bodyparts/mount_server_notes.texinfo
deleted file mode 100644
index aab7da2ae2..0000000000
--- a/docs/reference/bodyparts/mount_server_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-Hostname or IP address, this could be on a SAN.
diff --git a/docs/reference/bodyparts/mount_source_example.texinfo b/docs/reference/bodyparts/mount_source_example.texinfo
deleted file mode 100644
index 2111c9d472..0000000000
--- a/docs/reference/bodyparts/mount_source_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-@verbatim
-
-body mount example
-{
-mount_source "/location/disk/directory";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/mount_source_notes.texinfo b/docs/reference/bodyparts/mount_source_notes.texinfo
deleted file mode 100644
index c59549ce39..0000000000
--- a/docs/reference/bodyparts/mount_source_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-This is the location on the remote device, server, SAN etc.
diff --git a/docs/reference/bodyparts/mount_type_example.texinfo b/docs/reference/bodyparts/mount_type_example.texinfo
deleted file mode 100644
index 366b1ebe3f..0000000000
--- a/docs/reference/bodyparts/mount_type_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body mount example
-{
-mount_type => "nfs3";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/mount_type_notes.texinfo b/docs/reference/bodyparts/mount_type_notes.texinfo
deleted file mode 100644
index d10a2430e7..0000000000
--- a/docs/reference/bodyparts/mount_type_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-This field is mainly for future extensions.
diff --git a/docs/reference/bodyparts/mountfilesystems_example.texinfo b/docs/reference/bodyparts/mountfilesystems_example.texinfo
deleted file mode 100644
index f2940fafb6..0000000000
--- a/docs/reference/bodyparts/mountfilesystems_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-mountfilesystems => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/mountfilesystems_notes.texinfo b/docs/reference/bodyparts/mountfilesystems_notes.texinfo
deleted file mode 100644
index a0894ee421..0000000000
--- a/docs/reference/bodyparts/mountfilesystems_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Issues the generic command to mount file systems defined in the file system table.
-
diff --git a/docs/reference/bodyparts/move_obstructions_example.texinfo b/docs/reference/bodyparts/move_obstructions_example.texinfo
deleted file mode 100644
index c69a771953..0000000000
--- a/docs/reference/bodyparts/move_obstructions_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-files:
-
- "/tmp/testcopy"
-
- copy_from => mycopy("/tmp/source"),
- move_obstructions => "true",
- depth_search => recurse("inf");
-
-@end verbatim
diff --git a/docs/reference/bodyparts/move_obstructions_notes.texinfo b/docs/reference/bodyparts/move_obstructions_notes.texinfo
deleted file mode 100644
index e13dd710da..0000000000
--- a/docs/reference/bodyparts/move_obstructions_notes.texinfo
+++ /dev/null
@@ -1,13 +0,0 @@
-
-If we have promised to make file @file{X} a link, but it already
-exists as a file, or vice-versa, or if a file is blocking the creation
-of a directory etc, then normally CFEngine will report an error. If
-this is set, existing objects will be moved aside to allow the system
-to heal without intervention. Files and directories are saved/renamed, but
-symbolic links are deleted.
-
-Note that symbolic links for directories are treated as directories, not links.
-This behaviour can be discussed, but the aim is to err on the side of caution.
-Some operating systems (Solaris) use symbolic links in path names. Copying
-to a directory could then result in renaming of the important link, if the behaviour
-were different.
diff --git a/docs/reference/bodyparts/mtime_example.texinfo b/docs/reference/bodyparts/mtime_example.texinfo
deleted file mode 100644
index 91633d145c..0000000000
--- a/docs/reference/bodyparts/mtime_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-body files_select example
-
-{
-# Files modified more than one year ago (i.e., not in mtime range)
-mtime => irange(ago(1,0,0,0,0,0),now);
-file_result => "!mtime";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/mtime_notes.texinfo b/docs/reference/bodyparts/mtime_notes.texinfo
deleted file mode 100644
index 744c703cf5..0000000000
--- a/docs/reference/bodyparts/mtime_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-The file's modification time refers to both modification of content but not other attributes
-such as permissions.
-
diff --git a/docs/reference/bodyparts/namespace_example.texinfo b/docs/reference/bodyparts/namespace_example.texinfo
deleted file mode 100644
index 8687897880..0000000000
--- a/docs/reference/bodyparts/namespace_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-
-@verbatim
-
-body file control
-{
-namespace => "name1";
-}
-
-@end verbatim
-
-For fuller examples see @xref{Name spaces}.
diff --git a/docs/reference/bodyparts/namespace_notes.texinfo b/docs/reference/bodyparts/namespace_notes.texinfo
deleted file mode 100644
index 307a6cccff..0000000000
--- a/docs/reference/bodyparts/namespace_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@i{History}: Was introduced in 3.4.0, Enterprise 3.0.0 (2012)
-
-This directive can be given within any file, outside of body and
-bundle definitions, to change the namespace of subsequent bundles and
-bodies.
diff --git a/docs/reference/bodyparts/newname_example.texinfo b/docs/reference/bodyparts/newname_example.texinfo
deleted file mode 100644
index 8ed583d812..0000000000
--- a/docs/reference/bodyparts/newname_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body rename example(s)
-{
-newname => "$(s)";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/newname_notes.texinfo b/docs/reference/bodyparts/newname_notes.texinfo
deleted file mode 100644
index e69de29bb2..0000000000
diff --git a/docs/reference/bodyparts/no_output_example.texinfo b/docs/reference/bodyparts/no_output_example.texinfo
deleted file mode 100644
index f90091a81c..0000000000
--- a/docs/reference/bodyparts/no_output_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body contain example
-{
-no_output => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/no_output_notes.texinfo b/docs/reference/bodyparts/no_output_notes.texinfo
deleted file mode 100644
index cf876c6086..0000000000
--- a/docs/reference/bodyparts/no_output_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-This is equivalent to piping standard output and error to @file{/dev/null}.
diff --git a/docs/reference/bodyparts/nonalphanumfiles_example.texinfo b/docs/reference/bodyparts/nonalphanumfiles_example.texinfo
deleted file mode 100644
index 783e3756ee..0000000000
--- a/docs/reference/bodyparts/nonalphanumfiles_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-nonalphanumfiles => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/nonalphanumfiles_notes.texinfo b/docs/reference/bodyparts/nonalphanumfiles_notes.texinfo
deleted file mode 100644
index 7471ba7c25..0000000000
--- a/docs/reference/bodyparts/nonalphanumfiles_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-This test is applied in all recursive/depth searches.
-
diff --git a/docs/reference/bodyparts/not_example.texinfo b/docs/reference/bodyparts/not_example.texinfo
deleted file mode 100644
index c4140fb4b3..0000000000
--- a/docs/reference/bodyparts/not_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-classes:
-
- "others" not => "linux|solaris";
- "no_toor" not => userexists("toor");
-
-@end verbatim
diff --git a/docs/reference/bodyparts/not_matching_example.texinfo b/docs/reference/bodyparts/not_matching_example.texinfo
deleted file mode 100644
index c611247b2a..0000000000
--- a/docs/reference/bodyparts/not_matching_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-
-@verbatim
-delete_lines:
-
- # edit /etc/passwd - account names that are not "mark" or "root"
-
- "(mark|root):.*" not_matching => "true";
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/not_matching_notes.texinfo b/docs/reference/bodyparts/not_matching_notes.texinfo
deleted file mode 100644
index 293b7b7846..0000000000
--- a/docs/reference/bodyparts/not_matching_notes.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-
-When this option is true, it negates the pattern match of the promised lines
-(for convenience). @b{NOTE} that this does not negate any condition expressed
-in @code{delete_select} - it only negates the match of the initially promised
-lines.
-
-Note, this makes no sense for multi-line deletions and is therefore
-disallowed. Either a multi-line promiser matches and it should be
-removed (i.e. @code{not_matching} is false) or it doesn't match the
-whole thing and the ordered lines have no meaning anymore as an
-entity. In this case, the lines can be separately stated.
diff --git a/docs/reference/bodyparts/not_notes.texinfo b/docs/reference/bodyparts/not_notes.texinfo
deleted file mode 100644
index cb1bbb6bdc..0000000000
--- a/docs/reference/bodyparts/not_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-This negates the effect of the promiser-pattern regular
-expression. The class in the LHS will only be defined if the class
-expression in the RHS is false.
diff --git a/docs/reference/bodyparts/number_of_lines_example.texinfo b/docs/reference/bodyparts/number_of_lines_example.texinfo
deleted file mode 100644
index 648a39920f..0000000000
--- a/docs/reference/bodyparts/number_of_lines_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body printfile example
-{
-number_of_lines => "10";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/number_of_lines_notes.texinfo b/docs/reference/bodyparts/number_of_lines_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/bodyparts/number_of_lines_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/bodyparts/occurrences_example.texinfo b/docs/reference/bodyparts/occurrences_example.texinfo
deleted file mode 100644
index 3ba68a0a1d..0000000000
--- a/docs/reference/bodyparts/occurrences_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body replace_with example
-{
-occurrences => "first"; # Warning! Using "first" is non-convergent
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/occurrences_notes.texinfo b/docs/reference/bodyparts/occurrences_notes.texinfo
deleted file mode 100644
index 48d70d0bf6..0000000000
--- a/docs/reference/bodyparts/occurrences_notes.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-A policy for string replacement.
-
-@noindent @b{Default value}:@*
-The default value is "all". Using "first" is generally unwise, as it is
-possibly non-convergent (it will change a different matching string each time
-the promise is executed, and may not "catch up" with whatever external action
-is altering the text the promise applies to).
diff --git a/docs/reference/bodyparts/or_example.texinfo b/docs/reference/bodyparts/or_example.texinfo
deleted file mode 100644
index 92caab3449..0000000000
--- a/docs/reference/bodyparts/or_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-classes:
-
- "compound_test"
-
- or => { classmatch("linux_x86_64_2_6_22.*"), "suse_10_3" };
-
-@end verbatim
diff --git a/docs/reference/bodyparts/or_notes.texinfo b/docs/reference/bodyparts/or_notes.texinfo
deleted file mode 100644
index 1bb3026fa0..0000000000
--- a/docs/reference/bodyparts/or_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-A useful construction for writing expressions that contain special functions.
-The class in the LHS will be defined if any one (or more) of the class
-expressions in the RHS are true.
diff --git a/docs/reference/bodyparts/out_of_range_define_example.texinfo b/docs/reference/bodyparts/out_of_range_define_example.texinfo
deleted file mode 100644
index 5966ca95c5..0000000000
--- a/docs/reference/bodyparts/out_of_range_define_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body process_count example(s)
-{
-out_of_range_define => { "process_anomaly", "anomaly_$(s)"};
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/out_of_range_define_notes.texinfo b/docs/reference/bodyparts/out_of_range_define_notes.texinfo
deleted file mode 100644
index ae6d3900e4..0000000000
--- a/docs/reference/bodyparts/out_of_range_define_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Classes to activate remedial promises conditional on this promise failure
-to be kept.
diff --git a/docs/reference/bodyparts/output_directory_example.texinfo b/docs/reference/bodyparts/output_directory_example.texinfo
deleted file mode 100644
index 4176712274..0000000000
--- a/docs/reference/bodyparts/output_directory_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-
-@verbatim
-
-body runagent control
-{
-output_directory => "/tmp/run_output";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/output_directory_notes.texinfo b/docs/reference/bodyparts/output_directory_notes.texinfo
deleted file mode 100644
index 04ca7f5b59..0000000000
--- a/docs/reference/bodyparts/output_directory_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-@i{History}: Was introduced in version 3.2.0, Nova 2.1.0 (2011)
-
-Defines the location for parallelized output to be saved when running @code{cf-runagent}
-in parallel mode.
diff --git a/docs/reference/bodyparts/output_level_example.texinfo b/docs/reference/bodyparts/output_level_example.texinfo
deleted file mode 100644
index ccae19f180..0000000000
--- a/docs/reference/bodyparts/output_level_example.texinfo
+++ /dev/null
@@ -1,17 +0,0 @@
-
-@verbatim
-
-commands:
-
- "/etc/init.d/agent start"
-
- handle => "run_agent",
- ifvarclass => "need_to_run_agent";
-
-outputs:
-
- "run_agent"
-
- output_level => "inform";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/output_level_notes.texinfo b/docs/reference/bodyparts/output_level_notes.texinfo
deleted file mode 100644
index 57d11dd470..0000000000
--- a/docs/reference/bodyparts/output_level_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-With no attribute, @code{verbose} output is assumed.
diff --git a/docs/reference/bodyparts/output_prefix_example.texinfo b/docs/reference/bodyparts/output_prefix_example.texinfo
deleted file mode 100644
index 0ce85b06a2..0000000000
--- a/docs/reference/bodyparts/output_prefix_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body common control
-{
-output_prefix => "my_cf3";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/output_prefix_notes.texinfo b/docs/reference/bodyparts/output_prefix_notes.texinfo
deleted file mode 100644
index 748290f80d..0000000000
--- a/docs/reference/bodyparts/output_prefix_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-On native Windows versions of CFEngine (Nova and above), this string
-is also prefixed messages in the event log.
diff --git a/docs/reference/bodyparts/output_to_file_example.texinfo b/docs/reference/bodyparts/output_to_file_example.texinfo
deleted file mode 100644
index 127394cb89..0000000000
--- a/docs/reference/bodyparts/output_to_file_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body runagent control
-{
-output_to_file => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/output_to_file_notes.texinfo b/docs/reference/bodyparts/output_to_file_notes.texinfo
deleted file mode 100644
index a85656cf5c..0000000000
--- a/docs/reference/bodyparts/output_to_file_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Filenames are chosen automatically and placed in the
-@file{WORKDIR/outputs/@var{hostname}_runagent.out}.
diff --git a/docs/reference/bodyparts/owners_example.texinfo b/docs/reference/bodyparts/owners_example.texinfo
deleted file mode 100644
index 09587dfa04..0000000000
--- a/docs/reference/bodyparts/owners_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body perms example
-{
-owners => { "mark", "wwwrun", "jeang" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/owners_notes.texinfo b/docs/reference/bodyparts/owners_notes.texinfo
deleted file mode 100644
index 7800150248..0000000000
--- a/docs/reference/bodyparts/owners_notes.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-The first user is the reference value that CFEngine will set the file
-to if none of the list items matches the true state of the file. The
-reserved word @samp{none} may be used to match files that are not
-owned by a registered user.
-
-On windows, users can only take ownership of files, never give
-it. Thus, the first user in the list should be the user running the
-CFEngine process (usually ``Administrator''). Additionally, some
-groups may be owners on windows (such as the ``Administrators''
-group).
diff --git a/docs/reference/bodyparts/package_add_command_example.texinfo b/docs/reference/bodyparts/package_add_command_example.texinfo
deleted file mode 100644
index 6fb165e765..0000000000
--- a/docs/reference/bodyparts/package_add_command_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body package_method rpm
-{
-package_add_command => "/bin/rpm -i ";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_add_command_notes.texinfo b/docs/reference/bodyparts/package_add_command_notes.texinfo
deleted file mode 100644
index f327fc5665..0000000000
--- a/docs/reference/bodyparts/package_add_command_notes.texinfo
+++ /dev/null
@@ -1,13 +0,0 @@
-
-This command should install a package when appended with the package
-reference id, formed using the @code{package_name_convention}, using
-the model of (name,version,architecture). If
-@code{package_file_repositories} is specified, the package reference
-id will include the full path to a repoistory containing the package.
-
-Package managers generally expect the name of a package to be passed
-as a parameter. However, in some cases we do not need to pass the name
-of a particular package to the command. Ending the command string with
-@samp{$} prevents CFEngine from appending the package name to the
-string.
-
diff --git a/docs/reference/bodyparts/package_arch_regex_example.texinfo b/docs/reference/bodyparts/package_arch_regex_example.texinfo
deleted file mode 100644
index ec4cc39b92..0000000000
--- a/docs/reference/bodyparts/package_arch_regex_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body package_method rpm
-
-{
-package_list_arch_regex => "[^.]+\.([^.]+)";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_arch_regex_notes.texinfo b/docs/reference/bodyparts/package_arch_regex_notes.texinfo
deleted file mode 100644
index 3878830874..0000000000
--- a/docs/reference/bodyparts/package_arch_regex_notes.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-This is for use when extracting architecture from the name of the
-promiser, i.e. when the architecture is not specified using the
-@code{package_architectures} list. It is a regular expression that
-contains exactly one parenthesized back reference which marks the
-location in the @i{promiser} at which the architecture is specified.
-The regex may match a portion of the string (i.e., it is unanchored,
-@pxref{Anchored vs. unanchored regular expressions}).
-If no architecture is specified for the given package manager, then
-do not define this.
diff --git a/docs/reference/bodyparts/package_architectures_example.texinfo b/docs/reference/bodyparts/package_architectures_example.texinfo
deleted file mode 100644
index ba4c98a6a5..0000000000
--- a/docs/reference/bodyparts/package_architectures_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-packages:
-
- "$(exact_package)"
-
- package_policy => "add",
- package_method => rpm,
- package_architectures => { "x86_64" };
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_architectures_notes.texinfo b/docs/reference/bodyparts/package_architectures_notes.texinfo
deleted file mode 100644
index a67e31e575..0000000000
--- a/docs/reference/bodyparts/package_architectures_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-It is possible to specify a list of packages of different architectures if it is desirable to
-install multiple architectures on the host. If no value is specified, CFEngine makes no promise
-about the result; the package manager's behaviour prevails.
diff --git a/docs/reference/bodyparts/package_changes_example.texinfo b/docs/reference/bodyparts/package_changes_example.texinfo
deleted file mode 100644
index 2f6f89e764..0000000000
--- a/docs/reference/bodyparts/package_changes_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body package_method rpm
-
-{
-package_changes => "bulk";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_changes_notes.texinfo b/docs/reference/bodyparts/package_changes_notes.texinfo
deleted file mode 100644
index e784b82714..0000000000
--- a/docs/reference/bodyparts/package_changes_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-This indicate whether the package manager is capable of handling
-package operations in bulk, i.e. with by given multiple arguments. If
-this is set to @samp{bulk} then multiple arguments will be passed to
-the package commands. If set to @samp{individual} packages will be
-handled one by one. This might add a significant overhead to the
-operations, and also affect the ability of the operating system's
-package manager to handle dependencies.
diff --git a/docs/reference/bodyparts/package_commands_useshell_example.texinfo b/docs/reference/bodyparts/package_commands_useshell_example.texinfo
deleted file mode 100644
index 6eb0a76a5e..0000000000
--- a/docs/reference/bodyparts/package_commands_useshell_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@i{History}: Was introduced in 3.4.0b1.70bd7ea, Nova 2.3.0.a1.3167b00 (2012)
-
-
-@verbatim
-
-Fill me in (./bodyparts/package_commands_useshell_example.texinfo)
-""
-@end verbatim
diff --git a/docs/reference/bodyparts/package_commands_useshell_notes.texinfo b/docs/reference/bodyparts/package_commands_useshell_notes.texinfo
deleted file mode 100644
index fbb54a08c4..0000000000
--- a/docs/reference/bodyparts/package_commands_useshell_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@i{History}: Was introduced in 3.4.0b1.70bd7ea, Nova 2.3.0.a1.3167b00 (2012)
-
-
-@verbatim
-
-Fill me in (./bodyparts/package_commands_useshell_notes.texinfo)
-""
-@end verbatim
diff --git a/docs/reference/bodyparts/package_default_arch_command_example.texinfo b/docs/reference/bodyparts/package_default_arch_command_example.texinfo
deleted file mode 100644
index 393cd8039f..0000000000
--- a/docs/reference/bodyparts/package_default_arch_command_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-@verbatim
-body package_method dpkg
-{
- package_default_arch_command => "/usr/bin/dpkg --print-architecture";
-
- # ...
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/package_default_arch_command_notes.texinfo b/docs/reference/bodyparts/package_default_arch_command_notes.texinfo
deleted file mode 100644
index 29462c9e19..0000000000
--- a/docs/reference/bodyparts/package_default_arch_command_notes.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@i{History}: Was introduced in 3.4.0, Enterprise 3.0.0 (2012)
-
-This command allows CFEngine to detect default architecture of
-packages managed by package manager. As an example, multiarch-enabled
-dpkg only lists architectures explicitly for multiarch-enabled
-packages.
-
-In case this command is not provided, CFEngine treats all packages
-without explicit architecture set as belonging to implicit ``default''
-architecture.
diff --git a/docs/reference/bodyparts/package_delete_command_example.texinfo b/docs/reference/bodyparts/package_delete_command_example.texinfo
deleted file mode 100644
index af52c0a77f..0000000000
--- a/docs/reference/bodyparts/package_delete_command_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body package_method rpm
-
-{
-package_delete_command => "/bin/rpm -e --nodeps";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_delete_command_notes.texinfo b/docs/reference/bodyparts/package_delete_command_notes.texinfo
deleted file mode 100644
index 0adf31bb2c..0000000000
--- a/docs/reference/bodyparts/package_delete_command_notes.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-The command that deletes a package from the system when appended with
-the package reference identifier specified by
-@code{package_name_convention}.
-
-
-Package managers generally expect the name of a package to be passed
-as a parameter. However, in some cases we do not need to pass the name
-of a particular package to the command. Ending the command string with
-@samp{$} prevents CFEngine from appending the package name to the
-string.
-
diff --git a/docs/reference/bodyparts/package_delete_convention_example.texinfo b/docs/reference/bodyparts/package_delete_convention_example.texinfo
deleted file mode 100644
index 4f7d790539..0000000000
--- a/docs/reference/bodyparts/package_delete_convention_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-body package_method freebsd
-
-{
-package_file_repositories => { "/path/to/packages" };
-package_name_convention => "$(name)-$(version).tbz";
-package_delete_convention => "$(name)-$(version)";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_delete_convention_notes.texinfo b/docs/reference/bodyparts/package_delete_convention_notes.texinfo
deleted file mode 100644
index ee0d751d3c..0000000000
--- a/docs/reference/bodyparts/package_delete_convention_notes.texinfo
+++ /dev/null
@@ -1,17 +0,0 @@
-
-This attribute is used when @code{package_policy} is @samp{delete}, or
-@code{package_policy} is @samp{update} and @code{package_file_repositories} is set and
-@code{package_update_command} is not set. It is then used to
-set the pattern for naming the package in the way expected by the
-package manager during the deletion of existing packages.
-
-Three special variables are defined from the extracted data, in a
-private context for use: @samp{$(name)}, @samp{$(version)} and
-@samp{$(arch)}. @samp{version} and @samp{arch} is the version and arch
-(if @code{package_list_arch_regex} is given) of the already installed
-package. Additionally, if @code{package_file_repositories} is defined,
-@samp{$(firstrepo)} can be prepended to expand the first repository
-containing the package, e.g. @samp{$(firstrepo)$(name)-$(version)-$(arch).msi}.
-
-If this is not defined, it defaults to the value of
-@code{package_name_convention}.
diff --git a/docs/reference/bodyparts/package_file_repositories_example.texinfo b/docs/reference/bodyparts/package_file_repositories_example.texinfo
deleted file mode 100644
index add8188043..0000000000
--- a/docs/reference/bodyparts/package_file_repositories_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body package_method filebased
-{
-package_file_repositories => { "/package/repos1", "/packages/repos2" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_file_repositories_notes.texinfo b/docs/reference/bodyparts/package_file_repositories_notes.texinfo
deleted file mode 100644
index 6a7bedaaac..0000000000
--- a/docs/reference/bodyparts/package_file_repositories_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-If specified, CFEngine will assume that the package installation occurs by filename and will
-search the named paths for a package matching the pattern @code{package_name_convention}.
-If found the name will be prefixed to the package name in the package commands.
diff --git a/docs/reference/bodyparts/package_installed_regex_example.texinfo b/docs/reference/bodyparts/package_installed_regex_example.texinfo
deleted file mode 100644
index 65d9968fb8..0000000000
--- a/docs/reference/bodyparts/package_installed_regex_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body package_method yum
-{
-package_installed_regex => ".*installed.*";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_installed_regex_notes.texinfo b/docs/reference/bodyparts/package_installed_regex_notes.texinfo
deleted file mode 100644
index becd5c55e8..0000000000
--- a/docs/reference/bodyparts/package_installed_regex_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-This regular expression must match complete lines in the output
-of the list command that are actually installed packages (that is,
-the regex is anchored, @pxref{Anchored vs. unanchored regular expressions}).
-If all the lines match then the regex can be set of @samp{.*}, however
-most package systems output prefix lines and a variety of human
-padding that needs to be ignored.
diff --git a/docs/reference/bodyparts/package_list_arch_regex_example.texinfo b/docs/reference/bodyparts/package_list_arch_regex_example.texinfo
deleted file mode 100644
index 1f6f23174f..0000000000
--- a/docs/reference/bodyparts/package_list_arch_regex_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body package_method rpm
-{
-package_list_arch_regex => "[^|]+\|[^|]+\|[^|]+\|[^|]+\|\s+([^\s]+).*";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_list_arch_regex_notes.texinfo b/docs/reference/bodyparts/package_list_arch_regex_notes.texinfo
deleted file mode 100644
index e3979d0aaa..0000000000
--- a/docs/reference/bodyparts/package_list_arch_regex_notes.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-A regular expression that contains exactly one parenthesized back
-reference which marks the location in the listed package at which
-the architecture is specified. The regular expression may match a
-portion of the string (that is, it is unanchored,
-@pxref{Anchored vs. unanchored regular expressions}). If no architecture
-is specified for the given package manager, then do not define this
-regex.
diff --git a/docs/reference/bodyparts/package_list_command_example.texinfo b/docs/reference/bodyparts/package_list_command_example.texinfo
deleted file mode 100644
index eb9b032d23..0000000000
--- a/docs/reference/bodyparts/package_list_command_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body package_method rpm
-
-{
-package_list_command => "/bin/rpm -qa --queryformat \"%{name} %{version}-%{release}\n\"";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_list_command_notes.texinfo b/docs/reference/bodyparts/package_list_command_notes.texinfo
deleted file mode 100644
index f5325a9add..0000000000
--- a/docs/reference/bodyparts/package_list_command_notes.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-This command should provide a complete list of the packages installed
-on the system. It might also list packages that are not
-installed. Those should be filtered out using the
-@code{package_installed_regex}.
-
-
-Package managers generally expect the name of a package to be passed as a parameter. However, in some cases
-we do not need to pass the name of a particular package to the command. Ending the command string with @samp{$}
-prevents CFEngine from appending the package name to the string.
-
diff --git a/docs/reference/bodyparts/package_list_name_regex_example.texinfo b/docs/reference/bodyparts/package_list_name_regex_example.texinfo
deleted file mode 100644
index b19de8cbbc..0000000000
--- a/docs/reference/bodyparts/package_list_name_regex_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body package_method rpm
-
-{
-package_list_name_regex => "([^\s]+).*";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_list_name_regex_notes.texinfo b/docs/reference/bodyparts/package_list_name_regex_notes.texinfo
deleted file mode 100644
index 72a4aaa1ee..0000000000
--- a/docs/reference/bodyparts/package_list_name_regex_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-A regular expression that contains exactly one parenthesized back
-reference which marks the name of the package from the package
-listing. The regular expression may match a portion of the string
-(that is, it is unanchored, @pxref{Anchored vs. unanchored regular expressions}).
diff --git a/docs/reference/bodyparts/package_list_update_command_example.texinfo b/docs/reference/bodyparts/package_list_update_command_example.texinfo
deleted file mode 100644
index c67a999ec4..0000000000
--- a/docs/reference/bodyparts/package_list_update_command_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-body package_method xyz
-{
-debian|ubuntu::
-
-package_list_update_command => "/usr/bin/apt-get update";
-package_list_update_ifelapsed => "240"; # 4 hours
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/package_list_update_command_notes.texinfo b/docs/reference/bodyparts/package_list_update_command_notes.texinfo
deleted file mode 100644
index 3ea77128a9..0000000000
--- a/docs/reference/bodyparts/package_list_update_command_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-Not all package managers update their list information from source
-automatically. This command allows a separate update command to be executed at
-intervals determined by @code{package_list_update_ifelapsed}.
-
diff --git a/docs/reference/bodyparts/package_list_update_ifelapsed_example.texinfo b/docs/reference/bodyparts/package_list_update_ifelapsed_example.texinfo
deleted file mode 100644
index c67a999ec4..0000000000
--- a/docs/reference/bodyparts/package_list_update_ifelapsed_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-body package_method xyz
-{
-debian|ubuntu::
-
-package_list_update_command => "/usr/bin/apt-get update";
-package_list_update_ifelapsed => "240"; # 4 hours
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/package_list_update_ifelapsed_notes.texinfo b/docs/reference/bodyparts/package_list_update_ifelapsed_notes.texinfo
deleted file mode 100644
index b9b045e31f..0000000000
--- a/docs/reference/bodyparts/package_list_update_ifelapsed_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Not all package managers update their list information from source
-automatically. This command allows a separate update command to be executed at
-intervals determined by @code{package_list_update_ifelapsed}.
diff --git a/docs/reference/bodyparts/package_list_version_regex_example.texinfo b/docs/reference/bodyparts/package_list_version_regex_example.texinfo
deleted file mode 100644
index 5de6070647..0000000000
--- a/docs/reference/bodyparts/package_list_version_regex_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-body package_method rpm
-
-{
-package_list_version_regex => "[^\s]+ ([^.]+).*";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_list_version_regex_notes.texinfo b/docs/reference/bodyparts/package_list_version_regex_notes.texinfo
deleted file mode 100644
index da00aee865..0000000000
--- a/docs/reference/bodyparts/package_list_version_regex_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-This regular expression should containe exactly one parenthesized
-back-reference that marks the version string of packages listed as
-installed. The regular expression may match a portion of the string
-(that is, it is unanchored, @pxref{Anchored vs. unanchored regular expressions})
diff --git a/docs/reference/bodyparts/package_multiline_start_example.texinfo b/docs/reference/bodyparts/package_multiline_start_example.texinfo
deleted file mode 100644
index fcf374e050..0000000000
--- a/docs/reference/bodyparts/package_multiline_start_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-body package_method solaris (pkgname, spoolfile, adminfile)
-{
-package_changes => "individual";
-package_list_command => "/usr/bin/pkginfo -l";
-package_multiline_start => "\s*PKGINST:\s+[^\s]+";
-...
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_multiline_start_notes.texinfo b/docs/reference/bodyparts/package_multiline_start_notes.texinfo
deleted file mode 100644
index caf189fd32..0000000000
--- a/docs/reference/bodyparts/package_multiline_start_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-This pattern is used in determining when a new package record
-begins. It is used when package managers (like the solaris package
-manager) use multi-line output formats.
-This pattern matches the first line of a new record.
diff --git a/docs/reference/bodyparts/package_name_convention_example.texinfo b/docs/reference/bodyparts/package_name_convention_example.texinfo
deleted file mode 100644
index 2405cc1e1c..0000000000
--- a/docs/reference/bodyparts/package_name_convention_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-body package_method rpm
-
-{
-package_name_convention => "$(name).$(arch).rpm";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_name_convention_notes.texinfo b/docs/reference/bodyparts/package_name_convention_notes.texinfo
deleted file mode 100644
index 523363aac4..0000000000
--- a/docs/reference/bodyparts/package_name_convention_notes.texinfo
+++ /dev/null
@@ -1,15 +0,0 @@
-
-This sets the pattern for naming the package in the way expected by
-the package manager. Three special variables are defined from the
-extracted data, in a private context for use: @samp{$(name)},
-@samp{$(version)} and @samp{$(arch)}.
-Additionally, if @code{package_file_repositories} is defined,
-@samp{$(firstrepo)} can be prepended to expand the first repository
-containing the package, e.g. @samp{$(firstrepo)$(name)-$(version)-$(arch).msi}.
-
-When @code{package_policy} is @samp{update}, and
-@code{package_file_repositories} is specified,
-@code{package_delete_convention} may be used to specify a different
-convention for the delete command.
-
-If this is not defined, it defaults to the value @samp{$(name)}.
diff --git a/docs/reference/bodyparts/package_name_regex_example.texinfo b/docs/reference/bodyparts/package_name_regex_example.texinfo
deleted file mode 100644
index 1ec5f7df26..0000000000
--- a/docs/reference/bodyparts/package_name_regex_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body package_method rpm
-{
-package_name_regex => "([^\s]).*";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_name_regex_notes.texinfo b/docs/reference/bodyparts/package_name_regex_notes.texinfo
deleted file mode 100644
index 3f807610ca..0000000000
--- a/docs/reference/bodyparts/package_name_regex_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-This regular expression is only used when the @i{promiser} contains
-not only the name of the package, but its version and archiecture
-also. In that case, this expression should contain a single parenthesized
-back-reference to extract the name of the package from the string. The
-regex may match a portion of the string (that is, it is unanchored,
-@pxref{Anchored vs. unanchored regular expressions})
diff --git a/docs/reference/bodyparts/package_noverify_regex_example.texinfo b/docs/reference/bodyparts/package_noverify_regex_example.texinfo
deleted file mode 100644
index cbbd8f7f1b..0000000000
--- a/docs/reference/bodyparts/package_noverify_regex_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-body package_method xyz
-
-{
-package_noverify_regex => "Package .* is not installed.*";
-package_verify_command => "/usr/bin/dpkg -s";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_noverify_regex_notes.texinfo b/docs/reference/bodyparts/package_noverify_regex_notes.texinfo
deleted file mode 100644
index 637d298d24..0000000000
--- a/docs/reference/bodyparts/package_noverify_regex_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-A regular expression to match output from a package verification command. If the
-output string matches this expression, the package is deemed broken. The regex
-must match the entire line (that is, it is anchored,
-@pxref{Anchored vs. unanchored regular expressions})
diff --git a/docs/reference/bodyparts/package_noverify_returncode_example.texinfo b/docs/reference/bodyparts/package_noverify_returncode_example.texinfo
deleted file mode 100644
index c255e2f3f3..0000000000
--- a/docs/reference/bodyparts/package_noverify_returncode_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-@verbatim
-body package_method xyz
-{
-package_noverify_returncode => "-1";
-package_verify_command => "/bin/rpm -V";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/package_noverify_returncode_notes.texinfo b/docs/reference/bodyparts/package_noverify_returncode_notes.texinfo
deleted file mode 100644
index 9cace9eccb..0000000000
--- a/docs/reference/bodyparts/package_noverify_returncode_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-For use if a package verification command uses the return code as the signal
-for a failed package verification.
diff --git a/docs/reference/bodyparts/package_patch_arch_regex_example.texinfo b/docs/reference/bodyparts/package_patch_arch_regex_example.texinfo
deleted file mode 100644
index 6493712d0a..0000000000
--- a/docs/reference/bodyparts/package_patch_arch_regex_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body package_method zypper
-{
-package_patch_arch_regex => "";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_patch_arch_regex_notes.texinfo b/docs/reference/bodyparts/package_patch_arch_regex_notes.texinfo
deleted file mode 100644
index f6baf7ad6e..0000000000
--- a/docs/reference/bodyparts/package_patch_arch_regex_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-A few package managers keep a separate notion of patches, as opposed to package updates.
-OpenSuSE, for example, is one of these. This provide an analogous command struct to the
-packages for patch updates. The regular expression must match the entire line (that is,
-it is anchored, @pxref{Anchored vs. unanchored regular expressions}).
diff --git a/docs/reference/bodyparts/package_patch_command_example.texinfo b/docs/reference/bodyparts/package_patch_command_example.texinfo
deleted file mode 100644
index 59e9b11b61..0000000000
--- a/docs/reference/bodyparts/package_patch_command_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-@verbatim
-body package_method zypper
-
-{
-package_patch_command => "/usr/bin/zypper -non-interactive patch";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/package_patch_command_notes.texinfo b/docs/reference/bodyparts/package_patch_command_notes.texinfo
deleted file mode 100644
index 4a9efce56b..0000000000
--- a/docs/reference/bodyparts/package_patch_command_notes.texinfo
+++ /dev/null
@@ -1,14 +0,0 @@
-If the package manager supports patching, this command should patch
-a named package. If only patching of all packages is supported then
-consider running that as a batch operation in
-@code{commands}. Alternatively one can end the command string with a
-@samp{$} symbol, which CFEngine will interpret as an instruction to
-not append package names.
-
-
-Package managers generally expect the name of a package to be passed
-as a parameter. However, in some cases we do not need to pass the name
-of a particular package to the command. Ending the command string with
-@samp{$} prevents CFEngine from appending the package name to the
-string.
-
diff --git a/docs/reference/bodyparts/package_patch_installed_regex_example.texinfo b/docs/reference/bodyparts/package_patch_installed_regex_example.texinfo
deleted file mode 100644
index d37f927e95..0000000000
--- a/docs/reference/bodyparts/package_patch_installed_regex_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body package_method zypper
-{
-package_patch_installed_regex => ".*(Installed|Not Applicable).*";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_patch_installed_regex_notes.texinfo b/docs/reference/bodyparts/package_patch_installed_regex_notes.texinfo
deleted file mode 100644
index aad6de92e9..0000000000
--- a/docs/reference/bodyparts/package_patch_installed_regex_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-A few package managers keep a separate notion of patches, as opposed to package updates.
-OpenSuSE, for example, is one of these. This provide an analogous command struct to the
-packages for patch updates. The regular expression must match the entire string (that is,
-it is anchored, @pxref{Anchored vs. unanchored regular expressions}).
diff --git a/docs/reference/bodyparts/package_patch_list_command_example.texinfo b/docs/reference/bodyparts/package_patch_list_command_example.texinfo
deleted file mode 100644
index 0a5828c512..0000000000
--- a/docs/reference/bodyparts/package_patch_list_command_example.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@verbatim
-
- package_patch_list_command => "/usr/bin/zypper patches";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_patch_list_command_notes.texinfo b/docs/reference/bodyparts/package_patch_list_command_notes.texinfo
deleted file mode 100644
index 7c6b0aabae..0000000000
--- a/docs/reference/bodyparts/package_patch_list_command_notes.texinfo
+++ /dev/null
@@ -1,15 +0,0 @@
-
-This command, if it exists at all, is presumed to generate a list of
-available patches in a format analogous to (but not necessarily the
-same as) the package-list command, of patches that are available
-on the system. Patches might formally be available in the packagae
-manager's view, but if they have already been installed, CFEngine will
-ignore them.
-
-
-Package managers generally expect the name of a package to be passed
-as a parameter. However, in some cases we do not need to pass the name
-of a particular package to the command. Ending the command string with
-@samp{$} prevents CFEngine from appending the package name to the
-string.
-
diff --git a/docs/reference/bodyparts/package_patch_name_regex_example.texinfo b/docs/reference/bodyparts/package_patch_name_regex_example.texinfo
deleted file mode 100644
index 06340eb97e..0000000000
--- a/docs/reference/bodyparts/package_patch_name_regex_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-@verbatim
-
-body package_method zypper
-{
-package_patch_name_regex => "[^|]+\|\s+([^\s]+).*";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/package_patch_name_regex_notes.texinfo b/docs/reference/bodyparts/package_patch_name_regex_notes.texinfo
deleted file mode 100644
index 6f97d68f3c..0000000000
--- a/docs/reference/bodyparts/package_patch_name_regex_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-A few package managers keep a separate notion of patches, as opposed to package updates.
-OpenSuSE, for example, is one of these. This provide an analogous command struct to the
-packages for patch updates. The regular expression may match a partial string (that is,
-it is unanchored, @pxref{Anchored vs. unanchored regular expressions}).
diff --git a/docs/reference/bodyparts/package_patch_version_regex_example.texinfo b/docs/reference/bodyparts/package_patch_version_regex_example.texinfo
deleted file mode 100644
index 5175d8af0d..0000000000
--- a/docs/reference/bodyparts/package_patch_version_regex_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body package_method zypper
-{
-package_patch_version_regex => "[^|]+\|[^|]+\|\s+([^\s]+).*";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_patch_version_regex_notes.texinfo b/docs/reference/bodyparts/package_patch_version_regex_notes.texinfo
deleted file mode 100644
index 6f97d68f3c..0000000000
--- a/docs/reference/bodyparts/package_patch_version_regex_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-A few package managers keep a separate notion of patches, as opposed to package updates.
-OpenSuSE, for example, is one of these. This provide an analogous command struct to the
-packages for patch updates. The regular expression may match a partial string (that is,
-it is unanchored, @pxref{Anchored vs. unanchored regular expressions}).
diff --git a/docs/reference/bodyparts/package_policy_example.texinfo b/docs/reference/bodyparts/package_policy_example.texinfo
deleted file mode 100644
index 8c07198ff9..0000000000
--- a/docs/reference/bodyparts/package_policy_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-packages:
-
- "$(match_package)"
-
- package_policy => "add",
- package_method => xyz;
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_policy_notes.texinfo b/docs/reference/bodyparts/package_policy_notes.texinfo
deleted file mode 100644
index 7af32211ea..0000000000
--- a/docs/reference/bodyparts/package_policy_notes.texinfo
+++ /dev/null
@@ -1,22 +0,0 @@
-
-This decides what fate is intended for the named package.
-
-@table @bullet
-@item add
-Ensure that a package is present (this is the default setting from 3.3.0).
-@item delete
-Ensure that a package is not present.
-@item reinstall
-Delete then add package (warning, non-convergent).
-@item update
-Update the package if an update is available (manager dependent).
-@item addupdate
-Equivalent to @samp{add} if the package is not installed, and
-@samp{update} if it is installed.
-@item patch
-Install one or more patches if available (manager dependent).
-@item verify
-Verify the correctness of the package (manager dependent). The promise
-is kept if the package is installed correctly, not kept
-otherwise. Requires setting @code{package_verify_command}.
-@end table
diff --git a/docs/reference/bodyparts/package_select_example.texinfo b/docs/reference/bodyparts/package_select_example.texinfo
deleted file mode 100644
index 1ada9dce2f..0000000000
--- a/docs/reference/bodyparts/package_select_example.texinfo
+++ /dev/null
@@ -1,13 +0,0 @@
-
-@verbatim
-packages:
-
- "$(exact_package)"
-
- package_policy => "add",
- package_method => xyz,
- package_select => ">=",
- package_architectures => { "x86_64" },
- package_version => "1.2.3-456";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_select_notes.texinfo b/docs/reference/bodyparts/package_select_notes.texinfo
deleted file mode 100644
index b7c987150a..0000000000
--- a/docs/reference/bodyparts/package_select_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-This selects the operator that compares the promiser to the state of the system
-packages currently installed. If the criterion matches, the policy action is
-scheduled for promise-keeping.
diff --git a/docs/reference/bodyparts/package_update_command_example.texinfo b/docs/reference/bodyparts/package_update_command_example.texinfo
deleted file mode 100644
index e51504a58c..0000000000
--- a/docs/reference/bodyparts/package_update_command_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body package_method zypper
-{
-package_update_command => "/usr/bin/zypper -non-interactive update";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_update_command_notes.texinfo b/docs/reference/bodyparts/package_update_command_notes.texinfo
deleted file mode 100644
index 003c950366..0000000000
--- a/docs/reference/bodyparts/package_update_command_notes.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-If supported this should be a command that updates the version of a
-single currently installed package. If only bulk updates are
-supported, consider running this as a single command under
-@code{commands}. The package reference id is appended, with the
-pattern of @code{package_name_convention}.
-
-When @code{package_file_repositories} is specified, the package
-reference id will include the full path to a repoistory containing the
-package. If @code{package_policy} is @samp{update}, and this command
-is not specified, the @code{package_delete_command} and
-@code{package_add_command} will be executed to carry out the update.
diff --git a/docs/reference/bodyparts/package_verify_command_example.texinfo b/docs/reference/bodyparts/package_verify_command_example.texinfo
deleted file mode 100644
index d9c63ef702..0000000000
--- a/docs/reference/bodyparts/package_verify_command_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-body package_method rpm
-
-{
-package_verify_command => "/bin/rpm -V";
-package_noverify_returncode => "-1";
-}
-
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_verify_command_notes.texinfo b/docs/reference/bodyparts/package_verify_command_notes.texinfo
deleted file mode 100644
index b2581227a4..0000000000
--- a/docs/reference/bodyparts/package_verify_command_notes.texinfo
+++ /dev/null
@@ -1,21 +0,0 @@
-
-If available, this is a command to verify an already installed
-package. It is required only when @code{package_policy} is
-@samp{verify}.
-
-The outcome of the command is compared with
-@code{package_noverify_returncode} or @code{package_noverify_regex},
-one of which has to be set when using this command. If the package is
-not installed, the command will not be run --- the promise gets
-flagged as not kept before the verify command executes.
-
-In order for the promise to be considered kept, the package must be
-installed, and the verify command must be successful according to
-@code{package_noverify_returncode} xor @code{package_noverify_regex}.
-
-Package managers generally expect the name of a package to be passed
-as a parameter. However, in some cases we do not need to pass the name
-of a particular package to the command. Ending the command string with
-@samp{$} prevents CFEngine from appending the package name to the
-string.
-
diff --git a/docs/reference/bodyparts/package_version_equal_command_example.texinfo b/docs/reference/bodyparts/package_version_equal_command_example.texinfo
deleted file mode 100644
index 9de1e370d9..0000000000
--- a/docs/reference/bodyparts/package_version_equal_command_example.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-@verbatim
-body package_method deb
-{
-...
-package_version_equal_command => "dpkg --compare-versions ${v1} eq ${v2}";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/package_version_equal_command_notes.texinfo b/docs/reference/bodyparts/package_version_equal_command_notes.texinfo
deleted file mode 100644
index 05bbb72f83..0000000000
--- a/docs/reference/bodyparts/package_version_equal_command_notes.texinfo
+++ /dev/null
@@ -1,17 +0,0 @@
-@i{History}: Was introduced in 3.4.0 (2012)
-
-This attribute allows to override built-in CFEngine algorithm for
-version comparison by calling an external command to check whether the
-passed versions are the same. Some package managers consider textually
-different versions to be the same (e.g. optional epoch component, so
-0:1.0-1 and 1.0-1 versions are the same), and rules for comparing vary
-from package manager to package manager, so override is necessary.
-
-Variables @code{v1} and @code{v2} are substituted with the versions to
-be compared. Command should return code 0 if versions are equal and
-non-zero otherwise.
-
-Note that if package_version_equal_command is not specified, but
-package_version_less_command is, then equality will be tested by
-issuing less comparison twice (v1 equals to v2 if v1 is not less than
-v2, and v2 is not less than v1).
diff --git a/docs/reference/bodyparts/package_version_example.texinfo b/docs/reference/bodyparts/package_version_example.texinfo
deleted file mode 100644
index 8770573f16..0000000000
--- a/docs/reference/bodyparts/package_version_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-packages:
-
- "mypackage"
-
- package_policy => "add",
- package_method => rpm,
- package_select => "==",
- package_version => "1.2.3";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_version_less_command_example.texinfo b/docs/reference/bodyparts/package_version_less_command_example.texinfo
deleted file mode 100644
index b7c59609b6..0000000000
--- a/docs/reference/bodyparts/package_version_less_command_example.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-@verbatim
-body package_method deb
-{
-...
-package_version_less_command => "dpkg --compare-versions ${v1} lt ${v2}";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/package_version_less_command_notes.texinfo b/docs/reference/bodyparts/package_version_less_command_notes.texinfo
deleted file mode 100644
index 1a66f364ac..0000000000
--- a/docs/reference/bodyparts/package_version_less_command_notes.texinfo
+++ /dev/null
@@ -1,18 +0,0 @@
-@i{History}: Was introduced in 3.4.0 (2012)
-
-This attribute allows to override built-in CFEngine algorithm for
-version comparison by calling an external command to check whether the first passed version is less than another.
-
-Built-in algorithm does a good approximation of version comparison,
-but different packaging systems differ in corner cases (e.g Debian
-treats symbol ~ less than any other symbol and even less than empty
-string), so some sort of override is necessary.
-
-Variables @code{v1} and @code{v2} are substituted with the first and
-second version to be compared. Command should return code 0 if v1 is
-less than v2 and non-zero otherwise.
-
-Note that if package_version_equal_command is not specified, but
-package_version_less_command is, then equality will be tested by
-issuing less comparison twice (v1 equals to v2 if v1 is not less than
-v2, and v2 is not less than v1).
diff --git a/docs/reference/bodyparts/package_version_notes.texinfo b/docs/reference/bodyparts/package_version_notes.texinfo
deleted file mode 100644
index 858c5c83c5..0000000000
--- a/docs/reference/bodyparts/package_version_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Used for specifying the targeted package version when the version is written
-separately from the name of the command.
diff --git a/docs/reference/bodyparts/package_version_regex_example.texinfo b/docs/reference/bodyparts/package_version_regex_example.texinfo
deleted file mode 100644
index 7536fd5ccd..0000000000
--- a/docs/reference/bodyparts/package_version_regex_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body package_method rpm
-{
-package_version_regex => "[^\s]+ ([^.]+).*";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/package_version_regex_notes.texinfo b/docs/reference/bodyparts/package_version_regex_notes.texinfo
deleted file mode 100644
index f2c3fe2df2..0000000000
--- a/docs/reference/bodyparts/package_version_regex_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-If the version of a package is not specified separately using
-@code{package_version}, then this should be a regular expression that
-contains exactly one parenthesized back-reference that matches the version
-string in the promiser. The regular expression may match a partial string
-(that is, it is unanchored, @pxref{Anchored vs. unanchored regular expressions}).
diff --git a/docs/reference/bodyparts/path_name_example.texinfo b/docs/reference/bodyparts/path_name_example.texinfo
deleted file mode 100644
index 6f393328cd..0000000000
--- a/docs/reference/bodyparts/path_name_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-body file_select example
-{
-leaf_name => { "prog.pid", "prog.log" };
-path_name => { "/etc/.*", "/var/run/.*" };
-
-file_result => "leaf_name.path_name"
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/path_name_notes.texinfo b/docs/reference/bodyparts/path_name_notes.texinfo
deleted file mode 100644
index 4dfa39452b..0000000000
--- a/docs/reference/bodyparts/path_name_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Path name and leaf name can be conveniently tested for separately by use
-of appropriate regular expressions.
diff --git a/docs/reference/bodyparts/pathtype_example.texinfo b/docs/reference/bodyparts/pathtype_example.texinfo
deleted file mode 100644
index a3281e790c..0000000000
--- a/docs/reference/bodyparts/pathtype_example.texinfo
+++ /dev/null
@@ -1,19 +0,0 @@
-
-@verbatim
-
-files:
-
- "/var/lib\d"
- pathtype => "guess", # best guess (default)
- perms => system;
-
- "/var/lib\d"
- pathtype => "regex", # force regex interpretation
- perms => system;
-
- "/var/.*/lib"
-
- pathtype => "literal", # force literal interpretation
- perms => system;
-
-@end verbatim
diff --git a/docs/reference/bodyparts/pathtype_notes.texinfo b/docs/reference/bodyparts/pathtype_notes.texinfo
deleted file mode 100644
index 51ba684d1e..0000000000
--- a/docs/reference/bodyparts/pathtype_notes.texinfo
+++ /dev/null
@@ -1,27 +0,0 @@
-By default, CFEngine makes an educated guess as to whether the promise
-pathname involves a regular expression or not. This guesswork is needed due
-to cross-platform differences in filename interpretation.
-
-If CFEngine guesses (or is told) that the pathname uses a regular
-expression pattern, it will undertake a file search to find possible
-matches. This can consume significant resources, and so the
-@samp{guess} option will always try to optimize this. Guesswork is,
-however, imperfect, so you have the option to declare your intention.
-
-If the keyword @code{literal} is invoked, a path will be treated as a
-literal string regardless of what characters is contains. If it is
-declared @samp{regex}, it will be treated as a pattern to match.
-
-Note that CFEngine splits the promiser up into path links before
-matching, so that each link in the path chain is matched
-separately. Thus it it meaningless to have a @samp{/} in a regular
-expression, as the comparison will never see this character.
-
-In the examples above, at least one case implies an iteration over all
-files/directories matching the regular expression, while the last case
-means a single literal object with a name composed of dots and stars.
-
-Furthermore, on Windows paths using @code{regex} must use the forward slash
-(@code{/}) as path separator, since the backward slash has a special meaning
-in a regular expression. Literal paths may also use backslash (@code{\}) as a
-path separator, @xref{Regular expressions in paths}, for more information.
diff --git a/docs/reference/bodyparts/persist_time_example.texinfo b/docs/reference/bodyparts/persist_time_example.texinfo
deleted file mode 100644
index fda54e28ab..0000000000
--- a/docs/reference/bodyparts/persist_time_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body classes example
-{
-persist_time => "10";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/persist_time_notes.texinfo b/docs/reference/bodyparts/persist_time_notes.texinfo
deleted file mode 100644
index e58a92479d..0000000000
--- a/docs/reference/bodyparts/persist_time_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-By default classes are ephemeral entities that disappear when @code{cf-agent}
-terminates. By setting a persistence time, they can last even when the agent
-is not running.
diff --git a/docs/reference/bodyparts/persistence_example.texinfo b/docs/reference/bodyparts/persistence_example.texinfo
deleted file mode 100644
index bb13f434c9..0000000000
--- a/docs/reference/bodyparts/persistence_example.texinfo
+++ /dev/null
@@ -1,17 +0,0 @@
-
-
-@verbatim
-bundle common setclasses
-{
-classes:
-
- "cached_classes"
- or => { "any" },
- persistence => "1";
-
- "cached_class"
- expression => "any",
- persistence => "1";
-
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/persistence_notes.texinfo b/docs/reference/bodyparts/persistence_notes.texinfo
deleted file mode 100644
index 3d2e16408e..0000000000
--- a/docs/reference/bodyparts/persistence_notes.texinfo
+++ /dev/null
@@ -1,57 +0,0 @@
-
-@i{History}: Was introduced in 3.4.0, Nova 2.2.0 (2012)
-
-This feature can be used to avoid recomputing expensive classes
-calculations on each invocation. If a class discovered is essentially
-constant or only slowly varying (like a hostname or alias from a
-non-standard naming facility)
-
-For example, to create a conditional inclusion of costly class
-definitions, put them into a separate bundle in a file @file{classes.cf}.
-@verbatim
-# promises.cf
-
-body common control
-{
-cached_classes::
- bundlesequence => { "test" };
-
-!cached_classes::
- bundlesequence => { "setclasses", "test" };
-
-!cached_classes::
- inputs => { "classes.cf" };
-}
-
-
-bundle agent test
-{
-reports:
-
- !my_cached_class::
- "no cached class";
-
- my_cached_class::
- "cached class defined";
-}
-
-@end verbatim
-@noindent Then create @file{classes.cf}
-@verbatim
-# classes.cf
-
-bundle common setclasses
-{
-classes:
-
- "cached_classes" # timer flag
- expression => "any",
- persistence => "480";
-
- "my_cached_class"
- or => { ...long list or heavy function... } ,
- persistence => "480";
-
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/pgid_example.texinfo b/docs/reference/bodyparts/pgid_example.texinfo
deleted file mode 100644
index 64fc03a6e6..0000000000
--- a/docs/reference/bodyparts/pgid_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body process_select example
-{
-pgid => irange("1","10");
-process_result => "pgid";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/pgid_notes.texinfo b/docs/reference/bodyparts/pgid_notes.texinfo
deleted file mode 100644
index 139597f9cb..0000000000
--- a/docs/reference/bodyparts/pgid_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-
diff --git a/docs/reference/bodyparts/pid_example.texinfo b/docs/reference/bodyparts/pid_example.texinfo
deleted file mode 100644
index 64c6ed9fe0..0000000000
--- a/docs/reference/bodyparts/pid_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-body process_select example
-{
-pid => irange("1","10");
-process_result => "pid";
-}
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/pid_notes.texinfo b/docs/reference/bodyparts/pid_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/bodyparts/pid_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/bodyparts/policy_example.texinfo b/docs/reference/bodyparts/policy_example.texinfo
deleted file mode 100644
index d450fb45da..0000000000
--- a/docs/reference/bodyparts/policy_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-vars:
-
- "varid" string => "value...",
- policy => "constant";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/policy_notes.texinfo b/docs/reference/bodyparts/policy_notes.texinfo
deleted file mode 100644
index 0c31a95cdd..0000000000
--- a/docs/reference/bodyparts/policy_notes.texinfo
+++ /dev/null
@@ -1,32 +0,0 @@
-
-Variables can either be allowed to change their value dynamically (be
-redefined) or they can be constant. The use of private variable spaces
-in CFEngine 3 makes it unlikely that variable redefinition would be
-necessary in CFEngine 3.
-
-The value @code{constant} indicates that the variable value may not be
-changed. The values @code{free} and @code{overridable} are synonymous, and
-indicated the the variable's value may be changed.
-
-The value @code{ifdefined} applies only to lists and implies that unexpanded
-or undefined lists are dropped. The default behaviour is otherwise to
-retain this value as an indicator of the failure to quench the variable
-reference, e.g.
-@verbatim
-
- "one" slist => { "1", "2", "3" };
-
- "list" slist => { "@(one)", @(two) },
-
- policy => "ifdefined";
-
-@end verbatim
-@noindent would result in @samp{@@(list)} being the same as @samp{@@(one)},
-and the reference to @samp{@@(two)} would disappear. This is useful for combining
-lists, `inheritance-style' where one can extend a base with special cases if they
-are defined.
-
-@noindent @b{Default value}:@*
-@*
-
-@code{policy => constant}
diff --git a/docs/reference/bodyparts/port_example.texinfo b/docs/reference/bodyparts/port_example.texinfo
deleted file mode 100644
index d6f431be92..0000000000
--- a/docs/reference/bodyparts/port_example.texinfo
+++ /dev/null
@@ -1,18 +0,0 @@
-
-@verbatim
-
-body hub control
-{
-port => "5308";
-}
-
-body server control
-{
-specialhost::
- port => "5308";
-
-!specialhost::
- port => "5308";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/port_notes.texinfo b/docs/reference/bodyparts/port_notes.texinfo
deleted file mode 100644
index 589655d5a2..0000000000
--- a/docs/reference/bodyparts/port_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-The standard or registered port number is tcp/5308. CFEngine does not
-presently use its registered udp port with the same number, but this
-could change in the future.
-
-Changing the standard port number is not recommended practice. You should
-not do it without a good reason.
diff --git a/docs/reference/bodyparts/portnumber_example.texinfo b/docs/reference/bodyparts/portnumber_example.texinfo
deleted file mode 100644
index c7f227bc3b..0000000000
--- a/docs/reference/bodyparts/portnumber_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body copy_from example
-{
-portnumber => "5308";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/portnumber_notes.texinfo b/docs/reference/bodyparts/portnumber_notes.texinfo
deleted file mode 100644
index 57fa323da4..0000000000
--- a/docs/reference/bodyparts/portnumber_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-The standard or registered port number is tcp/5308. CFEngine does not
-presently use its registered udp port with the same number, but this
-could change in the future.
diff --git a/docs/reference/bodyparts/ppid_example.texinfo b/docs/reference/bodyparts/ppid_example.texinfo
deleted file mode 100644
index 6f3a408a91..0000000000
--- a/docs/reference/bodyparts/ppid_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body process_select example
-{
-ppid => irange("407","511");
-process_result => "ppid";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/ppid_notes.texinfo b/docs/reference/bodyparts/ppid_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/bodyparts/ppid_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/bodyparts/precedents_example.texinfo b/docs/reference/bodyparts/precedents_example.texinfo
deleted file mode 100644
index 05e7d08f84..0000000000
--- a/docs/reference/bodyparts/precedents_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-inferences:
-
- "is far from"
- comment => "Remote cluster property",
- precedent => { "is far from"},
- qualifier => { "is close to", "is far from" };
-
-@end verbatim
diff --git a/docs/reference/bodyparts/precedents_notes.texinfo b/docs/reference/bodyparts/precedents_notes.texinfo
deleted file mode 100644
index 0aa99fe66b..0000000000
--- a/docs/reference/bodyparts/precedents_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-@i{History}: Was introduced in version 3.1.0b3,Nova 2.0.0b1 (2010)
-
-A general regular expression may be used to match suitable alternatives, so as to make the
-promise unique.
diff --git a/docs/reference/bodyparts/preserve_example.texinfo b/docs/reference/bodyparts/preserve_example.texinfo
deleted file mode 100644
index 7eaa5a947e..0000000000
--- a/docs/reference/bodyparts/preserve_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body copy_from example
-{
-preserve => "true";
-}
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/preserve_notes.texinfo b/docs/reference/bodyparts/preserve_notes.texinfo
deleted file mode 100644
index c3e66e9024..0000000000
--- a/docs/reference/bodyparts/preserve_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-Ensures the destination file (promiser) gets the same Unix mode
-as the source. This also applies to remote copies.
-
-@i{History}: Was introduced in version 3.1.0b3,Nova 2.0.0b1 (2010)
-
diff --git a/docs/reference/bodyparts/preview_example.texinfo b/docs/reference/bodyparts/preview_example.texinfo
deleted file mode 100644
index d4f7ac827d..0000000000
--- a/docs/reference/bodyparts/preview_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body contain example
-{
-preview => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/preview_notes.texinfo b/docs/reference/bodyparts/preview_notes.texinfo
deleted file mode 100644
index bdbe32ef14..0000000000
--- a/docs/reference/bodyparts/preview_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-Previewing shell scripts during a dry-run is a potentially misleading
-activity. It should only be used on scripts that make no changes to
-the system. It is CFEngine best practice to never write
-change-functionality into user-written scripts except as a last
-resort: CFEngine can apply its safety checks to user defined scripts.
diff --git a/docs/reference/bodyparts/priority_example.texinfo b/docs/reference/bodyparts/priority_example.texinfo
deleted file mode 100644
index b8d41aeae2..0000000000
--- a/docs/reference/bodyparts/priority_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body process_select example
-{
-priority => irange("-5","0");
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/priority_notes.texinfo b/docs/reference/bodyparts/priority_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/bodyparts/priority_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/bodyparts/process_owner_example.texinfo b/docs/reference/bodyparts/process_owner_example.texinfo
deleted file mode 100644
index 313d57f602..0000000000
--- a/docs/reference/bodyparts/process_owner_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body process_select example
-{
-process_owner => { "wwwrun", "nobody" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/process_owner_notes.texinfo b/docs/reference/bodyparts/process_owner_notes.texinfo
deleted file mode 100644
index ed8b26622d..0000000000
--- a/docs/reference/bodyparts/process_owner_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Regular expression should match a legal user name on the system. The regex
-must match the entire name (that is, it is anchored,
-@pxref{Anchored vs. unanchored regular expressions}).
diff --git a/docs/reference/bodyparts/process_result_example.texinfo b/docs/reference/bodyparts/process_result_example.texinfo
deleted file mode 100644
index 033a8638dc..0000000000
--- a/docs/reference/bodyparts/process_result_example.texinfo
+++ /dev/null
@@ -1,15 +0,0 @@
-
-
-@verbatim
-
-body process_select proc_finder(p)
-
-{
-process_owner => { "avahi", "bin" };
-command => "$(p)";
-pid => irange("100","199");
-vsize => irange("0","1000");
-process_result => "command.(process_owner|vsize).!pid";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/process_result_notes.texinfo b/docs/reference/bodyparts/process_result_notes.texinfo
deleted file mode 100644
index 4651f0cd7e..0000000000
--- a/docs/reference/bodyparts/process_result_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-A logical combination of the process selection classifiers. The syntax
-is the same as that for class expressions. There should be no spaces
-in the expressions.
diff --git a/docs/reference/bodyparts/process_stop_example.texinfo b/docs/reference/bodyparts/process_stop_example.texinfo
deleted file mode 100644
index 9783cbdf85..0000000000
--- a/docs/reference/bodyparts/process_stop_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-processes:
-
- "snmpd"
-
- process_stop => "/etc/init.d/snmp stop";
-
-
-@end verbatim
diff --git a/docs/reference/bodyparts/process_stop_notes.texinfo b/docs/reference/bodyparts/process_stop_notes.texinfo
deleted file mode 100644
index 4495580d55..0000000000
--- a/docs/reference/bodyparts/process_stop_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-As an alternative to sending a termination or kill signal to a process,
-one may call a `stop script' to perform a graceful shutdown.
diff --git a/docs/reference/bodyparts/promise_kept_example.texinfo b/docs/reference/bodyparts/promise_kept_example.texinfo
deleted file mode 100644
index 97e0fb67a8..0000000000
--- a/docs/reference/bodyparts/promise_kept_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body classes example
-{
-promise_kept => { "success", "kaplah" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/promise_kept_notes.texinfo b/docs/reference/bodyparts/promise_kept_notes.texinfo
deleted file mode 100644
index cbf46fb7df..0000000000
--- a/docs/reference/bodyparts/promise_kept_notes.texinfo
+++ /dev/null
@@ -1,19 +0,0 @@
-
-This class is set if no action was necessary by @code{cf-agent}
-because the promise concerned was already kept without further action
-required.
-
-Note that any strings passed to this list are automatically
-canonified, so it is unecessary to call a canonify function on such inputs.
-
-Important: complex promises, e.g. @code{files} promises that set
-multiple parameters on a file simultaneously can report misleadingly.
-The classes for different parts of a promise are not separable. Thus,
-if you promise to create and file and change its permissions, when the
-file exists with incorrect permissions, @code{cf-agent} will report
-that the @samp{promise_kept} for the file existence, but
-@samp{promise_repaired} for the permissions. If you need separate
-reports, you should code two separate promises rather than `overloading'
-a single one.
-
-
diff --git a/docs/reference/bodyparts/promise_repaired_example.texinfo b/docs/reference/bodyparts/promise_repaired_example.texinfo
deleted file mode 100644
index 3c6fd6b233..0000000000
--- a/docs/reference/bodyparts/promise_repaired_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body classes example
-{
-promise_repaired => { "change_happened" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/promise_repaired_notes.texinfo b/docs/reference/bodyparts/promise_repaired_notes.texinfo
deleted file mode 100644
index 3cfd2e9f9d..0000000000
--- a/docs/reference/bodyparts/promise_repaired_notes.texinfo
+++ /dev/null
@@ -1,18 +0,0 @@
-
-If a promise is `repaired' it means that a corrective action had to be
-taken to keep the promise.
-
-Note that any strings passed to this list are automatically
-canonified, so it is unecessary to call a canonify function on such inputs.
-
-
-Important: complex promises, e.g. @code{files} promises that set
-multiple parameters on a file simultaneously can report misleadingly.
-The classes for different parts of a promise are not separable. Thus,
-if you promise to create and file and change its permissions, when the
-file exists with incorrect permissions, @code{cf-agent} will report
-that the @samp{promise_kept} for the file existence, but
-@samp{promise_repaired} for the permissions. If you need separate
-reports, you should code two separate promises rather than `overloading'
-a single one.
-
diff --git a/docs/reference/bodyparts/promiser_type_example.texinfo b/docs/reference/bodyparts/promiser_type_example.texinfo
deleted file mode 100644
index 5b73ff431f..0000000000
--- a/docs/reference/bodyparts/promiser_type_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-outputs:
-
- "web_server"
-
- promiser_type => "bundle";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/promiser_type_notes.texinfo b/docs/reference/bodyparts/promiser_type_notes.texinfo
deleted file mode 100644
index 996d83b50d..0000000000
--- a/docs/reference/bodyparts/promiser_type_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Without this attribute, CFEngine assumes a list of promises to report on
-(because there may be a promise for a thing that has the same name as a bundle,
-you must explicitly specify when you want to report on a bundle of promises).
diff --git a/docs/reference/bodyparts/purge_example.texinfo b/docs/reference/bodyparts/purge_example.texinfo
deleted file mode 100644
index a745ca704c..0000000000
--- a/docs/reference/bodyparts/purge_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body copy_from example
-{
-purge => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/purge_notes.texinfo b/docs/reference/bodyparts/purge_notes.texinfo
deleted file mode 100644
index 1d44919a23..0000000000
--- a/docs/reference/bodyparts/purge_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-Purging files is a potentially dangerous matter during a file copy it
-implies that any promiser (destination) file which is not matched by a
-source will be deleted. Since there is no source, this means the file
-will be irretrievable. Great care should be exercised when using this
-feature.
-
-Note that purging will also delete backup files generated during
-the file copying if @code{copy_backup} is set to true.
diff --git a/docs/reference/bodyparts/qualifiers_example.texinfo b/docs/reference/bodyparts/qualifiers_example.texinfo
deleted file mode 100644
index a4410874f6..0000000000
--- a/docs/reference/bodyparts/qualifiers_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-
-@verbatim
-inferences:
-
- "is far from"
- comment => "Remote cluster property",
- precedent => { "is far from" },
- qualifier => { "is close to|is far from" };
-
-@end verbatim
diff --git a/docs/reference/bodyparts/qualifiers_notes.texinfo b/docs/reference/bodyparts/qualifiers_notes.texinfo
deleted file mode 100644
index c21c0906e1..0000000000
--- a/docs/reference/bodyparts/qualifiers_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-@i{History}: Was introduced in version 3.1.0 (2010)
-
-A general regular expression may be used to match suitable alternatives, so as to make the
-promise unique.
diff --git a/docs/reference/bodyparts/real_example.texinfo b/docs/reference/bodyparts/real_example.texinfo
deleted file mode 100644
index 8bc79f1b90..0000000000
--- a/docs/reference/bodyparts/real_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-@verbatim
-
-vars:
-
- "scalar" real => "0.5";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/real_notes.texinfo b/docs/reference/bodyparts/real_notes.texinfo
deleted file mode 100644
index 46155c92c4..0000000000
--- a/docs/reference/bodyparts/real_notes.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-Real variables are strings that are expected to be used as real numbers. The
-typing in CFEngine is dynamic, so the variable types are interchangable, but
-when you declare a variable to be type @code{real}, CFEngine verifies that
-the value you assign to it looks like a real number (e.g., @samp{3},
-@samp{3.1415}, @samp{.17}, @samp{6.02e23}, @samp{-9.21e-17}, etc).
-
-Real numbers are not used in many places in CFEngine, but they are
-useful for representing probabilties and performance data.
diff --git a/docs/reference/bodyparts/recognize_join_example.texinfo b/docs/reference/bodyparts/recognize_join_example.texinfo
deleted file mode 100644
index 69e8b1f610..0000000000
--- a/docs/reference/bodyparts/recognize_join_example.texinfo
+++ /dev/null
@@ -1,17 +0,0 @@
-
-@verbatim
-files:
-
- "/tmp/test_insert"
- create => "true",
- edit_line => Insert("$(insert.v)"),
- edit_defaults => join;
-}
-
-#
-
-body edit_defaults join
-{
-recognize_join => "true";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/recognize_join_notes.texinfo b/docs/reference/bodyparts/recognize_join_notes.texinfo
deleted file mode 100644
index b08485c798..0000000000
--- a/docs/reference/bodyparts/recognize_join_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-If set to true, this option allows CFEngine to process line based files
-with backslash continuation. The default is to not process continuation backslashes.
-
-Back slash lines will only be concatenated if the file requires editing,
-and will not be restored. Restoration of the backslashes is not
-possible in a meaningful and convergent fashion.
diff --git a/docs/reference/bodyparts/refresh_processes_example.texinfo b/docs/reference/bodyparts/refresh_processes_example.texinfo
deleted file mode 100644
index 5b8877d247..0000000000
--- a/docs/reference/bodyparts/refresh_processes_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-refresh_processes => { "mybundle" };
-#refresh_processes => { "none" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/refresh_processes_notes.texinfo b/docs/reference/bodyparts/refresh_processes_notes.texinfo
deleted file mode 100644
index 94b1567b9c..0000000000
--- a/docs/reference/bodyparts/refresh_processes_notes.texinfo
+++ /dev/null
@@ -1,13 +0,0 @@
-
-@i{History}: Was introduced in version 3.1.3,Nova 2.0.2 (2010)
-
-If this list of regular expressions is non-null and an existing bundle
-is mentioned or matched in this list, CFEngine will reload the process table at
-the start of the named bundle, each time is is scheduled. If the list
-is null, the process list will be reloaded at the start of every
-scheduled bundle.
-
-In the example above we use a non-empty list with the name `none'.
-This is not a reserved word, but as long as there are no bundles with the name `none'
-this has the effect of @i{never} reloading the process table. This keeps improves the
-efficiency of the agent.
diff --git a/docs/reference/bodyparts/registry_exclude_example.texinfo b/docs/reference/bodyparts/registry_exclude_example.texinfo
deleted file mode 100644
index d7a05da352..0000000000
--- a/docs/reference/bodyparts/registry_exclude_example.texinfo
+++ /dev/null
@@ -1,21 +0,0 @@
-
-@verbatim
-
-databases:
-
- "HKEY_LOCAL_MACHINE\SOFTWARE"
-
- database_operation => "cache",
-
- registry_exclude => { ".*Windows.*CurrentVersion.*",
- ".*Touchpad.*",
- ".*Capabilities.FileAssociations.*",
- ".*Rfc1766.*" ,
- ".*Synaptics.SynTP.*",
- ".*SupportedDevices.*8086",
- ".*Microsoft.*ErrorThresholds"
- },
-
- database_type => "ms_registry";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/registry_exclude_notes.texinfo b/docs/reference/bodyparts/registry_exclude_notes.texinfo
deleted file mode 100644
index 83f68ada0a..0000000000
--- a/docs/reference/bodyparts/registry_exclude_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-During recursive Windows registry scanning, this option allows us to ignore keys of values matching a
-list of regular expressions. Some values in the registry are ephemeral and some should not be considered.
-This provdes a convenient way of avoiding names. It is analogous to @code{exclude_dirs} for files.
diff --git a/docs/reference/bodyparts/repair_denied_example.texinfo b/docs/reference/bodyparts/repair_denied_example.texinfo
deleted file mode 100644
index de6a18c0b0..0000000000
--- a/docs/reference/bodyparts/repair_denied_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body classes example
-{
-repair_denied => { "permission_failure" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/repair_denied_notes.texinfo b/docs/reference/bodyparts/repair_denied_notes.texinfo
deleted file mode 100644
index 780253b136..0000000000
--- a/docs/reference/bodyparts/repair_denied_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-A promise could not be kept because access to a key resource
-was denied.
-
-Note that any strings passed to this list are automatically
-canonified, so it is unecessary to call a canonify function on such inputs.
-
diff --git a/docs/reference/bodyparts/repair_failed_example.texinfo b/docs/reference/bodyparts/repair_failed_example.texinfo
deleted file mode 100644
index 77c70ce9d5..0000000000
--- a/docs/reference/bodyparts/repair_failed_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body classes example
-{
-repair_failed => { "unknown_error" };
-}
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/repair_failed_notes.texinfo b/docs/reference/bodyparts/repair_failed_notes.texinfo
deleted file mode 100644
index 697ca13c54..0000000000
--- a/docs/reference/bodyparts/repair_failed_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-A promise could not be repaired because the corrective
-action failed for some reason.
-
-Note that any strings passed to this list are automatically
-canonified, so it is unecessary to call a canonify function on such inputs.
-
diff --git a/docs/reference/bodyparts/repair_timeout_example.texinfo b/docs/reference/bodyparts/repair_timeout_example.texinfo
deleted file mode 100644
index 5193b89cb1..0000000000
--- a/docs/reference/bodyparts/repair_timeout_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-
-@verbatim
-
-body classes example
-{
-repair_timeout => { "too_slow", "did_not_wait" };
-}
-
-@end verbatim
-
-
diff --git a/docs/reference/bodyparts/repair_timeout_notes.texinfo b/docs/reference/bodyparts/repair_timeout_notes.texinfo
deleted file mode 100644
index 4153d20da7..0000000000
--- a/docs/reference/bodyparts/repair_timeout_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-A promise maintenance repair timed-out waiting for some dependent resource.
diff --git a/docs/reference/bodyparts/repaired_returncodes_example.texinfo b/docs/reference/bodyparts/repaired_returncodes_example.texinfo
deleted file mode 100644
index 42bcf1fd2f..0000000000
--- a/docs/reference/bodyparts/repaired_returncodes_example.texinfo
+++ /dev/null
@@ -1,18 +0,0 @@
-@verbatim
-bundle agent cmdtest
-{
-commands:
- "/bin/false"
- classes => example;
-
-reports:
-wasrepaired::
- "The command-promise got repaired!";
-}
-
-body classes example
-{
-repaired_returncodes => { "0", "1" };
-promise_repaired => { "wasrepaired" };
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/repaired_returncodes_notes.texinfo b/docs/reference/bodyparts/repaired_returncodes_notes.texinfo
deleted file mode 100644
index 05d6c38a89..0000000000
--- a/docs/reference/bodyparts/repaired_returncodes_notes.texinfo
+++ /dev/null
@@ -1,28 +0,0 @@
-
-A list of integer return codes indicating that a command-related
-promise has been repaired. This can in turn be used to define classes
-using the @code{promise_repaired} attribute, or merely alter the total
-compliance statistics.
-
-Currently, the attribute has impact on the following command-related
-promises.
-
-@itemize
-@item All promises of type @code{commands:}
-@item @code{files}-promises containing a @code{transformer}-attribute
-@item The package manager change command in @code{packages}-promises
-(e.g. the command for add, remove, etc.)
-@end itemize
-
-
-If none of the attributes @code{kept_returncodes}, @code{repaired_returncodes},
-or @code{failed_returncodes} are set, the default is to consider a
-return code zero as promise repaired, and nonzero as promise failed.
-
-Note that the return codes may overlap, so multiple classes may be set
-from one return code. In Unix systems the possible return codes are
-usually in the range from 0 to 255.
-
-@i{History}: Was introduced in version 3.1.3, Nova 2.0.2 (2010)
-
-
diff --git a/docs/reference/bodyparts/repchar_example.texinfo b/docs/reference/bodyparts/repchar_example.texinfo
deleted file mode 100644
index 27bdd6ba95..0000000000
--- a/docs/reference/bodyparts/repchar_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-repchar => "_";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/repchar_notes.texinfo b/docs/reference/bodyparts/repchar_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/bodyparts/repchar_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/bodyparts/replace_value_example.texinfo b/docs/reference/bodyparts/replace_value_example.texinfo
deleted file mode 100644
index 6590642413..0000000000
--- a/docs/reference/bodyparts/replace_value_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body replace_with example(s)
-{
-replace_value => "$(s)";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/replace_value_notes.texinfo b/docs/reference/bodyparts/replace_value_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/bodyparts/replace_value_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/bodyparts/report_changes_example.texinfo b/docs/reference/bodyparts/report_changes_example.texinfo
deleted file mode 100644
index 82335b590b..0000000000
--- a/docs/reference/bodyparts/report_changes_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body changes example
-{
-report_changes => "content";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/report_changes_notes.texinfo b/docs/reference/bodyparts/report_changes_notes.texinfo
deleted file mode 100644
index 1f42e729e5..0000000000
--- a/docs/reference/bodyparts/report_changes_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Files can change in permissions and contents, i.e. external or internal attributes.
-If @samp{all} is chosen all attributes are checked.
diff --git a/docs/reference/bodyparts/report_diffs_example.texinfo b/docs/reference/bodyparts/report_diffs_example.texinfo
deleted file mode 100644
index bfb8615a36..0000000000
--- a/docs/reference/bodyparts/report_diffs_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body changes example
-{
-report_diffs => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/report_diffs_notes.texinfo b/docs/reference/bodyparts/report_diffs_notes.texinfo
deleted file mode 100644
index 3fd1db8ece..0000000000
--- a/docs/reference/bodyparts/report_diffs_notes.texinfo
+++ /dev/null
@@ -1,14 +0,0 @@
-
-@i{This feature is available only in enterprise levels Nova and above.}
-
-If true, CFEngine will log a `diff' summary of major changes to the
-files. It is not permitted to combine this promise with a depth
-search, since this would consume a dangerous amount of resources and
-would lead to unreadable reports.
-
-The feature is intented as a informational summary, not as a version
-control function suitable for transaction control. If you want to
-do versioning on system files, you should keep a single repository
-for them and use CFEngine to synchronize changes from the repository
-source. Repositories should not be used to attempt to capture random
-changes of the system.
diff --git a/docs/reference/bodyparts/report_level_example.texinfo b/docs/reference/bodyparts/report_level_example.texinfo
deleted file mode 100644
index 4b8e73f68e..0000000000
--- a/docs/reference/bodyparts/report_level_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body action example
-{
-report_level => "verbose";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/report_level_notes.texinfo b/docs/reference/bodyparts/report_level_notes.texinfo
deleted file mode 100644
index ad030c201f..0000000000
--- a/docs/reference/bodyparts/report_level_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-cf-agent can be run in verbose mode (-v), inform mode (-I) and just print errors (no arguments).
-This attribute allows to set these three output levels on a per promise basis, allowing
-the promise to be more verbose than the global setting (but not less).
-
-In CFEngine 2 one would say @samp{inform=true} or @samp{syslog=true}, etc.
-This replaces these levels since they act as encapsulating super-sets.
diff --git a/docs/reference/bodyparts/report_output_example.texinfo b/docs/reference/bodyparts/report_output_example.texinfo
deleted file mode 100644
index 6b85da3753..0000000000
--- a/docs/reference/bodyparts/report_output_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body reporter control
-{
-report_output => "html";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/report_output_notes.texinfo b/docs/reference/bodyparts/report_output_notes.texinfo
deleted file mode 100644
index 34b8be8fe6..0000000000
--- a/docs/reference/bodyparts/report_output_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Sets the output format of embedded database reports.
-
diff --git a/docs/reference/bodyparts/report_to_file_example.texinfo b/docs/reference/bodyparts/report_to_file_example.texinfo
deleted file mode 100644
index a4ac2c9ed7..0000000000
--- a/docs/reference/bodyparts/report_to_file_example.texinfo
+++ /dev/null
@@ -1,15 +0,0 @@
-
-@verbatim
-
-bundle agent test
-{
-reports:
-
- linux::
-
- "$(sys.date),This is a report from $(sys.host)"
-
- report_to_file => "/tmp/test_log";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/report_to_file_notes.texinfo b/docs/reference/bodyparts/report_to_file_notes.texinfo
deleted file mode 100644
index a6c7207135..0000000000
--- a/docs/reference/bodyparts/report_to_file_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Append the output of the report to the named file instead of standard
-output. If the file cannot be opened for writing then the report
-defaults to the standard output.
diff --git a/docs/reference/bodyparts/reports_example.texinfo b/docs/reference/bodyparts/reports_example.texinfo
deleted file mode 100644
index 745c1c41ec..0000000000
--- a/docs/reference/bodyparts/reports_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body reporter control
-{
-reports => { "performance", "classes" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/reports_notes.texinfo b/docs/reference/bodyparts/reports_notes.texinfo
deleted file mode 100644
index bffc4b8971..0000000000
--- a/docs/reference/bodyparts/reports_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-A list of report types that can be generated by this agent. The
-listed items from @code{compliance} onward are available only
-Enterprise editions of CFEngine.
-
-The keyword @samp{all} can be used to get all reports except the audit
-and locking reports. The latter are large and unwieldy and need specific confirmation.
diff --git a/docs/reference/bodyparts/repository_example.texinfo b/docs/reference/bodyparts/repository_example.texinfo
deleted file mode 100644
index 76825fbf62..0000000000
--- a/docs/reference/bodyparts/repository_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-
-@verbatim
-
-files:
-
- "/path/file"
-
- copy_from => source,
- repository => "/var/cfengine/repository";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/repository_notes.texinfo b/docs/reference/bodyparts/repository_notes.texinfo
deleted file mode 100644
index 3a77957589..0000000000
--- a/docs/reference/bodyparts/repository_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-A local repository for this object, overrides the default,
-@xref{default_repository in agent, ,default_repository}.
-
-Note that when a repository is specified, the files are stored using the
-canonified directory name of the original file, concatenated with the name of
-the file. So, for example, @file{/usr/local/etc/postfix.conf} would ordinarily
-be stored in an alternative repository as
-@file{_usr_local_etc_postfix.conf.cfsaved}.
diff --git a/docs/reference/bodyparts/require_comments_example.texinfo b/docs/reference/bodyparts/require_comments_example.texinfo
deleted file mode 100644
index 3e677ce92a..0000000000
--- a/docs/reference/bodyparts/require_comments_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-common::
-
-require_comments => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/require_comments_notes.texinfo b/docs/reference/bodyparts/require_comments_notes.texinfo
deleted file mode 100644
index e61fb4d675..0000000000
--- a/docs/reference/bodyparts/require_comments_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-
-This may be used as a policy Quality Assurance measure, to remind
-policy makers to properly document their promises. When true,
-@code{cf-promises} will report loudly on promises that do not have
-comments. Variables promises are exempted from this
-rule, since they may be considered self-documenting.
diff --git a/docs/reference/bodyparts/resource_type_example.texinfo b/docs/reference/bodyparts/resource_type_example.texinfo
deleted file mode 100644
index d327e57119..0000000000
--- a/docs/reference/bodyparts/resource_type_example.texinfo
+++ /dev/null
@@ -1,43 +0,0 @@
-
-@verbatim
-
-
-bundle server access_rules()
-
-{
-access:
-
- "value of my test_scalar, can expand variables here - $(sys.host)"
- handle => "test_scalar",
- comment => "Grant access to contents of test_scalar VAR",
- resource_type => "literal",
- admit => { "127.0.0.1" };
-
- "XYZ"
- resource_type => "variable",
- handle => "XYZ",
- admit => { "127.0.0.1" };
-
-
- # On the policy hub
-
- "collect_calls"
- resource_type => "query",
- admit => { "127.0.0.1" };
-
- # On the isolated client in the field
-
-
- "delta"
- comment => "Grant access to cfengine hub to collect report deltas",
- resource_type => "query",
- admit => { "127.0.0.1" };
- "full"
- comment => "Grant access to cfengine hub to collect full report dump",
- resource_type => "query",
- admit => { "127.0.0.1" };
-
-
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/resource_type_notes.texinfo b/docs/reference/bodyparts/resource_type_notes.texinfo
deleted file mode 100644
index d2677b3013..0000000000
--- a/docs/reference/bodyparts/resource_type_notes.texinfo
+++ /dev/null
@@ -1,42 +0,0 @@
-
-By default, access to resources granted by the server are
-files. However, sometimes it is useful to cache @code{literal}
-strings, hints and data in the server, e.g. the contents of variables,
-hashed passwords etc for easy access. In the case of literal data, the
-promise handle serves as the reference identifier for queries. Queries
-are instigated by function calls by any agent.
-
-If the resource type is @code{literal}, CFEngine will grant access to a
-literal datastring. This string is defined either by the promiser
-itself, but the name of the variable is the identifier given by the promise
-handle of the access promise, since the promiser string might be complex.
-
-If the resource type is @code{variable} then the promiser is the name
-of a persistent scalar variable defined on the server-host. Currently
-persistent scalars are only used internally by Enterprise CFEngine to
-hold enumerated classes for orchestration purposes.
-
-If you want to send the value of a policy defined variable in the
-server host (which for some reason is not available directly through
-policy on the client, e.g. because they have differnet policies), then
-you could use the construction
-
-@verbatim
-access:
-
- "$(variable_name)"
-
- handle => "variable_name",
- resource_type => "literal";
-@end verbatim
-
-If the resource type is @code{context}, the promiser is treated as a
-regular expression to match persistent classes defined on the server
-host. If these are matched by the request from the client, they will
-be transmitted, @xref{Function remoteclassesmatching}.
-
-The term @code{query} may also be used in commercial versions of
-CFEngine to query the server for data from embedded databases. This is
-currently for internal use only, and is used to grant access to report
-`menus'. If the promiser of a query request is called @samp{collect_calls},
-this grants access to server peering collect-call tunneling, @xref{call_collect_interval in server}.
diff --git a/docs/reference/bodyparts/restart_class_example.texinfo b/docs/reference/bodyparts/restart_class_example.texinfo
deleted file mode 100644
index 4db8cfa4cb..0000000000
--- a/docs/reference/bodyparts/restart_class_example.texinfo
+++ /dev/null
@@ -1,16 +0,0 @@
-
-@verbatim
-
-processes:
-
- "cf-serverd"
-
- restart_class => "start_cfserverd";
-
-commands:
-
- start_cfserverd::
-
- "/var/cfengine/bin/cf-serverd";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/restart_class_notes.texinfo b/docs/reference/bodyparts/restart_class_notes.texinfo
deleted file mode 100644
index 5238bdd136..0000000000
--- a/docs/reference/bodyparts/restart_class_notes.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-This is a signal to restart a process that should be running, if it is
-not running. Processes are signalled first and then restarted later,
-at the end of bundle execution, after all possible corrective actions have
-been made that could influence their execution.
-
-Windows does not support that processes start themselves in the
-background, like Unix daemons usually do (i.e. fork off a child
-process). Therefore, it may be useful to specify an action bodypart
-that sets background to true in a commands promise that is invoked by
-the class set by restart_class. See the commands promise type for more
-information.
diff --git a/docs/reference/bodyparts/rlist_example.texinfo b/docs/reference/bodyparts/rlist_example.texinfo
deleted file mode 100644
index 8cd064d21f..0000000000
--- a/docs/reference/bodyparts/rlist_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-vars:
-
- "varid" rlist => { "0.1", "0.2", "0.3" };
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/rlist_notes.texinfo b/docs/reference/bodyparts/rlist_notes.texinfo
deleted file mode 100644
index 256b7507f4..0000000000
--- a/docs/reference/bodyparts/rlist_notes.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-Real lists are lists of strings that are expected to be used as real numbers.
-The typing in CFEngine is dynamic, so the variable types are interchangable,
-but when you declare a variable to be type @code{rlist}, CFEngine verifies that
-each value you assign to it looks like a real number (e.g., @samp{3},
-@samp{3.1415}, @samp{.17}, @samp{6.02e23}, @samp{-9.21e-17}, etc).
-
-Some functions return @code{rlist}s (@pxref{Introduction to functions}),
-and an @code{rlist} may contain the values copied from another @code{slist},
-@code{rlist}, or @code{ilist} (@pxref{List variable substitution and expansion},
-@pxref{policy in vars}).
diff --git a/docs/reference/bodyparts/rmdeadlinks_example.texinfo b/docs/reference/bodyparts/rmdeadlinks_example.texinfo
deleted file mode 100644
index e49d04caac..0000000000
--- a/docs/reference/bodyparts/rmdeadlinks_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body depth_search example
-{
-rmdeadlinks => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/rmdeadlinks_notes.texinfo b/docs/reference/bodyparts/rmdeadlinks_notes.texinfo
deleted file mode 100644
index cdb1ab1dc3..0000000000
--- a/docs/reference/bodyparts/rmdeadlinks_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-If we find links that point to non-existence files, should we delete them or keep them?
diff --git a/docs/reference/bodyparts/rmdirs_example.texinfo b/docs/reference/bodyparts/rmdirs_example.texinfo
deleted file mode 100644
index 5704f2e76e..0000000000
--- a/docs/reference/bodyparts/rmdirs_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body delete example
-{
-rmdirs => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/rmdirs_notes.texinfo b/docs/reference/bodyparts/rmdirs_notes.texinfo
deleted file mode 100644
index b4693f9759..0000000000
--- a/docs/reference/bodyparts/rmdirs_notes.texinfo
+++ /dev/null
@@ -1,51 +0,0 @@
-
-When deleting files recursively from a base directory, should we
-delete empty directories also, or keep the directory structure intact?
-
-Note the parent directory of a search is not deleted in recursive
-deletions. In CFEngine 2 there was an option to delete the parent of
-the search, but now in CFEngine 3, you must code a separate promise to
-delete the single parent object.
-
-@verbatim
-
-bundle agent cleanup
-{
-files:
-
- # This will not delete the parent
-
- "/home/mark/tmp/testcopy"
-
- delete => tidyfiles,
- file_select => changed_within_1_year,
- depth_search => recurse("inf");
-
- # Now delete the parent.
-
- "/home/mark/tmp/testcopy"
- delete => tidyfiles;
-}
-
-body delete tidyfiles
-{
-dirlinks => "delete";
-rmdirs => "true";
-}
-
-body file_select changed_within_1_year
-{
-mtime => irange(ago(1,0,0,0,0,0),now);
-file_result => "mtime";
-}
-
-@end verbatim
-
-@noindent @b{Default value} (only if body is present):@*
-@*
-
-The default value only has significance if there is a @code{delete} body
-present. If there is no @code{delete} body, then files (and directories)
-are @b{not} deleted.
-
-@code{rmdirs => true}
diff --git a/docs/reference/bodyparts/rotate_example.texinfo b/docs/reference/bodyparts/rotate_example.texinfo
deleted file mode 100644
index 0022e17c4b..0000000000
--- a/docs/reference/bodyparts/rotate_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body rename example
-{
-rotate => "4";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/rotate_notes.texinfo b/docs/reference/bodyparts/rotate_notes.texinfo
deleted file mode 100644
index 487379ea24..0000000000
--- a/docs/reference/bodyparts/rotate_notes.texinfo
+++ /dev/null
@@ -1,17 +0,0 @@
-
-Used for log rotation. If the file is named @file{foo} and the @samp{rotate}
-attribute is set to @samp{4}, as above, then initially @file{foo} is copied
-to @file{foo.1} and the old file @file{foo} is zeroed out (that is, the inode
-of the original logfile does not change, but the original logfile will be
-empty after the rotation is complete).
-
-The next time the promise is executed, @file{foo.1} will be renamed
-@file{foo.2}, @file{foo} is again copied to @file{foo.1} and the old file
-@file{foo} is again zeroed out.
-
-Each time the promise is executed (and typically, the promise would be
-executed as guarded by time-based or file-size-based classes), the files are
-copied/zeroed or rotated as above until there are @samp{rotate} numbered files
-plus the one "main" file. In the example above, the file @file{foo.3} will be
-renamed @file{foo.4}, but the old version of the file @file{foo.4} will be
-deleted (that is, it "falls off the end" of the rotation).
diff --git a/docs/reference/bodyparts/rsize_example.texinfo b/docs/reference/bodyparts/rsize_example.texinfo
deleted file mode 100644
index 9ee2a1741f..0000000000
--- a/docs/reference/bodyparts/rsize_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body process_select
-{
-rsize => irange("4000","8000");
-}
-
-
-@end verbatim
diff --git a/docs/reference/bodyparts/rsize_notes.texinfo b/docs/reference/bodyparts/rsize_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/bodyparts/rsize_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/bodyparts/rxdirs_example.texinfo b/docs/reference/bodyparts/rxdirs_example.texinfo
deleted file mode 100644
index 06a32600f9..0000000000
--- a/docs/reference/bodyparts/rxdirs_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body perms rxdirs
-{
-rxdirs => "false";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/rxdirs_notes.texinfo b/docs/reference/bodyparts/rxdirs_notes.texinfo
deleted file mode 100644
index 76c8dd20dc..0000000000
--- a/docs/reference/bodyparts/rxdirs_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-Default behaviour is to set the @samp{x} flag on directories
-automatically if the @samp{r} flag is specified when specifying
-multiple files in a single promise. This is ignored on windows, as the
-permission model uses ACLs.
diff --git a/docs/reference/bodyparts/scan_arrivals_example.texinfo b/docs/reference/bodyparts/scan_arrivals_example.texinfo
deleted file mode 100644
index bda5320d2f..0000000000
--- a/docs/reference/bodyparts/scan_arrivals_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body volume example
-{
-scan_arrivals => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/scan_arrivals_notes.texinfo b/docs/reference/bodyparts/scan_arrivals_notes.texinfo
deleted file mode 100644
index 6f8d81b595..0000000000
--- a/docs/reference/bodyparts/scan_arrivals_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-This operation should not be left `on' for more than a single run
-(maximum once per week). It causes CFEngine to perform an extensive
-disk scan noting the schedule of changes between files. This can be
-used for a number of analyses including optimum backup schedule computation.
diff --git a/docs/reference/bodyparts/schedule_example.texinfo b/docs/reference/bodyparts/schedule_example.texinfo
deleted file mode 100644
index 02a53dc6f0..0000000000
--- a/docs/reference/bodyparts/schedule_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body executor control
-{
-schedule => { "Min00", "(Evening|Night).Min15_20", "Min30", "(Evening|Night).Min45_50" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/schedule_notes.texinfo b/docs/reference/bodyparts/schedule_notes.texinfo
deleted file mode 100644
index 805639f462..0000000000
--- a/docs/reference/bodyparts/schedule_notes.texinfo
+++ /dev/null
@@ -1,21 +0,0 @@
-
-The list should contain class expressions comprised of classes which are
-visible to the @code{cf-execd} daemon. In principle, any defined class
-expression will cause the daemon to wake up
-and schedule the execution of the @code{cf-agent}. In practice, the classes
-listed in the list are usually date- and time-based.
-
-The actual execution of
-@code{cf-agent} may be delayed by @code{splaytime}, and may be deferred by
-promise caching and the value of @code{ifelapsed}. Note also that the
-effectiveness of the @code{splayclass} function may be affected by changing
-the @code{schedule}.
-
-
-@noindent @b{Default value}:@*
-
-@verbatim
-
-schedule => { "Min00", "Min05", "Min10", "Min15", "Min20", "Min25",
- "Min30", "Min35", "Min40", "Min45", "Min50", "Min55" };
-@end verbatim
diff --git a/docs/reference/bodyparts/search_bsdflags_example.texinfo b/docs/reference/bodyparts/search_bsdflags_example.texinfo
deleted file mode 100644
index a75475fc95..0000000000
--- a/docs/reference/bodyparts/search_bsdflags_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body file_select xyz
-{
-search_bsdflags => "archived|dump";
-file_result => "bsdflags";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/search_bsdflags_notes.texinfo b/docs/reference/bodyparts/search_bsdflags_notes.texinfo
deleted file mode 100644
index e259f4bd0a..0000000000
--- a/docs/reference/bodyparts/search_bsdflags_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Extra BSD file system flags (these have no effect on non-BSD versions of
-CFEngine). See the manual page for @code{chflags} for more details.
diff --git a/docs/reference/bodyparts/search_groups_example.texinfo b/docs/reference/bodyparts/search_groups_example.texinfo
deleted file mode 100644
index e7f3b11521..0000000000
--- a/docs/reference/bodyparts/search_groups_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-
-@verbatim
-
-body file_select example
-{
-search_groups => { "users", "special_.*" };
-file_result => "group";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/search_groups_notes.texinfo b/docs/reference/bodyparts/search_groups_notes.texinfo
deleted file mode 100644
index 29ba3c0869..0000000000
--- a/docs/reference/bodyparts/search_groups_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-A list of regular expressions, any of which which must match the entire group,
-(that is, it is anchored, @pxref{Anchored vs. unanchored regular expressions}).
-Note that on windows, files do not have group associations.
diff --git a/docs/reference/bodyparts/search_mode_example.texinfo b/docs/reference/bodyparts/search_mode_example.texinfo
deleted file mode 100644
index f6bc5567ec..0000000000
--- a/docs/reference/bodyparts/search_mode_example.texinfo
+++ /dev/null
@@ -1,54 +0,0 @@
-
-
-@verbatim
-
-#######################################################
-#
-# Searching for permissions
-#
-#######################################################
-
-body common control
- {
- any::
-
- bundlesequence => {
- "testbundle"
- };
-
- version => "1.2.3";
- }
-
-############################################
-
-bundle agent testbundle
-
-{
-files:
-
- "/home/mark/tmp/testcopy"
-
- file_select => by_modes,
- transformer => "/bin/echo DETECTED $(this.promiser)",
- depth_search => recurse("inf");
-
-}
-
-############################################
-
-body file_select by_modes
-
-{
-search_mode => { "711" , "666" };
-file_result => "mode";
-}
-
-############################################
-
-body depth_search recurse(d)
-
-{
-depth => "$(d)";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/search_mode_notes.texinfo b/docs/reference/bodyparts/search_mode_notes.texinfo
deleted file mode 100644
index 0de2a29fa7..0000000000
--- a/docs/reference/bodyparts/search_mode_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-The mode may be specified in symbolic or numerical form with @samp{+}
-and @samp{-} constraints.
-Note that concatenation @code{ug+s} implies @code{u} OR @code{g},
- and @code{u+s,g+s} implies @code{u} AND @code{g}.
diff --git a/docs/reference/bodyparts/search_owners_example.texinfo b/docs/reference/bodyparts/search_owners_example.texinfo
deleted file mode 100644
index c94ef157ef..0000000000
--- a/docs/reference/bodyparts/search_owners_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body file_select example
-{
-search_owners => { "mark", "jeang", "student_.*" };
-file_result => "owner";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/search_owners_notes.texinfo b/docs/reference/bodyparts/search_owners_notes.texinfo
deleted file mode 100644
index 520558fdb4..0000000000
--- a/docs/reference/bodyparts/search_owners_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-A list of regular expressions any of which must match the entire userid,
-(that is, it is anchored, @pxref{Anchored vs. unanchored regular expressions}).
-Note that windows does not have user ids, only names.
diff --git a/docs/reference/bodyparts/search_size_example.texinfo b/docs/reference/bodyparts/search_size_example.texinfo
deleted file mode 100644
index fd1b8d43e6..0000000000
--- a/docs/reference/bodyparts/search_size_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-
-@verbatim
-
-body file_select example
-{
-search_size => irange("0","20k");
-file_result => "size";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/search_size_notes.texinfo b/docs/reference/bodyparts/search_size_notes.texinfo
deleted file mode 100644
index e69de29bb2..0000000000
diff --git a/docs/reference/bodyparts/secureinput_example.texinfo b/docs/reference/bodyparts/secureinput_example.texinfo
deleted file mode 100644
index 4d0fee1d62..0000000000
--- a/docs/reference/bodyparts/secureinput_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-secureinput => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/secureinput_notes.texinfo b/docs/reference/bodyparts/secureinput_notes.texinfo
deleted file mode 100644
index 28a53d6353..0000000000
--- a/docs/reference/bodyparts/secureinput_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-If this is set, the agent will not accept an input file that is not owned
-by a privileged user.
diff --git a/docs/reference/bodyparts/select_class_example.texinfo b/docs/reference/bodyparts/select_class_example.texinfo
deleted file mode 100644
index db3a8fb31a..0000000000
--- a/docs/reference/bodyparts/select_class_example.texinfo
+++ /dev/null
@@ -1,16 +0,0 @@
-
-@verbatim
-bundle common g
-{
-classes:
- "selection" select_class => { "one", "two" };
-
-reports:
- one::
- "One was selected";
- two::
- "Two was selected";
- selection::
- "A selection was made";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/select_class_notes.texinfo b/docs/reference/bodyparts/select_class_notes.texinfo
deleted file mode 100644
index 3448dd9f30..0000000000
--- a/docs/reference/bodyparts/select_class_notes.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@i{History}: Was introduced in version 3.1.5, Nova 2.1.0 (2011)
-
-This feature is somewhat like the @code{splayclass} function, but instead of selecting
-a class for a moment in time, it always chooses one class in the list -- the same class each
-time for a given host. This allows hosts to be distributed across a controlled list of classes,
-e.g for load balancing purposes.
-
-The class is chosen deterministically (not randomly) but it is not possible to say which
-host will end up in which class in advance -- only that hosts will always end up in the same class
-every time.
diff --git a/docs/reference/bodyparts/select_end_example.texinfo b/docs/reference/bodyparts/select_end_example.texinfo
deleted file mode 100644
index 1fbacd1ff7..0000000000
--- a/docs/reference/bodyparts/select_end_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-
-@verbatim
-
-body select_region example(x)
-
-{
-select_start => "\[$(x)\]";
-select_end => "\[.*\]";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/select_end_notes.texinfo b/docs/reference/bodyparts/select_end_notes.texinfo
deleted file mode 100644
index 5d494c3476..0000000000
--- a/docs/reference/bodyparts/select_end_notes.texinfo
+++ /dev/null
@@ -1,23 +0,0 @@
-
-See also @code{select_start}. These delimiters mark out the region
-of a file to be edited. In the example, it is assumed that the file
-has section markes
-
-@smallexample
-[section 1]
-
-lines.
-lines...
-
-
-[section 2]
-
-lines ....
-etc..
-
-@end smallexample
-
-If you want to match from a starting location to the end of the file (even if
-there are other lines matching @code{select_start} intervening), then just omit
-the @code{select_end} promise and the selected region will run to the end of
-the file.
diff --git a/docs/reference/bodyparts/select_field_example.texinfo b/docs/reference/bodyparts/select_field_example.texinfo
deleted file mode 100644
index 65388a8c5f..0000000000
--- a/docs/reference/bodyparts/select_field_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-@verbatim
-
-body field_edits example
-{
-select_field => "5";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/select_field_notes.texinfo b/docs/reference/bodyparts/select_field_notes.texinfo
deleted file mode 100644
index ee0a87c2ed..0000000000
--- a/docs/reference/bodyparts/select_field_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-Numbering starts from 1 (not from 0).
diff --git a/docs/reference/bodyparts/select_line_matching_example.texinfo b/docs/reference/bodyparts/select_line_matching_example.texinfo
deleted file mode 100644
index 054943ce0f..0000000000
--- a/docs/reference/bodyparts/select_line_matching_example.texinfo
+++ /dev/null
@@ -1,18 +0,0 @@
-
-@verbatim
-
-# Editing
-
-body location example
-{
-select_line_matching => "Expression match.* whole line";
-}
-
-# Measurement promises
-
-body match_value example
-{
-select_line_matching => "Expression match.* whole line";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/select_line_matching_notes.texinfo b/docs/reference/bodyparts/select_line_matching_notes.texinfo
deleted file mode 100644
index 8aa1d47ef3..0000000000
--- a/docs/reference/bodyparts/select_line_matching_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-The expression must match a whole line, not a fragment within a line
-(that is, it is anchored, @pxref{Anchored vs. unanchored regular expressions}).
-
-This attribute is mutually exclusive of @code{select_line_number}.
diff --git a/docs/reference/bodyparts/select_line_number_example.texinfo b/docs/reference/bodyparts/select_line_number_example.texinfo
deleted file mode 100644
index a50b79fe36..0000000000
--- a/docs/reference/bodyparts/select_line_number_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body match_value find_line
-{
-select_line_number => "2";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/select_line_number_notes.texinfo b/docs/reference/bodyparts/select_line_number_notes.texinfo
deleted file mode 100644
index 3bf93d9e56..0000000000
--- a/docs/reference/bodyparts/select_line_number_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-This is mutually exclusive of @code{select_line_matching}.
diff --git a/docs/reference/bodyparts/select_multiline_policy_example.texinfo b/docs/reference/bodyparts/select_multiline_policy_example.texinfo
deleted file mode 100644
index ca18c683e9..0000000000
--- a/docs/reference/bodyparts/select_multiline_policy_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-
-@verbatim
-
-body match_value myvalue(xxx)
-{
- select_line_matching => ".*$(xxx).*";
- extraction_regex => "root\s+\S+\s+\S+\s+\S+\s+\S+\s+\S+\s+\S+\s+\S+\s+(\S+).*";
- select_multiline_policy => "sum";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/select_multiline_policy_notes.texinfo b/docs/reference/bodyparts/select_multiline_policy_notes.texinfo
deleted file mode 100644
index 877a9d407a..0000000000
--- a/docs/reference/bodyparts/select_multiline_policy_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@i{History}: Was introduced in 3.4.0 (2012)
-
-
-This option governs how CFEngine handels multiple matching lines in the input
-stream. We can average or sum values if they are integer or real, or use first or last representative samples. If non-numerical data types are used on the the first match is used.
diff --git a/docs/reference/bodyparts/select_start_example.texinfo b/docs/reference/bodyparts/select_start_example.texinfo
deleted file mode 100644
index 906e8f60db..0000000000
--- a/docs/reference/bodyparts/select_start_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-body select_region example(x)
-
-{
-select_start => "\[$(x)\]";
-select_end => "\[.*\]";
-}
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/select_start_notes.texinfo b/docs/reference/bodyparts/select_start_notes.texinfo
deleted file mode 100644
index a7842706f0..0000000000
--- a/docs/reference/bodyparts/select_start_notes.texinfo
+++ /dev/null
@@ -1,20 +0,0 @@
-
-See also @code{select_end}. These delimiters mark out the region
-of a file to be edited. In the example, it is assumed that the file
-has section markers.
-
-@smallexample
-[section 1]
-
-lines.
-lines...
-
-
-[section 2]
-
-lines ....
-etc..
-
-@end smallexample
-
-@noindent The start marker includes the first matched line.
diff --git a/docs/reference/bodyparts/select_xpath_example.texinfo b/docs/reference/bodyparts/select_xpath_example.texinfo
deleted file mode 100644
index 72df9bc74e..0000000000
--- a/docs/reference/bodyparts/select_xpath_example.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-@verbatim
-body select_xpath example(s)
-{
-select_xpath => "$(s)";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/select_xpath_notes.texinfo b/docs/reference/bodyparts/select_xpath_notes.texinfo
deleted file mode 100644
index 05a7381832..0000000000
--- a/docs/reference/bodyparts/select_xpath_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-Edits to the XML document take place within the selected node.
-Please note that this attribute is not used when inserting XML
-content into an empty file.
diff --git a/docs/reference/bodyparts/sensible_count_example.texinfo b/docs/reference/bodyparts/sensible_count_example.texinfo
deleted file mode 100644
index 557f399303..0000000000
--- a/docs/reference/bodyparts/sensible_count_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body volume example
-{
-sensible_count => "20";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/sensible_count_notes.texinfo b/docs/reference/bodyparts/sensible_count_notes.texinfo
deleted file mode 100644
index 27af8204ce..0000000000
--- a/docs/reference/bodyparts/sensible_count_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Files must be readable by the agent, i.e. it is assumed that the agent has privileges
-on volumes being checked.
diff --git a/docs/reference/bodyparts/sensible_size_example.texinfo b/docs/reference/bodyparts/sensible_size_example.texinfo
deleted file mode 100644
index 615a259cb3..0000000000
--- a/docs/reference/bodyparts/sensible_size_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-body volume example
-{
-sensible_size => "20K";
-}
-
-@end verbatim
-
-
-
diff --git a/docs/reference/bodyparts/sensible_size_notes.texinfo b/docs/reference/bodyparts/sensible_size_notes.texinfo
deleted file mode 100644
index 31fe7361f3..0000000000
--- a/docs/reference/bodyparts/sensible_size_notes.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-body volume control
-{
-sensible_size => "20K";
-}
-
-@end verbatim
-
-
-
diff --git a/docs/reference/bodyparts/sensiblecount_example.texinfo b/docs/reference/bodyparts/sensiblecount_example.texinfo
deleted file mode 100644
index 1600a46e1a..0000000000
--- a/docs/reference/bodyparts/sensiblecount_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-sensiblecount => "20";
-}
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/sensiblecount_notes.texinfo b/docs/reference/bodyparts/sensiblecount_notes.texinfo
deleted file mode 100644
index e69de29bb2..0000000000
diff --git a/docs/reference/bodyparts/sensiblesize_example.texinfo b/docs/reference/bodyparts/sensiblesize_example.texinfo
deleted file mode 100644
index cfc9eafc08..0000000000
--- a/docs/reference/bodyparts/sensiblesize_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-sensiblesize => "20K";
-}
-
-@end verbatim
-
-
diff --git a/docs/reference/bodyparts/sensiblesize_notes.texinfo b/docs/reference/bodyparts/sensiblesize_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/bodyparts/sensiblesize_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/bodyparts/serverfacility_example.texinfo b/docs/reference/bodyparts/serverfacility_example.texinfo
deleted file mode 100644
index 0ec72965eb..0000000000
--- a/docs/reference/bodyparts/serverfacility_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body server control
-{
-serverfacility => "LOG_USER";
-}
-@end verbatim
-
diff --git a/docs/reference/bodyparts/serverfacility_notes.texinfo b/docs/reference/bodyparts/serverfacility_notes.texinfo
deleted file mode 100644
index 6859c48344..0000000000
--- a/docs/reference/bodyparts/serverfacility_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-See syslog notes.
diff --git a/docs/reference/bodyparts/servers_example.texinfo b/docs/reference/bodyparts/servers_example.texinfo
deleted file mode 100644
index 835ad96cab..0000000000
--- a/docs/reference/bodyparts/servers_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body copy_from example
-{
-servers => { "primary.example.org", "secondary.example.org",
- "tertiary.other.domain" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/servers_notes.texinfo b/docs/reference/bodyparts/servers_notes.texinfo
deleted file mode 100644
index 0fdac05463..0000000000
--- a/docs/reference/bodyparts/servers_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-The servers are tried in order until one of them succeeds.
diff --git a/docs/reference/bodyparts/service_args_example.texinfo b/docs/reference/bodyparts/service_args_example.texinfo
deleted file mode 100644
index 6472c3fb13..0000000000
--- a/docs/reference/bodyparts/service_args_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body service_method example
-{
- service_args => "-f filename.conf --some-argument";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/service_args_notes.texinfo b/docs/reference/bodyparts/service_args_notes.texinfo
deleted file mode 100644
index 1529ee278b..0000000000
--- a/docs/reference/bodyparts/service_args_notes.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-These arguments will only be passed if CFEngine Nova starts the
-service. Thus, set @code{service_autostart_policy} to @code{none}
-to ensure that the arguments are always passed.
-
-Escaped quoutes can be used to pass an argument contianing spaces
-as a single argument, e.g. "-f \"file name.conf\"". Passing arguments
-is optional.
diff --git a/docs/reference/bodyparts/service_autostart_policy_example.texinfo b/docs/reference/bodyparts/service_autostart_policy_example.texinfo
deleted file mode 100644
index fbd9735888..0000000000
--- a/docs/reference/bodyparts/service_autostart_policy_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body service_method example
-{
- service_autostart_policy => "boot_time";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/service_autostart_policy_notes.texinfo b/docs/reference/bodyparts/service_autostart_policy_notes.texinfo
deleted file mode 100644
index ccf77404ef..0000000000
--- a/docs/reference/bodyparts/service_autostart_policy_notes.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-Defaults to @code{none}, which means that the service is not
-registered for automatic startup by the operating system in any
-way. It must be @code{none} if @code{service_policy} is not
-@code{start}. @code{boot_time} means the service is started at boot
-time, while @code{on_demand} means that the service is dispatched once
-it is being used.
-
-@code{on_demand} is not supported by Windows, and is implemented
-through inetd or xinetd on Unix.
diff --git a/docs/reference/bodyparts/service_dependence_chain_example.texinfo b/docs/reference/bodyparts/service_dependence_chain_example.texinfo
deleted file mode 100644
index 9e2f61916d..0000000000
--- a/docs/reference/bodyparts/service_dependence_chain_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body service_method example
-{
- service_dependence_chain => "start_parent_services";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/service_dependence_chain_notes.texinfo b/docs/reference/bodyparts/service_dependence_chain_notes.texinfo
deleted file mode 100644
index 6a421f95e5..0000000000
--- a/docs/reference/bodyparts/service_dependence_chain_notes.texinfo
+++ /dev/null
@@ -1,24 +0,0 @@
-
-The service dependencies include both the dependencies defined by the
-operating system and in @code{service_dependencies}, as described
-there.
-
-Defaults to @code{ignore}, which means that CFEngine Nova will never
-start or stop dependencies or dependent services, but fail if
-dependencies are not satisfied. @code{start_parent_services} means
-that all dependencies of the service will be started if they are not
-already running. When stopping a service, @code{stop_child_services}
-means that other services that depend on this service will be stopped
-also. @code{all_related} means both @code{start_parent_services} and
-@code{stop_child_services}.
-
-Note that this setting also affects dependencies of dependencies and
-so on.
-
-For example, consider the case where service A depends on B, which
-depends on C. If we want to start B, we must first make sure A is
-running. If @code{start_parent_services} or @code{all_related} is set,
-CFEngine Nova will start A, if it is not running. On the other hand,
-if we want to stop B, C needs to be stopped
-first. @code{stop_child_services} or @code{all_related} means that
-CFEngine Nova will stop C, if it is running.
diff --git a/docs/reference/bodyparts/service_dependencies_example.texinfo b/docs/reference/bodyparts/service_dependencies_example.texinfo
deleted file mode 100644
index 31f005fe1f..0000000000
--- a/docs/reference/bodyparts/service_dependencies_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-services:
-
- "ftp"
- service_policy => "start",
- service_dependencies => { "network", "logging" };
-
-@end verbatim
diff --git a/docs/reference/bodyparts/service_dependencies_notes.texinfo b/docs/reference/bodyparts/service_dependencies_notes.texinfo
deleted file mode 100644
index e55f898596..0000000000
--- a/docs/reference/bodyparts/service_dependencies_notes.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-A list of services that must be running before the service can be started.
-These dependencies can be started automatically by CFEngine Nova if they
-are not running --- see @code{service_dependence_chain}. However, the
-dependencies will never be implicitly stopped by CFEngine Nova. Specifying
-dependencies is optional.
-
-Note that the operating system may keep an additional list of dependencies
-for a given service, defined during installation of the service. CFEngine
-Nova requires these dependencies to be running as well before starting
-the service. The complete list of dependencies is thus the union of
-@code{service_dependencies} and the internal operating system list.
diff --git a/docs/reference/bodyparts/service_policy_example.texinfo b/docs/reference/bodyparts/service_policy_example.texinfo
deleted file mode 100644
index 9808b494e0..0000000000
--- a/docs/reference/bodyparts/service_policy_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-services:
-
- "Telnet"
- service_policy => "disable";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/service_policy_notes.texinfo b/docs/reference/bodyparts/service_policy_notes.texinfo
deleted file mode 100644
index 1afa7beb9a..0000000000
--- a/docs/reference/bodyparts/service_policy_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-If set to @code{start}, CFEngine Nova will keep the service in a running state,
-while @code{stop} means that the service is kept in a stopped state.
-@code{disable} implies @code{stop}, and ensures that the service can not be
-started directly, but needs to be enabled somehow first (e.g. by changing
-file permissions).
diff --git a/docs/reference/bodyparts/service_type_example.texinfo b/docs/reference/bodyparts/service_type_example.texinfo
deleted file mode 100644
index 6c6073e065..0000000000
--- a/docs/reference/bodyparts/service_type_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body service_method example
-{
- type => "windows";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/service_type_notes.texinfo b/docs/reference/bodyparts/service_type_notes.texinfo
deleted file mode 100644
index ebe072e689..0000000000
--- a/docs/reference/bodyparts/service_type_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-On Windows this defaults to, and must be @code{windows}.
-Unix systems can however have multiple means of registering
-services, but the choice must be available on the given system.
diff --git a/docs/reference/bodyparts/showstate_example.texinfo b/docs/reference/bodyparts/showstate_example.texinfo
deleted file mode 100644
index 49265b4deb..0000000000
--- a/docs/reference/bodyparts/showstate_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-reports:
- cfengine::
-
- "Comment"
-
- showstate => {"www_in", "ssh_out", "otherprocs" };
-
-@end verbatim
diff --git a/docs/reference/bodyparts/showstate_notes.texinfo b/docs/reference/bodyparts/showstate_notes.texinfo
deleted file mode 100644
index a185ab76e5..0000000000
--- a/docs/reference/bodyparts/showstate_notes.texinfo
+++ /dev/null
@@ -1,113 +0,0 @@
-
-The basic list of services is:
-
-@table @samp
-@item users
-Users logged in
-@item rootprocs
-Privileged system processes
-@item otherprocs
-Non-privileged process
-@item diskfree
-Free disk on / partition
-@item loadavg
-% kernel load utilization
-@item netbiosns_in
-netbios name lookups (in)
-@item netbiosns_out
-netbios name lookups (out)
-@item netbiosdgm_in
-netbios name datagrams (in)
-@item netbiosdgm_out
-netbios name datagrams (out)
-@item netbiosssn_in
-netbios name sessions (in)
-@item netbiosssn_out
-netbios name sessions (out)
-@item irc_in
-IRC connections (in)
-@item irc_out
-IRC connections (out)
-@item cfengine_in
-CFEngine connections (in)
-@item cfengine_out
-CFEngine connections (out)
-@item nfsd_in
-nfs connections (in)
-@item nfsd_out
-nfs connections (out)
-@item smtp_in
-smtp connections (in)
-@item smtp_out
-smtp connections (out)
-@item www_in
-www connections (in)
-@item www_out
-www connections (out)
-@item ftp_in
-ftp connections (in)
-@item ftp_out
-ftp connections (out)
-@item ssh_in
-ssh connections (in)
-@item ssh_out
-ssh connections (out)
-@item wwws_in
-wwws connections (in)
-@item wwws_out
-wwws connections (out)
-@item icmp_in
-ICMP packets (in)
-@item icmp_out
-ICMP packets (out)
-@item udp_in
-UDP dgrams (in)
-@item udp_out
-UDP dgrams (out)
-@item dns_in
-DNS requests (in)
-@item dns_out
-DNS requests (out)
-@item tcpsyn_in
-TCP sessions (in)
-@item tcpsyn_out
-TCP sessions (out)
-@item tcpack_in
-TCP acks (in)
-@item tcpack_out
-TCP acks (out)
-@item tcpfin_in
-TCP finish (in)
-@item tcpfin_out
-TCP finish (out)
-@item tcpmisc_in
-TCP misc (in)
-@item tcpmisc_out
-TCP misc (out)
-@item webaccess
-Webserver hits
-@item weberrors
-Webserver errors
-@item syslog
-New log entries (Syslog)
-@item messages
-New log entries (messages)
-@item temp0
-CPU Temperature 0
-@item temp1
-CPU Temperature 1
-@item temp2
-CPU Temperature 2
-@item temp3
-CPU Temperature 3
-@item cpu
-%CPU utilization (all)
-@item cpu0
-%CPU utilization 0
-@item cpu1
-%CPU utilization 1
-@item cpu2
-%CPU utilization 2
-@item cpu3
-%CPU utilization 3
-@end table
diff --git a/docs/reference/bodyparts/signals_example.texinfo b/docs/reference/bodyparts/signals_example.texinfo
deleted file mode 100644
index a7ad0b6ca1..0000000000
--- a/docs/reference/bodyparts/signals_example.texinfo
+++ /dev/null
@@ -1,19 +0,0 @@
-
-@verbatim
-
-processes:
-
- cfservd_out_of_control::
-
- "cfservd"
-
- signals => { "stop" , "term" },
- restart_class => "start_cfserv";
-
- any::
-
- "snmpd"
-
- signals => { "term" , "kill" };
-
-@end verbatim
diff --git a/docs/reference/bodyparts/signals_notes.texinfo b/docs/reference/bodyparts/signals_notes.texinfo
deleted file mode 100644
index f9713227f8..0000000000
--- a/docs/reference/bodyparts/signals_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Signals are presented as an ordered list to the process. On windows,
-only the kill signal is supported, which terminates the process.
diff --git a/docs/reference/bodyparts/site_classes_example.texinfo b/docs/reference/bodyparts/site_classes_example.texinfo
deleted file mode 100644
index c542b51c47..0000000000
--- a/docs/reference/bodyparts/site_classes_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-
-@verbatim
-body common control
-{
-site_classes => { "datacenters","datacentres" }; # locations is by default
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/site_classes_notes.texinfo b/docs/reference/bodyparts/site_classes_notes.texinfo
deleted file mode 100644
index 20db3367e1..0000000000
--- a/docs/reference/bodyparts/site_classes_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-@i{History}: Was introduced in version 3.2.0, Nova 2.1.0 (2011)
-
-This list is used to match against topics when connecting inferences about host locations in the knowledge
-map. Normally any CFEngine classes promise whose name is defined as a thing or topic under class @code{locations::}
-will be assumed to be a location defining classifier. This list will add alternative class contexts
-for interpreting location.
diff --git a/docs/reference/bodyparts/skipidentify_example.texinfo b/docs/reference/bodyparts/skipidentify_example.texinfo
deleted file mode 100644
index d682d84900..0000000000
--- a/docs/reference/bodyparts/skipidentify_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-skipidentify => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/skipidentify_notes.texinfo b/docs/reference/bodyparts/skipidentify_notes.texinfo
deleted file mode 100644
index 13276733e4..0000000000
--- a/docs/reference/bodyparts/skipidentify_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Hosts that are not registered in DNS cannot supply reasonable credentials
-for a secondary confirmation of their identity to a CFEngine server. This
-causes the agent to ignore its missing DNS credentials.
diff --git a/docs/reference/bodyparts/skipverify_example.texinfo b/docs/reference/bodyparts/skipverify_example.texinfo
deleted file mode 100644
index 2cc2f77259..0000000000
--- a/docs/reference/bodyparts/skipverify_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-
-@verbatim
-
-body server control
-{
-skipverify => { "special_host.*", "192.168\..*" };
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/skipverify_notes.texinfo b/docs/reference/bodyparts/skipverify_notes.texinfo
deleted file mode 100644
index 0d3a191e70..0000000000
--- a/docs/reference/bodyparts/skipverify_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Server side decision to ignore requirements of DNS identity confirmation.
-
-See also the warning about regular expressions in @code{allowallconnects}.
diff --git a/docs/reference/bodyparts/slist_example.texinfo b/docs/reference/bodyparts/slist_example.texinfo
deleted file mode 100644
index c68fdb9179..0000000000
--- a/docs/reference/bodyparts/slist_example.texinfo
+++ /dev/null
@@ -1,20 +0,0 @@
-
-@verbatim
-vars:
-
- "xxx" slist => { "literal1", "literal2" };
-
- "yyy" slist => {
- readstringlist(
- "/home/mark/tmp/testlist",
- "#[a-zA-Z0-9 ]*",
- "[^a-zA-Z0-9]",
- 15,
- 4000
- )
- };
-
- "zzz" slist => { readstringlist("/home/mark/tmp/testlist2","#[^\n]*",",",5,4000) };
-
-
-@end verbatim
diff --git a/docs/reference/bodyparts/slist_notes.texinfo b/docs/reference/bodyparts/slist_notes.texinfo
deleted file mode 100644
index 2d8601f703..0000000000
--- a/docs/reference/bodyparts/slist_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-Some functions return @code{slist}s (@pxref{Introduction to functions}),
-and an @code{slist} may contain the values copied from another @code{slist},
-@code{rlist}, or @code{ilist} (@pxref{List variable substitution and expansion},
-@pxref{policy in vars}).
diff --git a/docs/reference/bodyparts/smtpserver_example.texinfo b/docs/reference/bodyparts/smtpserver_example.texinfo
deleted file mode 100644
index 3ea39f5ff3..0000000000
--- a/docs/reference/bodyparts/smtpserver_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body executor control
-{
-smtpserver => "smtp.example.org";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/smtpserver_notes.texinfo b/docs/reference/bodyparts/smtpserver_notes.texinfo
deleted file mode 100644
index 90c2766839..0000000000
--- a/docs/reference/bodyparts/smtpserver_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-This should point to a standard port 25 server without encyption.
-If you are running secured or encrypted email then you should
-run a mail relay on localhost and point this to localhost.
diff --git a/docs/reference/bodyparts/source_example.texinfo b/docs/reference/bodyparts/source_example.texinfo
deleted file mode 100644
index c672ceb14a..0000000000
--- a/docs/reference/bodyparts/source_example.texinfo
+++ /dev/null
@@ -1,19 +0,0 @@
-
-
-@verbatim
-
-body copy_from example
-{
-source => "/path/to/source";
-}
-
-# or
-
-body link_from example
-{
-source => "/path/to/source";
-}
-
-@end verbatim
-
-
diff --git a/docs/reference/bodyparts/source_notes.texinfo b/docs/reference/bodyparts/source_notes.texinfo
deleted file mode 100644
index d73c6c6ab9..0000000000
--- a/docs/reference/bodyparts/source_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-For remote copies this refers to the file name on the remote server.
diff --git a/docs/reference/bodyparts/specify_inherit_aces_example.texinfo b/docs/reference/bodyparts/specify_inherit_aces_example.texinfo
deleted file mode 100644
index bda24714ad..0000000000
--- a/docs/reference/bodyparts/specify_inherit_aces_example.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-@verbatim
-body acl template
-{
-specify_default_aces => { "all:r" };
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/specify_inherit_aces_notes.texinfo b/docs/reference/bodyparts/specify_inherit_aces_notes.texinfo
deleted file mode 100644
index 8be1a3aafa..0000000000
--- a/docs/reference/bodyparts/specify_inherit_aces_notes.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
- @code{specify_default_aces} (optional) is a list of access control
- entries that are set on child objects. It is also parsed from left
- to right and allows multiple entries with same entity-type and
- id. Only valid if @code{acl_default} is set to
- @code{specify}.
-
-This is an acl which makes explicit setting for the acl inherited by
-new objects within a directory. It is included for those implementations
-that do not have a clear inheritance policy.
diff --git a/docs/reference/bodyparts/splaytime_example.texinfo b/docs/reference/bodyparts/splaytime_example.texinfo
deleted file mode 100644
index bd11901714..0000000000
--- a/docs/reference/bodyparts/splaytime_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body executor control
-{
-splaytime => "2";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/splaytime_notes.texinfo b/docs/reference/bodyparts/splaytime_notes.texinfo
deleted file mode 100644
index 379b6adc22..0000000000
--- a/docs/reference/bodyparts/splaytime_notes.texinfo
+++ /dev/null
@@ -1,22 +0,0 @@
-@noindent Whenever any class listed in the @code{schedule} attribute is
-present, @code{cf-execd} can schedule an execution of @code{cf-agent}. The
-actual execution will be delayed an integer number of seconds between
-0-@code{splaytime} minutes. The
-specific amount of delay for ``this'' host is based on a hash of the
-hostname. Thus a collection of hosts will all execute at different
-times, and surges in network traffic can be avoided.
-
-@noindent A rough rule of thumb for scaling of small
-updates is set the splay
-time between 1-5 minutes for up a few thousand hosts.
-The splaytime should not be set to a value larger than the
-@code{cf-execd} scheduling interval, else multiple clients might
-contend for data.
-
-@noindent @b{Default value}:@*
-@*
-
-The default value is 0 minutes.
-
-@noindent @b{See also:} The @code{splayclass()} function for a task-specific
-means for setting splay times.
diff --git a/docs/reference/bodyparts/start_fields_from_zero_example.texinfo b/docs/reference/bodyparts/start_fields_from_zero_example.texinfo
deleted file mode 100644
index de2b874a5f..0000000000
--- a/docs/reference/bodyparts/start_fields_from_zero_example.texinfo
+++ /dev/null
@@ -1,17 +0,0 @@
-
-@verbatim
-
-body edit_field col(split,col,newval,method)
-
-{
-field_separator => "$(split)";
-select_field => "$(col)";
-value_separator => ",";
-field_value => "$(newval)";
-field_operation => "$(method)";
-extend_fields => "true";
-allow_blank_fields => "true";
-start_fields_from_zero => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/start_fields_from_zero_notes.texinfo b/docs/reference/bodyparts/start_fields_from_zero_notes.texinfo
deleted file mode 100644
index 2548cd0d49..0000000000
--- a/docs/reference/bodyparts/start_fields_from_zero_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@i{History}: Was introduced in version 3.1.0b1,Nova 2.0.0b1 (2010)
-
-The numbering of fields is a matter for consistency and convention.
-Arrays are usually thought to start with first index equal to zero (0),
-but the first column in a file would normally be 1. By setting this option,
-you can tell CFEngine that the first column should be understood as number 0
-instead, for consistency with other array functions.
-
diff --git a/docs/reference/bodyparts/status_example.texinfo b/docs/reference/bodyparts/status_example.texinfo
deleted file mode 100644
index 3189416677..0000000000
--- a/docs/reference/bodyparts/status_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body process_select example
-{
-status => "Z";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/status_notes.texinfo b/docs/reference/bodyparts/status_notes.texinfo
deleted file mode 100644
index 169d6994f0..0000000000
--- a/docs/reference/bodyparts/status_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-For instance, characters in the set @samp{NRS "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/stealth_notes.texinfo b/docs/reference/bodyparts/stealth_notes.texinfo
deleted file mode 100644
index 9e09bb866f..0000000000
--- a/docs/reference/bodyparts/stealth_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-Preserves file access and modification times on the promiser files.
diff --git a/docs/reference/bodyparts/stime_range_example.texinfo b/docs/reference/bodyparts/stime_range_example.texinfo
deleted file mode 100644
index ff30e8da76..0000000000
--- a/docs/reference/bodyparts/stime_range_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body process_select example
-{
-stime_range => irange(ago(0,0,0,1,0,0),now);
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/stime_range_notes.texinfo b/docs/reference/bodyparts/stime_range_notes.texinfo
deleted file mode 100644
index e67ee894d0..0000000000
--- a/docs/reference/bodyparts/stime_range_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-
-The calculation of time from process table entries is sensitive to
-Daylight Savings Time (Summer/Winter Time) so calculations could be a
-hour off. This is for now a bug to be fixed.
-
diff --git a/docs/reference/bodyparts/stream_type_example.texinfo b/docs/reference/bodyparts/stream_type_example.texinfo
deleted file mode 100644
index e89b883dc8..0000000000
--- a/docs/reference/bodyparts/stream_type_example.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@verbatim
-
-stream_type => "pipe";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/stream_type_notes.texinfo b/docs/reference/bodyparts/stream_type_notes.texinfo
deleted file mode 100644
index 81041f3d46..0000000000
--- a/docs/reference/bodyparts/stream_type_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-CFEngine treats all input using a stream abstraction. The preferred interface is files, since they
-can be read without incurring the cost of a process. However pipes from executed commands may also
-be invoked.
diff --git a/docs/reference/bodyparts/string_example.texinfo b/docs/reference/bodyparts/string_example.texinfo
deleted file mode 100644
index 5759b8265e..0000000000
--- a/docs/reference/bodyparts/string_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-vars:
-
- "xxx" string => "Some literal string...";
-
- "yyy" string => readfile( "/home/mark/tmp/testfile" , "33" );
-
-@end verbatim
diff --git a/docs/reference/bodyparts/string_notes.texinfo b/docs/reference/bodyparts/string_notes.texinfo
deleted file mode 100644
index 0f62389a5b..0000000000
--- a/docs/reference/bodyparts/string_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-In CFEngine previously lists were represented (as in the shell) using
-separted scalars, e.g. like the PATH variable. This design feature
-turned out to be an error of judgement which has resulted in much
-trouble. This is no longer supported in CFEngine 3. By keeping lists
-an independent type many limitations have been removed.
diff --git a/docs/reference/bodyparts/suspiciousnames_example.texinfo b/docs/reference/bodyparts/suspiciousnames_example.texinfo
deleted file mode 100644
index 3a226a6232..0000000000
--- a/docs/reference/bodyparts/suspiciousnames_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body agent control
-{
-suspiciousnames => { ".mo", "lrk3", "rootkit" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/suspiciousnames_notes.texinfo b/docs/reference/bodyparts/suspiciousnames_notes.texinfo
deleted file mode 100644
index 6f823a595b..0000000000
--- a/docs/reference/bodyparts/suspiciousnames_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-If CFEngine sees these names during recursive (depth) file searches it will
-warn about them.
diff --git a/docs/reference/bodyparts/synonyms_example.texinfo b/docs/reference/bodyparts/synonyms_example.texinfo
deleted file mode 100644
index e4a201ecd0..0000000000
--- a/docs/reference/bodyparts/synonyms_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-
-@verbatim
-
- mathematics::
-
- "tree" synonyms => { "DAG", "directed acyclic graph" };
-
-@end verbatim
diff --git a/docs/reference/bodyparts/synonyms_notes.texinfo b/docs/reference/bodyparts/synonyms_notes.texinfo
deleted file mode 100644
index 6d27007c83..0000000000
--- a/docs/reference/bodyparts/synonyms_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-@i{History}: Was introduced in version 3.1.3a1,Nova 2.0.2a1 (2010)
-
-This may be used to simplify the identification of synonyms during topic searches.
diff --git a/docs/reference/bodyparts/syslog_example.texinfo b/docs/reference/bodyparts/syslog_example.texinfo
deleted file mode 100644
index d54521a0b6..0000000000
--- a/docs/reference/bodyparts/syslog_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-syslog => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/syslog_host_example.texinfo b/docs/reference/bodyparts/syslog_host_example.texinfo
deleted file mode 100644
index df413816cc..0000000000
--- a/docs/reference/bodyparts/syslog_host_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-@verbatim
-body common control
-{
-syslog_host => "syslog.example.org";
-syslog_port => "514";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/syslog_host_notes.texinfo b/docs/reference/bodyparts/syslog_host_notes.texinfo
deleted file mode 100644
index 2c5a33eaff..0000000000
--- a/docs/reference/bodyparts/syslog_host_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-The hostname or IP address of a local syslog service to which all CFEngine's components
-may promise to send data. This feature is provided in CFEngine Nova and above.
diff --git a/docs/reference/bodyparts/syslog_notes.texinfo b/docs/reference/bodyparts/syslog_notes.texinfo
deleted file mode 100644
index 139597f9cb..0000000000
--- a/docs/reference/bodyparts/syslog_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-
diff --git a/docs/reference/bodyparts/syslog_port_example.texinfo b/docs/reference/bodyparts/syslog_port_example.texinfo
deleted file mode 100644
index df413816cc..0000000000
--- a/docs/reference/bodyparts/syslog_port_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-@verbatim
-body common control
-{
-syslog_host => "syslog.example.org";
-syslog_port => "514";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/syslog_port_notes.texinfo b/docs/reference/bodyparts/syslog_port_notes.texinfo
deleted file mode 100644
index 26aae725ed..0000000000
--- a/docs/reference/bodyparts/syslog_port_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-The UDP port of a local syslog service to which all CFEngine's components
-may promise to send data. This feature is provided in CFEngine Nova and above.
diff --git a/docs/reference/bodyparts/tcpdump_example.texinfo b/docs/reference/bodyparts/tcpdump_example.texinfo
deleted file mode 100644
index 498612986d..0000000000
--- a/docs/reference/bodyparts/tcpdump_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body monitor control
-{
-tcpdump => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/tcpdump_notes.texinfo b/docs/reference/bodyparts/tcpdump_notes.texinfo
deleted file mode 100644
index af864181c3..0000000000
--- a/docs/reference/bodyparts/tcpdump_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-Interface with TCP stream if possible.
diff --git a/docs/reference/bodyparts/tcpdumpcommand_example.texinfo b/docs/reference/bodyparts/tcpdumpcommand_example.texinfo
deleted file mode 100644
index 0563846f45..0000000000
--- a/docs/reference/bodyparts/tcpdumpcommand_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body monitor control
-{
-tcpdumpcommand => "/usr/sbin/tcpdump -i eth1";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/tcpdumpcommand_notes.texinfo b/docs/reference/bodyparts/tcpdumpcommand_notes.texinfo
deleted file mode 100644
index bc20e005cf..0000000000
--- a/docs/reference/bodyparts/tcpdumpcommand_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-If this is defined, the monitor will try to interface with the TCP stream and
-monitor generic package categories for anomalies.
diff --git a/docs/reference/bodyparts/threads_example.texinfo b/docs/reference/bodyparts/threads_example.texinfo
deleted file mode 100644
index 6691c43423..0000000000
--- a/docs/reference/bodyparts/threads_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body process_select example
-{
-threads => irange(1,5);
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/threads_notes.texinfo b/docs/reference/bodyparts/threads_notes.texinfo
deleted file mode 100644
index 139597f9cb..0000000000
--- a/docs/reference/bodyparts/threads_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-
diff --git a/docs/reference/bodyparts/time_stamps_example.texinfo b/docs/reference/bodyparts/time_stamps_example.texinfo
deleted file mode 100644
index 0e4fd02ea3..0000000000
--- a/docs/reference/bodyparts/time_stamps_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body reporter control
-{
-time_stamps => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/time_stamps_notes.texinfo b/docs/reference/bodyparts/time_stamps_notes.texinfo
deleted file mode 100644
index 119088cf40..0000000000
--- a/docs/reference/bodyparts/time_stamps_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-This option is only necessary with the default build directory. This
-can be used to keep snapshots of the system but it will result in a
-lot of storage be consumed. For most purposes CFEngine is programmed
-to forget the past at a predictable rate and there is no need to
-override this.
diff --git a/docs/reference/bodyparts/timeout_example.texinfo b/docs/reference/bodyparts/timeout_example.texinfo
deleted file mode 100644
index c875ff1b22..0000000000
--- a/docs/reference/bodyparts/timeout_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body runagent control
-{
-timeout => "10";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/timeout_notes.texinfo b/docs/reference/bodyparts/timeout_notes.texinfo
deleted file mode 100644
index 725e5b64b9..0000000000
--- a/docs/reference/bodyparts/timeout_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-Timeout in seconds.
diff --git a/docs/reference/bodyparts/timer_policy_example.texinfo b/docs/reference/bodyparts/timer_policy_example.texinfo
deleted file mode 100644
index e844b6b713..0000000000
--- a/docs/reference/bodyparts/timer_policy_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body classes example
-{
-timer_policy => "reset";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/timer_policy_notes.texinfo b/docs/reference/bodyparts/timer_policy_notes.texinfo
deleted file mode 100644
index 33483f537c..0000000000
--- a/docs/reference/bodyparts/timer_policy_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-The in most cases resetting a timer will give a more honest appraisal
-of which classes are currently important, but if we want to activate
-a response of limited duration as a rare event then an asbolute
-time limit is useful.
diff --git a/docs/reference/bodyparts/timezone_example.texinfo b/docs/reference/bodyparts/timezone_example.texinfo
deleted file mode 100644
index 489475fe3f..0000000000
--- a/docs/reference/bodyparts/timezone_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-timezone => { "MET", "CET", "GMT+1" };
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/timezone_notes.texinfo b/docs/reference/bodyparts/timezone_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/bodyparts/timezone_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/bodyparts/touch_example.texinfo b/docs/reference/bodyparts/touch_example.texinfo
deleted file mode 100644
index a93dbbb205..0000000000
--- a/docs/reference/bodyparts/touch_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-files:
-
- "/path/file"
-
- touch => "true";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/touch_notes.texinfo b/docs/reference/bodyparts/touch_notes.texinfo
deleted file mode 100644
index 139597f9cb..0000000000
--- a/docs/reference/bodyparts/touch_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-
diff --git a/docs/reference/bodyparts/track_growing_file_example.texinfo b/docs/reference/bodyparts/track_growing_file_example.texinfo
deleted file mode 100644
index b420c45d5b..0000000000
--- a/docs/reference/bodyparts/track_growing_file_example.texinfo
+++ /dev/null
@@ -1,33 +0,0 @@
-
-@verbatim
-bundle monitor watch
-{
-measurements:
-
- "/home/mark/tmp/file"
-
- handle => "line_counter",
- stream_type => "file",
- data_type => "counter",
- match_value => scan_log("MYLINE.*"),
- history_type => "log",
- action => sample_rate("0");
-
-}
-
-#
-
-body match_value scan_log(x)
-{
-select_line_matching => "^$(x)$";
-track_growing_file => "true";
-}
-
-#
-
-body action sample_rate(x)
-{
-ifelapsed => "$(x)";
-expireafter => "10";
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/track_growing_file_notes.texinfo b/docs/reference/bodyparts/track_growing_file_notes.texinfo
deleted file mode 100644
index 4a4c850a68..0000000000
--- a/docs/reference/bodyparts/track_growing_file_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-This option applies only to file based input streams. If this is
-@samp{true}, CFEngine treats the file as if it were a log file,
-growing continuously. Thus the monitor reads all new entries since the
-last sampling time on each invocation. In this way, the monitor does
-not count lines in the log file redundantly.
-
-This makes a log pattern promise equivalent to something like
-@samp{tail -f logfile | grep pattern} in Unix parlance.
diff --git a/docs/reference/bodyparts/track_value_example.texinfo b/docs/reference/bodyparts/track_value_example.texinfo
deleted file mode 100644
index 44876b0289..0000000000
--- a/docs/reference/bodyparts/track_value_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body agent control
-{
-track_value => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/track_value_notes.texinfo b/docs/reference/bodyparts/track_value_notes.texinfo
deleted file mode 100644
index ffc2164591..0000000000
--- a/docs/reference/bodyparts/track_value_notes.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-If this is true, CFEngine generates a log in
-@file{WORKDIR/state/cf_value.log} of the estmated `business value' of
-the system automation as a running log, @code{value_kept}, etc. The
-format of the file is
-@verbatim
-date,sum value kept,sum value repaired,sum value notkept
-@end verbatim
diff --git a/docs/reference/bodyparts/transformer_example.texinfo b/docs/reference/bodyparts/transformer_example.texinfo
deleted file mode 100644
index 6b23d3a1c8..0000000000
--- a/docs/reference/bodyparts/transformer_example.texinfo
+++ /dev/null
@@ -1,25 +0,0 @@
-
-@verbatim
-
-files:
- "/home/mark/tmp/testcopy"
-
- file_select => pdf_files,
- transformer => "/usr/bin/gzip $(this.promiser)",
- depth_search => recurse("inf");
-
-@end verbatim
-
-@verbatim
-
- classes:
- "do_update" expression => isnewerthan("/etc/postfix/alias",
- "/etc/postfix/alias.cdb");
-
- files:
- "/etc/postfix/alias.cdb"
- create => "true", # Must have this!
- transformer => "/usr/sbin/postalias /etc/postfix/alias",
- ifvarclass => "do_update";
-
-@end verbatim
diff --git a/docs/reference/bodyparts/transformer_notes.texinfo b/docs/reference/bodyparts/transformer_notes.texinfo
deleted file mode 100644
index d6fcd5009a..0000000000
--- a/docs/reference/bodyparts/transformer_notes.texinfo
+++ /dev/null
@@ -1,45 +0,0 @@
-
-A command to execute, usually for the promised file to transform it to
-something else (but possibly to create the promised file based on a different
-origin file). The examples above show both types of promises.
-
-The promiser file must exist in order to effect the transformer.
-
-In the first example, the promise is made on the file that we wish to
-transform. If the promised file exists, the transformer will change the
-file to a compressed version (and the next time CFEngine runs, the promised
-file will no longer exist, because it now has the @samp{.gz} extension).
-
-In the second example, the promise is made on the file @i{resulting from} the
-transformation (and the promise is conditional on the original file being
-newer than the result file). In this case, we @i{must} specify @samp{create
-=> true}. If we do not, then if the promised file is removed, the
-transformer will not be executed.
-
-Note also that if you use the @code{$(this.promiser)}
-variable or other variable in this command, and the file object contains
-spaces you should quote the variable, e.g.
-
-@verbatim
- transformer => "/usr/bin/gzip \"$(this.promiser)\"",
-@end verbatim
-
-Note also that the transformer does not actually need to change the file.
-You can, for example, simply report on the existence of files with
-
-@verbatim
- transformer => "/bin/echo I found a file named $(this.promiser)",
-@end verbatim
-
-The file streams @code{stdout} and @code{stderr} are redirected by CFEngine, and
-will not appear in any output unless you run @code{cf-agent} with the
-@samp{-v} switch (or enable @code{verbose} in an @code{outputs}
-promise).
-
-It is possible to set classes based on the return code of a
-transformer-command in in a very flexible way. See the
-@code{kept_returncodes}, @code{repaired_returncodes} and
-@code{failed_returncodes} attributes.
-
-Finally, you should note that the command is not run in a shell - which means
-that you cannot perform file redirection or create pipelines.
diff --git a/docs/reference/bodyparts/traverse_links_example.texinfo b/docs/reference/bodyparts/traverse_links_example.texinfo
deleted file mode 100644
index 8fb32a038d..0000000000
--- a/docs/reference/bodyparts/traverse_links_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body depth_search example
-{
-traverse_links => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/traverse_links_notes.texinfo b/docs/reference/bodyparts/traverse_links_notes.texinfo
deleted file mode 100644
index 25234cb829..0000000000
--- a/docs/reference/bodyparts/traverse_links_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-If this is true, @code{cf-agent} will treat symbolic links to
-directories as if they were directories. Normally this is considered a
-potentially dangerous assumption and links are not traversed.
diff --git a/docs/reference/bodyparts/trustkey_example.texinfo b/docs/reference/bodyparts/trustkey_example.texinfo
deleted file mode 100644
index 0e69dd47c7..0000000000
--- a/docs/reference/bodyparts/trustkey_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body copy_from example
-{
-trustkey => "true";
-}
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/trustkey_notes.texinfo b/docs/reference/bodyparts/trustkey_notes.texinfo
deleted file mode 100644
index ca3b1d6869..0000000000
--- a/docs/reference/bodyparts/trustkey_notes.texinfo
+++ /dev/null
@@ -1,16 +0,0 @@
-
-If the server's public key has not already been trusted, this
-allows us to accept the key in automated key-exchange.
-
-Note that, as a simple security precaution, trustkey should normally
-be set to @samp{false}, to avoid key exchange with a server one is not
-one hundred percent sure about, though the risks for a client are
-rather low. On the server-side however, trust is often granted to
-many clients or to a whole network in which possibly unauthorized
-parties might be able to obtain an IP address, thus the trust issue
-is most important on the server side.
-
-As soon as a public key has been exchanged, the trust option has no
-effect. A machine that has been trusted remains trusted until
-its key is manually revoked by a system administrator. Keys are
-stored in @file{WORKDIR/ppkeys}.
diff --git a/docs/reference/bodyparts/trustkeysfrom_example.texinfo b/docs/reference/bodyparts/trustkeysfrom_example.texinfo
deleted file mode 100644
index ae210e102c..0000000000
--- a/docs/reference/bodyparts/trustkeysfrom_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body server control
-{
-trustkeysfrom => { "10\.0\.1\.1", "192\.168\..*"};
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/trustkeysfrom_notes.texinfo b/docs/reference/bodyparts/trustkeysfrom_notes.texinfo
deleted file mode 100644
index 404d13f97a..0000000000
--- a/docs/reference/bodyparts/trustkeysfrom_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-If connecting clients' public keys have not already been trusted, this
-allows us to say `yes' to accepting the keys on trust. Normally this
-should be an empty list except in controlled circumstances.
-
-See also the warning about regular expressions in @code{allowallconnects}.
-
diff --git a/docs/reference/bodyparts/ttime_range_example.texinfo b/docs/reference/bodyparts/ttime_range_example.texinfo
deleted file mode 100644
index 1d2ef4628d..0000000000
--- a/docs/reference/bodyparts/ttime_range_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body process_select example
-{
-ttime_range => irange(0,accumulated(0,1,0,0,0,0));
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/ttime_range_notes.texinfo b/docs/reference/bodyparts/ttime_range_notes.texinfo
deleted file mode 100644
index cfa190824b..0000000000
--- a/docs/reference/bodyparts/ttime_range_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-This is total accumulated time for a process.
diff --git a/docs/reference/bodyparts/tty_example.texinfo b/docs/reference/bodyparts/tty_example.texinfo
deleted file mode 100644
index a72a240fda..0000000000
--- a/docs/reference/bodyparts/tty_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body process_select example
-{
-tty => "pts/[0-9]+";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/tty_notes.texinfo b/docs/reference/bodyparts/tty_notes.texinfo
deleted file mode 100644
index 238901559c..0000000000
--- a/docs/reference/bodyparts/tty_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Windows processes are not regarded as attached to any terminal, so
-they all have tty '?'.
diff --git a/docs/reference/bodyparts/type_check_example.texinfo b/docs/reference/bodyparts/type_check_example.texinfo
deleted file mode 100644
index 99dd733cdd..0000000000
--- a/docs/reference/bodyparts/type_check_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body copy_from example
-{
-type_check => "false";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/type_check_notes.texinfo b/docs/reference/bodyparts/type_check_notes.texinfo
deleted file mode 100644
index b0b5f9576a..0000000000
--- a/docs/reference/bodyparts/type_check_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-File types at source and destination should normally match in order for
-updates to overwrite them. This option allows this checking to be switched off.
diff --git a/docs/reference/bodyparts/umask_example.texinfo b/docs/reference/bodyparts/umask_example.texinfo
deleted file mode 100644
index a70d0f2220..0000000000
--- a/docs/reference/bodyparts/umask_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body contain example
-{
-umask => "077";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/umask_notes.texinfo b/docs/reference/bodyparts/umask_notes.texinfo
deleted file mode 100644
index 21c7b6dd13..0000000000
--- a/docs/reference/bodyparts/umask_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Sets the internal umask for the process. Default value for the mask is
-@samp{077}. On windows, umask is not supported and is thus ignored by
-windows versions of CFEngine.
diff --git a/docs/reference/bodyparts/units_example.texinfo b/docs/reference/bodyparts/units_example.texinfo
deleted file mode 100644
index a38088b82b..0000000000
--- a/docs/reference/bodyparts/units_example.texinfo
+++ /dev/null
@@ -1,15 +0,0 @@
-
-@verbatim
-
- "/var/cfengine/state/cf_rootprocs"
-
- handle => "monitor_self_watch",
- stream_type => "file",
- data_type => "int",
- history_type => "weekly",
- units => "kB",
- match_value => proc_value(".*cf-monitord.*",
-
- "root\s+[0-9.]+\s+[0-9.]+\s+[0-9.]+\s+[0-9.]+\s+([0-9]+).*");
-
-@end verbatim
diff --git a/docs/reference/bodyparts/units_notes.texinfo b/docs/reference/bodyparts/units_notes.texinfo
deleted file mode 100644
index ff3813968f..0000000000
--- a/docs/reference/bodyparts/units_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-This is an arbitary string used in documentation only.
diff --git a/docs/reference/bodyparts/unmount_example.texinfo b/docs/reference/bodyparts/unmount_example.texinfo
deleted file mode 100644
index 77bdb8540f..0000000000
--- a/docs/reference/bodyparts/unmount_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body mount example
-{
-unmount => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/unmount_notes.texinfo b/docs/reference/bodyparts/unmount_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/bodyparts/unmount_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/bodyparts/update_hashes_example.texinfo b/docs/reference/bodyparts/update_hashes_example.texinfo
deleted file mode 100644
index fec4bdad23..0000000000
--- a/docs/reference/bodyparts/update_hashes_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body changes example
-{
-update_hashes => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/update_hashes_notes.texinfo b/docs/reference/bodyparts/update_hashes_notes.texinfo
deleted file mode 100644
index 72c6108f1f..0000000000
--- a/docs/reference/bodyparts/update_hashes_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-If this is positive, file hashes should be updated as soon as a change
-is registered so that multiple warnings are not given about a single
-change. This applies to addition and removal too.
diff --git a/docs/reference/bodyparts/useresult_example.texinfo b/docs/reference/bodyparts/useresult_example.texinfo
deleted file mode 100644
index 07d9f3aa16..0000000000
--- a/docs/reference/bodyparts/useresult_example.texinfo
+++ /dev/null
@@ -1,41 +0,0 @@
-
-@verbatim
-
-body common control
-{
-bundlesequence => { "test" };
-}
-
-
-bundle agent test
-{
-methods:
-
- "any" usebundle => child,
- useresult => "my_return_var";
-
-
-reports:
-
- cfengine_3::
-
- "My return was: \"$(my_return_var[1])\" and \"$(my_return_var[2])\"";
-
-}
-
-bundle agent child
-{
-reports:
-
- cfengine_3::
-
- # Map these indices into the useresult namespace
-
- "this is a return value"
- bundle_return_value_index => "1";
-
- "this is another return value"
- bundle_return_value_index => "2";
-
-}
-@end verbatim
diff --git a/docs/reference/bodyparts/useresult_notes.texinfo b/docs/reference/bodyparts/useresult_notes.texinfo
deleted file mode 100644
index c5639439c0..0000000000
--- a/docs/reference/bodyparts/useresult_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-@i{History}: Was introduced in 3.4.0 (2012)
-
-It is currently believed that only scalar return values make sense, hence
-return values are limited to scalars.
diff --git a/docs/reference/bodyparts/useshell_example.texinfo b/docs/reference/bodyparts/useshell_example.texinfo
deleted file mode 100644
index 7738279d3d..0000000000
--- a/docs/reference/bodyparts/useshell_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body contain example
-{
-useshell => "useshell";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/useshell_notes.texinfo b/docs/reference/bodyparts/useshell_notes.texinfo
deleted file mode 100644
index 068ae0e9ca..0000000000
--- a/docs/reference/bodyparts/useshell_notes.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-The default is to @i{not} use a shell when executing commands. Use of a
-shell has both resource and security consequences. A shell consumes an
-extra process and inherits environment variables, reads commands from
-files and performs other actions beyond the control of CFEngine. If
-one does not need shell functionality such as piping through multiple
-commands then it is best to manage without it. In the windows version
-of CFEngine Nova, the command is run in the the ``Command Prompt'' if
-useshell is true.
-
-
diff --git a/docs/reference/bodyparts/value_kept_example.texinfo b/docs/reference/bodyparts/value_kept_example.texinfo
deleted file mode 100644
index 43106f6604..0000000000
--- a/docs/reference/bodyparts/value_kept_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-body action mydef
-{
-value_kept => "4.5"; # this promise is worth 4.5 dollars per hour
-value_repaired => "2.5"; # fixing this promise is worth 2.5 dollars per hour
-value_notkept => "-10.0"; # not keeping this promise costs is 10 dollars per hour
-ifelapsed => "60"; # one hour
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/value_kept_notes.texinfo b/docs/reference/bodyparts/value_kept_notes.texinfo
deleted file mode 100644
index efdf9b8fa4..0000000000
--- a/docs/reference/bodyparts/value_kept_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-If nothing is specified, the default value is +1.0.
-However, nothing is logged unless the agent control body switched on
-@samp{track_value => "true"}.
diff --git a/docs/reference/bodyparts/value_notkept_example.texinfo b/docs/reference/bodyparts/value_notkept_example.texinfo
deleted file mode 100644
index 43106f6604..0000000000
--- a/docs/reference/bodyparts/value_notkept_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-body action mydef
-{
-value_kept => "4.5"; # this promise is worth 4.5 dollars per hour
-value_repaired => "2.5"; # fixing this promise is worth 2.5 dollars per hour
-value_notkept => "-10.0"; # not keeping this promise costs is 10 dollars per hour
-ifelapsed => "60"; # one hour
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/value_notkept_notes.texinfo b/docs/reference/bodyparts/value_notkept_notes.texinfo
deleted file mode 100644
index 670ec22e58..0000000000
--- a/docs/reference/bodyparts/value_notkept_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-If nothing is specified, the default value is -1.0.
-However, nothing is logged unless the agent control body switched on
-@samp{track_value => "true"}.
diff --git a/docs/reference/bodyparts/value_repaired_example.texinfo b/docs/reference/bodyparts/value_repaired_example.texinfo
deleted file mode 100644
index 43106f6604..0000000000
--- a/docs/reference/bodyparts/value_repaired_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-body action mydef
-{
-value_kept => "4.5"; # this promise is worth 4.5 dollars per hour
-value_repaired => "2.5"; # fixing this promise is worth 2.5 dollars per hour
-value_notkept => "-10.0"; # not keeping this promise costs is 10 dollars per hour
-ifelapsed => "60"; # one hour
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/value_repaired_notes.texinfo b/docs/reference/bodyparts/value_repaired_notes.texinfo
deleted file mode 100644
index 0fe665d678..0000000000
--- a/docs/reference/bodyparts/value_repaired_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-If nothing is specified, the default value is 0.5.
-However, nothing is logged unless the agent control body switched on
-@samp{track_value => "true"}.
diff --git a/docs/reference/bodyparts/value_separator_example.texinfo b/docs/reference/bodyparts/value_separator_example.texinfo
deleted file mode 100644
index a2f73ae9e1..0000000000
--- a/docs/reference/bodyparts/value_separator_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body field_edit example
-{
-value_separator => ",";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/value_separator_notes.texinfo b/docs/reference/bodyparts/value_separator_notes.texinfo
deleted file mode 100644
index 510c703265..0000000000
--- a/docs/reference/bodyparts/value_separator_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-For example, elements in the group file are separated by @samp{:},
-but the lists of users in these fields are separated by @samp{,}.
diff --git a/docs/reference/bodyparts/verbose_example.texinfo b/docs/reference/bodyparts/verbose_example.texinfo
deleted file mode 100644
index fcc7c1dade..0000000000
--- a/docs/reference/bodyparts/verbose_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-
-@verbatim
-
-body agent control
-{
-verbose => "true";
-}
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/verbose_notes.texinfo b/docs/reference/bodyparts/verbose_notes.texinfo
deleted file mode 100644
index 7fb9591b6c..0000000000
--- a/docs/reference/bodyparts/verbose_notes.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-
-Equivalent to (and when present, overrides) the command line option @samp{-v}.
-Sets the default output level `permanently' for this promise.
-
-Every promiser makes an implicit default promise to use output settings declared
-using @code{outputs} promises.
-
diff --git a/docs/reference/bodyparts/verify_example.texinfo b/docs/reference/bodyparts/verify_example.texinfo
deleted file mode 100644
index 1e0f27d431..0000000000
--- a/docs/reference/bodyparts/verify_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body copy_from example
-{
-verify => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/verify_notes.texinfo b/docs/reference/bodyparts/verify_notes.texinfo
deleted file mode 100644
index cb58143184..0000000000
--- a/docs/reference/bodyparts/verify_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-This is a highly resource intensive option, not recommended
-for large file transfers.
diff --git a/docs/reference/bodyparts/version_example.texinfo b/docs/reference/bodyparts/version_example.texinfo
deleted file mode 100644
index 87b02fd61f..0000000000
--- a/docs/reference/bodyparts/version_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-
-
-@verbatim
-
-body common control
-{
-version => "1.2.3";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/version_notes.texinfo b/docs/reference/bodyparts/version_notes.texinfo
deleted file mode 100644
index d54fd8cda4..0000000000
--- a/docs/reference/bodyparts/version_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-The version string is used in error messages and reports.
-
-This string should not contain the colon @samp{:} character, as this has a special
-meaning in the context of knowledge management. This restriction might be lifted later.
diff --git a/docs/reference/bodyparts/vsize_example.texinfo b/docs/reference/bodyparts/vsize_example.texinfo
deleted file mode 100644
index 55ef1ce50f..0000000000
--- a/docs/reference/bodyparts/vsize_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body process_select example
-{
-vsize => irange("4000","9000");
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/vsize_notes.texinfo b/docs/reference/bodyparts/vsize_notes.texinfo
deleted file mode 100644
index 332b50e737..0000000000
--- a/docs/reference/bodyparts/vsize_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-On Windows, the virtual memory size is the amount of memory that
-cannot be shared with other processes. In Task Manager, this is
-called Commit Size (Windows 2008), or VM Size (Windows XP).
diff --git a/docs/reference/bodyparts/when_linking_children_example.texinfo b/docs/reference/bodyparts/when_linking_children_example.texinfo
deleted file mode 100644
index b0b73b951b..0000000000
--- a/docs/reference/bodyparts/when_linking_children_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-body link_from example
-{
-when_linking_children => "if_no_such_file";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/when_linking_children_notes.texinfo b/docs/reference/bodyparts/when_linking_children_notes.texinfo
deleted file mode 100644
index 8d49a52a63..0000000000
--- a/docs/reference/bodyparts/when_linking_children_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-The options refer to what happens if the directory exists already and
-is already partially populated with files. If the directory being
-copied from contains a file with the same name as that of a link
-to be created, we must decide whether to override the existing
-destination object with a link or simply omit the automatic
-linkage for files that already exist. The latter case can
-be used to make a copy of one directory with certain fields
-overridden.
diff --git a/docs/reference/bodyparts/when_no_source_example.texinfo b/docs/reference/bodyparts/when_no_source_example.texinfo
deleted file mode 100644
index 190784ca27..0000000000
--- a/docs/reference/bodyparts/when_no_source_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body link_from example
-{
-when_no_source => "force";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/when_no_source_notes.texinfo b/docs/reference/bodyparts/when_no_source_notes.texinfo
deleted file mode 100644
index 81ae583e02..0000000000
--- a/docs/reference/bodyparts/when_no_source_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-If we try to create a link to a file that does not exist a link, how
-should CFEngine respond? The options are to force the creation to
-a file that does not (yet) exist, delete any existing link, or do nothing.
diff --git a/docs/reference/bodyparts/whitespace_policy_example.texinfo b/docs/reference/bodyparts/whitespace_policy_example.texinfo
deleted file mode 100644
index a6369ebf95..0000000000
--- a/docs/reference/bodyparts/whitespace_policy_example.texinfo
+++ /dev/null
@@ -1,13 +0,0 @@
-
-@verbatim
-bundle edit_line Insert(service, filename)
-{
-insert_lines:
-
- "$(service).* $(filename)"
-
- whitespace_policy => { "ignore_trailing", "ignore_embedded" };
-
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/whitespace_policy_notes.texinfo b/docs/reference/bodyparts/whitespace_policy_notes.texinfo
deleted file mode 100644
index 769d495d6d..0000000000
--- a/docs/reference/bodyparts/whitespace_policy_notes.texinfo
+++ /dev/null
@@ -1,25 +0,0 @@
-
-The white space matching policy applies only to @code{insert_lines},
-as a convenience. It works by rewriting the insert string as a regular
-expression when @i{matching} lines (that is, when determining if the line is
-already in the file), but leaving the string as specified when
-actually inserting it.
-
-Simply put, the `does this line exist' test will be changed to a
-regexp match. The line being tested will optionally have "\s*"
-prepended or appended if @code{ignore_leading} or
-@code{ignore_trailing} is specified, and if @code{ignore_imbedded} is
-used then all embedded whitespaces are replaced with @samp{\s+}. You may
-specify more than one @code{whitespace_policy} -- they are additive.
-
-Any regular
-expression meta-characters that exist in your input line will be escaped, so
-that you can still, for example, safely insert a line like
-@samp{"authpriv.* /var/log/something"} into your syslog config file.
-
-@b{History}: This attribute was introduced in CFEngine version 3.0.5 (2010)
-
-@noindent @b{Default value}:@*
-
-@code{exact_match} (so unless you use this new attribute, your
-@code{insert_line} promises should behave as before.
diff --git a/docs/reference/bodyparts/xdev_example.texinfo b/docs/reference/bodyparts/xdev_example.texinfo
deleted file mode 100644
index 6068415487..0000000000
--- a/docs/reference/bodyparts/xdev_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body depth_search example
-{
-xdev => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/bodyparts/xdev_notes.texinfo b/docs/reference/bodyparts/xdev_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/bodyparts/xdev_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/bodyparts/xor_example.texinfo b/docs/reference/bodyparts/xor_example.texinfo
deleted file mode 100644
index 1276b084f6..0000000000
--- a/docs/reference/bodyparts/xor_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-@verbatim
-
-classes:
-
- "another_global" xor => { "any", "linux", "solaris"};
-
-@end verbatim
-
diff --git a/docs/reference/bodyparts/xor_notes.texinfo b/docs/reference/bodyparts/xor_notes.texinfo
deleted file mode 100644
index 2bc670cabf..0000000000
--- a/docs/reference/bodyparts/xor_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-Behaves as the XOR operation on class expressions.
-It can be used to define a class if exactly one of the class expressions
-on the RHS matches.
-
diff --git a/docs/reference/bundletypes/agent_example.texinfo b/docs/reference/bundletypes/agent_example.texinfo
deleted file mode 100644
index 32f2197670..0000000000
--- a/docs/reference/bundletypes/agent_example.texinfo
+++ /dev/null
@@ -1,32 +0,0 @@
-
-@cartouche
-@smallexample
-
-bundle agent main(parameter)
-
-@{
-vars:
-
- "sys_files" slist => @{
- "/etc/passwd",
- "/etc/services"
- @};
-files:
-
- "$(sys_files)" perms => p("root","0644"),
- changes => trip_wire;
-
- "/etc/shadow" perms => p("root","0600"),
- changes => trip_wire;
-
- "/usr" changes => trip_wire,
- depth_search => recurse("inf");
-
- "/tmp" delete => tidy,
- file_select => days("2"),
- depth_search => recurse("inf");
-
-@}
-
-@end smallexample
-@end cartouche
diff --git a/docs/reference/bundletypes/agent_notes.texinfo b/docs/reference/bundletypes/agent_notes.texinfo
deleted file mode 100644
index b85358fd55..0000000000
--- a/docs/reference/bundletypes/agent_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Agent bundles contain user-defined promises for @code{cf-agent}. The
-types of promises and their corresponding bodies are detailed below.
diff --git a/docs/reference/bundletypes/common_example.texinfo b/docs/reference/bundletypes/common_example.texinfo
deleted file mode 100644
index a4085f0ccb..0000000000
--- a/docs/reference/bundletypes/common_example.texinfo
+++ /dev/null
@@ -1,17 +0,0 @@
-
-@cartouche
-@smallexample
-
-bundle common globals
-@{
-vars:
-
- "global_var" string => "value";
-
-classes:
-
- "global_class" expression => "value";
-@}
-
-@end smallexample
-@end cartouche
diff --git a/docs/reference/bundletypes/common_notes.texinfo b/docs/reference/bundletypes/common_notes.texinfo
deleted file mode 100644
index 94acf4b9ec..0000000000
--- a/docs/reference/bundletypes/common_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-Common bundles may only contain the promise types that are common to
-all bodies. Their main function is to define cross-component global
-definitions. Common bundles are observed by every agent, whereas the
-agent specific bundle types are ignored by components other than the
-intended recipient.
diff --git a/docs/reference/bundletypes/executor_example.texinfo b/docs/reference/bundletypes/executor_example.texinfo
deleted file mode 100644
index 508a66cdda..0000000000
--- a/docs/reference/bundletypes/executor_example.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-There are presently no bundles of this type.
-
diff --git a/docs/reference/bundletypes/executor_notes.texinfo b/docs/reference/bundletypes/executor_notes.texinfo
deleted file mode 100644
index b64777f87d..0000000000
--- a/docs/reference/bundletypes/executor_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-There are presently no bundle of this type.
-
diff --git a/docs/reference/bundletypes/monitor_example.texinfo b/docs/reference/bundletypes/monitor_example.texinfo
deleted file mode 100644
index acb18af3bb..0000000000
--- a/docs/reference/bundletypes/monitor_example.texinfo
+++ /dev/null
@@ -1,28 +0,0 @@
-
-@cartouche
-
-@smallexample
-
-bundle monitor example
-@{
-measurements:
-
- # Discover disk device information
-
- "/bin/df"
-
- handle => "free_diskspace_watch",
- stream_type => "pipe",
- data_type => "slist",
- history_type => "static",
- units => "device",
- match_value => file_systems;
-
-
-@}
-
-@end smallexample
-
-@end cartouche
-
-Monitor bundles contain user defined promises for system discovery and monitoring.
diff --git a/docs/reference/bundletypes/monitor_notes.texinfo b/docs/reference/bundletypes/monitor_notes.texinfo
deleted file mode 100644
index 139597f9cb..0000000000
--- a/docs/reference/bundletypes/monitor_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-
diff --git a/docs/reference/bundletypes/runagent_example.texinfo b/docs/reference/bundletypes/runagent_example.texinfo
deleted file mode 100644
index 9bb4ccde74..0000000000
--- a/docs/reference/bundletypes/runagent_example.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-There are currently no bundles in the run agent.
-
diff --git a/docs/reference/bundletypes/runagent_notes.texinfo b/docs/reference/bundletypes/runagent_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/bundletypes/runagent_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/bundletypes/server_example.texinfo b/docs/reference/bundletypes/server_example.texinfo
deleted file mode 100644
index 87176e9286..0000000000
--- a/docs/reference/bundletypes/server_example.texinfo
+++ /dev/null
@@ -1,25 +0,0 @@
-
-@cartouche
-@smallexample
-
-bundle server access_rules()
-
-@{
-access:
-
- "/home/mark/PrivateFiles"
-
- admit => @{ ".*\.example\.org" @};
-
- "/home/mark/\.cfagent/bin/cf-agent"
-
- admit => @{ ".*\.example\.org" @};
-
-roles:
-
- ".*" authorize => @{ "mark" @};
-@}
-
-
-@end smallexample
-@end cartouche
diff --git a/docs/reference/bundletypes/server_notes.texinfo b/docs/reference/bundletypes/server_notes.texinfo
deleted file mode 100644
index 6a45781a8c..0000000000
--- a/docs/reference/bundletypes/server_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Bundles in the server describe access promises on specific file and class
-objects supplied by the server to clients.
diff --git a/docs/reference/bundletypes/string_notes.texinfo b/docs/reference/bundletypes/string_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/bundletypes/string_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/control/agent_example.texinfo b/docs/reference/control/agent_example.texinfo
deleted file mode 100644
index 5bd3c33354..0000000000
--- a/docs/reference/control/agent_example.texinfo
+++ /dev/null
@@ -1,22 +0,0 @@
-
-@cartouche
-@smallexample
-
-body agent control
-@{
-123_456_789::
-
- domain => "mydomain.com";
-
-123_456_789_111::
-
- auditing => "true";
-
-any::
-
- fullencryption => "true";
-
-@}
-
-@end smallexample
-@end cartouche
diff --git a/docs/reference/control/agent_notes.texinfo b/docs/reference/control/agent_notes.texinfo
deleted file mode 100644
index dc3d8998c1..0000000000
--- a/docs/reference/control/agent_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-
-Settings describing the details of the fixed behavioural promises made by
-@code{cf-agent}.
diff --git a/docs/reference/control/common_example.texinfo b/docs/reference/control/common_example.texinfo
deleted file mode 100644
index 857ccdacf3..0000000000
--- a/docs/reference/control/common_example.texinfo
+++ /dev/null
@@ -1,29 +0,0 @@
-
-
-@cartouche
-@smallexample
-
-body common control
-
-@{
-inputs => @{
- "update.cf",
- "library.cf"
- @};
-
-bundlesequence => @{
- update("policy_host.domain.tld"),
- "main",
- "cfengine2"
- @};
-
-goal_categories => @{ "goals", "targets", "milestones" @};
-goal_patterns => @{ "goal_.*", "target.*" @};
-
-output_prefix => "cfengine>";
-version => "1.2.3";
-@}
-
-@end smallexample
-@end cartouche
-
diff --git a/docs/reference/control/common_notes.texinfo b/docs/reference/control/common_notes.texinfo
deleted file mode 100644
index 74cf44d4cd..0000000000
--- a/docs/reference/control/common_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-The @code{common} control body refers to those promises that are
-hard-coded into all the components of CFEngine, and therefore affect
-the behaviour of all the components.
diff --git a/docs/reference/control/executor_example.texinfo b/docs/reference/control/executor_example.texinfo
deleted file mode 100644
index 313d38022a..0000000000
--- a/docs/reference/control/executor_example.texinfo
+++ /dev/null
@@ -1,16 +0,0 @@
-
-@cartouche
-@smallexample
-
-body executor control
-
-@{
-splaytime => "5";
-mailto => "cfengine@@example.org";
-mailfrom => "cfengine@@$(host).example.org";
-smtpserver => "localhost";
-schedule => @{ "Min00_05", "Min30_35" @}
-@}
-
-@end smallexample
-@end cartouche
diff --git a/docs/reference/control/executor_notes.texinfo b/docs/reference/control/executor_notes.texinfo
deleted file mode 100644
index 277335e0b8..0000000000
--- a/docs/reference/control/executor_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-These body settings determine the behaviour of @code{cf-execd}, including
-scheduling times and output capture to @file{WORKDIR/outputs} and relay via email.
-Note that the @code{splaytime} and @code{schedule} parameters
-are now coded here rather than (as previously) in the agent.
diff --git a/docs/reference/control/file_example.texinfo b/docs/reference/control/file_example.texinfo
deleted file mode 100644
index 270cb35c56..0000000000
--- a/docs/reference/control/file_example.texinfo
+++ /dev/null
@@ -1,14 +0,0 @@
-
-@verbatim
-
-body file control
-{
-namespace => "name1";
-}
-
-bundle agent private
-{
-....
-}
-
-@end verbatim
diff --git a/docs/reference/control/file_notes.texinfo b/docs/reference/control/file_notes.texinfo
deleted file mode 100644
index d7dc018b6c..0000000000
--- a/docs/reference/control/file_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@i{History}: Was introduced in 3.4.0, Enterprise 3.0.0 (2012)
-
-
-This directive can be given multiple times within any file, outside of
-body and bundle definitions.
diff --git a/docs/reference/control/hub_example.texinfo b/docs/reference/control/hub_example.texinfo
deleted file mode 100644
index ee7e1e3ff8..0000000000
--- a/docs/reference/control/hub_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-body hub control
-{
-export_zenoss => "/var/www/reports/summary.z";
-}
-
-@end verbatim
diff --git a/docs/reference/control/hub_notes.texinfo b/docs/reference/control/hub_notes.texinfo
deleted file mode 100644
index e69de29bb2..0000000000
diff --git a/docs/reference/control/monitor_example.texinfo b/docs/reference/control/monitor_example.texinfo
deleted file mode 100644
index 1525cb9f53..0000000000
--- a/docs/reference/control/monitor_example.texinfo
+++ /dev/null
@@ -1,16 +0,0 @@
-
-@cartouche
-@smallexample
-
-body monitor control()
- @{
- #version => "1.2.3.4";
-
- forgetrate => "0.7";
- tcpdump => "false";
- tcpdumpcommand => "/usr/sbin/tcpdump -i eth1 -n -t -v";
-
- @}
-
-@end smallexample
-@end cartouche
diff --git a/docs/reference/control/monitor_notes.texinfo b/docs/reference/control/monitor_notes.texinfo
deleted file mode 100644
index b9f52caf00..0000000000
--- a/docs/reference/control/monitor_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-Settings describing the details of the fixed behavioural promises made by
-@code{cf-monitord}.
-The system defaults will be sufficient for most users. This
-configurability potential, however, will be a key to developing the
-integrated monitoring capabilities of CFEngine.
diff --git a/docs/reference/control/runagent_example.texinfo b/docs/reference/control/runagent_example.texinfo
deleted file mode 100644
index a946c94c78..0000000000
--- a/docs/reference/control/runagent_example.texinfo
+++ /dev/null
@@ -1,15 +0,0 @@
-
-@cartouche
-@smallexample
-
-body runagent control
-@{
-# default port is 5308
-
-hosts => @{ "127.0.0.1:5308", "eternity.iu.hio.no:80", "slogans.iu.hio.no" @};
-
-#output_to_file => "true";
-@}
-
-@end smallexample
-@end cartouche
diff --git a/docs/reference/control/runagent_notes.texinfo b/docs/reference/control/runagent_notes.texinfo
deleted file mode 100644
index eb08ad20db..0000000000
--- a/docs/reference/control/runagent_notes.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-Settings describing the details of the fixed behavioural promises made by
-@code{cf-runagent}.
-The most important parameter here is the list of hosts that the agent
-will poll for connections. This is easily read in from a file list,
-however when doing so always have a stable input source that does not
-depend on the network (including a database or directory service) in
-any way: introducing such dependencies makes configuration brittle.
diff --git a/docs/reference/control/server_example.texinfo b/docs/reference/control/server_example.texinfo
deleted file mode 100644
index 46f020b259..0000000000
--- a/docs/reference/control/server_example.texinfo
+++ /dev/null
@@ -1,16 +0,0 @@
-
-@cartouche
-@smallexample
-
-body server control
-
-@{
-allowconnects => @{ "127.0.0.1" , "::1" , ".*\.example\.org" @};
-allowallconnects => @{ "127.0.0.1" , "::1" , ".*\.example\.org" @};
-
-# Uncomment me under controlled circumstances
-#trustkeysfrom => @{ "127.0.0.1" , "::1" , ".*\.example\.org" @};
-@}
-
-@end smallexample
-@end cartouche
diff --git a/docs/reference/control/server_notes.texinfo b/docs/reference/control/server_notes.texinfo
deleted file mode 100644
index e8fdafe9e8..0000000000
--- a/docs/reference/control/server_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-Settings describing the details of the fixed behavioural promises made by
-@code{cf-serverd}.
-Server controls are mainly about determining access policy for the
-connection protocol: i.e. access to the server itself. Access to
-specific files must be granted in addition.
diff --git a/docs/reference/filelogic.png b/docs/reference/filelogic.png
deleted file mode 100644
index 01835571c6..0000000000
Binary files a/docs/reference/filelogic.png and /dev/null differ
diff --git a/docs/reference/functions/accessedbefore_example.texinfo b/docs/reference/functions/accessedbefore_example.texinfo
deleted file mode 100644
index a5a69a3500..0000000000
--- a/docs/reference/functions/accessedbefore_example.texinfo
+++ /dev/null
@@ -1,27 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-classes:
-
- "do_it" and => { accessedbefore("/tmp/earlier","/tmp/later"), "linux" };
-
-reports:
-
- do_it::
-
- "The secret changes have been accessed after the reference time";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/accessedbefore_notes.texinfo b/docs/reference/functions/accessedbefore_notes.texinfo
deleted file mode 100644
index ee2784ea8c..0000000000
--- a/docs/reference/functions/accessedbefore_notes.texinfo
+++ /dev/null
@@ -1,13 +0,0 @@
-
-The function accesses the @code{atime} fields of a file and makes a comparison.
-
-@smallexample
-
- touch /tmp/reference
- touch /tmp/secretfile
-
- /var/cfengine/bin/cf-agent -f ./unit_accessed_before.cf -K
- R: The secret changes have been accessed after the reference time
-
-@end smallexample
-
diff --git a/docs/reference/functions/accumulated_example.texinfo b/docs/reference/functions/accumulated_example.texinfo
deleted file mode 100644
index 151134f024..0000000000
--- a/docs/reference/functions/accumulated_example.texinfo
+++ /dev/null
@@ -1,40 +0,0 @@
-
-@verbatim
-
-bundle agent testbundle
-
-{
-processes:
-
- ".*"
-
- process_count => anyprocs,
- process_select => proc_finder;
-
-reports:
-
- any_procs::
-
- "Found processes in range";
-}
-
-########################################################
-
-body process_select proc_finder
-
-{
-ttime_range => irange(accumulated(0,0,0,0,2,0),accumulated(0,0,0,0,20,0));
-process_result => "ttime";
-}
-
-########################################################
-
-body process_count anyprocs
-
-{
-match_range => "0,0";
-out_of_range_define => { "any_procs" };
-}
-
-@end verbatim
-
diff --git a/docs/reference/functions/accumulated_notes.texinfo b/docs/reference/functions/accumulated_notes.texinfo
deleted file mode 100644
index 41a8943709..0000000000
--- a/docs/reference/functions/accumulated_notes.texinfo
+++ /dev/null
@@ -1,30 +0,0 @@
-
-In the example we look for processes that have accumulated between 2 and 20
-minutes of total run time.
-
-@noindent @b{ARGUMENTS}:
-
-The @code{accumulated} function measures total accumulated runtime.
-Arguments are applied additively, so that accumulated(0,0,2,27,90,0)
-means "2 days, 27 hours and 90 minutes of runtime" " -- however, you
-are strongly encouraged to keep your usage of @code{accumulated}
-sensible and readable, e.g., accumulated(0,0,0,48,0,0) or
-accumulated(0,0,0,0,90,0).
-
-@table @samp
-@item Years
-Years of run time. For convenience in conversion, a year of runtime is always
-365 days (one year equals 31,536,000 seconds).
-@item Month
-Months of run time. For convenience in conversion, a month of runtime is
-always equal to 30 days of runtime (one month equals 2,592,000 seconds).
-@item Day
-Days of runtime (one day equals 86,400 seconds)
-@item Hours
-Hours of runtime
-@item Minutes
-Minutes of runtime
-0-59
-@item Seconds
-Seconds of runtime
-@end table
diff --git a/docs/reference/functions/ago_example.texinfo b/docs/reference/functions/ago_example.texinfo
deleted file mode 100644
index 48c2a8d5c4..0000000000
--- a/docs/reference/functions/ago_example.texinfo
+++ /dev/null
@@ -1,40 +0,0 @@
-
-@verbatim
-
-bundle agent testbundle
-
-{
-processes:
-
- ".*"
-
- process_count => anyprocs,
- process_select => proc_finder;
-
-reports:
-
- any_procs::
-
- "Found processes out of range";
-}
-
-########################################################
-
-body process_select proc_finder
-
-{
-# Processes started between 5.5 hours and 20 minutes ago
-stime_range => irange(ago(0,0,0,5,30,0),ago(0,0,0,0,20,0));
-process_result => "stime";
-}
-
-########################################################
-
-body process_count anyprocs
-
-{
-match_range => "0,0";
-out_of_range_define => { "any_procs" };
-}
-
-@end verbatim
diff --git a/docs/reference/functions/ago_notes.texinfo b/docs/reference/functions/ago_notes.texinfo
deleted file mode 100644
index e7bcf92393..0000000000
--- a/docs/reference/functions/ago_notes.texinfo
+++ /dev/null
@@ -1,29 +0,0 @@
-
-The @code{ago} function measures time relative to now. Arguments are applied
-in order, so that ago(0,18,55,27,0,0) means "18 months, 55 days, and 27 hours
-ago" -- however, you are strongly encouraged to keep your usage of @code{ago}
-sensible and readable, e.g., ago(0,0,120,0,0,0) or ago(0,0,0,72,0,0).
-
-@noindent @b{ARGUMENTS}:
-
-@table @samp
-@item Years
-Years ago. If today is February 29, and "@b{n} years ago" is not within a
-leap-year, February 28 will be used.
-@item Month
-Months ago. If the current month has more days that "@b{n} months ago", the
-last day of "@b{n} months ago" will be used (e.g., if today is April 31 and
-you compute a date 1 month ago, the resulting date will be March 30).
-equal to 30 days of runtime (one month equals 2,592,000 seconds).
-@item Day
-Days ago (you may, for example, specify 120 days)
-@item Hours
-Hours ago. Since all computation are done using "Epoch time", 1 hour ago will
-alway result in a time 60 minutes in the past, even during the transition
-from Da ylight time to Standard time.
-@item Minutes
-Minutes ago
-0-59
-@item Seconds
-Seconds ago
-@end table
diff --git a/docs/reference/functions/and_example.texinfo b/docs/reference/functions/and_example.texinfo
deleted file mode 100644
index 3055e125a9..0000000000
--- a/docs/reference/functions/and_example.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-@verbatim
-
-commands:
- "/usr/bin/generate_config $(config)"
- ifvarclass => and(not(fileexists("/etc/config/$(config)")), "generating_configs");
-
-@end verbatim
diff --git a/docs/reference/functions/and_notes.texinfo b/docs/reference/functions/and_notes.texinfo
deleted file mode 100644
index 0ea8f981f5..0000000000
--- a/docs/reference/functions/and_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-@i{History}: Was introduced in 3.2.0, Nova 2.1.0 (2011)
diff --git a/docs/reference/functions/canonify_example.texinfo b/docs/reference/functions/canonify_example.texinfo
deleted file mode 100644
index 8bd1c61546..0000000000
--- a/docs/reference/functions/canonify_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-commands:
-
- "/var/cfengine/bin/$(component)"
-
- ifvarclass => canonify("start_$(component)");
-
-@end verbatim
-
diff --git a/docs/reference/functions/canonify_notes.texinfo b/docs/reference/functions/canonify_notes.texinfo
deleted file mode 100644
index f197c92a88..0000000000
--- a/docs/reference/functions/canonify_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-This is for use in turning arbitrary text into class data, @xref{Function classify}.
-
diff --git a/docs/reference/functions/changedbefore_example.texinfo b/docs/reference/functions/changedbefore_example.texinfo
deleted file mode 100644
index bad889d7ce..0000000000
--- a/docs/reference/functions/changedbefore_example.texinfo
+++ /dev/null
@@ -1,27 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-classes:
-
- "do_it" and => { changedbefore("/tmp/earlier","/tmp/later"), "linux" };
-
-reports:
-
- do_it::
-
- "The derived file needs updating";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/changedbefore_notes.texinfo b/docs/reference/functions/changedbefore_notes.texinfo
deleted file mode 100644
index a73e2bff24..0000000000
--- a/docs/reference/functions/changedbefore_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Change times include both file permissions and file contents. Comparisons like this are normally
-used for updating files (like the `make' command).
diff --git a/docs/reference/functions/classesmatching_example.texinfo b/docs/reference/functions/classesmatching_example.texinfo
deleted file mode 100644
index 78aa034c94..0000000000
--- a/docs/reference/functions/classesmatching_example.texinfo
+++ /dev/null
@@ -1,20 +0,0 @@
-
-@verbatim
-
-body common control
-{
- bundlesequence => { run };
-}
-
-bundle agent run
-{
- vars:
- "all" slist => classesmatching(".*");
- "c" slist => classesmatching("cfengine");
- reports:
- "All classes = $(all)";
- "Classes matching 'cfengine' = $(c)";
-}
-
-
-@end verbatim
diff --git a/docs/reference/functions/classesmatching_notes.texinfo b/docs/reference/functions/classesmatching_notes.texinfo
deleted file mode 100644
index 18a2b3cf3c..0000000000
--- a/docs/reference/functions/classesmatching_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-The regular expression is matched against the current list of defined
-classes (hard, then soft, then local to the current bundle). This
-regular expression does not need to be anchored.
-
-@xref{Anchored vs. unanchored regular expressions}.
-
-This function replaces the @code{allclasses.txt} static file available
-in older versions of CFEngine.
diff --git a/docs/reference/functions/classify_example.texinfo b/docs/reference/functions/classify_example.texinfo
deleted file mode 100644
index 97ab75c7f1..0000000000
--- a/docs/reference/functions/classify_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-@verbatim
-
-classes:
-
- "i_am_the_policy_host" expression => classify("master.example.org");
-
-@end verbatim
diff --git a/docs/reference/functions/classify_notes.texinfo b/docs/reference/functions/classify_notes.texinfo
deleted file mode 100644
index 0e928aba13..0000000000
--- a/docs/reference/functions/classify_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-This function returns true if the canonical form of
-the argument is already a defined class. This is useful, for example,
-transforming variables into classes, @xref{Function canonify}.
diff --git a/docs/reference/functions/classmatch_example.texinfo b/docs/reference/functions/classmatch_example.texinfo
deleted file mode 100644
index 8b14ee2290..0000000000
--- a/docs/reference/functions/classmatch_example.texinfo
+++ /dev/null
@@ -1,27 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-classes:
-
- "do_it" and => { classmatch(".*_cfengine_com"), "linux" };
-
-reports:
-
- do_it::
-
- "Host matches pattern";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/classmatch_notes.texinfo b/docs/reference/functions/classmatch_notes.texinfo
deleted file mode 100644
index 49de454d4d..0000000000
--- a/docs/reference/functions/classmatch_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-The regular expression is matched against the current list of defined classes.
-The regular expression must match a complete class for the expression to
-be true, that is, the regex is anchored,
-@xref{Anchored vs. unanchored regular expressions}.
-
diff --git a/docs/reference/functions/concat_example.texinfo b/docs/reference/functions/concat_example.texinfo
deleted file mode 100644
index 3e896600ee..0000000000
--- a/docs/reference/functions/concat_example.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-@verbatim
-
-commands:
- "/usr/bin/generate_config $(config)"
- ifvarclass => concat("have_config_", canonify("$(config)"));
-
-@end verbatim
diff --git a/docs/reference/functions/concat_notes.texinfo b/docs/reference/functions/concat_notes.texinfo
deleted file mode 100644
index 0ea8f981f5..0000000000
--- a/docs/reference/functions/concat_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-@i{History}: Was introduced in 3.2.0, Nova 2.1.0 (2011)
diff --git a/docs/reference/functions/countclassesmatching_example.texinfo b/docs/reference/functions/countclassesmatching_example.texinfo
deleted file mode 100644
index c74cb59b80..0000000000
--- a/docs/reference/functions/countclassesmatching_example.texinfo
+++ /dev/null
@@ -1,18 +0,0 @@
-
-@verbatim
-
-bundle agent example
-{
-vars:
-
- "num" int => countclassesmatching("entropy.*low");
-
-reports:
-
- cfengine_3::
-
- "Found $(num) classes matching";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/countclassesmatching_notes.texinfo b/docs/reference/functions/countclassesmatching_notes.texinfo
deleted file mode 100644
index c2ec838ba3..0000000000
--- a/docs/reference/functions/countclassesmatching_notes.texinfo
+++ /dev/null
@@ -1,13 +0,0 @@
-
-This function matches classes, using a regular expression
-that should match the whole line.
-
-@table @samp
-@item regex
-A regular expression matching zero or more classes in the current list
-of defined classes. The regular
-expression must match a complete class, that is, it is anchored,
-@xref{Anchored vs. unanchored regular expressions}.
-@end table
-
-The function returns the number of classes matched.
diff --git a/docs/reference/functions/countlinesmatching_example.texinfo b/docs/reference/functions/countlinesmatching_example.texinfo
deleted file mode 100644
index c61e53ab83..0000000000
--- a/docs/reference/functions/countlinesmatching_example.texinfo
+++ /dev/null
@@ -1,18 +0,0 @@
-
-@verbatim
-
-bundle agent example
-{
-vars:
-
- "no" int => countlinesmatching("m.*","/etc/passwd");
-
-reports:
-
- cfengine_3::
-
- "Found $(no) lines matching";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/countlinesmatching_notes.texinfo b/docs/reference/functions/countlinesmatching_notes.texinfo
deleted file mode 100644
index ffdfa2c496..0000000000
--- a/docs/reference/functions/countlinesmatching_notes.texinfo
+++ /dev/null
@@ -1,16 +0,0 @@
-
-
-This function matches lines in the named file, using a regular expression
-that should match the whole line.
-
-@table @samp
-@item regex
-A regular expression matching zero or more lines. The regular
-expression must match a complete line (that is, it is anchored,
-@pxref{Anchored vs. unanchored regular expressions}).
-
-@item filename
-The name of the file to be examined.
-@end table
-
-The function returns the number of lines matched.
diff --git a/docs/reference/functions/difference_example.texinfo b/docs/reference/functions/difference_example.texinfo
deleted file mode 100644
index ebbe6fdab0..0000000000
--- a/docs/reference/functions/difference_example.texinfo
+++ /dev/null
@@ -1,22 +0,0 @@
-
-@verbatim
-
-bundle agent test
-
-{
- vars:
- "a" slist => { 1,2,3,"x" };
- "b" slist => { "x" };
-
- "listname1" slist => { "a", "b" };
- "listname2" slist => { "a", "b" };
- "$(listname1)_str" string => join(",", $(listname1));
-
- "diff_$(listname1)_$(listname2)" slist => difference($(listname1), $(listname2));
- "diff_$(listname1)_$(listname2)_str" string => join(",", "diff_$(listname1)_$(listname2)");
-
- reports:
- "The difference of list '$($(listname1)_str)' with '$($(listname2)_str)' is '$(diff_$(listname1)_$(listname2)_str)'";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/difference_notes.texinfo b/docs/reference/functions/difference_notes.texinfo
deleted file mode 100644
index a7d7b9f673..0000000000
--- a/docs/reference/functions/difference_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Returns the unique elements in the list variable specified in arg1 that
-are @emph{not} in the list variable specified in arg2.
diff --git a/docs/reference/functions/dirname_example.texinfo b/docs/reference/functions/dirname_example.texinfo
deleted file mode 100644
index 4014b9cf0a..0000000000
--- a/docs/reference/functions/dirname_example.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-@verbatim
-vars:
- "apache_dir" string => dirname("/etc/apache2/httpd.conf");
-@end verbatim
diff --git a/docs/reference/functions/dirname_notes.texinfo b/docs/reference/functions/dirname_notes.texinfo
deleted file mode 100644
index 9aae808dee..0000000000
--- a/docs/reference/functions/dirname_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-@i{History}: Was introduced in 3.3.0, Nova 2.2.0 (2011)
-
-This function returns directory name for the argument. If directory
-name is provided, name of parent directory is returned.
diff --git a/docs/reference/functions/diskfree_example.texinfo b/docs/reference/functions/diskfree_example.texinfo
deleted file mode 100644
index fb147e3dd6..0000000000
--- a/docs/reference/functions/diskfree_example.texinfo
+++ /dev/null
@@ -1,18 +0,0 @@
-
-@verbatim
-
-bundle agent example
-{
-vars:
-
- "free" int => diskfree("/tmp");
-
-reports:
-
- cfengine_3::
-
- "Freedisk $(free)";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/diskfree_notes.texinfo b/docs/reference/functions/diskfree_notes.texinfo
deleted file mode 100644
index e7232d45fa..0000000000
--- a/docs/reference/functions/diskfree_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-
-Values returned in kilobytes.
diff --git a/docs/reference/functions/escape_example.texinfo b/docs/reference/functions/escape_example.texinfo
deleted file mode 100644
index 87b1fc00f3..0000000000
--- a/docs/reference/functions/escape_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-bundle server control
-{
-allowconnects => { "127\.0\.0\.1", escape("192.168.2.1") };
-}
-
-@end verbatim
diff --git a/docs/reference/functions/escape_notes.texinfo b/docs/reference/functions/escape_notes.texinfo
deleted file mode 100644
index 2c41fcf598..0000000000
--- a/docs/reference/functions/escape_notes.texinfo
+++ /dev/null
@@ -1,13 +0,0 @@
-
-This function is useful for making inputs readable when a regular expression
-is required, but the literal string contains special characters. The
-function simply 'escapes' all the regular expression characters, so that you
-don't have to.
-
-This in the example above, the string "192.168.2.1" is "escaped" to be
-equivalent to "192\.168\.2\.1" (because without the backslashes, the regular
-expression "192.168.2.1" will also match the IP ranges "192.168.201",
-"192.168.231", etc - since the dot character means "match any character" when
-used in a regular expression).
-
-@b{History}: This function was introduced in CFEngine version 3.0.4 (2010)
diff --git a/docs/reference/functions/every_example.texinfo b/docs/reference/functions/every_example.texinfo
deleted file mode 100644
index 1e31e25d64..0000000000
--- a/docs/reference/functions/every_example.texinfo
+++ /dev/null
@@ -1,32 +0,0 @@
-
-@verbatim
-
-bundle agent test
-
-{
- classes:
- "every1" expression => every(".*", "test");
- "every2" expression => every(".", "test");
-
- vars:
- "test" slist => {
- 1,2,3,
- "one", "two", "three",
- "long string",
- "four", "fix", "six",
- "one", "two", "three",
- };
-
- reports:
- "The test list is $(test)";
- every1::
- "every() test 1 passed";
- !every1::
- "every() test 1 failed";
- every2::
- "every() test 2 failed";
- !every2::
- "every() test 2 passed";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/every_notes.texinfo b/docs/reference/functions/every_notes.texinfo
deleted file mode 100644
index dc2dea340a..0000000000
--- a/docs/reference/functions/every_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-arg1 is a regular expression tested against every element of the list
-arg2. If all match, this function returns true.
diff --git a/docs/reference/functions/execresult_example.texinfo b/docs/reference/functions/execresult_example.texinfo
deleted file mode 100644
index 69c82da402..0000000000
--- a/docs/reference/functions/execresult_example.texinfo
+++ /dev/null
@@ -1,27 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-vars:
-
- "my_result" string => execresult("/bin/ls /tmp","noshell");
-
-reports:
-
- linux::
-
- "Variable is $(my_result)";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/execresult_notes.texinfo b/docs/reference/functions/execresult_notes.texinfo
deleted file mode 100644
index 0309fa74d3..0000000000
--- a/docs/reference/functions/execresult_notes.texinfo
+++ /dev/null
@@ -1,20 +0,0 @@
-
-The second argument (@samp{useshell}/@samp{noshell}) decides whether a
-shell will be used to encapsulate the command. This is necessary in
-order to combine commands with pipes etc, but remember that each
-command requires a new process that reads in files beyond CFEngine's
-control. Thus using a shell is both a performance hog and a potential
-security issue.
-
-Note: you should never use this function to execute comands that make
-changes to the system, or perform lengthy computations. Such an
-operation is beyond CFEngine's ability to guarantee convergence, and
-on multiple passes and during syntax verification, these function
-calls are executed resulting in system changes that are
-`covert'. Calls to @code{execresult} should be for discovery and
-information extraction only.
-
-Note: if the command is not found, the result will be the empty string!
-
-@noindent @b{Change:} policy change in CFEngine 3.0.5. Previously newlines
-were changed for spaces, now newlines are preserved.
diff --git a/docs/reference/functions/fileexists_example.texinfo b/docs/reference/functions/fileexists_example.texinfo
deleted file mode 100644
index c6c2aa28f4..0000000000
--- a/docs/reference/functions/fileexists_example.texinfo
+++ /dev/null
@@ -1,27 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-classes:
-
- "exists" expression => fileexists("/etc/passwd");
-
-reports:
-
- exists::
-
- "File exists";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/fileexists_notes.texinfo b/docs/reference/functions/fileexists_notes.texinfo
deleted file mode 100644
index b62190260d..0000000000
--- a/docs/reference/functions/fileexists_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-The user must have access permissions to the file for this to work
-faithfully.
diff --git a/docs/reference/functions/filesexist_example.texinfo b/docs/reference/functions/filesexist_example.texinfo
deleted file mode 100644
index aaa490d789..0000000000
--- a/docs/reference/functions/filesexist_example.texinfo
+++ /dev/null
@@ -1,37 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-vars:
-
- "mylist" slist => { "/tmp/a", "/tmp/b", "/tmp/c" };
-
-classes:
-
- "exists" expression => filesexist("@(mylist)");
-
-reports:
-
- exists::
-
- "Files exist";
-
- !exists::
-
- "Do not exist";
-
-}
-
-
-
-@end verbatim
diff --git a/docs/reference/functions/filesexist_notes.texinfo b/docs/reference/functions/filesexist_notes.texinfo
deleted file mode 100644
index b62190260d..0000000000
--- a/docs/reference/functions/filesexist_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-The user must have access permissions to the file for this to work
-faithfully.
diff --git a/docs/reference/functions/filesize_example.texinfo b/docs/reference/functions/filesize_example.texinfo
deleted file mode 100644
index d42f0e20f7..0000000000
--- a/docs/reference/functions/filesize_example.texinfo
+++ /dev/null
@@ -1,21 +0,0 @@
-
-
-@verbatim
-
-bundle agent example
-{
-vars:
-
- "exists" int => filesize("/etc/passwd");
- "nexists" int => filesize("/etc/passwdx");
-
-reports:
-
- !xyz::
-
- "File size $(exists)";
- "Does not exist $(nexists)";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/filesize_notes.texinfo b/docs/reference/functions/filesize_notes.texinfo
deleted file mode 100644
index 4eb9d05dd2..0000000000
--- a/docs/reference/functions/filesize_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-@i{History}: Was introduced in version 3.1.3,Nova 2.0.2 (2010)
-
-If the file object does not exist, the function call fails and the variable
-does not expand.
diff --git a/docs/reference/functions/filestat_example.texinfo b/docs/reference/functions/filestat_example.texinfo
deleted file mode 100644
index 97eca2e4ac..0000000000
--- a/docs/reference/functions/filestat_example.texinfo
+++ /dev/null
@@ -1,16 +0,0 @@
-
-
-@verbatim
-
-bundle agent fileinfo(f)
-{
- vars:
- "fields" slist => splitstring("size,gid,uid,ino,nlink,ctime,atime,mtime,mode,modeoct,permstr,permoct,type,devno,dev_minor,dev_major,basename,dirname", ",", 999);
-
- "stat[$(f)][$(fields)]" string => filestat($(f), $(fields));
-
- reports:
- "$(this.bundle): file $(f) has $(fields) = $(stat[$(f)][$(fields)])";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/filestat_notes.texinfo b/docs/reference/functions/filestat_notes.texinfo
deleted file mode 100644
index 8fb66cacba..0000000000
--- a/docs/reference/functions/filestat_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-@i{History}: Was introduced in version 3.5.0,Enterprise 3.1 (2013)
-
-If the file object does not exist, the function call fails and the variable
-does not expand.
diff --git a/docs/reference/functions/filter_example.texinfo b/docs/reference/functions/filter_example.texinfo
deleted file mode 100644
index ef7398d46a..0000000000
--- a/docs/reference/functions/filter_example.texinfo
+++ /dev/null
@@ -1,34 +0,0 @@
-
-@verbatim
-
-bundle agent test
-
-{
- vars:
- "test" slist => {
- 1,2,3,
- "one", "two", "three",
- "long string",
- "one", "two", "three",
- };
-
- "test_grep" slist => filter("[0-9]", "test", "true", "false", 999);
- "test_exact1" slist => filter("one", "test", "false", "false", 999);
- "test_exact2" slist => filter(".", "test", "false", "false", 999);
- "test_invert" slist => filter("[0-9]", "test", "true", "true", 999);
- "test_max2" slist => filter(".*", "test", "true", "false", 2);
- "test_max0" slist => filter(".*", "test", "true", "false", 0);
- "grep" slist => grep("[0-9]", "test");
-
- reports:
- "The test list is $(test)";
- "The grepped list is $(grep)";
- "The filter-grepped list is $(test_grep)";
- "The filter-exact list, looking for 'one' is $(test_exact1)";
- "This line should not appear: $(test_exact2)";
- "The filter-invert list, looking for non-digits, is $(test_invert)";
- "The filter-bound list, matching at most 2 items, is $(test_max2)";
- "This line should not appear: $(test_max0)";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/filter_notes.texinfo b/docs/reference/functions/filter_notes.texinfo
deleted file mode 100644
index 2a44180582..0000000000
--- a/docs/reference/functions/filter_notes.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-Extracts a sublist of elements matching arg1 as a regular expression (if
-arg3 is true) or as an exact string (if arg3 is false) from a list
-variable specified in arg2. In regular expression mode, the regex is
-anchored. @xref{Anchored vs. unanchored regular expressions}.
-
-If arg4 is true, the matches are inverted (you get elements that don't match arg1).
-
-arg5 specifies a maximum number of elements to return.
-
diff --git a/docs/reference/functions/format_example.texinfo b/docs/reference/functions/format_example.texinfo
deleted file mode 100644
index 1b70f6075c..0000000000
--- a/docs/reference/functions/format_example.texinfo
+++ /dev/null
@@ -1,48 +0,0 @@
-@verbatim
-
-body common control
-{
- bundlesequence => { run };
-}
-
-bundle agent run
-{
- vars:
- "formats[0]" string => "%10s %d";
- "formats[1]" string => "the %% the";
- "formats[2]" string => "%3.2f floater";
- "formats[3]" string => "%05d integer";
- "formats[4]" string => "%s end with %";
- "formats[5]" string => "%ss is a format followed by a s";
- "formats[6]" string => "%sf invalid";
- "formats[7]" string => "%dc invalid";
- "formats[8]" string => "no format specifiers here";
- "formats[9]" string => "%o";
- "formats[10]" string => "%x";
- "formats[11]" string => "%c";
- "formats[12]" string => "%qd";
-
- "indices" slist => getindices("formats");
-
- "values[0]" string => "x";
- "values[1]" string => "% inserted verbatim";
- "values[2]" string => "10";
- "values[3]" string => "-1";
- "values[4]" string => "hello";
- "values[5]" string => "bad1";
- "values[6]" string => "bad2";
- "values[7]" string => "bad3";
-
- "vindices" slist => getindices("values");
-
- # apply every format to every value above
- "print[$(indices)_$(vindices)]" string => format("$(formats[$(indices)])", "$(values[$(vindices)])", "second parameter");
-
- "bad" string => format("%s %s", "one parameter");
-
- reports:
- "format('$(formats[$(indices)])', '$(values[$(vindices)])') => $(print[$(indices)_$(vindices)])";
- "this should be an unexpanded variable: $(bad)";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/format_notes.texinfo b/docs/reference/functions/format_notes.texinfo
deleted file mode 100644
index a60607c26a..0000000000
--- a/docs/reference/functions/format_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-Applies sprintf() formatting to a given string with the rest of the
-parameters applied in place.
-
-Will fail if it doesn't have enough arguments; if any format specifier
-contains the modifiers @code{hLqjzt}; or if any format specifier is not
-one of @code{doxfs}.
diff --git a/docs/reference/functions/getenv_example.texinfo b/docs/reference/functions/getenv_example.texinfo
deleted file mode 100644
index 59914acc7b..0000000000
--- a/docs/reference/functions/getenv_example.texinfo
+++ /dev/null
@@ -1,26 +0,0 @@
-
-@verbatim
-
-bundle agent example
-{
-vars:
-
- "myvar" string => getenv("PATH","20");
-
-classes:
-
- "isdefined" not => strcmp("$(myvar)","");
-
-reports:
-
- isdefined::
-
- "The path is $(myvar)";
-
- !isdefined::
-
- "The named variable PATH does not exist";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/getenv_notes.texinfo b/docs/reference/functions/getenv_notes.texinfo
deleted file mode 100644
index 4929df1cf4..0000000000
--- a/docs/reference/functions/getenv_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-Returns an empty string if the environment variable is not defined.
-Arg2 is used to avoid unexpectedly large return values,
-which could lead to security issues. Choose a reasonable
-value based on the environment variable you are querying.
-
-@b{History}: This function was introduced in CFEngine version 3.0.4 (2010)
diff --git a/docs/reference/functions/getfields_example.texinfo b/docs/reference/functions/getfields_example.texinfo
deleted file mode 100644
index 304c9547db..0000000000
--- a/docs/reference/functions/getfields_example.texinfo
+++ /dev/null
@@ -1,20 +0,0 @@
-
-@verbatim
-
-bundle agent example
-
-{
-vars:
-
- "no" int => getfields("mark:.*","/etc/passwd",":","userdata");
-
-reports:
-
- cfengine_3::
-
- "Found $(no) lines matching";
- "Mark's homedir = $(userdata[6])";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/getfields_notes.texinfo b/docs/reference/functions/getfields_notes.texinfo
deleted file mode 100644
index 664ec625a0..0000000000
--- a/docs/reference/functions/getfields_notes.texinfo
+++ /dev/null
@@ -1,30 +0,0 @@
-
-
-This function matches lines (using a regular expression) in the named file, and
-splits the @b{@i{first}} matched line into fields (using a second) regular expression),
-placing these into a named array whose elements are @code{array[1],array[2],..}.
-This is useful for examining user data in the Unix password or group files.
-
-@table @samp
-@item regex
-A regular expression matching one or more lines. The regular
-expression must match the entire line (that is, it is anchored,
-@pxref{Anchored vs. unanchored regular expressions}).
-
-@item filename
-The name of the file to be examined.
-
-@item split
-A regex pattern which is used to parse the field separator(s)
-to split up the file into items
-
-@item array_lval
-The base name of the array that returns the values.
-
-@end table
-
-The function returns the number of lines matched. This function
-is most useful when you want only the first matching line (e.g.,
-to mimic the behavior of the @i{getpwnam(3)} on the file
-@file{/etc/passwd}). If you want to examine @i{all} matching lines,
-@xref{Function readstringarray}, instead.
diff --git a/docs/reference/functions/getgid_example.texinfo b/docs/reference/functions/getgid_example.texinfo
deleted file mode 100644
index 781c92a14e..0000000000
--- a/docs/reference/functions/getgid_example.texinfo
+++ /dev/null
@@ -1,27 +0,0 @@
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-vars:
-
- "gid" int => getgid("users");
-
-reports:
-
- Yr2008::
-
- "Users gid is $(gid)";
-
-}
-
-@end verbatim
-
diff --git a/docs/reference/functions/getgid_notes.texinfo b/docs/reference/functions/getgid_notes.texinfo
deleted file mode 100644
index a75c3bb9b4..0000000000
--- a/docs/reference/functions/getgid_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-If the named group does not exist, the variable will not be
-defined. On windows, which does not support group ids, the variable
-will not be defined.
diff --git a/docs/reference/functions/getindices_example.texinfo b/docs/reference/functions/getindices_example.texinfo
deleted file mode 100644
index 55098185ac..0000000000
--- a/docs/reference/functions/getindices_example.texinfo
+++ /dev/null
@@ -1,33 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-any::
-
- bundlesequence => { "testsetvar" };
-}
-
-
-#######################################################
-
-bundle agent testsetvar
-
-{
-vars:
-
- "v[index_1]" string => "value_1";
- "v[index_2]" string => "value_2";
-
- "parameter_name" slist => getindices("v");
-
-reports:
-
- Yr2008::
-
- "Found index: $(parameter_name)";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/getindices_notes.texinfo b/docs/reference/functions/getindices_notes.texinfo
deleted file mode 100644
index cbff7ca510..0000000000
--- a/docs/reference/functions/getindices_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-Make sure you specify the correct scope when supplying the name of the variable.
diff --git a/docs/reference/functions/getuid_example.texinfo b/docs/reference/functions/getuid_example.texinfo
deleted file mode 100644
index c47b0fa89d..0000000000
--- a/docs/reference/functions/getuid_example.texinfo
+++ /dev/null
@@ -1,27 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-vars:
-
- "uid" int => getuid("mark");
-
-reports:
-
- Yr2008::
-
- "Users uid is $(uid)";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/getuid_notes.texinfo b/docs/reference/functions/getuid_notes.texinfo
deleted file mode 100644
index c4b8ec12c6..0000000000
--- a/docs/reference/functions/getuid_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-If the named user is not registered the variable will not be
-defined. On windows, which does not support user ids, the variable
-will not be defined.
diff --git a/docs/reference/functions/getusers_example.texinfo b/docs/reference/functions/getusers_example.texinfo
deleted file mode 100644
index 5812a14b6b..0000000000
--- a/docs/reference/functions/getusers_example.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-vars:
- "allusers" slist => getusers("zenoss,mysql,at","12,0");
-
-reports:
-
- linux::
-
- "Found user $(allusers)";
-@end verbatim
diff --git a/docs/reference/functions/getusers_notes.texinfo b/docs/reference/functions/getusers_notes.texinfo
deleted file mode 100644
index 11c9b68750..0000000000
--- a/docs/reference/functions/getusers_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-@b{History}: Was introduced in version 3.1.0b1,Nova 2.0.0b1 (2010)
-This function is only available on Unix-like systems in the present version.
-
-The function has two arguments, both are comma separated lists. The first argument is a list
-of user names that should be excluded from the output. The second is a list of integrer UIDs
-that should be excluded.
diff --git a/docs/reference/functions/getvalues_example.texinfo b/docs/reference/functions/getvalues_example.texinfo
deleted file mode 100644
index 563349b9f6..0000000000
--- a/docs/reference/functions/getvalues_example.texinfo
+++ /dev/null
@@ -1,33 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-any::
-
- bundlesequence => { "testsetvar" };
-}
-
-
-#######################################################
-
-bundle agent testsetvar
-
-{
-vars:
-
- "v[index_1]" string => "value_1";
- "v[index_2]" string => "value_2";
-
- "parameter_name" slist => getvalues("v");
-
-reports:
-
- Yr2008::
-
- "Found index: $(parameter_name)";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/getvalues_notes.texinfo b/docs/reference/functions/getvalues_notes.texinfo
deleted file mode 100644
index 14cecdb6f0..0000000000
--- a/docs/reference/functions/getvalues_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Make sure you specify the correct scope when supplying the name of the
-variable. If the array contains list elements on the right hand side
-then all of the list elements are flattened into a single list to make the return value a list.
diff --git a/docs/reference/functions/grep_example.texinfo b/docs/reference/functions/grep_example.texinfo
deleted file mode 100644
index cd539dd824..0000000000
--- a/docs/reference/functions/grep_example.texinfo
+++ /dev/null
@@ -1,23 +0,0 @@
-
-@verbatim
-
-bundle agent test
-
-{
-vars:
-
- "mylist" slist => { "One", "Two", "Three", "Four", "Five" };
-
- "sublist" slist => grep("T.*","mylist");
-
- "empty_list" slist => grep("ive","mylist");
-
-reports:
-
- linux::
-
- "Item: $(sublist)";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/grep_notes.texinfo b/docs/reference/functions/grep_notes.texinfo
deleted file mode 100644
index eb634abe0e..0000000000
--- a/docs/reference/functions/grep_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Extracts a sublist of elements matching the regular expression in arg1 from a
-list variable specified in arg2. The regex is anchored.
-@xref{Anchored vs. unanchored regular expressions}.
diff --git a/docs/reference/functions/groupexists_example.texinfo b/docs/reference/functions/groupexists_example.texinfo
deleted file mode 100644
index fa9ecc4fc7..0000000000
--- a/docs/reference/functions/groupexists_example.texinfo
+++ /dev/null
@@ -1,33 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-classes:
-
- "gname" expression => groupexists("users");
- "gid" expression => groupexists("100");
-
-reports:
-
- gname::
-
- "Group exists by name";
-
- gid::
-
- "Group exists by id";
-
-}
-
-@end verbatim
-
diff --git a/docs/reference/functions/groupexists_notes.texinfo b/docs/reference/functions/groupexists_notes.texinfo
deleted file mode 100644
index 51d135dc6d..0000000000
--- a/docs/reference/functions/groupexists_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-The group may be specified by name or number.
diff --git a/docs/reference/functions/hash_example.texinfo b/docs/reference/functions/hash_example.texinfo
deleted file mode 100644
index 7090209af3..0000000000
--- a/docs/reference/functions/hash_example.texinfo
+++ /dev/null
@@ -1,28 +0,0 @@
-
-@verbatim
-
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-vars:
-
- "md5" string => hash("CFEngine is not cryptic","md5");
-
-reports:
-
- Yr2008::
-
- "Hashed to: $(md5)";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/hash_notes.texinfo b/docs/reference/functions/hash_notes.texinfo
deleted file mode 100644
index 6d38bd67de..0000000000
--- a/docs/reference/functions/hash_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-Hash functions are extremely sensitive to input. You should not expect
-to get the same answer from this function as you would from every other
-tool, since it depends on how whitespace and end of file characters are
-handled.
-
-Valid hash types (depending on availablity) include:
-@code{md5}, @code{sha1}, @code{sha256}, @code{sha512} ,@code{sha384},
-@code{crypt}.
diff --git a/docs/reference/functions/hashmatch_example.texinfo b/docs/reference/functions/hashmatch_example.texinfo
deleted file mode 100644
index 3424372a5c..0000000000
--- a/docs/reference/functions/hashmatch_example.texinfo
+++ /dev/null
@@ -1,19 +0,0 @@
-
-@verbatim
-
-bundle agent example
-
-{
-classes:
-
- "matches" expression => hashmatch("/etc/passwd","md5","c5068b7c2b1707f8939b283a2758a691");
-
-reports:
-
- matches::
-
- "File has correct version";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/hashmatch_notes.texinfo b/docs/reference/functions/hashmatch_notes.texinfo
deleted file mode 100644
index e812e97021..0000000000
--- a/docs/reference/functions/hashmatch_notes.texinfo
+++ /dev/null
@@ -1,20 +0,0 @@
-
-
-@cartouche
-@example
-
-(class) hashmatch(@var{file},@var{md5|sha1|crypt},@var{hash-comparison});
-
-@end example
-@end cartouche
-
-This function may be used to determine whether a system has a particular
-version of a binary file (e.g. software patch).
-
-@noindent @b{ARGUMENTS}:
-
-@itemize
-@item The file concerned
-@item The type of hash
-@item A string of the hash to which we expect the file to conform.
-@end itemize
diff --git a/docs/reference/functions/host2ip_example.texinfo b/docs/reference/functions/host2ip_example.texinfo
deleted file mode 100644
index e53d7e566c..0000000000
--- a/docs/reference/functions/host2ip_example.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@verbatim
-
-bundle server control
-{
-allowconnects => { escape(host2ip("www.example.com")) };
-}
-
-@end verbatim
diff --git a/docs/reference/functions/host2ip_notes.texinfo b/docs/reference/functions/host2ip_notes.texinfo
deleted file mode 100644
index 74d9accf97..0000000000
--- a/docs/reference/functions/host2ip_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-Uses whatever configured name service is used by the resolver library
-to translate a hostname into an IP address. It will return an IPv6
-address by preference if such an address exists. This function uses
-the standard lookup procedure for a name, so it mimics internal
-processes and can therefore be used not only to cache multiple lookups
-in the configuration, but to debug the behaviour of the resolver.
-
-@b{History}: This function was introduced in CFEngine version 3.0.4 (2010)
diff --git a/docs/reference/functions/hostinnetgroup_example.texinfo b/docs/reference/functions/hostinnetgroup_example.texinfo
deleted file mode 100644
index e893bddebc..0000000000
--- a/docs/reference/functions/hostinnetgroup_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-@verbatim
-
-classes:
-
- "ingroup" expression => hostinnetgroup("my_net_group");
-
-@end verbatim
diff --git a/docs/reference/functions/hostinnetgroup_notes.texinfo b/docs/reference/functions/hostinnetgroup_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/functions/hostinnetgroup_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/functions/hostrange_example.texinfo b/docs/reference/functions/hostrange_example.texinfo
deleted file mode 100644
index 3d3922c961..0000000000
--- a/docs/reference/functions/hostrange_example.texinfo
+++ /dev/null
@@ -1,29 +0,0 @@
-
-
-@verbatim
-
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-classes:
-
- "compute_nodes" expression => hostrange("cpu-","01-32");
-
-reports:
-
- compute_nodes::
-
- "No computer is a cluster";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/hostrange_notes.texinfo b/docs/reference/functions/hostrange_notes.texinfo
deleted file mode 100644
index 17779598a6..0000000000
--- a/docs/reference/functions/hostrange_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-This is a pattern matching function for non-regular (enumerated) expressions.
diff --git a/docs/reference/functions/hostsseen_example.texinfo b/docs/reference/functions/hostsseen_example.texinfo
deleted file mode 100644
index 412cf3cd8e..0000000000
--- a/docs/reference/functions/hostsseen_example.texinfo
+++ /dev/null
@@ -1,18 +0,0 @@
-
-@verbatim
-bundle agent test
-
-{
-vars:
-
- "myhosts" slist => { hostsseen("inf","lastseen","address") };
-
-reports:
-
- cfengine_3::
-
- "Found client/peer: $(myhosts)";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/hostsseen_notes.texinfo b/docs/reference/functions/hostsseen_notes.texinfo
deleted file mode 100644
index 3153fc4244..0000000000
--- a/docs/reference/functions/hostsseen_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-Finds a list of hosts seen by a CFEngine remote connection on the
-current host within the number of hours specified by argument
-1. Argument 2 may be @samp{lastseen} or @samp{notseen}, the latter
-being all hosts not observed to have connected within the specified
-time. Argument 3 may be @samp{address} or @samp{name}, to return ip
-address or hostname form.
diff --git a/docs/reference/functions/hostswithclass_example.texinfo b/docs/reference/functions/hostswithclass_example.texinfo
deleted file mode 100644
index a5d8423d04..0000000000
--- a/docs/reference/functions/hostswithclass_example.texinfo
+++ /dev/null
@@ -1,22 +0,0 @@
-@verbatim
-body common control
-{
-bundlesequence => { "test" };
-inputs => { "cfengine_stdlib.cf" };
-}
-
-
-bundle agent test
-{
-vars:
-
-am_policy_hub::
- "host_list" slist => hostswithclass( "debian", "name" );
-
-files:
-am_policy_hub::
- "/tmp/master_config.cfg"
- edit_line => insert_lines("host=$(host_list)"),
- create => "true";
-}
-@end verbatim
diff --git a/docs/reference/functions/hostswithclass_notes.texinfo b/docs/reference/functions/hostswithclass_notes.texinfo
deleted file mode 100644
index 833fe10122..0000000000
--- a/docs/reference/functions/hostswithclass_notes.texinfo
+++ /dev/null
@@ -1,16 +0,0 @@
-
-On CFEngine Nova hubs, this function can be used to return a list of
-hostnames or ip-addresses of hosts that has the class given as
-argument 1. Argument 2 may be @samp{address} or @samp{name}, to
-return ip address or hostname form.
-
-Note that this function only works locally on the hub, but allows the
-hub to construct custom configuration files for (classes of) hosts.
-
-@i{History}: Was introduced in 3.3.0, Nova 2.2.0 (2012)
-
-Availability: Enterprise editions of CFEngine only.
-
-@verbatim
-
-@end verbatim
diff --git a/docs/reference/functions/hubknowledge_example.texinfo b/docs/reference/functions/hubknowledge_example.texinfo
deleted file mode 100644
index 332ada4ea4..0000000000
--- a/docs/reference/functions/hubknowledge_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-vars:
-
- guard::
-
- "global_number" string => hubknowledge("number_variable");
-
-@end verbatim
diff --git a/docs/reference/functions/hubknowledge_notes.texinfo b/docs/reference/functions/hubknowledge_notes.texinfo
deleted file mode 100644
index 64ab7aa85d..0000000000
--- a/docs/reference/functions/hubknowledge_notes.texinfo
+++ /dev/null
@@ -1,22 +0,0 @@
-
-This function is only available in commercial releases of CFEngine.
-It is intended for use in distributed orchestration. It is recommended
-that you use this function sparingly with @i{guards}, as it
-contributes to network traffic and depends on the network for its function.
-Unlike @code{remotescalar()}, the value of hub-knowledge is not cached.
-
-This function behaves is essentially similar to the
-@code{remotescalar} function, except that it always gets its
-information from the policy server hub by an encrypted connection. It
-is designed for spreading globally calibrated information about a
-CFEngine swarm back to the client machines. The data available through
-this channel are generated automatically by discovery, unlike
-@code{remotescalar} which accesses user defined data.
-
-This function asks for an identifier; it is up to the server to interpret
-what this means and to return a value of its choosing. If the identifier matches
-a persistent scalar variable (such as is used to count distributed processes in CFEngine
-Enterprise) then this will be returned preferentially. If no such variable is found,
-then the server will look for a literal string in a server bundle with a handle that
-matches the requested object.
-
diff --git a/docs/reference/functions/ifelse_example.texinfo b/docs/reference/functions/ifelse_example.texinfo
deleted file mode 100644
index 129ae353f0..0000000000
--- a/docs/reference/functions/ifelse_example.texinfo
+++ /dev/null
@@ -1,40 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
- classes:
- "myclass" expression => "any";
- "myclass2" expression => "any";
- "secondpass" expression => "any";
- vars:
- # result: { "1", "single string parameter", "hardclass OK", "bundle class OK", "5 parameters OK" }
-
- # we need to use the secondpass class because on the first pass,
- # myclass and myclass2 are not defined yet
-
- secondpass::
- "mylist" slist => {
- ifelse(1),
- ifelse("single string parameter"),
- ifelse("cfengine", "hardclass OK", "hardclass broken"),
- ifelse("myclass.myclass2", "bundle class OK", "bundle class broken"),
- ifelse("this is not true", "5 parameters broken",
- "this is also not true", "5 parameters broken 2",
- "5 parameters OK"),
- };
-
- reports:
- "ifelse result list: $(mylist)";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/ifelse_notes.texinfo b/docs/reference/functions/ifelse_notes.texinfo
deleted file mode 100644
index 5df34e7b1a..0000000000
--- a/docs/reference/functions/ifelse_notes.texinfo
+++ /dev/null
@@ -1,18 +0,0 @@
-
-The @code{ifelse} function is like a multi-level if-else statement. It
-must have an odd number of arguments (from 1 to N). The last argument
-is the default value, like the @code{else} clause in standard
-programming languages. Every pair of arguments before the last one are
-evaluated as a pair. If the first one evaluates true (as if you had
-used it in a class @code{expression}, so it can be more than just a
-class name) then the second one is returned.
-
-As an example, if @code{ifelse} were called with arguments (@var{a1},
-@var{a2}, @var{b1}, @var{b2}, and @var{c}), the behavior expressed as
-pseudo-code is:
-
-@verbatim
-if a1 then return a2
-else-if b1 then return b2
-else return c
-@end verbatim
diff --git a/docs/reference/functions/innetgroup_example.texinfo b/docs/reference/functions/innetgroup_example.texinfo
deleted file mode 100644
index ef159082cd..0000000000
--- a/docs/reference/functions/innetgroup_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-@verbatim
-
-classes:
-
- "class" or => { innetgroup("local_hosts"), innetgroup("global_host") };
-
-@end verbatim
diff --git a/docs/reference/functions/innetgroup_notes.texinfo b/docs/reference/functions/innetgroup_notes.texinfo
deleted file mode 100644
index 9685903ea0..0000000000
--- a/docs/reference/functions/innetgroup_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-The function is true if the current host is a member of the named host-netgroup.
diff --git a/docs/reference/functions/intersection_example.texinfo b/docs/reference/functions/intersection_example.texinfo
deleted file mode 100644
index 47db92762a..0000000000
--- a/docs/reference/functions/intersection_example.texinfo
+++ /dev/null
@@ -1,22 +0,0 @@
-
-@verbatim
-
-bundle agent test
-
-{
- vars:
- "a" slist => { 1,2,3,"x" };
- "b" slist => { "x" };
-
- "listname1" slist => { "a", "b" };
- "listname2" slist => { "a", "b" };
- "$(listname1)_str" string => join(",", $(listname1));
-
- "int_$(listname1)_$(listname2)" slist => intersection($(listname1), $(listname2));
- "int_$(listname1)_$(listname2)_str" string => join(",", "int_$(listname1)_$(listname2)");
-
- reports:
- "The intersection of list '$($(listname1)_str)' with '$($(listname2)_str)' is '$(int_$(listname1)_$(listname2)_str)'";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/intersection_notes.texinfo b/docs/reference/functions/intersection_notes.texinfo
deleted file mode 100644
index 6b6fbbde6b..0000000000
--- a/docs/reference/functions/intersection_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Returns the unique elements in the list variable specified in arg1 that
-@emph{are also} in the list variable specified in arg2.
diff --git a/docs/reference/functions/ip2host_example.texinfo b/docs/reference/functions/ip2host_example.texinfo
deleted file mode 100644
index 54ed223ff9..0000000000
--- a/docs/reference/functions/ip2host_example.texinfo
+++ /dev/null
@@ -1,16 +0,0 @@
-
-@verbatim
-bundle agent reverse_lookup
-{
-vars:
- "local4" string => ip2host("127.0.0.1");
- "local6" string => ip2host("::1");
-
-
-reports:
-cfengine_3::
- "local4 is $(local4)";
- "local6 is $(local6)";
-}
-@end verbatim
-
diff --git a/docs/reference/functions/ip2host_notes.texinfo b/docs/reference/functions/ip2host_notes.texinfo
deleted file mode 100644
index ccfb38e928..0000000000
--- a/docs/reference/functions/ip2host_notes.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-Uses whatever configured name service is used by the resolver library
-to translate an IP address to a hostname. IPv6 addresses will also
-resolve, if supported by the resolver library.
-
-Note that DNS lookups may take time and thus cause CFEngine agents to
-wait for responses, slowing their progress significantly.
-
-@i{History}: Was introduced in version 3.1.3, Nova 2.0.2 (2010)
-
diff --git a/docs/reference/functions/iprange_example.texinfo b/docs/reference/functions/iprange_example.texinfo
deleted file mode 100644
index ded28bec87..0000000000
--- a/docs/reference/functions/iprange_example.texinfo
+++ /dev/null
@@ -1,32 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-classes:
-
- "adhoc_group_1" expression => iprange("128.39.89.10-15");
- "adhoc_group_2" expression => iprange("128.39.74.1/23");
-
-reports:
-
- adhoc_group_1::
-
- "Some numerology";
-
- adhoc_group_2::
-
- "The masked warriors";
-}
-
-@end verbatim
-
diff --git a/docs/reference/functions/iprange_notes.texinfo b/docs/reference/functions/iprange_notes.texinfo
deleted file mode 100644
index e80af35824..0000000000
--- a/docs/reference/functions/iprange_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Pattern matching based on IP addresses.
-
diff --git a/docs/reference/functions/irange_example.texinfo b/docs/reference/functions/irange_example.texinfo
deleted file mode 100644
index 11fb841e89..0000000000
--- a/docs/reference/functions/irange_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-@verbatim
-
-irange("1","100");
-
-irange(ago(0,0,0,1,30,0), "0");
-
-@end verbatim
diff --git a/docs/reference/functions/irange_notes.texinfo b/docs/reference/functions/irange_notes.texinfo
deleted file mode 100644
index fcad4f5a3e..0000000000
--- a/docs/reference/functions/irange_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-Used for any scalar attribute which requires an integer range. You can
-generally interchangeably say @samp{"1,10"} or @samp{irange("1","10")}
-(however, if you want to create a range of dates or times, you must use
-irange if you also use the functions @samp{ago}, @samp{now},
-@samp{accumulated}, etc).
-
diff --git a/docs/reference/functions/isdir_example.texinfo b/docs/reference/functions/isdir_example.texinfo
deleted file mode 100644
index 3addfe8379..0000000000
--- a/docs/reference/functions/isdir_example.texinfo
+++ /dev/null
@@ -1,28 +0,0 @@
-
-@verbatim
-
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-classes:
-
- "isdir" expression => isdir("/etc");
-
-reports:
-
- isdir::
-
- "Directory exists..";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/isdir_notes.texinfo b/docs/reference/functions/isdir_notes.texinfo
deleted file mode 100644
index 74413ed937..0000000000
--- a/docs/reference/functions/isdir_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-The CFEngine process must have access to the object concerned in order for
-this to work.
-
diff --git a/docs/reference/functions/isexecutable_example.texinfo b/docs/reference/functions/isexecutable_example.texinfo
deleted file mode 100644
index 18dae94912..0000000000
--- a/docs/reference/functions/isexecutable_example.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-@verbatim
-classes:
-
- "yes" expression => isexecutable("/bin/ls");
-
-@end verbatim
diff --git a/docs/reference/functions/isexecutable_notes.texinfo b/docs/reference/functions/isexecutable_notes.texinfo
deleted file mode 100644
index 1466394bb5..0000000000
--- a/docs/reference/functions/isexecutable_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-@i{History}: Was introduced in version 3.1.0b1,Nova 2.0.0b1 (2010)
-
diff --git a/docs/reference/functions/isgreaterthan_example.texinfo b/docs/reference/functions/isgreaterthan_example.texinfo
deleted file mode 100644
index 2c6f9d4b92..0000000000
--- a/docs/reference/functions/isgreaterthan_example.texinfo
+++ /dev/null
@@ -1,31 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "test" };
-}
-
-###########################################################
-
-bundle agent test
-
-{
-classes:
-
- "ok" expression => isgreaterthan("1","0");
-
-reports:
-
- ok::
-
- "Assertion is true";
-
- !ok::
-
- "Assertion is false";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/isgreaterthan_notes.texinfo b/docs/reference/functions/isgreaterthan_notes.texinfo
deleted file mode 100644
index f6a26909c5..0000000000
--- a/docs/reference/functions/isgreaterthan_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-The comparison is made numerically if possible. If the values are
-strings, the result is identical to that of comparing with @samp{strcmp()}.
diff --git a/docs/reference/functions/islessthan_example.texinfo b/docs/reference/functions/islessthan_example.texinfo
deleted file mode 100644
index 7f4a3a8e21..0000000000
--- a/docs/reference/functions/islessthan_example.texinfo
+++ /dev/null
@@ -1,31 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "test" };
-}
-
-###########################################################
-
-bundle agent test
-
-{
-classes:
-
- "ok" expression => islessthan("0","1");
-
-reports:
-
- ok::
-
- "Assertion is true";
-
- !ok::
-
- "Assertion is false";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/islessthan_notes.texinfo b/docs/reference/functions/islessthan_notes.texinfo
deleted file mode 100644
index fe19873471..0000000000
--- a/docs/reference/functions/islessthan_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-The complement of @code{isgreaterthan}.
-The comparison is made numerically if possible. If the values are
-strings, the result is identical to that of comparing with @samp{strcmp()}.
-
diff --git a/docs/reference/functions/islink_example.texinfo b/docs/reference/functions/islink_example.texinfo
deleted file mode 100644
index c18686e9a9..0000000000
--- a/docs/reference/functions/islink_example.texinfo
+++ /dev/null
@@ -1,29 +0,0 @@
-
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-classes:
-
- "isdir" expression => islink("/tmp/link");
-
-reports:
-
- isdir::
-
- "Directory exists..";
-
-}
-
-@end verbatim
-
diff --git a/docs/reference/functions/islink_notes.texinfo b/docs/reference/functions/islink_notes.texinfo
deleted file mode 100644
index 9e9f632859..0000000000
--- a/docs/reference/functions/islink_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-The link node must both exist and be a symbolic link. Hard links cannot be
-detected using this function. A hard link is a regular file or directory.
diff --git a/docs/reference/functions/isnewerthan_example.texinfo b/docs/reference/functions/isnewerthan_example.texinfo
deleted file mode 100644
index 73cd6d90f8..0000000000
--- a/docs/reference/functions/isnewerthan_example.texinfo
+++ /dev/null
@@ -1,27 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-classes:
-
- "do_it" and => { isnewerthan("/tmp/later","/tmp/earlier"), "linux" };
-
-reports:
-
- do_it::
-
- "The derived file needs updating";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/isnewerthan_notes.texinfo b/docs/reference/functions/isnewerthan_notes.texinfo
deleted file mode 100644
index 28da24728b..0000000000
--- a/docs/reference/functions/isnewerthan_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-This function compares the modification time of the file, referring to changes
-of content only.
diff --git a/docs/reference/functions/isplain_example.texinfo b/docs/reference/functions/isplain_example.texinfo
deleted file mode 100644
index 8e03567d89..0000000000
--- a/docs/reference/functions/isplain_example.texinfo
+++ /dev/null
@@ -1,27 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-classes:
-
- "isplain" expression => isplain("/etc/passwd");
-
-reports:
-
- isplain::
-
- "File exists..";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/isplain_notes.texinfo b/docs/reference/functions/isplain_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/functions/isplain_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/functions/isvariable_example.texinfo b/docs/reference/functions/isvariable_example.texinfo
deleted file mode 100644
index ccb8f13c24..0000000000
--- a/docs/reference/functions/isvariable_example.texinfo
+++ /dev/null
@@ -1,31 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-vars:
-
- "bla" string => "xyz..";
-
-classes:
-
- "exists" expression => isvariable("bla");
-
-reports:
-
- exists::
-
- "Variable exists: \"$(bla)\"..";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/isvariable_notes.texinfo b/docs/reference/functions/isvariable_notes.texinfo
deleted file mode 100644
index bd70606367..0000000000
--- a/docs/reference/functions/isvariable_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-The variable need only exist. This says nothing about its value. Use @code{regcmp}
-to check variable values.
diff --git a/docs/reference/functions/join_example.texinfo b/docs/reference/functions/join_example.texinfo
deleted file mode 100644
index 92f6f4be51..0000000000
--- a/docs/reference/functions/join_example.texinfo
+++ /dev/null
@@ -1,21 +0,0 @@
-
-@verbatim
-
-bundle agent test
-
-{
-vars:
-
- "mylist" slist => { "one", "two", "three", "four", "five" };
-
- "scalar" string => join("<->","mylist");
-
-reports:
-
- linux::
-
- "Concatenated $(scalar)";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/join_notes.texinfo b/docs/reference/functions/join_notes.texinfo
deleted file mode 100644
index dc3b378384..0000000000
--- a/docs/reference/functions/join_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Converts a string of type list into a scalar variable using the join string in first
-argument.
diff --git a/docs/reference/functions/lastnode_example.texinfo b/docs/reference/functions/lastnode_example.texinfo
deleted file mode 100644
index f104eb9fd3..0000000000
--- a/docs/reference/functions/lastnode_example.texinfo
+++ /dev/null
@@ -1,24 +0,0 @@
-
-@verbatim
-
-bundle agent yes
-{
-vars:
-
- "path1" string => "/one/two/last1";
- "path2" string => "one:two:last2";
-
- "last1" string => lastnode("$(path1)","/");
- "last2" string => lastnode("$(path2)",":");
-
- "last3" string => lastnode("$(path2)","/");
-
-reports:
-
- cfengine::
-
- "Last = $(last1),$(last2),$(last3)";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/lastnode_notes.texinfo b/docs/reference/functions/lastnode_notes.texinfo
deleted file mode 100644
index 4b67eb789a..0000000000
--- a/docs/reference/functions/lastnode_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-This function returns the final node in a chain, given a regular expression to split on.
-This is mainly useful for finding leaf-names of files, from a fully qualified path name.
diff --git a/docs/reference/functions/laterthan_example.texinfo b/docs/reference/functions/laterthan_example.texinfo
deleted file mode 100644
index 54ecb2255b..0000000000
--- a/docs/reference/functions/laterthan_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-@verbatim
-
-classes:
-
- "after_deadline" expression => laterthan(2000,1,1,0,0,0);
-
-@end verbatim
diff --git a/docs/reference/functions/laterthan_notes.texinfo b/docs/reference/functions/laterthan_notes.texinfo
deleted file mode 100644
index d8f26056a3..0000000000
--- a/docs/reference/functions/laterthan_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-The arguments are standard time, @xref{Function on}.
diff --git a/docs/reference/functions/ldaparray_example.texinfo b/docs/reference/functions/ldaparray_example.texinfo
deleted file mode 100644
index c3edebc28e..0000000000
--- a/docs/reference/functions/ldaparray_example.texinfo
+++ /dev/null
@@ -1,15 +0,0 @@
-
-@verbatim
-
-classes:
-
- "gotdata" expression => ldaparray(
- "myarray",
- "ldap://ldap.example.org",
- "dc=cfengine,dc=com",
- "(uid=mark)",
- "subtree",
- "none");
-
-@end verbatim
-
diff --git a/docs/reference/functions/ldaparray_notes.texinfo b/docs/reference/functions/ldaparray_notes.texinfo
deleted file mode 100644
index d335a18126..0000000000
--- a/docs/reference/functions/ldaparray_notes.texinfo
+++ /dev/null
@@ -1,44 +0,0 @@
-
-@cartouche
-@example
-
-(class) ldaparray (@var{array},@var{uri},@var{dn},@var{filter},@var{scope},@var{security})
-
-@end example
-@end cartouche
-
-This function retrieves an entire record with all elements and
-populates an associative array with the entries. It returns a class
-which is true if there was a match for the search and false if nothing
-was retrieved.
-
-@noindent @b{ARGUMENTS}:
-
-@table @samp
-@item array
-String name of the array to populate with the result of the search
-@item uri
-String value of the ldap server. e.g. @code{"ldap://ldap.cfengine.com.no"}
-@item dn
-Distinguished name, an ldap formatted name built from components, e.g. "dc=cfengine,dc=com".
-@item filter
-String filter criterion, in ldap search, e.g. "(sn=User)".
-@item scope
-Menu option, the type of ldap search, from
-@smallexample
- subtree
- onelevel
- base
-@end smallexample
-
-@item security
-Menu option indicating the encryption and authentication settings
-for communication with the LDAP server. These features might be subject
-to machine and server capabilites.
-@smallexample
- none
- ssl
- sasl
-@end smallexample
-@end table
-
diff --git a/docs/reference/functions/ldaplist_example.texinfo b/docs/reference/functions/ldaplist_example.texinfo
deleted file mode 100644
index 0dc1dfe8cf..0000000000
--- a/docs/reference/functions/ldaplist_example.texinfo
+++ /dev/null
@@ -1,16 +0,0 @@
-
-@verbatim
-vars:
-
- # Get all matching values for "uid" - should be a single record match
-
- "list" slist => ldaplist(
- "ldap://ldap.example.org",
- "dc=cfengine,dc=com",
- "(sn=User)",
- "uid",
- "subtree",
- "none"
- );
-
-@end verbatim
diff --git a/docs/reference/functions/ldaplist_notes.texinfo b/docs/reference/functions/ldaplist_notes.texinfo
deleted file mode 100644
index bd562fcd37..0000000000
--- a/docs/reference/functions/ldaplist_notes.texinfo
+++ /dev/null
@@ -1,41 +0,0 @@
-
-@cartouche
-@example
-
-(slist) ldaplist(@var{uri},@var{dn},@var{filter},@var{name},@var{scope},@var{security})
-
-@end example
-@end cartouche
-
-This function retrieves a single field from all matching LDAP records identified by the search
-parameters.
-
-@noindent @b{ARGUMENTS}:
-
-@table @samp
-@item uri
-String value of the ldap server. e.g. @code{"ldap://ldap.cfengine.com.no"}
-@item dn
-Distinguished name, an ldap formatted name built from components, e.g. "dc=cfengine,dc=com".
-@item filter
-String filter criterion, in ldap search, e.g. "(sn=User)".
-@item name
-String value, the name of a single record to be retrieved, e.g. @code{uid}.
-@item scope
-Menu option, the type of ldap search, from the specified root. May take values:
-@smallexample
- subtree
- onelevel
- base
-@end smallexample
-
-@item security
-Menu option indicating the encryption and authentication settings
-for communication with the LDAP server. These features might be subject
-to machine and server capabilites.
-@smallexample
- none
- ssl
- sasl
-@end smallexample
-@end table
diff --git a/docs/reference/functions/ldapvalue_example.texinfo b/docs/reference/functions/ldapvalue_example.texinfo
deleted file mode 100644
index 54e21833cb..0000000000
--- a/docs/reference/functions/ldapvalue_example.texinfo
+++ /dev/null
@@ -1,17 +0,0 @@
-
-@verbatim
-
-vars:
-
- # Get the first matching value for "uid" in schema
-
- "value" string => ldapvalue(
- "ldap://ldap.example.org",
- "dc=cfengine,dc=com",
- "(sn=User)",
- "uid",
- "subtree",
- "none"
- );
-
-@end verbatim
diff --git a/docs/reference/functions/ldapvalue_notes.texinfo b/docs/reference/functions/ldapvalue_notes.texinfo
deleted file mode 100644
index 180c2e807b..0000000000
--- a/docs/reference/functions/ldapvalue_notes.texinfo
+++ /dev/null
@@ -1,32 +0,0 @@
-
-
-@cartouche
-@example
-
-(string) ldapvalue(@var{uri},@var{dn},@var{filter},@var{name},@var{scope},@var{security})
-
-@end example
-@end cartouche
-
-This function retrieves a single field from a single LDAP record identified by the search
-parameters. The first matching value it taken.
-
-@noindent @b{ARGUMENTS}:
-
-@table @samp
-@item uri
-String value of the ldap server. e.g. @code{"ldap://ldap.cfengine.com.no"}
-@item dn
-Distinguished name, an ldap formatted name built from components, e.g. "dc=cfengine,dc=com".
-@item filter
-String filter criterion, in ldap search, e.g. "(sn=User)".
-@item name
-String value, the name of a single record to be retrieved, e.g. @code{uid}.
-@item scope
-Menu option, the type of ldap search, from the specified root. May take values:
-@smallexample
- subtree
- onelevel
- base
-@end smallexample
-@end table
diff --git a/docs/reference/functions/length_example.texinfo b/docs/reference/functions/length_example.texinfo
deleted file mode 100644
index 0e58d24e12..0000000000
--- a/docs/reference/functions/length_example.texinfo
+++ /dev/null
@@ -1,24 +0,0 @@
-
-@verbatim
-
-bundle agent test
-
-{
- vars:
- "test" slist => {
- 1,2,3,
- "one", "two", "three",
- "long string",
- "four", "fix", "six",
- "one", "two", "three",
- };
-
- "length" int => length("test");
- "test_str" string => join(",", "test");
-
- reports:
- "The test list is $(test_str)";
- "The test list has $(length) elements";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/length_notes.texinfo b/docs/reference/functions/length_notes.texinfo
deleted file mode 100644
index b2657cc8d8..0000000000
--- a/docs/reference/functions/length_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-Returns the number of elements in the list variable specified in arg1.
diff --git a/docs/reference/functions/lsdir_example.texinfo b/docs/reference/functions/lsdir_example.texinfo
deleted file mode 100644
index 7102b9fe00..0000000000
--- a/docs/reference/functions/lsdir_example.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-@verbatim
-vars:
- "listfiles" slist => lsdir("/etc", "(passwd|shadow).*", "true");
-@end verbatim
diff --git a/docs/reference/functions/lsdir_notes.texinfo b/docs/reference/functions/lsdir_notes.texinfo
deleted file mode 100644
index a4b48782fe..0000000000
--- a/docs/reference/functions/lsdir_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-@i{History}: Was introduced in 3.3.0, Nova 2.2.0 (2011)
-
-This function returns list of files in directory specified in arg1,
-matched with regular expression in arg2. In case arg3 is true, full
-paths are returned, otherwise only names relative to the the directory
-are returned.
diff --git a/docs/reference/functions/maparray_example.texinfo b/docs/reference/functions/maparray_example.texinfo
deleted file mode 100644
index c7ac5d05f8..0000000000
--- a/docs/reference/functions/maparray_example.texinfo
+++ /dev/null
@@ -1,31 +0,0 @@
-
-@verbatim
-
-body common control
-{
- bundlesequence => { run };
-}
-
-bundle agent run
-{
- vars:
- "todo[1]" string => "2";
- "todo[one]" string => "two";
- "todo[3999]" slist => { "big", "small" };
- "map" slist => maparray("yes $(this.k) $(this.v)", "todo");
-
- reports:
- cfengine::
- "Hello $(map)";
-}
-
-@end verbatim
-
-Outputs:
-
-@verbatim
-R: Hello yes 1 2
-R: Hello yes one two
-R: Hello yes 3999 big
-R: Hello yes 3999 small
-@end verbatim
diff --git a/docs/reference/functions/maparray_notes.texinfo b/docs/reference/functions/maparray_notes.texinfo
deleted file mode 100644
index 2c2da74ca9..0000000000
--- a/docs/reference/functions/maparray_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-The @var{this.k} and @var{this.v} variables will be available for
-expansion in the string scope, similar to the way @var{this} is
-available for @code{maplist}.
diff --git a/docs/reference/functions/maplist_example.texinfo b/docs/reference/functions/maplist_example.texinfo
deleted file mode 100644
index 4e2ef13427..0000000000
--- a/docs/reference/functions/maplist_example.texinfo
+++ /dev/null
@@ -1,16 +0,0 @@
-
-@verbatim
-
-bundle agent test
-{
-vars:
-
- "oldlist" slist => { "a", "b", "c" };
- "newlist" slist => maplist("Element ($(this))","oldlist");
-
-reports:
- linux::
- "Transform: $(newlist)";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/maplist_notes.texinfo b/docs/reference/functions/maplist_notes.texinfo
deleted file mode 100644
index e238e45a52..0000000000
--- a/docs/reference/functions/maplist_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-@i{History}: Was introduced in 3.3.0, Nova 2.2.0 (2011)
-
-This is essentially like the map() function in Perl, and applies to lists.
diff --git a/docs/reference/functions/none_example.texinfo b/docs/reference/functions/none_example.texinfo
deleted file mode 100644
index 87ec53566f..0000000000
--- a/docs/reference/functions/none_example.texinfo
+++ /dev/null
@@ -1,32 +0,0 @@
-
-@verbatim
-
-bundle agent test
-
-{
- classes:
- "none1" expression => none("jebadiah", "test");
- "none2" expression => none("2", "test");
-
- vars:
- "test" slist => {
- 1,2,3,
- "one", "two", "three",
- "long string",
- "four", "fix", "six",
- "one", "two", "three",
- };
-
- reports:
- "The test list is $(test)";
- none1::
- "none() test 1 passed";
- !none1::
- "none() test 1 failed";
- none2::
- "none() test 2 failed";
- !none2::
- "none() test 2 passed";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/none_notes.texinfo b/docs/reference/functions/none_notes.texinfo
deleted file mode 100644
index a7e101a878..0000000000
--- a/docs/reference/functions/none_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-arg1 is a regular expression tested against every element of the list
-arg2. If none match, this function returns true.
diff --git a/docs/reference/functions/not_example.texinfo b/docs/reference/functions/not_example.texinfo
deleted file mode 100644
index 286ff8f692..0000000000
--- a/docs/reference/functions/not_example.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-@verbatim
-
-commands:
- "/usr/bin/generate_config $(config)"
- ifvarclass => not(fileexists("/etc/config/$(config)"));
-
-@end verbatim
diff --git a/docs/reference/functions/not_notes.texinfo b/docs/reference/functions/not_notes.texinfo
deleted file mode 100644
index 0ea8f981f5..0000000000
--- a/docs/reference/functions/not_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-@i{History}: Was introduced in 3.2.0, Nova 2.1.0 (2011)
diff --git a/docs/reference/functions/now_example.texinfo b/docs/reference/functions/now_example.texinfo
deleted file mode 100644
index c322f4b742..0000000000
--- a/docs/reference/functions/now_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body file_select zero_age
-{
-mtime => irange(ago(1,0,0,0,0,0),now);
-file_result => "mtime";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/now_notes.texinfo b/docs/reference/functions/now_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/functions/now_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/functions/nth_example.texinfo b/docs/reference/functions/nth_example.texinfo
deleted file mode 100644
index c015d36305..0000000000
--- a/docs/reference/functions/nth_example.texinfo
+++ /dev/null
@@ -1,27 +0,0 @@
-
-@verbatim
-
-bundle agent test
-
-{
- vars:
- "test" slist => {
- 1,2,3,
- "one", "two", "three",
- "long string",
- "four", "fix", "six",
- "one", "two", "three",
- };
-
- "nth" slist => { 1, 2, 6, 10, 11, 1000 };
-
- "test[$(nth)]" string => nth("test", $(nth));
- "test[0]" string => nth("test", 0);
-
- reports:
- "The test list is $(test)";
- "element #$(nth) of the test list: $(test[$(nth)])";
- "element #0 of the test list: $(test[0])";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/nth_notes.texinfo b/docs/reference/functions/nth_notes.texinfo
deleted file mode 100644
index 9e6a0dd0a8..0000000000
--- a/docs/reference/functions/nth_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-Extracts a single element from a list variable specified in arg1 at the
-zero-based position arg2.
-
-Thus, if arg1 has @code{N} elements, arg2 would be useful between
-@code{0} and @code{N-1}. Above @code{N-1}, the call does not return a
-valid value.
diff --git a/docs/reference/functions/on_example.texinfo b/docs/reference/functions/on_example.texinfo
deleted file mode 100644
index 8126a65cf0..0000000000
--- a/docs/reference/functions/on_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-body file_select zero_age
-{
-mtime => irange(on(2000,1,1,0,0,0),now);
-file_result => "mtime";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/on_notes.texinfo b/docs/reference/functions/on_notes.texinfo
deleted file mode 100644
index 23743c0f62..0000000000
--- a/docs/reference/functions/on_notes.texinfo
+++ /dev/null
@@ -1,22 +0,0 @@
-
-An absolute date in the local timezone.
-Note that in process matching dates could be wrong by an hour
-depending on Daylight Savings Time / Summer Time. This is a known bug to be fixed.
-
-@noindent @b{ARGUMENTS}:
-
-@table @samp
-@item Years
-The year, e.g. 2009
-@item Month
-The Month, 1-12
-@item Day
-The day 1-31
-@item Hours
-The hour 0-23
-@item Minutes
-The minutes
-0-59
-@item Seconds
-The number of seconds 0-59
-@end table
diff --git a/docs/reference/functions/or_example.texinfo b/docs/reference/functions/or_example.texinfo
deleted file mode 100644
index 36a3fb3a95..0000000000
--- a/docs/reference/functions/or_example.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-@verbatim
-
-commands:
- "/usr/bin/generate_config $(config)"
- ifvarclass => or(not(fileexists("/etc/config/$(config)")), "force_configs");
-
-@end verbatim
diff --git a/docs/reference/functions/or_notes.texinfo b/docs/reference/functions/or_notes.texinfo
deleted file mode 100644
index 0ea8f981f5..0000000000
--- a/docs/reference/functions/or_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-@i{History}: Was introduced in 3.2.0, Nova 2.1.0 (2011)
diff --git a/docs/reference/functions/parseintarray_example.texinfo b/docs/reference/functions/parseintarray_example.texinfo
deleted file mode 100644
index 479322002c..0000000000
--- a/docs/reference/functions/parseintarray_example.texinfo
+++ /dev/null
@@ -1,37 +0,0 @@
-
-
-@verbatim
-
-bundle agent test(f)
-{
-vars:
-
- #######################################
- # Define data inline for convenience
- #######################################
-
- "table" string =>
-
-"1:2
-3:4
-5:6";
-
-#######################################
-
- "dim" int => parseintarray(
- "items",
- "$(table)",
- "\s*#[^\n]*",
- ":",
- "1000",
- "200000"
- );
-
- "keys" slist => getindices("items");
-
-reports:
- cfengine_3::
- "$(keys)";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/parseintarray_notes.texinfo b/docs/reference/functions/parseintarray_notes.texinfo
deleted file mode 100644
index 7434ba507a..0000000000
--- a/docs/reference/functions/parseintarray_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@i{History}: Was introduced in version 3.1.5a1, Nova 2.1.0 (2011)
-
-This function mirrors the exact behaviour of @code{readintarray()},
-but reads data from a variable instead of a file @pxref{Function readintarray}.
-By making data
-readable from a variable, data driven policies can be kept inline.
-This means that they will be visible in the CFEngine Knowledge
-Management portal.
diff --git a/docs/reference/functions/parserealarray_example.texinfo b/docs/reference/functions/parserealarray_example.texinfo
deleted file mode 100644
index 70956b46b2..0000000000
--- a/docs/reference/functions/parserealarray_example.texinfo
+++ /dev/null
@@ -1,37 +0,0 @@
-
-
-@verbatim
-
-bundle agent test(f)
-{
-vars:
-
- #######################################
- # Define data inline for convenience
- #######################################
-
- "table" string =>
-
-"1:1.6
-2:2.5
-3:3.4";
-
-#######################################
-
- "dim" int => parserealarray(
- "items",
- "$(table)",
- "\s*#[^\n]*",
- ":",
- "1000",
- "200000"
- );
-
- "keys" slist => getindices("items");
-
-reports:
- cfengine_3::
- "$(keys)";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/parserealarray_notes.texinfo b/docs/reference/functions/parserealarray_notes.texinfo
deleted file mode 100644
index 1f15c3f9f6..0000000000
--- a/docs/reference/functions/parserealarray_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@i{History}: Was introduced in version 3.1.5, Nova 2.1.0 (2011)
-
-This function mirrors the exact behaviour of @code{readrealarray()},
-but reads data from a variable instead of a file @pxref{Function readrealarray}.
-By making data
-readable from a variable, data driven policies can be kept inline.
-This means that they will be visible in the CFEngine Knowledge
-Management portal.
diff --git a/docs/reference/functions/parsestringarray_example.texinfo b/docs/reference/functions/parsestringarray_example.texinfo
deleted file mode 100644
index 891fcdc2d1..0000000000
--- a/docs/reference/functions/parsestringarray_example.texinfo
+++ /dev/null
@@ -1,37 +0,0 @@
-
-
-@verbatim
-
-bundle agent test(f)
-{
-vars:
-
- #######################################
- # Define data inline for convenience
- #######################################
-
- "table" string =>
-
-"one: a
-two: b
-three: c";
-
-#######################################
-
- "dim" int => parsestringarray(
- "items",
- "$(table)",
- "\s*#[^\n]*",
- ":",
- "1000",
- "200000"
- );
-
- "keys" slist => getindices("items");
-
-reports:
- cfengine_3::
- "$(keys)";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/parsestringarray_notes.texinfo b/docs/reference/functions/parsestringarray_notes.texinfo
deleted file mode 100644
index a439c84261..0000000000
--- a/docs/reference/functions/parsestringarray_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@i{History}: Was introduced in version 3.1.5, Nova 2.1.0 (2011)
-
-This function mirrors the exact behaviour of @code{readstringarray()},
-but reads data from a variable instead of a file
-@pxref{Function readstringarray}. By making data
-readable from a variable, data driven policies can be kept inline.
-This means that they will be visible in the CFEngine Knowledge
-Management portal.
diff --git a/docs/reference/functions/parsestringarrayidx_example.texinfo b/docs/reference/functions/parsestringarrayidx_example.texinfo
deleted file mode 100644
index 4cc17195f2..0000000000
--- a/docs/reference/functions/parsestringarrayidx_example.texinfo
+++ /dev/null
@@ -1,35 +0,0 @@
-@verbatim
-
-bundle agent test(f)
-{
-vars:
-
- #######################################
- # Define data inline for convenience
- #######################################
-
- "table" string =>
-
-"one: a
-two: b
-three: c";
-
-#######################################
-
- "dim" int => parsestringarrayidx(
- "items",
- "$(table)",
- "\s*#[^\n]*",
- ":",
- "1000",
- "200000"
- );
-
- "keys" slist => getindices("items");
-
-reports:
- cfengine_3::
- "$(keys)";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/parsestringarrayidx_notes.texinfo b/docs/reference/functions/parsestringarrayidx_notes.texinfo
deleted file mode 100644
index 916662a439..0000000000
--- a/docs/reference/functions/parsestringarrayidx_notes.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-@i{History}: Was introduced in version 3.1.5, Nova 2.1.0 (2011)
-
-This function mirrors the exact behaviour of @code{readstringarrayidx()},
-but reads data from a variable instead of a file
-@pxref{Function readstringarrayidx}. By making data
-readable from a variable, data driven policies can be kept inline.
-This means that they will be visible in the CFEngine Knowledge
-Management portal.
diff --git a/docs/reference/functions/peerleader_example.texinfo b/docs/reference/functions/peerleader_example.texinfo
deleted file mode 100644
index 5fab8b4887..0000000000
--- a/docs/reference/functions/peerleader_example.texinfo
+++ /dev/null
@@ -1,22 +0,0 @@
-
-@verbatim
-bundle agent peers
-{
-vars:
-
- "mygroup" slist => peers("/tmp/hostlist","#.*",4);
-
- "myleader" string => peerleader("/tmp/hostlist","#.*",4);
-
- "all_leaders" slist => peerleaders("/tmp/hostlist","#.*",4);
-
-reports:
-
- linux::
-
- "mypeer $(mygroup)";
- "myleader $(myleader)";
- "another leader $(all_leaders)";
-
-}
-@end verbatim
diff --git a/docs/reference/functions/peerleader_notes.texinfo b/docs/reference/functions/peerleader_notes.texinfo
deleted file mode 100644
index f01d600d82..0000000000
--- a/docs/reference/functions/peerleader_notes.texinfo
+++ /dev/null
@@ -1,57 +0,0 @@
-
-
-@cartouche
-@example
-
-(string) peerleader(@var{file of hosts},@var{comment pattern},@var{group size});
-
-@end example
-@end cartouche
-
-This function returns the name of a ost that may be considered the
-leader of a group of peers of the current host. Peers are defined
-according to a list of hosts, provided as a file in the first
-argument. This file should contain a list (one per line), possibly
-with comments, of fully qualified host names. CFEngine breaks up this
-list into non-overlapping groups of up to @var{groupsize}, each of
-which has a leader which is the first host in the group.
-
-The current host should belong to this file if it is expected to interact
-with the others. The function returns nothing if the host does not belong
-to the list.
-
-@noindent @b{ARGUMENTS}:
-
-@table @samp
-@item File of hosts
-A path to a list of hosts.
-
-@item Comment pattern
-A pattern that matches a legal comment in the file. The regex may
-match a partial line (that is, it is unanchored, @pxref{Anchored vs. unanchored regular expressions}).
-Comments are stripped as the file is read.
-
-@item Group size
-A number between 2 and 64 which represents the number of peers in a peer-group.
-An arbitary limit of 64 is set on groups to avoid nonsensical promises.
-
-@end table
-
-Example file:
-
-@smallexample
-one
-two
-three # this is a comment
-four
-five
-six
-seven
-eight
-nine
-ten
-eleven
-twelve
-etc
-
-@end smallexample
diff --git a/docs/reference/functions/peerleaders_example.texinfo b/docs/reference/functions/peerleaders_example.texinfo
deleted file mode 100644
index 7033d7004a..0000000000
--- a/docs/reference/functions/peerleaders_example.texinfo
+++ /dev/null
@@ -1,23 +0,0 @@
-
-@verbatim
-bundle agent peers
-{
-vars:
-
- "mygroup" slist => peers("/tmp/hostlist","#.*",4);
-
- "myleader" string => peerleader("/tmp/hostlist","#.*",4);
-
- "all_leaders" slist => peerleaders("/tmp/hostlist","#.*",4);
-
-reports:
-
- linux::
-
- "mypeer $(mygroup)";
- "myleader $(myleader)";
- "another leader $(all_leaders)";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/peerleaders_notes.texinfo b/docs/reference/functions/peerleaders_notes.texinfo
deleted file mode 100644
index 559ef91ddf..0000000000
--- a/docs/reference/functions/peerleaders_notes.texinfo
+++ /dev/null
@@ -1,57 +0,0 @@
-
-@cartouche
-@example
-
-(slist) peers(@var{file of hosts},@var{comment pattern},@var{group size});
-
-@end example
-@end cartouche
-
-This function returns a list of hostnames that may be considered peer
-leaders in the partitioning scheme described in the file of
-hosts. Peers are defined according to a list of hosts, provided as a
-file in the first argument. This file should contain a list (one per
-line), possible with comments, of fully qualified host names. CFEngine
-breaks up this list into non-overlapping groups of up to
-@var{groupsize}, each of which has a leader which is the first host in
-the group.
-
-The current host need not belong to this file.
-
-@noindent @b{ARGUMENTS}:
-
-@table @samp
-@item File of hosts
-A path to a list of hosts.
-
-@item Comment pattern
-A pattern that matches a legal comment in the file. The regex may
-match a partial line (that is, it is unanchored,
-@pxref{Anchored vs. unanchored regular expressions}).
-Comments are stripped as the file is read.
-
-@item Group size
-A number between 2 and 64 which represents the number of peers in a peer-group.
-An arbitary limit of 64 is set on groups to avoid nonsensical promises.
-
-@end table
-
-
-Example file:
-
-@smallexample
-one
-two
-three # this is a comment
-four
-five
-six
-seven
-eight
-nine
-ten
-eleven
-twelve
-etc
-
-@end smallexample
diff --git a/docs/reference/functions/peers_example.texinfo b/docs/reference/functions/peers_example.texinfo
deleted file mode 100644
index b480785935..0000000000
--- a/docs/reference/functions/peers_example.texinfo
+++ /dev/null
@@ -1,24 +0,0 @@
-
-@verbatim
-
-bundle agent peers
-{
-vars:
-
- "mygroup" slist => peers("/tmp/hostlist","#.*",4);
-
- "myleader" string => peerleader("/tmp/hostlist","#.*",4);
-
- "all_leaders" slist => peerleaders("/tmp/hostlist","#.*",4);
-
-reports:
-
- linux::
-
- "mypeer $(mygroup)";
- "myleader $(myleader)";
- "another leader $(all_leaders)";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/peers_notes.texinfo b/docs/reference/functions/peers_notes.texinfo
deleted file mode 100644
index a4562da5e1..0000000000
--- a/docs/reference/functions/peers_notes.texinfo
+++ /dev/null
@@ -1,58 +0,0 @@
-
-@cartouche
-@example
-
-(slist) peers(@var{file of hosts},@var{comment pattern},@var{group size});
-
-@end example
-@end cartouche
-
-This function returns a list of hostnames that may be considered peers
-of the current host. Peers are defined according to a list of hosts,
-provided as a file in the first argument. This file should contain a
-list (one per line), possible with comments, of fully qualified host
-names. CFEngine breaks up this list into non-overlapping groups of up to
-@var{groupsize}, each of which has a leader which is the first host
-in the group.
-
-
-The current host should belong to this file if it is expected to interact
-with the others. The function returns nothing if the host does not belong
-to the list.
-
-@noindent @b{ARGUMENTS}:
-
-@table @samp
-@item File of hosts
-A path to a list of hosts.
-
-@item Comment pattern
-A pattern that matches a legal comment in the file. The regex may
-match a partial line (that is, it is unanchored,
-@pxref{Anchored vs. unanchored regular expressions}).
-Comments are stripped as the file is read.
-
-@item Group size
-A number between 2 and 64 which represents the number of peers in a peer-group.
-An arbitary limit of 64 is set on groups to avoid nonsensical promises.
-@end table
-
-
-Example file:
-
-@smallexample
-one
-two
-three # this is a comment
-four
-five
-six
-seven
-eight
-nine
-ten
-eleven
-twelve
-etc
-
-@end smallexample
diff --git a/docs/reference/functions/product_example.texinfo b/docs/reference/functions/product_example.texinfo
deleted file mode 100644
index 94a958481e..0000000000
--- a/docs/reference/functions/product_example.texinfo
+++ /dev/null
@@ -1,18 +0,0 @@
-
-@verbatim
-bundle agent test
-{
-vars:
-
- "series" rlist => { "1.1", "2.2", "3.3", "5.5", "7.7" };
-
- "prod" real => product("series");
- "sum" real => sum("series");
-
-reports:
-
- cfengine_3::
-
- "Product result: $(prod) > $(sum)";
-}
-@end verbatim
diff --git a/docs/reference/functions/product_notes.texinfo b/docs/reference/functions/product_notes.texinfo
deleted file mode 100644
index 6fa0197f31..0000000000
--- a/docs/reference/functions/product_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-Of course, you could easily combine @code{product} with @code{readstringarray}
-or @code{readreallist}, etc. to collect summary information from a source
-external to CFEngine.
-
-@b{History}: Was introduced in version 3.1.0b1,Nova 2.0.0b1 (2010)
-
-This function might be used for simple ring computation.
diff --git a/docs/reference/functions/randomint_example.texinfo b/docs/reference/functions/randomint_example.texinfo
deleted file mode 100644
index 46bd01c184..0000000000
--- a/docs/reference/functions/randomint_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-@verbatim
-
-vars:
-
- "ran" int => randomint(4,88);
-
-@end verbatim
diff --git a/docs/reference/functions/randomint_notes.texinfo b/docs/reference/functions/randomint_notes.texinfo
deleted file mode 100644
index 75cce93a04..0000000000
--- a/docs/reference/functions/randomint_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-The limits must be integer values and the resulting numbers are based
-on the entropy of the md5 algorithm.
diff --git a/docs/reference/functions/readfile_example.texinfo b/docs/reference/functions/readfile_example.texinfo
deleted file mode 100644
index 37b5b497f8..0000000000
--- a/docs/reference/functions/readfile_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-vars:
-
- "xxx"
-
- string => readfile( "/home/mark/tmp/testfile" , "33" );
-
-@end verbatim
diff --git a/docs/reference/functions/readfile_notes.texinfo b/docs/reference/functions/readfile_notes.texinfo
deleted file mode 100644
index 6701cf9607..0000000000
--- a/docs/reference/functions/readfile_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-The file (fragment) is read into a single scalar variable.
diff --git a/docs/reference/functions/readintarray_example.texinfo b/docs/reference/functions/readintarray_example.texinfo
deleted file mode 100644
index 1ceccb3c92..0000000000
--- a/docs/reference/functions/readintarray_example.texinfo
+++ /dev/null
@@ -1,38 +0,0 @@
-
-@verbatim
-vars:
-
- "dim_array"
-
- int => readintarray("array_name","/tmp/array","#[^\n]*",":",10,4000);
-
-@end verbatim
-
-
-@noindent @b{ARGUMENTS}:
-
-@table @samp
-@item array_name
-The name to be used for the container array (the array is filled by this routine).
-
-@item filename
-The name of a text file containing the text to be split up as a list.
-
-@item comment
-A regex pattern which specifies comments to be ignored in the file.
-The @code{comment} field will strip out unwanted patterns from the
-file being read, leaving unstripped characters to be split into
-fields. Using the empty string (@code{""}) indicates no commments. The
-regex is unanchored, @xref{Anchored vs. unanchored regular
-expressions}.
-
-@item split
-A regex pattern which is used to parse the field separator(s)
-to split up the file into items. The @code{split} regex is also unanchored.
-
-@item maxent
-The maximum number of list items to read from the file
-
-@item maxsize
-The maximum number of bytes to read from the file
-@end table
diff --git a/docs/reference/functions/readintarray_notes.texinfo b/docs/reference/functions/readintarray_notes.texinfo
deleted file mode 100644
index 8fa7a9b2b8..0000000000
--- a/docs/reference/functions/readintarray_notes.texinfo
+++ /dev/null
@@ -1,37 +0,0 @@
-
-Reads a two dimensional array from a file. One dimension is separated by
-the character specified in the argument, the other by the the lines in the file.
-The first field of the lines names the first array argument.
-
-@smallexample
-
-1: 5:7:21:13
-2:19:8:14:14
-3:45:1:78:22
-4:64:2:98:99
-@end smallexample
-
-@noindent Results in
-
-@smallexample
-array_name[1][0] 1
-array_name[1][1] 5
-array_name[1][2] 7
-array_name[1][3] 21
-array_name[1][4] 13
-array_name[2][0] 2
-array_name[2][1] 19
-array_name[2][2] 8
-array_name[2][3] 14
-array_name[2][4] 14
-array_name[3][0] 3
-array_name[3][1] 45
-array_name[3][2] 1
-array_name[3][3] 78
-array_name[3][4] 22
-array_name[4][0] 4
-array_name[4][1] 64
-array_name[4][2] 2
-array_name[4][3] 98
-array_name[4][4] 99
-@end smallexample
diff --git a/docs/reference/functions/readintlist_example.texinfo b/docs/reference/functions/readintlist_example.texinfo
deleted file mode 100644
index 76bd806ada..0000000000
--- a/docs/reference/functions/readintlist_example.texinfo
+++ /dev/null
@@ -1,54 +0,0 @@
-
-@verbatim
-
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-vars:
-
- "mylist" ilist => { readintlist("/tmp/listofint","#.*","[\n]",10,400) };
-
-reports:
-
- Yr2008::
-
- "List entry: $(mylist)";
-
-}
-
-@end verbatim
-
-
-@noindent @b{ARGUMENTS}:
-
-@table @samp
-@item filename
-The name of a text file containing text to be split up as a list.
-
-@item comment
-A regex pattern which specifies comments to be ignored in the file.
-The @code{comment} field will strip out unwanted patterns from the
-file being read, leaving unstripped characters to be split into
-fields. Using the empty string (@code{""}) indicates no commments. The
-regex is unanchored, @xref{Anchored vs. unanchored regular
-expressions}.
-
-@item split
-A regex pattern which is used to parse the field separator(s)
-to split up the file into items. The @code{split} regex is also unanchored.
-
-@item maxent
-The maximum number of list items to read from the file
-
-@item maxsize
-The maximum number of bytes to read from the file
-@end table
diff --git a/docs/reference/functions/readintlist_notes.texinfo b/docs/reference/functions/readintlist_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/functions/readintlist_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/functions/readrealarray_example.texinfo b/docs/reference/functions/readrealarray_example.texinfo
deleted file mode 100644
index 9b755306ac..0000000000
--- a/docs/reference/functions/readrealarray_example.texinfo
+++ /dev/null
@@ -1,38 +0,0 @@
-
-@verbatim
-vars:
-
- "dim_array"
-
- int => readrealarray("array_name","/tmp/array","#[^\n]*",":",10,4000);
-
-@end verbatim
-
-
-@noindent @b{ARGUMENTS}:
-
-@table @samp
-@item array_name
-The name to be used for the container array (the array is filled by this routine).
-
-@item filename
-The name of a text file containing the text to be split up as a list.
-
-@item comment
-A regex pattern which specifies comments to be ignored in the file.
-The @code{comment} field will strip out unwanted patterns from the
-file being read, leaving unstripped characters to be split into
-fields. Using the empty string (@code{""}) indicates no commments. The
-regex is unanchored, @xref{Anchored vs. unanchored regular
-expressions}.
-
-@item split
-A regex pattern which is used to parse the field separator(s)
-to split up the file into items. The @code{split} regex is also unanchored.
-
-@item maxent
-The maximum number of list items to read from the file
-
-@item maxsize
-The maximum number of bytes to read from the file
-@end table
diff --git a/docs/reference/functions/readrealarray_notes.texinfo b/docs/reference/functions/readrealarray_notes.texinfo
deleted file mode 100644
index 38db67cc60..0000000000
--- a/docs/reference/functions/readrealarray_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-
-For detailed notes, @xref{Function readintarray}.
diff --git a/docs/reference/functions/readreallist_example.texinfo b/docs/reference/functions/readreallist_example.texinfo
deleted file mode 100644
index 4f2524a3f1..0000000000
--- a/docs/reference/functions/readreallist_example.texinfo
+++ /dev/null
@@ -1,54 +0,0 @@
-
-@verbatim
-
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-vars:
-
- "mylist" rlist => { readreallist("/tmp/listofreal","#.*","[\n]",10,400) };
-
-reports:
-
- Yr2008::
-
- "List entry: $(mylist)";
-
-}
-
-@end verbatim
-
-
-@noindent @b{ARGUMENTS}:
-
-@table @samp
-@item filename
-The name of a text file containing text to be split up as a list.
-
-@item comment
-A regex pattern which specifies comments to be ignored in the file.
-The @code{comment} field will strip out unwanted patterns from the
-file being read, leaving unstripped characters to be split into
-fields. Using the empty string (@code{""}) indicates no commments. The
-regex is unanchored, @xref{Anchored vs. unanchored regular
-expressions}.
-
-@item split
-A regex pattern which is used to parse the field separator(s)
-to split up the file into items. The @code{split} regex is also unanchored.
-
-@item maxent
-The maximum number of list items to read from the file
-
-@item maxsize
-The maximum number of bytes to read from the file
-@end table
diff --git a/docs/reference/functions/readreallist_notes.texinfo b/docs/reference/functions/readreallist_notes.texinfo
deleted file mode 100644
index e69de29bb2..0000000000
diff --git a/docs/reference/functions/readstringarray_example.texinfo b/docs/reference/functions/readstringarray_example.texinfo
deleted file mode 100644
index 397a153a74..0000000000
--- a/docs/reference/functions/readstringarray_example.texinfo
+++ /dev/null
@@ -1,43 +0,0 @@
-
-
-@verbatim
-vars:
-
- "dim_array"
-
- int => readstringarray("array_name","/tmp/array","\s*#[^\n]*",":",10,4000);
-
-@end verbatim
-
-@noindent Returns an integer number of keys in the array (i.e., the
-number of lines matched). If you only want the fields in the first
-matching line (e.g., to mimic the behavior of the @i{getpwnam(3)}
-on the file @file{/etc/passwd}), @xref{Function getfields}, instead.
-
-@noindent @b{ARGUMENTS}:
-
-@table @samp
-@item array_name
-The name to be used for the container array (the array is filled by this routine).
-
-@item filename
-The name of a text file containing the text to be split up as a list.
-
-@item comment
-A regex pattern which specifies comments to be ignored in the file.
-The @code{comment} field will strip out unwanted patterns from the
-file being read, leaving unstripped characters to be split into
-fields. Using the empty string (@code{""}) indicates no commments. The
-regex is unanchored, @xref{Anchored vs. unanchored regular
-expressions}.
-
-@item split
-A regex pattern which is used to parse the field separator(s)
-to split up the file into items. The @code{split} regex is also unanchored.
-
-@item maxent
-The maximum number of list items to read from the file
-
-@item maxsize
-The maximum number of bytes to read from the file
-@end table
diff --git a/docs/reference/functions/readstringarray_notes.texinfo b/docs/reference/functions/readstringarray_notes.texinfo
deleted file mode 100644
index df902c829f..0000000000
--- a/docs/reference/functions/readstringarray_notes.texinfo
+++ /dev/null
@@ -1,43 +0,0 @@
-
-
-
-Reads a two dimensional array from a file. One dimension is separated by
-the character specified in the argument, the other by the the lines in the file.
-The first field of the lines names the first array argument.
-
-@smallexample
-
-at:x:25:25:Batch jobs daemon:/var/spool/atjobs:/bin/bash
-avahi:x:103:105:User for Avahi:/var/run/avahi-daemon:/bin/false # Disallow login
-beagleindex:x:104:106:User for Beagle indexing:/var/cache/beagle:/bin/bash
-bin:x:1:1:bin:/bin:/bin/bash
-# Daemon has the default shell
-daemon:x:2:2:Daemon:/sbin:
-
-@end smallexample
-
-@noindent Results in a systematically indexed map of the file. Some samples
-are show below to illustrate the pattern.
-
-@smallexample
-...
-array_name[daemon][0] daemon
-array_name[daemon][1] x
-array_name[daemon][2] 2
-array_name[daemon][3] 2
-array_name[daemon][4] Daemon
-array_name[daemon][5] /sbin
-array_name[daemon][6] /bin/bash
-...
-array_name[at][3] 25
-array_name[at][4] Batch jobs daemon
-array_name[at][5] /var/spool/atjobs
-array_name[at][6] /bin/bash
-...
-array_name[games][3] 100
-array_name[games][4] Games account
-array_name[games][5] /var/games
-array_name[games][6] /bin/bash
-...
-
-@end smallexample
diff --git a/docs/reference/functions/readstringarrayidx_example.texinfo b/docs/reference/functions/readstringarrayidx_example.texinfo
deleted file mode 100644
index 9c0cb4e057..0000000000
--- a/docs/reference/functions/readstringarrayidx_example.texinfo
+++ /dev/null
@@ -1,44 +0,0 @@
-
-
-@verbatim
-vars:
-
- "dim_array"
-
- int => readstringarrayidx("array_name","/tmp/array","\s*#[^\n]*",":",10,4000);
-
-@end verbatim
-
-@noindent Returns an integer number of keys in the array (i.e., the
-number of lines matched). If you only want the fields in the first
-matching line (e.g., to mimic the behavior of the @i{getpwnam(3)}
-on the file @file{/etc/passwd}), @xref{Function getfields}, instead.
-
-@noindent @b{ARGUMENTS}:
-
-@table @samp
-@item array_name
-The name to be used for the container array (the array is filled by this routine).
-
-@item filename
-The name of a text file containing the text to be split up as a list.
-
-@item comment
-A regex pattern which specifies comments to be ignored in the file.
-The @code{comment} field will strip out unwanted patterns from the
-file being read, leaving unstripped characters to be split into
-fields. Using the empty string (@code{""}) indicates no commments. The
-regex is unanchored. @xref{Anchored vs. unanchored regular
-expressions}.
-
-@item split
-A regex pattern which is used to parse the field separator(s)
-to split up the file into items. The @code{split} regex is also unanchored.
-
-@item maxent
-The maximum number of list items to read from the file
-
-@item maxsize
-The maximum number of bytes to read from the file
-@end table
-
diff --git a/docs/reference/functions/readstringarrayidx_notes.texinfo b/docs/reference/functions/readstringarrayidx_notes.texinfo
deleted file mode 100644
index c077781e9a..0000000000
--- a/docs/reference/functions/readstringarrayidx_notes.texinfo
+++ /dev/null
@@ -1,40 +0,0 @@
-
-
-Reads a two dimensional array from a file. One dimension is separated by
-the character specified in the argument, the other by the the lines in the file.
-The array arguments are both integer indeces, allowing for
-non-identifiers at first field (e.g. duplicates or names with spaces),
-unlike @code{readstringarray}.
-
-@smallexample
-
-at spaced:x:25:25:Batch jobs daemon:/var/spool/atjobs:/bin/bash
-duplicate:x:103:105:User for Avahi:/var/run/avahi-daemon:/bin/false # Disallow login
-beagleindex:x:104:106:User for Beagle indexing:/var/cache/beagle:/bin/bash
-duplicate:x:1:1:bin:/bin:/bin/bash
-# Daemon has the default shell
-daemon:x:2:2:Daemon:/sbin:
-
-@end smallexample
-
-@noindent Results in a systematically indexed map of the file. Some samples
-are show below to illustrate the pattern.
-
-@smallexample
-array_name[0][0] at spaced
-array_name[0][1] x
-array_name[0][2] 25
-array_name[0][3] 25
-array_name[0][4] Batch jobs daemon
-array_name[0][5] /var/spool/atjobs
-array_name[0][6] /bin/bash
-array_name[1][0] duplicate
-array_name[1][1] x
-array_name[1][2] 103
-array_name[1][3] 105
-array_name[1][4] User for Avahi
-array_name[1][5] /var/run/avahi-daemon
-array_name[1][6] /bin/false
-...
-
-@end smallexample
diff --git a/docs/reference/functions/readstringlist_example.texinfo b/docs/reference/functions/readstringlist_example.texinfo
deleted file mode 100644
index 7360f2f084..0000000000
--- a/docs/reference/functions/readstringlist_example.texinfo
+++ /dev/null
@@ -1,56 +0,0 @@
-
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-vars:
-
- "mylist" slist => readstringlist("/tmp/listofstring", "#.*", "\s", 10, 400);
-
-reports:
-
- Yr2008::
-
- "List entry: $(mylist)";
-
-}
-
-@end verbatim
-
-
-@noindent @b{ARGUMENTS}:
-
-@table @samp
-@item filename
-The name of a text file containing text to be split up as a list.
-
-@item comment
-A regex pattern which specifies comments to be ignored in the file. The
-@code{comment} field will strip out unwanted patterns from the file being
-read, leaving unstripped characters to be split into fields. The
-regex is unanchored, @xref{Anchored vs. unanchored regular expressions}.
-@b{Note} that the text is not treated as a collection of lines, but is read
-as a single block of @code{maxsize} characters, and the regex is applied to
-that as a single string.
-
-@item split
-A regex pattern which is used to parse the field separator(s)
-to split up the file into items. The @code{split} regex is also unanchored.
-
-@item maxent
-The maximum number of list items to read from the file
-
-@item maxsize
-The maximum number of bytes to read from the file
-@end table
-
diff --git a/docs/reference/functions/readstringlist_notes.texinfo b/docs/reference/functions/readstringlist_notes.texinfo
deleted file mode 100644
index 08ecaf8f67..0000000000
--- a/docs/reference/functions/readstringlist_notes.texinfo
+++ /dev/null
@@ -1,19 +0,0 @@
-
-The following example file would be split into a list of the
-first ten Greek letters - alpha through kappa.
-
-@smallexample
-
-alpha beta
-gamma # This is a comment
-delta epsilon zeta
- eta
- theta
-iota
-kappa lambda
-mu
-nu
-etc
-
-
-@end smallexample
diff --git a/docs/reference/functions/readtcp_example.texinfo b/docs/reference/functions/readtcp_example.texinfo
deleted file mode 100644
index 7ced662b37..0000000000
--- a/docs/reference/functions/readtcp_example.texinfo
+++ /dev/null
@@ -1,40 +0,0 @@
-
-@verbatim
-
-bundle agent example
-
-{
-vars:
-
- "my80" string => readtcp("research.iu.hio.no","80","GET /index.php HTTP/1.1$(const.r)$(const.n)Host: research.iu.hio.no$(const.r)$(const.n)$(const.r)$(const.n)",20);
-
-classes:
-
- "server_ok" expression => regcmp("[^\n]*200 OK.*\n.*","$(my80)");
-
-reports:
-
- server_ok::
-
- "Server is alive";
-
- !server_ok::
-
- "Server is not responding - got $(my80)";
-}
-
-@end verbatim
-
-@table @samp
-@item hostnameip
-The host name or IP address of a tcp socket.
-@item port
-The port number to connect to.
-@item sendstring
-A string to send to the TCP port to elicit a response
-@item maxbytes
-The maximum number of bytes to read in response.
-@end table
-
-Important note: not all Unix TCP read operations respond to signals for interruption so
-poorly formed requests can hang. Always test TCP connections fully before deploying.
diff --git a/docs/reference/functions/readtcp_notes.texinfo b/docs/reference/functions/readtcp_notes.texinfo
deleted file mode 100644
index 94c770f7c4..0000000000
--- a/docs/reference/functions/readtcp_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-If the send string is empty, no data are sent or received from the socket. Then the
-function only tests whether the TCP port is alive and returns an empty variable.
-
-Note that on some systems the timeout mechanism does not seem to successfully interrupt
-the waiting system calls so this might hang if you send a query string that is incorrect.
-This should not happen, but the cause has yet to be diagnosed.
diff --git a/docs/reference/functions/regarray_example.texinfo b/docs/reference/functions/regarray_example.texinfo
deleted file mode 100644
index 1d76690669..0000000000
--- a/docs/reference/functions/regarray_example.texinfo
+++ /dev/null
@@ -1,38 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "testbundle" };
-}
-
-###########################################
-
-bundle agent testbundle
-{
-vars:
-
- "myarray[0]" string => "bla1";
- "myarray[1]" string => "bla2";
- "myarray[3]" string => "bla";
- "myarray" string => "345";
- "not" string => "345";
-
-classes:
-
- "ok" expression => regarray("myarray","b.*2");
-
-reports:
-
- ok::
-
- "Found in list";
-
- !ok::
-
- "Not found in list";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/regarray_notes.texinfo b/docs/reference/functions/regarray_notes.texinfo
deleted file mode 100644
index 1421de184f..0000000000
--- a/docs/reference/functions/regarray_notes.texinfo
+++ /dev/null
@@ -1,14 +0,0 @@
-
-Tests whether an associative array contains elements matching a certain regular expression.
-The result is a class.
-
-@noindent @b{ARGUMENTS}:
-
-@table @samp
-@item array_name
-The name of the array, with no @samp{$()} surrounding it, etc.
-@item regex
-A regular expression to match the content. The regular expression
-must match the complete array element (that is, it is anchored,
-@pxref{Anchored vs. unanchored regular expressions}).
-@end table
diff --git a/docs/reference/functions/regcmp_example.texinfo b/docs/reference/functions/regcmp_example.texinfo
deleted file mode 100644
index 70429a082b..0000000000
--- a/docs/reference/functions/regcmp_example.texinfo
+++ /dev/null
@@ -1,22 +0,0 @@
-
-@verbatim
-
-bundle agent subtest(user)
-
-{
-classes:
-
- "invalid" not => regcmp("[a-z]{4}","$(user)");
-
-reports:
-
- !invalid::
-
- "User name $(user) is valid at exactly 4 letters";
-
- invalid::
-
- "User name $(user) is invalid";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/regcmp_notes.texinfo b/docs/reference/functions/regcmp_notes.texinfo
deleted file mode 100644
index b0209e3bb2..0000000000
--- a/docs/reference/functions/regcmp_notes.texinfo
+++ /dev/null
@@ -1,65 +0,0 @@
-
-Compares a string to a regular expression.
-
-@noindent @b{ARGUMENTS}:
-
-@table @samp
-@item regex
-A regular expression to match the content. The regular expression
-must match the complete content (that is, it is anchored,
-@pxref{Anchored vs. unanchored regular expressions}).
-
-@item string
-Test data for the regular expression.
-@end table
-
-If there are multiple-lines in the data, it is necessary to code these
-explicitly, as regular expressions do not normally match the end of line
-as a regular character (they only match end of string). You can do this using either standard regular
-expression syntax or using the additional features of PCRE (where
-@code{(?ms)} changes the way that @samp{.}, @samp{^} and @samp{$} behave), e.g.
-
-@smallexample
-
-body common control
-@{
-bundlesequence => @{ "example" @};
-@}
-
-bundle agent example
-@{
-vars:
-
- "x" string => "
-NAME: apache2 - Apache 2.2 web server
-CATEGORY: application
-ARCH: all
-VERSION: 2.2.3,REV=2006.09.01
-BASEDIR: /
-VENDOR: http://httpd.apache.org/ packaged for CSW by Cory Omand
-PSTAMP: comand@@thor-20060901022929
-INSTDATE: Dec 14 2006 16:05
-HOTLINE: http://www.blastwave.org/bugtrack/
-EMAIL: comand@@blastwave.org
-STATUS: completely installed
-";
-
-classes:
-
- "pkg_installed" expression => regcmp("(.*\n)*STATUS:\s+completely installed\n(.*\n)*",$(x));
-
- "base_is_root" expression => regcmp("(?ms).*^BASEDIR:\s+/$.*", $(x));
-
-reports:
-
- pkg_installed::
-
- "installed";
-
- base_is_root::
-
- "in root";
-@}
-
-
-@end smallexample
diff --git a/docs/reference/functions/regextract_example.texinfo b/docs/reference/functions/regextract_example.texinfo
deleted file mode 100644
index c11bbe9e2e..0000000000
--- a/docs/reference/functions/regextract_example.texinfo
+++ /dev/null
@@ -1,22 +0,0 @@
-
-@verbatim
-bundle agent testbundle
-{
-classes:
-
- # Extract regex backreferences and put them in an array
-
- "ok" expression => regextract(
- "xx ([^\s]+) ([^\s]+).* xx",
- "xx one two three four xx",
- "myarray"
- );
-reports:
-
- ok::
-
- "ok - \"$(myarray[0])\" = xx + \"$(myarray[1])\" + \"$(myarray[2])\" + .. + xx";
-}
-
-
-@end verbatim
diff --git a/docs/reference/functions/regextract_notes.texinfo b/docs/reference/functions/regextract_notes.texinfo
deleted file mode 100644
index 1743333e55..0000000000
--- a/docs/reference/functions/regextract_notes.texinfo
+++ /dev/null
@@ -1,22 +0,0 @@
-
-@noindent @b{Arguments:}
-
-@table @i
-@item regex
-A regular expression containing one or more parenthesized back
-references. The regular expression must match the entire string
-(that is, it is anchored, @pxref{Anchored vs. unanchored regular expressions}).
-@item data
-A string to be matched to the regular expression.
-@item identifier
-The name of an array which (if there are any back reference matches
-from the regular expression) will be populated with the values, in
-the manner
-@example
-$(identifier[0]) = entire string
-$(identifier[1]) = back reference 1, etc
-@end example
-
-@end table
-
-@b{History}: This function was introduced in CFEngine version 3.0.4 (2010)
diff --git a/docs/reference/functions/registryvalue_example.texinfo b/docs/reference/functions/registryvalue_example.texinfo
deleted file mode 100644
index 6791bbb128..0000000000
--- a/docs/reference/functions/registryvalue_example.texinfo
+++ /dev/null
@@ -1,18 +0,0 @@
-
-@verbatim
-
-bundle agent reg
-{
-vars:
-
- "value" string => registryvalue("HKEY_LOCAL_MACHINE\SOFTWARE\CFEngine AS\CFEngine","value3");
-
-reports:
-
- windows::
-
- "Value extracted: $(value)";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/registryvalue_notes.texinfo b/docs/reference/functions/registryvalue_notes.texinfo
deleted file mode 100644
index b59752f5ef..0000000000
--- a/docs/reference/functions/registryvalue_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-This function applies only to Windows-based systems. It reads a data field for the value named
-in the second argument, which lies within the registry key given by the first argument.
-
-The value is parsed as a string. Currently values of type @code{REG_SZ} (string),
-@code{REG_EXPAND_SZ} (expandable string) and @code{REG_DWORD} (double word) are supported.
diff --git a/docs/reference/functions/regldap_example.texinfo b/docs/reference/functions/regldap_example.texinfo
deleted file mode 100644
index 57338ce00d..0000000000
--- a/docs/reference/functions/regldap_example.texinfo
+++ /dev/null
@@ -1,16 +0,0 @@
-
-@verbatim
-
-classes:
-
- "found" expression => regldap(
- "ldap://ldap.example.org",
- "dc=cfengine,dc=com",
- "(sn=User)",
- "uid",
- "subtree",
- "jon.*",
- "none"
- );
-
-@end verbatim
diff --git a/docs/reference/functions/regldap_notes.texinfo b/docs/reference/functions/regldap_notes.texinfo
deleted file mode 100644
index 31abb6b3d1..0000000000
--- a/docs/reference/functions/regldap_notes.texinfo
+++ /dev/null
@@ -1,50 +0,0 @@
-
-
-@cartouche
-@example
-
-(class) regldap(@var{uri},@var{dn},@var{filter},@var{name},@var{scope},@var{regex},@var{security})
-
-@end example
-@end cartouche
-
-This function retrieves a single field from all matching LDAP records identified by the search
-parameters and compares it to a regular expression. If there is a match, true is returned
-else false.
-
-@noindent @b{ARGUMENTS}:
-
-@table @samp
-@item uri
-String value of the ldap server. e.g. @code{"ldap://ldap.cfengine.com.no"}
-@item dn
-Distinguished name, an ldap formatted name built from components, e.g. "dc=cfengine,dc=com".
-@item filter
-String filter criterion, in ldap search, e.g. "(sn=User)".
-@item name
-String value, the name of a single record to be retrieved, e.g. @code{uid}.
-@item scope
-Menu option, the type of ldap search, from the specified root. May take values:
-@smallexample
- subtree
- onelevel
- base
-@end smallexample
-
-@item regex
-A regular expression string to match to the results of an LDAP
-search. The regular expression must match the entire named field
-(that is, it is anchored, @pxref{Anchored vs. unanchored regular expressions}).
-If any item matches the regex, the result will be true.
-
-@item security
-Menu option indicating the encryption and authentication settings
-for communication with the LDAP server. These features might be subject
-to machine and server capabilites.
-@smallexample
- none
- ssl
- sasl
-@end smallexample
-@end table
-
diff --git a/docs/reference/functions/regline_example.texinfo b/docs/reference/functions/regline_example.texinfo
deleted file mode 100644
index 4ee3b80e77..0000000000
--- a/docs/reference/functions/regline_example.texinfo
+++ /dev/null
@@ -1,28 +0,0 @@
-
-@verbatim
-
-bundle agent testbundle
-
-{
-files:
-
- "/tmp/testfile" edit_line => test;
-}
-
-########################################################
-
-bundle edit_line test
-{
-classes:
-
- "ok" expression => regline(".*XYZ.*","$(edit.filename)");
-
-reports:
-
- ok::
-
- "File $(edit.filename) has a line with \"XYZ\" in it";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/regline_notes.texinfo b/docs/reference/functions/regline_notes.texinfo
deleted file mode 100644
index 70d04bfbb3..0000000000
--- a/docs/reference/functions/regline_notes.texinfo
+++ /dev/null
@@ -1,32 +0,0 @@
-
-Note that the regular expression must match an entire line of the
-file in order to give a true result. This function is useful for
-@code{edit_line} applications, where one might want to set a class for
-detecting the presence of a string which does not exactly match
-one being inserted. e.g.
-
-@verbatim
-
-bundle edit_line upgrade_cfexecd
- {
- classes:
-
- # Check there is not already a crontab line, not identical to
- # the one proposed below...
-
- "exec_fix" not => regline(".*cf-execd.*","$(edit.filename)");
-
- insert_lines:
-
- exec_fix::
-
- "0,5,10,15,20,25,30,35,40,45,50,55 * * * * /var/cfengine/bin/cf-execd -F";
-
- reports:
-
- exec_fix::
-
- "Added a 5 minute schedule to crontabs";
- }
-
-@end verbatim
diff --git a/docs/reference/functions/reglist_example.texinfo b/docs/reference/functions/reglist_example.texinfo
deleted file mode 100644
index 1fc53fe180..0000000000
--- a/docs/reference/functions/reglist_example.texinfo
+++ /dev/null
@@ -1,16 +0,0 @@
-
-@verbatim
-
-vars:
-
- "nameservers" slist => {
- "128.39.89.10",
- "128.39.74.16",
- "192.168.1.103"
- };
-classes:
-
- "am_name_server" expression => reglist("@(nameservers)",escape("$(sys.ipv4[eth0])"));
-
-@end verbatim
-
diff --git a/docs/reference/functions/reglist_notes.texinfo b/docs/reference/functions/reglist_notes.texinfo
deleted file mode 100644
index c94994d928..0000000000
--- a/docs/reference/functions/reglist_notes.texinfo
+++ /dev/null
@@ -1,18 +0,0 @@
-
-Matches a list of test strings to a regular expression. In the
-example above, the IP address in @code{$(sys.ipv4[eth0])} must be
-@code{escape}d, because if not, the dot (@samp{.}) characters in the
-IP address would be interpreted as regular expression "match any"
-characters.
-
-@noindent @b{ARGUMENTS}:
-
-@table @samp
-
-@item list
-The list of strings to test with the regular expression.
-@item regex
-The scalar regular expression string. The regular expression must
-match the entire string (that is, it is anchored, @pxref{Anchored
-vs. unanchored regular expressions}).
-@end table
diff --git a/docs/reference/functions/remoteclassesmatching_example.texinfo b/docs/reference/functions/remoteclassesmatching_example.texinfo
deleted file mode 100644
index 7f40632e59..0000000000
--- a/docs/reference/functions/remoteclassesmatching_example.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@verbatim
-
- "succeeded" expression => remoteclassesmatching("regex","server","yes","myprefix");
-
-@end verbatim
diff --git a/docs/reference/functions/remoteclassesmatching_notes.texinfo b/docs/reference/functions/remoteclassesmatching_notes.texinfo
deleted file mode 100644
index 6bb360a070..0000000000
--- a/docs/reference/functions/remoteclassesmatching_notes.texinfo
+++ /dev/null
@@ -1,30 +0,0 @@
-This function is only available in Enterprise versions of CFEngine (Nova, Enterprise, etc).
-
-This function contacts a remote @code{cf-serverd} and requests access to defined
-@i{persistent classes} on that system. These must be granted access to by making an
-@code{access} promise with @code{resource_type} set to @code{context}.
-
-The return value is true (sets the class) if communication with the server was
-successful and classes are populated in the current bundle with a prefix of your choosing.
-The arguments are:
-
-@table @i
-@item Regular expression
-This should match a list of @i{persistent} classes of be returned from the server,
-if the server is willing, i.e. has granted access to them.
-
-@item Server
-The name or IP address of the remote server.
-
-@item Encryption
-Boolean value, whether or not to encrypt communication.
-
-@item Prefix
-A string to be added to the returned classes, e.g. if the server defines
-a persistent class @samp{alpha}, then this would generate a private class in the
-current bundle called @samp{myprefix_alpha}.
-@end table
-
-Note that this function assumes that you have already performed a successful key exchange between
-systems, (e.g. using either a remote copy or @code{cf-runagent} connection). It contains no mechanism
-for trust establishment and will fail if there is no trust relationship pre-established.
diff --git a/docs/reference/functions/remotescalar_example.texinfo b/docs/reference/functions/remotescalar_example.texinfo
deleted file mode 100644
index 521961ef89..0000000000
--- a/docs/reference/functions/remotescalar_example.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-@verbatim
-
-vars:
-
- "remote" string => remotescalar("test_scalar","127.0.0.1","yes");
-
-@end verbatim
diff --git a/docs/reference/functions/remotescalar_notes.texinfo b/docs/reference/functions/remotescalar_notes.texinfo
deleted file mode 100644
index 7f29bfd21d..0000000000
--- a/docs/reference/functions/remotescalar_notes.texinfo
+++ /dev/null
@@ -1,63 +0,0 @@
-The remote system's cf-serverd must accept the query for the requested variable from
-the host that is requesting it.
-An example of this configuration follows.
-
-This function asks for an identifier; it is up to the server to interpret
-what this means and to return a value of its choosing. If the identifier matches
-a persistent scalar variable (such as is used to count distributed processes in CFEngine
-Enterprise) then this will be returned preferentially. If no such variable is found,
-then the server will look for a literal string in a server bundle with a handle that
-matches the requested object.
-
-@verbatim
-bundle server access
-{
-access:
- "value of my test_scalar, can expand variables here - $(sys.host)"
- handle => "test_scalar",
- comment => "Grant access to contents of test_scalar VAR",
- resource_type => "literal",
- admit => { "127.0.0.1" };
-}
-@end verbatim
-
-CFEngine caches the value of this variable, so that, if the network is
-unavailable, the last known value will be used. Hence use of this function
-is fault tolerant. Care should be taken in attempting to access remote variables
-that are not available, as the repeated connections needed to resolve the
-absence of a value can lead to undesirable behaviour. As a general rule,
-users are recommended to refrain from relying on the availability of network resources.
-
-@cartouche
-@example
-
-(string) remotescalar(@var{resource handle},@var{host/IP address},@var{encrypt});
-
-@end example
-@end cartouche
-
-This function downloads a string from a remote server, using the promise handle
-as a variable identifier. Availability: Enterprise editions of CFEngine only.
-
-@noindent @b{ARGUMENTS}:
-
-@table @samp
-@item resource handle
-The name of the promise on the server side
-@item host or IP address
-The location of the server on which the resource resides.
-@item encrypt
-Whether to encrypt the connection to the server.
-@smallexample
- true
- yes
- false
- no
-@end smallexample
-@end table
-
-Note that this function assumes that you have already performed a
-successful key exchange between systems, (e.g. using either a remote
-copy or @code{cf-runagent} connection). It contains no mechanism for
-trust establishment and will fail if there is no trust relationship
-pre-established.
diff --git a/docs/reference/functions/returnszero_example.texinfo b/docs/reference/functions/returnszero_example.texinfo
deleted file mode 100644
index 8593f9d11c..0000000000
--- a/docs/reference/functions/returnszero_example.texinfo
+++ /dev/null
@@ -1,28 +0,0 @@
-
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-classes:
-
- "my_result" expression => returnszero("/usr/local/bin/mycommand","noshell");
-
-reports:
-
- !my_result::
-
- "Command failed";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/returnszero_notes.texinfo b/docs/reference/functions/returnszero_notes.texinfo
deleted file mode 100644
index 611fc90d4d..0000000000
--- a/docs/reference/functions/returnszero_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-This is the complement of @code{execresult}, but it returns a class
-result rather than the output of the command.
diff --git a/docs/reference/functions/rrange_example.texinfo b/docs/reference/functions/rrange_example.texinfo
deleted file mode 100644
index 46ace02773..0000000000
--- a/docs/reference/functions/rrange_example.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@verbatim
-
-?
-
-@end verbatim
diff --git a/docs/reference/functions/rrange_notes.texinfo b/docs/reference/functions/rrange_notes.texinfo
deleted file mode 100644
index 05438189e1..0000000000
--- a/docs/reference/functions/rrange_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-This is not yet used.
diff --git a/docs/reference/functions/selectservers_example.texinfo b/docs/reference/functions/selectservers_example.texinfo
deleted file mode 100644
index 9a735ab370..0000000000
--- a/docs/reference/functions/selectservers_example.texinfo
+++ /dev/null
@@ -1,49 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "test" };
-}
-
-###########################################################
-
-bundle agent test
-
-{
-vars:
-
- "hosts" slist => { "slogans.iu.hio.no", "eternity.iu.hio.no", "nexus.iu.hio.no" };
- "fhosts" slist => { "www.cfengine.com", "www.cfengine.org" };
-
- "up_servers" int => selectservers("@(hosts)","80","","","100","alive_servers");
- "has_favicon" int =>
- selectservers(
- "@(hosts)", "80",
- "GET /favicon.ico HTTP/1.0$(const.n)Host: www.cfengine.com$(const.n)$(const.n)",
- "(?s).*OK.*",
- "200", "favicon_servers");
-
-classes:
-
- "someone_alive" expression => isgreaterthan("$(up_servers)","0");
-
- "has_favicon" expression => isgreaterthan("$(has_favicon)","0");
-
-reports:
-
- cfengine_3::
- "Number of active servers $(up_servers)";
-
- someone_alive::
- "First server $(alive_servers[0]) fails over to $(alive_servers[1])";
-
- has_favicon::
- "At least $(favicon_servers[0]) has a favicon.ico";
-
-}
-
-
-@end verbatim
-
diff --git a/docs/reference/functions/selectservers_notes.texinfo b/docs/reference/functions/selectservers_notes.texinfo
deleted file mode 100644
index b9f741c907..0000000000
--- a/docs/reference/functions/selectservers_notes.texinfo
+++ /dev/null
@@ -1,36 +0,0 @@
-
-
-This function selects all the TCP ports that are active and
-functioning from an ordered list and builds an array of their names.
-This allows us to select a current list of failover alternatives
-that are pretested.
-
-@table @samp
-@item hostlist
-A list of host names or IP addresses to attempt to connect to.
-
-@item port
-The port number for the service.
-
-@item sendstr
-An optional string to send to the server to elicit a response. If
-@code{sendstr} is empty, then no query is sent to the server.
-
-@item regex_on_reply
-If a string is sent, this regex must match the entire resulting
-reply (that is, the regex is anchored,
-@pxref{Anchored vs. unanchored regular expressions}). If there
-is a multi-line response from the server, special care must be taken
-to ensure that you match the newlines, too (note the use of @code{(?s)}
-in the example above, which allows @samp{.} to also match newlines
-in the multi-line HTTP response). If @code{regex_on_reply} is
-empty, then no reply-checking is performed (and any server reply
-is deemed to be satisfactory).
-
-@item maxbytesread_reply
-The maximum number of bytes to read as the server's reply.
-
-@item array_name
-The name of the array to build containing the names of hosts
-that pass the above tests. The array is ordered @code{array_name[0],..} etc.
-@end table
diff --git a/docs/reference/functions/some_example.texinfo b/docs/reference/functions/some_example.texinfo
deleted file mode 100644
index dc242100af..0000000000
--- a/docs/reference/functions/some_example.texinfo
+++ /dev/null
@@ -1,32 +0,0 @@
-
-@verbatim
-
-bundle agent test
-
-{
- classes:
- "some1" expression => some("long string", "test");
- "some2" expression => some("none", "test");
-
- vars:
- "test" slist => {
- 1,2,3,
- "one", "two", "three",
- "long string",
- "four", "fix", "six",
- "one", "two", "three",
- };
-
- reports:
- "The test list is $(test)";
- some1::
- "some() test 1 passed";
- !some1::
- "some() test 1 failed";
- some2::
- "some() test 2 failed";
- !some2::
- "some() test 2 passed";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/some_notes.texinfo b/docs/reference/functions/some_notes.texinfo
deleted file mode 100644
index e625cca05e..0000000000
--- a/docs/reference/functions/some_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-arg1 is a regular expression tested against every element of the list
-arg2. If at least one matches, this function returns true.
diff --git a/docs/reference/functions/splayclass_example.texinfo b/docs/reference/functions/splayclass_example.texinfo
deleted file mode 100644
index dc6c39e920..0000000000
--- a/docs/reference/functions/splayclass_example.texinfo
+++ /dev/null
@@ -1,28 +0,0 @@
-
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-classes:
-
- "my_result" expression => splayclass("$(sys.host)$(sys.ipv4)","daily");
-
-reports:
-
- my_result::
-
- "Load balanced class activated";
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/splayclass_notes.texinfo b/docs/reference/functions/splayclass_notes.texinfo
deleted file mode 100644
index e89ee848fe..0000000000
--- a/docs/reference/functions/splayclass_notes.texinfo
+++ /dev/null
@@ -1,37 +0,0 @@
-
-
-The lvalue class evaluates to true if the system clock lies within a scheduled
-time-interval that maps to a hash of the first argument (which may be any
-arbitrary string). Different strings will hash to different time intervals,
-and thus one can map different tasks to time-intervals.
-
-This function may be used to distribute a task, typically in multiple hosts,
-in time over a day or
-an hourly period, depending on the policy in the second argument (which must
-be one of @code{"daily"} or @code{"hourly"}).
-This is useful for copying resources to multiple hosts from a single server,
-(e.g. large software updates), when simultaneous scheduling would lead to a
-bottleneck and/or server overload.
-
-The function is similar to the @code{splaytime} feature in @code{cf-execd},
-except
-that it allows you to base the decision on any string-criterion on a
-given host. The entropy (or string-variation) in the first argument
-determines how effectively CFEngine will be able to distribute tasks.
-CFEngine instances with the same first argument will yield a true
-result at the same time (and different first argument will yield a true
-result at a different time). Thus tasks could be scheduled according to
-group names for predictability, or according to IP addresses for
-distribution across the policy interval.
-
-The times at which the splayclass will be defined depends on the second
-argument. If the first argument is @code{"hourly"} then the class will be
-defined for a 5-minute interval every hour (and if the first argument is
-@code{"daily"}, then the class will be defined for one 5-minute interval
-every day. This means that @code{splayclass} assumes that you are running
-CFEngine with the default schedule of "every 5 minutes". If you change the
-executor @code{schedule} control variable, you may prevent the splayclass
-from ever being defined (that is, if the hashed 5-minute interval that is
-selected by the splayclass is a time when you have told CFEngine @i{not} to
-run).
-
diff --git a/docs/reference/functions/splitstring_example.texinfo b/docs/reference/functions/splitstring_example.texinfo
deleted file mode 100644
index fe152fcdce..0000000000
--- a/docs/reference/functions/splitstring_example.texinfo
+++ /dev/null
@@ -1,23 +0,0 @@
-
-@verbatim
-
-bundle agent test
-
-{
-vars:
-
- "split1" slist => splitstring("one:two:three",":","10");
- "split2" slist => splitstring("one:two:three",":","1");
- "split3" slist => splitstring("alpha:xyz:beta","xyz","10");
-
-reports:
-
- linux::
-
- "split1: $(split1)"; # will list "one", "two", and "three"
- "split2: $(split2)"; # will list "one" and "two:three"
- "split3: $(split3)"; # will list "alpha:" and ":beta"
-
-}
-
-@end verbatim
diff --git a/docs/reference/functions/splitstring_notes.texinfo b/docs/reference/functions/splitstring_notes.texinfo
deleted file mode 100644
index 9720b31d64..0000000000
--- a/docs/reference/functions/splitstring_notes.texinfo
+++ /dev/null
@@ -1,20 +0,0 @@
-
-@noindent Returns a list of strings from a string.
-
-@noindent @b{ARGUMENTS}:
-
-@table @samp
-@item string
-The string to be split.
-
-@item regex
-A regex pattern which is used to parse the field separator(s)
-to split up the file into items. The regex is unanchored,
-@pxref{Anchored vs. unanchored regular expressions}).
-
-@item maxent
-The maximum number of splits to perform.
-@end table
-
-If the maximum number of splits is insufficient to accomodate all entries, the
-final entry in the slist that is generated will contain the rest of the unsplit string.
diff --git a/docs/reference/functions/strcmp_example.texinfo b/docs/reference/functions/strcmp_example.texinfo
deleted file mode 100644
index 9506787a20..0000000000
--- a/docs/reference/functions/strcmp_example.texinfo
+++ /dev/null
@@ -1,30 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-classes:
-
- "same" expression => strcmp("test","test");
-
-reports:
-
- same::
-
- "Strings are equal";
-
- !same::
-
- "Strings are not equal";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/strcmp_notes.texinfo b/docs/reference/functions/strcmp_notes.texinfo
deleted file mode 100644
index e69de29bb2..0000000000
diff --git a/docs/reference/functions/strftime_example.texinfo b/docs/reference/functions/strftime_example.texinfo
deleted file mode 100644
index c638fd106b..0000000000
--- a/docs/reference/functions/strftime_example.texinfo
+++ /dev/null
@@ -1,28 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
- vars:
- "time" int => now();
- "now" string => strftime("localtime", "%F %T", now());
- "then" string => strftime("localtime", "%F %T", 0);
-
- "gmt_now" string => strftime("gmtime", "%F %T", now());
- "gmt_then" string => strftime("gmtime", "%F %T", 0);
-
- reports:
- "time $(time); now $(now); then $(then)";
- "time $(time); GMT now $(now); GMT then $(then)";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/strftime_notes.texinfo b/docs/reference/functions/strftime_notes.texinfo
deleted file mode 100644
index 3b6808d1f3..0000000000
--- a/docs/reference/functions/strftime_notes.texinfo
+++ /dev/null
@@ -1,247 +0,0 @@
-
-Note that @code{strftime} is a standard C function and you should
-consult its reference to be sure of the specifiers it allows. The below
-is from the documentation of the standard @code{strftime} implementation
-in the glibc manual at
-@uref{http://www.gnu.org/software/libc/manual/html_node/Formatting-Calendar-Time.html#Formatting-Calendar-Time}.
-
-This function takes a @var{mode}, a @var{template} and a @var{time}.
-
-The @var{mode} is either @code{gmtime} (to get GMT times and dates) or
-@code{localtime} (to get times and dates according to the local
-timezone).
-
-The conversion specifications that can appear in the format template
-@var{template} are specialized for printing components of the date and
-time according to the system locale. The @var{time} is simply an
-integer (Unix epoch time); you can get the current time with the
-@code{now()} function.
-
-Ordinary characters appearing in the @var{template} are copied to the
-output. Conversion specifiers are introduced by a @samp{%} character
-and end with a format specifier taken from the following list. The
-whole @samp{%} sequence is replaced in the output string as follows:
-
-@table @code
-@item %a
-The abbreviated weekday name according to the current locale.
-
-@item %A
-The full weekday name according to the current locale.
-
-@item %b
-The abbreviated month name according to the current locale.
-
-@item %B
-The full month name according to the current locale.
-
-Using @code{%B} together with @code{%d} produces grammatically
-incorrect results for some locales.
-
-@item %c
-The preferred calendar time representation for the current locale.
-
-@item %C
-The century of the year. This is equivalent to the greatest integer not
-greater than the year divided by 100.
-
-This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
-
-@item %d
-The day of the month as a decimal number (range @code{01} through @code{31}).
-
-@item %D
-The date using the format @code{%m/%d/%y}.
-
-This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
-
-@item %e
-The day of the month like with @code{%d}, but padded with blank (range
-@code{ 1} through @code{31}).
-
-This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
-
-@item %F
-The date using the format @code{%Y-%m-%d}. This is the form specified
-in the @w{ISO 8601} standard and is the preferred form for all uses.
-
-This format was first standardized by @w{ISO C99} and by POSIX.1-2001.
-
-@item %g
-The year corresponding to the ISO week number, but without the century
-(range @code{00} through @code{99}). This has the same format and value
-as @code{%y}, except that if the ISO week number (see @code{%V}) belongs
-to the previous or next year, that year is used instead.
-
-This format was first standardized by @w{ISO C99} and by POSIX.1-2001.
-
-@item %G
-The year corresponding to the ISO week number. This has the same format
-and value as @code{%Y}, except that if the ISO week number (see
-@code{%V}) belongs to the previous or next year, that year is used
-instead.
-
-This format was first standardized by @w{ISO C99} and by POSIX.1-2001
-but was previously available as a GNU extension.
-
-@item %h
-The abbreviated month name according to the current locale. The action
-is the same as for @code{%b}.
-
-This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
-
-@item %H
-The hour as a decimal number, using a 24-hour clock (range @code{00} through
-@code{23}).
-
-@item %I
-The hour as a decimal number, using a 12-hour clock (range @code{01} through
-@code{12}).
-
-@item %j
-The day of the year as a decimal number (range @code{001} through @code{366}).
-
-@item %k
-The hour as a decimal number, using a 24-hour clock like @code{%H}, but
-padded with blank (range @code{ 0} through @code{23}).
-
-This format is a GNU extension.
-
-@item %l
-The hour as a decimal number, using a 12-hour clock like @code{%I}, but
-padded with blank (range @code{ 1} through @code{12}).
-
-This format is a GNU extension.
-
-@item %m
-The month as a decimal number (range @code{01} through @code{12}).
-
-@item %M
-The minute as a decimal number (range @code{00} through @code{59}).
-
-@item %n
-A single @samp{\n} (newline) character.
-
-This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
-
-@item %p
-Either @samp{AM} or @samp{PM}, according to the given time value; or the
-corresponding strings for the current locale. Noon is treated as
-@samp{PM} and midnight as @samp{AM}. In most locales
-@samp{AM}/@samp{PM} format is not supported, in such cases @code{"%p"}
-yields an empty string.
-
-@ignore
-We currently have a problem with makeinfo. Write @samp{AM} and @samp{am}
-both results in `am'. I.e., the difference in case is not visible anymore.
-@end ignore
-@item %P
-Either @samp{am} or @samp{pm}, according to the given time value; or the
-corresponding strings for the current locale, printed in lowercase
-characters. Noon is treated as @samp{pm} and midnight as @samp{am}. In
-most locales @samp{AM}/@samp{PM} format is not supported, in such cases
-@code{"%P"} yields an empty string.
-
-This format is a GNU extension.
-
-@item %r
-The complete calendar time using the AM/PM format of the current locale.
-
-This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
-In the POSIX locale, this format is equivalent to @code{%I:%M:%S %p}.
-
-@item %R
-The hour and minute in decimal numbers using the format @code{%H:%M}.
-
-This format was first standardized by @w{ISO C99} and by POSIX.1-2001
-but was previously available as a GNU extension.
-
-@item %s
-The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC.
-Leap seconds are not counted unless leap second support is available.
-
-This format is a GNU extension.
-
-@item %S
-The seconds as a decimal number (range @code{00} through @code{60}).
-
-@item %t
-A single @samp{\t} (tabulator) character.
-
-This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
-
-@item %T
-The time of day using decimal numbers using the format @code{%H:%M:%S}.
-
-This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
-
-@item %u
-The day of the week as a decimal number (range @code{1} through
-@code{7}), Monday being @code{1}.
-
-This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
-
-@item %U
-The week number of the current year as a decimal number (range @code{00}
-through @code{53}), starting with the first Sunday as the first day of
-the first week. Days preceding the first Sunday in the year are
-considered to be in week @code{00}.
-
-@item %V
-The @w{ISO 8601:1988} week number as a decimal number (range @code{01}
-through @code{53}). ISO weeks start with Monday and end with Sunday.
-Week @code{01} of a year is the first week which has the majority of its
-days in that year; this is equivalent to the week containing the year's
-first Thursday, and it is also equivalent to the week containing January
-4. Week @code{01} of a year can contain days from the previous year.
-The week before week @code{01} of a year is the last week (@code{52} or
-@code{53}) of the previous year even if it contains days from the new
-year.
-
-This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
-
-@item %w
-The day of the week as a decimal number (range @code{0} through
-@code{6}), Sunday being @code{0}.
-
-@item %W
-The week number of the current year as a decimal number (range @code{00}
-through @code{53}), starting with the first Monday as the first day of
-the first week. All days preceding the first Monday in the year are
-considered to be in week @code{00}.
-
-@item %x
-The preferred date representation for the current locale.
-
-@item %X
-The preferred time of day representation for the current locale.
-
-@item %y
-The year without a century as a decimal number (range @code{00} through
-@code{99}). This is equivalent to the year modulo 100.
-
-@item %Y
-The year as a decimal number, using the Gregorian calendar. Years
-before the year @code{1} are numbered @code{0}, @code{-1}, and so on.
-
-@item %z
-@w{RFC 822}/@w{ISO 8601:1988} style numeric time zone (e.g.,
-@code{-0600} or @code{+0100}), or nothing if no time zone is
-determinable.
-
-This format was first standardized by @w{ISO C99} and by POSIX.1-2001
-but was previously available as a GNU extension.
-
-In the POSIX locale, a full @w{RFC 822} timestamp is generated by the format
-@w{@samp{"%a, %d %b %Y %H:%M:%S %z"}} (or the equivalent
-@w{@samp{"%a, %d %b %Y %T %z"}}).
-
-@item %Z
-The time zone abbreviation (empty if the time zone can't be determined).
-
-@item %%
-A literal @samp{%} character.
-@end table
-
-According to POSIX.1 every call to @code{strftime} checks the contents
-of the environment variable @code{TZ} before any output is produced.
diff --git a/docs/reference/functions/sublist_example.texinfo b/docs/reference/functions/sublist_example.texinfo
deleted file mode 100644
index 852ab26333..0000000000
--- a/docs/reference/functions/sublist_example.texinfo
+++ /dev/null
@@ -1,37 +0,0 @@
-
-@verbatim
-
-bundle agent test
-
-{
- vars:
- "test" slist => {
- 1,2,3,
- "one", "two", "three",
- "long string",
- "four", "fix", "six",
- };
-
- "test_head9999" slist => sublist("test", "head", 9999);
- "test_head1" slist => sublist("test", "head", 1);
- "test_head0" slist => sublist("test", "head", 0);
-
- "test_tail9999" slist => sublist("test", "tail", 9999);
- "test_tail10" slist => sublist("test", "tail", 10);
- "test_tail2" slist => sublist("test", "tail", 2);
- "test_tail1" slist => sublist("test", "tail", 1);
- "test_tail0" slist => sublist("test", "tail", 0);
-
- reports:
- "The test list is $(test)";
- "This line should not appear: $(test_head0)";
- "The head(1) of the test list is $(test_head1)";
- "The head(9999) of the test list is $(test_head9999)";
- "This line should not appear: $(test_tail0)";
- "The tail(1) of the test list is $(test_tail1)";
- "The tail(10) of the test list is $(test_tail10)";
- "The tail(2) of the test list is $(test_tail2)";
- "The tail(9999) of the test list is $(test_tail9999)";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/sublist_notes.texinfo b/docs/reference/functions/sublist_notes.texinfo
deleted file mode 100644
index 2d5819b1c4..0000000000
--- a/docs/reference/functions/sublist_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-Extracts a sublist of elements from a list variable specified in arg1.
-arg2 can be @code{head} to specify extraction from the head of the list
-or @code{tail} to extract from the tail.
-
-arg3 specifies how many items to extract.
diff --git a/docs/reference/functions/sum_example.texinfo b/docs/reference/functions/sum_example.texinfo
deleted file mode 100644
index 0ca8759f95..0000000000
--- a/docs/reference/functions/sum_example.texinfo
+++ /dev/null
@@ -1,31 +0,0 @@
-
-@verbatim
-
-body common control
-{
-bundlesequence => { "test" };
-}
-
-##############################
-
-bundle agent test
-{
-vars:
- "adds_to_six" ilist => { "1", "2", "3" };
- "six" real => sum("adds_to_six");
- "adds_to_zero" rlist => { "1.0", "2", "-3e0" };
- "zero" real => sum("adds_to_zero");
-
-reports:
- cfengine_3::
- "six is $(six), zero is $(zero)";
-}
-@end verbatim
-
-Because @code{$(six)} and @code{$(zero)} are both real numbers, the report
-that is generated will be:
-
-@verbatim
-six is 6.000000, zero is 0.000000
-@end verbatim
-
diff --git a/docs/reference/functions/sum_notes.texinfo b/docs/reference/functions/sum_notes.texinfo
deleted file mode 100644
index 0fb07da275..0000000000
--- a/docs/reference/functions/sum_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-Of course, you could easily combine @code{sum} with @code{readstringarray} or
-@code{readreallist}, etc. to collect summary information from a source
-external to CFEngine.
-
-@b{History}: Was introduced in version 3.1.0b1,Nova 2.0.0b1 (2010)
-
-This function might be used for simple ring computation.
diff --git a/docs/reference/functions/translatepath_example.texinfo b/docs/reference/functions/translatepath_example.texinfo
deleted file mode 100644
index c315549909..0000000000
--- a/docs/reference/functions/translatepath_example.texinfo
+++ /dev/null
@@ -1,25 +0,0 @@
-
-@verbatim
-
-body common control
-{
-bundlesequence => { "test" };
-}
-
-##############################
-
-bundle agent test
-{
-vars:
- "inputs_dir" string => translatepath("$(sys.workdir)/inputs");
-
-reports:
-
- windows::
- "The path has backslashes: $(inputs_dir)";
-
- !windows::
- "The path has slashes: $(inputs_dir)";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/translatepath_notes.texinfo b/docs/reference/functions/translatepath_notes.texinfo
deleted file mode 100644
index 4f589ecbad..0000000000
--- a/docs/reference/functions/translatepath_notes.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-Takes a string argument with slashes as path separators and translate
-these to the native format for path separators on the host. For
-example translatepath("a/b/c") would yield "a/b/c" on Unix platforms,
-but "a\b\c" on Windows.
-
-Be careful when using this function in combination with regular
-expressions, since backslash is also used as escape character in
-regex's. For example, in the regex @samp{dir/.abc}, the dot represents the
-regular expression "any character", while in the regex @samp{dir\.abc}, the
-backslash-dot represents a literal dot character.
diff --git a/docs/reference/functions/unique_example.texinfo b/docs/reference/functions/unique_example.texinfo
deleted file mode 100644
index 6e725987e7..0000000000
--- a/docs/reference/functions/unique_example.texinfo
+++ /dev/null
@@ -1,25 +0,0 @@
-
-@verbatim
-
-bundle agent test
-
-{
- vars:
- "test" slist => {
- 1,2,3,
- "one", "two", "three",
- "long string",
- "four", "fix", "six",
- "one", "two", "three",
- };
-
- "test_str" string => join(",", "test");
- "test_unique" slist => unique("test");
- "unique_str" string => join(",", "test_unique");
-
- reports:
- "The test list is $(test_str)";
- "The unique elements of the test list: $(unique_str)";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/unique_notes.texinfo b/docs/reference/functions/unique_notes.texinfo
deleted file mode 100644
index aa86175d9d..0000000000
--- a/docs/reference/functions/unique_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Extracts a sublist of unique elements (determined by a string
-comparison) from a list variable specified in arg1. Similar to the standard Unix uniq utility.
diff --git a/docs/reference/functions/usemodule_example.texinfo b/docs/reference/functions/usemodule_example.texinfo
deleted file mode 100644
index 2fba70ffe7..0000000000
--- a/docs/reference/functions/usemodule_example.texinfo
+++ /dev/null
@@ -1,30 +0,0 @@
-
-
-@verbatim
-
-body common control
- {
- any::
-
- bundlesequence => {
- test
- };
- }
-
-###################################################################
-
-bundle agent test
-
-{
-classes:
-
- # returns $(user)
-
- "done" expression => usemodule("getusers","");
-
-commands:
-
- "/bin/echo" args => "test $(user)";
-}
-
-@end verbatim
diff --git a/docs/reference/functions/usemodule_notes.texinfo b/docs/reference/functions/usemodule_notes.texinfo
deleted file mode 100644
index c95390624e..0000000000
--- a/docs/reference/functions/usemodule_notes.texinfo
+++ /dev/null
@@ -1,16 +0,0 @@
-
-Modules must reside in @file{WORKDIR/modules} but no longer require
-a special naming convention.
-
-@noindent @b{ARGUMENTS}:
-
-@table @samp
-
-@item Module name
-The name of the module without its leading path, since it is assuemed
-to be in the registered modules directory.
-
-@item Argument string
-Any command link arguments to pass to the module.
-
-@end table
diff --git a/docs/reference/functions/userexists_example.texinfo b/docs/reference/functions/userexists_example.texinfo
deleted file mode 100644
index 8351a620cc..0000000000
--- a/docs/reference/functions/userexists_example.texinfo
+++ /dev/null
@@ -1,32 +0,0 @@
-
-@verbatim
-
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-classes:
-
- "ok" expression => userexists("root");
-
-reports:
-
- ok::
-
- "Root exists";
-
- !ok::
-
- "Root does not exist";
-}
-
-
-@end verbatim
diff --git a/docs/reference/functions/userexists_notes.texinfo b/docs/reference/functions/userexists_notes.texinfo
deleted file mode 100644
index 6de13379a0..0000000000
--- a/docs/reference/functions/userexists_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Checks whether the user is in the password database for the current host.
-The argument must be a user name or user id.
diff --git a/docs/reference/functions_intro.texinfo b/docs/reference/functions_intro.texinfo
deleted file mode 100644
index 9899603574..0000000000
--- a/docs/reference/functions_intro.texinfo
+++ /dev/null
@@ -1,288 +0,0 @@
-There is a large number of functions built into CFEngine, and finding the
-right one to use can be a daunting task. The following tables are designed
-to make it easier for you to find the function you need, based on the value
-or type that the function returns or processes as inputs.
-
-
-@subsection Functions listed by return value
-
-@unnumberedsubsubsec Functions which return class
-@multitable @columnfractions .2 .2 .2 .2 .2
-@item @ref{Function accessedbefore, ,accessedbefore}
-@tab @ref{Function and, ,and}
-@tab @ref{Function changedbefore, ,changedbefore}
-@tab @ref{Function classify, ,classify}
-@tab @ref{Function classmatch, ,classmatch}
-@item @ref{Function concat, ,concat}
-@tab @ref{Function fileexists, ,fileexists}
-@tab @ref{Function filesexist, ,filesexist}
-@tab @ref{Function groupexists, ,groupexists}
-@tab @ref{Function hashmatch, ,hashmatch}
-@item @ref{Function hostinnetgroup, ,hostinnetgroup}
-@tab @ref{Function hostrange, ,hostrange}
-@tab @ref{Function iprange, ,iprange}
-@tab @ref{Function isdir, ,isdir}
-@tab @ref{Function isexecutable, ,isexecutable}
-@item @ref{Function isgreaterthan, ,isgreaterthan}
-@tab @ref{Function islessthan, ,islessthan}
-@tab @ref{Function islink, ,islink}
-@tab @ref{Function isnewerthan, ,isnewerthan}
-@tab @ref{Function isplain, ,isplain}
-@item @ref{Function isvariable, ,isvariable}
-@tab @ref{Function ldaparray, ,ldaparray}
-@tab @ref{Function or, ,or}
-@tab @ref{Function not, ,not}
-@tab @ref{Function regarray, ,regarray}
-@item @ref{Function regcmp, ,regcmp}
-@tab @ref{Function regextract, ,regextract}
-@tab @ref{Function regldap, ,regldap}
-@tab @ref{Function regline, ,regline}
-@tab @ref{Function reglist, ,reglist}
-@item @ref{Function remoteclassesmatching, ,remoteclassesmatching}
-@tab @ref{Function returnszero, ,returnszero}
-@tab @ref{Function splayclass, ,splayclass}
-@tab @ref{Function strcmp, ,strcmp}
-@tab @ref{Function usemodule, ,usemodule}
-@item @ref{Function userexists, ,userexists}
-@end multitable
-
-@unnumberedsubsubsec Functions which return (i,r,s)list
-@multitable @columnfractions .2 .2 .2 .2 .2
-@item @ref{Function getindices, ,getindices}
-@tab @ref{Function getusers, ,getusers}
-@tab @ref{Function grep, ,grep}
-@tab @ref{Function ldaplist, ,ldaplist}
-@tab @ref{Function maplist, ,maplist}
-@item @ref{Function peerleaders, ,peerleaders}
-@tab @ref{Function peers, ,peers}
-@tab @ref{Function readintlist, ,readintlist}
-@tab @ref{Function readreallist, ,readreallist}
-@tab @ref{Function readstringlist, ,readstringlist}
-@item @ref{Function splitstring, ,splitstring}
-@end multitable
-
-@unnumberedsubsubsec Functions which return int
-@multitable @columnfractions .2 .2 .2 .2 .2
-@item @ref{Function accumulated, ,accumulated}
-@tab @ref{Function ago, ,ago}
-@tab @ref{Function countlinesmatching, ,countlinesmatching}
-@tab @ref{Function diskfree, ,diskfree}
-@tab @ref{Function getfields, ,getfields}
-@item @ref{Function getgid, ,getgid}
-@tab @ref{Function getuid, ,getuid}
-@tab @ref{Function now, ,now}
-@tab @ref{Function on, ,on}
-@tab @ref{Function randomint, ,randomint}
-@item @ref{Function readintarray, ,readintarray}
-@tab @ref{Function readrealarray, ,readrealarray}
-@tab @ref{Function readstringarray, ,readstringarray}
-@tab @ref{Function readstringarrayidx, ,readstringarrayidx}
-@tab @ref{Function selectservers, ,selectservers}
-@end multitable
-
-@unnumberedsubsubsec Functions which return (i,r)range
-@multitable @columnfractions .2 .2 .2 .2 .2
-@item @ref{Function irange, ,irange}
-@tab @ref{Function rrange, ,rrange}
-@end multitable
-
-@unnumberedsubsubsec Functions which return real
-@multitable @columnfractions .2 .2 .2 .2 .2
-@item @ref{Function product, ,product}
-@tab @ref{Function sum, ,sum}
-@end multitable
-
-@unnumberedsubsubsec Functions which return string
-@multitable @columnfractions .2 .2 .2 .2 .2
-@item @ref{Function canonify, ,canonify}
-@tab @ref{Function escape, ,escape}
-@tab @ref{Function execresult, ,execresult}
-@tab @ref{Function getenv, ,getenv}
-@tab @ref{Function hash, ,hash}
-@item @ref{Function host2ip, ,host2ip}
-@tab @ref{Function hostsseen, ,hostsseen}
-@tab @ref{Function join, ,join}
-@tab @ref{Function lastnode, ,lastnode}
-@tab @ref{Function ldapvalue, ,ldapvalue}
-@item @ref{Function peerleader, ,peerleader}
-@tab @ref{Function readfile, ,readfile}
-@tab @ref{Function readtcp, ,readtcp}
-@tab @ref{Function registryvalue, ,registryvalue}
-@tab @ref{Function remotescalar, ,remotescalar}
-@item @ref{Function translatepath, ,translatepath}
-@end multitable
-
-@subsection Functions which fill arrays
-The following functions all fill arrays, although they return values which
-depend on the number of items processed.
-
-@multitable @columnfractions .2 .2 .2 .2 .2
-@item @ref{Function getfields, ,getfields}
-@tab @ref{Function readintarray, ,readintarray}
-@tab @ref{Function readrealarray, ,readrealarray}
-@tab @ref{Function readstringarray, ,readstringarray}
-@tab @ref{Function readstringarrayidx, ,readstringarrayidx}
-@item @ref{Function regextract, ,regextract}
-@end multitable
-
-@subsection Functions which read ``large'' data
-The following functions read data from inside CFEngine (from classes, lists,
-strings, etc.) and outside of CFEngine (from files, databases, arrays, etc.)
-
-@unnumberedsubsubsec Functions which read arrays
-@multitable @columnfractions .2 .2 .2 .2 .2
-@item @ref{Function getindices, ,getindices}
-@item @ref{Function getvalues, ,getvalues}
-@tab @ref{Function regarray, ,regarray}
-@end multitable
-
-@unnumberedsubsubsec Functions which read disk data
-@multitable @columnfractions .2 .2 .2 .2 .2
-@item @ref{Function diskfree, ,diskfree}
-@end multitable
-
-@unnumberedsubsubsec Functions which read from a remote-CFEngine
-@multitable @columnfractions .2 .2 .2 .2 .2
-@item @ref{Function remoteclassesmatching, ,remoteclassesmatching}
-@tab @ref{Function remotescalar, ,remotescalar}
-@end multitable
-
-@unnumberedsubsubsec Functions which read classes
-@multitable @columnfractions .2 .2 .2 .2 .2
-@item @ref{Function and, ,and}
-@tab @ref{Function classify, ,classify}
-@tab @ref{Function classmatch, ,classmatch}
-@tab @ref{Function concat, ,concat}
-@tab @ref{Function not, ,not}
-@item @ref{Function or, ,or}
-@end multitable
-
-@unnumberedsubsubsec Functions which read command output
-@multitable @columnfractions .2 .2 .2 .2 .2
-@item @ref{Function execresult, ,execresult}
-@tab @ref{Function returnszero, ,returnszero}
-@tab @ref{Function usemodule, ,usemodule}
-@end multitable
-
-@unnumberedsubsubsec Functions which read the environment
-@multitable @columnfractions .2 .2 .2 .2 .2
-@item @ref{Function getenv, ,getenv}
-@end multitable
-
-@unnumberedsubsubsec Functions which read files
-@multitable @columnfractions .2 .2 .2 .2 .2
-@item @ref{Function countlinesmatching, ,countlinesmatching}
-@tab @ref{Function getfields, ,getfields}
-@tab @ref{Function getusers, ,getusers}
-@tab @ref{Function hashmatch, ,hashmatch}
-@tab @ref{Function peerleader, ,peerleader}
-@item @ref{Function peerleaders, ,peerleaders}
-@tab @ref{Function peers, ,peers}
-@tab @ref{Function readfile, ,readfile}
-@tab @ref{Function readintarray, ,readintarray}
-@tab @ref{Function readintlist, ,readintlist}
-@item @ref{Function readrealarray, ,readrealarray}
-@tab @ref{Function readreallist, ,readreallist}
-@tab @ref{Function readstringarray, ,readstringarray}
-@tab @ref{Function readstringarrayidx, ,readstringarrayidx}
-@tab @ref{Function readstringlist, ,readstringlist}
-@item @ref{Function regline, ,regline}
-@end multitable
-
-@unnumberedsubsubsec Functions which read LDAP data
-@multitable @columnfractions .2 .2 .2 .2 .2
-@item @ref{Function ldaparray, ,ldaparray}
-@tab @ref{Function ldaplist, ,ldaplist}
-@tab @ref{Function ldapvalue, ,ldapvalue}
-@tab @ref{Function regldap, ,regldap}
-@end multitable
-
-@unnumberedsubsubsec Functions which read from the network
-@multitable @columnfractions .2 .2 .2 .2 .2
-@item @ref{Function readtcp, ,readtcp}
-@tab @ref{Function selectservers, ,selectservers}
-@end multitable
-
-@unnumberedsubsubsec Functions which read the Windows registry
-@multitable @columnfractions .2 .2 .2 .2 .2
-@item @ref{Function registryvalue, ,registryvalue}
-@end multitable
-
-@unnumberedsubsubsec Functions which read (i,r,s)lists
-@multitable @columnfractions .2 .2 .2 .2 .2
-@item @ref{Function grep, ,grep}
-@tab @ref{Function join, ,join}
-@item @ref{Function product, ,product}
-@item @ref{Function reglist, ,reglist}
-@item @ref{Function sum, ,sum}
-@end multitable
-
-@unnumberedsubsubsec Functions which read strings
-@multitable @columnfractions .2 .2 .2 .2 .2
-@item @ref{Function hash, ,hash}
-@tab @ref{Function lastnode, ,lastnode}
-@tab @ref{Function regcmp, ,regcmp}
-@tab @ref{Function regextract, ,regextract}
-@tab @ref{Function splitstring, ,splitstring}
-@item @ref{Function strcmp, ,strcmp}
-@tab @ref{Function translatepath, ,translatepath}
-@end multitable
-
-@subsection Functions which look at file metadata
-The following functions examine file metadata, but don't use the
-contents of the file.
-
-@multitable @columnfractions .2 .2 .2 .2 .2
-@item @ref{Function accessedbefore, ,accessedbefore}
-@tab @ref{Function changedbefore, ,changedbefore}
-@tab @ref{Function fileexists, ,fileexists}
-@tab @ref{Function filesexist, ,filesexist}
-@tab @ref{Function isdir, ,isdir}
-@item @ref{Function islink, ,islink}
-@tab @ref{Function isnewerthan, ,isnewerthan}
-@tab @ref{Function isplain, ,isplain}
-@end multitable
-
-@subsection Functions which look at variables
-@multitable @columnfractions .2 .2 .2 .2 .2
-@item @ref{Function isgreaterthan, ,isgreaterthan}
-@tab @ref{Function islessthan, ,islessthan}
-@tab @ref{Function isvariable, ,isvariable}
-@end multitable
-
-@subsection Functions involving date or time
-The following functions all do date or time computation
-
-@multitable @columnfractions .2 .2 .2 .2 .2
-@item @ref{Function accessedbefore, ,accessedbefore}
-@tab @ref{Function accumulated, ,accumulated}
-@tab @ref{Function ago, ,ago}
-@tab @ref{Function changedbefore, ,changedbefore}
-@tab @ref{Function isnewerthan, ,isnewerthan}
-@item @ref{Function now, ,now}
-@tab @ref{Function on, ,on}
-@tab @ref{Function splayclass, ,splayclass}
-@end multitable
-
-@subsection Functions which work with or on regular expressions
-@multitable @columnfractions .2 .2 .2 .2 .2
-@item @ref{Function classmatch, ,classmatch}
-@tab @ref{Function countlinesmatching, ,countlinesmatching}
-@tab @ref{Function escape, ,escape}
-@tab @ref{Function getfields, ,getfields}
-@tab @ref{Function grep, ,grep}
-@item @ref{Function readintarray, ,readintarray}
-@tab @ref{Function readintlist, ,readintlist}
-@tab @ref{Function readrealarray, ,readrealarray}
-@tab @ref{Function readreallist, ,readreallist}
-@tab @ref{Function readstringarray, ,readstringarray}
-@item @ref{Function readstringarrayidx, ,readstringarrayidx}
-@tab @ref{Function readstringlist, ,readstringlist}
-@tab @ref{Function regarray, ,regarray}
-@tab @ref{Function regcmp, ,regcmp}
-@tab @ref{Function regextract, ,regextract}
-@item @ref{Function regldap, ,regldap}
-@tab @ref{Function regline, ,regline}
-@tab @ref{Function reglist, ,reglist}
-@tab @ref{Function splitstring, ,splitstring}
-@end multitable
diff --git a/docs/reference/promise_common_intro.texinfo b/docs/reference/promise_common_intro.texinfo
deleted file mode 100644
index 3f32c9565c..0000000000
--- a/docs/reference/promise_common_intro.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-Whereas most promise types are specific to a particular kind of
-interpretation that requires a typed interpreter (the bundle type),
-a number of promises can be made in any kind of bundle since they
-are of a generic input/output nature. These are @code{vars}, @code{classes},
-and @code{reports} promises. The specific promise attributes are listed below.
diff --git a/docs/reference/promises/access_example.texinfo b/docs/reference/promises/access_example.texinfo
deleted file mode 100644
index cb46aa17b9..0000000000
--- a/docs/reference/promises/access_example.texinfo
+++ /dev/null
@@ -1,69 +0,0 @@
-
-Example:
-
-@verbatim
-
-#########################################################
-# Server config
-#########################################################
-
-body server control
-
-{
-allowconnects => { "127.0.0.1" , "::1" };
-allowallconnects => { "127.0.0.1" , "::1" };
-trustkeysfrom => { "127.0.0.1" , "::1" };
-}
-
-#########################################################
-
-bundle server access_rules()
-
-{
-access:
-
- "/source/directory"
- comment => "Access to file transfer",
- admit => { "127.0.0.1" };
-
- # Grant orchestration communication
-
- "did.*"
- comment => "Access to class context (enterprise)",
- resource_type => "context",
- admit => { "127.0.0.1" };
-
-
- "value of my test_scalar, can expand variables here - $(sys.host)"
- comment => "Grant access to the string in quotes, by name test_scalar",
- handle => "test_scalar",
- resource_type => "literal",
- admit => { "127.0.0.1" };
-
- "XYZ"
- comment => "Grant access to contents of persistent scalar variable XYZ",
- resource_type => "variable",
- admit => { "127.0.0.1" };
-
- # Client grants access to CFEngine hub access
-
- "delta"
- comment => "Grant access to cfengine hub to collect report deltas",
- resource_type => "query",
- admit => { "127.0.0.1" };
- "full"
- comment => "Grant access to cfengine hub to collect full report dump",
- resource_type => "query",
- admit => { "127.0.0.1" };
-
- policy_hub::
-
- "collect call"
- comment => "Grant access to cfengine client to request the collection of its reports",
- resource_type => "query",
- admit => { "10.1.2.*" };
-
-
-}
-
-@end verbatim
diff --git a/docs/reference/promises/access_intro.texinfo b/docs/reference/promises/access_intro.texinfo
deleted file mode 100644
index bf5c49bab2..0000000000
--- a/docs/reference/promises/access_intro.texinfo
+++ /dev/null
@@ -1,33 +0,0 @@
-
-Access promises are conditional promises made by the server about file
-objects. The promise has two consequences. For file copy requests, the
-file becomes transferrable to the remote client according to the
-conditions specified in the server promse (i.e. if the connection
-encryption requirements are met, and if the client has been granted
-appropriate privileges with @code{maproot} (like its NFS counterpart)
-to be able to see file objects not owned by the server process owner).
-
-The promise has two mutally exclusive attributes @samp{admit} and
-@samp{deny}. Use of @samp{admit} is preferred as mistakes and
-omissions can easily be made when excluding from a group.
-
-When access is granted to a directory, the promise is automatically
-given about all of its contents and sub-directories.
-The access promise allows overlapping promises to be made, and these
-are kept in a first-come-first-served fashion. Thus file
-objects (promisers) should be listed in order of most-specific file
-first. In this way, specific promises will override less specific ones.
-
-@cartouche
-@smallexample
-
- access:
-
- @var{"/path/file_object"}
-
- admit => @{ @var{"hostname"}, @var{"ipv4_address"}, @var{"ipv6_address"} @};
-
-
-@end smallexample
-@end cartouche
-
diff --git a/docs/reference/promises/access_notes.texinfo b/docs/reference/promises/access_notes.texinfo
deleted file mode 100644
index 403dcef595..0000000000
--- a/docs/reference/promises/access_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-Entries may be literal addresses of IPv4 or IPv6, or any name registered
-in the POSIX @code{gethostbyname} service.
diff --git a/docs/reference/promises/build_xpath_example.texinfo b/docs/reference/promises/build_xpath_example.texinfo
deleted file mode 100644
index 3843119ffb..0000000000
--- a/docs/reference/promises/build_xpath_example.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-bundle edit_xml example
- {
- build_xpath:
- "/Server/Service/Engine/Host[ @name=\"cfe_host\" | Alias = cfe_alias ]";
- }
-
-@end verbatim
diff --git a/docs/reference/promises/build_xpath_intro.texinfo b/docs/reference/promises/build_xpath_intro.texinfo
deleted file mode 100644
index e31a9a9dc9..0000000000
--- a/docs/reference/promises/build_xpath_intro.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-This promise is part of the XML-editing model. It assures that a
-balanced XML tree, described by the given XPath, will be present
-within the XML file. If the document is empty, the default promise is to
-build the XML tree within the document. If the document is not empty, the
-default promise is to verify the given XPath, and if necessary, locate an
-insertion node and build the necessary portion of xlm tree within
-selected node. The insertion node is selected as the last unique node
-that is described by the XPath and also found within the document. The
-promise object referred to is a literal string representation of an XPath.
diff --git a/docs/reference/promises/build_xpath_notes.texinfo b/docs/reference/promises/build_xpath_notes.texinfo
deleted file mode 100644
index 11ea996b84..0000000000
--- a/docs/reference/promises/build_xpath_notes.texinfo
+++ /dev/null
@@ -1,7 +0,0 @@
-
-Note that typically, only a single XPath is built in each @code{build_xpath}
-promise (you may of course have multiple promises that each build an XPath).
-Also, please note that the supported syntax used in building an XPath is
-currently limited to a simple and compact format, as shown in the above
-example. The XPath must begin with '/', as it is verified and built using
-an absolute path, from the root node of the document.
diff --git a/docs/reference/promises/classes_example.texinfo b/docs/reference/promises/classes_example.texinfo
deleted file mode 100644
index 85a265427d..0000000000
--- a/docs/reference/promises/classes_example.texinfo
+++ /dev/null
@@ -1,14 +0,0 @@
-
-
-@verbatim
-
-bundle common g
-{
-classes:
-
- "one" expression => "any";
-
- "client_network" expression => iprange("128.39.89.0/24");
-}
-
-@end verbatim
diff --git a/docs/reference/promises/classes_intro.texinfo b/docs/reference/promises/classes_intro.texinfo
deleted file mode 100644
index b3c5f4ea63..0000000000
--- a/docs/reference/promises/classes_intro.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-Classes promises refer to the classification of different
-run-contexts. These are not related to object oriented classes, they
-are more like tag labels representing different properties of the
-environement.
-
-The term classes was introduced before the widespread use of the term in
-Object Orientation, and has since stuck. Today, we use the words class
-and context interchangeably.
-
diff --git a/docs/reference/promises/classes_notes.texinfo b/docs/reference/promises/classes_notes.texinfo
deleted file mode 100644
index 2d171a7b06..0000000000
--- a/docs/reference/promises/classes_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Classes promises may be made in any bundle, i.e. in bundles pertaining to
-any agent. Classes that are defined in common bundles are global in scope,
-while classes in all other bundles are local.
diff --git a/docs/reference/promises/commands_example.texinfo b/docs/reference/promises/commands_example.texinfo
deleted file mode 100644
index 7fe180b194..0000000000
--- a/docs/reference/promises/commands_example.texinfo
+++ /dev/null
@@ -1,18 +0,0 @@
-
-@verbatim
-
-bundle agent example
-
-{
-commands:
-
- "/bin/sleep 10"
- action => background;
-
- "/bin/sleep"
- args => "20",
- action => background;
-
-}
-
-@end verbatim
diff --git a/docs/reference/promises/commands_intro.texinfo b/docs/reference/promises/commands_intro.texinfo
deleted file mode 100644
index 396ecd821e..0000000000
--- a/docs/reference/promises/commands_intro.texinfo
+++ /dev/null
@@ -1,46 +0,0 @@
-
-
-@cartouche
-@smallexample
-
-commands:
-
- @var{"/path/to/command args"}
-
- args => "@var{more args}",
- contain => @var{contain_body},
- module => @var{"true"/"false"};
-
-@end smallexample
-@end cartouche
-
-Command @i{containment} allows you to make a `sandbox' around a
-command, to run it as a non-privileged user inside an isolated
-directory tree. CFEngine @code{modules} are commands that support a simple
-protocol (see below) in order to set additional variables and classes
-on execution from user defined code. Modules are intended for use as
-system probes rather than additional configuration promises.
-
-In CFEngine 3 commands and processes have been separated
-cleanly. Restarting of processes must be coded as a separate
-command. This stricter type separation will allow more careful
-conflict analysis to be carried out.
-
-Output from commands executed here is quoted inline, but prefixed
-with the letter @samp{Q} to distinguish it from other output, e.g.
-from @code{reports} (which is prefixed with the letter @samp{R}).
-
-It is possible to set classes based on the return code of a
-commands-promise in a very flexible way. See the
-@code{kept_returncodes}, @code{repaired_returncodes} and
-@code{failed_returncodes} attributes.
-
-Commands were called @code{shellcommands} in CFEngine 2.
-
-
-@i{NOTE: a common mistake in using CFEngine is to embed many shell
-commands instead of using the built-in functionality. Use of CFEngine
-internals is preferred as it assures convergence and proper integrated
-checking. Extensive use of shell commands will make a CFEngine
-execution very heavy-weight like other management systems. To minimize
-the system cost of execution, always use CFEngine internals.}
diff --git a/docs/reference/promises/commands_notes.texinfo b/docs/reference/promises/commands_notes.texinfo
deleted file mode 100644
index 36e0077d9b..0000000000
--- a/docs/reference/promises/commands_notes.texinfo
+++ /dev/null
@@ -1,19 +0,0 @@
-
-NOTE: when referring to executables whose paths contain spaces, you
-should quote the entire program string separately so that CFEngine
-knows the name of the executable file. e.g.
-
-@smallexample
-
- commands:
-
- windows::
-
- "\"c:\Program Files\my name with space\" arg1 arg2";
-
- linux::
-
- "\"/usr/bin/funny command name\" -a -b -c";
-
-@end smallexample
-
diff --git a/docs/reference/promises/common_example.texinfo b/docs/reference/promises/common_example.texinfo
deleted file mode 100644
index 1df4ee8e3c..0000000000
--- a/docs/reference/promises/common_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-files:
-
- "/etc/passwd" -> "Security team"
-
- perms => p("644"),
- action => justcheck,
- comment => "This was decided in internal procedures XYZ123";
-
-@end verbatim
diff --git a/docs/reference/promises/common_intro.texinfo b/docs/reference/promises/common_intro.texinfo
deleted file mode 100644
index dc56711a20..0000000000
--- a/docs/reference/promises/common_intro.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-Most promise bodies belong to one and only one type of promise. The
-generic `*' promises bodies can be added to any promise type in
-@code{cf-agent}, hence the star which means (for this documentation
-only) `any'.
-
-
-The body attributes described below can thus be added to any promise rule
-in the agent. These promises address matters of a completely general
-nature -- how CFEngine behaves as it attempts to keep a promise,
-comments about the promises etc.
diff --git a/docs/reference/promises/common_notes.texinfo b/docs/reference/promises/common_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/promises/common_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/promises/databases_example.texinfo b/docs/reference/promises/databases_example.texinfo
deleted file mode 100644
index a9217a715b..0000000000
--- a/docs/reference/promises/databases_example.texinfo
+++ /dev/null
@@ -1,60 +0,0 @@
-
-@verbatim
-
-body common control
-{
-bundlesequence => { "databases" };
-}
-
-bundle agent databases
-
-{
-#commands:
-
-# "/usr/bin/createdb cf_topic_maps",
-
-# contain => as_user("mysql");
-
-databases:
-
- "cf_topic_maps/topics"
-
- database_operation => "create",
- database_type => "sql",
- database_columns => {
- "topic_name,varchar,256",
- "topic_comment,varchar,1024",
- "topic_id,varchar,256",
- "topic_type,varchar,256",
- "topic_extra,varchar,26"
- },
-
- database_server => myserver;
-
-
-
-}
-
-################################################
-
-body database_server myserver
-{
-any::
- db_server_owner => "postgres";
- db_server_password => "";
- db_server_host => "localhost";
- db_server_type => "postgres";
- db_server_connection_db => "postgres";
-none::
- db_server_owner => "root";
- db_server_password => "";
- db_server_host => "localhost";
- db_server_type => "mysql";
- db_server_connection_db => "mysql";
-}
-
-body contain as_user(x)
-{
-exec_owner => "$(x)";
-}
-@end verbatim
diff --git a/docs/reference/promises/databases_intro.texinfo b/docs/reference/promises/databases_intro.texinfo
deleted file mode 100644
index 87d004b1b2..0000000000
--- a/docs/reference/promises/databases_intro.texinfo
+++ /dev/null
@@ -1,77 +0,0 @@
-
-CFEngine Nova can interact with commonly used database servers to keep
-promises about the structure and content of data within them.
-
-
-There are two main cases of database management to address: small
-embedded databases and large centralized databases.
-
-CFEngine is a tool whose strength lies distributed management of
-computers. Databases are often centralized entities that have
-single point of management, so a large monolithic database
-is more easily managed with other tools. However, CFEngine can still
-monitor changes and discrepancies, and it can manage smaller embedded
-databases that are distributed in nature, whether they are SQL,
-registry or future types.
-
-So creating 100 new databases for test purposes is a task for
-CFEngine, but adding a new item to an important production database is
-not a task that we recommend using CFEngine for.
-
-There are three kinds of database supported by Nova:
-
-@table @emph
-
-@item LDAP - The Lightweight Directory Access Protocol
-A hierarchical network database primarily for reading simple schema.
-
-@item SQL - Structured Query Language
-A number of relational databases (currently supported: MySQL, Postgres)
-for reading and writing complex data.
-
-@item Registry - Microsoft Registry
-An embedded database for interfacing with system values in Microsoft Windows (Only CFEngine Nova)
-
-@end table
-In addition, CFEngine uses a variety of embedded databases
-for its own internals.
-
-
-CFEngine's ability to make promises about databases depends on the
-good grace of the database server. Embedded databases are directly
-part of the system and promises can be made directly. However,
-databases running through a server process (either on the same host or
-on a different host) are independent agents and CFEngine cannot make
-promises on their behalf, unless they promise (grant) permission for
-CFEngine to make the changes. Thus the pre-requisite for making
-SQL database promises is to grant a point of access on the server.
-
-
-@cartouche
-@smallexample
-
- databases:
-
- "@var{database}/@var{subkey or table}"
-
- database_operation => "@var{create/delete/drop}",
- database_type => "@var{sql/ms_registry}",
- database_columns => @{
- "@var{name},@var{type},@var{size}",
- "@var{name},@var{type}",
- @},
-
- database_server => @var{body};
-
-
- body database_server @var{name}
- @{
- db_server_owner => "@var{account name}";
- db_server_password => "@var{password}";
- db_server_host => "@var{hostname or omit for localhost}";
- db_server_type => "@var{mysql/posgres}";
- db_server_connection_db => "@var{database we can connect to}";
- @}
-
-@end smallexample
-@end cartouche
diff --git a/docs/reference/promises/databases_notes.texinfo b/docs/reference/promises/databases_notes.texinfo
deleted file mode 100644
index db9a81a5a0..0000000000
--- a/docs/reference/promises/databases_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-The promiser in database promises is a concatenation of the database name and underlying tables.
-This presents a simple hierarchical model that looks like a file-system. This is the normal
-structure within the Windows registry for instance. Entity-Relation databases do not normally
-present tables in this way, but no harm is done in representing them as a hierarchy of depth 1.
diff --git a/docs/reference/promises/defaults_example.texinfo b/docs/reference/promises/defaults_example.texinfo
deleted file mode 100644
index d8f571cefe..0000000000
--- a/docs/reference/promises/defaults_example.texinfo
+++ /dev/null
@@ -1,94 +0,0 @@
-
-A basic example, illustrating different ways to test for missing
-input. Note carefully that CFEngine does not use Perl semantics:
-i.e. undefined variables do not map to the empty string, they remain
-as variables for possible future expansion. Because of
-the convergence of CFEngine, some variables might in the strictest sense
-be defined but still contain unresolved variables, to handle this
-you will need to match the @code{$(abc)} form of the variables.
-
-@verbatim
-
-body common control
-{
-bundlesequence => { "main" };
-}
-
-bundle agent main
-{
-methods:
-
- "example" usebundle => test("one","x","","$(four)");
-
-}
-
-bundle agent test(a,b,c,d)
-{
-defaults:
-
- "a" string => "default a", if_match_regex => "";
- "b" string => "default b", if_match_regex => "x";
- "c" string => "default c", if_match_regex => "";
- "d" string => "default d", if_match_regex => "\$\([a-zA-Z0-9_.]+\)";
-
-reports:
-
- !nothing::
-
- "a = '$(a)', b = '$(b)', c = '$(c)' d = '$(d)'";
-}
-
-@end verbatim
-@noindent Another example:
-
-@verbatim
-
-bundle agent example
-
-{
-defaults:
-
- "X" string => "I am a default value";
- "Y" slist => { "I am a default list item 1", "I am a default list item 2" };
-
-methods:
-
- "example" usebundle => mymethod("","bbb");
-
-reports:
-
- !xyz::
-
- "The default value of X is $(X)";
- "The default value of Y is $(Y)";
-}
-
-###########################################################
-
-bundle agent mymethod(a,b)
-
-{
-vars:
-
- "no_return" string => "ok"; # readfile("/dont/exist","123");
-
-defaults:
-
- "a" string => "AAAAAAAAA", if_match_regex => "";
-
- "b" string => "BBBBBBBBB", if_match_regex => "";
-
- "no_return" string => "no such file";
-
-reports:
-
- !xyz::
-
- "The value of a is $(a)";
- "The value of b is $(b)";
-
- "The value of no_return is $(no_return)";
-
-}
-
-@end verbatim
diff --git a/docs/reference/promises/defaults_intro.texinfo b/docs/reference/promises/defaults_intro.texinfo
deleted file mode 100644
index 7a44944d00..0000000000
--- a/docs/reference/promises/defaults_intro.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Defaults promises are related to variables. If a variable or paramter
-in a promise bundle is undefined, or its value is defined to be invalid,
-a default value can be promised instead.
diff --git a/docs/reference/promises/defaults_notes.texinfo b/docs/reference/promises/defaults_notes.texinfo
deleted file mode 100644
index a78e7217b9..0000000000
--- a/docs/reference/promises/defaults_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-This was introduced in CFEngine core 3.4.0. (2012)
-
diff --git a/docs/reference/promises/delete_attribute_example.texinfo b/docs/reference/promises/delete_attribute_example.texinfo
deleted file mode 100644
index fdcbf8c9eb..0000000000
--- a/docs/reference/promises/delete_attribute_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-bundle edit_xml example
- {
- delete_attribute:
- "name"
-
- select_xpath => "/Server/Service/Engine/Host";
- }
-
-@end verbatim
diff --git a/docs/reference/promises/delete_attribute_intro.texinfo b/docs/reference/promises/delete_attribute_intro.texinfo
deleted file mode 100644
index 11e04da1f7..0000000000
--- a/docs/reference/promises/delete_attribute_intro.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-This promise is part of the XML-editing model. It assures that
-an attribute, with the given name, will not be present in the
-specified node within the XML file. If the attribute is found,
-the default promise is to remove the attribute, from within the
-specified node. The specified node is determined by
-body-attributes. The promise object referred to is a literal
-string representation of the name of the attribute to be deleted.
diff --git a/docs/reference/promises/delete_attribute_notes.texinfo b/docs/reference/promises/delete_attribute_notes.texinfo
deleted file mode 100644
index 8de73a161c..0000000000
--- a/docs/reference/promises/delete_attribute_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Note that typically, only a single attribute, within a single specified node,
-is deleted in each @code{delete_attribute} promise (you may of course
-have multiple promises that each delete an attribute).
diff --git a/docs/reference/promises/delete_lines_example.texinfo b/docs/reference/promises/delete_lines_example.texinfo
deleted file mode 100644
index 42f3d92905..0000000000
--- a/docs/reference/promises/delete_lines_example.texinfo
+++ /dev/null
@@ -1,21 +0,0 @@
-
-@verbatim
-
-bundle edit_line example
- {
- delete_lines:
-
- "olduser:.*";
-
- }
-
-@end verbatim
-
-Note that typically, only a single line is specified in each @code{delete_lines}
-promise (you may of course have multiple promises that each delete a line).
-
-It is also possible to specify multi-line @code{delete_lines} promises.
-However, these promises will only delete those lines if @i{all} the lines are
-present in the file @i{in exactly the same order} as specified in the promise
-(with no intervening lines). That is, all the lines must match as a unit for
-the @code{delete_lines} promise to be kept.
diff --git a/docs/reference/promises/delete_lines_intro.texinfo b/docs/reference/promises/delete_lines_intro.texinfo
deleted file mode 100644
index 7814fa463b..0000000000
--- a/docs/reference/promises/delete_lines_intro.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-This promise assures that certain lines matching regular expression
-patterns exactly will not be present in a text file. If the lines are
-found, the default promise is to remove them (this behavior may be modified
-with further pattern matching in @code{delete_select} and/or changed with
-@code{not_matching}).
diff --git a/docs/reference/promises/delete_lines_notes.texinfo b/docs/reference/promises/delete_lines_notes.texinfo
deleted file mode 100644
index da12c3c5d8..0000000000
--- a/docs/reference/promises/delete_lines_notes.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-If the promiser is contains multiple lines, then CFEngine assumes that
-all of the lines must exist as a contiguous block in order to be
-deletes. This gives @samp{preserve_block} semantics to any multiline
-@code{delete_lines} promise.
diff --git a/docs/reference/promises/delete_text_example.texinfo b/docs/reference/promises/delete_text_example.texinfo
deleted file mode 100644
index 984d25fd08..0000000000
--- a/docs/reference/promises/delete_text_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-bundle edit_xml example
- {
- delete_text:
- "text content to match, as a substring, of text to be deleted from specified node"
-
- select_xpath => "/Server/Service/Engine/Host/Alias";
- }
-
-@end verbatim
diff --git a/docs/reference/promises/delete_text_intro.texinfo b/docs/reference/promises/delete_text_intro.texinfo
deleted file mode 100644
index 9f62d0118f..0000000000
--- a/docs/reference/promises/delete_text_intro.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-This promise is part of the XML-editing model. It assures that a
-value string, containing the matching substring, will not be present
-in the specified node within the XML file. If the substring is
-found, the default promise is to remove the existing value string,
-from within the specified node. The specified node is determined
-by body-attributes. The promise object referred to is a literal
-string of text.
diff --git a/docs/reference/promises/delete_text_notes.texinfo b/docs/reference/promises/delete_text_notes.texinfo
deleted file mode 100644
index 99fa5bbf73..0000000000
--- a/docs/reference/promises/delete_text_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Note that typically, only a single value string, within a single specified
-node, is deleted in each @code{delete_text} promise (you may of course
-have multiple promises that each delete a value string).
diff --git a/docs/reference/promises/delete_tree_example.texinfo b/docs/reference/promises/delete_tree_example.texinfo
deleted file mode 100644
index 4049234f07..0000000000
--- a/docs/reference/promises/delete_tree_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-bundle edit_xml example
- {
- delete_tree:
- ""
-
- select_xpath => "/Server/Service/Engine";
- }
-
-@end verbatim
diff --git a/docs/reference/promises/delete_tree_intro.texinfo b/docs/reference/promises/delete_tree_intro.texinfo
deleted file mode 100644
index b182021277..0000000000
--- a/docs/reference/promises/delete_tree_intro.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-This promise is part of the XML-editing model. It assures that a
-balanced XML tree, containing the matching subtree, will not be
-present in the specified node within the XML file. If the subtree
-is found, the default promise is to remove the containing tree from
-within the specified node. The specified node is determined by
-body-attributes. The promise object referred to is a literal string
-representation of a balanced XML subtree.
diff --git a/docs/reference/promises/delete_tree_notes.texinfo b/docs/reference/promises/delete_tree_notes.texinfo
deleted file mode 100644
index 6c2f3a36ff..0000000000
--- a/docs/reference/promises/delete_tree_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Note that typically, only a single tree, within a single specified node,
-is deleted in each @code{delete_tree} promise (you may of course have
-multiple promises that each delete a tree).
diff --git a/docs/reference/promises/edit_line_intro.texinfo b/docs/reference/promises/edit_line_intro.texinfo
deleted file mode 100644
index e9e645a45d..0000000000
--- a/docs/reference/promises/edit_line_intro.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-Line based editing is a simple model for editing files. Before XML,
-and later JSON, most configuration files were line based. The
-line-based editing offers a powerful environment for model-based editing and
-templating.
diff --git a/docs/reference/promises/edit_xml_intro.texinfo b/docs/reference/promises/edit_xml_intro.texinfo
deleted file mode 100644
index 5c1eaa3cd1..0000000000
--- a/docs/reference/promises/edit_xml_intro.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-The use of XML documents in systems configuration is widespread. XML documents
-represent data that is complex and can be structured in various ways. The XML
-based editing offers a powerful environment for editing hierarchical and
-structured XML datasets.
-
-Please Note: Using edit_xml promise types will modify whitespace and tag format
-in the resulting edited document. This is standard behavior of an XML parser, and
-cannot be avoided. Please take this behavior into consideration when using the
-edit_xml promise types.
diff --git a/docs/reference/promises/field_edits_example.texinfo b/docs/reference/promises/field_edits_example.texinfo
deleted file mode 100644
index 37bd94016d..0000000000
--- a/docs/reference/promises/field_edits_example.texinfo
+++ /dev/null
@@ -1,70 +0,0 @@
-
-@verbatim
-
-bundle agent example
-
-{
-vars:
-
- "userset" slist => { "one-x", "two-x", "three-x" };
-
-files:
-
- "/tmp/passwd"
-
- create => "true",
- edit_line => SetUserParam("mark","6","/set/this/shell");
-
- "/tmp/group"
-
- create => "true",
- edit_line => AppendUserParam("root","4","@(userset)");
-}
-
-########################################################
-
-bundle edit_line SetUserParam(user,field,val)
- {
- field_edits:
-
- "$(user):.*"
-
- # Set field of the file to parameter
-
- edit_field => col(":","$(field)","$(val)","set");
- }
-
-########################################################
-
-bundle edit_line AppendUserParam(user,field,allusers)
- {
- vars:
-
- "val" slist => { @(allusers) };
-
- field_edits:
-
- "$(user):.*"
-
- # Set field of the file to parameter
-
- edit_field => col(":","$(field)","$(val)","alphanum");
-
- }
-
-########################################
-# Bodies
-########################################
-
-body edit_field col(split,col,newval,method)
-
-{
-field_separator => "$(split)";
-select_field => "$(col)";
-value_separator => ",";
-field_value => "$(newval)";
-field_operation => "$(method)";
-extend_fields => "true";
-}
-
-@end verbatim
diff --git a/docs/reference/promises/field_edits_intro.texinfo b/docs/reference/promises/field_edits_intro.texinfo
deleted file mode 100644
index 8d27671861..0000000000
--- a/docs/reference/promises/field_edits_intro.texinfo
+++ /dev/null
@@ -1,25 +0,0 @@
-
-Certain types of text file (e.g. the @file{passwd} and @file{group}
-files in Unix) are tabular in nature, with field separators
-(e.g. @samp{:} or @samp{,}). This promise assumes a parameterizable model
-for editing the fields of such files, using a regular expression to
-separate major fields and a character to separate sub-fields. First
-you match the line with a regular expression. The regular
-expression must match the entire line (that is, it is anchored,
-@pxref{Anchored vs. unanchored regular expressions}). Then a
-@code{field_edits} body describes the separators for fields and one
-level of sub-fields, along with policies for editing these fields, ordering
-the items within them etc.
-
-@cartouche
-@smallexample
-
-field_edits:
-
- "@var{regex matching line}"
-
- edit_field => @var{body};
-
-@end smallexample
-@end cartouche
-
diff --git a/docs/reference/promises/field_edits_notes.texinfo b/docs/reference/promises/field_edits_notes.texinfo
deleted file mode 100644
index a00be70bc8..0000000000
--- a/docs/reference/promises/field_edits_notes.texinfo
+++ /dev/null
@@ -1,15 +0,0 @@
-
-Field editing allows us to edit tabular files in a unique way, adding
-and removing data from addressable fields. The @file{passwd} and
-@file{group} files are classic examples of tabular files, but there
-are many ways to use this feature, e.g. edit a string
-
-@verbatim
-
-VARIABLE="one two three"
-
-@end verbatim
-
-@noindent View this line as a tabular line separated by @samp{"} and
-with sub-separator given by the space.
-
diff --git a/docs/reference/promises/files_example.texinfo b/docs/reference/promises/files_example.texinfo
deleted file mode 100644
index 64a22a1bfa..0000000000
--- a/docs/reference/promises/files_example.texinfo
+++ /dev/null
@@ -1,32 +0,0 @@
-Another example of files promises is to look for changes in files. The
-following example reports on all recent changes to files in a directory by
-maintaining the most recent version of the @code{md5} hash of the file
-contents. Similar checks can be used to examine metadata or both the contents
-and metadata, as well as using different difference checks. The Community
-Edition only reports that changes were found, but Enterprise versions of
-CFEngine can also report on what exactly the significant changes were.
-
-@verbatim
-
-bundle agent example
-{
-files:
-
- "/home/mark/tmp" -> "Security team"
-
- changes => lay_a_tripwire,
- depth_search => recurse("inf"),
- action => background;
-}
-
-#########################################################
-
-body changes lay_a_tripwire
-
-{
-hash => "md5";
-report_changes => "content";
-update => "yes";
-}
-
-@end verbatim
diff --git a/docs/reference/promises/files_intro.texinfo b/docs/reference/promises/files_intro.texinfo
deleted file mode 100644
index 62a1e2c112..0000000000
--- a/docs/reference/promises/files_intro.texinfo
+++ /dev/null
@@ -1,428 +0,0 @@
-
-Files promises are an umbrella concept for all attributes of files.
-Operations fall basically into three categories: create, delete and
-edit.
-
-@cartouche
-@smallexample
-
- files:
-
- "@var{/path/file_object}"
-
- perms => @var{perms_body},
- ... ;
-
-@end smallexample
-@end cartouche
-
-Prior to version 3, file promises were scattered into many different
-types such as @code{files}, @code{tidy}, @code{copy}, @code{links},
-etc. File handling in CFEngine 3 uses regular expressions everywhere for pattern
-matching. The old `wildcard/globbing' expressions @samp{*} and
-@samp{?} are deprecated, and everything is based consistently on Perl
-Compatible Regular Expressions.
-
-There is a natural ordering in file processing that obviates the need
-for the actionsequence. The trick of using multiple actionsequence
-items with different classes, e.g.
-
-@verbatim
- actionsequence = ( ... files.one .. files.two )
-@end verbatim
-
-can now be handled more elegantly using bundles. The natural ordering
-uses that fact that some operations are mutually exclusive and that
-some operations do not make sense in reverse order. For example,
-editing a file and then copying onto it would be nonsense.
-Similarly, you cannot both remove a file and rename it.
-
-@noindent @b{File copying}
-
-One of the first things users of CFEngine 2 will notice is that copying is now `backwards'.
-Instead of the default object being source and the option being the destination,
-in CFEngine 3 the destination is paramount and the source is an option.
-This is because the model of voluntary cooperation tells us that it is the
-object that is changed which is the agent making the promise. One cannot
-force change onto a destination with CFEngine, one can only invite change from
-a source.
-
-@noindent @b{Normal ordering of promise attributes}
-
-CFEngine 3 no longer has an `action sequence'. Ordering of operations has,
-in most cases, a natural ordering which is assumed by the agent. For instance:
-`delete then create' (normal ordering) makes sense, but
-`create then delete' does not. This sort of principle can be extended to
-deal with all aspects of file promises.
-
-The diagram below shows the ordering. Notice that the same ordering
-applies regardless of file type (plain-file or directory). Note also that
-file editing is done "atomically" (see `File editing in CFEngine 3' for
-important details).
-
-@image{filelogic,10cm,,The normal ordering of file operators in CFEngine 3,png}
-
-The pseudo-code for this logic is shown in the diagram and below:
-
-@verbatim
- for each file promise-object
- {
- if (depth_search)
- do
- DepthSearch (HandleLeaf)
- else
- (HandleLeaf)
- done
- }
-
- HandleLeaf()
- {
- Does leaf-file exist?
-
- NO: create
- YES: rename,delete,touch,
-
- do
- for all servers in {localhost, @(servers)}
- {
- if (server-will-provide)
- do
- if (depth_search)
- embedded source-depth-search (use file source)
- break
- else
- (use file source)
- break
- done
- done
- }
- done
-
- Do all links (always local)
-
- Check Permissions
-
- Do edits
- }
-
-@end verbatim
-
-@noindent @b{Depth searches (recursion) during searches}
-
-In CFEngine 2 there was the concept of recursion during file
-searches. Recursion is now called "depth-search".
-In addition, it was possible to specify
-wildcards in the base-path for this search. CFEngine 3 replaces
-the `globbing' symbols with standard regular expressions:
-
-@verbatim
-
- CFEngine 2 CFEngine 3
-
-/one/*/two/thr*/four /one/.*/two/thr.*/four
-
-@end verbatim
-
-Note that this now means when searching for ``hidden'' files (files with names
-starting with a `.') or files with specific extensions, you should take care to
-escape the dot (e.g., @code{\.cshrc} or @code{.*\.txt} when you wish it to
-mean a literal character and not the ``any character'' interpretation provided
-by regular expression interpretation.
-Note that when you do a recursive search, the files @file{'.'} and
-@file{'..'} are never included in the matched files, even if the regular
-expresion in the @samp{leaf_name} specifically allows them.
-
-Note also the the filename @samp{/dir/ect/ory/.} is a special case used with
-the @samp{create} attribute to indicate the directory named @samp{/dir/ect/ory}
-and not any of the files under it. If you really want to specify a regular
-expression that matches any single-character filename, use
-@samp{/dir/ect/ory/[\w\W]} as your promise regular expression (you can't use
-@samp{/dir/ect/ory[^/]}, see below for an explanation.
-
-When we talk about a depth search, it refers to a search for file
-objects which starts from the one or more matched base-paths as shown
-in the example above.
-
-@noindent @b{Filenames and regular expressions}
-
-CFEngine allows regular expressions within filenames, but only after first
-doing some sanity checking to prevent some readily avoidable problems. The
-biggest rule you need to know about filenames and regular expressions is that
-@i{all} regular expressions in filenames are bounded by directory separators,
-and that each component expression is anchored between the directory separators
-@xref{Anchored vs. unanchored regular expressions}.
-In other words, CFEngine splits up any file paths into its component parts,
-and then it evaluates any regular expressions at a component-level.
-
-What this means is that the path @samp{/tmp/gar.*} will only match filenames
-like @file{/tmp/gar}, @file{/tmp/garbage} and @file{/tmp/garden}. It will
-@i{not} match filename like @file{/tmp/gar/baz} (because even though the
-@samp{.*} in a regular expression means "zero or more of any character",
-CFEngine restricts that to mean "zero or more of any character @i{in a path
-component}"). Correspondingly, CFEngine
-also restricts where you can use the @samp{/} character (you can't use it
-in a character class like @samp{[^/]} or in a parenthesized or repeated
-regular expression component.
-
-This means that regular expressions which include "optional directory
-components" won't work. You can't have a files promise to tidy the directory
-@samp{(/usr)?/tmp}. Instead, you need to be more verbose and specify
-@samp{/usr/tmp|/tmp}, or even better, think declaratively and create an
-@i{slist} that contains both the strings @samp{/tmp} and @samp{/usr/tmp},
-and then allow CFEngine to iterate over the list!
-
-This also means that the path @samp{/tmp/.*/something} will match files like
-@file{/tmp/abc/something} or @file{/tmp/xyzzy/something}. However, even
-though the pattern @samp{.*} means "zero or more of any character (except
-@samp{/})", CFEngine matches files bounded by directory separators. So even
-though the pathname @file{/tmp//something} is technically the same as the
-pathname @file{/tmp/something}, the regular expression @samp{/tmp/.*/something}
-will @i{not} match on the degenerate case of @file{/tmp//something} (or
-@file{/tmp/something}).
-
-@noindent @b{Promises involving regular expressions}
-
-CFEngine can only keep (or repair, or fail to keep) a promise on files which
-actually exist. If you make a promise based on a wildcard match, then the
-promise is only ever attempted if the match succeeds. However, if you make a
-promise which includes a recursive search which includes a wildcard match,
-then the promise can be kept or repaired (provided that the directory
-specified in the promise exists). Consider the following two examples,
-(assuming that there first exist files named @file{/tmp/gar},
-@file{/tmp/garbage} and @file{/tmp/garden}). At first blush, the two
-promises look like they should do the same thing, but there is a subtle
-difference:
-
-@verbatim
-bundle agent foobaz bundle agent foobaz
-{ {
-files: files:
- "/tmp/gar.*" "/tmp"
- delete => tidy, delete => tidy,
- classes => if_ok("done"); depth_search => recurse("0"),
- file_select => gars,
- classes => if_ok("done");
- }
-
- body file_select gars
- {
- leaf_name => { "gar.*" };
- file_result => "leaf_name";
- }
-
-body classes if_ok(x) body classes if_ok(x)
-{ {
-promise_repaired => { "$(x)" }; promise_repaired => { "$(x)" };
-promise_kept => { "$(x)" }; promise_kept => { "$(x)" };
-} }
-@end verbatim
-
-In the first example, when the configuration containing this promise is first
-executed, any file starting with "gar" that exists in the @samp{/tmp}
-directory will be removed, and the @samp{done} class will be set. However,
-when the configuration is executed a second time, the pattern
-@samp{/tmp/gar.*} will not match any files, and that promise will not even
-be @i{attempted} (and, consequently the @samp{done} class will @i{not} be set).
-
-In the second example, when the configuration containing this promise is first
-executed, any file starting with "gar" that exists in the @samp{/tmp}
-directory will also be removed, and the @samp{done} class will also be set.
-The second time the configuration is executed, however, the promise on the
-@samp{/tmp} directory will still be executed (because @samp{/tmp} of course
-still exists), and the @samp{done} class @i{will} be set, because all files
-matching the @samp{file_select} attribute have been deleted from that
-directory.
-
-@noindent @b{Local and remote searches}
-
-There are two distinct kinds of depth
-search:
-
-@itemize
-@item A local search over promiser agents.
-@item A remote search over provider agents.
-@end itemize
-
-When we are @i{copying} or @i{linking} to a file source, it is the search over
-the @i{remote} source that drives the content of a promise (the
-promise is a promise to use what the remote source provides). In
-general, the sources are on a different device to the images that make
-the promises. For all other promises, we search over existing local
-objects.
-
-
-If we specify depth search together with copy of a directory, then the
-implied remote source search is assumed, and it is made after the
-search over local base-path objects has been made. If you mix complex
-promise body operations in a single prmose, this could lead to
-confusion about the resulting behaviour, and a warning is issued. In
-general it is not recommended to mix searches without a full
-understanding of the consequences, but this might occasionally be
-useful.
-
-Depth search is not allowed with @code{edit_line} promises.
-
-@noindent @b{File editing in CFEngine 3}
-
-CFEngine 2 assumed that all files were line-edited, because it was
-based on Unix traditions. Since then many new file formats have
-emerged, including XML. CFEngine 3 opens up the possibiltiy for
-multiple models of file editing. Line based editing is still present and
-is both much simplified and much more powerful than previously.
-
-File editing is not just a single kind of promise but a whole range of
-`promises within files'. It is therefore not merely a body to a single kind of
-promise, but a bundle of sub-promises. After all, inside each file is a new
-world of objects that can make promises, quite separate from files' external
-attributes.
-
-A typical file editing stanza has the elements in the following
-example.
-
-
-@verbatim
-######################################################################
-#
-# File editing
-#
-######################################################################
-
-body common control
-
-{
-version => "1.2.3";
-bundlesequence => { "outerbundle" };
-}
-
-########################################################
-
-bundle agent outerbundle
-
-{
-files:
-
- "/home/mark/tmp/cf3_test"
-
- create => "true", # Like autocreate in cf2
- edit_line => inner_bundle;
-}
-
-########################################################
-
-bundle edit_line inner_bundle
- {
- vars:
-
- "who" string => "SysAdmin John"; # private variable in bundle
-
- insert_lines:
- "/* This file is maintained by CFEngine (see $(who) for details) */",
- location => first_line;
-
- replace_patterns:
-
- # replace shell comments with C comments
-
- "#(.*)"
-
- replace_with => C_comment,
- select_region => MySection("New section");
-
- reports:
-
- someclass::
-
- "This is file $(edit.filename)";
- }
-
-########################################
-# Bodies for the library ...
-########################################
-
-body replace_with C_comment
-
-{
-replace_value => "/* $(match.1) */"; # backreference
-occurrences => "all"; # first, last all
-}
-
-########################################################
-
-body select_region MySection(x)
-
-{
-select_start => "\[$(x)\]";
-select_end => "\[.*\]";
-}
-
-########################################################
-
-body location first_line
-
-{
-before_after => "before";
-first_last => "first";
-select_line_matching => ".*";
-}
-
-
-@end verbatim
-
-@noindent There are several things to notice:
-
-@itemize
-@item
-The line-editing promises are all convergent promises about patterns within
-the file. They have bodies, just like other attributes do and these allow us
-to make simple templates about file editing while extending the power of the
-basic primitives.
-
-@item
-All file edits specified in a single @code{edit_line} bundle are handled
-"atomically". CFEngine edits files like this:
-@itemize
-@item
-CFEngine makes a copy of the file you you want to edit
-@item
-CFEngine makes all the edits in the @b{copy} of the file. The filename is the
-same as your original file with the extension @file{.cf-after-edit} appended.
-@item
-After all edits are complete (the @code{delete_lines}, @code{field_edits},
-@code{insert_lines}, and finally @code{replace_patterns} promises), CFEngine
-checks to see if the new file is the same as the original one. If there are
-no differences, the promises have converged, so it deletes the copy, and the
-original is left completely unmodified.
-@item
-If there are any differences, CFEngine makes a copy of your original file with
-the extension @file{.cf-before-edit} (so you always have the most recent backup
-available), and then renames the edited version
-to your original filename.
-@end itemize
-Because file rename is an atomic operation (guaranteed by the operating
-system), any application program will either see the old version of the file
-or the new one -- there is no "window of opportunity" where a partially edited
-file can be seen (unless an application intentionally looks for the
-@file{.cf-after-edit} file). Problems during editing (such as disk-full or
-permission errors) are likewise detected, and CFEngine will not rename a
-partial file over your original.
-
-@item
-All pattern matching is through perl compatible regular expressions
-@item
-Editing takes place within a marked region (which defaults to the whole file
-if not otherwise specified).
-@item
-Search/replace functions now allow back-references.
-@item
-The line edit model now contains a field or column model for dealing with tabular files such
-as Unix @file{passwd} and @file{group} files. We can now apply powerful convergent editing operations
-to single fields inside a table, to append, order and delete items from lists inside fields.
-
-@item
-The special variable @code{$(edit.filename)} contains the name of the file being edited within
-an edit bundle.
-@end itemize
-
-@noindent In the example above, back references are used to allow conversion of comments from shell-style
-to C-style.
-
diff --git a/docs/reference/promises/files_notes.texinfo b/docs/reference/promises/files_notes.texinfo
deleted file mode 100644
index e69de29bb2..0000000000
diff --git a/docs/reference/promises/guest_environments_example.texinfo b/docs/reference/promises/guest_environments_example.texinfo
deleted file mode 100644
index c2f543f164..0000000000
--- a/docs/reference/promises/guest_environments_example.texinfo
+++ /dev/null
@@ -1,20 +0,0 @@
-
-@verbatim
-
- site1::
-
- "unique_name1"
-
- environment_resources => myresources("2GB","512MB"),
- environment_interface => mymachine("hostname"),
- environment_type => "xen",
- environment_state => "running",
- environment_host => "atlas";
-
- "unique_name2"
-
- environment_type => "xen_network",
- environment_state => "create",
- environment_host => "atlas";
-
-@end verbatim
diff --git a/docs/reference/promises/guest_environments_intro.texinfo b/docs/reference/promises/guest_environments_intro.texinfo
deleted file mode 100644
index 6537f1690c..0000000000
--- a/docs/reference/promises/guest_environments_intro.texinfo
+++ /dev/null
@@ -1,16 +0,0 @@
-
-Guest environment promises describe enclosed computing environments that can
-host physical and virtual machines, solaris zones, grids, clouds or
-other enclosures, including embedded systems. CFEngine will support
-the convergent maintenance of such inner environments in a fixed
-location, with interfaces to an external environment.
-
-CFEngine currently seeks to add convergence properties to existing
-interfaces for automatic self-healing of guest environments. The
-current implementation integrates with @i{libvirt}, supporting host
-virtualization for Xen, KVM, VMWare, etc. Thus CFEngine, running on a
-virtual host, can maintain the state and deployment of virtual guest
-machines defined within the @i{libvirt} framework. Guest environment
-promises are not meant to manage what goes on within the virtual
-guests: for that purpose, you should run CFEngine directly on the
-virtual machine, as if it were any other machine.
diff --git a/docs/reference/promises/guest_environments_notes.texinfo b/docs/reference/promises/guest_environments_notes.texinfo
deleted file mode 100644
index 58679a8e17..0000000000
--- a/docs/reference/promises/guest_environments_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-CFEngine currently provides a convergent interface to @i{libvirt}.
diff --git a/docs/reference/promises/insert_lines_example.texinfo b/docs/reference/promises/insert_lines_example.texinfo
deleted file mode 100644
index 5e9b238947..0000000000
--- a/docs/reference/promises/insert_lines_example.texinfo
+++ /dev/null
@@ -1,39 +0,0 @@
-
-@verbatim
-
-body common control
-
-{
-any::
-
- bundlesequence => {
- example
- };
-}
-
-#######################################################
-
-bundle agent example
-
-{
-files:
-
- "/var/spool/cron/crontabs/root"
-
- edit_line => addline;
-}
-
-#######################################################
-# For the library
-#######################################################
-
-bundle edit_line addline
-
-{
-insert_lines:
-
- "0,5,10,15,20,25,30,35,40,45,50,55 * * * * /var/cfengine/bin/cf-execd -F";
-
-}
-
-@end verbatim
diff --git a/docs/reference/promises/insert_lines_intro.texinfo b/docs/reference/promises/insert_lines_intro.texinfo
deleted file mode 100644
index a0ca163d16..0000000000
--- a/docs/reference/promises/insert_lines_intro.texinfo
+++ /dev/null
@@ -1,19 +0,0 @@
-
-This promise is part of the line-editing model. It inserts lines into
-the file at a specified location. The location is determined by
-body-attributes. The promise object referred to can be a literal line
-of a file-reference from which to read lines.
-
-@cartouche
-@smallexample
-
- insert_lines:
-
- "@var{literal line or file reference}"
-
- location => @var{location_body},
- ...;
-
-@end smallexample
-@end cartouche
-
diff --git a/docs/reference/promises/insert_lines_notes.texinfo b/docs/reference/promises/insert_lines_notes.texinfo
deleted file mode 100644
index 1e75891f5f..0000000000
--- a/docs/reference/promises/insert_lines_notes.texinfo
+++ /dev/null
@@ -1,58 +0,0 @@
-
-By parameterizing the editing bundle, one can make generic and reusable editing bundles.
-
-Note, when inserting multiple lines anchored to a particular place in
-a file, be careful with your intuition. If your intention is to
-insert a set of lines in a given order after a marker, then the
-following is incorrect:
-
-@verbatim
-
-bundle edit_line x
-{
-insert_lines:
-
- "line one" location => myloc;
- "line two" location => myloc;
-}
-
-body location myloc
-
-{
-select_line_matching => "# Right here.*";
-before_after => "after";
-}
-
-@end verbatim
-This will reverse the order of the lines and will not converge, since
-the anchoring after the marker applies independently for each new
-line. This is not a bug, but an error of logic.
-
-What was probably intended was to add multiple ordered lines after the marker,
-which should be a single correlated promise.
-
-@verbatim
-
-bundle edit_line x
-{
-insert_lines:
-
- "line one$(const.n)line two" location => myloc;
-
-}
-
-@end verbatim
-Or:
-@verbatim
-
-bundle edit_line x
-{
-insert_lines:
-
- "line one
-line two" location => myloc;
-
-}
-
-@end verbatim
-
diff --git a/docs/reference/promises/insert_text_example.texinfo b/docs/reference/promises/insert_text_example.texinfo
deleted file mode 100644
index 363354b935..0000000000
--- a/docs/reference/promises/insert_text_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-bundle edit_xml example
- {
- insert_text:
- "text content to be appended to existing text, including whitespace, within specified node"
-
- select_xpath => "/Server/Service/Engine/Host/Alias";
- }
-
-@end verbatim
diff --git a/docs/reference/promises/insert_text_intro.texinfo b/docs/reference/promises/insert_text_intro.texinfo
deleted file mode 100644
index e44c9b9433..0000000000
--- a/docs/reference/promises/insert_text_intro.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-This promise is part of the XML-editing model. It assures that a
-value string, containing the matching substring, will be present
-in the specified node within the XML file. If the substring is not
-found, the default promise is to append the substring at the end of
-the existing value string, within the specified node. The specified
-node is determined by body-attributes. The promise object referred
-to is a literal string of text.
diff --git a/docs/reference/promises/insert_text_notes.texinfo b/docs/reference/promises/insert_text_notes.texinfo
deleted file mode 100644
index 8b7bbdd259..0000000000
--- a/docs/reference/promises/insert_text_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Note that typically, only a single value string, within a single specified
-node, is inserted in each @code{insert_text} promise (you may of course
-have multiple promises that each insert a value string).
diff --git a/docs/reference/promises/insert_tree_example.texinfo b/docs/reference/promises/insert_tree_example.texinfo
deleted file mode 100644
index 1ef47a4a6e..0000000000
--- a/docs/reference/promises/insert_tree_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-bundle edit_xml example
- {
- insert_tree:
- "cfe_alias"
-
- select_xpath => "/Server/Service/Engine";
- }
-
-@end verbatim
diff --git a/docs/reference/promises/insert_tree_intro.texinfo b/docs/reference/promises/insert_tree_intro.texinfo
deleted file mode 100644
index 1fab44643e..0000000000
--- a/docs/reference/promises/insert_tree_intro.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-This promise is part of the XML-editing model. It assures that a
-balanced XML tree, containing the matching subtree, will be present
-in the specified node within the XML file. If the subtree is not
-found, the default promise is to insert the tree into the specified
-node. The specified node is determined by body-attributes. The
-promise object referred to is a literal string representation of a
-balanced XML tree.
diff --git a/docs/reference/promises/insert_tree_notes.texinfo b/docs/reference/promises/insert_tree_notes.texinfo
deleted file mode 100644
index dbb77ee897..0000000000
--- a/docs/reference/promises/insert_tree_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Note that typically, only a single tree, within a single specified node,
-is inserted in each @code{insert_tree} promise (you may of course have
-multiple promises that each insert a tree).
diff --git a/docs/reference/promises/interfaces_example.texinfo b/docs/reference/promises/interfaces_example.texinfo
deleted file mode 100644
index d81b98b953..0000000000
--- a/docs/reference/promises/interfaces_example.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-For future use.
diff --git a/docs/reference/promises/interfaces_intro.texinfo b/docs/reference/promises/interfaces_intro.texinfo
deleted file mode 100644
index a30fe72933..0000000000
--- a/docs/reference/promises/interfaces_intro.texinfo
+++ /dev/null
@@ -1,21 +0,0 @@
-
-Interfaces promises describe the configurable aspects relating to
-network interfaces. Most workstations and servers have only a single
-network interface, but routers and multi-homed hosts often have
-multiple interfaces. Interface promises include attributes such as the
-IP address identity, assumed netmask and routing policy in the case of
-multi-homed hosts. For virtual machines and hosts, the list of
-interfaces can be quite large.
-
-@cartouche
-@smallexample
-
- interfaces:
-
- "@var{interface name}"
-
- tcp_ip => @var{tcp_ip_body},
- ...;
-
-@end smallexample
-@end cartouche
diff --git a/docs/reference/promises/interfaces_notes.texinfo b/docs/reference/promises/interfaces_notes.texinfo
deleted file mode 100644
index d81b98b953..0000000000
--- a/docs/reference/promises/interfaces_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-For future use.
diff --git a/docs/reference/promises/measurements_example.texinfo b/docs/reference/promises/measurements_example.texinfo
deleted file mode 100644
index 64efb35d3c..0000000000
--- a/docs/reference/promises/measurements_example.texinfo
+++ /dev/null
@@ -1,47 +0,0 @@
-
-@verbatim
-
- # Follow a special process over time
- # using CFEngine's process cache to avoid resampling
-
- "/var/cfengine/state/cf_rootprocs"
-
- handle => "monitor_self_watch",
- stream_type => "file",
- data_type => "int",
- history_type => "weekly",
- units => "kB",
- match_value => proc_value(".*cf-monitord.*",
- "root\s+[0-9.]+\s+[0-9.]+\s+[0-9.]+\s+[0-9.]+\s+([0-9]+).*");
-
-
- # Discover disk device information
-
- "/bin/df"
-
- handle => "free_diskspace_watch",
- stream_type => "pipe",
- data_type => "slist",
- history_type => "static",
- units => "device",
- match_value => file_systems;
- # Update this as often as possible
-
-}
-
-##########################################################
-
-body match_value proc_value(x,y)
-{
-select_line_matching => "$(x)";
-extraction_regex => "$(y)";
-}
-
-body match_value file_systems
-{
-select_line_matching => "/.*";
-extraction_regex => "(.*)";
-}
-
-
-@end verbatim
diff --git a/docs/reference/promises/measurements_intro.texinfo b/docs/reference/promises/measurements_intro.texinfo
deleted file mode 100644
index f4becc3437..0000000000
--- a/docs/reference/promises/measurements_intro.texinfo
+++ /dev/null
@@ -1,41 +0,0 @@
-
-@i{These features are available only in Enterprise versions of CFEngine.}
-
-CFEngine's monitoring component @code{cf-monitord} records a number
-of performance data about the system by default. These include
-process counts, service traffic, load average and cpu utilization and
-temperature when available.
-
-CFEngine Nova extends this in two ways. First it adds a three year
-trend summary based any `shift'-averages. Second, it adds customizable
-promises to monitor or log very specific user data through a
-generic interface. The end result is to either generate a periodic
-time series, like the above mentioned values, or to log the results to
-custom-defined reports.
-
-
-CFEngine Nova adds a new promise type in bundles for the monitoring
-agent. These are written just like all other promises within a bundle
-destined for the agent concerned (however, you do not need to add them
-to the @code{bundlesequence} -- they are executed by @code{cf-monitord}
-because they are bundles of type @code{monitor}). In this case:
-
-@verbatim
-bundle monitor watch
-
-{
-measurements:
-
- # promises ...
-
-}
-
-@end verbatim
-
-It is important to specificy a promise @code{handle} for measurement
-promises, as the names defined in the handle are used to determine the
-name of the log file or variable to which data will be reported. Log
-files are created under @file{WORKDIR/state}. Data that have no history
-type are stored in a special variable context called @samp{mon}, analogous
-to the system variables in @samp{sys}. Thus the values may be used
-in other promises in the form @code{$(mon.handle)}.
diff --git a/docs/reference/promises/measurements_notes.texinfo b/docs/reference/promises/measurements_notes.texinfo
deleted file mode 100644
index b5afd12d7f..0000000000
--- a/docs/reference/promises/measurements_notes.texinfo
+++ /dev/null
@@ -1,132 +0,0 @@
-
-@noindent @b{Notes:}
-
-The general pattern of these promises is to decide the source of the
-information either file or pipe, determine the data type (integer,
-string etc.), specify a pattern to match the result in the file stream
-and then specify what to do with the result afterwards.
-
-@noindent @b{Standard measurements:}
-
-The @code{cf-monitord} service monitors a number of variables as
-standard on Unix and Windows systems. Windows is fundamentally different
-from Unix and currently has less support for out-of-the-box probes.
-
-@enumerate
-@item users:
-Users logged in
-@item rootprocs:
-Privileged system processes
-@item otherprocs:
-Non-privileged process
-@item diskfree:
-Free disk on / partition
-@item loadavg:
-% kernel load utilization
-@item netbiosns_in:
-netbios name lookups (in)
-@item netbiosns_out:
-netbios name lookups (out)
-@item netbiosdgm_in:
-netbios name datagrams (in)
-@item netbiosdgm_out:
-netbios name datagrams (out)
-@item netbiosssn_in:
-netbios name sessions (in)
-@item netbiosssn_out:
-netbios name sessions (out)
-@item irc_in:
-IRC connections (in)
-@item irc_out:
-IRC connections (out)
-@item cfengine_in:
-CFEngine connections (in)
-@item cfengine_out:
-CFEngine connections (out)
-@item nfsd_in:
-nfs connections (in)
-@item nfsd_out:
-nfs connections (out)
-@item smtp_in:
-smtp connections (in)
-@item smtp_out:
-smtp connections (out)
-@item www_in:
-www connections (in)
-@item www_out:
-www connections (out)
-@item ftp_in:
-ftp connections (in)
-@item ftp_out:
-ftp connections (out)
-@item ssh_in:
-ssh connections (in)
-@item ssh_out:
-ssh connections (out)
-@item wwws_in:
-wwws connections (in)
-@item wwws_out:
-wwws connections (out)
-@item icmp_in:
-ICMP packets (in)
-@item icmp_out:
-ICMP packets (out)
-@item udp_in:
-UDP dgrams (in)
-@item udp_out:
-UDP dgrams (out)
-@item dns_in:
-DNS requests (in)
-@item dns_out:
-DNS requests (out)
-@item tcpsyn_in:
-TCP sessions (in)
-@item tcpsyn_out:
-TCP sessions (out)
-@item tcpack_in:
-TCP acks (in)
-@item tcpack_out:
-TCP acks (out)
-@item tcpfin_in:
-TCP finish (in)
-@item tcpfin_out:
-TCP finish (out)
-@item tcpmisc_in:
-TCP misc (in)
-@item tcpmisc_out:
-TCP misc (out)
-@item webaccess:
-Webserver hits
-@item weberrors:
-Webserver errors
-@item syslog:
-New log entries (Syslog)
-@item messages:
-New log entries (messages)
-@item temp0:
-CPU Temperature core 0
-@item temp1:
-CPU Temperature core 1
-@item temp2:
-CPU Temperature core 2
-@item temp3:
-CPU Temperature core 3
-@item cpu:
-%CPU utilization (all)
-@item cpu0:
-%CPU utilization core 0
-@item cpu1:
-%CPU utilization core 1
-@item cpu2:
-%CPU utilization core 2
-@item cpu3:
-%CPU utilization core 3
-@end enumerate
-
-Slots with a higher number are used for custom measurement promises in CFEngine Nova.
-
-These values collected and analysed by @code{cf-monitord} are
-transformed into agent variables in the @code{$(mon.@var{name})}
-context.
-
-@noindent @b{Measurement promise syntax:}
diff --git a/docs/reference/promises/meta_example.texinfo b/docs/reference/promises/meta_example.texinfo
deleted file mode 100644
index ad30121b67..0000000000
--- a/docs/reference/promises/meta_example.texinfo
+++ /dev/null
@@ -1,21 +0,0 @@
-
-@verbatim
-
-bundle agent example
-
-{
-meta:
-
- "bundle_version" string => "1.2.3";
- "works_with_cfengine" string => "3.4.0";
-
-reports:
-
- cfengine_3::
-
- "Not a local variable: $(bundle_version)";
- "Meta data (variable): $(example_meta.bundle_version)";
-
-}
-
-@end verbatim
diff --git a/docs/reference/promises/meta_intro.texinfo b/docs/reference/promises/meta_intro.texinfo
deleted file mode 100644
index d1776ac183..0000000000
--- a/docs/reference/promises/meta_intro.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-
-Meta-data promises have no internal function. They are intended to be
-used to represent arbitrary information about promise
-bundles. Formally, meta promises are implemented as variables, and the
-values map to a variable context called @var{bundlename_meta}, and
-therefore the values can be used as variables and will appear in
-Enterprise variable reports.
diff --git a/docs/reference/promises/meta_notes.texinfo b/docs/reference/promises/meta_notes.texinfo
deleted file mode 100644
index 02e798351f..0000000000
--- a/docs/reference/promises/meta_notes.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-@i{History}: Was introduced in 3.4.0, Enterprise 3.0.0 (2012)
-
diff --git a/docs/reference/promises/methods_example.texinfo b/docs/reference/promises/methods_example.texinfo
deleted file mode 100644
index 2f09c9e7da..0000000000
--- a/docs/reference/promises/methods_example.texinfo
+++ /dev/null
@@ -1,34 +0,0 @@
-
-@verbatim
-
-
-bundle agent example
-{
-vars:
-
- "userlist" slist => { "mark", "jeang", "jonhenrik", "thomas", "eben" };
-
-methods:
-
- "any" usebundle => subtest("$(userlist)");
-
-}
-
-###########################################
-
-bundle agent subtest(user)
-
-{
-commands:
-
- "/bin/echo Fix $(user)";
-
-reports:
-
- linux::
-
- "Finished doing stuff for $(user)";
-}
-
-
-@end verbatim
diff --git a/docs/reference/promises/methods_intro.texinfo b/docs/reference/promises/methods_intro.texinfo
deleted file mode 100644
index 722e2c4e7f..0000000000
--- a/docs/reference/promises/methods_intro.texinfo
+++ /dev/null
@@ -1,27 +0,0 @@
-
-Methods are compound promises that refer to whole bundles of promises.
-Methods may be parameterized. Methods promises are written in a form
-that is ready for future development. The promiser object is an
-abstract identifier that refers to a collection (or pattern) of lower
-level objects that are affected by the promise-bundle. Since the use
-of these identifiers is for the future, you can simply use any string
-here for the time being.
-
-@cartouche
-@smallexample
-
- methods:
-
- "any"
-
- usebundle => @var{method_id}("parameter",...);
-
-@end smallexample
-@end cartouche
-
-Methods are useful for encapsulating repeatedly used configuration
-issues and iterating over parameters.
-
-In CFEngine 2 methods referred to separate sub-programs executed
-as separate processes. Methods are now implemented as bundles
-that are run inline.
diff --git a/docs/reference/promises/methods_notes.texinfo b/docs/reference/promises/methods_notes.texinfo
deleted file mode 100644
index b9fc6873ab..0000000000
--- a/docs/reference/promises/methods_notes.texinfo
+++ /dev/null
@@ -1,30 +0,0 @@
-
-Methods offer powerful ways to encapsulate multiple issues pertaining
-to a set of parameters.
-
-Because a method is just an encapsulation, there is a subtlety about
-how to interpret a successful method invocation. Before version 3.1.0,
-a method was considered repaired if executed (like @code{commands}),
-however this led to unnecessary logging of executions, even if not
-actual encapsulated promise was kept. In version 3.1.0 this has been
-changed so that a method promise is considered kept if the method
-is expanded. A method promise is thus never considered repaired.
-
-Starting from version 3.1.0, methods may be specified using variables.
-Care should be exercised when using this approach. In order to make
-the function call uniquely classified, CFEngine requires the promiser
-to contain the variable name of the method if the variable is a list.
-
-@verbatim
-bundle agent default
-{
-vars:
- "m" slist => { "x", "y" };
- "p" string => "myfunction";
-
-methods:
- "set of $(m)" usebundle => $(m) ("one");
- "any" usebundle => $(p)("two");
-
-}
-@end verbatim
diff --git a/docs/reference/promises/outputs_example.texinfo b/docs/reference/promises/outputs_example.texinfo
deleted file mode 100644
index f17dc64b4f..0000000000
--- a/docs/reference/promises/outputs_example.texinfo
+++ /dev/null
@@ -1,41 +0,0 @@
-
-@verbatim
-
-outputs:
-
- "run_agent"; # Promise handle, verbose (default) output
-
- "web_server" # Bundle handle, inform output
- output_level => "inform",
- promiser_type => "bundle";
-
-@end verbatim
-
-A very handy paradigm is to include outputs promises in every bundle, and
-guard them with classes. For example:
-
-@verbatim
-
-bundle agent some_function
-{
-vars:
- ...
-classes:
- ...
-outputs:
- debug_some_function::
- "some_function"
- output_level => "verbose",
- promiser_type => "bundle";
-files:
- ...
-}
-
-@end verbatim
-
-You can then execute your promises normally with no extra output, but should
-you wish to temporarily enable debugging, you can simply do so from the
-command line by specifying @samp{-D debug_some_function}. You can also supply
-multiple arguments to @samp{-D} to debug multiple bundles. Of course, you can
-also provide much finer-grained control by creating outputs promises on
-specific promise handles.
diff --git a/docs/reference/promises/outputs_intro.texinfo b/docs/reference/promises/outputs_intro.texinfo
deleted file mode 100644
index 4b23ce0a8f..0000000000
--- a/docs/reference/promises/outputs_intro.texinfo
+++ /dev/null
@@ -1,15 +0,0 @@
-
-Outputs promises allow promises to make meta-promises about their output
-levels. More simply, you can switch on @samp{verbose} or @samp{inform}
-level output to named promises, or whole bundles for debugging
-purposes.
-
-If you use the @samp{-I} or @samp{-v} command line options, then CFEngine
-will generate informative or verbose output for all the promises it is
-processing. This can be a daunting collection of data when dealing with even
-a medium-sized set of promises.
-
-Output promises enable you to selectively debug individually named promises
-(or bundles), thus eliminating the need for scanning unrelated CFEngine
-output.
-
diff --git a/docs/reference/promises/outputs_notes.texinfo b/docs/reference/promises/outputs_notes.texinfo
deleted file mode 100644
index 012fc271c3..0000000000
--- a/docs/reference/promises/outputs_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-The default behaviour is to print verbose output for listed promise
-handles, @xref{handle in *}, for bundle names.
-
-@b{History} This was introduced in Nova version 1.1.3 (2010), Community version 3.4.0 (2012)
-
diff --git a/docs/reference/promises/packages_example.texinfo b/docs/reference/promises/packages_example.texinfo
deleted file mode 100644
index 5badadd29c..0000000000
--- a/docs/reference/promises/packages_example.texinfo
+++ /dev/null
@@ -1,26 +0,0 @@
-
-@verbatim
-
-bundle agent packages
-{
-vars:
-
- # Test the simplest case -- leave everything to the yum smart manager
-
- "match_package" slist => {
- "apache2",
- "apache2-mod_php5",
- "apache2-prefork",
- "php5"
- };
-packages:
-
- "$(match_package)"
-
- package_policy => "add",
- package_method => yum;
-
-}
-
-@end verbatim
-
diff --git a/docs/reference/promises/packages_intro.texinfo b/docs/reference/promises/packages_intro.texinfo
deleted file mode 100644
index 46e941ec1b..0000000000
--- a/docs/reference/promises/packages_intro.texinfo
+++ /dev/null
@@ -1,249 +0,0 @@
-
-@cartouche
-@verbatim
-
- vars:
-
- "match_package" slist => {
- "apache2",
- "apache2-mod_php5",
- "apache2-prefork",
- "php5"
- };
- packages:
-
- "$(match_package)"
-
- package_policy => "add",
- package_method => yum;
-
-@end verbatim
-@end cartouche
-
-
-Software packaging is a core paradigm in operating system release
-management today, and CFEngine supports a generic approach to
-integration with native operating support for packaging. Package
-promises allow CFEngine to make promises the state of software
-packages @i{conditionally}, given the assumption that a native package
-manager will perform the actual manipulations. Since no agent can make
-unconditional promises about another, this is the best that can be
-achieved.
-
-Packages are treated as black-boxes with three labels:
-
-@itemize @bullet
-@item A package name.
-@item A version string.
-@item An architecture name.
-@end itemize
-
-Package managers are treated as black boxes that may support some or all of the
-following promise types:
-
-@itemize @bullet
-@item List installed packages
-@item Add packages
-@item Delete packages
-@item Reinstall (repair) packages
-@item Update packages
-@item Patch packages
-@item Verify packages
-@end itemize
-
-If these services are promised by a package manager, @code{cf-agent}
-promises to use the service and encapsulate it within the overall
-CFEngine framework. It is possible to set classes based on the return
-code of a package-manager command in a very flexible way. See the
-@code{kept_returncodes}, @code{repaired_returncodes} and
-@code{failed_returncodes} attributes.
-
-
-@b{Domain knowledge}
-
-CFEngine does not maintain operating system specific expert knowledge
-internally, rather it uses a generic model for dealing with promises about
-packages (which depend on the behaviour of an external package manager).
-The approach is to define package system details in body-constraints that
-can be written once and for all, for each package system.
-
-Package promises are like @code{commands} promises in the sense that
-CFEngine promises nothing about the outcome of executing a
-command. All it can promise is to interface with it, starting it and
-using the results in good faith. Packages are basically `outsourced',
-to invoke IT parlance.
-
-The possibility of a CFEngine package format that enables more guaranteeable
-behaviour for special purposes has not been excluded for the future,
-but in any case @code{cf-agent} must support native package formats
-used by operating system maintainers as these are a core part of modern
-operating systems.
-
-@b{Behaviour}
-
-A package promise consists of a name, a version and an architecture, @i{(n,v,a)},
-and behaviour to be promised about packages that match criteria based on these.
-The components @i{(n,v,a)} can be determined in one of two different ways:
-
-@itemize
-@item They may be specified independently, e.g.
-
-@verbatim
-packages:
-
- "mypackage"
-
- package_policy => "add",
- package_method => rpm,
- package_select => ">=",
- package_architectures => { "x86_64", "i586" },
- package_version => "1.2.3";
-
-@end verbatim
-
-@item They may be extracted from a package identifier (promiser) or
-filename, using pattern matching. For example, a promiser
-``7-Zip-4.50-x86_64.msi'' and a package_method containing the following.
-
-@verbatim
- package_name_regex => "^(\S+)-(\d+\.?)+";
- package_version_regex => "^\S+-((\d+\.?)+)";
- package_arch_regex => "^\S+-[\d\.]+-(.*).msi";
-@end verbatim
-
-@end itemize
-
-When scanning a list of installed packages different managers present the information
-@i{(n,v,a)} in quite different forms and pattern extraction is necessary. When making a
-promise about a specific package, the CFEngine user may choose one or the other model.
-
-
-@b{Smart and dumb package systems}
-
-Package managers vary enormously in their capabilities and in the
-kinds of promises they make. There are broadly two types
-
-@itemize
-@item Smart package systems tha resolve dependencies and require only a symbolic package name.
-@item Dumb package managers that do not resolve dependencies and need filename input.
-@end itemize
-
-
-
-Normal ordering for packages is the following:
-
-@itemize @bullet
-@item Delete
-@item Add
-@item Update
-@item Patch
-@end itemize
-
-
-@b{Promise repair logic}
-
-We can discuss package promise repair in the following table.
-
-Identified package matches version constraints
-@multitable @columnfractions .20 .80
-@item
- add
- @tab
- never
-@item
- delete
- @tab
- =,>=,<=
-@item
- reinstall
- @tab
- =,>=,<=
-@item
- upgrade
- @tab
- =,>=,<=
-@item
- patch
- @tab
- =,>=,<=
-@end multitable
-
-Identified package matched by name, but not version
-@multitable @columnfractions .20 .40 .40
-@headitem
- Command
- @tab
- Dumb manager
- @tab
- Smart manager
-@item
- add
- @tab
- unable
- @tab
- Never
-@item
- delete
- @tab
- unable
- @tab
- Attempt deletion
-@item
- reinstall
- @tab
- unable
- @tab
- Attempt delete/add
-@item
- upgrade
- @tab
- unable
- @tab
- Upgrade if capable
-@item
- patch
- @tab
- unable
- @tab
- Patch if capable
-@end multitable
-
-Package not installed
-@multitable @columnfractions .20 .40 .40
-@headitem
- Command
- @tab
- Dumb manager
- @tab
- Smart manager
-@item
- add
- @tab
- Attempt to install named
- @tab
- Install any version
-@item
- delete
- @tab
- unable
- @tab
- unable
-@item
- reinstall
- @tab
- Attempt to install named
- @tab
- unable
-@item
- upgrade
- @tab
- unable
- @tab
- unable
-@item
- patch
- @tab
- unable
- @tab
- unable
-@end multitable
diff --git a/docs/reference/promises/packages_notes.texinfo b/docs/reference/promises/packages_notes.texinfo
deleted file mode 100644
index bd453c51ac..0000000000
--- a/docs/reference/promises/packages_notes.texinfo
+++ /dev/null
@@ -1,54 +0,0 @@
-
-Packages promises can be very simple if the package manager is of the
-smart variety that handles details for you. If you need to specify
-architecture and version numbers of packages, this adds some
-complexity, but the options are flexible and designed for maximal
-adaptability.
-
-@noindent @b{Patching}
-
-Some package systems also support the idea of `patches'. These might
-be formally different objects to packages. A patch might contain
-material for several packages and be numbered differently.
-When you select patching-policy the package name (promiser) can be
-a regular expression that will match possible patch names, otherwise
-identifying specific patches can be cumbersome.
-
-Note that patching is a subtle business. There is no simple way using
-the patch settings to install `all new system patches'. Here's why:
-
-If we specify the name of a patch, then CFEngine will try to see if it
-exists and/or is installed. If it exists in the pending list, it will
-be installed. If it exists in the installed list it will not be
-installed. Now consider the pattern @samp{.*}. This will match any
-installed package, so CFEngine will assume the relevant patch has been
-installed already. On the other hand, the pattern @samp{no match}
-will not match an installed patch, but it will not match a named patch
-either.
-
-Some systems provide a command to do this, which can be specified
-without specific patch arguments. If so, that command can be called
-periodically under @code{commands}. The main purposes of patching
-body items are:
-
-@itemize
-@item To install specific named patches in a controlled manner.
-@item To generate reports of available and installed patches during
-system reporting.
-@end itemize
-
-@noindent @b{Installers without package/patch arguments}
-
-CFEngine supports the syntax @samp{$} at the end of a command to mean
-that no package name arguments should be used or appended after the
-dollar. This is because some commands require a list of packages,
-while others require an empty list. The default behaviour is to try to
-append the name of one or more packages to the command, depending on
-whether the policy is for individual or bulk installation.
-
-@noindent @b{Default package method}
-
-As of core 3.3.0, if no @code{package_method} is defined, CFEngine will
-look for a method called @samp{generic}. Such a method is defined in
-the standard library for supported operating systems.
-
diff --git a/docs/reference/promises/processes_example.texinfo b/docs/reference/promises/processes_example.texinfo
deleted file mode 100644
index f366761e65..0000000000
--- a/docs/reference/promises/processes_example.texinfo
+++ /dev/null
@@ -1,39 +0,0 @@
-
-@verbatim
-
-bundle agent example
-{
-processes:
-
- ".*"
-
- process_count => anyprocs,
- process_select => proc_finder;
-
-reports:
-
- any_procs::
-
- "Found processes out of range";
-}
-
-########################################################
-
-body process_select proc_finder
-
-{
-# Processes started between 5.5 hours and 20 minutes ago
-stime_range => irange(ago(0,0,0,5,30,0),ago(0,0,0,0,20,0));
-process_result => "stime";
-}
-
-########################################################
-
-body process_count anyprocs
-
-{
-match_range => "0,0";
-out_of_range_define => { "any_procs" };
-}
-
-@end verbatim
diff --git a/docs/reference/promises/processes_intro.texinfo b/docs/reference/promises/processes_intro.texinfo
deleted file mode 100644
index 2fe8b092b7..0000000000
--- a/docs/reference/promises/processes_intro.texinfo
+++ /dev/null
@@ -1,58 +0,0 @@
-
-Process promises refer to items in the system process table. Note that
-this is not the same as commands (which are instructions that CFEngine will
-execute). A process
-is a command in some state of execution (with a Process Control
-Block). Promiser objects here are patterns that match line fragments
-in the system process table (that is, the patterns are unanchored,
-@pxref{Anchored vs. unanchored regular expressions}).
-@i{Take care to note that process table formats differ between operating
-systems, and the use of simple patterns such as program-names is recommended.
-For more sophisticated matches, users should use the @code{process_select}
-feature.} For example, on many systems, the process pattern @code{"^cp"}
-may not match any processes, even though @code{"cp"} is running! This is
-because the process table entry may list @code{"/bin/cp"}. However, the
-process pattern @code{"cp"} will also match a process containing @code{"scp"},
-so take care not to oversimplify your patterns (the PCRE pattern anchors
-@code{"\b"} and @code{"\B"} may prove very useful to you).
-
-@cartouche
-@smallexample
-
- processes:
-
- "@var{regex contained in process line}"
-
- process_select => @var{process_filter_body},
- restart_class => "activation class for process",
- ..;
-
-@end smallexample
-@end cartouche
-
-In CFEngine 2 there was a restart clause for directly executing a
-command to restart a process. In CFEngine 3 there is instead
-a class to activate. You must then desribe a @code{command} in that
-class to restart the process.
-
-@verbatim
-
-commands:
-
- restart_me::
-
- "/path/executable" ... ;
-
-@end verbatim
-This rationalizes complex restart-commands and avoids unnecessary overlap
-between @code{processes} and @code{commands}.
-
-The @code{process_stop} is also arguably a command, but it should be
-an ephemeral command that does not lead to a persistent process. It is
-intended only for commands of the form @samp{/etc/inetd service stop}, not
-for processes that persist. Processes are restarted at the end of a bundle's
-execution, but stop commands are executed immediately.
-
-Note: @code{process_select} was previously called process @code{filters} in
-CFEngine 2 and earlier.
-
diff --git a/docs/reference/promises/processes_notes.texinfo b/docs/reference/promises/processes_notes.texinfo
deleted file mode 100644
index 4fe2f2e2bf..0000000000
--- a/docs/reference/promises/processes_notes.texinfo
+++ /dev/null
@@ -1,151 +0,0 @@
-
-In CFEngine 3 we have
-
-@smallexample
- processes
- commands
-@end smallexample
-
-@noindent so that there is a clean separation between detection (promises
-about the process table) and certain repairs (promises to execute
-commands that start processes). Let's see why.
-
-Executions are about jobs, services, scripts etc. They are properties
-of an executable file. The referring `promiser' is a file
-object. On the other hand a process is a property of a "process
-identifier" which is a kernel instantiation, a quite different object
-altogether. So it makes sense to say that
-
-@itemize
-@item
-A "PID" (which is not an executable) promises to be reminded of a signal, e.g.
-@smallexample
- kill signal pid
-@end smallexample
-@item
-An "command" promises to start or stop itself with a parameterized specification.
-@smallexample
- exec command argument1 argument2 ...
-@end smallexample
-@end itemize
-
-Neither the file nor the pid necessarily promise to respond to these activations, but they
-are nonetheless physically meaningful phenomena or attributes associated with these objects.
-
-@itemize
-@item
-Executable files do not listen for signals as they have no active state.
-@item
-PIDs do not run themselves or stop themselves with new arguments, but they can use signals as they are running.
-@end itemize
-
-Executions lead to processes for the duration of their lifetime, so these two issues
-are related, although the promises themselves are not.
-
-@*
-@noindent @b{Services verus processes}:
-@*
-
-A service is an abstraction that requires processes to run and files
-to be configured. It makes a lot of sense to wrap services in modular
-bundles. Starting and stopping a service can be handled in at least two ways.
-Take the web service as an example.
-
-We can start the service by promising an execution of a daemon (e.g. @code{httpd}).
-Normally this execution does not terminate without intervention. We can
-terminate it in one of two ways:
-
-@itemize
-@item
-Using a process signal, by promising a signal to processes matching a certain pid search
-@item
-Using an execution of a termination command, e.g. @samp{/etc/init.d/apache stop}.
-@end itemize
-
-The first case makes sense if we need to qualify the termination by
-searching for the processes. The processes section of a CFEngine 3
-policy includes a control promise to search for matching processes.
-If matches are found, signals can be sent to precisely each specific process.
-
-Classes can also be defined, in principle triggering an execution of
-the stop script, but then the class refers only to the presence of
-matching pids, not to the individual pids concerned. So it becomes
-the responsibility of the execution to locate and interact with the
-pids necessary.
-
-@*
-@noindent @b{Want it running?}:
-@*
-
-How do we say simply that we want a service running?
-In the agent control promises, we could check each service
-individually.
-@verbatim
-bundlesequence => { Update, Service("apache"), Service("nfsd") };
-@end verbatim
-or
-@verbatim
-bundlesequence => { Update, @(globals.all_services) };
-@end verbatim
-
-The bundle for this can look like this:
-@verbatim
-bundle agent Service(service)
-{
-processes:
-
- "$(service)"
-
- process_count => up("$(service)");
-
-commands:
-
- "$daemons[$(service)]"
-
- ifvarclass => "$(service)_up",
- args => "$args[$(service)]";
-
-}
-@end verbatim
-
-An alternative would be self-contained:
-
-@verbatim
-body common control
-{
- bundlesequence => { "Service" };
-}
-
-bundle agent Service
-{
-vars:
-
- "service" slist => { "apache", "nfsd", "bind" };
-
-processes:
-
- "$(service)"
-
- process_count => up("$(service)");
-
-commands:
-
- "$daemons[$(service)]"
-
- ifvarclass => "$(service)_up",
- args => "$args[$(service)]";
-
-}
-
-######################
-# Parameterized body
-######################
-
-body process_count up(s)
-
-{
-match_range => "0,10";
-out_of_range_define => { "$(s)_up" };
-}
-
-@end verbatim
diff --git a/docs/reference/promises/replace_patterns_example.texinfo b/docs/reference/promises/replace_patterns_example.texinfo
deleted file mode 100644
index e875dd30b1..0000000000
--- a/docs/reference/promises/replace_patterns_example.texinfo
+++ /dev/null
@@ -1,19 +0,0 @@
-
-@verbatim
-
-bundle edit_line upgrade_cfexecd
-{
- replace_patterns:
-
- "cfexecd" replace_with => value("cf-execd");
-}
-
-########################################
-
-body replace_with value(x) # defined in cfengine_stdlib.cf
-{
-replace_value => "$(x)";
-occurrences => "all";
-}
-
-@end verbatim
diff --git a/docs/reference/promises/replace_patterns_intro.texinfo b/docs/reference/promises/replace_patterns_intro.texinfo
deleted file mode 100644
index 5656ffa99b..0000000000
--- a/docs/reference/promises/replace_patterns_intro.texinfo
+++ /dev/null
@@ -1,17 +0,0 @@
-
-This promise refers to arbitrary text patterns in a file. The pattern
-is expressed as a PCRE regular expression.
-
-@cartouche
-@smallexample
-
- replace_patterns:
-
- "@var{search pattern}"
-
- replace_with => @var{replace_body},
- ...;
-
-@end smallexample
-@end cartouche
-
diff --git a/docs/reference/promises/replace_patterns_notes.texinfo b/docs/reference/promises/replace_patterns_notes.texinfo
deleted file mode 100644
index c060bd74c6..0000000000
--- a/docs/reference/promises/replace_patterns_notes.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-This is a straightforward search and replace function.
-Only the portion of the line that matches the pattern in the promise will be
-replaced - the remainder of the line will not be affected. You can also use
-PCRE lookbehind and lookahead patterns to restrict the lines upon which the
-pattern will match.
-
-@b{NOTE:} In @code{replace_patterns} promises, the regular expression may
-match a line fragment, that is, it is unanchored,
-@xref{Anchored vs. unanchored regular expressions}.
diff --git a/docs/reference/promises/reports_example.texinfo b/docs/reference/promises/reports_example.texinfo
deleted file mode 100644
index fe801962c9..0000000000
--- a/docs/reference/promises/reports_example.texinfo
+++ /dev/null
@@ -1,18 +0,0 @@
-
-@verbatim
-
-bundle agent report
-{
-reports:
-
- linux::
-
- "/etc/passwd except $(const.n)"
-
- # printfile => pr("/etc/passwd","5");
-
- showstate => { "otherprocs", "rootprocs" };
-
-}
-
-@end verbatim
diff --git a/docs/reference/promises/reports_intro.texinfo b/docs/reference/promises/reports_intro.texinfo
deleted file mode 100644
index 239ac98d4f..0000000000
--- a/docs/reference/promises/reports_intro.texinfo
+++ /dev/null
@@ -1,28 +0,0 @@
-
-Reports promises simply print messages. Outputting a message without
-qualfication can be a `dangerous' operation. In a large installation
-it could unleash an avalanche of messaging. For that reason reports
-promises are not allowed to be in the class @samp{any}; they must
-be in a more specific class -- this is not a fool-proof protection
-but it generally weeds out simple carelessness.
-
-@cartouche
-@smallexample
-
- reports:
-
- "@var{literal string or file refererence}",
-
- printfile => @var{printfile_body},
- ...;
-
-@end smallexample
-@end cartouche
-
-
-Messages outputted from report promises are prefixed with the letter
-@samp{R} to distinguish them from other output, e.g. from @code{commands}.
-
-
-In CFEngine 2 reporting was performed with @code{alerts}. The phrase
-alerts seems too strong and has been replaced by @code{reports}.
diff --git a/docs/reference/promises/reports_notes.texinfo b/docs/reference/promises/reports_notes.texinfo
deleted file mode 100644
index 139597f9cb..0000000000
--- a/docs/reference/promises/reports_notes.texinfo
+++ /dev/null
@@ -1,2 +0,0 @@
-
-
diff --git a/docs/reference/promises/roles_example.texinfo b/docs/reference/promises/roles_example.texinfo
deleted file mode 100644
index 746511129f..0000000000
--- a/docs/reference/promises/roles_example.texinfo
+++ /dev/null
@@ -1,14 +0,0 @@
-
-@verbatim
-
-bundle server access_rules()
-
-{
-roles:
-
- # Allow mark
-
- "Myclass_.*" authorize => { "mark" };
-}
-
-@end verbatim
diff --git a/docs/reference/promises/roles_intro.texinfo b/docs/reference/promises/roles_intro.texinfo
deleted file mode 100644
index 4b5b7f5db0..0000000000
--- a/docs/reference/promises/roles_intro.texinfo
+++ /dev/null
@@ -1,29 +0,0 @@
-
-
-Roles promises are server-side decisions about which users are allowed
-to define soft-classes on the server's system during remote invocation
-of @code{cf-agent}. This implements a form of Role Based Access
-Control (RBAC) for pre-assigned class-promise bindings. The user names
-cited must be attached to trusted public keys in order to be accepted.
-The regular expression must match the entire name (that is, they are
-anchored, @pxref{Anchored vs. unanchored regular expressions}).
-
-@cartouche
-@smallexample
-
- roles:
-
- "@var{regex}"
-
- authorize => @{ "@var{usernames}", ... @};
-
-@end smallexample
-@end cartouche
-
-@i{It is worth re-iterating here that it is not possible to send
-commands or modify promise definitions by remote access. At best users
-may try to send classes when using @code{cf-runagent} in order to
-activate sleeping promises. This mechanism limits their ability to
-do this}.
-
-
diff --git a/docs/reference/promises/roles_notes.texinfo b/docs/reference/promises/roles_notes.texinfo
deleted file mode 100644
index a4ca09aed2..0000000000
--- a/docs/reference/promises/roles_notes.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-In this example user @samp{mark} is granted permission to remotely
-activate classes matching the regular expression when @samp{Mark_.*} using the
-@code{cf-runagent} to activate CFEngine. In this way one can
-implement a form of Role Based Access Control (RBAC), provided
-users do not have privileged access on the host directly.
diff --git a/docs/reference/promises/services_example.texinfo b/docs/reference/promises/services_example.texinfo
deleted file mode 100644
index 8cf0e450dd..0000000000
--- a/docs/reference/promises/services_example.texinfo
+++ /dev/null
@@ -1,24 +0,0 @@
-
-@verbatim
-
-bundle agent example
-{
-services:
-
- "Dhcp"
- service_policy => "start",
- service_dependencies => { "Alerter", "W32Time" },
- service_method => winmethod;
-}
-
-########################################################
-
-body service_method winmethod
-{
- service_type => "windows";
- service_args => "--netmask=255.255.0.0";
- service_autostart_policy => "none";
- service_dependence_chain => "start_parent_services";
-}
-
-@end verbatim
diff --git a/docs/reference/promises/services_intro.texinfo b/docs/reference/promises/services_intro.texinfo
deleted file mode 100644
index 27cb268be8..0000000000
--- a/docs/reference/promises/services_intro.texinfo
+++ /dev/null
@@ -1,30 +0,0 @@
-A service is a set of zero or more processes. It can be zero if the
-service is not currently running. Services run in the background, and
-do not require user intervention.
-
-Service promises may be viewed as an abstraction of process and
-commands promises. An important distinguiser is however that a single
-service may consist of multiple processes. Additionally, services are
-registered in the operating system in some way, and gets a unique
-name. Unlike processes and commands promises, this makes it possible
-to use the same name both when it is running and not.
-
-Some operating systems are bundled with a lot of unused services that
-are running as default. At the same time, faulty or inherently
-insecure services are often the cause of security issues. With
-CFEngine, one can create promises stating services that should be
-stopped and disabled.
-
-The operating system may start a service at boot time, or it can be
-started by CFEngine. Either way, CFEngine will ensure that the service
-maintains the correct state (started, stopped, or disabled). On some
-operating systems, CFEngine also allows services to be started on
-demand, i.e. when they are needed. This is implemented though the
-@code{inetd} or @code{xinetd} daemon on Unix. Windows does not support
-this.
-
-CFEngine also allows for the concept of dependencies between
-services, and can automatically start or stop these, if
-desired. Parameters can be passed to services that are started by
-CFEngine.
-
diff --git a/docs/reference/promises/services_notes.texinfo b/docs/reference/promises/services_notes.texinfo
deleted file mode 100644
index 29b6e0603c..0000000000
--- a/docs/reference/promises/services_notes.texinfo
+++ /dev/null
@@ -1,82 +0,0 @@
-
-Services promises for Windows are only available in CFEngine Nova and
-above.
-Windows Vista/Server 2008 and later introduced new complications to
-the service security policy. Therefore, when testing @code{services}
-promises from the command line, CFEngine may not be given proper
-access rights, which gives errors like "Access is denied". However,
-when running through the CFEngine Nova Executor service, typical for
-on production machines, CFEngine has sufficent rights.
-
-Services of type @samp{generic} promises are implemented for all
-operating systems and are merely as a convenient front-end to
-@code{processes} and @code{commands}. If nothing else is specified,
-CFEngine looks for an special reserved agent bundle called
-
-@verbatim
-bundle agent standard_services(service,state)
-{
-...
-}
-@end verbatim
-
-This bundle is called with two parameters: the name if the service and
-a start/stop state variable. The CFEngine standard library defines
-many common services for standard operating systems for convenience.
-If no @code{service_bundle} is defined in a @code{service_method}
-body, then CFEngine assumes the @samp{standard_services} bundle to be
-the default source of action for the services. This is executed just
-like a @code{methods} promise on the service bundle, so this is merely
-a front-end.
-
-The standard bundle can be replaced with another, as follows, e.g. for
-testing purposes:
-
-@verbatim
-body common control
-{
-bundlesequence => { "test" };
-}
-
-#
-
-bundle agent test
-{
-vars:
-
- "mail" slist => { "spamassassin", "postfix" };
-
-
-services:
-
- "www" service_policy => "start",
- service_method => service_test;
-
-
- "$(mail)" service_policy => "stop",
- service_method => service_test;
-}
-
-#
-
-body service_method service_test
-{
-service_bundle => non_standard_services("$(this.promiser)","$(this.service_policy)");
-}
-
-#
-
-bundle agent non_standard_services(service,state)
-{
-reports:
-
- !done::
-
- "Test service promise for \"$(service)\" -> $(state)";
-}
-@end verbatim
-
-Note that the special variables @code{$(this.promiser)} and
-@code{$(this.service_policy)} may be used to fill in the service and
-state parameters from the promise definition. The @code{$(this.service_policy)}
-variable is only defined for services promises.
diff --git a/docs/reference/promises/set_attribute_example.texinfo b/docs/reference/promises/set_attribute_example.texinfo
deleted file mode 100644
index 76bc2088c2..0000000000
--- a/docs/reference/promises/set_attribute_example.texinfo
+++ /dev/null
@@ -1,13 +0,0 @@
-
-@verbatim
-
-bundle edit_xml example
- {
- set_attribute:
- "name"
-
- attribute_value => "cfe_host",
- select_xpath => "/Server/Service/Engine/Host";
- }
-
-@end verbatim
diff --git a/docs/reference/promises/set_attribute_intro.texinfo b/docs/reference/promises/set_attribute_intro.texinfo
deleted file mode 100644
index 8c3dffa2e9..0000000000
--- a/docs/reference/promises/set_attribute_intro.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-This promise is part of the XML-editing model. It assures that
-an attribute, with the given name and value, will be present
-in the specified node within the XML file. If the attribute
-is not found, the default promise is to insert the attribute,
-into the specified node. If the attribute is already present,
-the default promise is to insure that the attribute value is
-set to the given value. The specified node and attribute value
-are each determined by body-attributes. The promise object
-referred to is a literal string representation of the name of
-the attribute to be set.
diff --git a/docs/reference/promises/set_attribute_notes.texinfo b/docs/reference/promises/set_attribute_notes.texinfo
deleted file mode 100644
index d4645fe34c..0000000000
--- a/docs/reference/promises/set_attribute_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Note that typically, only a single attribute, within a single selected
-node is set in each @code{set_attribute} promise (you may of course
-have multiple promises that each set an attribute).
diff --git a/docs/reference/promises/set_text_example.texinfo b/docs/reference/promises/set_text_example.texinfo
deleted file mode 100644
index 5969e3b0ad..0000000000
--- a/docs/reference/promises/set_text_example.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@verbatim
-
-bundle edit_xml example
- {
- set_text:
- "text content to replace existing text, including whitespace, within selected node"
-
- select_xpath => "/Server/Service/Engine/Host/Alias";
- }
-
-@end verbatim
diff --git a/docs/reference/promises/set_text_intro.texinfo b/docs/reference/promises/set_text_intro.texinfo
deleted file mode 100644
index 6bcbc57d60..0000000000
--- a/docs/reference/promises/set_text_intro.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-This promise is part of the XML-editing model. It assures
-that a matching value string will be present in the specified
-node within the XML file. If the existing value string does
-not exactly match, the default promise is to replace the
-existing value string, within the specified node. The
-specified node is determined by body-attributes. The promise
-object referred to is a literal string of text.
diff --git a/docs/reference/promises/set_text_notes.texinfo b/docs/reference/promises/set_text_notes.texinfo
deleted file mode 100644
index b1cdf76209..0000000000
--- a/docs/reference/promises/set_text_notes.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Note that typically, only a single value string, within a single selected
-node, is set in each @code{set_text} promise (you may of course
-have multiple promises that each set a value string).
diff --git a/docs/reference/promises/storage_example.texinfo b/docs/reference/promises/storage_example.texinfo
deleted file mode 100644
index 3d58d3de5c..0000000000
--- a/docs/reference/promises/storage_example.texinfo
+++ /dev/null
@@ -1,33 +0,0 @@
-
-@verbatim
-
-bundle agent storage
-
-{
-storage:
-
- "/usr" volume => mycheck("10%");
- "/mnt" mount => nfs("nfsserv.example.org","/home");
-
-}
-
-#######################################################
-
-body volume mycheck(free) # reusable template
-
-{
-check_foreign => "false";
-freespace => "$(free)";
-sensible_size => "10000";
-sensible_count => "2";
-}
-
-body mount nfs(server,source)
-
-{
-mount_type => "nfs";
-mount_source => "$(source)";
-mount_server => "$(server)";
-edit_fstab => "true";
-}
-@end verbatim
diff --git a/docs/reference/promises/storage_intro.texinfo b/docs/reference/promises/storage_intro.texinfo
deleted file mode 100644
index 272a9d5135..0000000000
--- a/docs/reference/promises/storage_intro.texinfo
+++ /dev/null
@@ -1,21 +0,0 @@
-
-Storage promises refer to disks and filesystem properties.
-
-@cartouche
-@smallexample
-
- storage:
-
- "/@var{disk volume or mountpoint}"
-
- volume => @var{volume_body},
- ...;
-
-@end smallexample
-@end cartouche
-
-In CFEngine 2, storage promises were divided into @code{disks} or
-@code{required}, and @code{misc_mounts} types. The old mount-models
-for binary and home servers has been deprecated and removed from
-CFEngine 3. Users who use these models can reconstruct them from the
-low-level tools.
diff --git a/docs/reference/promises/storage_notes.texinfo b/docs/reference/promises/storage_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/promises/storage_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/promises/vars_example.texinfo b/docs/reference/promises/vars_example.texinfo
deleted file mode 100644
index 5e047d7548..0000000000
--- a/docs/reference/promises/vars_example.texinfo
+++ /dev/null
@@ -1,26 +0,0 @@
-
-@verbatim
-
-bundle agent example
-
-{
-vars:
-
- "scalar1" string => "SCALAR 1";
- "list1" slist => { "LIST1_1", "LIST1_2" } ;
- "array[1]" string => "ARRAY 1";
- "array[2]" string => "ARRAY 2";
-
- "i" slist => getindices("array");
-
-reports:
-
- cfengine_3::
-
- "Scalar $(scalar1)";
- "List $(list1)";
- "Array $(array[$(i)])";
-}
-
-
-@end verbatim
diff --git a/docs/reference/promises/vars_intro.texinfo b/docs/reference/promises/vars_intro.texinfo
deleted file mode 100644
index b5694f9371..0000000000
--- a/docs/reference/promises/vars_intro.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-Variables in CFEngine are defined as promises that an identifier
-represents a particular value. Variables in CFEngine are dynamically
-typed as strings, integers and real numbers. Lists of these types
-are also possible.
-
-CFEngine supports a few operations on arrays. Arrays are simply a
-naming convention for scalar variables, using square brackets @samp{[]}
-to enclose an arbitrary key. Arrays are thus @code{associative}.
diff --git a/docs/reference/promises/vars_notes.texinfo b/docs/reference/promises/vars_notes.texinfo
deleted file mode 100644
index 8b13789179..0000000000
--- a/docs/reference/promises/vars_notes.texinfo
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/reference/reference_basics.texinfo b/docs/reference/reference_basics.texinfo
deleted file mode 100644
index ffcf85b63a..0000000000
--- a/docs/reference/reference_basics.texinfo
+++ /dev/null
@@ -1,3666 +0,0 @@
-
-CFEngine is a suite of programs for integrated autonomic management of
-either individual or networked computers. It has existed as as
-software suite since 1993 and this version published under the GNU
-Public License (GPL v3) and a Commercial Open Source License (COSL).
-CFEngine is Copyright by @b{CFEngine AS}, a company founded by CFEngine
-author Mark Burgess.
-
-This document describes major version 3 of CFEngine, which is a
-significant departure from earlier versions, and represents the newest
-and most carefully researched technology available for configuration
-management. It is both simpler and more powerful. CFEngine 3 will
-exist as both free open source and commercial enterprise versions:
-
-@itemize
-@item @b{Community Edition} - a free and gratis core of the software (available now).
-@item @b{Enterprise} - a commercial enhanced version for basic enterprise needs (available now; previously known as Nova).
-@end itemize
-
-This document is valid for @b{all versions} of CFEngine. Whenever a feature is only
-available in a specific version, that fact will be noted in the documentation for that
-feature (if there is no note, then that feature is available in all versions).
-
-CFEngine 3 has been changed to be both a more powerful tool and a much
-simpler tool. CFEngine 3's language interface is not backwards
-compatible with the CFEngine 2 configuration language, but it
-interoperates with CFEngine 2 so that it is "run-time compatible".
-This means that you can change over to version 3 slowly, with low risk
-and at your own speed.
-
-With CFEngine 3 you can install, configure and maintain computers
-using powerful hands-free tools. You can also integrate knowledge
-management and diagnosis into the processes.
-
-CFEngine differs from most management systems in being
-
-@itemize
-@item Open software (GPL or COSL).
-@item Lightweight and generic.
-@item Non-reliant on a working network to function correctly.
-@item Capable of making each and every host autonomous
-@end itemize
-
-@menu
-* Software components::
-* Core concepts::
-* A renewed CFEngine::
-* Installation::
-* Syntax::
-* Work directory::
-* Decisions::
-* Filenames and paths::
-* Upgrading from CFEngine 2::
-* Testing as a non-privilieged user::
-* The bare necessities of a CFEngine 3::
-* Familiiarizing yourself::
-* Remote access troubleshooting::
-@end menu
-
-@node Software components
-@section Software components
-
-CFEngine 3 consists of a number of components. The names of the programs are
-intentionally different from those in CFEngine 2 to help disambiguate them (and
-some CFEngine 2 components have been merged and/or eliminated). The
-starred components are new to CFEngine 3:
-
-@menu
-* cf-agent::
-* cf-execd::
-* cf-monitord::
-* cf-promises::
-* cf-runagent::
-* cf-serverd::
-* cf-key::
-* cf-hub::
-@end menu
-
-
-@node cf-agent
-@subsection cf-agent
-
-Active agent -- responsible for maintaining promises about the state of
- your system (in CFEngine 2 the agent was called @code{cfagent}).
- You can run @code{cf-agent} manually, but if you want to have it
- run on a regular basis, you should use @ref{cf-execd, ,cf-execd}
- (instead of using @code{cron}).
-
-@code{cf-agent} keeps the promises made in @ref{Bundles for common, ,common}
-and @ref{Bundles for agent, ,agent} bundles, and is affected by
-@ref{control common, , common} and @ref{control agent, ,agent}
-control bodies.
-
-@node cf-execd
-@subsection cf-execd
-Scheduler -- responsible for running cf-agent on a regular (and
- user-configurable) basis (in CFEngine 2 the scheduler was called
- @code{cfexecd}).
-
-EXECUTOR
-@code{cf-execd} keeps the promises made in @ref{Bundles for common, ,common}
-bundles, and is affected by
-@ref{control common, , common} and @ref{control executor, ,executor}
-control bodies.
-
-@node cf-monitord
-@subsection cf-monitord
-
-Passive monitoring agent -- responsible for collecting information about
- the status of your system (which can be reported upon or used to
- enforce promises or influence when promises are enforced). In CFEngine 2
- the passive monitoring agent was known as @code{cfenvd}.
-
-@code{cf-monitord} keeps the promises made in @ref{Bundles for common, ,common}
-and @ref{Bundles for monitor, ,monitor} bundles, and is affected by
-@ref{control common, , common} and @ref{control monitor, ,monitor}
-control bodies.
-
-@node cf-promises
-@subsection cf-promises
-Promise validator -- used to verify that the promises used by the other
- components of CFEngine are syntactically valid.
-@code{cf-promises} does not execute any promises, but can syntax-check
-all of them.
-
-@node cf-runagent
-@subsection cf-runagent
-
-Remote run agent -- used to execute @code{cf-agent} on a remote machine (in
- CFEngine 2 the remote run agent was called @code{cfrun}).
-@code{cf-runagent} does not keep any promises, but instead is used to ask
-another machine to do so.
-
-@node cf-serverd
-@subsection cf-serverd
-Server -- used to distribute policy and/or data files to clients requesting
- them and used to respond to requests from @code{cf-runagent} (in
- CFEngine 2 the remote run agent was called @code{cfservd}).
-
-@code{cf-serverd} keeps the promises made in @ref{Bundles for common, ,common}
-and @ref{Bundles for server, ,server} bundles, and is affected by
-@ref{control common, , common} and @ref{control server, ,server}
-control bodies.
-
-@node cf-key
-@subsection cf-key
-Key generation tool -- run once on every host to create public/private key
- pairs for secure communication (in CFEngine 2 the key generation tool
- was called @code{cfkey}). @code{cf-key} does not keep any promises.
-
-@node cf-hub
-@subsection cf-hub
-A data aggregator used as part of the commercial product. This stub is not
-used in the community edition of CFEngine.
-
-
-
-@node Core concepts
-@section Core concepts
-
-Unlike previous versions of CFEngine, which had no consistent model
-for its features, you can recognize @i{everything} in CFEngine 3
-from just a few concepts.
-
-@table @i
-@item Promise
-A declaration about the @i{state} we desire to maintain (@i{e.g.,} the permissions
-or contents of a file, the availability or absence of a service, the
-(de)installation of a package).
-@item Promise bundles
-A collection of promises.
-@item Promise bodies
-A part of a promise which details and constrains its nature.
-@item Data types
-An interpretation of a scalar value: string, integer or real number.
-@item Variables
-An association of the form "LVALUE @i{represents} RVALUE", where rval may be a scalar value or a list of scalar values.
-@item Functions
-Built-in parameterized rvalues.
-@item Classes
-CFEngine's boolean classifiers that describe context.
-@end table
-
-
-If you have used CFEngine before then the most visible part of
-CFEngine 3 will be its new language interface. Although it has been
-clear for a long time that the organically grown language used in
-CFEngine 1 and 2 developed many problems, it was not immediately
-clear exactly what would be better. It has taken years of research to
-simplify the successful features of CFEngine to a single overarching
-model. To understand the new CFEngine, it is best to set aside any
-preconceptions about what CFEngine is today. CFEngine 3 is a genuine
-"next generation" effort, which will be a springboard into the
-future of system management.
-
-@node A renewed CFEngine
-@section A renewed CFEngine
-
-
-CFEngine 3 is a significant rewrite of underlying CFEngine technology
-which preserves the core principles and methodology of CFEngine's
-tried and tested approach. It comes with a new, improved language,
-with a consistent syntax and powerful pattern expression features that
-display the intent behind CFEngine code more clearly. The main goal in
-changing the language is to simplify and improve the robustness and
-functionality without sacrificing the basic freedoms and self-repairing
-concepts.
-
-CFEngine 3's new language is a direct implementation of a model
-developed at Oslo University College over the past four years, known
-colloquially as "Promise Theory". Promises were originally introduced
-by Mark Burgess as a way to talk about CFEngine's model of autonomy
-and have since become a powerful way of modelling cooperative systems
--- not just computers, but humans too.
-
-@quotation
-
-@i{ ``The biggest challenge of implementing CFEngine in our organization@*
- was not technical but political -- getting everyone to agree.@*
- Promise theory was a big help in understand this.''}
-
-@end quotation
-
-CFEngine 3 is a generic implementation of the language of promises
-that allows all of the aspects of configuration and change management to be
-unified under a single umbrella.
-
-Why talk about promises instead of simply talking about changes? After
-all, the trend in business and IT management today is to talk about
-Change Management (with capital letters), e.g. in the IT
-Infrastructure Library (ITIL) terminology. This comes from a long
-history of process management thinking. But we are not really
-interested in change -- we are interested in avoiding it, i.e. being
-in a state where we don't need to make any changes. In other words we
-want to be able to promise that the system is correct, verify this and
-only make changes if our promises are not kept. If you want
-to think ITIL, think of this as a service that CFEngine provides.
-
-To put it another way, CFEngine is not really a @i{change
-management} system, it is a @i{maintenance system}. Maintenance
-is the process of making small changes or corrections to a model. A
-`model' is just another word for a template or a specification of how
-we want the system to work. CFEngine's model is based on the idea of
-promises, which means that it focuses on what is stable and lasting
-about a system -- not about what is changing.
-
-
-This is an important philosophical shift. It means we are focused
-mainly on what is right and not on what is wrong. By saying what
-"right" is (the ideal state of our system) we are focused on the
-actual behaviour. If we focus too much on the changes, i.e. the
-differences between now and the future, we might forget to verify that what
-we assume is working now in fact works.
-
-
-Models that talk about change management tend to forget that after
-every change there is a litany of @i{incidents} during which it is
-necessary to repair the system or return it to its intended state.
-But if we know what we have promised, it is easy to verify whether the
-promise is kept.
-This means that it is the @i{promises} about how the system should
-be that are most important, not the actual changes that are made in
-order to keep them.
-
-
-
-
-@node Installation
-@section Installation
-
-In order to install CFEngine, you should first ensure that the following
-packages are installed.
-
-@table @r
-@item @b{OpenSSL}
-Open source Secure Sockets Layer for encryption.@*URL: @url{http://www.openssl.org}
-@item @b{Tokyo Cabinet} (version 1.4.42 or later)
-Lightweight flat-file database system.@*URL: @url{http://fallabs.com/tokyocabinet/}
-@item @b{PCRE}
-Perl Compatible Regular Expression library.@*URL: @url{http://www.pcre.org/}
-
-@item
-On Windows machines, you need to install the basic Cygwin DLL from @url{http://www.cygwin.com}
-in order to run CFEngine.
-@end table
-
-Additional functionality becomes available if other libraries are present, e.g.
-OpenLDAP, client libraries for MySQL and PostgreSQL, etc. It is possible to run
-CFEngine without these, but related functionality will be missing.
-
-Unless you have purchased ready-to-run binaries, or are using a
-package distribution, you will need to compile CFEngine. For this you
-will also need a build environment tools: @code{gcc}, @code{flex}, @code{bison}.
-
-@noindent
-The preferred method of installation is then
-
-@smallexample
-tar zxf cfengine-x.x.x.tar.gz
-cd cfengine-x.x.x
-./configure
-make
-make install
-@end smallexample
-
-@noindent
-This results in binaries being installed in @file{/var/cfengine/bin}.
-
-@node Syntax
-@section Syntax, identifiers and names
-
-The CFEngine 3 language has a few simple rules:
-
-@itemize
-@item CFEngine built-in words, and identifiers of your choosing (the names
-of variables, bundles, body templates and classes) may only contain
-the usual alphanumeric and underscore characters (@samp{a-zA-Z0-9_}).
-
-@item All other `literal' data must be quoted.
-
-@item Declarations of promise bundles
-in the form:
-@example
-bundle @var{agent-type} identifier
-@{
-...
-@}
-@end example
-
-@item Declarations of promise body-parts in the form:
-@example
-body constraint_type template_identifier
-@{
-...
-@}
-@end example
-matching and expanding on a reference inside a promise
-of the form
-@samp{constraint_type => template_identifier}.
-
-
-@item CFEngine uses many `constraint expressions'
-as part of the body of a promise. These take the form: left-hand-side (CFEngine word)
-@samp{=>} right-hand-side (user defined data). This can take several forms:
-
-@verbatim
-cfengine_word => user_defined_template(parameters)
- user_defined_template
- builtin_function()
- "quoted literal scalar"
- { list }
-@end verbatim
-In each of these cases, the right hand side is a user choice.
-@end itemize
-
-
-@node Work directory
-@section The work directory
-
-In order to achieve the desired simplifications, it was decided to
-reserve a private work area for the CFEngine tool-set.
-@c chew begin Work directory
-
-@cartouche
-In CFEngine 1.x, the administrator could choose the locations of
-configuration files, locks, and logging data independently. In
-CFEngine 2.x, this diversity has been simplified to a single directory
-which defaults to @file{/var/cfengine} (similar to @file{/var/cron}), and in
-CFEngine 3.x this is preserved.
-@end cartouche
-
-@w{}
-@smallexample
-/var/cfengine
-/var/cfengine/bin
-/var/cfengine/inputs
-/var/cfengine/outputs
-@end smallexample
-@c chew end Work directory
-
-A trusted cache of the input files must now be maintained
-in the @file{inputs} subdirectory. When CFEngine is invoked by the
-scheduler, it reads only from this directory. It is up to the user to
-keep this cache updated, on each host. This simplifies and
-consolidates the CFEngine resources in a single place.
-
-Unlike CFEngine 2, CFEngine 3 does not recognize the
-@code{CFINPUTS} environment variable.
-
-The @file{outputs} directory is now a record of spooled run-reports. These
-are often mailed to the administrator by @code{cf-execd}, or can be copied
-to another central location and viewed in an alternative browser.
-
-
-@c -------------------------------------------------------------------------------
-@c SECTION
-@c -------------------------------------------------------------------------------
-
-@node Decisions
-@section Decisions
-
-CFEngine decisions are made behind the scenes and the results of
-certain true/false propositions are cached in Booleans referred to as
-`classes'. There are no if-then-else statements in CFEngine; all
-decisions are made with classes.
-
-Classes fall into hard (discovered) and soft (user-defined) types. A
-single hard class can be one of several things:
-
-@menu
-* Hard classes::
-* Class combination operators and precedence::
-* Global and local classes::
-@end menu
-
-@node Hard classes
-@subsection CFEngine hard classes
-
-CFEngine runs on every computer individually and each time it wakes up
-the underlying generic agent platform discovers and classifies
-properties of the environment or context in which it runs. This information
-is cached and may be used to make decisions about configuration@footnote{There are
-no if-then-else statements in CFEngine; all decisions are made with classes.}.
-
-Classes fall into hard (discovered) and soft (defined) types. A
-single class can be one of several things:
-
-@c chew start Hard classes
-
-@itemize @bullet
-
-@item The name of an operating system architecture e.g. @code{ultrix}, @code{sun4}, etc.
-
-@item The unqualified name of a particular host (e.g., @code{www}). If your
-system returns a fully qualified domain name for your host (e.g.,
-@code{www.iu.hio.no}), CFEngine will also define a hard class for the fully
-qualified name, as well as the partially-qualified component names
-@code{iu.hio.no}, @code{hio.no}, and @code{no}.
-
-@item The name of a user-defined group of hosts.
-
-@item A day of the week (in the form @code{Monday, Tuesday, Wednesday, ..}).
-
-@item An hour of the day, in the current time zone (in the form @code{Hr00,
-Hr01 ... Hr23}).
-
-@item An hour of the day GMT (in the form @code{GMT_Hr00, GMT_Hr01 ... GMT_Hr23}).
-This is consistent the world over, in case you need virtual simulteneity of change
-coordination.
-
-@item Minutes in the hour (in the form @code{Min00, Min17 ... Min45}).
-
-@item A five minute interval in the hour (in the form @code{Min00_05, Min05_10 ... Min55_00}).
-
-@item A fifteen minute (quarter-hour) interval (in the form @code{Q1, Q2,
-Q3, Q4}).
-
-@item An expression of the current quarter hour (in the form @code{Hr12_Q3}).
-
-@item A day of the month (in the form @code{Day1, Day2, ... Day31}).
-
-@item A month (in the form @code{January, February, ... December}).
-
-@item A year (in the form @code{Yr1997, Yr2004}).
-
-@item A shift in @code{Night,Morning,Afternoon,Evening}, which fall into six hour blocks
-starting at 00:00 hours.
-
-@item A `lifecycle index', which is the year number modulo 3 (in the form
-@code{Lcycle_0, Lcycle_1, Lcycle_2}, used in long term resource memory).
-
-@item An arbitrary user-defined string (as specified in the @code{-D} command
-line option, or defined in a @code{classes} promise or body,
-@code{restart_class} in a @code{processes} promise, etc).
-
-@item The IP address octets of any active interface (in the form @code{@w{ipv4_192_0_0_1}},
-@code{@w{ipv4_192_0_0}}, @code{@w{ipv4_192_0}}, @code{@w{ipv4_192}}),
-provided they are not excluded by a regular expression in the file @file{WORKDIR/inputs/ignore_interfaces.rx}.
-
-@item The names of the active interfaces (in the form @code{net_iface_xl0},
-@code{net_iface_vr0}).
-
-@item System status and entropy information reported by @code{cf-monitord}.
-
-@item On Solaris-10 systems, the zone name (in the form @code{zone_global,
-zone_foo, zone_baz}).
-
-@end itemize
-
-@c chew end Hard classes
-
-To see all of the classes defined on a particular host, run
-
-@smallexample
-host# cf-promises -v
-@end smallexample
-as a privileged user. Note that some of the classes are set only
-if a trusted link can be established with cf-monitord, i.e. if both
-are running with privilege, and the @file{/var/cfengine/state/env_data}
-file is secure. More information about classes can be found in connection with
-@code{allclasses}.
-
-@c -------------------------------------------------------------------------------
-@c SECTION
-@c -------------------------------------------------------------------------------
-
-@node Class combination operators and precedence
-@subsection Class combination operators and precedence
-
-Classes may be combined with the usual boolean operators, in the usual precedence (AND binds
-stronger than OR). On addition the dot may be used for AND to improve readability, or
-imply the interpretation `subset' or `subclass'. In order of precedence:
-
-@table @samp
-@item ()
-The parenthesis group operator.
-@item !
-The NOT operator.
-@item .
-The AND operator.
-@item &
-The AND operator (alternative).
-@item |
-The OR operator.
-@item ||
-The OR operator (alternative).
-@end table
-
-@noindent
-So the following expression would be only true on Mondays or Wednesdays
-from 2:00pm to 2:59pm on Windows XP systems:
-
-@example
-
-(Monday|Wednesday).Hr14.WinXP::
-
-@end example
-
-
-
-@c -------------------------------------------------------------------------------
-@c SECTION
-@c -------------------------------------------------------------------------------
-
-@node Global and local classes
-@subsection Global and local classes
-
-User defined classes are mostly defined in bundles, but they are used as a
-signalling mechanism between promises. We'll return to those in a moment.
-
-Classes promises define new classes based on combinations of old ones.
-This is how to make complex decisions in CFEngine, with readable results.
-It is like defining aliases for class combinations.
-Such class `aliases' may be specified in any kind of bundle.
-Bundles of type @code{common} yield classes that are global in scope,
-whereas in all other bundle types classes are local. Classes are
-evaluated when the bundle is evaluated (and the bundles are evaluated
-in the order specified in the @code{bundlesequence}). Consider the
-following example.
-
-@verbatim
-
-body common control
-{
-bundlesequence => { "g","tryclasses_1", "tryclasses_2" };
-}
-
-#################################
-
-bundle common g
-{
-classes:
-
- "one" expression => "any";
-
-}
-
-#################################
-
-bundle agent tryclasses_1
-{
-classes:
-
- "two" expression => "any";
-}
-
-#################################
-
-bundle agent tryclasses_2
-{
-classes:
-
- "three" expression => "any";
-
-reports:
-
- one.three.!two::
-
- "Success";
-}
-
-@end verbatim
-
-Here we see that class @samp{one} is global (because it is defined inside the
-@code{common} bundle), while classes @samp{two} and @samp{three} are local (to
-their respective bundles).
-The report result `Success' is therefore true because only @samp{one} and
-@samp{three} are in scope (and @samp{two} is @i{not} in scope) inside of the
-third bundle.
-
-Note that any class promise must have one - and only one - value
-constraint. That is, you might not leave @samp{expression} in the
-example above or add both @samp{and} and @samp{xor} constraints to the
-single promise.
-
-Another type of class definition happens when you define classes based on the
-outcome of a promise, e.g. to set a class if a promise is repaired, one might write:
-
-@verbatim
- "promiser..."
-
- ...
-
- classes => if_repaired("signal_class");
-@end verbatim
-
-These classes are global in scope. Finally @code{restart_class} classes in @code{processes}
-are global.
-
-@c -------------------------------------------------------------------------------
-@c SECTION
-@c -------------------------------------------------------------------------------
-
-@node Filenames and paths
-@section Filenames and paths
-
-@c chew start Unix filenames
-
-Filenames in Unix-like operating systems use the forward slash
-@samp{/} character for their directory separator . All references to
-file locations must be absolute pathnames in CFEngine, i.e. they must
-begin with a complete specification of which directory they are
-in. For example:
-
-@smallexample
-/etc/passwd
-/var/cfengine/masterfiles/distfile
-@end smallexample
-@noindent
-The only place where it makes sense to refer to a file without a complete
-directory specification is when searching through directories for different
-kinds of file, e.g. in pattern matching
-
-@verbatim
-
-leaf_name => { "tmp_.*", "output_file", "core" };
-
-@end verbatim
-
-@noindent
-Here, one can write @file{core} without a path, because one is looking for any
-file of that name in a number of directories.
-@c chew end Unix filenames
-
-@c chew start Windows filenames
-The Windows operating systems traditionally use a different filename
-convention. The following are all valid absolute file names under
-Windows:
-
-@smallexample
- c:\winnt
- "c:\spaced name"
- c:/winnt
- /var/cfengine/inputs
- //@var{fileserver}/share2/dir
-@end smallexample
-The `drive' name ``C:'' in Windows refers to a partition or device. Unlike Unix,
-Windows does not integrate these seamlessly into a single file-tree.
-This is not a valid absolute filename:
-
-@smallexample
-\var\cfengine\inputs
-@end smallexample
-Paths beginning with a backslash are assumed to be win32 paths. They
-must begin with a drive letter or double-slash server name.
-@c chew end Windows filenames
-
-Note in recent versions of Cygwin you can decide to use the
-@code{/cygdrive} to specify a path to windows file E.g
-@file{/cygdrive/c/myfile} means @file{c:\myfile} or you can do it straight away in
-CFEngine as @code{c:\myfile}.
-
-@c ---------------------------------------------------------------------------
-@node Upgrading from CFEngine 2
-@section Upgrading from CFEngine 2
-
-CFEngine 3 has a completely new syntax, designed to solve the issues
-brought up from 15 years of experience with configuration
-management. Rather than clutter CFEngine 3 with buggy
-backward-compatability issues, it was decided to make no compromises
-with CFEngine 3 and instead allow CFEngine 2 and CFEngine 3 to
-coincide in a cooperative fashion for the foreseeable future. This
-means that users can upgrade at their own pace, in the classic
-CFEngine incremental fashion. We expect that CFEngine 2 installations
-will be around for years to come so this upgrade path seems the most
-defensible.
-
-The daemons and support services are fully interoperable between
-CFEngine 2 and CFEngine 3, so it does not matter whether you run
-@code{cfservd} (cf2) together with @code{cf-agent} (cf3) or
-@code{cf-serverd} (cf3) together with @code{cfagent} (cf2). You can
-change the servers at your own pace.
-
-CFEngine 3's @code{cf-execd} replaces CFEngine 2's @code{cfexecd} and
-it is designed to work optimally with @code{cf-agent} (cf3). Running
-this daemon has no consequences for access control, only for
-scheduling @code{cf-agent}. You can (indeed should) replace
-@code{cfexecd} with @code{cf-execd} immediately. You will want to
-alter your @file{crontab} file to run the new component instead of the
-old. The sample CFEngine 3 input files asks @code{cf-agent} to do
-this automatically, simply replacing the string.
-
-The sample @file{inputs} files supplied with CFEngine 3 contain
-promises to integrate CFEngine 2 as described. What can you do to
-upgrade? Here is a simple recipe that assumes you have a standardized
-CFEngine 2 setup, running @code{cfexecd} in @file{crontabs} and possibly
-running @code{cfservd} and @code{cfenvd} as daemons.
-
-@enumerate
-
-@item Install the CFEngine 3 software on a host.
-
-@item Go to the @file{inputs/} directory in the source and copy these
-files to your master update repository, i.e. where you will publish
-policies for distribution.
-
-@item Remove any self-healing rules to reinstall CFEngine 2, especially
-rules to add @code{cfexecd} or @code{cfagent} to @file{crontabs} etc. CFEngine 3
-will handle this from now on and encapsulate old CFEngine 2 scripts.
-
-@item Move to this inputs directory: @code{cd @var{your-path}/inputs}.
-
-@item Set the location of this master update directory in the @file{update.cf}
-file to the location of the master directory.
-
-@item Set the email options for the executor in @file{promises.cf}.
-
-@item Run @code{cf-agent --bootstrap} as the root or privileged user. This will install
-CFEngine 3 in place of CFEngine 2, integrate your old CFEngine 2
-configuration, and warn you about any rules that need to be removed
-from your old CFEngine configuration.
-
-@item You should now be running CFEngine 3. You can now add new rules to the files
-in your own time, or convert the old CFEngine 2 rules and gradually comment them
-out of the CFEngine 2 files.
-
-@item Make sure there are no rules in your old CFEngine 2 configuration to activate
-CFEngine 2 components, i.e. rules that will fight against CFEngine 3.
-Then, when you are ready, convert @file{cfservd.conf} into a server bundle e.g. in @file{promises.cf}
-and remove all rules to run @code{cfservd} and replace them with rules to run
-@code{cf-serverd} at your own pace.
-
-@end enumerate
-
-
-@c ---------------------------------------------------------------------------
-@node Testing as a non-privilieged user
-@section Testing as a non-privilieged user
-
-One of the practical advantages of CFEngine is that you can test it
-without the need for root or administrator privileges. This is
-recommended for all new users of CFEngine 3.
-
-CFEngine operates with the notion of a work-directory. The default
-work directory for the @code{root} user is @file{/var/cfengine}
-(except on Debian Linux and various derivatives which prefer
-@file{/var/lib/cfengine}). For any other user, the work directory
-lies in the user's home directory, named @file{~/.cfagent}. CFEngine
-prefers you to keep certain files here. You should not resist this
-too strongly or you will make unnecessary trouble for yourself. The
-decision to have this `known directory' was made to simplify a lot of
-configuration.
-
-To test CFEngine as an ordinary user, do the following:
-
-@itemize
-@item Compile and make the software.
-@item Copy the binaries into the work directory:
-@smallexample
-host$ mkdir -p ~/.cfagent/inputs
-host$ mkdir -p ~/.cfagent/bin
-host$ cd src
-host$ cp cf-* ~/.cfagent/bin
-host$ cd ../inputs
-host$ cp *.cf ~/.cfagent/inputs
-@end smallexample
-@end itemize
-
-You can test the software and play with configuration files by editing the basic get-started files
-directly in the @file{~/.cfagent/inputs} directory. For example, try the following:
-
-@smallexample
-host$ ~/.cfagent/bin/cf-promises
-host$ ~/.cfagent/bin/cf-promises --verbose
-@end smallexample
-
-This is always the way to start checking a configuration in CFEngine
-3. If a configuration does not pass this check/test, you will not be
-allowed to use it, and @file{cf-agent} will look for the file
-@file{failsafe.cf}.
-
-Notice that the CFEngine 3 binaries have slightly different names than the CFEngine
-2 binaries. They all start with the @file{cf-} prefix.
-@smallexample
-host$ ~/.cfagent/bin/cf-agent
-@end smallexample
-
-
-@c ---------------------------------------------------------------------------
-@node The bare necessities of a CFEngine 3
-@section The `bare necessities' of a CFEngine 3
-
-Here is the simplest `Hello world' program in CFEngine 3:
-
-@verbatim
-
-body common control
-{
-bundlesequence => { "test" };
-}
-
-bundle agent test
-{
-reports:
-
- cfengine::
- "Hello world";
-}
-
-@end verbatim
-
-@noindent If you try to process this using the @code{cf-promises} command, you will
-see something like this:
-
-@smallexample
-atlas$ ~/LapTop/CFEngine3/trunk/src/cf-promises -r -f ./unit_null_config.cf
-Summarizing promises as text to ./unit_null_config.cf.txt
-Summarizing promises as html to ./unit_null_config.cf.html
-@end smallexample
-
-@noindent The @samp{-r} option produces a report. Examine the files produced:
-
-@smallexample
-cat ./unit_null_config.cf.txt
-firefox ./unit_null_config.cf.html
-@end smallexample
-
-You will see a summary of how CFEngine interprets the files, either in
-HTML or text. By default, the CFEngine components also dump a debugging
-file, e.g. @file{promise_output_agent.html}, @file{promise_output_agent.txt}
-with an expanded view.
-
-@c ---------------------------------------------------------------------------
-@node Familiiarizing yourself
-@section Familiarizing yourself
-
-
-To familiarize yourself with CFEngine 3, type or paste in the following example text:
-
-@verbatim
-########################################################
-#
-# Simple test execution
-#
-########################################################
-
-body common control
-
-{
-bundlesequence => { "testbundle" };
-}
-
-########################################################
-
-bundle agent testbundle
-
-{
-vars:
-
- "size" int => "46k";
- "rand" int => randomint("33","$(size)");
-
-commands:
-
- "/bin/echo"
- args => "Hello world - $(size)/$(rand)",
- contain => standard,
- classes => cdefine("followup","alert");
-
- followup::
-
- "/bin/ls"
- contain => standard;
-
-reports:
-
- alert::
-
- "What happened?";
-
-}
-
-######################################################################
-
-body contain standard
-
-{
-useshell => "useshell";
-}
-
-######################################################################
-
-body classes cdefine(class,alert)
-
-{
-promise_repaired => { "$(class)" };
-repair_failed => { "$(alert)" };
-}
-@end verbatim
-
-This example shows all of the main features of CFEngine: bundles,
-bodies, control, variables, and promises. To the casual eye it might
-look complex, but that is because it is explicit about all of the
-details. Fortunately it is easy to hide many of these details to
-make the example simpler without sacrificing any functionality.
-
-
-The first thing to try with this example is to verify it -- did we
-make any mistakes? Are there any inconsistencies? To do this we use
-the new CFEngine program @code{cf-promises}. Let's assume that you
-typed this into a file called @file{test.cf} in the current directory.
-
-@smallexample
-cf-promises -f ./test.cf
-@end smallexample
-
-If all is well, typing this command shows no output. Try now running the
-command with verbose output.
-
-@smallexample
-cf-promises -f ./test.cf -v
-@end smallexample
-
-Now you see a lot of information
-
-@smallexample
-Reference time set to Sat Aug 2 11:26:06 2008
-
-cf3 CFEngine - 3.0.0
-Free Software Foundation 1994-
-Donated by Mark Burgess, Oslo University College, Norway
-cf3 ------------------------------------------------------------------------
-cf3 Host name is: atlas
-cf3 Operating System Type is linux
-cf3 Operating System Release is 2.6.22.18-0.2-default
-cf3 Architecture = x86_64
-cf3 Using internal soft-class linux for host linux
-cf3 The time is now Sat Aug 2 11:26:06 2008
-cf3 ------------------------------------------------------------------------
-cf3 Additional hard class defined as: 64_bit
-cf3 Additional hard class defined as: linux_2_6_22_18_0_2_default
-cf3 Additional hard class defined as: linux_x86_64
-cf3 Additional hard class defined as: linux_x86_64_2_6_22_18_0_2_default
-cf3 GNU autoconf class from compile time: compiled_on_linux_gnu
-cf3 Interface 1: lo
-cf3 Trying to locate my IPv6 address
-cf3 Looking for environment from cf-monitord...
-cf3 Unable to detect environment from cf-monitord
----------------------------------------------------------------------
-Loading persistent classes
----------------------------------------------------------------------
-
----------------------------------------------------------------------
-Loaded persistent memory
----------------------------------------------------------------------
-cf3 > Parsing file ./test.cf
----------------------------------------------------------------------
-Agent's basic classified context
----------------------------------------------------------------------
-
-
-Defined Classes = ( any Saturday Hr11 Min26 Min25_30 Q2 Hr11_Q2 Day2
-August Yr2008 linux atlas 64_bit linux_2_6_22_18_0_2_default x86_64
-linux_x86_64 linux_x86_64_2_6_22_18_0_2_default
-linux_x86_64_2_6_22_18_0_2_default__1_SMP_2008_06_09_13_53_20__0200
-compiled_on_linux_gnu net_iface_lo )
-
-Negated Classes = ( )
-
-Installable classes = ( )
-cf3 Wrote expansion summary to promise_output_common.html
-cf3 Inputs are valid
-@end smallexample
-
-
-The last two lines of this are of interest. Each time a component of
-CFEngine 3 parses a number of promises, it summarizes the information
-in an HTML file called generically @code{promise_output_@i{component-type}.html}.
-In this case the @code{cf-promises} command represents all possible promises,
-by the type "common". You can view this output file in a suitable web browser
-to see exactly what CFEngine has understood by the configuration.
-
-
-Now that you have verified it, you can execute it.
-The non-verbose output of the script when run in the CFEngine 3
-directory looks something like this:
-
-@verbatim
-host$ ./cf-agent -f ../tests/units/unit_exec_in_sequence.cf
-Q ".../bin/echo Hello": Hello world - 46k/219
- -> Last 1 QUOTEed lines were generated by "/bin/echo Hello world - 46k/219"
-Q ".../bin/ls": agent.c
-Q ".../bin/ls": agentdiagnostic.c
-Q ".../bin/ls": agentdiagnostic.o
-Q ".../bin/ls": agent.o
-Q ".../bin/ls": args.c
-Q ".../bin/ls": args.lo
-Q ".../bin/ls": args.o
-...
-Q ".../bin/ls": verify_reports.o
-Q ".../bin/ls": verify_storage.c
-Q ".../bin/ls": verify_storage.o
- -> Last 288 QUOTEed lines were generated by "/bin/ls"
-atlas$
-@end verbatim
-
-
-
-@c ---------------------------------------------------------------------------
-@node Remote access troubleshooting
-@section Remote access troubleshooting
-
-@menu
-* Server connection::
-* Key exchange::
-* Time windows::
-* Other users than root::
-* Encryption::
-@end menu
-
-@node Server connection
-@subsection Server connection
-
-When setting up @code{cf-serverd}, you might see the error message
-
-@verbatim
- Unspecified server refusal
-@end verbatim
-
-This means that @code{cf-serverd} is unable or is unwilling to
-authenticate the connection from your client machine. The message is
-generic: it is deliberately non-specific so that anyone attempting to
-attack or exploit the service will not be given information which
-might be useful to them. There is a simple checklist for curing this
-problem:
-
-@enumerate
-@item
-Make sure that the domain variable is set in the configuration files read by both client
-and server; alternatively use @code{skipidentify} and @code{skipverify} to decouple DNS from the
-the authentication.
-
-@item
-Make sure that you have granted access to your client in the server body
-
-@smallexample
-
-body server control
-@{
-allowconnects => @{ "127.0.0.1" , "::1" @var{...etc} @};
-allowallconnects => @{ "127.0.0.1" , "::1" @var{...etc} @};
-trustkeysfrom => @{ "127.0.0.1" , "::1" @var{...etc} @};
-@}
-
-@end smallexample
-
-@item
-Make sure you have created valid keys for the hosts using @code{cf-key}.
-@item
-If you are using secure copy, make sure that you have created a key
-file and that you have distributed and installed it to all
-participating hosts in your cluster.
-@end enumerate
-
-@noindent Always remember that you can run CFEngine in verbose or
-debugging modes to see how the authentication takes place:
-
-@verbatim
-cf-agent -v
-cf-serverd -v
-@end verbatim
-
-@code{cf-agent} reports that access is denied regardless of the nature
-of the error, to avoid giving away information which might be used by
-an attacker. To find out the real reason for a denial, use verbose @samp{-v} or
-even debugging mode @samp{-d2}.
-
-
-@node Key exchange
-@subsection Key exchange
-
-The key exchange model used by CFEngine is based on that used by
-OpenSSH. It is a peer to peer exchange model, not a central
-certificate authority model. This means that there are no scalability
-bottlenecks (at least by design, though you might introduce your own
-if you go for an overly centralized architecture).
-
-The problem of key distribution is the conundrum of every public key
-infrastructure. Key exchange is handled automatically by CFEngine and all you
-need to do is to decide which keys to trust.
-
-When public keys are offered to a server, they could be accepted
-automatically on trust because no one is available to make a decision
-about them. This would lead to a race to be the first to submit a key
-claiming identity.
-
-Even with DNS checks for correct name/IP address correlation (turned
-off with @code{skipverify}), it might be possible to submit a false
-key to a server.
-
-The server @code{cf-serverd} blocks the acceptance of unknown keys by
-default. In order to accept such a new key, the IP address of the
-presumed client must be listed in the @code{trustkeysfrom} stanza of a
-@code{server} bundle (these bundles can be placed in any file). Once a
-key has been accepted, it will never be replaced with a new key, thus
-no more trust is offered or required.
-
-Once you have arranged for the right to connect to the server, you
-must decide which hosts will have access to which files. This is done
-with @code{access} rules.
-
-@verbatim
-
-bundle server access_rules()
-
-{
-access:
-
- "/path/file"
-
- admit => { "127.0.0.1", "127.0.0.2", "127.0.0.3" },
- deny => { "192\..*" };
-}
-
-@end verbatim
-
-On the client side, i.e. @code{cf-runagent} and @code{cf-agent}, there are three issues:
-
-@enumerate
-@item
-Choosing which server to connect to.
-@item
-Trusting the identity of any previously unknown servers, i.e. trusting
-the server's public key to be its and no one else's. (The issues here are
-the same as for the server.)
-@item
-Choosing whether data transfers should be encrypted (with @code{encrypt}).
-@end enumerate
-
-Because there are two clients for connecting to @code{cf-serverd}
-(@code{cf-agent} and @code{cf-runagent}), there are also two ways of
-managing trust of server keys by a client. One is an automated option, setting the option
-@code{trustkey} in a @code{copy_from} stanza, e.g.
-
-@verbatim
-
-body copy_from example
- {
- # .. other settings ..
- trustkey => "true";
- }
-
-@end verbatim
-
-Another way is to run @code{cf-runagent} in interactive mode. When you run @code{cf-runagent}, unknown
-server keys are offered to you interactively (as with @code{ssh}) for you to
-accept or deny manually:
-
-@smallexample
-
-WARNING - You do not have a public key from host ubik.iu.hio.no = 128.39.74.25
- Do you want to accept one on trust? (yes/no)
--->
-
-@end smallexample
-
-@node Time windows
-@subsection Time windows (races)
-
-Once public keys have been exchanged from client to server and from
-server to client, the issue of trust is solved according to public key
-authentication schemes. You only need to worry about trust when one side
-of a connection has never seen the other side before.
-
-Often you will have a central server and many client satellites. Then
-the best way to transfer all the keys is to set the @code{trustkey}
-flags on server and clients sides to coincide with a time at which you
-know that @code{cf-agent} will be run, and when a spoofer is unlikely
-to be able to interfere.
-
-This is a once-only task, and the chance of an attacker being able to
-spoof a key-transfer is small. It would require skill and
-inside-information about the exchange procedure, which would tend to
-imply that the trust model was already broken.
-
-Another approach would be to run @code{cf-runagent} against all the hosts
-in the group from the central server and accept the keys one by one,
-by hand, though there is little to be gained from this.
-
-Trusting a host for key exchange is unavoidable. There is no clever
-way to avoid it. Even transferring the files manually by diskette, and
-examining every serial number of the computers you have, the host has
-to trust the information you are giving it. It is all based on
-assertion. You can make it almost impossible for keys to be faked
-or attacked, but you cannot make it absolutely impossible. Security is
-about managing reasonable levels of risk, not about magic.
-
-All security is based on a moment of trust, that is granted by a user
-at some point in time -- and is assumed thereafter (once given, hard
-to rescind). Cryptographic key methods only remove the need for a
-repeat of the trust decision. After the first exchange, trust is no
-longer needed, because they keys allow identity to be actually
-verified.
-
-Even if you leave the trust options switched on, you are not blindly
-trusting the hosts you know about. The only potential insecurity lies
-in any new keys that you have not thought about. If you use wildcards
-or IP prefixes in the trust rules, then other hosts might be able to
-spoof their way in on trust because you have left open a hole for them
-to exploit. That is why it is recommended to return the system to the
-default state of zero trust immediately after key transfer, by
-commenting out the trust options.
-
-
-It is possible, though somewhat laborious to transfer the keys out of
-band, by copying @file{/var/cfengine/ppkeys/localhost.pub} to
-@code{/var/cfengine/ppkeys/user-aaa.bbb.ccc.mmm} (assuming IPv4) on
-another host. e.g.
-
-@smallexample
-
-localhost.pub -> root-128.39.74.71.pub
-
-@end smallexample
-
-This would be a silly way to transfer keys between nearby hosts that you
-control yourself, but if transferring to long distance, remote hosts
-it might be an easier way to manage trust.
-
-@node Other users than root
-@subsection Other users than root
-
-CFEngine normally runs as user "root" (except on Windows which does
-not normally have a root user), i.e. a privileged administrator. If other users
-are to be granted access to the system, they must also generate a key
-and go through the same process. In addition, the users must be added
-to the server configuration file.
-
-@node Encryption
-@subsection Encryption
-
-CFEngine provides encryption for keeping file contents private during
-transfer. It is assumed that users will use this judiciously. There is
-nothing to be gained by encrypting the transfer of public files --
-overt use of encryption just contributes to global warming, burning
-unnecessary CPU cycles without offering any security.
-
-The main role for encryption in configuration management is for
-authentication. CFEngine always uses encryption during authentication, so
-none of the encryption settings affect the security of authentication.
-
-
-
-
-@c ---------------------------------------------------------------------------
-@node A simple crash course
-@chapter A simple crash course in concepts
-
-@menu
-* Rules are promises::
-* Best practice for writing promises::
-* Containers::
-* When and where are promises made?::
-* Types in CFEngine 3::
-* Datatypes in CFEngine 3::
-* Variable expansion in CFEngine 3::
-* Name spaces::
-* Normal ordering::
-* Loops and lists in CFEngine 3::
-* Pattern matching and referencing::
-* Distributed discovery::
-@end menu
-
-@node Rules are promises
-@section Rules are promises
-
-Everything in CFEngine 3 can be interpreted as a promise. Promises can
-be made about all kinds of different subjects, from file attributes,
-to the execution of commands, to access control decisions and
-knowledge relationships.
-
-This simple but powerful idea allows a very practical uniformity in
-CFEngine syntax. There is only one grammatical form for statements in
-the language that you need to know and it looks generically like this:
-
-@smallexample
-
- type:
-
- classes::
-
- "promiser" -> @{ "promisee1", "promisee2", ... @}
-
- attribute_1 => value_1,
- attribute_2 => value_2,
- ...
- attribute_n => value_n;
-
-@end smallexample
-
-@noindent
-We speak of a promiser (the abstract object making the promise), the promisee
-is the abstract object to whom the promise is made, and them there is a list
-of associations that we call the `body' of the promise, which together with the
-promiser-type tells us what it is all about.
-
-Not all of these elements are necessary every time. Some promises contain a lot
-of implicit behaviour. In other cases we might want to be much more explicit.
-For example, the simplest promise looks like this:
-
-@smallexample
-
-commands:
-
- "/bin/echo hello world";
-
-@end smallexample
-
-@noindent
-This promise has default attributes for everything except the `promiser', i.e. the
-command string that promises to execute.
-A more complex promise contains many attributes:
-
-@smallexample
-
-files:
-
- "/home/mark/tmp/test_plain" -> "system blue team",
-
- comment => "This comment follows the rule for knowledge integration",
- perms => users("@@(usernames)"),
- create => "true";
-
-@end smallexample
-The list of promisees is not used by CFEngine except for documentation, just
-as the comment attribute (which can be added to any promise) has no actual function
-other than to provide more information to the user in error tracing and auditing.
-
-You see several kinds of object in this example. All literal strings
-(e.g. @code{"true"}) in CFEngine 3 must be quoted. This provides
-absolute consistency and makes type-checking easy and error-correction
-powerful. All function-like objects (e.g. @code{users("..")}) are either builtin
-special functions or parameterized templates which contain the `meat' of the right hand
-side.
-
-The words @code{commands}, and @code{files} are built-in promise
-types. Promise types generally belong each to a particular component
-of CFEngine, as the components are designed to keep different kinds of
-promises. A few types, such as @code{vars}, @code{classes} and
-@code{reports} are common to all the different component bundles. You
-will find a full list of the promise types that can be made by the
-different components in the `bundles' chapters that follow.
-
-@c -----------------------------------------------------------------------
-@node Best practice for writing promises
-@section Best practice for writing promises
-
-When writing promises, get into the habit of giving every promise a comment
-that explains its intention.
-
-Also, give related promises @i{handles}, or labels that can be used to
-refer to them.
-
-@verbatim
-
-files:
-
- "/var/cfengine/inputs"
-
- handle => "update_policy",
- comment => "Update the configuration from a master server",
-
- perms => system("600"),
- copy_from => mycopy("$(master_location)","$(policy_server)"),
- depth_search => recurse("inf"),
- file_select => input_files,
- action => immediate;
-
-@end verbatim
-If a promise affects another promise in some way, you can make the affected
-promise one of the promisees, like this:
-
-@verbatim
-
-access:
-
- "/master/cfengine/inputs" -> { "update_policy", "other_promisee" },
-
- comment => "Grant access to policy to our clients",
- handle => "serve_updates",
-
- admit => { "217.77.34.*" };
-
-@end verbatim
-
-@noindent Conversely, if a promise might depend on another in some (even indirect) way, document this too.
-
-@verbatim
-
-files:
-
- "/var/cfengine/inputs"
-
- comment => "Update the configuration from a master server",
- handle => "update_policy",
-
- depends_on => {"serve_updates"},
-
- perms => system("600"),
- copy_from => mycopy("$(master_location)","$(policy_server)"),
- depth_search => recurse("inf"),
- file_select => input_files,
- action => immediate;
-
-
-@end verbatim
-
-Get into the habit of adding the cause-effect lines of influence.
-Enterprise editions of CFEngine will track the dependencies between these
-promises and map out impact analyses.
-
-@c -----------------------------------------------------------------------
-@node Containers
-@section Containers
-
-CFEngine allows you to group multiple promise statements
- into containers called bundles.
-@smallexample
-
-bundle agent identifier
-
-@{
-commands:
-
- "/bin/echo These commands are a silly way to use CFEngine";
- "/bin/ls -l";
- "/bin/echo But they illustrate a point";
-
-@}
-
-@end smallexample
-
-Bundles serve two purposes: they allow us to collect related promises under a
-single heading, like a subroutine, and they allow us to mix configuration for different
-parts of CFEngine in the same file. The type of a bundle is the name of the component
-of CFEngine for which it is intended.
-
-For instance, we can make a self-contained example agent-server
-configuration by labelling the bundles:
-
-@smallexample
-
-#
-# Not a complete example
-#
-
-bundle agent testbundle
-
-@{
-files:
-
- "/home/mark/tmp/testcopy"
-
- comment => "Throwaway example...",
- copy_from => mycopy("/home/mark/LapTop/words","127.0.0.1"),
- perms => system,
- depth_search => recurse("inf");
-
-@}
-
-#
-
-bundle server access_rules
-
-@{
-access:
-
- "/home/mark/LapTop"
-
- admit => @{ "127.0.0.1" @};
-@}
-
-@end smallexample
-
-Another type of container in CFEngine 3 is a `body' part. Body parts
-exist to hide complex parameter information in reusable containers.
-The right hand side of some attribute assignments use body containers
-to reduce the amount of in-line information and preserve readability.
-You cannot choose where to use bodies: either they are used or they
-are not used for a particular kind of attribute. What you can choose, however, is
-the name and number of parameters for the body; and you can make as many of them as you like:
-For example:
-
-@smallexample
-
-body copy_from mycopy(from,server)
-
-@{
-source => "$(from)";
-servers => @{ "$(server)" @};
-copy_backup => "true";
-
-special_class::
-
- purge => "true";
-@}
-
-@end smallexample
-
-Notice also that classes can be used in bodies as well as parameters so that
-you can hide environmental adaptations in these bodies also. The classes used
-here are effectively ANDed with the classes under which the calling promise
-is defined.
-
-
-@c -----------------------------------------------------------------------
-@node When and where are promises made?
-@section When and where are promises made?
-
-When you type a promise into a CFEngine bundle, the promise will be
-read by every cf-agent that reads the file, each time it is
-called into being. For some promises this is okay, but for others
-you only want to verify the promise once in a while, e.g. once per day
-or once per hour. There are two ways to say when and where a promise
-applies in CFEngine:
-
-@table @i
-@item Classes
-Classes are the double-colon decision syntax in CFEngine. They
-determine in what context a promise is made, i.e. when and
-where. Recall the basic syntax of a promise:
-@smallexample
-
- @var{promise-type}:
-
- @var{class-expression}::
-
- @var{promiser} -> @var{promisee}
-
- @var{attribute} => @var{body},
- ifvarclass => @var{other-class-expression};
-
-@end smallexample
-The class expression may contain words like @samp{Hr12}, meaning
-from 12:00 p.m - 13:00 p.m., or @samp{Hr12&Min05_10}, meaning
-between 12:05 and 12:10. Classes may also have spatial descriptors
-like @samp{myhost} or @samp{solaris}, which decide which hosts
-in the namespace, or @samp{ipv4_192_168_1_101} which decides the location
-in IPv4 address space.
-
-If the class expression is true, the promise can be considered made
-for the duration of the current execution.
-
-CFEngine 3 has a new class predicate @code{ifvarclass} which is
-ANDed with the normal class expression, and which is evaluated
-together with the promise. It may contain variables as long as the
-resulting expansion is a legal class expression.
-@cindex ifvarclass
-
-@item Locks
-Locks determine how often a promise is verified.
-@end table
-
-CFEngine is controlled by a series of locks which prevent it from
-checking promises too often, and which prevent it from spending too
-long trying to verify promises it already verified recently. The locks
-work in such a way that you can start several CFEngine processes
-simultaneously without them interfering with each other. You can
-control two things about each kind of action in the action sequence:
-
-@table @samp
-
-@item ifelapsed
-The minimum time (in minutes) which should have passed since the last time
-that promise was verified. It will not be executed again until
-this amount of time has elapsed.
-(Default time is 1 minute.)
-
-@item expireafter
-The maximum amount (in minutes) of time cf-agent should wait for an old
-instantiation to finish before killing it
-and starting again. (Default time is 120 minutes.)
-
-@end table
-
-@noindent
-You can set these values either globally (for all
-actions) or for each action separately. If you
-set global and local values, the local values override
-the global ones. All times are written in units
-of @emph{minutes}. Global setting is in the control body:
-
-@verbatim
-
-body agent control
-{
-ifelapsed => "60"; # one hour
-}
-
-@end verbatim
-
-@noindent
-or locally in the transaction bodies:
-
-
-@verbatim
-
-body action example
-{
-ifelapsed => "90"; # 1.5 hours
-}
-
-@end verbatim
-
-These locks do not prevent the whole of cf-agent from running, only
-atomic promise checks. Several different atoms can be run concurrently
-by different cf-agents. The locks ensure that atoms will never be
-started by two cf-agents at the same time, or too soon after a
-verification, causing contention and wasting CPU cycles.
-
-
-@c -----------------------------------------------------------------------
-@node Types in CFEngine 3
-@section Types in CFEngine 3
-
-A key difference in CFEngine 3 compared to earlier versions is the
-presence of data types. Data types are a mechanism for associating
-values and checking consistency in a language. Once again, there is a
-simple pattern to types in CFEngine.
-
-The principle is very simple: types exist in order to match like a
-plug-socket relationship. In the examples above, you can see two places
-where types are used to match templates:
-
-@itemize
-@item Matching bundles to CFEngine components (such as agent, server, common, etc.):
-@smallexample
-
-bundle TYPE name # matches TYPE to running agent
-@{
-@}
-
-@end smallexample
-
-@item Match bodies templates to lvalues in @code{lvalues => rvalue} constraints:
-
-@smallexample
-
-body TYPE name # matches TYPE => name in promise
-@{
-@}
-
-@end smallexample
-@end itemize
-
-Check these by identifying the words @samp{agent} and @samp{copy_from}
-in the examples above. Types are there to make configuration more robust.
-
-@c -----------------------------------------------------------------------
-@node Datatypes in CFEngine 3
-@section Datatypes in CFEngine 3
-
-CFEngine variables have two meta-types: scalars and lists. A scalar is a single value,
-a list is a collection of scalars. Each scalar may have one of three types:
-@code{string}, @code{int} or @code{real}. Typing is dynamic, so these are
-interchangable in many instances. However arguments to special functions check legal
-type for consistency.
-
-Integer constants may use suffixes to represent large numbers.
-
-@itemize
- @item 'k'
- = value times 1000.
-
- @item 'K'
- = value times 1024.
-
- @item 'm'
- = value times 1000^2
- @item 'M'
- = value times 1024^2
- @item 'g'
- = value times 1000^3
- @item 'G'
- = value times 1024^3
-
- @item '%'
- meaning percent, in limited contexts
-
- @item 'inf'
- = a constant representing an unlimited value.
-@end itemize
-
-@c -----------------------------------------------------------------------
-@node Variable expansion in CFEngine 3
-@section Variable expansion in CFEngine 3
-
-CFEngine 3 has some simple rules for variable expansion. These make
-a couple of restrictions that enforce discipline of clarity and
-allow automatic dependency tracking in enterprise versions of CFEngine.
-
-@menu
-* Scalar variable expansion::
-* List variable substitution and expansion::
-* Special list value cf_null::
-* Arrays in CFEngine 3::
-@end menu
-
-@node Scalar variable expansion
-@subsection Scalar variable expansion
-
-Scalar variables are written @samp{$(name)} and they represent
-a single value at a time.
-
-@itemize
-@item Scalars that are written without a context, e.g. @samp{$(myvar)}
-are local to the current bundle (and are equivalent to @samp{$(this.myvar)}).
-
-@item Scalars are globally available everywhere provided one
-uses the context to verify them e.g. @samp{$(context.myvar)}
-may be written to access the variable `myvar' in bundle `context'.
-
-@end itemize
-
-@c -----------------------------------------------------------------------
-@node List variable substitution and expansion
-@subsection List variable substitution and expansion
-
-@itemize
-
-@item Scalar references to @i{local} list variables imply iteration, e.g.
-suppose we have local list variable @samp{@@(list)}, then the
-scalar @samp{$(list)} implies an iteration over every value of the
-list.
-
-
-@item Lists can be passed around in their entirety in any context
-where a list is expected as @samp{@@(list)}., e.g.
-
-@verbatim
-
- vars:
-
- "longlist" slist => { @(shortlist), "plus", "plus" };
-
- "shortlist" slist => { "you", "me" };
-
-@end verbatim
-
-@end itemize
-
-You can pass lists to functions by parameter or by qualified reference.
-The first uses parameterization to map a global list into a local
-context.
-@verbatim
-
-#
-# Show access of external lists.
-#
-# - to pass lists globally, use a parameter to dereference them
-#
-
-body common control
-{
-bundlesequence => { hardening(@(va.tmpdirs)) };
-}
-
-#########################################################
-
-bundle common va
-{
-vars:
-
- "tmpdirs" slist => { "/tmp", "/var/tmp", "/usr/tmp" };
-
-}
-
-##########################################################
-
-bundle agent hardening(x)
-{
-classes:
-
- "ok" expression => "any";
-
-vars:
-
- "other" slist => { "/tmp", "/var/tmp" };
-
-reports:
-
- ok::
-
- "Do $(x)";
- "Other: $(other)";
-}
-
-@end verbatim
-
-This alternative uses a direct `short-circuit' approach to map the global
-list into the local context.
-
-@verbatim
-#
-# Show access of external lists.
-#
-
-body common control
-{
-bundlesequence => { hardening };
-}
-
-#########################################################
-
-bundle common va
-{
-vars:
-
- "tmpdirs" slist => { "/tmp", "/var/tmp", "/usr/tmp" };
-
-}
-
-##########################################################
-
-bundle agent hardening
-{
-classes:
-
- "ok" expression => "any";
-
-vars:
-
- "other" slist => { "/tmp", "/var/tmp" };
- "x" slist => { @(va.tmpdirs) };
-
-reports:
-
- ok::
-
- "Do $(x)";
- "Other: $(other)";
-}
-@end verbatim
-
-@c -----------------------------------------------------------------------
-
-@node Special list value cf_null
-@subsection Special list value @code{cf_null}
-
-As of CFEngine core version 3.1.0, the value @samp{cf_null} may be used as a NULL
-value within lists. This value is ignored in list variable expansion.
-
-@verbatim
-
-vars:
-
- "empty_list" slist => { "cf_null" };
-
-@end verbatim
-
-@c -----------------------------------------------------------------------
-@node Arrays in CFEngine 3
-@subsection Arrays in CFEngine 3
-
-Array variables are written with @samp{[} and @samp{]} brackets, e.g.
-
-@verbatim
-body common control
-
-{
- bundlesequence => { "example" };
-}
-
-bundle agent example
-
-{
-vars:
-
- "component" slist => { "cf-monitord", "cf-serverd", "cf-execd" };
-
- "array[cf-monitord]" string => "The monitor";
- "array[cf-serverd]" string => "The server";
- "array[cf-execd]" string => "The executor, not executioner";
-
-commands:
-
- "/bin/echo $(component) is"
-
- args => "$(array[$(component)])";
-
-}
-
-@end verbatim
-
-Arrays are associative and may be of type scalar or list. Enumerated
-arrays are simply treated as a special case of associative arrays, since
-there are no numerical loops in CFEngine. Special functions exist to
-extract lists of keys from array variables for iteration purposes.
-
-Thus one could have written the example above in the form of the
-following example. Note, too, that the use of @code{getindices} avoids the earlier poor practice of repeating the enumeration of key names, and instead uses the better strategy of automatically deriving them.
-
-@verbatim
-body common control
-
-{
- bundlesequence => { "example" };
-}
-
-bundle agent example
-
-{
-vars:
-
- "array[cf-monitord]" string => "The monitor";
- "array[cf-serverd]" string => "The server";
- "array[cf-execd]" string => "The executor, not executioner";
-
- "component" slist => getindices("array");
-
-commands:
-
- "/bin/echo $(component) is"
-
- args => "$(array[$(component)])";
-}
-
-@end verbatim
-
-
-@c -----------------------------------------------------------------------
-@node Name spaces
-@section Name spaces
-
-Name spaces are private bundle and body contexts, allowing multiple files
-to define the bundles and bodies with the same name, without conflict.
-
-To isolate a file into its own name space, you add a control promise
-to the file before the relevant bundles or bodies. All files start off in the
-default namespace if you don't explicitly set this. Once set, this applies
-until the end of the file or the next namespace change.
-
-@verbatim
-body file control
-{
-namespace => "myspace";
-}
-@end verbatim
-
-To distinguish the bundle @code{mymethod} in the default namespace
-from one in another namespace, you prefix the bundle name with the
-namespace, separated by a colon.
-@verbatim
-methods:
-
- "namespace demo" usebundle => myspace:mymethod("arg1");
-
- "namespace demo" usebundle => mymethod("arg1","arg2");
-
-@end verbatim
-
-To distinguish a body from one in another namespace, you can prefix
-the body name with the namespace, separated by a colon.
-@verbatim
-files:
-
- "/file"
-
- create => "true",
- perms => name1:settings;
-
-@end verbatim
-
-The default namespace, i.e. that which is implied by not making any namespace
-declarations, can be accessed or referred to by prefixing with the default string
-
-@verbatim
-files:
-
- "/file"
-
- create => "true",
- perms => default:settings;
-
-@end verbatim
-@noindent For example, this can be used to refer to standard library objects from
-within a private namespace.
-
-Global classes are not handled by namespaces, and you are advised to prefix
-them with the namespace like this:
-
-@verbatim
-files:
-
- "/file"
-
- create => "true",
- action => if_repaired("namespace_done");
-
-@end verbatim
-@noindent This is not prepended automatically because references to this
-class in class expressions cannot be detected and modified automatically.
-
-To access variables or meta-data in bundles in a different namespace, use the colon
-as a namespace prefix:
-
-@verbatim
-
- $(namespace:bundle.variable)
- $(namespace:bundle_meta.variable)
-
-@end verbatim
-
-
-@c -----------------------------------------------------------------------
-@node Normal ordering
-@section Normal ordering
-
-
-CFEngine takes a pragmatic point of view to ordering. When promising
-`scalar' attributes and properties, ordering is irrelevant and need
-not be considered. More complex patterned data structures require
-ordering to be preserved, e.g. editing in files. CFEngine
-solves this in a two-part strategy:
-@itemize
-@item CFEngine maintains a default order of promise-types. This is based
-on a simple logic of what needs to come first, e.g. it makes no sense to create something
-and then delete it, but it could make sense to delete and then create (an equilibrium).
-This is called @i{normal ordering} and is described below.
-
-@item You can override normal ordering in exceptional circumstances by making
-a promise in a class context and defining that class based on the outcome of another
-promise.
-@end itemize
-
-@menu
-* Agent normal ordering::
-* Server normal ordering::
-* Monitor normal ordering::
-@end menu
-
-@node Agent normal ordering
-@subsection Agent normal ordering
-
-@enumerate
-@item
-CFEngine tries to keep variable and class promises before starting to
-consider any other kind of promise. In this way, global variable and
-classes can be set, as well as creating @code{classes} promises, upon
-which later agent-bundle @code{vars} promises may depend. Place these
-at the start of your configuration (see next item).
-
-@item If you set variables based on classes that are determined by variables, in a
-complex dependency chain, then you introduce an order dependence to
-the resolution that might be non-unique. Since CFEngine starts trying
-to converge values as soon as possible, it is best to define variables
-in bundles before using them, i.e. as early as possible in your
-configuration. In general it is wise to avoid class-variable
-dependency as much as possible.
-
-@item
-CFEngine executes agent promise bundles in the strict order defined by
-the @code{bundlesequence} (possibly overridden by the @code{-b} or
-@code{--bundlesequence} command line option).
-@item
-Within a bundle, the promise types are executed in a round-robin
-fashion according to so-called `normal ordering' (essentially deletion
-first, followed by creation). The actual sequence continues for up to three
-iterations of the following, converging towards a final state:
-
-@verbatim
- meta
- vars
- defaults
- classes
- outputs
- interfaces
- files
- packages
- guest_environments
- methods
- processes
- services
- commands
- storage
- databases
- reports
-@end verbatim
-
-Within @code{edit_line} bundles in @code{files} promises
-(See `File editing in CFEngine 3' for important details),
-the normal ordering is:
-@verbatim
- vars
- classes
- delete_lines
- field_edits
- insert_lines
- replace_patterns
- reports
-@end verbatim
-
-@item
-The order of promises within one of the above types follows their
-top-down ordering within the bundle itself
-
-@item
-The order may be overridden by making a promise depend on a class
-that is set by another promise.
-
-@end enumerate
-
-@node Server normal ordering
-@subsection Server normal ordering
-
-
-As with the agent, common bundles are executed before any server bundles;
-following this @i{all} server bundles are executed (the @code{bundlesequence}
-is only used for @code{cf-agent}).
-Within a server bundle, the promise types are unamgibuous.
-Variables and classes are resolved in the same way as the agent.
-On connection, access control must be handled first, then a role
-request might be made once access has been granted. Thus ordering
-is fully constrained by process with no additional freedoms.
-
-Within a server bundle, the normal ordering is:
-
-@verbatim
- vars
- classes
- access
- roles
-@end verbatim
-
-@node Monitor normal ordering
-@subsection Monitor normal ordering
-
-As with the agent, common bundles are executed before any monitor bundles;
-following this @i{all} monitor bundles are executed (the @code{bundlesequence}
-is only used for @code{cf-agent}).
-Variables and classes are resolved in the same way as the agent.
-
-Within a monitor bundle, the normal ordering is:
-
-@verbatim
- vars
- classes
- measurements
- reports
-@end verbatim
-
-@c -----------------------------------------------------------------------
-@node Loops and lists in CFEngine 3
-@section Loops and lists in CFEngine 3
-
-There are no explicit loops in CFEngine, instead there are lists.
-To make a loop, you simply refer to a list as a scalar and CFEngine
-will assume a loop over all items in the list.
-
-For example, in the examples below the list @code{component} has three
-elements. The list as a whole may be referred to as
-@code{@@(component)}, in order to pass the whole list to a promise
-where a list is expected. However, if we write @code{$(component)},
-i.e. the scalar variable, then CFEngine assumes that it should substitute
-each scalar from the list in turn, and thus iterate over the list
-elements using a loop.
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-vars:
-
- "component" slist => { "cf-monitord", "cf-serverd", "cf-execd" };
-
- "new_list" slist => { "cf-know", @(component) };
-
-processes:
-
- "$(component)" restart_class => canonify("start_$(component)");
-
-commands:
-
- "/bin/echo /var/cfengine/bin/$(component)"
-
- ifvarclass => canonify("start_$(component)");
-}
-
-@end verbatim
-
-If a variable is repeated, its value is tied throughout
-the expression; so the output of:
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-bundle agent example
-
-{
-vars:
-
- "component" slist => { "cf-monitord", "cf-serverd", "cf-execd" };
-
- "array[cf-monitord]" string => "The monitor";
- "array[cf-serverd]" string => "The server";
- "array[cf-execd]" string => "The executor, not executioner";
-
-commands:
-
- "/bin/echo $(component) is"
-
- args => "$(array[$(component)])";
-}
-
-@end verbatim
-
-@noindent is as follows:
-
-@verbatim
-
-Q ".../bin/echo cf-mo": cf-monitord is The monitor
- -> Last 1 QUOTEed lines were generated by "/bin/echo cf-monitord is The monitor"
-Q ".../bin/echo cf-se": cf-serverd is The server
- -> Last 1 QUOTEed lines were generated by "/bin/echo cf-serverd is The server"
-Q ".../bin/echo cf-ex": cf-execd is The executor, not executioner
- -> Last 1 QUOTEed lines were generated by "/bin/echo cf-execd is The executor, not executioner"
-
-@end verbatim
-
-
-@c -----------------------------------------------------------------------
-@node Pattern matching and referencing
-@section Pattern matching and referencing
-
-One of the strengths of CFEngine 3 is the ability to recognize and
-exploit patterns. All string patterns in CFEngine 3 are matched using
-PCRE regular expressions.
-
-CFEngine has the ability to extract back-references from pattern matches.
-This makes sense in two cases. Back references are fragments of a string
-that match parenethetic expressions. For instance, suppose we have the string:
-
-@smallexample
-
- Mary had a little lamb ...
-
-@end smallexample
-
-@noindent and apply the regular expression
-
-@smallexample
-
- "Mary ([^l]+)little (.*)"
-
-@end smallexample
-The pattern matches the entire string, and it
-contains two parenthesized subexpressions, which respectively match
-the fragments `had a ' and `lamb ...'. The regular
-expression libraries assign @i{three} matches to this
-result, labelled 0, 1 and 2.
-
-The zeroth value is the entire string matched by the
-total expression. The first value is the fragment matched
-by the first parenthesis, and so on.
-
-Each time CFEngine matches a string, these values are
-assigned to a special variable context @code{$(match.@var{n})}.
-The fragments can be referred to in the remainder of the promise.
-There are two places where this makes sense. One is in pattern replacement
-during file editing, and the other is in searching for files.
-
-Consider the examples below:
-@verbatim
-
-bundle agent testbundle
-
-{
-files:
-
- # This might be a dangerous pattern - see explanation in the next section
- # on "Runaway change warning"
-
- "/home/mark/tmp/cf([23])?_(.*)"
- edit_line => myedit("second backref: $(match.2)");
-}
-
-@end verbatim
-There are other filenames that could match this pattern, but if, for
-example, there were to exist a file @file{/home/mark/tmp/cf3_test},
-then we would have:
-
-@table @samp
-@item $(match.0)
-equal to `/home/mark/tmp/cf3_test'
-@item $(match.1)
-equal to `3'
-@item $(match.2)
-equal to `test'
-@end table
-
-Note that because the pattern allows for an @i{optional} '2' or '3' to follow
-the letters 'cf', it is possible that @code{$(match.1)} would contain the
-empty string. For example, if there was a file named
-@file{/home/mark/tmp/cf_widgets}, then we would have@table @samp
-@item $(match.0)
-equal to `/home/mark/tmp/cf_widgets'
-@item $(match.1)
-equal to `'
-@item $(match.2)
-equal to `widgets'
-@end table
-
-Now look at the edit bundle. This takes a parameter (which is the
-back-reference from the filename match), but it also uses back references to
-replace shell comment lines with C comment lines (the same
-approach is used to hash-comment lines in files). The back-reference
-variables @code{$(match.@var{n})} refer to the most recent pattern match, and
-so in the @samp{C_comment} body, they do not refer to the filename components,
-but instead to the hash-commented line in the @samp{replace_patterns} promise.
-
-@verbatim
-###########################################################
-
-body common control
-
-{
-bundlesequence => { "example" };
-}
-
-###########################################################
-
-
-bundle agent example
-
-{
-vars:
-
- "file" string => "/tmp/test.cfengine3";
-
-files:
- "${file}"
- create => "true",
- edit_line => myedit("test_parameter");
-}
-
-
-bundle edit_line myedit(parameter)
- {
- vars:
-
- "edit_variable" string => "private edit variable is $(parameter)";
-
- insert_lines:
-
- "$(edit_variable)";
-
- replace_patterns:
-
- # replace shell comments with C comments
-
- "#(.*)"
-
- replace_with => C_comment,
- select_region => MySection("New section");
-
- }
-
-########################################
-# Bodies
-########################################
-
-body replace_with C_comment
-
-{
-replace_value => "/* $(match.1) */"; # backreference from replace_patterns
-occurrences => "all"; # first, last, or all
-}
-
-########################################################
-
-body select_region MySection(x)
-
-{
-select_start => "\[$(x)\]";
-select_end => "\[.*\]";
-}
-
-@end verbatim
-
-Put this example in the file /tmp/test.cfengine3
-@verbatim
-[First section]
-
-one
-two
-three
-
-[New section]
-
-four
-#five
-six
-
-[final]
-
-seven
-eleven
-@end verbatim
-
-@noindent The resulting file is edited like this:
-@verbatim
-[First section]
-
-one
-two
-three
-
-[New section]
-
-four
-/* five */
-six
-
-[final]
-
-seven
-eleven
-
-private edit variable is test_parameter
-@end verbatim
-
-@menu
-* Runaway change warning::
-* Commenting lines::
-* Regular expressions in paths::
-* Anchored vs. unanchored regular expressions::
-* Special topics on Regular Expressions::
-@end menu
-
-@node Runaway change warning
-@subsection Runaway change warning
-
-Be careful when using patterns to search for files that are altered by CFEngine
-if you are not using a file repository. Each time CFEngine makes a change it
-saves an old file into a copy like @file{cf3_test.cf-before-edit}. These
-new files then get matched by the same expression above -- because it ends
-in the generic@code{.*}), or does not
-specify a tail for the expression. Thus CFEngine will happily edit backups
-of the edit file too, and generate a recursive process, resulting in something
-like the following:
-
-@smallexample
-cf3_test cf3_test.cf-before-edit
-cf3_test~ cf3_test~.cf-before-edit.cf-before-edit
-cf3_test~.cf-before-edit cf3_test~.cf-before-edit.cf-before-edit.cf-before-edit
-@end smallexample
-
-Always try to be as specific as possible when specifying patterns. A lazy approach
-will often come back to haunt you.
-
-
-@node Commenting lines
-@subsection Commenting lines
-
-The following example shows how you would hash-comment lines in a file
-using CFEngine 3.
-
-@verbatim
-######################################################################
-#
-# HashCommentLines implemented in CFEngine 3
-#
-######################################################################
-
-body common control
-
-{
-version => "1.2.3";
-bundlesequence => { "testbundle" };
-}
-
-########################################################
-
-bundle agent testbundle
-
-{
-files:
-
- "/tmp/comment_test"
-
- create => "true",
- edit_line => comment_lines_matching;
-}
-
-########################################################
-
-bundle edit_line comment_lines_matching
- {
- vars:
-
- "regexes" slist => { "one.*", "two.*", "four.*" };
-
- replace_patterns:
-
- "^($(regexes))$"
- replace_with => comment("# ");
- }
-
-########################################
-# Bodies
-########################################
-
-body replace_with comment(c)
-
-{
-replace_value => "$(c) $(match.1)";
-occurrences => "all";
-}
-
-@end verbatim
-
-Put this example in /tmp/comment_test
-@begin verbatim
-one $
-two #
-three &
-four *
-@end verbatim
-
-@noindent The resulting file is edited like this:
-@begin verbatim
-# one $
-# two #
-three &
-# four *
-@end verbatim
-
-@node Regular expressions in paths
-@subsection Regular expressions in paths
-
-When applying regular expressions in paths, the path will first be
-split at the path separators, and each element matched
-independently. For example, this makes it possible to write
-expressions like @code{"/home/.*/file"} to match a single file inside
-a lot of directories --- the .* does not eat the whole string.
-
-Note that whenever regular expressions are used in paths, the @code{/} is
-always used as the path separator, even on Windows. However, on Windows, if
-the pathname is interpreted literally (no regular expressions), then the
-backslash is also recognized as the path separator. This is because the
-backslash has a special (and potentially ambiguous) meaning in regular
-expressions (a @code{\d} means the same as @code{[0-9]}, but on Windows it
-could also be a path separator and a directory named @code{d}).
-
-The @code{pathtype} attribute allows you to force a specific behavior when
-interpreting pathnames. By default, CFEngine looks at your pathname and
-makes an educated guess as to whether your pathname contains a regular
-expression. The values @code{"literal"} and @code{"regex"} explicitly force
-CFEngine to interpret the pathname either one way or another.
-
-(see the @code{pathtype} attribute).
-
-@verbatim
-
-body common control
-{
-bundlesequence => { "wintest" };
-}
-
-########################################
-
-bundle agent wintest
-{
-files:
- "c:/tmp/file/f.*" # "best guess" interpretation
- delete => nodir;
-
-
- "c:\tmp\file"
- delete => nodir,
- pathtype => "literal"; # force literal string interpretation
-
-
- "C:/windows/tmp/f\d"
- delete => nodir,
- pathtype => "regex"; # force regular expression interpretation
-}
-
-########################################
-
-body delete nodir
-{
-rmdirs => "false";
-}
-
-@end verbatim
-
-Note that the path @samp{/tmp/gar.*} will only match filenames
-like @file{/tmp/gar}, @file{/tmp/garbage} and @file{/tmp/garden}. It will
-@i{not} match filename like @file{/tmp/gar/baz} (because even though the
-@samp{.*} in a regular expression means "zero or more of any character",
-CFEngine restricts that to mean "zero or more of any character @i{in a path
-component}"). Correspondingly, CFEngine
-also restricts where you can use the @samp{/} character (you can't use it
-in a character class like @samp{[^/]} or in a parenthesized or repeated
-regular expression component.
-
-This means that regular expressions which include "optional directory
-components" won't work. You can't have a files promise to tidy the directory
-@samp{(/usr)?/tmp}. Instead, you need to be more verbose and specify
-@samp{/usr/tmp|/tmp}, or even better, think declaratively and create an
-@i{slist} that contains both the strings @samp{/tmp} and @samp{/usr/tmp},
-and then allow CFEngine to iterate over the list!
-
-This also means that the path @samp{/tmp/.*/something} will match files like
-@file{/tmp/abc/something} or @file{/tmp/xyzzy/something}. However, even
-though the pattern @samp{.*} means "zero or more of any character (except
-@samp{/})", CFEngine matches files bounded by directory separators. So even
-though the pathname @file{/tmp//something} is technically the same as the
-pathname @file{/tmp/something}, the regular expression @samp{/tmp/.*/something}
-will @i{not} match on the degenerate case of @file{/tmp//something} (or
-@file{/tmp/something}).
-
-@node Anchored vs. unanchored regular expressions
-@subsection Anchored vs. unanchored regular expressions
-
-CFEngine uses the full power of regular expressions, but there are two ``flavors'' of regex. Because they
-behave somewhat differently (while still utilizing the same syntax), it is
-important to know which one is used for a particular component of CFEngine:
-
-@itemize
-
-@item
-An ``anchored'' regular expression will only successfully match an
-entire string, from start to end. An anchored regular expression
-behaves as if it starts with @samp{^} and ends with @samp{$}, whether
-you specify them yourself or not. Furthermore, an anchored regular
-expression cannot have these automatic anchors removed.
-
-@item
-An ``unanchored'' regular expression may successfully match anywhere
-in a string. An unanchored regex may use anchors (such as @samp{^},
-@samp{$}, @samp{\A}, @samp{\Z}, @samp{\b}, etc.) to restrict where
-in the string it may match. That is, an unanchored regular expression
-may be easily converted into a partially- or fully-anchored regex.
-
-@end itemize
-
-For example, the @code{comment} parameter in @code{readstringarray}
-is an unanchored regex (@pxref{Function readstringarray}). If you
-specify the regular expression as @code{"#.*"}, then on any line
-which contains a pound sign, everything from there until the end
-of the line will be removed as a comment. However, if you specify
-the regular expression as @code{"^#.*"} (note the @samp{^} anchor
-at the start of the regex), then only lines which @i{start} with a
-@samp{#} will be removed as a comment! If you want to ignore C-style
-comment in a multi-line string, then you have to a bit more clever,
-and use this regex: @code{"(?s)/\*.*?\*/"}
-
-Conversely, @code{delete_lines} promises use anchored regular
-expressions to delete lines. If our promise uses @code{"bob:\d*}
-as a line-matching regex, then only the second line of this file
-will be deleted (because only the second line starts with @samp{bob:}
-and is then followed exclusively by digits, all the way to the end of
-the string).
-
-@verbatim
-bobs:your:uncle
-bob:111770
-thingamabob:1234
-robert:bob:xyz
-i:am:not:bob
-@end verbatim
-
-If CFEngine expects an unanchored regular expression, then finding
-every line that contains the letters @samp{bob} is easy. You just
-use the regex @code{"bob"}. But if CFEngine expects an anchored
-regular expression, then you must use @code{".*bob.*"}.
-
-If you want to find every line that has a field which is exactly
-@samp{bob} with no characters before or after, then it is only a
-little more complicated if CFEngine expects an unanchored regex:
-@code{"(^|:)bob(:|$)"}. But if CFEngine expects an anchored
-regular expression, then it starts getting ugly, and you'd need to
-use @code{"bob:.*|.*:bob:.*|.*:bob"}.
-
-
-@node Special topics on Regular Expressions
-@subsection Special topics on Regular Expressions
-
-Regular expressions are a complicated subject, and really are beyond the
-scope of this document. However, it is worth mentioning a couple of special
-topics that you might want to know of when using regular expressions.
-
-The first is how to @i{not} get a backreference. If you want to have a
-parenthesized expression that does not generate a back reference, there is a
-special PCRE syntax to use. Instead of using @code{()} to bracket the piece
-of a regular expression, use @code{(?:)} instead. For example, this will
-match the filenames @file{foolish}, @file{foolishly}, @file{bearish},
-@file{bearishly}, @file{garish}, and @file{garishly} in the @file{/tmp}
-directory. The variable @code{$match.0} will contain the full filename, and
-@code{$match.1} will either contain the string @samp{ly} or the empty string.
-But the @code{(?:}expression@code{)} which matches foo, bear,
-or gar does @i{not} create a back-reference:
-
-@verbatim
-files:
- "/tmp/(?:foo|bear|gar)ish(ly)?"
-
-@end verbatim
-
-Note that sometimes multi-line strings are subject to be matched by
-regular expressions. CFEngine internally matches all regular
-expressions using PCRE_DOTALL option, so @code{.} matches newlines. If
-you want to match any character except newline you could use @code{\N}
-escape sequence.
-
-Another thing you might want to do is ignore capitalization. CFEngine is
-case-sensitive (in all things), so the files promise @file{/tmp/foolish} will
-not match the files @file{/tmp/Foolish} or @file{/tmp/fOoLish}, etc. There are
-two ways to acheive case-insensitivity. The first is to use character classes:
-
-@verbatim
-files:
- "/tmp/[Ff][Oo][Oo][Ll][Ii][Ss][Hh]"
-
-@end verbatim
-
-While this is certainly correct, it can also lead to unreadability. The PCRE
-patterns in CFEngine have another way of introducing case-insensitvity into a
-pattern:
-
-@verbatim
-files:
- "/tmp/(?i:foolish)"
-@end verbatim
-
-The @code{(?i:)} brackets impose case-insensitive matching on the text that
-it surrounds, without creating a sub-expression. You could also write the
-regular expression like this (but be aware that the two expressions are
-different, and work slightly differently, so check the documentation for the
-specifics):
-
-@verbatim
-files:
- "/tmp/(?i)foolish"
-@end verbatim
-
-
-The @code{/s}, @code{/m}, and @code{/x} switches from PCRE are also
-available, but use them with great care!
-
-
-@c ----------------------------------------------------------------------------
-@node Distributed discovery
-@section Distributed discovery
-
-CFEngine's philosophy and modus operandi is to make machines as self-reliant
-as possible. This is the path to scalability. Sometimes we want machines
-to be able to detect one another and sample each others' behaviour. This can
-be accomplished using probes and server functions.
-
-For example, testing whether services are up and running can be a useful
-probe even from a local host. CFEngine has in-built functions for generically
-probing the environment; these are designed to encourage decentralized
-monitoring.
-
-@verbatim
-
-body common control
-
-{
-bundlesequence => { "test" };
-}
-
-###########################################################
-
-bundle agent test
-
-{
-vars:
-
- "hosts" slist => { "server1.example.org", "server2", "server3" };
-
- "up_servers" int => selectservers("@(hosts)","80","","","100","alive_servers");
-
-classes:
-
- "someone_alive" expression => isgreaterthan("$(up_servers)","0");
-
- "i_am_a_server" expression => regarray("up_servers","$(host)|$(fqhost)");
-
-reports:
-
- someone_alive::
-
- "Number of active servers $(up_servers)" action => always;
-
- "First server $(alive_servers[0]) fails over to $(alive_servers[1])";
-
-
-}
-
-@end verbatim
-
-@c -----------------------------------------------------------------------
-
-@node How to run CFEngine 3 examples
-@chapter How to run CFEngine 3 examples
-
-The CFEngine @file{tests} directory contains a multitude of examples of CFEngine 3 code.
-These instructions assume that you have all of your configuration in a
-single test file, such as the example in the distribution directory
-@file{tests/units}.
-
-@enumerate
-@item Test the file as a non-privileged user first, if you can.
-
-@item Always verify syntax first with @code{cf-promises}. This requires no privileges.
-An @code{cf-agent} will not execute a configuration that has not passed this test.
-
-@smallexample
-
-host$ cf-promises -f ./inputfile.cf
-
-@end smallexample
-
-@item Run the examples like this, e.g.
-
-@smallexample
-
-host$ src/cf-promises -f ./tests/units/unit_server_copy_localhost.cf
-host$ src/cf-serverd -f ./tests/units/unit_server_copy_localhost.cf
-host$ src/cf-agent -f ./tests/units/unit_server_copy_localhost.cf
-
-@end smallexample
-
-@end enumerate
-
-Running @code{cf-agent} in verbose mode provides detailed information
-about the state of the systems promises.
-
-@smallexample
-Outcome of version 1.2.3: Promises observed to be kept 99%,
-Promises repaired 1%, Promises not repaired 0%
-@end smallexample
-
-The log-file @file{WORKDIR/promise.log} contains the summary of these reports
-with timestamps. This is the simplest kind of high level audit record of the
-system.
-
-
-
-
-@c ---------------------------------------------------------------------------
-@node A complete configuration
-@chapter A complete configuration
-
-To illustrate a complete configuration for agents and daemons,
-consider the following example code, supplied in the @file{inputs/}
-directory of the distribution. Comments indicate the thinking behind
-this starting point.
-
-
-@menu
-* promises.cf::
-* site.cf::
-* update.cf::
-* failsafe.cf::
-* What should a failsafe or update file contain::
-* Recovery from errors in the configuration::
-* Recovery from errors in the software::
-@end menu
-
-@node promises.cf
-@section @file{promises.cf}
-
-This file is the first file that @code{cf-agent} with no arguments
-will try to look for. It should contain all of the basic
-configuration settings, including a list of other files
-to include. In normal operation, it must have a @code{bundlesequence}.
-
-This file can stay fixed, except for extending the bundlesequence.
-The bundlesequence acts like the `genetic makeup' of the
-configuration. In a large configuration, you might want to have a
-different bundlesequence for different classes of host, so that you
-can build a complete system like a check-list from different
-combinations of building blocks. You can construct different lists by
-composing them from other lists, or you can use @code{methods}
-promises as an alternative for composing bundles for different classes.
-
-@verbatim
-#######################################################
-#
-# promises.cf
-#
-#######################################################
-
-body common control
-
-{
-# List the `genes' for this system..
-
-bundlesequence => {
- "update",
- "garbage_collection",
- "main",
- "cfengine"
- };
-
-
-inputs => {
- "update.cf",
- "site.cf",
- "library.cf"
- };
-}
-
-#######################################################
-# Now set defaults for all components' hard-promises
-#######################################################
-
-body agent control
-{
-# if default runtime is 5 mins, we need more for long jobs
-ifelapsed => "15";
-}
-
-#######################################################
-
-body monitor control
-{
-forgetrate => "0.7";
-}
-
-###########si###########################################
-
-body executor control
-
-{
-splaytime => "1";
-mailto => "cfengine_mail@example.org";
-smtpserver => "localhost";
-mailmaxlines => "30";
-
-# Instead of a separate update script, now do this
-
-exec_command => "$(sys.workdir)/bin/cf-agent -f failsafe.cf && $(sys.workdir)/bin/cf-agent";
-}
-
-#######################################################
-
-body runagent control
-{
-hosts => {
- "127.0.0.1"
- # , "myhost.example.com:5308", ...
- };
-
-}
-
-#######################################################
-
-body server control
-
-{
-allowconnects => { "127.0.0.1" , "::1" };
-allowallconnects => { "127.0.0.1" , "::1" };
-trustkeysfrom => { "127.0.0.1" , "::1" };
-
-# Make updates and runs happen in one
-
-cfruncommand => "$(sys.workdir)/bin/cf-agent";
-
-allowusers => { "root" };
-}
-
-@end verbatim
-
-
-
-@node site.cf
-@section @file{site.cf}
-
-Use this file to add your site-specific configuration.
-Common bundles can be used to define global variables.
-Otherwise, unqualified variables are local to the bundle in which
-they are defined -- however they can be accessed by
-writing @code{$(bundle_name.variable_name)}.
-
-@verbatim
-#######################################################
-#
-# site.cf
-#
-#######################################################
-
-bundle common g
-{
-vars:
-
- SuSE::
-
- "crontab" string => "/var/spool/cron/tabs/root";
-
- !SuSE::
-
- "crontab" string => "/var/spool/cron/crontabs/root";
-}
-
-@end verbatim
-
-The CFEngine bundle below detects whether CFEngine 2 is already
-running on the host or not, and if so attempts to kill off old daemon
-processes and encapsulate the agent. It also looks for rules in the
-old CFEngine configuration that would potentially spoil CFEngine 3's
-control of the system: the last thing we want is for CFEngine 2 and
-CFEngine 3 to fight each other for control of the system. CFEngine 3
-tries to edit an existing crontab entry to replace any references to
-@code{cfexecd} with @code{cf-execd}; if none are found it will add a 5
-minute run schedule. You should never put @code{cf-agent}or
-@code{cf-agent} directly inside @code{cron} without the @code{cf-execd}
-wrapper.
-
-@verbatim
-#######################################################
-# Start with CFEngine itself
-#######################################################
-
-bundle agent cfengine
-
-{
-classes:
-
- "integrate_cfengine2"
-
- and => {
- fileexists("$(sys.workdir)/inputs/cfagent.conf"),
- fileexists("$(sys.workdir)/bin/cfagent")
- };
-
-vars:
-
- "cf2bits" slist => { "cfenvd", "cfservd", "cfexecd" };
-
-commands:
-
- integrate_cfengine2::
-
- "$(sys.workdir)/bin/cfagent"
-
- action => longjob;
-
-files:
-
- # Warn about rules relating to CFEngine 2 in inputs - could conflict
-
- "$(sys.workdir)/inputs/.*"
-
- comment => "Check if there are still promises about CFEngine 2 that need removing",
- edit_line => DeleteLinesMatching(".*$(cf2bits).*"),
- file_select => OldCf2Files,
- action => WarnOnly;
-
- # Check cf-execd and schedule is in crontab
-
- "$(g.crontab)"
- edit_line => upgrade_cfexecd,
- classes => define("exec_fix");
-
-processes:
-
- exec_fix::
-
- "cron" signals => { "hup" };
-
-
-}
-
-#######################################################
-# General site issues can be in bundles like this one
-#######################################################
-
-bundle agent main
-
-{
-vars:
-
- "component" slist => { "cf-monitord", "cf-serverd" };
-
- # - - - - - - - - - - - - - - - - - - - - - - - -
-
-files:
-
- "$(sys.resolv)" # test on "/tmp/resolv.conf" #
-
- create => "true",
- edit_line => resolver,
- edit_defaults => def;
-
- # Uncomment this to perform a change-detection scan
-
- # "/usr"
- # changes => lay_trip_wire,
- # depth_search => recurse("inf"),
- # action => measure;
-
-processes:
-
- "cfenvd" signals => { "term" };
-
- # Uncomment this when you are ready to upgrade the server
- #
- # "cfservd" signals => { "term" };
- #
-
- # Now make sure the new parts are running, cf-serverd will fail if
- # the old server is still running
-
- "$(component)" restart_class => canonify("start_$(component)");
-
- # - - - - - - - - - - - - - - - - - - - - - - - -
-
-commands:
-
- "$(sys.workdir)/bin/$(component)"
-
- ifvarclass => canonify("start_$(component)");
-
-}
-
-@end verbatim
-
-This section takes a backup of a user home directory. This is
-especially useful for a single laptop or personal workstation that
-does not have a regular external backup. If a user deletes a file by
-accident, this shadow backup might contain the file even while
-travelling offline.
-
-@verbatim
-
-#######################################################
-# Backup
-#######################################################
-
-bundle agent backup
-{
-files:
-
- "/home/backup"
-
- copy_from => cp("/home/mark"),
- depth_search => recurse("inf"),
- file_select => exclude_files,
- action => longjob;
-
-}
-
-#######################################################
-# Garbage collection issues
-#######################################################
-
-bundle agent garbage_collection
-{
-files:
-
- "$(sys.workdir)/outputs"
-
- delete => tidy,
- file_select => days_old("3"),
- depth_search => recurse("inf");
-
-
-}
-
-###########################################################
-
-body file_select OldCf2Files
-{
-leaf_name => {
- "promises\.cf",
- "site\.cf",
- "library\.cf",
- "failsafe\.cf",
- ".*\.txt",
- ".*\.html",
- ".*~",
- "#.*"
- };
-
-file_result => "!leaf_name";
-}
-
-###########################################################
-
-body action measure
-{
-measurement_class => "Detect Changes in /usr";
-ifelapsed => "240"; # 4 hours
-expireafter => "240"; # 4 hours
-}
-
-@end verbatim
-
-Some basic anomaly detection: we respond with simple warnings
-if resource anomalies are detected.
-
-@verbatim
-#######################################################
-# Anomaly monitoring
-#######################################################
-
-bundle agent anomalies
-{
-reports:
-
-rootprocs_high_dev2::
-
- "RootProc anomaly high 2 dev on $(mon.host) at $(mon.env_time)
- measured value $(mon.value_rootprocs) av $(mon.av_rootprocs)
- pm $(mon.dev_rootprocs)"
-
- showstate => { "rootprocs" };
-
-entropy_www_in_high&anomaly_hosts.www_in_high_anomaly::
-
- "HIGH ENTROPY Incoming www anomaly high anomaly dev!!
- on $(mon.host) at $(mon.env_time)
- - measured value $(mon.value_www_in)
- av $(mon.av_www_in) pm $(mon.dev_www_in)"
-
- showstate => { "incoming.www" };
-
- entropy_www_in_low.anomaly_hosts.www_in_high_anomaly::
-
- "LOW ENTROPY Incoming www anomaly high anomaly dev!!
- on $(mon.host) at $(mon.env_time)
- - measured value $(svalue_www_in)
- av $(av_www_in) pm $(dev_www_in)"
-
- showstate => { "incoming.www" };
-
-entropy_tcpsyn_in_low.anomaly_hosts.tcpsyn_in_high_dev2::
-
- "Anomalous number of new TCP connections on $(mon.host)
- at $(mon.env_time)
- - measured value $(mon.value_tcpsyn_in)
- av $(mon.av_tcpsyn_in) pm $(mon.dev_tcpsyn_in)"
-
- showstate => { "incoming.tcpsyn" };
-
- entropy_dns_in_low.anomaly_hosts.dns_in_high_anomaly::
-
- "Anomalous (3dev) incoming DNS packets on $(mon.host)
- at $(mon.env_time) - measured value $(mon.value_dns_in)
- av $(av_dns_in) pm $(mon.dev_dns_in)"
-
- showstate => { "incoming.dns" };
-
- entropy_dns_in_low.anomaly_hosts.udp_in_high_dev2::
-
- "Anomalous (2dev) incoming (non-DNS) UDP traffic
- on $(mon.host) at $(mon.env_time) - measured value
- $(mon.value_udp_in) av $(mon.av_udp_in) pm $(mon.dev_udp_in)"
-
- showstate => { "incoming.udp" };
-
- anomaly_hosts.icmp_in_high_anomaly.!entropy_icmp_in_high::
-
- "Anomalous low entropy (3dev) incoming ICMP traffic
- on $(mon.host) at $(mon.env_time) - measured value $(mon.value_icmp_in)
- av $(mon.av_icmp_in) pm $(mon.dev_icmp_in)"
-
- showstate => { "incoming.icmp" };
-}
-
-@end verbatim
-
-Server access rules are a touchy business. In an enterprise
-setting you generally want every host to allow a monitoring
-host to be able to download data, and a backup host to be able
-to access important data on every host. On a laptop or personal
-workstation, there might not be any reason to run a server
-for external use; however you might configure it as below
-to allow localhost access for testing.
-
-@verbatim
-
-#######################################################
-# Server configuration
-#######################################################
-
-bundle server access_rules()
-{
-access:
-
- "/home/mark/test_area"
-
- admit => { "127.0.0.1" };
-
- # Rule for cf-runagent
-
- "/home/mark/.cfagent/bin/cf-agent"
-
- admit => { "127.0.0.1" };
-
-# New in cf3 - RBAC with cf-runagent
-
-roles:
-
- ".*" authorize => { "mark" };
-}
-
-@end verbatim
-
-
-@node update.cf
-@section @file{update.cf}
-
-This file should rarely if ever change. Should you ever change it (or when you
-upgrade CFEngine), take special care to ensure the old and the new CFEngine can
-parse and execute this file successfully. If not, you risk losing control of
-your system (that is, if CFEngine cannot successfully execute this set of
-promises, it has no mechanism for distributing @i{new} policy files).
-
-By default, the policy defined in @file{update.cf} is executed from two sets
-of promise bodies. The ``usual'' one (defined in the @code{bundlesequence}
-in @file{promises.cf}) and another in the backup/failsafe @code{bundlesequence}
-(defined in @file{failsafe.cf}).
-
-@verbatim
-#########################################################
-#
-# update.cf
-#
-#########################################################
-
-bundle agent update
-{
-vars:
-
- "master_location" string => "/your/master/cfengine-inputs";
-
-files:
-
- # Update the configuration
-
- "/var/cfengine/inputs"
-
- perms => system("600"),
- copy_from => mycopy("$(master_location)","localhost"),
- depth_search => recurse("inf"),
- action => immediate;
-
-}
-
-############################################
-
-body perms system(p)
-
-{
-mode => "$(p)";
-}
-
-############################################
-
-body file_select cf3_files
-
-{
-leaf_name => { "cf-.*" };
-
-file_result => "leaf_name";
-}
-
-#########################################################
-
-body copy_from mycopy(from,server)
-
-{
-source => "$(from)";
-compare => "digest";
-}
-
-#########################################################
-
-body action immediate
-{
-ifelapsed => "1";
-}
-@end verbatim
-
-
-
-
-@node failsafe.cf
-@section @file{failsafe.cf}
-
-This file should probably never change. The only job of @file{failsafe.cf} is
-to execute the @code{update} bundle in a ``standalone'' context should there be
-a syntax error somewhere in the main set of promises. In this way, if a
-client machine's policies are ever corrupted after downloading erroneous
-policy from a server, that client will have a failsafe method for downloading
-a corrected policy once it becomes available on the server. Note that by
-``corrupted'' and ``erroneous'' we typically mean ``broken via administrator
-error'' - mistakes happen, and the @file{failsafe.cf} file is CFEngine's way
-of being prepared for that eventuality.
-
-If you ever change @file{failsafe.cf} (or when you
-upgrade CFEngine), make sure the old and the new CFEngine can successfully
-parse and execute this file. If not, you risk losing control of your system
-(that is, if CFEngine cannot successfully execute this policy file, it has no
-failsafe/fallback mechanism for distributing @i{new} policy files).
-
-@verbatim
-#########################################################
-#
-# Failsafe file
-#
-#########################################################
-
-body common control
-
-{
-bundlesequence => { "update" };
-
-inputs => { "update.cf" };
-}
-
-############################################
-
-body depth_search recurse(d)
-
-{
-depth => "$(d)";
-}
-
-@end verbatim
-
-
-@node What should a failsafe or update file contain
-@section What should a failsafe and update file contain?
-
-
-The @file{failsafe.cf} file is to make sure that your system can
-upgrade gracefully to new versions even when mistakes are made.
-
-
-As a general rule:
-@itemize
-
-@item
-Upgrade the software first, then add new features
-to the configuration.
-
-@item
-Never use advanced features in the failsafe or update file.
-
-@item
-Avoid using library code (including any bodies from @file{cfengine_stdlib.cf}).
-Copy/paste any bodies you need using a unique name that does not collide with
-a name in library (we recommend simply adding the prefix ``@code{u_}''). This
-may mean that you create duplicate functionality, but that is okay in this
-case to ensure a 100% functioning @i{standalone} update process). The promises
-which manage the update process should not have @i{any} dependencies on any
-other files.
-
-@end itemize
-
-@noindent A CFEngine configuration will fail-over to the @code{failsafe.cf}
-configuration
-if it is unable to read or parse the contents successfully. That means
-that any syntax errors you introduce (or any new features you utilize in a
-configuration) will cause a
-fail-over, because the parser will not be able to interpret the policy. If
-the failover is due to the use of new features, they will not parse until the
-software itself has been updated (so we recommend that you always update
-CFEngine before updating policy to use new features). If you accidentally
-cause a bad (i.e., unparseable) policy to be distributed to client machines,
-the @code{failsafe.cf} policy on those machines will run (and will eventually
-download a working policy, once you fix it on the policy host).
-
-
-
-@node Recovery from errors in the configuration
-@section Recovery from errors in the configuration
-
-The @file{failsafe.cf} file should be able to download the latest
-master configuration from source always.
-
-@verbatim
-
-#######################################################
-#
-# failsafe.cf
-#
-#######################################################
-
-body common control
-
-{
-bundlesequence => { "update" };
-}
-
-#########################################################
-
-bundle agent update
-{
-files:
-
- "/var/cfengine/inputs"
-
- perms => system,
- copy_from => mycopy("/home/mark/cfengine-inputs","localhost"),
- file_select => cf3_files,
- depth_search => recurse("inf");
-}
-
-#########################################################
-
-body perms system
-
-{
-mode => "0700";
-}
-
-#########################################################
-
-body depth_search recurse(d)
-
-{
-depth => "$(d)";
-}
-
-############################################
-
-body file_select cf3_files
-
-{
-leaf_name => { "cf-.*" };
-
-file_result => "leaf_name";
-}
-
-#########################################################
-
-body copy_from mycopy(from,server)
-
-{
-source => "$(from)";
-servers => { "$(server)" , "failover.domain.tld" };
-#copy_backup => "true";
-#trustkey => "true";
-encrypt => "true";
-}
-
-@end verbatim
-
-@noindent If the @code{copy_backup} option is true, CFEngine will keep a single
-previous version of the file before copy, if the value is @samp{timestamp}
-CFEngine keeps time-stamped versions either in the location of the file, or in the
-file repository if one is defined. The @code{trustkey} option should normally
-be commented out so that public keys are only exchanged under controlled conditions.
-
-
-@node Recovery from errors in the software
-@section Recovery from errors in the software
-
-The update should optionally include an update of software
-so that a single failover from a configuration that is `too new'
-for the software will still correct itself once the new software
-is available.
-
-@verbatim
-
-#######################################################
-#
-# update.cf
-#
-#######################################################
-
-bundle agent update
-
-{
-files:
-
- "/var/cfengine/inputs"
-
- perms => system("600"),
- copy_from => mycopy("/home/mark/cfengine-inputs","localhost"),
- depth_search => recurse("inf");
-}
-
-############################################
-
-body perms system(p)
-
-{
-mode => "$(p)";
-}
-
-############################################
-
-body file_select cf3_files
-
-{
-leaf_name => { "cf-.*" };
-
-file_result => "leaf_name";
-}
-
-#########################################################
-
-body copy_from mycopy(from,server)
-
-{
-source => "$(from)";
-compare => "digest";
-}
-
-@end verbatim
diff --git a/docs/reference/reference_control_intro.texinfo b/docs/reference/reference_control_intro.texinfo
deleted file mode 100644
index 648ad4e5c1..0000000000
--- a/docs/reference/reference_control_intro.texinfo
+++ /dev/null
@@ -1,17 +0,0 @@
-
-While promises to configure your system are entirley user-defined, the
-details of the operational behaviour of the CFEngine software is of
-course hard-coded. You can still configure the details of this
-behaviour using the control promise bodies. Control behaviour is
-defined in bodies because the actual promises are fixed and you only
-change their details within sensible limits.
-
-Note that in CFEngine's previous versions, the @code{control} part of
-the configuration contained a mixture of internal control parameters
-and user definitions. There is now a cleaner separation in
-CFEngine 3. User defined behaviour requires a promise, and must
-therefore be defined in a bundle.
-
-Below is a list of the control parameters for the different components
-(Agents and Daemons@footnote{There is no Da Vinci code in CFEngine}) of the CFEngine software.
-
diff --git a/docs/reference/reference_logs.texinfo b/docs/reference/reference_logs.texinfo
deleted file mode 100644
index 94e8678d1b..0000000000
--- a/docs/reference/reference_logs.texinfo
+++ /dev/null
@@ -1,174 +0,0 @@
-
-CFEngine writes numerous logs and records to its private workspace,
-referred to as @file{WORKDIR}. This chapter makes some brief notes
-about these files. CFEngine approaches monitoring and reporting from
-the viewpoint of scalability so there is no default centralizatio of
-reporting information, as this is untenable for more than a few
-hundred hosts. Instead, in the classic CFEngine way, every host
-is reponsible for its own data. Solutions for centralization and
-netwide reporting will be given elsewhere.
-
-The filenames referred to in this section are all relative to the
-CFEngine work directory @file{WORKDIR}.
-
-@menu
-* Embedded Databases::
-* Text logs::
-* Reports in outputs::
-* Additional reports in commercical CFEngine versions::
-* State information::
-@end menu
-
-
-@node Embedded Databases
-@section Embedded Databases
-
-Embedded datbases' file extensions will vary based on which library is used to
-implement them; either Tokyo Cabinet (@code{.tcdb}), Quick Database
-Manager (@code{.qdbm}), or Berkeley DB (@code{.db}). Converting one
-database format to another is not handled by CFEngine, but there exist
-external tools meant for that purpose.
-
-@table @file
-@item cf_Audit.tcdb
-A compressed database of auditing information. This file grows very large
-is auditing is switched on. By default, only minor information about CFEngine runs
-are recorded. This file should be archived and deleted regularly to avoid choking
-the system.
-@item cf_lastseen.tcdb
-A database of hosts that last contacted this host, or were contacted by this
-host which includes the times at which they were last observed.
-@item cf_classes.tcdb
-A database of classes that have been defined on the current host, including
-their relative frequences, scaled like a probability.
-
-@item checksum_digests.tcdb
-The database of hash values used in CFEngine's change management functions.
-@item performance.tcdb
-A database of last, average and deviation times of jobs recorded by @code{cf-agent}.
-Most promises take an immeasurablely short time to check, but longer
-tasks such as command execution and file copying are measured by default.
-Other checks can be instrumented by setting a @code{measurement_class}
-in the @code{action} body of a promise.
-
-@item stats.tcdb
-A database of external file attributes for change management functionality.
-
-@item state/cf_lock.tcdb
-A database of active and inactive locks and their expiry times. Deleting
-this database will reset all lock protections in CFEngine.
-
-@item state/history.tcdb
-Enterprise level versions of CFEngine maintain this long-term trend database.
-
-@item state/cf_observations.tcdb
-This database contains the current state of the observational history
-of the host as recorded by @code{cf-monitord}.
-
-@item state/promise_compliance.tcdb
-Enterprise CFEngine (Nova and above) database of individual promise compliance history.
-The database is approximate because promise references can change as policy is
-edited. It quickly approaches accuracy as a policy goes unchanged for more than a day.
-
-@item state/cf_state.tcdb
-A database of persistent classes active on this current host.
-
-@item state/nova_measures.tcdb
-Enterprise CFEngine (Nova and above) database of custom measurables.
-@item state/nova_static.tcdb
-Enterprise CFEngine (Nova and above) database of static system discovery data.
-@end table
-
-@node Text logs
-@section Text logs
-
-@table @file
-@item promise_summary.log
-A time-stamped log of the percentage fraction of promises kept after each run.
-@item cf3.HOSTNAME.runlog
-A time-stamped log of when each lock was released. This shows the last
-time each individual promise was verified.
-@item cfagent.HOSTNAME.log
-Although ambiguously named (for historical reasons) this log contains the current
-list of setuid/setgid programs observed on the system. CFEngine warns about
-new additions to this list. This log has been deprecated.
-
-@item cf_value.log
-A time stamped log of the business value estimated from the execution of the automation
-system.
-
-@item cf_notkept.log
-A list of promises, with handles and comments, that were not kept. Nova enterprise versions only.
-
-@item cf_repaired.log
-A list of promises, with handles and comments, that were repaired. Nova enterprise versions only.
-
-@item reports/*
-Enterprise versions of CFEngine use this directory as a default place for
-outputting reports.
-
-@item reports/class_notes
-Class data in csv format for export to CMDB.
-
-@item state/file_change.log
-A time-stamped log of which files have experienced content changes
-since the last observation, as determined by the hashing algorithms in
-CFEngine.
-
-@item state/vars.out
-Enterprise level versions of CFEngine use this log to communicate variable
-data.
-
-@item state/*_measure.log
-Enterprise level versions of CFEngine maintain user-defined logs based on
-specifically promised observations of the system.
-
-
-@end table
-
-@node Reports in outputs
-@section Reports in outputs
-
-The @file{outputs} directory contains a time-stamped list of outputs
-generated by @code{cf-agent}. These are collected by @code{cf-execd}
-and are often E-mailed as reports. However, not all hosts have an
-E-mail capability or are online, so the reports are kept here. Reports
-are not tidied automatically, so you should delete these files after a
-time to avoid a build up.
-
-
-@node Additional reports in commercical CFEngine versions
-@section Additional reports in commcerical CFEngine versions
-
-
-
-
-@node State information
-@section State information
-
-The CFEngine components keep their current process identifier number
-in `pid files' in the work directory: e.g.
-
-@verbatim
-cf-execd.pid
-cf-serverd.pid
-@end verbatim
-
-Most other state data refer to the running condition of the host and
-are generated by @code{cf-monitord} (@code{cfenvd} in earlier versions
-of CFEngine).
-
-@table @file
-@item state/env_data
-This file contains a list of currently discovered classes and variable values
-that characterize the anomaly alert environment. They are altered by the monitor
-daemon.
-@item state/all_classes
-A list of all the classes that were defined the last time that CFEngine
-was run.
-@item state/cf_*
-All files that begin with this prefix refer to cached data that were observed
-by the monitor daemon, and may be used by @code{cf-agent} in @code{reports} with @code{showstate}.
-@end table
-
-
diff --git a/docs/reference/varcontexts/const_intro.texinfo b/docs/reference/varcontexts/const_intro.texinfo
deleted file mode 100644
index 81f07570c0..0000000000
--- a/docs/reference/varcontexts/const_intro.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-CFEngine defines a number of variables for embedding unprintable values
-or values with special meanings in strings.
diff --git a/docs/reference/varcontexts/edit_intro.texinfo b/docs/reference/varcontexts/edit_intro.texinfo
deleted file mode 100644
index eddb65b54a..0000000000
--- a/docs/reference/varcontexts/edit_intro.texinfo
+++ /dev/null
@@ -1,35 +0,0 @@
-
-This context @samp{edit} is used to access information about editing promises
-during their execution. It is context dependent and not universally
-meaningful or available. For example:
-
-@verbatim
-bundle agent testbundle
-{
-files:
-
- "/tmp/testfile"
- edit_line => test;
-}
-
-#
-
-bundle edit_line test
-{
-classes:
- "ok" expression => regline(".*mark.*","$(edit.filename)");
-
-reports:
-
- ok::
- "File matched $(edit.filename)";
-}
-
-@end verbatim
-
-@noindent @b{$(edit.filename)}
-
-This variable points to the filename of the file currently making an edit
-promise. If the file has been arrived at through a search, this could be
-different from the @file{files} promiser.
-
diff --git a/docs/reference/varcontexts/match_intro.texinfo b/docs/reference/varcontexts/match_intro.texinfo
deleted file mode 100644
index 6d9f721172..0000000000
--- a/docs/reference/varcontexts/match_intro.texinfo
+++ /dev/null
@@ -1,30 +0,0 @@
-
-Each time CFEngine matches a string, these values are
-assigned to a special variable context @code{$(match.@var{n})}.
-The fragments can be referred to in the remainder of the promise.
-There are two places where this makes sense. One is in pattern replacement
-during file editing, and the other is in searching for files.
-
-Consider the examples below:
-@verbatim
-
-bundle agent testbundle
-
-{
-files:
-
- "/home/mark/tmp/(cf[23])_(.*)"
- create => "true",
- edit_line => myedit("second $(match.2)");
-
-
- # but more specifically...
-
- "/home/mark/tmp/cf3_(test)"
- create => "true",
- edit_line => myedit("second $(match.1)");
-
-
-}
-
-@end verbatim
diff --git a/docs/reference/varcontexts/mon_intro.texinfo b/docs/reference/varcontexts/mon_intro.texinfo
deleted file mode 100644
index 45d4ca1c82..0000000000
--- a/docs/reference/varcontexts/mon_intro.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-The variables discovered by @code{cf-monitord} are placed in this
-monitoring context. Monitoring variables are expected to be ephemeral
-properties, rapidly changing.
-
-In enterprise versions of CFEngine, custom defined monitoring targets
-also become variables in this context, named by the handle of the
-promise that defined them.
-
diff --git a/docs/reference/varcontexts/sys_intro.texinfo b/docs/reference/varcontexts/sys_intro.texinfo
deleted file mode 100644
index 9b0b4a7e44..0000000000
--- a/docs/reference/varcontexts/sys_intro.texinfo
+++ /dev/null
@@ -1,21 +0,0 @@
-
-System variables are derived from CFEngine's automated discovery of system values.
-They are provided as variables in order to make automatically adaptive rules for
-configuration, e.g.
-
-@verbatim
-
-files:
-
- any::
-
- "$(sys.resolv)"
-
- create => "true",
- edit_line => doresolv("@(this.list1)","@(this.list2)"),
- edit_defaults => reconstruct;
-
-@end verbatim
-
-@noindent The above rule requires no class specification because the
-variable itself is class-specific.
diff --git a/docs/reference/varcontexts/this_intro.texinfo b/docs/reference/varcontexts/this_intro.texinfo
deleted file mode 100644
index e8300ddc54..0000000000
--- a/docs/reference/varcontexts/this_intro.texinfo
+++ /dev/null
@@ -1,118 +0,0 @@
-
-This context @samp{this} is used to access information about promises
-during their execution. It is context dependent and not universally
-meaningful or available, but provides a context for variables where one is
-needed (such as when passing the value of a list variable into a parameterized
-@code{edit_line} promise from a @code{file} promise). For example:
-
-@verbatim
-bundle agent resolver(s,n)
-{
-files:
- "$(sys.resolv)"
-
- create => "true",
- edit_line => doresolv("@(this.s)","@(this.n)"),
- edit_defaults => reconstruct;
-}
-@end verbatim
-
-Note that every unqualified variable is automatically considered to be in
-context @samp{this}, so that a reference to the variable @code{$(foo)} is
-identical to referencing @code{$(this.foo)}. You are strongly encourged to
-@b{not} take advantage of this behaviour, but simply to be aware that if you
-attempt to declare a variable name with one of the following special
-reserved names, CFEngine will issue a warning (and you can reference your
-variable by qualifying it with the bundle name in which it is declared).
-
-@menu
-* Variable this.bundle::
-* Variable this.handle::
-* Variable this.namespace::
-* Variable this.promise_filename::
-* Variable this.promise_linenumber::
-* Variable this.promiser::
-* Variable service_policy::
-* Variable this.this::
-@end menu
-
-@node Variable this.bundle
-@subsection Variable this.bundle
-
-This variable contains the current bundle name.
-
-@node Variable this.handle
-@subsection Variable this.handle
-
-This variable points to the promise handle of the currently handled promise;
- it is useful for referring to the intention in log messages.
-
-@node Variable this.namespace
-@subsection Variable this.namespace
-
-This variable contains the current namespace.
-
-@node Variable this.promise_filename
-@subsection Variable this.promise_filename
-
-This variable reveals the name of the file in which the current promise is defined.
-
-@node Variable this.promise_linenumber
-@subsection Variable this.promise_linenumber
-
-This variable reveals the line number in the file at which it is used. It is
-useful to differentiate otherwise identical reports promises.
-
-@node Variable this.promiser
-@subsection Variable this.promiser
-
-The special variable @code{$(this.promiser)} is used to refer to the current
-value of the promiser itself, in a number of allowed cases, typically when
-searches can take place. Current promise types that define @code{$(this.promiser)}
-are: @code{files}, @code{processes}, @code{commands}.
-
-This variable is useful in @code{files} promises, for instance when using
-pattern matching or @code{depth_search} that implicitly match multiple
-objects. In that case, @code{$(this.promiser)} refers to the
-currently identified file that makes the promise. For example:
-
-@verbatim
-bundle agent find666
-{
-files:
- "/home"
- file_select => world_writeable,
- transformer => "/bin/echo DETECTED $(this.promiser)",
- depth_search => recurse("inf");
-
- "/etc/.*"
- file_select => world_writeable,
- transformer => "/bin/echo DETECTED $(this.promiser)";
-}
-
-body file_select world_writeable
-{
- search_mode => { "o+w" };
- file_result => "mode";
-}
-@end verbatim
-
-@node Variable service_policy
-@subsection Variable service_policy
-
-This variable is set to the values of the promise attribute @code{service_policy}, e.g.
-
-@verbatim
-services:
-
- "www" service_policy => "start";
-@end verbatim
-@noindent and is typically used in the adaptations for custom services bundles
-in the service methods, @xref{service_method in services}.
-
-@node Variable this.this
-@subsection Variable this.this
-
-From version core 3.3.0 this variables is reserved. It is used by
-functions like @code{maplist()} to represent the current object in
-a transformation map.
diff --git a/docs/reference/vars/const_dollar.texinfo b/docs/reference/vars/const_dollar.texinfo
deleted file mode 100644
index 163207b9a6..0000000000
--- a/docs/reference/vars/const_dollar.texinfo
+++ /dev/null
@@ -1,14 +0,0 @@
-
-@verbatim
-
-reports:
-
- some::
-
- # This will report: The value of $(const.dollar) is $
- "The value of $(const.dollar)(const.dollar) is $(const.dollar)";
-
- # This will report: But the value of \$(dollar) is \$(dollar)
- "But the value of \$(dollar) is \$(dollar)";
-
-@end verbatim
diff --git a/docs/reference/vars/const_endl.texinfo b/docs/reference/vars/const_endl.texinfo
deleted file mode 100644
index f3d265ed25..0000000000
--- a/docs/reference/vars/const_endl.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-reports:
-
- cfengine_3::
-
- "A newline with either $(const.n) or with $(const.endl) is ok";
- "But a string with \n in it does not have a newline!";
-
-@end verbatim
diff --git a/docs/reference/vars/const_n.texinfo b/docs/reference/vars/const_n.texinfo
deleted file mode 100644
index f3d265ed25..0000000000
--- a/docs/reference/vars/const_n.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-@verbatim
-
-reports:
-
- cfengine_3::
-
- "A newline with either $(const.n) or with $(const.endl) is ok";
- "But a string with \n in it does not have a newline!";
-
-@end verbatim
diff --git a/docs/reference/vars/const_r.texinfo b/docs/reference/vars/const_r.texinfo
deleted file mode 100644
index 583cc39bc3..0000000000
--- a/docs/reference/vars/const_r.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-reports:
-
- cfengine_3::
-
- "A carriage return character is $(const.r)";
-
-@end verbatim
diff --git a/docs/reference/vars/const_t.texinfo b/docs/reference/vars/const_t.texinfo
deleted file mode 100644
index 52afb02298..0000000000
--- a/docs/reference/vars/const_t.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@verbatim
-
-reports:
-
- cfengine_3::
-
- "A report with a$(const.t)tab in it";
-
-@end verbatim
diff --git a/docs/reference/vars/edit_filename.texinfo b/docs/reference/vars/edit_filename.texinfo
deleted file mode 100644
index f749950d3d..0000000000
--- a/docs/reference/vars/edit_filename.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-This variable points to the filename of the file currently making an edit
-promise. If the file has been arrived at through a search, this could be
-different from the @file{files} promiser.
-
diff --git a/docs/reference/vars/match_0.texinfo b/docs/reference/vars/match_0.texinfo
deleted file mode 100644
index b4b056f62f..0000000000
--- a/docs/reference/vars/match_0.texinfo
+++ /dev/null
@@ -1,3 +0,0 @@
-
-A string matching the complete regular expression whether or not
-back-references were used in the pattern.
diff --git a/docs/reference/vars/sys_arch.texinfo b/docs/reference/vars/sys_arch.texinfo
deleted file mode 100644
index fd7a1e8cf0..0000000000
--- a/docs/reference/vars/sys_arch.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-
-The variable gives the kernel's short architecture description.
-
-@verbatim
-
-# arch = x86_64
-
-@end verbatim
diff --git a/docs/reference/vars/sys_cdate.texinfo b/docs/reference/vars/sys_cdate.texinfo
deleted file mode 100644
index ce20ad8d42..0000000000
--- a/docs/reference/vars/sys_cdate.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-The date of the system in canonical form, i.e. in the form of a class.
-
-@verbatim
-
-# cdate = Sun_Dec__7_10_39_53_2008_
-
-@end verbatim
diff --git a/docs/reference/vars/sys_cf_agent.texinfo b/docs/reference/vars/sys_cf_agent.texinfo
deleted file mode 100644
index 9841c6bdf1..0000000000
--- a/docs/reference/vars/sys_cf_agent.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-A variable containing the path to the CFEngine agent @code{cf-agent}
-on the platform you are using.
-
-@verbatim
-body executor control
-{
-exec_command => "$(sys.cf_twin) -f failsafe.cf && $(sys.cf_agent)";
-}
-
-@end verbatim
diff --git a/docs/reference/vars/sys_cf_execd.texinfo b/docs/reference/vars/sys_cf_execd.texinfo
deleted file mode 100644
index 0cf34e6582..0000000000
--- a/docs/reference/vars/sys_cf_execd.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-A variable containing the path to the CFEngine executor @code{cf-execd}
-on the platform you are using.
-
-@verbatim
-commands:
-
- "$(sys.cf_execd)";
-
-@end verbatim
diff --git a/docs/reference/vars/sys_cf_hub.texinfo b/docs/reference/vars/sys_cf_hub.texinfo
deleted file mode 100644
index bc7079b494..0000000000
--- a/docs/reference/vars/sys_cf_hub.texinfo
+++ /dev/null
@@ -1,14 +0,0 @@
-
-@i{History}: Was introduced in version 3.1.0b1,Nova 2.0.0b1 (2010)
-
-@verbatim
-
-reports:
-
- cfengine_3::
-
- "The hub path is $(sys.cf_hub)";
-
-@end verbatim
-
-The path of the @code{cf-hub} program.
diff --git a/docs/reference/vars/sys_cf_key.texinfo b/docs/reference/vars/sys_cf_key.texinfo
deleted file mode 100644
index 4a16fdd15e..0000000000
--- a/docs/reference/vars/sys_cf_key.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-
-A variable containing the path to the CFEngine key generator @code{cf-key}
-on the platform you are using.
-
-@verbatim
-
-commands:
-
- "$(sys.cf_key)";
-
-@end verbatim
diff --git a/docs/reference/vars/sys_cf_monitord.texinfo b/docs/reference/vars/sys_cf_monitord.texinfo
deleted file mode 100644
index 639e87ebfb..0000000000
--- a/docs/reference/vars/sys_cf_monitord.texinfo
+++ /dev/null
@@ -1,13 +0,0 @@
-
-
-A variable containing the path to the CFEngine monitoring daemon @code{cf-monitord}
-on the platform you are using.
-
-@verbatim
-commands:
-
- restart_monitord::
-
- "$(sys.cf_monitord)";
-
-@end verbatim
diff --git a/docs/reference/vars/sys_cf_promises.texinfo b/docs/reference/vars/sys_cf_promises.texinfo
deleted file mode 100644
index 2a72d47fdf..0000000000
--- a/docs/reference/vars/sys_cf_promises.texinfo
+++ /dev/null
@@ -1,13 +0,0 @@
-
-
-A variable containing the path to the CFEngine syntax analyxer @code{cf-promises}
-on the platform you are using.
-
-@verbatim
-
-classes:
-
- "syntax_ok" expression => returnszero("$(sys.cf_promises)");
-
-@end verbatim
-
diff --git a/docs/reference/vars/sys_cf_runagent.texinfo b/docs/reference/vars/sys_cf_runagent.texinfo
deleted file mode 100644
index a573769763..0000000000
--- a/docs/reference/vars/sys_cf_runagent.texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-This variable is used for completeness, but it is unlikely to be called from
-within CFEngine. It contains the full path to the interactive progam
-@code{cf-runagent}.
diff --git a/docs/reference/vars/sys_cf_serverd.texinfo b/docs/reference/vars/sys_cf_serverd.texinfo
deleted file mode 100644
index e0900a26d7..0000000000
--- a/docs/reference/vars/sys_cf_serverd.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-A variable containing the path to the CFEngine server daemon @code{cf-serverd}
-on the platform you are using.
-
-@verbatim
-commands:
-
- restart_serverd::
-
- "$(sys.cf_serverd)";
-
-@end verbatim
diff --git a/docs/reference/vars/sys_cf_twin.texinfo b/docs/reference/vars/sys_cf_twin.texinfo
deleted file mode 100644
index 357b2a101d..0000000000
--- a/docs/reference/vars/sys_cf_twin.texinfo
+++ /dev/null
@@ -1,15 +0,0 @@
-
-A variable containing the path to the CFEngine agent's twin
-@code{cf-twin} on the platform you are using. A twin is simply a
-second copy of the agent in CFEngine's work directory @samp{bin} area,
-used during upgrades and cases where modification of the
-@code{cf-agent} binary could be attempted (this is not allowed on some
-platforms, such as Windows).
-
-@verbatim
-body executor control
-{
-exec_command => "$(sys.cf_twin) -f failsafe.cf && $(sys.cf_agent)";
-}
-
-@end verbatim
diff --git a/docs/reference/vars/sys_cf_version.texinfo b/docs/reference/vars/sys_cf_version.texinfo
deleted file mode 100644
index 73e1f15a9e..0000000000
--- a/docs/reference/vars/sys_cf_version.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-The variable gives the version of the running CFEngine Community Edition.
-
-@verbatim
-
-# cf_version = 3.0.5
-
-@end verbatim
diff --git a/docs/reference/vars/sys_class.texinfo b/docs/reference/vars/sys_class.texinfo
deleted file mode 100644
index cba8c0bd8f..0000000000
--- a/docs/reference/vars/sys_class.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-This variable contains the name of the hard-class category for this host, i.e. its
-top level operating system type classification.
-
-@verbatim
-
-# class = linux
-
-@end verbatim
diff --git a/docs/reference/vars/sys_cpus.texinfo b/docs/reference/vars/sys_cpus.texinfo
deleted file mode 100644
index 3e414eb3e8..0000000000
--- a/docs/reference/vars/sys_cpus.texinfo
+++ /dev/null
@@ -1,20 +0,0 @@
-
-@i{History}: Was introduced in 3.3.0, Nova 2.2.0 (2012)
-
-A variable containing the number of CPU cores detected. On systems
-which provide virtual cores, it is set to the total number of virtual, not
-physical, cores. In addition, on a single-core system the class "1_cpu"
-is set, and on multi-core systems the class "@emph{n}_cpus" is set, where
-"@emph{n}" is the number of cores identified.
-
-@verbatim
-reports:
-
- cfengine_3::
-
- "Number of CPUS = $(sys.cpus)";
-
- 8_cpus::
- "This system has 8 processors.";
-
-@end verbatim
diff --git a/docs/reference/vars/sys_crontab.texinfo b/docs/reference/vars/sys_crontab.texinfo
deleted file mode 100644
index 4829f83884..0000000000
--- a/docs/reference/vars/sys_crontab.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-The variable gives the location of the current users's master crontab directory.
-
-@verbatim
-
-# crontab = /var/spool/crontas/root
-
-@end verbatim
diff --git a/docs/reference/vars/sys_date.texinfo b/docs/reference/vars/sys_date.texinfo
deleted file mode 100644
index 5155b4429e..0000000000
--- a/docs/reference/vars/sys_date.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-The date of the system as a text string.
-
-@verbatim
-
-# date = Sun Dec 7 10:39:53 2008
-
-@end verbatim
diff --git a/docs/reference/vars/sys_doc_root.texinfo b/docs/reference/vars/sys_doc_root.texinfo
deleted file mode 100644
index c73b34b6b4..0000000000
--- a/docs/reference/vars/sys_doc_root.texinfo
+++ /dev/null
@@ -1,5 +0,0 @@
-
-@i{History}: Was introduced in 3.1.0, Nova 2.0.
-
-A scalar variable containing the default path for the document root of the standard
-web server package.
diff --git a/docs/reference/vars/sys_domain.texinfo b/docs/reference/vars/sys_domain.texinfo
deleted file mode 100644
index 4c601cd7e0..0000000000
--- a/docs/reference/vars/sys_domain.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-The domain name as divined by CFEngine. If the DNS is in use, it could
-be possible to derive the domain name from its DNS regisration, but in
-general there is no way to discover this value automatically. The
-@code{common control} body permits the ultimate specification of this
-value.
-
-@verbatim
-
-# domain = example.org
-
-@end verbatim
diff --git a/docs/reference/vars/sys_enterprise_version.texinfo b/docs/reference/vars/sys_enterprise_version.texinfo
deleted file mode 100644
index 1381b3df44..0000000000
--- a/docs/reference/vars/sys_enterprise_version.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@i{History}: Was introduced in 3.5.0, Enterprise 3.0.0
-
-The variable gives the version of the running CFEngine Enterprise Edition.
-
-@verbatim
-
-# enterprise_version = 3.0.0
-
-@end verbatim
diff --git a/docs/reference/vars/sys_expires.texinfo b/docs/reference/vars/sys_expires.texinfo
deleted file mode 100644
index 07b7e342e0..0000000000
--- a/docs/reference/vars/sys_expires.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-@verbatim
-reports:
-
- nova::
-
- "License expires $(sys.expires)";
-@end verbatim
diff --git a/docs/reference/vars/sys_exports.texinfo b/docs/reference/vars/sys_exports.texinfo
deleted file mode 100644
index 1d5664f1ce..0000000000
--- a/docs/reference/vars/sys_exports.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-The location of the system NFS exports file.
-
-@verbatim
-
-# exports = /etc/exports
-# exports = /etc/dfs/dfstab
-
-@end verbatim
diff --git a/docs/reference/vars/sys_flavor.texinfo b/docs/reference/vars/sys_flavor.texinfo
deleted file mode 100644
index 7c73f99fe6..0000000000
--- a/docs/reference/vars/sys_flavor.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@i{History}: Was introduced in 3.2.0, Nova 2.0
-
-A variable containing an operating system identification string that
-is used to determine the current release of the operating system in a
-form that can be used as a label in naming. This is used, for
-instance, to detect which package name to choose when updating
-software binaries for CFEngine.
-
-This is a synonym for @code{$(sys.flavour)}.
diff --git a/docs/reference/vars/sys_flavour.texinfo b/docs/reference/vars/sys_flavour.texinfo
deleted file mode 100644
index 76a132b098..0000000000
--- a/docs/reference/vars/sys_flavour.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-@i{History}: Was introduced in 3.2.0, Nova 2.0
-
-A variable containing an operating system identification string that
-is used to determine the current release of the operating system in a
-form that can be used as a label in naming. This is used, for
-instance, to detect which package name to choose when updating
-software binaries for CFEngine.
-
-This is a synonym for @code{$(sys.flavor)}.
diff --git a/docs/reference/vars/sys_fqhost.texinfo b/docs/reference/vars/sys_fqhost.texinfo
deleted file mode 100644
index ea724e5e1b..0000000000
--- a/docs/reference/vars/sys_fqhost.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-The fully qualified name of the host. In order to compute this value properly, the domain
-name must be defined.
-
-@verbatim
-
-# fqhost = host.example.org
-
-@end verbatim
diff --git a/docs/reference/vars/sys_fstab.texinfo b/docs/reference/vars/sys_fstab.texinfo
deleted file mode 100644
index d5dcee262c..0000000000
--- a/docs/reference/vars/sys_fstab.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-The location of the system filesystem (mount) table.
-
-@verbatim
-
-# fstab = /etc/fstab
-
-@end verbatim
diff --git a/docs/reference/vars/sys_hardware_addresses.texinfo b/docs/reference/vars/sys_hardware_addresses.texinfo
deleted file mode 100644
index 9dc229b144..0000000000
--- a/docs/reference/vars/sys_hardware_addresses.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@i{History}: Was introduced in 3.3.0, Nova 2.2.0 (2011)
-
-
-This is a list variable containing a list of all known MAC addresses for
-system interfaces.
diff --git a/docs/reference/vars/sys_hardware_mac[interface_name].texinfo b/docs/reference/vars/sys_hardware_mac[interface_name].texinfo
deleted file mode 100644
index 6995ed9dde..0000000000
--- a/docs/reference/vars/sys_hardware_mac[interface_name].texinfo
+++ /dev/null
@@ -1,15 +0,0 @@
-
-@i{History}: Was introduced in 3.3.0, Nova 2.2.0 (2011)
-
-This contains the MAC address of the named interface. e.g.
-
-
-@verbatim
-
-reports:
-
- linux::
-
- "Tell me $(sys.hardware_mac[eth0])";
-@end verbatim
-
diff --git a/docs/reference/vars/sys_host.texinfo b/docs/reference/vars/sys_host.texinfo
deleted file mode 100644
index c654184328..0000000000
--- a/docs/reference/vars/sys_host.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-The name of the current host, according to the kernel. It is undefined whether this
-is qualified or unqualified with a domain name.
-
-@verbatim
-
-# host = myhost
-
-@end verbatim
diff --git a/docs/reference/vars/sys_hub_master.texinfo b/docs/reference/vars/sys_hub_master.texinfo
deleted file mode 100644
index e11580556c..0000000000
--- a/docs/reference/vars/sys_hub_master.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@i{History}: Was introduced in 3.2.0, Nova 2.1.0 (2011)
-
-@verbatim
-
-reports:
- am_hub_master::
- "This hub is a primary hub for other replicas";
- !am_hub_master::
- "This hub is replicated from $(sys.hub_master)";
-
-@end verbatim
diff --git a/docs/reference/vars/sys_interface.texinfo b/docs/reference/vars/sys_interface.texinfo
deleted file mode 100644
index 3a8846348c..0000000000
--- a/docs/reference/vars/sys_interface.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-The assumed (default) name of the main system interface on this host.
-
-@verbatim
-
-# interface = eth0
-
-@end verbatim
diff --git a/docs/reference/vars/sys_interface_flags[interface_name].texinfo b/docs/reference/vars/sys_interface_flags[interface_name].texinfo
deleted file mode 100644
index 6dd08e5817..0000000000
--- a/docs/reference/vars/sys_interface_flags[interface_name].texinfo
+++ /dev/null
@@ -1,31 +0,0 @@
-
-@i{History}: Was introduced in XXXX, Nova XXXX (2013)
-
-Contains a space separated list of the flags of the named interface. e.g.
-
-@verbatim
-
- reports:
-
- cfengine::
-
- "eth0 flags: $(sys.interface_flags[eth0])";
-@end verbatim
-
-@verbatim
-
-R: eth0 flags: up broadcast running multicast
-@end verbatim
-
-The following device flags are supported:
--up
--broadcast
--debug
--loopback
--pointopoint
--notrailers
--running
--noarp
--promisc
--allmulti
--multicast
diff --git a/docs/reference/vars/sys_interfaces.texinfo b/docs/reference/vars/sys_interfaces.texinfo
deleted file mode 100644
index fba79ef8ec..0000000000
--- a/docs/reference/vars/sys_interfaces.texinfo
+++ /dev/null
@@ -1,33 +0,0 @@
-
-@i{History}: Was introduced in 3.3.0, Nova 2.2.0 (2011)
-
-Displays a system list of configured interfaces currently active
-in use by the system.
-This list is detected at runtime and it passed in the variables report
-to a Mission Portal in commercial editions of CFEngine.
-
-To use this list in a policy, you will need a local copy since only local
-variables can be iterated.
-
-@verbatim
-
-bundle agent test
-{
-vars:
-
- # To iterate, we need a local copy
-
- "i1" slist => { @(sys.ip_addresses)} ;
- "i2" slist => { @(sys.interfaces)} ;
-
-reports:
-
- cfengine::
-
- "Addresses: $(i1)";
- "Interfaces: $(i2)";
- "Addresses of the interfaces: $(sys.ipv4[$(i2)])";
-
-}
-
-@end verbatim
diff --git a/docs/reference/vars/sys_ip_addresses.texinfo b/docs/reference/vars/sys_ip_addresses.texinfo
deleted file mode 100644
index a5a2e1fe79..0000000000
--- a/docs/reference/vars/sys_ip_addresses.texinfo
+++ /dev/null
@@ -1,32 +0,0 @@
-
-@i{History}: Was introduced in 3.3.0, Nova 2.2.0 (2011)
-
-Displays a system list of IP addresses currently in use by the system.
-This list is detected at runtime and it passed in the variables report
-to a Mission Portal in commercial editions of CFEngine.
-
-To use this list in a policy, you will need a local copy since only local
-variables can be iterated.
-
-@verbatim
-
-bundle agent test
-{
-vars:
-
- # To iterate, we need a local copy
-
- "i1" slist => { @(sys.ip_addresses)} ;
- "i2" slist => { @(sys.interfaces)} ;
-
-reports:
-
- cfengine::
-
- "Addresses: $(i1)";
- "Interfaces: $(i2)";
- "Addresses of the interfaces: $(sys.ipv4[$(i2)])";
-
-}
-
-@end verbatim
diff --git a/docs/reference/vars/sys_ipv4.texinfo b/docs/reference/vars/sys_ipv4.texinfo
deleted file mode 100644
index 330e0d4486..0000000000
--- a/docs/reference/vars/sys_ipv4.texinfo
+++ /dev/null
@@ -1,10 +0,0 @@
-
-All four octets of the IPv4 address of the first system interface.
-
-@noindent @b{Note}:@*
-
-If your system has a single ethernet interface, @samp{$(sys.ipv4)} will
-contain your IPv4 address. However, if your system has multiple interfaces,
-then @samp{$(sys.ipv4)} will simply be the IPv4 address of the first
-interface in the list that has an assigned address, @xref{Variable sys.ipv4[interface_name]}, for details on obtaining the IPv4
-addresses of all interfaces on a system.
diff --git a/docs/reference/vars/sys_ipv4[interface_name].texinfo b/docs/reference/vars/sys_ipv4[interface_name].texinfo
deleted file mode 100644
index 2b3997cca2..0000000000
--- a/docs/reference/vars/sys_ipv4[interface_name].texinfo
+++ /dev/null
@@ -1,28 +0,0 @@
-
-The full IPv4 address of the system interface named
-as the associative array index, e.g.
-@samp{$(ipv4[le0])} or @samp{$(ipv4[xr1])}.
-
-@verbatim
-
-# If the IPv4 address on the interfaces are
-# le0 = 192.168.1.101
-# xr1 = 10.12.7.254
-#
-# Then the octets of all interfaces are accessable as an associative array
-# ipv4_1[le0] = 192
-# ipv4_2[le0] = 192.168
-# ipv4_3[le0] = 192.168.1
-# ipv4[le0] = 192.168.1.101
-# ipv4_1[xr1] = 10
-# ipv4_2[xr1] = 10.12
-# ipv4_3[xr1] = 10.12.7
-# ipv4[xr1] = 10.12.7.254
-
-@end verbatim
-
-@noindent @b{Note}:@*
-
-The list of interfaces may be acquired with @samp{getindices("sys.ipv4")} (or
-from any of the other associative arrays). Only those interfaces which are
-marked as "up" and have an IP address will be listed.
diff --git a/docs/reference/vars/sys_ipv4_1[interface_name].texinfo b/docs/reference/vars/sys_ipv4_1[interface_name].texinfo
deleted file mode 100644
index 00263b8b8c..0000000000
--- a/docs/reference/vars/sys_ipv4_1[interface_name].texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-The first octet of the IPv4 address of the system interface named
-as the associative array index, e.g.
-@samp{$(ipv4_1[le0])} or @samp{$(ipv4_1[xr1])}, @xref{Variable sys.ipv4[interface_name]}.
diff --git a/docs/reference/vars/sys_ipv4_2[interface_name].texinfo b/docs/reference/vars/sys_ipv4_2[interface_name].texinfo
deleted file mode 100644
index 197b339045..0000000000
--- a/docs/reference/vars/sys_ipv4_2[interface_name].texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-The first two octets of the IPv4 address of the system interface named
-as the associative array index, e.g.
-@samp{$(ipv4_2[le0])} or @samp{$(ipv4_2[xr1])}, @xref{Variable sys.ipv4[interface_name]}.
diff --git a/docs/reference/vars/sys_ipv4_3[interface_name].texinfo b/docs/reference/vars/sys_ipv4_3[interface_name].texinfo
deleted file mode 100644
index 3529a1ed6c..0000000000
--- a/docs/reference/vars/sys_ipv4_3[interface_name].texinfo
+++ /dev/null
@@ -1,4 +0,0 @@
-
-The first three octets of the IPv4 address of the system interface named
-as the associative array index, e.g.
-@samp{$(ipv4_3[le0])} or @samp{$(ipv4_3[xr1])}, @xref{Variable sys.ipv4[interface_name]}.
diff --git a/docs/reference/vars/sys_key_digest.texinfo b/docs/reference/vars/sys_key_digest.texinfo
deleted file mode 100644
index d59e7ceb00..0000000000
--- a/docs/reference/vars/sys_key_digest.texinfo
+++ /dev/null
@@ -1,11 +0,0 @@
-
-Contains the unique identifier of the current host.
-
-@verbatim
-reports:
-
- cfengine_3_1::
-
- "My digest is $(sys.key_digest)";
-
-@end verbatim
diff --git a/docs/reference/vars/sys_last_policy_update.texinfo b/docs/reference/vars/sys_last_policy_update.texinfo
deleted file mode 100644
index f2199469c3..0000000000
--- a/docs/reference/vars/sys_last_policy_update.texinfo
+++ /dev/null
@@ -1,6 +0,0 @@
-
-@i{History}: Was introduced in 3.4.0, Nova 2.2.0 (2012)
-
-
-A scalar string variable containing the date stamp of the last time the agent's
-policy was updated from the policy server.
diff --git a/docs/reference/vars/sys_license_owner.texinfo b/docs/reference/vars/sys_license_owner.texinfo
deleted file mode 100644
index 8dc652fa5b..0000000000
--- a/docs/reference/vars/sys_license_owner.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@i{History}: Was introduced in version 3.1.4,Nova 2.0.2 (2011)
-
-@verbatim
-
-reports:
-
- nova::
-
- "This version of CFEngine is licensed to $(sys.license_owner)";
-
-@end verbatim
diff --git a/docs/reference/vars/sys_licenses_granted.texinfo b/docs/reference/vars/sys_licenses_granted.texinfo
deleted file mode 100644
index 57dc99c82b..0000000000
--- a/docs/reference/vars/sys_licenses_granted.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-@i{History}: Was introduced in version 3.1.4,Nova 2.0.2 (2011)
-
-@verbatim
-
-reports:
-
- nova::
-
- "There are $(sys.licenses_granted) licenses granted for use";
-
-@end verbatim
diff --git a/docs/reference/vars/sys_licenses_installtime.texinfo b/docs/reference/vars/sys_licenses_installtime.texinfo
deleted file mode 100644
index 32b0536d53..0000000000
--- a/docs/reference/vars/sys_licenses_installtime.texinfo
+++ /dev/null
@@ -1,13 +0,0 @@
-
-@i{History}: Was introduced in version 3.1.5, Nova 2.1 (2011)
-
-@verbatim
-
-reports:
-
- nova::
-
- "The license was installed on $(sys.licenses_installtime)";
-
-
-@end verbatim
diff --git a/docs/reference/vars/sys_long_arch.texinfo b/docs/reference/vars/sys_long_arch.texinfo
deleted file mode 100644
index c87774a6cd..0000000000
--- a/docs/reference/vars/sys_long_arch.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-The long architecture name for this system kernel. This name is sometimes quite unwieldy
-but can be useful for logging purposes.
-
-@verbatim
-
-# long_arch = linux_x86_64_2_6_22_19_0_1_default__1_SMP_2008_10_14_22_17_43__0200
-
-@end verbatim
diff --git a/docs/reference/vars/sys_maildir.texinfo b/docs/reference/vars/sys_maildir.texinfo
deleted file mode 100644
index 392666e2c0..0000000000
--- a/docs/reference/vars/sys_maildir.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-The name of the system email spool directory.
-
-@verbatim
-
-# maildir = /var/spool/mail
-
-@end verbatim
diff --git a/docs/reference/vars/sys_nova_version.texinfo b/docs/reference/vars/sys_nova_version.texinfo
deleted file mode 100644
index 8403f65988..0000000000
--- a/docs/reference/vars/sys_nova_version.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-The variable gives the version of the running CFEngine Nova Edition.
-
-@verbatim
-
-# nova_version = 1.1.3
-
-@end verbatim
diff --git a/docs/reference/vars/sys_os.texinfo b/docs/reference/vars/sys_os.texinfo
deleted file mode 100644
index ed6fbeee6c..0000000000
--- a/docs/reference/vars/sys_os.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-The name of the operating system according to the kernel.
-
-@verbatim
-
-# os = linux
-
-@end verbatim
diff --git a/docs/reference/vars/sys_ostype.texinfo b/docs/reference/vars/sys_ostype.texinfo
deleted file mode 100644
index 997b8713ab..0000000000
--- a/docs/reference/vars/sys_ostype.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-Another name for the operating system.
-
-@verbatim
-
-# ostype = linux_x86_64
-
-@end verbatim
diff --git a/docs/reference/vars/sys_policy_hub.texinfo b/docs/reference/vars/sys_policy_hub.texinfo
deleted file mode 100644
index a300fbe179..0000000000
--- a/docs/reference/vars/sys_policy_hub.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-Hostname of the machine acting as a policy hub. This value is set
-during bootstrap. In case bootstrap was not performed, it is set to ``undefined''.
-
-@b{History}: Was introduced in version 3.1.0b1,Nova 2.0.0b1 (2010). Available in Community since 3.2.0
-
-@verbatim
-
-reports:
-
- "Policy hub is $(sys.policy_hub)";
-
-@end verbatim
diff --git a/docs/reference/vars/sys_release.texinfo b/docs/reference/vars/sys_release.texinfo
deleted file mode 100644
index 58227a4558..0000000000
--- a/docs/reference/vars/sys_release.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-The kernel release of the operating system.
-
-@verbatim
-
-# release = 2.6.22.19-0.1-default
-
-@end verbatim
diff --git a/docs/reference/vars/sys_resolv.texinfo b/docs/reference/vars/sys_resolv.texinfo
deleted file mode 100644
index 4e76b863fb..0000000000
--- a/docs/reference/vars/sys_resolv.texinfo
+++ /dev/null
@@ -1,8 +0,0 @@
-
-The location of the system resolver file.
-
-@verbatim
-
-# resolv = /etc/resolv.conf
-
-@end verbatim
diff --git a/docs/reference/vars/sys_uqhost.texinfo b/docs/reference/vars/sys_uqhost.texinfo
deleted file mode 100644
index b225687f56..0000000000
--- a/docs/reference/vars/sys_uqhost.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-
-The unqualified name of the current host. See also @code{sys.fqhost}.
-
-@verbatim
-
-# uqhost = myhost
-
-@end verbatim
diff --git a/docs/reference/vars/sys_version.texinfo b/docs/reference/vars/sys_version.texinfo
deleted file mode 100644
index 7c65fd6ad7..0000000000
--- a/docs/reference/vars/sys_version.texinfo
+++ /dev/null
@@ -1,12 +0,0 @@
-
-The version of the running kernel. On Linux, this corresponds
-to the ouput of @code{uname -v}.
-
-@verbatim
-
-# version = #55-Ubuntu SMP Mon Jan 10 23:42:43 UTC 2011
-
-@end verbatim
-
-
-@i{History}: Was introduced in version 3.1.4,Nova 2.0.2 (2011)
diff --git a/docs/reference/vars/sys_windir.texinfo b/docs/reference/vars/sys_windir.texinfo
deleted file mode 100644
index 6170a65b5b..0000000000
--- a/docs/reference/vars/sys_windir.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-On the Windows version of CFEngine Nova, this is the path to the
-Windows directory of this system.
-
-@verbatim
-
-# windir = C:\WINDOWS
-
-@end verbatim
diff --git a/docs/reference/vars/sys_winprogdir.texinfo b/docs/reference/vars/sys_winprogdir.texinfo
deleted file mode 100644
index a24a68119b..0000000000
--- a/docs/reference/vars/sys_winprogdir.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-On the Windows version of CFEngine Nova, this is the path to the
-program files directory of the system.
-
-@verbatim
-
-# winprogdir = C:\Program Files
-
-@end verbatim
diff --git a/docs/reference/vars/sys_winprogdir86.texinfo b/docs/reference/vars/sys_winprogdir86.texinfo
deleted file mode 100644
index 5ed0099a66..0000000000
--- a/docs/reference/vars/sys_winprogdir86.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-On 64 bit Windows versions of CFEngine Nova, this is the path to the
-32 bit (x86) program files directory of the system.
-
-@verbatim
-
-# winprogdir86 = C:\Program Files (x86)
-
-@end verbatim
diff --git a/docs/reference/vars/sys_winsysdir.texinfo b/docs/reference/vars/sys_winsysdir.texinfo
deleted file mode 100644
index 518bbaffeb..0000000000
--- a/docs/reference/vars/sys_winsysdir.texinfo
+++ /dev/null
@@ -1,9 +0,0 @@
-
-On the Windows version of CFEngine Nova, this is the path to the
-Windows system directory.
-
-@verbatim
-
-# winsysdir = C:\WINDOWS\system32
-
-@end verbatim
diff --git a/docs/reference/vars/sys_workdir.texinfo b/docs/reference/vars/sys_workdir.texinfo
deleted file mode 100644
index 358ee18293..0000000000
--- a/docs/reference/vars/sys_workdir.texinfo
+++ /dev/null
@@ -1,26 +0,0 @@
-
-The location of the CFEngine work directory and cache. For the
-system privileged user this is normally:
-
-@verbatim
-
-# workdir = /var/cfengine
-
-@end verbatim
-
-For non-privileged users it is in the user's home directory:
-
-@verbatim
-
-# workdir = /home/user/.cfagent
-
-@end verbatim
-
-On the Windows version of CFEngine Nova, it is normally under program
-files (the directory name may change with the language of Windows):
-
-@verbatim
-
-# workdir = C:\Program Files\CFEngine
-
-@end verbatim
diff --git a/docs/tex-include/Makefile.am b/docs/tex-include/Makefile.am
deleted file mode 100644
index 0811a34756..0000000000
--- a/docs/tex-include/Makefile.am
+++ /dev/null
@@ -1 +0,0 @@
-EXTRA_DIST = texinfo-altfont.tex texinfo-logo.tex texinfo.tex txi-cmbright.tex txi-helvetica.tex txi-iwona.tex
diff --git a/docs/tex-include/texinfo-altfont.tex b/docs/tex-include/texinfo-altfont.tex
deleted file mode 100644
index 6185556e8c..0000000000
--- a/docs/tex-include/texinfo-altfont.tex
+++ /dev/null
@@ -1,31 +0,0 @@
-\message{altfont (v1.0)}
-
-\def \selectaltfont #1{\tex
- \input txi-#1.tex
- \endgroup
- \textfonts \rm}
-
-\def \txifontonesize #1#2{\begingroup
- \def \7{\altsuff}
- \global\expandafter\font \csname #1rm\endcsname = \txifontrm\7
- scaled #2\relax
- \global\expandafter\font \csname #1bf\endcsname = \txifontbf\7
- scaled #2\relax
- \global\expandafter\font \csname #1it\endcsname = \txifontit\7
- scaled #2\relax
- \global\expandafter\font \csname #1sl\endcsname = \txifontsl\7
- scaled #2\relax
- \global\expandafter\font \csname #1sc\endcsname = \txifontsc\7
- scaled #2\relax
- \global\expandafter\font \csname #1sf\endcsname = \txifontsf\7
- scaled #2\relax
- \global\expandafter\font \csname #1tt\endcsname = \txifonttt\7
- scaled #2\relax
- \global\expandafter\font \csname #1ttsl\endcsname = \txifontttsl\7
- scaled #2\relax
- \global\expandafter\font \csname #1i\endcsname = cmmi10
- scaled #2
- \global\expandafter\font \csname #1sy\endcsname = cmsy10
- scaled #2
- \endgroup
-}
diff --git a/docs/tex-include/texinfo-logo.tex b/docs/tex-include/texinfo-logo.tex
deleted file mode 100644
index 74ec18d68e..0000000000
--- a/docs/tex-include/texinfo-logo.tex
+++ /dev/null
@@ -1,18 +0,0 @@
-\message{logo (v1.02)}
-
-\def \footlinelogo {{\ifpdf
-% \dopdfimage{\texilogo}{}{24pt}%
- \dopdfimage{NewLogo}{}{24pt}%
- \else
- \catcode`\^^M = 5 \normalturnoffactive
- \epsfysize=24pt\relax
- \epsfbox{\texilogo.eps}%
- \fi}}
-
-\def \setlogo #1{%
- \def \texilogo {#1}%
- \def \titlepagetopglue{-0.5in\relax
- \line{\image{\texilogo,,8.0in}\hfil}
- \vskip -1.2in
- }
- \footline = {\iffinishedtitlepage \else \footlinelogo \fi \hfill}}
diff --git a/docs/tex-include/texinfo.tex b/docs/tex-include/texinfo.tex
deleted file mode 100644
index 9a11306f8c..0000000000
--- a/docs/tex-include/texinfo.tex
+++ /dev/null
@@ -1,9000 +0,0 @@
-% texinfo.tex -- TeX macros to handle Texinfo files.
-%
-% Load plain if necessary, i.e., if running under initex.
-\expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi
-%
-\def\texinfoversion{2011-06-28.17}
-%
-% Copyright (C) 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995,
-% 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
-% 2007, 2008 Free Software Foundation, Inc.
-%
-% This texinfo.tex file 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 3 of the
-% License, or (at your option) any later version.
-%
-% This texinfo.tex file 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, see .
-%
-% As a special exception, when this file is read by TeX when processing
-% a Texinfo source document, you may use the result without
-% restriction. (This has been our intent since Texinfo was invented.)
-%
-% Please try the latest version of texinfo.tex before submitting bug
-% reports; you can get the latest version from:
-% http://www.gnu.org/software/texinfo/ (the Texinfo home page), or
-% ftp://tug.org/tex/texinfo.tex
-% (and all CTAN mirrors, see http://www.ctan.org).
-% The texinfo.tex in any given distribution could well be out
-% of date, so if that's what you're using, please check.
-%
-% Send bug reports to bug-texinfo@gnu.org. Please include including a
-% complete document in each bug report with which we can reproduce the
-% problem. Patches are, of course, greatly appreciated.
-%
-% To process a Texinfo manual with TeX, it's most reliable to use the
-% texi2dvi shell script that comes with the distribution. For a simple
-% manual foo.texi, however, you can get away with this:
-% tex foo.texi
-% texindex foo.??
-% tex foo.texi
-% tex foo.texi
-% dvips foo.dvi -o # or whatever; this makes foo.ps.
-% The extra TeX runs get the cross-reference information correct.
-% Sometimes one run after texindex suffices, and sometimes you need more
-% than two; texi2dvi does it as many times as necessary.
-%
-% It is possible to adapt texinfo.tex for other languages, to some
-% extent. You can get the existing language-specific files from the
-% full Texinfo distribution.
-%
-% The GNU Texinfo home page is http://www.gnu.org/software/texinfo.
-
-
-\message{Loading texinfo [version \texinfoversion]:}
-
-% If in a .fmt file, print the version number
-% and turn on active characters that we couldn't do earlier because
-% they might have appeared in the input file name.
-\everyjob{\message{[Texinfo version \texinfoversion]}%
- \catcode`+=\active \catcode`\_=\active}
-
-
-\chardef\other=12
-
-% We never want plain's \outer definition of \+ in Texinfo.
-% For @tex, we can use \tabalign.
-\let\+ = \relax
-
-% Save some plain tex macros whose names we will redefine.
-\let\ptexb=\b
-\let\ptexbullet=\bullet
-\let\ptexc=\c
-\let\ptexcomma=\,
-\let\ptexdot=\.
-\let\ptexdots=\dots
-\let\ptexend=\end
-\let\ptexequiv=\equiv
-\let\ptexexclam=\!
-\let\ptexfootnote=\footnote
-\let\ptexgtr=>
-\let\ptexhat=^
-\let\ptexi=\i
-\let\ptexindent=\indent
-\let\ptexinsert=\insert
-\let\ptexlbrace=\{
-\let\ptexless=<
-\let\ptexnewwrite\newwrite
-\let\ptexnoindent=\noindent
-\let\ptexplus=+
-\let\ptexrbrace=\}
-\let\ptexslash=\/
-\let\ptexstar=\*
-\let\ptext=\t
-\let\ptextop=\top
-
-% If this character appears in an error message or help string, it
-% starts a new line in the output.
-\newlinechar = `^^J
-
-% Use TeX 3.0's \inputlineno to get the line number, for better error
-% messages, but if we're using an old version of TeX, don't do anything.
-%
-\ifx\inputlineno\thisisundefined
- \let\linenumber = \empty % Pre-3.0.
-\else
- \def\linenumber{l.\the\inputlineno:\space}
-\fi
-
-% Set up fixed words for English if not already set.
-\ifx\putwordAppendix\undefined \gdef\putwordAppendix{Appendix}\fi
-\ifx\putwordChapter\undefined \gdef\putwordChapter{Chapter}\fi
-\ifx\putwordfile\undefined \gdef\putwordfile{file}\fi
-\ifx\putwordin\undefined \gdef\putwordin{in}\fi
-\ifx\putwordIndexIsEmpty\undefined \gdef\putwordIndexIsEmpty{(Index is empty)}\fi
-\ifx\putwordIndexNonexistent\undefined \gdef\putwordIndexNonexistent{(Index is nonexistent)}\fi
-\ifx\putwordInfo\undefined \gdef\putwordInfo{Info}\fi
-\ifx\putwordInstanceVariableof\undefined \gdef\putwordInstanceVariableof{Instance Variable of}\fi
-\ifx\putwordMethodon\undefined \gdef\putwordMethodon{Method on}\fi
-\ifx\putwordNoTitle\undefined \gdef\putwordNoTitle{No Title}\fi
-\ifx\putwordof\undefined \gdef\putwordof{of}\fi
-\ifx\putwordon\undefined \gdef\putwordon{on}\fi
-\ifx\putwordpage\undefined \gdef\putwordpage{page}\fi
-\ifx\putwordsection\undefined \gdef\putwordsection{section}\fi
-\ifx\putwordSection\undefined \gdef\putwordSection{Section}\fi
-\ifx\putwordsee\undefined \gdef\putwordsee{see}\fi
-\ifx\putwordSee\undefined \gdef\putwordSee{See}\fi
-\ifx\putwordShortTOC\undefined \gdef\putwordShortTOC{Short Contents}\fi
-\ifx\putwordTOC\undefined \gdef\putwordTOC{Table of Contents}\fi
-%
-\ifx\putwordMJan\undefined \gdef\putwordMJan{January}\fi
-\ifx\putwordMFeb\undefined \gdef\putwordMFeb{February}\fi
-\ifx\putwordMMar\undefined \gdef\putwordMMar{March}\fi
-\ifx\putwordMApr\undefined \gdef\putwordMApr{April}\fi
-\ifx\putwordMMay\undefined \gdef\putwordMMay{May}\fi
-\ifx\putwordMJun\undefined \gdef\putwordMJun{June}\fi
-\ifx\putwordMJul\undefined \gdef\putwordMJul{July}\fi
-\ifx\putwordMAug\undefined \gdef\putwordMAug{August}\fi
-\ifx\putwordMSep\undefined \gdef\putwordMSep{September}\fi
-\ifx\putwordMOct\undefined \gdef\putwordMOct{October}\fi
-\ifx\putwordMNov\undefined \gdef\putwordMNov{November}\fi
-\ifx\putwordMDec\undefined \gdef\putwordMDec{December}\fi
-%
-\ifx\putwordDefmac\undefined \gdef\putwordDefmac{Macro}\fi
-\ifx\putwordDefspec\undefined \gdef\putwordDefspec{Special Form}\fi
-\ifx\putwordDefvar\undefined \gdef\putwordDefvar{Variable}\fi
-\ifx\putwordDefopt\undefined \gdef\putwordDefopt{User Option}\fi
-\ifx\putwordDeffunc\undefined \gdef\putwordDeffunc{Function}\fi
-
-% Since the category of space is not known, we have to be careful.
-\chardef\spacecat = 10
-\def\spaceisspace{\catcode`\ =\spacecat}
-
-% sometimes characters are active, so we need control sequences.
-\chardef\colonChar = `\:
-\chardef\commaChar = `\,
-\chardef\dashChar = `\-
-\chardef\dotChar = `\.
-\chardef\exclamChar= `\!
-\chardef\lquoteChar= `\`
-\chardef\questChar = `\?
-\chardef\rquoteChar= `\'
-\chardef\semiChar = `\;
-\chardef\underChar = `\_
-
-% Ignore a token.
-%
-\def\gobble#1{}
-
-% The following is used inside several \edef's.
-\def\makecsname#1{\expandafter\noexpand\csname#1\endcsname}
-
-% Hyphenation fixes.
-\hyphenation{
- Flor-i-da Ghost-script Ghost-view Mac-OS Post-Script
- ap-pen-dix bit-map bit-maps
- data-base data-bases eshell fall-ing half-way long-est man-u-script
- man-u-scripts mini-buf-fer mini-buf-fers over-view par-a-digm
- par-a-digms rath-er rec-tan-gu-lar ro-bot-ics se-vere-ly set-up spa-ces
- spell-ing spell-ings
- stand-alone strong-est time-stamp time-stamps which-ever white-space
- wide-spread wrap-around
-}
-
-% Margin to add to right of even pages, to left of odd pages.
-\newdimen\bindingoffset
-\newdimen\normaloffset
-\newdimen\pagewidth \newdimen\pageheight
-
-% For a final copy, take out the rectangles
-% that mark overfull boxes (in case you have decided
-% that the text looks ok even though it passes the margin).
-%
-\def\finalout{\overfullrule=0pt}
-
-% @| inserts a changebar to the left of the current line. It should
-% surround any changed text. This approach does *not* work if the
-% change spans more than two lines of output. To handle that, we would
-% have adopt a much more difficult approach (putting marks into the main
-% vertical list for the beginning and end of each change).
-%
-\def\|{%
- % \vadjust can only be used in horizontal mode.
- \leavevmode
- %
- % Append this vertical mode material after the current line in the output.
- \vadjust{%
- % We want to insert a rule with the height and depth of the current
- % leading; that is exactly what \strutbox is supposed to record.
- \vskip-\baselineskip
- %
- % \vadjust-items are inserted at the left edge of the type. So
- % the \llap here moves out into the left-hand margin.
- \llap{%
- %
- % For a thicker or thinner bar, change the `1pt'.
- \vrule height\baselineskip width1pt
- %
- % This is the space between the bar and the text.
- \hskip 12pt
- }%
- }%
-}
-
-% Sometimes it is convenient to have everything in the transcript file
-% and nothing on the terminal. We don't just call \tracingall here,
-% since that produces some useless output on the terminal. We also make
-% some effort to order the tracing commands to reduce output in the log
-% file; cf. trace.sty in LaTeX.
-%
-\def\gloggingall{\begingroup \globaldefs = 1 \loggingall \endgroup}%
-\def\loggingall{%
- \tracingstats2
- \tracingpages1
- \tracinglostchars2 % 2 gives us more in etex
- \tracingparagraphs1
- \tracingoutput1
- \tracingmacros2
- \tracingrestores1
- \showboxbreadth\maxdimen \showboxdepth\maxdimen
- \ifx\eTeXversion\undefined\else % etex gives us more logging
- \tracingscantokens1
- \tracingifs1
- \tracinggroups1
- \tracingnesting2
- \tracingassigns1
- \fi
- \tracingcommands3 % 3 gives us more in etex
- \errorcontextlines16
-}%
-
-% add check for \lastpenalty to plain's definitions. If the last thing
-% we did was a \nobreak, we don't want to insert more space.
-%
-\def\smallbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\smallskipamount
- \removelastskip\penalty-50\smallskip\fi\fi}
-\def\medbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\medskipamount
- \removelastskip\penalty-100\medskip\fi\fi}
-\def\bigbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\bigskipamount
- \removelastskip\penalty-200\bigskip\fi\fi}
-
-% For @cropmarks command.
-% Do @cropmarks to get crop marks.
-%
-\newif\ifcropmarks
-\let\cropmarks = \cropmarkstrue
-%
-% Dimensions to add cropmarks at corners.
-% Added by P. A. MacKay, 12 Nov. 1986
-%
-\newdimen\outerhsize \newdimen\outervsize % set by the paper size routines
-\newdimen\cornerlong \cornerlong=1pc
-\newdimen\cornerthick \cornerthick=.3pt
-\newdimen\topandbottommargin \topandbottommargin=.75in
-
-% Output a mark which sets \thischapter, \thissection and \thiscolor.
-% We dump everything together because we only have one kind of mark.
-% This works because we only use \botmark / \topmark, not \firstmark.
-%
-% A mark contains a subexpression of the \ifcase ... \fi construct.
-% \get*marks macros below extract the needed part using \ifcase.
-%
-% Another complication is to let the user choose whether \thischapter
-% (\thissection) refers to the chapter (section) in effect at the top
-% of a page, or that at the bottom of a page. The solution is
-% described on page 260 of The TeXbook. It involves outputting two
-% marks for the sectioning macros, one before the section break, and
-% one after. I won't pretend I can describe this better than DEK...
-\def\domark{%
- \toks0=\expandafter{\lastchapterdefs}%
- \toks2=\expandafter{\lastsectiondefs}%
- \toks4=\expandafter{\prevchapterdefs}%
- \toks6=\expandafter{\prevsectiondefs}%
- \toks8=\expandafter{\lastcolordefs}%
- \mark{%
- \the\toks0 \the\toks2
- \noexpand\or \the\toks4 \the\toks6
- \noexpand\else \the\toks8
- }%
-}
-% \topmark doesn't work for the very first chapter (after the title
-% page or the contents), so we use \firstmark there -- this gets us
-% the mark with the chapter defs, unless the user sneaks in, e.g.,
-% @setcolor (or @url, or @link, etc.) between @contents and the very
-% first @chapter.
-\def\gettopheadingmarks{%
- \ifcase0\topmark\fi
- \ifx\thischapter\empty \ifcase0\firstmark\fi \fi
-}
-\def\getbottomheadingmarks{\ifcase1\botmark\fi}
-\def\getcolormarks{\ifcase2\topmark\fi}
-
-% Avoid "undefined control sequence" errors.
-\def\lastchapterdefs{}
-\def\lastsectiondefs{}
-\def\prevchapterdefs{}
-\def\prevsectiondefs{}
-\def\lastcolordefs{}
-
-% Main output routine.
-\chardef\PAGE = 255
-\output = {\onepageout{\pagecontents\PAGE}}
-
-\newbox\headlinebox
-\newbox\footlinebox
-
-% \onepageout takes a vbox as an argument. Note that \pagecontents
-% does insertions, but you have to call it yourself.
-\def\onepageout#1{%
- \ifcropmarks \hoffset=0pt \else \hoffset=\normaloffset \fi
- %
- \ifodd\pageno \advance\hoffset by \bindingoffset
- \else \advance\hoffset by -\bindingoffset\fi
- %
- % Do this outside of the \shipout so @code etc. will be expanded in
- % the headline as they should be, not taken literally (outputting ''code).
- \ifodd\pageno \getoddheadingmarks \else \getevenheadingmarks \fi
- \setbox\headlinebox = \vbox{\let\hsize=\pagewidth \makeheadline}%
- \ifodd\pageno \getoddfootingmarks \else \getevenfootingmarks \fi
- \setbox\footlinebox = \vbox{\let\hsize=\pagewidth \makefootline}%
- %
- {%
- % Have to do this stuff outside the \shipout because we want it to
- % take effect in \write's, yet the group defined by the \vbox ends
- % before the \shipout runs.
- %
- \indexdummies % don't expand commands in the output.
- \normalturnoffactive % \ in index entries must not stay \, e.g., if
- % the page break happens to be in the middle of an example.
- % We don't want .vr (or whatever) entries like this:
- % \entry{{\tt \indexbackslash }acronym}{32}{\code {\acronym}}
- % "\acronym" won't work when it's read back in;
- % it needs to be
- % {\code {{\tt \backslashcurfont }acronym}
- \shipout\vbox{%
- % Do this early so pdf references go to the beginning of the page.
- \ifpdfmakepagedest \pdfdest name{\the\pageno} xyz\fi
- %
- \ifcropmarks \vbox to \outervsize\bgroup
- \hsize = \outerhsize
- \vskip-\topandbottommargin
- \vtop to0pt{%
- \line{\ewtop\hfil\ewtop}%
- \nointerlineskip
- \line{%
- \vbox{\moveleft\cornerthick\nstop}%
- \hfill
- \vbox{\moveright\cornerthick\nstop}%
- }%
- \vss}%
- \vskip\topandbottommargin
- \line\bgroup
- \hfil % center the page within the outer (page) hsize.
- \ifodd\pageno\hskip\bindingoffset\fi
- \vbox\bgroup
- \fi
- %
- \unvbox\headlinebox
- \pagebody{#1}%
- \ifdim\ht\footlinebox > 0pt
- % Only leave this space if the footline is nonempty.
- % (We lessened \vsize for it in \oddfootingyyy.)
- % The \baselineskip=24pt in plain's \makefootline has no effect.
- \vskip 24pt
- \unvbox\footlinebox
- \fi
- %
- \ifcropmarks
- \egroup % end of \vbox\bgroup
- \hfil\egroup % end of (centering) \line\bgroup
- \vskip\topandbottommargin plus1fill minus1fill
- \boxmaxdepth = \cornerthick
- \vbox to0pt{\vss
- \line{%
- \vbox{\moveleft\cornerthick\nsbot}%
- \hfill
- \vbox{\moveright\cornerthick\nsbot}%
- }%
- \nointerlineskip
- \line{\ewbot\hfil\ewbot}%
- }%
- \egroup % \vbox from first cropmarks clause
- \fi
- }% end of \shipout\vbox
- }% end of group with \indexdummies
- \advancepageno
- \ifnum\outputpenalty>-20000 \else\dosupereject\fi
-}
-
-\newinsert\margin \dimen\margin=\maxdimen
-
-\def\pagebody#1{\vbox to\pageheight{\boxmaxdepth=\maxdepth #1}}
-{\catcode`\@ =11
-\gdef\pagecontents#1{\ifvoid\topins\else\unvbox\topins\fi
-% marginal hacks, juha@viisa.uucp (Juha Takala)
-\ifvoid\margin\else % marginal info is present
- \rlap{\kern\hsize\vbox to\z@{\kern1pt\box\margin \vss}}\fi
-\dimen@=\dp#1\relax \unvbox#1\relax
-\ifvoid\footins\else\vskip\skip\footins\footnoterule \unvbox\footins\fi
-\ifr@ggedbottom \kern-\dimen@ \vfil \fi}
-}
-
-% Here are the rules for the cropmarks. Note that they are
-% offset so that the space between them is truly \outerhsize or \outervsize
-% (P. A. MacKay, 12 November, 1986)
-%
-\def\ewtop{\vrule height\cornerthick depth0pt width\cornerlong}
-\def\nstop{\vbox
- {\hrule height\cornerthick depth\cornerlong width\cornerthick}}
-\def\ewbot{\vrule height0pt depth\cornerthick width\cornerlong}
-\def\nsbot{\vbox
- {\hrule height\cornerlong depth\cornerthick width\cornerthick}}
-
-% Parse an argument, then pass it to #1. The argument is the rest of
-% the input line (except we remove a trailing comment). #1 should be a
-% macro which expects an ordinary undelimited TeX argument.
-%
-\def\parsearg{\parseargusing{}}
-\def\parseargusing#1#2{%
- \def\argtorun{#2}%
- \begingroup
- \obeylines
- \spaceisspace
- #1%
- \parseargline\empty% Insert the \empty token, see \finishparsearg below.
-}
-
-{\obeylines %
- \gdef\parseargline#1^^M{%
- \endgroup % End of the group started in \parsearg.
- \argremovecomment #1\comment\ArgTerm%
- }%
-}
-
-% First remove any @comment, then any @c comment.
-\def\argremovecomment#1\comment#2\ArgTerm{\argremovec #1\c\ArgTerm}
-\def\argremovec#1\c#2\ArgTerm{\argcheckspaces#1\^^M\ArgTerm}
-
-% Each occurrence of `\^^M' or `\^^M' is replaced by a single space.
-%
-% \argremovec might leave us with trailing space, e.g.,
-% @end itemize @c foo
-% This space token undergoes the same procedure and is eventually removed
-% by \finishparsearg.
-%
-\def\argcheckspaces#1\^^M{\argcheckspacesX#1\^^M \^^M}
-\def\argcheckspacesX#1 \^^M{\argcheckspacesY#1\^^M}
-\def\argcheckspacesY#1\^^M#2\^^M#3\ArgTerm{%
- \def\temp{#3}%
- \ifx\temp\empty
- % Do not use \next, perhaps the caller of \parsearg uses it; reuse \temp:
- \let\temp\finishparsearg
- \else
- \let\temp\argcheckspaces
- \fi
- % Put the space token in:
- \temp#1 #3\ArgTerm
-}
-
-% If a _delimited_ argument is enclosed in braces, they get stripped; so
-% to get _exactly_ the rest of the line, we had to prevent such situation.
-% We prepended an \empty token at the very beginning and we expand it now,
-% just before passing the control to \argtorun.
-% (Similarly, we have to think about #3 of \argcheckspacesY above: it is
-% either the null string, or it ends with \^^M---thus there is no danger
-% that a pair of braces would be stripped.
-%
-% But first, we have to remove the trailing space token.
-%
-\def\finishparsearg#1 \ArgTerm{\expandafter\argtorun\expandafter{#1}}
-
-% \parseargdef\foo{...}
-% is roughly equivalent to
-% \def\foo{\parsearg\Xfoo}
-% \def\Xfoo#1{...}
-%
-% Actually, I use \csname\string\foo\endcsname, ie. \\foo, as it is my
-% favourite TeX trick. --kasal, 16nov03
-
-\def\parseargdef#1{%
- \expandafter \doparseargdef \csname\string#1\endcsname #1%
-}
-\def\doparseargdef#1#2{%
- \def#2{\parsearg#1}%
- \def#1##1%
-}
-
-% Several utility definitions with active space:
-{
- \obeyspaces
- \gdef\obeyedspace{ }
-
- % Make each space character in the input produce a normal interword
- % space in the output. Don't allow a line break at this space, as this
- % is used only in environments like @example, where each line of input
- % should produce a line of output anyway.
- %
- \gdef\sepspaces{\obeyspaces\let =\tie}
-
- % If an index command is used in an @example environment, any spaces
- % therein should become regular spaces in the raw index file, not the
- % expansion of \tie (\leavevmode \penalty \@M \ ).
- \gdef\unsepspaces{\let =\space}
-}
-
-
-\def\flushcr{\ifx\par\lisppar \def\next##1{}\else \let\next=\relax \fi \next}
-
-% Define the framework for environments in texinfo.tex. It's used like this:
-%
-% \envdef\foo{...}
-% \def\Efoo{...}
-%
-% It's the responsibility of \envdef to insert \begingroup before the
-% actual body; @end closes the group after calling \Efoo. \envdef also
-% defines \thisenv, so the current environment is known; @end checks
-% whether the environment name matches. The \checkenv macro can also be
-% used to check whether the current environment is the one expected.
-%
-% Non-false conditionals (@iftex, @ifset) don't fit into this, so they
-% are not treated as environments; they don't open a group. (The
-% implementation of @end takes care not to call \endgroup in this
-% special case.)
-
-
-% At run-time, environments start with this:
-\def\startenvironment#1{\begingroup\def\thisenv{#1}}
-% initialize
-\let\thisenv\empty
-
-% ... but they get defined via ``\envdef\foo{...}'':
-\long\def\envdef#1#2{\def#1{\startenvironment#1#2}}
-\def\envparseargdef#1#2{\parseargdef#1{\startenvironment#1#2}}
-
-% Check whether we're in the right environment:
-\def\checkenv#1{%
- \def\temp{#1}%
- \ifx\thisenv\temp
- \else
- \badenverr
- \fi
-}
-
-% Environment mismatch, #1 expected:
-\def\badenverr{%
- \errhelp = \EMsimple
- \errmessage{This command can appear only \inenvironment\temp,
- not \inenvironment\thisenv}%
-}
-\def\inenvironment#1{%
- \ifx#1\empty
- out of any environment%
- \else
- in environment \expandafter\string#1%
- \fi
-}
-
-% @end foo executes the definition of \Efoo.
-% But first, it executes a specialized version of \checkenv
-%
-\parseargdef\end{%
- \if 1\csname iscond.#1\endcsname
- \else
- % The general wording of \badenverr may not be ideal, but... --kasal, 06nov03
- \expandafter\checkenv\csname#1\endcsname
- \csname E#1\endcsname
- \endgroup
- \fi
-}
-
-\newhelp\EMsimple{Press RETURN to continue.}
-
-
-%% Simple single-character @ commands
-
-% @@ prints an @
-% Kludge this until the fonts are right (grr).
-\def\@{{\tt\char64}}
-
-% This is turned off because it was never documented
-% and you can use @w{...} around a quote to suppress ligatures.
-%% Define @` and @' to be the same as ` and '
-%% but suppressing ligatures.
-%\def\`{{`}}
-%\def\'{{'}}
-
-% Used to generate quoted braces.
-\def\mylbrace {{\tt\char123}}
-\def\myrbrace {{\tt\char125}}
-\let\{=\mylbrace
-\let\}=\myrbrace
-\begingroup
- % Definitions to produce \{ and \} commands for indices,
- % and @{ and @} for the aux/toc files.
- \catcode`\{ = \other \catcode`\} = \other
- \catcode`\[ = 1 \catcode`\] = 2
- \catcode`\! = 0 \catcode`\\ = \other
- !gdef!lbracecmd[\{]%
- !gdef!rbracecmd[\}]%
- !gdef!lbraceatcmd[@{]%
- !gdef!rbraceatcmd[@}]%
-!endgroup
-
-% @comma{} to avoid , parsing problems.
-\let\comma = ,
-
-% Accents: @, @dotaccent @ringaccent @ubaraccent @udotaccent
-% Others are defined by plain TeX: @` @' @" @^ @~ @= @u @v @H.
-\let\, = \c
-\let\dotaccent = \.
-\def\ringaccent#1{{\accent23 #1}}
-\let\tieaccent = \t
-\let\ubaraccent = \b
-\let\udotaccent = \d
-
-% Other special characters: @questiondown @exclamdown @ordf @ordm
-% Plain TeX defines: @AA @AE @O @OE @L (plus lowercase versions) @ss.
-\def\questiondown{?`}
-\def\exclamdown{!`}
-\def\ordf{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{a}}}
-\def\ordm{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{o}}}
-
-% Dotless i and dotless j, used for accents.
-\def\imacro{i}
-\def\jmacro{j}
-\def\dotless#1{%
- \def\temp{#1}%
- \ifx\temp\imacro \ifmmode\imath \else\ptexi \fi
- \else\ifx\temp\jmacro \ifmmode\jmath \else\j \fi
- \else \errmessage{@dotless can be used only with i or j}%
- \fi\fi
-}
-
-% The \TeX{} logo, as in plain, but resetting the spacing so that a
-% period following counts as ending a sentence. (Idea found in latex.)
-%
-\edef\TeX{\TeX \spacefactor=1000 }
-
-% @LaTeX{} logo. Not quite the same results as the definition in
-% latex.ltx, since we use a different font for the raised A; it's most
-% convenient for us to use an explicitly smaller font, rather than using
-% the \scriptstyle font (since we don't reset \scriptstyle and
-% \scriptscriptstyle).
-%
-\def\LaTeX{%
- L\kern-.36em
- {\setbox0=\hbox{T}%
- \vbox to \ht0{\hbox{\selectfonts\lllsize A}\vss}}%
- \kern-.15em
- \TeX
-}
-
-% Be sure we're in horizontal mode when doing a tie, since we make space
-% equivalent to this in @example-like environments. Otherwise, a space
-% at the beginning of a line will start with \penalty -- and
-% since \penalty is valid in vertical mode, we'd end up putting the
-% penalty on the vertical list instead of in the new paragraph.
-{\catcode`@ = 11
- % Avoid using \@M directly, because that causes trouble
- % if the definition is written into an index file.
- \global\let\tiepenalty = \@M
- \gdef\tie{\leavevmode\penalty\tiepenalty\ }
-}
-
-% @: forces normal size whitespace following.
-\def\:{\spacefactor=1000 }
-
-% @* forces a line break.
-\def\*{\hfil\break\hbox{}\ignorespaces}
-
-% @/ allows a line break.
-\let\/=\allowbreak
-
-% @. is an end-of-sentence period.
-\def\.{.\spacefactor=\endofsentencespacefactor\space}
-
-% @! is an end-of-sentence bang.
-\def\!{!\spacefactor=\endofsentencespacefactor\space}
-
-% @? is an end-of-sentence query.
-\def\?{?\spacefactor=\endofsentencespacefactor\space}
-
-% @frenchspacing on|off says whether to put extra space after punctuation.
-%
-\def\onword{on}
-\def\offword{off}
-%
-\parseargdef\frenchspacing{%
- \def\temp{#1}%
- \ifx\temp\onword \plainfrenchspacing
- \else\ifx\temp\offword \plainnonfrenchspacing
- \else
- \errhelp = \EMsimple
- \errmessage{Unknown @frenchspacing option `\temp', must be on/off}%
- \fi\fi
-}
-
-% @w prevents a word break. Without the \leavevmode, @w at the
-% beginning of a paragraph, when TeX is still in vertical mode, would
-% produce a whole line of output instead of starting the paragraph.
-\def\w#1{\leavevmode\hbox{#1}}
-
-% @group ... @end group forces ... to be all on one page, by enclosing
-% it in a TeX vbox. We use \vtop instead of \vbox to construct the box
-% to keep its height that of a normal line. According to the rules for
-% \topskip (p.114 of the TeXbook), the glue inserted is
-% max (\topskip - \ht (first item), 0). If that height is large,
-% therefore, no glue is inserted, and the space between the headline and
-% the text is small, which looks bad.
-%
-% Another complication is that the group might be very large. This can
-% cause the glue on the previous page to be unduly stretched, because it
-% does not have much material. In this case, it's better to add an
-% explicit \vfill so that the extra space is at the bottom. The
-% threshold for doing this is if the group is more than \vfilllimit
-% percent of a page (\vfilllimit can be changed inside of @tex).
-%
-\newbox\groupbox
-\def\vfilllimit{0.7}
-%
-\envdef\group{%
- \ifnum\catcode`\^^M=\active \else
- \errhelp = \groupinvalidhelp
- \errmessage{@group invalid in context where filling is enabled}%
- \fi
- \startsavinginserts
- %
- \setbox\groupbox = \vtop\bgroup
- % Do @comment since we are called inside an environment such as
- % @example, where each end-of-line in the input causes an
- % end-of-line in the output. We don't want the end-of-line after
- % the `@group' to put extra space in the output. Since @group
- % should appear on a line by itself (according to the Texinfo
- % manual), we don't worry about eating any user text.
- \comment
-}
-%
-% The \vtop produces a box with normal height and large depth; thus, TeX puts
-% \baselineskip glue before it, and (when the next line of text is done)
-% \lineskip glue after it. Thus, space below is not quite equal to space
-% above. But it's pretty close.
-\def\Egroup{%
- % To get correct interline space between the last line of the group
- % and the first line afterwards, we have to propagate \prevdepth.
- \endgraf % Not \par, as it may have been set to \lisppar.
- \global\dimen1 = \prevdepth
- \egroup % End the \vtop.
- % \dimen0 is the vertical size of the group's box.
- \dimen0 = \ht\groupbox \advance\dimen0 by \dp\groupbox
- % \dimen2 is how much space is left on the page (more or less).
- \dimen2 = \pageheight \advance\dimen2 by -\pagetotal
- % if the group doesn't fit on the current page, and it's a big big
- % group, force a page break.
- \ifdim \dimen0 > \dimen2
- \ifdim \pagetotal < \vfilllimit\pageheight
- \page
- \fi
- \fi
- \box\groupbox
- \prevdepth = \dimen1
- \checkinserts
-}
-%
-% TeX puts in an \escapechar (i.e., `@') at the beginning of the help
-% message, so this ends up printing `@group can only ...'.
-%
-\newhelp\groupinvalidhelp{%
-group can only be used in environments such as @example,^^J%
-where each line of input produces a line of output.}
-
-% @need space-in-mils
-% forces a page break if there is not space-in-mils remaining.
-
-\newdimen\mil \mil=0.001in
-
-% Old definition--didn't work.
-%\parseargdef\need{\par %
-%% This method tries to make TeX break the page naturally
-%% if the depth of the box does not fit.
-%{\baselineskip=0pt%
-%\vtop to #1\mil{\vfil}\kern -#1\mil\nobreak
-%\prevdepth=-1000pt
-%}}
-
-\parseargdef\need{%
- % Ensure vertical mode, so we don't make a big box in the middle of a
- % paragraph.
- \par
- %
- % If the @need value is less than one line space, it's useless.
- \dimen0 = #1\mil
- \dimen2 = \ht\strutbox
- \advance\dimen2 by \dp\strutbox
- \ifdim\dimen0 > \dimen2
- %
- % Do a \strut just to make the height of this box be normal, so the
- % normal leading is inserted relative to the preceding line.
- % And a page break here is fine.
- \vtop to #1\mil{\strut\vfil}%
- %
- % TeX does not even consider page breaks if a penalty added to the
- % main vertical list is 10000 or more. But in order to see if the
- % empty box we just added fits on the page, we must make it consider
- % page breaks. On the other hand, we don't want to actually break the
- % page after the empty box. So we use a penalty of 9999.
- %
- % There is an extremely small chance that TeX will actually break the
- % page at this \penalty, if there are no other feasible breakpoints in
- % sight. (If the user is using lots of big @group commands, which
- % almost-but-not-quite fill up a page, TeX will have a hard time doing
- % good page breaking, for example.) However, I could not construct an
- % example where a page broke at this \penalty; if it happens in a real
- % document, then we can reconsider our strategy.
- \penalty9999
- %
- % Back up by the size of the box, whether we did a page break or not.
- \kern -#1\mil
- %
- % Do not allow a page break right after this kern.
- \nobreak
- \fi
-}
-
-% @br forces paragraph break (and is undocumented).
-
-\let\br = \par
-
-% @page forces the start of a new page.
-%
-\def\page{\par\vfill\supereject}
-
-% @exdent text....
-% outputs text on separate line in roman font, starting at standard page margin
-
-% This records the amount of indent in the innermost environment.
-% That's how much \exdent should take out.
-\newskip\exdentamount
-
-% This defn is used inside fill environments such as @defun.
-\parseargdef\exdent{\hfil\break\hbox{\kern -\exdentamount{\rm#1}}\hfil\break}
-
-% This defn is used inside nofill environments such as @example.
-\parseargdef\nofillexdent{{\advance \leftskip by -\exdentamount
- \leftline{\hskip\leftskip{\rm#1}}}}
-
-% @inmargin{WHICH}{TEXT} puts TEXT in the WHICH margin next to the current
-% paragraph. For more general purposes, use the \margin insertion
-% class. WHICH is `l' or `r'.
-%
-\newskip\inmarginspacing \inmarginspacing=1cm
-\def\strutdepth{\dp\strutbox}
-%
-\def\doinmargin#1#2{\strut\vadjust{%
- \nobreak
- \kern-\strutdepth
- \vtop to \strutdepth{%
- \baselineskip=\strutdepth
- \vss
- % if you have multiple lines of stuff to put here, you'll need to
- % make the vbox yourself of the appropriate size.
- \ifx#1l%
- \llap{\ignorespaces #2\hskip\inmarginspacing}%
- \else
- \rlap{\hskip\hsize \hskip\inmarginspacing \ignorespaces #2}%
- \fi
- \null
- }%
-}}
-\def\inleftmargin{\doinmargin l}
-\def\inrightmargin{\doinmargin r}
-%
-% @inmargin{TEXT [, RIGHT-TEXT]}
-% (if RIGHT-TEXT is given, use TEXT for left page, RIGHT-TEXT for right;
-% else use TEXT for both).
-%
-\def\inmargin#1{\parseinmargin #1,,\finish}
-\def\parseinmargin#1,#2,#3\finish{% not perfect, but better than nothing.
- \setbox0 = \hbox{\ignorespaces #2}%
- \ifdim\wd0 > 0pt
- \def\lefttext{#1}% have both texts
- \def\righttext{#2}%
- \else
- \def\lefttext{#1}% have only one text
- \def\righttext{#1}%
- \fi
- %
- \ifodd\pageno
- \def\temp{\inrightmargin\righttext}% odd page -> outside is right margin
- \else
- \def\temp{\inleftmargin\lefttext}%
- \fi
- \temp
-}
-
-% @include FILE -- \input text of FILE.
-%
-\def\include{\parseargusing\filenamecatcodes\includezzz}
-\def\includezzz#1{%
- \pushthisfilestack
- \def\thisfile{#1}%
- {%
- \makevalueexpandable % we want to expand any @value in FILE.
- \turnoffactive % and allow special characters in the expansion
- \edef\temp{\noexpand\input #1 }%
- %
- % This trickery is to read FILE outside of a group, in case it makes
- % definitions, etc.
- \expandafter
- }\temp
- \popthisfilestack
-}
-\def\filenamecatcodes{%
- \catcode`\\=\other
- \catcode`~=\other
- \catcode`^=\other
- \catcode`_=\other
- \catcode`|=\other
- \catcode`<=\other
- \catcode`>=\other
- \catcode`+=\other
- \catcode`-=\other
-}
-
-\def\pushthisfilestack{%
- \expandafter\pushthisfilestackX\popthisfilestack\StackTerm
-}
-\def\pushthisfilestackX{%
- \expandafter\pushthisfilestackY\thisfile\StackTerm
-}
-\def\pushthisfilestackY #1\StackTerm #2\StackTerm {%
- \gdef\popthisfilestack{\gdef\thisfile{#1}\gdef\popthisfilestack{#2}}%
-}
-
-\def\popthisfilestack{\errthisfilestackempty}
-\def\errthisfilestackempty{\errmessage{Internal error:
- the stack of filenames is empty.}}
-
-\def\thisfile{}
-
-% @center line
-% outputs that line, centered.
-%
-\parseargdef\center{%
- \ifhmode
- \let\next\centerH
- \else
- \let\next\centerV
- \fi
- \next{\hfil \ignorespaces#1\unskip \hfil}%
-}
-\def\centerH#1{%
- {%
- \hfil\break
- \advance\hsize by -\leftskip
- \advance\hsize by -\rightskip
- \line{#1}%
- \break
- }%
-}
-\def\centerV#1{\line{\kern\leftskip #1\kern\rightskip}}
-
-% @sp n outputs n lines of vertical space
-
-\parseargdef\sp{\vskip #1\baselineskip}
-
-% @comment ...line which is ignored...
-% @c is the same as @comment
-% @ignore ... @end ignore is another way to write a comment
-
-\def\comment{\begingroup \catcode`\^^M=\other%
-\catcode`\@=\other \catcode`\{=\other \catcode`\}=\other%
-\commentxxx}
-{\catcode`\^^M=\other \gdef\commentxxx#1^^M{\endgroup}}
-
-\let\c=\comment
-
-% @paragraphindent NCHARS
-% We'll use ems for NCHARS, close enough.
-% NCHARS can also be the word `asis' or `none'.
-% We cannot feasibly implement @paragraphindent asis, though.
-%
-\def\asisword{asis} % no translation, these are keywords
-\def\noneword{none}
-%
-\parseargdef\paragraphindent{%
- \def\temp{#1}%
- \ifx\temp\asisword
- \else
- \ifx\temp\noneword
- \defaultparindent = 0pt
- \else
- \defaultparindent = #1em
- \fi
- \fi
- \parindent = \defaultparindent
-}
-
-% @exampleindent NCHARS
-% We'll use ems for NCHARS like @paragraphindent.
-% It seems @exampleindent asis isn't necessary, but
-% I preserve it to make it similar to @paragraphindent.
-\parseargdef\exampleindent{%
- \def\temp{#1}%
- \ifx\temp\asisword
- \else
- \ifx\temp\noneword
- \lispnarrowing = 0pt
- \else
- \lispnarrowing = #1em
- \fi
- \fi
-}
-
-% @firstparagraphindent WORD
-% If WORD is `none', then suppress indentation of the first paragraph
-% after a section heading. If WORD is `insert', then do indent at such
-% paragraphs.
-%
-% The paragraph indentation is suppressed or not by calling
-% \suppressfirstparagraphindent, which the sectioning commands do.
-% We switch the definition of this back and forth according to WORD.
-% By default, we suppress indentation.
-%
-\def\suppressfirstparagraphindent{\dosuppressfirstparagraphindent}
-\def\insertword{insert}
-%
-\parseargdef\firstparagraphindent{%
- \def\temp{#1}%
- \ifx\temp\noneword
- \let\suppressfirstparagraphindent = \dosuppressfirstparagraphindent
- \else\ifx\temp\insertword
- \let\suppressfirstparagraphindent = \relax
- \else
- \errhelp = \EMsimple
- \errmessage{Unknown @firstparagraphindent option `\temp'}%
- \fi\fi
-}
-
-% Here is how we actually suppress indentation. Redefine \everypar to
-% \kern backwards by \parindent, and then reset itself to empty.
-%
-% We also make \indent itself not actually do anything until the next
-% paragraph.
-%
-\gdef\dosuppressfirstparagraphindent{%
- \gdef\indent{%
- \restorefirstparagraphindent
- \indent
- }%
- \gdef\noindent{%
- \restorefirstparagraphindent
- \noindent
- }%
- \global\everypar = {%
- \kern -\parindent
- \restorefirstparagraphindent
- }%
-}
-
-\gdef\restorefirstparagraphindent{%
- \global \let \indent = \ptexindent
- \global \let \noindent = \ptexnoindent
- \global \everypar = {}%
-}
-
-
-% @asis just yields its argument. Used with @table, for example.
-%
-\def\asis#1{#1}
-
-% @math outputs its argument in math mode.
-%
-% One complication: _ usually means subscripts, but it could also mean
-% an actual _ character, as in @math{@var{some_variable} + 1}. So make
-% _ active, and distinguish by seeing if the current family is \slfam,
-% which is what @var uses.
-{
- \catcode`\_ = \active
- \gdef\mathunderscore{%
- \catcode`\_=\active
- \def_{\ifnum\fam=\slfam \_\else\sb\fi}%
- }
-}
-% Another complication: we want \\ (and @\) to output a \ character.
-% FYI, plain.tex uses \\ as a temporary control sequence (why?), but
-% this is not advertised and we don't care. Texinfo does not
-% otherwise define @\.
-%
-% The \mathchar is class=0=ordinary, family=7=ttfam, position=5C=\.
-\def\mathbackslash{\ifnum\fam=\ttfam \mathchar"075C \else\backslash \fi}
-%
-\def\math{%
- \tex
- \mathunderscore
- \let\\ = \mathbackslash
- \mathactive
- % make the texinfo accent commands work in math mode
- \let\"=\ddot
- \let\'=\acute
- \let\==\bar
- \let\^=\hat
- \let\`=\grave
- \let\u=\breve
- \let\v=\check
- \let\~=\tilde
- \let\dotaccent=\dot
- $\finishmath
-}
-\def\finishmath#1{#1$\endgroup} % Close the group opened by \tex.
-
-% Some active characters (such as <) are spaced differently in math.
-% We have to reset their definitions in case the @math was an argument
-% to a command which sets the catcodes (such as @item or @section).
-%
-{
- \catcode`^ = \active
- \catcode`< = \active
- \catcode`> = \active
- \catcode`+ = \active
- \gdef\mathactive{%
- \let^ = \ptexhat
- \let< = \ptexless
- \let> = \ptexgtr
- \let+ = \ptexplus
- }
-}
-
-% Some math mode symbols.
-\def\bullet{$\ptexbullet$}
-\def\geq{\ifmmode \ge\else $\ge$\fi}
-\def\leq{\ifmmode \le\else $\le$\fi}
-\def\minus{\ifmmode -\else $-$\fi}
-
-% @dots{} outputs an ellipsis using the current font.
-% We do .5em per period so that it has the same spacing in the cm
-% typewriter fonts as three actual period characters; on the other hand,
-% in other typewriter fonts three periods are wider than 1.5em. So do
-% whichever is larger.
-%
-\def\dots{%
- \leavevmode
- \setbox0=\hbox{...}% get width of three periods
- \ifdim\wd0 > 1.5em
- \dimen0 = \wd0
- \else
- \dimen0 = 1.5em
- \fi
- \hbox to \dimen0{%
- \hskip 0pt plus.25fil
- .\hskip 0pt plus1fil
- .\hskip 0pt plus1fil
- .\hskip 0pt plus.5fil
- }%
-}
-
-% @enddots{} is an end-of-sentence ellipsis.
-%
-\def\enddots{%
- \dots
- \spacefactor=\endofsentencespacefactor
-}
-
-% @comma{} is so commas can be inserted into text without messing up
-% Texinfo's parsing.
-%
-\let\comma = ,
-
-% @refill is a no-op.
-\let\refill=\relax
-
-% If working on a large document in chapters, it is convenient to
-% be able to disable indexing, cross-referencing, and contents, for test runs.
-% This is done with @novalidate (before @setfilename).
-%
-\newif\iflinks \linkstrue % by default we want the aux files.
-\let\novalidate = \linksfalse
-
-% @setfilename is done at the beginning of every texinfo file.
-% So open here the files we need to have open while reading the input.
-% This makes it possible to make a .fmt file for texinfo.
-\def\setfilename{%
- \fixbackslash % Turn off hack to swallow `\input texinfo'.
- \iflinks
- \tryauxfile
- % Open the new aux file. TeX will close it automatically at exit.
- \immediate\openout\auxfile=\jobname.aux
- \fi % \openindices needs to do some work in any case.
- \openindices
- \let\setfilename=\comment % Ignore extra @setfilename cmds.
- %
- % If texinfo.cnf is present on the system, read it.
- % Useful for site-wide @afourpaper, etc.
- \openin 1 texinfo.cnf
- \ifeof 1 \else \input texinfo.cnf \fi
- \closein 1
- %
- \comment % Ignore the actual filename.
-}
-
-% Called from \setfilename.
-%
-\def\openindices{%
- \newindex{cp}%
- \newcodeindex{fn}%
- \newcodeindex{vr}%
- \newcodeindex{tp}%
- \newcodeindex{ky}%
- \newcodeindex{pg}%
-}
-
-% @bye.
-\outer\def\bye{\pagealignmacro\tracingstats=1\ptexend}
-
-
-\message{pdf,}
-% adobe `portable' document format
-\newcount\tempnum
-\newcount\lnkcount
-\newtoks\filename
-\newcount\filenamelength
-\newcount\pgn
-\newtoks\toksA
-\newtoks\toksB
-\newtoks\toksC
-\newtoks\toksD
-\newbox\boxA
-\newcount\countA
-\newif\ifpdf
-\newif\ifpdfmakepagedest
-
-% when pdftex is run in dvi mode, \pdfoutput is defined (so \pdfoutput=1
-% can be set). So we test for \relax and 0 as well as \undefined,
-% borrowed from ifpdf.sty.
-\ifx\pdfoutput\undefined
-\else
- \ifx\pdfoutput\relax
- \else
- \ifcase\pdfoutput
- \else
- \pdftrue
- \fi
- \fi
-\fi
-
-% PDF uses PostScript string constants for the names of xref targets,
-% for display in the outlines, and in other places. Thus, we have to
-% double any backslashes. Otherwise, a name like "\node" will be
-% interpreted as a newline (\n), followed by o, d, e. Not good.
-% http://www.ntg.nl/pipermail/ntg-pdftex/2004-July/000654.html
-% (and related messages, the final outcome is that it is up to the TeX
-% user to double the backslashes and otherwise make the string valid, so
-% that's what we do).
-
-% double active backslashes.
-%
-{\catcode`\@=0 \catcode`\\=\active
- @gdef@activebackslashdouble{%
- @catcode`@\=@active
- @let\=@doublebackslash}
-}
-
-% To handle parens, we must adopt a different approach, since parens are
-% not active characters. hyperref.dtx (which has the same problem as
-% us) handles it with this amazing macro to replace tokens, with minor
-% changes for Texinfo. It is included here under the GPL by permission
-% from the author, Heiko Oberdiek.
-%
-% #1 is the tokens to replace.
-% #2 is the replacement.
-% #3 is the control sequence with the string.
-%
-\def\HyPsdSubst#1#2#3{%
- \def\HyPsdReplace##1#1##2\END{%
- ##1%
- \ifx\\##2\\%
- \else
- #2%
- \HyReturnAfterFi{%
- \HyPsdReplace##2\END
- }%
- \fi
- }%
- \xdef#3{\expandafter\HyPsdReplace#3#1\END}%
-}
-\long\def\HyReturnAfterFi#1\fi{\fi#1}
-
-% #1 is a control sequence in which to do the replacements.
-\def\backslashparens#1{%
- \xdef#1{#1}% redefine it as its expansion; the definition is simply
- % \lastnode when called from \setref -> \pdfmkdest.
- \HyPsdSubst{(}{\realbackslash(}{#1}%
- \HyPsdSubst{)}{\realbackslash)}{#1}%
-}
-
-\newhelp\nopdfimagehelp{Texinfo supports .png, .jpg, .jpeg, and .pdf images
-with PDF output, and none of those formats could be found. (.eps cannot
-be supported due to the design of the PDF format; use regular TeX (DVI
-output) for that.)}
-
-\ifpdf
- %
- % Color manipulation macros based on pdfcolor.tex.
- \def\cmykDarkRed{0.28 1 1 0.35}
- \def\cmykBlack{0 0 0 1}
- %
- \def\pdfsetcolor#1{\pdfliteral{#1 k}}
- % Set color, and create a mark which defines \thiscolor accordingly,
- % so that \makeheadline knows which color to restore.
- \def\setcolor#1{%
- \xdef\lastcolordefs{\gdef\noexpand\thiscolor{#1}}%
- \domark
- \pdfsetcolor{#1}%
- }
- %
- \def\maincolor{\cmykBlack}
- \pdfsetcolor{\maincolor}
- \edef\thiscolor{\maincolor}
- \def\lastcolordefs{}
- %
- \def\makefootline{%
- \baselineskip24pt
- \line{\pdfsetcolor{\maincolor}\the\footline}%
- }
- %
- \def\makeheadline{%
- \vbox to 0pt{%
- \vskip-22.5pt
- \line{%
- \vbox to8.5pt{}%
- % Extract \thiscolor definition from the marks.
- \getcolormarks
- % Typeset the headline with \maincolor, then restore the color.
- \pdfsetcolor{\maincolor}\the\headline\pdfsetcolor{\thiscolor}%
- }%
- \vss
- }%
- \nointerlineskip
- }
- %
- %
- \pdfcatalog{/PageMode /UseOutlines}
- %
- % #1 is image name, #2 width (might be empty/whitespace), #3 height (ditto).
- \def\dopdfimage#1#2#3{%
- \def\imagewidth{#2}\setbox0 = \hbox{\ignorespaces #2}%
- \def\imageheight{#3}\setbox2 = \hbox{\ignorespaces #3}%
- %
- % pdftex (and the PDF format) support .png, .jpg, .pdf (among
- % others). Let's try in that order.
- \let\pdfimgext=\empty
- \begingroup
- \openin 1 #1.png \ifeof 1
- \openin 1 #1.jpg \ifeof 1
- \openin 1 #1.jpeg \ifeof 1
- \openin 1 #1.JPG \ifeof 1
- \openin 1 #1.pdf \ifeof 1
- \openin 1 #1.PDF \ifeof 1
- \errhelp = \nopdfimagehelp
- \errmessage{Could not find image file #1 for pdf}%
- \else \gdef\pdfimgext{PDF}%
- \fi
- \else \gdef\pdfimgext{pdf}%
- \fi
- \else \gdef\pdfimgext{JPG}%
- \fi
- \else \gdef\pdfimgext{jpeg}%
- \fi
- \else \gdef\pdfimgext{jpg}%
- \fi
- \else \gdef\pdfimgext{png}%
- \fi
- \closein 1
- \endgroup
- %
- % without \immediate, ancient pdftex seg faults when the same image is
- % included twice. (Version 3.14159-pre-1.0-unofficial-20010704.)
- \ifnum\pdftexversion < 14
- \immediate\pdfimage
- \else
- \immediate\pdfximage
- \fi
- \ifdim \wd0 >0pt width \imagewidth \fi
- \ifdim \wd2 >0pt height \imageheight \fi
- \ifnum\pdftexversion<13
- #1.\pdfimgext
- \else
- {#1.\pdfimgext}%
- \fi
- \ifnum\pdftexversion < 14 \else
- \pdfrefximage \pdflastximage
- \fi}
- %
- \def\pdfmkdest#1{{%
- % We have to set dummies so commands such as @code, and characters
- % such as \, aren't expanded when present in a section title.
- \indexnofonts
- \turnoffactive
- \activebackslashdouble
- \makevalueexpandable
- \def\pdfdestname{#1}%
- \backslashparens\pdfdestname
- \safewhatsit{\pdfdest name{\pdfdestname} xyz}%
- }}
- %
- % used to mark target names; must be expandable.
- \def\pdfmkpgn#1{#1}
- %
- % by default, use a color that is dark enough to print on paper as
- % nearly black, but still distinguishable for online viewing.
- \def\urlcolor{\cmykDarkRed}
- \def\linkcolor{\cmykDarkRed}
- \def\endlink{\setcolor{\maincolor}\pdfendlink}
- %
- % Adding outlines to PDF; macros for calculating structure of outlines
- % come from Petr Olsak
- \def\expnumber#1{\expandafter\ifx\csname#1\endcsname\relax 0%
- \else \csname#1\endcsname \fi}
- \def\advancenumber#1{\tempnum=\expnumber{#1}\relax
- \advance\tempnum by 1
- \expandafter\xdef\csname#1\endcsname{\the\tempnum}}
- %
- % #1 is the section text, which is what will be displayed in the
- % outline by the pdf viewer. #2 is the pdf expression for the number
- % of subentries (or empty, for subsubsections). #3 is the node text,
- % which might be empty if this toc entry had no corresponding node.
- % #4 is the page number
- %
- \def\dopdfoutline#1#2#3#4{%
- % Generate a link to the node text if that exists; else, use the
- % page number. We could generate a destination for the section
- % text in the case where a section has no node, but it doesn't
- % seem worth the trouble, since most documents are normally structured.
- \def\pdfoutlinedest{#3}%
- \ifx\pdfoutlinedest\empty
- \def\pdfoutlinedest{#4}%
- \else
- % Doubled backslashes in the name.
- {\activebackslashdouble \xdef\pdfoutlinedest{#3}%
- \backslashparens\pdfoutlinedest}%
- \fi
- %
- % Also double the backslashes in the display string.
- {\activebackslashdouble \xdef\pdfoutlinetext{#1}%
- \backslashparens\pdfoutlinetext}%
- %
- \pdfoutline goto name{\pdfmkpgn{\pdfoutlinedest}}#2{\pdfoutlinetext}%
- }
- %
- \def\pdfmakeoutlines{%
- \begingroup
- % Thanh's hack / proper braces in bookmarks
- \edef\mylbrace{\iftrue \string{\else}\fi}\let\{=\mylbrace
- \edef\myrbrace{\iffalse{\else\string}\fi}\let\}=\myrbrace
- %
- % Read toc silently, to get counts of subentries for \pdfoutline.
- \def\numchapentry##1##2##3##4{%
- \def\thischapnum{##2}%
- \def\thissecnum{0}%
- \def\thissubsecnum{0}%
- }%
- \def\numsecentry##1##2##3##4{%
- \advancenumber{chap\thischapnum}%
- \def\thissecnum{##2}%
- \def\thissubsecnum{0}%
- }%
- \def\numsubsecentry##1##2##3##4{%
- \advancenumber{sec\thissecnum}%
- \def\thissubsecnum{##2}%
- }%
- \def\numsubsubsecentry##1##2##3##4{%
- \advancenumber{subsec\thissubsecnum}%
- }%
- \def\thischapnum{0}%
- \def\thissecnum{0}%
- \def\thissubsecnum{0}%
- %
- % use \def rather than \let here because we redefine \chapentry et
- % al. a second time, below.
- \def\appentry{\numchapentry}%
- \def\appsecentry{\numsecentry}%
- \def\appsubsecentry{\numsubsecentry}%
- \def\appsubsubsecentry{\numsubsubsecentry}%
- \def\unnchapentry{\numchapentry}%
- \def\unnsecentry{\numsecentry}%
- \def\unnsubsecentry{\numsubsecentry}%
- \def\unnsubsubsecentry{\numsubsubsecentry}%
- \readdatafile{toc}%
- %
- % Read toc second time, this time actually producing the outlines.
- % The `-' means take the \expnumber as the absolute number of
- % subentries, which we calculated on our first read of the .toc above.
- %
- % We use the node names as the destinations.
- \def\numchapentry##1##2##3##4{%
- \dopdfoutline{##1}{count-\expnumber{chap##2}}{##3}{##4}}%
- \def\numsecentry##1##2##3##4{%
- \dopdfoutline{##1}{count-\expnumber{sec##2}}{##3}{##4}}%
- \def\numsubsecentry##1##2##3##4{%
- \dopdfoutline{##1}{count-\expnumber{subsec##2}}{##3}{##4}}%
- \def\numsubsubsecentry##1##2##3##4{% count is always zero
- \dopdfoutline{##1}{}{##3}{##4}}%
- %
- % PDF outlines are displayed using system fonts, instead of
- % document fonts. Therefore we cannot use special characters,
- % since the encoding is unknown. For example, the eogonek from
- % Latin 2 (0xea) gets translated to a | character. Info from
- % Staszek Wawrykiewicz, 19 Jan 2004 04:09:24 +0100.
- %
- % xx to do this right, we have to translate 8-bit characters to
- % their "best" equivalent, based on the @documentencoding. Right
- % now, I guess we'll just let the pdf reader have its way.
- \indexnofonts
- \setupdatafile
- \catcode`\\=\active \otherbackslash
- \input \tocreadfilename
- \endgroup
- }
- %
- \def\skipspaces#1{\def\PP{#1}\def\D{|}%
- \ifx\PP\D\let\nextsp\relax
- \else\let\nextsp\skipspaces
- \ifx\p\space\else\addtokens{\filename}{\PP}%
- \advance\filenamelength by 1
- \fi
- \fi
- \nextsp}
- \def\getfilename#1{\filenamelength=0\expandafter\skipspaces#1|\relax}
- \ifnum\pdftexversion < 14
- \let \startlink \pdfannotlink
- \else
- \let \startlink \pdfstartlink
- \fi
- % make a live url in pdf output.
- \def\pdfurl#1{%
- \begingroup
- % it seems we really need yet another set of dummies; have not
- % tried to figure out what each command should do in the context
- % of @url. for now, just make @/ a no-op, that's the only one
- % people have actually reported a problem with.
- %
- \normalturnoffactive
- \def\@{@}%
- \let\/=\empty
- \makevalueexpandable
- \leavevmode\setcolor{\urlcolor}%
- \startlink attr{/Border [0 0 0]}%
- user{/Subtype /Link /A << /S /URI /URI (#1) >>}%
- \endgroup}
- \def\pdfgettoks#1.{\setbox\boxA=\hbox{\toksA={#1.}\toksB={}\maketoks}}
- \def\addtokens#1#2{\edef\addtoks{\noexpand#1={\the#1#2}}\addtoks}
- \def\adn#1{\addtokens{\toksC}{#1}\global\countA=1\let\next=\maketoks}
- \def\poptoks#1#2|ENDTOKS|{\let\first=#1\toksD={#1}\toksA={#2}}
- \def\maketoks{%
- \expandafter\poptoks\the\toksA|ENDTOKS|\relax
- \ifx\first0\adn0
- \else\ifx\first1\adn1 \else\ifx\first2\adn2 \else\ifx\first3\adn3
- \else\ifx\first4\adn4 \else\ifx\first5\adn5 \else\ifx\first6\adn6
- \else\ifx\first7\adn7 \else\ifx\first8\adn8 \else\ifx\first9\adn9
- \else
- \ifnum0=\countA\else\makelink\fi
- \ifx\first.\let\next=\done\else
- \let\next=\maketoks
- \addtokens{\toksB}{\the\toksD}
- \ifx\first,\addtokens{\toksB}{\space}\fi
- \fi
- \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi
- \next}
- \def\makelink{\addtokens{\toksB}%
- {\noexpand\pdflink{\the\toksC}}\toksC={}\global\countA=0}
- \def\pdflink#1{%
- \startlink attr{/Border [0 0 0]} goto name{\pdfmkpgn{#1}}
- \setcolor{\linkcolor}#1\endlink}
- \def\done{\edef\st{\global\noexpand\toksA={\the\toksB}}\st}
-\else
- \let\pdfmkdest = \gobble
- \let\pdfurl = \gobble
- \let\endlink = \relax
- \let\setcolor = \gobble
- \let\pdfsetcolor = \gobble
- \let\pdfmakeoutlines = \relax
-\fi % \ifx\pdfoutput
-
-
-\message{fonts,}
-
-% Change the current font style to #1, remembering it in \curfontstyle.
-% For now, we do not accumulate font styles: @b{@i{foo}} prints foo in
-% italics, not bold italics.
-%
-\def\setfontstyle#1{%
- \def\curfontstyle{#1}% not as a control sequence, because we are \edef'd.
- \csname ten#1\endcsname % change the current font
-}
-
-% Select #1 fonts with the current style.
-%
-\def\selectfonts#1{\csname #1fonts\endcsname \csname\curfontstyle\endcsname}
-
-\def\rm{\fam=0 \setfontstyle{rm}}
-\def\it{\fam=\itfam \setfontstyle{it}}
-\def\sl{\fam=\slfam \setfontstyle{sl}}
-\def\bf{\fam=\bffam \setfontstyle{bf}}\def\bfstylename{bf}
-\def\tt{\fam=\ttfam \setfontstyle{tt}}
-
-% Texinfo sort of supports the sans serif font style, which plain TeX does not.
-% So we set up a \sf.
-\newfam\sffam
-\def\sf{\fam=\sffam \setfontstyle{sf}}
-\let\li = \sf % Sometimes we call it \li, not \sf.
-
-% We don't need math for this font style.
-\def\ttsl{\setfontstyle{ttsl}}
-
-
-% Default leading.
-\newdimen\textleading \textleading = 13.2pt
-
-% Set the baselineskip to #1, and the lineskip and strut size
-% correspondingly. There is no deep meaning behind these magic numbers
-% used as factors; they just match (closely enough) what Knuth defined.
-%
-\def\lineskipfactor{.08333}
-\def\strutheightpercent{.70833}
-\def\strutdepthpercent {.29167}
-%
-% can get a sort of poor man's double spacing by redefining this.
-\def\baselinefactor{1}
-%
-\def\setleading#1{%
- \dimen0 = #1\relax
- \normalbaselineskip = \baselinefactor\dimen0
- \normallineskip = \lineskipfactor\normalbaselineskip
- \normalbaselines
- \setbox\strutbox =\hbox{%
- \vrule width0pt height\strutheightpercent\baselineskip
- depth \strutdepthpercent \baselineskip
- }%
-}
-
-% PDF CMaps. See also LaTeX's t1.cmap.
-%
-% do nothing with this by default.
-\expandafter\let\csname cmapOT1\endcsname\gobble
-\expandafter\let\csname cmapOT1IT\endcsname\gobble
-\expandafter\let\csname cmapOT1TT\endcsname\gobble
-
-% if we are producing pdf, and we have \pdffontattr, then define cmaps.
-% (\pdffontattr was introduced many years ago, but people still run
-% older pdftex's; it's easy to conditionalize, so we do.)
-\ifpdf \ifx\pdffontattr\undefined \else
- \begingroup
- \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char.
- \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap
-%%DocumentNeededResources: ProcSet (CIDInit)
-%%IncludeResource: ProcSet (CIDInit)
-%%BeginResource: CMap (TeX-OT1-0)
-%%Title: (TeX-OT1-0 TeX OT1 0)
-%%Version: 1.000
-%%EndComments
-/CIDInit /ProcSet findresource begin
-12 dict begin
-begincmap
-/CIDSystemInfo
-<< /Registry (TeX)
-/Ordering (OT1)
-/Supplement 0
->> def
-/CMapName /TeX-OT1-0 def
-/CMapType 2 def
-1 begincodespacerange
-<00> <7F>
-endcodespacerange
-8 beginbfrange
-<00> <01> <0393>
-<09> <0A> <03A8>
-<23> <26> <0023>
-<28> <3B> <0028>
-<3F> <5B> <003F>
-<5D> <5E> <005D>
-<61> <7A> <0061>
-<7B> <7C> <2013>
-endbfrange
-40 beginbfchar
-<02> <0398>
-<03> <039B>
-<04> <039E>
-<05> <03A0>
-<06> <03A3>
-<07> <03D2>
-<08> <03A6>
-<0B> <00660066>
-<0C> <00660069>
-<0D> <0066006C>
-<0E> <006600660069>
-<0F> <00660066006C>
-<10> <0131>
-<11> <0237>
-<12> <0060>
-<13> <00B4>
-<14> <02C7>
-<15> <02D8>
-<16> <00AF>
-<17> <02DA>
-<18> <00B8>
-<19> <00DF>
-<1A> <00E6>
-<1B> <0153>
-<1C> <00F8>
-<1D> <00C6>
-<1E> <0152>
-<1F> <00D8>
-<21> <0021>
-<22> <201D>
-<27> <2019>
-<3C> <00A1>
-<3D> <003D>
-<3E> <00BF>
-<5C> <201C>
-<5F> <02D9>
-<60> <2018>
-<7D> <02DD>
-<7E> <007E>
-<7F> <00A8>
-endbfchar
-endcmap
-CMapName currentdict /CMap defineresource pop
-end
-end
-%%EndResource
-%%EOF
- }\endgroup
- \expandafter\edef\csname cmapOT1\endcsname#1{%
- \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}%
- }%
-%
-% \cmapOT1IT
- \begingroup
- \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char.
- \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap
-%%DocumentNeededResources: ProcSet (CIDInit)
-%%IncludeResource: ProcSet (CIDInit)
-%%BeginResource: CMap (TeX-OT1IT-0)
-%%Title: (TeX-OT1IT-0 TeX OT1IT 0)
-%%Version: 1.000
-%%EndComments
-/CIDInit /ProcSet findresource begin
-12 dict begin
-begincmap
-/CIDSystemInfo
-<< /Registry (TeX)
-/Ordering (OT1IT)
-/Supplement 0
->> def
-/CMapName /TeX-OT1IT-0 def
-/CMapType 2 def
-1 begincodespacerange
-<00> <7F>
-endcodespacerange
-8 beginbfrange
-<00> <01> <0393>
-<09> <0A> <03A8>
-<25> <26> <0025>
-<28> <3B> <0028>
-<3F> <5B> <003F>
-<5D> <5E> <005D>
-<61> <7A> <0061>
-<7B> <7C> <2013>
-endbfrange
-42 beginbfchar
-<02> <0398>
-<03> <039B>
-<04> <039E>
-<05> <03A0>
-<06> <03A3>
-<07> <03D2>
-<08> <03A6>
-<0B> <00660066>
-<0C> <00660069>
-<0D> <0066006C>
-<0E> <006600660069>
-<0F> <00660066006C>
-<10> <0131>
-<11> <0237>
-<12> <0060>
-<13> <00B4>
-<14> <02C7>
-<15> <02D8>
-<16> <00AF>
-<17> <02DA>
-<18> <00B8>
-<19> <00DF>
-<1A> <00E6>
-<1B> <0153>
-<1C> <00F8>
-<1D> <00C6>
-<1E> <0152>
-<1F> <00D8>
-<21> <0021>
-<22> <201D>
-<23> <0023>
-<24> <00A3>
-<27> <2019>
-<3C> <00A1>
-<3D> <003D>
-<3E> <00BF>
-<5C> <201C>
-<5F> <02D9>
-<60> <2018>
-<7D> <02DD>
-<7E> <007E>
-<7F> <00A8>
-endbfchar
-endcmap
-CMapName currentdict /CMap defineresource pop
-end
-end
-%%EndResource
-%%EOF
- }\endgroup
- \expandafter\edef\csname cmapOT1IT\endcsname#1{%
- \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}%
- }%
-%
-% \cmapOT1TT
- \begingroup
- \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char.
- \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap
-%%DocumentNeededResources: ProcSet (CIDInit)
-%%IncludeResource: ProcSet (CIDInit)
-%%BeginResource: CMap (TeX-OT1TT-0)
-%%Title: (TeX-OT1TT-0 TeX OT1TT 0)
-%%Version: 1.000
-%%EndComments
-/CIDInit /ProcSet findresource begin
-12 dict begin
-begincmap
-/CIDSystemInfo
-<< /Registry (TeX)
-/Ordering (OT1TT)
-/Supplement 0
->> def
-/CMapName /TeX-OT1TT-0 def
-/CMapType 2 def
-1 begincodespacerange
-<00> <7F>
-endcodespacerange
-5 beginbfrange
-<00> <01> <0393>
-<09> <0A> <03A8>
-<21> <26> <0021>
-<28> <5F> <0028>
-<61> <7E> <0061>
-endbfrange
-32 beginbfchar
-<02> <0398>
-<03> <039B>
-<04> <039E>
-<05> <03A0>
-<06> <03A3>
-<07> <03D2>
-<08> <03A6>
-<0B> <2191>
-<0C> <2193>
-<0D> <0027>
-<0E> <00A1>
-<0F> <00BF>
-<10> <0131>
-<11> <0237>
-<12> <0060>
-<13> <00B4>
-<14> <02C7>
-<15> <02D8>
-<16> <00AF>
-<17> <02DA>
-<18> <00B8>
-<19> <00DF>
-<1A> <00E6>
-<1B> <0153>
-<1C> <00F8>
-<1D> <00C6>
-<1E> <0152>
-<1F> <00D8>
-<20> <2423>
-<27> <2019>
-<60> <2018>
-<7F> <00A8>
-endbfchar
-endcmap
-CMapName currentdict /CMap defineresource pop
-end
-end
-%%EndResource
-%%EOF
- }\endgroup
- \expandafter\edef\csname cmapOT1TT\endcsname#1{%
- \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}%
- }%
-\fi\fi
-
-
-% Set the font macro #1 to the font named #2, adding on the
-% specified font prefix (normally `cm').
-% #3 is the font's design size, #4 is a scale factor, #5 is the CMap
-% encoding (currently only OT1, OT1IT and OT1TT are allowed, pass
-% empty to omit).
-\def\setfont#1#2#3#4#5{%
- \font#1=\fontprefix#2#3 scaled #4
- \csname cmap#5\endcsname#1%
-}
-% This is what gets called when #5 of \setfont is empty.
-\let\cmap\gobble
-% emacs-page end of cmaps
-
-% Use cm as the default font prefix.
-% To specify the font prefix, you must define \fontprefix
-% before you read in texinfo.tex.
-\ifx\fontprefix\undefined
-\def\fontprefix{cm}
-\fi
-% Support font families that don't use the same naming scheme as CM.
-\def\rmshape{r}
-\def\rmbshape{bx} %where the normal face is bold
-\def\bfshape{b}
-\def\bxshape{bx}
-\def\ttshape{tt}
-\def\ttbshape{tt}
-\def\ttslshape{sltt}
-\def\itshape{ti}
-\def\itbshape{bxti}
-\def\slshape{sl}
-\def\slbshape{bxsl}
-\def\sfshape{ss}
-\def\sfbshape{ss}
-\def\scshape{csc}
-\def\scbshape{csc}
-
-% Definitions for a main text size of 11pt. This is the default in
-% Texinfo.
-%
-\def\definetextfontsizexi{%
-% Text fonts (11.2pt, magstep1).
-\def\textnominalsize{11pt}
-\edef\mainmagstep{\magstephalf}
-\setfont\textrm\rmshape{10}{\mainmagstep}{OT1}
-\setfont\texttt\ttshape{10}{\mainmagstep}{OT1TT}
-\setfont\textbf\bfshape{10}{\mainmagstep}{OT1}
-\setfont\textit\itshape{10}{\mainmagstep}{OT1IT}
-\setfont\textsl\slshape{10}{\mainmagstep}{OT1}
-\setfont\textsf\sfshape{10}{\mainmagstep}{OT1}
-\setfont\textsc\scshape{10}{\mainmagstep}{OT1}
-\setfont\textttsl\ttslshape{10}{\mainmagstep}{OT1TT}
-\font\texti=cmmi10 scaled \mainmagstep
-\font\textsy=cmsy10 scaled \mainmagstep
-\def\textecsize{1095}
-
-% A few fonts for @defun names and args.
-\setfont\defbf\bfshape{10}{\magstep1}{OT1}
-\setfont\deftt\ttshape{10}{\magstep1}{OT1TT}
-\setfont\defttsl\ttslshape{10}{\magstep1}{OT1TT}
-\def\df{\let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf}
-
-% Fonts for indices, footnotes, small examples (9pt).
-\def\smallnominalsize{9pt}
-\setfont\smallrm\rmshape{9}{1000}{OT1}
-\setfont\smalltt\ttshape{9}{1000}{OT1TT}
-\setfont\smallbf\bfshape{10}{900}{OT1}
-\setfont\smallit\itshape{9}{1000}{OT1IT}
-\setfont\smallsl\slshape{9}{1000}{OT1}
-\setfont\smallsf\sfshape{9}{1000}{OT1}
-\setfont\smallsc\scshape{10}{900}{OT1}
-\setfont\smallttsl\ttslshape{10}{900}{OT1TT}
-\font\smalli=cmmi9
-\font\smallsy=cmsy9
-\def\smallecsize{0900}
-
-% Fonts for small examples (8pt).
-\def\smallernominalsize{8pt}
-\setfont\smallerrm\rmshape{8}{1000}{OT1}
-\setfont\smallertt\ttshape{8}{1000}{OT1TT}
-\setfont\smallerbf\bfshape{10}{800}{OT1}
-\setfont\smallerit\itshape{8}{1000}{OT1IT}
-\setfont\smallersl\slshape{8}{1000}{OT1}
-\setfont\smallersf\sfshape{8}{1000}{OT1}
-\setfont\smallersc\scshape{10}{800}{OT1}
-\setfont\smallerttsl\ttslshape{10}{800}{OT1TT}
-\font\smalleri=cmmi8
-\font\smallersy=cmsy8
-\def\smallerecsize{0800}
-
-% Fonts for title page (20.4pt):
-\def\titlenominalsize{20pt}
-\setfont\titlerm\rmbshape{12}{\magstep3}{OT1}
-\setfont\titleit\itbshape{10}{\magstep4}{OT1IT}
-\setfont\titlesl\slbshape{10}{\magstep4}{OT1}
-\setfont\titlett\ttbshape{12}{\magstep3}{OT1TT}
-\setfont\titlettsl\ttslshape{10}{\magstep4}{OT1TT}
-\setfont\titlesf\sfbshape{17}{\magstep1}{OT1}
-\let\titlebf=\titlerm
-\setfont\titlesc\scbshape{10}{\magstep4}{OT1}
-\font\titlei=cmmi12 scaled \magstep3
-\font\titlesy=cmsy10 scaled \magstep4
-\def\authorrm{\secrm}
-\def\authortt{\sectt}
-\def\titleecsize{2074}
-
-% Chapter (and unnumbered) fonts (17.28pt).
-\def\chapnominalsize{17pt}
-\setfont\chaprm\rmbshape{12}{\magstep2}{OT1}
-\setfont\chapit\itbshape{10}{\magstep3}{OT1IT}
-\setfont\chapsl\slbshape{10}{\magstep3}{OT1}
-\setfont\chaptt\ttbshape{12}{\magstep2}{OT1TT}
-\setfont\chapttsl\ttslshape{10}{\magstep3}{OT1TT}
-\setfont\chapsf\sfbshape{17}{1000}{OT1}
-\let\chapbf=\chaprm
-\setfont\chapsc\scbshape{10}{\magstep3}{OT1}
-\font\chapi=cmmi12 scaled \magstep2
-\font\chapsy=cmsy10 scaled \magstep3
-\def\chapecsize{1728}
-
-% Section fonts (14.4pt).
-\def\secnominalsize{14pt}
-\setfont\secrm\rmbshape{12}{\magstep1}{OT1}
-\setfont\secit\itbshape{10}{\magstep2}{OT1IT}
-\setfont\secsl\slbshape{10}{\magstep2}{OT1}
-\setfont\sectt\ttbshape{12}{\magstep1}{OT1TT}
-\setfont\secttsl\ttslshape{10}{\magstep2}{OT1TT}
-\setfont\secsf\sfbshape{12}{\magstep1}{OT1}
-\let\secbf\secrm
-\setfont\secsc\scbshape{10}{\magstep2}{OT1}
-\font\seci=cmmi12 scaled \magstep1
-\font\secsy=cmsy10 scaled \magstep2
-\def\sececsize{1440}
-
-% Subsection fonts (13.15pt).
-\def\ssecnominalsize{13pt}
-\setfont\ssecrm\rmbshape{12}{\magstephalf}{OT1}
-\setfont\ssecit\itbshape{10}{1315}{OT1IT}
-\setfont\ssecsl\slbshape{10}{1315}{OT1}
-\setfont\ssectt\ttbshape{12}{\magstephalf}{OT1TT}
-\setfont\ssecttsl\ttslshape{10}{1315}{OT1TT}
-\setfont\ssecsf\sfbshape{12}{\magstephalf}{OT1}
-\let\ssecbf\ssecrm
-\setfont\ssecsc\scbshape{10}{1315}{OT1}
-\font\sseci=cmmi12 scaled \magstephalf
-\font\ssecsy=cmsy10 scaled 1315
-\def\ssececsize{1200}
-
-% Reduced fonts for @acro in text (10pt).
-\def\reducednominalsize{10pt}
-\setfont\reducedrm\rmshape{10}{1000}{OT1}
-\setfont\reducedtt\ttshape{10}{1000}{OT1TT}
-\setfont\reducedbf\bfshape{10}{1000}{OT1}
-\setfont\reducedit\itshape{10}{1000}{OT1IT}
-\setfont\reducedsl\slshape{10}{1000}{OT1}
-\setfont\reducedsf\sfshape{10}{1000}{OT1}
-\setfont\reducedsc\scshape{10}{1000}{OT1}
-\setfont\reducedttsl\ttslshape{10}{1000}{OT1TT}
-\font\reducedi=cmmi10
-\font\reducedsy=cmsy10
-\def\reducedecsize{1000}
-
-% reset the current fonts
-\textfonts
-\rm
-} % end of 11pt text font size definitions
-
-
-% Definitions to make the main text be 10pt Computer Modern, with
-% section, chapter, etc., sizes following suit. This is for the GNU
-% Press printing of the Emacs 22 manual. Maybe other manuals in the
-% future. Used with @smallbook, which sets the leading to 12pt.
-%
-\def\definetextfontsizex{%
-% Text fonts (10pt).
-\def\textnominalsize{10pt}
-\edef\mainmagstep{1000}
-\setfont\textrm\rmshape{10}{\mainmagstep}{OT1}
-\setfont\texttt\ttshape{10}{\mainmagstep}{OT1TT}
-\setfont\textbf\bfshape{10}{\mainmagstep}{OT1}
-\setfont\textit\itshape{10}{\mainmagstep}{OT1IT}
-\setfont\textsl\slshape{10}{\mainmagstep}{OT1}
-\setfont\textsf\sfshape{10}{\mainmagstep}{OT1}
-\setfont\textsc\scshape{10}{\mainmagstep}{OT1}
-\setfont\textttsl\ttslshape{10}{\mainmagstep}{OT1TT}
-\font\texti=cmmi10 scaled \mainmagstep
-\font\textsy=cmsy10 scaled \mainmagstep
-\def\textecsize{1000}
-
-% A few fonts for @defun names and args.
-\setfont\defbf\bfshape{10}{\magstephalf}{OT1}
-\setfont\deftt\ttshape{10}{\magstephalf}{OT1TT}
-\setfont\defttsl\ttslshape{10}{\magstephalf}{OT1TT}
-\def\df{\let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf}
-
-% Fonts for indices, footnotes, small examples (9pt).
-\def\smallnominalsize{9pt}
-\setfont\smallrm\rmshape{9}{1000}{OT1}
-\setfont\smalltt\ttshape{9}{1000}{OT1TT}
-\setfont\smallbf\bfshape{10}{900}{OT1}
-\setfont\smallit\itshape{9}{1000}{OT1IT}
-\setfont\smallsl\slshape{9}{1000}{OT1}
-\setfont\smallsf\sfshape{9}{1000}{OT1}
-\setfont\smallsc\scshape{10}{900}{OT1}
-\setfont\smallttsl\ttslshape{10}{900}{OT1TT}
-\font\smalli=cmmi9
-\font\smallsy=cmsy9
-\def\smallecsize{0900}
-
-% Fonts for small examples (8pt).
-\def\smallernominalsize{8pt}
-\setfont\smallerrm\rmshape{8}{1000}{OT1}
-\setfont\smallertt\ttshape{8}{1000}{OT1TT}
-\setfont\smallerbf\bfshape{10}{800}{OT1}
-\setfont\smallerit\itshape{8}{1000}{OT1IT}
-\setfont\smallersl\slshape{8}{1000}{OT1}
-\setfont\smallersf\sfshape{8}{1000}{OT1}
-\setfont\smallersc\scshape{10}{800}{OT1}
-\setfont\smallerttsl\ttslshape{10}{800}{OT1TT}
-\font\smalleri=cmmi8
-\font\smallersy=cmsy8
-\def\smallerecsize{0800}
-
-% Fonts for title page (20.4pt):
-\def\titlenominalsize{20pt}
-\setfont\titlerm\rmbshape{12}{\magstep3}{OT1}
-\setfont\titleit\itbshape{10}{\magstep4}{OT1IT}
-\setfont\titlesl\slbshape{10}{\magstep4}{OT1}
-\setfont\titlett\ttbshape{12}{\magstep3}{OT1TT}
-\setfont\titlettsl\ttslshape{10}{\magstep4}{OT1TT}
-\setfont\titlesf\sfbshape{17}{\magstep1}{OT1}
-\let\titlebf=\titlerm
-\setfont\titlesc\scbshape{10}{\magstep4}{OT1}
-\font\titlei=cmmi12 scaled \magstep3
-\font\titlesy=cmsy10 scaled \magstep4
-\def\authorrm{\secrm}
-\def\authortt{\sectt}
-\def\titleecsize{2074}
-
-% Chapter fonts (14.4pt).
-\def\chapnominalsize{14pt}
-\setfont\chaprm\rmbshape{12}{\magstep1}{OT1}
-\setfont\chapit\itbshape{10}{\magstep2}{OT1IT}
-\setfont\chapsl\slbshape{10}{\magstep2}{OT1}
-\setfont\chaptt\ttbshape{12}{\magstep1}{OT1TT}
-\setfont\chapttsl\ttslshape{10}{\magstep2}{OT1TT}
-\setfont\chapsf\sfbshape{12}{\magstep1}{OT1}
-\let\chapbf\chaprm
-\setfont\chapsc\scbshape{10}{\magstep2}{OT1}
-\font\chapi=cmmi12 scaled \magstep1
-\font\chapsy=cmsy10 scaled \magstep2
-\def\chapecsize{1440}
-
-% Section fonts (12pt).
-\def\secnominalsize{12pt}
-\setfont\secrm\rmbshape{12}{1000}{OT1}
-\setfont\secit\itbshape{10}{\magstep1}{OT1IT}
-\setfont\secsl\slbshape{10}{\magstep1}{OT1}
-\setfont\sectt\ttbshape{12}{1000}{OT1TT}
-\setfont\secttsl\ttslshape{10}{\magstep1}{OT1TT}
-\setfont\secsf\sfbshape{12}{1000}{OT1}
-\let\secbf\secrm
-\setfont\secsc\scbshape{10}{\magstep1}{OT1}
-\font\seci=cmmi12
-\font\secsy=cmsy10 scaled \magstep1
-\def\sececsize{1200}
-
-% Subsection fonts (10pt).
-\def\ssecnominalsize{10pt}
-\setfont\ssecrm\rmbshape{10}{1000}{OT1}
-\setfont\ssecit\itbshape{10}{1000}{OT1IT}
-\setfont\ssecsl\slbshape{10}{1000}{OT1}
-\setfont\ssectt\ttbshape{10}{1000}{OT1TT}
-\setfont\ssecttsl\ttslshape{10}{1000}{OT1TT}
-\setfont\ssecsf\sfbshape{10}{1000}{OT1}
-\let\ssecbf\ssecrm
-\setfont\ssecsc\scbshape{10}{1000}{OT1}
-\font\sseci=cmmi10
-\font\ssecsy=cmsy10
-\def\ssececsize{1000}
-
-% Reduced fonts for @acro in text (9pt).
-\def\reducednominalsize{9pt}
-\setfont\reducedrm\rmshape{9}{1000}{OT1}
-\setfont\reducedtt\ttshape{9}{1000}{OT1TT}
-\setfont\reducedbf\bfshape{10}{900}{OT1}
-\setfont\reducedit\itshape{9}{1000}{OT1IT}
-\setfont\reducedsl\slshape{9}{1000}{OT1}
-\setfont\reducedsf\sfshape{9}{1000}{OT1}
-\setfont\reducedsc\scshape{10}{900}{OT1}
-\setfont\reducedttsl\ttslshape{10}{900}{OT1TT}
-\font\reducedi=cmmi9
-\font\reducedsy=cmsy9
-\def\reducedecsize{0900}
-
-% reduce space between paragraphs
-\divide\parskip by 2
-
-% reset the current fonts
-\textfonts
-\rm
-} % end of 10pt text font size definitions
-
-
-% We provide the user-level command
-% @fonttextsize 10
-% (or 11) to redefine the text font size. pt is assumed.
-%
-\def\xword{10}
-\def\xiword{11}
-%
-\parseargdef\fonttextsize{%
- \def\textsizearg{#1}%
- \wlog{doing @fonttextsize \textsizearg}%
- %
- % Set \globaldefs so that documents can use this inside @tex, since
- % makeinfo 4.8 does not support it, but we need it nonetheless.
- %
- \begingroup \globaldefs=1
- \ifx\textsizearg\xword \definetextfontsizex
- \else \ifx\textsizearg\xiword \definetextfontsizexi
- \else
- \errhelp=\EMsimple
- \errmessage{@fonttextsize only supports `10' or `11', not `\textsizearg'}
- \fi\fi
- \endgroup
-}
-
-
-% In order for the font changes to affect most math symbols and letters,
-% we have to define the \textfont of the standard families. Since
-% texinfo doesn't allow for producing subscripts and superscripts except
-% in the main text, we don't bother to reset \scriptfont and
-% \scriptscriptfont (which would also require loading a lot more fonts).
-%
-\def\resetmathfonts{%
- \textfont0=\tenrm \textfont1=\teni \textfont2=\tensy
- \textfont\itfam=\tenit \textfont\slfam=\tensl \textfont\bffam=\tenbf
- \textfont\ttfam=\tentt \textfont\sffam=\tensf
-}
-
-% The font-changing commands redefine the meanings of \tenSTYLE, instead
-% of just \STYLE. We do this because \STYLE needs to also set the
-% current \fam for math mode. Our \STYLE (e.g., \rm) commands hardwire
-% \tenSTYLE to set the current font.
-%
-% Each font-changing command also sets the names \lsize (one size lower)
-% and \lllsize (three sizes lower). These relative commands are used in
-% the LaTeX logo and acronyms.
-%
-% This all needs generalizing, badly.
-%
-\def\textfonts{%
- \let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl
- \let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc
- \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy
- \let\tenttsl=\textttsl
- \def\curfontsize{text}%
- \def\lsize{reduced}\def\lllsize{smaller}%
- \resetmathfonts \setleading{\textleading}}
-\def\titlefonts{%
- \let\tenrm=\titlerm \let\tenit=\titleit \let\tensl=\titlesl
- \let\tenbf=\titlebf \let\tentt=\titlett \let\smallcaps=\titlesc
- \let\tensf=\titlesf \let\teni=\titlei \let\tensy=\titlesy
- \let\tenttsl=\titlettsl
- \def\curfontsize{title}%
- \def\lsize{chap}\def\lllsize{subsec}%
- \resetmathfonts \setleading{25pt}}
-\def\titlefont#1{{\titlefonts\rm #1}}
-\def\chapfonts{%
- \let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl
- \let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc
- \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy
- \let\tenttsl=\chapttsl
- \def\curfontsize{chap}%
- \def\lsize{sec}\def\lllsize{text}%
- \resetmathfonts \setleading{19pt}}
-\def\secfonts{%
- \let\tenrm=\secrm \let\tenit=\secit \let\tensl=\secsl
- \let\tenbf=\secbf \let\tentt=\sectt \let\smallcaps=\secsc
- \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy
- \let\tenttsl=\secttsl
- \def\curfontsize{sec}%
- \def\lsize{subsec}\def\lllsize{reduced}%
- \resetmathfonts \setleading{16pt}}
-\def\subsecfonts{%
- \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl
- \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc
- \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy
- \let\tenttsl=\ssecttsl
- \def\curfontsize{ssec}%
- \def\lsize{text}\def\lllsize{small}%
- \resetmathfonts \setleading{15pt}}
-\let\subsubsecfonts = \subsecfonts
-\def\reducedfonts{%
- \let\tenrm=\reducedrm \let\tenit=\reducedit \let\tensl=\reducedsl
- \let\tenbf=\reducedbf \let\tentt=\reducedtt \let\reducedcaps=\reducedsc
- \let\tensf=\reducedsf \let\teni=\reducedi \let\tensy=\reducedsy
- \let\tenttsl=\reducedttsl
- \def\curfontsize{reduced}%
- \def\lsize{small}\def\lllsize{smaller}%
- \resetmathfonts \setleading{10.5pt}}
-\def\smallfonts{%
- \let\tenrm=\smallrm \let\tenit=\smallit \let\tensl=\smallsl
- \let\tenbf=\smallbf \let\tentt=\smalltt \let\smallcaps=\smallsc
- \let\tensf=\smallsf \let\teni=\smalli \let\tensy=\smallsy
- \let\tenttsl=\smallttsl
- \def\curfontsize{small}%
- \def\lsize{smaller}\def\lllsize{smaller}%
- \resetmathfonts \setleading{10.5pt}}
-\def\smallerfonts{%
- \let\tenrm=\smallerrm \let\tenit=\smallerit \let\tensl=\smallersl
- \let\tenbf=\smallerbf \let\tentt=\smallertt \let\smallcaps=\smallersc
- \let\tensf=\smallersf \let\teni=\smalleri \let\tensy=\smallersy
- \let\tenttsl=\smallerttsl
- \def\curfontsize{smaller}%
- \def\lsize{smaller}\def\lllsize{smaller}%
- \resetmathfonts \setleading{9.5pt}}
-
-% Set the fonts to use with the @small... environments.
-\let\smallexamplefonts = \smallfonts
-
-% About \smallexamplefonts. If we use \smallfonts (9pt), @smallexample
-% can fit this many characters:
-% 8.5x11=86 smallbook=72 a4=90 a5=69
-% If we use \scriptfonts (8pt), then we can fit this many characters:
-% 8.5x11=90+ smallbook=80 a4=90+ a5=77
-% For me, subjectively, the few extra characters that fit aren't worth
-% the additional smallness of 8pt. So I'm making the default 9pt.
-%
-% By the way, for comparison, here's what fits with @example (10pt):
-% 8.5x11=71 smallbook=60 a4=75 a5=58
-%
-% I wish the USA used A4 paper.
-% --karl, 24jan03.
-
-
-% Set up the default fonts, so we can use them for creating boxes.
-%
-\definetextfontsizexi
-
-% Define these so they can be easily changed for other fonts.
-\def\angleleft{$\langle$}
-\def\angleright{$\rangle$}
-
-% Count depth in font-changes, for error checks
-\newcount\fontdepth \fontdepth=0
-
-% Fonts for short table of contents.
-\setfont\shortcontrm\rmshape{12}{1000}{OT1}
-\setfont\shortcontbf\bfshape{10}{\magstep1}{OT1} % no cmb12
-\setfont\shortcontsl\slshape{12}{1000}{OT1}
-\setfont\shortconttt\ttshape{12}{1000}{OT1TT}
-
-%% Add scribe-like font environments, plus @l for inline lisp (usually sans
-%% serif) and @ii for TeX italic
-
-% \smartitalic{ARG} outputs arg in italics, followed by an italic correction
-% unless the following character is such as not to need one.
-\def\smartitalicx{\ifx\next,\else\ifx\next-\else\ifx\next.\else
- \ptexslash\fi\fi\fi}
-\def\smartslanted#1{{\ifusingtt\ttsl\sl #1}\futurelet\next\smartitalicx}
-\def\smartitalic#1{{\ifusingtt\ttsl\it #1}\futurelet\next\smartitalicx}
-
-% like \smartslanted except unconditionally uses \ttsl.
-% @var is set to this for defun arguments.
-\def\ttslanted#1{{\ttsl #1}\futurelet\next\smartitalicx}
-
-% like \smartslanted except unconditionally use \sl. We never want
-% ttsl for book titles, do we?
-\def\cite#1{{\sl #1}\futurelet\next\smartitalicx}
-
-\let\i=\smartitalic
-\let\slanted=\smartslanted
-\let\var=\smartslanted
-\let\dfn=\smartslanted
-\let\emph=\smartitalic
-
-% @b, explicit bold.
-\def\b#1{{\bf #1}}
-\let\strong=\b
-
-% @sansserif, explicit sans.
-\def\sansserif#1{{\sf #1}}
-
-% We can't just use \exhyphenpenalty, because that only has effect at
-% the end of a paragraph. Restore normal hyphenation at the end of the
-% group within which \nohyphenation is presumably called.
-%
-\def\nohyphenation{\hyphenchar\font = -1 \aftergroup\restorehyphenation}
-\def\restorehyphenation{\hyphenchar\font = `- }
-
-% Set sfcode to normal for the chars that usually have another value.
-% Can't use plain's \frenchspacing because it uses the `\x notation, and
-% sometimes \x has an active definition that messes things up.
-%
-\catcode`@=11
- \def\plainfrenchspacing{%
- \sfcode\dotChar =\@m \sfcode\questChar=\@m \sfcode\exclamChar=\@m
- \sfcode\colonChar=\@m \sfcode\semiChar =\@m \sfcode\commaChar =\@m
- \def\endofsentencespacefactor{1000}% for @. and friends
- }
- \def\plainnonfrenchspacing{%
- \sfcode`\.3000\sfcode`\?3000\sfcode`\!3000
- \sfcode`\:2000\sfcode`\;1500\sfcode`\,1250
- \def\endofsentencespacefactor{3000}% for @. and friends
- }
-\catcode`@=\other
-\def\endofsentencespacefactor{3000}% default
-
-\def\t#1{%
- {\tt \rawbackslash \plainfrenchspacing #1}%
- \null
-}
-\def\samp#1{`\tclose{#1}'\null}
-\setfont\keyrm\rmshape{8}{1000}{OT1}
-\font\keysy=cmsy9
-\def\key#1{{\keyrm\textfont2=\keysy \leavevmode\hbox{%
- \raise0.4pt\hbox{\angleleft}\kern-.08em\vtop{%
- \vbox{\hrule\kern-0.4pt
- \hbox{\raise0.4pt\hbox{\vphantom{\angleleft}}#1}}%
- \kern-0.4pt\hrule}%
- \kern-.06em\raise0.4pt\hbox{\angleright}}}}
-\def\key #1{{\nohyphenation \uppercase{#1}}\null}
-% The old definition, with no lozenge:
-%\def\key #1{{\ttsl \nohyphenation \uppercase{#1}}\null}
-\def\ctrl #1{{\tt \rawbackslash \hat}#1}
-
-% @file, @option are the same as @samp.
-\let\file=\samp
-\let\option=\samp
-
-% @code is a modification of @t,
-% which makes spaces the same size as normal in the surrounding text.
-\def\tclose#1{%
- {%
- % Change normal interword space to be same as for the current font.
- \spaceskip = \fontdimen2\font
- %
- % Switch to typewriter.
- \tt
- %
- % But `\ ' produces the large typewriter interword space.
- \def\ {{\spaceskip = 0pt{} }}%
- %
- % Turn off hyphenation.
- \nohyphenation
- %
- \rawbackslash
- \plainfrenchspacing
- #1%
- }%
- \null
-}
-
-% We *must* turn on hyphenation at `-' and `_' in @code.
-% Otherwise, it is too hard to avoid overfull hboxes
-% in the Emacs manual, the Library manual, etc.
-
-% Unfortunately, TeX uses one parameter (\hyphenchar) to control
-% both hyphenation at - and hyphenation within words.
-% We must therefore turn them both off (\tclose does that)
-% and arrange explicitly to hyphenate at a dash.
-% -- rms.
-{
- \catcode`\-=\active \catcode`\_=\active
- \catcode`\'=\active \catcode`\`=\active
- %
- \global\def\code{\begingroup
- \catcode\rquoteChar=\active \catcode\lquoteChar=\active
- \let'\codequoteright \let`\codequoteleft
- %
- \catcode\dashChar=\active \catcode\underChar=\active
- \ifallowcodebreaks
- \let-\codedash
- \let_\codeunder
- \else
- \let-\realdash
- \let_\realunder
- \fi
- \codex
- }
-}
-
-\def\realdash{-}
-\def\codedash{-\discretionary{}{}{}}
-\def\codeunder{%
- % this is all so @math{@code{var_name}+1} can work. In math mode, _
- % is "active" (mathcode"8000) and \normalunderscore (or \char95, etc.)
- % will therefore expand the active definition of _, which is us
- % (inside @code that is), therefore an endless loop.
- \ifusingtt{\ifmmode
- \mathchar"075F % class 0=ordinary, family 7=ttfam, pos 0x5F=_.
- \else\normalunderscore \fi
- \discretionary{}{}{}}%
- {\_}%
-}
-\def\codex #1{\tclose{#1}\endgroup}
-
-% An additional complication: the above will allow breaks after, e.g.,
-% each of the four underscores in __typeof__. This is undesirable in
-% some manuals, especially if they don't have long identifiers in
-% general. @allowcodebreaks provides a way to control this.
-%
-\newif\ifallowcodebreaks \allowcodebreakstrue
-
-\def\keywordtrue{true}
-\def\keywordfalse{false}
-
-\parseargdef\allowcodebreaks{%
- \def\txiarg{#1}%
- \ifx\txiarg\keywordtrue
- \allowcodebreakstrue
- \else\ifx\txiarg\keywordfalse
- \allowcodebreaksfalse
- \else
- \errhelp = \EMsimple
- \errmessage{Unknown @allowcodebreaks option `\txiarg'}%
- \fi\fi
-}
-
-% @kbd is like @code, except that if the argument is just one @key command,
-% then @kbd has no effect.
-
-% @kbdinputstyle -- arg is `distinct' (@kbd uses slanted tty font always),
-% `example' (@kbd uses ttsl only inside of @example and friends),
-% or `code' (@kbd uses normal tty font always).
-\parseargdef\kbdinputstyle{%
- \def\txiarg{#1}%
- \ifx\txiarg\worddistinct
- \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl}%
- \else\ifx\txiarg\wordexample
- \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\tt}%
- \else\ifx\txiarg\wordcode
- \gdef\kbdexamplefont{\tt}\gdef\kbdfont{\tt}%
- \else
- \errhelp = \EMsimple
- \errmessage{Unknown @kbdinputstyle option `\txiarg'}%
- \fi\fi\fi
-}
-\def\worddistinct{distinct}
-\def\wordexample{example}
-\def\wordcode{code}
-
-% Default is `distinct.'
-\kbdinputstyle distinct
-
-\def\xkey{\key}
-\def\kbdfoo#1#2#3\par{\def\one{#1}\def\three{#3}\def\threex{??}%
-\ifx\one\xkey\ifx\threex\three \key{#2}%
-\else{\tclose{\kbdfont\look}}\fi
-\else{\tclose{\kbdfont\look}}\fi}
-
-% For @indicateurl, @env, @command quotes seem unnecessary, so use \code.
-\let\indicateurl=\code
-\let\env=\code
-\let\command=\code
-
-% @clicksequence{File @click{} Open ...}
-\def\clicksequence#1{\begingroup #1\endgroup}
-
-% @clickstyle @arrow (by default)
-\parseargdef\clickstyle{\def\click{#1}}
-\def\click{\arrow}
-
-% @uref (abbreviation for `urlref') takes an optional (comma-separated)
-% second argument specifying the text to display and an optional third
-% arg as text to display instead of (rather than in addition to) the url
-% itself. First (mandatory) arg is the url. Perhaps eventually put in
-% a hypertex \special here.
-%
-\def\uref#1{\douref #1,,,\finish}
-\def\douref#1,#2,#3,#4\finish{\begingroup
- \unsepspaces
- \pdfurl{#1}%
- \setbox0 = \hbox{\ignorespaces #3}%
- \ifdim\wd0 > 0pt
- \unhbox0 % third arg given, show only that
- \else
- \setbox0 = \hbox{\ignorespaces #2}%
- \ifdim\wd0 > 0pt
- \ifpdf
- \unhbox0 % PDF: 2nd arg given, show only it
- \else
- \unhbox0\ (\code{#1})% DVI: 2nd arg given, show both it and url
- \fi
- \else
- \code{#1}% only url given, so show it
- \fi
- \fi
- \endlink
-\endgroup}
-
-% @url synonym for @uref, since that's how everyone uses it.
-%
-\let\url=\uref
-
-% rms does not like angle brackets --karl, 17may97.
-% So now @email is just like @uref, unless we are pdf.
-%
-%\def\email#1{\angleleft{\tt #1}\angleright}
-\ifpdf
- \def\email#1{\doemail#1,,\finish}
- \def\doemail#1,#2,#3\finish{\begingroup
- \unsepspaces
- \pdfurl{mailto:#1}%
- \setbox0 = \hbox{\ignorespaces #2}%
- \ifdim\wd0>0pt\unhbox0\else\code{#1}\fi
- \endlink
- \endgroup}
-\else
- \let\email=\uref
-\fi
-
-% Check if we are currently using a typewriter font. Since all the
-% Computer Modern typewriter fonts have zero interword stretch (and
-% shrink), and it is reasonable to expect all typewriter fonts to have
-% this property, we can check that font parameter.
-%
-\def\ifmonospace{\ifdim\fontdimen3\font=0pt }
-
-% Typeset a dimension, e.g., `in' or `pt'. The only reason for the
-% argument is to make the input look right: @dmn{pt} instead of @dmn{}pt.
-%
-\def\dmn#1{\thinspace #1}
-
-\def\kbd#1{\def\look{#1}\expandafter\kbdfoo\look??\par}
-
-% @l was never documented to mean ``switch to the Lisp font'',
-% and it is not used as such in any manual I can find. We need it for
-% Polish suppressed-l. --karl, 22sep96.
-%\def\l#1{{\li #1}\null}
-
-% Explicit font changes: @r, @sc, undocumented @ii.
-\def\r#1{{\rm #1}} % roman font
-\def\sc#1{{\smallcaps#1}} % smallcaps font
-\def\ii#1{{\it #1}} % italic font
-
-% @acronym for "FBI", "NATO", and the like.
-% We print this one point size smaller, since it's intended for
-% all-uppercase.
-%
-\def\acronym#1{\doacronym #1,,\finish}
-\def\doacronym#1,#2,#3\finish{%
- {\selectfonts\lsize #1}%
- \def\temp{#2}%
- \ifx\temp\empty \else
- \space ({\unsepspaces \ignorespaces \temp \unskip})%
- \fi
-}
-
-% @abbr for "Comput. J." and the like.
-% No font change, but don't do end-of-sentence spacing.
-%
-\def\abbr#1{\doabbr #1,,\finish}
-\def\doabbr#1,#2,#3\finish{%
- {\plainfrenchspacing #1}%
- \def\temp{#2}%
- \ifx\temp\empty \else
- \space ({\unsepspaces \ignorespaces \temp \unskip})%
- \fi
-}
-
-% @pounds{} is a sterling sign, which Knuth put in the CM italic font.
-%
-\def\pounds{{\it\$}}
-
-% @euro{} comes from a separate font, depending on the current style.
-% We use the free feym* fonts from the eurosym package by Henrik
-% Theiling, which support regular, slanted, bold and bold slanted (and
-% "outlined" (blackboard board, sort of) versions, which we don't need).
-% It is available from http://www.ctan.org/tex-archive/fonts/eurosym.
-%
-% Although only regular is the truly official Euro symbol, we ignore
-% that. The Euro is designed to be slightly taller than the regular
-% font height.
-%
-% feymr - regular
-% feymo - slanted
-% feybr - bold
-% feybo - bold slanted
-%
-% There is no good (free) typewriter version, to my knowledge.
-% A feymr10 euro is ~7.3pt wide, while a normal cmtt10 char is ~5.25pt wide.
-% Hmm.
-%
-% Also doesn't work in math. Do we need to do math with euro symbols?
-% Hope not.
-%
-%
-\def\euro{{\eurofont e}}
-\def\eurofont{%
- % We set the font at each command, rather than predefining it in
- % \textfonts and the other font-switching commands, so that
- % installations which never need the symbol don't have to have the
- % font installed.
- %
- % There is only one designed size (nominal 10pt), so we always scale
- % that to the current nominal size.
- %
- % By the way, simply using "at 1em" works for cmr10 and the like, but
- % does not work for cmbx10 and other extended/shrunken fonts.
- %
- \def\eurosize{\csname\curfontsize nominalsize\endcsname}%
- %
- \ifx\curfontstyle\bfstylename
- % bold:
- \font\thiseurofont = \ifusingit{feybo10}{feybr10} at \eurosize
- \else
- % regular:
- \font\thiseurofont = \ifusingit{feymo10}{feymr10} at \eurosize
- \fi
- \thiseurofont
-}
-
-% Hacks for glyphs from the EC fonts similar to \euro. We don't
-% use \let for the aliases, because sometimes we redefine the original
-% macro, and the alias should reflect the redefinition.
-\def\guillemetleft{{\ecfont \char"13}}
-\def\guillemotleft{\guillemetleft}
-\def\guillemetright{{\ecfont \char"14}}
-\def\guillemotright{\guillemetright}
-\def\guilsinglleft{{\ecfont \char"0E}}
-\def\guilsinglright{{\ecfont \char"0F}}
-\def\quotedblbase{{\ecfont \char"12}}
-\def\quotesinglbase{{\ecfont \char"0D}}
-%
-\def\ecfont{%
- % We can't distinguish serif/sanserif and italic/slanted, but this
- % is used for crude hacks anyway (like adding French and German
- % quotes to documents typeset with CM, where we lose kerning), so
- % hopefully nobody will notice/care.
- \edef\ecsize{\csname\curfontsize ecsize\endcsname}%
- \edef\nominalsize{\csname\curfontsize nominalsize\endcsname}%
- \ifx\curfontstyle\bfstylename
- % bold:
- \font\thisecfont = ecb\ifusingit{i}{x}\ecsize \space at \nominalsize
- \else
- % regular:
- \font\thisecfont = ec\ifusingit{ti}{rm}\ecsize \space at \nominalsize
- \fi
- \thisecfont
-}
-
-% @registeredsymbol - R in a circle. The font for the R should really
-% be smaller yet, but lllsize is the best we can do for now.
-% Adapted from the plain.tex definition of \copyright.
-%
-\def\registeredsymbol{%
- $^{{\ooalign{\hfil\raise.07ex\hbox{\selectfonts\lllsize R}%
- \hfil\crcr\Orb}}%
- }$%
-}
-
-% @textdegree - the normal degrees sign.
-%
-\def\textdegree{$^\circ$}
-
-% Laurent Siebenmann reports \Orb undefined with:
-% Textures 1.7.7 (preloaded format=plain 93.10.14) (68K) 16 APR 2004 02:38
-% so we'll define it if necessary.
-%
-\ifx\Orb\undefined
-\def\Orb{\mathhexbox20D}
-\fi
-
-% Quotes.
-\chardef\quotedblleft="5C
-\chardef\quotedblright=`\"
-\chardef\quoteleft=`\`
-\chardef\quoteright=`\'
-
-
-\message{page headings,}
-
-\newskip\titlepagetopglue \titlepagetopglue = 1.5in
-\newskip\titlepagebottomglue \titlepagebottomglue = 2pc
-
-% First the title page. Must do @settitle before @titlepage.
-\newif\ifseenauthor
-\newif\iffinishedtitlepage
-
-% Do an implicit @contents or @shortcontents after @end titlepage if the
-% user says @setcontentsaftertitlepage or @setshortcontentsaftertitlepage.
-%
-\newif\ifsetcontentsaftertitlepage
- \let\setcontentsaftertitlepage = \setcontentsaftertitlepagetrue
-\newif\ifsetshortcontentsaftertitlepage
- \let\setshortcontentsaftertitlepage = \setshortcontentsaftertitlepagetrue
-
-\parseargdef\shorttitlepage{\begingroup\hbox{}\vskip 1.5in \chaprm \centerline{#1}%
- \endgroup\page\hbox{}\page}
-
-\envdef\titlepage{%
- % Open one extra group, as we want to close it in the middle of \Etitlepage.
- \begingroup
- \parindent=0pt \textfonts
- % Leave some space at the very top of the page.
- \vglue\titlepagetopglue
- % No rule at page bottom unless we print one at the top with @title.
- \finishedtitlepagetrue
- %
- % Most title ``pages'' are actually two pages long, with space
- % at the top of the second. We don't want the ragged left on the second.
- \let\oldpage = \page
- \def\page{%
- \iffinishedtitlepage\else
- \finishtitlepage
- \fi
- \let\page = \oldpage
- \page
- \null
- }%
-}
-
-\def\Etitlepage{%
- \iffinishedtitlepage\else
- \finishtitlepage
- \fi
- % It is important to do the page break before ending the group,
- % because the headline and footline are only empty inside the group.
- % If we use the new definition of \page, we always get a blank page
- % after the title page, which we certainly don't want.
- \oldpage
- \endgroup
- %
- % Need this before the \...aftertitlepage checks so that if they are
- % in effect the toc pages will come out with page numbers.
- \HEADINGSon
- %
- % If they want short, they certainly want long too.
- \ifsetshortcontentsaftertitlepage
- \shortcontents
- \contents
- \global\let\shortcontents = \relax
- \global\let\contents = \relax
- \fi
- %
- \ifsetcontentsaftertitlepage
- \contents
- \global\let\contents = \relax
- \global\let\shortcontents = \relax
- \fi
-}
-
-%%% MARK CFENGINE CHANGES
-
-\def\finishtitlepage{%
-% \vskip4pt \hrule height 1pt width \hsize
- \vskip\titlepagebottomglue
- \finishedtitlepagetrue
-}
-
-%%% Macros to be used within @titlepage:
-
-\let\subtitlerm=\tenrm
-\def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines}
-
-\def\authorfont{\authorrm \normalbaselineskip = 16pt \normalbaselines
- \let\tt=\authortt}
-
-\parseargdef\title{%
- \checkenv\titlepage
- \centerline{\titlefonts\rm #1} % Mark change from \leftline
- % print a rule at the page bottom also.
- \finishedtitlepagefalse
-% \vskip4pt \hrule height 1pt width \hsize \vskip4pt
-\vskip4pt %mark
-}
-
-\parseargdef\subtitle{%
- \checkenv\titlepage
- {\subtitlefont \centerline{#1}}% Mark change from \rightline
-}
-
-% @author should come last, but may come many times.
-% It can also be used inside @quotation.
-%
-\parseargdef\author{%
- \def\temp{\quotation}%
- \ifx\thisenv\temp
- \def\quotationauthor{#1}% printed in \Equotation.
- \else
- \checkenv\titlepage
- \ifseenauthor\else \vskip 0pt plus 1filll \seenauthortrue \fi
- {\authorfont \centerline{#1}}%mark from \leftline
- \fi
-}
-
-
-%%% Set up page headings and footings.
-
-\let\thispage=\folio
-
-\newtoks\evenheadline % headline on even pages
-\newtoks\oddheadline % headline on odd pages
-\newtoks\evenfootline % footline on even pages
-\newtoks\oddfootline % footline on odd pages
-
-% Now make TeX use those variables
-\headline={{\textfonts\rm \ifodd\pageno \the\oddheadline
- \else \the\evenheadline \fi}}
-\footline={{\textfonts\rm \ifodd\pageno \the\oddfootline
- \else \the\evenfootline \fi}\HEADINGShook}
-\let\HEADINGShook=\relax
-
-% Commands to set those variables.
-% For example, this is what @headings on does
-% @evenheading @thistitle|@thispage|@thischapter
-% @oddheading @thischapter|@thispage|@thistitle
-% @evenfooting @thisfile||
-% @oddfooting ||@thisfile
-
-
-\def\evenheading{\parsearg\evenheadingxxx}
-\def\evenheadingxxx #1{\evenheadingyyy #1\|\|\|\|\finish}
-\def\evenheadingyyy #1\|#2\|#3\|#4\finish{%
-\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}}
-
-\def\oddheading{\parsearg\oddheadingxxx}
-\def\oddheadingxxx #1{\oddheadingyyy #1\|\|\|\|\finish}
-\def\oddheadingyyy #1\|#2\|#3\|#4\finish{%
-\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}}
-
-\parseargdef\everyheading{\oddheadingxxx{#1}\evenheadingxxx{#1}}%
-
-\def\evenfooting{\parsearg\evenfootingxxx}
-\def\evenfootingxxx #1{\evenfootingyyy #1\|\|\|\|\finish}
-\def\evenfootingyyy #1\|#2\|#3\|#4\finish{%
-\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}}
-
-\def\oddfooting{\parsearg\oddfootingxxx}
-\def\oddfootingxxx #1{\oddfootingyyy #1\|\|\|\|\finish}
-\def\oddfootingyyy #1\|#2\|#3\|#4\finish{%
- \global\oddfootline = {\rlap{\centerline{#2}}\line{#1\hfil#3}}%
- %
- % Leave some space for the footline. Hopefully ok to assume
- % @evenfooting will not be used by itself.
- \global\advance\pageheight by -12pt
- \global\advance\vsize by -12pt
-}
-
-\parseargdef\everyfooting{\oddfootingxxx{#1}\evenfootingxxx{#1}}
-
-% @evenheadingmarks top \thischapter <- chapter at the top of a page
-% @evenheadingmarks bottom \thischapter <- chapter at the bottom of a page
-%
-% The same set of arguments for:
-%
-% @oddheadingmarks
-% @evenfootingmarks
-% @oddfootingmarks
-% @everyheadingmarks
-% @everyfootingmarks
-
-\def\evenheadingmarks{\headingmarks{even}{heading}}
-\def\oddheadingmarks{\headingmarks{odd}{heading}}
-\def\evenfootingmarks{\headingmarks{even}{footing}}
-\def\oddfootingmarks{\headingmarks{odd}{footing}}
-\def\everyheadingmarks#1 {\headingmarks{even}{heading}{#1}
- \headingmarks{odd}{heading}{#1} }
-\def\everyfootingmarks#1 {\headingmarks{even}{footing}{#1}
- \headingmarks{odd}{footing}{#1} }
-% #1 = even/odd, #2 = heading/footing, #3 = top/bottom.
-\def\headingmarks#1#2#3 {%
- \expandafter\let\expandafter\temp \csname get#3headingmarks\endcsname
- \global\expandafter\let\csname get#1#2marks\endcsname \temp
-}
-
-\everyheadingmarks bottom
-\everyfootingmarks bottom
-
-% @headings double turns headings on for double-sided printing.
-% @headings single turns headings on for single-sided printing.
-% @headings off turns them off.
-% @headings on same as @headings double, retained for compatibility.
-% @headings after turns on double-sided headings after this page.
-% @headings doubleafter turns on double-sided headings after this page.
-% @headings singleafter turns on single-sided headings after this page.
-% By default, they are off at the start of a document,
-% and turned `on' after @end titlepage.
-
-\def\headings #1 {\csname HEADINGS#1\endcsname}
-
-\def\HEADINGSoff{%
-\global\evenheadline={\hfil} \global\evenfootline={\hfil}
-\global\oddheadline={\hfil} \global\oddfootline={\hfil}}
-\HEADINGSoff
-% When we turn headings on, set the page number to 1.
-% For double-sided printing, put current file name in lower left corner,
-% chapter name on inside top of right hand pages, document
-% title on inside top of left hand pages, and page numbers on outside top
-% edge of all pages.
-\def\HEADINGSdouble{%
-\global\pageno=1
-\global\evenfootline={\hfil}
-\global\oddfootline={\hfil}
-\global\evenheadline={\line{\folio\hfil\thistitle}}
-\global\oddheadline={\line{\thischapter\hfil\folio}}
-\global\let\contentsalignmacro = \chapoddpage
-}
-\let\contentsalignmacro = \chappager
-
-% For single-sided printing, chapter title goes across top left of page,
-% page number on top right.
-\def\HEADINGSsingle{%
-\global\pageno=1
-\global\evenfootline={\hfil}
-\global\oddfootline={\hfil}
-\global\evenheadline={\line{\thischapter\hfil\folio}}
-\global\oddheadline={\line{\thischapter\hfil\folio}}
-\global\let\contentsalignmacro = \chappager
-}
-\def\HEADINGSon{\HEADINGSdouble}
-
-\def\HEADINGSafter{\let\HEADINGShook=\HEADINGSdoublex}
-\let\HEADINGSdoubleafter=\HEADINGSafter
-\def\HEADINGSdoublex{%
-\global\evenfootline={\hfil}
-\global\oddfootline={\hfil}
-\global\evenheadline={\line{\folio\hfil\thistitle}}
-\global\oddheadline={\line{\thischapter\hfil\folio}}
-\global\let\contentsalignmacro = \chapoddpage
-}
-
-\def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsinglex}
-\def\HEADINGSsinglex{%
-\global\evenfootline={\hfil}
-\global\oddfootline={\hfil}
-\global\evenheadline={\line{\thischapter\hfil\folio}}
-\global\oddheadline={\line{\thischapter\hfil\folio}}
-\global\let\contentsalignmacro = \chappager
-}
-
-% Subroutines used in generating headings
-% This produces Day Month Year style of output.
-% Only define if not already defined, in case a txi-??.tex file has set
-% up a different format (e.g., txi-cs.tex does this).
-\ifx\today\undefined
-\def\today{%
- \number\day\space
- \ifcase\month
- \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr
- \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug
- \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec
- \fi
- \space\number\year}
-\fi
-
-% @settitle line... specifies the title of the document, for headings.
-% It generates no output of its own.
-\def\thistitle{\putwordNoTitle}
-\def\settitle{\parsearg{\gdef\thistitle}}
-
-
-\message{tables,}
-% Tables -- @table, @ftable, @vtable, @item(x).
-
-% default indentation of table text
-\newdimen\tableindent \tableindent=.8in
-% default indentation of @itemize and @enumerate text
-\newdimen\itemindent \itemindent=.3in
-% margin between end of table item and start of table text.
-\newdimen\itemmargin \itemmargin=.1in
-
-% used internally for \itemindent minus \itemmargin
-\newdimen\itemmax
-
-% Note @table, @ftable, and @vtable define @item, @itemx, etc., with
-% these defs.
-% They also define \itemindex
-% to index the item name in whatever manner is desired (perhaps none).
-
-\newif\ifitemxneedsnegativevskip
-
-\def\itemxpar{\par\ifitemxneedsnegativevskip\nobreak\vskip-\parskip\nobreak\fi}
-
-\def\internalBitem{\smallbreak \parsearg\itemzzz}
-\def\internalBitemx{\itemxpar \parsearg\itemzzz}
-
-\def\itemzzz #1{\begingroup %
- \advance\hsize by -\rightskip
- \advance\hsize by -\tableindent
- \setbox0=\hbox{\itemindicate{#1}}%
- \itemindex{#1}%
- \nobreak % This prevents a break before @itemx.
- %
- % If the item text does not fit in the space we have, put it on a line
- % by itself, and do not allow a page break either before or after that
- % line. We do not start a paragraph here because then if the next
- % command is, e.g., @kindex, the whatsit would get put into the
- % horizontal list on a line by itself, resulting in extra blank space.
- \ifdim \wd0>\itemmax
- %
- % Make this a paragraph so we get the \parskip glue and wrapping,
- % but leave it ragged-right.
- \begingroup
- \advance\leftskip by-\tableindent
- \advance\hsize by\tableindent
- \advance\rightskip by0pt plus1fil
- \leavevmode\unhbox0\par
- \endgroup
- %
- % We're going to be starting a paragraph, but we don't want the
- % \parskip glue -- logically it's part of the @item we just started.
- \nobreak \vskip-\parskip
- %
- % Stop a page break at the \parskip glue coming up. However, if
- % what follows is an environment such as @example, there will be no
- % \parskip glue; then the negative vskip we just inserted would
- % cause the example and the item to crash together. So we use this
- % bizarre value of 10001 as a signal to \aboveenvbreak to insert
- % \parskip glue after all. Section titles are handled this way also.
- %
- \penalty 10001
- \endgroup
- \itemxneedsnegativevskipfalse
- \else
- % The item text fits into the space. Start a paragraph, so that the
- % following text (if any) will end up on the same line.
- \noindent
- % Do this with kerns and \unhbox so that if there is a footnote in
- % the item text, it can migrate to the main vertical list and
- % eventually be printed.
- \nobreak\kern-\tableindent
- \dimen0 = \itemmax \advance\dimen0 by \itemmargin \advance\dimen0 by -\wd0
- \unhbox0
- \nobreak\kern\dimen0
- \endgroup
- \itemxneedsnegativevskiptrue
- \fi
-}
-
-\def\item{\errmessage{@item while not in a list environment}}
-\def\itemx{\errmessage{@itemx while not in a list environment}}
-
-% @table, @ftable, @vtable.
-\envdef\table{%
- \let\itemindex\gobble
- \tablecheck{table}%
-}
-\envdef\ftable{%
- \def\itemindex ##1{\doind {fn}{\code{##1}}}%
- \tablecheck{ftable}%
-}
-\envdef\vtable{%
- \def\itemindex ##1{\doind {vr}{\code{##1}}}%
- \tablecheck{vtable}%
-}
-\def\tablecheck#1{%
- \ifnum \the\catcode`\^^M=\active
- \endgroup
- \errmessage{This command won't work in this context; perhaps the problem is
- that we are \inenvironment\thisenv}%
- \def\next{\doignore{#1}}%
- \else
- \let\next\tablex
- \fi
- \next
-}
-\def\tablex#1{%
- \def\itemindicate{#1}%
- \parsearg\tabley
-}
-\def\tabley#1{%
- {%
- \makevalueexpandable
- \edef\temp{\noexpand\tablez #1\space\space\space}%
- \expandafter
- }\temp \endtablez
-}
-\def\tablez #1 #2 #3 #4\endtablez{%
- \aboveenvbreak
- \ifnum 0#1>0 \advance \leftskip by #1\mil \fi
- \ifnum 0#2>0 \tableindent=#2\mil \fi
- \ifnum 0#3>0 \advance \rightskip by #3\mil \fi
- \itemmax=\tableindent
- \advance \itemmax by -\itemmargin
- \advance \leftskip by \tableindent
- \exdentamount=\tableindent
- \parindent = 0pt
- \parskip = \smallskipamount
- \ifdim \parskip=0pt \parskip=2pt \fi
- \let\item = \internalBitem
- \let\itemx = \internalBitemx
-}
-\def\Etable{\endgraf\afterenvbreak}
-\let\Eftable\Etable
-\let\Evtable\Etable
-\let\Eitemize\Etable
-\let\Eenumerate\Etable
-
-% This is the counter used by @enumerate, which is really @itemize
-
-\newcount \itemno
-
-\envdef\itemize{\parsearg\doitemize}
-
-\def\doitemize#1{%
- \aboveenvbreak
- \itemmax=\itemindent
- \advance\itemmax by -\itemmargin
- \advance\leftskip by \itemindent
- \exdentamount=\itemindent
- \parindent=0pt
- \parskip=\smallskipamount
- \ifdim\parskip=0pt \parskip=2pt \fi
- \def\itemcontents{#1}%
- % @itemize with no arg is equivalent to @itemize @bullet.
- \ifx\itemcontents\empty\def\itemcontents{\bullet}\fi
- \let\item=\itemizeitem
-}
-
-% Definition of @item while inside @itemize and @enumerate.
-%
-\def\itemizeitem{%
- \advance\itemno by 1 % for enumerations
- {\let\par=\endgraf \smallbreak}% reasonable place to break
- {%
- % If the document has an @itemize directly after a section title, a
- % \nobreak will be last on the list, and \sectionheading will have
- % done a \vskip-\parskip. In that case, we don't want to zero
- % parskip, or the item text will crash with the heading. On the
- % other hand, when there is normal text preceding the item (as there
- % usually is), we do want to zero parskip, or there would be too much
- % space. In that case, we won't have a \nobreak before. At least
- % that's the theory.
- \ifnum\lastpenalty<10000 \parskip=0in \fi
- \noindent
- \hbox to 0pt{\hss \itemcontents \kern\itemmargin}%
- \vadjust{\penalty 1200}}% not good to break after first line of item.
- \flushcr
-}
-
-% \splitoff TOKENS\endmark defines \first to be the first token in
-% TOKENS, and \rest to be the remainder.
-%
-\def\splitoff#1#2\endmark{\def\first{#1}\def\rest{#2}}%
-
-% Allow an optional argument of an uppercase letter, lowercase letter,
-% or number, to specify the first label in the enumerated list. No
-% argument is the same as `1'.
-%
-\envparseargdef\enumerate{\enumeratey #1 \endenumeratey}
-\def\enumeratey #1 #2\endenumeratey{%
- % If we were given no argument, pretend we were given `1'.
- \def\thearg{#1}%
- \ifx\thearg\empty \def\thearg{1}\fi
- %
- % Detect if the argument is a single token. If so, it might be a
- % letter. Otherwise, the only valid thing it can be is a number.
- % (We will always have one token, because of the test we just made.
- % This is a good thing, since \splitoff doesn't work given nothing at
- % all -- the first parameter is undelimited.)
- \expandafter\splitoff\thearg\endmark
- \ifx\rest\empty
- % Only one token in the argument. It could still be anything.
- % A ``lowercase letter'' is one whose \lccode is nonzero.
- % An ``uppercase letter'' is one whose \lccode is both nonzero, and
- % not equal to itself.
- % Otherwise, we assume it's a number.
- %
- % We need the \relax at the end of the \ifnum lines to stop TeX from
- % continuing to look for a .
- %
- \ifnum\lccode\expandafter`\thearg=0\relax
- \numericenumerate % a number (we hope)
- \else
- % It's a letter.
- \ifnum\lccode\expandafter`\thearg=\expandafter`\thearg\relax
- \lowercaseenumerate % lowercase letter
- \else
- \uppercaseenumerate % uppercase letter
- \fi
- \fi
- \else
- % Multiple tokens in the argument. We hope it's a number.
- \numericenumerate
- \fi
-}
-
-% An @enumerate whose labels are integers. The starting integer is
-% given in \thearg.
-%
-\def\numericenumerate{%
- \itemno = \thearg
- \startenumeration{\the\itemno}%
-}
-
-% The starting (lowercase) letter is in \thearg.
-\def\lowercaseenumerate{%
- \itemno = \expandafter`\thearg
- \startenumeration{%
- % Be sure we're not beyond the end of the alphabet.
- \ifnum\itemno=0
- \errmessage{No more lowercase letters in @enumerate; get a bigger
- alphabet}%
- \fi
- \char\lccode\itemno
- }%
-}
-
-% The starting (uppercase) letter is in \thearg.
-\def\uppercaseenumerate{%
- \itemno = \expandafter`\thearg
- \startenumeration{%
- % Be sure we're not beyond the end of the alphabet.
- \ifnum\itemno=0
- \errmessage{No more uppercase letters in @enumerate; get a bigger
- alphabet}
- \fi
- \char\uccode\itemno
- }%
-}
-
-% Call \doitemize, adding a period to the first argument and supplying the
-% common last two arguments. Also subtract one from the initial value in
-% \itemno, since @item increments \itemno.
-%
-\def\startenumeration#1{%
- \advance\itemno by -1
- \doitemize{#1.}\flushcr
-}
-
-% @alphaenumerate and @capsenumerate are abbreviations for giving an arg
-% to @enumerate.
-%
-\def\alphaenumerate{\enumerate{a}}
-\def\capsenumerate{\enumerate{A}}
-\def\Ealphaenumerate{\Eenumerate}
-\def\Ecapsenumerate{\Eenumerate}
-
-
-% @multitable macros
-% Amy Hendrickson, 8/18/94, 3/6/96
-%
-% @multitable ... @end multitable will make as many columns as desired.
-% Contents of each column will wrap at width given in preamble. Width
-% can be specified either with sample text given in a template line,
-% or in percent of \hsize, the current width of text on page.
-
-% Table can continue over pages but will only break between lines.
-
-% To make preamble:
-%
-% Either define widths of columns in terms of percent of \hsize:
-% @multitable @columnfractions .25 .3 .45
-% @item ...
-%
-% Numbers following @columnfractions are the percent of the total
-% current hsize to be used for each column. You may use as many
-% columns as desired.
-
-
-% Or use a template:
-% @multitable {Column 1 template} {Column 2 template} {Column 3 template}
-% @item ...
-% using the widest term desired in each column.
-
-% Each new table line starts with @item, each subsequent new column
-% starts with @tab. Empty columns may be produced by supplying @tab's
-% with nothing between them for as many times as empty columns are needed,
-% ie, @tab@tab@tab will produce two empty columns.
-
-% @item, @tab do not need to be on their own lines, but it will not hurt
-% if they are.
-
-% Sample multitable:
-
-% @multitable {Column 1 template} {Column 2 template} {Column 3 template}
-% @item first col stuff @tab second col stuff @tab third col
-% @item
-% first col stuff
-% @tab
-% second col stuff
-% @tab
-% third col
-% @item first col stuff @tab second col stuff
-% @tab Many paragraphs of text may be used in any column.
-%
-% They will wrap at the width determined by the template.
-% @item@tab@tab This will be in third column.
-% @end multitable
-
-% Default dimensions may be reset by user.
-% @multitableparskip is vertical space between paragraphs in table.
-% @multitableparindent is paragraph indent in table.
-% @multitablecolmargin is horizontal space to be left between columns.
-% @multitablelinespace is space to leave between table items, baseline
-% to baseline.
-% 0pt means it depends on current normal line spacing.
-%
-\newskip\multitableparskip
-\newskip\multitableparindent
-\newdimen\multitablecolspace
-\newskip\multitablelinespace
-\multitableparskip=0pt
-\multitableparindent=6pt
-\multitablecolspace=12pt
-\multitablelinespace=0pt
-
-% Macros used to set up halign preamble:
-%
-\let\endsetuptable\relax
-\def\xendsetuptable{\endsetuptable}
-\let\columnfractions\relax
-\def\xcolumnfractions{\columnfractions}
-\newif\ifsetpercent
-
-% #1 is the @columnfraction, usually a decimal number like .5, but might
-% be just 1. We just use it, whatever it is.
-%
-\def\pickupwholefraction#1 {%
- \global\advance\colcount by 1
- \expandafter\xdef\csname col\the\colcount\endcsname{#1\hsize}%
- \setuptable
-}
-
-\newcount\colcount
-\def\setuptable#1{%
- \def\firstarg{#1}%
- \ifx\firstarg\xendsetuptable
- \let\go = \relax
- \else
- \ifx\firstarg\xcolumnfractions
- \global\setpercenttrue
- \else
- \ifsetpercent
- \let\go\pickupwholefraction
- \else
- \global\advance\colcount by 1
- \setbox0=\hbox{#1\unskip\space}% Add a normal word space as a
- % separator; typically that is always in the input, anyway.
- \expandafter\xdef\csname col\the\colcount\endcsname{\the\wd0}%
- \fi
- \fi
- \ifx\go\pickupwholefraction
- % Put the argument back for the \pickupwholefraction call, so
- % we'll always have a period there to be parsed.
- \def\go{\pickupwholefraction#1}%
- \else
- \let\go = \setuptable
- \fi%
- \fi
- \go
-}
-
-% multitable-only commands.
-%
-% @headitem starts a heading row, which we typeset in bold.
-% Assignments have to be global since we are inside the implicit group
-% of an alignment entry. Note that \everycr resets \everytab.
-\def\headitem{\checkenv\multitable \crcr \global\everytab={\bf}\the\everytab}%
-%
-% A \tab used to include \hskip1sp. But then the space in a template
-% line is not enough. That is bad. So let's go back to just `&' until
-% we encounter the problem it was intended to solve again.
-% --karl, nathan@acm.org, 20apr99.
-\def\tab{\checkenv\multitable &\the\everytab}%
-
-% @multitable ... @end multitable definitions:
-%
-\newtoks\everytab % insert after every tab.
-%
-\envdef\multitable{%
- \vskip\parskip
- \startsavinginserts
- %
- % @item within a multitable starts a normal row.
- % We use \def instead of \let so that if one of the multitable entries
- % contains an @itemize, we don't choke on the \item (seen as \crcr aka
- % \endtemplate) expanding \doitemize.
- \def\item{\crcr}%
- %
- \tolerance=9500
- \hbadness=9500
- \setmultitablespacing
- \parskip=\multitableparskip
- \parindent=\multitableparindent
- \overfullrule=0pt
- \global\colcount=0
- %
- \everycr = {%
- \noalign{%
- \global\everytab={}%
- \global\colcount=0 % Reset the column counter.
- % Check for saved footnotes, etc.
- \checkinserts
- % Keeps underfull box messages off when table breaks over pages.
- %\filbreak
- % Maybe so, but it also creates really weird page breaks when the
- % table breaks over pages. Wouldn't \vfil be better? Wait until the
- % problem manifests itself, so it can be fixed for real --karl.
- }%
- }%
- %
- \parsearg\domultitable
-}
-\def\domultitable#1{%
- % To parse everything between @multitable and @item:
- \setuptable#1 \endsetuptable
- %
- % This preamble sets up a generic column definition, which will
- % be used as many times as user calls for columns.
- % \vtop will set a single line and will also let text wrap and
- % continue for many paragraphs if desired.
- \halign\bgroup &%
- \global\advance\colcount by 1
- \multistrut
- \vtop{%
- % Use the current \colcount to find the correct column width:
- \hsize=\expandafter\csname col\the\colcount\endcsname
- %
- % In order to keep entries from bumping into each other
- % we will add a \leftskip of \multitablecolspace to all columns after
- % the first one.
- %
- % If a template has been used, we will add \multitablecolspace
- % to the width of each template entry.
- %
- % If the user has set preamble in terms of percent of \hsize we will
- % use that dimension as the width of the column, and the \leftskip
- % will keep entries from bumping into each other. Table will start at
- % left margin and final column will justify at right margin.
- %
- % Make sure we don't inherit \rightskip from the outer environment.
- \rightskip=0pt
- \ifnum\colcount=1
- % The first column will be indented with the surrounding text.
- \advance\hsize by\leftskip
- \else
- \ifsetpercent \else
- % If user has not set preamble in terms of percent of \hsize
- % we will advance \hsize by \multitablecolspace.
- \advance\hsize by \multitablecolspace
- \fi
- % In either case we will make \leftskip=\multitablecolspace:
- \leftskip=\multitablecolspace
- \fi
- % Ignoring space at the beginning and end avoids an occasional spurious
- % blank line, when TeX decides to break the line at the space before the
- % box from the multistrut, so the strut ends up on a line by itself.
- % For example:
- % @multitable @columnfractions .11 .89
- % @item @code{#}
- % @tab Legal holiday which is valid in major parts of the whole country.
- % Is automatically provided with highlighting sequences respectively
- % marking characters.
- \noindent\ignorespaces##\unskip\multistrut
- }\cr
-}
-\def\Emultitable{%
- \crcr
- \egroup % end the \halign
- \global\setpercentfalse
-}
-
-\def\setmultitablespacing{%
- \def\multistrut{\strut}% just use the standard line spacing
- %
- % Compute \multitablelinespace (if not defined by user) for use in
- % \multitableparskip calculation. We used define \multistrut based on
- % this, but (ironically) that caused the spacing to be off.
- % See bug-texinfo report from Werner Lemberg, 31 Oct 2004 12:52:20 +0100.
-\ifdim\multitablelinespace=0pt
-\setbox0=\vbox{X}\global\multitablelinespace=\the\baselineskip
-\global\advance\multitablelinespace by-\ht0
-\fi
-%% Test to see if parskip is larger than space between lines of
-%% table. If not, do nothing.
-%% If so, set to same dimension as multitablelinespace.
-\ifdim\multitableparskip>\multitablelinespace
-\global\multitableparskip=\multitablelinespace
-\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller
- %% than skip between lines in the table.
-\fi%
-\ifdim\multitableparskip=0pt
-\global\multitableparskip=\multitablelinespace
-\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller
- %% than skip between lines in the table.
-\fi}
-
-
-\message{conditionals,}
-
-% @iftex, @ifnotdocbook, @ifnothtml, @ifnotinfo, @ifnotplaintext,
-% @ifnotxml always succeed. They currently do nothing; we don't
-% attempt to check whether the conditionals are properly nested. But we
-% have to remember that they are conditionals, so that @end doesn't
-% attempt to close an environment group.
-%
-\def\makecond#1{%
- \expandafter\let\csname #1\endcsname = \relax
- \expandafter\let\csname iscond.#1\endcsname = 1
-}
-\makecond{iftex}
-\makecond{ifnotdocbook}
-\makecond{ifnothtml}
-\makecond{ifnotinfo}
-\makecond{ifnotplaintext}
-\makecond{ifnotxml}
-
-% Ignore @ignore, @ifhtml, @ifinfo, and the like.
-%
-\def\direntry{\doignore{direntry}}
-\def\documentdescription{\doignore{documentdescription}}
-\def\docbook{\doignore{docbook}}
-\def\html{\doignore{html}}
-\def\ifdocbook{\doignore{ifdocbook}}
-\def\ifhtml{\doignore{ifhtml}}
-\def\ifinfo{\doignore{ifinfo}}
-\def\ifnottex{\doignore{ifnottex}}
-\def\ifplaintext{\doignore{ifplaintext}}
-\def\ifxml{\doignore{ifxml}}
-\def\ignore{\doignore{ignore}}
-\def\menu{\doignore{menu}}
-\def\xml{\doignore{xml}}
-
-% Ignore text until a line `@end #1', keeping track of nested conditionals.
-%
-% A count to remember the depth of nesting.
-\newcount\doignorecount
-
-\def\doignore#1{\begingroup
- % Scan in ``verbatim'' mode:
- \obeylines
- \catcode`\@ = \other
- \catcode`\{ = \other
- \catcode`\} = \other
- %
- % Make sure that spaces turn into tokens that match what \doignoretext wants.
- \spaceisspace
- %
- % Count number of #1's that we've seen.
- \doignorecount = 0
- %
- % Swallow text until we reach the matching `@end #1'.
- \dodoignore{#1}%
-}
-
-{ \catcode`_=11 % We want to use \_STOP_ which cannot appear in texinfo source.
- \obeylines %
- %
- \gdef\dodoignore#1{%
- % #1 contains the command name as a string, e.g., `ifinfo'.
- %
- % Define a command to find the next `@end #1'.
- \long\def\doignoretext##1^^M@end #1{%
- \doignoretextyyy##1^^M@#1\_STOP_}%
- %
- % And this command to find another #1 command, at the beginning of a
- % line. (Otherwise, we would consider a line `@c @ifset', for
- % example, to count as an @ifset for nesting.)
- \long\def\doignoretextyyy##1^^M@#1##2\_STOP_{\doignoreyyy{##2}\_STOP_}%
- %
- % And now expand that command.
- \doignoretext ^^M%
- }%
-}
-
-\def\doignoreyyy#1{%
- \def\temp{#1}%
- \ifx\temp\empty % Nothing found.
- \let\next\doignoretextzzz
- \else % Found a nested condition, ...
- \advance\doignorecount by 1
- \let\next\doignoretextyyy % ..., look for another.
- % If we're here, #1 ends with ^^M\ifinfo (for example).
- \fi
- \next #1% the token \_STOP_ is present just after this macro.
-}
-
-% We have to swallow the remaining "\_STOP_".
-%
-\def\doignoretextzzz#1{%
- \ifnum\doignorecount = 0 % We have just found the outermost @end.
- \let\next\enddoignore
- \else % Still inside a nested condition.
- \advance\doignorecount by -1
- \let\next\doignoretext % Look for the next @end.
- \fi
- \next
-}
-
-% Finish off ignored text.
-{ \obeylines%
- % Ignore anything after the last `@end #1'; this matters in verbatim
- % environments, where otherwise the newline after an ignored conditional
- % would result in a blank line in the output.
- \gdef\enddoignore#1^^M{\endgroup\ignorespaces}%
-}
-
-
-% @set VAR sets the variable VAR to an empty value.
-% @set VAR REST-OF-LINE sets VAR to the value REST-OF-LINE.
-%
-% Since we want to separate VAR from REST-OF-LINE (which might be
-% empty), we can't just use \parsearg; we have to insert a space of our
-% own to delimit the rest of the line, and then take it out again if we
-% didn't need it.
-% We rely on the fact that \parsearg sets \catcode`\ =10.
-%
-\parseargdef\set{\setyyy#1 \endsetyyy}
-\def\setyyy#1 #2\endsetyyy{%
- {%
- \makevalueexpandable
- \def\temp{#2}%
- \edef\next{\gdef\makecsname{SET#1}}%
- \ifx\temp\empty
- \next{}%
- \else
- \setzzz#2\endsetzzz
- \fi
- }%
-}
-% Remove the trailing space \setxxx inserted.
-\def\setzzz#1 \endsetzzz{\next{#1}}
-
-% @clear VAR clears (i.e., unsets) the variable VAR.
-%
-\parseargdef\clear{%
- {%
- \makevalueexpandable
- \global\expandafter\let\csname SET#1\endcsname=\relax
- }%
-}
-
-% @value{foo} gets the text saved in variable foo.
-\def\value{\begingroup\makevalueexpandable\valuexxx}
-\def\valuexxx#1{\expandablevalue{#1}\endgroup}
-{
- \catcode`\- = \active \catcode`\_ = \active
- %
- \gdef\makevalueexpandable{%
- \let\value = \expandablevalue
- % We don't want these characters active, ...
- \catcode`\-=\other \catcode`\_=\other
- % ..., but we might end up with active ones in the argument if
- % we're called from @code, as @code{@value{foo-bar_}}, though.
- % So \let them to their normal equivalents.
- \let-\realdash \let_\normalunderscore
- }
-}
-
-% We have this subroutine so that we can handle at least some @value's
-% properly in indexes (we call \makevalueexpandable in \indexdummies).
-% The command has to be fully expandable (if the variable is set), since
-% the result winds up in the index file. This means that if the
-% variable's value contains other Texinfo commands, it's almost certain
-% it will fail (although perhaps we could fix that with sufficient work
-% to do a one-level expansion on the result, instead of complete).
-%
-\def\expandablevalue#1{%
- \expandafter\ifx\csname SET#1\endcsname\relax
- {[No value for ``#1'']}%
- \message{Variable `#1', used in @value, is not set.}%
- \else
- \csname SET#1\endcsname
- \fi
-}
-
-% @ifset VAR ... @end ifset reads the `...' iff VAR has been defined
-% with @set.
-%
-% To get special treatment of `@end ifset,' call \makeond and the redefine.
-%
-\makecond{ifset}
-\def\ifset{\parsearg{\doifset{\let\next=\ifsetfail}}}
-\def\doifset#1#2{%
- {%
- \makevalueexpandable
- \let\next=\empty
- \expandafter\ifx\csname SET#2\endcsname\relax
- #1% If not set, redefine \next.
- \fi
- \expandafter
- }\next
-}
-\def\ifsetfail{\doignore{ifset}}
-
-% @ifclear VAR ... @end ifclear reads the `...' iff VAR has never been
-% defined with @set, or has been undefined with @clear.
-%
-% The `\else' inside the `\doifset' parameter is a trick to reuse the
-% above code: if the variable is not set, do nothing, if it is set,
-% then redefine \next to \ifclearfail.
-%
-\makecond{ifclear}
-\def\ifclear{\parsearg{\doifset{\else \let\next=\ifclearfail}}}
-\def\ifclearfail{\doignore{ifclear}}
-
-% @dircategory CATEGORY -- specify a category of the dir file
-% which this file should belong to. Ignore this in TeX.
-\let\dircategory=\comment
-
-% @defininfoenclose.
-\let\definfoenclose=\comment
-
-
-\message{indexing,}
-% Index generation facilities
-
-% Define \newwrite to be identical to plain tex's \newwrite
-% except not \outer, so it can be used within macros and \if's.
-\edef\newwrite{\makecsname{ptexnewwrite}}
-
-% \newindex {foo} defines an index named foo.
-% It automatically defines \fooindex such that
-% \fooindex ...rest of line... puts an entry in the index foo.
-% It also defines \fooindfile to be the number of the output channel for
-% the file that accumulates this index. The file's extension is foo.
-% The name of an index should be no more than 2 characters long
-% for the sake of vms.
-%
-\def\newindex#1{%
- \iflinks
- \expandafter\newwrite \csname#1indfile\endcsname
- \openout \csname#1indfile\endcsname \jobname.#1 % Open the file
- \fi
- \expandafter\xdef\csname#1index\endcsname{% % Define @#1index
- \noexpand\doindex{#1}}
-}
-
-% @defindex foo == \newindex{foo}
-%
-\def\defindex{\parsearg\newindex}
-
-% Define @defcodeindex, like @defindex except put all entries in @code.
-%
-\def\defcodeindex{\parsearg\newcodeindex}
-%
-\def\newcodeindex#1{%
- \iflinks
- \expandafter\newwrite \csname#1indfile\endcsname
- \openout \csname#1indfile\endcsname \jobname.#1
- \fi
- \expandafter\xdef\csname#1index\endcsname{%
- \noexpand\docodeindex{#1}}%
-}
-
-
-% @synindex foo bar makes index foo feed into index bar.
-% Do this instead of @defindex foo if you don't want it as a separate index.
-%
-% @syncodeindex foo bar similar, but put all entries made for index foo
-% inside @code.
-%
-\def\synindex#1 #2 {\dosynindex\doindex{#1}{#2}}
-\def\syncodeindex#1 #2 {\dosynindex\docodeindex{#1}{#2}}
-
-% #1 is \doindex or \docodeindex, #2 the index getting redefined (foo),
-% #3 the target index (bar).
-\def\dosynindex#1#2#3{%
- % Only do \closeout if we haven't already done it, else we'll end up
- % closing the target index.
- \expandafter \ifx\csname donesynindex#2\endcsname \undefined
- % The \closeout helps reduce unnecessary open files; the limit on the
- % Acorn RISC OS is a mere 16 files.
- \expandafter\closeout\csname#2indfile\endcsname
- \expandafter\let\csname\donesynindex#2\endcsname = 1
- \fi
- % redefine \fooindfile:
- \expandafter\let\expandafter\temp\expandafter=\csname#3indfile\endcsname
- \expandafter\let\csname#2indfile\endcsname=\temp
- % redefine \fooindex:
- \expandafter\xdef\csname#2index\endcsname{\noexpand#1{#3}}%
-}
-
-% Define \doindex, the driver for all \fooindex macros.
-% Argument #1 is generated by the calling \fooindex macro,
-% and it is "foo", the name of the index.
-
-% \doindex just uses \parsearg; it calls \doind for the actual work.
-% This is because \doind is more useful to call from other macros.
-
-% There is also \dosubind {index}{topic}{subtopic}
-% which makes an entry in a two-level index such as the operation index.
-
-\def\doindex#1{\edef\indexname{#1}\parsearg\singleindexer}
-\def\singleindexer #1{\doind{\indexname}{#1}}
-
-% like the previous two, but they put @code around the argument.
-\def\docodeindex#1{\edef\indexname{#1}\parsearg\singlecodeindexer}
-\def\singlecodeindexer #1{\doind{\indexname}{\code{#1}}}
-
-% Take care of Texinfo commands that can appear in an index entry.
-% Since there are some commands we want to expand, and others we don't,
-% we have to laboriously prevent expansion for those that we don't.
-%
-\def\indexdummies{%
- \escapechar = `\\ % use backslash in output files.
- \def\@{@}% change to @@ when we switch to @ as escape char in index files.
- \def\ {\realbackslash\space }%
- %
- % Need these in case \tex is in effect and \{ is a \delimiter again.
- % But can't use \lbracecmd and \rbracecmd because texindex assumes
- % braces and backslashes are used only as delimiters.
- \let\{ = \mylbrace
- \let\} = \myrbrace
- %
- % I don't entirely understand this, but when an index entry is
- % generated from a macro call, the \endinput which \scanmacro inserts
- % causes processing to be prematurely terminated. This is,
- % apparently, because \indexsorttmp is fully expanded, and \endinput
- % is an expandable command. The redefinition below makes \endinput
- % disappear altogether for that purpose -- although logging shows that
- % processing continues to some further point. On the other hand, it
- % seems \endinput does not hurt in the printed index arg, since that
- % is still getting written without apparent harm.
- %
- % Sample source (mac-idx3.tex, reported by Graham Percival to
- % help-texinfo, 22may06):
- % @macro funindex {WORD}
- % @findex xyz
- % @end macro
- % ...
- % @funindex commtest
- %
- % The above is not enough to reproduce the bug, but it gives the flavor.
- %
- % Sample whatsit resulting:
- % .@write3{\entry{xyz}{@folio }{@code {xyz@endinput }}}
- %
- % So:
- \let\endinput = \empty
- %
- % Do the redefinitions.
- \commondummies
-}
-
-% For the aux and toc files, @ is the escape character. So we want to
-% redefine everything using @ as the escape character (instead of
-% \realbackslash, still used for index files). When everything uses @,
-% this will be simpler.
-%
-\def\atdummies{%
- \def\@{@@}%
- \def\ {@ }%
- \let\{ = \lbraceatcmd
- \let\} = \rbraceatcmd
- %
- % Do the redefinitions.
- \commondummies
- \otherbackslash
-}
-
-% Called from \indexdummies and \atdummies.
-%
-\def\commondummies{%
- %
- % \definedummyword defines \#1 as \string\#1\space, thus effectively
- % preventing its expansion. This is used only for control% words,
- % not control letters, because the \space would be incorrect for
- % control characters, but is needed to separate the control word
- % from whatever follows.
- %
- % For control letters, we have \definedummyletter, which omits the
- % space.
- %
- % These can be used both for control words that take an argument and
- % those that do not. If it is followed by {arg} in the input, then
- % that will dutifully get written to the index (or wherever).
- %
- \def\definedummyword ##1{\def##1{\string##1\space}}%
- \def\definedummyletter##1{\def##1{\string##1}}%
- \let\definedummyaccent\definedummyletter
- %
- \commondummiesnofonts
- %
- \definedummyletter\_%
- %
- % Non-English letters.
- \definedummyword\AA
- \definedummyword\AE
- \definedummyword\L
- \definedummyword\OE
- \definedummyword\O
- \definedummyword\aa
- \definedummyword\ae
- \definedummyword\l
- \definedummyword\oe
- \definedummyword\o
- \definedummyword\ss
- \definedummyword\exclamdown
- \definedummyword\questiondown
- \definedummyword\ordf
- \definedummyword\ordm
- %
- % Although these internal commands shouldn't show up, sometimes they do.
- \definedummyword\bf
- \definedummyword\gtr
- \definedummyword\hat
- \definedummyword\less
- \definedummyword\sf
- \definedummyword\sl
- \definedummyword\tclose
- \definedummyword\tt
- %
- \definedummyword\LaTeX
- \definedummyword\TeX
- %
- % Assorted special characters.
- \definedummyword\bullet
- \definedummyword\comma
- \definedummyword\copyright
- \definedummyword\registeredsymbol
- \definedummyword\dots
- \definedummyword\enddots
- \definedummyword\equiv
- \definedummyword\error
- \definedummyword\euro
- \definedummyword\guillemetleft
- \definedummyword\guillemetright
- \definedummyword\guilsinglleft
- \definedummyword\guilsinglright
- \definedummyword\expansion
- \definedummyword\minus
- \definedummyword\pounds
- \definedummyword\point
- \definedummyword\print
- \definedummyword\quotedblbase
- \definedummyword\quotedblleft
- \definedummyword\quotedblright
- \definedummyword\quoteleft
- \definedummyword\quoteright
- \definedummyword\quotesinglbase
- \definedummyword\result
- \definedummyword\textdegree
- %
- % We want to disable all macros so that they are not expanded by \write.
- \macrolist
- %
- \normalturnoffactive
- %
- % Handle some cases of @value -- where it does not contain any
- % (non-fully-expandable) commands.
- \makevalueexpandable
-}
-
-% \commondummiesnofonts: common to \commondummies and \indexnofonts.
-%
-\def\commondummiesnofonts{%
- % Control letters and accents.
- \definedummyletter\!%
- \definedummyaccent\"%
- \definedummyaccent\'%
- \definedummyletter\*%
- \definedummyaccent\,%
- \definedummyletter\.%
- \definedummyletter\/%
- \definedummyletter\:%
- \definedummyaccent\=%
- \definedummyletter\?%
- \definedummyaccent\^%
- \definedummyaccent\`%
- \definedummyaccent\~%
- \definedummyword\u
- \definedummyword\v
- \definedummyword\H
- \definedummyword\dotaccent
- \definedummyword\ringaccent
- \definedummyword\tieaccent
- \definedummyword\ubaraccent
- \definedummyword\udotaccent
- \definedummyword\dotless
- %
- % Texinfo font commands.
- \definedummyword\b
- \definedummyword\i
- \definedummyword\r
- \definedummyword\sc
- \definedummyword\t
- %
- % Commands that take arguments.
- \definedummyword\acronym
- \definedummyword\cite
- \definedummyword\code
- \definedummyword\command
- \definedummyword\dfn
- \definedummyword\emph
- \definedummyword\env
- \definedummyword\file
- \definedummyword\kbd
- \definedummyword\key
- \definedummyword\math
- \definedummyword\option
- \definedummyword\pxref
- \definedummyword\ref
- \definedummyword\samp
- \definedummyword\strong
- \definedummyword\tie
- \definedummyword\uref
- \definedummyword\url
- \definedummyword\var
- \definedummyword\verb
- \definedummyword\w
- \definedummyword\xref
-}
-
-% \indexnofonts is used when outputting the strings to sort the index
-% by, and when constructing control sequence names. It eliminates all
-% control sequences and just writes whatever the best ASCII sort string
-% would be for a given command (usually its argument).
-%
-\def\indexnofonts{%
- % Accent commands should become @asis.
- \def\definedummyaccent##1{\let##1\asis}%
- % We can just ignore other control letters.
- \def\definedummyletter##1{\let##1\empty}%
- % Hopefully, all control words can become @asis.
- \let\definedummyword\definedummyaccent
- %
- \commondummiesnofonts
- %
- % Don't no-op \tt, since it isn't a user-level command
- % and is used in the definitions of the active chars like <, >, |, etc.
- % Likewise with the other plain tex font commands.
- %\let\tt=\asis
- %
- \def\ { }%
- \def\@{@}%
- % how to handle braces?
- \def\_{\normalunderscore}%
- %
- % Non-English letters.
- \def\AA{AA}%
- \def\AE{AE}%
- \def\L{L}%
- \def\OE{OE}%
- \def\O{O}%
- \def\aa{aa}%
- \def\ae{ae}%
- \def\l{l}%
- \def\oe{oe}%
- \def\o{o}%
- \def\ss{ss}%
- \def\exclamdown{!}%
- \def\questiondown{?}%
- \def\ordf{a}%
- \def\ordm{o}%
- %
- \def\LaTeX{LaTeX}%
- \def\TeX{TeX}%
- %
- % Assorted special characters.
- % (The following {} will end up in the sort string, but that's ok.)
- \def\bullet{bullet}%
- \def\comma{,}%
- \def\copyright{copyright}%
- \def\registeredsymbol{R}%
- \def\dots{...}%
- \def\enddots{...}%
- \def\equiv{==}%
- \def\error{error}%
- \def\euro{euro}%
- \def\guillemetleft{<<}%
- \def\guillemetright{>>}%
- \def\guilsinglleft{<}%
- \def\guilsinglright{>}%
- \def\expansion{==>}%
- \def\minus{-}%
- \def\pounds{pounds}%
- \def\point{.}%
- \def\print{-|}%
- \def\quotedblbase{"}%
- \def\quotedblleft{"}%
- \def\quotedblright{"}%
- \def\quoteleft{`}%
- \def\quoteright{'}%
- \def\quotesinglbase{,}%
- \def\result{=>}%
- \def\textdegree{degrees}%
- %
- % We need to get rid of all macros, leaving only the arguments (if present).
- % Of course this is not nearly correct, but it is the best we can do for now.
- % makeinfo does not expand macros in the argument to @deffn, which ends up
- % writing an index entry, and texindex isn't prepared for an index sort entry
- % that starts with \.
- %
- % Since macro invocations are followed by braces, we can just redefine them
- % to take a single TeX argument. The case of a macro invocation that
- % goes to end-of-line is not handled.
- %
- \macrolist
-}
-
-\let\indexbackslash=0 %overridden during \printindex.
-\let\SETmarginindex=\relax % put index entries in margin (undocumented)?
-
-% Most index entries go through here, but \dosubind is the general case.
-% #1 is the index name, #2 is the entry text.
-\def\doind#1#2{\dosubind{#1}{#2}{}}
-
-% Workhorse for all \fooindexes.
-% #1 is name of index, #2 is stuff to put there, #3 is subentry --
-% empty if called from \doind, as we usually are (the main exception
-% is with most defuns, which call us directly).
-%
-\def\dosubind#1#2#3{%
- \iflinks
- {%
- % Store the main index entry text (including the third arg).
- \toks0 = {#2}%
- % If third arg is present, precede it with a space.
- \def\thirdarg{#3}%
- \ifx\thirdarg\empty \else
- \toks0 = \expandafter{\the\toks0 \space #3}%
- \fi
- %
- \edef\writeto{\csname#1indfile\endcsname}%
- %
- \safewhatsit\dosubindwrite
- }%
- \fi
-}
-
-% Write the entry in \toks0 to the index file:
-%
-\def\dosubindwrite{%
- % Put the index entry in the margin if desired.
- \ifx\SETmarginindex\relax\else
- \insert\margin{\hbox{\vrule height8pt depth3pt width0pt \the\toks0}}%
- \fi
- %
- % Remember, we are within a group.
- \indexdummies % Must do this here, since \bf, etc expand at this stage
- \def\backslashcurfont{\indexbackslash}% \indexbackslash isn't defined now
- % so it will be output as is; and it will print as backslash.
- %
- % Process the index entry with all font commands turned off, to
- % get the string to sort by.
- {\indexnofonts
- \edef\temp{\the\toks0}% need full expansion
- \xdef\indexsorttmp{\temp}%
- }%
- %
- % Set up the complete index entry, with both the sort key and
- % the original text, including any font commands. We write
- % three arguments to \entry to the .?? file (four in the
- % subentry case), texindex reduces to two when writing the .??s
- % sorted result.
- \edef\temp{%
- \write\writeto{%
- \string\entry{\indexsorttmp}{\noexpand\folio}{\the\toks0}}%
- }%
- \temp
-}
-
-% Take care of unwanted page breaks/skips around a whatsit:
-%
-% If a skip is the last thing on the list now, preserve it
-% by backing up by \lastskip, doing the \write, then inserting
-% the skip again. Otherwise, the whatsit generated by the
-% \write or \pdfdest will make \lastskip zero. The result is that
-% sequences like this:
-% @end defun
-% @tindex whatever
-% @defun ...
-% will have extra space inserted, because the \medbreak in the
-% start of the @defun won't see the skip inserted by the @end of
-% the previous defun.
-%
-% But don't do any of this if we're not in vertical mode. We
-% don't want to do a \vskip and prematurely end a paragraph.
-%
-% Avoid page breaks due to these extra skips, too.
-%
-% But wait, there is a catch there:
-% We'll have to check whether \lastskip is zero skip. \ifdim is not
-% sufficient for this purpose, as it ignores stretch and shrink parts
-% of the skip. The only way seems to be to check the textual
-% representation of the skip.
-%
-% The following is almost like \def\zeroskipmacro{0.0pt} except that
-% the ``p'' and ``t'' characters have catcode \other, not 11 (letter).
-%
-\edef\zeroskipmacro{\expandafter\the\csname z@skip\endcsname}
-%
-\newskip\whatsitskip
-\newcount\whatsitpenalty
-%
-% ..., ready, GO:
-%
-\def\safewhatsit#1{%
-\ifhmode
- #1%
-\else
- % \lastskip and \lastpenalty cannot both be nonzero simultaneously.
- \whatsitskip = \lastskip
- \edef\lastskipmacro{\the\lastskip}%
- \whatsitpenalty = \lastpenalty
- %
- % If \lastskip is nonzero, that means the last item was a
- % skip. And since a skip is discardable, that means this
- % -\whatsitskip glue we're inserting is preceded by a
- % non-discardable item, therefore it is not a potential
- % breakpoint, therefore no \nobreak needed.
- \ifx\lastskipmacro\zeroskipmacro
- \else
- \vskip-\whatsitskip
- \fi
- %
- #1%
- %
- \ifx\lastskipmacro\zeroskipmacro
- % If \lastskip was zero, perhaps the last item was a penalty, and
- % perhaps it was >=10000, e.g., a \nobreak. In that case, we want
- % to re-insert the same penalty (values >10000 are used for various
- % signals); since we just inserted a non-discardable item, any
- % following glue (such as a \parskip) would be a breakpoint. For example:
- %
- % @deffn deffn-whatever
- % @vindex index-whatever
- % Description.
- % would allow a break between the index-whatever whatsit
- % and the "Description." paragraph.
- \ifnum\whatsitpenalty>9999 \penalty\whatsitpenalty \fi
- \else
- % On the other hand, if we had a nonzero \lastskip,
- % this make-up glue would be preceded by a non-discardable item
- % (the whatsit from the \write), so we must insert a \nobreak.
- \nobreak\vskip\whatsitskip
- \fi
-\fi
-}
-
-% The index entry written in the file actually looks like
-% \entry {sortstring}{page}{topic}
-% or
-% \entry {sortstring}{page}{topic}{subtopic}
-% The texindex program reads in these files and writes files
-% containing these kinds of lines:
-% \initial {c}
-% before the first topic whose initial is c
-% \entry {topic}{pagelist}
-% for a topic that is used without subtopics
-% \primary {topic}
-% for the beginning of a topic that is used with subtopics
-% \secondary {subtopic}{pagelist}
-% for each subtopic.
-
-% Define the user-accessible indexing commands
-% @findex, @vindex, @kindex, @cindex.
-
-\def\findex {\fnindex}
-\def\kindex {\kyindex}
-\def\cindex {\cpindex}
-\def\vindex {\vrindex}
-\def\tindex {\tpindex}
-\def\pindex {\pgindex}
-
-\def\cindexsub {\begingroup\obeylines\cindexsub}
-{\obeylines %
-\gdef\cindexsub "#1" #2^^M{\endgroup %
-\dosubind{cp}{#2}{#1}}}
-
-% Define the macros used in formatting output of the sorted index material.
-
-% @printindex causes a particular index (the ??s file) to get printed.
-% It does not print any chapter heading (usually an @unnumbered).
-%
-\parseargdef\printindex{\begingroup
- \dobreak \chapheadingskip{10000}%
- %
- \smallfonts \rm
- \tolerance = 9500
- \plainfrenchspacing
- \everypar = {}% don't want the \kern\-parindent from indentation suppression.
- %
- % See if the index file exists and is nonempty.
- % Change catcode of @ here so that if the index file contains
- % \initial {@}
- % as its first line, TeX doesn't complain about mismatched braces
- % (because it thinks @} is a control sequence).
- \catcode`\@ = 11
- \openin 1 \jobname.#1s
- \ifeof 1
- % \enddoublecolumns gets confused if there is no text in the index,
- % and it loses the chapter title and the aux file entries for the
- % index. The easiest way to prevent this problem is to make sure
- % there is some text.
- \putwordIndexNonexistent
- \else
- %
- % If the index file exists but is empty, then \openin leaves \ifeof
- % false. We have to make TeX try to read something from the file, so
- % it can discover if there is anything in it.
- \read 1 to \temp
- \ifeof 1
- \putwordIndexIsEmpty
- \else
- % Index files are almost Texinfo source, but we use \ as the escape
- % character. It would be better to use @, but that's too big a change
- % to make right now.
- \def\indexbackslash{\backslashcurfont}%
- \catcode`\\ = 0
- \escapechar = `\\
- \begindoublecolumns
- \input \jobname.#1s
- \enddoublecolumns
- \fi
- \fi
- \closein 1
-\endgroup}
-
-% These macros are used by the sorted index file itself.
-% Change them to control the appearance of the index.
-
-\def\initial#1{{%
- % Some minor font changes for the special characters.
- \let\tentt=\sectt \let\tt=\sectt \let\sf=\sectt
- %
- % Remove any glue we may have, we'll be inserting our own.
- \removelastskip
- %
- % We like breaks before the index initials, so insert a bonus.
- \nobreak
- \vskip 0pt plus 3\baselineskip
- \penalty 0
- \vskip 0pt plus -3\baselineskip
- %
- % Typeset the initial. Making this add up to a whole number of
- % baselineskips increases the chance of the dots lining up from column
- % to column. It still won't often be perfect, because of the stretch
- % we need before each entry, but it's better.
- %
- % No shrink because it confuses \balancecolumns.
- \vskip 1.67\baselineskip plus .5\baselineskip
- \leftline{\secbf #1}%
- % Do our best not to break after the initial.
- \nobreak
- \vskip .33\baselineskip plus .1\baselineskip
-}}
-
-% \entry typesets a paragraph consisting of the text (#1), dot leaders, and
-% then page number (#2) flushed to the right margin. It is used for index
-% and table of contents entries. The paragraph is indented by \leftskip.
-%
-% A straightforward implementation would start like this:
-% \def\entry#1#2{...
-% But this freezes the catcodes in the argument, and can cause problems to
-% @code, which sets - active. This problem was fixed by a kludge---
-% ``-'' was active throughout whole index, but this isn't really right.
-%
-% The right solution is to prevent \entry from swallowing the whole text.
-% --kasal, 21nov03
-\def\entry{%
- \begingroup
- %
- % Start a new paragraph if necessary, so our assignments below can't
- % affect previous text.
- \par
- %
- % Do not fill out the last line with white space.
- \parfillskip = 0in
- %
- % No extra space above this paragraph.
- \parskip = 0in
- %
- % Do not prefer a separate line ending with a hyphen to fewer lines.
- \finalhyphendemerits = 0
- %
- % \hangindent is only relevant when the entry text and page number
- % don't both fit on one line. In that case, bob suggests starting the
- % dots pretty far over on the line. Unfortunately, a large
- % indentation looks wrong when the entry text itself is broken across
- % lines. So we use a small indentation and put up with long leaders.
- %
- % \hangafter is reset to 1 (which is the value we want) at the start
- % of each paragraph, so we need not do anything with that.
- \hangindent = 2em
- %
- % When the entry text needs to be broken, just fill out the first line
- % with blank space.
- \rightskip = 0pt plus1fil
- %
- % A bit of stretch before each entry for the benefit of balancing
- % columns.
- \vskip 0pt plus1pt
- %
- % Swallow the left brace of the text (first parameter):
- \afterassignment\doentry
- \let\temp =
-}
-\def\doentry{%
- \bgroup % Instead of the swallowed brace.
- \noindent
- \aftergroup\finishentry
- % And now comes the text of the entry.
-}
-\def\finishentry#1{%
- % #1 is the page number.
- %
- % The following is kludged to not output a line of dots in the index if
- % there are no page numbers. The next person who breaks this will be
- % cursed by a Unix daemon.
- \setbox\boxA = \hbox{#1}%
- \ifdim\wd\boxA = 0pt
- \ %
- \else
- %
- % If we must, put the page number on a line of its own, and fill out
- % this line with blank space. (The \hfil is overwhelmed with the
- % fill leaders glue in \indexdotfill if the page number does fit.)
- \hfil\penalty50
- \null\nobreak\indexdotfill % Have leaders before the page number.
- %
- % The `\ ' here is removed by the implicit \unskip that TeX does as
- % part of (the primitive) \par. Without it, a spurious underfull
- % \hbox ensues.
- \ifpdf
- \pdfgettoks#1.%
- \ \the\toksA
- \else
- \ #1%
- \fi
- \fi
- \par
- \endgroup
-}
-
-% Like plain.tex's \dotfill, except uses up at least 1 em.
-\def\indexdotfill{\cleaders
- \hbox{$\mathsurround=0pt \mkern1.5mu.\mkern1.5mu$}\hskip 1em plus 1fill}
-
-\def\primary #1{\line{#1\hfil}}
-
-\newskip\secondaryindent \secondaryindent=0.5cm
-\def\secondary#1#2{{%
- \parfillskip=0in
- \parskip=0in
- \hangindent=1in
- \hangafter=1
- \noindent\hskip\secondaryindent\hbox{#1}\indexdotfill
- \ifpdf
- \pdfgettoks#2.\ \the\toksA % The page number ends the paragraph.
- \else
- #2
- \fi
- \par
-}}
-
-% Define two-column mode, which we use to typeset indexes.
-% Adapted from the TeXbook, page 416, which is to say,
-% the manmac.tex format used to print the TeXbook itself.
-\catcode`\@=11
-
-\newbox\partialpage
-\newdimen\doublecolumnhsize
-
-\def\begindoublecolumns{\begingroup % ended by \enddoublecolumns
- % Grab any single-column material above us.
- \output = {%
- %
- % Here is a possibility not foreseen in manmac: if we accumulate a
- % whole lot of material, we might end up calling this \output
- % routine twice in a row (see the doublecol-lose test, which is
- % essentially a couple of indexes with @setchapternewpage off). In
- % that case we just ship out what is in \partialpage with the normal
- % output routine. Generally, \partialpage will be empty when this
- % runs and this will be a no-op. See the indexspread.tex test case.
- \ifvoid\partialpage \else
- \onepageout{\pagecontents\partialpage}%
- \fi
- %
- \global\setbox\partialpage = \vbox{%
- % Unvbox the main output page.
- \unvbox\PAGE
- \kern-\topskip \kern\baselineskip
- }%
- }%
- \eject % run that output routine to set \partialpage
- %
- % Use the double-column output routine for subsequent pages.
- \output = {\doublecolumnout}%
- %
- % Change the page size parameters. We could do this once outside this
- % routine, in each of @smallbook, @afourpaper, and the default 8.5x11
- % format, but then we repeat the same computation. Repeating a couple
- % of assignments once per index is clearly meaningless for the
- % execution time, so we may as well do it in one place.
- %
- % First we halve the line length, less a little for the gutter between
- % the columns. We compute the gutter based on the line length, so it
- % changes automatically with the paper format. The magic constant
- % below is chosen so that the gutter has the same value (well, +-<1pt)
- % as it did when we hard-coded it.
- %
- % We put the result in a separate register, \doublecolumhsize, so we
- % can restore it in \pagesofar, after \hsize itself has (potentially)
- % been clobbered.
- %
- \doublecolumnhsize = \hsize
- \advance\doublecolumnhsize by -.04154\hsize
- \divide\doublecolumnhsize by 2
- \hsize = \doublecolumnhsize
- %
- % Double the \vsize as well. (We don't need a separate register here,
- % since nobody clobbers \vsize.)
- \vsize = 2\vsize
-}
-
-% The double-column output routine for all double-column pages except
-% the last.
-%
-\def\doublecolumnout{%
- \splittopskip=\topskip \splitmaxdepth=\maxdepth
- % Get the available space for the double columns -- the normal
- % (undoubled) page height minus any material left over from the
- % previous page.
- \dimen@ = \vsize
- \divide\dimen@ by 2
- \advance\dimen@ by -\ht\partialpage
- %
- % box0 will be the left-hand column, box2 the right.
- \setbox0=\vsplit255 to\dimen@ \setbox2=\vsplit255 to\dimen@
- \onepageout\pagesofar
- \unvbox255
- \penalty\outputpenalty
-}
-%
-% Re-output the contents of the output page -- any previous material,
-% followed by the two boxes we just split, in box0 and box2.
-\def\pagesofar{%
- \unvbox\partialpage
- %
- \hsize = \doublecolumnhsize
- \wd0=\hsize \wd2=\hsize
- \hbox to\pagewidth{\box0\hfil\box2}%
-}
-%
-% All done with double columns.
-\def\enddoublecolumns{%
- % The following penalty ensures that the page builder is exercised
- % _before_ we change the output routine. This is necessary in the
- % following situation:
- %
- % The last section of the index consists only of a single entry.
- % Before this section, \pagetotal is less than \pagegoal, so no
- % break occurs before the last section starts. However, the last
- % section, consisting of \initial and the single \entry, does not
- % fit on the page and has to be broken off. Without the following
- % penalty the page builder will not be exercised until \eject
- % below, and by that time we'll already have changed the output
- % routine to the \balancecolumns version, so the next-to-last
- % double-column page will be processed with \balancecolumns, which
- % is wrong: The two columns will go to the main vertical list, with
- % the broken-off section in the recent contributions. As soon as
- % the output routine finishes, TeX starts reconsidering the page
- % break. The two columns and the broken-off section both fit on the
- % page, because the two columns now take up only half of the page
- % goal. When TeX sees \eject from below which follows the final
- % section, it invokes the new output routine that we've set after
- % \balancecolumns below; \onepageout will try to fit the two columns
- % and the final section into the vbox of \pageheight (see
- % \pagebody), causing an overfull box.
- %
- % Note that glue won't work here, because glue does not exercise the
- % page builder, unlike penalties (see The TeXbook, pp. 280-281).
- \penalty0
- %
- \output = {%
- % Split the last of the double-column material. Leave it on the
- % current page, no automatic page break.
- \balancecolumns
- %
- % If we end up splitting too much material for the current page,
- % though, there will be another page break right after this \output
- % invocation ends. Having called \balancecolumns once, we do not
- % want to call it again. Therefore, reset \output to its normal
- % definition right away. (We hope \balancecolumns will never be
- % called on to balance too much material, but if it is, this makes
- % the output somewhat more palatable.)
- \global\output = {\onepageout{\pagecontents\PAGE}}%
- }%
- \eject
- \endgroup % started in \begindoublecolumns
- %
- % \pagegoal was set to the doubled \vsize above, since we restarted
- % the current page. We're now back to normal single-column
- % typesetting, so reset \pagegoal to the normal \vsize (after the
- % \endgroup where \vsize got restored).
- \pagegoal = \vsize
-}
-%
-% Called at the end of the double column material.
-\def\balancecolumns{%
- \setbox0 = \vbox{\unvbox255}% like \box255 but more efficient, see p.120.
- \dimen@ = \ht0
- \advance\dimen@ by \topskip
- \advance\dimen@ by-\baselineskip
- \divide\dimen@ by 2 % target to split to
- %debug\message{final 2-column material height=\the\ht0, target=\the\dimen@.}%
- \splittopskip = \topskip
- % Loop until we get a decent breakpoint.
- {%
- \vbadness = 10000
- \loop
- \global\setbox3 = \copy0
- \global\setbox1 = \vsplit3 to \dimen@
- \ifdim\ht3>\dimen@
- \global\advance\dimen@ by 1pt
- \repeat
- }%
- %debug\message{split to \the\dimen@, column heights: \the\ht1, \the\ht3.}%
- \setbox0=\vbox to\dimen@{\unvbox1}%
- \setbox2=\vbox to\dimen@{\unvbox3}%
- %
- \pagesofar
-}
-\catcode`\@ = \other
-
-
-\message{sectioning,}
-% Chapters, sections, etc.
-
-% \unnumberedno is an oxymoron, of course. But we count the unnumbered
-% sections so that we can refer to them unambiguously in the pdf
-% outlines by their "section number". We avoid collisions with chapter
-% numbers by starting them at 10000. (If a document ever has 10000
-% chapters, we're in trouble anyway, I'm sure.)
-\newcount\unnumberedno \unnumberedno = 10000
-\newcount\chapno
-\newcount\secno \secno=0
-\newcount\subsecno \subsecno=0
-\newcount\subsubsecno \subsubsecno=0
-
-% This counter is funny since it counts through charcodes of letters A, B, ...
-\newcount\appendixno \appendixno = `\@
-%
-% \def\appendixletter{\char\the\appendixno}
-% We do the following ugly conditional instead of the above simple
-% construct for the sake of pdftex, which needs the actual
-% letter in the expansion, not just typeset.
-%
-\def\appendixletter{%
- \ifnum\appendixno=`A A%
- \else\ifnum\appendixno=`B B%
- \else\ifnum\appendixno=`C C%
- \else\ifnum\appendixno=`D D%
- \else\ifnum\appendixno=`E E%
- \else\ifnum\appendixno=`F F%
- \else\ifnum\appendixno=`G G%
- \else\ifnum\appendixno=`H H%
- \else\ifnum\appendixno=`I I%
- \else\ifnum\appendixno=`J J%
- \else\ifnum\appendixno=`K K%
- \else\ifnum\appendixno=`L L%
- \else\ifnum\appendixno=`M M%
- \else\ifnum\appendixno=`N N%
- \else\ifnum\appendixno=`O O%
- \else\ifnum\appendixno=`P P%
- \else\ifnum\appendixno=`Q Q%
- \else\ifnum\appendixno=`R R%
- \else\ifnum\appendixno=`S S%
- \else\ifnum\appendixno=`T T%
- \else\ifnum\appendixno=`U U%
- \else\ifnum\appendixno=`V V%
- \else\ifnum\appendixno=`W W%
- \else\ifnum\appendixno=`X X%
- \else\ifnum\appendixno=`Y Y%
- \else\ifnum\appendixno=`Z Z%
- % The \the is necessary, despite appearances, because \appendixletter is
- % expanded while writing the .toc file. \char\appendixno is not
- % expandable, thus it is written literally, thus all appendixes come out
- % with the same letter (or @) in the toc without it.
- \else\char\the\appendixno
- \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi
- \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi}
-
-% Each @chapter defines these (using marks) as the number+name, number
-% and name of the chapter. Page headings and footings can use
-% these. @section does likewise.
-\def\thischapter{}
-\def\thischapternum{}
-\def\thischaptername{}
-\def\thissection{}
-\def\thissectionnum{}
-\def\thissectionname{}
-
-\newcount\absseclevel % used to calculate proper heading level
-\newcount\secbase\secbase=0 % @raisesections/@lowersections modify this count
-
-% @raisesections: treat @section as chapter, @subsection as section, etc.
-\def\raisesections{\global\advance\secbase by -1}
-\let\up=\raisesections % original BFox name
-
-% @lowersections: treat @chapter as section, @section as subsection, etc.
-\def\lowersections{\global\advance\secbase by 1}
-\let\down=\lowersections % original BFox name
-
-% we only have subsub.
-\chardef\maxseclevel = 3
-%
-% A numbered section within an unnumbered changes to unnumbered too.
-% To achive this, remember the "biggest" unnum. sec. we are currently in:
-\chardef\unmlevel = \maxseclevel
-%
-% Trace whether the current chapter is an appendix or not:
-% \chapheadtype is "N" or "A", unnumbered chapters are ignored.
-\def\chapheadtype{N}
-
-% Choose a heading macro
-% #1 is heading type
-% #2 is heading level
-% #3 is text for heading
-\def\genhead#1#2#3{%
- % Compute the abs. sec. level:
- \absseclevel=#2
- \advance\absseclevel by \secbase
- % Make sure \absseclevel doesn't fall outside the range:
- \ifnum \absseclevel < 0
- \absseclevel = 0
- \else
- \ifnum \absseclevel > 3
- \absseclevel = 3
- \fi
- \fi
- % The heading type:
- \def\headtype{#1}%
- \if \headtype U%
- \ifnum \absseclevel < \unmlevel
- \chardef\unmlevel = \absseclevel
- \fi
- \else
- % Check for appendix sections:
- \ifnum \absseclevel = 0
- \edef\chapheadtype{\headtype}%
- \else
- \if \headtype A\if \chapheadtype N%
- \errmessage{@appendix... within a non-appendix chapter}%
- \fi\fi
- \fi
- % Check for numbered within unnumbered:
- \ifnum \absseclevel > \unmlevel
- \def\headtype{U}%
- \else
- \chardef\unmlevel = 3
- \fi
- \fi
- % Now print the heading:
- \if \headtype U%
- \ifcase\absseclevel
- \unnumberedzzz{#3}%
- \or \unnumberedseczzz{#3}%
- \or \unnumberedsubseczzz{#3}%
- \or \unnumberedsubsubseczzz{#3}%
- \fi
- \else
- \if \headtype A%
- \ifcase\absseclevel
- \appendixzzz{#3}%
- \or \appendixsectionzzz{#3}%
- \or \appendixsubseczzz{#3}%
- \or \appendixsubsubseczzz{#3}%
- \fi
- \else
- \ifcase\absseclevel
- \chapterzzz{#3}%
- \or \seczzz{#3}%
- \or \numberedsubseczzz{#3}%
- \or \numberedsubsubseczzz{#3}%
- \fi
- \fi
- \fi
- \suppressfirstparagraphindent
-}
-
-% an interface:
-\def\numhead{\genhead N}
-\def\apphead{\genhead A}
-\def\unnmhead{\genhead U}
-
-% @chapter, @appendix, @unnumbered. Increment top-level counter, reset
-% all lower-level sectioning counters to zero.
-%
-% Also set \chaplevelprefix, which we prepend to @float sequence numbers
-% (e.g., figures), q.v. By default (before any chapter), that is empty.
-\let\chaplevelprefix = \empty
-%
-\outer\parseargdef\chapter{\numhead0{#1}} % normally numhead0 calls chapterzzz
-\def\chapterzzz#1{%
- % section resetting is \global in case the chapter is in a group, such
- % as an @include file.
- \global\secno=0 \global\subsecno=0 \global\subsubsecno=0
- \global\advance\chapno by 1
- %
- % Used for \float.
- \gdef\chaplevelprefix{\the\chapno.}%
- \resetallfloatnos
- %
- \message{\putwordChapter\space \the\chapno}%
- %
- % Write the actual heading.
- \chapmacro{#1}{Ynumbered}{\the\chapno}%
- %
- % So @section and the like are numbered underneath this chapter.
- \global\let\section = \numberedsec
- \global\let\subsection = \numberedsubsec
- \global\let\subsubsection = \numberedsubsubsec
-}
-
-\outer\parseargdef\appendix{\apphead0{#1}} % normally apphead0 calls appendixzzz
-\def\appendixzzz#1{%
- \global\secno=0 \global\subsecno=0 \global\subsubsecno=0
- \global\advance\appendixno by 1
- \gdef\chaplevelprefix{\appendixletter.}%
- \resetallfloatnos
- %
- \def\appendixnum{\putwordAppendix\space \appendixletter}%
- \message{\appendixnum}%
- %
- \chapmacro{#1}{Yappendix}{\appendixletter}%
- %
- \global\let\section = \appendixsec
- \global\let\subsection = \appendixsubsec
- \global\let\subsubsection = \appendixsubsubsec
-}
-
-\outer\parseargdef\unnumbered{\unnmhead0{#1}} % normally unnmhead0 calls unnumberedzzz
-\def\unnumberedzzz#1{%
- \global\secno=0 \global\subsecno=0 \global\subsubsecno=0
- \global\advance\unnumberedno by 1
- %
- % Since an unnumbered has no number, no prefix for figures.
- \global\let\chaplevelprefix = \empty
- \resetallfloatnos
- %
- % This used to be simply \message{#1}, but TeX fully expands the
- % argument to \message. Therefore, if #1 contained @-commands, TeX
- % expanded them. For example, in `@unnumbered The @cite{Book}', TeX
- % expanded @cite (which turns out to cause errors because \cite is meant
- % to be executed, not expanded).
- %
- % Anyway, we don't want the fully-expanded definition of @cite to appear
- % as a result of the \message, we just want `@cite' itself. We use
- % \the to achieve this: TeX expands \the only once,
- % simply yielding the contents of . (We also do this for
- % the toc entries.)
- \toks0 = {#1}%
- \message{(\the\toks0)}%
- %
- \chapmacro{#1}{Ynothing}{\the\unnumberedno}%
- %
- \global\let\section = \unnumberedsec
- \global\let\subsection = \unnumberedsubsec
- \global\let\subsubsection = \unnumberedsubsubsec
-}
-
-% @centerchap is like @unnumbered, but the heading is centered.
-\outer\parseargdef\centerchap{%
- % Well, we could do the following in a group, but that would break
- % an assumption that \chapmacro is called at the outermost level.
- % Thus we are safer this way: --kasal, 24feb04
- \let\centerparametersmaybe = \centerparameters
- \unnmhead0{#1}%
- \let\centerparametersmaybe = \relax
-}
-
-% @top is like @unnumbered.
-\let\top\unnumbered
-
-% Sections.
-\outer\parseargdef\numberedsec{\numhead1{#1}} % normally calls seczzz
-\def\seczzz#1{%
- \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1
- \sectionheading{#1}{sec}{Ynumbered}{\the\chapno.\the\secno}%
-}
-
-\outer\parseargdef\appendixsection{\apphead1{#1}} % normally calls appendixsectionzzz
-\def\appendixsectionzzz#1{%
- \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1
- \sectionheading{#1}{sec}{Yappendix}{\appendixletter.\the\secno}%
-}
-\let\appendixsec\appendixsection
-
-\outer\parseargdef\unnumberedsec{\unnmhead1{#1}} % normally calls unnumberedseczzz
-\def\unnumberedseczzz#1{%
- \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1
- \sectionheading{#1}{sec}{Ynothing}{\the\unnumberedno.\the\secno}%
-}
-
-% Subsections.
-\outer\parseargdef\numberedsubsec{\numhead2{#1}} % normally calls numberedsubseczzz
-\def\numberedsubseczzz#1{%
- \global\subsubsecno=0 \global\advance\subsecno by 1
- \sectionheading{#1}{subsec}{Ynumbered}{\the\chapno.\the\secno.\the\subsecno}%
-}
-
-\outer\parseargdef\appendixsubsec{\apphead2{#1}} % normally calls appendixsubseczzz
-\def\appendixsubseczzz#1{%
- \global\subsubsecno=0 \global\advance\subsecno by 1
- \sectionheading{#1}{subsec}{Yappendix}%
- {\appendixletter.\the\secno.\the\subsecno}%
-}
-
-\outer\parseargdef\unnumberedsubsec{\unnmhead2{#1}} %normally calls unnumberedsubseczzz
-\def\unnumberedsubseczzz#1{%
- \global\subsubsecno=0 \global\advance\subsecno by 1
- \sectionheading{#1}{subsec}{Ynothing}%
- {\the\unnumberedno.\the\secno.\the\subsecno}%
-}
-
-% Subsubsections.
-\outer\parseargdef\numberedsubsubsec{\numhead3{#1}} % normally numberedsubsubseczzz
-\def\numberedsubsubseczzz#1{%
- \global\advance\subsubsecno by 1
- \sectionheading{#1}{subsubsec}{Ynumbered}%
- {\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno}%
-}
-
-\outer\parseargdef\appendixsubsubsec{\apphead3{#1}} % normally appendixsubsubseczzz
-\def\appendixsubsubseczzz#1{%
- \global\advance\subsubsecno by 1
- \sectionheading{#1}{subsubsec}{Yappendix}%
- {\appendixletter.\the\secno.\the\subsecno.\the\subsubsecno}%
-}
-
-\outer\parseargdef\unnumberedsubsubsec{\unnmhead3{#1}} %normally unnumberedsubsubseczzz
-\def\unnumberedsubsubseczzz#1{%
- \global\advance\subsubsecno by 1
- \sectionheading{#1}{subsubsec}{Ynothing}%
- {\the\unnumberedno.\the\secno.\the\subsecno.\the\subsubsecno}%
-}
-
-% These macros control what the section commands do, according
-% to what kind of chapter we are in (ordinary, appendix, or unnumbered).
-% Define them by default for a numbered chapter.
-\let\section = \numberedsec
-\let\subsection = \numberedsubsec
-\let\subsubsection = \numberedsubsubsec
-
-% Define @majorheading, @heading and @subheading
-
-% NOTE on use of \vbox for chapter headings, section headings, and such:
-% 1) We use \vbox rather than the earlier \line to permit
-% overlong headings to fold.
-% 2) \hyphenpenalty is set to 10000 because hyphenation in a
-% heading is obnoxious; this forbids it.
-% 3) Likewise, headings look best if no \parindent is used, and
-% if justification is not attempted. Hence \raggedright.
-
-
-\def\majorheading{%
- {\advance\chapheadingskip by 10pt \chapbreak }%
- \parsearg\chapheadingzzz
-}
-
-\def\chapheading{\chapbreak \parsearg\chapheadingzzz}
-\def\chapheadingzzz#1{%
- {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000
- \parindent=0pt\raggedright
- \rm #1\hfill}}%
- \bigskip \par\penalty 200\relax
- \suppressfirstparagraphindent
-}
-
-% @heading, @subheading, @subsubheading.
-\parseargdef\heading{\sectionheading{#1}{sec}{Yomitfromtoc}{}
- \suppressfirstparagraphindent}
-\parseargdef\subheading{\sectionheading{#1}{subsec}{Yomitfromtoc}{}
- \suppressfirstparagraphindent}
-\parseargdef\subsubheading{\sectionheading{#1}{subsubsec}{Yomitfromtoc}{}
- \suppressfirstparagraphindent}
-
-% These macros generate a chapter, section, etc. heading only
-% (including whitespace, linebreaking, etc. around it),
-% given all the information in convenient, parsed form.
-
-%%% Args are the skip and penalty (usually negative)
-\def\dobreak#1#2{\par\ifdim\lastskip<#1\removelastskip\penalty#2\vskip#1\fi}
-
-%%% Define plain chapter starts, and page on/off switching for it
-% Parameter controlling skip before chapter headings (if needed)
-
-\newskip\chapheadingskip
-
-\def\chapbreak{\dobreak \chapheadingskip {-4000}}
-\def\chappager{\par\vfill\supereject}
-% Because \domark is called before \chapoddpage, the filler page will
-% get the headings for the next chapter, which is wrong. But we don't
-% care -- we just disable all headings on the filler page.
-\def\chapoddpage{%
- \chappager
- \ifodd\pageno \else
- \begingroup
- \evenheadline={\hfil}\evenfootline={\hfil}%
- \oddheadline={\hfil}\oddfootline={\hfil}%
- \hbox to 0pt{}%
- \chappager
- \endgroup
- \fi
-}
-
-\def\setchapternewpage #1 {\csname CHAPPAG#1\endcsname}
-
-\def\CHAPPAGoff{%
-\global\let\contentsalignmacro = \chappager
-\global\let\pchapsepmacro=\chapbreak
-\global\let\pagealignmacro=\chappager}
-
-\def\CHAPPAGon{%
-\global\let\contentsalignmacro = \chappager
-\global\let\pchapsepmacro=\chappager
-\global\let\pagealignmacro=\chappager
-\global\def\HEADINGSon{\HEADINGSsingle}}
-
-\def\CHAPPAGodd{%
-\global\let\contentsalignmacro = \chapoddpage
-\global\let\pchapsepmacro=\chapoddpage
-\global\let\pagealignmacro=\chapoddpage
-\global\def\HEADINGSon{\HEADINGSdouble}}
-
-\CHAPPAGon
-
-% Chapter opening.
-%
-% #1 is the text, #2 is the section type (Ynumbered, Ynothing,
-% Yappendix, Yomitfromtoc), #3 the chapter number.
-%
-% To test against our argument.
-\def\Ynothingkeyword{Ynothing}
-\def\Yomitfromtockeyword{Yomitfromtoc}
-\def\Yappendixkeyword{Yappendix}
-%
-\def\chapmacro#1#2#3{%
- % Insert the first mark before the heading break (see notes for \domark).
- \let\prevchapterdefs=\lastchapterdefs
- \let\prevsectiondefs=\lastsectiondefs
- \gdef\lastsectiondefs{\gdef\thissectionname{}\gdef\thissectionnum{}%
- \gdef\thissection{}}%
- %
- \def\temptype{#2}%
- \ifx\temptype\Ynothingkeyword
- \gdef\lastchapterdefs{\gdef\thischaptername{#1}\gdef\thischapternum{}%
- \gdef\thischapter{\thischaptername}}%
- \else\ifx\temptype\Yomitfromtockeyword
- \gdef\lastchapterdefs{\gdef\thischaptername{#1}\gdef\thischapternum{}%
- \gdef\thischapter{}}%
- \else\ifx\temptype\Yappendixkeyword
- \toks0={#1}%
- \xdef\lastchapterdefs{%
- \gdef\noexpand\thischaptername{\the\toks0}%
- \gdef\noexpand\thischapternum{\appendixletter}%
- \gdef\noexpand\thischapter{\putwordAppendix{} \noexpand\thischapternum:
- \noexpand\thischaptername}%
- }%
- \else
- \toks0={#1}%
- \xdef\lastchapterdefs{%
- \gdef\noexpand\thischaptername{\the\toks0}%
- \gdef\noexpand\thischapternum{\the\chapno}%
- \gdef\noexpand\thischapter{\putwordChapter{} \noexpand\thischapternum:
- \noexpand\thischaptername}%
- }%
- \fi\fi\fi
- %
- % Output the mark. Pass it through \safewhatsit, to take care of
- % the preceding space.
- \safewhatsit\domark
- %
- % Insert the chapter heading break.
- \pchapsepmacro
- %
- % Now the second mark, after the heading break. No break points
- % between here and the heading.
- \let\prevchapterdefs=\lastchapterdefs
- \let\prevsectiondefs=\lastsectiondefs
- \domark
- %
- {%
- \chapfonts \rm
- %
- % Have to define \lastsection before calling \donoderef, because the
- % xref code eventually uses it. On the other hand, it has to be called
- % after \pchapsepmacro, or the headline will change too soon.
- \gdef\lastsection{#1}%
- %
- % Only insert the separating space if we have a chapter/appendix
- % number, and don't print the unnumbered ``number''.
- \ifx\temptype\Ynothingkeyword
- \setbox0 = \hbox{}%
- \def\toctype{unnchap}%
- \else\ifx\temptype\Yomitfromtockeyword
- \setbox0 = \hbox{}% contents like unnumbered, but no toc entry
- \def\toctype{omit}%
- \else\ifx\temptype\Yappendixkeyword
- \setbox0 = \hbox{\putwordAppendix{} #3\enspace}%
- \def\toctype{app}%
- \else
- \setbox0 = \hbox{#3\enspace}%
- \def\toctype{numchap}%
- \fi\fi\fi
- %
- % Write the toc entry for this chapter. Must come before the
- % \donoderef, because we include the current node name in the toc
- % entry, and \donoderef resets it to empty.
- \writetocentry{\toctype}{#1}{#3}%
- %
- % For pdftex, we have to write out the node definition (aka, make
- % the pdfdest) after any page break, but before the actual text has
- % been typeset. If the destination for the pdf outline is after the
- % text, then jumping from the outline may wind up with the text not
- % being visible, for instance under high magnification.
- \donoderef{#2}%
- %
- % Typeset the actual heading.
- \nobreak % Avoid page breaks at the interline glue.
- \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright
- \hangindent=\wd0 \centerparametersmaybe
- \unhbox0 #1\par}%
- }%
- \nobreak\bigskip % no page break after a chapter title
- \nobreak
-}
-
-% @centerchap -- centered and unnumbered.
-\let\centerparametersmaybe = \relax
-\def\centerparameters{%
- \advance\rightskip by 3\rightskip
- \leftskip = \rightskip
- \parfillskip = 0pt
-}
-
-
-% I don't think this chapter style is supported any more, so I'm not
-% updating it with the new noderef stuff. We'll see. --karl, 11aug03.
-%
-\def\setchapterstyle #1 {\csname CHAPF#1\endcsname}
-%
-\def\unnchfopen #1{%
-\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000
- \parindent=0pt\raggedright
- \rm #1\hfill}}\bigskip \par\nobreak
-}
-\def\chfopen #1#2{\chapoddpage {\chapfonts
-\vbox to 3in{\vfil \hbox to\hsize{\hfil #2} \hbox to\hsize{\hfil #1} \vfil}}%
-\par\penalty 5000 %
-}
-\def\centerchfopen #1{%
-\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000
- \parindent=0pt
- \hfill {\rm #1}\hfill}}\bigskip \par\nobreak
-}
-\def\CHAPFopen{%
- \global\let\chapmacro=\chfopen
- \global\let\centerchapmacro=\centerchfopen}
-
-
-% Section titles. These macros combine the section number parts and
-% call the generic \sectionheading to do the printing.
-%
-\newskip\secheadingskip
-\def\secheadingbreak{\dobreak \secheadingskip{-1000}}
-
-% Subsection titles.
-\newskip\subsecheadingskip
-\def\subsecheadingbreak{\dobreak \subsecheadingskip{-500}}
-
-% Subsubsection titles.
-\def\subsubsecheadingskip{\subsecheadingskip}
-\def\subsubsecheadingbreak{\subsecheadingbreak}
-
-
-% Print any size, any type, section title.
-%
-% #1 is the text, #2 is the section level (sec/subsec/subsubsec), #3 is
-% the section type for xrefs (Ynumbered, Ynothing, Yappendix), #4 is the
-% section number.
-%
-\def\seckeyword{sec}
-%
-\def\sectionheading#1#2#3#4{%
- {%
- % Switch to the right set of fonts.
- \csname #2fonts\endcsname \rm
- %
- \def\sectionlevel{#2}%
- \def\temptype{#3}%
- %
- % Insert first mark before the heading break (see notes for \domark).
- \let\prevsectiondefs=\lastsectiondefs
- \ifx\temptype\Ynothingkeyword
- \ifx\sectionlevel\seckeyword
- \gdef\lastsectiondefs{\gdef\thissectionname{#1}\gdef\thissectionnum{}%
- \gdef\thissection{\thissectionname}}%
- \fi
- \else\ifx\temptype\Yomitfromtockeyword
- % Don't redefine \thissection.
- \else\ifx\temptype\Yappendixkeyword
- \ifx\sectionlevel\seckeyword
- \toks0={#1}%
- \xdef\lastsectiondefs{%
- \gdef\noexpand\thissectionname{\the\toks0}%
- \gdef\noexpand\thissectionnum{#4}%
- \gdef\noexpand\thissection{\putwordSection{} \noexpand\thissectionnum:
- \noexpand\thissectionname}%
- }%
- \fi
- \else
- \ifx\sectionlevel\seckeyword
- \toks0={#1}%
- \xdef\lastsectiondefs{%
- \gdef\noexpand\thissectionname{\the\toks0}%
- \gdef\noexpand\thissectionnum{#4}%
- \gdef\noexpand\thissection{\putwordSection{} \noexpand\thissectionnum:
- \noexpand\thissectionname}%
- }%
- \fi
- \fi\fi\fi
- %
- % Output the mark. Pass it through \safewhatsit, to take care of
- % the preceding space.
- \safewhatsit\domark
- %
- % Insert space above the heading.
- \csname #2headingbreak\endcsname
- %
- % Now the second mark, after the heading break. No break points
- % between here and the heading.
- \let\prevsectiondefs=\lastsectiondefs
- \domark
- %
- % Only insert the space after the number if we have a section number.
- \ifx\temptype\Ynothingkeyword
- \setbox0 = \hbox{}%
- \def\toctype{unn}%
- \gdef\lastsection{#1}%
- \else\ifx\temptype\Yomitfromtockeyword
- % for @headings -- no section number, don't include in toc,
- % and don't redefine \lastsection.
- \setbox0 = \hbox{}%
- \def\toctype{omit}%
- \let\sectionlevel=\empty
- \else\ifx\temptype\Yappendixkeyword
- \setbox0 = \hbox{#4\enspace}%
- \def\toctype{app}%
- \gdef\lastsection{#1}%
- \else
- \setbox0 = \hbox{#4\enspace}%
- \def\toctype{num}%
- \gdef\lastsection{#1}%
- \fi\fi\fi
- %
- % Write the toc entry (before \donoderef). See comments in \chapmacro.
- \writetocentry{\toctype\sectionlevel}{#1}{#4}%
- %
- % Write the node reference (= pdf destination for pdftex).
- % Again, see comments in \chapmacro.
- \donoderef{#3}%
- %
- % Interline glue will be inserted when the vbox is completed.
- % That glue will be a valid breakpoint for the page, since it'll be
- % preceded by a whatsit (usually from the \donoderef, or from the
- % \writetocentry if there was no node). We don't want to allow that
- % break, since then the whatsits could end up on page n while the
- % section is on page n+1, thus toc/etc. are wrong. Debian bug 276000.
- \nobreak
- %
- % Output the actual section heading.
- \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright
- \hangindent=\wd0 % zero if no section number
- \unhbox0 #1}%
- }%
- % Add extra space after the heading -- half of whatever came above it.
- % Don't allow stretch, though.
- \kern .5 \csname #2headingskip\endcsname
- %
- % Do not let the kern be a potential breakpoint, as it would be if it
- % was followed by glue.
- \nobreak
- %
- % We'll almost certainly start a paragraph next, so don't let that
- % glue accumulate. (Not a breakpoint because it's preceded by a
- % discardable item.)
- \vskip-\parskip
- %
- % This is purely so the last item on the list is a known \penalty >
- % 10000. This is so \startdefun can avoid allowing breakpoints after
- % section headings. Otherwise, it would insert a valid breakpoint between:
- %
- % @section sec-whatever
- % @deffn def-whatever
- \penalty 10001
-}
-
-
-\message{toc,}
-% Table of contents.
-\newwrite\tocfile
-
-% Write an entry to the toc file, opening it if necessary.
-% Called from @chapter, etc.
-%
-% Example usage: \writetocentry{sec}{Section Name}{\the\chapno.\the\secno}
-% We append the current node name (if any) and page number as additional
-% arguments for the \{chap,sec,...}entry macros which will eventually
-% read this. The node name is used in the pdf outlines as the
-% destination to jump to.
-%
-% We open the .toc file for writing here instead of at @setfilename (or
-% any other fixed time) so that @contents can be anywhere in the document.
-% But if #1 is `omit', then we don't do anything. This is used for the
-% table of contents chapter openings themselves.
-%
-\newif\iftocfileopened
-\def\omitkeyword{omit}%
-%
-\def\writetocentry#1#2#3{%
- \edef\writetoctype{#1}%
- \ifx\writetoctype\omitkeyword \else
- \iftocfileopened\else
- \immediate\openout\tocfile = \jobname.toc
- \global\tocfileopenedtrue
- \fi
- %
- \iflinks
- {\atdummies
- \edef\temp{%
- \write\tocfile{@#1entry{#2}{#3}{\lastnode}{\noexpand\folio}}}%
- \temp
- }%
- \fi
- \fi
- %
- % Tell \shipout to create a pdf destination on each page, if we're
- % writing pdf. These are used in the table of contents. We can't
- % just write one on every page because the title pages are numbered
- % 1 and 2 (the page numbers aren't printed), and so are the first
- % two pages of the document. Thus, we'd have two destinations named
- % `1', and two named `2'.
- \ifpdf \global\pdfmakepagedesttrue \fi
-}
-
-
-% These characters do not print properly in the Computer Modern roman
-% fonts, so we must take special care. This is more or less redundant
-% with the Texinfo input format setup at the end of this file.
-%
-\def\activecatcodes{%
- \catcode`\"=\active
- \catcode`\$=\active
- \catcode`\<=\active
- \catcode`\>=\active
- \catcode`\\=\active
- \catcode`\^=\active
- \catcode`\_=\active
- \catcode`\|=\active
- \catcode`\~=\active
-}
-
-
-% Read the toc file, which is essentially Texinfo input.
-\def\readtocfile{%
- \setupdatafile
- \activecatcodes
- \input \tocreadfilename
-}
-
-\newskip\contentsrightmargin \contentsrightmargin=1in
-\newcount\savepageno
-\newcount\lastnegativepageno \lastnegativepageno = -1
-
-% Prepare to read what we've written to \tocfile.
-%
-\def\startcontents#1{%
- % If @setchapternewpage on, and @headings double, the contents should
- % start on an odd page, unlike chapters. Thus, we maintain
- % \contentsalignmacro in parallel with \pagealignmacro.
- % From: Torbjorn Granlund
- \contentsalignmacro
- \immediate\closeout\tocfile
- %
- % Don't need to put `Contents' or `Short Contents' in the headline.
- % It is abundantly clear what they are.
- \chapmacro{#1}{Yomitfromtoc}{}%
- %
- \savepageno = \pageno
- \begingroup % Set up to handle contents files properly.
- \raggedbottom % Worry more about breakpoints than the bottom.
- \advance\hsize by -\contentsrightmargin % Don't use the full line length.
- %
- % Roman numerals for page numbers.
- \ifnum \pageno>0 \global\pageno = \lastnegativepageno \fi
-}
-
-% redefined for the two-volume lispref. We always output on
-% \jobname.toc even if this is redefined.
-%
-\def\tocreadfilename{\jobname.toc}
-
-% Normal (long) toc.
-%
-\def\contents{%
- \startcontents{\putwordTOC}%
- \openin 1 \tocreadfilename\space
- \ifeof 1 \else
- \readtocfile
- \fi
- \vfill \eject
- \contentsalignmacro % in case @setchapternewpage odd is in effect
- \ifeof 1 \else
- \pdfmakeoutlines
- \fi
- \closein 1
- \endgroup
- \lastnegativepageno = \pageno
- \global\pageno = \savepageno
-}
-
-% And just the chapters.
-\def\summarycontents{%
- \startcontents{\putwordShortTOC}%
- %
- \let\numchapentry = \shortchapentry
- \let\appentry = \shortchapentry
- \let\unnchapentry = \shortunnchapentry
- % We want a true roman here for the page numbers.
- \secfonts
- \let\rm=\shortcontrm \let\bf=\shortcontbf
- \let\sl=\shortcontsl \let\tt=\shortconttt
- \rm
- \hyphenpenalty = 10000
- \advance\baselineskip by 1pt % Open it up a little.
- \def\numsecentry##1##2##3##4{}
- \let\appsecentry = \numsecentry
- \let\unnsecentry = \numsecentry
- \let\numsubsecentry = \numsecentry
- \let\appsubsecentry = \numsecentry
- \let\unnsubsecentry = \numsecentry
- \let\numsubsubsecentry = \numsecentry
- \let\appsubsubsecentry = \numsecentry
- \let\unnsubsubsecentry = \numsecentry
- \openin 1 \tocreadfilename\space
- \ifeof 1 \else
- \readtocfile
- \fi
- \closein 1
- \vfill \eject
- \contentsalignmacro % in case @setchapternewpage odd is in effect
- \endgroup
- \lastnegativepageno = \pageno
- \global\pageno = \savepageno
-}
-\let\shortcontents = \summarycontents
-
-% Typeset the label for a chapter or appendix for the short contents.
-% The arg is, e.g., `A' for an appendix, or `3' for a chapter.
-%
-\def\shortchaplabel#1{%
- % This space should be enough, since a single number is .5em, and the
- % widest letter (M) is 1em, at least in the Computer Modern fonts.
- % But use \hss just in case.
- % (This space doesn't include the extra space that gets added after
- % the label; that gets put in by \shortchapentry above.)
- %
- % We'd like to right-justify chapter numbers, but that looks strange
- % with appendix letters. And right-justifying numbers and
- % left-justifying letters looks strange when there is less than 10
- % chapters. Have to read the whole toc once to know how many chapters
- % there are before deciding ...
- \hbox to 1em{#1\hss}%
-}
-
-% These macros generate individual entries in the table of contents.
-% The first argument is the chapter or section name.
-% The last argument is the page number.
-% The arguments in between are the chapter number, section number, ...
-
-% Chapters, in the main contents.
-\def\numchapentry#1#2#3#4{\dochapentry{#2\labelspace#1}{#4}}
-%
-% Chapters, in the short toc.
-% See comments in \dochapentry re vbox and related settings.
-\def\shortchapentry#1#2#3#4{%
- \tocentry{\shortchaplabel{#2}\labelspace #1}{\doshortpageno\bgroup#4\egroup}%
-}
-
-% Appendices, in the main contents.
-% Need the word Appendix, and a fixed-size box.
-%
-\def\appendixbox#1{%
- % We use M since it's probably the widest letter.
- \setbox0 = \hbox{\putwordAppendix{} M}%
- \hbox to \wd0{\putwordAppendix{} #1\hss}}
-%
-\def\appentry#1#2#3#4{\dochapentry{\appendixbox{#2}\labelspace#1}{#4}}
-
-% Unnumbered chapters.
-\def\unnchapentry#1#2#3#4{\dochapentry{#1}{#4}}
-\def\shortunnchapentry#1#2#3#4{\tocentry{#1}{\doshortpageno\bgroup#4\egroup}}
-
-% Sections.
-\def\numsecentry#1#2#3#4{\dosecentry{#2\labelspace#1}{#4}}
-\let\appsecentry=\numsecentry
-\def\unnsecentry#1#2#3#4{\dosecentry{#1}{#4}}
-
-% Subsections.
-\def\numsubsecentry#1#2#3#4{\dosubsecentry{#2\labelspace#1}{#4}}
-\let\appsubsecentry=\numsubsecentry
-\def\unnsubsecentry#1#2#3#4{\dosubsecentry{#1}{#4}}
-
-% And subsubsections.
-\def\numsubsubsecentry#1#2#3#4{\dosubsubsecentry{#2\labelspace#1}{#4}}
-\let\appsubsubsecentry=\numsubsubsecentry
-\def\unnsubsubsecentry#1#2#3#4{\dosubsubsecentry{#1}{#4}}
-
-% This parameter controls the indentation of the various levels.
-% Same as \defaultparindent.
-\newdimen\tocindent \tocindent = 15pt
-
-% Now for the actual typesetting. In all these, #1 is the text and #2 is the
-% page number.
-%
-% If the toc has to be broken over pages, we want it to be at chapters
-% if at all possible; hence the \penalty.
-\def\dochapentry#1#2{%
- \penalty-300 \vskip1\baselineskip plus.33\baselineskip minus.25\baselineskip
- \begingroup
- \chapentryfonts
- \tocentry{#1}{\dopageno\bgroup#2\egroup}%
- \endgroup
- \nobreak\vskip .25\baselineskip plus.1\baselineskip
-}
-
-\def\dosecentry#1#2{\begingroup
- \secentryfonts \leftskip=\tocindent
- \tocentry{#1}{\dopageno\bgroup#2\egroup}%
-\endgroup}
-
-\def\dosubsecentry#1#2{\begingroup
- \subsecentryfonts \leftskip=2\tocindent
- \tocentry{#1}{\dopageno\bgroup#2\egroup}%
-\endgroup}
-
-\def\dosubsubsecentry#1#2{\begingroup
- \subsubsecentryfonts \leftskip=3\tocindent
- \tocentry{#1}{\dopageno\bgroup#2\egroup}%
-\endgroup}
-
-% We use the same \entry macro as for the index entries.
-\let\tocentry = \entry
-
-% Space between chapter (or whatever) number and the title.
-\def\labelspace{\hskip1em \relax}
-
-\def\dopageno#1{{\rm #1}}
-\def\doshortpageno#1{{\rm #1}}
-
-\def\chapentryfonts{\secfonts \rm}
-\def\secentryfonts{\textfonts}
-\def\subsecentryfonts{\textfonts}
-\def\subsubsecentryfonts{\textfonts}
-
-
-\message{environments,}
-% @foo ... @end foo.
-
-% @point{}, @result{}, @expansion{}, @print{}, @equiv{}.
-%
-% Since these characters are used in examples, they should be an even number of
-% \tt widths. Each \tt character is 1en, so two makes it 1em.
-%
-\def\point{$\star$}
-\def\arrow{\leavevmode\raise.05ex\hbox to 1em{\hfil$\rightarrow$\hfil}}
-\def\result{\leavevmode\raise.05ex\hbox to 1em{\hfil$\Rightarrow$\hfil}}
-\def\expansion{\leavevmode\hbox to 1em{\hfil$\mapsto$\hfil}}
-\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}}
-\def\equiv{\leavevmode\hbox to 1em{\hfil$\ptexequiv$\hfil}}
-
-% The @error{} command.
-% Adapted from the TeXbook's \boxit.
-%
-\newbox\errorbox
-%
-{\tentt \global\dimen0 = 3em}% Width of the box.
-\dimen2 = .55pt % Thickness of rules
-% The text. (`r' is open on the right, `e' somewhat less so on the left.)
-\setbox0 = \hbox{\kern-.75pt \reducedsf error\kern-1.5pt}
-%
-\setbox\errorbox=\hbox to \dimen0{\hfil
- \hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right.
- \advance\hsize by -2\dimen2 % Rules.
- \vbox{%
- \hrule height\dimen2
- \hbox{\vrule width\dimen2 \kern3pt % Space to left of text.
- \vtop{\kern2.4pt \box0 \kern2.4pt}% Space above/below.
- \kern3pt\vrule width\dimen2}% Space to right.
- \hrule height\dimen2}
- \hfil}
-%
-\def\error{\leavevmode\lower.7ex\copy\errorbox}
-
-% @tex ... @end tex escapes into raw Tex temporarily.
-% One exception: @ is still an escape character, so that @end tex works.
-% But \@ or @@ will get a plain tex @ character.
-
-\envdef\tex{%
- \catcode `\\=0 \catcode `\{=1 \catcode `\}=2
- \catcode `\$=3 \catcode `\&=4 \catcode `\#=6
- \catcode `\^=7 \catcode `\_=8 \catcode `\~=\active \let~=\tie
- \catcode `\%=14
- \catcode `\+=\other
- \catcode `\"=\other
- \catcode `\|=\other
- \catcode `\<=\other
- \catcode `\>=\other
- \escapechar=`\\
- %
- \let\b=\ptexb
- \let\bullet=\ptexbullet
- \let\c=\ptexc
- \let\,=\ptexcomma
- \let\.=\ptexdot
- \let\dots=\ptexdots
- \let\equiv=\ptexequiv
- \let\!=\ptexexclam
- \let\i=\ptexi
- \let\indent=\ptexindent
- \let\noindent=\ptexnoindent
- \let\{=\ptexlbrace
- \let\+=\tabalign
- \let\}=\ptexrbrace
- \let\/=\ptexslash
- \let\*=\ptexstar
- \let\t=\ptext
- \expandafter \let\csname top\endcsname=\ptextop % outer
- \let\frenchspacing=\plainfrenchspacing
- %
- \def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}%
- \def\enddots{\relax\ifmmode\endldots\else$\mathsurround=0pt \endldots\,$\fi}%
- \def\@{@}%
-}
-% There is no need to define \Etex.
-
-% Define @lisp ... @end lisp.
-% @lisp environment forms a group so it can rebind things,
-% including the definition of @end lisp (which normally is erroneous).
-
-% Amount to narrow the margins by for @lisp.
-\newskip\lispnarrowing \lispnarrowing=0.4in
-
-% This is the definition that ^^M gets inside @lisp, @example, and other
-% such environments. \null is better than a space, since it doesn't
-% have any width.
-\def\lisppar{\null\endgraf}
-
-% This space is always present above and below environments.
-\newskip\envskipamount \envskipamount = 0pt
-
-% Make spacing and below environment symmetrical. We use \parskip here
-% to help in doing that, since in @example-like environments \parskip
-% is reset to zero; thus the \afterenvbreak inserts no space -- but the
-% start of the next paragraph will insert \parskip.
-%
-\def\aboveenvbreak{{%
- % =10000 instead of <10000 because of a special case in \itemzzz and
- % \sectionheading, q.v.
- \ifnum \lastpenalty=10000 \else
- \advance\envskipamount by \parskip
- \endgraf
- \ifdim\lastskip<\envskipamount
- \removelastskip
- % it's not a good place to break if the last penalty was \nobreak
- % or better ...
- \ifnum\lastpenalty<10000 \penalty-50 \fi
- \vskip\envskipamount
- \fi
- \fi
-}}
-
-\let\afterenvbreak = \aboveenvbreak
-
-% \nonarrowing is a flag. If "set", @lisp etc don't narrow margins; it will
-% also clear it, so that its embedded environments do the narrowing again.
-\let\nonarrowing=\relax
-
-% @cartouche ... @end cartouche: draw rectangle w/rounded corners around
-% environment contents.
-\font\circle=lcircle10
-\newdimen\circthick
-\newdimen\cartouter\newdimen\cartinner
-\newskip\normbskip\newskip\normpskip\newskip\normlskip
-\circthick=\fontdimen8\circle
-%
-\def\ctl{{\circle\char'013\hskip -6pt}}% 6pt from pl file: 1/2charwidth
-\def\ctr{{\hskip 6pt\circle\char'010}}
-\def\cbl{{\circle\char'012\hskip -6pt}}
-\def\cbr{{\hskip 6pt\circle\char'011}}
-\def\carttop{\hbox to \cartouter{\hskip\lskip
- \ctl\leaders\hrule height\circthick\hfil\ctr
- \hskip\rskip}}
-\def\cartbot{\hbox to \cartouter{\hskip\lskip
- \cbl\leaders\hrule height\circthick\hfil\cbr
- \hskip\rskip}}
-%
-\newskip\lskip\newskip\rskip
-
-\envdef\cartouche{%
- \ifhmode\par\fi % can't be in the midst of a paragraph.
- \startsavinginserts
- \lskip=\leftskip \rskip=\rightskip
- \leftskip=0pt\rightskip=0pt % we want these *outside*.
- \cartinner=\hsize \advance\cartinner by-\lskip
- \advance\cartinner by-\rskip
- \cartouter=\hsize
- \advance\cartouter by 18.4pt % allow for 3pt kerns on either
- % side, and for 6pt waste from
- % each corner char, and rule thickness
- \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip
- % Flag to tell @lisp, etc., not to narrow margin.
- \let\nonarrowing = t%
- \vbox\bgroup
- \baselineskip=0pt\parskip=0pt\lineskip=0pt
- \carttop
- \hbox\bgroup
- \hskip\lskip
- \vrule\kern3pt
- \vbox\bgroup
- \kern3pt
- \hsize=\cartinner
- \baselineskip=\normbskip
- \lineskip=\normlskip
- \parskip=\normpskip
- \vskip -\parskip
- \comment % For explanation, see the end of \def\group.
-}
-\def\Ecartouche{%
- \ifhmode\par\fi
- \kern3pt
- \egroup
- \kern3pt\vrule
- \hskip\rskip
- \egroup
- \cartbot
- \egroup
- \checkinserts
-}
-
-
-% This macro is called at the beginning of all the @example variants,
-% inside a group.
-\def\nonfillstart{%
- \aboveenvbreak
- \hfuzz = 12pt % Don't be fussy
- \sepspaces % Make spaces be word-separators rather than space tokens.
- \let\par = \lisppar % don't ignore blank lines
- \obeylines % each line of input is a line of output
- \parskip = 0pt
- \parindent = 0pt
- \emergencystretch = 0pt % don't try to avoid overfull boxes
- \ifx\nonarrowing\relax
- \advance \leftskip by \lispnarrowing
- \exdentamount=\lispnarrowing
- \else
- \let\nonarrowing = \relax
- \fi
- \let\exdent=\nofillexdent
-}
-
-% If you want all examples etc. small: @set dispenvsize small.
-% If you want even small examples the full size: @set dispenvsize nosmall.
-% This affects the following displayed environments:
-% @example, @display, @format, @lisp
-%
-\def\smallword{small}
-\def\nosmallword{nosmall}
-\let\SETdispenvsize\relax
-\def\setnormaldispenv{%
- \ifx\SETdispenvsize\smallword
- % end paragraph for sake of leading, in case document has no blank
- % line. This is redundant with what happens in \aboveenvbreak, but
- % we need to do it before changing the fonts, and it's inconvenient
- % to change the fonts afterward.
- \ifnum \lastpenalty=10000 \else \endgraf \fi
- \smallexamplefonts \rm
- \fi
-}
-\def\setsmalldispenv{%
- \ifx\SETdispenvsize\nosmallword
- \else
- \ifnum \lastpenalty=10000 \else \endgraf \fi
- \smallexamplefonts \rm
- \fi
-}
-
-% We often define two environments, @foo and @smallfoo.
-% Let's do it by one command:
-\def\makedispenv #1#2{
- \expandafter\envdef\csname#1\endcsname {\setnormaldispenv #2}
- \expandafter\envdef\csname small#1\endcsname {\setsmalldispenv #2}
- \expandafter\let\csname E#1\endcsname \afterenvbreak
- \expandafter\let\csname Esmall#1\endcsname \afterenvbreak
-}
-
-% Define two synonyms:
-\def\maketwodispenvs #1#2#3{
- \makedispenv{#1}{#3}
- \makedispenv{#2}{#3}
-}
-
-% @lisp: indented, narrowed, typewriter font; @example: same as @lisp.
-%
-% @smallexample and @smalllisp: use smaller fonts.
-% Originally contributed by Pavel@xerox.
-%
-\maketwodispenvs {lisp}{example}{%
- \nonfillstart
- \tt\quoteexpand
- \let\kbdfont = \kbdexamplefont % Allow @kbd to do something special.
- \gobble % eat return
-}
-% @display/@smalldisplay: same as @lisp except keep current font.
-%
-\makedispenv {display}{%
- \nonfillstart
- \gobble
-}
-
-% @format/@smallformat: same as @display except don't narrow margins.
-%
-\makedispenv{format}{%
- \let\nonarrowing = t%
- \nonfillstart
- \gobble
-}
-
-% @flushleft: same as @format, but doesn't obey \SETdispenvsize.
-\envdef\flushleft{%
- \let\nonarrowing = t%
- \nonfillstart
- \gobble
-}
-\let\Eflushleft = \afterenvbreak
-
-% @flushright.
-%
-\envdef\flushright{%
- \let\nonarrowing = t%
- \nonfillstart
- \advance\leftskip by 0pt plus 1fill
- \gobble
-}
-\let\Eflushright = \afterenvbreak
-
-
-% @quotation does normal linebreaking (hence we can't use \nonfillstart)
-% and narrows the margins. We keep \parskip nonzero in general, since
-% we're doing normal filling. So, when using \aboveenvbreak and
-% \afterenvbreak, temporarily make \parskip 0.
-%
-\envdef\quotation{%
- {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip
- \parindent=0pt
- %
- % @cartouche defines \nonarrowing to inhibit narrowing at next level down.
- \ifx\nonarrowing\relax
- \advance\leftskip by \lispnarrowing
- \advance\rightskip by \lispnarrowing
- \exdentamount = \lispnarrowing
- \else
- \let\nonarrowing = \relax
- \fi
- \parsearg\quotationlabel
-}
-
-% We have retained a nonzero parskip for the environment, since we're
-% doing normal filling.
-%
-\def\Equotation{%
- \par
- \ifx\quotationauthor\undefined\else
- % indent a bit.
- \leftline{\kern 2\leftskip \sl ---\quotationauthor}%
- \fi
- {\parskip=0pt \afterenvbreak}%
-}
-
-% If we're given an argument, typeset it in bold with a colon after.
-\def\quotationlabel#1{%
- \def\temp{#1}%
- \ifx\temp\empty \else
- {\bf #1: }%
- \fi
-}
-
-
-% LaTeX-like @verbatim...@end verbatim and @verb{...}
-% If we want to allow any as delimiter,
-% we need the curly braces so that makeinfo sees the @verb command, eg:
-% `@verbx...x' would look like the '@verbx' command. --janneke@gnu.org
-%
-% [Knuth]: Donald Ervin Knuth, 1996. The TeXbook.
-%
-% [Knuth] p.344; only we need to do the other characters Texinfo sets
-% active too. Otherwise, they get lost as the first character on a
-% verbatim line.
-\def\dospecials{%
- \do\ \do\\\do\{\do\}\do\$\do\&%
- \do\#\do\^\do\^^K\do\_\do\^^A\do\%\do\~%
- \do\<\do\>\do\|\do\@\do+\do\"%
-}
-%
-% [Knuth] p. 380
-\def\uncatcodespecials{%
- \def\do##1{\catcode`##1=\other}\dospecials}
-%
-% [Knuth] pp. 380,381,391
-% Disable Spanish ligatures ?` and !` of \tt font
-\begingroup
- \catcode`\`=\active\gdef`{\relax\lq}
-\endgroup
-%
-% Setup for the @verb command.
-%
-% Eight spaces for a tab
-\begingroup
- \catcode`\^^I=\active
- \gdef\tabeightspaces{\catcode`\^^I=\active\def^^I{\ \ \ \ \ \ \ \ }}
-\endgroup
-%
-\def\setupverb{%
- \tt % easiest (and conventionally used) font for verbatim
- \def\par{\leavevmode\endgraf}%
- \catcode`\`=\active
- \tabeightspaces
- % Respect line breaks,
- % print special symbols as themselves, and
- % make each space count
- % must do in this order:
- \obeylines \uncatcodespecials \sepspaces
-}
-
-% Setup for the @verbatim environment
-%
-% Real tab expansion
-\newdimen\tabw \setbox0=\hbox{\tt\space} \tabw=8\wd0 % tab amount
-%
-\def\starttabbox{\setbox0=\hbox\bgroup}
-
-% Allow an option to not replace quotes with a regular directed right
-% quote/apostrophe (char 0x27), but instead use the undirected quote
-% from cmtt (char 0x0d). The undirected quote is ugly, so don't make it
-% the default, but it works for pasting with more pdf viewers (at least
-% evince), the lilypond developers report. xpdf does work with the
-% regular 0x27.
-%
-\def\codequoteright{%
- \expandafter\ifx\csname SETtxicodequoteundirected\endcsname\relax
- \expandafter\ifx\csname SETcodequoteundirected\endcsname\relax
- '%
- \else \char'15 \fi
- \else \char'15 \fi
-}
-%
-% and a similar option for the left quote char vs. a grave accent.
-% Modern fonts display ASCII 0x60 as a grave accent, so some people like
-% the code environments to do likewise.
-%
-\def\codequoteleft{%
- \expandafter\ifx\csname SETtxicodequotebacktick\endcsname\relax
- \expandafter\ifx\csname SETcodequotebacktick\endcsname\relax
- `%
- \else \char'22 \fi
- \else \char'22 \fi
-}
-%
-\begingroup
- \catcode`\^^I=\active
- \gdef\tabexpand{%
- \catcode`\^^I=\active
- \def^^I{\leavevmode\egroup
- \dimen0=\wd0 % the width so far, or since the previous tab
- \divide\dimen0 by\tabw
- \multiply\dimen0 by\tabw % compute previous multiple of \tabw
- \advance\dimen0 by\tabw % advance to next multiple of \tabw
- \wd0=\dimen0 \box0 \starttabbox
- }%
- }
- \catcode`\'=\active
- \gdef\rquoteexpand{\catcode\rquoteChar=\active \def'{\codequoteright}}%
- %
- \catcode`\`=\active
- \gdef\lquoteexpand{\catcode\lquoteChar=\active \def`{\codequoteleft}}%
- %
- \gdef\quoteexpand{\rquoteexpand \lquoteexpand}%
-\endgroup
-
-% start the verbatim environment.
-\def\setupverbatim{%
- \let\nonarrowing = t%
- \nonfillstart
- % Easiest (and conventionally used) font for verbatim
- \tt
- \def\par{\leavevmode\egroup\box0\endgraf}%
- \catcode`\`=\active
- \tabexpand
- \quoteexpand
- % Respect line breaks,
- % print special symbols as themselves, and
- % make each space count
- % must do in this order:
- \obeylines \uncatcodespecials \sepspaces
- \everypar{\starttabbox}%
-}
-
-% Do the @verb magic: verbatim text is quoted by unique
-% delimiter characters. Before first delimiter expect a
-% right brace, after last delimiter expect closing brace:
-%
-% \def\doverb'{'#1'}'{#1}
-%
-% [Knuth] p. 382; only eat outer {}
-\begingroup
- \catcode`[=1\catcode`]=2\catcode`\{=\other\catcode`\}=\other
- \gdef\doverb{#1[\def\next##1#1}[##1\endgroup]\next]
-\endgroup
-%
-\def\verb{\begingroup\setupverb\doverb}
-%
-%
-% Do the @verbatim magic: define the macro \doverbatim so that
-% the (first) argument ends when '@end verbatim' is reached, ie:
-%
-% \def\doverbatim#1@end verbatim{#1}
-%
-% For Texinfo it's a lot easier than for LaTeX,
-% because texinfo's \verbatim doesn't stop at '\end{verbatim}':
-% we need not redefine '\', '{' and '}'.
-%
-% Inspired by LaTeX's verbatim command set [latex.ltx]
-%
-\begingroup
- \catcode`\ =\active
- \obeylines %
- % ignore everything up to the first ^^M, that's the newline at the end
- % of the @verbatim input line itself. Otherwise we get an extra blank
- % line in the output.
- \xdef\doverbatim#1^^M#2@end verbatim{#2\noexpand\end\gobble verbatim}%
- % We really want {...\end verbatim} in the body of the macro, but
- % without the active space; thus we have to use \xdef and \gobble.
-\endgroup
-%
-\envdef\verbatim{%
- \setupverbatim\doverbatim
-}
-\let\Everbatim = \afterenvbreak
-
-
-% @verbatiminclude FILE - insert text of file in verbatim environment.
-%
-\def\verbatiminclude{\parseargusing\filenamecatcodes\doverbatiminclude}
-%
-\def\doverbatiminclude#1{%
- {%
- \makevalueexpandable
- \setupverbatim
- \input #1
- \afterenvbreak
- }%
-}
-
-% @copying ... @end copying.
-% Save the text away for @insertcopying later.
-%
-% We save the uninterpreted tokens, rather than creating a box.
-% Saving the text in a box would be much easier, but then all the
-% typesetting commands (@smallbook, font changes, etc.) have to be done
-% beforehand -- and a) we want @copying to be done first in the source
-% file; b) letting users define the frontmatter in as flexible order as
-% possible is very desirable.
-%
-\def\copying{\checkenv{}\begingroup\scanargctxt\docopying}
-\def\docopying#1@end copying{\endgroup\def\copyingtext{#1}}
-%
-\def\insertcopying{%
- \begingroup
- \parindent = 0pt % paragraph indentation looks wrong on title page
- \scanexp\copyingtext
- \endgroup
-}
-
-
-\message{defuns,}
-% @defun etc.
-
-\newskip\defbodyindent \defbodyindent=.4in
-\newskip\defargsindent \defargsindent=50pt
-\newskip\deflastargmargin \deflastargmargin=18pt
-\newcount\defunpenalty
-
-% Start the processing of @deffn:
-\def\startdefun{%
- \ifnum\lastpenalty<10000
- \medbreak
- \defunpenalty=10003 % Will keep this @deffn together with the
- % following @def command, see below.
- \else
- % If there are two @def commands in a row, we'll have a \nobreak,
- % which is there to keep the function description together with its
- % header. But if there's nothing but headers, we need to allow a
- % break somewhere. Check specifically for penalty 10002, inserted
- % by \printdefunline, instead of 10000, since the sectioning
- % commands also insert a nobreak penalty, and we don't want to allow
- % a break between a section heading and a defun.
- %
- % As a minor refinement, we avoid "club" headers by signalling
- % with penalty of 10003 after the very first @deffn in the
- % sequence (see above), and penalty of 10002 after any following
- % @def command.
- \ifnum\lastpenalty=10002 \penalty2000 \else \defunpenalty=10002 \fi
- %
- % Similarly, after a section heading, do not allow a break.
- % But do insert the glue.
- \medskip % preceded by discardable penalty, so not a breakpoint
- \fi
- %
- \parindent=0in
- \advance\leftskip by \defbodyindent
- \exdentamount=\defbodyindent
-}
-
-\def\dodefunx#1{%
- % First, check whether we are in the right environment:
- \checkenv#1%
- %
- % As above, allow line break if we have multiple x headers in a row.
- % It's not a great place, though.
- \ifnum\lastpenalty=10002 \penalty3000 \else \defunpenalty=10002 \fi
- %
- % And now, it's time to reuse the body of the original defun:
- \expandafter\gobbledefun#1%
-}
-\def\gobbledefun#1\startdefun{}
-
-% \printdefunline \deffnheader{text}
-%
-\def\printdefunline#1#2{%
- \begingroup
- % call \deffnheader:
- #1#2 \endheader
- % common ending:
- \interlinepenalty = 10000
- \advance\rightskip by 0pt plus 1fil
- \endgraf
- \nobreak\vskip -\parskip
- \penalty\defunpenalty % signal to \startdefun and \dodefunx
- % Some of the @defun-type tags do not enable magic parentheses,
- % rendering the following check redundant. But we don't optimize.
- \checkparencounts
- \endgroup
-}
-
-\def\Edefun{\endgraf\medbreak}
-
-% \makedefun{deffn} creates \deffn, \deffnx and \Edeffn;
-% the only thing remaining is to define \deffnheader.
-%
-\def\makedefun#1{%
- \expandafter\let\csname E#1\endcsname = \Edefun
- \edef\temp{\noexpand\domakedefun
- \makecsname{#1}\makecsname{#1x}\makecsname{#1header}}%
- \temp
-}
-
-% \domakedefun \deffn \deffnx \deffnheader
-%
-% Define \deffn and \deffnx, without parameters.
-% \deffnheader has to be defined explicitly.
-%
-\def\domakedefun#1#2#3{%
- \envdef#1{%
- \startdefun
- \parseargusing\activeparens{\printdefunline#3}%
- }%
- \def#2{\dodefunx#1}%
- \def#3%
-}
-
-%%% Untyped functions:
-
-% @deffn category name args
-\makedefun{deffn}{\deffngeneral{}}
-
-% @deffn category class name args
-\makedefun{defop}#1 {\defopon{#1\ \putwordon}}
-
-% \defopon {category on}class name args
-\def\defopon#1#2 {\deffngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} }
-
-% \deffngeneral {subind}category name args
-%
-\def\deffngeneral#1#2 #3 #4\endheader{%
- % Remember that \dosubind{fn}{foo}{} is equivalent to \doind{fn}{foo}.
- \dosubind{fn}{\code{#3}}{#1}%
- \defname{#2}{}{#3}\magicamp\defunargs{#4\unskip}%
-}
-
-%%% Typed functions:
-
-% @deftypefn category type name args
-\makedefun{deftypefn}{\deftypefngeneral{}}
-
-% @deftypeop category class type name args
-\makedefun{deftypeop}#1 {\deftypeopon{#1\ \putwordon}}
-
-% \deftypeopon {category on}class type name args
-\def\deftypeopon#1#2 {\deftypefngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} }
-
-% \deftypefngeneral {subind}category type name args
-%
-\def\deftypefngeneral#1#2 #3 #4 #5\endheader{%
- \dosubind{fn}{\code{#4}}{#1}%
- \defname{#2}{#3}{#4}\defunargs{#5\unskip}%
-}
-
-%%% Typed variables:
-
-% @deftypevr category type var args
-\makedefun{deftypevr}{\deftypecvgeneral{}}
-
-% @deftypecv category class type var args
-\makedefun{deftypecv}#1 {\deftypecvof{#1\ \putwordof}}
-
-% \deftypecvof {category of}class type var args
-\def\deftypecvof#1#2 {\deftypecvgeneral{\putwordof\ \code{#2}}{#1\ \code{#2}} }
-
-% \deftypecvgeneral {subind}category type var args
-%
-\def\deftypecvgeneral#1#2 #3 #4 #5\endheader{%
- \dosubind{vr}{\code{#4}}{#1}%
- \defname{#2}{#3}{#4}\defunargs{#5\unskip}%
-}
-
-%%% Untyped variables:
-
-% @defvr category var args
-\makedefun{defvr}#1 {\deftypevrheader{#1} {} }
-
-% @defcv category class var args
-\makedefun{defcv}#1 {\defcvof{#1\ \putwordof}}
-
-% \defcvof {category of}class var args
-\def\defcvof#1#2 {\deftypecvof{#1}#2 {} }
-
-%%% Type:
-% @deftp category name args
-\makedefun{deftp}#1 #2 #3\endheader{%
- \doind{tp}{\code{#2}}%
- \defname{#1}{}{#2}\defunargs{#3\unskip}%
-}
-
-% Remaining @defun-like shortcuts:
-\makedefun{defun}{\deffnheader{\putwordDeffunc} }
-\makedefun{defmac}{\deffnheader{\putwordDefmac} }
-\makedefun{defspec}{\deffnheader{\putwordDefspec} }
-\makedefun{deftypefun}{\deftypefnheader{\putwordDeffunc} }
-\makedefun{defvar}{\defvrheader{\putwordDefvar} }
-\makedefun{defopt}{\defvrheader{\putwordDefopt} }
-\makedefun{deftypevar}{\deftypevrheader{\putwordDefvar} }
-\makedefun{defmethod}{\defopon\putwordMethodon}
-\makedefun{deftypemethod}{\deftypeopon\putwordMethodon}
-\makedefun{defivar}{\defcvof\putwordInstanceVariableof}
-\makedefun{deftypeivar}{\deftypecvof\putwordInstanceVariableof}
-
-% \defname, which formats the name of the @def (not the args).
-% #1 is the category, such as "Function".
-% #2 is the return type, if any.
-% #3 is the function name.
-%
-% We are followed by (but not passed) the arguments, if any.
-%
-\def\defname#1#2#3{%
- % Get the values of \leftskip and \rightskip as they were outside the @def...
- \advance\leftskip by -\defbodyindent
- %
- % How we'll format the type name. Putting it in brackets helps
- % distinguish it from the body text that may end up on the next line
- % just below it.
- \def\temp{#1}%
- \setbox0=\hbox{\kern\deflastargmargin \ifx\temp\empty\else [\rm\temp]\fi}
- %
- % Figure out line sizes for the paragraph shape.
- % The first line needs space for \box0; but if \rightskip is nonzero,
- % we need only space for the part of \box0 which exceeds it:
- \dimen0=\hsize \advance\dimen0 by -\wd0 \advance\dimen0 by \rightskip
- % The continuations:
- \dimen2=\hsize \advance\dimen2 by -\defargsindent
- % (plain.tex says that \dimen1 should be used only as global.)
- \parshape 2 0in \dimen0 \defargsindent \dimen2
- %
- % Put the type name to the right margin.
- \noindent
- \hbox to 0pt{%
- \hfil\box0 \kern-\hsize
- % \hsize has to be shortened this way:
- \kern\leftskip
- % Intentionally do not respect \rightskip, since we need the space.
- }%
- %
- % Allow all lines to be underfull without complaint:
- \tolerance=10000 \hbadness=10000
- \exdentamount=\defbodyindent
- {%
- % defun fonts. We use typewriter by default (used to be bold) because:
- % . we're printing identifiers, they should be in tt in principle.
- % . in languages with many accents, such as Czech or French, it's
- % common to leave accents off identifiers. The result looks ok in
- % tt, but exceedingly strange in rm.
- % . we don't want -- and --- to be treated as ligatures.
- % . this still does not fix the ?` and !` ligatures, but so far no
- % one has made identifiers using them :).
- \df \tt
- \def\temp{#2}% return value type
- \ifx\temp\empty\else \tclose{\temp} \fi
- #3% output function name
- }%
- {\rm\enskip}% hskip 0.5 em of \tenrm
- %
- \boldbrax
- % arguments will be output next, if any.
-}
-
-% Print arguments in slanted roman (not ttsl), inconsistently with using
-% tt for the name. This is because literal text is sometimes needed in
-% the argument list (groff manual), and ttsl and tt are not very
-% distinguishable. Prevent hyphenation at `-' chars.
-%
-\def\defunargs#1{%
- % use sl by default (not ttsl),
- % tt for the names.
- \df \sl \hyphenchar\font=0
- %
- % On the other hand, if an argument has two dashes (for instance), we
- % want a way to get ttsl. Let's try @var for that.
- \let\var=\ttslanted
- #1%
- \sl\hyphenchar\font=45
-}
-
-% We want ()&[] to print specially on the defun line.
-%
-\def\activeparens{%
- \catcode`\(=\active \catcode`\)=\active
- \catcode`\[=\active \catcode`\]=\active
- \catcode`\&=\active
-}
-
-% Make control sequences which act like normal parenthesis chars.
-\let\lparen = ( \let\rparen = )
-
-% Be sure that we always have a definition for `(', etc. For example,
-% if the fn name has parens in it, \boldbrax will not be in effect yet,
-% so TeX would otherwise complain about undefined control sequence.
-{
- \activeparens
- \global\let(=\lparen \global\let)=\rparen
- \global\let[=\lbrack \global\let]=\rbrack
- \global\let& = \&
-
- \gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb}
- \gdef\magicamp{\let&=\amprm}
-}
-
-\newcount\parencount
-
-% If we encounter &foo, then turn on ()-hacking afterwards
-\newif\ifampseen
-\def\amprm#1 {\ampseentrue{\bf\ }}
-
-\def\parenfont{%
- \ifampseen
- % At the first level, print parens in roman,
- % otherwise use the default font.
- \ifnum \parencount=1 \rm \fi
- \else
- % The \sf parens (in \boldbrax) actually are a little bolder than
- % the contained text. This is especially needed for [ and ] .
- \sf
- \fi
-}
-\def\infirstlevel#1{%
- \ifampseen
- \ifnum\parencount=1
- #1%
- \fi
- \fi
-}
-\def\bfafterword#1 {#1 \bf}
-
-\def\opnr{%
- \global\advance\parencount by 1
- {\parenfont(}%
- \infirstlevel \bfafterword
-}
-\def\clnr{%
- {\parenfont)}%
- \infirstlevel \sl
- \global\advance\parencount by -1
-}
-
-\newcount\brackcount
-\def\lbrb{%
- \global\advance\brackcount by 1
- {\bf[}%
-}
-\def\rbrb{%
- {\bf]}%
- \global\advance\brackcount by -1
-}
-
-\def\checkparencounts{%
- \ifnum\parencount=0 \else \badparencount \fi
- \ifnum\brackcount=0 \else \badbrackcount \fi
-}
-% these should not use \errmessage; the glibc manual, at least, actually
-% has such constructs (when documenting function pointers).
-\def\badparencount{%
- \message{Warning: unbalanced parentheses in @def...}%
- \global\parencount=0
-}
-\def\badbrackcount{%
- \message{Warning: unbalanced square brackets in @def...}%
- \global\brackcount=0
-}
-
-
-\message{macros,}
-% @macro.
-
-% To do this right we need a feature of e-TeX, \scantokens,
-% which we arrange to emulate with a temporary file in ordinary TeX.
-\ifx\eTeXversion\undefined
- \newwrite\macscribble
- \def\scantokens#1{%
- \toks0={#1}%
- \immediate\openout\macscribble=\jobname.tmp
- \immediate\write\macscribble{\the\toks0}%
- \immediate\closeout\macscribble
- \input \jobname.tmp
- }
-\fi
-
-\def\scanmacro#1{%
- \begingroup
- \newlinechar`\^^M
- \let\xeatspaces\eatspaces
- % Undo catcode changes of \startcontents and \doprintindex
- % When called from @insertcopying or (short)caption, we need active
- % backslash to get it printed correctly. Previously, we had
- % \catcode`\\=\other instead. We'll see whether a problem appears
- % with macro expansion. --kasal, 19aug04
- \catcode`\@=0 \catcode`\\=\active \escapechar=`\@
- % ... and \example
- \spaceisspace
- %
- % Append \endinput to make sure that TeX does not see the ending newline.
- % I've verified that it is necessary both for e-TeX and for ordinary TeX
- % --kasal, 29nov03
- \scantokens{#1\endinput}%
- \endgroup
-}
-
-\def\scanexp#1{%
- \edef\temp{\noexpand\scanmacro{#1}}%
- \temp
-}
-
-\newcount\paramno % Count of parameters
-\newtoks\macname % Macro name
-\newif\ifrecursive % Is it recursive?
-
-% List of all defined macros in the form
-% \definedummyword\macro1\definedummyword\macro2...
-% Currently is also contains all @aliases; the list can be split
-% if there is a need.
-\def\macrolist{}
-
-% Add the macro to \macrolist
-\def\addtomacrolist#1{\expandafter \addtomacrolistxxx \csname#1\endcsname}
-\def\addtomacrolistxxx#1{%
- \toks0 = \expandafter{\macrolist\definedummyword#1}%
- \xdef\macrolist{\the\toks0}%
-}
-
-% Utility routines.
-% This does \let #1 = #2, with \csnames; that is,
-% \let \csname#1\endcsname = \csname#2\endcsname
-% (except of course we have to play expansion games).
-%
-\def\cslet#1#2{%
- \expandafter\let
- \csname#1\expandafter\endcsname
- \csname#2\endcsname
-}
-
-% Trim leading and trailing spaces off a string.
-% Concepts from aro-bend problem 15 (see CTAN).
-{\catcode`\@=11
-\gdef\eatspaces #1{\expandafter\trim@\expandafter{#1 }}
-\gdef\trim@ #1{\trim@@ @#1 @ #1 @ @@}
-\gdef\trim@@ #1@ #2@ #3@@{\trim@@@\empty #2 @}
-\def\unbrace#1{#1}
-\unbrace{\gdef\trim@@@ #1 } #2@{#1}
-}
-
-% Trim a single trailing ^^M off a string.
-{\catcode`\^^M=\other \catcode`\Q=3%
-\gdef\eatcr #1{\eatcra #1Q^^MQ}%
-\gdef\eatcra#1^^MQ{\eatcrb#1Q}%
-\gdef\eatcrb#1Q#2Q{#1}%
-}
-
-% Macro bodies are absorbed as an argument in a context where
-% all characters are catcode 10, 11 or 12, except \ which is active
-% (as in normal texinfo). It is necessary to change the definition of \.
-
-% Non-ASCII encodings make 8-bit characters active, so un-activate
-% them to avoid their expansion. Must do this non-globally, to
-% confine the change to the current group.
-
-% It's necessary to have hard CRs when the macro is executed. This is
-% done by making ^^M (\endlinechar) catcode 12 when reading the macro
-% body, and then making it the \newlinechar in \scanmacro.
-
-\def\scanctxt{%
- \catcode`\"=\other
- \catcode`\+=\other
- \catcode`\<=\other
- \catcode`\>=\other
- \catcode`\@=\other
- \catcode`\^=\other
- \catcode`\_=\other
- \catcode`\|=\other
- \catcode`\~=\other
- \ifx\declaredencoding\ascii \else \setnonasciicharscatcodenonglobal\other \fi
-}
-
-\def\scanargctxt{%
- \scanctxt
- \catcode`\\=\other
- \catcode`\^^M=\other
-}
-
-\def\macrobodyctxt{%
- \scanctxt
- \catcode`\{=\other
- \catcode`\}=\other
- \catcode`\^^M=\other
- \usembodybackslash
-}
-
-\def\macroargctxt{%
- \scanctxt
- \catcode`\\=\other
-}
-
-% \mbodybackslash is the definition of \ in @macro bodies.
-% It maps \foo\ => \csname macarg.foo\endcsname => #N
-% where N is the macro parameter number.
-% We define \csname macarg.\endcsname to be \realbackslash, so
-% \\ in macro replacement text gets you a backslash.
-
-{\catcode`@=0 @catcode`@\=@active
- @gdef@usembodybackslash{@let\=@mbodybackslash}
- @gdef@mbodybackslash#1\{@csname macarg.#1@endcsname}
-}
-\expandafter\def\csname macarg.\endcsname{\realbackslash}
-
-\def\macro{\recursivefalse\parsearg\macroxxx}
-\def\rmacro{\recursivetrue\parsearg\macroxxx}
-
-\def\macroxxx#1{%
- \getargs{#1}% now \macname is the macname and \argl the arglist
- \ifx\argl\empty % no arguments
- \paramno=0%
- \else
- \expandafter\parsemargdef \argl;%
- \fi
- \if1\csname ismacro.\the\macname\endcsname
- \message{Warning: redefining \the\macname}%
- \else
- \expandafter\ifx\csname \the\macname\endcsname \relax
- \else \errmessage{Macro name \the\macname\space already defined}\fi
- \global\cslet{macsave.\the\macname}{\the\macname}%
- \global\expandafter\let\csname ismacro.\the\macname\endcsname=1%
- \addtomacrolist{\the\macname}%
- \fi
- \begingroup \macrobodyctxt
- \ifrecursive \expandafter\parsermacbody
- \else \expandafter\parsemacbody
- \fi}
-
-\parseargdef\unmacro{%
- \if1\csname ismacro.#1\endcsname
- \global\cslet{#1}{macsave.#1}%
- \global\expandafter\let \csname ismacro.#1\endcsname=0%
- % Remove the macro name from \macrolist:
- \begingroup
- \expandafter\let\csname#1\endcsname \relax
- \let\definedummyword\unmacrodo
- \xdef\macrolist{\macrolist}%
- \endgroup
- \else
- \errmessage{Macro #1 not defined}%
- \fi
-}
-
-% Called by \do from \dounmacro on each macro. The idea is to omit any
-% macro definitions that have been changed to \relax.
-%
-\def\unmacrodo#1{%
- \ifx #1\relax
- % remove this
- \else
- \noexpand\definedummyword \noexpand#1%
- \fi
-}
-
-% This makes use of the obscure feature that if the last token of a
-% is #, then the preceding argument is delimited by
-% an opening brace, and that opening brace is not consumed.
-\def\getargs#1{\getargsxxx#1{}}
-\def\getargsxxx#1#{\getmacname #1 \relax\getmacargs}
-\def\getmacname #1 #2\relax{\macname={#1}}
-\def\getmacargs#1{\def\argl{#1}}
-
-% Parse the optional {params} list. Set up \paramno and \paramlist
-% so \defmacro knows what to do. Define \macarg.blah for each blah
-% in the params list, to be ##N where N is the position in that list.
-% That gets used by \mbodybackslash (above).
-
-% We need to get `macro parameter char #' into several definitions.
-% The technique used is stolen from LaTeX: let \hash be something
-% unexpandable, insert that wherever you need a #, and then redefine
-% it to # just before using the token list produced.
-%
-% The same technique is used to protect \eatspaces till just before
-% the macro is used.
-
-\def\parsemargdef#1;{\paramno=0\def\paramlist{}%
- \let\hash\relax\let\xeatspaces\relax\parsemargdefxxx#1,;,}
-\def\parsemargdefxxx#1,{%
- \if#1;\let\next=\relax
- \else \let\next=\parsemargdefxxx
- \advance\paramno by 1%
- \expandafter\edef\csname macarg.\eatspaces{#1}\endcsname
- {\xeatspaces{\hash\the\paramno}}%
- \edef\paramlist{\paramlist\hash\the\paramno,}%
- \fi\next}
-
-% These two commands read recursive and nonrecursive macro bodies.
-% (They're different since rec and nonrec macros end differently.)
-
-\long\def\parsemacbody#1@end macro%
-{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}%
-\long\def\parsermacbody#1@end rmacro%
-{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}%
-
-% This defines the macro itself. There are six cases: recursive and
-% nonrecursive macros of zero, one, and many arguments.
-% Much magic with \expandafter here.
-% \xdef is used so that macro definitions will survive the file
-% they're defined in; @include reads the file inside a group.
-\def\defmacro{%
- \let\hash=##% convert placeholders to macro parameter chars
- \ifrecursive
- \ifcase\paramno
- % 0
- \expandafter\xdef\csname\the\macname\endcsname{%
- \noexpand\scanmacro{\temp}}%
- \or % 1
- \expandafter\xdef\csname\the\macname\endcsname{%
- \bgroup\noexpand\macroargctxt
- \noexpand\braceorline
- \expandafter\noexpand\csname\the\macname xxx\endcsname}%
- \expandafter\xdef\csname\the\macname xxx\endcsname##1{%
- \egroup\noexpand\scanmacro{\temp}}%
- \else % many
- \expandafter\xdef\csname\the\macname\endcsname{%
- \bgroup\noexpand\macroargctxt
- \noexpand\csname\the\macname xx\endcsname}%
- \expandafter\xdef\csname\the\macname xx\endcsname##1{%
- \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}%
- \expandafter\expandafter
- \expandafter\xdef
- \expandafter\expandafter
- \csname\the\macname xxx\endcsname
- \paramlist{\egroup\noexpand\scanmacro{\temp}}%
- \fi
- \else
- \ifcase\paramno
- % 0
- \expandafter\xdef\csname\the\macname\endcsname{%
- \noexpand\norecurse{\the\macname}%
- \noexpand\scanmacro{\temp}\egroup}%
- \or % 1
- \expandafter\xdef\csname\the\macname\endcsname{%
- \bgroup\noexpand\macroargctxt
- \noexpand\braceorline
- \expandafter\noexpand\csname\the\macname xxx\endcsname}%
- \expandafter\xdef\csname\the\macname xxx\endcsname##1{%
- \egroup
- \noexpand\norecurse{\the\macname}%
- \noexpand\scanmacro{\temp}\egroup}%
- \else % many
- \expandafter\xdef\csname\the\macname\endcsname{%
- \bgroup\noexpand\macroargctxt
- \expandafter\noexpand\csname\the\macname xx\endcsname}%
- \expandafter\xdef\csname\the\macname xx\endcsname##1{%
- \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}%
- \expandafter\expandafter
- \expandafter\xdef
- \expandafter\expandafter
- \csname\the\macname xxx\endcsname
- \paramlist{%
- \egroup
- \noexpand\norecurse{\the\macname}%
- \noexpand\scanmacro{\temp}\egroup}%
- \fi
- \fi}
-
-\def\norecurse#1{\bgroup\cslet{#1}{macsave.#1}}
-
-% \braceorline decides whether the next nonwhitespace character is a
-% {. If so it reads up to the closing }, if not, it reads the whole
-% line. Whatever was read is then fed to the next control sequence
-% as an argument (by \parsebrace or \parsearg)
-\def\braceorline#1{\let\macnamexxx=#1\futurelet\nchar\braceorlinexxx}
-\def\braceorlinexxx{%
- \ifx\nchar\bgroup\else
- \expandafter\parsearg
- \fi \macnamexxx}
-
-
-% @alias.
-% We need some trickery to remove the optional spaces around the equal
-% sign. Just make them active and then expand them all to nothing.
-\def\alias{\parseargusing\obeyspaces\aliasxxx}
-\def\aliasxxx #1{\aliasyyy#1\relax}
-\def\aliasyyy #1=#2\relax{%
- {%
- \expandafter\let\obeyedspace=\empty
- \addtomacrolist{#1}%
- \xdef\next{\global\let\makecsname{#1}=\makecsname{#2}}%
- }%
- \next
-}
-
-
-\message{cross references,}
-
-\newwrite\auxfile
-\newif\ifhavexrefs % True if xref values are known.
-\newif\ifwarnedxrefs % True if we warned once that they aren't known.
-
-% @inforef is relatively simple.
-\def\inforef #1{\inforefzzz #1,,,,**}
-\def\inforefzzz #1,#2,#3,#4**{\putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}},
- node \samp{\ignorespaces#1{}}}
-
-% @node's only job in TeX is to define \lastnode, which is used in
-% cross-references. The @node line might or might not have commas, and
-% might or might not have spaces before the first comma, like:
-% @node foo , bar , ...
-% We don't want such trailing spaces in the node name.
-%
-\parseargdef\node{\checkenv{}\donode #1 ,\finishnodeparse}
-%
-% also remove a trailing comma, in case of something like this:
-% @node Help-Cross, , , Cross-refs
-\def\donode#1 ,#2\finishnodeparse{\dodonode #1,\finishnodeparse}
-\def\dodonode#1,#2\finishnodeparse{\gdef\lastnode{#1}}
-
-\let\nwnode=\node
-\let\lastnode=\empty
-
-% Write a cross-reference definition for the current node. #1 is the
-% type (Ynumbered, Yappendix, Ynothing).
-%
-\def\donoderef#1{%
- \ifx\lastnode\empty\else
- \setref{\lastnode}{#1}%
- \global\let\lastnode=\empty
- \fi
-}
-
-% @anchor{NAME} -- define xref target at arbitrary point.
-%
-\newcount\savesfregister
-%
-\def\savesf{\relax \ifhmode \savesfregister=\spacefactor \fi}
-\def\restoresf{\relax \ifhmode \spacefactor=\savesfregister \fi}
-\def\anchor#1{\savesf \setref{#1}{Ynothing}\restoresf \ignorespaces}
-
-% \setref{NAME}{SNT} defines a cross-reference point NAME (a node or an
-% anchor), which consists of three parts:
-% 1) NAME-title - the current sectioning name taken from \lastsection,
-% or the anchor name.
-% 2) NAME-snt - section number and type, passed as the SNT arg, or
-% empty for anchors.
-% 3) NAME-pg - the page number.
-%
-% This is called from \donoderef, \anchor, and \dofloat. In the case of
-% floats, there is an additional part, which is not written here:
-% 4) NAME-lof - the text as it should appear in a @listoffloats.
-%
-\def\setref#1#2{%
- \pdfmkdest{#1}%
- \iflinks
- {%
- \atdummies % preserve commands, but don't expand them
- \edef\writexrdef##1##2{%
- \write\auxfile{@xrdef{#1-% #1 of \setref, expanded by the \edef
- ##1}{##2}}% these are parameters of \writexrdef
- }%
- \toks0 = \expandafter{\lastsection}%
- \immediate \writexrdef{title}{\the\toks0 }%
- \immediate \writexrdef{snt}{\csname #2\endcsname}% \Ynumbered etc.
- \safewhatsit{\writexrdef{pg}{\folio}}% will be written later, during \shipout
- }%
- \fi
-}
-
-% @xref, @pxref, and @ref generate cross-references. For \xrefX, #1 is
-% the node name, #2 the name of the Info cross-reference, #3 the printed
-% node name, #4 the name of the Info file, #5 the name of the printed
-% manual. All but the node name can be omitted.
-%
-\def\pxref#1{\putwordsee{} \xrefX[#1,,,,,,,]}
-\def\xref#1{\putwordSee{} \xrefX[#1,,,,,,,]}
-\def\ref#1{\xrefX[#1,,,,,,,]}
-\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup
- \unsepspaces
- \def\printedmanual{\ignorespaces #5}%
- \def\printedrefname{\ignorespaces #3}%
- \setbox1=\hbox{\printedmanual\unskip}%
- \setbox0=\hbox{\printedrefname\unskip}%
- \ifdim \wd0 = 0pt
- % No printed node name was explicitly given.
- \expandafter\ifx\csname SETxref-automatic-section-title\endcsname\relax
- % Use the node name inside the square brackets.
- \def\printedrefname{\ignorespaces #1}%
- \else
- % Use the actual chapter/section title appear inside
- % the square brackets. Use the real section title if we have it.
- \ifdim \wd1 > 0pt
- % It is in another manual, so we don't have it.
- \def\printedrefname{\ignorespaces #1}%
- \else
- \ifhavexrefs
- % We know the real title if we have the xref values.
- \def\printedrefname{\refx{#1-title}{}}%
- \else
- % Otherwise just copy the Info node name.
- \def\printedrefname{\ignorespaces #1}%
- \fi%
- \fi
- \fi
- \fi
- %
- % Make link in pdf output.
- \ifpdf
- {\indexnofonts
- \turnoffactive
- % This expands tokens, so do it after making catcode changes, so _
- % etc. don't get their TeX definitions.
- \getfilename{#4}%
- %
- % See comments at \activebackslashdouble.
- {\activebackslashdouble \xdef\pdfxrefdest{#1}%
- \backslashparens\pdfxrefdest}%
- %
- \leavevmode
- \startlink attr{/Border [0 0 0]}%
- \ifnum\filenamelength>0
- goto file{\the\filename.pdf} name{\pdfxrefdest}%
- \else
- goto name{\pdfmkpgn{\pdfxrefdest}}%
- \fi
- }%
- \setcolor{\linkcolor}%
- \fi
- %
- % Float references are printed completely differently: "Figure 1.2"
- % instead of "[somenode], p.3". We distinguish them by the
- % LABEL-title being set to a magic string.
- {%
- % Have to otherify everything special to allow the \csname to
- % include an _ in the xref name, etc.
- \indexnofonts
- \turnoffactive
- \expandafter\global\expandafter\let\expandafter\Xthisreftitle
- \csname XR#1-title\endcsname
- }%
- \iffloat\Xthisreftitle
- % If the user specified the print name (third arg) to the ref,
- % print it instead of our usual "Figure 1.2".
- \ifdim\wd0 = 0pt
- \refx{#1-snt}{}%
- \else
- \printedrefname
- \fi
- %
- % if the user also gave the printed manual name (fifth arg), append
- % "in MANUALNAME".
- \ifdim \wd1 > 0pt
- \space \putwordin{} \cite{\printedmanual}%
- \fi
- \else
- % node/anchor (non-float) references.
- %
- % If we use \unhbox0 and \unhbox1 to print the node names, TeX does not
- % insert empty discretionaries after hyphens, which means that it will
- % not find a line break at a hyphen in a node names. Since some manuals
- % are best written with fairly long node names, containing hyphens, this
- % is a loss. Therefore, we give the text of the node name again, so it
- % is as if TeX is seeing it for the first time.
- \ifdim \wd1 > 0pt
- \putwordSection{} ``\printedrefname'' \putwordin{} \cite{\printedmanual}%
- \else
- % _ (for example) has to be the character _ for the purposes of the
- % control sequence corresponding to the node, but it has to expand
- % into the usual \leavevmode...\vrule stuff for purposes of
- % printing. So we \turnoffactive for the \refx-snt, back on for the
- % printing, back off for the \refx-pg.
- {\turnoffactive
- % Only output a following space if the -snt ref is nonempty; for
- % @unnumbered and @anchor, it won't be.
- \setbox2 = \hbox{\ignorespaces \refx{#1-snt}{}}%
- \ifdim \wd2 > 0pt \refx{#1-snt}\space\fi
- }%
- % output the `[mynode]' via a macro so it can be overridden.
- \xrefprintnodename\printedrefname
- %
- % But we always want a comma and a space:
- ,\space
- %
- % output the `page 3'.
- \turnoffactive \putwordpage\tie\refx{#1-pg}{}%
- \fi
- \fi
- \endlink
-\endgroup}
-
-% This macro is called from \xrefX for the `[nodename]' part of xref
-% output. It's a separate macro only so it can be changed more easily,
-% since square brackets don't work well in some documents. Particularly
-% one that Bob is working on :).
-%
-\def\xrefprintnodename#1{[#1]}
-
-% Things referred to by \setref.
-%
-\def\Ynothing{}
-\def\Yomitfromtoc{}
-\def\Ynumbered{%
- \ifnum\secno=0
- \putwordChapter@tie \the\chapno
- \else \ifnum\subsecno=0
- \putwordSection@tie \the\chapno.\the\secno
- \else \ifnum\subsubsecno=0
- \putwordSection@tie \the\chapno.\the\secno.\the\subsecno
- \else
- \putwordSection@tie \the\chapno.\the\secno.\the\subsecno.\the\subsubsecno
- \fi\fi\fi
-}
-\def\Yappendix{%
- \ifnum\secno=0
- \putwordAppendix@tie @char\the\appendixno{}%
- \else \ifnum\subsecno=0
- \putwordSection@tie @char\the\appendixno.\the\secno
- \else \ifnum\subsubsecno=0
- \putwordSection@tie @char\the\appendixno.\the\secno.\the\subsecno
- \else
- \putwordSection@tie
- @char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno
- \fi\fi\fi
-}
-
-% Define \refx{NAME}{SUFFIX} to reference a cross-reference string named NAME.
-% If its value is nonempty, SUFFIX is output afterward.
-%
-\def\refx#1#2{%
- {%
- \indexnofonts
- \otherbackslash
- \expandafter\global\expandafter\let\expandafter\thisrefX
- \csname XR#1\endcsname
- }%
- \ifx\thisrefX\relax
- % If not defined, say something at least.
- \angleleft un\-de\-fined\angleright
- \iflinks
- \ifhavexrefs
- \message{\linenumber Undefined cross reference `#1'.}%
- \else
- \ifwarnedxrefs\else
- \global\warnedxrefstrue
- \message{Cross reference values unknown; you must run TeX again.}%
- \fi
- \fi
- \fi
- \else
- % It's defined, so just use it.
- \thisrefX
- \fi
- #2% Output the suffix in any case.
-}
-
-% This is the macro invoked by entries in the aux file. Usually it's
-% just a \def (we prepend XR to the control sequence name to avoid
-% collisions). But if this is a float type, we have more work to do.
-%
-\def\xrdef#1#2{%
- {% The node name might contain 8-bit characters, which in our current
- % implementation are changed to commands like @'e. Don't let these
- % mess up the control sequence name.
- \indexnofonts
- \turnoffactive
- \xdef\safexrefname{#1}%
- }%
- %
- \expandafter\gdef\csname XR\safexrefname\endcsname{#2}% remember this xref
- %
- % Was that xref control sequence that we just defined for a float?
- \expandafter\iffloat\csname XR\safexrefname\endcsname
- % it was a float, and we have the (safe) float type in \iffloattype.
- \expandafter\let\expandafter\floatlist
- \csname floatlist\iffloattype\endcsname
- %
- % Is this the first time we've seen this float type?
- \expandafter\ifx\floatlist\relax
- \toks0 = {\do}% yes, so just \do
- \else
- % had it before, so preserve previous elements in list.
- \toks0 = \expandafter{\floatlist\do}%
- \fi
- %
- % Remember this xref in the control sequence \floatlistFLOATTYPE,
- % for later use in \listoffloats.
- \expandafter\xdef\csname floatlist\iffloattype\endcsname{\the\toks0
- {\safexrefname}}%
- \fi
-}
-
-% Read the last existing aux file, if any. No error if none exists.
-%
-\def\tryauxfile{%
- \openin 1 \jobname.aux
- \ifeof 1 \else
- \readdatafile{aux}%
- \global\havexrefstrue
- \fi
- \closein 1
-}
-
-\def\setupdatafile{%
- \catcode`\^^@=\other
- \catcode`\^^A=\other
- \catcode`\^^B=\other
- \catcode`\^^C=\other
- \catcode`\^^D=\other
- \catcode`\^^E=\other
- \catcode`\^^F=\other
- \catcode`\^^G=\other
- \catcode`\^^H=\other
- \catcode`\^^K=\other
- \catcode`\^^L=\other
- \catcode`\^^N=\other
- \catcode`\^^P=\other
- \catcode`\^^Q=\other
- \catcode`\^^R=\other
- \catcode`\^^S=\other
- \catcode`\^^T=\other
- \catcode`\^^U=\other
- \catcode`\^^V=\other
- \catcode`\^^W=\other
- \catcode`\^^X=\other
- \catcode`\^^Z=\other
- \catcode`\^^[=\other
- \catcode`\^^\=\other
- \catcode`\^^]=\other
- \catcode`\^^^=\other
- \catcode`\^^_=\other
- % It was suggested to set the catcode of ^ to 7, which would allow ^^e4 etc.
- % in xref tags, i.e., node names. But since ^^e4 notation isn't
- % supported in the main text, it doesn't seem desirable. Furthermore,
- % that is not enough: for node names that actually contain a ^
- % character, we would end up writing a line like this: 'xrdef {'hat
- % b-title}{'hat b} and \xrdef does a \csname...\endcsname on the first
- % argument, and \hat is not an expandable control sequence. It could
- % all be worked out, but why? Either we support ^^ or we don't.
- %
- % The other change necessary for this was to define \auxhat:
- % \def\auxhat{\def^{'hat }}% extra space so ok if followed by letter
- % and then to call \auxhat in \setq.
- %
- \catcode`\^=\other
- %
- % Special characters. Should be turned off anyway, but...
- \catcode`\~=\other
- \catcode`\[=\other
- \catcode`\]=\other
- \catcode`\"=\other
- \catcode`\_=\other
- \catcode`\|=\other
- \catcode`\<=\other
- \catcode`\>=\other
- \catcode`\$=\other
- \catcode`\#=\other
- \catcode`\&=\other
- \catcode`\%=\other
- \catcode`+=\other % avoid \+ for paranoia even though we've turned it off
- %
- % This is to support \ in node names and titles, since the \
- % characters end up in a \csname. It's easier than
- % leaving it active and making its active definition an actual \
- % character. What I don't understand is why it works in the *value*
- % of the xrdef. Seems like it should be a catcode12 \, and that
- % should not typeset properly. But it works, so I'm moving on for
- % now. --karl, 15jan04.
- \catcode`\\=\other
- %
- % Make the characters 128-255 be printing characters.
- {%
- \count1=128
- \def\loop{%
- \catcode\count1=\other
- \advance\count1 by 1
- \ifnum \count1<256 \loop \fi
- }%
- }%
- %
- % @ is our escape character in .aux files, and we need braces.
- \catcode`\{=1
- \catcode`\}=2
- \catcode`\@=0
-}
-
-\def\readdatafile#1{%
-\begingroup
- \setupdatafile
- \input\jobname.#1
-\endgroup}
-
-
-\message{insertions,}
-% including footnotes.
-
-\newcount \footnoteno
-
-% The trailing space in the following definition for supereject is
-% vital for proper filling; pages come out unaligned when you do a
-% pagealignmacro call if that space before the closing brace is
-% removed. (Generally, numeric constants should always be followed by a
-% space to prevent strange expansion errors.)
-\def\supereject{\par\penalty -20000\footnoteno =0 }
-
-% @footnotestyle is meaningful for info output only.
-\let\footnotestyle=\comment
-
-{\catcode `\@=11
-%
-% Auto-number footnotes. Otherwise like plain.
-\gdef\footnote{%
- \let\indent=\ptexindent
- \let\noindent=\ptexnoindent
- \global\advance\footnoteno by \@ne
- \edef\thisfootno{$^{\the\footnoteno}$}%
- %
- % In case the footnote comes at the end of a sentence, preserve the
- % extra spacing after we do the footnote number.
- \let\@sf\empty
- \ifhmode\edef\@sf{\spacefactor\the\spacefactor}\ptexslash\fi
- %
- % Remove inadvertent blank space before typesetting the footnote number.
- \unskip
- \thisfootno\@sf
- \dofootnote
-}%
-
-% Don't bother with the trickery in plain.tex to not require the
-% footnote text as a parameter. Our footnotes don't need to be so general.
-%
-% Oh yes, they do; otherwise, @ifset (and anything else that uses
-% \parseargline) fails inside footnotes because the tokens are fixed when
-% the footnote is read. --karl, 16nov96.
-%
-\gdef\dofootnote{%
- \insert\footins\bgroup
- % We want to typeset this text as a normal paragraph, even if the
- % footnote reference occurs in (for example) a display environment.
- % So reset some parameters.
- \hsize=\pagewidth
- \interlinepenalty\interfootnotelinepenalty
- \splittopskip\ht\strutbox % top baseline for broken footnotes
- \splitmaxdepth\dp\strutbox
- \floatingpenalty\@MM
- \leftskip\z@skip
- \rightskip\z@skip
- \spaceskip\z@skip
- \xspaceskip\z@skip
- \parindent\defaultparindent
- %
- \smallfonts \rm
- %
- % Because we use hanging indentation in footnotes, a @noindent appears
- % to exdent this text, so make it be a no-op. makeinfo does not use
- % hanging indentation so @noindent can still be needed within footnote
- % text after an @example or the like (not that this is good style).
- \let\noindent = \relax
- %
- % Hang the footnote text off the number. Use \everypar in case the
- % footnote extends for more than one paragraph.
- \everypar = {\hang}%
- \textindent{\thisfootno}%
- %
- % Don't crash into the line above the footnote text. Since this
- % expands into a box, it must come within the paragraph, lest it
- % provide a place where TeX can split the footnote.
- \footstrut
- \futurelet\next\fo@t
-}
-}%end \catcode `\@=11
-
-% In case a @footnote appears in a vbox, save the footnote text and create
-% the real \insert just after the vbox finished. Otherwise, the insertion
-% would be lost.
-% Similarly, if a @footnote appears inside an alignment, save the footnote
-% text to a box and make the \insert when a row of the table is finished.
-% And the same can be done for other insert classes. --kasal, 16nov03.
-
-% Replace the \insert primitive by a cheating macro.
-% Deeper inside, just make sure that the saved insertions are not spilled
-% out prematurely.
-%
-\def\startsavinginserts{%
- \ifx \insert\ptexinsert
- \let\insert\saveinsert
- \else
- \let\checkinserts\relax
- \fi
-}
-
-% This \insert replacement works for both \insert\footins{foo} and
-% \insert\footins\bgroup foo\egroup, but it doesn't work for \insert27{foo}.
-%
-\def\saveinsert#1{%
- \edef\next{\noexpand\savetobox \makeSAVEname#1}%
- \afterassignment\next
- % swallow the left brace
- \let\temp =
-}
-\def\makeSAVEname#1{\makecsname{SAVE\expandafter\gobble\string#1}}
-\def\savetobox#1{\global\setbox#1 = \vbox\bgroup \unvbox#1}
-
-\def\checksaveins#1{\ifvoid#1\else \placesaveins#1\fi}
-
-\def\placesaveins#1{%
- \ptexinsert \csname\expandafter\gobblesave\string#1\endcsname
- {\box#1}%
-}
-
-% eat @SAVE -- beware, all of them have catcode \other:
-{
- \def\dospecials{\do S\do A\do V\do E} \uncatcodespecials % ;-)
- \gdef\gobblesave @SAVE{}
-}
-
-% initialization:
-\def\newsaveins #1{%
- \edef\next{\noexpand\newsaveinsX \makeSAVEname#1}%
- \next
-}
-\def\newsaveinsX #1{%
- \csname newbox\endcsname #1%
- \expandafter\def\expandafter\checkinserts\expandafter{\checkinserts
- \checksaveins #1}%
-}
-
-% initialize:
-\let\checkinserts\empty
-\newsaveins\footins
-\newsaveins\margin
-
-
-% @image. We use the macros from epsf.tex to support this.
-% If epsf.tex is not installed and @image is used, we complain.
-%
-% Check for and read epsf.tex up front. If we read it only at @image
-% time, we might be inside a group, and then its definitions would get
-% undone and the next image would fail.
-\openin 1 = epsf.tex
-\ifeof 1 \else
- % Do not bother showing banner with epsf.tex v2.7k (available in
- % doc/epsf.tex and on ctan).
- \def\epsfannounce{\toks0 = }%
- \input epsf.tex
-\fi
-\closein 1
-%
-% We will only complain once about lack of epsf.tex.
-\newif\ifwarnednoepsf
-\newhelp\noepsfhelp{epsf.tex must be installed for images to
- work. It is also included in the Texinfo distribution, or you can get
- it from ftp://tug.org/tex/epsf.tex.}
-%
-\def\image#1{%
- \ifx\epsfbox\undefined
- \ifwarnednoepsf \else
- \errhelp = \noepsfhelp
- \errmessage{epsf.tex not found, images will be ignored}%
- \global\warnednoepsftrue
- \fi
- \else
- \imagexxx #1,,,,,\finish
- \fi
-}
-%
-% Arguments to @image:
-% #1 is (mandatory) image filename; we tack on .eps extension.
-% #2 is (optional) width, #3 is (optional) height.
-% #4 is (ignored optional) html alt text.
-% #5 is (ignored optional) extension.
-% #6 is just the usual extra ignored arg for parsing this stuff.
-\newif\ifimagevmode
-\def\imagexxx#1,#2,#3,#4,#5,#6\finish{\begingroup
- \catcode`\^^M = 5 % in case we're inside an example
- \normalturnoffactive % allow _ et al. in names
- % If the image is by itself, center it.
- \ifvmode
- \imagevmodetrue
- \nobreak\medskip
- % Usually we'll have text after the image which will insert
- % \parskip glue, so insert it here too to equalize the space
- % above and below.
- \nobreak\vskip\parskip
- \nobreak
- \fi
- %
- % Leave vertical mode so that indentation from an enclosing
- % environment such as @quotation is respected. On the other hand, if
- % it's at the top level, we don't want the normal paragraph indentation.
- \noindent
- %
- % Output the image.
- \ifpdf
- \dopdfimage{#1}{#2}{#3}%
- \else
- % \epsfbox itself resets \epsf?size at each figure.
- \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \epsfxsize=#2\relax \fi
- \setbox0 = \hbox{\ignorespaces #3}\ifdim\wd0 > 0pt \epsfysize=#3\relax \fi
- \epsfbox{#1.eps}%
- \fi
- %
- \ifimagevmode \medskip \fi % space after the standalone image
-\endgroup}
-
-
-% @float FLOATTYPE,LABEL,LOC ... @end float for displayed figures, tables,
-% etc. We don't actually implement floating yet, we always include the
-% float "here". But it seemed the best name for the future.
-%
-\envparseargdef\float{\eatcommaspace\eatcommaspace\dofloat#1, , ,\finish}
-
-% There may be a space before second and/or third parameter; delete it.
-\def\eatcommaspace#1, {#1,}
-
-% #1 is the optional FLOATTYPE, the text label for this float, typically
-% "Figure", "Table", "Example", etc. Can't contain commas. If omitted,
-% this float will not be numbered and cannot be referred to.
-%
-% #2 is the optional xref label. Also must be present for the float to
-% be referable.
-%
-% #3 is the optional positioning argument; for now, it is ignored. It
-% will somehow specify the positions allowed to float to (here, top, bottom).
-%
-% We keep a separate counter for each FLOATTYPE, which we reset at each
-% chapter-level command.
-\let\resetallfloatnos=\empty
-%
-\def\dofloat#1,#2,#3,#4\finish{%
- \let\thiscaption=\empty
- \let\thisshortcaption=\empty
- %
- % don't lose footnotes inside @float.
- %
- % BEWARE: when the floats start float, we have to issue warning whenever an
- % insert appears inside a float which could possibly float. --kasal, 26may04
- %
- \startsavinginserts
- %
- % We can't be used inside a paragraph.
- \par
- %
- \vtop\bgroup
- \def\floattype{#1}%
- \def\floatlabel{#2}%
- \def\floatloc{#3}% we do nothing with this yet.
- %
- \ifx\floattype\empty
- \let\safefloattype=\empty
- \else
- {%
- % the floattype might have accents or other special characters,
- % but we need to use it in a control sequence name.
- \indexnofonts
- \turnoffactive
- \xdef\safefloattype{\floattype}%
- }%
- \fi
- %
- % If label is given but no type, we handle that as the empty type.
- \ifx\floatlabel\empty \else
- % We want each FLOATTYPE to be numbered separately (Figure 1,
- % Table 1, Figure 2, ...). (And if no label, no number.)
- %
- \expandafter\getfloatno\csname\safefloattype floatno\endcsname
- \global\advance\floatno by 1
- %
- {%
- % This magic value for \lastsection is output by \setref as the
- % XREFLABEL-title value. \xrefX uses it to distinguish float
- % labels (which have a completely different output format) from
- % node and anchor labels. And \xrdef uses it to construct the
- % lists of floats.
- %
- \edef\lastsection{\floatmagic=\safefloattype}%
- \setref{\floatlabel}{Yfloat}%
- }%
- \fi
- %
- % start with \parskip glue, I guess.
- \vskip\parskip
- %
- % Don't suppress indentation if a float happens to start a section.
- \restorefirstparagraphindent
-}
-
-% we have these possibilities:
-% @float Foo,lbl & @caption{Cap}: Foo 1.1: Cap
-% @float Foo,lbl & no caption: Foo 1.1
-% @float Foo & @caption{Cap}: Foo: Cap
-% @float Foo & no caption: Foo
-% @float ,lbl & Caption{Cap}: 1.1: Cap
-% @float ,lbl & no caption: 1.1
-% @float & @caption{Cap}: Cap
-% @float & no caption:
-%
-\def\Efloat{%
- \let\floatident = \empty
- %
- % In all cases, if we have a float type, it comes first.
- \ifx\floattype\empty \else \def\floatident{\floattype}\fi
- %
- % If we have an xref label, the number comes next.
- \ifx\floatlabel\empty \else
- \ifx\floattype\empty \else % if also had float type, need tie first.
- \appendtomacro\floatident{\tie}%
- \fi
- % the number.
- \appendtomacro\floatident{\chaplevelprefix\the\floatno}%
- \fi
- %
- % Start the printed caption with what we've constructed in
- % \floatident, but keep it separate; we need \floatident again.
- \let\captionline = \floatident
- %
- \ifx\thiscaption\empty \else
- \ifx\floatident\empty \else
- \appendtomacro\captionline{: }% had ident, so need a colon between
- \fi
- %
- % caption text.
- \appendtomacro\captionline{\scanexp\thiscaption}%
- \fi
- %
- % If we have anything to print, print it, with space before.
- % Eventually this needs to become an \insert.
- \ifx\captionline\empty \else
- \vskip.5\parskip
- \captionline
- %
- % Space below caption.
- \vskip\parskip
- \fi
- %
- % If have an xref label, write the list of floats info. Do this
- % after the caption, to avoid chance of it being a breakpoint.
- \ifx\floatlabel\empty \else
- % Write the text that goes in the lof to the aux file as
- % \floatlabel-lof. Besides \floatident, we include the short
- % caption if specified, else the full caption if specified, else nothing.
- {%
- \atdummies
- %
- % since we read the caption text in the macro world, where ^^M
- % is turned into a normal character, we have to scan it back, so
- % we don't write the literal three characters "^^M" into the aux file.
- \scanexp{%
- \xdef\noexpand\gtemp{%
- \ifx\thisshortcaption\empty
- \thiscaption
- \else
- \thisshortcaption
- \fi
- }%
- }%
- \immediate\write\auxfile{@xrdef{\floatlabel-lof}{\floatident
- \ifx\gtemp\empty \else : \gtemp \fi}}%
- }%
- \fi
- \egroup % end of \vtop
- %
- % place the captured inserts
- %
- % BEWARE: when the floats start floating, we have to issue warning
- % whenever an insert appears inside a float which could possibly
- % float. --kasal, 26may04
- %
- \checkinserts
-}
-
-% Append the tokens #2 to the definition of macro #1, not expanding either.
-%
-\def\appendtomacro#1#2{%
- \expandafter\def\expandafter#1\expandafter{#1#2}%
-}
-
-% @caption, @shortcaption
-%
-\def\caption{\docaption\thiscaption}
-\def\shortcaption{\docaption\thisshortcaption}
-\def\docaption{\checkenv\float \bgroup\scanargctxt\defcaption}
-\def\defcaption#1#2{\egroup \def#1{#2}}
-
-% The parameter is the control sequence identifying the counter we are
-% going to use. Create it if it doesn't exist and assign it to \floatno.
-\def\getfloatno#1{%
- \ifx#1\relax
- % Haven't seen this figure type before.
- \csname newcount\endcsname #1%
- %
- % Remember to reset this floatno at the next chap.
- \expandafter\gdef\expandafter\resetallfloatnos
- \expandafter{\resetallfloatnos #1=0 }%
- \fi
- \let\floatno#1%
-}
-
-% \setref calls this to get the XREFLABEL-snt value. We want an @xref
-% to the FLOATLABEL to expand to "Figure 3.1". We call \setref when we
-% first read the @float command.
-%
-\def\Yfloat{\floattype@tie \chaplevelprefix\the\floatno}%
-
-% Magic string used for the XREFLABEL-title value, so \xrefX can
-% distinguish floats from other xref types.
-\def\floatmagic{!!float!!}
-
-% #1 is the control sequence we are passed; we expand into a conditional
-% which is true if #1 represents a float ref. That is, the magic
-% \lastsection value which we \setref above.
-%
-\def\iffloat#1{\expandafter\doiffloat#1==\finish}
-%
-% #1 is (maybe) the \floatmagic string. If so, #2 will be the
-% (safe) float type for this float. We set \iffloattype to #2.
-%
-\def\doiffloat#1=#2=#3\finish{%
- \def\temp{#1}%
- \def\iffloattype{#2}%
- \ifx\temp\floatmagic
-}
-
-% @listoffloats FLOATTYPE - print a list of floats like a table of contents.
-%
-\parseargdef\listoffloats{%
- \def\floattype{#1}% floattype
- {%
- % the floattype might have accents or other special characters,
- % but we need to use it in a control sequence name.
- \indexnofonts
- \turnoffactive
- \xdef\safefloattype{\floattype}%
- }%
- %
- % \xrdef saves the floats as a \do-list in \floatlistSAFEFLOATTYPE.
- \expandafter\ifx\csname floatlist\safefloattype\endcsname \relax
- \ifhavexrefs
- % if the user said @listoffloats foo but never @float foo.
- \message{\linenumber No `\safefloattype' floats to list.}%
- \fi
- \else
- \begingroup
- \leftskip=\tocindent % indent these entries like a toc
- \let\do=\listoffloatsdo
- \csname floatlist\safefloattype\endcsname
- \endgroup
- \fi
-}
-
-% This is called on each entry in a list of floats. We're passed the
-% xref label, in the form LABEL-title, which is how we save it in the
-% aux file. We strip off the -title and look up \XRLABEL-lof, which
-% has the text we're supposed to typeset here.
-%
-% Figures without xref labels will not be included in the list (since
-% they won't appear in the aux file).
-%
-\def\listoffloatsdo#1{\listoffloatsdoentry#1\finish}
-\def\listoffloatsdoentry#1-title\finish{{%
- % Can't fully expand XR#1-lof because it can contain anything. Just
- % pass the control sequence. On the other hand, XR#1-pg is just the
- % page number, and we want to fully expand that so we can get a link
- % in pdf output.
- \toksA = \expandafter{\csname XR#1-lof\endcsname}%
- %
- % use the same \entry macro we use to generate the TOC and index.
- \edef\writeentry{\noexpand\entry{\the\toksA}{\csname XR#1-pg\endcsname}}%
- \writeentry
-}}
-
-
-\message{localization,}
-
-% @documentlanguage is usually given very early, just after
-% @setfilename. If done too late, it may not override everything
-% properly. Single argument is the language (de) or locale (de_DE)
-% abbreviation. It would be nice if we could set up a hyphenation file.
-%
-{
- \catcode`\_ = \active
- \globaldefs=1
-\parseargdef\documentlanguage{\begingroup
- \let_=\normalunderscore % normal _ character for filenames
- \tex % read txi-??.tex file in plain TeX.
- % Read the file by the name they passed if it exists.
- \openin 1 txi-#1.tex
- \ifeof 1
- \documentlanguagetrywithoutunderscore{#1_\finish}%
- \else
- \input txi-#1.tex
- \fi
- \closein 1
- \endgroup
-\endgroup}
-}
-%
-% If they passed de_DE, and txi-de_DE.tex doesn't exist,
-% try txi-de.tex.
-%
-\def\documentlanguagetrywithoutunderscore#1_#2\finish{%
- \openin 1 txi-#1.tex
- \ifeof 1
- \errhelp = \nolanghelp
- \errmessage{Cannot read language file txi-#1.tex}%
- \else
- \input txi-#1.tex
- \fi
- \closein 1
-}
-%
-\newhelp\nolanghelp{The given language definition file cannot be found or
-is empty. Maybe you need to install it? In the current directory
-should work if nowhere else does.}
-
-% Set the catcode of characters 128 through 255 to the specified number.
-%
-\def\setnonasciicharscatcode#1{%
- \count255=128
- \loop\ifnum\count255<256
- \global\catcode\count255=#1\relax
- \advance\count255 by 1
- \repeat
-}
-
-\def\setnonasciicharscatcodenonglobal#1{%
- \count255=128
- \loop\ifnum\count255<256
- \catcode\count255=#1\relax
- \advance\count255 by 1
- \repeat
-}
-
-% @documentencoding sets the definition of non-ASCII characters
-% according to the specified encoding.
-%
-\parseargdef\documentencoding{%
- % Encoding being declared for the document.
- \def\declaredencoding{\csname #1.enc\endcsname}%
- %
- % Supported encodings: names converted to tokens in order to be able
- % to compare them with \ifx.
- \def\ascii{\csname US-ASCII.enc\endcsname}%
- \def\latnine{\csname ISO-8859-15.enc\endcsname}%
- \def\latone{\csname ISO-8859-1.enc\endcsname}%
- \def\lattwo{\csname ISO-8859-2.enc\endcsname}%
- \def\utfeight{\csname UTF-8.enc\endcsname}%
- %
- \ifx \declaredencoding \ascii
- \asciichardefs
- %
- \else \ifx \declaredencoding \lattwo
- \setnonasciicharscatcode\active
- \lattwochardefs
- %
- \else \ifx \declaredencoding \latone
- \setnonasciicharscatcode\active
- \latonechardefs
- %
- \else \ifx \declaredencoding \latnine
- \setnonasciicharscatcode\active
- \latninechardefs
- %
- \else \ifx \declaredencoding \utfeight
- \setnonasciicharscatcode\active
- \utfeightchardefs
- %
- \else
- \message{Unknown document encoding #1, ignoring.}%
- %
- \fi % utfeight
- \fi % latnine
- \fi % latone
- \fi % lattwo
- \fi % ascii
-}
-
-% A message to be logged when using a character that isn't available
-% the default font encoding (OT1).
-%
-\def\missingcharmsg#1{\message{Character missing in OT1 encoding: #1.}}
-
-% Take account of \c (plain) vs. \, (Texinfo) difference.
-\def\cedilla#1{\ifx\c\ptexc\c{#1}\else\,{#1}\fi}
-
-% First, make active non-ASCII characters in order for them to be
-% correctly categorized when TeX reads the replacement text of
-% macros containing the character definitions.
-\setnonasciicharscatcode\active
-%
-% Latin1 (ISO-8859-1) character definitions.
-\def\latonechardefs{%
- \gdef^^a0{~}
- \gdef^^a1{\exclamdown}
- \gdef^^a2{\missingcharmsg{CENT SIGN}}
- \gdef^^a3{{\pounds}}
- \gdef^^a4{\missingcharmsg{CURRENCY SIGN}}
- \gdef^^a5{\missingcharmsg{YEN SIGN}}
- \gdef^^a6{\missingcharmsg{BROKEN BAR}}
- \gdef^^a7{\S}
- \gdef^^a8{\"{}}
- \gdef^^a9{\copyright}
- \gdef^^aa{\ordf}
- \gdef^^ab{\missingcharmsg{LEFT-POINTING DOUBLE ANGLE QUOTATION MARK}}
- \gdef^^ac{$\lnot$}
- \gdef^^ad{\-}
- \gdef^^ae{\registeredsymbol}
- \gdef^^af{\={}}
- %
- \gdef^^b0{\textdegree}
- \gdef^^b1{$\pm$}
- \gdef^^b2{$^2$}
- \gdef^^b3{$^3$}
- \gdef^^b4{\'{}}
- \gdef^^b5{$\mu$}
- \gdef^^b6{\P}
- %
- \gdef^^b7{$^.$}
- \gdef^^b8{\cedilla\ }
- \gdef^^b9{$^1$}
- \gdef^^ba{\ordm}
- %
- \gdef^^bb{\missingcharmsg{RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK}}
- \gdef^^bc{$1\over4$}
- \gdef^^bd{$1\over2$}
- \gdef^^be{$3\over4$}
- \gdef^^bf{\questiondown}
- %
- \gdef^^c0{\`A}
- \gdef^^c1{\'A}
- \gdef^^c2{\^A}
- \gdef^^c3{\~A}
- \gdef^^c4{\"A}
- \gdef^^c5{\ringaccent A}
- \gdef^^c6{\AE}
- \gdef^^c7{\cedilla C}
- \gdef^^c8{\`E}
- \gdef^^c9{\'E}
- \gdef^^ca{\^E}
- \gdef^^cb{\"E}
- \gdef^^cc{\`I}
- \gdef^^cd{\'I}
- \gdef^^ce{\^I}
- \gdef^^cf{\"I}
- %
- \gdef^^d0{\missingcharmsg{LATIN CAPITAL LETTER ETH}}
- \gdef^^d1{\~N}
- \gdef^^d2{\`O}
- \gdef^^d3{\'O}
- \gdef^^d4{\^O}
- \gdef^^d5{\~O}
- \gdef^^d6{\"O}
- \gdef^^d7{$\times$}
- \gdef^^d8{\O}
- \gdef^^d9{\`U}
- \gdef^^da{\'U}
- \gdef^^db{\^U}
- \gdef^^dc{\"U}
- \gdef^^dd{\'Y}
- \gdef^^de{\missingcharmsg{LATIN CAPITAL LETTER THORN}}
- \gdef^^df{\ss}
- %
- \gdef^^e0{\`a}
- \gdef^^e1{\'a}
- \gdef^^e2{\^a}
- \gdef^^e3{\~a}
- \gdef^^e4{\"a}
- \gdef^^e5{\ringaccent a}
- \gdef^^e6{\ae}
- \gdef^^e7{\cedilla c}
- \gdef^^e8{\`e}
- \gdef^^e9{\'e}
- \gdef^^ea{\^e}
- \gdef^^eb{\"e}
- \gdef^^ec{\`{\dotless i}}
- \gdef^^ed{\'{\dotless i}}
- \gdef^^ee{\^{\dotless i}}
- \gdef^^ef{\"{\dotless i}}
- %
- \gdef^^f0{\missingcharmsg{LATIN SMALL LETTER ETH}}
- \gdef^^f1{\~n}
- \gdef^^f2{\`o}
- \gdef^^f3{\'o}
- \gdef^^f4{\^o}
- \gdef^^f5{\~o}
- \gdef^^f6{\"o}
- \gdef^^f7{$\div$}
- \gdef^^f8{\o}
- \gdef^^f9{\`u}
- \gdef^^fa{\'u}
- \gdef^^fb{\^u}
- \gdef^^fc{\"u}
- \gdef^^fd{\'y}
- \gdef^^fe{\missingcharmsg{LATIN SMALL LETTER THORN}}
- \gdef^^ff{\"y}
-}
-
-% Latin9 (ISO-8859-15) encoding character definitions.
-\def\latninechardefs{%
- % Encoding is almost identical to Latin1.
- \latonechardefs
- %
- \gdef^^a4{\euro}
- \gdef^^a6{\v S}
- \gdef^^a8{\v s}
- \gdef^^b4{\v Z}
- \gdef^^b8{\v z}
- \gdef^^bc{\OE}
- \gdef^^bd{\oe}
- \gdef^^be{\"Y}
-}
-
-% Latin2 (ISO-8859-2) character definitions.
-\def\lattwochardefs{%
- \gdef^^a0{~}
- \gdef^^a1{\missingcharmsg{LATIN CAPITAL LETTER A WITH OGONEK}}
- \gdef^^a2{\u{}}
- \gdef^^a3{\L}
- \gdef^^a4{\missingcharmsg{CURRENCY SIGN}}
- \gdef^^a5{\v L}
- \gdef^^a6{\'S}
- \gdef^^a7{\S}
- \gdef^^a8{\"{}}
- \gdef^^a9{\v S}
- \gdef^^aa{\cedilla S}
- \gdef^^ab{\v T}
- \gdef^^ac{\'Z}
- \gdef^^ad{\-}
- \gdef^^ae{\v Z}
- \gdef^^af{\dotaccent Z}
- %
- \gdef^^b0{\textdegree}
- \gdef^^b1{\missingcharmsg{LATIN SMALL LETTER A WITH OGONEK}}
- \gdef^^b2{\missingcharmsg{OGONEK}}
- \gdef^^b3{\l}
- \gdef^^b4{\'{}}
- \gdef^^b5{\v l}
- \gdef^^b6{\'s}
- \gdef^^b7{\v{}}
- \gdef^^b8{\cedilla\ }
- \gdef^^b9{\v s}
- \gdef^^ba{\cedilla s}
- \gdef^^bb{\v t}
- \gdef^^bc{\'z}
- \gdef^^bd{\H{}}
- \gdef^^be{\v z}
- \gdef^^bf{\dotaccent z}
- %
- \gdef^^c0{\'R}
- \gdef^^c1{\'A}
- \gdef^^c2{\^A}
- \gdef^^c3{\u A}
- \gdef^^c4{\"A}
- \gdef^^c5{\'L}
- \gdef^^c6{\'C}
- \gdef^^c7{\cedilla C}
- \gdef^^c8{\v C}
- \gdef^^c9{\'E}
- \gdef^^ca{\missingcharmsg{LATIN CAPITAL LETTER E WITH OGONEK}}
- \gdef^^cb{\"E}
- \gdef^^cc{\v E}
- \gdef^^cd{\'I}
- \gdef^^ce{\^I}
- \gdef^^cf{\v D}
- %
- \gdef^^d0{\missingcharmsg{LATIN CAPITAL LETTER D WITH STROKE}}
- \gdef^^d1{\'N}
- \gdef^^d2{\v N}
- \gdef^^d3{\'O}
- \gdef^^d4{\^O}
- \gdef^^d5{\H O}
- \gdef^^d6{\"O}
- \gdef^^d7{$\times$}
- \gdef^^d8{\v R}
- \gdef^^d9{\ringaccent U}
- \gdef^^da{\'U}
- \gdef^^db{\H U}
- \gdef^^dc{\"U}
- \gdef^^dd{\'Y}
- \gdef^^de{\cedilla T}
- \gdef^^df{\ss}
- %
- \gdef^^e0{\'r}
- \gdef^^e1{\'a}
- \gdef^^e2{\^a}
- \gdef^^e3{\u a}
- \gdef^^e4{\"a}
- \gdef^^e5{\'l}
- \gdef^^e6{\'c}
- \gdef^^e7{\cedilla c}
- \gdef^^e8{\v c}
- \gdef^^e9{\'e}
- \gdef^^ea{\missingcharmsg{LATIN SMALL LETTER E WITH OGONEK}}
- \gdef^^eb{\"e}
- \gdef^^ec{\v e}
- \gdef^^ed{\'\i}
- \gdef^^ee{\^\i}
- \gdef^^ef{\v d}
- %
- \gdef^^f0{\missingcharmsg{LATIN SMALL LETTER D WITH STROKE}}
- \gdef^^f1{\'n}
- \gdef^^f2{\v n}
- \gdef^^f3{\'o}
- \gdef^^f4{\^o}
- \gdef^^f5{\H o}
- \gdef^^f6{\"o}
- \gdef^^f7{$\div$}
- \gdef^^f8{\v r}
- \gdef^^f9{\ringaccent u}
- \gdef^^fa{\'u}
- \gdef^^fb{\H u}
- \gdef^^fc{\"u}
- \gdef^^fd{\'y}
- \gdef^^fe{\cedilla t}
- \gdef^^ff{\dotaccent{}}
-}
-
-% UTF-8 character definitions.
-%
-% This code to support UTF-8 is based on LaTeX's utf8.def, with some
-% changes for Texinfo conventions. It is included here under the GPL by
-% permission from Frank Mittelbach and the LaTeX team.
-%
-\newcount\countUTFx
-\newcount\countUTFy
-\newcount\countUTFz
-
-\gdef\UTFviiiTwoOctets#1#2{\expandafter
- \UTFviiiDefined\csname u8:#1\string #2\endcsname}
-%
-\gdef\UTFviiiThreeOctets#1#2#3{\expandafter
- \UTFviiiDefined\csname u8:#1\string #2\string #3\endcsname}
-%
-\gdef\UTFviiiFourOctets#1#2#3#4{\expandafter
- \UTFviiiDefined\csname u8:#1\string #2\string #3\string #4\endcsname}
-
-\gdef\UTFviiiDefined#1{%
- \ifx #1\relax
- \message{\linenumber Unicode char \string #1 not defined for Texinfo}%
- \else
- \expandafter #1%
- \fi
-}
-
-\begingroup
- \catcode`\~13
- \catcode`\"12
-
- \def\UTFviiiLoop{%
- \global\catcode\countUTFx\active
- \uccode`\~\countUTFx
- \uppercase\expandafter{\UTFviiiTmp}%
- \advance\countUTFx by 1
- \ifnum\countUTFx < \countUTFy
- \expandafter\UTFviiiLoop
- \fi}
-
- \countUTFx = "C2
- \countUTFy = "E0
- \def\UTFviiiTmp{%
- \xdef~{\noexpand\UTFviiiTwoOctets\string~}}
- \UTFviiiLoop
-
- \countUTFx = "E0
- \countUTFy = "F0
- \def\UTFviiiTmp{%
- \xdef~{\noexpand\UTFviiiThreeOctets\string~}}
- \UTFviiiLoop
-
- \countUTFx = "F0
- \countUTFy = "F4
- \def\UTFviiiTmp{%
- \xdef~{\noexpand\UTFviiiFourOctets\string~}}
- \UTFviiiLoop
-\endgroup
-
-\begingroup
- \catcode`\"=12
- \catcode`\<=12
- \catcode`\.=12
- \catcode`\,=12
- \catcode`\;=12
- \catcode`\!=12
- \catcode`\~=13
-
- \gdef\DeclareUnicodeCharacter#1#2{%
- \countUTFz = "#1\relax
- \wlog{\space\space defining Unicode char U+#1 (decimal \the\countUTFz)}%
- \begingroup
- \parseXMLCharref
- \def\UTFviiiTwoOctets##1##2{%
- \csname u8:##1\string ##2\endcsname}%
- \def\UTFviiiThreeOctets##1##2##3{%
- \csname u8:##1\string ##2\string ##3\endcsname}%
- \def\UTFviiiFourOctets##1##2##3##4{%
- \csname u8:##1\string ##2\string ##3\string ##4\endcsname}%
- \expandafter\expandafter\expandafter\expandafter
- \expandafter\expandafter\expandafter
- \gdef\UTFviiiTmp{#2}%
- \endgroup}
-
- \gdef\parseXMLCharref{%
- \ifnum\countUTFz < "A0\relax
- \errhelp = \EMsimple
- \errmessage{Cannot define Unicode char value < 00A0}%
- \else\ifnum\countUTFz < "800\relax
- \parseUTFviiiA,%
- \parseUTFviiiB C\UTFviiiTwoOctets.,%
- \else\ifnum\countUTFz < "10000\relax
- \parseUTFviiiA;%
- \parseUTFviiiA,%
- \parseUTFviiiB E\UTFviiiThreeOctets.{,;}%
- \else
- \parseUTFviiiA;%
- \parseUTFviiiA,%
- \parseUTFviiiA!%
- \parseUTFviiiB F\UTFviiiFourOctets.{!,;}%
- \fi\fi\fi
- }
-
- \gdef\parseUTFviiiA#1{%
- \countUTFx = \countUTFz
- \divide\countUTFz by 64
- \countUTFy = \countUTFz
- \multiply\countUTFz by 64
- \advance\countUTFx by -\countUTFz
- \advance\countUTFx by 128
- \uccode `#1\countUTFx
- \countUTFz = \countUTFy}
-
- \gdef\parseUTFviiiB#1#2#3#4{%
- \advance\countUTFz by "#10\relax
- \uccode `#3\countUTFz
- \uppercase{\gdef\UTFviiiTmp{#2#3#4}}}
-\endgroup
-
-\def\utfeightchardefs{%
- \DeclareUnicodeCharacter{00A0}{\tie}
- \DeclareUnicodeCharacter{00A1}{\exclamdown}
- \DeclareUnicodeCharacter{00A3}{\pounds}
- \DeclareUnicodeCharacter{00A8}{\"{ }}
- \DeclareUnicodeCharacter{00A9}{\copyright}
- \DeclareUnicodeCharacter{00AA}{\ordf}
- \DeclareUnicodeCharacter{00AB}{\guillemetleft}
- \DeclareUnicodeCharacter{00AD}{\-}
- \DeclareUnicodeCharacter{00AE}{\registeredsymbol}
- \DeclareUnicodeCharacter{00AF}{\={ }}
-
- \DeclareUnicodeCharacter{00B0}{\ringaccent{ }}
- \DeclareUnicodeCharacter{00B4}{\'{ }}
- \DeclareUnicodeCharacter{00B8}{\cedilla{ }}
- \DeclareUnicodeCharacter{00BA}{\ordm}
- \DeclareUnicodeCharacter{00BB}{\guillemetright}
- \DeclareUnicodeCharacter{00BF}{\questiondown}
-
- \DeclareUnicodeCharacter{00C0}{\`A}
- \DeclareUnicodeCharacter{00C1}{\'A}
- \DeclareUnicodeCharacter{00C2}{\^A}
- \DeclareUnicodeCharacter{00C3}{\~A}
- \DeclareUnicodeCharacter{00C4}{\"A}
- \DeclareUnicodeCharacter{00C5}{\AA}
- \DeclareUnicodeCharacter{00C6}{\AE}
- \DeclareUnicodeCharacter{00C7}{\cedilla{C}}
- \DeclareUnicodeCharacter{00C8}{\`E}
- \DeclareUnicodeCharacter{00C9}{\'E}
- \DeclareUnicodeCharacter{00CA}{\^E}
- \DeclareUnicodeCharacter{00CB}{\"E}
- \DeclareUnicodeCharacter{00CC}{\`I}
- \DeclareUnicodeCharacter{00CD}{\'I}
- \DeclareUnicodeCharacter{00CE}{\^I}
- \DeclareUnicodeCharacter{00CF}{\"I}
-
- \DeclareUnicodeCharacter{00D1}{\~N}
- \DeclareUnicodeCharacter{00D2}{\`O}
- \DeclareUnicodeCharacter{00D3}{\'O}
- \DeclareUnicodeCharacter{00D4}{\^O}
- \DeclareUnicodeCharacter{00D5}{\~O}
- \DeclareUnicodeCharacter{00D6}{\"O}
- \DeclareUnicodeCharacter{00D8}{\O}
- \DeclareUnicodeCharacter{00D9}{\`U}
- \DeclareUnicodeCharacter{00DA}{\'U}
- \DeclareUnicodeCharacter{00DB}{\^U}
- \DeclareUnicodeCharacter{00DC}{\"U}
- \DeclareUnicodeCharacter{00DD}{\'Y}
- \DeclareUnicodeCharacter{00DF}{\ss}
-
- \DeclareUnicodeCharacter{00E0}{\`a}
- \DeclareUnicodeCharacter{00E1}{\'a}
- \DeclareUnicodeCharacter{00E2}{\^a}
- \DeclareUnicodeCharacter{00E3}{\~a}
- \DeclareUnicodeCharacter{00E4}{\"a}
- \DeclareUnicodeCharacter{00E5}{\aa}
- \DeclareUnicodeCharacter{00E6}{\ae}
- \DeclareUnicodeCharacter{00E7}{\cedilla{c}}
- \DeclareUnicodeCharacter{00E8}{\`e}
- \DeclareUnicodeCharacter{00E9}{\'e}
- \DeclareUnicodeCharacter{00EA}{\^e}
- \DeclareUnicodeCharacter{00EB}{\"e}
- \DeclareUnicodeCharacter{00EC}{\`{\dotless{i}}}
- \DeclareUnicodeCharacter{00ED}{\'{\dotless{i}}}
- \DeclareUnicodeCharacter{00EE}{\^{\dotless{i}}}
- \DeclareUnicodeCharacter{00EF}{\"{\dotless{i}}}
-
- \DeclareUnicodeCharacter{00F1}{\~n}
- \DeclareUnicodeCharacter{00F2}{\`o}
- \DeclareUnicodeCharacter{00F3}{\'o}
- \DeclareUnicodeCharacter{00F4}{\^o}
- \DeclareUnicodeCharacter{00F5}{\~o}
- \DeclareUnicodeCharacter{00F6}{\"o}
- \DeclareUnicodeCharacter{00F8}{\o}
- \DeclareUnicodeCharacter{00F9}{\`u}
- \DeclareUnicodeCharacter{00FA}{\'u}
- \DeclareUnicodeCharacter{00FB}{\^u}
- \DeclareUnicodeCharacter{00FC}{\"u}
- \DeclareUnicodeCharacter{00FD}{\'y}
- \DeclareUnicodeCharacter{00FF}{\"y}
-
- \DeclareUnicodeCharacter{0100}{\=A}
- \DeclareUnicodeCharacter{0101}{\=a}
- \DeclareUnicodeCharacter{0102}{\u{A}}
- \DeclareUnicodeCharacter{0103}{\u{a}}
- \DeclareUnicodeCharacter{0106}{\'C}
- \DeclareUnicodeCharacter{0107}{\'c}
- \DeclareUnicodeCharacter{0108}{\^C}
- \DeclareUnicodeCharacter{0109}{\^c}
- \DeclareUnicodeCharacter{010A}{\dotaccent{C}}
- \DeclareUnicodeCharacter{010B}{\dotaccent{c}}
- \DeclareUnicodeCharacter{010C}{\v{C}}
- \DeclareUnicodeCharacter{010D}{\v{c}}
- \DeclareUnicodeCharacter{010E}{\v{D}}
-
- \DeclareUnicodeCharacter{0112}{\=E}
- \DeclareUnicodeCharacter{0113}{\=e}
- \DeclareUnicodeCharacter{0114}{\u{E}}
- \DeclareUnicodeCharacter{0115}{\u{e}}
- \DeclareUnicodeCharacter{0116}{\dotaccent{E}}
- \DeclareUnicodeCharacter{0117}{\dotaccent{e}}
- \DeclareUnicodeCharacter{011A}{\v{E}}
- \DeclareUnicodeCharacter{011B}{\v{e}}
- \DeclareUnicodeCharacter{011C}{\^G}
- \DeclareUnicodeCharacter{011D}{\^g}
- \DeclareUnicodeCharacter{011E}{\u{G}}
- \DeclareUnicodeCharacter{011F}{\u{g}}
-
- \DeclareUnicodeCharacter{0120}{\dotaccent{G}}
- \DeclareUnicodeCharacter{0121}{\dotaccent{g}}
- \DeclareUnicodeCharacter{0124}{\^H}
- \DeclareUnicodeCharacter{0125}{\^h}
- \DeclareUnicodeCharacter{0128}{\~I}
- \DeclareUnicodeCharacter{0129}{\~{\dotless{i}}}
- \DeclareUnicodeCharacter{012A}{\=I}
- \DeclareUnicodeCharacter{012B}{\={\dotless{i}}}
- \DeclareUnicodeCharacter{012C}{\u{I}}
- \DeclareUnicodeCharacter{012D}{\u{\dotless{i}}}
-
- \DeclareUnicodeCharacter{0130}{\dotaccent{I}}
- \DeclareUnicodeCharacter{0131}{\dotless{i}}
- \DeclareUnicodeCharacter{0132}{IJ}
- \DeclareUnicodeCharacter{0133}{ij}
- \DeclareUnicodeCharacter{0134}{\^J}
- \DeclareUnicodeCharacter{0135}{\^{\dotless{j}}}
- \DeclareUnicodeCharacter{0139}{\'L}
- \DeclareUnicodeCharacter{013A}{\'l}
-
- \DeclareUnicodeCharacter{0141}{\L}
- \DeclareUnicodeCharacter{0142}{\l}
- \DeclareUnicodeCharacter{0143}{\'N}
- \DeclareUnicodeCharacter{0144}{\'n}
- \DeclareUnicodeCharacter{0147}{\v{N}}
- \DeclareUnicodeCharacter{0148}{\v{n}}
- \DeclareUnicodeCharacter{014C}{\=O}
- \DeclareUnicodeCharacter{014D}{\=o}
- \DeclareUnicodeCharacter{014E}{\u{O}}
- \DeclareUnicodeCharacter{014F}{\u{o}}
-
- \DeclareUnicodeCharacter{0150}{\H{O}}
- \DeclareUnicodeCharacter{0151}{\H{o}}
- \DeclareUnicodeCharacter{0152}{\OE}
- \DeclareUnicodeCharacter{0153}{\oe}
- \DeclareUnicodeCharacter{0154}{\'R}
- \DeclareUnicodeCharacter{0155}{\'r}
- \DeclareUnicodeCharacter{0158}{\v{R}}
- \DeclareUnicodeCharacter{0159}{\v{r}}
- \DeclareUnicodeCharacter{015A}{\'S}
- \DeclareUnicodeCharacter{015B}{\'s}
- \DeclareUnicodeCharacter{015C}{\^S}
- \DeclareUnicodeCharacter{015D}{\^s}
- \DeclareUnicodeCharacter{015E}{\cedilla{S}}
- \DeclareUnicodeCharacter{015F}{\cedilla{s}}
-
- \DeclareUnicodeCharacter{0160}{\v{S}}
- \DeclareUnicodeCharacter{0161}{\v{s}}
- \DeclareUnicodeCharacter{0162}{\cedilla{t}}
- \DeclareUnicodeCharacter{0163}{\cedilla{T}}
- \DeclareUnicodeCharacter{0164}{\v{T}}
-
- \DeclareUnicodeCharacter{0168}{\~U}
- \DeclareUnicodeCharacter{0169}{\~u}
- \DeclareUnicodeCharacter{016A}{\=U}
- \DeclareUnicodeCharacter{016B}{\=u}
- \DeclareUnicodeCharacter{016C}{\u{U}}
- \DeclareUnicodeCharacter{016D}{\u{u}}
- \DeclareUnicodeCharacter{016E}{\ringaccent{U}}
- \DeclareUnicodeCharacter{016F}{\ringaccent{u}}
-
- \DeclareUnicodeCharacter{0170}{\H{U}}
- \DeclareUnicodeCharacter{0171}{\H{u}}
- \DeclareUnicodeCharacter{0174}{\^W}
- \DeclareUnicodeCharacter{0175}{\^w}
- \DeclareUnicodeCharacter{0176}{\^Y}
- \DeclareUnicodeCharacter{0177}{\^y}
- \DeclareUnicodeCharacter{0178}{\"Y}
- \DeclareUnicodeCharacter{0179}{\'Z}
- \DeclareUnicodeCharacter{017A}{\'z}
- \DeclareUnicodeCharacter{017B}{\dotaccent{Z}}
- \DeclareUnicodeCharacter{017C}{\dotaccent{z}}
- \DeclareUnicodeCharacter{017D}{\v{Z}}
- \DeclareUnicodeCharacter{017E}{\v{z}}
-
- \DeclareUnicodeCharacter{01C4}{D\v{Z}}
- \DeclareUnicodeCharacter{01C5}{D\v{z}}
- \DeclareUnicodeCharacter{01C6}{d\v{z}}
- \DeclareUnicodeCharacter{01C7}{LJ}
- \DeclareUnicodeCharacter{01C8}{Lj}
- \DeclareUnicodeCharacter{01C9}{lj}
- \DeclareUnicodeCharacter{01CA}{NJ}
- \DeclareUnicodeCharacter{01CB}{Nj}
- \DeclareUnicodeCharacter{01CC}{nj}
- \DeclareUnicodeCharacter{01CD}{\v{A}}
- \DeclareUnicodeCharacter{01CE}{\v{a}}
- \DeclareUnicodeCharacter{01CF}{\v{I}}
-
- \DeclareUnicodeCharacter{01D0}{\v{\dotless{i}}}
- \DeclareUnicodeCharacter{01D1}{\v{O}}
- \DeclareUnicodeCharacter{01D2}{\v{o}}
- \DeclareUnicodeCharacter{01D3}{\v{U}}
- \DeclareUnicodeCharacter{01D4}{\v{u}}
-
- \DeclareUnicodeCharacter{01E2}{\={\AE}}
- \DeclareUnicodeCharacter{01E3}{\={\ae}}
- \DeclareUnicodeCharacter{01E6}{\v{G}}
- \DeclareUnicodeCharacter{01E7}{\v{g}}
- \DeclareUnicodeCharacter{01E8}{\v{K}}
- \DeclareUnicodeCharacter{01E9}{\v{k}}
-
- \DeclareUnicodeCharacter{01F0}{\v{\dotless{j}}}
- \DeclareUnicodeCharacter{01F1}{DZ}
- \DeclareUnicodeCharacter{01F2}{Dz}
- \DeclareUnicodeCharacter{01F3}{dz}
- \DeclareUnicodeCharacter{01F4}{\'G}
- \DeclareUnicodeCharacter{01F5}{\'g}
- \DeclareUnicodeCharacter{01F8}{\`N}
- \DeclareUnicodeCharacter{01F9}{\`n}
- \DeclareUnicodeCharacter{01FC}{\'{\AE}}
- \DeclareUnicodeCharacter{01FD}{\'{\ae}}
- \DeclareUnicodeCharacter{01FE}{\'{\O}}
- \DeclareUnicodeCharacter{01FF}{\'{\o}}
-
- \DeclareUnicodeCharacter{021E}{\v{H}}
- \DeclareUnicodeCharacter{021F}{\v{h}}
-
- \DeclareUnicodeCharacter{0226}{\dotaccent{A}}
- \DeclareUnicodeCharacter{0227}{\dotaccent{a}}
- \DeclareUnicodeCharacter{0228}{\cedilla{E}}
- \DeclareUnicodeCharacter{0229}{\cedilla{e}}
- \DeclareUnicodeCharacter{022E}{\dotaccent{O}}
- \DeclareUnicodeCharacter{022F}{\dotaccent{o}}
-
- \DeclareUnicodeCharacter{0232}{\=Y}
- \DeclareUnicodeCharacter{0233}{\=y}
- \DeclareUnicodeCharacter{0237}{\dotless{j}}
-
- \DeclareUnicodeCharacter{1E02}{\dotaccent{B}}
- \DeclareUnicodeCharacter{1E03}{\dotaccent{b}}
- \DeclareUnicodeCharacter{1E04}{\udotaccent{B}}
- \DeclareUnicodeCharacter{1E05}{\udotaccent{b}}
- \DeclareUnicodeCharacter{1E06}{\ubaraccent{B}}
- \DeclareUnicodeCharacter{1E07}{\ubaraccent{b}}
- \DeclareUnicodeCharacter{1E0A}{\dotaccent{D}}
- \DeclareUnicodeCharacter{1E0B}{\dotaccent{d}}
- \DeclareUnicodeCharacter{1E0C}{\udotaccent{D}}
- \DeclareUnicodeCharacter{1E0D}{\udotaccent{d}}
- \DeclareUnicodeCharacter{1E0E}{\ubaraccent{D}}
- \DeclareUnicodeCharacter{1E0F}{\ubaraccent{d}}
-
- \DeclareUnicodeCharacter{1E1E}{\dotaccent{F}}
- \DeclareUnicodeCharacter{1E1F}{\dotaccent{f}}
-
- \DeclareUnicodeCharacter{1E20}{\=G}
- \DeclareUnicodeCharacter{1E21}{\=g}
- \DeclareUnicodeCharacter{1E22}{\dotaccent{H}}
- \DeclareUnicodeCharacter{1E23}{\dotaccent{h}}
- \DeclareUnicodeCharacter{1E24}{\udotaccent{H}}
- \DeclareUnicodeCharacter{1E25}{\udotaccent{h}}
- \DeclareUnicodeCharacter{1E26}{\"H}
- \DeclareUnicodeCharacter{1E27}{\"h}
-
- \DeclareUnicodeCharacter{1E30}{\'K}
- \DeclareUnicodeCharacter{1E31}{\'k}
- \DeclareUnicodeCharacter{1E32}{\udotaccent{K}}
- \DeclareUnicodeCharacter{1E33}{\udotaccent{k}}
- \DeclareUnicodeCharacter{1E34}{\ubaraccent{K}}
- \DeclareUnicodeCharacter{1E35}{\ubaraccent{k}}
- \DeclareUnicodeCharacter{1E36}{\udotaccent{L}}
- \DeclareUnicodeCharacter{1E37}{\udotaccent{l}}
- \DeclareUnicodeCharacter{1E3A}{\ubaraccent{L}}
- \DeclareUnicodeCharacter{1E3B}{\ubaraccent{l}}
- \DeclareUnicodeCharacter{1E3E}{\'M}
- \DeclareUnicodeCharacter{1E3F}{\'m}
-
- \DeclareUnicodeCharacter{1E40}{\dotaccent{M}}
- \DeclareUnicodeCharacter{1E41}{\dotaccent{m}}
- \DeclareUnicodeCharacter{1E42}{\udotaccent{M}}
- \DeclareUnicodeCharacter{1E43}{\udotaccent{m}}
- \DeclareUnicodeCharacter{1E44}{\dotaccent{N}}
- \DeclareUnicodeCharacter{1E45}{\dotaccent{n}}
- \DeclareUnicodeCharacter{1E46}{\udotaccent{N}}
- \DeclareUnicodeCharacter{1E47}{\udotaccent{n}}
- \DeclareUnicodeCharacter{1E48}{\ubaraccent{N}}
- \DeclareUnicodeCharacter{1E49}{\ubaraccent{n}}
-
- \DeclareUnicodeCharacter{1E54}{\'P}
- \DeclareUnicodeCharacter{1E55}{\'p}
- \DeclareUnicodeCharacter{1E56}{\dotaccent{P}}
- \DeclareUnicodeCharacter{1E57}{\dotaccent{p}}
- \DeclareUnicodeCharacter{1E58}{\dotaccent{R}}
- \DeclareUnicodeCharacter{1E59}{\dotaccent{r}}
- \DeclareUnicodeCharacter{1E5A}{\udotaccent{R}}
- \DeclareUnicodeCharacter{1E5B}{\udotaccent{r}}
- \DeclareUnicodeCharacter{1E5E}{\ubaraccent{R}}
- \DeclareUnicodeCharacter{1E5F}{\ubaraccent{r}}
-
- \DeclareUnicodeCharacter{1E60}{\dotaccent{S}}
- \DeclareUnicodeCharacter{1E61}{\dotaccent{s}}
- \DeclareUnicodeCharacter{1E62}{\udotaccent{S}}
- \DeclareUnicodeCharacter{1E63}{\udotaccent{s}}
- \DeclareUnicodeCharacter{1E6A}{\dotaccent{T}}
- \DeclareUnicodeCharacter{1E6B}{\dotaccent{t}}
- \DeclareUnicodeCharacter{1E6C}{\udotaccent{T}}
- \DeclareUnicodeCharacter{1E6D}{\udotaccent{t}}
- \DeclareUnicodeCharacter{1E6E}{\ubaraccent{T}}
- \DeclareUnicodeCharacter{1E6F}{\ubaraccent{t}}
-
- \DeclareUnicodeCharacter{1E7C}{\~V}
- \DeclareUnicodeCharacter{1E7D}{\~v}
- \DeclareUnicodeCharacter{1E7E}{\udotaccent{V}}
- \DeclareUnicodeCharacter{1E7F}{\udotaccent{v}}
-
- \DeclareUnicodeCharacter{1E80}{\`W}
- \DeclareUnicodeCharacter{1E81}{\`w}
- \DeclareUnicodeCharacter{1E82}{\'W}
- \DeclareUnicodeCharacter{1E83}{\'w}
- \DeclareUnicodeCharacter{1E84}{\"W}
- \DeclareUnicodeCharacter{1E85}{\"w}
- \DeclareUnicodeCharacter{1E86}{\dotaccent{W}}
- \DeclareUnicodeCharacter{1E87}{\dotaccent{w}}
- \DeclareUnicodeCharacter{1E88}{\udotaccent{W}}
- \DeclareUnicodeCharacter{1E89}{\udotaccent{w}}
- \DeclareUnicodeCharacter{1E8A}{\dotaccent{X}}
- \DeclareUnicodeCharacter{1E8B}{\dotaccent{x}}
- \DeclareUnicodeCharacter{1E8C}{\"X}
- \DeclareUnicodeCharacter{1E8D}{\"x}
- \DeclareUnicodeCharacter{1E8E}{\dotaccent{Y}}
- \DeclareUnicodeCharacter{1E8F}{\dotaccent{y}}
-
- \DeclareUnicodeCharacter{1E90}{\^Z}
- \DeclareUnicodeCharacter{1E91}{\^z}
- \DeclareUnicodeCharacter{1E92}{\udotaccent{Z}}
- \DeclareUnicodeCharacter{1E93}{\udotaccent{z}}
- \DeclareUnicodeCharacter{1E94}{\ubaraccent{Z}}
- \DeclareUnicodeCharacter{1E95}{\ubaraccent{z}}
- \DeclareUnicodeCharacter{1E96}{\ubaraccent{h}}
- \DeclareUnicodeCharacter{1E97}{\"t}
- \DeclareUnicodeCharacter{1E98}{\ringaccent{w}}
- \DeclareUnicodeCharacter{1E99}{\ringaccent{y}}
-
- \DeclareUnicodeCharacter{1EA0}{\udotaccent{A}}
- \DeclareUnicodeCharacter{1EA1}{\udotaccent{a}}
-
- \DeclareUnicodeCharacter{1EB8}{\udotaccent{E}}
- \DeclareUnicodeCharacter{1EB9}{\udotaccent{e}}
- \DeclareUnicodeCharacter{1EBC}{\~E}
- \DeclareUnicodeCharacter{1EBD}{\~e}
-
- \DeclareUnicodeCharacter{1ECA}{\udotaccent{I}}
- \DeclareUnicodeCharacter{1ECB}{\udotaccent{i}}
- \DeclareUnicodeCharacter{1ECC}{\udotaccent{O}}
- \DeclareUnicodeCharacter{1ECD}{\udotaccent{o}}
-
- \DeclareUnicodeCharacter{1EE4}{\udotaccent{U}}
- \DeclareUnicodeCharacter{1EE5}{\udotaccent{u}}
-
- \DeclareUnicodeCharacter{1EF2}{\`Y}
- \DeclareUnicodeCharacter{1EF3}{\`y}
- \DeclareUnicodeCharacter{1EF4}{\udotaccent{Y}}
-
- \DeclareUnicodeCharacter{1EF8}{\~Y}
- \DeclareUnicodeCharacter{1EF9}{\~y}
-
- \DeclareUnicodeCharacter{2013}{--}
- \DeclareUnicodeCharacter{2014}{---}
- \DeclareUnicodeCharacter{2018}{\quoteleft}
- \DeclareUnicodeCharacter{2019}{\quoteright}
- \DeclareUnicodeCharacter{201A}{\quotesinglbase}
- \DeclareUnicodeCharacter{201C}{\quotedblleft}
- \DeclareUnicodeCharacter{201D}{\quotedblright}
- \DeclareUnicodeCharacter{201E}{\quotedblbase}
- \DeclareUnicodeCharacter{2022}{\bullet}
- \DeclareUnicodeCharacter{2026}{\dots}
- \DeclareUnicodeCharacter{2039}{\guilsinglleft}
- \DeclareUnicodeCharacter{203A}{\guilsinglright}
- \DeclareUnicodeCharacter{20AC}{\euro}
-
- \DeclareUnicodeCharacter{2192}{\expansion}
- \DeclareUnicodeCharacter{21D2}{\result}
-
- \DeclareUnicodeCharacter{2212}{\minus}
- \DeclareUnicodeCharacter{2217}{\point}
- \DeclareUnicodeCharacter{2261}{\equiv}
-}% end of \utfeightchardefs
-
-
-% US-ASCII character definitions.
-\def\asciichardefs{% nothing need be done
- \relax
-}
-
-% Make non-ASCII characters printable again for compatibility with
-% existing Texinfo documents that may use them, even without declaring a
-% document encoding.
-%
-\setnonasciicharscatcode \other
-
-
-\message{formatting,}
-
-\newdimen\defaultparindent \defaultparindent = 15pt
-
-\chapheadingskip = 15pt plus 4pt minus 2pt
-\secheadingskip = 12pt plus 3pt minus 2pt
-\subsecheadingskip = 9pt plus 2pt minus 2pt
-
-% Prevent underfull vbox error messages.
-\vbadness = 10000
-
-% Don't be so finicky about underfull hboxes, either.
-\hbadness = 2000
-
-% Following George Bush, get rid of widows and orphans.
-\widowpenalty=10000
-\clubpenalty=10000
-
-% Use TeX 3.0's \emergencystretch to help line breaking, but if we're
-% using an old version of TeX, don't do anything. We want the amount of
-% stretch added to depend on the line length, hence the dependence on
-% \hsize. We call this whenever the paper size is set.
-%
-\def\setemergencystretch{%
- \ifx\emergencystretch\thisisundefined
- % Allow us to assign to \emergencystretch anyway.
- \def\emergencystretch{\dimen0}%
- \else
- \emergencystretch = .15\hsize
- \fi
-}
-
-% Parameters in order: 1) textheight; 2) textwidth;
-% 3) voffset; 4) hoffset; 5) binding offset; 6) topskip;
-% 7) physical page height; 8) physical page width.
-%
-% We also call \setleading{\textleading}, so the caller should define
-% \textleading. The caller should also set \parskip.
-%
-\def\internalpagesizes#1#2#3#4#5#6#7#8{%
- \voffset = #3\relax
- \topskip = #6\relax
- \splittopskip = \topskip
- %
- \vsize = #1\relax
- \advance\vsize by \topskip
- \outervsize = \vsize
- \advance\outervsize by 2\topandbottommargin
- \pageheight = \vsize
- %
- \hsize = #2\relax
- \outerhsize = \hsize
- \advance\outerhsize by 0.5in
- \pagewidth = \hsize
- %
- \normaloffset = #4\relax
- \bindingoffset = #5\relax
- %
- \ifpdf
- \pdfpageheight #7\relax
- \pdfpagewidth #8\relax
- % if we don't reset these, they will remain at "1 true in" of
- % whatever layout pdftex was dumped with.
- \pdfhorigin = 1 true in
- \pdfvorigin = 1 true in
- \fi
- %
- \setleading{\textleading}
- %
- \parindent = \defaultparindent
- \setemergencystretch
-}
-
-% @letterpaper (the default).
-\def\letterpaper{{\globaldefs = 1
- \parskip = 3pt plus 2pt minus 1pt
- \textleading = 13.2pt
- %
- % If page is nothing but text, make it come out even.
- \internalpagesizes{607.2pt}{6in}% that's 46 lines
- {\voffset}{.25in}%
- {\bindingoffset}{36pt}%
- {11in}{8.5in}%
-}}
-
-% Use @smallbook to reset parameters for 7x9.25 trim size.
-\def\smallbook{{\globaldefs = 1
- \parskip = 2pt plus 1pt
- \textleading = 12pt
- %
- \internalpagesizes{7.5in}{5in}%
- {-.2in}{0in}%
- {\bindingoffset}{16pt}%
- {9.25in}{7in}%
- %
- \lispnarrowing = 0.3in
- \tolerance = 700
- \hfuzz = 1pt
- \contentsrightmargin = 0pt
- \defbodyindent = .5cm
-}}
-
-% Use @smallerbook to reset parameters for 6x9 trim size.
-% (Just testing, parameters still in flux.)
-\def\smallerbook{{\globaldefs = 1
- \parskip = 1.5pt plus 1pt
- \textleading = 12pt
- %
- \internalpagesizes{7.4in}{4.8in}%
- {-.2in}{-.4in}%
- {0pt}{14pt}%
- {9in}{6in}%
- %
- \lispnarrowing = 0.25in
- \tolerance = 700
- \hfuzz = 1pt
- \contentsrightmargin = 0pt
- \defbodyindent = .4cm
-}}
-
-% Use @afourpaper to print on European A4 paper.
-\def\afourpaper{{\globaldefs = 1
- \parskip = 3pt plus 2pt minus 1pt
- \textleading = 13.2pt
- %
- % Double-side printing via postscript on Laserjet 4050
- % prints double-sided nicely when \bindingoffset=10mm and \hoffset=-6mm.
- % To change the settings for a different printer or situation, adjust
- % \normaloffset until the front-side and back-side texts align. Then
- % do the same for \bindingoffset. You can set these for testing in
- % your texinfo source file like this:
- % @tex
- % \global\normaloffset = -6mm
- % \global\bindingoffset = 10mm
- % @end tex
- \internalpagesizes{673.2pt}{160mm}% that's 51 lines
- {\voffset}{\hoffset}%
- {\bindingoffset}{44pt}%
- {297mm}{210mm}%
- %
- \tolerance = 700
- \hfuzz = 1pt
- \contentsrightmargin = 0pt
- \defbodyindent = 5mm
-}}
-
-% Use @afivepaper to print on European A5 paper.
-% From romildo@urano.iceb.ufop.br, 2 July 2000.
-% He also recommends making @example and @lisp be small.
-\def\afivepaper{{\globaldefs = 1
- \parskip = 2pt plus 1pt minus 0.1pt
- \textleading = 12.5pt
- %
- \internalpagesizes{160mm}{120mm}%
- {\voffset}{\hoffset}%
- {\bindingoffset}{8pt}%
- {210mm}{148mm}%
- %
- \lispnarrowing = 0.2in
- \tolerance = 800
- \hfuzz = 1.2pt
- \contentsrightmargin = 0pt
- \defbodyindent = 2mm
- \tableindent = 12mm
-}}
-
-% A specific text layout, 24x15cm overall, intended for A4 paper.
-\def\afourlatex{{\globaldefs = 1
- \afourpaper
- \internalpagesizes{237mm}{150mm}%
- {\voffset}{4.6mm}%
- {\bindingoffset}{7mm}%
- {297mm}{210mm}%
- %
- % Must explicitly reset to 0 because we call \afourpaper.
- \globaldefs = 0
-}}
-
-% Use @afourwide to print on A4 paper in landscape format.
-\def\afourwide{{\globaldefs = 1
- \afourpaper
- \internalpagesizes{241mm}{165mm}%
- {\voffset}{-2.95mm}%
- {\bindingoffset}{7mm}%
- {297mm}{210mm}%
- \globaldefs = 0
-}}
-
-% @pagesizes TEXTHEIGHT[,TEXTWIDTH]
-% Perhaps we should allow setting the margins, \topskip, \parskip,
-% and/or leading, also. Or perhaps we should compute them somehow.
-%
-\parseargdef\pagesizes{\pagesizesyyy #1,,\finish}
-\def\pagesizesyyy#1,#2,#3\finish{{%
- \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \hsize=#2\relax \fi
- \globaldefs = 1
- %
- \parskip = 3pt plus 2pt minus 1pt
- \setleading{\textleading}%
- %
- \dimen0 = #1\relax
- \advance\dimen0 by \voffset
- %
- \dimen2 = \hsize
- \advance\dimen2 by \normaloffset
- %
- \internalpagesizes{#1}{\hsize}%
- {\voffset}{\normaloffset}%
- {\bindingoffset}{44pt}%
- {\dimen0}{\dimen2}%
-}}
-
-% Set default to letter.
-%
-\letterpaper
-
-
-\message{and turning on texinfo input format.}
-
-% Define macros to output various characters with catcode for normal text.
-\catcode`\"=\other
-\catcode`\~=\other
-\catcode`\^=\other
-\catcode`\_=\other
-\catcode`\|=\other
-\catcode`\<=\other
-\catcode`\>=\other
-\catcode`\+=\other
-\catcode`\$=\other
-\def\normaldoublequote{"}
-\def\normaltilde{~}
-\def\normalcaret{^}
-\def\normalunderscore{_}
-\def\normalverticalbar{|}
-\def\normalless{<}
-\def\normalgreater{>}
-\def\normalplus{+}
-\def\normaldollar{$}%$ font-lock fix
-
-% This macro is used to make a character print one way in \tt
-% (where it can probably be output as-is), and another way in other fonts,
-% where something hairier probably needs to be done.
-%
-% #1 is what to print if we are indeed using \tt; #2 is what to print
-% otherwise. Since all the Computer Modern typewriter fonts have zero
-% interword stretch (and shrink), and it is reasonable to expect all
-% typewriter fonts to have this, we can check that font parameter.
-%
-\def\ifusingtt#1#2{\ifdim \fontdimen3\font=0pt #1\else #2\fi}
-
-% Same as above, but check for italic font. Actually this also catches
-% non-italic slanted fonts since it is impossible to distinguish them from
-% italic fonts. But since this is only used by $ and it uses \sl anyway
-% this is not a problem.
-\def\ifusingit#1#2{\ifdim \fontdimen1\font>0pt #1\else #2\fi}
-
-% Turn off all special characters except @
-% (and those which the user can use as if they were ordinary).
-% Most of these we simply print from the \tt font, but for some, we can
-% use math or other variants that look better in normal text.
-
-\catcode`\"=\active
-\def\activedoublequote{{\tt\char34}}
-\let"=\activedoublequote
-\catcode`\~=\active
-\def~{{\tt\char126}}
-\chardef\hat=`\^
-\catcode`\^=\active
-\def^{{\tt \hat}}
-
-\catcode`\_=\active
-\def_{\ifusingtt\normalunderscore\_}
-\let\realunder=_
-% Subroutine for the previous macro.
-\def\_{\leavevmode \kern.07em \vbox{\hrule width.3em height.1ex}\kern .07em }
-
-\catcode`\|=\active
-\def|{{\tt\char124}}
-\chardef \less=`\<
-\catcode`\<=\active
-\def<{{\tt \less}}
-\chardef \gtr=`\>
-\catcode`\>=\active
-\def>{{\tt \gtr}}
-\catcode`\+=\active
-\def+{{\tt \char 43}}
-\catcode`\$=\active
-\def${\ifusingit{{\sl\$}}\normaldollar}%$ font-lock fix
-
-% If a .fmt file is being used, characters that might appear in a file
-% name cannot be active until we have parsed the command line.
-% So turn them off again, and have \everyjob (or @setfilename) turn them on.
-% \otherifyactive is called near the end of this file.
-\def\otherifyactive{\catcode`+=\other \catcode`\_=\other}
-
-% Used sometimes to turn off (effectively) the active characters even after
-% parsing them.
-\def\turnoffactive{%
- \normalturnoffactive
- \otherbackslash
-}
-
-\catcode`\@=0
-
-% \backslashcurfont outputs one backslash character in current font,
-% as in \char`\\.
-\global\chardef\backslashcurfont=`\\
-\global\let\rawbackslashxx=\backslashcurfont % let existing .??s files work
-
-% \realbackslash is an actual character `\' with catcode other, and
-% \doublebackslash is two of them (for the pdf outlines).
-{\catcode`\\=\other @gdef@realbackslash{\} @gdef@doublebackslash{\\}}
-
-% In texinfo, backslash is an active character; it prints the backslash
-% in fixed width font.
-\catcode`\\=\active
-@def@normalbackslash{{@tt@backslashcurfont}}
-% On startup, @fixbackslash assigns:
-% @let \ = @normalbackslash
-
-% \rawbackslash defines an active \ to do \backslashcurfont.
-% \otherbackslash defines an active \ to be a literal `\' character with
-% catcode other.
-@gdef@rawbackslash{@let\=@backslashcurfont}
-@gdef@otherbackslash{@let\=@realbackslash}
-
-% Same as @turnoffactive except outputs \ as {\tt\char`\\} instead of
-% the literal character `\'.
-%
-@def@normalturnoffactive{%
- @let\=@normalbackslash
- @let"=@normaldoublequote
- @let~=@normaltilde
- @let^=@normalcaret
- @let_=@normalunderscore
- @let|=@normalverticalbar
- @let<=@normalless
- @let>=@normalgreater
- @let+=@normalplus
- @let$=@normaldollar %$ font-lock fix
- @unsepspaces
-}
-
-% Make _ and + \other characters, temporarily.
-% This is canceled by @fixbackslash.
-@otherifyactive
-
-% If a .fmt file is being used, we don't want the `\input texinfo' to show up.
-% That is what \eatinput is for; after that, the `\' should revert to printing
-% a backslash.
-%
-@gdef@eatinput input texinfo{@fixbackslash}
-@global@let\ = @eatinput
-
-% On the other hand, perhaps the file did not have a `\input texinfo'. Then
-% the first `\' in the file would cause an error. This macro tries to fix
-% that, assuming it is called before the first `\' could plausibly occur.
-% Also turn back on active characters that might appear in the input
-% file name, in case not using a pre-dumped format.
-%
-@gdef@fixbackslash{%
- @ifx\@eatinput @let\ = @normalbackslash @fi
- @catcode`+=@active
- @catcode`@_=@active
-}
-
-% Say @foo, not \foo, in error messages.
-@escapechar = `@@
-
-% These look ok in all fonts, so just make them not special.
-@catcode`@& = @other
-@catcode`@# = @other
-@catcode`@% = @other
-
-
-@c Local variables:
-@c eval: (add-hook 'write-file-hooks 'time-stamp)
-@c page-delimiter: "^\\\\message"
-@c time-stamp-start: "def\\\\texinfoversion{"
-@c time-stamp-format: "%:y-%02m-%02d.%02H"
-@c time-stamp-end: "}"
-@c End:
-
-@c vim:sw=2:
-
-@ignore
- arch-tag: e1b36e32-c96e-4135-a41a-0b2efa2ea115
-@end ignore
diff --git a/docs/tex-include/txi-cmbright.tex b/docs/tex-include/txi-cmbright.tex
deleted file mode 100644
index a3f432b046..0000000000
--- a/docs/tex-include/txi-cmbright.tex
+++ /dev/null
@@ -1,95 +0,0 @@
-\message{altfont-cmbright (v1.0)}
-
-\global\def \txifontrm {cmbr10}
-\global\def \txifontbf {cmbrbx10}
-\global\def \txifontit {cmbrsl10}
-\global\def \txifontsl {cmbrsl10}
-\global\def \txifontsc {phvrc7tn}
-\global\def \txifontsf {cmss10}
-\global\def \txifonttt {cmtl10}
-\global\def \txifontttsl {cmsltl10}
-\global\def \altsuff {}
-
-\global\def \definetextfontsizexi {% Text fonts (11.2pt, magstep1).
- \def \smallernominalsize {8pt}
- \txifontonesize{smaller}{800}
-
- \def \smallnominalsize {9pt}
- \txifontonesize{small}{900}
-
- \def \reducednominalsize {10pt}
- \txifontonesize{reduced}{1000}
-
- \def \textnominalsize {11pt}
- \edef \mainmagstep {\magstephalf}
- \txifontonesize{text}{\mainmagstep}
- \global\let \defbf = \textbf
- \global\let \deftt = \texttt
- \global\let \defttsl = \textttsl
- \def\df{%
- \let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf
- }
-
- \def \ssecnominalsize {13pt}
- \txifontonesize{ssec}{1300}
-
- \def \secnominalsize {14pt}
- \txifontonesize{sec}{1400}
-
- \def \chapnominalsize {17pt}
- \txifontonesize{chap}{1700}
-
- \def \titlenominalsize {20pt}
- \txifontonesize{title}{2000}
-
- % Reset the current fonts
- \textfonts
- \rm
-}
-
-\global\def \definetextfontsizex {% Text fonts (10pt).
- \def \smallernominalsize {8pt}
- \txifontonesize{smaller}{800}
-
- \def \smallnominalsize {9pt}
- \txifontonesize{small}{900}
-
- \def \reducednominalsize {9pt}
- \txifontonesize{reduced}{900}
-
- \def \textnominalsize {10pt}
- \edef \mainmagstep {1000}
- \txifontonesize{text}{\mainmagstep}
- \global\let \defbf = \textbf
- \global\let \deftt = \texttt
- \global\let \defttsl = \textttsl
- \def\df{%
- \let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf
- }
-
- \def \ssecnominalsize {10pt}
- \txifontonesize{ssec}{1000}
-
- \def \secnominalsize {12pt}
- \txifontonesize{sec}{1200}
-
- \def \chapnominalsize {14pt}
- \txifontonesize{chap}{1400}
-
- \def \titlenominalsize {20pt}
- \txifontonesize{title}{2000}
-
- % Reduce space between paragraphs
- \divide\parskip by 2
-
- % Reset the current fonts
- \textfonts
- \rm
-}
-
-\global\def \subtitlerm {\tenrm} % Fix a bug in texinfo.tex
-
-\ifx \textsizearg\xword \definetextfontsizex
-\else \definetextfontsizexi \fi
-
-\endinput
diff --git a/docs/tex-include/txi-helvetica.tex b/docs/tex-include/txi-helvetica.tex
deleted file mode 100644
index 65c2fa905b..0000000000
--- a/docs/tex-include/txi-helvetica.tex
+++ /dev/null
@@ -1,93 +0,0 @@
-\message{altfont-helvetica (v1.0)}
-
-\global\def \txifontrm {phvr}
-\global\def \txifontbf {phvb}
-\global\def \txifontit {phvro}
-\global\def \txifontsl {phvro}
-\global\def \txifontsc {phvrc}
-\global\def \txifontsf {pagk}
-\global\def \txifonttt {pcrr}
-\global\def \txifontttsl {pcrro}
-\global\def \altsuff {7t}
-
-\global\def \definetextfontsizexi {% Text fonts (11.2pt, magstep1).
- \def \smallernominalsize {8pt}
- \txifontonesize{smaller}{800}
-
- \def \smallnominalsize {9pt}
- \txifontonesize{small}{900}
-
- \def \reducednominalsize {10pt}
- \txifontonesize{reduced}{1000}
-
- \def \textnominalsize {11pt}
- \edef \mainmagstep {\magstephalf}
- \txifontonesize{text}{\mainmagstep}
- \global\let \defbf = \textbf
- \global\let \deftt = \texttt
- \global\let \defttsl = \textttsl
- \def\df{%
- \let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf
- }
-
- \def \ssecnominalsize {13pt}
- \txifontonesize{ssec}{1300}
-
- \def \secnominalsize {14pt}
- \txifontonesize{sec}{1400}
-
- \def \chapnominalsize {17pt}
- \txifontonesize{chap}{1700}
-
- \def \titlenominalsize {20pt}
- \txifontonesize{title}{2000}
-
- % Reset the current fonts
- \textfonts
- \rm
-}
-
-\global\def \definetextfontsizex {% Text fonts (10pt).
- \def \smallernominalsize {8pt}
- \txifontonesize{smaller}{800}
-
- \def \smallnominalsize {9pt}
- \txifontonesize{small}{900}
-
- \def \reducednominalsize {9pt}
- \txifontonesize{reduced}{900}
-
- \def \textnominalsize {10pt}
- \edef \mainmagstep {1000}
- \txifontonesize{text}{\mainmagstep}
- \global\let \defbf = \textbf
- \global\let \deftt = \texttt
- \global\let \defttsl = \textttsl
- \def\df{%
- \let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf
- }
-
- \def \ssecnominalsize {10pt}
- \txifontonesize{ssec}{1000}
-
- \def \secnominalsize {12pt}
- \txifontonesize{sec}{1200}
-
- \def \chapnominalsize {14pt}
- \txifontonesize{chap}{1400}
-
- \def \titlenominalsize {20pt}
- \txifontonesize{title}{2000}
-
- % Reduce space between paragraphs
- \divide\parskip by 2
-
- % Reset the current fonts
- \textfonts
- \rm
-}
-
-\ifx \textsizearg\xword \definetextfontsizex
-\else \definetextfontsizexi \fi
-
-\endinput
diff --git a/docs/tex-include/txi-iwona.tex b/docs/tex-include/txi-iwona.tex
deleted file mode 100644
index 8a370883fc..0000000000
--- a/docs/tex-include/txi-iwona.tex
+++ /dev/null
@@ -1,91 +0,0 @@
-\def \txifontrm {qx-iwonar}
-\def \txifontbf {qx-iwonab}
-\def \txifontit {qx-iwonari}
-\def \txifontsl {qx-iwonari}
-\def \txifontsc {qx-iwonarcap}
-\def \txifontsf {pagk7t}
-\def \txifonttt {cmtt10}
-\def \txifontttsl {cmitt10}
-\def \altsuff {}
-
-\def \definetextfontsizexi {% Text fonts (11.2pt, magstep1).
- \def \smallernominalsize {8pt}
- \txifontonesize{smaller}{800}
-
- \def \smallnominalsize {9pt}
- \txifontonesize{small}{900}
-
- \def \reducednominalsize {10pt}
- \txifontonesize{reduced}{1000}
-
- \def \textnominalsize {11pt}
- \edef \mainmagstep {\magstephalf}
- \txifontonesize{text}{\mainmagstep}
- \global\let \defbf = \textbf
- \global\let \deftt = \texttt
- \global\let \defttsl = \textttsl
- \def\df{%
- \let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf
- }
-
- \def \ssecnominalsize {13pt}
- \txifontonesize{ssec}{1300}
-
- \def \secnominalsize {14pt}
- \txifontonesize{sec}{1400}
-
- \def \chapnominalsize {17pt}
- \txifontonesize{chap}{1700}
-
- \def \titlenominalsize {20pt}
- \txifontonesize{title}{2000}
-
- % Reset the current fonts
- \textfonts
- \rm
-}
-
-\def \definetextfontsizex {% Text fonts (10pt).
- \def \smallernominalsize {8pt}
- \txifontonesize{smaller}{800}
-
- \def \smallnominalsize {9pt}
- \txifontonesize{small}{900}
-
- \def \reducednominalsize {9pt}
- \txifontonesize{reduced}{900}
-
- \def \textnominalsize {10pt}
- \edef \mainmagstep {1000}
- \txifontonesize{text}{\mainmagstep}
- \global\let \defbf = \textbf
- \global\let \deftt = \texttt
- \global\let \defttsl = \textttsl
- \def\df{%
- \let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf
- }
-
- \def \ssecnominalsize {10pt}
- \txifontonesize{ssec}{1000}
-
- \def \secnominalsize {12pt}
- \txifontonesize{sec}{1200}
-
- \def \chapnominalsize {14pt}
- \txifontonesize{chap}{1400}
-
- \def \titlenominalsize {20pt}
- \txifontonesize{title}{2000}
-
- % Reduce space between paragraphs
- \divide\parskip by 2
-
- % Reset the current fonts
- \textfonts
- \rm
-}
-
-\ifx \textsizearg\xword \definetextfontsizex
-\else \definetextfontsizexi \fi
-
-\endinput
diff --git a/docs/tools/Makefile.am b/docs/tools/Makefile.am
deleted file mode 100644
index 1042692310..0000000000
--- a/docs/tools/Makefile.am
+++ /dev/null
@@ -1,9 +0,0 @@
-
-AM_CPPFLAGS = @CPPFLAGS@ -I$(srcdir)/../../libutils
-LDADD = ../../libcompat/libcompat.la
-
-noinst_PROGRAMS = build-solutions-guide build-stdlib
-
-noinst_SCRIPTS = texi2pdfclean extract-images
-
-EXTRA_DIST = texi2pdfclean extract-images
diff --git a/docs/tools/build-solutions-guide.c b/docs/tools/build-solutions-guide.c
deleted file mode 100644
index 3d5121de3a..0000000000
--- a/docs/tools/build-solutions-guide.c
+++ /dev/null
@@ -1,132 +0,0 @@
-/*****************************************************************************/
-/* */
-/* File: build_solutions_guide.c */
-/* */
-/* Created: Fri Aug 19 11:06:29 2011 */
-/* */
-/*****************************************************************************/
-
-#include
-#include
-#include
-#include
-
-static void Manual(const char *examples_dir);
-
-/*****************************************************************************/
-
-int main(int argc, char **argv)
-{
- if (argc != 2)
- {
- fprintf(stderr, "Usage: build_solutions_guide < in > out\n");
- return 2;
- }
-
- Manual(argv[1]);
- return 0;
-}
-
-/*****************************************************************************/
-
-/*
- * Strips out \n from the end of line
- */
-static void Chomp(char *str)
-{
- char *s = strrchr(str, '\n');
-
- if (s)
- {
- *s = '\0';
- }
-}
-
-/*****************************************************************************/
-
-#define EXAMPLE_INCLUDE_TOKEN "#CFEexample:"
-#define EXAMPLE_HEADER_TOKEN "COSL.txt"
-
-static void IncludeExampleFile(const char *examples_dir, const char *filename)
-{
- char path[2048];
-
- snprintf(path, sizeof(path), "%s/%s", examples_dir, filename);
-
- FILE *example_fh = fopen(path, "r");
-
- if (example_fh == NULL)
- {
- fprintf(stderr, "Unable to find file %s to include.\n", path);
- exit(1);
- }
-
-/* Skip header */
- while (!feof(example_fh))
- {
- char line[2048];
- line[0] = '\0';
-
- if (fgets(line, sizeof(line), example_fh) != NULL)
- {
- if (strstr(line, "COSL.txt"))
- {
- break;
- }
- }
- }
-
- while (!feof(example_fh))
- {
- char buf[4096];
- size_t read_ = fread(buf, 1, 4096, example_fh);
-
- if (read_ < 4096 && ferror(example_fh))
- {
- fprintf(stderr, "Error reading example file %s. Bailing out.\n", path);
- exit(1);
- }
-
- if (fwrite(buf, 1, read_, stdout) < read_)
- {
- fprintf(stderr, "Error writing to stdout. Bailing out.\n");
- exit(1);
- }
- }
-
- fclose(example_fh);
-}
-
-static void Manual(const char *examples_dir)
-{
- for (;;)
- {
- char line[2048];
-
- if (fgets(line, sizeof(line), stdin) == NULL)
- {
- if (ferror(stdin))
- {
- fprintf(stderr, "Error during reading stdin. Bailing out.\n");
- exit(1);
- }
- else
- {
- return;
- }
- }
-
- if (strstr(line, EXAMPLE_INCLUDE_TOKEN))
- {
- char *filename = strstr(line, EXAMPLE_INCLUDE_TOKEN) + strlen(EXAMPLE_INCLUDE_TOKEN);
-
- Chomp(filename);
-
- IncludeExampleFile(examples_dir, filename);
- }
- else
- {
- fputs(line, stdout);
- }
- }
-}
diff --git a/docs/tools/build-stdlib.c b/docs/tools/build-stdlib.c
deleted file mode 100644
index 33e5f2cd22..0000000000
--- a/docs/tools/build-stdlib.c
+++ /dev/null
@@ -1,308 +0,0 @@
-/*****************************************************************************/
-/* */
-/* File: build_procedures.c */
-/* */
-/* Created: Fri Dec 4 18:30:52 2009 */
-/* */
-/*****************************************************************************/
-
-#include "platform.h"
-#include
-#include
-
-struct Item
- {
- char done;
- char *name;
- char *classes;
- int counter;
- struct Item *next;
- };
-
-void PrependItem(struct Item **liststart,char *itemstring,char *classes);
- struct Item *SortItemListNames(struct Item *list);
-int IncludeManualFile(FILE *fout,char *file);
-
-
-int main(int argc, char *argv[])
-
-{ FILE *fin,*fout = NULL;
- struct Item *ip,*contents = NULL;
- char buffer[1024],type[1024],control[1024],data[1024],name[1024];
-
- if (argc != 2)
- {
- fprintf(stderr, "Usage: build-stdlib \n");
- return 1;
- }
-
-if ((fin = fopen(argv[1],"r")) == NULL)
- {
- printf("Could not open the %s file\n", argv[1]);
- return 1;
- }
-
-
-while(!feof(fin))
- {
- buffer[0] = '\0';
- control[0] = '\0';
- data[0] = '\0';
- type[0] = '\0';
- fgets(buffer, sizeof(buffer),fin);
-
- if (strncmp(buffer,"##",2) == 0)
- {
- continue;
- }
-
- sscanf(buffer,"%s %s %[^(\n]",type,data,control);
-
- if (strncmp(type,"body",4) == 0 || strncmp(type,"bundle",6) == 0)
- {
- if (fout)
- {
- fclose(fout);
- fout = NULL;
- }
-
- snprintf(name,1024,"%s_%s_%s.tmp",type,data,control);
-
- if ((fout = fopen(name,"w")) == NULL)
- {
- printf("Could not open output file %s\n",name);
- return 2;
- }
-
- fprintf(fout,"%s",buffer);
- PrependItem(&contents,buffer,"");
- }
- else if (fout)
- {
- fprintf(fout,"%s",buffer);
- }
- else
- {
- printf("XXXX %s",buffer);
- }
- }
-
-if (fout)
- {
- fclose(fout);
- fout = NULL;
- }
-
-if ((fout = fopen("CfengineStdLibrary.texinfo","w")) == NULL)
- {
- printf("Could not open the CfengineStdLibrary.texinfo file\n");
- return 3;
- }
-
-IncludeManualFile(fout,"preamble.texinfo");
-
-contents = SortItemListNames(contents);
-
-for (ip = contents; ip != NULL; ip=ip->next)
- {
- sscanf(ip->name,"%s %s %[^(\n]",type,data,control);
- fprintf(fout,"@node %s %s %s\n",type,data,control);
- fprintf(fout,"@section %s\n",ip->name);
-
- fprintf(fout,"@verbatim\n");
- snprintf(name,1024,"%s_%s_%s.tmp",type,data,control);
- IncludeManualFile(fout,name);
- fprintf(fout,"@end verbatim\n\n");
- }
-
-IncludeManualFile(fout,"postamble.texinfo");
-
-fclose(fin);
-fclose(fout);
-}
-
-/*****************************************************************************/
-
-
-
-/*****************************************************************************/
-
-int IncludeManualFile(FILE *fout,char *file)
-
-{ char buffer[1024];
- FILE *fp;
-
-if ((fp = fopen(file,"r")) == NULL)
- {
- printf("Could not read %s\n",file);
- return 1;
- }
-
-while(!feof(fp))
- {
- buffer[0] = '\0';
- fgets(buffer, sizeof(buffer),fp);
- fprintf(fout,"%s",buffer);
- }
-
-fclose(fp);
-
-return 0;
-}
-
-
-
-
-
-/* CODE FROM CFENGINE .....*/
-
-/*********************************************************************/
-
-void PrependItem(struct Item **liststart,char *itemstring,char *classes)
-
-{ struct Item *ip;
- char *sp,*spe = NULL;
-
-if ((ip = (struct Item *)malloc(sizeof(struct Item))) == NULL)
- {
- return;
- }
-
-if ((sp = malloc(strlen(itemstring)+2)) == NULL)
- {
- return;
- }
-
-if ((classes != NULL) && (spe = malloc(strlen(classes)+2)) == NULL)
- {
- return;
- }
-
-strcpy(sp,itemstring);
-ip->name = sp;
-ip->next = *liststart;
-ip->counter = 0;
-*liststart = ip;
-
-if (classes != NULL)
- {
- strcpy(spe,classes);
- ip->classes = spe;
- }
-else
- {
- ip->classes = NULL;
- }
-}
-
-/*******************************************************************/
-
-/* Borrowed this algorithm from merge-sort implementation */
-
-struct Item *SortItemListNames(struct Item *list) /* Alphabetical */
-
-{ struct Item *p, *q, *e, *tail;
- int insize, nmerges, psize, qsize, i;
-
-if (list == NULL)
- {
- return NULL;
- }
-
-insize = 1;
-
-while (true)
- {
- p = list;
- list = NULL;
- tail = NULL;
-
- nmerges = 0; /* count number of merges we do in this pass */
-
- while (p)
- {
- nmerges++; /* there exists a merge to be done */
- /* step `insize' places along from p */
- q = p;
- psize = 0;
-
- for (i = 0; i < insize; i++)
- {
- psize++;
-
- q = q->next;
-
- if (!q)
- {
- break;
- }
- }
-
- /* if q hasn't fallen off end, we have two lists to merge */
- qsize = insize;
-
- /* now we have two lists; merge them */
- while (psize > 0 || (qsize > 0 && q))
- {
- /* decide whether next element of merge comes from p or q */
- if (psize == 0)
- {
- /* p is empty; e must come from q. */
- e = q;
- q = q->next;
- qsize--;
- }
- else if (qsize == 0 || !q)
- {
- /* q is empty; e must come from p. */
- e = p;
- p = p->next;
- psize--;
- }
- else if (strcmp(p->name, q->name) <= 0)
- {
- /* First element of p is lower (or same);
- * e must come from p. */
- e = p;
- p = p->next;
- psize--;
- }
- else
- {
- /* First element of q is lower; e must come from q. */
- e = q;
- q = q->next;
- qsize--;
- }
-
- /* add the next element to the merged list */
- if (tail)
- {
- tail->next = e;
- }
- else
- {
- list = e;
- }
-
- tail = e;
- }
-
- /* now p has stepped `insize' places along, and q has too */
- p = q;
- }
-
- tail->next = NULL;
-
- /* If we have done only one merge, we're finished. */
-
- if (nmerges <= 1) /* allow for nmerges==0, the empty list case */
- {
- return list;
- }
-
- /* Otherwise repeat, merging lists twice the size */
- insize *= 2;
- }
-}
-
diff --git a/docs/tools/extract-images b/docs/tools/extract-images
deleted file mode 100755
index 2bf96ffa27..0000000000
--- a/docs/tools/extract-images
+++ /dev/null
@@ -1,30 +0,0 @@
-#!/bin/sh -e
-
-if [ "$#" -eq 0 ]; then
- echo "Usage: extract-images ..."
- echo
- echo " This tool extracts all image file names referenced in Texinfo file"
- echo " and prints them out to standard output"
-
- exit 1
-fi
-
-# @c are comments
-# ...@image{filename,...,...,..}... -> filename.png
-# ...@image{filename,...,...,..,extension}... -> filename.extension
-
-for f in "$@"; do
- d=$(dirname "$f")
- images=$(sed -n \
- -e 's%^@c .*%%' \
- -e 's%^.*@image{\([^,]*\),[^,]*,[^,]*,[^,]*,\([^,}]*\)}.*$%'"$d"'/\1.\2%p' \
- -e 's%^.*@image{\([^,]*\)[^}]*}.*$%'"$d"'/\1.png%p' \
- "$f")
- for image in $images; do
- if [ -f $(basename "$image") ]; then
- printf "%s\n" $(basename "$image")
- else
- printf "%s\n" "$image"
- fi
- done
-done
diff --git a/docs/tools/texi2pdfclean b/docs/tools/texi2pdfclean
deleted file mode 100755
index ac4f05ffbb..0000000000
--- a/docs/tools/texi2pdfclean
+++ /dev/null
@@ -1,24 +0,0 @@
-#!/bin/sh
-
-#
-# Clean garbage generated by texi2pdf. Note that --build=clean does not work
-# properly, as it breaks relative links to the images in .texinfo file.
-#
-
-INPUT=$1
-shift
-
-clean_garbage() {
- retcode=$?
- for ext in aux cp cps fn ky log pg toc tp vr; do
- rm -f ${INPUT%.texinfo}.$ext
- done
- if [ $retcode -ne 0 ]; then
- rm -f ${INPUT%.texinfo}.pdf
- fi
- exit $retcode
-}
-
-trap clean_garbage 0 INT QUIT
-
-"$@" "$INPUT"