CTLADM(8)

📦
version 15.1 · 2 versions
, in freebsd 15.1

✨ NAME ✨

ctladm — the CAM Target Layer control utility 💅 this is page CTLADM(8) from the System Manager's Manual, and she is the girl who talks to CTL, no cap 👑

🌈 SYNOPSIS 🌈

       ctladm ⟨command⟩ [lun] [generic args] [command args]
       ctladm tur ⟨lun⟩ [general options]
       ctladm inquiry ⟨lun⟩ [general options]
       ctladm reqsense ⟨lun⟩ [general options]
       ctladm reportluns ⟨lun⟩ [general options]
       ctladm read ⟨lun⟩ [general options] ⟨-l lba⟩ ⟨-d datalen⟩ ⟨-f file|-⟩
              ⟨-b blocksize_bytes⟩ [-c cdbsize] [-N]
       ctladm write ⟨lun⟩ [general options] ⟨-l lba⟩ ⟨-d datalen⟩ ⟨-f file|-⟩
              ⟨-b blocksize_bytes⟩ [-c cdbsize] [-N]
       ctladm readcap ⟨lun⟩ [general options] [-c cdbsize]
       ctladm modesense ⟨lun⟩ ⟨-m page | -l⟩ [-P pc] [-d] [-S subpage]
              [-c size]
       ctladm start ⟨lun⟩ [general options] [-i] [-o]
       ctladm stop ⟨lun⟩ [general options] [-i] [-o]
       ctladm synccache ⟨lun⟩ [general options] [-l lba] [-b blockcount] [-r]
              [-i] [-c cdbsize]
       ctladm lunlist
       ctladm delay ⟨lun⟩ ⟨-l datamove|done⟩ ⟨-t secs⟩ [-T oneshot|cont]
       ctladm inject ⟨-i action⟩ ⟨-p pattern⟩ [-r lba,len] [-s len fmt [args]]
              [-c] [-d delete_id]
       ctladm create ⟨-b backend⟩ [-B blocksize] [-d device_id] [-l lun_id]
              [-o name=value] [-s size_bytes] [-S serial_num] [-t device_type]
       ctladm remove ⟨-b backend⟩ ⟨-l lun_id⟩ [-o name=value]
       ctladm modify ⟨-b backend⟩ ⟨-l lun_id⟩ [-o name=value] ⟨-s size_bytes⟩
       ctladm devlist [-b backend] [-v] [-x]
       ctladm port [-c] [-d driver] [-o on|off] [-w wwpn] [-W wwnn]
              [-O name=value] [-p targ_port] [-r] [-t fe_type]
       ctladm portlist [-f frontend] [-i] [-l] [-p targ_port] [-q] [-v] [-x]
       ctladm lunmap ⟨-p targ_port⟩ [-l pLUN] [-L cLUN]
       ctladm dumpooa
       ctladm dumpstructs
       ctladm islist [-v] [-x]
       ctladm islogout ⟨-a | -c connection-id | -i name | -p portal⟩
       ctladm isterminate ⟨-a | -c connection-id | -i name | -p portal⟩
       ctladm nvlist [-v] [-x]
       ctladm nvterminate ⟨-a | -c controller-id | -h name⟩
       ctladm help

💖 DESCRIPTION 💖

okay so the ctladm utility exists to give you a way to access and control the CAM Target Layer (CTL) 🌸. It's your little doorway: it lets you send SCSI commands to the CTL layer, and it also ships some meta-commands that are built on top of SCSI commands. (Like, for example — the lunlist command is literally implemented using the SCSI REPORT LUNS and INQUIRY commands. iykyk 🫶)

The ctladm utility has a bunch of primary functions, and ngl a lot of them need a device identifier. The device identifier looks like this:

  • lun — specify the LUN number to operate on. that's the whole vibe 🎀

Many of the primary functions of the ctladm utility take the following optional arguments, bestie — these are the shared ones:

  • -C retries — specify the number of times to retry a command in the event of failure 🔁
  • -D device — specify the device to open. this lets a device other than the default device, /dev/cam/ctl, be opened for sending commands 👀
  • -I id — specify the initiator number to use. by default, ctladm will use 7 as the initiator number ⭐

👑 Primary commands 👑

🦋 tur

Send the SCSI TEST UNIT READY command to the device and report whether or not it is ready. literally just a vibe check on the device 💅

