CTL.CONF(5)

📦
version 15.1 · 2 versions
, in freebsd 15.1

✨ CTL.CONF(5) ✨

Hey bestie! Welcome to ctl.conf(5) 💖 — the File Formats Manual page that's about to become your new obsession. No cap, this file is lowkey iconic.

🎀 NAME 🎀

ctl.conf — the configuration file for the CAM Target Layer / iSCSI target / NVMeoF controller daemon. Yes, that's a whole mouthful, but it's giving main character energy, so we move.

🌸 DESCRIPTION 🌸

Okay so the ctl.conf configuration file is what the ctld(8) daemon reads. Lines that start with #? Those are comments — literally just your notes to yourself, bestie. The general syntax of the ctl.conf file goes like this:

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 — Creates an auth-group configuration context. It defines a brand-new auth-group that you can then assign to any number of targets. Teamwork makes the dream work, fr fr.
  • debug level — Sets how chatty the debug output is. The default is 0. Adjust to your vibe.
  • maxproc number — The limit for how many child processes can run at once handling incoming connections. The default is 30. Setting it to 0 disables the limit entirely. Slay, unlimited power.
  • pidfile path — Where the pidfile lives. The default is /var/run/ctld.pid. Very demure, very mindful.
  • portal-group name — Creates a portal-group configuration context. It defines a new portal-group that you can assign to any number of targets. Obsessed.
  • transport-group name — Creates a transport-group configuration context. Defines a new transport-group that can be assigned to any number of NVMeoF controllers. Iconic behaviour.
  • lun name — Creates a lun configuration context. Defines a LUN to be exported by any number of targets or controllers. It's giving "share the wealth" energy.
  • target name — Creates a target configuration context, which can optionally contain one or more lun contexts. Nested and cute.
  • controller name — Creates a controller configuration context, which can optionally contain one or more namespace contexts. So organized.
  • timeout seconds — The timeout for login sessions. After this, the connection gets forcibly terminated. The default is 60. A setting of 0 disables the timeout. Choose your adventure wisely, bestie.
  • isns-server address — An IPv4 or IPv6 address and optionally a port of the iSNS server to register on. Drop that address, periodt.
  • isns-period seconds — The iSNS registration period. Any registered Network Entity that doesn't update during this period will get unregistered. The default is 900. Keep it fresh or get cut.
  • isns-timeout seconds — Timeout for iSNS requests. The default is 5. Quick, like your group chat replies.

🦋 auth-group Context 🦋

  • auth-type type — Sets the authentication type. Type can be either "none", "deny", "chap", or "chap-mutual". In most cases you don't need to set the type with this clause — it's usually there to disable authentication for a given auth-group. Sometimes you just gotta say "no thanks."
  • chap user secret — A set of CHAP authentication credentials. Real talk: for any auth-group, the configuration may only contain either chap or chap-mutual entries. Mixing them is an error. Pick a lane, bestie.
  • chap-mutual user secret mutualuser mutualsecret — A set of mutual CHAP authentication credentials. Same rule applies: for any auth-group, the configuration may only contain either chap or chap-mutual entries — it is an error to mix them. Mutual respect only.
  • 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 you don't define this, there are no restrictions based on host address. Let everyone in or gatekeep, your call.
  • 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. Name-drop accordingly.
  • initiator-name initiator-name — An iSCSI initiator name. Only initiators with a name matching one of the defined names will be allowed to connect. Not defined? No restrictions based on initiator name. The VIP list is optional.
  • 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. Location-based access, we love to see it.

🌈 portal-group Context 🌈

  • discovery-auth-group name — Assigns a previously defined authentication group to the portal group, used for target discovery. By default, portal groups are assigned the predefined auth-group "default", which denies discovery. Another predefined auth-group, "no-authentication", may be used to permit discovery without authentication. Choose wisely, bestie.
  • discovery-filter filter — Determines which targets get returned during discovery. Filter can be either "none", "portal", "portal-name", or "portal-name-auth".
    • When set to "none", discovery returns all targets assigned to that portal group. No filter, no stress.
    • When set to "portal", discovery won't return targets that the initiator can't access because of their initiator-portal. Respecting boundaries.
    • When set to "portal-name", the check includes both initiator-portal and initiator-name. Double-checking, we love it.
    • When set to "portal-name-auth", the check includes initiator-portal, initiator-name, and authentication credentials. The target is returned if it doesn't 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". So much detail, but we ate.
  • listen address — An IPv4 or IPv6 address and port to listen on for incoming connections. Open for business.
  • offload driver — Defines the iSCSI hardware offload driver to use for this portal-group. The default is "none". Hardware acceleration? Only if you ask nicely.
  • option name value — The CTL-specific port options passed to the kernel. Secret menu energy.
  • redirect address — An IPv4 or IPv6 address to redirect initiators to. When configured, all initiators attempting to connect to a 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. "Not here, go there" — very direct.
  • tag value — Unique 16-bit tag value of this portal-group. If not specified, the value is generated automatically. Let the system handle it, or take control.
  • foreign — Specifies that this portal-group is listened by some other host. This host will announce it on the discovery stage, but won't listen. It's like being the wingman — you point people in the right direction but stay out of it.
  • 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. Quality of service, but make it fashion.
  • 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. Priorities, we all have them.

