Metadata-Version: 2.4
Name: remap_badblocks
Version: 1.0.2
Summary: CLI tool for remapping bad sectors on Linux disks using device-mapper
Author-email: Luigi Privitera <ti8wqs97k@mozmail.com>
License-Expression: GPL-3.0-only
Project-URL: Repository, https://gitlab.com/Luigi-98/remap_badblocks.git
Project-URL: Issues, https://gitlab.com/Luigi-98/remap_badblocks/-/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: packaging
Provides-Extra: dev
Requires-Dist: mypy; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Dynamic: license-file

# remap-badblocks

`remap-badblocks` is a Linux CLI tool written in Python that scans a block device for bad sectors and creates a device-mapper target that skips over them. It can also reserve extra space to dynamically remap future badblocks.

It's a simple way to extend the usefulness of slightly damaged drives, ideal for anyone who wants to avoid discarding a disk due to a few bad sectors. This can also be useful for disk rescue, when your broken disk fails when reading some of its sectors (see example workflow below).

## Features

* Scans disks using `badblocks` to identify damaged sectors
* Creates a `device-mapper` target that avoids bad sectors
* Reserves spare sectors for dynamic remapping
* Supports using only part of a device (e.g., for hard partitioning or isolation)

## Installation

### From PyPI

```bash
pip install remap-badblocks
```

### From source

```bash
git clone [https://gitlab.com/Luigi-98/remap-badblocks.git](https://gitlab.com/Luigi-98/remap-badblocks.git)
cd remap-badblocks
pip install -e .
```

## Usage

### Database

`remap-badblocks` relies on a single source of stateful storage: a SQLite database. By default, it is stored at `/etc/remap_badblocks/devices_config.db`, but you can specify an alternative location using the `-P` option.

### Device Model

A **device** in `remap-badblocks` is a logical configuration that:

* points to a physical block device (e.g. `/dev/sda`)
* scans bad blocks and keeps track of them over time
* defines how they are remapped using spare sectors
* creates a virtual block device that actually remaps broken sectors to good ones

The actual `/dev/mapper/...` device is only created when you run `apply`.

### CLI Overview

```bash
remap-badblocks -h

Usage: remap-badblocks [OPTIONS] COMMAND [ARGS]...

Badblocks remapper for block devices.

Commands:
  init            Initialize a device (add + scan + remap + apply)
  update-mapping  Scan for new badblocks, update mapping, and apply
  apply           Apply an existing mapping (recreate /dev/mapper device)

  device          Low-level device operations
  version         Show version
```

### High-level commands (recommended)

These commands cover the most common workflows:

```bash
# Initialize a device (first-time setup)
remap-badblocks init my_disk --path /dev/sda --spare-space 100MB

# Periodically update mapping with new badblocks
remap-badblocks update-mapping --name my_disk --mode read

# Recreate the device-mapper (e.g. after reboot)
remap-badblocks apply
```

### Low-level commands

You can also control each step individually and do some tweaking of the devices:

```bash
remap-badblocks device -h

Commands:
  add       Define a new device (no mapping yet)
  list      List devices
  get       Show device info from DB
  set       Modify device configuration
  remove    Remove a device

  scan      Scan for badblocks (updates DB only)
  remap     Update mapping based on known badblocks
  apply     Apply mapping to create /dev/mapper device

  badblocks Further subcommands for badblocks
```

### Advanced workflows

#### Manual control

```bash
# Define device (choose spare space here)
remap-badblocks device add my_disk --path /dev/sda --spare-space 100MB

# Scan disk
remap-badblocks device scan my_disk --mode read

# Update mapping
remap-badblocks device remap my_disk

# Apply mapping
remap-badblocks device apply my_disk
```

#### Incremental remapping (data recovery scenario)

```bash
# Scan for new badblocks only
remap-badblocks device scan my_disk

# Remap all badblocks that were not remapped so far
remap-badblocks device remap my_disk
```

This allows updating the mapping without rebuilding it from scratch, minimizing disruption and preserving data access.

### Disk rescue workflow (read-first, map-later)

`remap-badblocks` can also be used as a *read stabilizer* for damaged disks during data recovery. The idea is to:

1. create an initial mapping table without taking badblocks into account, this way you can preserve the original sector order,
2. remap broken sectors, so that disk doesn't fail trying to read from them,
3. use external tools to copy the data.
    - if new badblocks need to be remapped during rescue, you can pause the rescue, scan for new badblocks and remap them live without any downtime for the virtual remapper device

#### Step 1 — Define the device without scanning

Create the device and reserve spare sectors, but **do not scan yet**:

```bash
remap-badblocks device add rescue_disk --path /dev/sda --spare-space 10MB
remap-badblocks device remap --name rescue_disk --ignore-badblocks
```

At this point there are **no badblocks recorded** and no remapping logic applied beyond reserving space.

#### Step 2 — Remap broken sectors

Now that you've got a 1:1 mapping from real device to virtual device, you can remap badblocks to spare sectors.

If you already have a list of badblocks, you can avoid further disk wear by doing this:

```bash
remap-badblocks device scan --name rescue_disk --mode skip --known-badblocks-file /my/known/badblocks/list.txt
remap-badblocks device remap --name rescue_disk
remap-badblocks device apply --name rescue_disk
```

Otherwise, let remap-badblocks scan the disk for you before remapping.

```bash
sudo remap-badblocks device scan --name rescue_disk --mode read
remap-badblocks device remap --name rescue_disk
sudo remap-badblocks device apply --name rescue_disk
```

Now your virtual disk can be accessed at `/dev/mapper/rescue_disk` as a block device.

#### Step 3 — Run your recovery tool

Use tools like `ddrescue`, `testdisk`, or filesystem-specific recovery utilities against the mapper:

```bash
ddrescue /dev/mapper/rescue_disk image.img mapfile
```

##### Incrementally handle read errors

When read errors occur, you can still remap badblocks without taking the device down. I/O will be suspended only during the apply command, so that no downtime is needed.

**Option A — Targeted scan (avoid if possible)**

```bash
sudo remap-badblocks device scan --name rescue_disk --mode read
remap-badblocks device remap --name rescue_disk
sudo remap-badblocks device apply --name rescue_disk --allow-reapply
```

**Option B — Manual intervention (advanced, but avoids wearout of disk)**
If you know the failing block ranges from your recovery tool, you can add/remap them directly, then re-apply.

```bash
sudo remap-badblocks device scan --name rescue_disk --mode skip --known-badblocks-file /my/known/badblocks/list.txt
remap-badblocks device remap --name rescue_disk
sudo remap-badblocks device apply --name rescue_disk --allow-reapply
```

## Contributing

We welcome feedback, bug reports, feature ideas, code contributions, and help shaping the roadmap — or even rethinking the project from the ground up.

Start with CONTRIBUTING.md, then open an issue or submit a merge request to get involved.

## License

GPL v3 License — see LICENSE for details.

## Community

* GitLab: [remap-badblocks project page](https://gitlab.com/Luigi-98/remap_badblocks)
* PyPI: [remap-badblocks](https://pypi.org/project/remap-badblocks/)
* Issues: [remap-badblocks Gitlab issues](https://gitlab.com/Luigi-98/remap_badblocks/-/issues)

## Acknowledgements & Related Tools

* [`badblocks`](https://linux.die.net/man/8/badblocks)
* [`device-mapper`](https://linux.die.net/man/8/dmsetup)
