## iSCSI Software Initiator Configuration

## Introduction

The iSCSI Software Initiator allows you to configure an iSCSI target
device to be used as a boot source. The BIOS current configuration
object contains a link to a separate resource of type
`HpeiSCSISoftwareInitiator`. The BIOS current configuration resource
and the iSCSI Software Initiator current configuration resources are
read-only. To change iSCSI settings, you need to follow another link
to the Settings resource, which allows PUT and PATCH operations.

The iSCSI target configurations are represented in an `iSCSISources`
property, that is an array of objects, each containing the settings
for a single target. The size of the array represents the total number
of iSCSI boot sources that can be configured at the same time. Many
mutable properties exist, including `iSCSIAttemptInstance`, which can
be set to a unique integer in the range [1, N], where N is the boot
sources array size. By default, this instance number is 0 for all
objects, indicating that the object should be ignored
when configuring iSCSI.

Each object also contains two read-only properties—`StructuredBootString`
and `UEFIDevicePath`, which are only populated after the target has
been successfully configured as a boot source. More information about
each property is available in the corresponding schema. The iSCSI
initiator name is represented by the `iSCSIInitiatorName` property.

An additional read-only property, `iSCSINicSources`, is only shown in
the iSCSI current configuration resource. This property is an array of
strings representing the possible NIC instances that can be used as
targets for iSCSI boot configuration. To confirm which NIC device each
string corresponds to, it is recommended to cross-reference two
other resources.

* A resource of type `HpeBiosMapping` can be found through a `Mappings` link
in the BIOS current configurations resource. Within its
`BiosPciSettingsMappings` property is an array of mappings between
BIOS-specific device strings (such as the `NIC` source string) and
a `CorrelatableID` string that can be used to refer to the same
device in non-BIOS contexts.
* A collection of `HpeServerPciDevices` may be found through a PCIDevices
link in the `ComputerSystem` resource. To find the specific PCI device
corresponding to the NIC instance, you can search for the `CorrelatableID`
that usually matches a `UEFIDevicePath.` Once you find the
`HpeServerPciDevice` resource, you have access to all the
human-readable properties useful for describing a NIC source.


Changing the `iSCSISources` and `iSCSIInitiatorName` settings can be done
through `PATCH` operations, very similar to how `HpeBios` settings are
changed. However, whereas all BIOS settings are located in a single flat
object, iSCSI settings are nested into arrays and sub-objects. When doing
a `PATCH` operation, use empty objects (`{}`) in place of those boot
source objects that you do not want to alter.

The following example covers a situation where you have configured two
iSCSI boot sources, and you would like to edit some existing settings,
and add a third source.

1. Iterate through `/redfish/v1/Systems` and choose a member `ComputerSystem.`
Find a child resource of type `HpeiSCSISoftwareInitiator` that allows
PATCH operations.
  * `{ilo-address}/redfish/v1/Systems/1/BIOS/iSCSI/Settings`
2. Inspect the existing `iSCSISources` array. You need to inspect the
`iSCSIAttemptInstance` property of each object to find the boot sources
you are prefer to change.
3. Create a new JSON object with the `iSCSISources` property.
  * Use an empty object in the position of instance 1 to indicate that
it should not be modified.
Use an object in the position of instance 2 containing the properties that
should be modified. All omitted properties remain unmodified.
  * To add a new boot source, find any position of instance 0 and replace
it with an object containing all the new settings, and most
importantly, a new unique value of `iSCSIAttemptInstance.`
4. Change the iSCSI software initiator settings.
  * `PATCH {ilo-address}/redfish/v1/Systems/1/BIOS/iSCSI/Settings`