MFIUTIL(8)

📦

version 1.0.15-rivoreo-r2~rc-20250214-e8c6289 · 3 versions

1.0.15-rivoreo-r2~rc-20250214-e8c6289 · ubuntu resolute, ubuntu stonking (latest)
14.5 · freebsd 14.5
15.1 · freebsd 15.1

🌸 NAME 🌸

okay bestie, say hi to mfiutil — section 8 of the System Manager's Manual, and it's literally the Utility for managing LSI MegaRAID SAS controllers. she's giving sysadmin royalty, no cap. 👑

✨ SYNOPSIS ✨

mfiutil version
mfiutil [-t drv_type] [-u unit] show adapter
mfiutil [-t drv_type] [-u unit] show battery
mfiutil [-d] [-e] [-p] [-t drv_type] [-u unit] show config
mfiutil [-p] [-t drv_type] [-u unit] show drives
mfiutil [-t drv_type] [-u unit] show events [-c class] [-l locale]
        [-n count] [-v] [start [stop]]
mfiutil [-t drv_type] [-u unit] show firmware
mfiutil [-p] [-t drv_type] [-u unit] show foreign [volume]
mfiutil [-t drv_type] [-u unit] show logstate
mfiutil [-d] [-e] [-t drv_type] [-u unit] show patrol
mfiutil [-d] [-e] [-t drv_type] [-u unit] show progress
mfiutil [-p] [-t drv_type] [-u unit] show volumes
mfiutil [-t drv_type] [-u unit] fail drive
mfiutil [-t drv_type] [-u unit] good drive
mfiutil [-t drv_type] [-u unit] rebuild drive
mfiutil [-t drv_type] [-u unit] syspd drive
mfiutil [-t drv_type] [-u unit] drive progress drive
mfiutil [-t drv_type] [-u unit] drive clear drive {start | stop}
mfiutil [-t drv_type] [-u unit] start rebuild drive
mfiutil [-t drv_type] [-u unit] abort rebuild drive
mfiutil [-t drv_type] [-u unit] locate drive {on | off}
mfiutil [-t drv_type] [-u unit] cache volume [setting [value] [...]]
mfiutil [-t drv_type] [-u unit] name volume name
mfiutil [-t drv_type] [-u unit] volume progress volume
mfiutil [-t drv_type] [-u unit] clear
mfiutil [-t drv_type] [-u unit] create type [-v] [-s stripe_size]
        drive[,drive[,...]] [drive[,drive[,...]]]
mfiutil [-t drv_type] [-u unit] delete volume
mfiutil [-t drv_type] [-u unit] add drive [volume]
mfiutil [-t drv_type] [-u unit] remove drive
mfiutil [-t drv_type] [-u unit] start patrol
mfiutil [-t drv_type] [-u unit] stop patrol
mfiutil [-t drv_type] [-u unit] patrol command [interval [start]]
mfiutil [-t drv_type] [-u unit] foreign scan
mfiutil [-t drv_type] [-u unit] foreign clear [config]
mfiutil [-t drv_type] [-u unit] foreign diag [config]
mfiutil [-t drv_type] [-u unit] foreign preview [config]
mfiutil [-t drv_type] [-u unit] foreign import [config]
mfiutil [-t drv_type] [-u unit] flash file
mfiutil [-t drv_type] [-u unit] start learn
mfiutil [-t drv_type] [-u unit] bbu setting value
mfiutil [-t drv_type] [-u unit] ctrlprop rebuild [rate]
mfiutil [-t drv_type] [-u unit] ctrlprop alarm [on|off]

🦋 DESCRIPTION 🦋

so the whole point of mfiutil is that it can display or modify a bunch of parameters on LSI MegaRAID SAS RAID controllers. every single time you invoke it, you give it zero or more global options and then a command. and psst — commands can take their own extra optional or required arguments after the command itself. 💫

The global options are:

-t drv_type — (FreeBSD only) drv_type says which type of driver you're working with; it takes either mfi or mrsas. the default type is mrsas if this tool was invoked as mrsasutil, otherwise it's mfi. (Solaris only) drv_type says which type of driver you're working with. the default type is mr_sas.
-u unit — unit says which unit of the controller you're working with. if you don't specify a unit, then unit 0 is used. simple as. ✨

