Oracle VM VirtualBox. User Manual (Version 7.0.18)

9 VBoxManage

--passwordfile=<filename>

Specifies the absolute path to a file on the guest OS that contains the password for the

specified user. If the password file is empty or if you do not specify a password on the

command line, the specified user needs to have an empty password.

--username=<username>

Specifies an existing user on the guest OS that runs the process. If unspecified, the host

user runs the process.

Guest Process Restrictions

By default, you can run up to five guest processes simultaneously. If a new guest process starts

and would exceed this limit, the oldest not-running guest process is discarded to run the new

process. You cannot retrieve output from a discarded guest process. If all five guest processes

are active and running, attempting to start a new guest process fails.

You can modify the guest process execution limit in two ways:

• Use

the

VBoxManage setproperty

command

update

the

/VirtualBox/GuestAdd/VBoxService/-control-procs-max-kept

guest

property

value.

• Use the VBoxService command and specify the --control-procs-max-kept=<value>

option.

After you change the limit, you must restart the guest OS.

You can serve an unlimited number guest processes by specifing a value of 0, however this

action is not recommended.

Run a Command on the guest

VBoxManage guestcontrol <uuid | vmname> run [--arg0=argument 0]

[--domain=domainname] [--dos2unix] [--exe=filename]

[--ignore-orphaned-processes] [--no-wait-stderr | --wait-stderr]

[--no-wait-stdout | --wait-stdout] [--passwordfile=password-file

| --password=password] [--profile] [--putenv=var-name=[value]] [--quiet]

[--timeout=msec] [--unix2dos] [--unquoted-args] [--username=username]

[--verbose] <-- [argument. . . ]

The VBoxManage guestcontrol vmname run command enables you to execute a program

on the guest VM. Standard input, standard output, and standard error are redirected from the

VM to the host system until the program completes.

Note: The Windows OS imposes certain limitations for graphical applications. See

chapter 15, Known Limitations, page 421.

--exe=<path-to-executable>

Specifies the absolute path of the executable program to run on the guest VM. For example:

C:\Windows\System32\calc.exe.

--timeout=<msec>

Specifies the maximum amount of time, in milliseconds, that the program can run. While

the program runs, VBoxManage receives its output.

If you do not specify a timeout value, VBoxManage waits indefinitely for the process to end,

or for an error to occur.

286

9 VBoxManage

--putenv=<NAME>=[<value>]

Sets, modifies, and unsets environment variables in the guest VM environment.

When you create a guest process, it runs with the default standard guest OS environment.

Use this option to modify environment variables in that default environment.

Use the --putenv=<NAME>=[<value>] option to set or modify the environment variable

specified by NAME.

Use the --putenv=<NAME>=[<value>] option to unset the environment variable specified

by NAME.

Ensure that any environment variable name or value that includes spaces is enclosed by

quotes.

Specify a --putenv option for each environment variable that you want to modify.

The short form of this option is -E.

--unquoted-args

Disables the escaped double quoting of arguments that you pass to the program. For ex-

ample, \"fred\".

--ignore-orphaned-processes

Ignores orphaned processes. Not yet implemented.

--profile

Uses a shell profile to specify the environment to use. Not yet implemented.

--no-wait-stdout

Does not wait for the guest process to end or receive its exit code and any failure explana-

tion.

--wait-stdout

Waits for the guest process to end to receive its exit code and any failure explanation. The

VBoxManage command receives the standard output of the guest process while the process

runs.

--no-wait-stderr

Does not wait for the guest process to end to receive its exit code, error messages, and

flags.

--wait-stderr

Waits for the guest process to end to receive its exit code, error messages, and flags. The

VBoxManage command receives the standard error of the guest process while the process

runs.

--dos2unix

Transform DOS or Windows guest output to UNIX or Linux output. This transformation

changes CR + LF line endings to LF. Not yet implemented.

--unix2dos

Transform UNIX or Linux guest output to DOS or Windows output. This transformation

changes LF line endings to CR + LF.

--[<argument>...]

Specifies the name of the program and any arguments to pass to the program.

Ensure that any command argument that includes spaces is enclosed by quotes.

287

9 VBoxManage

Start a Command on the guest

VBoxManage guestcontrol <uuid | vmname> start [--arg0=argument 0]

[--domain=domainname] [--exe=filename] [--ignore-orphaned-processes]

[--passwordfile=password-file | --password=password] [--profile]

[--putenv=var-name=[value]] [--quiet] [--timeout=msec] [--unquoted-args]

[--username=username] [--verbose] <-- [argument. . . ]

The VBoxManage guestcontrol vmname start command enables you to execute a guest

program until it completes.

Note: The Windows OS imposes certain limitations for graphical applications. See

chapter 15, Known Limitations, page 421.

Copy a file from the guest to the host.

VBoxManage guestcontrol <uuid | vmname> copyfrom [--dereference]

[--domain=domainname] [--passwordfile=password-file

| --password=password] [--quiet] [--no-replace] [--recursive]

[--target-directory=host-destination-dir] [--update]

[--username=username] [--verbose] <guest-source0> guest-source1 [...]

<host-destination>

The VBoxManage guestcontrol vmname copyfrom command enables you to copy a file from

the guest VM to the host system.

--dereference

Enables following of symbolic links on the guest file system.

--no-replace

Only copies a file if it does not exist on the host yet.

The short form of this option is -n.

--recursive

Recursively copies files and directories from the specified guest directory to the host.

The short form of this option is -R.

--target-directory=<host-dst-dir>

Specifies the absolute path of the destination directory on the host system. For example,

C:\Temp.

--update

Only copies a file if the guest file is newer than on the host.

The short form of this option is -u.

guest-source0 [guest-source1 [...]]

Specifies the absolute path of one or more files to copy from the guest VM. For example,

C:\Windows\System32\calc.exe. You can use wildcards to specify multiple files. For

example, C:\Windows\System*\*.dll.

288

9 VBoxManage

Copy a file from the host to the guest.

VBoxManage guestcontrol <uuid | vmname> copyto [--dereference]

[--domain=domainname] [--passwordfile=password-file

| --password=password] [--quiet] [--no-replace] [--recursive]

[--target-directory=guest-destination-dir] [--update]

[--username=username] [--verbose] <host-source0> host-source1 [...]

The VBoxManage guestcontrol vmname copyto command enables you to copy a file from

the host system to the guest VM.

--dereference

Enables following of symbolic links on the host system.

--no-replace

Only copies a file if it does not exist on the guest yet.

The short form of this option is -n.

--recursive

Recursively copies files and directories from the specified host directory to the guest.

The short form of this option is -R.

--target-directory=<guest-dst-dir>

Specifies the absolute path of the destination directory on the guest. For example,

/home/myuser/fromhost.

--update

Only copies a file if the host file is newer than on the guest.

The short form of this option is -u.

host-source0 [host-source1 [...]]

