#Communicators (SSH)

A communicator is the channel the build uses to talk to the running VM while provisioning it — the mechanism for uploading files and executing scripts inside the guest. After the VM boots, the build needs a way to reach in and run things; the communicator is that connection.

It sits between two phases:

1. Boot — the VM comes up (ISO or cloud image, plus any bootCommand) and brings up its network and SSH daemon.
2. Provision — file and shell provisioners run inside the guest over the communicator.

SSH is the only supported communicator.

communicator:
    type: ssh # default
    shell: bash # bash | powershell, default bash
    sshUsername: debian # default "root"
    sshPort: 22 # default 22
    sshPassword: '' # optional, used in addition to keys
    sshTimeout: '5m' # how long to wait for SSH to come up; default 5m

shell is the most consequential field — it controls how files are uploaded and how scripts are executed. Get this wrong and provisioners break in subtle ways.

sshTimeout should be generous. ISO installs especially can take 30 minutes to an hour before SSH is ready. Set this to your reasonable upper bound — a too-short timeout fails the build.

To pre-set a known SSH keypair (e.g., for debugging), use sshPrivateKeySecret to reference a Secret containing your key. Otherwise the build generates a fresh keypair per build and discards it.

#Communicator vs. bootCommand

These two cover different windows in the build:

• Use bootCommand for anything that has to happen before SSH exists — typing at the BIOS/GRUB menu, dismissing "Press any key to boot from CD", pointing an installer at a preseed/kickstart URL. It works by typing keystrokes into the VM's VNC console, so it's the only option when there's no OS (or no networking) to connect to yet.
• Use the communicator for everything after the OS is up and SSH responds — copying files, running shell or PowerShell scripts, installing packages. This is where provisioners do their work.

Rule of thumb: if you can express the step as a script, do it over the communicator. Reserve bootCommand for the parts of installer UX that only accept keystrokes.