ODA #107: Create snippet files for single-sourcing repetitive instruc…

…tions (#505)

* add prereq snippet

* add disable netfilter snippet

* add check networking delete default snippet

* add create bridge network snippet

* add system prereq snippet

* doc: move reuse/*.txt to .md files

This is for improved Markdown code highlighting.
Also, update the conf.py to ignore/exclude reuse/*.md files.

doc/conf.py

@@ -305,6 +305,7 @@
     'Thumbs.db',
     '.DS_Store',
     '.sphinx',
+    'reuse',
 ]
 exclude_patterns.extend(custom_excludes)
 

doc/multi-nic-vm-host-with-bonds-and-vlans.md

@@ -3,9 +3,9 @@
 This guide shows how to configure a virtual machine (VM) host using Netplan and the `virsh` interface. The host in this scenario has four network interface (NICs). The host uses network bonding and three VLAN networks.
 
 
-## Prerequisites
+```{include} reuse/configure-vm-prerequisites.md
 
-Ensure the following prerequisites are satisfied.
+```
 
 
 ### System
@@ -35,23 +35,9 @@ Ensure the following prerequisites are satisfied.
 - Firewall configured; see [UFW](https://help.ubuntu.com/community/UFW).
 
 
-#### Disable netfilter for bridged interfaces
+```{include} reuse/configure-vm-disable-netfilter.md
 
-To allow communication between the host server, its virtual machines, and the devices in the local VLANs, disable netfilter for bridged interfaces:
-
-1. Add the following lines to the `/etc/systemctl.conf` configuration file:
-
-    ```
-    net.bridge.bridge-nf-call-iptables = 0
-    net.bridge.bridge-nf-call-ip6tables = 0
-    net.bridge.bridge-nf-call-arptables = 0
-    ```
-
-2. Apply the changes immediately, without rebooting the host.
-
-    ```none
-    sysctl -p /etc/sysctl.conf
-    ```
+```
 
 
 ## Netplan configuration
@@ -155,104 +141,16 @@ Configure Netplan:
     ```
 
 
-## Configure virtual networks using `virsh`
-
-The next step is to configure virtual networks defined for `virsh` domains. This is not necessary, but it makes VM deployment and management easier.
-
-
-### Check networking and delete the default network
-
-1. Check existing virtual networks:
-
-    ```none
-    virsh net-list --all
-    ```
-
-   There should be one default network as in this example:
-
-    ```
-    Name      State    Autostart   Persistent
-    --------------------------------------------
-    default   active   yes         yes
-    ```
-
-   If needed, use the `net-info` command to gather more details about the default network:
-
-    ```
-    virsh net-info default
-    ```
-
-2. Remove the default network:
-
-    ```
-    virsh net-destroy default
-    virsh net-undefine default
-    ```
-
-3. Check network list to confirm the changes have been applied. There should no networks defined now:
-
-    ```none
-    virsh net-list --all
-    ```
-
+```{include} reuse/configure-vm-using-virsh.md
 
-### Create bridged networks
+```
 
-1. Create a directory for VM data. For example:
 
-    ```none
-    mkdir /mnt/vmstore/
-    cd /mnt/vmstore/
-    ```
+```{include} reuse/configure-vm-check-networking-delete-default.md
 
-2. Define the bridge interface, `br0`, for VLAN1 by creating the `/mnt/vmstore/net-br0.xml` file with  the following contents:
+```
 
-    ```xml
-    <network>
-        <name>br0</name>
-        <forward mode="bridge" />
-        <bridge name="br0" />
-    </network>
-    ```
-
-3. Define the bridge interface, `br0-vlan40`, for VLAN40 by creating the `/mnt/vmstore/net-br0-vlan40.xml` file with  the following contents:
-
-    ```xml
-    <network>
-        <name>br0-vlan40</name>
-        <forward mode="bridge" />
-        <bridge name="br0-vlan40" />
-    </network>
-    ```
-
-4. Define the bridge interface, `br0-vlan41`, for VLAN41 by creating the `/mnt/vmstore/net-br0-vlan41.xml` file with  the following contents:
-
-    ```xml
-    <network>
-        <name>br0-vlan41</name>
-        <forward mode="bridge" />
-        <bridge name="br0-vlan41" />
-    </network>
-    ```
-
-5. Enable the virtual (bridged) networks. This consists of three steps (performed for each of the networks):
-
-   1. Define the network.
-   2. Start  the network.
-   3. Set the network to autostart.
-
-    ```
-    virsh net-define net-br0.xml
-    virsh net-define net-br0-vlan40.xml
-    virsh net-define net-br0-vlan41.xml
-    virsh net-start br0
-    virsh net-start br0-vlan40
-    virsh net-start br0-vlan41
-    virsh net-autostart br0
-    virsh net-autostart br0-vlan40
-    virsh net-autostart br0-vlan41
-    ```
 
-6. Test the bridged networks.
+```{include} reuse/configure-vm-create-bridged-networks.md
 
-Congratulations, the configuration is complete. You can now create a virtual machine, assign the desired network using your preferred VM configuration tool, and run some tests.
+```

doc/reuse/configure-vm-check-networking-delete-default.md

@@ -0,0 +1,34 @@
+### Check networking and delete the default network
+
+1. Check existing virtual networks:
+
+    ```none
+    virsh net-list --all
+    ```
+
+   There should be one default network as in this example:
+
+    ```
+    Name      State    Autostart   Persistent
+    --------------------------------------------
+    default   active   yes         yes
+    ```
+
+   If needed, use the `net-info` command to gather more details about the default network:
+
+    ```
+    virsh net-info default
+    ```
+
+2. Remove the default network:
+
+    ```
+    virsh net-destroy default
+    virsh net-undefine default
+    ```
+
+3. Check network list to confirm the changes have been applied. There should no networks defined now:
+
+    ```none
+    virsh net-list --all
+    ```

doc/reuse/configure-vm-create-bridged-networks.md

@@ -0,0 +1,60 @@
+### Create bridged networks
+
+1. Create a directory for VM data. For example:
+
+    ```none
+    mkdir /mnt/vmstore/
+    cd /mnt/vmstore/
+    ```
+
+2. Define the bridge interface, `br0`, for VLAN1 by creating the `/mnt/vmstore/net-br0.xml` file with  the following contents:
+
+    ```xml
+    <network>
+        <name>br0</name>
+        <forward mode="bridge" />
+        <bridge name="br0" />
+    </network>
+    ```
+
+3. Define the bridge interface, `br0-vlan40`, for VLAN40 by creating the `/mnt/vmstore/net-br0-vlan40.xml` file with  the following contents:
+
+    ```xml
+    <network>
+        <name>br0-vlan40</name>
+        <forward mode="bridge" />
+        <bridge name="br0-vlan40" />
+    </network>
+    ```
+
+4. Define the bridge interface, `br0-vlan41`, for VLAN41 by creating the `/mnt/vmstore/net-br0-vlan41.xml` file with  the following contents:
+
+    ```xml
+    <network>
+        <name>br0-vlan41</name>
+        <forward mode="bridge" />
+        <bridge name="br0-vlan41" />
+    </network>
+    ```
+
+5. Enable the virtual (bridged) networks. This consists of three steps (performed for each of the networks):
+
+   1. Define the network.
+   2. Start  the network.
+   3. Set the network to autostart.
+
+    ```
+    virsh net-define net-br0.xml
+    virsh net-define net-br0-vlan40.xml
+    virsh net-define net-br0-vlan41.xml
+    virsh net-start br0
+    virsh net-start br0-vlan40
+    virsh net-start br0-vlan41
+    virsh net-autostart br0
+    virsh net-autostart br0-vlan40
+    virsh net-autostart br0-vlan41
+    ```
+
+6. Test the bridged networks.
+
+Congratulations, the configuration is complete. You can now create a virtual machine, assign the desired network using your preferred VM configuration tool, and run some tests.

doc/reuse/configure-vm-disable-netfilter.md

@@ -0,0 +1,17 @@
+#### Disable netfilter for bridged interfaces
+
+To allow communication between the host server, its virtual machines, and the devices in the local VLANs, disable netfilter for bridged interfaces:
+
+1. Add the following lines to the `/etc/systemctl.conf` configuration file:
+
+    ```
+    net.bridge.bridge-nf-call-iptables = 0
+    net.bridge.bridge-nf-call-ip6tables = 0
+    net.bridge.bridge-nf-call-arptables = 0
+    ```
+
+2. Apply the changes immediately, without rebooting the host.
+
+    ```none
+    sysctl -p /etc/sysctl.conf
+    ```

doc/reuse/configure-vm-prerequisites-system.md

@@ -0,0 +1,6 @@
+### System
+
+- Computer with a single network interface card (NIC).
+- Ubuntu Server installed.
+- KVM and QEMU installed; see [KVM installation](https://help.ubuntu.com/community/KVM/Installation).
+- Administrator privileges.

doc/reuse/configure-vm-prerequisites.md

@@ -0,0 +1,3 @@
+## Prerequisites
+
+Ensure the following prerequisites are satisfied.

doc/reuse/configure-vm-using-virsh.md

@@ -0,0 +1,3 @@
+## Configure virtual networks using `virsh`
+
+The next step is to configure virtual networks defined for `virsh` domains. This is not necessary, but it makes VM deployment and management easier.