🐚 transport-group Context 🐚

  • discovery-auth-group name — See the description for this option for portal-group contexts. Reusing the wisdom, love that for us.
  • discovery-filter filter — Filter can be either "none", "address", or "address-name".
    • When set to "none", discovery returns all controllers assigned to that transport group. No filter, no problem.
    • When set to "address", discovery won't return controllers that the host can't access because of their host-address. Setting boundaries.
    • When set to "address-name", the check includes both host-address and host-nqn. Double validation, very secure.
    • The default is "none". Keep it simple or lock it down.
  • 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). Pick your channel.
  • option name value — One of the following options, bestie. Here's the whole menu:
    • MAXH2CDATA — Default: 256KiB. Transports: 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. Big data energy, but with rules.
    • SQFC — Default: false. Transports: any. Always enable SQ flow control. "Just do it" mode.
    • HDGST — Default: false. Transports: TCP. Enable PDU header digests if requested by a remote host. Only if they ask.
    • DDGST — Default: false. Transports: TCP. Enable PDU data digests if requested by a remote host. Again, only if they ask.
    • max_admin_qsize — Default: 4096. Transports: any. The maximum number of entries a remote host can request for an admin queue pair. Cap it.
    • max_io_qsize — Default: 65536. Transports: any. The maximum number of entries a remote host can request for an I/O queue pair. Another cap, another slay.
  • tag value — Unique 16-bit port ID for this transport-group. If not specified, the value is generated automatically. Auto-magic or manual, your choice.
  • dscp value — See the description for this option for portal-group contexts. Same vibes, different context.

(To be continued in Part 2, bestie — don't go anywhere! 💖)

  • pcp value — bestie just peek at the description for this option over in the portal-group contexts section, it's the same vibe 💅

🎯 target Context 🎯

okay so this whole context is you hyping up one target — every clause below goes in here, no cap ✨

  • alias text — gives the target a human-readable description. There is no default, so if you want the cute label you gotta write it yourself 🎀
  • auth-group name — hands the target a previously defined authentication group. By default, targets that don't specify their own auth settings — like via clauses such as chap or initiator-name — get assigned the predefined auth-group "default", which denies all access 💀. There's another predefined one, "no-authentication", that you can use to permit access without authentication. Heads up: 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 you don't need to set the type with this clause; it's usually used to disable authentication for a given target. This clause is mutually exclusive with auth-group — you cannot use both in a single target, periodt 🙅
  • chap user secret — a set of CHAP authentication credentials. Note that targets must only use one of auth-group, chap, or chap-mutual; mixing multiple types in one target is a configuration error 🚨
  • chap-mutual user secret mutualuser mutualsecret — a set of mutual CHAP authentication credentials. Same deal: targets must only use one of auth-group, chap, or chap-mutual, and mixing multiple types in one target is a configuration error 🫶
  • 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 give you an alternative to assigning an auth-group defined separately — super useful in the common case where the auth settings are specific to a single target 💜

  • portal-group name [ag-name] — assigns 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. The optional second argument specifies the auth-group for connections to this specific portal group; if the second argument isn't specified, the target auth-group is used 🌈
  • port name port name/pp port name/pp/vp — assigns the specified CTL port (such as "isp0" or "isp2/1") to the target. This is how you export the target through a specific physical — eg Fibre Channel — port, in addition to portal-groups configured for the target. Use the 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 — the IPv4 or IPv6 address to redirect initiators to. When configured, all initiators attempting to connect to this target will get redirected using the "Target moved temporarily" login response. Redirection happens after successful authentication 🔥
  • lun number name — exports a previously defined lun by the parent target.
  • lun number — creates 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 🌀

NVMeoF girlies this one's for you — here's the whole clause lineup for a controller, bestie 😭🫶

  • auth-group name — assigns a previously defined authentication group to the controller. By default, controllers that don't specify their own auth settings — using clauses such as host-address or host-nqn — get 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's not necessary to set the type using this clause; it's 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 give you 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] — assigns 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 isn't specified, the controller auth-group is used.
  • namespace number name — exports a previously defined lun as an NVMe namespace from the parent controller.
  • namespace number — creates 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 same properties as lun contexts 🌸

💫 lun Context 💫

the LUN glow-up zone — every knob you can twist for a single LUN lives here, iykyk 💅

  • 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, while 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 — the 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 — specifies 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 🎀

okay bestie, this is the part everyone actually scrolls down for — real configs you can copy, paste, and immediately feel like a storage goddess 💅 Every single one of these is legit, so keep the spelling and quoting exactly as written, mwah.

First up, two auth groups. ag0 is doing mutual CHAP with a portal restriction, and ag1 is the "I trust these darlings, no password needed" vibe:

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]
}

