usr.sbin/ctld/ctl.conf.5

   1 .\" Copyright (c) 2012 The FreeBSD Foundation
   2 .\" All rights reserved.
   3 .\"
   4 .\" This software was developed by Edward Tomasz Napierala under sponsorship
   5 .\" from the FreeBSD Foundation.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD$
  29 .\"
  30 .Dd December 2, 2013
  31 .Dt CTL.CONF 5
  32 .Os
  33 .Sh NAME
  34 .Nm ctl.conf
  35 .Nd CAM Target Layer / iSCSI target daemon configuration file
  36 .Sh DESCRIPTION
  37 The
  38 .Nm
  39 configuration file is used by the
  40 .Xr ctld 8
  41 daemon.
  42 Lines starting with
  43 .Ql #
  44 and empty lines are interpreted as comments.
  45 The general syntax of the
  46 .Nm
  47 file is:
  48 .Bd -literal -offset indent
  49 pidfile <path>
  50
  51 auth-group <name> {
  52         chap <user> <secret>
  53         ...
  54 }
  55
  56 portal-group <name> {
  57         listen <address>
  58         listen-iser <address>
  59         discovery-auth-group <name>
  60         ...
  61 }
  62
  63 target <name> {
  64         auth-group <name>
  65         portal-group <name>
  66         lun <number> {
  67                 path <path>
  68         }
  69         ...
  70 }
  71 .Ed
  72 .Ss global level
  73 The following statements are available at the global level:
  74 .Bl -tag -width indent
  75 .It Ic auth-group Aq Ar name
  76 Opens an auth-group section, defining an authentication group,
  77 which can then be assigned to any number of targets.
  78 .It Ic debug Aq Ar level
  79 Specifies debug level.
  80 The default is 0.
  81 .It Ic maxproc Aq Ar number
  82 Specifies limit for concurrently running child processes handling
  83 incoming connections.
  84 The default is 30.
  85 Setting it to 0 disables the limit.
  86 .It Ic pidfile Aq Ar path
  87 Specifies path to pidfile.
  88 The default is
  89 .Pa /var/run/ctld.pid .
  90 .It Ic portal-group Aq Ar name
  91 Opens a portal-group section, defining a portal group,
  92 which can then be assigned to any number of targets.
  93 .It Ic target Aq Ar name
  94 Opens a target configuration section.
  95 .It Ic timeout Aq Ar seconds
  96 Specifies timeout for login session, after which the connection
  97 will be forcibly terminated.
  98 The default is 60.
  99 Setting it to 0 disables the timeout.
 100 .El
 101 .Ss auth-group level
 102 The following statements are available at the auth-group level:
 103 .Bl -tag -width indent
 104 .It Ic chap Ao Ar user Ac Aq Ar secret
 105 Specifies CHAP authentication credentials.
 106 .It Ic chap-mutual Ao Ar user Ac Ao Ar secret Ac Ao Ar mutualuser Ac Aq Ar mutualsecret
 107 Specifies mutual CHAP authentication credentials.
 108 Note that for any auth-group, configuration may contain either chap,
 109 or chap-mutual entries; it's an error to mix them.
 110 .El
 111 .Ss portal-group level
 112 The following statements are available at the portal-group level:
 113 .Bl -tag -width indent
 114 .It Ic discovery-auth-group Aq Ar name
 115 Assigns previously defined authentication group to that portal group,
 116 to be used for target discovery.
 117 By default, the discovery will be denied.
 118 A special auth-group, "no-authentication", may be used to allow for discovery
 119 without authentication.
 120 .It Ic listen Aq Ar address
 121 Specifies IPv4 or IPv6 address and port to listen on for incoming connections.
 122 .It Ic listen-iser Aq Ar address
 123 Specifies IPv4 or IPv6 address and port to listen on for incoming connections
 124 using iSER (iSCSI over RDMA) protocol.
 125 .El
 126 .Ss target level:
 127 The following statements are available at the target level:
 128 .Bl -tag -width indent
 129 .It Ic alias Aq Ar text
 130 Assigns human-readable description to that target.
 131 There is no default.
 132 .It Ic auth-group Aq Ar name
 133 Assigns previously defined authentication group to that target.
 134 There is no default; every target must use either auth-group,
 135 or chap, or chap-mutual statements.
 136 A special auth-group, "no-authentication", may be used to permit access
 137 without authentication.
 138 .It Ic chap Ao Ar user Ac Aq Ar secret
 139 Specifies CHAP authentication credentials.
 140 Note that targets must use either auth-group, or chap,
 141 or chap-mutual clauses; it's a configuration error to mix them in one target.
 142 .It Ic chap-mutual Ao Ar user Ac Ao Ar secret Ac Ao Ar mutualuser Ac Aq Ar mutualsecret
 143 Specifies mutual CHAP authentication credentials.
 144 Note that targets must use either auth-group, chap, or
 145 chap-mutual clauses; it's a configuration error to mix them in one target.
 146 .It Ic portal-group Aq Ar name
 147 Assigns previously defined portal group to that target.
 148 Default portal group is "default", which makes the target available
 149 on TCP port 3260 on all configured IPv4 and IPv6 addresses.
 150 .It Ic lun Aq Ar number
 151 Opens a lun configuration section, defining LUN exported by a target.
 152 .El
 153 .Ss lun level
 154 The following statements are available at the lun level:
 155 .Bl -tag -width indent
 156 .It Ic backend Ao Ar block | Ar ramdisk Ac
 157 Specifies the CTL backend to use for a given LUN.
 158 Valid choices are
 159 .Dq block
 160 and
 161 .Dq ramdisk ;
 162 block is used for LUNs backed
 163 by files in the filesystem; ramdisk is a bitsink device, used mostly for
 164 testing.
 165 The default backend is block.
 166 .It Ic blocksize Aq Ar size
 167 Specifies blocksize visible to the initiator.
 168 The default blocksize is 512.
 169 .It Ic device-id Aq Ar string
 170 Specifies SCSI Device Identification string presented to the initiator.
 171 .It Ic option Ao Ar name Ac Aq Ar value
 172 Specifies CTL-specific options passed to the kernel.
 173 .It Ic path Aq Ar path
 174 Specifies path to file used to back the LUN.
 175 .It Ic serial Aq Ar string
 176 Specifies SCSI serial number presented to the initiator.
 177 .It Ic size Aq Ar size
 178 Specifies LUN size, in bytes.
 179 .El
 180 .Sh FILES
 181 .Bl -tag -width ".Pa /etc/ctl.conf" -compact
 182 .It Pa /etc/ctl.conf
 183 The default location of the
 184 .Xr ctld 8
 185 configuration file.
 186 .El
 187 .Sh EXAMPLES
 188 .Bd -literal
 189 pidfile /var/run/ctld.pid
 190
 191 auth-group example2 {
 192         chap-mutual "user" "secret" "mutualuser" "mutualsecret"
 193         chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
 194 }
 195
 196 portal-group example2 {
 197         discovery-auth-group no-authentication
 198         listen 127.0.0.1
 199         listen 0.0.0.0:3261
 200         listen [::]:3261
 201         listen [fe80::be:ef]
 202 }
 203
 204 target iqn.2012-06.com.example:target0 {
 205         alias "Testing target"
 206         auth-group no-authentication
 207         lun 0 {
 208                 path /dev/zvol/example_0
 209                 blocksize 4096
 210                 size 4G
 211         }
 212 }
 213
 214 target iqn.2012-06.com.example:target3 {
 215         chap chapuser chapsecret
 216         lun 0 {
 217                 path /dev/zvol/example_3
 218         }
 219 }
 220
 221 target iqn.2012-06.com.example:target2 {
 222         auth-group example2
 223         portal-group example2
 224         lun 0 {
 225                 path /dev/zvol/example2_0
 226         }
 227         lun 1 {
 228                 path /dev/zvol/example2_1
 229                 option foo bar
 230         }
 231 }
 232 .Ed
 233 .Sh SEE ALSO
 234 .Xr ctl 4 ,
 235 .Xr ctladm 8 ,
 236 .Xr ctld 8
 237 .Sh AUTHORS
 238 The
 239 .Nm
 240 configuration file functionality for
 241 .Xr ctld 8
 242 was developed by
 243 .An Edward Tomasz Napierala Aq trasz@FreeBSD.org
 244 under sponsorship from the FreeBSD Foundation.