Raspberry Pi ImmortalWrt documentation

Raspberry Pi ImmortalWrtInstallation and configuration manual

A complete reference for first-time ImmortalWrt setup, covering firmware flashing, network access, OpenClash, backups, and routine maintenance. Each phase includes prerequisites, procedures, and acceptance checks.

Devices: Raspberry Pi 4B / 400 / CM4; covers OpenWrt 24.10 and 25.12 or newer

SETUP OVERVIEW

Installation sequence

  1. 01Plan
  2. 02Flash firmware
  3. 03Configure network
  4. 04Set up OpenClash
  5. 05Create backup
  6. 06Maintain system

Documentation coverage

  • Defined reading order
  • Clear LAN and WAN roles
  • Version-specific package commands
  • Acceptance checks for each phase

Use cases

Select a guide for the current state

Begin with the quick start or open the relevant section for an existing installation.

Configuration sequence

Installation and configuration steps

These six phases cover the standard deployment. Reading progress is stored in this browser and does not require an account.
Reading progress0/6 completed
  1. 8 min
    Deployment preparation

    Confirm the hardware target, network role, and configuration sequence.

    Acceptance check · The applicable network plan is selected
  2. 12 min
    Download and flash firmware

    Choose the correct target and filesystem, write the image safely, and complete first boot.

    Acceptance check · The LuCI interface opens
  3. 15 minNetwork option
    Connect to an upstream router

    Keep the existing router upstream and let the Pi obtain internet access over Ethernet.

    Acceptance check · Pi Wi-Fi clients can reach the internet
  4. 18 min
    Configure OpenClash

    Identify opkg or apk first, then import a template, add your subscription, and verify routing.

    Acceptance check · Proxy and direct rules work
  5. 10 min
    Backup and recovery preparation

    Export and verify a configuration backup, then record the firmware release and packages that require separate installation.

    Acceptance check · A usable configuration backup is stored
  6. 14 minOperations
    System maintenance

    Establish health checks, log review, and a recurring maintenance process.

    Acceptance check · A routine maintenance checklist is available

Preparation

Items to confirm before configuration

Network role

Upstream LAN and direct PPPoE

Use upstream LAN when an existing router handles internet access. Use PPPoE when the Pi dials directly. The interface settings differ between these configurations.Open PPPoE configuration

System branch

24.10 uses opkg; 25.12+ uses apk

Confirm the release and package manager before running installation commands. A mismatched package command usually does not indicate a network fault.View the release check

Filesystem

Select a filesystem for recovery and expansion requirements

Writing a fresh disk image overwrites the target media. Configuration retention depends on the upgrade and backup process, not only the EXT4 or SQUASHFS label.Read firmware selection

Technical guides

Configuration and maintenance manuals

Detailed guidance for networking, storage, proxy routing, and maintenance, organized for reference after the basic deployment.

Network scenarios

Uplink, dial-up, and connectivity

3 docs

Capabilities

Proxy, storage, and advanced configuration

3 docs

Backup and operations

Recovery, monitoring, and maintenance

3 docs

Project reference

Scripts, conventions, and release notes

3 docs

PROJECT SUPPORT

Report an issue

Include the device model, system release, network topology, failed step, and relevant check results so the problem can be reproduced.