logo
Manual Pages
Table of Contents

NAME

iscsi - manage iSCSI service

SYNOPSIS

iscsi alias [-c | <new_alias>] iscsi connection show [-v] [ {new | <session_tsih>} <conn_id>] iscsi initiator show iscsi interface accesslist add [-f] <initiator_name> {-a | <interface> ...} iscsi interface accesslist remove [-f] <initiator_name> {-a | <interface> ...} iscsi interface accesslist show [ { -a | <initiator_name> ...} ] iscsi interface enable {-a | <interface> ...} iscsi interface disable [-f] {-a | <interface> ...} iscsi interface show [-a | <interface> ...] iscsi isns config <hostname> | <ip_addr> iscsi isns show iscsi isns start iscsi isns stop iscsi isns update iscsi nodename [<new_nodename>] iscsi portal show iscsi security add -i <initiator> -s CHAP -p <inpassword> -n <inname> [ -o <outpassword> -m <outname> ] iscsi security add -i <initiator> -s { deny | none } iscsi security default -s CHAP -p <inpassword> -n <inname> [ -o <outpassword> -m <out_name> ] iscsi security default -s { deny | none } iscsi security delete -i <initiator> iscsi security generate iscsi security show iscsi session show [-v | -t | -p | -c] [<session_tsih> ...] iscsi start iscsi stats [-z | -a | ipv4 | ipv6] iscsi status iscsi stop iscsi tpgroup add [-f] <tpgroup_name> [<interface> ...] iscsi tpgroup create [-f] [-t <tpgtag>] <tpgroup_name> [<interface> ...] iscsi tpgroup destroy [-f] <tpgroup_name> iscsi tpgroup remove [-f] <tpgroup_name> [<interface> ...] iscsi tpgroup show iscsi tpgroup alua show iscsi tpgroup alua set <tpgroup_name> { optimized | nonoptimized } [preferred] iscsi ip_tpgroup add [-f] <tpgroup_name> [<IP address> ...] iscsi ip_tpgroup create [-f] [-t <tpgtag>] <tpgroup_name> [<IP Address> ...] iscsi ip_tpgroup destroy [-f] <tpgroup_name> iscsi ip_tpgroup remove [-f] <tpgroup_name> [<IP Address> ...] iscsi ip_tpgroup show

DESCRIPTION

iSCSI is a transport protocol which allows standard SCSI block access over a TCP/IP network. When the iSCSI service is licensed and enabled, Network Appliance filer can operate as an iSCSI target device. The iscsi command manages the iSCSI service on a filer, and is available only if your filer has iSCSI licensed. Using the iscsi command, you may set the iSCSI nodename and target alias, and start or stop the iSCSI service, and display initiators currently connected to a the filer. You may also manage iSCSI use of filer network interfaces, configure security parameters, and dump iSCSI statistics.

USAGE