Either or both of the following two global options have effect on various commands that display physical drives:

-d — print numeric device IDs as the drive identifier. this is the default. super useful in combination with -e so you can print both numeric device IDs and enclosure:slot info at the same time. 😌
-e — print drive identifiers in enclosure:slot form. (see the next paragraph for the format deets, in the context of input rather than output.) 🎀

The following global option have effect on commands that display byte values:

-p — print byte values in machine-parsable (exact) instead of human-readable values.

Drives may be specified in two forms, bestie, so listen up:

a drive may be identified by its device ID. you can find the device ID for configured drives in show config.
a drive may be identified by its location as [Exx:]Syy where xx is the enclosure and yy is the slot for each drive, exactly as displayed in show drives.

A volume may be identified by its target ID. alternatively, when you're working with the mfi(4) driver, the volume may also be specified by the corresponding mfidX device name, such as mfid0. 💅

ok so, the way that this tool is organized: mfiutil supports several different groups of commands. 🧚

The first group of commands provide information about the controller, the volumes it manages, and the drives it controls.
The second group of commands are used to manage the physical drives attached to the controller.
The third group of commands are used to manage the logical volumes managed by the controller.
The fourth group of commands are used to manage the drive configuration for the controller.
The fifth group of commands are used to manage controller-wide operations.

The informational commands include:

version — Displays the version of mfiutil. iconic lil flex. 💖
show adapter — Displays information about the RAID controller, such as the model number.
show battery — Displays information about the battery from the battery backup unit. 🔋
show config — Displays the volume and drive configuration for the controller. each array is listed along with the physical drives the array is built from. each volume is listed along with the arrays that the volume spans. and if any hot spare drives are configured, then they're listed as well. ✨
show drives — Lists all of the physical drives attached to the controller.
show events [-c class] [-l locale] [-n count] [-v] [start [stop]] — Display entries from the controller's event log. the controller maintains a circular buffer of events, and each event is tagged with a class and a locale.
- The class parameter limits the output to entries at the specified class or higher. the default class is "warn". the available classes, from lowest priority to highest, are:
  - debug — Debug messages.
  - progress — Periodic progress updates for long-running operations such as background initializations, array rebuilds, or patrol reads. ⏳
  - info — Informational messages such as drive insertions and volume creations.
  - warn — Indicates that some component may be close to failing. 😬
  - crit — A component has failed, but no data is lost. for example, a volume becoming degraded due to a drive failure.
  - fatal — A component has failed resulting in data loss. 😭
  - dead — The controller itself has died. 💀
- The locale parameter limits the output to entries for the specified part of the controller. the default locale is "all". the available locales are "volume", "drive", "enclosure", "battery", "sas", "controller", "config", "cluster", and "all".
- The count parameter is a debugging aid that specifies the number of events to fetch from the controller for each low-level request. the default is 15 events.
- By default, matching event log entries from the previous shutdown up to the present are displayed. this range can be adjusted via the start and stop parameters. each of these parameters can either be specified as a log entry number or as one of the following aliases:
  - newest — The newest entry in the event log.
  - oldest — The oldest entry in the event log.
  - clear — The first entry since the event log was cleared.
  - shutdown — The entry in the event log corresponding to the last time the controller was cleanly shut down.
  - boot — The entry in the event log corresponding to the most recent boot.
show firmware — Lists all of the firmware images present on the controller.
show foreign — Displays detected foreign configurations on disks for importation or removal. 👀
show logstate — Display the various sequence numbers associated with the event log.
show patrol — Display the status of the controller's patrol read operation.
show progress — Report the current progress and estimated completion time for active operations on all volumes and drives.
show volumes — Lists all of the logical volumes managed by the controller.

🎀 The physical drive management commands 🎀

fail drive — Mark drive as failed. drive must be an online drive that is part of an array.
good drive — Mark drive as an unconfigured good drive. drive must not be part of an existing array.
rebuild drive — Mark a failed drive that is still part of an array as a good drive suitable for a rebuild. the firmware should kick off an array rebuild on its own if a failed drive is marked as a rebuild drive. 🛠️
syspd drive — Present the drive to the host operating system directly as a system physical drive. when using the mfi(4) driver, the device node will be in format /dev/mfisyspdX. clear this state with good drive. 💅
drive progress drive — Report the current progress and estimated completion time of drive operations such as rebuilds or patrol reads.
drive clear drive {start | stop} — Start or stop the writing of all 0x00 characters to a drive.
start rebuild drive — Manually start a rebuild on drive.
abort rebuild drive — Abort an in-progress rebuild operation on drive. it can be resumed with the start rebuild command.
locate drive {on | off} — Change the state of the external LED associated with drive. ✨ blink blink ✨

🌈 The logical volume management commands 🌈

cache volume [setting [value] [...]] — If no setting arguments are supplied, then the current cache policy for volume is displayed; otherwise, the cache policy for volume is modified. one or more setting arguments may be given. some settings take an additional value argument, as noted below. the valid settings are:
- enable — Enable caching for both read and write I/O operations.
- disable — Disable caching for both read and write I/O operations.
- reads — Enable caching only for read I/O operations.
- writes — Enable caching only for write I/O operations.
- write-back — Use write-back policy for cached writes.
write-through — bestie, this one says use the write-through policy for cached writes. That's it, that's the whole vibe. ✨
read-ahead value — sets the read ahead policy for cached reads, and value can be none, adaptive, or always. pick your fighter 💅
bad-bbu-write-cache value — controls what happens with I/O write caching when the battery is dead or straight up missing 😭. value is either disable or enable. ngl the general consensus is leave this disabled, because otherwise you're risking data loss the second the system loses power. no cap.
write-cache value — controls the write caches sitting on the physical drives backing the volume. value can be disable, enable, or default.

and fr fr, leave this one disabled too, because data loss is on the table when the physical drives lose power. here's the tea: the RAID controller's battery backup does not save data in the write caches of the physical drives. it's giving false security, so don't. 💀

name volume name — sets the name of volume to name. cute, simple, iconic.
volume progress volume — reports the current progress and the estimated completion time of volume operations, like consistency checks and initializations. it's the "are we there yet" command 🎀

✨ the configuration commands ✨

the ones that actually change stuff, bestie. handle with care 🫶

clear — deletes the entire configuration. all volumes, all arrays, all spares. gone. poof. 💀 proceed with intention.
create type [-v] [-s stripe_size] drive[,drive[,...]] [drive[,drive[,...]]] — creates a new volume, slay. type tells it what kind of volume to make. the currently supported types are:
- jbod — creates a RAID0 volume for each drive specified. every drive has to be its own separate argument, so don't try to be cute and group them.
- raid0 — creates one RAID0 volume spanning the drives listed in the single drive list.
- raid1 — creates one RAID1 volume spanning the drives listed in the single drive list.
- raid5 — creates one RAID5 volume spanning the drives listed in the single drive list.
- raid6 — creates one RAID6 volume spanning the drives listed in the single drive list.
- raid10 — creates one RAID10 volume spanning multiple RAID1 arrays. the drives for each RAID1 array get specified as a single drive list.
- raid50 — creates one RAID50 volume spanning multiple RAID5 arrays. the drives for each RAID5 array get specified as a single drive list.
- raid60 — creates one RAID60 volume spanning multiple RAID6 arrays. the drives for each RAID6 array get specified as a single drive list.
- concat — creates a single volume by concatenating all of the drives in the single drive list.

Note: not all volume types are supported by all controllers. so like, vibe check your hardware first 🙈

if you drop the -v flag after type, you get more verbose output. currently it just notifies you as drives get added to arrays and arrays get added to volumes while the configuration is being built. little live commentary, we love that. 🌸

the -s stripe_size parameter lets you set the stripe size of the array. default is a stripe size of 64K. valid values are 512 through 1M, though the MFI firmware may reject some values. so it's giving "suggestions welcome, decisions final." 😭

delete volume — deletes the volume volume. bye bestie 👋
add drive [volume] — marks drive as a hot spare. the drive has to be in the unconfigured good state. if volume is specified, the hot spare gets dedicated to the arrays backing that volume. otherwise, drive is used as a global hot spare backing all arrays for this controller. and heads up: drive has to be as large as the smallest drive in all of the arrays it's going to back. no shortcuts. 📏
remove drive — removes the hot spare drive from service. it goes right back to the unconfigured good state. retirement era. ✨

