diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/10-bootstrapping.md | 76 |
1 files changed, 76 insertions, 0 deletions
diff --git a/docs/10-bootstrapping.md b/docs/10-bootstrapping.md new file mode 100644 index 0000000..05f8867 --- /dev/null +++ b/docs/10-bootstrapping.md @@ -0,0 +1,76 @@ +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.11.199.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 \ + -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 10.11.199.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. |