podman machine ssh: set correct exit code

Forward the ssh exit code to the podman caller. This is useful for
scripts. Use the same logic as podman unshare.

Fixes #14401

Signed-off-by: Paul Holzinger <pholzing@redhat.com>

1 files changed, 30 insertions, 0 deletions

diff --git a/docs/source/markdown/podman-machine-ssh.1.md b/docs/source/markdown/podman-machine-ssh.1.md
index db0350961..6a1455df1 100644
--- a/docs/source/markdown/podman-machine-ssh.1.md
+++ b/docs/source/markdown/podman-machine-ssh.1.md
@@ -14,6 +14,7 @@ first argument must be the virtual machine name. The optional command to
 execute can then follow. If no command is provided, an interactive session
 with the virtual machine is established.
 
+The exit code from ssh command will be forwarded to the podman machine ssh caller, see [Exit Codes](#Exit-Codes).
 
 ## OPTIONS
 
@@ -25,6 +26,35 @@ Print usage statement.
 
 Username to use when SSH-ing into the VM.
 
+## Exit Codes
+
+The exit code from `podman machine ssh` gives information about why the command failed.
+When `podman machine ssh` commands exit with a non-zero code,
+the exit codes follow the `chroot` standard, see below:
+
+  **125** The error is with podman **_itself_**
+
+    $ podman machine ssh --foo; echo $?
+    Error: unknown flag: --foo
+    125
+
+  **126** Executing a _contained command_ and the _command_ cannot be invoked
+
+    $ podman machine ssh /etc; echo $?
+    Error: fork/exec /etc: permission denied
+    126
+
+  **127** Executing a _contained command_ and the _command_ cannot be found
+
+    $ podman machine ssh foo; echo $?
+    Error: fork/exec /usr/bin/bogus: no such file or directory
+    127
+
+  **Exit code** _contained command_ exit code
+
+    $ podman machine ssh /bin/sh -c 'exit 3'; echo $?
+    3
+
 ## EXAMPLES
 
 To get an interactive session with the default virtual machine: