halfway working idm server and laptop hostclasses

1 files changed, 128 insertions, 3 deletions

diff --git a/docs/10-bootstrapping.md b/docs/10-bootstrapping.md
index 05f8867..cda5c80 100644
--- a/docs/10-bootstrapping.md
+++ b/docs/10-bootstrapping.md
@@ -41,13 +41,13 @@ all the necessary packages and serve them over HTTP.
 
 On the FreeBSD hypervisor, use `jailctl` to create a jail for the `pkg` repo.
 The following command will create a jail named `pkg1` with VLAN tag `199`,
-IP address `10.11.199.4`, 32G memory limit, 256G disk quota, and 32 CPU cores.
+IP address `10.99.99.4`, 32G memory limit, 256G disk quota, and 32 CPU cores.
 Note that running `poudriere` in a jail requires many custom jail options, which
 are also set with this command.
 
     alcatraz1# jailctl create \
       -v 199 \
-      -a 10.11.199.4 \
+      -a 10.99.99.4 \
       -k ~/id_ed25519.pub \
       -c 64-95 \
       -m 32g \
@@ -70,7 +70,132 @@ are also set with this command.
 Now you are ready to build all the packages and create the repository. `boxconf`
 assumes that any host named `pkg[0-1]` has the `pkg_repository` hostclass.
 
-    ./boxconf -e idm_bootstrap=true 10.11.199.4
+    ./boxconf -e idm_bootstrap=true 10.99.99.4
 
 Substitute whatever IP you chose for the `pkg1` jail as necessary. Note that it
 will take a while to build all the packages for the first time.
+
+
+## Step 3: The IDM Servers
+
+Next, we'll build the IDM jails. While you technically only need one, you should
+build at least two so that you can reboot one of them without causing a DNS
+outage for your entire environment.
+
+
+### Create the Jails
+
+Let's two jails named `idm1` and `idm2`. Note that `boxconf` assumes any host
+named `idm[0-9]` has the `idm_server` hostclass.
+
+    alcatraz1# jailctl create \
+      -v 199 \
+      -a 10.99.99.2 \
+      -k ~/id_ed25519.pub \
+      -c 2-3 \
+      -m 4g \
+      -q 32G \
+      idm1 freebsd14
+
+    alcatraz1# jailctl create \
+      -v 199 \
+      -a 10.99.99.3 \
+      -k ~/id_ed25519.pub \
+      -c 4-5 \
+      -m 4g \
+      -q 32G \
+      idm2 freebsd14
+
+
+## Set Boxconf Variables
+
+Before continuing, you'll need to tailor `site/vars/common` to your
+environment:
+
+  - The `domain` variable must contain your internal domain name. Eg:
+
+        domain=idm.example.com
+
+  - The `pkg_host_ip` variable must contain the IP address of the `pkg1` jail:
+
+        pkg_host_ip=10.99.99.4
+
+  - The `idm_server_list` variable must contain a newline-separated list of
+    IDM server hostnames, along with their associated LDAP server ID and IP address.
+    These should be the IPs of the jails you just created.
+
+    The server ID can be any number 1-9, as long as it is unique for each host
+    and you never, ever change it. Eg:
+
+        idm_server_list="\
+        idm1  1  10.99.99.2
+        idm2  2  10.99.99.3"
+
+  - The `reverse_dns_zones` variable must contain a space-separated list of
+    all the reverse DNS zones in your environment. Eg:
+
+        reverse_dns_zones="\
+        99.99.10.in-addr.arpa
+        88.99.10.in-addr.arpa"
+
+    Note: only 3-octet IPv4 zones are supported (`10.in-addr.arpa` won't work).
+
+
+## Create TLS Certificates
+
+We will also need some TLS certificates for the LDAP servers. These certificates
+allow for secure replication between the LDAP daemons on the IDM servers.
+
+First, initialize the PKI. This will create a root certificate authority with
+a name contraint for hostnames underneath your internal domain.
+
+*However,* the LDAP servers replicate using their IP addresses, rather than DNS
+names. Therefore, you will need to specify additional constraints for the IP
+address of each IDM server. Eg:
+
+    ./pki init \
+      -c IP:10.99.0.0/255.255.0.0 \
+      idm.example.com
+
+Next, create server certificates for each IDM server. Each certificate will
+need three SANs:
+
+  - The FQDN of the IDM server.
+  - The IP of the IDM server.
+  - The bare domain name (we'll make this a multi-valued A record later).
+
+Eg:
+
+    ./pki cert -d 3650 idm1 slapd idm1.idm.example.com IP:10.99.99.2 idm.example.com
+    ./pki cert -d 3650 idm2 slapd idm2.idm.example.com IP:10.99.99.3 idm.example.com
+
+Finally, create a client certificate for the OpenLDAP replicator DN. Eg:
+
+    ./pki client-cert -d 3650 idm1 replicator cn=replicator,dc=idm,dc=example,dc=com
+    ./pki client-cert -d 3650 idm2 replicator cn=replicator,dc=idm,dc=example,dc=com
+
+
+## Configure the IDM servers.
+
+Now, you're ready to build the IDM servers!
+
+The first server in the `$idm_server_list` is somewhat special, as the
+`boxconf` scripts will use that one to create all the initial LDAP objects.
+So make sure you configure that one first.
+
+    ./boxconf -s 10.99.99.2 -e idm_bootstrap=true idm1
+    ./boxconf -s 10.99.99.3 -e idm_bootstrap=true idm2
+
+
+## Verify LDAP replication, DNS, etc.
+
+If everything is working, you should get the same result from each of the
+following `dig` queries:
+
+    $ dig +short @10.99.99.2 idm.example.com
+    10.99.99.3
+    10.99.99.2
+
+    $ dig +short @10.99.99.3 idm.example.com
+    10.99.99.3
+    10.99.99.2