Overview

Date: 2026-05-11

Time: 15:13

Overview

This page covers FTL2's primary use case: executing automation modules on remote machines via SSH. It walks through setting up a Docker-based SSH target, configuring inventory for SSH connectivity, and running modules remotely. It also explains the internal "gate" mechanism that FTL2 uses to package and ship module code to remote hosts.

Key Concepts

• Remote execution is FTL2's primary use case — running modules on remote systems via SSH, not just locally
• ansible_connection: ssh in inventory triggers the RemoteModuleRunner using the asyncssh library
• Gate mechanism — FTL2 packages each module into a Python zipapp (.pyz), uploads it to the remote host's /tmp/, executes it with the remote Python interpreter, and reads results back via length-prefixed JSON protocol
• Gates are cached by content hash — once uploaded, a gate remains in /tmp for reuse on subsequent runs
• SSH authentication supports both password and key-based auth — key-based is strongly recommended for production
• ansiblepythoninterpreter must point to a valid Python 3 path on the remote host — if wrong, gate execution fails
• Same modules work locally and remotely — the module interface is identical; only the connection type changes

Commands and Syntax

Inventory configuration for SSH:

all:
  hosts:
    remote-server:
      ansible_host: 127.0.0.1
      ansible_port: 2222
      ansible_user: testuser
      ansible_connection: ssh
      ansible_python_interpreter: /usr/bin/python3
      vars:
        ansible_password: testpass

Core remote commands:

ftl2 -m ping -i inventory.yml                      # Test connectivity
ftl2 -m setup -i inventory.yml                     # Gather remote facts
ftl2 -m shell -i inventory.yml -a "cmd='uname -a'" # Run shell command
ftl2 -m file -i inventory.yml -a "path=/tmp/test.txt state=touch"  # Create file
ftl2 -m copy -i inventory.yml -a "src=/tmp/local.txt dest=/tmp/remote.txt"  # Copy file
ftl2 -m file -i inventory.yml -a "path=/tmp/test.txt state=absent" # Remove file

Verbose debugging:

ftl2 -m ping -i inventory.yml -vvv

Inspecting gates:

ls -la /tmp/ftl_gate_*.pyz
echo -n '0000000d["Hello", {}]' | python3 /tmp/ftl_gate_*.pyz

Key inventory fields: ansiblehost, ansibleport (default 22), ansibleuser, ansibleconnection, ansiblepythoninterpreter, vars.ansible_password

Relationships

• Inventory management — SSH connection parameters are configured in inventory YAML; understanding inventory structure is prerequisite
• Module usage — same modules (ping, setup, file, shell, copy) work identically in local and remote modes
• Gate modules — the gate zipapp mechanism is central to remote execution; gate pre-building improves performance
• Privilege escalation — become/sudo configuration layers on top of SSH connections for remote privilege changes
• Vault integration — production deployments should use Vault for SSH credentials rather than plaintext passwords in inventory
• Migration from Ansible — inventory field names (ansiblehost, ansibleport, etc.) mirror Ansible conventions intentionally

Exam-Relevant Points

• The remote execution flow is: detect SSH → build gate zipapp → connect via asyncssh → upload gate to /tmp/ → execute with Python → return length-prefixed JSON results
• ansible_connection: ssh is the inventory field that enables remote execution
• Gates are cached by content hash, not by name or timestamp
• Gate protocol uses length-prefixed JSON for communication
• ansiblepythoninterpreter must be set correctly or remote execution fails with "Python interpreter not found"
• Password auth uses vars.ansiblepassword; key auth uses ~/.ssh/idrsa by default with no password field needed
• The -vvv flag enables verbose logging for troubleshooting remote execution
• Security: password authentication and disabled StrictHostKeyChecking are for development only — production requires SSH keys, host key verification, and SSH agent forwarding