workshop: Update docs and support default cloud image

Update instructions on how to build images starting with Fedora 34 using
kickstart files used by Fedora to build its cloud images.

Change vagrant provisioning steps to support both prebuilt and default
cloud images, removing the burden of maintaining boxes up-to-date, but
also providing a way to build fresh images without external packer
templates.

Signed-off-by: Armando Neto <abiagion@redhat.com>
Reviewed-By: Florence Blanc-Renaud <flo@redhat.com>
Reviewed-By: Rob Crittenden <rcritten@redhat.com>

.gitignore

@@ -57,6 +57,12 @@ py-compile
 freeipa2-dev-doc
 ~/doc/guide/Makefile
 
+# Workshop
+doc/workshop/.vagrant/
+doc/workshop/packer_cache/
+doc/workshop/output-*/
+doc/workshop/anaconda-ks.cfg
+
 # Root directory
 /freeipa.spec
 /dist/

doc/Makefile

@@ -23,12 +23,6 @@ help:
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: workshop-remote workshop-pull
-workshop-remote:
-	git remote add -f freeipa-workshop https://github.com/freeipa/freeipa-workshop.git
-workshop-pull:
-	git pull -s subtree freeipa-workshop master
-
 .PHONY: lint
 lint:
 	$(MAKE) html SPHINXOPTS="$(SPHINXOPTS) -E -a"

doc/workshop.rst

@@ -6,7 +6,6 @@ FreeIPA workshop
    :caption: Workshop:
 
    workshop/workshop.rst
-   workshop/building.rst
    workshop/1-server-install.rst
    workshop/2-client-install.rst
    workshop/3-user-management.rst
@@ -18,4 +17,10 @@ FreeIPA workshop
    workshop/9-selinux-user-map.rst
    workshop/10-ssh-key-management.rst
    workshop/11-kerberos-ticket-policy.rst
+
+.. toctree::
+   :includehidden:
+
    workshop/troubleshooting.rst
+   workshop/building.rst
+   workshop/facilitators.rst

doc/workshop/Vagrantfile

@@ -3,7 +3,11 @@
 
 Vagrant.configure(2) do |config|
 
-  config.vm.box = "netoarmando/freeipa-workshop"
+  # Replace this with "fedora/34-cloud-base" (or latest) for a fresh box without
+  # pre-installed freeipa packages, you must also uncomment shell provisioning step
+  # at the bottom of this file.
+  # config.vm.box = "fedora/34-cloud-base"
+  config.vm.box = "freeipa/freeipa-workshop"
 
   config.vm.synced_folder ".", "/vagrant", disabled: true
 
@@ -12,22 +16,21 @@ Vagrant.configure(2) do |config|
     libvirt.memory = 1024
   end
 
-  # Vagrant's "change host name" sets the short host name.  Before
-  # we repair /etc/hosts (see below) let's reset /etc/hostname to
-  # the *full* host name
-  #
-  config.vm.provision "shell",
-    inline: "hostname --fqdn > /etc/hostname && hostname -F /etc/hostname"
-
-  # Vagrant's "change host name" capability for Fedora maps hostname
-  # to loopback.  We must repair /etc/hosts
-  #
-  config.vm.provision "shell",
-    inline: "sed -ri 's/127\.0\.0\.1\s.*/127.0.0.1 localhost localhost.localdomain/' /etc/hosts"
+  config.vm.provider :virtualbox do |virtualbox|
+    virtualbox.memory = 1536
+  end
 
   config.vm.define "server" do |server|
     server.vm.network "private_network", ip: "192.168.33.10"
     server.vm.hostname = "server.ipademo.local"
+
+    config.vm.provider "virtualbox" do |v|
+      v.memory = 1536
+    end
+    config.vm.provider "libvirt" do |v|
+      v.memory = 1536
+    end
+
   end
 
   config.vm.define "replica" do |replica|
@@ -39,7 +42,17 @@ Vagrant.configure(2) do |config|
     replica.vm.provision "shell",
       inline: 'echo "DNS1=192.168.33.10" >> /etc/sysconfig/network-scripts/ifcfg-eth1'
     replica.vm.provision "shell",
