--- name: "ctl.conf" section: "5" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd"] url: "https://new.carta.tech/ctl.conf" --- # ctl.conf(5) CAM Target Layer / iSCSI target / NVMeoF controller daemon configuration file ## NAME **ctl.conf** – CAM Target Layer / iSCSI target / NVMeoF controller daemon configuration file ## DESCRIPTION The **ctl.conf** configuration file is used by the [ctld(8)](/ctld/8.md) daemon. Lines starting with ‘#’ are interpreted as comments. The general syntax of the **ctl.conf** file is: ``` pidfile path auth-group name { chap user secret ``` ``` ... ``` } portal-group *name* { ``` listen address ``` ``` discovery-auth-group name ``` ``` ... ``` } transport-group *name* { ``` listen transport address ``` ``` ... ``` } target *name* *{* ``` auth-group name ``` ``` portal-group name ``` ``` lun number { ``` ``` path path ``` ``` } ``` ``` ... ``` } controller *name* *{* ``` auth-group name ``` ``` transport-group name ``` ``` namespace number { ``` ``` path path ``` ``` } ``` ``` ... ``` } ### Global Context - **auth-group** *name* Create an **auth-group** configuration context, defining a new auth-group, which can then be assigned to any number of targets. - **debug** *level* The debug verbosity level. The default is 0. - **maxproc** *number* The limit for concurrently running child processes handling incoming connections. The default is 30. A setting of 0 disables the limit. - **pidfile** *path* The path to the pidfile. The default is */var/run/ctld.pid*. - **portal-group** *name* Create a **portal-group** configuration context, defining a new portal-group, which can then be assigned to any number of targets. - **transport-group** *name* Create a **transport-group** configuration context, defining a new transport-group, which can then be assigned to any number of NVMeoF controllers. - **lun** *name* Create a **lun** configuration context, defining a LUN to be exported by any number of targets or controllers. - **target** *name* Create a **target** configuration context, which can optionally contain one or more **lun** contexts. - **controller** *name* Create a **controller** configuration context, which can optionally contain one or more **namespace** contexts. - **timeout** *seconds* The timeout for login sessions, after which the connection will be forcibly terminated. The default is 60. A setting of 0 disables the timeout. - **isns-server** *address* An IPv4 or IPv6 address and optionally port of iSNS server to register on. - **isns-period** *seconds* iSNS registration period. Registered Network Entity not updated during this period will be unregistered. The default is 900. - **isns-timeout** *seconds* Timeout for iSNS requests. The default is 5. ### auth-group Context - **auth-type** *type* Sets the authentication type. Type can be either "*none*", "*deny*", "*chap*", or "*chap-mutual*". In most cases it is not necessary to set the type using this clause; it is usually used to disable authentication for a given **auth-group**. - **chap** *user* *secret* A set of CHAP authentication credentials. Note that for any **auth-group**, the configuration may only contain either **chap** or **chap-mutual** entries; it is an error to mix them. - **chap-mutual** *user* *secret* *mutualuser* *mutualsecret* A set of mutual CHAP authentication credentials. Note that for any **auth-group**, the configuration may only contain either **chap** or **chap-mutual** entries; it is an error to mix them. - **host-address** *address*\[/*prefixlen*\] An NVMeoF host address: an IPv4 or IPv6 address, optionally followed by a literal slash and a prefix length. Only NVMeoF hosts with an address matching one of the defined addresses will be allowed to connect. If not defined, there will be no restrictions based on host address. - **host-nqn** *name* An NVMeoF host name. Only NVMeoF hosts with a name matching one of the defined names will be allowed to connect. If not defined, there will be no restrictions based on NVMe host name. - **initiator-name** *initiator-name* An iSCSI initiator name. Only initiators with a name matching one of the defined names will be allowed to connect. If not defined, there will be no restrictions based on initiator name. - **initiator-portal** *address*\[/*prefixlen*\] An iSCSI initiator portal: an IPv4 or IPv6 address, optionally followed by a literal slash and a prefix length. Only initiators with an address matching one of the defined addresses will be allowed to connect. If not defined, there will be no restrictions based on initiator address. ### portal-group Context - **discovery-auth-group** *name* Assign a previously defined authentication group to the portal group, to be used for target discovery. By default, portal groups are assigned predefined **auth-group** "*default*", which denies discovery. Another predefined **auth-group**, "*no-authentication*", may be used to permit discovery without authentication. - **discovery-filter** *filter* Determines which targets are returned during discovery. Filter can be either "*none*", "*portal*", "*portal-name*", or "*portal-name-auth*". When set to "*none*", discovery will return all targets assigned to that portal group. When set to "*portal*", discovery will not return targets that cannot be accessed by the initiator because of their **initiator-portal**. When set to "*portal-name*", the check will include both **initiator-portal** and **initiator-name**. When set to "*portal-name-auth*", the check will include **initiator-portal**, **initiator-name**, and authentication credentials. The target is returned if it does not require CHAP authentication, or if the CHAP user and secret used during discovery match those used by the target. Note that when using "*portal-name-auth*", targets that require CHAP authentication will only be returned if **discovery-auth-group** requires CHAP. The default is "*none*". - **listen** *address* An IPv4 or IPv6 address and port to listen on for incoming connections. - **offload** *driver* Define iSCSI hardware offload driver to use for this **portal-group**. The default is "*none*". - **option** *name* *value* The CTL-specific port options passed to the kernel. - **redirect** *address* IPv4 or IPv6 address to redirect initiators to. When configured, all initiators attempting to connect to portal belonging to this **portal-group** will get redirected using "Target moved temporarily" login response. Redirection happens before authentication and any **initiator-name** or **initiator-portal** checks are skipped. - **tag** *value* Unique 16-bit tag value of this **portal-group**. If not specified, the value is generated automatically. - **foreign** Specifies that this **portal-group** is listened by some other host. This host will announce it on discovery stage, but won't listen. - **dscp** *value* The DiffServ Codepoint used for sending data. The DSCP can be set to numeric, or hexadecimal values directly, as well as the well-defined "*CSx*" and "*AFxx*" codepoints. - **pcp** *value* The 802.1Q Priority CodePoint used for sending packets. The PCP can be set to a value in the range between "*0*" to "*7*". When omitted, the default for the outgoing interface is used. ### transport-group Context - **discovery-auth-group** *name* See the description for this option for **portal-group** contexts. - **discovery-filter** *filter* Filter can be either "*none*", "*address*", or "*address-name*". When set to "*none*", discovery will return all controllers assigned to that transport group. When set to "*address*", discovery will not return controllers that cannot be accessed by the host because of their **host-address**. When set to "*address-name*", the check will include both **host-address** and **host-nqn**. The default is "*none*". - **listen** *transport* *address* An IPv4 or IPv6 address and port to listen on for incoming connections using the specified NVMeoF transport. Supported transports are "*tcp*" (for NVMe/TCP I/O controllers) and "*discovery-tcp*" (for NVMe/TCP discovery controllers). - **option** *name* *value* One of the following options: | | | | | | --- | --- | --- | --- | | **Name** | **Default** | **Transports** | **Description** | | MAXH2CDATA | 256KiB | TCP | | | SQFC | false | any | | | HDGST | false | TCP | | | DDGST | false | TCP | | | max\_admin\_qsize | 4096 | any | | | max\_io\_qsize | 65536 | any | | - **tag** *value* Unique 16-bit port ID for this **transport-group**. If not specified, the value is generated automatically. - **dscp** *value* See the description for this option for **portal-group** contexts. - **pcp** *value* See the description for this option for **portal-group** contexts. ### target Context - **alias** *text* Assign a human-readable description to the target. There is no default. - **auth-group** *name* Assign a previously defined authentication group to the target. By default, targets that do not specify their own auth settings, using clauses such as **chap** or **initiator-name**, are assigned predefined **auth-group** "*default*", which denies all access. Another predefined **auth-group**, "*no-authentication*", may be used to permit access without authentication. Note that this clause can be overridden using the second argument to a **portal-group** clause. - **auth-type** *type* Sets the authentication type. Type can be either "*none*", "*deny*", "*chap*", or "*chap-mutual*". In most cases it is not necessary to set the type using this clause; it is usually used to disable authentication for a given **target**. This clause is mutually exclusive with **auth-group**; one cannot use both in a single target. - **chap** *user* *secret* A set of CHAP authentication credentials. Note that targets must only use one of **auth-group**, **chap**, or **chap-mutual**; it is a configuration error to mix multiple types in one target. - **chap-mutual** *user* *secret* *mutualuser* *mutualsecret* A set of mutual CHAP authentication credentials. Note that targets must only use one of **auth-group**, **chap**, or **chap-mutual**; it is a configuration error to mix multiple types in one target. - **initiator-name** *initiator-name* An iSCSI initiator name. Only initiators with a name matching one of the defined names will be allowed to connect. If not defined, there will be no restrictions based on initiator name. This clause is mutually exclusive with **auth-group**; one cannot use both in a single target. - **initiator-portal** *address*\[/*prefixlen*\] An iSCSI initiator portal: an IPv4 or IPv6 address, optionally followed by a literal slash and a prefix length. Only initiators with an address matching one of the defined addresses will be allowed to connect. If not defined, there will be no restrictions based on initiator address. This clause is mutually exclusive with **auth-group**; one cannot use both in a single target. The **auth-type**, **chap**, **chap-mutual**, **initiator-name**, and **initiator-portal** clauses in the target context provide an alternative to assigning an **auth-group** defined separately, useful in the common case of authentication settings specific to a single target. - **portal-group** *name* \[*ag-name*\] Assign a previously defined portal group to the target. The default portal group is "*default*", which makes the target available on TCP port 3260 on all configured IPv4 and IPv6 addresses. Optional second argument specifies **auth-group** for connections to this specific portal group. If second argument is not specified, target **auth-group** is used. - **port** *name* - **port** *name/pp* - **port** *name/pp/vp* Assign specified CTL port (such as "isp0" or "isp2/1") to the target. This is used to export the target through a specific physical - eg Fibre Channel - port, in addition to portal-groups configured for the target. Use **ctladm portlist** command to retrieve the list of available ports. On startup [ctld(8)](/ctld/8.md) configures LUN mapping and enables all assigned ports. Each port can be assigned to only one target. - **redirect** *address* IPv4 or IPv6 address to redirect initiators to. When configured, all initiators attempting to connect to this target will get redirected using "Target moved temporarily" login response. Redirection happens after successful authentication. - **lun** *number* *name* Export previously defined **lun** by the parent target. - **lun** *number* Create a **lun** configuration context, defining a LUN exported by the parent target. This is an alternative to defining the LUN separately, useful in the common case of a LUN being exported by a single target. ### controller Context - **auth-group** *name* Assign a previously defined authentication group to the controller. By default, controllers that do not specify their own auth settings, using clauses such as **host-address** or **host-nqn**, are assigned to the predefined **auth-group** "*default*", which denies all access. Another predefined **auth-group**, "*no-authentication*", may be used to permit access without authentication. Note that this clause can be overridden using the second argument to a **transport-group** clause. - **auth-type** *type* Sets the authentication type. Type can be either "*none*" or "*deny*". In most cases it is not necessary to set the type using this clause; it is usually used to disable authentication for a given **controller**. This clause is mutually exclusive with **auth-group**; one cannot use both in a single controller. - **host-address** *address*\[/*prefixlen*\] An NVMeoF host address: an IPv4 or IPv6 address, optionally followed by a literal slash and a prefix length. Only NVMeoF hosts with an address matching one of the defined addresses will be allowed to connect. If not defined, there will be no restrictions based on host address. This clause is mutually exclusive with **auth-group**; one cannot use both in a single controller. - **host-nqn** *name* An NVMeoF host name. Only NVMeoF hosts with a name matching one of the defined names will be allowed to connect. If not defined, there will be no restrictions based on NVMe host name. This clause is mutually exclusive with **auth-group**; one cannot use both in a single target. The **auth-type**, **host-address**, and **host-nqn** clauses in the controller context provide an alternative to assigning an **auth-group** defined separately, useful in the common case of authentication settings specific to a single controller. - **transport-group** *name* \[*ag-name*\] Assign a previously defined transport group to the controller. The default transport group is "*default*", which makes the controller available on TCP port 4420 on all configured IPv4 and IPv6 addresses. The optional second argument specifies the **auth-group** for connections to this specific transport group group. If the second argument is not specified, the controller **auth-group** is used. - **namespace** *number* *name* Export previously defined **lun** as an NVMe namespace from the parent controller. - **namespace** *number* Create a **namespace** configuration context, defining an NVMe namespace exported by the parent target. This is an alternative to defining the namespace separately, useful in the common case of a namespace being exported by a single controller. **namespace** configuration contexts accept the the same properties as **lun** contexts. ### lun Context - **backend** *block* \| *ramdisk* The CTL backend to use for a given LUN. Valid choices are "*block*" and "*ramdisk*"; block is used for LUNs backed by files or disk device nodes; ramdisk is a bitsink device, used mostly for testing. The default backend is block. - **blocksize** *size* The blocksize visible to the initiator. The default blocksize is 512 for disks, and 2048 for CD/DVDs. - **ctl-lun** *lun\_id* Global numeric identifier to use for a given LUN inside CTL. By default CTL allocates those IDs dynamically, but explicit specification may be needed for consistency in HA configurations. - **device-id** *string* The SCSI Device Identification string presented to iSCSI initiators. - **device-type** *type* Specify the SCSI device type to use when creating the LUN. Currently CTL supports Direct Access (type 0), Processor (type 3) and CD/DVD (type 5) LUNs. - **option** *name* *value* The CTL-specific options passed to the kernel. All CTL-specific options are documented in the OPTIONS section of [ctladm(8)](/ctladm/8.md). - **path** *path* The path to the file, device node, or [zfs(8)](/zfs/8.md) volume used to back the LUN. For optimal performance, create ZFS volumes with the "*volmode=dev*" property set. - **serial** *string* The SCSI serial number presented to iSCSI initiators. - **size** *size* The LUN size, in bytes or by number with a suffix of **K**, **M**, **G**, **T** (for kilobytes, megabytes, gigabytes, or terabytes). When the configuration is in UCL format, use the suffix format **kKmMgG**\|**bB**, (i.e., 4GB, 4gb, and 4Gb are all equivalent). ## FILES - */etc/ctl.conf* The default location of the [ctld(8)](/ctld/8.md) configuration file. ## EXAMPLES ``` auth-group ag0 { chap-mutual "user" "secret" "mutualuser" "mutualsecret" chap-mutual "user2" "secret2" "mutualuser" "mutualsecret" initiator-portal 192.168.1.1/16 } auth-group ag1 { auth-type none initiator-name "iqn.2012-06.com.example:initiatorhost1" initiator-name "iqn.2012-06.com.example:initiatorhost2" initiator-portal 192.168.1.1/24 initiator-portal [2001:db8::de:ef] } portal-group pg0 { discovery-auth-group no-authentication listen 0.0.0.0:3260 listen [::]:3260 listen [fe80::be:ef]:3261 } target iqn.2012-06.com.example:target0 { alias "Example target" auth-group no-authentication lun 0 { path /dev/zvol/tank/example_0 blocksize 4096 size 4G } } lun example_1 { path /dev/zvol/tank/example_1 option naa 0x50015178f369f093 } target iqn.2012-06.com.example:target1 { auth-group ag0 portal-group pg0 lun 0 example_1 lun 1 { path /dev/zvol/tank/example_2 option vendor "FreeBSD" } } target naa.50015178f369f092 { port isp0 port isp1 lun 0 example_1 } controller nqn.2012-06.com.example:controller1 { auth-group no-authentication; namespace 1 example_1 namespace 2 { backend ramdisk size 1G option capacity 1G } } ``` An equivalent configuration in UCL format, for use with **-u**: ``` auth-group { ag0 { chap-mutual = [ { user = "user" secret = "secretsecret" mutual-user = "mutualuser" mutual-secret = "mutualsecret" }, { user = "user2" secret = "secret2secret2" mutual-user = "mutualuser" mutual-secret = "mutualsecret" } ] } ag1 { auth-type = none initiator-name = [ "iqn.2012-06.com.example:initiatorhost1", "iqn.2012-06.com.example:initiatorhost2" ] initiator-portal = [192.168.1.1/24, "[2001:db8::de:ef]"] } } portal-group { pg0 { discovery-auth-group = no-authentication listen = [ 0.0.0.0:3260, "[::]:3260", "[fe80::be:ef]:3261" ] } } lun { example_1 { path = /dev/zvol/tank/example_1 options { naa = "0x50015178f369f093" } } } target { "iqn.2012-06.com.example:target0" { alias = "Example target" auth-group = no-authentication lun = { 0 { path = /dev/zvol/tank/example_0 blocksize = 4096 size = 4GB } } } "iqn.2012-06.com.example:target1" { auth-group = ag0 portal-group = pg0 lun { 0 = example_1 1 { path = /dev/zvol/tank/example_2 options { vendor = "FreeBSD" } } } } naa.50015178f369f092 { port = isp0 lun { 0 = example_1 } } } controller { "nqn.2012-06.com.example:controller1" { auth-group = no-authentication namespace = { 1 = example_1, 2 { backend = ramdisk size = 1G options { capacity = 1G } } } } } ``` ## SEE ALSO [ctl(4)](/ctl/4.md), [ctladm(8)](/ctladm/8.md), [ctld(8)](/ctld/8.md), [zfs(8)](/zfs/8.md) ## AUTHORS The **ctl.conf** configuration file functionality for [ctld(8)](/ctld/8.md) was developed by Edward Tomasz Napierala ⟨*trasz@FreeBSD.org*⟩ under sponsorship from the FreeBSD Foundation.