VirtualBox Main API

Public Member Functions | Public Attributes | List of all members
IUnattended Interface Reference

The IUnattended interface represents the pipeline for preparing the Guest OS for fully automated install. More...

Inheritance diagram for IUnattended:

## Public Member Functions
void | detectIsoOS ()
| Detects the OS on the ISO given by IUnattended::isoPath and sets IUnattended::detectedOSTypeId, IUnattended::detectedOSVersion IUnattended::detectedOSFlavor, IUnattended::detectedOSLanguages, IUnattended::detectedOSHints, IUnattended::detectedImageNames, and IUnattended::detectedImageIndices,.
void | prepare ()
| Prepare for running the unattended process of installation.
void | constructMedia ()
| Constructors the necessary ISO/VISO/Floppy images, with unattended scripts and all necessary bits on them.
void | reconfigureVM ()
| Reconfigures the machine to start the installation.
void | done ()
| Done - time to start the VM.

## Public Attributes
attribute wstring | isoPath
| Guest operating system ISO image.
attribute IMachine | machine
| The associated machine object.
attribute wstring | user
| Assigns an user login name.
attribute wstring | userPassword
| Assigns a password to the user.
attribute wstring | adminPassword
| Assigns a password to the Administrator / 'root' accounts.
attribute wstring | fullUserName
| The full name of the user.
attribute wstring | productKey
| Any key which is used as authorization of access to install genuine OS.
attribute wstring | additionsIsoPath
| Guest Additions ISO image path.
attribute boolean | installGuestAdditions
| Indicates whether the Guest Additions should be installed or not.
readonly attribute boolean | productKeyRequired
| Indicates whether the product key is required for the installation.
attribute wstring | validationKitIsoPath
| VirtualBox ValidationKit ISO image path.
attribute boolean | installTestExecService
| Indicates whether the test execution service (TXS) from the VBox ValidationKit should be installed.
attribute wstring | userPayloadIsoPath
| User Payload ISO image path.
attribute boolean | installUserPayload
| Indicates whether the User Payload should be installed or not.
attribute wstring | timeZone
| The guest time zone specifier.
attribute wstring | keyboardLayout
| Sets the keyboard layout of the guest, if available.
attribute wstring | keyboardVariant
| Sets the keyboard variant of the guest, if available.
attribute wstring | locale
| The 5 letter locale identifier, no codesets or such.
attribute wstring | language
| This is more or less a Windows specific setting for choosing the UI language setting of the installer.
attribute wstring | country
| The 2 upper case letter country identifier, ISO 3166-1 alpha-2.
attribute wstring | proxy
| Proxy incantation to pass on to the guest OS installer.
attribute wstring | packageSelectionAdjustments
| Guest OS specific package selection adjustments.
attribute wstring | hostname
| The fully qualified guest hostname.
attribute wstring | auxiliaryBasePath
| The path + basename for auxiliary files generated by the unattended installation.
attribute unsigned long | imageIndex
| The image index on installation CD/DVD used to install.
attribute wstring | scriptTemplatePath
| The unattended installation script template file.
attribute wstring | postInstallScriptTemplatePath
| The post installation (shell/batch) script template file.
attribute wstring | postInstallCommand
| Custom post installation command.
attribute wstring | extraInstallKernelParameters
| Extra kernel arguments passed to the install kernel of some guests.
readonly attribute wstring | detectedOSTypeId
| The detected OS type ID (IGuestOSType::id).
readonly attribute wstring | detectedOSVersion
| The detected OS version string.
readonly attribute wstring | detectedOSFlavor
| The detected OS flavor (e.g.
readonly attribute wstring | detectedOSLanguages
| The space separated list of (Windows) installation UI languages we detected (lang.ini).
readonly attribute wstring | detectedOSHints
| Space separated list of other stuff detected about the OS and the installation ISO.
readonly attribute wstring[] | detectedImageNames
| A list of names of the images detected from install.wim file of a Windows Vista or later ISO.
readonly attribute unsigned long[] | detectedImageIndices
| A list of image indexes detected from install.wim file of a Windows ISO.
readonly attribute boolean | isUnattendedInstallSupported
| Checks the detected OS type and version against a set of rules and returns whether unattended install is supported or not.
attribute boolean | avoidUpdatesOverNetwork
| When set to true installation is configured to abstain from using network to update/get data.

## Detailed Description

The IUnattended interface represents the pipeline for preparing the Guest OS for fully automated install.

The typical workflow is:

1. Call IVirtualBox::createUnattendedInstaller to create the object
2. Set IUnattended::isoPath and call IUnattended::detectIsoOS
3. Create, configure and register a machine according to IUnattended::detectedOSTypeId and the other detectedOS* attributes.
4. Set IUnattended::machine to the new IMachine instance.
5. Set the other IUnattended attributes as desired.
6. Call IUnattended::prepare for the object to check the attribute values and create an internal installer instance.
7. Call IUnattended::constructMedia to create additional media files (ISO/floppy) needed.
8. Call IUnattended::reconfigureVM to reconfigure the VM with the installation ISO, additional media files and whatnot
9. Optionally call IUnattended::done to destroy the internal installer and allow restarting from the second step.

Note! Step two is currently not implemented.

Interface ID:
  `{39D1F56C-C1C2-40DF-84E9-468062D84768}`

## Member Function Documentation

## ◆ detectIsoOS()

void IUnattended::detectIsoOS | ( |  | ) |

Detects the OS on the ISO given by IUnattended::isoPath and sets IUnattended::detectedOSTypeId, IUnattended::detectedOSVersion IUnattended::detectedOSFlavor, IUnattended::detectedOSLanguages, IUnattended::detectedOSHints, IUnattended::detectedImageNames, and IUnattended::detectedImageIndices,.

Not really yet implemented.

## ◆ prepare()

void IUnattended::prepare | ( |  | ) |

Prepare for running the unattended process of installation.

This will perform IUnattended::detectIsoOS if not yet called on the current IUnattended::isoPath value. It may then may cause IUnattended::detectedOSTypeId, IUnattended::detectedOSVersion, IUnattended::detectedOSFlavor, IUnattended::detectedOSLanguages, and IUnattended::detectedOSHints to be updated with values specific to the image selected by IUnattended::imageIndex if the ISO contains images.

This method will then instantiate the installer based on the detected guest type (see IUnattended::detectedOSTypeId).

## ◆ constructMedia()

void IUnattended::constructMedia | ( |  | ) |

Constructors the necessary ISO/VISO/Floppy images, with unattended scripts and all necessary bits on them.

## ◆ reconfigureVM()

void IUnattended::reconfigureVM | ( |  | ) |

Reconfigures the machine to start the installation.

This involves mounting the ISOs and floppy images created by IUnattended::constructMedia, attaching new DVD and floppy drives as necessary, and possibly modifying the boot order.

## ◆ done()

void IUnattended::done | ( |  | ) |

Done - time to start the VM.

This deletes the internal installer instance that IUnattended::prepare created. Before done() is called, it is not possible to start over again from IUnattended::prepare.

## Member Data Documentation

## ◆ isoPath

attribute wstring IUnattended::isoPath

Guest operating system ISO image.

## ◆ machine

attribute IMachine IUnattended::machine

The associated machine object.

This must be set before IUnattended::prepare is called. The VM must be registered.

## ◆ user

attribute wstring IUnattended::user

Assigns an user login name.

## ◆ userPassword

attribute wstring IUnattended::userPassword

Assigns a password to the user.

## ◆ adminPassword

attribute wstring IUnattended::adminPassword

Assigns a password to the Administrator / 'root' accounts.

If no Administrator / 'root' password is being set explicitly, the password set via IUnattended::userPassword will be used instead.

## ◆ fullUserName

attribute wstring IUnattended::fullUserName

The full name of the user.

This is optional and defaults to IUnattended::user. Please note that not all guests picks up this attribute.

## ◆ productKey

attribute wstring IUnattended::productKey

Any key which is used as authorization of access to install genuine OS.

## ◆ additionsIsoPath

attribute wstring IUnattended::additionsIsoPath

Guest Additions ISO image path.

This defaults to ISystemProperties::defaultAdditionsISO when the Unattended object is instantiated.

This property is ignored when IUnattended::installGuestAdditions is false.

## ◆ installGuestAdditions

attribute boolean IUnattended::installGuestAdditions

Indicates whether the Guest Additions should be installed or not.

Setting this to false does not affect guest additions shipped with Linux distributions, only the installation of additions pointed to by IUnattended::additionsIsoPath.

## ◆ productKeyRequired

readonly attribute boolean IUnattended::productKeyRequired

Indicates whether the product key is required for the installation.

## ◆ validationKitIsoPath

attribute wstring IUnattended::validationKitIsoPath

VirtualBox ValidationKit ISO image path.

This is used when IUnattended::installTestExecService is set to true.

## ◆ installTestExecService

attribute boolean IUnattended::installTestExecService

Indicates whether the test execution service (TXS) from the VBox ValidationKit should be installed.

The TXS binary will be taken from the ISO indicated by IUnattended::validationKitIsoPath.

## ◆ userPayloadIsoPath

attribute wstring IUnattended::userPayloadIsoPath

User Payload ISO image path.

This is used when IUnattended::installUserPayload is set to true.

## ◆ installUserPayload

attribute boolean IUnattended::installUserPayload

Indicates whether the User Payload should be installed or not.

The User Payload will be taken from the ISO indicated by IUnattended::userPayloadIsoPath.

## ◆ timeZone

attribute wstring IUnattended::timeZone

The guest time zone specifier.

This is unfortunately guest OS specific.

Windows XP and earlier takes the index number from this table: https://support.microsoft.com/en-gb/help/973627/microsoft-time-zone-index-values

Windows Vista and later takes the time zone string from this table: https://technet.microsoft.com/en-us/library/cc749073(v=ws.10).aspx

Linux usually takes the TZ string from this table: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

The default is currently UTC/GMT, but this may change to be same as the host later.

TODO: Investigate automatic mapping between linux and the two windows time zone formats. TODO: Take default from host (this requires mapping).

## ◆ keyboardLayout

attribute wstring IUnattended::keyboardLayout

Sets the keyboard layout of the guest, if available.

The 2 letter locale identifier, no codesets or such.

The format is two lower case country letter (ISO 3166-1 alpha-2). For instance 'us', 'de', or 'no'.

The default is taken from the host if possible, with 'us' as fallback.

Expected result codes:

  E_NOTIMPL | Not implemented yet.

## ◆ keyboardVariant

attribute wstring IUnattended::keyboardVariant

Sets the keyboard variant of the guest, if available.

Leave empty to use the default variant for the current keyboard layout set.

TODO: Define + document a keyboard variants table (e.g. by using 'localectl list-x11-keymap-variants [layout]' as a base), plus a mapping to Windows-based guests for that.

This depends on the current keyboard layout being set.

Expected result codes:

  E_NOTIMPL | Not implemented yet.

## ◆ locale

attribute wstring IUnattended::locale

The 5 letter locale identifier, no codesets or such.

The format is two lower case language letters (ISO 639-1), underscore ('_'), and two upper case country letters (ISO 3166-1 alpha-2). For instance 'en_US', 'de_DE', or 'ny_NO'.

The default is taken from the host if possible, with 'en_US' as fallback.

## ◆ language

attribute wstring IUnattended::language

This is more or less a Windows specific setting for choosing the UI language setting of the installer.

The value should be from the list available via IUnattended::detectedOSLanguages. The typical format is {language-code}-{COUNTRY} but windows may also use {16-bit code}:{32-bit code} or insert another component between the language and country codes. We consider the format guest OS specific.

Note that it is crucial that this is correctly specified for Windows installations. If an unsupported value is given the installer will ask for an installation language and wait for user input. Best to leave it to the default value.

The default is the first one from IUnattended::detectedOSLanguages.

## ◆ country

attribute wstring IUnattended::country

The 2 upper case letter country identifier, ISO 3166-1 alpha-2.

This is used for mirrors and such.

The default is taken from the host when possible, falling back on IUnattended::locale.

## ◆ proxy

attribute wstring IUnattended::proxy

Proxy incantation to pass on to the guest OS installer.

This is important to get right if the guest OS installer is of the type that goes online to fetch the packages (e.g. debian-*-netinst.iso) or to fetch updates during the install process.

Format: [schema=]schema://[login[:password]@]proxy[:port][;...]

The default is taken from the host proxy configuration (once implemented).

## ◆ packageSelectionAdjustments

attribute wstring IUnattended::packageSelectionAdjustments

Guest OS specific package selection adjustments.

This is a semicolon separated list of keywords, and later maybe guest OS package specifiers. Currently the 'minimal' is the only recognized value, and this only works with a selection of linux installers.

## ◆ hostname

attribute wstring IUnattended::hostname

The fully qualified guest hostname.

This defaults to machine-name + ".myguest.virtualbox.org", though it may change to the host domain name later.

## ◆ auxiliaryBasePath

attribute wstring IUnattended::auxiliaryBasePath

The path + basename for auxiliary files generated by the unattended installation.

This defaults to the VM folder + Unattended + VM UUID.

The files which get generated depend on the OS being installed. When installing Windows there is currently only an auxiliaryBasePath + "floppy.img" being created. But for Linux, a "cdrom.viso" and one or more configuration files are generated.

## ◆ imageIndex

attribute unsigned long IUnattended::imageIndex

The image index on installation CD/DVD used to install.

This index should be one of the indices of IUnattended::detectedImageIndices.

Changing this after ISO detection may cause IUnattended::detectedOSTypeId, IUnattended::detectedOSVersion, IUnattended::detectedOSFlavor, IUnattended::detectedOSLanguages, and IUnattended::detectedOSHints to be updated with values specific to the selected image.

Used only with Windows installation CD/DVD: https://technet.microsoft.com/en-us/library/cc766022%28v=ws.10%29.aspx

## ◆ scriptTemplatePath

attribute wstring IUnattended::scriptTemplatePath

The unattended installation script template file.

The template default is based on the guest OS type and is determined by the internal installer when when IUnattended::prepare is invoked. Most users will want the defaults.

After IUnattended::prepare is called, it can be read to see which file is being used.

## ◆ postInstallScriptTemplatePath

attribute wstring IUnattended::postInstallScriptTemplatePath

The post installation (shell/batch) script template file.

The template default is based on the guest OS type and is determined by the internal installer when when IUnattended::prepare is invoked. Most users will want the defaults.

After IUnattended::prepare is called, it can be read to see which file is being used.

## ◆ postInstallCommand

attribute wstring IUnattended::postInstallCommand

Custom post installation command.

Exactly what is expected as input here depends on the guest OS installer and the post installation script template (see IUnattended::postInstallScriptTemplatePath). Most users will not need to set this attribute.

## ◆ extraInstallKernelParameters

attribute wstring IUnattended::extraInstallKernelParameters

Extra kernel arguments passed to the install kernel of some guests.

This is currently only picked up by Linux guests. The exact parameters are specific to the guest OS being installed of course.

After IUnattended::prepare is called, it can be read to see which parameters are being used.

## ◆ detectedOSTypeId

readonly attribute wstring IUnattended::detectedOSTypeId

The detected OS type ID (IGuestOSType::id).

Set by IUnattended::detectIsoOS or IUnattended::prepare.

Not yet implemented.

## ◆ detectedOSVersion

readonly attribute wstring IUnattended::detectedOSVersion

The detected OS version string.

Set by IUnattended::detectIsoOS or IUnattended::prepare.

Not yet implemented.

## ◆ detectedOSFlavor

readonly attribute wstring IUnattended::detectedOSFlavor

The detected OS flavor (e.g.

server, desktop, etc)

Set by IUnattended::detectIsoOS or IUnattended::prepare.

Not yet implemented.

## ◆ detectedOSLanguages

readonly attribute wstring IUnattended::detectedOSLanguages

The space separated list of (Windows) installation UI languages we detected (lang.ini).

The language specifier format is specific to the guest OS. They are used to set IUnattended::language.

Set by IUnattended::detectIsoOS or IUnattended::prepare.

Partially implemented.

## ◆ detectedOSHints

readonly attribute wstring IUnattended::detectedOSHints

Space separated list of other stuff detected about the OS and the installation ISO.

Set by IUnattended::detectIsoOS or IUnattended::prepare.

Not yet implemented.

## ◆ detectedImageNames

readonly attribute wstring [] IUnattended::detectedImageNames

A list of names of the images detected from install.wim file of a Windows Vista or later ISO.

This array is parallel to IUnattended::detectedImageIndices. This will be empty for older Windows ISOs and non-Windows ISOs.

## ◆ detectedImageIndices

readonly attribute unsigned long [] IUnattended::detectedImageIndices

A list of image indexes detected from install.wim file of a Windows ISO.

This array is parallel to IUnattended::detectedImageNames. IUnattended::imageIndex should be set to one of these indices for Vista and later Windows ISOs.

## ◆ isUnattendedInstallSupported

readonly attribute boolean IUnattended::isUnattendedInstallSupported

Checks the detected OS type and version against a set of rules and returns whether unattended install is supported or not.

Note that failing detecting OS type from the ISO causes this attribute to be false by default.

## ◆ avoidUpdatesOverNetwork

attribute boolean IUnattended::avoidUpdatesOverNetwork

When set to true installation is configured to abstain from using network to update/get data.

Especially useful when network is not available (as in our test boxes).