From 42afcc95be0292dd0dbdf955dbe0e8e3a683782e Mon Sep 17 00:00:00 2001 From: Armando Neto Date: Mon, 19 Apr 2021 19:40:40 -0300 Subject: [PATCH] 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 Reviewed-By: Florence Blanc-Renaud Reviewed-By: Rob Crittenden Reviewed-By: Francisco Trivino Reviewed-By: Sumit Bose --- .gitignore | 6 ++ doc/Makefile | 6 -- doc/workshop.rst | 7 +- doc/workshop/Vagrantfile | 49 ++++++++---- doc/workshop/app.py | 14 ---- doc/workshop/building.rst | 56 ++++++-------- .../{README.facilitators => facilitators.rst} | 4 +- doc/workshop/packer-template-fedora.json | 77 +++++++++++++++++++ doc/workshop/troubleshooting.rst | 15 ++-- doc/workshop/workshop-install-packages.sh | 3 + ...{ipa.sh => workshop-ipa-customizations.sh} | 16 +++- doc/workshop/workshop.rst | 37 +++------ 12 files changed, 184 insertions(+), 106 deletions(-) delete mode 100644 doc/workshop/app.py rename doc/workshop/{README.facilitators => facilitators.rst} (87%) create mode 100644 doc/workshop/packer-template-fedora.json create mode 100644 doc/workshop/workshop-install-packages.sh rename doc/workshop/{ipa.sh => workshop-ipa-customizations.sh} (66%) diff --git a/.gitignore b/.gitignore index 376de6926..bfc04c474 100644 --- a/.gitignore +++ b/.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/ diff --git a/doc/Makefile b/doc/Makefile index e34b94c7d..42f7b1a82 100644 --- a/doc/Makefile +++ b/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" diff --git a/doc/workshop.rst b/doc/workshop.rst index 3896f0195..c6f59d794 100644 --- a/doc/workshop.rst +++ b/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 diff --git a/doc/workshop/Vagrantfile b/doc/workshop/Vagrantfile index e3377259e..f059ae24e 100644 --- a/doc/workshop/Vagrantfile +++ b/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 diff --git a/doc/workshop/app.py b/doc/workshop/app.py deleted file mode 100644 index 4425daf47..000000000 --- a/doc/workshop/app.py +++ /dev/null @@ -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') diff --git a/doc/workshop/building.rst b/doc/workshop/building.rst index 747d99b7c..75ceca1a0 100644 --- a/doc/workshop/building.rst +++ b/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. diff --git a/doc/workshop/README.facilitators b/doc/workshop/facilitators.rst similarity index 87% rename from doc/workshop/README.facilitators rename to doc/workshop/facilitators.rst index 92c80767a..2bf5230e1 100644 --- a/doc/workshop/README.facilitators +++ b/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. diff --git a/doc/workshop/packer-template-fedora.json b/doc/workshop/packer-template-fedora.json new file mode 100644 index 000000000..db0fb3cff --- /dev/null +++ b/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": [ + " ", + "inst.ks=http://{{.HTTPIP}}:{{.HTTPPort}}/anaconda-ks.cfg ", + "biosdevname=0 ", + "net.ifnames=0 ", + "" + ], + "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": [ + " ", + "inst.ks=http://{{.HTTPIP}}:{{.HTTPPort}}/anaconda-ks.cfg ", + "biosdevname=0 ", + "net.ifnames=0 ", + "" + ], + "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" + } +} diff --git a/doc/workshop/troubleshooting.rst b/doc/workshop/troubleshooting.rst index 2009acfd9..74a9f3f13 100644 --- a/doc/workshop/troubleshooting.rst +++ b/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:: diff --git a/doc/workshop/workshop-install-packages.sh b/doc/workshop/workshop-install-packages.sh new file mode 100644 index 000000000..eb0b6ec71 --- /dev/null +++ b/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 diff --git a/doc/workshop/ipa.sh b/doc/workshop/workshop-ipa-customizations.sh similarity index 66% rename from doc/workshop/ipa.sh rename to doc/workshop/workshop-ipa-customizations.sh index 881b6cd60..a2d1c6b97 100755 --- a/doc/workshop/ipa.sh +++ b/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" </etc/httpd/conf.d/app.conf" < 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 diff --git a/doc/workshop/workshop.rst b/doc/workshop/workshop.rst index 37da2b4bf..c1fddcf70 100644 --- a/doc/workshop/workshop.rst +++ b/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