feat(groq): An Ansible playbook that configures a persistent reverse SSH tunnel via a systemd service for remote access to machines behind NAT.

[polsala]

Implementation Summary

• Utility: nightly-ansible-ssh-tunnel-setup
• Provider: groq
• Location: ansible-playbooks/nightly-nightly-ansible-ssh-tunnel-s
• Files Created: 3
• Description: An Ansible playbook that configures a persistent reverse SSH tunnel via a systemd service for remote access to machines behind NAT.

Rationale

• Automated proposal from the Groq generator delivering a fresh community utility.
• This utility was generated using the groq AI provider.

Why safe to merge

• Utility is isolated to ansible-playbooks/nightly-nightly-ansible-ssh-tunnel-s.
• README + tests ship together (see folder contents).
• No secrets or credentials touched.
• All changes are additive and self-contained.

Test Plan

• Follow the instructions in the generated README at ansible-playbooks/nightly-nightly-ansible-ssh-tunnel-s/README.md
• Run tests located in ansible-playbooks/nightly-nightly-ansible-ssh-tunnel-s/tests/

Links

• Generated docs and examples committed alongside this change.

Mock Justification

• Not applicable; generator did not introduce new mocks.

[polsala]

🤖 Review by GROQ Agent

✅ What's solid

• Clear purpose & scope – The README and playbook name make it obvious that this utility sets up a persistent reverse SSH tunnel via a systemd service.
• Idempotent Ansible tasks –
  • user module creates a system user only if it does not exist.
  • package ensures autossh is present without reinstalling.
  • copy writes the unit file with a fixed checksum, so subsequent runs are a no‑op unless the content changes.
• Resilient tunnel – Using autossh with ServerAliveInterval/ServerAliveCountMax and Restart=always gives the service self‑healing behaviour.
• Isolation – All files live under ansible‑playbooks/nightly‑nightly‑ansible‑ssh‑tunnel‑s, so the change does not touch any existing playbooks or roles.
• Documentation of variables – The README lists every playbook variable with defaults, making it easy for a consumer to override only what they need.

🧪 Tests

• Current test approach – The test runs the playbook in --check mode via a command task and asserts a zero return code. This gives a quick sanity check that the playbook parses and that Ansible can reach the local host.
• Opportunities for improvement

  • Leverage Ansible’s built‑in testing tools – Consider using Molecule (or ansible-test integration) to spin up a lightweight container/VM, apply the playbook, and then verify the resulting systemd unit exists and is enabled. Example snippet for a Molecule verify step:

    - name: Verify service file
      stat:
        path: /etc/systemd/system/ssh-reverse-tunnel.service
      register: unit_file
    
    - assert:
        that:
          - unit_file.stat.exists
          - unit_file.stat.mode == '0644'

  • Avoid command to invoke ansible-playbook – Running Ansible from within Ansible adds a layer of indirection and can mask failures (e.g., syntax errors that only surface when the playbook is actually executed). Instead, place the playbook under test in the tests/ directory and call it directly with ansible-playbook -i inventory.yml test_setup_tunnel.yml.

  • Mock external dependencies – The test currently relies on the host having autossh and a functional SSH key pair. Use the ansible.builtin.mock or ansible.builtin.command with creates/removes to simulate package installation and systemd interactions, or run the test inside a container where those dependencies are pre‑installed.

  • Add assertions on idempotency – Run the playbook twice (first normal, second with --check) and assert that the second run reports “changed=0”.

🔒 Security

• Default remote_user is root – This is risky; if a consumer forgets to override the variable they will be opening an SSH tunnel as the root user on the central server.

  • Recommendation: Change the default to a non‑privileged user (e.g., {{ remote_user | default('ssh_tunnel') }}) and document that the central server must have a matching account.

• Service runs as a system user (tunnel_user) – Good practice, but the unit file does not restrict the SSH command’s options beyond ServerAlive*. Consider adding:

  • -o StrictHostKeyChecking=no only if you control the host keys, otherwise keep the default to avoid MITM.
  • -o ExitOnForwardFailure=yes to ensure the service fails fast if the remote port cannot be bound.

• File permissions – The unit file is owned by root with mode 0644. That is standard, but ensure the directory /etc/systemd/system/ is not world‑writable on the target hosts.

• SSH key handling – The README mentions a “pre‑shared SSH key pair” but does not enforce its presence. Adding a task that checks for the public key in ~{{ tunnel_user }}/.ssh/authorized_keys (or a configurable path) would prevent silent misconfiguration. Example:

  - name: Ensure public key is present for tunnel user
    authorized_key:
      user: "{{ tunnel_user }}"
      state: present
      key: "{{ lookup('file', 'files/id_rsa.pub') }}"

• Potential privilege escalation – The playbook uses become: true for all hosts. If the inventory contains hosts that should not receive this service, consider scoping the playbook to a specific group (e.g., hosts: tunnel_targets) to avoid accidental deployment.

🧩 Docs/DX

• README completeness – The overview, requirements, usage, and variable sections are solid. A few additions would make the developer experience smoother:
  • Inventory example – Show a minimal inventory.ini with a host entry and any required group vars.
  • Verification steps – After running the playbook, suggest commands such as systemctl status ssh-reverse-tunnel.service and netstat -tnlp | grep {{ remote_port }} to confirm the tunnel is active.
  • Troubleshooting – Common failure modes (e.g., missing SSH key, firewall blocking remote_port) and how to inspect logs (journalctl -u ssh-reverse-tunnel.service).
  • Version pinning – Mention the minimum Ansible version (2.9) and any OS constraints (e.g., Debian/Ubuntu for autossh package name).
