Add podman machine restart subcommand

[jaitjacob]

Checklist

Ensure you have completed the following checklist for your pull request to be reviewed:

• Certify you wrote the patch or otherwise have the right to pass it on as an open-source patch by signing all
  commits. (git commit -s). (If needed, use git commit -s --amend). The author email must match
  the sign-off email address. See CONTRIBUTING.md
  for more information.
• Referenced issues using Fixes: #00000 in commit message (if applicable)
• Tests have been added/updated (or no tests are needed)
• Documentation has been updated (or no documentation changes are needed)
• All commits pass make validatepr (format/lint checks)
• Release note entered in the section below (or None if no user-facing changes)

Does this PR introduce a user-facing change?

Yes? No action needed when upgrading?

Fixes #28366

This PR implements podman machine restart subcommand.

Here's how I tested it,

1. Locally build podman binary using make BUILDTAGS="selinux seccomp" PREFIX=/usr
2. cd bin/
3. Run ./podman machine restart --help & verify help text displays correctly.

jaitjacob@fedora:~/Documents/workbench/podman/bin$ ./podman machine restart --help
Restart an existing machine

Description:
  Restart a managed virtual machine

Usage:
  podman machine restart [MACHINE]

Examples:
  podman machine restart podman-machine-default

5. Run ./podman machine list

jaitjacob@fedora:~/Documents/workbench/podman/bin$ ./podman machine list
NAME                     VM TYPE     CREATED      LAST UP            CPUS        MEMORY      DISK SIZE
podman-machine-default*  qemu        3 hours ago  About an hour ago  2           2GiB        10GiB

6. Run ./podman machine start

jaitjacob@fedora:~/Documents/workbench/podman/bin$ ./podman machine start
Starting machine "podman-machine-default"

This machine is currently configured in rootless mode. If your containers
require root permissions (e.g. ports < 1024), or if you run into compatibility
issues with non-podman clients, you can switch using the following command:

        podman machine set --rootful

Mounting volume... /home/jaitjacob:/home/jaitjacob
API forwarding listening on: /run/user/1000/podman/podman-machine-default-api.sock
You can connect Docker API clients by setting DOCKER_HOST using the
following command in your terminal session:

        export DOCKER_HOST='unix:///run/user/1000/podman/podman-machine-default-api.sock'

Machine "podman-machine-default" started successfully

7. SSH into VM and check uptime

jaitjacob@fedora:~/Documents/workbench/podman/bin$ ./podman machine ssh
Connecting to vm podman-machine-default. To close connection, use `~.` or `exit`
Fedora CoreOS 43.20260316.3.1
Tracker: https://github.com/coreos/fedora-coreos-tracker
Discuss: https://discussion.fedoraproject.org/tag/coreos

Last login: Mon May 11 22:26:20 2026 from 192.168.127.1
core@localhost:~$ uptime -p
up 0 minutes
core@localhost:~$ uptime -s
2026-05-12 00:36:59

8. Wait couple mins and run ./podman machine restart

jaitjacob@fedora:~/Documents/workbench/podman/bin$ ./podman machine restart
Waiting for VM to exit...
Machine "podman-machine-default" stopped successfully

This machine is currently configured in rootless mode. If your containers
require root permissions (e.g. ports < 1024), or if you run into compatibility
issues with non-podman clients, you can switch using the following command:

        podman machine set --rootful

Mounting volume... /home/jaitjacob:/home/jaitjacob
API forwarding listening on: /run/user/1000/podman/podman-machine-default-api.sock
You can connect Docker API clients by setting DOCKER_HOST using the
following command in your terminal session:

        export DOCKER_HOST='unix:///run/user/1000/podman/podman-machine-default-api.sock'

Machine "podman-machine-default" started successfully

10. SSH into VM and Check uptime again

jaitjacob@fedora:~/Documents/workbench/podman/bin$ ./podman machine ssh
Connecting to vm podman-machine-default. To close connection, use `~.` or `exit`
Fedora CoreOS 43.20260316.3.1
Tracker: https://github.com/coreos/fedora-coreos-tracker
Discuss: https://discussion.fedoraproject.org/tag/coreos

Last login: Tue May 12 00:37:17 2026 from 192.168.127.1
core@localhost:~$ uptime -p
up 0 minutes
core@localhost:~$ uptime -s
2026-05-12 00:39:14

I also built the docs locally and viewed in browser,

[TomSweeneyRedHat]

@jaitjacob TYVM for the PR! It looks great overall. You should add a test or two if possible, and there are a few tweaks to do to the documenation.

By far the best description I've seen on a PR in a very long time!

[Honny1]

Thanks! At first glance, the code looks good. However, the PR is missing tests. Please implement e2e tests for machine. Here is an example you can use as a reference: https://github.com/containers/podman/blob/main/pkg/machine/e2e/start_test.go. You can add a restart_test.go file for this.

[baude]

One of the reasons I never wanted this sub-command is because there were cases were if the Podman binary did not exit, then there could be collision or zombied processes of helper functions or the various sockets and pipes being used. Are you certain that this cannot happen?

[baude]

in addition to tests, we might need a basic test added to podman-machine-os as well?

[packit-as-a-service]

[NON-BLOCKING] Packit jobs failed. @containers/packit-build please check. Everyone else, feel free to ignore.

[jaitjacob]

1. new commits introduce a Shim.StopThenStart such that podman machine restart holds a lock across both stop and start. I refactored a private function shim.startLocked from Shim.Start for this. With the old shim.Stop it would try to mc.Lock() again while already holding it.

func Start(...) error {
    dirs := ...
    if !opts.ReExec {
        mc.Lock()
        defer mc.Unlock()
    }
    mc.Refresh()
    return startLocked(...)  // rest of Start is refactored inside startLocked
}

2. this is how the sequence of shim.StopThenStart looks like now:

mc.Lock()
defer mc.Unlock()

mc.Refresh()
stopLocked(...)
startLocked(...)

[TomSweeneyRedHat]

@jaitjacob all kinds of test unhappiness.