👑 the controller management commands 👑

patrol command [interval [start]] — sets the patrol read operation mode. the command argument can be one of these:
- disable — disables patrol reads. nope, not today.
- auto — enables periodic patrol reads initiated by the firmware. the optional interval argument sets how many seconds between patrol reads. and if you want patrol reads running continuously, interval should just be the word continuously. the optional start argument sets a non-negative, relative start time for the next patrol read. if you don't specify an interval or a start time, the existing setting is kept. ✨
- manual — enables manual patrol reads that are only initiated by the user. you're the main character here 💅
start patrol — starts a patrol read operation. go go go 🔥
stop patrol — stops a currently running patrol read operation. okay bestie, rest. 🫶
foreign scan — scans for foreign configurations and displays how many it found. and psst — the config argument for the commands below takes the form of a number from 0 to the total configurations found. iykyk.
foreign clear [config] — clears the specified foreign config, or all of them if no config argument is given.
foreign diag [config] — displays a diagnostic display of the specified foreign config, or all of them if no config argument is given.
foreign preview [config] — previews the specified foreign config after import, or all of them if no config argument is given.
foreign import [config] — imports the specified foreign config, or all of them if no config argument is given.
flash file — updates the flash on the controller with the firmware stored in file. a reboot is required for the new firmware to take effect, so don't come for me when nothing changes without one. 😭
start learn — starts a battery relearn. and okay, fair warning: this seems to always result in the battery being completely drained, regardless of the BBU mode. in particular, the controller write cache will be disabled during the relearn even if transparent learning mode is enabled. it's giving chaos, honestly. 💀
bbu setting value — updates battery backup unit (BBU) properties related to battery relearning. here's what's configurable:
- learn-delay — adds a delay to the next scheduled battery relearn event. this setting is given in hours and must lie in the range of 0 to 255.
- autolearn-mode — enables or disables automatic periodic battery relearning. you can set it to enable or disable to respectively enable or disable the relearn cycle. or alternatively, you can give a mode of 0, 1 or 2. mode 0 enables periodic relearning, mode 1 disables it, and mode 2 disables it and logs a warning to the event log when it detects that a battery relearn should be performed. pick your poison, but like, the logging one is lowkey the responsible choice ✨
- bbu-mode — sets the BBU's mode of operation. this setting is not supported by all BBUs, so don't be shocked if yours ghosts you. where it is supported, the possible values are the integers between 1 and 5 inclusive. modes 1, 2 and 3 enable a transparent learn cycle, whereas modes 4 and 5 do not. and here's the tradeoff: the BBU's data retention time is greater when transparent learning is not used. ✨
ctrlprop rebuild [rate] — with no arguments, it displays the rate of rebuild (percentage)a for volumes. with an integer argument (0-100), it sets that value as the new rebuild rate for volumes. go fast or go careful, your call 💅
ctrlprop alarm [on|off] — with no arguments, it displays the current alarm enable/disable status. with an on or an off argument, it enables or disables the alarm. 🚨

💅 GET UNIT NUMBER OF CONTROLLERS 💅

okay bestie so here's the tea: mfiutil makes no attempt to enumerate all the installed controllers. Nope, not doing it. Instead, the correct unit number of the intended controller must be passed via the global option -u. Otherwise, the controller with unit 0 is assumed. So yeah, don't sleep on -u.

The particular ways of listing controllers differ between different drivers and kernels; the following descriptions use X to indicate the unit number. Periodt.

mfi(4) driver — This driver creates a /dev/mfiX device node for each controller it attached. A list of the available device nodes can be queried using a shell command such as:

ls -l /dev/mfi[0-9]*

mrsas(4) driver — Similar to the mfi(4) driver, this driver creates a /dev/mrsasX device node for each controller it attached.
Linux megaraid_sas(4) driver — This driver uses the global SCSI host unit number as the controller unit number; therefore if other SCSI host devices are also installed, multiple unit numbers are sometimes not continuous as users might expect. It's giving chaotic numbering, lowkey.

To find out the SCSI host unit numbers assigned to the installed controllers, list the sysfs directory /sys/class/scsi_host/, where /sys/class/scsi_host/hostX are symbolic links to different SCSI host device directories. For example:

