realip

README

Real IP

Extract the real HTTP client's Remote IP Address.

Installation

The only requirement is the Go Programming Language.

$ go get github.com/kataras/realip

Getting Started

The main function is Get, it makes use of the Default options to extract the request's remote address.

package main

import (
	"fmt"
	"net/http"

	"github.com/kataras/realip"
)

func main() {
    http.HandleFunc("/", handler)
    http.ListenAndServe(":8080", nil)
}

func handler(w http.ResponseWriter, r *http.Request) {
    ip := realip.Get(r)
    fmt.Fprintf(w, "Your Public IPv4 is: %s", ip)
}

The Get(r) function calls the Default.Get(r) method

Options

Here are the default values:

var Default = Options{
	Headers: []string{
		"X-Real-Ip",
		"X-Forwarded-For",
		"CF-Connecting-IP",
	},
	PrivateSubnets: []Range{
		{
			Start: net.ParseIP("10.0.0.0"),
			End:   net.ParseIP("10.255.255.255"),
		},
		{
			Start: net.ParseIP("100.64.0.0"),
			End:   net.ParseIP("100.127.255.255"),
		},
		{
			Start: net.ParseIP("172.16.0.0"),
			End:   net.ParseIP("172.31.255.255"),
		},
		{
			Start: net.ParseIP("192.0.0.0"),
			End:   net.ParseIP("192.0.0.255"),
		},
		{
			Start: net.ParseIP("192.168.0.0"),
			End:   net.ParseIP("192.168.255.255"),
		},
		{
			Start: net.ParseIP("198.18.0.0"),
			End:   net.ParseIP("198.19.255.255"),
		},
	},
}

Use the AddRange method helper to add an IP range in custom options:

func main() {
    myOptions := &realip.Options{Headers: []string{"X-Forwarded-For"}}
    myOptions.AddRange("192.168.0.0", "192.168.255.255")

    // [...]
    http.HandleFunc("/", handler(myOptions))
}

func handler(opts *realip.Options) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request){
        ip := opts.Get(r)

        // [...]
    }
}

Please navigate through _examples directory for more.

License

This software is licensed under the MIT License.

Documentation

Index

• Variables
• func Get(r *http.Request) string
• func GetIPAddress(ipAddresses []string, privateRanges []Range) (string, bool)
• func InRange(r Range, ipAddress net.IP) bool
• func IsPrivateSubnet(ipAddress net.IP, privateRanges []Range) bool
• type Options
  • func (opts *Options) AddHeader(headerKey string) *Options
  • func (opts *Options) AddRange(start, end string) *Options
  • func (opts *Options) Get(r *http.Request) string
• type Range

Variables

var Default = Options{
	Headers: []string{
		"X-Real-Ip",
		"X-Forwarded-For",
		"CF-Connecting-IP",
	},
	PrivateSubnets: []Range{
		{
			Start: net.ParseIP("10.0.0.0"),
			End:   net.ParseIP("10.255.255.255"),
		},
		{
			Start: net.ParseIP("100.64.0.0"),
			End:   net.ParseIP("100.127.255.255"),
		},
		{
			Start: net.ParseIP("172.16.0.0"),
			End:   net.ParseIP("172.31.255.255"),
		},
		{
			Start: net.ParseIP("192.0.0.0"),
			End:   net.ParseIP("192.0.0.255"),
		},
		{
			Start: net.ParseIP("192.168.0.0"),
			End:   net.ParseIP("192.168.255.255"),
		},
		{
			Start: net.ParseIP("198.18.0.0"),
			End:   net.ParseIP("198.19.255.255"),
		},
	},
}

Default is an `Options` value with some default headers and private subnets. See `Get` method.

Functions

func Get

func Get(r *http.Request) string

Get is a shortcut of `Default.Get`. Extracts the real client's remote IP Address.

func GetIPAddress

func GetIPAddress(ipAddresses []string, privateRanges []Range) (string, bool)

GetIPAddress returns a valid public IP Address from a collection of IP Addresses and a range of private subnets.

Reports whether a valid IP was found.

func InRange

func InRange(r Range, ipAddress net.IP) bool

InRange reports whether a given IP Address is within a range given.

func IsPrivateSubnet

func IsPrivateSubnet(ipAddress net.IP, privateRanges []Range) bool

IsPrivateSubnet reports whether this "ipAddress" is in a private subnet.

Types

type Options

type Options struct {
	Headers        []string `json:"headers" yaml:"Headers" toml:"Headers"`
	PrivateSubnets []Range  `json:"privateSubnets" yaml:"PrivateSubnets" toml:"PrivateSubnets"`
}

Options holds the request `Headers` which IP should be fetched from. A header value should be separated by comma if contains more than one ip address. The `PrivateSubnets` field can be used to skip "local" addresses parsed by the `Headers` field.

See `AddHeader`, `AddRange` and `Get` methods.

func (*Options) AddHeader

func (opts *Options) AddHeader(headerKey string) *Options

AddHeader adds a proxy remote address header to "opts". Should be called before any use of `Get`.

func (*Options) AddRange

func (opts *Options) AddRange(start, end string) *Options

AddRange adds a private subnet to "opts". Should be called before any use of `Get`.

func (*Options) Get

func (opts *Options) Get(r *http.Request) string

Get extracts the real client's remote IP Address.

Based on proxy headers of `Headers` and `PrivateSubnets`.

Fallbacks to the request's `RemoteAddr` field which is filled by the server.

type Range

type Range struct {
	Start net.IP `json:"start" yaml:"Start" toml:"Start"`
	End   net.IP `json:"end" yaml:"End" toml:"End"` // End, e.g. 255 is not a private one, but 254 is.
}

Range is a structure that holds the start and end of a range of IP Addresses.