🦋 inquiry

Send the SCSI INQUIRY command to the device and display some of the returned inquiry data. she wants to know who she's talking to 💖

🦋 reqsense

Send the SCSI REQUEST SENSE command to the device and display the returned sense information.

🦋 reportluns

Send the SCSI REPORT LUNS command to the device and display supported LUNs. it's giving a guest list ✨

🦋 read

Send a SCSI READ command to the device, and write the requested data to a file or stdout.

  • -l lba — specify the starting Logical Block Address for the READ. this can be specified in decimal, octal (starting with 0), hexadecimal (starting with 0x) or any other base supported by strtoull(3) 🔢
  • -d datalen — specify the length, in 512 byte blocks, of the READ request.
  • -f file — specify the destination for the data read by the READ command. either a filename or '-' for stdout may be specified.
  • -c cdbsize — specify the minimum SCSI CDB (Command Data Block) size to be used for the READ request. allowable values are 6, 10, 12 and 16. depending upon the LBA and amount of data requested, a larger CDB size may be used to satisfy the request. (e.g., for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.)
  • -b blocksize — specify the blocksize of the underlying SCSI device, so the transfer length can be calculated accurately. the blocksize can be obtained via the SCSI READ CAPACITY command 🎯
  • -N — do not copy data to ctladm from the kernel when doing a read, just execute the command without copying data. this is to be used for performance testing. (yes, it's a benchmark-brain option, treat it accordingly 🧚)

🦋 write

Read data from a file or stdin, and write the data to the device using the SCSI WRITE command.

  • -l lba — specify the starting Logical Block Address for the WRITE. this can be specified in decimal, octal (starting with 0), hexadecimal (starting with 0x) or any other base supported by strtoull(3) 🔢
  • -d atalen — specify the length, in 512 byte blocks, of the WRITE request.
  • -f file — specify the source for the data to be written by the WRITE command. either a filename or '-' for stdin may be specified.
  • -c cdbsize — specify the minimum SCSI CDB (Command Data Block) size to be used for the READ request. allowable values are 6, 10, 12 and 16. depending upon the LBA and amount of data requested, a larger CDB size may be used to satisfy the request. (e.g., for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.)
  • -b blocksize — specify the blocksize of the underlying SCSI device, so the transfer length can be calculated accurately. the blocksize can be obtained via the SCSI READ CAPACITY command 🎯
  • -N — do not copy data to ctladm to the kernel when doing a write, just execute the command without copying data. this is to be used for performance testing.

🦋 readcap

Send the SCSI READ CAPACITY command to the device and display the device size and device block size 📏. by default, READ CAPACITY(10) is used. if the device returns a maximum LBA of 0xffffffff, however, ctladm will automatically issue a READ CAPACITY(16), which is implemented as a service action of the SERVICE ACTION IN(16) opcode. the user can specify the minimum CDB size with the -c argument. valid values for the -c option are 10 and 16. if a 10 byte CDB is specified, the request will be automatically reissued with a 16 byte CDB if the maximum LBA returned is 0xffffffff. she's thorough like that 💅

🦋 modesense

Send a SCSI MODE SENSE command to the device, and display the requested mode page(s) or page list.

  • -m page — specify the mode page to display. this option and the -l option are mutually exclusive. one of the two must be specified, though. mode page numbers may be specified in decimal or hexadecimal.
  • -l — request that the list of mode pages supported by the device be returned. this option and the -m option are mutually exclusive. one of the two must be specified, though.
  • -P pc — specify the mode page control value. possible values are:
    • 0 — current values.
    • 1 — changeable value bitmask.
    • 2 — default values.
    • 3 — saved values.
  • -d — disable block descriptors when sending the mode sense request.
  • -S subpage — specify the subpage used with the mode sense request.
  • -c cdbsize — specify the CDB size used for the mode sense request. supported values are 6 and 10.
bestie pls notice: -m and -l are mutually exclusive, and you have to pick one. no third option, no vibes-based skipping 🙈

🦋 start

Send the SCSI START STOP UNIT command to the specified LUN with the start bit set. let her wake up 🌞

  • -i — set the immediate bit in the CDB. note that CTL does not support the immediate bit, so this is primarily useful for making sure that CTL returns the proper error.

🦋 stop

Send the SCSI START STOP UNIT command to the specified LUN with the start bit cleared. we use an ordered tag to stop the LUN, so we can guarantee that all pending I/O executes before it is stopped. (CTL guarantees this anyway, but ctladm sends an ordered tag for completeness.) nap time, but make it orderly 😴

  • -i — set the immediate bit in the CDB. note that CTL does not support the immediate bit, so this is primarily useful for making sure that CTL returns the proper error.

🦋 synccache

Send the SCSI SYNCHRONIZE CACHE command to the device. by default, SYNCHRONIZE CACHE(10) is used. if the specified starting LBA is greater than 0xffffffff or the length is greater than 0xffff, though, SYNCHRONIZE CACHE(16) will be used. the 16 byte command will also be used if the user specifies a 16 byte CDB with the -c argument. flush it and slay 💫

  • -l lba — tells it which LBA the cache region you wanna sync starts at ✨ but bestie, this one's a total no-op for CTL. If you send a SYNCHRONIZE CACHE command, it just syncs the cache for the entire LUN anyway. So like, cute option, does nothing here 💅
  • -b blockcount — same deal, but for the length of the cache region to synchronize. Also a no-op for CTL, for the exact same reason: send a SYNCHRONIZE CACHE and it syncs the cache for the whole entire LUN. 🫶
  • -r — asks for relative addressing for the starting LBA. CTL does not support relative addressing, because it only works for linked commands, and CTL does not support linked commands. so... no. 💀
  • -i — tells the target to return status immediately after issuing the SYNCHRONIZE CACHE command instead of waiting around for the cache to finish syncing. CTL does not support this bit. ngl it's giving "we don't do that here" 🙈
  • -c cdbsize — sets the minimum CDB size. Valid values are 10 and 16 bytes. that's it, that's the list 🎀

🌸 lunlist

Lists all LUNs registered with CTL — like a little roll call of everyone on the bus 📋✨

Heads up though: because this command uses the ioctl port, it will only work when the FETDs (Front End Target Drivers) are enabled. So if that's not happening, it's not happening.

It's the equivalent of doing a REPORT LUNS on one LUN and then an INQUIRY on each LUN in the system. basically a whole vibe check of the entire system, one LUN at a time 💖

🦋 delay

Delays commands at the given location ⏳ There are two places where commands may be delayed currently: before data is transferred (datamove) and just prior to sending status to the host (done).

One of the two must be supplied as an argument to the -l option. The -t option must also be specified. no skipping, bestie 😤

  • -l delayloc — delay command(s) at the specified location. This can either be at the data movement stage (datamove) or prior to command completion (done).
  • -t delaytime — delay command(s) for the specified number of seconds. This must be specified. If set to 0, it will clear out any previously set delay for this particular location (datamove or done). so 0 = the undo button 🧚
  • -T delaytype — specify the delay type. By default, the delay option will delay the next command sent to the given LUN. With the -T cont option, every command will be delayed by the specified period of time. With the -T oneshot the next command sent to the given LUN will be delayed and all subsequent commands will be completed normally — and that one is the default. so one-and-done unless you say otherwise ✨

🔥 inject

Injects the specified type of error for the LUN specified, when a command that matches the given pattern is seen 🎯 Yes, on purpose. Yes, for testing. Slay.

The sense data returned is in either fixed or descriptor format, depending upon the status of the D_SENSE bit in the control mode page (page 0xa) for the LUN.

Two important caveats, no cap:

Errors are only injected for commands that have not already failed for other reasons. And by default, only the first command matching the pattern specified is returned with the supplied error.

If the -c flag is specified, all commands matching the pattern will be returned with the specified error until the error injection command is deleted with -d flag. persistent chaos mode, activated 💀

  • -i action — specify the error to return:
    • aborted — return the next matching command on the specified LUN with the sense key ABORTED COMMAND (0x0b), and the ASC/ASCQ 0x45,0x00 ("Select or reselect failure").
    • mediumerr — return the next matching command on the specified LUN with the sense key MEDIUM ERROR (0x03) and the ASC/ASCQ 0x11,0x00 ("Unrecovered read error") for reads, or ASC/ASCQ 0x0c,0x02 ("Write error - auto reallocation failed") for write errors.
    • ua — return the next matching command on the specified LUN with the sense key UNIT ATTENTION (0x06) and the ASC/ASCQ 0x29,0x00 ("POWER ON, RESET, OR BUS DEVICE RESET OCCURRED").
    • custom — return the next matching command on the specified LUN with the supplied sense data. The -s argument must be specified.
  • -p pattern — specify which commands should be returned with the given error:
    • read — the error should apply to READ(6), READ(10), READ(12), READ(16), etc.
    • write — the error should apply to WRITE(6), WRITE(10), WRITE(12), WRITE(16), WRITE AND VERIFY(10), etc.
    • rw — the error should apply to both read and write type commands.
    • readcap — the error should apply to READ CAPACITY(10) and READ CAPACITY(16) commands.
    • tur — the error should apply to TEST UNIT READY commands.
    • any — the error should apply to any command.
  • -r lba,len — specify the starting lba and length of the range of LBAs which should trigger an error. This option only applies when read and/or write patterns are specified. If used with other command types, the error will never be triggered. so like, don't do that 🙈
  • -s len fmt [args] — specify the sense data that is to be returned for custom actions. If the format is ‘-’, len bytes of sense data will be read from standard input and written to the sense buffer. If len is longer than 252 bytes (the maximum allowable SCSI sense data length), it will be truncated to that length. The sense data format is described in cam_cdbparse(3). go read it, iykyk 📖
  • -c — the error injection should be persistent, instead of happening once. Persistent errors must be deleted with the -d argument. you will have to clean up after yourself 💅
  • -d delete_id — delete the specified error injection serial number. The serial number is returned when the error is injected. keep that number, bestie, it's your receipt 🧾

👑 port

Performs one of several CTL frontend port operations — like the plugin menu for ports 🎛️

Either create a new frontend port (-c), destroy a frontend port (-r), turn one or more frontends on or off (-o on|off), or set the World Wide Node Name (-w wwnn) or World Wide Port Name (-W wwpn) for a given port.

One of -c, -r, -o, or -w or -W must be specified. The WWNN and WWPN may both be specified at the same time, but cannot be combined with enabling/disabling or listing ports. pick a lane, babe 😌

  • -c — create new frontend port. main character energy, brand new port ✨
  • -d driver — specify the name of the frontend driver used by the (-c) or (-r) subcommands. Valid driver names include “ioctl”, “iscsi”, and “nvmf”, but more can be added by external kernel modules. the roster keeps growing 🫶
  • -o on|off — turn the specified CTL frontend ports on or off. If no port number or port type is specified, all ports are turned on or off. all of them. every single one. 🌈
  • -O pp|vp — specify generic options on the ioctl frontend port. The list of recognized options is driver-dependent:
    • the “ioctl” driver recognizes “pp” and “vp”.
    • the “iscsi” driver recognizes “cfiscsi_portal_group_tag”, “cfiscsi_target”, and “cfiscsi_target_alias”.
    • the “nvmf” driver recognizes “subnqn”, “portid”, “max_io_qsize”, “enable_timeout”, “ioccsz”, “nn”, and “serial”.

and yes those have to be typed exactly like that, no autocorrect energy 💀

  • -p targ_port — tells it which frontend port number you mean 💖 you can find those numbers in the frontend port list, so go peek there first.
  • -r — removes a port. bye bestie 👋
  • -t fe_type — picks the frontend type used by the -o, -w and -W subcommands. The port types that exist rn are fc (Fibre Channel), scsi (Parallel SCSI), ioctl (CTL ioctl interface) and internal (CTL CAM SIM). ✨
  • -w wwnn — sets the World Wide Node Name for the port you named. You gotta also pass -p, because this is only possible to implement on a single port, no cap. General rule 🫶: the WWNN should be the same across all ports on the system.
  • -W wwpn — sets the World Wide Port Name for the given port. Again, -p is mandatory for the same single-port reason. General rule 🫶: the WWPN must be different for every port in the system. every. single. one. 💅

portlist 👑

Lists CTL frontend ports. That's it, that's the vibe.

  • -f frontend — specify the frontend type.
  • -i — reports target and connected initiator names 🎀
  • -l — reports the LUN mapping.
  • -p targ_port — specify the frontend port number.
  • -q — omits the header in the port list output (for the minimalists 🦋).
  • -v — verbose output, which reports all port options. the way she tells you everything 😭
  • -x — spits the port list out in XML format.

lunmap 🗺️

Changes the LUN mapping for a specified port. The logic is giving choose-your-own-adventure:

  • Both pLUN and cLUN given → the LUN gets mapped ✨
  • pLUN given but cLUN not → the LUN gets unmapped
  • Neither given → LUN mapping gets disabled, exposing all CTL LUNs 👀
  • -p targ_port — specify the frontend port number.
  • -l pLUN — the LUN number visible by the specified port.
  • -L cLUN — the CTL LUN number.

dumpooa 💅

Dumps the OOA (Order Of Arrival) queue for each LUN registered with CTL. it's giving receipts, honestly.

dumpstructs 🧚

Dumps the CTL structures to the console.

create 🌱

Creates a shiny new LUN ✨ The backend is non-negotiable — you must specify it — and depending on which backend you asked for, some of the other options may be required too. If the LUN gets created successfully, the LUN configuration will be displayed 🎀 If creation fails, you get a message describing the failure, so at least you know what went wrong 😭

  • -b backend — this flag is required. It names the backend to use when creating the LUN. Examples are ramdisk and block.
  • -B blocksize — specify the blocksize of the backend, in bytes.
  • -d device_id — specify the LUN-associated string to use in the SCSI INQUIRY VPD page 0x83 data.
  • -l lun_id — request that a particular LUN number be assigned. If that number isn't available, the request just fails. no negotiation 😤
  • -o name=value — specify a backend-specific name/value pair. Multiple -o arguments may be specified, stack 'em up 🍓 Refer to the backend documentation for which arguments you can use.
  • -s size_bytes — specify the size of the LUN in bytes. Some backends may allow setting the size (e.g. the ramdisk backend) and for others the size may be implicit (e.g. the block backend).
  • -S serial_num — specify the serial number to use in the SCSI INQUIRY VPD page 0x80 data.
  • -t device_type — specify the numeric SCSI device type to use when creating the LUN. If you don't use this flag, the type of LUN created is backend-specific. Not all LUN types are supported. Currently CTL supports Direct Access (type 0), Processor (type 3) and CD/DVD (type 5) LUNs. And heads up 🫶: the backend you requested may or may not support all of the LUN types that CTL supports.

remove 🗑️

Removes a LUN. The backend must be specified, and the LUN number must also be specified. Backend-specific options may also be passed with the -o flag.

  • -b backend — specify the backend that owns the LUN to be removed. Examples are ramdisk and block.
  • -l lun_id — specify the LUN number to remove.
  • -o name=value — specify a backend-specific name/value pair. Multiple -o arguments may be specified. Refer to the backend documentation for arguments that may be used.

modify 🛠️

Modifies a LUN size. The backend, the LUN number and the size all have to be specified — no skipping steps 💅

  • -b backend — specify the backend that owns the LUN to be modified. Examples are ramdisk and block.
  • -l lun_id — specify the LUN number to modify.
  • -o name=value — specify a backend-specific name/value pair. Multiple -o arguments may be specified. Refer to the backend documentation for arguments that may be used.
  • -s size_bytes — specify the size of the LUN in bytes. For the block backend, an auto keyword may be passed instead — that makes CTL use the size of the backing file or device. iconic shortcut honestly ✨

devlist 📋

Gets a list of all the configured LUNs. This also includes the LUN size and blocksize, the serial number and the device ID. the whole info dump, we love to see it 💖

  • -b backend — specify the backend. This restricts the LUN list to the named backend. Examples are ramdisk and block.
  • -v — be verbose. This will also display any backend-specific LUN attributes in addition to the standard per-LUN information. she's thorough 😭
  • -x — dump the raw XML. The LUN list information from the kernel comes in XML format, and this option lets you display that raw XML data. This option and the -v and -b options are mutually exclusive 🚨 If you specify -x, the entire LUN database is displayed in XML format.

islist 🔍

Gets a list of the currently running iSCSI sessions. This includes initiator and target names and the unique connection IDs 🎀

  • -v — verbose mode.
  • -x — dump the raw XML. The sessions list information from the kernel comes in XML format, and this option lets you display that raw XML data.

islogout 👋

Asks the initiator to log out iSCSI sessions matching the criteria. politely. with feeling 🫶

  • -a — log out all sessions.
  • -c — specify connection ID.
  • -i — specify initiator name.
  • -p — specify initiator portal (hostname or IP address).

isterminate 💀

Forcibly terminates iSCSI sessions matching the criteria. not a request this time, fr fr 😤

  • -a — terminate all sessions.
  • -c — specify connection ID.
  • -i — specify initiator name.
  • -p — specify initiator portal (hostname or IP address).

nvlist 🦋

Gets a list of the currently running NVMeoF associations. This includes host and controller names and the unique controller IDs ✨

  • -v — verbose mode.
  • -x — dump the raw XML. The sessions list information from the kernel comes in XML format, and this option lets you display that raw XML data.

nvterminate 🔥

Forcibly terminates NVMeoF associations matching the criteria.

  • -a — terminate all associations.
  • -c — specify controller ID.
  • -h — specify host name.

help 🌈

Displays ctladm usage information. when in doubt, bestie, ask for help 💜

✨ OPTIONS ✨

okay so bestie, you can tack a whole bunch of additional configuration options onto LUNs. Some are global, some are backend-specific — iykyk 💅

🌍 Global options 🌍

  • vendor — specifies the LUN vendor string, up to 8 chars.
  • product — specifies the LUN product string, up to 16 chars.
  • revision — specifies the LUN revision string, up to 4 chars.
  • scsiname — specifies the LUN SCSI name string.
  • eui — specifies the LUN EUI-64 identifier.
  • naa — specifies the LUN NAA identifier.
  • uuid — specifies the LUN locally assigned RFC 4122 UUID identifier.
🚨 important, bestie: EUI, NAA or UUID identifier should be set to UNIQUE value to allow EXTENDED COPY command access the LUN. Non-unique LUN identifiers may lead to data corruption. Some initiators may not support later introduced UUID identifiers.
  • ident_info — specifies LUN identification information (a string, or 0x + hex).
  • text_ident_info — specifies LUN text identification information (UTF-8 string).
  • ha_role — setting to "primary" or "secondary" overrides the default role of the node in the HA cluster, which is set by the kern.cam.ctl.ha_role sysctl.
  • insecure_tpc — setting to "on" allows an EXTENDED COPY command sent to this LUN to access other LUNs on this host that are not accessible otherwise. This allows offload copying between different iSCSI targets residing on the same host in trusted environments.
  • readcache — set to "off", disables read caching for the LUN, if supported by the backend.
  • readonly — set to "on", blocks all media write operations to the LUN, reporting it as write protected.
  • removable — set to "on", makes the LUN removable.
  • reordering — set to "unrestricted", allows the target to process commands with SIMPLE task attribute in arbitrary order. Any data integrity exposures related to command sequence order shall be explicitly handled by the application client through the selection of appropriate commands and task attributes. The default value is "restricted". It improves data integrity, but may introduce some additional delays.
  • serseq — set to "on" to fully serialize consecutive reads/writes. Set to "read" to fully serialize consecutive reads. Set to "soft" to slightly serialize consecutive reads. Set to "off" to allow them be issued in parallel. Parallel issue of consecutive operations may confuse the logic of the backing file system, hurting performance; but it may improve performance of backing stores without prefetch/write-back.
  • pblocksize, pblockoffset — specify physical block size and offset of the device.
  • ublocksize, ublockoffset — specify UNMAP block size and offset of the device.
  • rpm — specifies medium rotation rate of the device: 0 = not reported, 1 = non-rotating (SSD), >1024 = value in revolutions per minute.
  • formfactor — specifies nominal form factor of the device: 0 = not reported, 1 = 5.25", 2 = 3.5", 3 = 2.5", 4 = 1.8", 5 = less then 1.8".
  • temperature, reftemperature — specify current and reference (maximum) temperatures of the device.
  • provisioning_type — when UNMAP support is enabled, this option specifies provisioning type: "resource", "thin" or "unknown". Default value is "thin". Logical units without UNMAP support are reported as fully provisioned.
  • unmap — setting to "on" or "off" controls UNMAP support for the logical unit. Default value is "on" if supported by the backend.
  • unmap_max_lba, unmap_max_descr — specify maximum allowed number of LBAs and block descriptors per UNMAP command to report in Block Limits VPD page.
  • write_same_max_lba — specify maximum allowed number of LBAs per WRITE SAME command to report in Block Limits VPD page.
  • avail-threshold, used-threshold, pool-avail-threshold, pool-used-threshold — set per-LUN/-pool thin provisioning soft thresholds. LUN will establish UNIT ATTENTION condition if its or pool available space get below configured avail values, or its or pool used space get above configured used values. Pool thresholds are working only for ZVOL-backed LUNs.
  • writecache — set to "off", disables write caching for the LUN, if supported by the backend.

🧱 Options specific for block backend 🧱

  • file — specifies file or device name to use for backing store.
  • num_threads — specifies number of backend threads to use for this LUN.

🍓 Options specific for ramdisk backend 🍓

  • capacity — specifies capacity of backing store (maximum RAM for data). The default value is zero, that disables backing store completely, making all writes go to nowhere, while all reads return zeroes.

💖 EXAMPLES 💖

Send a SCSI TEST UNIT READY command to LUN 1.

ctladm tur 1

Display the list of mode pages supported by LUN 1.

ctladm modesense 1 -l

Display the saved version of the Control mode page (page 10) on LUN 0. Disable fetching block descriptors, and use a 10 byte MODE SENSE command instead of the default 6 byte command.

ctladm modesense 0 -m 10 -P 3 -d -c 10

Read the first 512 byte block from LUN 2 and dump it to the file — the command sends it to foo with >.

ctladm read 2 -l 0 -d 1 -b 512 -f - > foo

Read 10240 bytes from the file /tmp/bar and write it to LUN 3, starting at LBA 0xff432140.

ctladm write 3 -l 0xff432140 -d 20 -b 512 -f /tmp/bar

Create a LUN with the “fake” ramdisk as a backing store. The LUN will claim to have a size of approximately 10 terabytes, while having no real data store (all written data are lost).

ctladm create -b ramdisk -s 10485760000000000

Create a thin provisioned LUN with a ramdisk as a backing store. The LUN will have maximal backing store capacity of 10 gigabytes, while reporting size of 10 terabytes.

ctladm create -b ramdisk -s 10T -o capacity=10G

Create a LUN using the block backend, specify the ZFS volume tank/example as the backing store, and specify the SCSI VPD page 0x80 and 0x83 serial number (-S) and device ID (-d). The size of the LUN will be derived from the size of the ZVOL.

ctladm create -b block -o file=/dev/zvol/tank/example -S MYSERIAL321 -d MYDEVID123

Use to specify generic options on ioctl frontend port, now it is only possible to set pp and/or vp port number.

ctladm port -c -O pp=11 -O vp=12

Remove specified targ_port.

ctladm port -r -p 4

Remove LUN 12, which is handled by the block backend, from the system.

ctladm remove -b block -l 12

List configured LUNs in the system, along with their backend and serial number. This works when the Front End Target Drivers are enabled or disabled.

ctladm devlist

List all LUNs in the system, along with their inquiry data and device type. This only works when the FETDs are enabled, since the commands go through the ioctl port.

ctladm lunlist

Inject a medium error on LUN 6 for every read that covers the first 512 blocks of the LUN.

ctladm inject 6 -i mediumerr -p read -r 0,512 -c

Inject a custom error on LUN 6 for the next TEST UNIT READY command only. This will result in a sense key of NOT READY (0x02), and an ASC/ASCQ of 0x04,0x02 ("Logical unit not ready, initializing command required").

ctladm inject 6 -i custom -p tur -s 18 "f0 0 02 s12 04 02"

🦋 SEE ALSO 🦋

go hang with these besties: cam(3), cam_cdbparse(3), cam(4), ctl(4), xpt(4), camcontrol(8), ctld(8), ctlstat(8). 💖

🌈 HISTORY 🌈

The ctladm utility was originally written during the Winter/Spring of 2003 as an interface to CTL. iconic origin story, honestly ✨

👑 AUTHORS 👑

Ken Merry <ken@FreeBSD.org> — yes bestie, that's the author. 🫶

💖 source/version: Debian — date: February 20, 2025. that's the cute little footer energy, mwah! 💖

📦 where this page comes from
  • freebsd 15.1: base 15.1
  • Copyright (c) 2003 Silicon Graphics International Corp
  • Copyright (c) 2015-2021 Alexander Motin <mav@FreeBSD.org>
  • Copyright (c) 2018 Marcelo Araujo <araujo@FreeBSD.org>
  • 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms