CTL.CONF(5) FreeBSD File Formats Manual CTL.CONF(5)
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) 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 Size in bytes of the
maximum data payload
size for data PDUs
accepted from remote
hosts. The value
must be at least 4KiB
and must be a
multiple of 4.
SQFC false any Always enable SQ flow
control.
HDGST false TCP Enable PDU header
digests if requested
by a remote host.
DDGST false TCP Enable PDU data
digests if requested
by a remote host.
max_admin_qsize 4096 any The maximum number of
entries a remote host
can request for an
admin queue pair.
max_io_qsize 65536 any The maximum number of
entries a remote host
can request for an
I/O queue pair.
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)
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).
path path
The path to the file, device node, or zfs(8) 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) 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), ctladm(8), ctld(8), zfs(8)
AUTHORS
The ctl.conf configuration file functionality for ctld(8) was developed
by Edward Tomasz Napierala <trasz@FreeBSD.org> under sponsorship from the
FreeBSD Foundation.
FreeBSD 15.1-STABLE-HBSD August 6, 2025 CTL.CONF(5)