lxd/instance/drivers: Add comments for lxd-agent udev rules, systemd …

…unit, and serial devices

Signed-off-by: Din Music <din.music@canonical.com>

lxd/instance/drivers/driver_qemu.go

@@ -2484,6 +2484,9 @@ func (d *qemu) generateConfigShare() error {
 		return err
 	}
 
+	// Systemd unit for lxd-agent. It ensures the lxd-agent is copied from the shared filesystem before it is
+	// started. The service is triggered dynamically via udev rules when certain virtio-ports are detected,
+	// rather than being enabled at boot.
 	lxdAgentServiceUnit := `[Unit]
 Description=LXD - agent
 Documentation=https://documentation.ubuntu.com/lxd/en/latest/
@@ -2506,6 +2509,9 @@ StartLimitBurst=10
 		return err
 	}
 
+	// Setup script for lxd-agent that is executed by the lxd-agent systemd unit before lxd-agent is started.
+	// The script sets up a temporary mount point, copies data from the mount (including lxd-agent binary),
+	// and then unmounts it. It also ensures appropriate permissions for the LXD agent's runtime directory.
 	lxdAgentSetupScript := `#!/bin/sh
 set -eu
 PREFIX="/run/lxd_agent"
@@ -2552,12 +2558,12 @@ chown -R root:root "${PREFIX}"
 		return err
 	}
 
-	// Udev rules
 	err = os.MkdirAll(filepath.Join(configDrivePath, "udev"), 0500)
 	if err != nil {
 		return err
 	}
 
+	// Udev rules to start the lxd-agent.service when QEMU serial devices (symlinks in virtio-ports) appear.
 	lxdAgentRules := `SYMLINK=="virtio-ports/com.canonical.lxd", TAG+="systemd", ENV{SYSTEMD_WANTS}+="lxd-agent.service"
 
 # Legacy.

lxd/instance/drivers/driver_qemu_templates.go

@@ -177,12 +177,15 @@ func qemuSerial(opts *qemuSerialOpts) []cfgSection {
 		comment: "Virtual serial bus",
 		entries: qemuDeviceEntries(&entriesOpts),
 	}, {
+		// Ring buffer used by the lxd agent to report (write) its status to. LXD server will read
+		// its content via QMP using "ringbuf-read" command.
 		name:    fmt.Sprintf(`chardev "%s"`, opts.charDevName),
 		comment: "LXD serial identifier",
 		entries: []cfgEntry{
 			{key: "backend", value: "ringbuf"},
 			{key: "size", value: fmt.Sprintf("%dB", opts.ringbufSizeBytes)}},
 	}, {
+		// QEMU serial device connected to the above ring buffer.
 		name: `device "qemu_serial"`,
 		entries: []cfgEntry{
 			{key: "driver", value: "virtserialport"},
@@ -191,6 +194,10 @@ func qemuSerial(opts *qemuSerialOpts) []cfgSection {
 			{key: "bus", value: "dev-qemu_serial.0"},
 		},
 	}, {
+		// Legacy QEMU serial device, not connected to any ring buffer. Its purpose is to
+		// create a symlink in /dev/virtio-ports/, triggering a udev rule to start the lxd-agent.
+		// This is necessary for backward compatibility with virtual machines lacking the
+		// updated lxd-agent-loader package, which includes updated udev rules and a systemd unit.
 		name: `device "qemu_serial_legacy"`,
 		entries: []cfgEntry{
 			{key: "driver", value: "virtserialport"},