How To Block IPFS Nodes From Storing Illegal Content On Your Drive?

The Interplanetary File System (IPFS) is a powerful tool for sharing and storing files across a decentralized network. But this power comes with a serious concern. Other IPFS nodes can store data on your drive without your direct permission. Your node automatically caches content that passes through it. This means illegal or unwanted files could end up on your local storage.

You are not alone if this worries you. Thousands of IPFS node operators face the same challenge every day. The good news is that IPFS now provides built in tools to block, filter, and remove unwanted content from your drive. You can take full control of what your node stores and serves.

This guide will walk you through every practical step. You will learn how to set up denylists, configure garbage collection, use the NOpfs plugin, filter peers, and limit your storage. By the end, you will have a secure IPFS node that keeps illegal content off your drive.

In A Nutshell

• IPFS nodes cache content automatically as it passes through the network, which means unwanted or illegal files can land on your local storage without you adding them directly. Understanding this behavior is the first step to protecting your drive.
• Kubo’s built in denylist system lets you block specific CIDs and IPFS paths from being stored or served by your node. You place .deny files in the correct directory, and your node will refuse to download or share those items.
• The NOpfs plugin and the Badbits denylist give you access to a community maintained list of known illegal and harmful content hashes. Installing these tools blocks a large amount of flagged content with minimal effort on your part.
• Garbage collection is essential for clearing cached data you did not pin. Enabling automatic garbage collection ensures your node regularly cleans out temporary files, reducing the chance that unwanted content stays on your disk for long.
• Setting your node to DHT client mode (autoclient) stops your node from storing and serving provider records for blocked content, giving you a deeper level of protection beyond just content blocking.
• Running a private IPFS network with a swarm key is the most effective solution if you need total control. This restricts your node to communicate only with approved peers and eliminates exposure to public network content entirely.

How IPFS Stores Content On Your Drive

IPFS works differently from traditional file storage systems. Every node in the network acts as both a client and a server. When you request a file, your node downloads it and automatically caches it in your local repository. This cache makes the file available to other peers who request it.

Your IPFS repository lives in the ~/.ipfs directory by default. Inside this directory, a folder called blocks holds all the cached data. Every piece of content you access, and even content that routes through your node during peer exchanges, can end up stored here.

The protocol uses a system called Bitswap to exchange data blocks between nodes. If a nearby peer requests content and your node has it cached, your node will serve it. This is how IPFS achieves its speed and resilience. But it also means your drive can fill up with content you never asked for.

Content you did not pin will eventually be removed by garbage collection. But until that happens, it sits on your drive. If illegal content passes through your node, even temporarily, it could create legal and ethical concerns for you as the node operator. This is why active content blocking matters.

Why Illegal Content Can End Up On Your Node

The decentralized nature of IPFS means no single entity controls what gets shared. Anyone can upload any file and distribute its CID (Content Identifier) across the network. When peers exchange blocks, your node might receive data that contains illegal material.

There are three main ways this happens. First, your node caches content during Bitswap exchanges with peers. Second, if you run a DHT server (the default setting), your node stores provider records that help others find content. Third, some malicious actors deliberately try to spread illegal data across as many nodes as possible.

You are responsible for what your node stores. Even if you did not intentionally download the content, having it on your drive can be problematic. This is why the IPFS community has developed multiple tools and methods to give node operators the ability to block and filter content.

The risk is real. Several IPFS forum discussions highlight cases where operators found unexpected data in their local repositories. Taking a proactive approach to content blocking protects you legally and keeps your node clean.

Understanding The Kubo Denylist System

Kubo, the most popular IPFS implementation (formerly called go-ipfs), ships with built in support for content blocking through denylists. This feature follows the IPIP-383 specification and provides a standardized way to block content on your node.

A denylist is a simple text file with a .deny extension. Each line contains an IPFS path or CID that you want to block. When your Kubo node reads this file, it will refuse to download, cache, or serve any content matching those entries.

The denylist system works at multiple levels. It blocks content on Bitswap, so your node will not request or serve blocked blocks to peers. It blocks content on the gateway and CLI, returning an error (HTTP 410 Gone) for denied CIDs. It also blocks IPNS resolution for denied names.

Important: denylists do not block routing by default. Your node can still store and serve provider records in the DHT for blocked content. We will cover how to fix this in a later section. But the denylist is your first and most important line of defense against unwanted content.

How To Create And Install Deny Files

Setting up a denylist is straightforward. You need to create a .deny file and place it in one of the directories that Kubo monitors. The supported directories are $HOME/.ipfs/denylists/, $HOME/.config/ipfs/denylists/, and /etc/ipfs/denylists/ for global blocking.

