#3594 PR merged: docs: add iSCSI devices section to user guide

Labels: documentation

copilot-swe-agent opened issue at 2026-03-28 08:55:

No documentation existed for recovering systems that boot entirely from iSCSI (no local storage), a common enough scenario that it generated repeated support requests.

Changes

  • doc/user-guide/18-iSCSI.md — new guide covering:

    • Required local.conf settings: REQUIRED_PROGS, COPY_AS_IS, BOOT_OVER_SAN, AUTOEXCLUDE_MULTIPATH
    • NETWORKING_PREPARATION_COMMANDS pattern to automate network bring-up, iscsid start, and target login at rescue boot
    • RHEL 9+ gotcha: mkdir -p /run/lock/iscsi must precede iscsid (tmpfs directory not preserved across boots)
    • Manual login steps, pre-recovery script approach for interactive environments
    • Troubleshooting: missing lock dir, no session visible (both --loginall=automatic and explicit target login), oversized initrd

  • doc/user-guide/00-relax-and-recover-user-guide.md — adds a numbered ToC linking all 18 guide sections

Minimal working local.conf

REQUIRED_PROGS+=( iscsid iscsiadm )
COPY_AS_IS+=( /etc/iscsi /var/lib/iscsi )
BOOT_OVER_SAN=y

NETWORKING_PREPARATION_COMMANDS=(
    'ip addr add 192.168.111.222/24 dev enp6s0'
    'ip link set dev enp6s0 up'
    'sleep 1'
    'mkdir -p /run/lock/iscsi'
    'iscsid'
    'sleep 1'
    'iscsiadm -m node --loginall=automatic'
    'return'
)

jsmeix commented at 2026-03-30 07:17:

@gdha
thank you for making an official documentation about that!

I could not do it because I have zero personal experience
with iSCSI - now I learned some initial iSCSI basics
by reading this documentation.

jsmeix commented at 2026-03-31 13:49:

@gdha
what about my above
https://github.com/rear/rear/pull/3594#discussion_r3007961849
?

If all is OK as is then please state it
so it is clear what the outcome is.

[Export of Github issue for rear/rear.]