# ls -l /sys/class/scsi_host/
total 0
lrwxrwxrwx 1 root root 0 Aug 26 00:00 host0 -> ../../devices/pci0000:00/0000:00:01.0/0000:02:00.0/host0/scsi_host/host0
lrwxrwxrwx 1 root root 0 Aug 26 00:00 host1 -> ../../devices/pci0000:00/0000:00:11.4/ata1/host1/scsi_host/host1
lrwxrwxrwx 1 root root 0 Aug 26 00:00 host2 -> ../../devices/pci0000:00/0000:00:11.4/ata2/host2/scsi_host/host2
lrwxrwxrwx 1 root root 0 Aug 26 00:00 host3 -> ../../devices/pci0000:00/0000:00:02.2/0000:05:00.0/host3/scsi_host/host3

Manual inspection must be taken to distinguish MegaRAID SAS controllers from other devices if any. No cap, you gotta look.

Newer versions of megaraid_sas(4) driver creates per-controller nodes in debugfs, so if the debugfs is mounted at conventional path, a clearer list of available controller can also be queried by listing the /sys/kernel/debug/megaraid_sas/ directory. For example:

# ls -l /sys/kernel/debug/megaraid_sas/
total 0
drwxr-xr-x 2 root root 0 May 29 11:43 scsi_host0
drwxr-xr-x 2 root root 0 May 29 11:43 scsi_host3

Solaris kernel — Drivers for Solaris kernel assign a per-driver instance number when a newly installed controller is probed; this number is then recorded, so it is generally persistent if the hardware configuration remain unchanged. Iconic behavior honestly.

The instance numbers can be queried from the path_to_inst(4) file. Simply search the double quoted driver name in it, by running:

grep -F \"driver\" /etc/path_to_inst

For example, listing instances of the mr_sas(7D) driver would be look like:

# /usr/xpg4/bin/grep -F \"mr_sas\" /etc/path_to_inst
"/pci@0,0/pci8086,2f02@1/pci1028,1f49@0" 0 "mr_sas"
"/pci@76,0/pci8086,2f04@2/pci1014,454@0" 1 "mr_sas"

Then take an appropriate instance number for use in mfiutil.

If multiple supported controllers are installed in the system, it is suggested to run a

mfiutil -u X show adapter

first to ensure the unit number X is correct for the intended controller. Do that vibe check before you commit, bestie. 🫶

✨ EXAMPLES ✨

Configure the cache for volume mfid0 to cache only writes:

mfiutil cache mfid0 writes
mfiutil cache mfid0 write-back

Create a RAID5 array spanning the first four disks in the second enclosure:

mfiutil create raid5 e1:s0,e1:s1,e1:s2,e1:s4

Configure the first three disks on a controller as JBOD:

mfiutil create jbod 0 1 2

Create a RAID10 volume that spans two arrays each of which contains two disks from two different enclosures:

mfiutil create raid10 e1:s0,e1:s1 e2:s0,e2:s1

Add drive with the device ID of 4 as a global hot spare:

mfiutil add 4

Add the drive in slot 2 in the main chassis as a hot spare for volume mfid0:

mfiutil add s2 mfid0

Reconfigure a disk as a SYSTEM physical drive with no RAID:

mfiutil syspd 0

Configure the adapter to run periodic patrol reads once a week with the first patrol read starting in 5 minutes:

mfiutil patrol auto 604800 300

Display the second detected foreign configuration:

mfiutil show foreign 1

Set the current rebuild rate for volumes to 40%:

mfiutil ctrlprop rebuild 40

🌈 SEE ALSO 🌈

mfi(4), mrsas(4)

💖 HISTORY 💖

The mfiutil utility first appeared in FreeBSD 8.0.

okay that's the whole page bestie! this was mfiutil 1.0.15-rivoreo-r2 from 2024, and you're reading MFIUTIL(8). slay 💅✨

📦 where this page comes from

ubuntu resolute: mfiutil 1.0.15-rivoreo-r2~rc-20250214-e8c6289-2 · BSD-3-Clause
ubuntu stonking: mfiutil 1.0.15-rivoreo-r2~rc-20250214-e8c6289-2 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms