CTL.CONF(5)						      BSD File Formats Manual						       CTL.CONF(5)

NAME

     ctl.conf -- CAM Target Layer / iSCSI target 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
		 ...
	   }

	   lun name {
		 path path
	   }

	   target name {
		 auth-group name
		 portal-group name [agname]
		 port name
		 lun number name
		 lun 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.

     lun name
	     Create a lun configuration context, defining a LUN to be exported by some target(s).

     target name
	     Create a target configuration context, which can contain one or more lun 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.

     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.

     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.

   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 prede-
	     fined auth-group, "no-authentication", may be used to permit access without authentication.  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.

     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 configu-
	     ration 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.

     offload driver
	     Define iSCSI hardware offload driver to use for this target.

     portal-group name [agname]
	     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 name for connections to this
	     specific portal group.  If second argument is not specified, target auth group is used.

     port name
	     Assign specified CTL port (such as "isp0") to the target.	On startup ctld 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 redi-
	     rected 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.

   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.

     device-id string
	     The SCSI Device Identification string presented to the initiator.

     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 or device node used to back the LUN.

     serial string
	     The SCSI serial number presented to the initiator.

     size size
	     The LUN size, in bytes.

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
     }

     target iqn.2012-06.com.example:target1 {
	     chap chapuser chapsecret
	     lun 0 example_1
     }

     target iqn.2012-06.com.example:target2 {
	     auth-group ag0
	     portal-group pg0
	     lun 0 example_1
	     lun 1 {
		     path /dev/zvol/tank/example_2
		     option foo bar
	     }
     }

SEE ALSO

     ctl(4), ctladm(8), ctld(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.

BSD
								 February 11, 2015							       BSD