ledctl(8)

1ledctl(8)         Intel(R) Enclosure LED Control Application         ledctl(8)
2
3
4

NAME

6       ledctl - Intel(R) LED control application for a storage enclosures.
7

SYNOPSIS

9       ledctl [OPTIONS] pattern_name=list_of_devices ...
10

DESCRIPTION

12       The ledctl is an user space application designed to control LEDs
13       associated with each slot in an enclosure or a drive bay. The LEDs of
14       devices listed in list_of_devices are set to the given pattern
15       pattern_name and all other LEDs are turned off.  User must have root
16       privileges to use this application.
17
18       There are two types of systems: 2-LEDs systems (Activity LED, Status
19       LED) and 3-LEDs systems (Activity LED, Locate LED, Fail LED).
20
21       The ledctl application supports LED management of the SAS/SATA and PCIe
22       storages.
23
24       Supported protocols/methods for LED management are:
25
26       •   SES-2 and SMP for SAS devices,
27
28       •   LED messages over SGPIO for SATA,
29
30       •   VMD and NPEM for PCIe.
31
32       SAF-TE protocol is not supported.
33
34       For SAS/SATA storages supporting controllers may transmit LED
35       management information to the backplane controllers via the SGPIO
36       interface. The SGPIO bus carries bit patterns, which translate into LED
37       blink patterns in accordance with the International Blinking Pattern
38       Interpretation (IBPI) of SFF-8489 specification for SGPIO.  Please note
39       some enclosures do not stick close to the SFF-8489 specification. It
40       might happen that the enclosure processor will accept the IBPI pattern
41       but it will blink LEDs not according to SFF-8489 specification or it
42       has a limited number of patterns supported.
43
44       The ledctl application has been verified to work with Intel(R) storage
45       controllers (i.e. Intel(R) AHCI controller and Intel(R) SAS
46       controller).  The application might work with storage controllers of
47       other vendors (especially SCSI/SAS controllers). However, storage
48       controllers of other vendors have not been tested.
49
50       The ledmon application has the highest priority when accessing LEDs.
51       It means that some patterns set by ledctl may have no effect if ledmon
52       is running (except Locate pattern).
53
54       The ledctl application is a part of Intel(R) Enclosure LED Utilities.
55
56       The ledctl utilizes the following documents as references:
57
58       •   SGPIO (Serial GPIO) - SFF-8485
59
60       •   IBPI (International Blinking Pattern Interpretation) - SFF-8489
61
62       •   LED Enclosure management messages - AHCI specification rev 1.3,
63           section 12.2.1.
64
65       •   SAS (Serial Attached SCSI) - T10/1760-D
66
67       •   SES-2 (SCSI Enclosure Services-2) - T10/1559-D
68
69       •   SMP (Serial Management Protocol) - T10/1760-D
70
71       •   NPEM (Native PCIe Enclosure Management) - PCIe base specification
72           rev 4.0
73
74       •   VMD (Intel(R) Volume Management Device) - Intel(R) VROC (VMD NVMe
75           RAID) Quick
76
77           Configuration Guide rev 1.2
78
79   Pattern Names
80       The ledctl application accepts the following names for pattern_name
81       argument according to SFF-8489 specification.
82
83       locate  Turns Locate LED associated with the given device(s) on.
84
85       locate_off
86               Turns only Locate LED off.
87
88       normal  Turns Status LED, Failure LED and Locate LED off.
89
90       off     Turns only Status LED and Failure LED off.
91
92       ica or degraded
93               Visualizes "In a Critical Array" pattern.
94
95       rebuild Visualizes "Rebuild" pattern.
96
97       ifa or failed_array
98               Visualizes "In a Failed Array" pattern.
99
100       hotspare
101               Visualizes "Hotspare" pattern.
102
103       pfa     Visualizes "Predicted Failure Analysis" pattern.
104
105       failure or disk_failed
106               Visualizes "Failure" pattern.
107
108       ses_abort
109               SES-2 R/R ABORD
110
111       ses_rebuild
112               SES-2 REBUILD/REMAP
113
114       ses_ifa SES-2 IN FAILED ARRAY
115
116       ses_ica SES-2 IN CRIT ARRAY
117
118       ses_cons_check
119               SES-2 CONS CHECK
120
121       ses_hotspare
122               SES-2 HOT SPARE
123
124       ses_rsvd_dev
125               SES-2 RSVD DEVICE
126
127       ses_ok  SES-2 OK
128
129       ses_ident
130               SES-2 IDENT
131
132       ses_rm  SES-2 REMOVE
133
134       ses_insert
135               SES-2 INSERT
136
137       ses_missing
138               SES-2 MISSING
139
140       ses_dnr SES-2 DO NOT REMOVE
141
142       ses_active
143               SES-2 ACTIVE
144
145       ses_enable_bb
146               SES-2 ENABLE BYP B
147
148       ses_enable_ba
149               SES-2 ENABLE BYP A
150
151       ses_devoff
152               SES-2 DEVICE OFF
153
154       ses_fault
155               SES-2 FAULT
156
157       ses_prdfail
158               SES-2 PRDFAIL
159
160   Patterns Translation
161       When non SES-2 pattern is send to device in enclosure automatic
162       translation is being done.
163
164       locate  locate is translated to ses_ident
165
166       locate_off
167               locate_off is translated to ~ses_ident
168
169       normal or off
170               normal or off is translated to ses_ok
171
172       ica or degraded
173               ica or degraded is translated to ses_ica
174
175       rebuild rebuild is translated to ses_rebuild
176
177       ifa or failed_array
178               ifa or failed_array is translated to ses_ifa
179
180       hotspare
181               hotspare is translated to ses_hotspare
182
183       pfa     pfa is translated to ses_prdfail
184
185       failure or disk_failed
186               failure or disk_failed is translated to ses_fault
187
188   List of Devices
189       The application accepts a list of devices in two formats. The first
190       format is a list with comma separated elements. The second format is
191       a list in curly braces and elements are separated by space. See
192       examples section below for details.
193
194       A device is a path to file in /dev directory or in /sys/block
195       directory.
196
197       The LEDs of devices listed in list_of_devices are set to the given
198       pattern pattern_name and all other LEDs, on all devices, are turned off
199       (unless --listed-only option is given).
200

