FreeBSD sesutil Operations: Map Drive Bays and Verify Enclosure Signals

SCSI Enclosure Services (SES) exposes information and controls for a storage enclosure: element identity, health indications, and locate or fault LEDs. On FreeBSD, sesutil(8) can map enclosure elements to disk device names, display controller status, and change supported LED states. The most important operational discipline is proving that a logical disk identifier maps to the physical bay you intend to touch.

An SES LED is an aid to human correlation, not a replacement for redundancy checks or a maintenance procedure. A mistaken locate operation is usually reversible; a mistaken drive pull can degrade a pool, interrupt a rebuild, or remove the wrong member. Treat discovery, identification, signaling, and replacement as separate stages with recorded evidence between them.

Confirm the host sees an SES controller

Inventory CAM devices and GEOM providers before using an enclosure command:

camcontrol devlist -v
geom disk list
ls -l /dev/ses* /dev/da* 2>/dev/null

The exact device names depend on the controller, transport, and probe order. A disk might appear as da12, while an enclosure controller might be /dev/ses0; neither number is a durable identity across hardware changes or reboot. Record serial numbers, enclosure addresses if available, pool/vdev membership, and bay coordinates in an asset inventory rather than documenting only transient unit numbers.

If no /dev/sesN device exists, verify that the enclosure exposes SES through the connected expander or backplane, inspect kernel messages, and check the relevant driver and firmware. A SAS HBA connected through a path that suppresses enclosure management can still expose disks while hiding SES. That condition is not repaired by guessing another controller number.

Map enclosure elements before changing a signal

Use map to list elements and their associations. If more than one enclosure exists, query each controller explicitly:

sesutil map
sesutil map -u /dev/ses0
sesutil status -u /dev/ses0

The map is the key safety artifact: it associates enclosure element identifiers with devices such as da12. The status view helps identify whether the enclosure or an element is reporting a fault condition. Save both outputs with a timestamp before dispatching a technician. Re-run the map after topology changes, firmware updates, cable moves, or a controller replacement.

Do not assume that element ID equals the printed bay number. Enclosures can include power supplies, fans, slots, expanders, and other elements in the same index space. A sesid accepted by the utility is an SES element identifier, not a human bay label. Correlate it with the map, chassis markings, vendor documentation, and a controlled locate test before using it during a live replacement.

For a managed fleet, sesutil can request structured output through libxo on supported versions. Validate the exact output schema on the installed release before wiring it into an inventory parser. Do not scrape formatted columns from multiple versions and silently assume a stable field order.

Turn on a locate LED as a reversible test

When the mapping has been checked by a second operator or an equivalent change-control procedure, locate the disk by its current device name:

sesutil locate da12 on
sesutil status -u /dev/ses0

The manual documents locate for a disk name or SES element ID, and supports on and off. Verify that the expected physical bay illuminates. If another bay lights, stop; do not infer that the map is “close enough.” Correct the cabling or inventory mismatch before proceeding.

Turn the signal off after identification:

sesutil locate da12 off

A blinking or solid indication is implementation-dependent. The tool requests an external locate LED state; it does not guarantee a particular blink pattern across enclosure firmware. Check status and the physical chassis, and avoid leaving stale locate indicators that can mislead the next maintenance team.

The fault command controls a fault indication where supported. Use it only when the operational process calls for a visual fault marker and the correct element has been independently verified. Do not use the fault LED as proof that the disk has failed, and do not clear a fault display until the actual hardware and storage state have been reviewed.

Coordinate drive replacement with storage state

Before any drive is removed, inspect the relevant storage layer. For ZFS, capture zpool status -v; for GEOM mirrors or multipath, inspect their specific status tools; for a mounted filesystem, confirm the provider and mount dependencies. The fact that sesutil maps a disk to a bay does not show whether the disk is redundant, currently resilvering, or required by another consumer.

Record the disk’s serial number and current identifier, then compare it with the enclosure map and the storage membership output. If the disk is healthy but is being replaced for planned maintenance, the storage-specific procedure may require an explicit offline operation first. Do not invent an offline command from another subsystem. Follow the exact procedure for ZFS, gmirror, multipath, or the relevant controller.

Keep the replacement workflow ordered: identify the physical drive, mark it, verify the lit bay, confirm the storage state and authorization, remove or offline the device according to its subsystem, replace only that bay, then verify that the new device appears with the expected serial and capacity. Finally inspect enclosure status and storage resilver or recovery progress. A green LED does not prove that the replacement was accepted by the pool.

If the utility cannot map a disk, do not compensate by using all. sesutil locate all on affects every associated device and defeats the purpose of isolating one bay. Inspect SES topology and vendor documentation, then use a controlled human-assisted mapping procedure or another management interface.

Troubleshoot a stale or ambiguous map

When the map is empty or inconsistent, collect evidence from the kernel, CAM, and enclosure layers before changing cabling:

dmesg | tail -120
camcontrol devlist -v
sesutil status
sesutil map

Compare before and after outputs around a single planned cable or controller action. If /dev/ses0 changed to another unit, the former unit number may now point to a different enclosure. Re-run status and map; do not reuse stale command history.

An enclosure can expose disk slots without reporting every LED or temperature element. SES capabilities vary by hardware and firmware. If locate or fault state is unsupported, the command may fail or no visible light may change. Do not treat that as a failed disk diagnosis; use the supported management channel and document the missing capability.

Permissions also matter. These commands change hardware-visible state and may require root privileges. Run them through the approved administrative path, retain command output, and avoid granting broad device access to monitoring accounts merely to illuminate LEDs. If automation is needed, use a narrow privileged interface that validates a disk identity against inventory and requires an explicit maintenance request.

Define an acceptance check

For each enclosure maintenance run, the record should include host, controller, timestamp, sesutil map output, status output, selected disk serial, pool or GEOM membership, physical bay confirmation, and final LED state. After replacement, record the new serial, device name, capacity, and recovery progress. These checks make the mapping reproducible and reveal when numbering changed.

sesutil is most valuable when it closes the gap between a kernel device name and a human-visible slot. It cannot decide whether a drive is safe to remove, guarantee an enclosure will honor a signal, or replace storage-level validation. Use the map to identify, the subsystem tools to authorize the operation, and post-change status to prove recovery.

Related:

Sources: