{"id":18853973,"url":"https://github.com/janbar/ipfilter","last_synced_at":"2026-02-17T07:04:44.185Z","repository":{"id":211464143,"uuid":"729226506","full_name":"janbar/ipfilter","owner":"janbar","description":"IP filtering module for NGINX ","archived":false,"fork":false,"pushed_at":"2025-04-23T22:10:14.000Z","size":203,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-09-03T15:45:02.206Z","etag":null,"topics":["cidr","ip-filter","ip-filtering","nginx"],"latest_commit_sha":null,"homepage":"","language":"C++","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/janbar.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-12-08T17:06:20.000Z","updated_at":"2025-04-23T22:10:18.000Z","dependencies_parsed_at":"2023-12-23T01:30:32.972Z","dependency_job_id":"97551936-d4fb-4b97-9dcd-2f36cf4ff589","html_url":"https://github.com/janbar/ipfilter","commit_stats":null,"previous_names":["janbar/ipfilter"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/janbar/ipfilter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/janbar%2Fipfilter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/janbar%2Fipfilter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/janbar%2Fipfilter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/janbar%2Fipfilter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/janbar","download_url":"https://codeload.github.com/janbar/ipfilter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/janbar%2Fipfilter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29536553,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-17T05:00:25.817Z","status":"ssl_error","status_checked_at":"2026-02-17T04:57:16.126Z","response_time":100,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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":["cidr","ip-filter","ip-filtering","nginx"],"created_at":"2024-11-08T03:46:20.557Z","updated_at":"2026-02-17T07:04:44.179Z","avatar_url":"https://github.com/janbar.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"![coverity-scan status](https://img.shields.io/coverity/scan/31426.svg)\r\n\r\n# IP FILTER MODULE\r\n\r\nThe module uses a very efficient algorithm to match an IP address with a large number of CIDR addresses. It uses a database, filled with list of CIDR records with the following format:\r\n\r\n- IPv4 : `nnn.nnn.nnn.nnn/pp`\r\n\r\n- IPv6 : `x:x::x:x/ppp`\r\n\r\n- IPv4 mapped : `::FFFF:nnn.nnn.nnn.nnn/ppp`\r\n\r\nThe database can be used for any purposes. Later I present its use in a module for NGINX.\r\n\r\n## About the database\r\n\r\nThe data format is binary form and optimized to store a bitmap tree. The search time is constant and do not depends of the number of rules. Typical benchmark with a database filled with 1 million rules report an average response time less than 10 usec. In addition, database operations such as insert, update or delete are extremely fast.\r\n\r\nThe only limit in terms of number of rules is the size of the database and the memory available on the system. As an example, load all country subnets of US UK DE and FR, so 500K rules (Dec 2023), increases the database to 6 MB.\r\n\r\nThe database is administred using the command line `ipfiltercli`. Loading or updating the rules can be made on the fly without need to stop consumers.\r\n\r\n### Create a new database\r\n\r\nFirst you need to download some CIDR files or define your list of CIDR records to fill the database. Finally use the CLI `ipfiltercli` to create or update the database as follows:\r\n\r\nLaunch the CLI.\r\n\r\n```\r\n./ipfiltercli\r\n```\r\n\r\nType 'help' to learn commands ... then create the database.\r\n\r\n```\r\ncreate database.db\r\nnoname \u003e\u003e\u003e setname DB1\r\nDB1 \u003e\u003e\u003e load allow firewall_france.txt\r\nDB1 \u003e\u003e\u003e allow 127.0.0.0/16\r\nDB1 \u003e\u003e\u003e allow 10.0.0.0/16\r\nDB1 \u003e\u003e\u003e load deny firewall_denied.txt\r\n```\r\n\r\nMake some Tests.\r\n\r\n```\r\nDB1 \u003e\u003e\u003e test 127.0.0.1/32\r\n[ allow ] elap: 0.000004 sec\r\nDB1 \u003e\u003e\u003e test 8.8.8.8/32\r\n[ empty ] elap: 0.000004 sec\r\n```\r\n\r\nQuit the CLI.\r\n\r\n```\r\nDB1 \u003e\u003e\u003e exit\r\n```\r\n\r\n### Update the database online\r\n\r\nThe database is updated on the fly using the CLI. Therefore no need to stop/restart the consumers.\r\n\r\nLaunch the CLI.\r\n\r\n```\r\n./ipfiltercli\r\n```\r\n\r\nMount the database to update.\r\n\r\n```\r\nmount /etc/nginx/modules/database.db\r\n```\r\n\r\nUse commands `allow`, `deny`, `load` ...\r\n\r\n```\r\nallow  10.1.0.0/16\r\n```\r\n\r\n*Notes: Updates are applied instantly.*\r\n\r\n## Configure the module for NGINX\r\n\r\nSee [BUILD](./BUILD.txt) to make the module for NGINX.\r\n\r\nCopy the module `ngx_http_ipfilter_module.so` and your database file(s) in place, i.e `/etc/nginx/modules/`.\r\n\r\nEdit the nginx.conf to load the module.\r\n\r\n```\r\nload_module /etc/nginx/modules/ngx_http_ipfilter_module.so;\r\n```\r\n\r\nEdit the sites configution to enable/configure the module per location. You can share one database with many locations, or use dedicated databases.\r\n\r\n```\r\nlocation / {\r\nipfilter_enabled;                            # enable the module\r\nipfilter_db /etc/nginx/modules/database.db;  # path of the db file\r\nipfilter_denied_url \"/403.html\";             # denied url\r\n...\r\n}\r\n```\r\n\r\nIf the denied url is not configured, you can test the variable `$ipfilter` to rewrite the flow. It contains one of the following values:\r\n\r\n  **0** = Not found, **1** = Allow, **2** = Deny or **3** = Error.\r\n\r\nThe directive could be as follows.\r\n\r\n```\r\n  if ($ipfilter != 1) { return 403; }\r\n```\r\n\r\nRestart the server NGINX.\r\n\r\nAt this point, the module has been enabled for the configured location(s). In the given example, only the request with allowed IP in the database are allowed to browse resources. Others are redirected to the denied url.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjanbar%2Fipfilter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjanbar%2Fipfilter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjanbar%2Fipfilter/lists"}