1 files changed, 86 insertions, 0 deletions
diff --git a/doc/appendix/guides/nat_howto.txt b/doc/appendix/guides/nat_howto.txt
new file mode 100644
index 000000000..818d3e644
--- /dev/null
+++ b/doc/appendix/guides/nat_howto.txt
@@ -0,0 +1,86 @@
+.. -*- mode: rst -*-
+
+.. _appendix-guides-nat_howto:
+
+=========
+NAT HOWTO
+=========
+
+This page describes how to setup Bcfg2 to properly function with a
+collection of clients behind NAT. It describes the issues, how the
+underlying portions of the Bcfg2 system function, and how to correctly
+setup client metadata to cope with this environment.
+
+Issues
+======
+
+Bcfg2, by default, uses ip address lookup to determine the identity of
+a client that has connected. This process doesn't work properly in the
+case of NAT'ed hosts, because all requests from these clients come from
+the same external address when connecting to the server.
+
+These client identification issues will manifest themselves in a number
+of ways:
+
+* Inability to setup discrete clients with different profiles
+* Incorrect sharing of probe results across clients in the same NAT pool
+* Inability to bootstrap clients properly when client data is not
+  predefined
+
+Architectural Issues
+====================
+
+Client identification is performed at the beginning of each client/server
+interaction. As of 0.9.3, client identification via IP address can be
+completely short-circuited through the use of a client uuid. Setup of
+client uuids requires actions of both the client and server. On the
+server side, the client uuid must be added to the client record in
+``Metadata/clients.xml``. This attribute allows the server to use the
+user part of the authentication to resolve the client's metadata. Also,
+either the location attribute should be set to floating, or the IP address
+of the NAT must be reflected in the address attribute.  Once added,
+the Client entry in clients.xml will look something like this:
+
+.. code-block:: xml
+
+    <Client profile="desktop" name="test1" pingable="N"
+     uuid='9001ec29-1531-4b16-8198-a71bea093d0a' location='floating'/>
+
+Alternatively, the Client entry can be setup like this:
+
+.. code-block:: xml
+
+    <Client profile="desktop" name="test1" pingable="N"
+     uuid='9001ec29-1531-4b16-8198-a71bea093d0a' address='ip-address-of-NAT'/>
+
+The difference between these definitions is explained in detail in the
+:ref:`appendix-guides-authentication` section, but in short, the second
+form requires that the client access the server from the NAT address,
+while the first form allows it to connect from any address provided it
+uses the proper uuid. (Client identification is orthogonal to the use
+of per-client passwords; this can be set in addition to the attributes
+above.)
+
+Once this setup is done, each client must be configured to use the proper
+uuid upon any server interaction. This can be done using either the
+command line argument -u, or the setting "user" in the "communication"
+section of ``/etc/bcfg2.conf``.
+
+UUID Choice
+===========
+
+When determining client UUIDs, one must take care to ensure that UUIDs
+are unique to the client. Any hardware-specific attribute, like a hash
+of a mac address would be sufficient. Alternatively, if a local hostname
+is unique, it may be used as well.
+
+Automated Client Bootstrapping
+==============================
+
+Automated setup of new clients from behind NAT works by using the common
+password. For example::
+
+    /usr/sbin/bcfg2 -u ubik3 -p desktop -x <password>
+
+It is not possible at this time to do automated setup without setting
+up a pre-shared per-client key.