Step 1: Create the denylists directory if it does not exist.

mkdir -p ~/.ipfs/denylists/

Step 2: Create a new deny file. Open a text editor and add the CIDs or IPFS paths you want to block, one per line.

/ipfs/QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR
/ipfs/bafybeihfg3d7rdltd43u3tfvncx7n5loqofbsobojcadtmokrljfthuc7y

Step 3: Save the file with a .deny extension inside the denylists directory.

nano ~/.ipfs/denylists/my-blocklist.deny

Step 4: Restart your IPFS daemon. The deny files must be in place before the daemon starts to be detected properly.

ipfs shutdown
ipfs daemon

Once active, any request for a blocked CID will return an error message: “/ipfs/[CID] is blocked and cannot be provided.” You can append new entries to the deny file while the daemon is running, and Kubo will detect them. But if you remove or reorder entries, you must restart the daemon.

Using The Badbits Denylist For Known Illegal Content

You do not need to build your blocklist from scratch. The IPFS community maintains a public denylist called Badbits that contains hashes of known illegal and harmful content. This list is actively updated and used by major IPFS gateway operators.

The Badbits denylist is available at https://badbits.dwebops.pub/badbits.deny in the compact denylist format. It uses double hashed entries so that the actual CIDs of illegal content are not visible in plain text. This protects you from exposure while still allowing your node to block the content effectively.

To install the Badbits denylist, download it into your denylists directory:

curl -o ~/.ipfs/denylists/badbits.deny https://badbits.dwebops.pub/badbits.deny

After downloading, restart your IPFS daemon. Your node will now block all content flagged in the Badbits list. You should update this file regularly to catch newly flagged content. Set up a cron job to automate the download.

0 */6 * * * curl -o ~/.ipfs/denylists/badbits.deny https://badbits.dwebops.pub/badbits.deny

This cron job updates the list every six hours. ChainSafe also maintains its own denylist called Orbitor that includes known phishing, malware, scam, and abusive content. You can add multiple deny files to your denylists directory for layered protection.

Installing The NOpfs Plugin For Advanced Blocking

NOpfs is a dedicated content blocking tool built for the IPFS stack. It provides more advanced blocking capabilities than basic deny files alone. The NOpfs plugin integrates directly with Kubo to prevent blocked content from being downloaded at the Bitswap level.

Before NOpfs, content blocking in IPFS only worked at the gateway level using Nginx rules. This meant blocked content could still be fetched and cached by the underlying Kubo node. NOpfs closes this gap by blocking content before it ever reaches your storage.

To install NOpfs, visit the GitHub releases page at github.com/ipfs-shipyard/nopfs and download the plugin version that matches your Kubo version. Place the plugin file in your ~/.ipfs/plugins/ directory.

mkdir -p ~/.ipfs/plugins/
cp nopfs-kubo-plugin ~/.ipfs/plugins/

After installation, restart your Kubo daemon. NOpfs reads the same .deny files from your denylists directory. It understands the compact denylist format from IPIP-383 and supports clear text rules, double hashed rules, and content path blocking.

NOpfs also supports metadata tags on blocked items. This means each entry in a denylist can include a reason for the block. IPFS implementations can then choose whether to expose that information to end users. This makes NOpfs a complete content moderation solution for serious node operators.

Configuring Garbage Collection To Remove Unwanted Cache

Even with denylists in place, some unwanted content might end up cached on your node before you add its CID to a blocklist. Garbage collection is your safety net. It automatically removes unpinned data from your local repository to free up disk space.

IPFS garbage collection settings live in the Datastore section of your config file at ~/.ipfs/config. The two key settings are:

StorageMax sets the upper limit for your repository size. The default is 10GB. You can lower this to reduce risk.

ipfs config Datastore.StorageMax "5GB"

StorageGCWatermark sets the percentage of StorageMax that triggers automatic garbage collection. The default is 90, meaning garbage collection starts when your repo reaches 90% of StorageMax.

ipfs config Datastore.StorageGCWatermark 80

To enable automatic garbage collection, start your daemon with the --enable-gc flag:

ipfs daemon --enable-gc

You can also trigger manual garbage collection at any time:

ipfs repo gc

Set your GCPeriod to a shorter interval if you want more frequent cleanups. The default is one hour. Frequent garbage collection ensures unwanted cached content does not stay on your drive for long.

ipfs config Datastore.GCPeriod "30m"

Switching To DHT Client Mode For Deeper Protection

Denylists block your node from downloading and serving content. But if your node runs as a DHT server (the default when publicly reachable), it still stores and serves provider records for blocked content. This means your node helps other peers discover where to find that content.

