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