- administer iSCSI targets
iscsitadm create [-? | --help] object [-? | --help] [options] operand
iscsitadm modify [-? | --help] object [-? | --help] [options] operand
iscsitadm delete [-? | --help] object [-? | --help] [options] operand
iscsitadm list [-? | --help] object [-? | --help] [options] operand
iscsitadm show [-? | --help] admin
iscsitadm show [-? | --help] object [-? | --help] [options] [operand]
iscsitadm -? --help
The iscsitadm command enables you to manage Internet SCSI (iSCSI) target nodes. It is a companion to iscsiadm(1M), which enables you to manage iSCSI initiator nodes.
The iscsitadm command has the following subcommands:
Creates a target using a local target as a reference.
Modifies a target or a list of targets.
Deletes a target or a list of targets.
Lists names and information about targets.
Displays target-related statistics.
The preceding subcommands work on the following objects:
An iSCSI target node, or list of target nodes.
An iSCSI initiator node, or list of initiator nodes.
Stores administrative information, such as server locations and passwords.
Stands for TargetPortGroupTag. A number that represents a list of connections that an initiator can use for a given target.
Displays statistics; can accept interval and count values. Used only with the show subcommand.
These objects are discussed in greater detail under the options descriptions for each subcommand.
As indicated in the SYNOPSIS, iscsitadm has two levels of help. If you invoke -? or --help following a subcommand, the command displays available operands, options, and objects. If you invoke an help option following an object, iscsitadm displays options and operands.
The iscsitadm options and objects are discussed below in the context of each subcommand. Note that the help options (-? or --help) are invoked as shown in the SYNOPSIS. See EXAMPLES.
The following are the options and objects for the create subcommand:
Create a target using local_name as a reference. local_name is only used within the context iscsitgtd. --size is a multiplier and is specified as a number followed by a single letter. The letter is one of:
--lun specifies the logical unit number. --type specifies which type of emulation will occur for the LUN. disk and tape are the familiar devices. raw indicates that the emulator will use the uSCSI interface and pass the command blocks directly to and from the device. The use of raw also implies the option --backing-store will be entered. The argument to this option is the full pathname to the device node normally found in /dev. If you use --backing-store, the size of the store is determined by a SCSI READ_CAPACITY command or, if the backing store is a regular file, by stat(2).
If local_name already exists, a new target name is not generated for this LUN. The LUN is created within the local_name storage hierarchy. You can use the --backing-store option to specify a different location for the data. If you use --backing-store, it is up to you to allocate actual storage instead of having the target create the data file.
To use access control lists you must know the name of the initiator. Since the iSCSI initiator name can be quite long (223 bytes) and made up of a long list of numbers, it is best to enter this information once and then refer to the initiator using a simplified name of local_initiator.
If a host has multiple NICs, you might want to limit the number of connections that an initiator can use for a given target. To establish this limit, you must first create a TargetPortGroupTag (TPGT), which can be any number from 1 to 65535. Once this tag is created, the IP addresses of the NICs can be added to the TPGT, using the modify subcommand. Then, the TPGT can itself be added to the target.
The following are the options and objects for the modify subcommand:
Specifies one or more target portal groups to use when initiators reference local_target during discovery.
Adds to the list a local initiator that can access local_target. By adding an initiator to a target all initiators from that point on must be in the ACL.
Sets the alias if it was not done during the creation of the target or change an existing target's alias.
Sets the MaxRecvDataSegmentLength, which can be any value between 512 to (224 - 1). You can use this option to limit the amount of memory used by the target.
Prompts the user to enter the value, using getpassphrase(3C). Associates the secret used for CHAP authentication during login with local_initiator.
Specifies the CHAP username used during authentication.
Adds the NIC's address to tpgt_number.
Sets the location of where to store the data files that represent the individual LUNs. This should be done before any other function is performed. Otherwise, an error will be generated when attempting to set a persistent value.
Upon entering this option, you will be prompted to enter the value using getpassphrase(3C). For bidirectional authentication, this is the value used to generate a response to the initiator's challenge.
Specifies the user name portion of the CHAP protocol.
Enables or disables the use of the RADIUS server. Even with a RADIUS server address defined, the use of that server must be enabled. If the server becomes inaccessible and you need to fall back on configuration file access, you can use this option to disable the server.
Location of RADIUS server. hostname can be either a resolvable name or an IP address.
Used to initiate contact with the RADIUS server. Interaction with server uses getpassphrase(3C).
Enables or disables access to an iSNS server. iSNS servers broadcast their locations.
Location of the iSNS server. “hostname” can be either a resolvable host name or an IP address.
Enables or disables fast-write acknowledgment. You should enable this option only if a system is connected to the power grid through a UPS. Otherwise, data corruption could occur if power is lost and some writes that were acknowledged have not been completely flushed to the backing store.
The following are the options and objects for the delete subcommand:
Removes information about the LUN identified by lun_number. This includes the data that is stored in the LUNs.
Remove access to local_target by local_initiator. If the initiator is currently logged into the target, this option sends an asynchronous event message to the initiator.
Removes the local_tpgt from local_target. Does not affect existing connections.
Removes information about local_initiator. Does not affect current connections. This option search all targets, seeking those that reference local_initiator. On these, it performs the action defined by the command:
# iscsitadm delete target --acl local_initiator target
Removes from the system all knowledge of the target portal group identified by tpgt_number. This includes removal of the references by targets to this group.
Removes a NIC's address from the target portal group identified by tpgt_number. Does not affect current connections.
The following are the options and objects for the list subcommand:
By default, displays a list of target local names followed by the iSCSI TargetName, as it was created. By specifying local_target, the same information is displayed for that target and can be used to validate the name of local_target. With the --verbose option, information about the target's LUNs and current connections is displayed.
You can use the iostat(1M) command to obtain information on the number of SCSI commands issued and sectors read and written.
Displays detailed information about local_initiator. Among this data is CHAP information, what target portal groups this initiator belongs to, and any available connections.
Displays detailed information about target group identified by tpgt_number. Among this data is the list of NICs that are a part of this target group.
The following are the options and objects for the show subcommand:
Displays a list of administrative information, including the base directory used by the target, CHAP, RADIUS, iSNS, and if fast writes are enabled.
Displays statistics for all available targets, unless you specify local_target, in which case, displays statistics only for local_target. If you use --interval, displays statistics for an interval specified by seconds. If you do not specify --count, the display continues until you enter a Control-C.
Example 1 Invoking Help
All of the commands shown below are valid ways of invoking help.
# iscsitadm -? # iscsitadm modify -? # iscsitadm modify target -? # iscsitadm --help # iscsitadm create --help # iscsitadm create tpgt --help
Example 2 Establishing Backing Store
The following command establishes the default location for the backing store. In addition to the backing store, certain configuration files will be stored in the same location.
# iscsitadm modify admin --base-directory /zfs/data/targets
The short form of the --base-directory option is -d.
Example 3 Simplest-Case Target Creation
The following command creates a target that will emulate an LBA device that has 10 GB of storage available. With the base directory set up and as well as a single target, it is possible to use the system as an iSCSI target. Note that because the LUN is not specified on the command line, it reverts to the default, 0.
# iscsitadm create target --size 10g play_area
The short form of the --size option is -z.
Example 4 Creating with Both Size and Backing Store
The following iscsitadm create command specifies LUN size and a backing store location. The result of this command is that the daemon will create a LUN file at the named location, of the specified size (20 GB).
# iscsitadm create target -z 20g -b /zfs/mirror/data/payroll payroll
A target such as the one created by the preceding command might be useful, for example, when most of the LUN can be created in a default area, using whatever redundancy is provided by the underlying file system. Alternatively, you might want to create a special LUN on a higher speed storage medium or one with better failover characteristics.
The long form of the -z option is --size. The long form of the -b option is --backing-store
Example 5 Specifying a Local Name for a SCSI Initiator
Consider that you want to restrict access to the payroll target, created in the previous example, to a limited set of initiators. Because the initiator names can be quite long (and therefore prone to be entered incorrectly), you create a local name for each initiator, as in the command below.
# iscsitadm create initiator --iqn \ iqn.1986-03.com.example[node name continues...] multistrada
The short form of the --iqn option is -q.
Example 6 Granting an Initiator Access to a Target
Upon completion of the command below, only the initiator multistrada is allowed to log into the daemon and access the payroll target. This presents a potential gap in security, which is addressed in the following example.
# iscsitadm modify target --acl multistrada payroll
The short form of the --acl option is -l.
Example 7 Adding CHAP Secret and Name for an Initiator
The initiator is allowed to identify itself. Because of this, it is prudent to add a CHAP secret an name for an initiator. This is accomplished with the following command.
# iscsitadm modify initiator -C multistrada
The preceding command prompts you for a secret to use. This must be the same secret that was setup on the initiator with the local name of multistrada. If it is not, the target daemon will issue a challenge to multistrada when it attempts to login. A non-matching response will cause the target to drop the connection. If you have many targets that require authentication, it is probably best to setup a RADIUS server to administer the secrets.
The long form of the -C option is --chap-secret.
Example 8 Displaying Target Information
The following commands displays information about iSCSI targets.
# iscsitadm list target Target: vol0 iSCSI Name: iqn.1986-03.com.sun:01:00093d12170c.434c5250.vol0 Target: disk0 iSCSI Name: iqn.1986-03.com.sun:01:00093d12170c.434c6f05.disk0
The following command differs from the preceding in that it uses the verbose (-v) option and it specifies a single target.
# iscsitadm list target -v vol0 Target: vol0 iSCSI Name: iqn.1986-03.com.sun:01:00093d12170c.434c5250.vol0 ACL list: TPGT list: LUN information: LUN: 0 GUID: 010000093d12170c00002a00434c5251 VID: SUN PID: SOLARIS Type: raw Size: 0x1400000 blocks
Example 9 Displaying Administrative Information
The following command uses the show subcommand to display administrative information.
# iscsitadm show admin iscsitadm: Base Directory: /zfs/stress/play/targets CHAP Name: Not set RADIUS Access: Not set RADIUS Server: Not set iSNS Access: Not set Fast Write ACK: Not set
Example 10 Displaying Statistics
The following command uses the show subcommand to display statistics.
# iscsitadm show stats operations bandwidth device read write read write -------------------- ----- ----- ----- ----- vol0 0 0 0K 0K disk0 0 0 0K 0K
An error occurred.
See attributes(5) for descriptions of the following attributes:
This command set is considered to be experimental. Future releases, both minor and micro, might introduce incompatible changes to the command set. A future release will stabilize the command set. Any future changes in stability level will be reflected in the ATTRIBUTES section of this man page.
The iSCSI Target daemon, iscsitgtd, is managed by the service management facility (smf(5)), under the fault management resource identifier (FMRI):
Use iscsitadm to perform administrative actions, such as are performed by the create, modify, and delete subcommands, on iSCSI Target properties. Such actions require that you become superuser or assume the Primary Administrator role. See rbac(5).