whatismyip/README.md

What is my IP address

• What is my IP address
  • Features
  • Endpoints
  • Build
  • Usage
  • Examples
    • Run a default TCP server
    • Run a TLS (HTTP/2) server only
    • Run an HTTP/3 server
    • Run a default TCP server with a custom template and trust a pair of custom headers set by an upstream proxy
  • Download
  • Docker
    • Run a container locally using test databases
    • From Docker Hub

Just another "what is my IP address" service, including geolocation and headers information, written in go with high performance in mind, it uses gin which uses httprouter a lightweight high performance HTTP multiplexer.

Take a look at ifconfig.es a live site using whatismyip

Get your public IP easily from the command line:

curl ifconfig.es
127.0.0.1

curl -6 ifconfig.es
::1

Features

• TLS and HTTP/2.
• Experimental support to HTTP/3. HTTP/3 requires a TLS server running (-tls-bind), as HTTP/3 starts as a TLS connection that then gets upgraded to UDP. The UDP port is the same as the one used for the TLS server.
• Can run behind a proxy by trusting a custom header (usually X-Real-IP) to figure out the source IP address. It also supports a custom header to resolve the client port, if the proxy can only add a header for the IP (for example a fixed header from CDNs) the client port is shown as unknown.
• IPv4 and IPv6.
• Geolocation info including ASN. This feature is possible thanks to maxmind GeoLite2 databases. In order to use these databases, a license key is needed. Please visit Maxmind site for further instructions and get a free license.
• High performance.
• Self-contained server what can reload GeoLite2 databases and/or SSL certificates without stop/start. The hup signal is honored.
• HTML templates for the landing page.
• Text plain and JSON output.

Endpoints

• https://ifconfig.es/
• https://ifconfig.es/client-port
• https://ifconfig.es/json (this is the same as curl -H "Accept: application/json" https://ifconfig.es/)
• https://ifconfig.es/geo
  • https://ifconfig.es/geo/city
  • https://ifconfig.es/geo/country
  • https://ifconfig.es/geo/country_code
  • https://ifconfig.es/geo/latitude
  • https://ifconfig.es/geo/longitude
  • https://ifconfig.es/geo/postal_code
  • https://ifconfig.es/geo/time_zone
• https://ifconfig.es/asn
  • https://ifconfig.es/asn/number
  • https://ifconfig.es/asn/organization
• https://ifconfig.es/all
• https://ifconfig.es/headers
  • https://ifconfig.es/<header_name>

Build

Golang >= 1.19 is required.

make build

Usage

Usage of whatismyip:
  -bind string
        Listening address (see https://pkg.go.dev/net?#Listen) (default ":8080")
  -enable-http3
        Enable HTTP/3 protocol. HTTP/3 requires --tls-bind set, as HTTP/3 starts as a TLS connection that then gets upgraded to UDP. The UDP port is the same as the one used for the TLS server.
  -enable-secure-headers
        Add sane security-related headers to every response
  -geoip2-asn string
        Path to GeoIP2 ASN database
  -geoip2-city string
        Path to GeoIP2 city database
  -template string
        Path to template file
  -tls-bind string
        Listening address for TLS (see https://pkg.go.dev/net?#Listen)
  -tls-crt string
        When using TLS, path to certificate file
  -tls-key string
        When using TLS, path to private key file
  -trusted-header string
        Trusted request header for remote IP (e.g. X-Real-IP). When using this feature if -trusted-port-header is not set the client port is shown as 'unknown'
  -trusted-port-header string
        Trusted request header for remote client port (e.g. X-Real-Port). When this parameter is set -trusted-header becomes mandatory
  -version
        Output version information and exit

Examples

Run a default TCP server

./whatismyip -geoip2-city ./test/GeoIP2-City-Test.mmdb -geoip2-asn ./test/GeoLite2-ASN-Test.mmdb

Run a TLS (HTTP/2) server only

./whatismyip -geoip2-city ./test/GeoIP2-City-Test.mmdb -geoip2-asn ./test/GeoLite2-ASN-Test.mmdb \
             -bind "" -tls-bind :8081 -tls-crt ./test/server.pem -tls-key ./test/server.key

Run an HTTP/3 server

./whatismyip -geoip2-city ./test/GeoIP2-City-Test.mmdb -geoip2-asn ./test/GeoLite2-ASN-Test.mmdb \
             -bind "" -tls-bind :8081 -tls-crt ./test/server.pem -tls-key ./test/server.key -enable-http3

Run a default TCP server with a custom template and trust a pair of custom headers set by an upstream proxy

./whatismyip -geoip2-city ./test/GeoIP2-City-Test.mmdb -geoip2-asn ./test/GeoLite2-ASN-Test.mmdb \
             -trusted-header X-Real-IP -trusted-port-header X-Real-Port -template mytemplate.tmpl

Download

Download latest version from https://github.com/dcarrillo/whatismyip/releases

Docker

An ultra-light (~12MB) image is available at docker hub.

Run a container locally using test databases

make docker-run

From Docker Hub

docker run --tty --interactive --rm \
    -v $PWD/<path to city database>:/tmp/GeoIP2-City-Test.mmdb:ro \
    -v $PWD/<path to ASN database>:/tmp/GeoLite2-ASN-Test.mmdb:ro -p 8080:8080 \
    dcarrillo/whatismyip:latest \
      -geoip2-city /tmp/GeoIP2-City-Test.mmdb \
      -geoip2-asn /tmp/GeoLite2-ASN-Test.mmdb