Rescan SCSI Hosts Safely with rescan-scsi-bus.sh

You will rescan selected SCSI hosts for newly attached devices, check what changed, and handle resize or removal operations without rebooting. Allow about ten minutes for a normal discovery. A storage rescan can change the devices visible to the kernel, so schedule it with the same care as any other storage administration task.

This guide describes the installed sg3-utils package, version 1.46-3ubuntu4. The command reports script version 20180615 here. The manual page is dated July 2018, so keep the local output and package documentation as the authority if a later distribution changes an option.

1. Check the command and the hosts

Start with read-only checks. You need a shell and access to the SCSI host information under /sys. The scan itself normally needs elevated privileges because it asks the kernel to add, remove or update devices.

$ command -v rescan-scsi-bus.sh
/usr/bin/rescan-scsi-bus.sh
$ rescan-scsi-bus.sh --version
20180615
$ find /sys/class/scsi_host -maxdepth 1 -type l -printf '%f\n' | sort

Host numbers are the suffixes in names such as host0 and host3. Record the host that owns the adapter or path you intend to inspect. If you do not know it, do not guess: ask the storage or hardware owner, or inspect the host's devices first.

Checkpoint: the version command prints 20180615 on the system described here, and the host list contains the adapter you expect. An empty host list is a discovery problem, not a reason to add an arbitrary host number.

2. Run a normal discovery scan

Use --hosts with a comma-separated list or range. This example scans only host 3:

$ sudo rescan-scsi-bus.sh --hosts=3

To scan two hosts, use a list with no spaces. A range is also accepted:

$ sudo rescan-scsi-bus.sh --hosts=2,3
$ sudo rescan-scsi-bus.sh --hosts=2-4

The script reports changes using prefixes such as NEW, OLD and DEL. Exact lines depend on the adapter, target and kernel. A normal scan does not enable removal, does not scan every possible target, and does not update multipath devices unless you request those behaviours.

Checkpoint: save the command output with the time of the change. Confirm the resulting device nodes and kernel view before handing the storage to another service:

$ lsblk
$ dmesg --ctime | tail -40

Use the second command only if your account can read the kernel log. It is a verification aid, not a substitute for checking the storage mapping supplied by your SAN or enclosure.

3. Scan beyond the usual targets or LUNs

The default scan checks the targets and LUNs the script normally considers present. Use these options only when the storage layout requires them:

• --alltargets scans all targets, not only currently existing ones.
• --wide scans target IDs 0 through 15 instead of the default 0 through 7.
• --luns=LIST restricts the scan to selected LUNs, using values and ranges such as 0,2-4.
• -l scans LUNs 0 through 7.
• -L NUM scans LUNs 0 through NUM.
• --channels=LIST restricts the channel list.

For example, this asks host 3 to inspect target IDs 0 through 15 and LUNs 0 through 7:

$ sudo rescan-scsi-bus.sh --hosts=3 --wide -l

Do not combine every broadening option as a reflex. A wider scan takes longer and can expose paths you did not intend to use. The list syntax permits values and ranges separated by commas, with no spaces.

4. Handle resized disks and multipath

A rescan discovers devices. It does not automatically make every storage layer consume a changed capacity. For a disk or logical unit whose size has been increased, use --resize:

$ sudo rescan-scsi-bus.sh --hosts=3 --resize

The option looks for resized disks and reloads associated multipath devices where applicable. Verify the result at the layer you actually use:

$ lsblk
$ sudo multipath -ll

The multipath command is only useful when the multipath tools are installed and configured. If you use a volume manager or filesystem above the device, follow that layer's documented expansion procedure after the kernel and multipath view show the new size. Do not assume that a larger block device means the filesystem is already larger.

--multipath explicitly asks the script to update multipath devices. Use it when that is part of the intended change, and check which paths are active before proceeding. Keep the original mapping and volume-manager information available as a recovery reference.

5. Remove stale devices only with a change plan

Adding a newly presented device is usually easier to recover from than removing a device that a running process still has open. The --remove option enables removal of devices that the scan finds absent:

$ sudo rescan-scsi-bus.sh --hosts=3 --remove

Before using it, confirm that the storage owner has really withdrawn the LUN, that no filesystem is mounted from it, and that no service, volume group or backup job still expects it. Check mounts and open users:

$ findmnt
$ sudo lsof /dev/DEVICE

Replace DEVICE with the affected device name. If it is mounted or in use, stop at this checkpoint and follow the service's shutdown and unmount procedure. Do not use --remove to tidy up an uncertain device list.

--forceremove is marked dangerous by the command and removes stale devices more aggressively. --forcerescan removes and re-adds existing devices and is also marked dangerous. Leave both out of routine scans. Reconnecting storage and rescanning may rediscover a device, but it is not an undo operation for writes made through the wrong path or for a damaged multipath state.

6. Treat Fibre Channel resets as service events

--issue-lip issues a Fibre Channel LIP reset. --issue-lip-wait=SECS, or -I SECS, issues the reset and waits for the requested number of seconds. A reset can affect paths and I/O, so use it only under the storage team's change procedure:

$ sudo rescan-scsi-bus.sh --hosts=3 --issue-lip-wait=10

Do not add this option merely because a normal scan found nothing. First verify the fabric, zoning, target presentation and host number. If the reset causes a path problem, stop further scans and follow the multipath recovery procedure for the platform. There is no general command-level rollback for a Fibre Channel reset.

7. Diagnose a surprising result

Use --debug to show more of the script's discovery work, and --help to check the exact option spelling installed on this host:

$ sudo rescan-scsi-bus.sh --hosts=3 --debug
$ rescan-scsi-bus.sh --help

If a device is missing, check the selected host, target ID, channel and LUN before widening the scan. If a device is unexpectedly removed, stop using destructive options and inspect the kernel log, mounts, multipath paths and the storage presentation. If an existing disk was remapped, --update asks the script to look for existing disks that have been remapped.

For removable or intermittently presented storage, keep a record of the before and after device identity, including serial information where available. Device names such as /dev/sdb can change after discovery; scripts should use stable identifiers appropriate to the host rather than assuming a letter will remain attached to one LUN.