To stop this behavior, switch your node to autoclient mode. In this mode, your node only acts as a DHT client. It does not store or serve provider records on behalf of other peers.

ipfs config Routing.Type autoclient

Restart your daemon after making this change. Your node will still be able to find and retrieve content from the network. But it will no longer participate as a routing server for other nodes. This eliminates the risk of your node facilitating access to blocked content.

There is a trade off. Running in autoclient mode means your node contributes less to the overall health of the IPFS network. The network depends on DHT servers to function efficiently. But for operators who prioritize keeping illegal content away from their drives, autoclient mode is a strong protective measure.

If you run a public gateway, you may want to keep DHT server mode for performance. In that case, combine it with thorough denylists and the NOpfs plugin for the best balance of utility and protection.

Using Swarm Filters To Block Specific Peers

Sometimes the problem is not the content itself but the peers sending it. IPFS allows you to block specific peers or IP ranges using swarm filters. This prevents your node from connecting to known bad actors.

To add a swarm filter, use the CLI:

ipfs swarm filters add /ip4/192.168.1.100/ipcidr/32

This command blocks a specific IP address. You can also block entire subnets:

ipfs swarm filters add /ip4/10.0.0.0/ipcidr/8

Swarm filters are stored in your node’s config file and persist across restarts. You can view your current filters with:

ipfs swarm filters

To remove a filter:

ipfs swarm filters rm /ip4/192.168.1.100/ipcidr/32

For larger scale blocking, you can combine swarm filters with your system firewall. Use iptables on Linux or a similar tool to block IP addresses at the network level before traffic even reaches your IPFS node. This adds an extra layer of protection that operates independently of IPFS software.

Monitor your peer connections regularly with ipfs swarm peers to identify suspicious nodes. If you notice a peer sending unusual amounts of data or connecting repeatedly, add it to your swarm filters immediately.

Setting Up A Private IPFS Network

If your use case allows it, running a private IPFS network gives you the ultimate control over what content your node handles. A private network uses a shared secret key called a swarm key. Only nodes with this key can connect to each other.

Step 1: Generate a swarm key using the key generation tool.

go install github.com/Kubuxu/go-ipfs-swarm-key-gen/ipfs-swarm-key-gen@latest
ipfs-swarm-key-gen > ~/.ipfs/swarm.key

Step 2: Copy this swarm key to every node that should be part of your private network. All nodes must have the exact same key.

Step 3: Remove the default bootstrap peers so your node does not try to connect to the public network.

ipfs bootstrap rm --all

Step 4: Add only your trusted peers as bootstrap nodes.

ipfs bootstrap add /ip4/YOUR_PEER_IP/tcp/4001/p2p/PEER_ID

Step 5: Set the LIBP2P_FORCE_PEERID environment variable and restart your daemon.

With a private network, your node will only communicate with approved peers. No public content will flow through your node. This eliminates the risk of caching illegal content entirely. The trade off is that you lose access to the vast public IPFS network and its content. Private networks work best for organizations that need controlled, internal file sharing without exposure to public data.

Limiting Storage And Controlling Reprovider Settings

Beyond garbage collection, you can fine tune how much data your node stores and what it advertises to the network. The reprovider settings control whether your node tells other peers about the content it has cached.

By default, your IPFS node announces all content in its repository to the network. This includes content you did not deliberately add. You can change this behavior in your config file.

Set reprovider strategy to “pinned” so your node only announces content you have explicitly pinned:

ipfs config Reprovider.Strategy pinned

Or set it to “roots” to announce only the root CIDs of pinned content:

ipfs config Reprovider.Strategy roots

This prevents your node from advertising cached content that you did not choose to store. Other nodes will not know that your node has the cached data, reducing the chance that they request it from you.

You should also set a strict storage limit. Lower your StorageMax value to the minimum size that meets your needs. A smaller repository means less room for unwanted cached files.

ipfs config Datastore.StorageMax "2GB"

Combine these settings with aggressive garbage collection for a tight and clean repository. The result is a node that only stores and advertises content you have chosen to keep.

Monitoring Your Node For Unwanted Content

Blocking and filtering are proactive measures. But you also need to monitor your node regularly to catch anything that slips through. IPFS provides several tools for this.

Check your repository statistics to see how much space is being used:

ipfs repo stat

List all pinned objects on your node:

ipfs pin ls

If you see pinned content you do not recognize, remove it:

ipfs pin rm UNWANTED_CID
ipfs repo gc

Enable debug logging for NOpfs to track when content is blocked. This helps you verify that your denylists are working correctly.

GOLOG_LOG_LEVEL="nopfs-blocks=warn" ipfs daemon