-      inline: 'echo "nameserver 192.168.33.10" > /etc/resolv.conf'
+      inline: 'printf "DNS=192.168.33.10\nDomains=~." >> /etc/systemd/resolved.conf'
+    replica.vm.provision "shell",
+      inline: 'systemctl restart systemd-resolved'
+
+    config.vm.provider "virtualbox" do |v|
+      v.memory = 1536
+    end
+    config.vm.provider "libvirt" do |v|
+      v.memory = 1536
+    end
+
   end
 
   config.vm.define "client" do |client|
@@ -51,7 +64,9 @@ Vagrant.configure(2) do |config|
     client.vm.provision "shell",
       inline: 'echo "DNS1=192.168.33.10" >> /etc/sysconfig/network-scripts/ifcfg-eth1'
     client.vm.provision "shell",
-      inline: 'echo "nameserver 192.168.33.10" > /etc/resolv.conf'
+      inline: 'printf "DNS=192.168.33.10\nDomains=~." >> /etc/systemd/resolved.conf'
+    client.vm.provision "shell",
+      inline: 'systemctl restart systemd-resolved'
     client.vm.provision "shell",
       inline: 'sudo sed -i "s/^/#/g" /etc/httpd/conf.d/ssl.conf'
     client.vm.provision "shell",
@@ -60,4 +75,8 @@ Vagrant.configure(2) do |config|
       inline: 'systemctl -q enable oddjobd && systemctl start oddjobd'
   end
 
+  # Uncomment line below when using Fedora's cloud base box.
+  # config.vm.provision "shell", path: "workshop-install-packages.sh"
+  config.vm.provision "shell", path: "workshop-ipa-customizations.sh"
+
 end

doc/workshop/app.py

@@ -1,14 +0,0 @@
-def application(environ, start_response):
-    start_response('200 OK', [('Content-Type', 'text/plain')])
-    remote_user = environ.get('REMOTE_USER')
-
-    if remote_user is not None:
-        yield "LOGGED IN AS: {}\n".format(remote_user).encode('utf8')
-    else:
-        yield b"NOT LOGGED IN\n"
-
-    yield b"\nREMOTE_* REQUEST VARIABLES:\n\n"
-
-    for k, v in environ.items():
-        if k.startswith('REMOTE_'):
-            yield "  {}: {}\n".format(k, v).encode('utf8')

doc/workshop/building.rst

