{"id":40560004,"url":"https://github.com/asimkadav/block-filter","last_synced_at":"2026-01-21T00:40:36.741Z","repository":{"id":146000582,"uuid":"13184343","full_name":"asimkadav/block-filter","owner":"asimkadav","description":"linux block filter driver","archived":false,"fork":false,"pushed_at":"2013-09-29T02:05:15.000Z","size":112,"stargazers_count":14,"open_issues_count":2,"forks_count":10,"subscribers_count":2,"default_branch":"master","last_synced_at":"2023-03-23T08:50:39.243Z","etag":null,"topics":["block-driver","block-filter-driver","linux","samplecode"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/asimkadav.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-09-29T01:54:44.000Z","updated_at":"2023-03-23T11:05:57.905Z","dependencies_parsed_at":"2023-03-23T11:05:57.691Z","dependency_job_id":null,"html_url":"https://github.com/asimkadav/block-filter","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"purl":"pkg:github/asimkadav/block-filter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asimkadav%2Fblock-filter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asimkadav%2Fblock-filter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asimkadav%2Fblock-filter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asimkadav%2Fblock-filter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asimkadav","download_url":"https://codeload.github.com/asimkadav/block-filter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asimkadav%2Fblock-filter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28619994,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T23:49:58.628Z","status":"ssl_error","status_checked_at":"2026-01-20T23:47:29.996Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["block-driver","block-filter-driver","linux","samplecode"],"created_at":"2026-01-21T00:40:36.098Z","updated_at":"2026-01-21T00:40:36.729Z","avatar_url":"https://github.com/asimkadav.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"Block Filter Driver\n===================\n\nA simple block I/O filter driver for modern Linux kernels (5.0+). This driver creates a virtual block device that intercepts and forwards I/O requests to an underlying block device, allowing monitoring, logging, and potential modification of block I/O operations.\n\n**Updated for Linux Kernel 5.0+** - This version has been modernized to use the blk-mq (multi-queue block layer) API instead of the deprecated request_fn interface.\n\n## Features\n\n- **Modern Kernel Support**: Compatible with Linux kernels 5.0 and above\n- **Bio-based Filtering**: Intercepts block I/O at the bio submission level\n- **Configurable Target Device**: Use module parameters to specify which device to filter\n- **Statistics Tracking**: Counts processed I/O operations\n- **Proper Resource Management**: Safe device reference counting and error handling\n- **Control Interface**: Misc device for querying statistics via ioctl\n\n## Requirements\n\n- Linux kernel 5.0 or newer\n- Kernel headers for your running kernel\n- GCC and make\n- Root privileges for loading/unloading the module\n\n## How It Works\n\nThe driver operates by:\n\n1. **Creating a Virtual Block Device**: Allocates a new block device (`/dev/blockfilter`) using the modern `blk_alloc_disk()` API\n2. **Opening the Target Device**: Safely opens the target block device (e.g., `/dev/sda1`) with proper reference counting using `blkdev_get_by_path()`\n3. **Intercepting I/O**: Implements a `submit_bio` callback that intercepts all bio submissions to the filter device\n4. **Forwarding Requests**: Clones each bio and forwards it to the underlying target device using `submit_bio_noacct()`\n5. **Logging \u0026 Statistics**: Logs I/O operations and maintains counters for monitoring\n\nThis approach allows transparent interception of block I/O without modifying the target device or filesystem.\n\n## Building\n\n```bash\ncd misc\nmake\n```\n\nThis will compile the `misc.ko` kernel module.\n\n## Installation\n\n### Loading the Module\n\nBasic usage with default settings (targets `/dev/sda1`):\n```bash\nsudo insmod misc.ko\n```\n\nSpecify a custom target device:\n```bash\nsudo insmod misc.ko target_device=/dev/sdb1\n```\n\n**WARNING**: Be very careful when specifying target devices. Incorrect usage could interfere with disk I/O.\n\n### Checking Module Status\n\nView kernel messages:\n```bash\ndmesg | tail -20\n```\n\nList loaded modules:\n```bash\nlsmod | grep misc\n```\n\nCheck module information:\n```bash\nmodinfo misc.ko\n```\n\n### Unloading the Module\n\n```bash\nsudo rmmod misc\n```\n\n### System Installation (Optional)\n\nTo install the module system-wide:\n```bash\nsudo make install\n```\n\nTo uninstall:\n```bash\nsudo make uninstall\n```\n\n## Usage\n\n### Module Parameters\n\n- **target_device** (string): Path to the block device to filter\n  - Default: `/dev/sda1`\n  - Example: `target_device=/dev/nvme0n1p1`\n\n### Control Interface\n\nThe driver creates a misc device at `/dev/blockfilter` that supports ioctl commands:\n\n**Get I/O Statistics**:\n```c\n#include \u003csys/ioctl.h\u003e\n#include \u003cfcntl.h\u003e\n\n#define MISC_GET _IOR('B', 0x01, unsigned long)\n\nint fd = open(\"/dev/blockfilter\", O_RDONLY);\nunsigned long bio_count;\nioctl(fd, MISC_GET, \u0026bio_count);\nprintf(\"Total BIOs processed: %lu\\n\", bio_count);\nclose(fd);\n```\n\n### Viewing Debug Output\n\nEnable debug messages:\n```bash\necho 8 \u003e /proc/sys/kernel/printk\n```\n\nView real-time kernel logs:\n```bash\nsudo dmesg -w\n```\n\n## Code Structure\n\n```\nmisc/\n├── misc.c       - Main driver implementation\n├── misc.h       - Header with ioctl definitions\n└── Makefile     - Build configuration\n```\n\n### Key Functions\n\n- `filter_submit_bio()`: Bio submission callback that intercepts I/O\n- `register_block_device()`: Opens target device and creates filter device\n- `unregister_block_device()`: Cleanup and resource release\n- `mischelp_ioctl()`: Control interface for statistics and management\n\n## Important Changes from Original Version\n\nThis modernized version includes:\n\n1. **Modern Block Layer API**: Uses `blk_alloc_disk()` and `submit_bio` instead of deprecated `request_fn`\n2. **Proper Reference Counting**: Uses `blkdev_get_by_path()`/`blkdev_put()` for safe device access\n3. **Comprehensive Error Handling**: All error paths properly cleanup resources\n4. **NULL Pointer Protection**: Validates all pointers before use\n5. **Module Parameters**: Configurable target device without recompilation\n6. **Better Logging**: Uses `pr_*` macros with appropriate log levels\n7. **Thread Safety**: Uses mutex for synchronization\n8. **Atomic Statistics**: Lock-free statistics using atomic64_t\n9. **Proper IOCTL Definitions**: Uses standard `_IOR`/`_IOW` macros\n10. **Clean Code**: Removed unused headers and improved documentation\n\n## Limitations \u0026 Caveats\n\n- **Educational Purpose**: This is a demonstration driver, not production-ready\n- **Performance Impact**: Bio cloning adds overhead to I/O path\n- **No Hot-Plug Support**: Target device must exist when module loads\n- **Single Target**: Only supports one target device per module instance\n- **Root Required**: Must run as root to load kernel modules\n\n## Safety Warnings\n\n⚠️ **IMPORTANT SAFETY NOTES**:\n\n- This module operates at the kernel level and can cause system instability if misused\n- Always test on non-production systems first\n- Specifying the wrong target device could cause data loss\n- The default target (`/dev/sda1`) may be your system drive - change it if needed\n- Kernel panics are possible if the target device is removed while the module is loaded\n\n## Troubleshooting\n\n**Module fails to load**:\n- Check kernel version: `uname -r` (must be 5.0+)\n- Verify kernel headers are installed: `ls /lib/modules/$(uname -r)/build`\n- Check dmesg for specific error messages\n\n**Target device errors**:\n- Ensure the device path exists: `ls -l /dev/sda1`\n- Verify you have permission to access the device\n- Check that the device is not exclusively locked by another process\n\n**Compilation errors**:\n- Ensure kernel headers match your running kernel\n- Update to latest kernel headers: `sudo apt update \u0026\u0026 sudo apt install linux-headers-$(uname -r)`\n\n## Development \u0026 Debugging\n\nEnable additional debugging by modifying the code:\n- Change `pr_debug()` to `pr_info()` in `misc.c:107` to see all I/O operations\n- Add custom logic in `filter_submit_bio()` to inspect/modify I/O requests\n\n## Backstory\n\nThe original driver was written in 2013 for Linux 3.x kernels. This updated version (2025) modernizes the code for current Linux kernels (5.0+), which underwent major block layer rewrites. The kernel's transition from request_fn to blk-mq required a complete rewrite of the I/O interception mechanism.\n\n## License\n\nMIT License - See source files for full license text.\n\n## Keywords\n\nLinux kernel, block filter driver, blk-mq, bio interception, block I/O monitoring, device mapper, kernel module\n\n## Author\n\nOriginal: Asim Kadav (asimkadav@gmail.com)\nModernized: 2025 update for Linux 5.0+ kernels\n\n## Disclaimer\n\n**NO WARRANTIES. Use at your own risk.** This software is provided \"as is\" without warranty of any kind. Test thoroughly in safe environments before any production use.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasimkadav%2Fblock-filter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasimkadav%2Fblock-filter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasimkadav%2Fblock-filter/lists"}