This logs a warning every time a blocked CID is requested. You will see entries like: “QmRFni…: blocked (badbits.deny:42)”. Review these logs periodically to understand what types of content your node encounters.

You can also write a simple script that checks your block store periodically for known bad CIDs. Compare the CIDs in your ~/.ipfs/blocks/ directory against your denylist to detect any content that was cached before the block rule was added.

Reporting Illegal Content To The IPFS Community

Protecting your own node is important. But helping the broader IPFS community stay safe matters too. If you discover illegal content on the IPFS network, you should report it.

The IPFS project accepts abuse reports at abuse@ipfs.io. The infrastructure team reviews all reports and can add confirmed illegal content to the Badbits denylist. This helps every node operator who uses the list.

When you report content, include the CID or IPFS path of the material. Provide any relevant context about how you encountered it. Do not download or redistribute the content. Simply share the identifier so the team can take action.

Gateway operators like Cloudflare, Pinata, and Protocol Labs maintain their own content moderation processes. If you find illegal content served through a specific gateway, report it directly to that gateway operator as well.

Community maintained denylists like ChainSafe’s Orbitor list also accept contributions. By reporting illegal content, you help maintain and grow the blocklists that protect the entire IPFS ecosystem. A collective effort makes the decentralized web safer for everyone.

You can also participate in discussions about content moderation on the IPFS forums at discuss.ipfs.tech. The community actively develops new tools and policies to address these challenges.

Combining All Methods For Maximum Protection

No single method provides complete protection. The most effective approach combines multiple layers of defense. Here is a summary of the recommended setup for a well protected IPFS node.

Start by installing the Badbits denylist and any other community denylists in your ~/.ipfs/denylists/ directory. Set up a cron job to keep them updated. This blocks the majority of known illegal content.

Install the NOpfs plugin to ensure blocked content is stopped at the Bitswap level before it reaches your storage. This closes the gap that gateway level blocking alone cannot cover.

Switch your routing mode to autoclient so your node does not serve as a DHT server. This prevents your node from storing provider records for blocked content.

Enable automatic garbage collection with a short period and a low storage watermark. This clears cached data frequently and keeps your repository small.

Set your reprovider strategy to “pinned” so you only advertise content you have chosen to keep. Add swarm filters for any known malicious peers.

Finally, monitor your node regularly. Check repository stats, review logs, and verify that your denylists are active. Update your security setup as new tools and denylists become available.

This layered approach gives you the strongest possible defense against illegal content landing on your IPFS drive.

Frequently Asked Questions

Can IPFS nodes store content on my drive without my permission?

Yes, they can. Your IPFS node automatically caches content that passes through it during Bitswap exchanges. This is how IPFS works by design. Your node stores blocks temporarily so it can serve them to other peers. You did not request this content directly, but it ends up in your local repository. Garbage collection will eventually remove unpinned cache, but you should use denylists and storage limits to reduce the window of exposure.

How often should I update my denylist files?

You should update your denylists at least once per day. New illegal content is flagged regularly, and an outdated denylist leaves gaps in your protection. Setting up a cron job to download the latest Badbits denylist every six hours is a practical approach. Always restart your IPFS daemon after major denylist changes to ensure all entries are properly loaded.

Will content blocking slow down my IPFS node?

The performance impact is minimal. Kubo’s denylist system is optimized to check CIDs against block rules efficiently. NOpfs uses an optimized matching engine that adds very little overhead to content requests. The benefit of keeping illegal content off your drive far outweighs any minor performance cost. Most node operators report no noticeable difference in speed after enabling content blocking.

Is running a private IPFS network practical for individual users?

A private network is most practical for organizations or groups that need controlled file sharing. For individual users, it can be limiting because you lose access to all public IPFS content. If you need to access the public network, use denylists, garbage collection, and autoclient mode instead. Reserve private networks for cases where you need total isolation from public content.

Can I completely prevent all illegal content from reaching my node?

No solution guarantees 100% prevention. New illegal content appears constantly, and there is always a delay before it gets added to denylists. However, combining multiple blocking methods significantly reduces your risk. Denylists, garbage collection, autoclient routing, swarm filters, and regular monitoring together create a strong defense. Stay engaged with the IPFS community and update your tools regularly for the best protection.

What should I do if I find illegal content already stored on my node?

First, do not open or redistribute the content. Unpin it immediately using ipfs pin rm followed by its CID. Then run ipfs repo gc to remove it from your local storage. Report the CID to abuse@ipfs.io so it can be added to the Badbits denylist. Add the CID to your own local deny file as well. Check your node logs to understand how the content arrived and tighten your blocking settings if needed.