Filer Nodename and Alias
Under the iSCSI protocol, each iSCSI target device is assigned a nodename which is unique within the operational domain of the end user. The protocol also allows an administrator to assign a user-friendly target alias string for the device, for ease of identification in user interfaces. The nodename and alias subcommands are used to manage the filer's nodename and target alias. iscsi nodename [<new_nodename>] Set the iSCSI target nodename of the filer to new_nodename, if specified. Otherwise, display the current iSCSI target nodename of the filer. iscsi alias [-c | <new_alias>] Set the iSCSI target alias of the filer to new_alias, if specified. Clear the target alias if the -c option is specified. Otherwise, display the current iSCSI target alias of the filer. Service State
When the iSCSI service is licensed, the filer administrator may use the start and stop subcommands to control whether the filer accepts new incoming iSCSI requests. iscsi start Starts the iSCSI service if it is not already running. iscsi stop Stops the iSCSI service if it is running; this causes any active iSCSI sessions to be shutdown. iscsi status Displays current status of the iSCSI service. iSCSI Activity
When the iSCSI service is running, the filer is actively accepting new iSCSI connections and servicing incoming iSCSI requests from connected initiators. The initiator, stats, session, and connection subcommands are used to monitor the filer's iSCSI activity. iscsi initiator show Display a list of initiators currently connected to the filer. Information displayed for each initiator includes the Target Session ID Handle (TSIH) assigned to the session, the target portal group number to which the initiator is connected, the iSCSI initiator alias (if provided by the initiator), and the initiator's iSCSI nodename and Initiator Session ID (ISID). iscsi stats [-z | -a | ipv4 | ipv6] Display the current iSCSI statistics. Statistics displayed include the different iSCSI PDU types transmitted and received, SCSI CDB's processed, and various iSCSI errors which may occur. If the -z option is given, all iSCSI statistics are zeroed. If the -a option is given, the output contains the iSCSI statistics for ipv4, ipv6 and the total. If the ipv4 option is given, the output contains the iSCSI statistics only for ipv4. If the ipv6 option is given, the output contains the iSCSI statistics only for ipv6. iscsi session show [-v | -t | -p | -c] [<session_tsih> ...] Show status of specified session, or for all sessions if no sessions are specified. If the -t option is specified, the output contains underlying TCP connection information. If the -p option is specified, the output contains iSCSI session parameter information. If the -c option is specified, the output contains information about the iSCSI commands which are in progress on the session. If the -v option is specified, the output is verbose, and contains all information, including that shown with the -t, -p, and -c options. Status information displayed includes: Initiator name, ISID - The iSCSI nodename and iSCSI Initiator Session ID, which combine to identify the initiator using this session. TCP connections - The local and remote IP addresses, TCP ports, and filer network interface used for each underlying TCP connection. for each connection. Session Parameters - iSCSI session parameters negotiated via the iSCSI login key exchanges. For specific definitions of these parameters, please see the iSCSI protocol specification. iscsi connection show [-v] [ {new | <session_tsih>} <conn_id>] Show status of one connection, or for all connections if no connection is specified. A connection may be one of the connections which compose an active iSCSI session, or it may be a new connection which has not yet completed the iSCSI login sequence. If the -v option is specified, the output is verbose. Status information displayed includes: Connection name - session_tsih/connection_id for connections associated with active sessions; new/connection_num for new connections not yet associated with a session. Connection state - State of this connection (e.g. Login_In_Progress, Full_Feature_Phase, Shutdown_In_Progress). TCP connections - The local and remote IP addresses and TCP ports of the underlying TCP connections, and the filer interface used for the connection (verbose mode only). Network Interface Management
The filer may be accessed as an iSCSI target device over any or all of the filer's network interfaces. The iscsi interface command allows the administrator to control which network interfaces may be used for iSCSI connectivity. For example, an administrator may wish to configure a filer to support iSCSI access only through the filer's Gigabit Ethernet interfaces. When the iscsi service is enabled, ONTAP will accept iSCSI connections and requests over those network interfaces enabled for iSCSI use via the iscsi interface command, but not over disabled interfaces. When the iscsi service is stopped, ONTAP will not accept iSCSI connections or requests over any interface, regardless of its enable/disable state. iscsi interface show [-a | <interface> ...] Show the enable/disable state of the specified interfaces, or of all interfaces if -a is specified. If no arguments are specified, the state of all interfaces is displayed. iscsi interface enable { -a | <interface> ... } Enable the specified interfaces for iSCSI service. If -a is specified, all interfaces are enabled for iSCSI use. Once enabled, new iSCSI connections will be accepted, and iSCSI requests serviced, over the newly enabled interfaces. iscsi interface disable [-f] { -a | <interface> ... } Disable the specified interfaces for iSCSI service. If -a is specified, all interfaces are disabled for iSCSI use. The process of disabling an interface requires termination of any outstanding iSCSI connections and sessions currently using that interface. The command prompts for confirmation if any active sessions will be affected, unless the -f flag is specified. Once disabled, ONTAP rejects subsequent attempts to establish new iSCSI connections over the newly disabled interfaces. Network Interface Accesslist Management
The iscsi interface command, as described above, controls access to an interface for all initiators. With the iscsi interface accesslist subcommand, the administrator can restrict an initiator to certain network interfaces. This is useful in environments where a particular initiator cannot access all of the network interfaces on a filer, for example in configurations that use IEEE 802.1Q Virtual LANs (VLANs). An accesslist for an initiator is a list of network interfaces that the initiator is allowed to use for iSCSI logins. Accesslists are recorded as part of the filer configuration and are preserved across reboots. In addition, separate accesslists are maintained for each vfiler. The rules for accesslists are: * If a network interface is disabled for iSCSI use (via iscsi interface disable), then it is not accessible to any initiator regardless of any accesslists in effect. * If there is no accesslist for a particular initiator, then that initiator can access any iSCSI-enabled network interface. * If there is an accesslist for a particular initiator, then that initiator can only login to network interfaces in its accesslist. Furthermore, the initiator cannot discover IP addresses to which it does not have access. If an initiator logs into an accessible network interface for a discovery session and sends an iSCSI SendTargets command, the filer will respond with a list of network portals that includes only IP addresses from network interfaces that are in its accesslist. * If an initiator has no accesslist and an iscsi interface accesslist add command is invoked for that initiator, an accesslist is created. If an initiator has an accesslist and all of its interfaces are removed via an iscsi interface accesslist remove operation, then the accesslist itself is deleted. * Creating or modifying an accesslist may require shutting down existing iSCSI sessions associated with network interfaces that no longer appear on the accesslist. For example, creating a new accesslist via the add operation may cause sessions to be shut down on network interfaces that are not in the new accesslist. Likewise, removing network interfaces from an existing accesslist via the remove operation may also cause sessions to be shut down. The add and remove subcommands warn the user if iSCSI sessions could be affected. Note that adding all interfaces (add -a) and removing all interfaces (remove -a) will not affect any iSCSI sessions. The following subcommands manage accesslists: iscsi interface accesslist show [ { -a | <initiator_name> ...} ] Show the accesslist for each of the named initiators (or all initiators if -a is specified). iscsi interface accesslist add [-f] <initiator_name> {-a | <interface> ...} Add the named network interfaces (or all interfaces if -a is specified) to the accesslist for the specified initiator. If there is no accesslist, one will be created. This command prompts for confirmation if any active sessions will be affected, unless the -f flag is specified. iscsi interface accesslist remove [-f] <initiator_name> {-a | <interface> ...} Remove the named network interfaces (or all interfaces if -a is specified) from the accesslist for the specified initiator. If this command leaves the initiator's accesslist empty, the accesslist itself is removed. This command prompts for confirmation if any active sessions will be affected, unless the -f flag is specified. Target Portal Group Management
As an iSCSI target device, a filer receives iSCSI requests over any or all of its network interfaces. Each network interface is assigned to an iSCSI target portal group. The iscsi tpgroup command is used to manage the assignment of a filer's network interfaces to target portal groups. The administrator may create user-defined target portal groups containing a specific set of filer network interfaces. Any interface which is not part of a user-defined target portal group is assigned by ONTAP to a system default tpgroup. Use the iscsi ip_tpgroup command to manage the assignment of a vFiler's IP Addresses to target portal groups. The administrator may create userdefined target portal groups containing a specific set of vFiler's IP Addresses. Data ONTAP assigns any IP Address that is not part of a user-defined target portal group to the system default ip_tpgroup. The administrator should take into account the following factors, imposed by the iSCSI protocol, when assigning interfaces to target portal groups: 1) All TCP connections within an iSCSI session must use interfaces within the same target portal group. 2) A given initiator may have no more than one iSCSI session in progress to the filer through a specific target portal group. The iscsi portal command may be used to display the list of portals (IP address/TCP port number), and their portal group assignments, over which the filer operates the iSCSI service. The contents of the portal list depends on the enable/disable state and the IP addresses configured on the filer's network interfaces, plus the target portal group assignment for each interface. iscsi tpgroup show Display the filer's list of target portal groups, both user-defined and system default. iscsi tpgroup create [-f] [-t <tpgtag>] <tpgroup_name> [<interface> ...] Create a user-defined target portal group. If one or more network interfaces are provided, add those interfaces to the group. If a target portal group tag is specified, that tpgtag is assigned to the created group; otherwise, a tpgtag is automatically assigned. Reassigning network interfaces may result in termination of sessions already in progress on those interfaces. The command prompts for confirmation if any active sessions will be affected, unless the -f flag is specified. iscsi tpgroup add [-f] <tpgroup_name> [<interface> ...] Add interfaces to a user-defined target portal group. Reassigning network interfaces may result in termination of sessions already in progress on those interfaces. The command prompts for confirmation if any active sessions will be affected, unless the -f flag is specified. iscsi tpgroup remove [-f] <tpgroup_name> [<interface> ...] Remove interfaces from a user-defined target portal group. The interfaces are assigned by ONTAP back to their system default tpgroups. Reassigning network interfaces may result in termination of sessions already in progress on those interfaces. The command prompts for confirmation if any active sessions will be affected, unless the -f flag is specified. iscsi tpgroup destroy [-f] <tpgroup_name> Destroy a user-defined target portal group. Any network interfaces which are members of the tpgroup are assigned by ONTAP back to their system default tpgroups. Reassigning network interfaces may result in termination of sessions already in progress on those interfaces. The command prompts for confirmation if any active sessions will be affected, unless the -f flag is specified. iscsi ip_tpgroup show Display the vFiler's list of IP-based target portal groups, both user-defined and system default. iscsi ip_tpgroup create [-f] [-t <tpgtag>] <tpgroup_name> [<IP Address> ...] Create a user-defined IP-based target portal group. If one or more IP Addresses are provided, add those IP Addresses to the group. If a target portal group tag is specified, that tpgtag is assigned to the created group; otherwise, a tpgtag is automatically assigned. Reassigning IP Addresses may result in termination of sessions already in progress on those IP Addresses. The command prompts for confirmation if any active sessions will be affected, unless the -f flag is specified. iscsi ip_tpgroup add [-f] <tpgroup_name> [<IP Address> ...] Add IP Addresses to a user-defined target portal group. Reassigning IP Addresses may result in termination of sessions already in progress on those IP Addresses. The command prompts for confirmation if any active sessions will be affected, unless the -f flag is specified. iscsi ip_tpgroup remove [-f] <tpgroup_name> [<IP Address> ...] Remove IP Addresses from a user-defined target portal group. Data ONTAP assigns the IP Addresses back to their system default ip_tpgroups. Reassigning IP Addresses may result in termination of sessions already in progress on those IP Addresses. The command prompts for confirmation if any active sessions will be affected, unless the -f flag is specified. iscsi ip_tpgroup destroy [-f] <tpgroup_name> Destroy a user-defined IP-based target portal group. Data ONTAP assigns any IP Addresses that are members of the ip_tpgroup back to their system default ip_tpgroups. Reassigning IP Addresses may result in termination of sessions already in progress on those IP Addresses. The command prompts for confirmation if any active sessions will be affected, unless the -f flag is specified. iscsi portal show Display the list of target portals (IP address, TCP port number) over which the filer is currently making available the iSCSI service. Asymmetric Logical Unit Access (ALUA) management Data ONTAP supports SCSI ALUA functionality for managing multi-pathed SCSI devices. ALUA provides a standardized mechanism for path discovery and prioritization. Devices are identified by target port IDs, which are then grouped into target port
groups
Each group has a state which, when configured, enables the host multipathing software to select the appropriate path priorities when accessing a LUN.
For iSCSI, ALUA settings are controlled at the target portal group level using the iscsi tpgroup alua set command. A target portal group can be configured to be either optimized or non-optimized; a host typically uses all the optimized paths
before
using any non-optimized paths it may find. All target portal groups are optimized by default.
There is also an optional preferred setting that may be used on a target portal group. Check your host's multipathing software documentation to see if it supports ALUA and the preferred setting. ALUA is enabled on Initiator Groups using the igroup set command. All LUNs mapped to an ALUA enabled igroup will support ALUA functionality. iscsi tpgroup alua show Display the ALUA settings for all iSCSI target portal groups. iscsi tpgroup alua set <tpgroup_name> { optimized non-optimized } [preferred] Configure ALUA priorities for a target portal group. If the preferred argument is not given then the target portal group will not be configured as preferred. Security Parameters
ONTAP supports the configuration of default and per-initiator authentication parameters; these parameters are used during the iSCSI connection login phase. Initiators may be allowed access only after successfully performing the CHAP authentication procedure; or may be allowed access without CHAP authentication; or denied access. iscsi security add -i <initiator> -s CHAP -p <inpassword>
-n <inname> [ -o <outpassword> -m <outname> ] Configure the initiator with CHAP as the authentication method. The -p option is used to specify the inbound CHAP password and the -n option to specify the inbound CHAP username. The -o option is used to specify the outbound CHAP password and the -m option is used to specify the outbound CHAP name. The outbound CHAP password and username are optional and need to be configured if mutual authentication is desired. If the password is not specified on the command line then the administrator is prompted for the password twice. iscsi security add -i <initiator> -s { deny | none } Configure the initiator with the authentication method as deny or none. If the authentication method is deny then the specified initiator will be denied access. If the authentication method is chosen as none then no authentication would be done for the specified initiator. iscsi security default -s CHAP -p <inpassword> -n <inname>
[ -o <outpassword> -m <outname> ] Configure the default authentication method as CHAP. The default authentication parameters apply to any initiator which is not configured with a specific authentication method via the add command. The -p option is used to specify the inbound CHAP password and the -n option to specify the inbound CHAP username. The -o option is used to specify the outbound CHAP password and the -m option is used to specify the outbound CHAP name. The outbound CHAP password and username are optional and need to be configured if mutual authentication is desired. If the password is not specified on the command line then the administator is prompted for the password twice. iscsi security default -s { deny | none } Configure the default authentication method as deny or none. The default authentication parameters apply to any initiator which is not configured with a specific authentication method via the add command. iscsi security delete -i <initiator> Remove the initiator from the authentication list. The default authentication would now be applied for this initiator. iscsi security show Display the default authentication and all the initiator specific authentication information. iscsi security generate Generate a 128 bit Random password that can be used as a CHAP secret. iSNS Server Registration
ONTAP supports registration with an external iSNS server. Large-scale installations may choose to use the iSNS mechanism for centralized management and automatic device discovery. The iscsi isns command is used to configure and manage the filer's interaction with an iSNS server. iscsi isns config <hostname> | <ip_addr> Configure the iSNS service with the hostname or IP address of the iSNS server. The ip_addr is an Internet address expressed in the Internet standard dot notation for IPv4 addresses and Standard/Compressed/Mixed notation for IPv6 addresses. Configuration of the iSNS service should take place before the iSNS service is started. The -i ip_addr option will continue to work for backwards compatability, but has been deprecated. iscsi isns show Show the iSNS service configuration. This includes the entity_id_string (EID), the ip_addr of the iSNS server and if the service is enabled. iscsi isns start Start the iSNS service. This will start the iSNS service and automatically register with the iSNS server. It is best to configure the iSNS service before starting it. iscsi isns stop Stop the iSNS service. This will disable the ability to register with the iSNS server and to be discovered by iSNS clients. iscsi isns update Force an update of the registration information with the iSNS server.

