docs: enhance LXD documentation with proper group setup and security best practices

- Add comprehensive LXD group setup guide based on official documentation
- Document the permission denied socket issue and proper solutions
- Add reboot as most reliable method for group membership activation
- Distinguish between CI workarounds (sudo chmod 666) and local best practices
- Update GitHub workflow with security warnings about CI-specific approaches
- Add troubleshooting section with diagnostic commands (id -nG, getent group)
- Include example of successful provisioning output
- Clarify difference between being in lxd group vs having active group membership
- Add proper sg lxd -c alternative for temporary group access
- Based on real-world testing and official LXD security documentation

Author: josecelano

.github/workflows/test-lxd-provision.yml

@@ -1,5 +1,9 @@
 name: Test LXD Container Provisioning
 
+# NOTE: This workflow uses CI-specific approaches like 'sudo chmod 666' on the LXD socket
+# and 'sudo' with LXD commands. These approaches are NOT recommended for local development.
+# For local use, follow the proper group membership approach documented in config/lxd/README.md
+
 on:
   push:
     branches: [main, develop]
@@ -29,7 +33,9 @@ jobs:
           # Add runner to lxd group
           sudo usermod -a -G lxd runner
 
-          # Fix socket permissions for CI environment
+          # IMPORTANT: This approach is ONLY for CI environments
+          # For local development, use proper group membership instead
+          # Fix socket permissions for CI environment (NOT recommended for local use)
           sudo chmod 666 /var/snap/lxd/common/lxd/unix.socket
 
           # Test basic LXD functionality
@@ -61,7 +67,8 @@ jobs:
       - name: Apply configuration
         working-directory: config/lxd
         run: |
-          # Run with sudo to ensure LXD access
+          # Run with sudo to ensure LXD access in CI environment
+          # NOTE: For local development, use "sg lxd -c 'tofu apply'" instead
           sudo -E tofu apply -auto-approve
 
       - name: Wait for container to be ready
@@ -130,6 +137,8 @@ jobs:
         working-directory: config/lxd
         run: |
           echo "Cleaning up container..."
+          # Use sudo for CI environment cleanup
+          # NOTE: For local development, use "sg lxd -c 'tofu destroy'" instead
           sudo -E tofu destroy -auto-approve || true
           sudo lxc delete torrust-vm --force || true
 

config/lxd/README.md

@@ -41,7 +41,17 @@ If both commands return version information, you can skip the installation steps
    # Add your user to the lxd group
    sudo usermod -a -G lxd $USER
 
-   # You may need to log out and back in for group changes to take effect
+   # IMPORTANT: For group membership to take effect, you MUST do ONE of:
+   # Option 1 (Temporary): Use 'newgrp lxd' to start a new shell with the group active
+   # Option 2: Log out and log back in completely
+   # Option 3: Close terminal and open a new one
+   # Option 4 (Most Reliable): Reboot your system if other methods don't work
+
+   # Verify you're in the lxd group (should show your username)
+   getent group lxd | grep "$USER"
+
+   # Verify the group is active in your session (lxd should be in the list)
+   id -nG
    ```
 
 2. **OpenTofu**: Install from [https://opentofu.org/](https://opentofu.org/)
@@ -55,6 +65,62 @@ If both commands return version information, you can skip the installation steps
 
 ## Configuration
 
+### Proper LXD Group Setup (Required for Direct LXD Access)
+
+**The Problem**: LXD's client (`lxc`) connects to the daemon via a Unix socket that only members of the `lxd` group can access. Even if your user is in the `lxd` group, your current shell session might not have picked up that membership yet, resulting in "permission denied" errors.
+
+**The Solution**: Based on the [official LXD documentation](https://documentation.ubuntu.com/lxd/en/latest/tutorial/first_steps/#add-the-current-user-to-the-lxd-group), follow these steps:
+
+1. **Check if you're already in the lxd group**:
+
+   ```bash
+   getent group lxd | grep "$USER"
+   ```
+
+   If this returns your username, you're already in the group.
+
+2. **Verify your current session has the group active**:
+
+   ```bash
+   id -nG
+   ```
+
+   If `lxd` is not in the list, your session hasn't picked up the group membership.
+
+3. **If not in the group, add yourself**:
+
+   ```bash
+   sudo usermod -aG lxd "$USER"
+   ```
+
+4. **Activate the group membership** (choose ONE method):
+
+   **Method 1 (Temporary)**: Start a subshell with the group active:
+
+   ```bash
+   newgrp lxd
+   ```
+
+   **Method 2 (Permanent)**: Log out and log back in completely
+
+   **Method 3 (Permanent)**: Close your terminal and open a new one
+
+   **Method 4 (Most Reliable)**: Reboot your system - this ensures all processes pick up the new group membership
+
+   **Note**: In some cases, logging out/in or closing the terminal may not be sufficient, and a full system reboot may be required to properly activate the group membership.
+
+5. **Verify the setup works**:
+
+   ```bash
+   lxc version
+   ```
+
+   If this works without `sudo` or permission errors, you're all set!
+
+**Important**: The official LXD documentation states that if `lxd init --minimal` results in an error, "your group membership might not have taken effect. In this case, close and re-open your terminal, then try again."
+
+### Container Configuration Files
+
 The LXD configuration consists of:
 
 - **`main.tf`** - OpenTofu configuration defining the LXD container and profile
@@ -107,6 +173,26 @@ To provision the container:
 
    Type `yes` when prompted to confirm the creation.
 
+   **Note**: If you encounter LXD socket permission issues, use:
+
+   ```bash
+   sg lxd -c "tofu apply"
+   ```
+
+   Example successful output:
+
+   ```text
+   Apply complete! Resources: 2 added, 0 changed, 0 destroyed.
+
+   Outputs:
+   container_info = {
+     "image" = "ubuntu:22.04"
+     "ip_address" = "10.140.190.155"
+     "name" = "torrust-vm"
+     "status" = "Running"
+   }
+   ```
+
 5. **Get container information**:
 
    ```bash
