NBD Server

NBD Server

RiptOPL can turn the PS2 into an NBD (Network Block Device) server, exposing the internal HDD to any PC on your LAN. The implementation is based on lwNBD — a formally-documented, open-standard NBD protocol stack. Once connected, the drive appears to the host OS the same way it would if physically attached, so any tool that works directly on the drive (including hdl_dump and pfs-shell) works identically over NBD.

ℹ NBD replaces the old HDL server

OPL used to ship an HDL server for remote HDD access. NBD supersedes it. The protocol is an open standard (NBD protocol spec); any compliant NBD client will work.

Prerequisites

• An internal HDD installed in the PS2 (original or HDD OSD-format is fine; APA layout).
• A network adapter and Ethernet cable — the same adapter used for SMB or network boot.
• RiptOPL configured with an IP address: either a static IP or DHCP, set under Settings → Network. The PS2's IP address is what you will connect to.
• An NBD client installed on the host PC (see the per-OS sections below).

ℹ Read-only vs read-write

The NBD server exports the drive as read-only when the Write Operations option is off in RiptOPL's settings, and as read-write when it is on. Write Operations is the same toggle that controls rename/delete in the game lists. Be careful with write access: direct block-level writes bypass all filesystem safety checks.

Starting the server

Open the main menu

From any game list, press Triangle to open the main menu.

Select "Start NBD Server"

Scroll to Start NBD Server and confirm. RiptOPL will display "NBD Server starting…" while it loads the network and ATA modules, then "NBD Server running…" once the server is live.

Connect from your PC

Use one of the client options below (Linux nbd-client, Linux/WSL2 nbdfuse, or Windows wnbd) to mount the drive. macOS is not supported.

Disconnect and exit

Disconnect the client first, then dismiss the "NBD Server running…" message box on the PS2. RiptOPL will display "NBD Server unloading…" and then return to the normal menu.

ℹ Audio is suspended while the server runs

RiptOPL mutes the audio library while the NBD server is active and restores it when the server is dismissed. This is expected behaviour.

Export name

The NBD server exports a single device. By default the export name is hdd0. You can override this by setting nbd_default_export in conf_network.cfg (the network configuration file stored alongside your other config files on your boot device). Leave it blank or omit the key to keep the default hdd0.

nbd_default_export=hdd0

When listing available exports (see the client sections below), the server will report whatever name is configured here.

nbd-client (Linux)

Supported on: Linux, and Windows with WSL using a custom kernel that includes NBD support.

nbd-client requires the nbd kernel module. Load it if it is not already present:

sudo modprobe nbd

List the available exports (replace the IP with your PS2's IP):

nbd-client -l 192.168.1.45

Connect the drive to a block device node (you may need sudo, or membership in the disk group):

nbd-client 192.168.1.45 /dev/nbd1

Disconnect:

nbd-client -d /dev/nbd1

Once connected, /dev/nbd1 behaves like a directly-attached disk. Partition tools, hdl_dump, pfs-shell, and hex editors all work against it.

nbdfuse (Linux / WSL2)

Supported on: Linux and Windows with WSL2. nbdfuse and nbdinfo are part of libnbd; install the libnbd-bin package on Debian/Ubuntu or the equivalent on your distro.

List available exports:

nbdinfo --list nbd://192.168.1.45

Mount the drive as a file (the directory must exist first):

mkdir ps2
nbdfuse ps2/ nbd://192.168.1.45 &

The drive appears as a raw disk image file inside the ps2/ directory. Unmount:

umount ps2

wnbd (Windows)

Supported on: Windows. Download and install WNBD (Cloudbase Solutions), then reboot. Open an elevated PowerShell (Run as Administrator).

Connect (the first argument is a label you choose; the second is the PS2's IP):

wnbd-client.exe map hdd0 192.168.1.22

The drive will appear in Disk Management as a new disk. Disconnect:

wnbd-client.exe unmap hdd0

macOS

macOS is not supported. There is no NBD client available for macOS that is compatible with the lwNBD server.

Using hdl_dump over NBD

Once the drive is connected via any of the clients above, hdl_dump treats the exposed block device (or file) the same as a local drive. A typical workflow to install a game image to the PS2's HDD:

Connect the NBD client

Follow the steps for your OS above. Note which device node or mount path you are using (e.g. /dev/nbd1).

Run hdl_dump

Pass the device path as the target. For example, to inject a DVD image:

hdl_dump inject_dvd ps2/nbd "Test Game" ./TEST.ISO

Replace ps2/nbd with the actual block device or mount path for your setup.

Disconnect

Disconnect the NBD client, then dismiss the server on the PS2.

ℹ Other tools

pfs-shell (from the ps2sdk tool set) and even a hex editor work the same way — any tool that operates on a raw block device or disk image will work once the drive is mounted via NBD.

What happens internally when the server starts?

Selecting Start NBD Server calls handleLwnbdSrv() in src/opl.c. This function:

1. Suspends the audio library (audioEnd()).
2. Blocks pending I/O operations and waits for them to finish.
3. Unloads the gamepad drivers.
4. Loads the Ethernet modules via ethLoadInitModules() (the same path used for SMB / network boot).
5. Loads ps2atad.irx for low-level ATA access, then lwnbdsvr.irx — the lwNBD IOP module — passing a small config struct that sets the export name (defaulting to hdd0 if nbd_default_export is blank) and the read-only flag (derived from gEnableWrite).
6. Displays "NBD Server running…" and blocks until the user dismisses the message box.
7. On dismissal, unloadLwnbdSvr() tears down the Ethernet modules and calls reset() to return OPL to its normal state.

The lwNBD source is vendored from github.com/bignaux/lwNBD at a pinned commit, downloaded by download_lwNBD.sh into modules/network/lwNBD/ at build time.

Related pages

• 💽 Internal HDD APA/PFS & exFAT (BDMA) setup

• 📡 Network Boot Stream games over LAN via UDPBD/UDPFS

• 🌐 SMB Share a PC folder as a game source

• 🔧 Settings Reference All settings including Write Operations

---

Source: nbd.html @ fc2e13154e51. Read on the documentation website.