CLUSTER CONSIDERATIONS

Each filer in a cluster operates as an independent iSCSI target device, with its own iSCSI nodename and alias. During a cluster takeover, the takeover filer assumes the iSCSI identity of the failed filer, including its nodename and portals, and services incoming iSCSI requests on behalf of the failed filer.

VFILER CONSIDERATIONS

When run from a vfiler context (e.g. via the vfiler run command), iscsi subcommands operate on the concerned vfiler with the following exceptions: iscsi stats subcommand: the statistics displayed apply to the entire physical filer and not to individual vfilers; iscsi interface subcommand: filer interfaces are physical filer attributes; iscsi interface accesslist subcommand: all filer interfaces can be added to the accesslist of the vfiler but the initiator will only be able to access the interfaces bound to the vfiler's IP addresses; iscsi tpgroup subcommand: target portal group assignments apply to the entire filer. iscsi ip_tpgroup subcommand: IP-based target portal group assignments are not available on default filer.

EXAMPLES

Set the iSCSI target nodename to a new value:
    filer> iscsi nodename iqn.1992-08.com.vendor:sn.mytarget
Start and stop the iSCSI service:
    filer> iscsi start
    filer> iscsi stop
Display all initiators currently connected to the filer:
    filer> iscsi initiator show
    Initiators connected:
    TSIH  TPGroup  Initiator
      26    1001   iqn.1992-08.com.vendor:host1 / 00:00:00:00:00:00
Display current iSCSI statistics:
    filer> iscsi stats

    iSCSI PDUs Received
      SCSI-Cmd:   15236 | Nop-Out:      0  | SCSI TaskMgtCmd:      0
      LoginReq:       3 | LogoutReq:    1  | Text Req:             1
      DataOut:        0 | SNACK:        0  | Unknown:              0
      Total: 15241
    iSCSI PDUs Transmitted
      SCSI-Rsp:   15173 | Nop-In:       0  | SCSI TaskMgtRsp:      0
      LoginRsp:       3 | LogoutRsp:    1  | Text Rsp:             1
      Data_In:    60743 | R2T:          0  | Reject:               0
      Total: 75921
    iSCSI CDBs
      DataIn Blocks:     1942288  | DataOut Blocks:          0
      Error Status:            0  | Success Status:      15221
      Total CDBs: 15221
    iSCSI ERRORS
      Failed Logins:           1  | Failed TaskMgt:          0
      Failed Logouts:          0  | Failed TextCmd:          0
      Protocol:                1
      Digest:                  0
      Unexpected session disconnects:      0
      PDU discards (outside CmdSN window): 0
      PDU discards (invalid header):       0
      Total: 2
Disable use of a network interface for the iSCSI service:
    filer> iscsi interface disable e0
    filer> iscsi interface show
    Interface e0 disabled
    Interface e5 enabled
    Interface e11a enabled
    Interface e11b enabled
