Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

OpenSolaris 2009.06 - man page for iscsitadm (opensolaris section 1m)

iscsitadm(1M)						  System Administration Commands					     iscsitadm(1M)

iscsitadm - 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: create Creates a target using a local target as a reference. modify Modifies a target or a list of targets. delete Deletes a target or a list of targets. list Lists names and information about targets. show Displays target-related statistics. The preceding subcommands work on the following objects: target An iSCSI target node, or list of target nodes. initiator An iSCSI initiator node, or list of initiator nodes. admin Stores administrative information, such as server locations and passwords. tpgt Stands for TargetPortGroupTag. A number that represents a list of connections that an initiator can use for a given target. stats 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. create Options The following are the options and objects for the create subcommand: target --size|-z lun_size [--lun number] [--type disk|tape|raw] [--backing-store|-b pathname] local_name 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: k kilobyte m megabyte g gigabyte t terabyte --lun specifies the logical unit number. --type specifies which type of emulation will occur for the LUN. disk and tape are the famil- iar 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 hierar- chy. 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. initiator --iqn|-n iSCSI_node_name local_initiator 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. tpgt tpgt_number 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 estab- lish 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. modify Options The following are the options and objects for the modify subcommand: target --tpgt|-p local_tpgt local_target Specifies one or more target portal groups to use when initiators reference local_target during discovery. target --acl|-l local_initiator local_target 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. target --alias|-a TargetAlias local_target Sets the alias if it was not done during the creation of the target or change an existing target's alias. target --maxrecv|-m value local_target Sets the MaxRecvDataSegmentLength, which can be any value between 512 to (2^24 - 1). You can use this option to limit the amount of memory used by the target. initiator --chap-secret|-C local_initiator Prompts the user to enter the value, using getpassphrase(3C). Associates the secret used for CHAP authentication during login with local_initiator. initiator --chap-name|-H value local_initiator Specifies the CHAP username used during authentication. tpgt --ip-address|-i address tpgt_number Adds the NIC's address to tpgt_number. admin --base-directory|-d directory 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. admin --chap-secret|-C 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. admin --chap-name|-H value Specifies the user name portion of the CHAP protocol. admin --radius-access|-R enable | disable 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. admin --radius-server|-r hostname:port Location of RADIUS server. hostname can be either a resolvable name or an IP address. admin --radius-secret|-P Used to initiate contact with the RADIUS server. Interaction with server uses getpassphrase(3C). admin --isns-access|-S enable | disable Enables or disables access to an iSNS server. iSNS servers broadcast their locations. admin --isns-server|-s hostname Location of the iSNS server. "hostname" can be either a resolvable host name or an IP address. admin --fast-write-ack|-f enable | disable 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. delete Options The following are the options and objects for the delete subcommand: target --lun|-u lun_number local_target Removes information about the LUN identified by lun_number. This includes the data that is stored in the LUNs. target --acl|-l local_initiator local_target Remove access to local_target by local_initiator. If the initiator is currently logged into the target, this option sends an asynchro- nous event message to the initiator. target --tpgt|-p local_tpgt local_target Removes the local_tpgt from local_target. Does not affect existing connections. initiator --all|-A local_initiator Removes information about local_initiator. Does not affect current connections. This option search all targets, seeking those that ref- erence local_initiator. On these, it performs the action defined by the command: # iscsitadm delete target --acl local_initiator target tpgt --all|-A tpgt_number 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. tpgt --ip-address|-i address tpgt_number Removes a NIC's address from the target portal group identified by tpgt_number. Does not affect current connections. list Options The following are the options and objects for the list subcommand: target [--verbose] [local_target] target [-v|-s num] [local_target] 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, informa- tion 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. initiator [--verbose|-v] local_initiator Displays detailed information about local_initiator. Among this data is CHAP information, what target portal groups this initiator belongs to, and any available connections. tpgt [--verbose|-v] tpgt_number 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. show Options The following are the options and objects for the show subcommand: admin Displays a list of administrative information, including the base directory used by the target, CHAP, RADIUS, iSNS, and if fast writes are enabled. stats [--interval|-I seconds [--count|-N value]] [local_target] Displays statistics for all available targets, unless you specify local_target, in which case, displays statistics only for local_tar- get. If you use --interval, displays statistics for an interval specified by seconds. If you do not specify --count, the display con- tinues 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 com- mand line, it reverts to the default, 0. # iscsitadm create target --size 10g playarea 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 \[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 accom- plished 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: Target: disk0 iSCSI Name: 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: 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
0 Command successful. >0 An error occurred.
See attributes(5) for descriptions of the following attributes: +-----------------------------+-----------------------------+ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | +-----------------------------+-----------------------------+ |Availability |SUNWiscsitgtu | +-----------------------------+-----------------------------+ |Interface Stability |Volatile | +-----------------------------+-----------------------------+
iostat(1M), iscsiadm(1M), getpassphrase(3C), attributes(5), rbac(5), smf(5)
This command set is considered to be experimental. Future releases, both minor and micro, might introduce incompatible changes to the com- mand set. A future release will stabilize the command set. Any future changes in stability level will be reflected in the ATTRIBUTES sec- tion 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): svc:/system/iscsitgt:default Use iscsitadm to perform administrative actions, such as are performed by the create, modify, and delete subcommands, on iSCSI Target prop- erties. Such actions require that you become superuser or assume the Primary Administrator role. See rbac(5). SunOS 5.11 5 Feb 2009 iscsitadm(1M)