Specifies the absolute path of a file to copy from the host system. For example,

C:\Windows\System32\calc.exe. You can use wildcards to specify multiple files. For

example, C:\Windows\System*\*.dll.

Create a directory on the guest.

VBoxManage guestcontrol <uuid | vmname> mkdir [--domain=domainname]

[--mode=mode] [--parents] [--passwordfile=password-file

| --password=password] [--quiet] [--username=username] [--verbose]

<guest-directory. . . >

The VBoxManage guestcontrol vmname mkdir command enables you to create one or more

directories on the guest VM.

Alternate forms of this subcommand are md, createdir, and createdirectory.

--parents

Creates any of the missing parent directories of the specified directory.

For example, if you attempt to create the D:\Foo\Bar directory and the D:\Foo directory

does not exist, using the --parents creates the missing D:\Foo directory. However, if you

attempt to create the D:\Foo\Bar and do not specify the --parents option, the command

fails.

289

9 VBoxManage

--mode=<mode>

Specifies the permission mode to use for the specified directory. If you specify the

--parents option, the mode is used for the associated parent directories, as well. mode is

a four-digit octal mode such as 0755.

guest-dir [guest-dir...]

Specifies an absolute path of one or more directories to create on the guest VM. For exam-

ple, D:\Foo\Bar.

If all of the associated parent directories do not exist on the guest VM, you must specify

the --parents option.

You must have sufficient rights on the guest VM to create the specified directory and its

parent directories.

Remove a directory from the guest.

VBoxManage guestcontrol <uuid | vmname> rmdir [--domain=domainname]

[--passwordfile=password-file | --password=password] [--quiet]

[--recursive] [--username=username] [--verbose] <guest-directory. . . >

The VBoxManage guestcontrol vmname rmdir command enables you to delete the specified

directory from the guest VM.

Alternate forms of this subcommand are removedir and removedirectory.

--recursive

Recursively removes directories from the specified from the guest VM.

The short form of this option is -R.

guest-dir [guest-dir...]

Specifies an absolute path of one or more directories to remove from the guest VM. You

can use wildcards to specify the directory names. For example, D:\Foo\*Bar.

You must have sufficient rights on the guest VM to remove the specified directory and its

parent directories.

Remove a file from the guest.

VBoxManage guestcontrol <uuid | vmname> rm [--domain=domainname] [--force]

[--passwordfile=password-file | --password=password] [--quiet]

[--username=username] [--verbose] <guest-directory. . . >

The VBoxManage guestcontrol vmname rm command enables you to delete the specified

files from the guest VM.

The alternate form of this subcommand is removefile.

--force

Forces the operation and overrides any confirmation requests.

The short form of this option is -f.

guest-file [guest-file...]

Specifies an absolute path of one or more file to remove from the guest VM. You can use

wildcards to specify the file names. For example, D:\Foo\Bar\text*.txt.

You must have sufficient rights on the guest VM to remove the specified file.

290

9 VBoxManage

Rename a file or Directory on the guest

VBoxManage guestcontrol <uuid | vmname> mv [--domain=domainname]

[--passwordfile=password-file | --password=password] [--quiet]

[--username=username] [--verbose] <source. . . > <destination-directory>

The VBoxManage guestcontrol vmname mv command enables you to rename files and di-

rectories on the guest VM.

Alternate forms of this subcommand are move, ren, and rename.

guest-source [guest-source...]

Specifies an absolute path of a file or a single directory to move or rename on the guest

VM. You can use wildcards to specify the file names.

You must have sufficient rights on the guest VM to access the specified file or directory.

dest

Specifies the absolute path of the renamed file or directory, or the destination directory

to which to move the files. If you move only one file, dest can be a file or a directory,

otherwise dest must be a directory.

You must have sufficient rights on the guest VM to access the destination file or directory.

Create a Temporary File or Directory on the guest

VBoxManage guestcontrol <uuid | vmname> mktemp [--directory]

[--domain=domainname] [--mode=mode] [--passwordfile=password-file

| --password=password] [--quiet] [--secure] [--tmpdir=directory-name]

[--username=username] [--verbose] <template-name>

The VBoxManage guestcontrol vmname mktemp command enables you to create a tempo-

rary file or temporary directory on the guest VM. You can use this command to assist with the

subsequent copying of files from the host system to the guest VM. By default, this command

creates the file or directory in the guest VM’s platform-specific temp directory.

Alternate forms of this subcommand are createtemp and createtemporary.

--directory

Creates a temporary directory that is specified by the template operand.

--secure

Enforces secure file and directory creation by setting the permission mode to 0755. Any

operation that cannot be performed securely fails.

--mode=<mode>

Specifies the permission mode to use for the specified directory. mode is a four-digit octal

mode such as 0755.

--tmpdir=<directory>

Specifies the absolute path of the directory on the guest VM in which to create the specified

file or directory. If unspecified, directory is the platform-specific temp directory.

template

Specifies a template file name for the temporary file, without a directory path. The template

file name must contain at least one sequence of three consecutive X characters, or must end

in X.

291

9 VBoxManage

Show a file or File System Status on the guest

VBoxManage guestcontrol <uuid | vmname> stat [--domain=domainname]

[--passwordfile=password-file | --password=password] [--quiet]

[--username=username] [--verbose] <filename>

The VBoxManage guestcontrol vmname stat command enables you to show the status of

files or file systems on the guest VM.

file [file ...]

Specifies an absolute path of a file or file system on the guest VM. For example,

/home/foo/a.out.

You must have sufficient rights on the guest VM to access the specified files or file systems.

List the Configuration and Status Information for a Guest Virtual Machine

VBoxManage guestcontrol <uuid | vmname> list <all | files | processes

| sessions> [--quiet] [--verbose]

The VBoxManage guestcontrol vmname list command enables you to list guest control

configuration and status information. For example, the output shows open guest sessions, guest

processes, and files.

all|sessions|processes|files

Indicates the type of information to show. all shows all available data, sessions shows

guest sessions, processes shows processes, and files shows files.

Terminate a Process in a guest Session

VBoxManage guestcontrol <uuid | vmname> closeprocess [--session-id=ID

| --session-name=name-or-pattern] [--quiet] [--verbose] <PID. . . >

The VBoxManage guestcontrol vmname closeprocess command enables you to terminate

a guest process that runs in a guest session. Specify the process by using a process identifier

(PID) and the session by using the session ID or name.

--session-id=<ID>

Specifies the ID of the guest session.

--session-name=<name>|<pattern>

Specifies the name of the guest session. Use a pattern that contains wildcards to specify

multiple sessions.

PID [PID ...]

Specifies the list of PIDs of guest processes to terminate.

Close a guest Session

VBoxManage guestcontrol <uuid | vmname> closesession [--all

| --session-id=ID | --session-name=name-or-pattern] [--quiet] [--verbose]

