Unix‎ > ‎Solaris‎ > ‎Solaris man pages‎ > ‎1m‎ > ‎

iscsitadm


NAME
     iscsitadm - administer iSCSI targets

SYNOPSIS
     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


DESCRIPTION
     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  refer-
               ence.


     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 ini-
                  tiator can use for a given target.


     stats        Displays statistics; can  accept  interval  and
                  count  values.  Used only with the show subcom-
                  mand.



     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.

OPTIONS
     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  EXAM-
     PLES.

  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 fol-
         lowed by a single letter. The letter is one of:

         k    kilobyte


         m    megabyte


         g    gigabyte


         t    terabyte

         --lun specifies the logical unit number.  --type  speci-
         fies  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 deter-
         mined 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.


     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 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.


  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 per-
         sistent 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 inaccessi-
         ble  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 corrup-
         tion  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 asynchronous event message to  the  ini-
         tiator.


     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 tar-
         gets, seeking those that reference  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 por-
         tal group identified by tpgt_number. This includes remo-
         val 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 con-
         nections.


  list Options
     The following are the options and objects for the list  sub-
     command:

     target [--verbose] [local_target]
     target [-v|-s num] [local_target]

         By default, displays a list of target local  names  fol-
         lowed  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 connec-
         tions 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 con-
         nections.


     tpgt [--verbose|-v] tpgt_number

         Displays detailed information about target group identi-
         fied 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  sub-
     command:


     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_target. 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.


EXAMPLES
     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  loca-
     tion, 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 pro-
     vided  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 ini-
     tiator. 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 dae-
     mon  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 tar-
     gets.


       # 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 tar-
     get.


       # 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



EXIT STATUS
     0     Command successful.


     >0    An error occurred.


ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWiscsitgtu               |
    |_____________________________|_____________________________|
    | Interface Stability         | Volatile                    |
    |_____________________________|_____________________________|


SEE ALSO
     iostat(1M), iscsiadm(1M), getpassphrase(3C),  attributes(5),
     rbac(5), smf(5)

NOTES
     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  ser-
     vice  management  facility (smf(5)), under the fault manage-
     ment 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  properties.  Such  actions  require  that  you
     become  superuser  or assume the Primary Administrator role.
     See rbac(5).










Man pages from Solaris 10 Update 8. See docs.sun.com and www.oracle.com for further documentation and Solaris information.
Comments