OPTIONS

202       -l or --log=path
203               Sets a path to local log file. If this option is specified the
204               global log file /var/log/ledctl.log is not used.
205
206       -h or --help
207               Prints this text out and exits.
208
209       -v or --version
210               Displays version of ledctl and information about the license
211               and exits.
212
213       -L or --list-controllers
214               Prints information (system path and type) of all controllers
215               detected by ledmon and exits.
216
217       -P or --list-slots --controller-type=controller-type
218               Prints all slots for the controller type. Slot definition
219               depends on the controller and is unique across all controllers
220               of the same type.
221
222               Definitions for supported controller types are described below:
223
224               •   VMD - PCI Express Hot Plug Controller Driver slot number
225
226               •   NPEM - PCI Express Downstream Port address
227
228               Command returns a list of all slots for the controller type
229               with current state and attached device name (if any).
230               controller-type is type of controller (vmd, NPEM) that should
231               be scanned here.
232
233       -G or --get-slot --controller-type=controller-type --device=device
234               Displays slot details of given device. device is devnode of
235               selected drive.
236
237       -G or --get-slot --controller-type=controlle-typer --slot=slot
238               Displays details of given slot. slot is unique slot identifier.
239
240       -S or --set-slot --controller-type=controller-type --slot=slot
241       --state=IBPI_state
242               Changes led state for given slot. controller-type is type of
243               the controller.  slot is unique slot identifier. IBPI_state is
244               led pattern.
245
246       -x or --listed-only
247               With this option ledctl will change state only on devices
248               listed in CLI. The rest of devices will not be touched.
249
250       --quiet or --error or --warning or --info or --debug or --all
251               Verbose level - 'quiet' means no logging at all and 'all' means
252               to log everything. The levels are given in order. If user
253               specifies more then one verbose option the last option comes
254               into effect. The default level is 'warning'. Verbose level also
255               can be set by --log-level=level.
256

FILES

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

EXAMPLES

263       The following example illustrates how to set locate on a single block
264       device. Note that all remaining LEDs, on all devices, will be turned
265       off.
266
267           ledctl locate=/dev/sda
268
269       The following example illustrates how to set locate_off on a single
270       block device.
271
272           ledctl --listed-only locate_off=/dev/sda
273
274       The following example illustrates how to set off on the given devices.
275       It uses second format of device list.
276
277            ledctl --listed-only off={ /dev/sda /dev/sdb }
278
279       The following example illustrates how to set locate and rebuild on
280       different devices at the same time. It uses the second format of device
281       list.
282
283            ledctl --listed-only locate={ /dev/sdb } rebuild={ /sys/block/sdc }
284
285       The following example illustrates how to locate on three block devices.
286       It uses the first format of device list.
287
288            ledctl --listed-only locate=/dev/sda,/dev/sdb,/dev/sdc
289
290       The following example illustrates how to set locate and rebuild on
291       different devices at the same time. It uses the first format of device
292       list.
293
294            ledctl --listed-only locate=/dev/sdb rebuild=/sys/block/sdc
295
296       The following example illustrates how to set locate and rebuild on
297       different devices at the same time. It uses the both formats of device
298       list.
299
300            ledctl --listed-only locate={ /dev/sdb } rebuild=/sys/block/sdc
301

LICENSE

303       Copyright (c) 2009-2022 Intel Corporation.
304
305       This program is distributed under the terms of the GNU General Public
306       License as published by the Free Software Foundation. See the built-in
307       help for details on the License and the lack of warranty.
308

AUTHOR

313       This manual page was written by Artur Wojcik <artur.wojcik@intel.com>.
314       It may be used by others.
315
316
317
318LEDCTL Version 0.97                May 2023                          ledctl(8)