The VBoxManage guestcontrol vmname closesession command enables you to close a

guest session. Specify the guest session either by session ID or by name.

292

9 VBoxManage

--session-id=<ID>

Specifies the ID of the guest session.

--session-name=<name>|<pattern>

Specifies the name of the guest session. Use a pattern that contains wildcards to specify

multiple sessions.

--all

Closes all guest sessions.

Update the Guest Additions Software on the guest

VBoxManage guestcontrol <uuid | vmname> updatega [--quiet] [--verbose]

[--source=guest-additions.ISO] [--wait-start] [-- [argument. . . ]

]

The VBoxManage guestcontrol vmname updatega command enables you to update the

Guest Additions software installed in the specified guest VM.

Alternate forms of this subcommand are updateadditions and updateguestadditions.

--source=<new-iso-path>

Specifies the absolute path of the Guest Additions update .ISO file on the guest VM.

--reboot

Automatically reboots the guest after a successful Guest Additions update.

--timeout=<ms>

Sets the timeout (in ms) to wait for the overall Guest Additions update to complete. By

default no timeout is being used.

--verify

Verifies whether the Guest Additions were updated successfully after a successful installa-

tion. A guest reboot is mandatory.

--wait-ready

Waits for the current Guest Additions being ready to handle the Guest Additions update.

--wait-start

Starts the VBoxManage update process on the guest VM and then waits for the Guest Addi-

tions update to begin before terminating the VBoxManage process.

By default, the VBoxManage command waits for the Guest Additions update to complete

before it terminates. Use this option when a running VBoxManage process affects the inter-

action between the installer and the guest OS.

-- <argument> [<argument> ...]

Specifies optional command-line arguments to pass to the Guest Additions updater. You

might use the -- option to pass the appropriate updater arguments to retrofit features that

are not yet installed.

Ensure that any command argument that includes spaces is enclosed by quotes.

Wait for a guest run level

The VBoxManage guestcontrol vmname waitrunlevel command enables you to wait for a

guest run level being reached.

--timeout=<ms>

Sets the timeout (in ms) to wait for reaching the run level. By default no timeout is being

used.

293

9 VBoxManage

Specifies the run level to wait for.

Show Current Guest Control Activity

VBoxManage guestcontrol <uuid | vmname> watch [--quiet] [--verbose]

The VBoxManage guestcontrol vmname watch command enables you to show current guest

control activity.

Examples

The following VBoxManage guestcontrol run command executes the ls -l /usr command

on the My OL VM Oracle Linux VM as the user1 user.

$ VBoxManage --nologo guestcontrol "My OL VM" run --exe "/bin/ls" \

--username user1 --passwordfile pw.txt --wait-stdout -- -l /usr

The --exe option specifies the absolute path of the command to run in the guest VM, /bin/ls.

Use the -- option to pass any arguments that follow it to the ls command.

Use the --username option to specify the user name, user1 and use the --passwordfile

option to specify the name of a file that includes the password for the user1 user, pw.txt.

The --wait-stdout option waits for the ls guest process to complete before providing the

exit code and the command output. The --nologo option suppresses the output of the logo

information.

The following VBoxManage guestcontrol run command executes the ipconfig command

on the My Win VM Windows VM as the user1 user. Standard input, standard output, and stan-

dard error are redirected from the VM to the host system until the program completes.

$ VBoxManage --nologo guestcontrol "My Win VM" run \

--exe "c:\\windows\\system32\\ipconfig.exe" \

--username user1 --passwordfile pw.txt --wait-stdout

The

--exe specifies the absolute path of command to run in the guest VM,

c:\windows\system32\ipconfig.exe. The double backslashes shown in this example are re-

quired only on UNIX host systems.

Use the --username option to specify the user name, user1 and use the --passwordfile

option to specify the name of a file that includes the password for the user1 user, pw.txt.

The --wait-stdout option waits for the ls guest process to complete before providing the

exit code and the command output. The --nologo option to suppress the output of the logo

information.

The following VBoxManage guestcontrol start command executes the ls -l /usr com-

mand on the My OL VM Oracle Linux VM until the program completes.

$ VBoxManage --nologo guestcontrol "My Win VM" start \

--exe "c:\\windows\\system32\\ipconfig.exe" \

--username user1 --passwordfile pw.txt

The

following

VBoxManage guestcontrol run

command

executes

/usr/bin/busybox -l /usr command on the My OL VM Oracle Linux VM as the user1

user, explicitly using ls as argument 0.

294

9 VBoxManage

$ VBoxManage --nologo guestcontrol "My OL VM" run --exe "/usr/bin/busybox" \

--username user1 --passwordfile pw.txt --wait-stdout --arg0 ls -- -l /usr

The --exe option specifies the absolute path of the command to run in the guest VM,

/usr/bin/busybox. Use the -- option to pass any arguments that follow it to the busybox

command.

Use the --username option to specify the user name, user1 and use the --passwordfile

option to specify the name of a file that includes the password for the user1 user, pw.txt.

The --wait-stdout option waits for the ls guest process to complete before providing the

exit code and the command output. The --nologo option suppresses the output of the logo

information.

The --arg0 option explicitly specifies the argument 0 to use for the command to execute.

Note: If this option is not set, argument 0 will be taken from the value of --exe, or, if

--exe is also not set, the first value passed after --.Use --verbose to see the effective

command line passed to the guest.

The default behavior of argument 0 is to either use the value from --exe, or, if not set, the

first value passed after --.

9.45 VBoxManage debugvm

Introspection and guest debugging.

Synopsis

VBoxManage debugvm <uuid|vmname> dumpvmcore [--filename=name]

VBoxManage debugvm <uuid|vmname> info <item> [args. . . ]

VBoxManage debugvm <uuid|vmname> injectnmi

VBoxManage debugvm <uuid|vmname> log [[--release] | [--debug]]

[group-settings. . . ]

VBoxManage debugvm <uuid|vmname> logdest [[--release] | [--debug]]

[destinations. . . ]

VBoxManage debugvm <uuid|vmname> logflags [[--release] | [--debug]]

[flags. . . ]

VBoxManage debugvm <uuid|vmname> osdetect

VBoxManage debugvm <uuid|vmname> osinfo

VBoxManage debugvm <uuid|vmname> osdmesg [--lines=lines]

VBoxManage debugvm <uuid|vmname> getregisters [--cpu=id]

[reg-set.reg-name. . . ]

VBoxManage debugvm <uuid|vmname> setregisters [--cpu=id]

[reg-set.reg-name=value. . . ]

295

9 VBoxManage

VBoxManage debugvm <uuid|vmname> show [[--human-readable] | [--sh-export]

| [--sh-eval] | [--cmd-set]] [settings-item. . . ]

VBoxManage debugvm <uuid|vmname> stack [--cpu=id]

VBoxManage debugvm <uuid|vmname> statistics [--reset] [--descriptions]

[--pattern=pattern]

VBoxManage debugvm <uuid|vmname> guestsample [--filename=filename]

[--sample-interval-us=interval] [--sample-time-us=time]

Description

The “debugvm” commands are for experts who want to tinker with the exact details of virtual

machine execution. Like the VM debugger described in chapter 13.1.4, The Built-In VM Debugger,

page 401, these commands are only useful if you are very familiar with the details of the PC

architecture and how to debug software.

Common options

The subcommands of debugvm all operate on a running virtual machine:

uuid|vmname

Either the UUID or the name (case sensitive) of a VM.

debugvm dumpvmcore

VBoxManage debugvm <uuid|vmname> dumpvmcore [--filename=name]

Creates a system dump file of the specified VM. This file will have the standard ELF core format

(with custom sections); see chapter 13.1.5, VM Core Format, page 403.

This corresponds to the writecore command in the debugger.

--filename=<filename>

The name of the output file.

debugvm info

VBoxManage debugvm <uuid|vmname> info <item> [args. . . ]

Displays info items relating to the VMM, device emulations and associated drivers.

This corresponds to the info command in the debugger.

item

Name of the info item to display. The special name help will list all the available info items

and hints about optional arguments.

args

Optional argument string for the info item handler. Most info items does not take any extra

arguments. Arguments not recognized are generally ignored.

296

9 VBoxManage

debugvm injectnmi

VBoxManage debugvm <uuid|vmname> injectnmi

Causes a non-maskable interrupt (NMI) to be injected into the guest. This might be useful for

certain debugging scenarios. What happens exactly is dependent on the guest operating system,

but an NMI can crash the whole guest operating system. Do not use unless you know what you’re

doing.

debugvm log

VBoxManage debugvm <uuid|vmname> log [[--release] | [--debug]]

[group-settings. . . ]

Changes the group settings for either debug (--debug) or release (--release) logger of the

VM process.

The group-settings are typically strings on the form em.e.f.l, hm=~0 and -em.f. Basic

wildcards are supported for group matching. The all group is an alias for all the groups.

Please do keep in mind that the group settings are applied as modifications to the current ones.

This corresponds to the log command in the debugger.

debugvm logdest

VBoxManage debugvm <uuid|vmname> logdest [[--release] | [--debug]]

[destinations. . . ]

Changes the destination settings for either debug (--debug) or release (--release)

logger of the VM process.

For details on the destination format, the best source is

src/VBox/Runtime/common/log/log.cpp.

The destinations is one or more mnemonics, optionally prefixed by “no” to disable them.

Some of them take values after a “:“ or “=“ separator. Multiple mnemonics can be separated by

space or given as separate arguments on the command line.

List of available destination:

file[=<file>], nofile

Specifies a log file. If no filename is given, one will be generated based on the current UTC

time and VM process name and placed in the current directory of the VM process. Note

that this will currently not have any effect if the log file has already been opened.

dir=<directory>, nodir

Specifies the output directory for log files. Note that this will currently not have any effect

if the log file has already been opened.

history=<count>, nohistory

A non-zero value enables log historization, with the value specifying how many old log files

to keep.

histsize=<bytes>

The max size of a log file before it is historized. Default is infinite.

histtime=<seconds>

The max age (in seconds) of a log file before it is historized. Default is infinite.

297

9 VBoxManage

ringbuffer, noringbuffer

Only log to the log buffer until an explicit flush (e.g. via an assertion) occurs. This is fast

and saves diskspace.

stdout, nostdout

Write the log content to standard output.

stdout, nostdout

Write the log content to standard error.

debugger, nodebugger

Write the log content to the debugger, if supported by the host OS.

com, nocom

Writes logging to the COM port. This is only applicable for raw-mode and ring-0 logging.

user, nouser

Custom destination which has no meaning to VM processes..

This corresponds to the logdest command in the debugger.

debugvm logflags

VBoxManage debugvm <uuid|vmname> logflags [[--release] | [--debug]]

[flags. . . ]

Changes the flags on either debug (--debug) or release (--release) logger of the VM process.

Please note that the modifications are applied onto the existing changes, they are not replacing

them.

The flags are a list of flag mnemonics, optionally prefixed by a “no”, “¡‘, “~“ or “-“ to negate

their meaning. The “+“ prefix can be used to undo previous negation or use as a separator,

though better use whitespace or separate arguments for that.

List of log flag mnemonics, with their counter form where applicable (asterisk indicates de-

faults):

enabled*, disabled

Enables or disables logging.

buffered, unbuffered*

Enabling buffering of log output before it hits the destinations.

writethrough(/writethru)

Whether to open the destination file with writethru buffering settings or not.

flush

Enables flushing of the output file (to disk) after each log statement.

lockcnts

Prefix each log line with lock counts for the current thread.

cpuid

Prefix each log line with the ID of the current CPU.

pid

Prefix each log line with the current process ID.

flagno

Prefix each log line with the numberic flags corresponding to the log statement.

298

9 VBoxManage

flag

Prefix each log line with the flag mnemonics corresponding to the log statement.

groupno

Prefix each log line with the log group number for the log statement producing it.

group

Prefix each log line with the log group name for the log statement producing it.

tid

Prefix each log line with the current thread identifier.

thread

Prefix each log line with the current thread name.

time

Prefix each log line with the current UTC wall time.

timeprog

Prefix each log line with the current monotonic time since the start of the program.

msprog

Prefix each log line with the current monotonic timestamp value in milliseconds since the

start of the program.

Prefix each log line with the current monotonic timestamp value in nanoseconds.

tsc

Prefix each log line with the current CPU timestamp counter (TSC) value.

rel, abs*

Selects the whether ts and tsc prefixes should be displayed as relative to the previous log

line or as absolute time.

hex*, dec

Selects the whether the ts and tsc prefixes should be formatted as hexadecimal or deci-

mal.

custom

Custom log prefix, has by default no meaning for VM processes.

usecrlf, uself*

Output with DOS style (CRLF) or just UNIX style (LF) line endings.

overwrite*, append

Overwrite the destination file or append to it.

This corresponds to the logflags command in the debugger.

debugvm osdetect

VBoxManage debugvm <uuid|vmname> osdetect

Make the VMM’s debugger facility (re)-detect the guest operating system (OS). This will first

load all debugger plug-ins.

This corresponds to the detect command in the debugger.

299

9 VBoxManage

debugvm osinfo

VBoxManage debugvm <uuid|vmname> osinfo

Displays information about the guest operating system (OS) previously detected by the VMM’s

debugger facility.

debugvm osdmesg

VBoxManage debugvm <uuid|vmname> osdmesg [--lines=lines]

Displays the guest OS kernel log, if detected and supported.

--lines=<lines>

Number of lines of the log to display, counting from the end. The default is infinite.

debugvm getregisters

