ledctl - Man Page

Intel(R) LED control application for a storage enclosures.

Examples (TL;DR)

Turn on the "Locate" LED for specified device(s): sudo ledctl locate=/dev/sda,/dev/sdb,...
Turn off the "Locate" LED for specified device(s): sudo ledctl locate_off=/dev/sda,/dev/sdb,...
Turn off the "Status" LED and "Failure" LED for specified device(s): sudo ledctl off=/dev/sda,/dev/sdb,...
Turn off the "Status" LED, "Failure" LED and "Locate" LED for specified device(s): sudo ledctl normal=/dev/sda,/dev/sdb,...

Description

Ledctl is a user-space application designed to control LEDs associated with each slot in an enclosure or a drive bay. Root privileges are required for its operation.

The ledctl application facilitates LED management for SAS/SATA and PCIe storage devices.

Supported protocols/methods for LED management are:

SES-2 and SMP for SAS devices,
LED messages over SGPIO for SATA,
VMD and NPEM for PCIe.

SAF-TE protocol is not supported.

For SAS/SATA storage, supporting controllers may transmit LED management information to the backplane controllers via the SGPIO interface. The SGPIO bus carries bit patterns, which translate into LED blink patterns in accordance with the International Blinking Pattern Interpretation (IBPI) of SFF-8489 specification for SGPIO. Please note some enclosures do not stick closely to the SFF-8489 specification. It might occur that the enclosure processor will accept the IBPI pattern but will not blink LEDs according to SFF-8489 specification. Or, it may have a limited number of patterns supported.

The ledctl application has been verified to work with Intel(R) storage controllers (i.e. Intel(R) AHCI controller and Intel(R) SAS controller). The application might work with storage controllers of other vendors (especially SCSI/SAS controllers). However, storage controllers of other vendors have not been tested.

The ledmon application has the highest priority when accessing LEDs. Meaning that some patterns set by ledctl may have no effect if ledmon is running (exception: Locate pattern).

The ledctl application is a part of Intel(R) Enclosure LED Utilities.

The ledctl utilizes the following documents as references:

SGPIO (Serial GPIO) - SFF-8485
IBPI (International Blinking Pattern Interpretation) - SFF-8489
LED Enclosure management messages - AHCI specification rev 1.3, section 12.2.1.
SAS (Serial Attached SCSI) - T10/1760-D
SES-2 (SCSI Enclosure Services-2) - T10/1559-D
SMP (Serial Management Protocol) - T10/1760-D
NPEM (Native PCIe Enclosure Management) - PCIe base specification rev 4.0
VMD (Intel(R) Volume Management Device) - Intel(R) VROC (VMD NVMe RAID) Quick
Configuration Guide rev 1.2

Pattern Names

The ledctl application accepts the following names for pattern_name argument according to SFF-8489 specification.

locate: Turns Locate LED associated with the given device(s) on.
locate_off: Turns only Locate LED off.
locate_and_failure: Turns Locate LED and Failure LED on.
normal: Turns Status LED, Failure LED and Locate LED off.
off: Turns only Status LED and Failure LED off.
ica or degraded: Visualizes "In a Critical Array" pattern.
rebuild: Visualizes "Rebuild" pattern.
ifa or failed_array: Visualizes "In a Failed Array" pattern.
hotspare: Visualizes "Hotspare" pattern.
pfa: Visualizes "Predicted Failure Analysis" pattern.
failure or disk_failed: Visualizes "Failure" pattern.
ses_abort: SES-2 R/R ABORD
ses_rebuild: SES-2 REBUILD/REMAP
ses_ifa: SES-2 IN FAILED ARRAY
ses_ica: SES-2 IN CRIT ARRAY
ses_cons_check: SES-2 CONS CHECK
ses_hotspare: SES-2 HOT SPARE
ses_rsvd_dev: SES-2 RSVD DEVICE
ses_ok: SES-2 OK
ses_ident: SES-2 IDENT
ses_rm: SES-2 REMOVE
ses_insert: SES-2 INSERT
ses_missing: SES-2 MISSING
ses_dnr: SES-2 DO NOT REMOVE
ses_active: SES-2 ACTIVE
ses_enable_bb: SES-2 ENABLE BYP B
ses_enable_ba: SES-2 ENABLE BYP A
ses_devoff: SES-2 DEVICE OFF
ses_fault: SES-2 FAULT
ses_prdfail: SES-2 PRDFAIL

Patterns Translation

When a non SES-2 pattern is sent to device an enclosure automatic translation is done.

locate: locate is translated to ses_ident
locate_off: locate_off is translated to ~ses_ident
normal or off: normal or off is translated to ses_ok
ica or degraded: ica or degraded is translated to ses_ica
rebuild: rebuild is translated to ses_rebuild
ifa or failed_array: ifa or failed_array is translated to ses_ifa
hotspare: hotspare is translated to ses_hotspare
pfa: pfa is translated to ses_prdfail
failure or disk_failed: failure or disk_failed is translated to ses_fault

