From 4b550c1417287c01496021ec56a79af232abfda7 Mon Sep 17 00:00:00 2001 From: Francisco Trivino Date: Sep 27 2023 07:55:00 +0000 Subject: Workshop: fix broken Sphinx cross-references. Many of the workshop pages links are directing to URLs that end with ".rst" instead of ".html", as a result, these links are broken. This commit introduces explicit targets and references to ensure that the pages are correctly linked. Signed-off-by: Francisco Trivino Reviewed-By: Alexander Bokovoy Reviewed-By: Florence Blanc-Renaud --- diff --git a/doc/workshop/1-server-install.rst b/doc/workshop/1-server-install.rst index 838d502..0e58d16 100644 --- a/doc/workshop/1-server-install.rst +++ b/doc/workshop/1-server-install.rst @@ -1,4 +1,5 @@ -.. +.. _1-server-install: + Copyright 2015-2018 Red Hat, Inc. This work is licensed under the Creative Commons Attribution 4.0 @@ -157,8 +158,8 @@ more! To prepare for the next unit, exit the ``server`` SSH session (but do not shut the VM down). The next essential unit is -`Unit 2: Enrolling client machines <2-client-install.rst>`_. +:ref:`Unit 2: Enrolling client machines <2-client-install>`. Alternatively, if you would like to immediately install a replica server (essential for production deployments), you can take a detour -to `Unit 7: Replica installation <7-replica-install.rst>`_. +to :ref:`Unit 7: Replica installation <7-replica-install>`. diff --git a/doc/workshop/10-ssh-key-management.rst b/doc/workshop/10-ssh-key-management.rst index 18d8ad9..a20de77 100644 --- a/doc/workshop/10-ssh-key-management.rst +++ b/doc/workshop/10-ssh-key-management.rst @@ -1,9 +1,11 @@ +.. _10-ssh-key-management: + Unit 10: SSH user and host key management ========================================= **Prerequisites:** -- `Unit 3: User management and Kerberos authentication <3-user-management.rst>`_ +- :ref:`Unit 3: User management and Kerberos authentication <3-user-management>` In this module you will explore how to use FreeIPA as a backend provider for SSH keys. Instead of distributing ``authorized_keys`` diff --git a/doc/workshop/11-kerberos-ticket-policy.rst b/doc/workshop/11-kerberos-ticket-policy.rst index a2fbb6e..580a12d 100644 --- a/doc/workshop/11-kerberos-ticket-policy.rst +++ b/doc/workshop/11-kerberos-ticket-policy.rst @@ -1,9 +1,11 @@ +.. _11-kerberos-ticket-policy: + Unit 11: Kerberos ticket policy ========================================= **Prerequisites:** -- `Unit 3: User management and Kerberos authentication <3-user-management.rst>`_ +- :ref:`Unit 3: User management and Kerberos authentication <3-user-management>` In this module you will explore how to manage properties of Kerberos authentication and authorization in FreeIPA. diff --git a/doc/workshop/12-external-idp-support.rst b/doc/workshop/12-external-idp-support.rst index 1451703..a21e6b7 100644 --- a/doc/workshop/12-external-idp-support.rst +++ b/doc/workshop/12-external-idp-support.rst @@ -1,9 +1,11 @@ +.. _12-external-idp-support: + Unit 12: Authentication against external Identity Providers =========================================================== **Prerequisites:** -- `Unit 11: Kerberos ticket policy <11-kerberos-ticket-policy.rst>`_ +- :ref:`Unit 11: Kerberos ticket policy <11-kerberos-ticket-policy>` In this module you will explore how to manage use external OAuth 2.0 servers to authorize issuance of Kerberos tickets in FreeIPA. diff --git a/doc/workshop/2-client-install.rst b/doc/workshop/2-client-install.rst index 795da36..fadc5e0 100644 --- a/doc/workshop/2-client-install.rst +++ b/doc/workshop/2-client-install.rst @@ -1,9 +1,11 @@ +.. _2-client-install: + Unit 2: Enrolling client machines =================================== **Prerequisites**: -- `Unit 1: Installing the FreeIPA server <1-server-install.rst>`_ +- :ref:`Unit 1: Installing the FreeIPA server <1-server-install>` In this unit, you will enrol a *host* as a client of your FreeIPA domain. This means that *users* in your FreeIPA realm (or Active @@ -57,4 +59,4 @@ logged onto the host can also acquire Kerberos tickets for accessing *services* in your domain. You can now move on to -`Unit 3: User management and Kerberos authentication <3-user-management.rst>`_. +:ref:`Unit 3: User management and Kerberos authentication <3-user-management>`. diff --git a/doc/workshop/3-user-management.rst b/doc/workshop/3-user-management.rst index a36c702..406b54b 100644 --- a/doc/workshop/3-user-management.rst +++ b/doc/workshop/3-user-management.rst @@ -1,3 +1,5 @@ +.. _3-user-management: + Unit 3: User management and Kerberos authentication ===================================================== @@ -124,8 +126,8 @@ is a true *single sign-on* protocol! Now that you have created some users, it's time to define some access policies. Proceed to -`Unit 4: Host-based access control (HBAC) <4-hbac.rst>`_. +:ref:`Unit 4: Host-based access control (HBAC) <4-hbac>`. Alternatively, if you are interested in SSH public key management for users and hosts, jump ahead to -`Unit 10: SSH user and host key management <10-ssh-key-management.rst>`_. +:ref:`Unit 10: SSH user and host key management <10-ssh-key-management>`. diff --git a/doc/workshop/4-hbac.rst b/doc/workshop/4-hbac.rst index 65f91ed..13cff73 100644 --- a/doc/workshop/4-hbac.rst +++ b/doc/workshop/4-hbac.rst @@ -1,9 +1,11 @@ +.. _4-hbac: + Unit 4: Host-based access control (HBAC) ========================================== **Prerequisites:** -- `Unit 3: User management and Kerberos authentication <3-user-management.rst>`_ +- :ref:`Unit 3: User management and Kerberos authentication <3-user-management>` FreeIPA's *host-based access control* (HBAC) feature allows you to define policies that restrict access to hosts or services based on @@ -142,7 +144,7 @@ Now try ``alice``:: This was the final mandatory unit in the workshop. From here, there are several optional units you can choose from. You can proceed directly to -`Unit 5: Web application authentication and authorisation <5-web-app-authnz.rst>`_. +:ref:`Unit 5: Web application authentication and authorisation <5-web-app-authnz>`. Otherwise, -`return to the curriculum overview `_ +:ref:`return to the curriculum overview ` to see all the options. diff --git a/doc/workshop/5-web-app-authnz.rst b/doc/workshop/5-web-app-authnz.rst index 39d053f..f8a8275 100644 --- a/doc/workshop/5-web-app-authnz.rst +++ b/doc/workshop/5-web-app-authnz.rst @@ -1,10 +1,12 @@ +.. _5-web-app-authnz: + Unit 5: Web application authentication and authorisation ========================================================== **Prerequisites**: -- `Unit 3: User management and Kerberos authentication <3-user-management.rst>`_ -- `Unit 4: Host-based access control (HBAC) <4-hbac.rst>`_ +- :ref:`Unit 3: User management and Kerberos authentication <3-user-management>` +- :ref:`Unit 4: Host-based access control (HBAC) <4-hbac>` You can configure many kinds of applications to rely on FreeIPA's centralised authentication, including web applications. In this @@ -309,4 +311,4 @@ authenticated as ``bob`` instead? This unit is now concluded. Now that you have mastered web app authentication, you'll want to configure TLS for your site. Proceed to -`Unit 6: Service certificates <6-cert-management.rst>`_. +:ref:`Unit 6: Service certificates <6-cert-management>`. diff --git a/doc/workshop/6-cert-management.rst b/doc/workshop/6-cert-management.rst index 0b9b5dc..f57998a 100644 --- a/doc/workshop/6-cert-management.rst +++ b/doc/workshop/6-cert-management.rst @@ -1,3 +1,5 @@ +.. _6-cert-management: + Unit 6: Service certificates ================================ @@ -126,9 +128,9 @@ Restart Apache and make a request to the app over HTTPS:: You can now proceed to -`Unit 7: Replica installation <7-replica-install.rst>`_ +:ref:`Unit 7: Replica installation <7-replica-install>` or -`Unit 8: Sudo rule management <8-sudorule.rst>`_. +:ref:`Unit 8: Sudo rule management <8-sudorule>`. Otherwise, -`return to the curriculum overview `_ +:ref:`return to the curriculum overview ` to see all the options. diff --git a/doc/workshop/7-replica-install.rst b/doc/workshop/7-replica-install.rst index 6df1812..ebd5e36 100644 --- a/doc/workshop/7-replica-install.rst +++ b/doc/workshop/7-replica-install.rst @@ -1,9 +1,11 @@ +.. _7-replica-install: + Unit 7: Replica installation ============================== **Prerequisites**: -- `Unit 1: Installing the FreeIPA server <1-server-install.rst>`_ +- :ref:`Unit 1: Installing the FreeIPA server <1-server-install>` FreeIPA is designed to be run in a replicated multi-master environment. In this unit, we will install a replica of the @@ -19,7 +21,7 @@ Client installation The first step of replica creation is to enrol the machine that will become the replica. SSH to the ``replica`` VM and enrol it per -`Unit 2: Enrolling client machines <2-client-install.rst>`_ +:ref:`Unit 2: Enrolling client machines <2-client-install>` Replica promotion ----------------- @@ -56,7 +58,7 @@ After ``ipa-replica-install`` finishes, the replica is operational. LDAP changes on any server will be replicated to all other servers. You can proceed to -`Unit 8: Sudo rule management <8-sudorule.rst>`_ +:ref:`Unit 8: Sudo rule management <8-sudorule>` or -`return to the curriculum overview `_ +:ref:`return to the curriculum overview ` to see all the available topics. diff --git a/doc/workshop/8-sudorule.rst b/doc/workshop/8-sudorule.rst index 7e16c4e..32e234d 100644 --- a/doc/workshop/8-sudorule.rst +++ b/doc/workshop/8-sudorule.rst @@ -1,10 +1,12 @@ +.. _8-sudorule: + Unit 8: Sudo rule management ============================ **Prerequisites**: -- `Unit 3: User management and Kerberos authentication <3-user-management.rst>`_ -- `Unit 4: Host-based access control (HBAC) <4-hbac.rst>`_ +- :ref:`Unit 3: User management and Kerberos authentication <3-user-management>` +- :ref:`Unit 4: Host-based access control (HBAC) <4-hbac>` Sudo is a program that allows users to run programs as another user with different privileges (possibly ``root``). Sudo rules provide @@ -241,4 +243,4 @@ restart (or start) Apache, but not run other commands via ``sudo``:: This concludes the unit. Now that you have Sudo rules working, -proceed to `Unit 9: SELinux User Maps <9-selinux-user-map.rst>`_. +proceed to :ref:`Unit 9: SELinux User Maps <9-selinux-user-map>`. diff --git a/doc/workshop/9-selinux-user-map.rst b/doc/workshop/9-selinux-user-map.rst index d744ac8..be3a24d 100644 --- a/doc/workshop/9-selinux-user-map.rst +++ b/doc/workshop/9-selinux-user-map.rst @@ -1,11 +1,13 @@ +.. _9-selinux-user-map: + Unit 9: SELinux User Maps ========================= **Prerequisites**: -- `Unit 3: User management and Kerberos authentication <3-user-management.rst>`_ -- `Unit 4: Host-based access control (HBAC) <4-hbac.rst>`_ -- `Unit 8: Sudo rule management <8-sudorule.rst>`_ +- :ref:`Unit 3: User management and Kerberos authentication <3-user-management>` +- :ref:`Unit 4: Host-based access control (HBAC) <4-hbac>` +- :ref:`Unit 8: Sudo rule management <8-sudorule>` SELinux is a *mandatory access controls* mechanism for Linux, providing more powerful and flexible access control than traditional @@ -43,7 +45,7 @@ will automatically be used. Recall that members of the ``sysadmin`` User Group already have access to ``webservers`` via the ``sysadmin_webservers`` rule that -was created in `Unit 4: Host-based access control (HBAC)`_. Create +was created in :ref:`Unit 4: Host-based access control (HBAC)<4-hbac>`. Create the SELinux User Map:: [client]$ ipa selinuxusermap-add sysadmin_staff_t \ @@ -135,7 +137,7 @@ the program being run:: Hello, world! This concludes the unit. You can now proceed to -`Unit 10: SSH user and host key management <10-ssh-key-management.rst>`_ +:ref:`Unit 10: SSH user and host key management <10-ssh-key-management>` or -`return to the curriculum overview `_ +:ref:`return to the curriculum overview ` to see all the available topics. diff --git a/doc/workshop/building.rst b/doc/workshop/building.rst index 75ceca1..8a9cbba 100644 --- a/doc/workshop/building.rst +++ b/doc/workshop/building.rst @@ -1,3 +1,5 @@ +.. _building: + Building Vagrant box images =========================== diff --git a/doc/workshop/facilitators.rst b/doc/workshop/facilitators.rst index 2bf5230..122d42a 100644 --- a/doc/workshop/facilitators.rst +++ b/doc/workshop/facilitators.rst @@ -30,6 +30,6 @@ Example: https://goo.gl/forms/UOkcsVROqV Vagrant boxes ------------- -See ``building.rst`` for instructions on building Vagrant boxes. +See :ref:`building` for instructions on building Vagrant boxes. 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/workshop.rst b/doc/workshop/workshop.rst index f4f87bf..04da720 100644 --- a/doc/workshop/workshop.rst +++ b/doc/workshop/workshop.rst @@ -1,4 +1,5 @@ -.. +.. _workshop: + Copyright 2015, 2016 Red Hat, Inc. This work is licensed under the Creative Commons Attribution 4.0 @@ -18,27 +19,28 @@ X.509 certificates for services. .. _FreeIPA: http://www.freeipa.org/page/Main_Page +.. _curriculum-overview: Curriculum overview ------------------- Mandatory: -- `Unit 1: Installing the FreeIPA server <1-server-install.rst>`_ -- `Unit 2: Enrolling client machines <2-client-install.rst>`_ -- `Unit 3: User management and Kerberos authentication <3-user-management.rst>`_ -- `Unit 4: Host-based access control (HBAC) <4-hbac.rst>`_ +- :ref:`Unit 1: Installing the FreeIPA server <1-server-install>` +- :ref:`Unit 2: Enrolling client machines <2-client-install>` +- :ref:`Unit 3: User management and Kerberos authentication <3-user-management>` +- :ref:`Unit 4: Host-based access control (HBAC) <4-hbac>` Optional units—choose the topics that are relevant to you: -- `Unit 5: Web application authentication and authorisation <5-web-app-authnz.rst>`_ -- `Unit 6: Service certificates <6-cert-management.rst>`_ -- `Unit 7: Replica installation <7-replica-install.rst>`_ -- `Unit 8: Sudo rule management <8-sudorule.rst>`_ -- `Unit 9: SELinux User Maps <9-selinux-user-map.rst>`_ -- `Unit 10: SSH user and host key management <10-ssh-key-management.rst>`_ -- `Unit 11: Kerberos ticket policy <11-kerberos-ticket-policy.rst>`_ -- `Unit 12: External IdP support <12-external-idp-support.rst>`_ +- :ref:`Unit 5: Web application authentication and authorisation <5-web-app-authnz>` +- :ref:`Unit 6: Service certificates <6-cert-management>` +- :ref:`Unit 7: Replica installation <7-replica-install>` +- :ref:`Unit 8: Sudo rule management <8-sudorule>` +- :ref:`Unit 9: SELinux User Maps <9-selinux-user-map>` +- :ref:`Unit 10: SSH user and host key management <10-ssh-key-management>` +- :ref:`Unit 11: Kerberos ticket policy <11-kerberos-ticket-policy>` +- :ref:`Unit 12: External IdP support <12-external-idp-support>` Editing files on VMs -------------------- @@ -241,7 +243,7 @@ Next step --------- You are ready to begin the workshop. Continue to -`Unit 1: Installing the FreeIPA server <1-server-install.rst>`_. +:ref:`Unit 1: Installing the FreeIPA server <1-server-install>`. After the workshop