VBoxManage debugvm <uuid|vmname> getregisters [--cpu=id]

[reg-set.reg-name. . . ]

Retrieves register values for guest CPUs and emulated devices.

reg-set.reg-name

One of more registers, each having one of the following forms:

1. register-set.register-name.sub-field

2. register-set.register-name

3. cpu-register-name.sub-field

4. cpu-register-name

5. all

The all form will cause all registers to be shown (no sub-fields). The registers names are

case-insensitive.

--cpu=<id>

Selects the CPU register set when specifying just a CPU register (3rd and 4th form). The

default is 0.

debugvm setregisters

VBoxManage debugvm <uuid|vmname> setregisters [--cpu=id]

[reg-set.reg-name=value. . . ]

Changes register values for guest CPUs and emulated devices.

reg-set.reg-name=value

One of more register assignment, each having one of the following forms:

1. register-set.register-name.sub-field=value

2. register-set.register-name=value

3. cpu-register-name.sub-field=value

300

9 VBoxManage

4. cpu-register-name=value

The value format should be in the same style as what getregisters displays, with the

exception that both octal and decimal can be used instead of hexadecimal.

--cpu=<id>

Selects the CPU register set when specifying just a CPU register (3rd and 4th form). The

default is 0.

debugvm show

VBoxManage debugvm <uuid|vmname> show [[--human-readable] | [--sh-export]

| [--sh-eval] | [--cmd-set]] [settings-item. . . ]

Shows logging settings for the VM.

--human-readable

Selects human readable output.

--sh-export

Selects output format as bourne shell style export commands.

--sh-eval

Selects output format as bourne shell style eval command input.

--cmd-set

Selects output format as DOS style SET commands.

settings-item

What to display. One or more of the following:

• logdbg-settings - debug log settings.

• logrel-settings - release log settings.

• log-settings - alias for both debug and release log settings.

debugvm stack

VBoxManage debugvm <uuid|vmname> stack [--cpu=id]

Unwinds the guest CPU stacks to the best of our ability. It is recommended to first run the

osdetect command, as this gives both symbols and perhaps unwind information.

--cpu=<id>

Selects a single guest CPU to display the stack for. The default is all CPUs.

debugvm statistics

VBoxManage debugvm <uuid|vmname> statistics [--reset] [--descriptions]

[--pattern=pattern]

Displays or resets VMM statistics.

Retrieves register values for guest CPUs and emulated devices.

301

9 VBoxManage

--pattern=<pattern>

DOS/NT-style wildcards patterns for selecting statistics. Multiple patterns can be specified

by using the ’|’ (pipe) character as separator.

--reset

Select reset instead of display mode.

debugvm guestsample

VBoxManage debugvm <uuid|vmname> guestsample [--filename=filename]

[--sample-interval-us=interval] [--sample-time-us=time]

Creates a sample report of the guest activity.

Retrieves the filename to dump the report to.

--filename=<filename>

The filename to dump the sample report to.

--sample-interval-us=<interval>

The interval in microseconds between guest samples.

--sample-time-us=<time>

The amount of microseconds to take guest samples.

9.46 VBoxManage metrics

Monitor system resource usage.

Synopsis

VBoxManage metrics collect [--detach] [--list] [--period=seconds]

[--samples=count] [_* | host | vmname [metric-list] ]

VBoxManage metrics disable [--list] [_* | host | vmname [metric-list] ]

VBoxManage metrics enable [--list] [_* | host | vmname [metric-list] ]

VBoxManage metrics list [_* | host | vmname [metric-list] ]

VBoxManage metrics query [_* | host | vmname [metric-list] ]

VBoxManage metrics setup [--list] [--period seconds] [--samples count] [_*

| host | vmname [metric-list] ]

Description

The VBoxManage metrics command enables you to monitor system resource usage for the host

system and for virtual machines (VMs). For example, you can monitor particular metrics, such

as the percentage of time CPUs spend executing in user mode (CPU/Load/User) over a specified

sampling period.

While it runs, the VBoxSVC process collects and saves the specified metric data internally.

The VBoxSVC process runs until shortly after you close all VMs and frontends. Use the

VBoxManage metrics query command to retrieve data at any time.

By default, metrics are not collected unless you run the VBoxManage metrics setup com-

mand to specify a sampling interval in seconds and the number of metrics to save.

Note that you can enable metric collection only for started VMs. Collected data and collection

settings for a VM are discarded when the VM shuts down.

302

9 VBoxManage

Metrics

The host and VMs have different sets of associated metrics, which you can view by running the

VBoxManage metrics list command.

Each metric is represented as a string that is composed of a category and a metric. Option-

ally, the metric string can include any of the following: a submetric, a sub-submetric, and an

aggregate. The metric string has the following format:

<category>/<metric>[/<submetric>[/<sub-submetric>]][:<aggregate>]

• category is the resource type, such as CPU, RAM, FS, Net.

• metric is a measurement type that is associated with the resource category. For example,

the Load and MHz metrics are associated with the CPU resource category.

• submetric is an optional measurement type that is associated with the metric. For exam-

ple, the User, Kernel, and Idle submetrics are associated with the Load metric.

• sub-submetric is an optional measurement type that is associated with the submetric. For

example, the Rx and Tx sub-submetrics are associated with the Rate submetric of the Net

resource category. The associated metric is the network interface.

• aggregate is an optional function to provide minimum, maximum, and average measure-

ments for a resource category. For example, the RAM/Usage/Free:min metric represents

the minimum amount of available memory found in all saved data on the host system.

By default, the VBoxManage metrics commands operate on the host system and all VMs, and

report on all metrics. You can optionally limit these commands to operate on the host system or

on a particular VM, and report on a list of one or more metrics.

Common Options

* | host | vmname

Specifies the component on which to operate. By default, this command operates on the

host system and all running VMs.

If you specify host, the VBoxManage metrics command operates on the host system only.

If you specify an asterisk (_*), the command operates on all VMs. If you specify the name

of a VM, the VBoxManage metrics command operates on that VM.

metric-list

Specifies a comma-separated list of one or more metrics.

The form of the metric must include the category and metric part of the metric string

separated by a slash.

Note that the VBoxManage metrics enable and VBoxManage metrics disable com-

mands require that you specify metrics as parameters. The metrics must include only the

resource category and metric part, such as CPU/Load and RAM/Usage.

Collect Data Metrics

VBoxManage metrics collect [--detach] [--list] [--period=seconds]

[--samples=count] [_* | host | vmname [metric-list] ]

The VBoxManage metrics collect command collects and outputs data periodically until you

stop the process by pressing Ctrl+C.

303

9 VBoxManage

--detach

Disables the collection of metric data, so no data is output. Using this option is the same

as running the VBoxManage metrics setup command.

--list

Shows which metrics match the specified filter.

--period=<seconds>

Specifies the number of seconds to wait between collecting metric data samples. The de-

