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::detectedOSVersionIUnattended::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.

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:

Call IVirtualBox::createUnattendedInstaller to create the object
Set IUnattended::isoPath and call IUnattended::detectIsoOS
Create, configure and register a machine according to IUnattended::detectedOSTypeId and the other detectedOS* attributes.
Set IUnattended::machine to the new IMachine instance.
Set the other IUnattended attributes as desired.
Call IUnattended::prepare for the object to check the attribute values and create an internal installer instance.
Call IUnattended::constructMedia to create additional media files (ISO/floppy) needed.
Call IUnattended::reconfigureVM to reconfigure the VM with the installation ISO, additional media files and whatnot
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:: {A71E5822-365B-49BA-BD14-C8D616E6740D}

Member Function Documentation

◆ detectIsoOS()

void IUnattended::detectIsoOS ( )

Detects the OS on the ISO given by IUnattended::isoPath and sets IUnattended::detectedOSTypeId, IUnattended::detectedOSVersionIUnattended::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 additions shipped with the linux distribution, only the installation of additions pointed to by IUnattended::additionsIsoPath.

◆ 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 gets generated depends on the OS being installed. When installing Windows there is currently only a auxiliaryBasePath + "floppy.img" being created. But for linux, a "cdrom.viso" and one or more configuration files are generate 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).

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ detectIsoOS()

◆ prepare()

◆ constructMedia()

◆ reconfigureVM()

◆ done()

Member Data Documentation

◆ isoPath

◆ machine

◆ user

◆ userPassword

◆ adminPassword

◆ fullUserName

◆ productKey

◆ additionsIsoPath

◆ installGuestAdditions

◆ validationKitIsoPath

◆ installTestExecService

◆ userPayloadIsoPath

◆ installUserPayload

◆ timeZone

◆ keyboardLayout

◆ keyboardVariant

◆ locale

◆ language

◆ country

◆ proxy

◆ packageSelectionAdjustments

◆ hostname

◆ auxiliaryBasePath

◆ imageIndex

◆ scriptTemplatePath

◆ postInstallScriptTemplatePath

◆ postInstallCommand

◆ extraInstallKernelParameters

◆ detectedOSTypeId

◆ detectedOSVersion

◆ detectedOSFlavor

◆ detectedOSLanguages

◆ detectedOSHints

◆ detectedImageNames

◆ detectedImageIndices

◆ isUnattendedInstallSupported

◆ avoidUpdatesOverNetwork