Initial commit

README.md

@@ -0,0 +1,68 @@
+# TrueNAS 13 QEMU Guest Agent
+
+This is a guide for Installing and Configuring QEMU Guest Agent for TrueNAS 13. It is based on the **QEMU Guest Agent** and **VirtIO Console driver** from **FreeBSD 13**.
+
+## Requirements
+
+Due to the TrueNAS kernel lacking certain FreeBSD drivers, it's necessary to download the FreeBSD 13 kernel, extract the VirtIO Console driver and integrate it into the TrueNAS system. This ensures TrueNAS compatibility with virtualized environments.
+
+Required packages for this guide:
+- VirtIO Console driver: https://man.freebsd.org/cgi/man.cgi?query=virtio_console
+- QEMU Guest Agent: https://freebsd.pkgs.org/13/freebsd-amd64/qemu-guest-agent-8.1.3.pkg.html
+
+FreeBSD 13 Binary Packages:
+- FreeBSD 13.1 Kernel: http://ftp-archive.freebsd.org/pub/FreeBSD-Archive/old-releases/amd64/13.1-RELEASE/kernel.txz
+- QEMU Guest Agent 8.1.3: https://pkg.freebsd.org/FreeBSD:13:amd64/latest/All/qemu-guest-agent-8.1.3.pkg
+
+## Manual Installation
+
+1. Download FreeBSD 13.1 kernel.txz and extract `./boot/kernel/virtio_console.ko` driver to `/boot/modules/` directory.
+
+2. Load the VirtIO Console driver with
+    ```bash
+    kldload /boot/modules/virtio_console.ko
+    ```
+
+3. Download FreeBSD 13 QEMU Guest Agent package.
+
+4. Install downloaded `qemu-guest-agent` package using `pkg add`.
+
+5. Backup installed `/usr/local/etc/rc.d/qemu-guest-agent` to `/root/qga_backup/`. This will be a copy that is re-added to the rc.d directory each time TrueNAS boots.
+
+6. Create the following Tunables in the TrueNAS web UI under **System** -> **Tunables**:
+    1. Variable: `qemu_guest_agent_enable`, Value: `YES`, Type: `RC`, Enabled: `yes`
+    2. Variable: `qemu_guest_agent_flags`, Value: `-d -v -l /var/log/qemu-ga.log`, Type: `RC`, Enabled: `yes`
+    3. Variable: `virtio_console_load`, Value: `YES`, Type: `LOADER`, Enabled: `yes`
+
+7. Set up Init/Shutdown Scripts in **Tasks** -> **Init/Shutdown Scripts**:
+    1. Type: `Command`, Command: `service qemu-guest-agent start`, When: `POSTINIT`, Enabled: `yes`, Timeout: `10`
+    2. Type: `Command`, Command: `cp /root/qga_backup/qemu-guest-agent /usr/local/etc/rc.d`, When: `PREINIT`, Enabled: `yes`, Timeout: `10`
+
+8. Reboot TrueNAS to apply changes.
+
+## Automated Installation
+
+Via bash script:
+
+1. Execute the following commands on your TrueNAS system:
+    ```bash
+    curl -O https://raw.githubusercontent.com/gushmazuko/truenas-qemu-guest-agent/master/install.sh
+    chmod +x install.sh
+    ./install.sh
+    ```
+
+2. Reboot TrueNAS to apply changes.
+
+Or via ansible:
+
+1. Execute ansible-playbook on your TrueNAS system:
+    ```bash
+    ansible-playbook ./install_qemu_guest_agent_on_truenas.yml \
+    -e working_host=truenas.example.com \
+    -e ansible_ssh_port=22
+    ```
+
+2. Reboot TrueNAS to apply changes.
+
+## Conclusion
+Following these steps ensures the successful installation and configuration of the `QEMU Guest Agent` on TrueNAS 13, improving its functionality in virtualized environments.

install.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+
+# Exit script on error
+set -e
+
+# Error handler
+trap 'echo "An error occurred. Exiting..." >&2' ERR
+
+# Variables
+freebsd13_kernel="http://ftp-archive.freebsd.org/pub/FreeBSD-Archive/old-releases/amd64/13.1-RELEASE/kernel.txz"
+freebsd13_qga_pkg="https://pkg.freebsd.org/FreeBSD:13:amd64/latest/All/qemu-guest-agent-8.1.3.pkg"
+qga_backup_dir="/root/qga_backup"
+
+# Download FreeBSD 13.1 kernel.txz and extract virtio_console.ko driver to /boot/kernel
+echo -e "\nDownloading FreeBSD 13.1 kernel.txz and extracting virtio_console.ko driver to /boot/kernel..."
+curl -#O ${freebsd13_kernel} --output-dir /tmp/
+tar -xf /tmp/kernel.txz --strip-components=3 -C /boot/modules/ ./boot/kernel/virtio_console.ko 1> /dev/null
+
+# Load virtio_console.ko driver
+kldload /boot/modules/virtio_console.ko
+
+# Download and install FreeBSD 13 qemu-guest-agent package
+echo -e "\nDownloading and installing FreeBSD 13 qemu-guest-agent package..."
+IGNORE_OSVERSION=yes pkg add ${freebsd13_qga_pkg} 1> /dev/null
+
+# Create backup of qemu-guest-agent file
+mkdir ${qga_backup_dir}
+cp /usr/local/etc/rc.d/qemu-guest-agent ${qga_backup_dir}/
+
+export TERM=dumb
+
+# Create tunables for QEMU Guest Agent
+echo -e "\nCreating tunables for QEUM Guest Agent..."
+cli << EOF &> /dev/null
+    system tunable create type=RC var="qemu_guest_agent_enable" value="YES" enabled=true
+    system tunable create type=RC var="qemu_guest_agent_flags" value="-d -v -l /var/log/qemu-ga.log" enabled=true
+    system tunable create type=LOADER var="virtio_console_load" value="YES" enabled=true
+EOF
+
+# Set un init/shutdown scripts for QEUM Guest Agent
+echo -e "\nSetting init/shutdown scripts for QEUM Guest Agent..."
+cli << EOF &> /dev/null
+    system initshutdownscript create type=COMMAND command="service qemu-guest-agent start" when=POSTINIT enabled=true timeout=10 comment="start qemu-guest-agent on boot"
+    system initshutdownscript create type=COMMAND command="cp ${qga_backup_dir}/qemu-guest-agent /usr/local/etc/rc.d" when=PREINIT enabled=true timeout=10 comment="copy qemu-guest-agent on boot"
+EOF
+
+# Ask user to reboot TrueNAS
+echo -e "\nPlease reboot TrueNAS to apply changes."

