doc: Add a lot more unsorted stuff from the wiki

Signed-off-by: Sol Jerome <solj@ices.utexas.edu>

git-svn-id: https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2@5703 ce84e21b-d406-0410-9b95-82705330c041

4 files changed, 116 insertions, 4 deletions

diff --git a/doc/client/agent.txt b/doc/client/agent.txt
new file mode 100644
index 000000000..1a3b4b2eb
--- /dev/null
+++ b/doc/client/agent.txt
@@ -0,0 +1,39 @@
+.. -*- mode: rst -*-
+
+.. _client-agent:
+
+=============================
+Agent Functionality using SSH
+=============================
+
+The Bcfg2 agent code provides the ability to trigger a client update from the server using a secure mechanism that is restricted to running the bcfg2 client with the options the agent was started with. This same capability is provided by SSH keypairs, if properly configured. Setup is pretty easy:
+
+#. Create an ssh keypair that is to be used solely for triggering bcfg2 client runs. This key may or may not have a password associated with it; a keyphrase will make things more secure, but will require a person to enter the key passphrase, so it will not be usable automatically.::
+
+    $ ssh-keygen -t dsa -b 1024 -f /path/to/key -N ""
+    Generating public/private dsa key pair.
+    Your identification has been saved in /path/to/key.
+    Your public key has been saved in /path/to/key.pub.
+    The key fingerprint is:
+    aa:25:9b:a7:10:60:f3:eb:2b:ae:4b:1a:42:1b:63:5d desai@ubik
+
+#. Add this this public key to root's authorized_keys file, with several commands prepended to it::
+
+    command="/usr/sbin/bcfg2 -q <other options>",no-port-forwarding,no-X11-forwarding,no-pty,no-agent-forwarding,from="<bcfg2-server ipaddr>" <pub key>
+
+   This key is now only useful to call the bcfg2 client, from the bcfg2-server's ip address. If PermitRootLogin was set to no in sshd_config, you will need to set it to forced-commands-only. Adding a & to the end of the command will cause the command to immediately return. 
+
+#. Now, to cause a client to reconfigure, call::
+
+    $ ssh -i /path/to/key root@client /usr/sbin/bcfg2
+
+   Note that you will not be able to alter the command line options from the ones specified in authorized_keys in any way. Also, it is not needed that the invocation of bcfg2 in the ssh command match. The following will have the same result.::
+
+    $ ssh -i /path/to/key root@client /bin/true
+
+   If a passphrase was used to create the keypair, then it will need to be entered here. 
+
+See Also
+========
+
+`SSH "triggers" <http://blog.ganneff.de/blog/2007/12/29/ssh-triggers.html>`_ (from Ganneff's Little Blog)
diff --git a/doc/client/debugging.txt b/doc/client/debugging.txt
new file mode 100644
index 000000000..c99e73c3e
--- /dev/null
+++ b/doc/client/debugging.txt
@@ -0,0 +1,24 @@
+.. -*- mode: rst -*-
+
+.. _client-debugging:
+
+================
+Client Debugging
+================
+
+When working on the Bcfg2 client, it is helpful to employ a few specific techniques to isolate and remedy problems.
+
+First, running the client with the -f flag allows configuration from a local file, rather than querying the server. This helps rule out server configuration problems, and allows for rapid development. For example: `bcfg2 -f test-config.conf` with the following test-config.conf:
+
+.. code-block:: rst
+
+    <Configuration>
+        <Bundle name="ssh-tests">
+            <Service type="launchd" name="com.openssh.sshd" status="on" />
+        </Bundle>
+    </Configuration>
+
+Next, it is important to look at the interactive mode. This is similar to the interactive mode on the server and provides an interactive Python interpreter with which one may manipulate all the objects in the client. It will setup all the infrastructure so you will have the appropriate objects to play with. It will run the client through once, then present you with an interpreter. Try it out with: `python -i /usr/bin/bcfg2` or, for more fun, a local config file and also enable Debugging and Verbose output with `-d` and `-v`, yielding `python -i /usr/bin/bcfg2 -d -v -f test-config.conf`
+
+Now we just explore; use `dir()` to examine different objects in the client, or run a reconfiguration again by calling `client.run()`
+
diff --git a/doc/client/index.txt b/doc/client/index.txt
index 163caf8af..96787814f 100644
--- a/doc/client/index.txt
+++ b/doc/client/index.txt
@@ -2,7 +2,6 @@
 
 .. _client-index:
 
-================
 The Bcfg2 Client
 ================
 
@@ -12,13 +11,19 @@ processing of the target configuration description. We chose this
 architecture, as opposed to one with a smarter client, for a few reasons:
 
 * Client failure forces administrators to perform an O(n) reconfiguration operation. Simpler code is easier to debug and maintain.
-* Minimize the bootstrap size; a complicated client can require more aspects of the system to function in order for reconfiguration to work. 
-* Isolate configuration generation functionality on the server, where it can be readily observed. This is the most complicated task that Bcfg2 performs. 
+* Minimize the bootstrap size; a complicated client can require more aspects of the system to function in order for reconfiguration to work.
+* Isolate configuration generation functionality on the server, where it can be readily observed. This is the most complicated task that Bcfg2 performs.
 * The results of the configuration process fit a fairly simple model. We wanted to validate it. The result is that Bcfg2 has a programmable deployment engine that can be driven by anything that writes a compatible configuration description.
 
 .. toctree::
    :maxdepth: 2
+
+   agent
+   debugging
+   metadata
+
+.. toctree::
+   :maxdepth: 2
    :glob:
 
-   *
    tools/*
diff --git a/doc/client/metadata.txt b/doc/client/metadata.txt
new file mode 100644
index 000000000..6675f59d7
--- /dev/null
+++ b/doc/client/metadata.txt
@@ -0,0 +1,44 @@
+.. -*- mode: rst -*-
+
+.. _client-metadata:
+
+===============
+Client Metadata
+===============
+
+This page describes ClientMetadata objects. These are used to describe clients in terms of a variety of parameters, group memberships, and so forth.
+
+Construction
+============
+
+ClientMetadata instances are constructed whenever the server needs to recognize a client. This occurs in every aspect of client server interaction:
+
+* Probing
+* Configuration Generation
+* Statistics Upload
+
+This construction process spans several server plugins. The [wiki:Plugins/Metadata Metadata plugin] is responsible for initial instance creation, including the client hostname, profile, and basic group memberships. After this initial creation, Connector plugins (such as [wiki:Plugins/Probes Probes] or [wiki:Plugins/Properties Properties]) can add additional group memberships for clients. These memberships are merged into the instance; that is, the new group memberships are treated as if they were included in groups.xml. If any of these groups are defined in groups.xml, then groups included there are included in the ClientMetadata instance group list. At the end of this process, the ClientMetadata instance has its complete set of group memberships. At this point, each connector plugin has the opportunity to return an additional object which will be placed in an attribute corresponding to the Connector name. For example, the Probes plugin returns a dictionary of probe name to probe result mappings for the client. This dictionary is available as the "Probes" attribute. With this, ClientMetadata resolution is complete, and the ClientMetadata instance can be used by the rest of the system.
+
+Contents
+========
+
+ClientMetadata instances contain all of the information needed to differentiate clients from one another. This data includes:
+
+* hostname
+* groups
+* profile group
+* address information (if specified)
+
+ClientMetadata instances also contain a query object. This can be used to query the metadata of other clients. Currently, several methods are supported. In this table, we refer to the instance as meta. Each of these is a function that must be called.
+
+|| Name || Description || Return Type ||
+|| meta.query.names_by_groups([group list]) || Returns names of clients which are members of all groups || List of client names ||
+|| meta.query.names_by_profile(profile) || Returns names of clients which use profile group || List of client names ||
+|| meta.query.all_clients() || Returns names of all clients || List of client names ||
+|| meta.query.all_groups() || Returns names of all groups || List of group names ||
+|| meta.query.all() || Returns metadata for all clients || List of ClientMetadata instances ||
+|| meta.query.by_name(name) || Returns metadata for named client || ClientMetadata instance ||
+|| meta.query.by_groups([group list]) || Returns metadata for all members of all groups || List of ClientMetadata instances ||
+|| meta.query.by_profile(profile) || Returns metadata for all profile havers || List of ClientMetadata instances ||
+
+In general, there is no substantial benefit to using name returning versions of the query functions; metadata resolution is (in general) fast.