fault value is 1.

--samples=<count>

Specifies the number of metric data samples to save. To view the saved data, use the

VBoxManage metrics query command. The default value is 1.

Disable Metric Data Collection

VBoxManage metrics disable [--list] [_* | host | vmname [metric-list] ]

The VBoxManage metrics disable command suspends data collection. This action does not

affect the data collection properties or the collected data. Note that specifying a submetric in the

metric list does not disable its underlying metrics.

Note that the VBoxManage metrics disable command requires that you specify metrics

as parameters. The metrics must include only the resource category and metric part, such as

CPU/Load and RAM/Usage.

--list

Shows whether the command succeeded as expected.

Enable Metric Data Collection

VBoxManage metrics enable [--list] [_* | host | vmname [metric-list] ]

The VBoxManage metrics enable command resumes data collection after it has been sus-

pended by using the VBoxManage metrics disable command. Note that specifying a submet-

ric in the metric list does not enable its underlying metrics.

Unlike the VBoxManage metrics setup command, the VBoxManage metrics enable com-

mand does not discard previously collected samples for the specified set of objects and metrics.

Note that the VBoxManage metrics enable command requires that you specify metrics as pa-

rameters. The metrics must include only the resource category and metric part, such as CPU/Load

and RAM/Usage.

--list

Shows whether the command succeeded as expected.

List Metric Values

VBoxManage metrics list [_* | host | vmname [metric-list] ]

The VBoxManage metrics list command shows the metrics that are currently available.

Note that VM-specific metrics are shown only when that VM is running.

304

9 VBoxManage

List Saved Metric Data

VBoxManage metrics query [_* | host | vmname [metric-list] ]

The VBoxManage metrics query command retrieves and shows the saved metric data.

Note that the VBoxManage metrics query command does not remove or flush saved data

but older samples are replaced by newer samples over time.

Configure Metric-Gathering Properties

VBoxManage metrics setup [--list] [--period seconds] [--samples count] [_*

| host | vmname [metric-list] ]

The VBoxManage metrics setup command configures metric-gathering properties.

Note that this command discards any previously collected samples for the specified set of

objects and metrics. To enable or disable metrics collection without discarding the data, use

the VBoxManage metrics enable command or the VBoxManage metrics disable command,

respectively.

--list

Shows which metrics have been modified as a result of the command execution.

--period=<seconds>

Specifies the number of seconds to wait between collecting metric data samples. The de-

fault value is 1.

--samples=<count>

Specifies the number of metric data samples to save. To view the saved data, use the

VBoxManage metrics query command. The default value is 1.

Examples

The following example command enables the collection of host processor and memory usage

metrics every second. The --samples option saves the five latest samples.

$ VBoxManage metrics setup --period 1 --samples 5 host CPU/Load,RAM/Usage

The following command lists the metrics that are available to the host system and VMs:

$ VBoxManage metrics list

Note that the host system and VMs have different sets of metrics.

The following example shows how to query metric data about the CPU time spent in user and

kernel modes for the test VM:

$ VBoxManage metrics query test CPU/Load/User,CPU/Load/Kernel

9.47 VBoxManage natnetwork

Create, modify, and manage a NAT network.

305

9 VBoxManage

Synopsis

VBoxManage natnetwork add [--disable | --enable] <--netname=name>

<--network=network> [--dhcp=on|off] [--ipv6=on|off] [--loopback-4=rule]

[--loopback-6=rule] [--port-forward-4=rule] [--port-forward-6=rule]

VBoxManage natnetwork list [filter-pattern]

VBoxManage natnetwork modify [--dhcp=on|off] [--disable | --enable]

<--netname=name> <--network=network> [--ipv6=on|off]

[--loopback-4=rule] [--loopback-6=rule] [--port-forward-4=rule]

[--port-forward-6=rule]

VBoxManage natnetwork remove <--netname=name>

VBoxManage natnetwork start <--netname=name>

VBoxManage natnetwork stop <--netname=name>

Description

The VBoxManage natnetwork command enables you to create, modify and manage a NAT net-

work.

NAT networks use the Network Address Translation (NAT) service. The service groups systems

into a network and prevents external systems from directly accessing the systems in the network.

The service also enables the systems in the network to communicate with each other and with

external systems by means of TCP and UDP over IPv4 and IPv6.

A NAT service is attached to an internal network. For a VM to use the NAT service, you must

attach the VM to the internal network. Specify the name of the internal network when you create

the NAT service. Note that the internal network is created if it does not already exist.

Add a NAT Network Service

VBoxManage natnetwork add [--disable | --enable] <--netname=name>

<--network=network> [--dhcp=on|off] [--ipv6=on|off] [--loopback-4=rule]

[--loopback-6=rule] [--port-forward-4=rule] [--port-forward-6=rule]

The VBoxManage natnetwork add command creates a new internal network interface, and

adds a NAT network service. You must use this command before you can attach the VM to the

NAT network.

--disable

Disables the NAT network service.

--enable

Enables the NAT network service.

--netname=<name>

Specifies the name of the new internal network interface on the host OS.

--network

Specifies the static or DHCP network address and mask of the NAT service interface. By

default, this value specifies the static network address.

--dhcp

Enables or disables the DHCP server that you specify by using the --netname option.

306

9 VBoxManage

--ipv6

Enables or disables IPv6. By default, IPv6 is disabled and IPv4 is enabled.

--loopback-4=<rule>

Enables an IPv4 loopback interface by using the specified rule.

--loopback-6=<rule>

Enables an IPv6 loopback interface by using the specified rule.

--port-forward-4=<rule>

Enables IPv4 port forwarding by using the rule specified by rule.

--port-forward-6=<rule>

Enables IPv6 port forwarding by using the rule specified by rule.

Remove a NAT Network Service

VBoxManage natnetwork remove <--netname=name>

The VBoxManage natnetwork remove command removes the specified NAT network service.

--netname=<name>

Specifies the name of the NAT network service to remove.

Start a NAT Network Service

VBoxManage natnetwork start <--netname=name>

The VBoxManage natnetwork start command starts a NAT network service and any associ-

ated DHCP server.

--netname=<name>

Specifies the name of the NAT network service to start.

Stop a NAT Network Service

VBoxManage natnetwork stop <--netname=name>

The VBoxManage natnetwork stop command stops a NAT network service and any associ-

ated DHCP server.

--netname=<name>

Specifies the name of the NAT network service to stop.

List All NAT Network Services

VBoxManage natnetwork list [filter-pattern]

The VBoxManage natnetwork list command lists all NAT network services. You can use a

pattern to show a subset of the NAT network services.

filter-pattern

Specifies an optional filtering pattern.

307

9 VBoxManage

Modify the Settings of a NAT Network Service

VBoxManage natnetwork modify [--dhcp=on|off] [--disable | --enable]

<--netname=name> <--network=network> [--ipv6=on|off]