see how ag1 lets in both an IPv4 range and an IPv6 address? it's giving bilingual queen 🌈 and yes, initiator-name gets repeated once per name — no list syntax here, just stack 'em.

next, a portal group listening on basically everywhere — all of IPv4, all of IPv6, and one very specific link-local address on port 3261 because why not:

portal-group pg0 {
        discovery-auth-group no-authentication
        listen 0.0.0.0:3260
        listen [::]:3260
        listen [fe80::be:ef]:3261
}

and here's the main character section ✨ a target with an alias and a LUN, a standalone LUN with a naa option set, another target that pulls in ag0 and pg0 plus a reused LUN, and finally a naa.-named target hanging off two ports:

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
}

quick vibe check 👀 — lun 0 example_1 is the shortcut form that says "yo, use that named LUN from earlier", while lun 1 { … } is the inline one with its own path and option vendor "FreeBSD".

last one in the classic syntax, a controller with two namespaces — one borrowed, one ramdisk:

controller nqn.2012-06.com.example:controller1 {
        auth-group no-authentication;
        namespace 1 example_1
        namespace 2 {
                backend ramdisk
                size 1G
                option capacity 1G
        }
}

(spot the rogue ; after no-authentication? it's just sitting there living its life. copy it as-is, don't @ me 💀)

🌸 the same thing, but UCL 🌸

An equivalent configuration in UCL format, for use with -u:

okay so this is the exact same setup rewritten in UCL. it's the same info, just wearing a different outfit 🦋 note that UCL wants = signs, braces for everything, and array literals in [ ] — nothing else changes.

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]"]
        }
}

the portal group, now with a listen array — note the quoted IPv6 entries get brackets AND quotes. fussy? yes. correct? also yes 😌

portal-group {
        pg0 {
                discovery-auth-group = no-authentication
                listen = [
                        0.0.0.0:3260,
                        "[::]:3260",
                        "[fe80::be:ef]:3261"
                ]
        }
}

the standalone LUN, with its naa tucked into an options block:

lun {
        example_1 {
                path = /dev/zvol/tank/example_1
                options {
                        naa = "0x50015178f369f093"
                }
        }
}

and the targets — quoted keys, size = 4GB, and LUN assignments written as 0 = example_1:

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

finally the controller, with the namespace array doing the same "one borrowed, one ramdisk" thing:

controller {
        "nqn.2012-06.com.example:controller1" {
                auth-group = no-authentication
                namespace = {
                        1 = example_1,
                        2 {
                                backend = ramdisk
                                size = 1G
                                options {
                                        capacity = 1G
                                }
                        }
                }
        }
}

proud of you for making it to the bottom of that, fr fr 🫶

✨ SEE ALSO ✨

go read these next, they're the rest of the lore 👑

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

put some respect on the name, that's the icon who built this 🫡

okay that's the whole page bestie, you're officially a ctl.conf scholar!! 🌟 this was the Debian build, dated August 6, 2025, and the page itself is CTL.CONF(5) — go configure something iconic 💖🎀

📦 where this page comes from
  • freebsd 15.1: base 15.1
  • Copyright (c) 2012 The FreeBSD Foundation
  • Copyright (c) 2015 Alexander Motin <mav@FreeBSD.org>
  • 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms