vsphere-iso: clarify if ssh_timeout and ssh_handshake_attempts are mutually exclusive

[lindhe]

Community Note

Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request.
Please do not leave "+1" or "me too" comments, they generate extra noise for issue followers and do not help prioritize the request.
If you are interested in working on this issue or have submitted a pull request, please leave a comment.

Description

The documentation says the following:

ssh_timeout (duration string | ex: "1h5m2s") - The time to wait for SSH to become available. Packer uses this to determine when the machine has booted so this is usually quite long. Example value: 10m. This defaults to 5m, unless ssh_handshake_attempts is set.

[…]

ssh_handshake_attempts (int) - The number of handshakes to attempt with SSH once it can connect. This defaults to 10, unless a ssh_timeout is set.

This leaves me wondering:

1. Are the ssh_timeout and ssh_handshake_attempts fields mutually exclusive? It kind of sounds like that, but it's not clear.
2. What is the value of ssh_timeout if ssh_handshake_attempts is set (and vice versa)? (if they are not mutually exclusive, of course).

I think this should be clarified in the documentation.

Use Case(s)

The documentation should be clear on how things works.

Potential configuration

n/a

Potential References

See links above.

[tenthirtyam]

The ssh_timeout and ssh_handshake_attempts fields are not mutually exclusive. They control different aspects of the SSH connection process.

ssh_timeout specifies the maximum amount of time to wait for SSH to become available. This is used to determine when the machine has booted up and is ready to accept SSH connections.

ssh_handshake_attempts specifies the number of SSH handshake attempts to make once a connection can be established. This is used to handle transient issues that might cause an SSH handshake to fail.

If ssh_handshake_attempts is set and ssh_timeout is not, ssh_timeout defaults to 5 minutes. This means that Packer will wait up to 5 minutes for SSH to become available, and then make the specified number of handshake attempts.

If ssh_timeout is set and ssh_handshake_attempts is not, ssh_handshake_attempts defaults to 10. This means that Packer will make up to 10 SSH handshake attempts once a connection can be established, and will wait the specified amount of time for SSH to become available.

If both ssh_timeout and ssh_handshake_attempts are set, Packer will use the specified values. If neither is set, Packer will use the default values (5 minutes for ssh_timeout and 10 for ssh_handshake_attempts).

I'd be happy to update and generate the documentation to help clarify this concern.

[lindhe]

I'd be happy to update and generate the documentation to help clarify this concern.

Thanks, that would be great. 👍

I think that the root cause for my confusion is that the default values are explained with so many conditions. But if I read your clarification above correctly, the possible states are simply:

ssh_timeout is set	ssh_handshake_attempts is set	ssh_timeout default value	ssh_handshake_attempts default value
True	True	-	-
False	True	5 min	-
True	False	-	10
False	False	5 min	10

Does this table correctly represent all possible states? If so, I see no reason for all the conditionals in explaining the fields' default values. If my table is correct, we can simply say that "the default value for ssh_timeout is 5 min and the default value for ssh_handshake_attempts is 10".

[tenthirtyam]

Certainly, I'll address this today.

[tenthirtyam]

Upon further review, this concern needs to be raised in the Packer Plugin SDK hashicorp/packer-plugin-sdk as it impacts all plugins.

• SSHTimeout
• SSHHandshakeAttempts

[lindhe]

Ok. Will you raise it, or should I?

[tenthirtyam]

Please feel to raise it on the SDK and link to this issue if you like.