Bootstrapping the Environment ============================= Most hosts that are built with `boxconf` depend on at least two other hosts being available: 1. The IDM (identity management) server. This server provides DNS, Kerberos authentication, and LDAP user and group lookups. 2. The package repository. Almost all hosts are FreeBSD, and they depend on the local `poudriere` server which hosts in-house packages built with custom options. The IDM servers and the package repo are themselves built with boxconf, but you must build them in a specific order to solve the chicken-and-egg problem. ## Step 1: The Hypervisor It is assumed that most hosts will be FreeBSD jails. Therefore, you will need a FreeBSD "hypervisor" along with our custom `jailctl` script. Boxconf can be used to configure a FreeBSD hypervisor for running jails and bhyve VMs. The only requirement for this server is a NIC that supports VLAN tagging. By default, this interface is assumed to be `lagg0`. Boxconf assumes any host named `alcatraz[0-9]` has the `freebsd_hypervisor` hostclass. Therefore, you can run the following to setup the jail host: ./boxconf -s $FREEBSD_HYPERVISOR_IP alcatraz1 Then, on `alcatraz1`, download a FreeBSD rootfs image used for templating jails: alcatraz1# jailctl download-release 14.1-RELEASE ## Step 2: The Pkg Repository First, we'll need a jail to serve as our Poudriere server. This jail will build 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.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.99.99.4 \ -k ~/id_ed25519.pub \ -c 64-95 \ -m 32g \ -q 256g \ -e mount.procfs=true \ -e allow.mount.tmpfs=true \ -e allow.mount.devfs=true \ -e allow.mount.procfs=true \ -e allow.mount.nullfs=true \ -e allow.mount.linprocfs=true \ -e allow.raw_sockets=true \ -e allow.socket_af=true \ -e allow.mlock=true \ -e sysvmsg=new \ -e sysvsem=new \ -e sysvshm=new \ -e children.max=1000 \ pkg1 freebsd14.1 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 -s 10.99.99.4 pkg1 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