Skip to content

Commit c97e2fa

Browse files
dipakparmardipakparmar
committed
docs: add Ubiquiti EdgeRouter USB recovery guide
1 parent c1d3c41 commit c97e2fa

File tree

2 files changed

+382
-0
lines changed

2 files changed

+382
-0
lines changed

‎docs/networking/ubnt/_category_.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"label": "Ubiquiti",
3+
"collapsible": true,
4+
"collapsed": true,
5+
"link": {
6+
"type": "generated-index",
7+
"title": "Ubiquiti Networking"
8+
}
9+
}

‎docs/networking/ubnt/ubnt-edgerouter-usb-recovery.mdx‎

Lines changed: 373 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,373 @@
1+
---
2+
id: ubnt-edgerouter-usb-recovery
3+
title: 'Replacing Failed USB Flash on Ubiquiti EdgeRouter: A Recovery Guide'
4+
sidebar_label: EdgeRouter USB Recovery
5+
keywords:
6+
[
7+
ubnt,
8+
ubnt edgerouter,
9+
edgerouter usb recovery,
10+
edgerouter flash replacement,
11+
edgerouter usb flash failed,
12+
edgerouter recovery guide,
13+
edgerouter troubleshooting,
14+
edgerouter usb repair,
15+
edgerouter usb flash recovery,
16+
edgerouter usb flash replacement guide,
17+
edgerouter usb flash troubleshooting,
18+
edgerouter usb flash repair guide
19+
edgerouter lite usb recovery
20+
edgerouter poe usb recovery
21+
edgerouter poe flash replacement
22+
]
23+
description: 'A step-by-step guide to replacing a failed USB flash drive on Ubiquiti EdgeRouter.'
24+
tags: [Networking, Ubiquiti, EdgeRouter]
25+
---
26+
27+
28+
*When your EdgeRouter dies silently, it's probably the USB flash. Here's how I recovered from yet another flash failure.*
29+
30+
## The Problem
31+
32+
33+
If you're experiencing any of these issues with your Ubiquiti EdgeRouter:
34+
35+
- **Router keeps running** but **fails to boot after a reboot**
36+
- **Boot loops** or **kernel panic on startup**
37+
- **System appears to work** but logs errors about missing configuration files
38+
- **Can't SSH in** after rebooting, but was fine before
39+
- **DHCP or firewall rules** suddenly not applying after a restart
40+
41+
...your internal USB flash drive has likely failed.
42+
43+
## The Solution
44+
45+
The recovery process involves creating a new bootable USB drive with EdgeOS. While Ubiquiti provides the OS tarball, you can't just extract it to a USB stick – it needs proper partitioning, formatting, and careful placement of the boot files.
46+
47+
Fortunately, **[mkeosimg](https://github.com/deimosfr/mkeosimg)** Orignally by [sowbug](https://github.com/sowbug) exists to automate most of the process. This bash script takes an EdgeOS tarball and produces a ready-to-use disk image.
48+
49+
:::warning
50+
51+
Double-check remote scripts, i'm not affiliated with Ubiquiti or the script author. Use at your own risk. You should always verify the contents of any script before running it with elevated privileges.
52+
53+
:::
54+
55+
56+
## What You'll Need
57+
58+
Before you start, make sure you have:
59+
60+
- A **machine** running any Debian/Ubuntu-based Linux distribution
61+
- An **EdgeOS tarball** (the release image from Ubiquiti) --> you can download it from [Ubiquiti's website](https://ui.com/download)
62+
- A **USB drive or SD card** (at least 2GB; 4GB+ is safer)
63+
- **About 4GB of free disk space** on your machine
64+
- The **mkeosimg script** (or you can clone it from GitHub)
65+
66+
67+
## Step 1: Install the Required Tools
68+
69+
The mkeosimg script depends on several command-line utilities. Let's verify they're installed:
70+
71+
```bash
72+
which losetup parted mkfs.msdos mkfs.ext3 tar dd
73+
```
74+
75+
You should see paths for all of these commands. If not, install the missing ones:
76+
77+
```bash
78+
sudo apt update
79+
sudo apt install -y parted e2fsprogs dosfstools
80+
```
81+
82+
These packages provide:
83+
- **parted** – for disk partitioning
84+
- **e2fsprogs** – includes `mkfs.ext3` for ext3 filesystems
85+
- **dosfstools** – includes `mkfs.msdos` for FAT32
86+
- The others (`losetup`, `tar`, `dd`) are part of the base OS
87+
88+
Quick verification:
89+
90+
```bash
91+
parted --version
92+
mkfs.msdos -h 2>&1 | head -1
93+
mkfs.ext3 -h 2>&1 | head -1
94+
```
95+
96+
## Step 2: Prepare Your EdgeOS Tarball
97+
98+
Get the EdgeOS release image ready:
99+
100+
```bash
101+
ls -lh *.tar
102+
```
103+
104+
You should see something like:
105+
```
106+
edgeos-v2.1.10-amd64-20250101.tar (100-500MB typically)
107+
```
108+
109+
If you have a custom EdgeOS config you want to include:
110+
111+
```bash
112+
ls -l edgeos_config.tar.gz
113+
```
114+
115+
If this file exists, the script will apply it when creating the image (and add a `-configured` suffix to the output filename).
116+
117+
118+
## Step 3: Identify Your USB Drive (The Critical Part)
119+
120+
This is where you need to be careful. Identifying the wrong device could be destructive.
121+
122+
### List all disks:
123+
124+
```bash
125+
lsblk
126+
```
127+
128+
Example output:
129+
```
130+
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
131+
sda 8:0 1 14.9G 0 disk
132+
├─sda1 8:1 1 512M 0 part
133+
└─sda2 8:2 1 14.4G 0 part
134+
sdb 8:16 0 931.5G 0 disk
135+
├─sdb1 8:17 0 256M 0 part /boot
136+
└─sdb2 8:18 0 931.2G 0 part /
137+
```
138+
139+
### How to identify your USB drive:
140+
141+
- **Look for a device in `/dev/sdX`** (where X is a letter like `a`, `b`, `c`)
142+
- **Check the size** – your USB drive should be smaller than your Pi's main storage
143+
- **Check RM column** – removable media will show `1`
144+
- **Check MOUNTPOINT** – USB drives are often unmounted (empty)
145+
146+
In the example above, `/dev/sda` (14.9G) is likely the USB drive, while `/dev/sdb` (931.5G) is the Pi's main storage.
147+
148+
### Verify before proceeding:
149+
150+
```bash
151+
sudo fdisk -l /dev/sdX
152+
```
153+
154+
Replace `sdX` with your identified device. Check:
155+
- The size matches your USB drive
156+
- It's not your Pi's system drive
157+
158+
**If you're unsure, stop here and double-check.** Writing to the wrong device is irreversible.
159+
160+
161+
## Step 4: Run the mkeosimg Script
162+
163+
### Get the script:
164+
165+
You can clone it from GitHub or copy it directly:
166+
167+
```bash
168+
git clone https://github.com/deimosfr/mkeosimg.git
169+
cd mkeosimg
170+
```
171+
172+
Or if you already have it:
173+
174+
```bash
175+
cd /path/to/mkeosimg
176+
chmod +x mkeosimg.sh
177+
```
178+
179+
### Run it with your tarball:
180+
181+
```bash
182+
sudo ./mkeosimg.sh edgeos-v2.1.10-amd64-20250101.tar
183+
```
184+
185+
Replace the filename with your actual EdgeOS tarball.
186+
187+
### What it does:
188+
189+
1. **Creates a 2GB disk image** file (`.img`)
190+
2. **Partitions it** into boot (150MB) and root (1750MB) sections
191+
3. **Formats the partitions** with FAT32 and ext3
192+
4. **Extracts the EdgeOS release** into the image
193+
5. **Verifies checksums** to ensure nothing got corrupted
194+
6. **Applies your custom config** (if you have one)
195+
7. **Creates data directories** for EdgeOS's writable files
196+
197+
The whole process takes a few minutes. You'll see output like:
198+
199+
```
200+
Creating edgeos-v2.1.10-amd64-20250101.img
201+
2048+0 records in
202+
2048+0 records out
203+
...
204+
Unpacking EdgeOS release image
205+
Verifying EdgeOS kernel
206+
Copying EdgeOS kernel to boot partition
207+
...
208+
Done.
209+
```
210+
211+
When you see "Done." at the end, your image is ready.
212+
213+
214+
## Step 5: Write the Image to Your USB Drive
215+
216+
Now comes the moment of truth. **Triple-check your device name one more time:**
217+
218+
```bash
219+
lsblk
220+
```
221+
222+
### Unmount the USB drive:
223+
224+
```bash
225+
sudo umount /dev/sdX*
226+
```
227+
228+
This ensures nothing is locked while we write to it.
229+
230+
### Write the image:
231+
232+
```bash
233+
sudo dd if=edgeos-v2.1.10-amd64-20250101.img of=/dev/sdX bs=4M status=progress
234+
```
235+
236+
**Important notes:**
237+
- `if=` is the input file (your `.img` file)
238+
- `of=` is the output device (your USB drive—**not a partition number**, just `/dev/sda`, not `/dev/sda1`)
239+
- `bs=4M` writes in 4MB chunks for speed
240+
- `status=progress` shows you how far along it is
241+
242+
Wait for it to complete. You'll see something like:
243+
244+
```
245+
15728640000 bytes (15.7 GB) copied, 45.2 s, 348 MB/s
246+
```
247+
248+
### Sync to ensure everything is written:
249+
250+
```bash
251+
sudo sync
252+
echo "Write complete"
253+
```
254+
255+
The `sync` command flushes any buffered data to disk. Don't unplug the USB drive until this completes.
256+
257+
258+
## Step 6: Replace the Failed USB in Your EdgeRouter
259+
260+
### For EdgeRouter Lite (internal USB):
261+
262+
The original EdgeRouter Lite units have an internal USB flash drive. To replace it:
263+
264+
1. **Power off** the EdgeRouter completely
265+
2. **Open the case** (remove screws on the bottom)
266+
3. **Locate the internal USB** (it's a small USB stick plugged into the internal header)
267+
4. **Remove the dead USB** and **insert your new one**
268+
5. **Close the case** and power on
269+
270+
The router should boot from the new USB flash drive.
271+
272+
### For external USB recovery:
273+
274+
If you're using this as an external recovery drive:
275+
276+
1. **Eject safely** from your Pi:
277+
```bash
278+
sudo eject /dev/sdX
279+
```
280+
281+
2. **Insert the USB** into your EdgeRouter
282+
283+
3. **Power on** and access the boot menu (DEL/F12/ESC depending on model)
284+
285+
4. **Select the USB** as the boot device
286+
287+
5. EdgeOS should load from your new drive
288+
289+
290+
## Troubleshooting
291+
292+
### "Must run as root or with sudo"
293+
294+
Make sure you're using `sudo`:
295+
```bash
296+
sudo ./mkeosimg.sh your-image.tar
297+
```
298+
299+
### "parted: command not found"
300+
301+
Install it:
302+
```bash
303+
sudo apt install parted
304+
```
305+
306+
### "mkfs.ext3: No such file or directory"
307+
308+
Install e2fsprogs:
309+
```bash
310+
sudo apt install e2fsprogs
311+
```
312+
313+
### "Kernel in image is corrupted!"
314+
315+
Your EdgeOS tarball is damaged. Try:
316+
```bash
317+
md5sum edgeos-v2.1.10*.tar
318+
```
319+
320+
Compare the checksum with the official EdgeOS release. If it doesn't match, re-download the tarball.
321+
322+
### "Device busy" when writing
323+
324+
The USB drive is still mounted. Unmount it:
325+
```bash
326+
sudo umount /dev/sdX*
327+
```
328+
329+
### Not enough disk space
330+
331+
Free up space on your Pi:
332+
```bash
333+
df -h
334+
sudo apt clean
335+
rm -rf ~/Downloads/*
336+
```
337+
338+
## Why Use mkeosimg?
339+
340+
Instead of manually:
341+
- Creating a disk image with `dd`
342+
- Partitioning with `parted`
343+
- Formatting each partition
344+
- Extracting and positioning kernel and filesystem images
345+
- Verifying checksums
346+
- Setting ownership and permissions
347+
348+
...mkeosimg handles all of this in one command. When you're dealing with a failed router at a client site (or in a data center), you want a reliable, tested process—not a series of manual steps where one typo could waste an hour.
349+
350+
351+
## Credits
352+
353+
This guide uses the **[mkeosimg](https://github.com/deimosfr/mkeosimg)** script, modified version of the original by [sowbug](https://github.com/sowbug). Huge thanks to both authors for making EdgeRouter recovery easier for all of us.
354+
355+
356+
## Next Steps
357+
358+
Once your EdgeRouter is booted with the new USB flash:
359+
360+
1. **Restore your configuration backup** (you have one, right?)
361+
2. **Update to the latest EdgeOS** version
362+
3. **Test all network interfaces** and routes
363+
4. **Verify firewall rules** are working
364+
5. **Set up automated config backups** to prevent future headaches
365+
366+
If you don't have a config backup, you'll need to reconfigure from scratch. This is a painful lesson learned once—always keep recent backups of your router configs.
367+
368+
369+
## Final Thoughts
370+
371+
The EdgeRouter Lite is a solid piece of hardware, but those internal USB flash drives are its Achilles' heel. If you manage multiple EdgeRouter units, keep a few spare USB drives pre-imaged and ready to go. Your future self (or your on-call engineer at 2 AM) will thank you.
372+
373+

0 commit comments

Comments
 (0)