install_qemu_guest_agent_on_truenas.yml

@@ -0,0 +1,104 @@
+- name: Change host variable
+  hosts: localhost
+  connection: local
+  tasks:
+    - name: Use hostname from env var working_host
+      ansible.builtin.add_host:
+        name: "{{ working_host }}"
+        groups: working_group
+  tags:
+    - always
+
+
+- name: TrueNAS QEMU Guest Agent Setup
+  hosts: working_group
+  gather_facts: true
+  remote_user: root
+  vars:
+    # ansible_python_interpreter: /usr/bin/python
+    ansible_ssh_port: 22
+    ansible_ssh_common_args: '-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null'
+    freebsd13_kernel: "http://ftp-archive.freebsd.org/pub/FreeBSD-Archive/old-releases/amd64/13.1-RELEASE/kernel.txz"
+    freebsd13_qga_pkg: "https://pkg.freebsd.org/FreeBSD:13:amd64/latest/All/qemu-guest-agent-8.1.3.pkg"
+    qga_backup_dir: "/root/qga_backup"
+
+  tasks:
+    - name: Download FreeBSD 13.1 kernel.txz to /tmp
+      ansible.builtin.get_url:
+        url: "{{ freebsd13_kernel }}"
+        dest: /tmp/kernel.txz
+        mode: '0644'
+      register: fetch_kernel
+      failed_when: fetch_kernel is failed
+      tags: 
+        - fetch_kernel
+
+    - name: Extract kernel.txz to /tmp
+      ansible.builtin.shell: |
+        tar -xf /tmp/kernel.txz --strip-components=3 -C /boot/modules/ ./boot/kernel/virtio_console.ko
+      register: extract_kernel
+      failed_when: extract_kernel is failed
+      tags: 
+        - extract_kernel
+
+    - name: Load VirtIO Console driver
+      ansible.builtin.shell: |
+        kldload /boot/modules/virtio_console.ko
+      register: load_kernel
+      failed_when: load_kernel is failed
+      tags: 
+        - load_kernel
+
+    - name: Download and Install downloaded FreeBSD 13 QEMU Guest Agent package
+      ansible.builtin.shell: |
+        IGNORE_OSVERSION=yes pkg add {{ freebsd13_qga_pkg }}
+      args:
+        executable: /bin/bash
+      register: install_qga
+      failed_when: install_qga is failed
+      tags: 
+        - install_qga
+
+    - name: Create backup of qemu-guest-agent file
+      ansible.builtin.shell: |
+        mkdir {{ qga_backup_dir }}
+        cp /usr/local/etc/rc.d/qemu-guest-agent {{ qga_backup_dir }}/qemu-guest-agent
+      args:
+        executable: /bin/bash
+      register: backup_qga
+      failed_when: backup_qga is failed
+      tags: 
+        - backup_qga
+
+    - name: Create Tunables for QEMU Guest Agent
+      ansible.builtin.shell: |
+        cli <<EOF
+          system tunable create type=RC var="qemu_guest_agent_enable" value="YES" enabled=true
+          system tunable create type=RC var="qemu_guest_agent_flags" value="-d -v -l /var/log/qemu-ga.log" enabled=true
+          system tunable create type=LOADER var="virtio_console_load" value="YES" enabled=true
+        EOF
+      args:
+        executable: /bin/bash
+      register: create_tunables
+      failed_when: create_tunables is failed
+      tags: 
+        - create_tunables
+
+    - name: Set un init/shutdown Scripts
+      ansible.builtin.shell: |
+        cli << EOF
+            system initshutdownscript create type=COMMAND command="service qemu-guest-agent start" when=POSTINIT enabled=true timeout=10 comment="start qemu-guest-agent on boot"
+            system initshutdownscript create type=COMMAND command="cp {{ qga_backup_dir }}/qemu-guest-agent /usr/local/etc/rc.d" when=PREINIT enabled=true timeout=10 comment="copy qemu-guest-agent on boot"
+        EOF
+      args:
+        executable: /bin/bash
+      register: create_scripts
+      failed_when: create_scripts is failed
+      tags: 
+        - create_scripts
+
+    - name: Print message
+      ansible.builtin.debug:
+        msg: "Please reboot TrueNAS to apply changes."
+      tags: 
+        - reboot_message