• Variable defaults – The playbook already provides defaults for most variables, but the README could explicitly note which ones are required (remote_host) and which have sensible defaults.
• Link to upstream docs – Provide a short link to the autossh man page or a blog post describing reverse tunnels for readers unfamiliar with the concept.

🧱 Mocks/Fakes

• No explicit mocks – The PR states “Not applicable; generator did not introduce new mocks.” While the playbook itself does not need mocks, the test suite would benefit from them:

  • Package module – Mock the package task to avoid pulling autossh from the host’s package manager during CI.
  • Systemd daemon reload – Use the ansible.builtin.command mock to simulate systemctl daemon-reload without requiring a real systemd environment.
  • User creation – Mock the user module to verify that the correct parameters (system: true, shell: /usr/sbin/nologin) are passed.

  Example of a simple mock using ansible-test:

  - name: Mock autossh installation
    set_fact:
      __autossh_installed: true
    when: ansible_facts['pkg_mgr'] == 'apt'

  Or, with ansible.builtin.import_role you could create a lightweight role that stubs out the package and systemd modules for unit‑test runs.

---

Overall, the contribution adds a useful, well‑documented utility that follows Ansible best practices. Addressing the security default for remote_user, enriching the test suite with idempotency checks and proper mocking, and expanding the README with verification and troubleshooting steps will make the playbook safer and easier to adopt in production environments.

[polsala]

🤖 Review by GEMINI Agent

✅ What's solid

• Robust Systemd Integration: The playbook effectively leverages systemd for persistent service management, including After=network.target, Restart=always, RestartSec=10, and WantedBy=multi-user.target, ensuring the tunnel's resilience.
• Idempotent Task Design: Key tasks like user creation (user module), package installation (package module), and service file deployment (copy module) are designed to be idempotent, allowing safe re-execution without unintended side effects.
• Sensible autossh Usage: The inclusion of autossh with -M 0 (disabling monitoring port) and ServerAliveInterval/ServerAliveCountMax options demonstrates a good understanding of maintaining stable and secure SSH tunnels.

🧪 Tests

• Expand Check Mode Assertions: The current test only verifies that the playbook runs in check mode without errors. Enhance the test to assert the expected content of the generated /etc/systemd/system/ssh-reverse-tunnel.service file.

  - name: Assert service file content
    command: cat /etc/systemd/system/ssh-reverse-tunnel.service
    register: service_file_content
    changed_when: false
    check_mode: false # This task needs to run outside check mode to read the file
    when: not ansible_check_mode # Or use a separate test run for this
  
  - name: Verify ExecStart command in service file
    assert:
      that:
        - "'ExecStart=/usr/bin/autossh -M 0 -N -o \"ServerAliveInterval 30\" -o \"ServerAliveCountMax 3\" -R {{ remote_port }}:localhost:{{ local_port }} {{ remote_user }}@{{ remote_host }}' in service_file_content.stdout"
        - "'User={{ tunnel_user }}' in service_file_content.stdout"

• Variable Coverage: Add test cases that explicitly set all variables (tunnel_user, remote_port, local_port) to non-default values to ensure they are correctly applied in the generated service file.
• User Existence Check: Consider adding a check mode task to verify that the tunnel_user would be created with the correct attributes (e.g., nologin shell) without actually creating it.

🔒 Security

• Review remote_user Default: The playbook defaults remote_user to root. It is generally safer to use a dedicated, less privileged user on the central server for SSH tunnel connections. Consider changing the default to a non-privileged user (e.g., tunnel_remote) or removing the default to make it a mandatory variable.
• Document Central Server Firewall: Add a note in the README emphasizing the importance of properly securing the remote_port on the central server's firewall to restrict access to the tunneled service.
• Explicit Host Key Checking: While SSH typically performs host key checking, consider adding -o StrictHostKeyChecking=yes and -o UserKnownHostsFile=/dev/null (if keys are managed out-of-band) or documenting the expectation for host key management in the autossh command within the systemd unit file for enhanced security.

🧩 Docs/DX

• Align remote_user Default: The README usage example suggests remote_user=ubuntu, but the playbook defaults to root. Standardize this by either changing the playbook's default to ubuntu or updating the README example to reflect the root default.
• Complete Usage Example: Update the README's usage example to explicitly include local_port (even if using the default 22) for clarity, demonstrating all available variables.

  ansible-playbook -i inventory.ini src/setup_tunnel.yml -e "remote_user=ubuntu tunnel_user=ssh_tunnel remote_host=central.example.com remote_port=2222 local_port=22"

• Add Playbook Comments: Enhance the src/setup_tunnel.yml playbook with comments, particularly for the ExecStart command in the systemd unit, to explain the purpose of each autossh option (-M 0, -N, -o ServerAliveInterval, etc.).
• Variable for Service Path: While /etc/systemd/system/ssh-reverse-tunnel.service is standard, consider making service_path a configurable variable in vars (with its current value as the default) to allow for greater flexibility in specific deployment scenarios.

🧱 Mocks/Fakes

• Acknowledge Check Mode as Mocking: Explicitly state that running the playbook with --check serves as a form of mocking, allowing validation of syntax and idempotency without making actual system changes.
• Suggest Containerized Testing: For more comprehensive testing of network-related utilities, explore using container-based testing frameworks (e.g., Ansible Molecule with a Docker driver). This would allow for isolated, realistic functional tests that can verify actual service startup, tunnel establishment, and connectivity without impacting the host system.
• Simulate External Commands: For future complex scenarios, consider using Ansible's command module with changed_when: false and failed_when: false in test playbooks to simulate the output or behavior of external commands that are not fully covered by check mode.