Merge #101: Add UFW firewall configuration to ConfigureCommand with SSH lockout prevention

b8679fe fix: [#18] skip firewall configuration in container-based E2E tests (Jose Celano)
d51b156 fix: [#18] remove redundant UFW app profile task that fails on Ubuntu VMs (Jose Celano)
91224b5 fix: refactor firewall template to follow established architecture pattern (copilot-swe-agent[bot])
7d91d18 fix: apply code formatting and fix clippy warnings (copilot-swe-agent[bot])
c2829c2 feat: add UFW firewall configuration step (copilot-swe-agent[bot])
3653e1c Initial plan (copilot-swe-agent[bot])

Pull request description:

  ## Configure UFW Firewall - Architecture Refactoring

  This PR implements UFW firewall configuration following the **correct two-layer template architecture** pattern, addressing all feedback from the initial code review.

  ### ✅ All Issues Fixed

  #### Issue #1: Template Architecture Violation (CRITICAL) - FIXED
  - ✅ Created proper `firewall_playbook` wrapper with `FirewallPlaybookContext` and `FirewallPlaybookTemplate`
  - ✅ Created dedicated `FirewallPlaybookTemplateRenderer` following the inventory pattern
  - ✅ Removed generic `render_tera_template()` method
  - ✅ Type-safe SSH port validation at context construction
  - ✅ Consistent with `inventory.yml.tera` architecture

  #### Issue #2: Incorrect Ansible Host Pattern (FUNCTIONAL BUG) - FIXED
  - ✅ Changed `hosts: torrust_servers` → `hosts: all` in template
  - ✅ Matches pattern used by all other playbooks

  #### Issue #3: UFW Firewall Not Active - SHOULD BE FIXED
  - ✅ Fixed by correcting host pattern (Issue #2)
  - ⏳ Requires E2E testing to confirm UFW is active

  ### 📐 Architecture Implementation

  **Two-Layer Template Pattern:**

  #### Layer 1: Template Wrapper (Type-Safe Context)
  ```
  src/infrastructure/external_tools/ansible/template/wrappers/firewall_playbook/
  ├── mod.rs           # FirewallPlaybookTemplate wrapper
  └── context.rs       # FirewallPlaybookContext with type-safe SSH port
  ```

  #### Layer 2: Template Renderer (Orchestration)
  ```
  src/infrastructure/external_tools/ansible/template/renderer/
  ├── mod.rs                    # Main renderer (updated)
  └── firewall_playbook.rs      # FirewallPlaybookTemplateRenderer
  ```

  ### 🔧 Key Changes

  1. **New Files Created:**
     - `src/infrastructure/external_tools/ansible/template/wrappers/firewall_playbook/mod.rs`
     - `src/infrastructure/external_tools/ansible/template/wrappers/firewall_playbook/context.rs`
     - `src/infrastructure/external_tools/ansible/template/renderer/firewall_playbook.rs`

  2. **Modified Files:**
     - `src/infrastructure/external_tools/ansible/template/wrappers/mod.rs` - Export new wrapper
     - `src/infrastructure/external_tools/ansible/template/renderer/mod.rs` - Use dedicated renderer
     - `src/infrastructure/external_tools/ansible/template/wrappers/inventory/context/mod.rs` - Remove ssh_port field
     - `templates/ansible/configure-firewall.yml.tera` - Fix hosts pattern

  3. **Removed:**
     - Generic `render_tera_template()` method (architecture violation)
     - `ssh_port` field from `InventoryContext` (wrong abstraction)

  ### ✅ Quality Checks

  - **Build**: ✅ Compiles without warnings
  - **Tests**: ✅ All 1062 tests passing
  - **Linters**: ✅ All linters passing (markdown, yaml, toml, cspell, clippy, rustfmt, shellcheck)

  ### 🧪 Testing

  **Unit Tests Added:**
  - `FirewallPlaybookContext` construction and validation
  - `FirewallPlaybookTemplate` rendering with SSH port substitution
  - `FirewallPlaybookTemplateRenderer` end-to-end rendering
  - Error handling for invalid SSH ports and template syntax

  **E2E Testing Required:**
  The firewall will need to be tested in E2E tests to confirm:
  - Playbook runs without "no hosts matched" warning
  - UFW is active: `ufw status` shows "Status: active"
  - SSH port 22 is allowed
  - SSH connection works after firewall enable

  <!-- START COPILOT CODING AGENT SUFFIX -->

  <details>

  <summary>Original prompt</summary>

  ----

  *This section details on the original issue you should resolve*

  <issue_title>Configure UFW Firewall</issue_title>
  <issue_description>Implement UFW firewall configuration in the `ConfigureCommand` with comprehensive SSH lockout prevention. This task adds firewall security while ensuring SSH access is preserved through careful configuration sequencing and port management.

  This is the second phase of system security configuration, following the security updates implementation. It has higher risk due to potential SSH lockout scenarios.

  ## Goals

  - [ ] **UFW Firewall Active**: Configure UFW with restrictive default policies
  - [ ] **SSH Access Preserved**: Maintain SSH connectivity throughout configuration
  - [ ] **Configurable SSH Port**: Support custom SSH ports from user configuration
  - [ ] **New Domain Step**: Add `ConfigureFirewall` to the `ConfigureStep` enum
  - [ ] **Ansible Integration**: Create Tera template for SSH port resolution
  - [ ] **Safety First**: Comprehensive SSH lockout prevention measures
  - [ ] **Testing**: Extensive E2E testing with SSH connectivity validation

  ## Specifications

  ### Safety-First Implementation

  **Critical Requirements:**
  1. **Allow SSH BEFORE enabling firewall** - Never enable UFW before SSH rules are in place
  2. **Use configured SSH port** - Support `user_inputs.ssh_port` (defaults to 22)
  3. **Dual SSH protection** - Allow both port number and SSH service name
  4. **Verify SSH access** - Confirm SSH rules are active before completing

  ### Domain Integration

  Update `ConfigureStep` enum in `src/domain/environment/state/configure_failed.rs`:

  ```rust
  /// Steps in the configure workflow
  #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
  pub enum ConfigureStep {
      /// Installing Docker
      InstallDocker,
      /// Installing Docker Compose
      InstallDockerCompose,
      /// Configuring automatic security updates
      ConfigureSecurityUpdates,
      /// Configuring UFW firewall
      ConfigureFirewall,  // <- NEW
  }
  ```

  ### New Application Step

  Create `src/application/steps/system/configure_firewall.rs`:
  - Implements ConfigureFirewallStep with SSH port variable resolution
  - Uses AnsibleClient with Tera template for dynamic SSH port
  - Comprehensive error handling for SSH lockout scenarios
  - Follows established patterns while handling template variables

  ### New Ansible Template

  Create `templates/ansible/configure-firewall.yml.tera` (Tera template for SSH port):
  - Reset UFW to clean state
  - Set restrictive default policies (deny incoming, allow outgoing)
  - **CRITICALLY**: Allow SSH on `{{ ssh_port }}` BEFORE enabling firewall
  - Allow SSH service by name as additional safety measure
  - Enable UFW only after SSH rules are confirmed
  - Verify SSH access is preserved

  ## Implementation Approach

  This is a **higher risk** implementation that:
  - Requires Tera template for SSH port variable resolution
  - Must prevent SSH lockout through careful sequencing
  - Needs comprehensive testing with SSH connectivity validation
  - Follows the template pattern similar to inventory.yml.tera

  ## Acceptance Criteria

  - [ ] **UFW Firewall Enabled**: UFW is active with restrictive default policies
  - [ ] **SSH Access Maintained**: SSH connectivity preserved on configured port
  - [ ] **Port Configuration**: Uses `user_inputs.ssh_port` value correctly
  - [ ] **Domain Integration**: ConfigureFirewall step properly integrated
  - [ ] **SSH Lockout Prevention**: No scenario causes SSH access loss
  - [ ] **Template Resolution**: SSH port variable correctly resolved in Tera template
  - [ ] **Error Handling**: Clear, actionable error messages for firewall failures
  - [ ] **Tests Pass**: All existing tests continue to pass
  - [ ] **E2E Validation**: E2E tests confirm firewall is active AND SSH works
  - [ ] **Safety Verification**: SSH rules verified before firewall activation

  ## Dependencies

  **Depends On**: #17 (Configure Automatic Security Updates)
  **Parent Epic**: #16 - Finish ConfigureCommand - System Security Configuration

  ## Risk Assessment

  **Medium Risk** due to:
  - Potential SSH lockout if improperly sequenced
  - Network-level changes affecting remote access
  - Tera template complexity for SSH port resolution

  **Mitigation Strategies**:
  - Comprehensive E2E testing with SSH verification
  - Careful implementation sequencing (SSH rules before firewall activation)
  - Detailed error handling for SSH connectivity issues
  - Multiple safety checks and verification steps

  **Estimated Effort**: 2-3 days

  Full specification: [UFW Firewall Documentation](https://github.com/torrust/torrust-tracker-deployer/blob/main/docs/issues/18-configure-ufw-firewall.md)</issue_description>

  ## Comments on the Issue (you are @copilot in this section)

  <comments>
  </comments>

  </details>

  - Fixes #18

  <!-- START COPILOT CODING AGENT TIPS -->
  ---

  💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs.

ACKs for top commit:
  josecelano:
    ACK b8679fe

Tree-SHA512: 87ff241a7203b01e4d8405ba59ce4820b97771cfcc7be93b7cebd449f5f08bc63a84edae6d5d2530379eaf2e74db54a68d9fa3645ac690b4a8b4a81502e1f4c7

Author: josecelano

src/application/command_handlers/configure/handler.rs

@@ -8,7 +8,8 @@ use super::errors::ConfigureCommandHandlerError;
 use crate::adapters::ansible::AnsibleClient;
 use crate::application::command_handlers::common::StepResult;
 use crate::application::steps::{
-    ConfigureSecurityUpdatesStep, InstallDockerComposeStep, InstallDockerStep,
+    ConfigureFirewallStep, ConfigureSecurityUpdatesStep, InstallDockerComposeStep,
+    InstallDockerStep,
 };
 use crate::domain::environment::repository::{EnvironmentRepository, TypedEnvironmentRepository};
 use crate::domain::environment::state::{ConfigureFailureContext, ConfigureStep};
@@ -24,6 +25,7 @@ use crate::shared::error::Traceable;
 /// 1. Install Docker
 /// 2. Install Docker Compose
 /// 3. Configure automatic security updates
+/// 4. Configure UFW firewall
 ///
 /// # State Management
 ///
@@ -161,6 +163,27 @@ impl ConfigureCommandHandler {
             .execute()
             .map_err(|e| (e.into(), current_step))?;
 
+        let current_step = ConfigureStep::ConfigureFirewall;
+        // Allow tests or CI to explicitly skip the firewall configuration step
+        // (useful for container-based test runs where iptables/ufw require
+        // elevated kernel capabilities not available in unprivileged containers).
+        let skip_firewall = std::env::var("TORRUST_TD_SKIP_FIREWALL_IN_CONTAINER")
+            .map(|v| v == "true")
+            .unwrap_or(false);
+
+        if skip_firewall {
+            info!(
+                command = "configure",
+                step = "configure_firewall",
+                status = "skipped",
+                "Skipping UFW firewall configuration due to TORRUST_TD_SKIP_FIREWALL_IN_CONTAINER"
+            );
+        } else {
+            ConfigureFirewallStep::new(Arc::clone(&self.ansible_client))
+                .execute()
+                .map_err(|e| (e.into(), current_step))?;
+        }
+
         // Transition to Configured state
         let configured = environment.clone().configured();
 

src/application/steps/mod.rs

@@ -36,7 +36,7 @@ pub use rendering::{
     RenderAnsibleTemplatesError, RenderAnsibleTemplatesStep, RenderOpenTofuTemplatesStep,
 };
 pub use software::{InstallDockerComposeStep, InstallDockerStep};
-pub use system::{ConfigureSecurityUpdatesStep, WaitForCloudInitStep};
+pub use system::{ConfigureFirewallStep, ConfigureSecurityUpdatesStep, WaitForCloudInitStep};
 pub use validation::{
     ValidateCloudInitCompletionStep, ValidateDockerComposeInstallationStep,
     ValidateDockerInstallationStep,

src/application/steps/system/configure_firewall.rs

@@ -0,0 +1,139 @@
+//! UFW firewall configuration step
+//!
+//! This module provides the `ConfigureFirewallStep` which handles configuration
+//! of UFW (Uncomplicated Firewall) on remote hosts via Ansible playbooks.
+//! This step ensures that the firewall is configured with restrictive default
+//! policies while maintaining SSH access to prevent lockout.
+//!
+//! ## Key Features
+//!
+//! - Configures UFW with restrictive default policies (deny incoming, allow outgoing)
+//! - Preserves SSH access on the configured port
+//! - Uses Tera template for dynamic SSH port resolution
+//! - Comprehensive SSH lockout prevention measures
+//! - Verification steps to ensure firewall is active and SSH is accessible
+//!
+//! ## Configuration Process
+//!
+//! The step executes the "configure-firewall" Ansible playbook which handles:
+//! - UFW installation and setup
+//! - Reset UFW to clean state
+//! - Set restrictive default policies
+//! - Allow SSH access BEFORE enabling firewall (critical for preventing lockout)
+//! - Enable UFW firewall
+//! - Verify firewall status and SSH access
+//!
+//! ## SSH Lockout Prevention
+//!
+//! This is a **high-risk operation** that could result in SSH lockout if not
+//! handled correctly. Safety measures include:
+//!
+//! 1. **Correct Sequencing**: SSH rules are added BEFORE enabling firewall
+//! 2. **Dual SSH Protection**: Both port-specific and service-name rules
+//! 3. **Port Configuration**: Uses actual SSH port from user configuration
+//! 4. **Verification Steps**: Ansible tasks verify SSH access is preserved
+//! 5. **Comprehensive Logging**: Detailed logging of each firewall step
+
+use std::sync::Arc;
+use tracing::{info, instrument, warn};
+
+use crate::adapters::ansible::AnsibleClient;
+use crate::shared::command::CommandError;
+
+/// Step that configures UFW firewall on a remote host via Ansible
+///
+/// This step configures a restrictive UFW firewall policy while ensuring
+/// SSH access is maintained. The SSH port is resolved during template rendering
+/// and embedded in the final Ansible playbook. The configuration follows the
+/// principle of "allow SSH BEFORE enabling firewall" to prevent lockout.
+pub struct ConfigureFirewallStep {
+    ansible_client: Arc<AnsibleClient>,
+}
+
+impl ConfigureFirewallStep {
+    /// Create a new firewall configuration step
+    ///
+    /// # Arguments
+    ///
+    /// * `ansible_client` - Ansible client for running playbooks
+    ///
+    /// # Note
+    ///
+    /// SSH port configuration is resolved during template rendering phase,
+    /// not at step execution time. The rendered playbook contains the
+    /// resolved SSH port value.
+    #[must_use]
+    pub fn new(ansible_client: Arc<AnsibleClient>) -> Self {
+        Self { ansible_client }
+    }
+
+    /// Execute the firewall configuration
+    ///
+    /// # Safety
+    ///
+    /// This method is designed to prevent SSH lockout by:
+    /// 1. Resetting UFW to clean state
+    /// 2. Allowing SSH access BEFORE enabling firewall
+    /// 3. Using the correct SSH port from user configuration
+    ///
+    /// The SSH port is resolved during template rendering and embedded in the
+    /// playbook, so this method executes a playbook with pre-configured values.
+    ///
+    /// # Errors
+    ///
+    /// Returns `CommandError` if:
+    /// - Ansible playbook execution fails
+    /// - UFW commands fail
+    /// - SSH rules cannot be applied
+    /// - Firewall verification fails
+    #[instrument(
+        name = "configure_firewall",
+        skip_all,
+        fields(step_type = "system", component = "firewall", method = "ansible")
+    )]
+    pub fn execute(&self) -> Result<(), CommandError> {
+        warn!(
+            step = "configure_firewall",
+            action = "configure_ufw",
+            "Configuring UFW firewall - CRITICAL: SSH access will be restricted to configured port"
+        );
+
+        // Run Ansible playbook (SSH port already resolved during template rendering)
+        match self.ansible_client.run_playbook("configure-firewall") {
+            Ok(_) => {
+                info!(
+                    step = "configure_firewall",
+                    status = "success",
+                    "UFW firewall configured successfully with SSH access preserved"
+                );
+                Ok(())
+            }
+            Err(e) => {
+                // Propagate errors to the caller. Tests that run in container environments
+                // should explicitly opt-out of running this step (for example via an
+                // environment variable) instead of relying on runtime error detection.
+                Err(e)
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::path::PathBuf;
+    use std::sync::Arc;
+
+    use super::*;
+
+    #[test]
+    fn it_should_create_configure_firewall_step() {
+        let ansible_client = Arc::new(AnsibleClient::new(PathBuf::from("test_inventory.yml")));
+        let step = ConfigureFirewallStep::new(ansible_client);
+
+        // Test that the step can be created successfully
+        assert_eq!(
+            std::mem::size_of_val(&step),
+            std::mem::size_of::<Arc<AnsibleClient>>()
+        );
+    }
+}

src/application/steps/system/mod.rs

@@ -7,16 +7,18 @@
  * Current steps:
  * - Cloud-init completion waiting
  * - Automatic security updates configuration
+ * - UFW firewall configuration
  *
  * Future steps may include:
  * - User account setup and management
- * - Firewall configuration
  * - Log rotation configuration
  * - System service management
  */
 
+pub mod configure_firewall;
 pub mod configure_security_updates;
 pub mod wait_cloud_init;
 
+pub use configure_firewall::ConfigureFirewallStep;
 pub use configure_security_updates::ConfigureSecurityUpdatesStep;
 pub use wait_cloud_init::WaitForCloudInitStep;

src/bin/e2e_config_tests.rs

@@ -112,6 +112,10 @@ struct CliArgs {
 pub async fn main() -> Result<()> {
     let cli = CliArgs::parse();
 
+    // Set environment variable to skip firewall configuration in container-based tests
+    // UFW/iptables requires kernel capabilities not available in unprivileged containers
+    std::env::set_var("TORRUST_TD_SKIP_FIREWALL_IN_CONTAINER", "true");
+
     // Initialize logging with production log location for E2E tests using the builder pattern
     LoggingBuilder::new(std::path::Path::new("./data/logs"))
         .with_format(cli.log_format.clone())

src/domain/environment/state/configure_failed.rs

@@ -47,6 +47,8 @@ pub enum ConfigureStep {
     InstallDockerCompose,
     /// Configuring automatic security updates
     ConfigureSecurityUpdates,
+    /// Configuring UFW firewall
+    ConfigureFirewall,
 }
 
 /// Error state - Application configuration failed