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.