share/man/man4/ctl.4

   1 .\" Copyright (c) 2013 Edward Tomasz Napierala
   2 .\" Copyright (c) 2015 Alexander Motin <mav@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .Dd September 27, 2015
  28 .Dt CTL 4
  29 .Os
  30 .Sh NAME
  31 .Nm ctl
  32 .Nd CAM Target Layer / iSCSI target
  33 .Sh SYNOPSIS
  34 To compile this driver into the kernel,
  35 place the following line in your
  36 kernel configuration file:
  37 .Bd -ragged -offset indent
  38 .Cd "device iscsi"
  39 .Cd "device ctl"
  40 .Ed
  41 .Pp
  42 Alternatively, to load the driver as a
  43 module at boot time, place the following line in
  44 .Xr loader.conf 5 :
  45 .Bd -literal -offset indent
  46 ctl_load="YES"
  47 .Ed
  48 .Sh DESCRIPTION
  49 The
  50 .Nm
  51 subsystem provides SCSI disk and processor emulation.
  52 It supports features such as:
  53 .Pp
  54 .Bl -bullet -compact
  55 .It
  56 Disk, processor and cdrom device emulation
  57 .It
  58 Tagged queueing
  59 .It
  60 SCSI task attribute support (ordered, head of queue, simple tags)
  61 .It
  62 SCSI implicit command ordering support
  63 .It
  64 Full task management support (abort, LUN reset, target reset, etc.)
  65 .It
  66 Support for multiple ports
  67 .It
  68 Support for multiple simultaneous initiators
  69 .It
  70 Support for multiple simultaneous backing stores
  71 .It
  72 Support for VMWare VAAI: COMPARE AND WRITE, XCOPY, WRITE SAME,
  73 and UNMAP commands
  74 .It
  75 Support for Microsoft ODX: POPULATE TOKEN/WRITE USING TOKEN,
  76 WRITE SAME, and UNMAP commands
  77 .It
  78 Persistent reservation support
  79 .It
  80 Mode sense/select support
  81 .It
  82 Error injection support
  83 .It
  84 High Availability clustering support with ALUA
  85 .It
  86 All I/O handled in-kernel, no userland context switch overhead
  87 .El
  88 .Pp
  89 It also serves as a kernel component of the native iSCSI target.
  90 .Sh SYSCTL VARIABLES
  91 The following variables are available as both
  92 .Xr sysctl 8
  93 variables and
  94 .Xr loader 8
  95 tunables:
  96 .Bl -tag -width indent
  97 .It Va kern.cam.ctl.debug
  98 Bit mask of enabled CTL log levels:
  99 .Bl -tag -offset indent -compact
 100 .It 1
 101 log commands with errors;
 102 .It 2
 103 log all commands;
 104 .It 4
 105 log data for commands other then READ/WRITE.
 106 .El
 107 Defaults to 0.
 108 .It Va kern.cam.ctl.ha_id
 109 Specifies unique position of this node within High Availability cluster.
 110 Default is 0 -- no HA, 1 and 2 -- HA enabled at specified position.
 111 .It Va kern.cam.ctl.ha_mode
 112 Specifies High Availability cluster operation mode:
 113 .Bl -tag -offset indent -compact
 114 .It 0
 115 Active/Standby -- primary node has backend access and processes requests,
 116 while secondary can only do basic LUN discovery and reservation;
 117 .It 1
 118 Active/Active -- both nodes have backend access and process requests,
 119 while secondary node synchronizes processing with primary one;
 120 .It 2
 121 Active/Active -- primary node has backend access and processes requests,
 122 while secondary node forwards all requests and data to primary one;
 123 .El
 124 All above modes require established connection between HA cluster nodes.
 125 If connection is not configured, secondary node will report Unavailable
 126 state; if configured but not established -- Transitioning state.
 127 Defaults to 0.
 128 .It Va kern.cam.ctl.ha_peer
 129 String value, specifying method to establish connection to peer HA node.
 130 Can be "listen IP:port", "connect IP:port" or empty.
 131 .It Va kern.cam.ctl.ha_link
 132 Reports present state of connection between HA cluster nodes:
 133 .Bl -tag -offset indent -compact
 134 .It 0
 135 not configured;
 136 .It 1
 137 configured but not established;
 138 .It 2
 139 established.
 140 .El
 141 .It Va kern.cam.ctl.ha_role
 142 Specifies default role of this node:
 143 .Bl -tag -offset indent -compact
 144 .It 0
 145 primary;
 146 .It 1
 147 secondary.
 148 .El
 149 This role can be overriden on per-LUN basis using "ha_role" LUN option,
 150 so that for one LUN one node is primary, while for another -- another.
 151 Role change from primary to secondary for HA modes 0 and 2 closes backends,
 152 the opposite change -- opens.
 153 If there is no primary node (both nodes are secondary, or secondary node has
 154 no connection to primary one), secondary node(s) report Transitioning state.
 155 State with two primary nodes is illegal (split brain condition).
 156 .It Va kern.cam.ctl.iscsi.debug
 157 Verbosity level for log messages from the kernel part of iSCSI target.
 158 Set to 0 to disable logging or 1 to warn about potential problems.
 159 Larger values enable debugging output.
 160 Defaults to 1.
 161 .It Va kern.cam.ctl.iscsi.maxcmdsn_delta
 162 The number of outstanding commands to advertise to the iSCSI initiator.
 163 Technically, it is the difference between ExpCmdSN and MaxCmdSN fields
 164 in the iSCSI PDU.
 165 Defaults to 256.
 166 .It Va kern.cam.ctl.iscsi.ping_timeout
 167 The number of seconds to wait for the iSCSI initiator to respond to a NOP-In
 168 PDU.
 169 In the event that there is no response within that time the session gets
 170 forcibly terminated.
 171 Set to 0 to disable sending NOP-In PDUs.
 172 Defaults to 5.
 173 .Sh SEE ALSO
 174 .Xr ctladm 8 ,
 175 .Xr ctld 8 ,
 176 .Xr ctlstat 8
 177 .Sh HISTORY
 178 The
 179 .Nm
 180 subsystem first appeared in
 181 .Fx 9.1 .
 182 .Sh AUTHORS
 183 The
 184 .Nm
 185 subsystem was originally written by
 186 .An Kenneth Merry Aq Mt ken@FreeBSD.org .
 187 Later work was done by
 188 .An Alexander Motin Aq Mt mav@FreeBSD.org .