@@ -8,55 +8,45 @@ Requirements
 ------------
 
 - Install packer (http://packer.io/)
-- Clone the packer-templates repository
-  (https://github.com/kaorimatz/packer-templates)
+- Install Vagrant, libvirt and VirtualBox
+- Clone the Fedora kickstarts repo (https://pagure.io/fedora-kickstarts)
 
 
 Packer template
 ---------------
 
-Apply the following changes to the ``fedora-28-x86_64.json`` packer
-template:
+Packer template ``packer-template-fedora.json`` requires Fedora 34 kickstart file
+used by Fedora to build vagrant images:
 
-- Add the ``scripts/fedora/ipa.sh`` provisioner and copy (or
-  symlink) ``ipa.sh`` from *this* repository to ``scripts/fedora``.
-  This script installs the FreeIPA packages and creates other files
-  required for the workshop.
+- Clone the repo and checkout latest Fedora release branch::
+
+  $ git clone https://pagure.io/fedora-kickstarts.git
+  $ cd fedora-kickstarts
+  $ git checkout f34
+
+- Install ``pykickstart`` package which provides ``ksflatten`` tool::
+
+  $ sudo dnf install pykickstart
+
+- Generate the ``anaconda-ks.cfg`` file needed by flattening vagrant kickstart files
+  and putting it onto the same folder as the packer template file::
+
+  $ ksflatten -c $FEDORA_KICKSTARTS_REPO/fedora-cloud-base-vagrant.ks > $FREEIPA_REPO/doc/workshop/anaconda-ks.cfg
 
 
-Building the virtualbox image
+Building the vagrant images
 -----------------------------
 
 Build the images::
 
-  $BIN_PACKER build -only=virtualbox-iso -var disk_size=4000 -var memory=1024 fedora-28-x86_64.json
-
-Packer stores images and other data in ``/tmp`` during processing.
-If you have limited space in ``/tmp`` set ``TMPDIR`` to point
-somewhere else with more space.
+  $ cd $FREEIPA_REPO/doc/workshop
+  $ BIN_PACKER build packer-template-fedora.json
 
 
-Building the QEMU/libvirt image
--------------------------------
-
-Build the image::
-
-  $BIN_PACKER build -only=qemu -var disk_size=4000 -var memory=1024 fedora-28-x86_64.json
-
-The output box is a gzip-compressed tarball.  Unfortunately, the VM
-image it contains is not sparse and will waste a lot of space (and
-time) when Vagrant unpacks and imports the image.  Therefore we
-unpack, sparsify and repack the box::
-
-  mkdir box && cd box && tar -xf ../fedora-28-x86_64-libvirt.box
-  virt-sparsify --in-place box.img
-  tar -czf ../fedora-28-x86_64-libvirt.box * && cd .. && rm -rf box
-
-
-Uploading boxes to HashiCorp Atlas
+Uploading boxes to Vagrant Cloud
 ----------------------------------
 
-Vagrant by default looks for boxes in a directory called *Atlas*.
+Vagrant by default looks for boxes in a directory called *Vagrant Cloud*.
 Therefore is is good to make images available there, so that people
 can easily download them as part of workshop preparation.
 

doc/workshop/facilitators.rst

@@ -31,5 +31,5 @@ Vagrant boxes
 -------------
 
 See ``building.rst`` for instructions on building Vagrant boxes.
-At time of writing, the ``netoarmando/freeipa-workshop`` box is
-FreeIPA 4.6.90 / Fedora 28, for the VirtualBox and libvirt providers.
+At time of writing, the ``freeipa/freeipa-workshop`` box is
+FreeIPA 4.9.3 / Fedora 34, for the VirtualBox and libvirt providers.

doc/workshop/packer-template-fedora.json

@@ -0,0 +1,77 @@
+{
+  "builders": [{
+    "type": "qemu",
+    "iso_url": "{{user `iso_url`}}",
+    "iso_checksum": "{{user `iso_checksum`}}",
+    "output_directory": "output-{{user `box_name`}}-x86_64-{{build_type}}",
+    "vm_name": "packer-{{user `box_name`}}-x86_64",
+    "disk_size": "{{user `disk_size`}}",
+    "headless": "{{user `headless`}}",
+    "http_directory": ".",
+    "boot_wait": "5s",
+    "boot_command": [
+      "<tab> ",
+      "inst.ks=http://{{.HTTPIP}}:{{.HTTPPort}}/anaconda-ks.cfg ",
+      "biosdevname=0 ",
+      "net.ifnames=0 ",
+      "<enter>"
+    ],
+    "ssh_timeout": "{{user `ssh_timeout`}}",
+    "ssh_username": "vagrant",
+    "ssh_password": "vagrant",
+    "shutdown_command": "sudo systemctl poweroff",
+    "qemuargs": [
+      ["-m", "{{user `memory`}}"],
+      ["-smp", "{{user `cpus`}}"]
+    ]
+  }, {
+    "type": "virtualbox-iso",
+    "guest_os_type": "Fedora_64",
+    "iso_url": "{{user `iso_url`}}",
+    "iso_checksum": "{{user `iso_checksum`}}",
+    "output_directory": "output-{{user `box_name`}}-x86_64-{{build_type}}",
+    "vm_name": "packer-{{user `box_name`}}-x86_64",
+    "disk_size": "{{user `disk_size`}}",
+    "headless": "{{user `headless`}}",
+    "http_directory": ".",
+    "boot_wait": "5s",
+    "boot_command": [
+      "<tab> ",
+      "inst.ks=http://{{.HTTPIP}}:{{.HTTPPort}}/anaconda-ks.cfg ",
+      "biosdevname=0 ",
+      "net.ifnames=0 ",
+      "<enter>"
+    ],
+    "ssh_timeout": "{{user `ssh_timeout`}}",
+    "ssh_username": "vagrant",
+    "ssh_password": "vagrant",
+    "shutdown_command": "sudo systemctl poweroff",
+    "vboxmanage": [
+      ["modifyvm", "{{.Name}}", "--memory", "{{user `memory`}}"],
+      ["modifyvm", "{{.Name}}", "--cpus", "{{user `cpus`}}"]
+    ]
+  }],
+  "provisioners": [{
+    "type": "shell",
+    "scripts": [
+      "workshop-install-packages.sh"
+    ]
+  }],
+  "post-processors": [{
+    "type": "vagrant",
+    "compression_level": "{{user `compression_level`}}",
+    "output": "{{user `box_name`}}-x86_64-{{.Provider}}.box"
+  }],
+  "variables": {
+    "box_name": "fedora-34",
+    "iso_url": "{{user `mirror`}}/releases/34/Server/x86_64/iso/Fedora-Server-netinst-x86_64-34-1.2.iso",
+    "iso_checksum": "file:{{user `mirror`}}/releases/34/Server/x86_64/iso/Fedora-Server-34-1.2-x86_64-CHECKSUM",
+    "compression_level": "9",
+    "cpus": "1",
+    "disk_size": "40000",
+    "headless": "false",
+    "memory": "1024",
+    "mirror": "http://download.fedoraproject.org/pub/fedora/linux",
+    "ssh_timeout": "60m"
+  }
+}

doc/workshop/troubleshooting.rst

@@ -1,16 +1,19 @@
-Local webserver
+Troubleshooting
 ===============
 
+Local webserver
+---------------
+
 Drop firewall::
 
   sudo firewall-cmd --add-service=http
 
 
 DNS / hosts file issues
-=======================
+-----------------------
 
 Flush cache
------------
+^^^^^^^^^^^
 
 Note: some resolvers cache NX.
 
@@ -24,7 +27,7 @@ Windows::
 
 
 Virtual network
-===============
+---------------
 
 If ``Vagrant::Errors::NetworkCollision`` occurs, try deleting host
 network device, e.g.::
@@ -39,7 +42,7 @@ up::
 
 
 Vagrant
-=======
+-------
 
 If ``vagrant up`` fails to SSH into VM, delete
 ``~/.vagrant.d/insecure_private_key``.  See
@@ -47,7 +50,7 @@ https://stackoverflow.com/questions/28284112/.
 
 
 mod_lookup_identity
-===================
+-------------------
 
 To flush cache::
 

doc/workshop/workshop-install-packages.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+sudo dnf install -y freeipa-server freeipa-server-dns sssd-dbus mod_lookup_identity mod_authnz_pam haveged nmap-ncat nano pamtester bash-completion
+sudo dnf clean all

doc/workshop/workshop-ipa-customizations.sh

@@ -1,5 +1,4 @@
 #!/bin/bash
-sudo dnf install -y freeipa-server freeipa-server-dns sssd-dbus mod_lookup_identity mod_authnz_pam haveged nmap-ncat nano pamtester bash-completion
 sudo systemctl enable haveged
 sudo sh -c "echo 'PS1=\"[\u@\h]\\\\$ \"' >> /etc/profile"
 sudo sh -c "echo 'PS1=\"[\h]\\\\$ \"' >> /etc/bashrc"
@@ -11,10 +10,10 @@ sudo rm -f /etc/httpd/conf.d/welcome.conf
 sudo sh -c "cat >/usr/share/httpd/app.py" <<EOF
 def application(environ, start_response):
     start_response('200 OK', [('Content-Type', 'text/plain')])
-    logged_in = 'REMOTE_USER' in environ
+    remote_user = environ.get('REMOTE_USER')
 
-    if logged_in:
-        yield "LOGGED IN AS: {}\n".format(environ['REMOTE_USER']).encode('utf8')
+    if remote_user is not None:
+        yield "LOGGED IN AS: {}\n".format(remote_user).encode('utf8')
     else:
         yield b"NOT LOGGED IN\n"
 
@@ -37,3 +36,12 @@ sudo sh -c "cat >/etc/httpd/conf.d/app.conf" <<EOF
     </Directory>
 </VirtualHost>
 EOF
+
+# Vagrant's "change host name" sets the short host name.  Before
+# we repair /etc/hosts (see below) let's reset /etc/hostname to
+# the *full* host name
+hostname --fqdn > /etc/hostname && hostname -F /etc/hostname
+
+# Vagrant's "change host name" capability for Fedora maps hostname
+# to loopback.  We must repair /etc/hosts
+sed -ri 's/127\.0\.0\.1\s.*/127.0.0.1 localhost localhost.localdomain/' /etc/hosts

doc/workshop/workshop.rst

@@ -119,14 +119,11 @@ password everytime::
   $ sudo gpasswd -a ${USER} libvirt
   $ newgrp libvirt
 
-On **Fedoda 28** you need to enable ``virtlogd``::
-
-  $ systemctl enable --now virtlogd.socket
-
 Finally restart the services::
 
   $ systemctl restart libvirtd
-  $ systemctl restart polkit
+
+More information: https://docs.fedoraproject.org/en-US/quick-docs/getting-started-with-virtualization/
 
 Otherwise, you will use VirtualBox and the ``virtualbox`` provider.
 VirtualBox needs to build kernel modules, and that means that you must
@@ -150,7 +147,7 @@ in the transcript below (to make sure it wasn't tampered with)::
   repo_gpgcheck=1
   gpgkey=https://www.virtualbox.org/download/oracle_vbox.asc
 
-  $ sudo dnf install -y VirtualBox-5.2
+  $ sudo dnf install -y VirtualBox-6.1
 
 Finally, load the kernel modules (you may need to restart your system for this to work)::
 
@@ -163,7 +160,7 @@ Mac OS X
 Install Vagrant for Mac OS X from
 https://www.vagrantup.com/downloads.html.
 
-Install VirtualBox 5.2 for **OS X hosts** from
+Install VirtualBox 6.1 for **OS X hosts** from
 https://www.virtualbox.org/wiki/Downloads.
 
 Install Git from https://git-scm.com/download/mac or via your
@@ -173,23 +170,12 @@ preferred package manager.
 Debian / Ubuntu
 ^^^^^^^^^^^^^^^
 
-Install Vagrant and Git::
+Install Vagrant, Git and VirtualBox::
 
   $ sudo apt-get install -y vagrant git
+  $ sudo apt-get install -y virtualbox-6.1
 
-**Virtualbox 5.2** may be available from the system package manager,
-depending your your release.  Find out which version of VirtualBox is
-available::
-
-  $ apt list virtualbox
-  Listing... done
-  virtualbox/bionic 5.2.10-dfsg-6 amd64
-
-If version 5.2 is available, install it via ``apt-get``::
-
-  $ sudo apt-get install -y virtualbox
-
-If VirtualBox 5.2 was not available in the official packages for
+If VirtualBox 6.1 was not available in the official packages for
 your release, follow the instructions at
 https://www.virtualbox.org/wiki/Linux_Downloads to install it.
 
@@ -200,7 +186,7 @@ Windows
 Install Vagrant via the ``.msi`` available from
 https://www.vagrantup.com/downloads.html.
 
-Install VirtualBox 5.2 for **Windows hosts** from
+Install VirtualBox for **Windows hosts** from
 https://www.virtualbox.org/wiki/Downloads.
 
 You will also need to install an SSH client, and Git.  Git for
@@ -216,18 +202,19 @@ workshop, which you will need locally.
 
 ::
 
-  $ git clone https://github.com/freeipa/freeipa-workshop.git
+  $ git clone https://github.com/freeipa/freeipa.git
+  $ cd freeipa/doc/workshop
 
 
 Fetch Vagrant box
 -----------------
 
-Please fetch the Vagrant box prior to the workshop.  It is > 600MB
+Please fetch the Vagrant box prior to the workshop.  It is > 700MB
 so it may not be feasible to download it during the workshop.
 
 ::
 
-  $ vagrant box add netoarmando/freeipa-workshop
+  $ vagrant box add freeipa/freeipa-workshop
 
 
 Add hosts file entries