{"id":26830861,"url":"https://github.com/oltdaniel/caddy-ipinfo-free","last_synced_at":"2025-03-30T14:18:01.087Z","repository":{"id":233165352,"uuid":"783350881","full_name":"oltdaniel/caddy-ipinfo-free","owner":"oltdaniel","description":"get the free  ipinfo database integrated into your caddy setup","archived":false,"fork":false,"pushed_at":"2024-04-13T21:02:39.000Z","size":34,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-04-14T08:52:44.956Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oltdaniel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2024-04-07T16:46:29.000Z","updated_at":"2024-04-14T08:54:20.453Z","dependencies_parsed_at":"2024-04-14T08:53:41.265Z","dependency_job_id":"d27d5da7-b551-4d45-add4-413419e074d8","html_url":"https://github.com/oltdaniel/caddy-ipinfo-free","commit_stats":null,"previous_names":["oltdaniel/caddy-ipinfo-free"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oltdaniel%2Fcaddy-ipinfo-free","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oltdaniel%2Fcaddy-ipinfo-free/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oltdaniel%2Fcaddy-ipinfo-free/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oltdaniel%2Fcaddy-ipinfo-free/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oltdaniel","download_url":"https://codeload.github.com/oltdaniel/caddy-ipinfo-free/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246326761,"owners_count":20759439,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2025-03-30T14:18:00.652Z","updated_at":"2025-03-30T14:18:01.078Z","avatar_url":"https://github.com/oltdaniel.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\t\u003cpicture\u003e\n\t\t\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://user-images.githubusercontent.com/1128849/210187358-e2c39003-9a5e-4dd5-a783-6deb6483ee72.svg\"\u003e\n\t\t\u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://user-images.githubusercontent.com/1128849/210187356-dfb7f1c5-ac2e-43aa-bb23-fc014280ae1f.svg\"\u003e\n\t\t\u003cimg src=\"https://user-images.githubusercontent.com/1128849/210187356-dfb7f1c5-ac2e-43aa-bb23-fc014280ae1f.svg\" alt=\"Caddy\" width=\"200\"\u003e\n\t\u003c/picture\u003e\n    \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n    \u003cpicture\u003e\n        \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://github.com/oltdaniel/caddy-ipinfo-free/assets/53529846/10bb1c41-f738-440f-8bb1-7be970fc7826\"\u003e\n\t\t\u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://github.com/oltdaniel/caddy-ipinfo-free/assets/53529846/42055591-fad7-4bae-8ee8-1632e52bd3c4\"\u003e\n\t\t\u003cimg src=\"https://github.com/oltdaniel/caddy-ipinfo-free/assets/53529846/42055591-fad7-4bae-8ee8-1632e52bd3c4\" alt=\"IPInfo\" width=\"200\"\u003e\n\t\u003c/picture\u003e\n\t\u003cbr\u003e\n\t\u003ch3 align=\"center\"\u003eCaddy x IPInfo\u003c/h3\u003e\n\u003c/p\u003e\n\n\u003e This project does not affiliate with Caddy nor IPInfo. It only extends Caddy with custom code to integrate the free databases provided by IPInfo into Caddy. Logo Copyright belongs to the corresponding project.\n\n# Caddy IPInfo free\n\nEasy country and ASN lookup by IP with the free IPInfo database.\n\n\u003e This module is still in development. Breaking changes will likely come. No stability checks yet.\n\n## Example\n\n```\n{\n    # Required as a third-party handler\n    order ipinfo_free first\n    # Configure module\n    ipinfo_free_config {\n        url https://ipinfo.io/data/free/country_asn.mmdb?token=magicduck\n        cron \"10 16 * * *\"\n        path /tmp/caddy_ipinfo\n    }\n}\n\n:8080 {\n    ipinfo_free \"{http.request.uri.query.ip}\"\n\n    header Content-Type text/plain\n    respond \u003c\u003cTEXT\n    IP: {ipinfo_free.ip}\n                \n    Country: {ipinfo_free.country_name} ({ipinfo_free.country})\n    Continent: {ipinfo_free.continent_name} ({ipinfo_free.continent})\n    ASN: {ipinfo_free.asn} {ipinfo_free.as_name} {ipinfo_free.as_domain}\n    TEXT 200\n}\n```\n\n```bash\n$ curl \"http://localhost:8080/?ip=1.1.1.1\"\nIP: 1.1.1.1\n            \nCountry: Australia (AU)\nContinent: Oceania (OC)\nASN: AS13335 Cloudflare, Inc. cloudflare.com\n```\n\n## Why?\n\nIPInfo distributes their country and ASN databases for free every 24h with full accuracy. With this module and a few lines of config in your `Caddyfile`, you can query the database anywhere with anything.\n\n## Installation\n\n### Web Download\n\nDownload a caddy binary from `caddyserver.com` with this package included [here](https://caddyserver.com/download?package=github.com%2Foltdaniel%2Fcaddy-ipinfo-free).\n\n### CLI Download (experimental)\n\n\u003e This is equal to the version above but replaces your existing binary with the new one including the package.\n\nCaddy has a feature to add packages to your current installation by running the following command:\n\n```bash\ncaddy add-package github.com/oltdaniel/caddy-ipinfo-free\n```\n\n### DIY Route\n\nBuild a custom binary of the latest caddy release with this module enabled.\n\n```bash\nCADDY_VERSION=latest xcaddy build --with github.com/oltdaniel/caddy-ipinfo-free\n./caddy run\n```\n\n## Directives\n\n### `ipinfo_free_config` (global)\n\n#### Examples\n```\nipinfo_free_config https://ipinfo.io/data/free/country.mmdb?token=magicduck\n\nipinfo_free_config {\n    url https://ipinfo.io/data/free/country.mmdb?token=magicduck\n    cron \"10 16 * * *\"\n    path /tmp/caddy_ipinfo\n    quiet_on_invalid_ip\n}\n```\n\n#### Values\n\n| Name | Values | Description |\n|-|-|-|\n| `url` | valid ipinfo free database url | This url can be easily found in the [Dashboard](https://ipinfo.io/account/data-downloads) of IPInfo after creating an account. Simply choose a database of your choice in the MMDB format and paste the url here. If you only choose the Country or ASN Database, only these values can be extracted and filled into the vairables. The other values will simply be empty. If the Database with both types is chosen, all details will be available. |\n| `cron` | valid crontab notation\u003cbr\u003e\u003cbr\u003eDefault: `10 16 * * *` | Customize how often you want to check for a new database. The official time is published by IPInfo in their FAQ [here](https://ipinfo.io/faq/article/141-when-do-the-updates-happen). Timezone is UTC. |\n| `path` | valid path to store the database\u003cbr\u003e\u003cbr\u003eDefault: [`os.TempDir()`](https://pkg.go.dev/os#TempDir) with directory `caddy_ipinfo_free` | This will be the path where the databases are stored after download. As there are different kinds of databases, we only accept a path and not a specific filename. Each database will be stored here by their corresponding names from the configured url.\u003cbr\u003e\u003cbr\u003eIf the configured path does not exist, the directories will be created. If not path is given, a temporary directory will be created in the systems temporary directory with the name `caddy_ipinfo_free`. |\n| `quiet_on_invalid_ip` | ` `, `enabled`, `true`, `on`, `1`, `disabled`, `false`, `off`, `0` | Default is ` ` (true) and means it will be quiet by default when presented with an invalid IP. If you debug something disabling this is recommended. The Variable `ipinfo_free.error` will be set regardless. The main use-case for this feature is to avoid overloading the logs in production when presented with invalid IPs by the client. |\n\n### `ipinfo_free` (handler)\n\n#### Examples\n\n```\nipinfo_free\nipinfo_free 1\nipinfo_free on\nipinfo_free true\nipinfo_free enabled\nipinfo_free forwarded\nipinfo_free trusted\nipinfo_free \"{http.request.uri.query.ip}\"\n```\n\n| Values | Description |\n|-|-|\n| `disabled`, `false`, `off`, `0` | Explicit disabling of looking up ip information. |\n| `enabled`, `true`, `on`, `1`, `strict`, empty | The remote address of the request will be used to lookup the ip information. |\n| `forwarded` | Use the IP set in the `X-Forwarded-For` Header if present, else it will fallback to the remote address of the request. |\n| `trusted` | Same as `forwarded` but it will make sure that the ip from which the request comes is listed as a trusted proxy in the current caddy environment. |\n| any value that is an IPv4 or IPv6 | The mode field supportes the [Caddy placeholders ](https://caddyserver.com/docs/json/apps/http/#docs) which allows you to fully customize the IP that is used for lookup.\u003cbr\u003e\u003cbr\u003e**NOTE**: If the value maps to an empty string, the remote address of the client will be used as a fallback. |\n\n## Placeholder Variables\n\n| Variable | Example |\n|-|-|\n| `ipinfo_free.error` | `IP cannot be nil for lookup` |\n| `ipinfo_free.ip` | `1.1.1.1` |\n| `ipinfo_free.country` | `AU` |\n| `ipinfo_free.country_name` | `Australia` |\n| `ipinfo_free.continent` | `OC` |\n| `ipinfo_free.continent_name`| `Oceania` |\n| `ipinfo_free.asn` | `AS13335` |\n| `ipinfo_free.as_name` | `Cloudflare, Inc.` | \n| `ipinfo_free.as_domain` | `cloudflare.com` |\n\n## Advanced Examples\n\n\u003e Just replace the body of the server from the Caddyfile example on top.\n\n### Change Response for Countries\n\nThis is a simple example on how the response can be changed for certain countries.\n\n```\nipinfo_free\n\nheader Content-Type text/plain\n\n@dach expression ({ipinfo_free.country} in [\"DE\", \"CH\", \"AT\"])\n\nrespond @dach \"Hallo Besucher aus der DACH-Region!\"\nrespond \"Hello visistor from {ipinfo_free.country_name}\"\n```\n\n### Simple GeoIP API\n\nSimply query with `http://localhost:8080/?ip=IP`.\n\n```\nipinfo_free \"{http.request.uri.query.ip}\"\n\nheader Content-Type text/plain\nrespond \u003c\u003cTEXT\nIP: {ipinfo_free.ip}\n            \nCountry: {ipinfo_free.country_name} ({ipinfo_free.country})\nContinent: {ipinfo_free.continent_name} ({ipinfo_free.continent})\nASN: {ipinfo_free.asn} {ipinfo_free.as_name} {ipinfo_free.as_domain}\nTEXT 200\n```\n\n### GeoIP API with Error Handling\n\n```\n@hasIP query ip=*\n\nhandle @hasIP {\n    ipinfo_free \"{http.request.uri.query.ip}\"\n\n    @hasError not vars {ipinfo_free.error} \"\"\n\n    header Content-Type text/plain\n\n    respond @hasError \"Error: {ipinfo_free.error}\" 400\n    respond \u003c\u003cTEXT\n    IP: {ipinfo_free.ip}\n                    \n    Country: {ipinfo_free.country_name} ({ipinfo_free.country})\n    Continent: {ipinfo_free.continent_name} ({ipinfo_free.continent})\n    ASN: {ipinfo_free.asn} {ipinfo_free.as_name} {ipinfo_free.as_domain}\n    TEXT 200\n}\n\nrespond \"Error: Missing 'ip' query parameter\" 400\n```\n\n### More?\n\nDo you have a neat way of using this library in your Caddyfile? Feel free to submit it.\n\n## Internals\n\nThis module will automatically update the database from ipinfo and store it in the configured path. You can freely configure the `cron` option to update the database in a timely manner of your choosing. However, the most frequent update rate that should be used is hourly as the database will only be updated by IPInfo every 24 hours.\n\n### Resources\n\n- [IPInfo Database Download rate limits](https://community.ipinfo.io/t/announcement-we-are-adding-rate-limits-to-data-downloads/358)\n- [IPInfo Update Schedule](https://ipinfo.io/faq/article/141-when-do-the-updates-happen)\n- [Caddy order option](https://caddyserver.com/docs/caddyfile/options#order)\n\n## Development\n\nClone, create example config and run with xcaddy.\n\n```bash\ngit clone https://github.com/oltdaniel/caddy-ipinfo-free.git\ncd caddy-ipinfo-free\n\nCADDY_VERSION=master xcaddy run\n# or\nCADDY_VERSION=master xcaddy build --with github.com/oltdaniel/caddy-ipinfo-free=.\n./caddy run\n```\n\n## License\n\n\u003cp\u003eIP address data powered by \u003ca href=\"https://ipinfo.io\"\u003eIPinfo\u003c/a\u003e\u003c/p\u003e\n\n![GitHub License](https://img.shields.io/github/license/oltdaniel/caddy-ipinfo-free)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foltdaniel%2Fcaddy-ipinfo-free","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foltdaniel%2Fcaddy-ipinfo-free","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foltdaniel%2Fcaddy-ipinfo-free/lists"}