[--loopback-4=rule] [--loopback-6=rule] [--port-forward-4=rule]

[--port-forward-6=rule]

The VBoxManage natnetwork modify command modifies the settings of an existing internal

network interface.

--disable

Disables the NAT network service.

--enable

Enables the NAT network service.

--netname=<name>

Specifies the name of the new internal network interface on the host OS.

--network

Specifies the static or DHCP network address and mask of the NAT service interface. By

default, this value specifies the static network address.

--dhcp

Enables or disables the DHCP server that you specify by using the --netname option.

--ipv6

Enables or disables IPv6. By default, IPv6 is disabled and IPv4 is enabled.

--loopback-4=<rule>

Enables an IPv4 loopback interface by using the specified rule.

--loopback-6=<rule>

Enables an IPv6 loopback interface by using the specified rule.

--port-forward-4=<rule>

Enables IPv4 port forwarding by using the rule specified by rule.

--port-forward-6=<rule>

Enables IPv6 port forwarding by using the rule specified by rule.

Examples

The following command shows how to create a NAT network for the natnet1 internal network

that uses the 192.168.15.0/24 network address and mask of the NAT service interface. In this

static configuration, the gateway is assigned the 192.168.15.1 IP address by default. Note that

this IP address is the next address after the network address that you specify with the --network

option.

$ VBoxManage natnetwork add --netname natnet1 --network "192.168.15.0/24" --enable

The following command shows how to add a DHCP server to the natnet1 NAT network after

creation:

$ VBoxManage natnetwork modify --netname natnet1 --dhcp on

308

9 VBoxManage

9.48 VBoxManage hostonlyif

Manage host-only network interfaces.

Synopsis

VBoxManage hostonlyif ipconfig <ifname> [--dhcp | --ip=IPv4-address

[--netmask=IPv4-netmask]

| --ipv6=IPv6-address

[--netmasklengthv6=length] ]

VBoxManage hostonlyif create

VBoxManage hostonlyif remove <ifname>

Description

The VBoxManage hostonlyif command enables you to change the IP configuration of a host-

only network interface. For a description of host-only networking, see chapter 7.7, Host-Only

Networking, page 136. Each host-only network interface is identified by a name and can either

use the internal DHCP server or a manual IP configuration, both IPv4 and IPv6.

Configure a Host-Only Interface

VBoxManage hostonlyif ipconfig <ifname> [--dhcp | --ip=IPv4-address

[--netmask=IPv4-netmask]

| --ipv6=IPv6-address

[--netmasklengthv6=length] ]

The VBoxManage hostonlyif ipconfig command configures a host-only interface.

ifname

Specifies the name of the network interface. The name is of the form vboxnetN where N is

the interface instance.

--dhcp

Uses DHCP for the network interface.

You cannot use this option with the --ip, --ipv6, --netmask, and --netmasklengthv6

options.

--ip=<IPv4-address>

Specifies the IPv4 IP address for the network interface.

You cannot use this option with the --dhcp, --ipv6, and --netmasklengthv6 options.

--netmask=<IPv4-netmask>

Specifies the IPv4 netmask of the network interface. The default value is 255.255.255.0.

You can use this option only with the --ip option.

--ipv6=<IPv6-address>

Specifies the IPv6 IP address for the network interface.

You cannot use this option with the --dhcp, --ip, and --netmask options.

--netmasklengthv6=<length>

Specifies the length of the IPv6 network interface. The default value is 64.

You can use this option only with the --ipv6 option.

309

9 VBoxManage

Create a Network Interface on the Host System

VBoxManage hostonlyif create

The VBoxManage hostonlyif create command creates a new host-only network interface

on the host operating system (OS). The network interface name is of the form vboxnetN where

N is the interface instance. You must run this command before you can attach virtual machines

(VMs) to the host-only network.

Remove a Network Interface From the Host System

VBoxManage hostonlyif remove <ifname>

The VBoxManage hostonlyif remove command removes the specified host-only network in-

terface from the host OS.

ifname

Specifies the name of the network interface. The name is of the form vboxnetN where N is

the interface instance.

Examples

The following command creates a new host-only network interface.

$ VBoxManage hostonlyif create

0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

Interface ’vboxnet2’ was successfully created

The following command configures the IPv4 address for the vboxnet2 host-only network in-

terface.

$ VBoxManage hostonlyif ipconfig vboxnet2 --ip 10.0.2.18

9.49 VBoxManage hostonlynet

Host Only Network management.

Synopsis

VBoxManage hostonlynet add <--name=netname> [--id=netid] <--netmask=mask>

<--lower-ip=address> <--upper-ip=address> [--enable | --disable]

VBoxManage hostonlynet modify <--name=netname | --id=netid>

[--lower-ip=address] [--upper-ip=address] [--netmask=mask] [--enable

| --disable]

VBoxManage hostonlynet remove <--name=netname | --id=netid>

Description

The hostonlynet commands enable you to control host-only networks.

310

9 VBoxManage

Common options

The subcommands of hostonlynet all operate on an host-only network that can be identified

via its name or uuid:

-name=netname

The host-only network name. You see it as VBoxNetworkName in the output from

VBoxManage list hostonlynets.

-id=netid

The host-only network uuid. If not specified when adding a new network, one will be

generated automatically.

hostonlynet add

VBoxManage hostonlynet add <--name=netname> [--id=netid] <--netmask=mask>

<--lower-ip=address> <--upper-ip=address> [--enable | --disable]

Adds a new host-only network.

Options configuring the host-only network:

--netmask=<mask>

The network mask. Typically 255.255.255.0.

--lower-ip=<address>, --upper-ip=<address>

The IP address range for handing out via DHCP. The upper boundrary is inclusive while

the lower one is not, so the upper address will be handed out to a client, while the lower

address will be used by the host itself.

--enable, -disable

Whether to enable the host-only network or disable it. If not specified, the network will be

created in enabled state.

hostonlynet modify

VBoxManage hostonlynet modify <--name=netname | --id=netid>

[--lower-ip=address] [--upper-ip=address] [--netmask=mask] [--enable

| --disable]

This modifies an existing host-only network configuration. It takes the same options as the

add command.

hostonlynet remove

VBoxManage hostonlynet remove <--name=netname | --id=netid>

Removes the specified host-only network.

9.50 VBoxManage dhcpserver

DHCP server management.

311

9 VBoxManage

Synopsis

VBoxManage dhcpserver add <--network=netname | --interface=ifname>

<--server-ip=address> <--netmask=mask> <--lower-ip=address>

<--upper-ip=address> <--enable | --disable>

[[--global] | [--set-opt=dhcp-opt-no value. . . ] | [--set-opt-hex=dhcp-opt-no

hexstring. . . ] | [--force-opt=dhcp-opt-no. . . ]

| [--supress-opt=dhcp-opt-no. . . ] | [--min-lease-time=seconds]

| [--default-lease-time=seconds] | [--max-lease-time=seconds] . . . ]