Modes and Mode Specific Options

This chapter outlines the modes and options applicable to specific modes. If no mode is specified, the default is IBPI mode.

-I or --ibpi

Sets pattern on given devices. Allows ledctl to determine the best controller automatically. Must be followed by IBPI option. By default, it checks all devices and may update states on different drives than requested if state change is determined (generally it happens for devices in raid array).

PATTERN={ device1 device2 } or PATTERN=device1,device2: The IBPI option accepts device lists in two formats: comma-separated elements and elements enclosed in curly braces with spaces between them. Refer to "Pattern names" for supported states. For usage examples, see "Examples".
-x or --listed-only: Suppresses default behavior, changes state only on devices listed in CLI. It is optional.

-L or --list-controllers

Prints information (system path and type) of all controllers detected.

-B or --default-controller

There is a possibility that device is supported by more than one controller (e.g. NPEM and VMD). In that case, this command can be used to query ledctl to return preferred controller type. The returned controller type is used by subset of routines which do not take controller type directly (e.g. --get-slot, --list-slots, --set-slot).

Prints preferred controller type which should be used to control LED for this device. Must be followed by --device, for which controller will be printed.

-P or --list-slots

Prints all slots for the controller type. Must be followed by --controller-type.

-G or --get-slot

Displays specific slot details. Must be followed by --controller-type and slot identifier --device or --slot. --print can be used to control output.

-r print or --print=print: Optional parameter for --get-slot. It is utilized to retrieve a specific property from the output. Supported values include: slot, device, and state.

-S or --set-slot

Changes led state for slot. Must be followed by --controller-type, slot identifier --device or --slot and --state.

-p state or --state=state: It is mandatory for --set-slot. It provides the state to be set for the slot. Refer to "Pattern names" for supported states list.

Slot Management Options

This section describes options necessary by various slot management modes.

-n controller_type or --controller-type=controller_type: Controller type chosen for the request. It aggregates multiple controllers of the same type. Supported types are: VMD, NPEM and SCSI.
-d device or --device=device: Block device node for device attached to the slot. It can be used instead of --slot.
-p slot or --slot=slot: Unique slot identifier. It can be used instead of --device. Use --list-slots to determine slot identifiers. Slot definition depends on the controller and is unique across all controllers of the same type. The slot identifier is always available, even if a device is not connected.

General Options

This section describes options available for every mode.

-l path or --log=path: Sets a path to log file. If this option is not specified then default log file /var/log/ledctl.log is used.
-h or --help: Prints help text out. Use --MODE --help to get help for requested mode or --help to get general help.
-v or --version: Displays version of ledctl and information about the license.
--log_level=log_level: Set the application's logging level. Available levels, listed from most verbose to least verbose, include: ALL, DEBUG, INFO, WARNING, ERROR, and QUIET. The default setting is WARNING.

Files

/var/log/ledctl.log: Global log file, used by all instances of ledctl application. To force logging to user defined file use -l option switch.

Examples

The following example illustrates how to set locate on a single block device. Note that all remaining LEDs, might be changed.

ledctl --ibpi locate=/dev/sda

The following example illustrates how to set locate_off on a single block device.

ledctl --ibpi --listed-only locate_off=/dev/sda

The following example illustrates how to set off on the given devices. It uses second format of the device list.

ledctl --ibpi --listed-only off={ /dev/sda /dev/sdb }

The following example illustrates how to set locate and rebuild on different devices at the same time. It uses the second format of the device list.

ledctl --ibpi --listed-only locate={ /dev/sdb } rebuild={ /sys/block/sdc }

The following example illustrates how to locate on three block devices. It uses the first format of the device list.

ledctl --ibpi --listed-only locate=/dev/sda,/dev/sdb,/dev/sdc

The following example illustrates how to set locate and rebuild on different devices at the same time. It uses the first format of the device list.

ledctl --ibpi --listed-only locate=/dev/sdb rebuild=/sys/block/sdc

The following example illustrates how to set locate and rebuild on different devices at the same time. It uses the both formats of the device list.

ledctl --ibpi --listed-only locate={ /dev/sdb } rebuild=/sys/block/sdc

The following example illustrates how to get all detected controllers.

ledctl --list-controllers

The following example illustrates how to get all slots for controller type NPEM.

ledctl --list-slots --controller-type=npem

The following example illustrates how to get particular slot with device specified, for controller type SCSI. Print state only.

ledctl --get-slot --controller-type=scsi --device=/dev/sda --print=state

The following example illustrates how to get particular slot with slot specified, for controller type NPEM. Print device only.

ledctl --get-slot --controller-type=npem --slot=10000:02:04.0 --print=device