shutdown_windows_server(8)

NAME

shutdown_windows_server - shut down a Windows guest through its SAC console

SYNOPSIS

/opt/omnicube/sbin/shutdown_windows_server zone

DESCRIPTION

shutdown_windows_server shuts down the Windows guest running in zone by driving the guest's Special Administration Console (SAC) over the zone console, so that the guest stops its own services before the virtual machine disappears.

It is an expect(1) script, run directly by /opt/ooce/bin/expect, and the whole conversation is four steps:

1.: Attach to the zone console with zlogin -e '#' -C zone. When the caller is already root (id -u returns 0) the plain zlogin is spawned; otherwise it is spawned through pfexec.
2.: Send a carriage return, which is what makes SAC print its prompt.
3.: Wait for the string SAC> and send shutdown.
4.: Send the console escape sequence #. to detach, leaving the guest to power itself off.

The pfexec test exists because pfexec adds no privilege when the caller is already root, while pfexec zlogin into an LX zone can emit pfexecd not running; pid NNNNN privileges not elevated on standard error, which expect would then mix into the console stream it is matching on. Being a Tcl script it cannot source /opt/omnicube/lib/common/utils.sh, so id -u stands in for the ${PFEXEC} test made there; for the same reason there is no run-level guard and no locking.

Use from manage_zone.sh

This command is normally not run by hand. The shutdown_zone path of manage_zone.sh(8) reads the zone's type attribute with zonecfg and, when it is windows, runs

/opt/omnicube/sbin/shutdown_windows_server zone

before issuing zoneadm -z zone shutdown, falling back to zoneadm ... halt if that fails. The guest is thus given the chance to stop cleanly first, and the host-side shutdown becomes the backstop rather than the primary mechanism.

OPERANDS

zone: Name of the zone hosting the Windows guest. Required, and taken from the first argument only; further arguments are ignored. The name is not validated and is passed to zlogin as given, so an empty or wrong name simply produces a failed zlogin.

USAGE

Example 1: shut a Windows guest down by hand

pfexec /opt/omnicube/sbin/shutdown_windows_server win2022
zoneadm -z win2022 list -v

Example 2: check first whether the guest agent could do it instead

/opt/omnicube/sbin/qemu-monitor-command -z win2022 -c ping \\
    || /opt/omnicube/sbin/shutdown_windows_server win2022

EXIT STATUS

The script sets no status of its own.

0: The conversation ran to its end. Note that this says nothing about whether the guest accepted the shutdown command.
1: expect itself failed, for example because the console could not be spawned.

FILES

/opt/omnicube/sbin/shutdown_windows_server: This command.
/opt/ooce/bin/expect: The interpreter named in the script's interpreter line; the command cannot run without it.
/etc/security/exec_attr.d/omnicube: Grants the OmniCube Administration profile uid=0 execution of /usr/sbin/zlogin (and of /opt/ooce/bin/expect itself).

ENVIRONMENT

PATH: Inherited, not reset: unlike most of the suite, this script sets no PATH of its own, and expect resolves the spawned zlogin and pfexec through it. It must therefore contain /usr/sbin and /usr/bin. Only /usr/bin/id is called by absolute path.

SECURITY

A non-root caller reaches the console through pfexec, which requires the root-equivalent OmniCube Administration profile; the restricted per-zone alternative is restrict-shell-cmd(8). The zone name is interpolated into the spawned command line without validation, so this command must not be exposed to untrusted callers or driven from unvalidated input.

NOTES

SAC must be enabled in the guest (Emergency Management Services on the serial port) and reachable on the console that zlogin -C attaches to. If the SAC> prompt never appears, the wait ends on the default expect timeout and the shutdown line is sent anyway, into whatever is listening - there is no timeout branch and no error is reported. A guest sitting at a login prompt instead of SAC is the common case for this.

The command detaches from the console as soon as shutdown has been sent and does not wait for the guest to finish. When it is called from manage_zone.sh(8) the subsequent zoneadm shutdown may therefore overtake a guest that is still stopping services; the zoneadm halt fallback makes that unconditional.

Where the QEMU guest agent is installed and configured, qemu-monitor-command -z zone -c shutdown --arguments.mode powerdown is the more observable route, since it reports whether the agent accepted the request.