Create an accesslist for initiator iqn.1995-07.com.vendor:host1 with two interfaces:
    filer> iscsi interface accesslist add iqn.1995-07.com.vendor:host1 e0 e11a
List target portal groups:
    filer> iscsi tpgroup show
    TPGTag  Name          Member Interfaces
     1000   e0_default    e0
     1001   e5_default    e5
     1002   e11a_default  e11a
     1003   e11b_default  e11b
Create a user-defined target portal group with a specific target portal group tag:
    filer> iscsi tpgroup create -t 10 dev_tpgroup e11a e11b
List network portal over which the filer is conducting the iSCSI service:
    filer> iscsi portal show
    Network portals:
    IP address        TCP Port  TPGroup  Interface
    192.168.10.10        3260    3000    e5
    192.168.20.10        3260    4000    e11a
    192.168.20.11        3260    4000    e11b
List IP_based target portal groups:
  vfiler2@filer> iscsi ip_tpgroup show
  TPGTag  Name                    Member IP Addresses
     32   user_defined_tp1        (none)
     64   user_defined_tp2        192.168.10.10, 192.168.10.11
   1007   e10a_default            10.60.155.7
   1008   e10b_default            10.60.155.8
   4001   10.60.155.104_default   10.60.155.104
Create a user-defined IP-based target portal group with a specific target portal group tag:
    filer> iscsi ip_tpgroup create -t 64 user_defined_tp2 192.168.10.10, 192.168.10.11
Add initiator iqn.1995-07.com.vendor:host1 to the configuration list with CHAP as the authentication method, pass as the CHAP password, and name as the CHAP name:
    filer> iscsi security add -i iqn.1995-07.com.vendor:host1 -s CHAP -p pass -n name
Do not allow access by initiator eui.123456789abcdef0:
    filer> iscsi security add -i eui.123456789abcdef0 -s deny
Display the configured security parameters:
    filer> iscsi security show
Set the default security method as CHAP with pass as the CHAP password and name as CHAP name:
    filer> iscsi security default -s CHAP -p pass -n name
Show the configuration of the iSNS service:
    filer> iscsi isns show

    iSNS Entity id:          entity1
    iSNS Server ip-addr:     192.168.1.1
    iSNS Status:             Enabled
Start or stop the iSNS service:
    filer> iscsi isns start
    filer> iscsi isns stop
Configure the iSNS service using the hostname or IP address of the iSNS server:
    filer> iscsi isns config server.foo.com
    filer> iscsi isns config 192.168.1.1

SEE ALSO

na_vfiler(1), na_igroup(1), na_fcp(1), na_lun(1), na_san(1)
Table of Contents