ai_manifest - Automated installation manifest file format
/usr/share/install/ai.dtd.1
Automated Installer (AI) provides a customizable, hands-free installation mechanism for Oracle Solaris and uses an XML-based file format as the description of the installation parameters. This installation parameters file is called an AI manifest. The installation can be customized in various ways such as disk layout and the software to be installed on the system.
The AI manifest has the following sections:
Automated installation settings. Specifies settings used during the installation.
Disk layout. Specifies the disk layout for the installation.
Software. Specifies the software packages to be installed.
Boot configuration (x86 only). Specifies how to configure the GRUB boot menu.
Other configuration. Specifies other configuration components to be installed onto the system.
These sections are described in more detail below.
To create a new AI manifest, use a copy of the template or default manifest from the relevant install service image. For example, if the install service image is located at imagepath, the following files are available:
The original default AI manifest for this install service.
An annotated, sample AI manifest with example customizations.
You can use the installadm export command to retrieve a copy of any manifest that already exists in an install service.
AI manifests are also used for installing non-global zones using the zoneadm install command. An AI manifest file can be passed to this command to customize the zone installation. Only a subset of AI manifest specifications applies to installing non-global zones. These specifications are noted in the sections below.
Complementing the AI manifest are Service Management Facility (SMF) configuration profiles. These profiles specify the system configuration for the installed system such as hostname, networking, and root and initial user account settings.
For more information about install services, AI manifests, and configuration profiles, see the installadm(1M) man page and Part 3, Installing Using an Install Server, in Installing Oracle Solaris 11.3 Systems. For information about the configuration profile file format, see smf(5).
The ai_instance element has the following attributes:
The name of this manifest instance.
The HTTP proxy to use to access remote files during the installation. Examples of remote files accessed during installation are software packages in an Image Packaging System (IPS) package repository. The value of http_proxy is an HTTP URI such as http://myproxy.mycompany.com:8080/.
This attribute is not applicable when installing a non-global zone and is ignored if provided.
The flag that specifies whether to automatically reboot after installation. The default value of auto_reboot is false. When auto_reboot is false, the installation waits for manual intervention to reboot.
When auto_reboot is true, on a successful installation, the machine automatically reboots into the newly installed boot environment.
This attribute is not applicable when installing a non-global zone and is ignored if provided.
The following example demonstrates how to use the ai_instance element:
<auto_install>
<ai_instance name='default' auto_reboot='true'
http_proxy='http://myproxy.mycompany.com:8080/'>
<!-- target and software sections -->
</ai_instance>
</auto_install>
AI enables a range of disk specification, varying from completely automatic selection of the installation target to fine-grained control of the disk layout.
The target element specifies the disk layout. The default disk layout when no target element is specified has the following characteristics:
The whole of one disk is used to install the Oracle Solaris OS. This disk is usually the boot disk or first disk.
For x86 and SPARC with GPT aware firmware, a GPT partition is allocated that consumes the full disk contents. See the –B option of the zpool create command in the zpool(1M) man page.
For SPARC systems that are not capable of using GPT, a single slice 0 that is the full size of the disk is created.
A single root pool is created that uses either the complete slice 0 or the complete GPT partition.
A swap volume and a dump volume are created in the root pool if space is available.
The target element has the following structure:
<!-- zero or one target element -->
<target>
<!-- zero or more disk elements -->
<disk ...>
<!-- One of the following elements:
disk_name
disk_prop
disk_keyword
iscsi
Zero or more of the following elements:
gpt_partition
partition
slice
gpt_partition can have zero or one size element.
partition can have zero or one size element
followed by zero or more slice elements.
slice can have zero or one size element.
-->
</disk>
<!-- zero or one logical element -->
<logical ...>
<!-- zero or more zpool elements -->
<zpool ...>
<!-- zero or more vdev elements -->
<vdev ...>
</vdev>
<!-- zero or more filesystem elements
with zero or one options element
-->
<filesystem>
<options>
<option .../>
</options>
<!-- zero or more zvol elements
with zero or one options element
and one size element
-->
<zvol ...>
<options>
<option .../>
</options>
<size val="..."/>
</zvol>
<!-- zero or one pool_options element
with one or more option elements
-->
<pool_options>
<option .../>
</pool_options>
<!-- zero or one dataset_options element
with one or more option elements
-->
<dataset_options>
<option .../>
</dataset_options>
<!-- zero or one be element
with zero or one options elements
-->
<be>
<options>
<option .../>
</options>
</be>
</zpool>
</logical>
</target>
Child elements of the target element enable you to specify disks and logical layout.
Disk specifications are not applicable when installing a non-global zone and are ignored if provided.
Some disk layout elements have a size sub-element. The size element has the following format:
<size val="size" start_sector=" start_sector"/>
The start_sector value is a numeric value that specifies the desired start sector for the new partition or slice. If the start_sector attribute is omitted, the installer searches for the first location large enough to contain the specified size.
Values for size are numeric with one of the following suffixes:
s or sec: sectors
b: bytes
k or kb: kilobytes (210)
m or mb: megabytes (220)
g or gb: gigabytes (230)
t or tb: terabytes (240)
p or pb: petabytes (250)
e or eb: exabytes (260)
z or zb: zettabytes (270)
The remainder of this section describes the disk and logical elements in detail.
If you do not specify a location for installing the Oracle Solaris OS on a client, AI selects a default location for that client.
The default location for the installation is the first disk found on each client that meets the size requirement. If the size of a disk is greater than or equal to the required size, the installer selects that disk as the installation location. If the size of the disk is less than the required size, the installer checks the next disk. If no disk is found that meets the size requirement, the automated installation fails for that client. The install log at /system/volatile/install_log shows the details of the disk selection process for that system.
The disk section of the target section specifies the installation location.
Disk specifications are not applicable when installing a non-global zone and are ignored if provided.
Disks can be selected using one of the following types of selection criteria:
Group 1: Deterministic criteria such as disk name or IP address. Use the <disk_name> sub-element as described in “Target Device Name” below or the <iscsi> sub-element as described in “ISCSI Target Device” below.
Group 2: Nondeterministic criteria such as disk size or vendor. Use the <disk_prop> sub-element as described in “Target Device Properties” below.
Group 3: Keyword criteria such as the boot_disk keyword. Use the <disk_keyword> sub-element as described in “Target Device Keyword” below.
You can specify criteria from only one of these three groups. If you use Group 2 selection criteria, you can specify multiple criteria. For example, you can specify both size and vendor. If you use Group 1 selection criteria, you can specify only one of those criteria.
Target Device NameUse the disk_name element to specify the target device name for a device that is not an iSCSI device. The disk_name element has the following attributes:
The name attribute specifies the name of the target device.
The name_type attribute specifies the type of the target device name. The name_type attribute can have one of the following values:
This is a CTD name such as c0t0d0 or c0t2000002037CD9F72d0. This type of name is commonly seen when running the format(1M) command.
<disk_name name="c0t0d0" name_type="ctd"/>
This is the default target device name type if the name_type attribute is omitted.
This is the volume identifier as can be set by the format(1M) command.
<disk_name name="MY_BOOT_DISK" name_type="volid"/>
This is the device path relative to the /devices directory.
<disk_name name="/pci@0,0/pci10de,375@f/pci108e,286@0/disk@0,0" name_type="devpath"/>
This is the device identifier as found in the “Device Id” in the output from the iostat(1M) command with the –iEn options.
<disk_name name="id1,sd@TSun_____STK_RAID_INT____F0F0F0" name_type="devid"/>
This is the receptacle value from a CRO (Chassis, Receptacle, Occupant) configuration as found in the output from the diskinfo(1M) command with the –ocR option.
<disk_name name="SYS/HDDO" name_type="receptacle"/>
Use the iscsi element to specify an iSCSI disk as the installation target. The iscsi element has the following attributes:
The source attribute specifies the source of the iSCSI configuration data. The source attribute can have the following values:
This value refers to this AI manifest. This is the default if no value is specified for the source attribute.
When the source attribute is omitted or the value of the source attribute is manifest, the target_lun and target_ip attributes must be specified.
This value refers to the use of DHCP where the iSCSI information is sourced by specifying the information in the DHCP rootpath parameter.
When the value of the source attribute is dhcp, do not specify any other iscsi attributes.
<iscsi source="dhcp"/>
The value of this attribute is the IP address of the iSCSI target. The target at this IP address must be online and accessible from this system. This attribute is required.
<iscsi target_lun="0" target_ip="192.168.1.34"/>
If an iSCSI target provides more than one LUN, specify which LUN to use by specifying an integer value for target_lun. LUN numbers are indexed from 0. To specify the first LUN, specify a target_lun value of 0.
If only one LUN is provided, this attribute can be omitted. If more than one LUN is provided by the iSCSI target, then this attribute is required.
The target_name attribute specifies the iSCSI Qualified Name (IQN) or the Extended Unique Identifier (EUI) of the iSCSI target, as shown in the following example:
iqn.1986-03.com.sun:02:a4a694bc-6de2-ee50-8979-e25ba29acb86
If not specified, the default target_port of 3260 (the iSCSI standard port) is used. This attribute enables you to specify an alternative port number.
The initiator_name attribute specifies the IQN or the EUI of the iSCSI initiator.
The following two attributes provide CHAP (Challenge-Handshake Authentication Protocol) authentication:
The chap_name attribute specifies the CHAP username to be used for authentication.
The chap_password attribute specifies the CHAP password to be used for authentication.
SPARC clients can optionally set chap-user and chap-password at the Open Boot PROM (ok) prompt. For more information, see “iSCSI Boot” in the boot(1M) man page.
The iscsi element does not have an action attribute. AI uses iSCSI devices but does not operate directly on them.
If the target_name attribute is not provided, AI uses iscsiadm(1M) in sendtargets mode.
If the target_name attribute is provided, AI uses static discovery.
Given this information, the iSCSI device is made available for installation.
Because the network interface for the iSCSI device is configured early in the client boot process, you do not need to configure the network/install service for this interface in any system configuration profile file for this installation.
Target Device PropertiesUse the disk_prop element to specify properties of the target device. Multiple properties can be specified. AI attempts to find a best match based on the criteria provided.
Use attributes of the disk_prop element to specify the target properties. The disk_prop element has the following attributes:
The type of the target disk. Possible values include SCSI, ATA, and USB. This value is not case sensitive.
The vendor as shown by the inquiry menu option of the format(1M) command.
<disk_prop dev_vendor="Sun"/>
The chassis value from a CRO (Chassis, Receptacle, Occupant) configuration as found in the output from the croinfo(1M) command with the –ocA option.
<disk_prop dev_chassis="SYS"/>
The minimum size for the disk. The value is a number with a size unit.
<disk_prop dev_size="100gb"/>
The disk_prop element allows specification of multiple attributes at the same time to further constrain the disk search. The following example limits the selection of a disk to a Hitachi drive with a size of at least 100 GB.
<disk_prop dev_vendor="HITACHI" dev_size="100gb"/>Target Device Keyword
The disk_keyword element can be used to specify the system's boot disk as the target disk.
<disk_keyword key="boot_disk"/>
The only value supported for the key attribute is boot_disk.
The simplest way to lay out a disk is to use the entire disk for installation by setting the whole_disk attribute to true.
For more complex disk layouts, you can specify partitions (for x86 systems only) and slices.
The disk element has the following attributes:
The default value of this attribute is false. When whole_disk is false, partitions or slices must be defined. Any existing partitions or slices are retained unless you remove them by specifying the delete value for the action attribute of the partition or slice.
When whole_disk is true, any existing partitions or slices are removed.
The following example specifies using the entire disk for installation:
<disk whole_disk="true"> <disk_name name="c0t0d0" name_type="ctd"/> </disk>
The in_zpool attribute links this disk to a ZFS pool defined in the logical section of the AI manifest. The value of the in_zpool attribute must match the value of the name attribute of the corresponding zpool element.
If the in_zpool attribute is specified here, then do not specify in_zpool for any subordinate partitions or slices.
The in_vdev attribute links this disk to a virtual device defined in the logical section of the AI manifest. The value of the in_vdev attribute must match the value of the name attribute of the corresponding vdev element.
If the in_vdev attribute is specified here, then do not specify in_vdev for any subordinate partitions or slices.
GUID Partition Table partitions are the preferred x86 and SPARC partitioning method. GPT partitions are usable directly by ZFS without requiring slices. The gpt_partition element has the following attributes:
The name attribute is the GPT partition number. Values 0-7 are valid for Oracle Solaris.
The name attribute is required.
The action attribute can have the following values:
This is the default action for a partition. The create action tells the installer to create a partition with the specified name. If a partition with the same name already exists, that existing partition is deleted first.
The delete action tells the installer to delete the named partition. If the named partition does not exist, the delete action is skipped and a warning message is output.
The preserve action tells the installer to leave the named partition untouched. This action is commonly used if another operating system is installed at another location on the same disk.
The part_type attribute specifies the GUID partition type. The value can be a supported GUID alias, such as solaris, or an explicit GUID hexadecimal string value.
The part_type attribute is required.
The in_zpool attribute links this partition to a ZFS pool defined in the logical section of the AI manifest. The value of the in_zpool attribute must match the value of the name attribute of the corresponding zpool element.
If the in_zpool attribute is specified, then do not specify in_zpool for the associated disk element or any subordinate slice elements.
The in_vdev attribute links this partition to a virtual device defined in the logical section of the AI manifest. The value of the in_vdev attribute must match the value of the name attribute of the corresponding vdev element.
If the in_vdev attribute is specified, then do not specify in_vdev for the associated disk element or any subordinate slice elements.
GPT partitions can have a size sub-element to specify the size of the partition. See the beginning of the “Disk Layout” section for details about how to use the size element. If you specify a size for the partition, the size sub-element must precede any slice sub-element in the partition element.
Legacy PartitionsLegacy fdisk partitions can only be specified when installing to an x86 system. If fdisk partitions are specified for a SPARC system, the installation fails. The partition element is used for fdisk partitions. The partition element has the following attributes:
The name attribute is the fdisk partition number. Values 1, 2, 3, and 4 are primary partitions. If one of the primary partitions is an extended partition, values 5 through 32 can be specified for logical partitions.
The name attribute is required unless the specified action is use_existing_solaris2.
The action attribute can have the following values:
This is the default action for a partition. The create action tells the installer to create a partition with the specified name. If a partition with the same name already exists, that existing partition is deleted first.
The delete action tells the installer to delete the named partition. If the named partition does not exist, the delete action is skipped and a warning message is output.
The preserve action tells the installer to leave the named partition untouched. This action is commonly used if another operating system is installed at another location on the same disk.
The use_existing_solaris2 action tells the installer to use an existing Solaris2 partition. The installer searches for the existing Solaris2 partition.
When use_existing_solaris2 is specified, the name and part_type attributes are ignored.
The part_type is the fdisk partition type. The default value is 191, which is the partition type for a Solaris2 partition. See the fdisk(1M) man page for more information about possible partition types.
The in_zpool attribute links this partition to a ZFS pool defined in the logical section of the AI manifest. The value of the in_zpool attribute must match the value of the name attribute of the corresponding zpool element.
If the in_zpool attribute is specified, then do not specify in_zpool for the associated disk element or any subordinate slice elements.
The in_vdev attribute links this partition to a virtual device defined in the logical section of the AI manifest. The value of the in_vdev attribute must match the value of the name attribute of the corresponding vdev element.
If the in_vdev attribute is specified, then do not specify in_vdev for the associated disk element or any subordinate slice elements.
Partitions can have a size sub-element to specify the size of the partition. See the beginning of the “Disk Layout” section for details about how to use the size element. If you specify a size for the partition, the size sub-element must precede any slice sub-element in the partition element.
The following example creates a 10 GB Solaris2 partition using default attribute values:
<disk>
<disk_name name="c0t0d0" name_type="ctd"/>
<partition name="1">
<size val="10gb"/>
</partition>
</disk>
If the size is not specified, the size of the parent element is used.
The preserve, delete, and use_existing_solaris2 actions do not need a size specification.
SlicesFor an x86 system, slices must be contained within a partition definition.
The slice element has the following attributes:
The name attribute is the slice number. The value can be 0 through 7.
The action attribute can have the following values:
This is the default action for a slice. The create action tells the installer to create a slice with the specified name. If a slice with the same name already exists, that existing slice is deleted first.
The delete action tells the installer to delete the named slice. If the named slice does not exist, the delete action is skipped and a warning message is output.
The preserve action tells the installer to leave the named slice untouched. This action is commonly used when data exists from a previous installation.
The use_existing action tells the installer to use an existing slice dimensions (starting sector and size). This differs from the preserve action in that this may be used as part of a zpool which would destroy any existing data on that slice.
As with the create action, it is necessary to specify the force option as true if the slice is part of an existing zpool.
The default value of this attribute is false. When is_swap is false, the installer creates a swap volume in the root pool.
When is_swap is true, the named slice is used as a swap device. When is_swap is true, do not use the in_zpool or in_vdev attributes.
The default value of this attribute is false.
When force is true, the installer ignores any existing slice that might already be in use (for example, a slice that is used in an existing ZFS storage pool) and continues to perform the specified action on the named slice.
The in_zpool attribute links this slice to a ZFS pool defined in the logical section of the AI manifest. The value of the in_zpool attribute must match the value of the name attribute of the corresponding zpool element.
If the in_zpool attribute is specified, then do not specify in_zpool for the associated partition or disk elements.
The in_vdev attribute links this slice to a virtual device defined in the logical section of the AI manifest. The value of the in_vdev attribute must match the value of the name attribute of the corresponding vdev element.
If the in_vdev attribute is specified, then do not specify in_vdev for the associated partition or disk elements.
Slices can have a size sub-element to specify the size of the slice. See the beginning of the “Disk Layout” section for details about how to use the size element. If the size is not specified, the size of the parent element is used.
The following example creates a 20 GB slice using default attribute values and a 4 GB swap slice for a SPARC system:
<disk>
<disk_name name="c0t0d0" name_type="ctd"/>
<slice name="0">
<size val="20gb"/>
</slice>
<slice name="1" is_swap="true">
<size val="4gb"/>
</slice>
</disk>
The following example is the same example for an x86 system:
<disk>
<disk_name name="c0t0d0" name_type="ctd"/>
<partition name="1">
<slice name="0">
<size val="20gb"/>
</slice>
<slice name="1" is_swap="true">
<size val="4gb"/>
</slice>
</partition>
</disk>
A swap slice can be explicitly defined by setting the is_swap attribute of the slice element to true, as shown in “Slices” above.
A volume in a pool can be explicitly defined as a swap volume or a dump volume by setting the use attribute of the zvol element to swap or dump, as shown in “ZFS Volumes” below.
By default, a swap volume and a dump volume are automatically created if space is available.
On low memory systems, a swap slice can be preferable to a swap volume since volumes incur a small memory overhead.
If you want to explicitly specify swap or dump and do not want swap or dump volumes automatically created, set the following attributes of the logical element to true:
The default value of this attribute is false. When noswap is false, if space allows, the installer automatically creates a swap volume in the root pool.
When noswap is true, no swap volume is automatically created.
The default value of this attribute is false. When nodump is false, if space allows, the installer automatically creates a dump volume in the root pool.
When nodump is true, no dump volume is automatically created.
Use the logical section of the target section to specify any number of ZFS storage pools.
Multiple pools can be defined by using the zpool sub-element of the logical element. Only one of these pools can be the root pool. The installation fails if multiple root pools are defined.
If a zpool element defines a root pool, and no target disks, partitions (GPT or fdisk), or slices are specified in the AI manifest, then the installer selects a target as described in “Installation Location” above. This selection is automatically assigned to the root pool.
If target disks, partitions (GPT or fdisk), or slices are specified in the AI manifest, then the zpool must be associated with at least one of these disks, partitions (GPT or fdisk), or slices. To make this association, use the in_zpool attribute of the disk element, the gpt_partition element, the partition element, or the slice element.
If the root pool is associated with a target device that is not bootable by firmware (such as an iSCSI disk over IPoIB), a separate boot pool is required. If a boot pool is not defined, then the installer will automatically define a boot pool. If the boot pool is not associated with any target disks, then the installer will check if the system has any dedicated boot pool devices and automatically select them for the boot pool, configuring them with a mirrored redundancy. If the system does not contain any dedicated boot pool devices, devices for the boot pool must be defined in the manifest.
The zpool element has the following attributes:
This is the name of the new pool. This value must be a name that can be passed to the zpool create command.
This name could be used as the value of an in_zpool attribute of a disk, gpt_partition, partition, or slice element to define that disk, GPT partition, fdisk partition, or slice as a constituent device in the zpool.
The action attribute can have the following values:
This is the default action for a zpool. The create action tells the installer to create a pool with the specified name.
The delete action tells the installer to delete the named pool.
The preserve action tells the installer to leave the named pool unmodified. This action can be specified only for a non-root pool.
The value of the action attribute must be preserve in the following cases:
The value of the action attribute of any subordinate filesystem is preserve.
The value of the action attribute of any subordinate zvol is preserve.
The value of the action attribute of any subordinate zvol is use_existing.
The use_existing action tells the installer to install to the existing root pool. Any existing volumes or file systems (datasets) are retained.
The default value of this attribute is false. When is_root is true, the root pool is created in the named pool and the new boot environment is created in this pool.
When is_root is false and is_boot is false, a data pool is defined.
The default value of this attribute is false. When is_boot is true, a boot pool is created in the named pool. Boot pools may not have any child sub-elements defined, and the mountpoint attribute is ignored as the boot pool is managed by the system and is not kept mounted.
When is_boot is false and is_root is false, a data pool is defined.
The mountpoint attribute specifies the mount point of the top level file system of the pool. The default mount point is /poolname. The mount point must be an absolute path.
To set ZFS properties on the new pool, use the pool_options element. Similarly, to set ZFS properties on the automatically created ZFS dataset, use the dataset_options element. Both the pool_options and dataset_options elements have an option sub-element. Each option element has a name attribute and a value attribute. The properties set with these name/value pairs are subject to the same restrictions that the zpool(1M) command enforces. The following example shows how to set these properties:
<logical>
<zpool name="rpool" is_root="true">
<pool_options>
<option name="listsnaps" value="on"/>
<option name="delegation" value="off"/>
</pool_options>
<dataset_options>
<option name="atime" value="on"/>
<option name="compression" value="on"/>
</dataset_options>
</zpool>
</logical>
Any number of virtual device redundancy groups (vdev element), ZFS datasets (filesystem element), or ZFS volumes (zvol element) can be defined for a pool. Boot environments (be element) can be specified for a pool. The following sections describe the vdev, filesystem, zvol, and be elements.
Virtual Device Redundancy GroupsUse the vdev element to define the size or structure of a zpool. You can specify multiple vdev elements, each with a different redundancy type.
If a zpool contains more than one vdev element, then you must use the in_vdev attribute on any disk, gpt_partition, partition, or slice elements that are defined with in_zpool attributes.
You can omit the in_zpool attribute on a disk, GPT partition, fdisk partition, or slice if the vdev name is unique throughout the AI manifest.
If a zpool contains only one vdev element, you can omit the in_vdev attribute on a disk, gpt_partition, partition, or slice.
The vdev element has the following attributes:
This is the name of the new vdev.
This name should be used as the value of an in_vdev attribute of a disk, gpt_partition, partition, or slice element to define that disk, partition (GPT or fdisk), or slice as a constituent device in the vdev
The redundancy attribute can have the following values:
This is the default value. When redundancy is mirror or is not specified, all devices contained are considered to be mirrors of each other.
Devices in a group with one of these values are used to define a RAIDZ grouping.
Devices in this group are seen as hot spares in case of failure.
Devices in this group provide caching for the pool.
Devices in this group are used for logging. If logmirror is specified, the devices are mirrors.
When redundancy is none, no redundancy is defined. If multiple devices are included in this group, these devices are striped.
A root pool can be defined as having only one of the following configurations:
A redundancy type of none with one device. Multiple devices are not supported in this configuration.
A redundancy type of mirror with multiple devices.
To add a device to a vdev, use the in_zpool and in_vdev attributes of a disk, gpt_partition, partition, or slice element. The following example specifies a root pool named rpool that is mirrored over two disks:
<disk whole_disk="true" in_zpool="rpool" in_vdev="mirrored">
<disk_name name="c0t0d0" name_type="ctd"/>
</disk>
<disk whole_disk="true" in_zpool="rpool" in_vdev="mirrored">
<disk_name name="c1t0d0" name_type="ctd"/>
</disk>
<logical>
<zpool name="rpool" is_root="true">
<vdev name="mirrored" redundancy="mirror"/>
</zpool>
</logical>
You can omit one of the in_zpool or in_vdev attributes if the pool or virtual device they refer to is unambiguous.
File Systems (Datasets)Use the filesystem element to define ZFS file systems or datasets within a ZFS pool.
The filesystem element has the following attributes:
This is the name of the new filesystem, relative to the zpool. For example, if the filesystem is named export within a zpool named rpool, the ZFS dataset name is rpool/export.
If the in_be attribute of the filesystem is set to true, this name is relative to the root dataset of the boot environment.
The action attribute can have the following values:
This is the default action for a filesystem. The create action tells the installer to create a file system with the specified name.
The delete action tells the installer to delete the named file system.
The preserve action tells the installer to leave the named file system unmodified. If preserve is specified for the filesystem, then preserve should be specified for the associated zpool.
The mountpoint attribute specifies the mount point of the new file system. If a mount point is not specified, the file system inherits the mount point from its parent.
The default value of this attribute is false. When in_be is false, the new dataset is shared among all boot environments.
When in_be is true, a separate copy of this new dataset is created within each boot environment. When in_be is true, the value of the name attribute is relative to the root dataset of the boot environment.
Use the options sub-element to set the ZFS dataset properties on a filesystem. Any editable ZFS file system property can be set. Use of the options element for a filesystem is similar to the use of the dataset_options element for a zpool, as shown in the following example:
<logical>
<zpool name="rpool" is_root="true">
<filesystem name="export">
<options>
<option name="compression" value="off"/>
<option name="dedup" value="on"/>
</options>
</filesystem>
</zpool>
</logical>
A child filesystem inherits any property set on a parent filesystem unless that property is explicitly set differently. This is the default behavior of ZFS file systems.
ZFS VolumesUse the zvol element to define ZFS volumes within a ZFS pool. A zvol is typically used for swap or dump devices, but it can have other uses.
The zvol element has the following attributes:
This is the name of the new ZFS volume.
The action attribute can have the following values:
This is the default action for a zvol. The create action tells the installer to create a ZFS volume with the specified name.
The delete action tells the installer to delete the named volume.
The preserve action tells the installer to leave the named zvol unmodified. If preserve is specified for the zvol, then preserve should be specified for the associated zpool.
If this value is specified for a swap or dump device, the existing volume is reused. If use_existing is specified for the zvol, then preserve should be specified for the associated zpool.
The use attribute can have the following values:
This is the default value. When use is none, the zvol is created but not used during the installation.
When use is swap, the zvol is created and used as a swap device. The zvol is also used as a swap device during the installation. The size sub-element of the zvol element can have the value max. When the max keyword is specified, the size of the volume will be 90% of the free space on the pool on which the volume is created. Only one volume on a pool can specify a size of max.
When use is dump, the zvol is created and used as a dump device. The zvol is also used as a dump device during the installation.
Use the size sub-element to specify the size of the volume. See the beginning of the “Disk Layout” section for details about how to use the size element. If you specify a size for the volume, the size sub-element must follow any options sub-element in the zvol element, as shown in the example below.
Use the options sub-element to set ZFS volume options on a zvol. Use of the options element for a zvol is similar to the use of the dataset_options element for a zpool, as shown in the following example:
<logical>
<zpool name="rpool" is_root="true">
<zvol name="swap">
<options>
<option name="compression" value="off"/>
<options>
<size val="8gb"/>
</zvol>
</zpool>
</logical>
Boot Environments
Use the be element to specify how the boot environment is created during the installation.
The be element has one attribute:
This is the name of the new boot environment that is created by the installer. If the be element is not specified, the default name for this boot environment is solaris.
The installer makes use of the auto-naming feature provided by the boot environment subsystem. When installing into an existing target area (for example, when installing a zone), a boot environment with the name specified by the be element name attribute might already exist. If the specified boot environment name already exists, this name is used as a base to generate a new name. For example, if be is not specified, and a boot environment named solaris already exists, the new boot environment is named solaris-n, where n is the first integer in counting order that forms a boot environment name that does not already exist.
A boot environment is created as a ZFS dataset and can have ZFS properties set on it. Use the options sub-element to set ZFS properties on a boot environment, as shown in the following example:
<logical>
<zpool name="rpool" is_root="true">
<be name="installed_be">
<options>
<option name="compression" value="on"/>
<option name="dedup" value="on"/>
<options>
</be>
</zpool>
</logical>
The software element specifies software to install. The software section specifies the following information:
The type of the software source
The location of the source
The names of software packages to install or uninstall
Optional components of software to install
Image properties
SSL keys and certificates required to access the IPS repository or unified archive
Authorization token required to access a unified archive.
The software element has the following attributes:
This is the name of the software instance. This name must be unique among all software instances in this AI manifest.
This is the type of the software source.
The type attribute can have one of the following values. The default value if type is not specified is IPS.
IPS: IPS package repository
P5I: IPS package file
SVR4: SVR4 packages
CPIO: cpio archive
ARCHIVE: Unified Archive
The software element has the following structure:
<!-- one or more software elements -->
<software>
<!-- zero or one destination element
Only used when type is IPS or P5I.
-->
<destination>
<!-- image properties and
optional software components
-->
</destination>
<!-- zero or one source element -->
<source>
<!-- one or more publisher, dir or file elements
IPS, P5I, and SVR4 types:
one or more publisher/origin elements
CPIO types: one or more dir elements
ARCHIVE types: one file element
-->
</source>
<!-- zero or more software_data elements
At least one software_data element must have
an action of install.
P5I type: zero software_data elements
-->
<software_data>
<!-- one or more name elements
ARCHIVE type: one name element-->
<name>...</name>
</software_data>
</software>
The default installation type if the type attribute is not specified is IPS.
Use the source element to specify which publishers to use for installing the packages. In the publisher element, the name attribute is required, and at least one origin sub-element is required. Each publisher can have multiple origins and mirrors, one credentials sub-element, and multiple cmd_options sub-elements.
Multiple publishers can be specified in one source element. The order in which publishers are defined in the AI manifest is the order in which the publishers are searched for IPS packages to install and the order in which the publishers are set in the installed image.
Use the cmd_options sub-element of the publisher element to specify an options string to be passed to the pkg(1) set-publisher command to be run on the publisher. This element can be used to set properties, attributes, or other options on the publisher. See the pkg(1) man page for more information about the set-publisher subcommand. Note that not all options are applicable to be set on publishers in the context of installation.
The following example specifies a publisher that has two cmd_options to set the non-sticky attribute on the publisher and to set the signature-policy property of the publisher to ignore:
<software type="IPS">
<source>
<publisher name="solaris">
<origin name="http://pkg.oracle.com/solaris/release"/>
<mirror name="http://localpkg.mycompany.com/solaris"/>
</publisher>
<publisher name="internal-software">
<origin name="http://internalsoft.mycompany.com/"/>
<cmd_options>--non-sticky</cmd_options>
<cmd_options>--set-property signature-policy=ignore</cmd_options>
</publisher>
</source>
</software>
When installing a non-global zone, the system repository is used by the zone. Any publishers specified in the AI manifest are added in the order in which they appear in the AI manifest, after the publishers provided by the system repository. See the pkg(1) and pkg.sysrepo(1M) man pages for more information about the system repository.
The following example specifies multiple publishers, one of which has a mirror as well as an origin:
<software type="IPS">
<source>
<publisher name="solaris">
<origin name="http://pkg.oracle.com/solaris/release"/>
<mirror name="http://localpkg.mycompany.com/solaris"/>
</publisher>
<publisher name="internal-software">
<origin name="http://internalsoft.mycompany.com/"/>
</publisher>
</source>
</software>
Use the software_data element to specify packages to install, reject, avoid, unavoid, or uninstall. The action attribute of the software_data element can have one of the following values:
Installs the IPS packages specified in the name sub-elements. This is the default if the action attribute is not specified. At least one software_data element must have an action of install.
By default, the newest version of a named package available from the specified sources and compatible with other packages in the image is installed. To install other versions of a package, use the version string in the package FMRI. For example, pkg:/mypkg@0.5.11-0.175.0.0.0.2.1 is more precise than pkg:/mypkg. If the specified version is not compatible with other packages in the image, the installation fails. If the specified version is not available from any of the specified sources, the installation fails. Use the keyword latest (for example, pkg:/mypkg@latest ) to install the newest version available from the specified sources that is compatible with other packages in the image.
Packages specified in name sub-elements might install other packages that are not explicitly named. If one of those packages is a package that you do not want to install, you can specify the name of the package that you do not want to install in a reject sub-element.
The reject sub-element only applies to the install section in which the reject sub-element appears. If a package is the value of a reject sub-element in one install section, but is only installed in a different install section, then the package is installed and not rejected.
Rejected packages that are the target of group dependencies are placed on the avoid list. See the avoid action below.
Adds the IPS packages in the name sub-elements to the avoid list.
Packages on the avoid list are not installed if they are the target of a group dependency.
Packages on the avoid list are installed if they are the target of a require dependency. If that require dependency is removed (for example, the package that contains the require dependency is uninstalled), the avoided package is uninstalled.
Only packages that are not currently installed can be avoided. Therefore, avoid sections must come before the install sections where you install the packages that have dependencies on the packages you want to avoid.
Removes the IPS packages in the name sub-elements from the avoid list.
Removes the IPS packages specified in the name sub-elements. Uninstalled packages that are the target of group dependencies are placed on the avoid list. See the avoid action above.
Any avoid list created during the installation continues to exist in the installed image.
The following example illustrates the use of software_data sections with different action values in a software section of type IPS:
<software_data action="avoid"> <name>pkg:/to/avoid</name> </software_data> <software_data action="install"> <name>pkg:/to/install</name> <reject>pkg:/to/reject</reject> </software_data> <software_data action="uninstall"> <name>pkg:/unwanted/pkg</name> </software_data>
A .p5i file is a file that describes IPS publishers, packages, and possibly mirrors.
To specify one or more .p5i files to be processed, provide the files as origins in the publisher element, as shown in the following example:
<software type="P5I">
<source>
<publisher>
<origin name="/somewhere/image1.p5i"/>
<origin name="/somewhere/image2.p5i"/>
</publisher>
</source>
</software>
If this AI manifest does not also have an IPS type software section, make sure your .p5i files specify origins.
Specification of packages to install is not supported for P5I installations. Therefore, software_data elements are not supported in a software element of type P5I.
For a SVR4 transfer, a directory containing SVR4 package subdirectories or a SVR4 package datastream file must be specified using a file directory path or a FILE URI. The SVR4 package datastream file can also be specified using an HTTP URI.
<software type="SVR4">
<source>
<publisher>
<origin name="/somedir"/>
</publisher>
</source>
</software>
The software_data element is used to specify the action to be performed. The action attribute can have one of the following two values:
Copies the files from the source to the new boot environment. This is the default if the action attribute is not specified. At least one software_data element must have an action of install.
Removes the files from the new boot environment.
For each of these actions, one or more packages can be specified in the name element, as shown in the following example:
<software type="SVR4">
<source>
<publisher>
<origin name="/somedir"/>
</publisher>
</source>
<software_data> <!-- defaults to install action -->
<name>ORGpackage1</name>
<name>ORGpackage2</name>
</software_data>
<software_data action="uninstall">
<name>ORGpackage8</name>
</software_data>
</software>
For a CPIO transfer, a source directory must be specified. The destination directory is set to the mount point for the new boot environment during the installation.
<software type="CPIO">
<source>
<dir path="/somedir"/>
</source>
</software>
The software_data element is used to specify the action to be performed. The action attribute can have one of the following values:
Copies the files from the source to the new boot environment. This is the default if the action attribute is not specified. At least one software_data element must have an action of install.
Use the name element to specify the files or directories to be copied. Paths specified in the name element are relative to the source.
<software_data> <!-- defaults to install action --> <name>path/relative/to/source</name> <name>another/path/relative/to/source</name> </software_data>
Removes files from the new boot environment.
Use the name element to specify the files or directories to be removed. Paths specified in the name element are relative to the destination.
<software_data action="uninstall"> <name>path/relative/to/destination</name> </software_data>
For an ARCHIVE transfer, a source file URI must be specified. The URI value can be an HTTP, HTTPS or FILE URI specification.
<software type="ARCHIVE"> <source> <file uri="http://mycompany.com/myarchive.ua"/> </source> </software>
Use elements of the file element to specify SSL Keys, certificates and CA certificates or an authorization token that are required to access the unified archive securely.
To access a unified archive requiring SSL client authentication you can provide key, certificate and CA certificate within the credentials sub-element.
<software type="ARCHIVE">
<source>
<file uri="https://mycompany.com/myarchive.ua"/>
<credentials>
<key src="file://root/key.pem"/>
<cert src="file://root/cert.pem"/>
<cacert src="file://root/cacert.pem"/>
</credentials>
</file>
</source>
</software>
Refer to the section on IPS Installations for specific information on format and accepted values for key, cert and cacert elements.
To access a unified archive requiring a specific authorization token you can provide this within the credentials sub-element.
<software type="ARCHIVE">
<source>
<file uri="http://mycompany.com/myarchive.ua"/>
<credentials>
<http_auth_token>my-specifically-granted-auth-token</http_auth_token>
</credentials>
</file>
</source>
</software>
The http_auth_token specified is passed as a X-Auth-Token HTTP header when the unified archive is accessed.
The software_data element is used to specify the action to be performed. The action attribname element value must be the name of any one of the deployable systems contained within the Unified Archive. Each deployable system name matches the name of a non-global zone or the global zone.
<software_data action="install"> <name>myzonename</name> </software_data>
Recovery Unified Archives can only be used for system recovery and do not allow deployable system selection from within the recovery Unified Archive.
For Recovery Unified Archives, the name element value must be *.
<software_data action="install"> <name>*</name> </software_data>
Use the destination element and the image sub-element to specify the following information:
Optional components of software to install
Image properties
SSL keys and certificates
The destination section only applies to IPS and P5I installation types. A destination element can have only one image sub-element.
SSL Keys and CertificatesUse attributes of the image element to specify SSL keys and certificates that are required for publishers using client SSL authentication. The key and certificate specified here apply to the first publisher defined in this AI manifest.
This attribute maps to the following pkg command:
pkg set-publisher -k ssl_key
The value of the ssl_key attribute is the ssl_key. See the pkg(1) man page for more information about the pkg set-publisher command.
This attribute maps to the following pkg command:
pkg set-publisher -c ssl_cert
The value of the ssl_cert attribute is the ssl_cert.
Use the facet sub-element of the image element to specify optional software components to install. Facets are not separate software packages but are optional components of any given software package such as locales, documentation, and development files such as files with debug information. You can save space by specifying that you only want to install one or two languages, for example. See the pkg(1) man page for more information about IPS facets.
The facet element has a boolean set attribute and a value that is the name of an IPS facet.
<facet set="true|false">facet_name</facet>
The following example specifies that only German and English facets of packages should be installed. The example first specifies that no locales should be installed and then specifies that German and English locales should be installed:
<destination>
<image>
<!-- de-select all locales -->
<facet set="false">facet.locale.*</facet>
<!-- specify specific locales to install -->
<!-- install German and English only -->
<facet set="true">facet.locale.de</facet>
<facet set="true">facet.locale.de_DE</facet>
<facet set="true">facet.locale.en</facet>
<facet set="true">facet.locale.en_US</facet>
</image>
</destination>
Image Properties
Use the property sub-element of the image element to specify IPS image properties for the new image this installation creates.
The property element has a boolean val attribute and a value that is the name of a property.
<property val="true|false">property_name</property>
See the “Image Properties” section of the pkg(1) man page for information about what properties can be set.
The AI manifest can be used to modify how the GRUB boot menu is configured on the installed system.
This section is not applicable to zone installations and is ignored when installing a non-global zone.
Use the boot_mods element and the boot_entry sub-element to modify the GRUB boot menu.
The boot_mods element has the following attributes:
The value of the title attribute is the base title of boot entries specified by boot_entry sub-elements of this boot_mods element. This attribute value overrides the name automatically generated from the first line of /etc/release or from the install media.
The value of the timeout attribute is the number of seconds to wait before the default boot_entry of this boot_mods element is selected.
Only the title attribute can be set on SPARC systems. All other settings in this section are ignored for SPARC systems.
Use the boot_entry sub-element to add one or more menu items to the boot menu. These menu items are in addition to any menu items that are automatically generated by the installer. The default menu item for active BE will not be present if menu item from boot_entry is present.
The boot_entry element has the following attributes:
If this boolean value is set to true, then this menu item is the default option selected on boot. The default value of this attribute is false.
If multiple boot_entry elements have default_entry set to true, then the last such entry is the default option selected on boot.
This attribute can be set to one of the following two values:
Place the entry at the end of the generated boot menu. This is the default placement.
Place the entry at the beginning of the generated boot menu.
The boot_entry menu item is then defined by the following sub-elements:
This element is required. This element defines text to be added to the end of the title specified in the boot_mods element.
This element is optional. This element is a string of values passed to the kernel by the boot loader.
The following example specifies a boot menu entry named “Boot Testing Default Boot Entry” that is the last entry on the menu and is automatically selected after 20 seconds:
<boot_mods title="Boot Testing" timeout="20">
<boot_entry default_entry="true">
<title_suffix>Default Boot Entry</title_suffix>
</boot_entry>
</boot_mods>
The configuration element supports non-global zone configurations. When installing a global zone system, the zone configurations specified in the AI manifest are used to install non-global zones onto the system after the global zone has been installed.
The configuration element has the following attributes:
The type of configuration to install. The only type supported by AI is zone.
A name given to the configuration. This name must be unique across all configuration elements in an AI manifest. For configurations of type zone, this name is also used as the zonename for the zone.
The location from which AI downloads the configuration file for this configuration element. The value can be an HTTP or FILE URI specification. For configurations of type zone, this value should point to a zone configuration file as produced from the zonecfg export command.
The following specification installs zone1 on the installation clients:
<configuration type="zone" name="zone1" source="http://myserver.com/configs/zone1/config"/>
The following equivalent specification installs zone1 on the installation clients, but uses a Unified Archive containing an archived zone configuration named myzone:
<configuration type="zone" name="zone1" source="archive:myzone" archive="http://myserver.com/archives/mysystem.uar"/>
For more information about configuring and installing zones, see Chapter 12, Installing and Configuring Zones in Installing Oracle Solaris 11.3 Systems.
A default system installation specification with no customizations. This AI manifest is provided on the system for reference only. To create a new AI manifest, use the copy of this file from the relevant install service image. See the “Description” section for information about copying this file from an install service.
A default zone installation with no customization. This file is used as the default manifest by the zoneadm install command to install non-global zones.
A template AI manifest with details commented out. This file provides examples of some customizations that can be performed. This file is provided on the system for reference only. To create a new AI manifest, use the copy of this file from the relevant install service image. See the “Description” section for information about copying this file from an install service.
See attributes(5) for descriptions of the following attributes:
|
pkg(1), beadm(1M), boot(1M), croinfo(1M), fdisk(1M), format(1M), installadm(1M), iostat(1M), iscsiadm(1M), pkg.sysrepo(1M), prtconf(1M), zfs(1M), zoneadm(1M), zonecfg(1M), zpool(1M), grub(5), smf(5)
Part 3, Installing Using an Install Server, in Installing Oracle Solaris 11.3 Systems
If you specify to install the Oracle Solaris OS on a dual-path FC disk on a SPARC system, the installation fails with the following error:
17:22:08 Error occurred during execution of 'target-selection' checkpoint. 17:22:08 100% None 17:22:09 Failed Checkpoints: 17:22:09 17:22:09 target-selection 17:22:09 17:22:09 Checkpoint execution error: 17:22:09 17:22:09 Unable to locate the disk '[devpath='/pci@0,600000/pci@0/pci@8/pci@0,1/SUNW,emlxs@1,1/fp@0,0/ssd@w20350080e517b4da,6']' on the system. 17:22:09 17:22:09 Automated Installation Failed. See install log at /system/volatile/install_log Automated Installation failed Please refer to the /system/volatile/install_log file for details
The workaround for this issue is to disconnect one of the dual-path SAS JBOD cables.
If the name_type attributes (vol-id and volid) specified by the user exists on more than one disk on a system being installed, then there is no guarantee as to which disk will be selected. For example, if a user has assigned volname of ai-disk to two disks on the system, and specified name_type as volid, then there is no guarantee which disk will be selected.
In the following example, the format command shows two disks available with a volid of ai-disk.
# format
Searching for disks...done
AVAILABLE DISK SELECTIONS:
0. c1t0d0 <SUN72G cyl 14087 alt 2 hd 24 sec 424>
/pci@780/pci@0/pci@9/scsi@0/sd@0,0
1. c1t1d0 <SUN72G cyl 14087 alt 2 hd 24 sec 424> ai-disk
/pci@780/pci@0/pci@9/scsi@0/sd@1,0
2. c1t2d0 <HITACHI-H101473SCSUN72G-SA23-68.37GB>
/pci@780/pci@0/pci@9/scsi@0/sd@2,0
3. c1t3d0 <HITACHI-H101473SCSUN72G-SA23-68.37GB> ai-disk
/pci@780/pci@0/pci@9/scsi@0/sd@3,0
Specify disk (enter its number):
For example, if the manifest attempts to select the disk via the name_type ai-disk, the AI Installer will not know which disk to use and will select one.
<target> <disk> <disk_name name="ai-disk" name_type="volid"/> ... </target>
There is no guarantee that the first volid labeled ai-disk listed by format command will be selected.
This condition also occurs, if the name_type is set to wwn and the device specified in the manifest are derived from a RAID system. In this scenario, the WWN exported for all devices from the RAID system may not be unique.
When using name_type in a manifest, it is important to use a name that is unique across all the devices being installed.