[<--group=name> | [--set-opt=dhcp-opt-no value. . . ]

| [--set-opt-hex=dhcp-opt-no hexstring. . . ] | [--force-opt=dhcp-opt-no. . . ]

| [--supress-opt=dhcp-opt-no. . . ] | [--incl-mac=address. . . ]

| [--excl-mac=address. . . ] | [--incl-mac-wild=pattern. . . ]

| [--excl-mac-wild=pattern. . . ] | [--incl-vendor=string. . . ]

| [--excl-vendor=string. . . ] | [--incl-vendor-wild=pattern. . . ]

| [--excl-vendor-wild=pattern. . . ] | [--incl-user=string. . . ]

| [--excl-user=string. . . ] | [--incl-user-wild=pattern. . . ]

| [--excl-user-wild=pattern. . . ] | [--min-lease-time=seconds]

| [--default-lease-time=seconds] | [--max-lease-time=seconds] . . . ]

[<--vm=name|uuid> | [--nic=1-N] | [--set-opt=dhcp-opt-no value. . . ]

| [--set-opt-hex=dhcp-opt-no hexstring. . . ] | [--force-opt=dhcp-opt-no. . . ]

| [--supress-opt=dhcp-opt-no. . . ] | [--min-lease-time=seconds]

| [--default-lease-time=seconds] | [--max-lease-time=seconds]

| [--fixed-address=address] . . . ]

[<--mac-address=address> | [--set-opt=dhcp-opt-no value. . . ]

| [--set-opt-hex=dhcp-opt-no hexstring. . . ] | [--force-opt=dhcp-opt-no. . . ]

| [--supress-opt=dhcp-opt-no. . . ] | [--min-lease-time=seconds]

| [--default-lease-time=seconds] | [--max-lease-time=seconds]

| [--fixed-address=address] . . . ]

VBoxManage dhcpserver modify <--network=netname | --interface=ifname>

[--server-ip=address] [--lower-ip=address] [--upper-ip=address]

[--netmask=mask] [--enable | --disable]

[[--global] | [--del-opt=dhcp-opt-no. . . ] | [--set-opt=dhcp-opt-no value. . . ]

| [--set-opt-hex=dhcp-opt-no hexstring. . . ] | [--force-opt=dhcp-opt-no. . . ]

| [--unforce-opt=dhcp-opt-no. . . ] | [--supress-opt=dhcp-opt-no. . . ]

| [--unsupress-opt=dhcp-opt-no. . . ] | [--min-lease-time=seconds]

| [--default-lease-time=seconds] | [--max-lease-time=seconds]

| [--remove-config] . . . ]

[<--group=name> | [--set-opt=dhcp-opt-no value. . . ]

| [--set-opt-hex=dhcp-opt-no hexstring. . . ] | [--force-opt=dhcp-opt-no. . . ]

| [--unforce-opt=dhcp-opt-no. . . ] | [--supress-opt=dhcp-opt-no. . . ]

| [--unsupress-opt=dhcp-opt-no. . . ] | [--del-mac=address. . . ]

| [--incl-mac=address. . . ] | [--excl-mac=address. . . ]

| [--del-mac-wild=pattern. . . ] | [--incl-mac-wild=pattern. . . ]

| [--excl-mac-wild=pattern. . . ] | [--del-vendor=string. . . ]

| [--incl-vendor=string. . . ] | [--excl-vendor=string. . . ]

| [--del-vendor-wild=pattern. . . ] | [--incl-vendor-wild=pattern. . . ]

| [--excl-vendor-wild=pattern. . . ] | [--del-user=string. . . ]

| [--incl-user=string. . . ] | [--excl-user=string. . . ]

| [--del-user-wild=pattern. . . ] | [--incl-user-wild=pattern. . . ]

| [--excl-user-wild=pattern. . . ] | [--zap-conditions]

| [--min-lease-time=seconds] | [--default-lease-time=seconds]

| [--max-lease-time=seconds] | [--remove-config] . . . ]

312

9 VBoxManage

[<--vm=name|uuid> | [--nic=1-N] | [--del-opt=dhcp-opt-no. . . ]

| [--set-opt=dhcp-opt-no value. . . ] | [--set-opt-hex=dhcp-opt-no

hexstring. . . ] | [--force-opt=dhcp-opt-no. . . ]

| [--unforce-opt=dhcp-opt-no. . . ] | [--supress-opt=dhcp-opt-no. . . ]

| [--unsupress-opt=dhcp-opt-no. . . ] | [--min-lease-time=seconds]

| [--default-lease-time=seconds] | [--max-lease-time=seconds]

| [--fixed-address=address] | [--remove-config] . . . ]

[<--mac-address=address> | [--del-opt=dhcp-opt-no. . . ]

| [--set-opt=dhcp-opt-no value. . . ] | [--set-opt-hex=dhcp-opt-no

hexstring. . . ] | [--force-opt=dhcp-opt-no. . . ]

| [--unforce-opt=dhcp-opt-no. . . ] | [--supress-opt=dhcp-opt-no. . . ]

| [--unsupress-opt=dhcp-opt-no. . . ] | [--min-lease-time=seconds]

| [--default-lease-time=seconds] | [--max-lease-time=seconds]

| [--fixed-address=address] | [--remove-config] . . . ]

VBoxManage dhcpserver remove <--network=netname | --interface=ifname>

VBoxManage dhcpserver start <--network=netname | --interface=ifname>

VBoxManage dhcpserver restart <--network=netname | --interface=ifname>

VBoxManage dhcpserver stop <--network=netname | --interface=ifname>

VBoxManage dhcpserver findlease <--network=netname | --interface=ifname>

<--mac-address=mac>

Description

The dhcpserver commands enable you to control the DHCP server that is built into VirtualBox.

You may find this useful when using internal or host-only networking. Theoretically, you can

also enable it for a bridged network, but that may cause conflicts with other DHCP servers in

your physical network.

Common options

The subcommands of dhcpserver all operate on an internal network that can be identified via

its name or in the host-only case via the host-only interface name:

-network=netname

The internal network name. This is the same as you would use as value to the

VBoxManage modifyvm --intnet option when configuring a VM for internal network-

ing. Or you see as VBoxNetworkName in the output from VBoxManage list intnets,

VBoxManage list natnets, or VBoxManage list hostonlyifs.

-interface=ifname

The host only interface name.

This would be same value as you would use for

the VBoxManage modifyvm --host-only-adapter option when configuring a VM to

use a host-only network.

The value can also be found in the Name row in

VBoxManage list hostonlyifs.

dhcpserver add

VBoxManage dhcpserver add <--network=netname | --interface=ifname>

<--server-ip=address> <--netmask=mask> <--lower-ip=address>

<--upper-ip=address> <--enable | --disable>

313