UDPFS Server

UDPFS (User Datagram Protocol File System) is the modern, lightweight network streaming protocol built specifically for PlayStation 2 homebrew. It eliminates SMB overhead, supports on-the-fly decompression of disc images, and powers network booting in Neutrino, NHDDL, and RiptOPL.

Why UDPFS?

Unlike SMB, which requires TCP state machines, SMB dialect negotiation, session handshakes, and strict authentication trees, UDPFS operates over raw UDP datagrams. The protocol is connection-oriented at the application layer, dramatically reducing CPU and memory overhead on the PS2's Input/Output Processor (IOP).

1. Ports & Network Architecture

By default, UDPFS operates in a two-port model:

Socket	Port	Purpose
Discovery Port	UDP 62966 (`0xF5F6`)	Listens for broadcast discovery probes and initial connection requests from the PS2 console.
Data Port	Dynamic (or Pinned e.g. 62967)	Dedicated high-speed socket created for the session to handle file reads, directory listings, and block operations.

Firewall Configuration for Two-Port Operation

If you run a firewall with strict port rules, set an explicit Data port (such as 62967) on the UDPFS card or use CLI flag --data-port 62967, and allow both UDP 62966 and 62967. Alternatively, CLI flag --single-port forces discovery and data over the single port 62966.

2. Resolving "Games List But Fail to Launch"

The single most frequent support question is: "My games show up in the menu, but when I click launch, the screen goes black and nothing happens."

This is almost always caused by a dual-interface routing issue on the host PC. When a computer has active Wi-Fi and wired Ethernet simultaneously, the operating system's routing table may send UDP data replies out of the Wi-Fi adapter instead of the Ethernet cable connected to the PS2.

Identify Your PS2-Facing Network Interface

Look at the LAN IP selector at the top of the PS2 Servers window and ensure you select the adapter physically cabled to your PS2 (for example 192.168.1.100).

Pin the UDPFS Bind Address

On the UDPFS server card, locate Bind address (PC) and click the button Use LAN IP (or type that IP directly). Do NOT type 0.0.0.0 or the PS2's IP here; enter the PC's own interface IP.

Restart the Server

Click Stop on the UDPFS card, then click Start. Relaunch your game from the console menu.

Equivalent command in Core CLI:

python ps2servers.py serve udpfs --root-dir /srv/ps2 --bind 192.168.1.100

3. Protocol Modes: Auto, Standard, and Modulo

Over the years, different homebrew loaders introduced divergent implementations of the UDPFS protocol:

Standard Mode (upstream udpfsd): Uses 4KB data blocks, separate discovery and data sockets, and sequence-based acknowledgment. Used by modern Neutrino and RiptOPL.
Modulo Mode (legacy NHDDL): Employs a single socket with modulo-sequence packet pacing and smaller block buffers.
Auto Mode (Default in PS2 Servers): PS2 Servers dynamically inspects the initial connection probe from the client and automatically adapts its sequencing and protocol mode on a per-session basis.

Leave Protocol Mode on Auto

Keep Protocol mode: Auto selected. Do not check Enforce Modulo mode unless you are explicitly testing an older NHDDL build that fails during the initial handshake. Forcing Modulo mode is never the solution for a network interface binding issue.

4. On-The-Fly Disc Decompression

PS2 Servers features transparent real-time disc decompression. You can store your game library in compressed formats and stream them directly as raw DVD/CD images without decompressing them to disk beforehand.

Format	Supported Extensions	Decompression Behavior
Raw ISO	`.iso`	Streamed directly with zero CPU overhead.
CSO / CISO	`.cso`, `.ciso`	Decompressed on the fly by the server with a bounded sector cache.
ZSO / ZISO	`.zso`, `.ziso`	Decompressed on the fly by the server, or passed directly if the console loader implements LZ4 decoding natively.
CHD	`.chd`	Decompressed on the fly using native `libchdr` in Desktop and Core editions.

5. Idle Timeouts & Concurrency

PS2 Servers maintains stateful peer tracking for each active console session:

Idle Timeout: Defaults to 3600 seconds (1 hour). If a console is powered off or paused for longer than this duration, open file descriptors are cleanly closed. Configurable from 60 to 86400 seconds via CLI flag --peer-timeout.
Multiple Consoles: Both Python (Desktop/Core) and Go (Edge) implementations support multiple concurrent PS2 consoles playing different games simultaneously from the same shared folder.