NAME

vcrash - crash a running netkit virtual machine

SYNOPSIS

vcrash [options] MACHINE-ID...

DESCRIPTION

The vcrash command can be used to forcedly halt running virtual machines. It allows both to stop machines immediately (i.e., without having to go through their shutdown sequence) and to kill frozen machines. MACHINE-ID can be either the PID or the name of a virtual machine.

This command is quite similar to vhalt (see vhalt(1)), except that it is faster and its effect is comparable to that of unplugging the virtual machine power cord (as opposed to gracefully shutdown it). This also implies that crashed virtual machines will perform a file system integrity check upon their next boot.

The following options can be used to influence the way vcrash behaves.

-k

--kill

By default, virtual machines are crashed by sending them a special directive through their management console (mconsole) socket. Such method is generally faster, but in some situations it may not work properly (for example, if a virtual machine is somewhy frozen). If an attempt to crash a virtual machine via the mconsole fails, vcrash automatically tries hard to kill the virtual machine processes.
By using this option, the attempt with the mconsole socket is simply skipped, and vcrash directly kills virtual machine processes. This should work in most cases. If still it does not, try using vclean (see vclean(1)).

-q

--quick

--quiet

After crashing virtual machines, vcrash waits a few instants to check whether they have actually stopped. By using the -q (--quick, --quiet) option, vcrash exits immediately, without waiting for the machine to stop. This option also suppresses any kind of output except errors and warnings.
Notice that, when a virtual machine is crashed via its mconsole socket (default if the -k option is not used), vcrash still waits for the crash directive to reach the virtual machine before returning, even when using the -q option. The reason why this is necessary is simple: if somehy the directive does not reach the virtual machine within a predefined timeout, vcrash takes care of quitting the mconsole helper tool before exiting, thus getting rid of unuseful hanging processes.

-r

--remove-fs

Delete virtual machine (COW) filesystem after halting machine. This option does not affect in any way the model filesystem. In particular, using this option has no effect on machines started with the --no-cow or -W option. See the README in the Netkit filesystem package for more information about COW and model filesystems.

--test

Instead of actually crashing virtual machines, just show what would be done (i.e., which processes would be killed or which socket would be used to send the crash directive). This option cannot be used in conjunction with -q (or --quick, --quiet).

-u USERNAME

--user=USERNAME

This option limits the range of action of vcrash to machines owned by user USERNAME (i.e., only USERNAME's machines can be killed). This is useful, for example, if you need to crash someone else's machines (which requires administrative privileges). By default, vcrash only operates on virtual machines owned by the current user (the one who issued the vcrash command). The special user name '-' is reserved, and can be used to crash machines regardless of their owner.

Consider that different users may be running virtual machines having the same name. Hence, special care must be taken when using the '--user=-' option and one or more MACHINE-IDs are virtual machine names. In this case, if two (or more) users are running virtual machines having the same name, then only the one returned by

'vlist --user=- name'

is halted.

vcrash also supports the following options:

-h

--help

Show usage information.

--version

Print information about the installed Netkit release and the host kernel version and exit. If ''<unavailable>'' is printed instead of a version number, then the corresponding information could not be retrieved (for example because a non-standard Netkit kernel or filesystem is being used).

ENVIRONMENT VARIABLES

All Netkit commands require that the NETKIT_HOME variable contains the name of the directory Netkit is installed in.

Apart from this, vcrash supports no other environment variables.

BACKWARD COMPATIBILITY

The following options are deprecated and you are encouraged not to use them. They are only provided to ensure backward compatibility with older versions of Netkit.

--force

This option can be used to crash a virtual machine for which both the PID and the name are known. When using --force, vcrash switches to an alternative syntax. In particular, it takes exactly two arguments: the virtual machine PID and its name. Option -r or --remove-fs does not work when using --force.

This option had been introduced (but was undocumented) in older versions of vcrash with the purpose of speeding up the process of halting laboratories. With the current version of vcrash there isn't any reason to use it (not even for speeding up the crash).

--root

A synonym for --user=-.

SEE ALSO

vclean(1), vconf(1), vhalt(1), vlist(1), vstart(1), Netkit filesystem README.

AUTHOR

vcrash script: Massimo Rimondini
This man page: Massimo Rimondini, Fabio Ricci

REPORTING BUGS

Report bugs to the Github issues page: https://github.com/netkit-jh/netkit-jh-build/issues

Please follow the recommended templates when reporting bugs.