@@ -119,6 +205,9 @@ To provision the container:
    # Direct shell access
    lxc exec torrust-vm -- /bin/bash
 
+   # If you have LXD permission issues, use:
+   sg lxd -c "lxc exec torrust-vm -- /bin/bash"
+
    # SSH access (if you configured your SSH key and networking)
    ssh torrust@<container-ip-address>
    ```
@@ -131,14 +220,21 @@ To provision the container:
 # Using lxc directly
 lxc exec torrust-vm -- /bin/bash
 
+# If you have permission issues, use sg to switch to lxd group
+sg lxd -c "lxc exec torrust-vm -- /bin/bash"
+
 # Or via SSH (if you configured your SSH key)
 ssh torrust@<container-ip-address>
 ```
 
 ### Check Container Status
 
 ```bash
+# Preferred (if group membership is active)
 lxc list
+
+# If you get permission denied, use:
+sg lxd -c "lxc list"
 ```
 
 ### Stop the Container
@@ -197,13 +293,26 @@ To destroy the container and clean up resources:
 
    Type `yes` when prompted to confirm the destruction.
 
+   **Note**: If you encounter LXD permission issues, use:
+
+   ```bash
+   sg lxd -c "tofu destroy"
+   ```
+
 ## Troubleshooting
 
 ### Common Issues
 
 1. **LXD not found**: Ensure LXD is installed via snap
 2. **Permission errors**: Make sure your user is in the `lxd` group
 3. **Socket permissions**: In CI environments, you may need to adjust socket permissions
+4. **LXD unix socket not accessible**: If you get `Error: LXD unix socket "/var/snap/lxd/common/lxd/unix.socket" not accessible: permission denied`, follow the [Proper LXD Group Setup](#proper-lxd-group-setup-required-for-direct-lxd-access) section above. Quick fixes:
+   - **Most Reliable**: Reboot your system after adding yourself to the `lxd` group
+   - **Alternative**: Log out and log back in after adding yourself to the `lxd` group
+   - **Temporary**: Use `sg lxd -c "lxc command"` to run LXD commands with proper group access
+   - **Alternative**: Use `newgrp lxd` to activate the group in your current session
+   - **CI environments only**: As a temporary workaround (not recommended for regular use), you can use `sudo chmod 666 /var/snap/lxd/common/lxd/unix.socket` but this creates security risks
+   - **Last resort**: Use `sudo` with LXD commands, though this is not recommended for regular use
 
 ### Useful Commands
 
@@ -219,6 +328,29 @@ lxc info torrust-vm
 
 # View container logs
 lxc info torrust-vm --show-log
+
+# Troubleshoot LXD permissions
+# Check if you're in the lxd group
+groups $USER
+
+# Check current active groups (lxd should be in this list)
+id -nG
+
+# If lxd is missing from id -nG, your session hasn't picked up group membership
+# Fix with: newgrp lxd (temporary), log out/in, or reboot (most reliable)
+
+# Check socket permissions
+ls -la /var/snap/lxd/common/lxd/unix.socket
+
+# If permission denied error occurs, try activating lxd group
+newgrp lxd
+
+# Or use sg (switch group) to run commands with proper group access
+sg lxd -c "lxc list"
+sg lxd -c "lxc info torrust-vm"
+
+# Or as a workaround, use sudo (not recommended for regular use)
+sudo lxc list
 ```
 
 ## GitHub Actions Support
@@ -231,6 +363,8 @@ This configuration is designed specifically for CI/CD environments like GitHub A
 - **Status**: Fully supported and tested
 - **No special requirements**: Works in standard GitHub Actions runners
 
+**Important Note**: The GitHub workflow uses `sudo chmod 666` on the LXD socket as a workaround for CI environments where terminal restarts aren't practical. **This approach is not recommended for local development** due to security implications. For local use, follow the proper group membership approach described in the troubleshooting section.
+
 ### Pros and Cons
 
 **✅ Advantages:**

project-words.txt

@@ -1,13 +1,16 @@
 cloudinit
 cpus
 debootstrap
+getent
 larstobi
 lxdbr
 multipassd
+newgrp
 noninteractive
 NOPASSWD
 resolv
 runcmd
+subshell
 sysfs
 tfstate
 tfvars