Example usage

This vignette demonstrates some typical use cases for the ipaddress package.

Addresses from integers

Although IPv4 addresses are usually displayed in a human-readable format (e.g. 192.168.0.1), they are often saved to disk as integers to reduce storage requirements. R is unable to store the entire range of IPv4 addresses in its integer data type, but they can instead be stored in its numeric data type. More details are found under help("ip_to_integer").

Given this, it’s quite possible that you’ll receive IPv4 addresses represented as integers, and we’ll want to convert them to the ip_address() vector type. Here’s an example of how to do that:

integer_to_ip(c(0, 3232235521, 4294967295))
#> <ip_address[3]>
#> [1] 0.0.0.0         192.168.0.1     255.255.255.255

Networks from address ranges

There are multiple equivalent ways to represent an IP network:

  1. start address + prefix length (e.g. CIDR notation)
  2. start address + netmask
  3. start address + hostmask
  4. start address + end address

Although the ip_network() function can handle the first 3 options, we use the common_network() function for the final option.

tibble(
  start = ip_address(c("192.168.0.0", "2001:db8::")),
  end = ip_address(c("192.168.0.15", "2001:db8::ffff:ffff:ffff"))
) %>%
  mutate(network = common_network(start, end))
#> # A tibble: 2 x 3
#>         start                      end        network
#>     <ip_addr>                <ip_addr>     <ip_netwk>
#> 1 192.168.0.0             192.168.0.15 192.168.0.0/28
#> 2  2001:db8:: 2001:db8::ffff:ffff:ffff  2001:db8::/80

Note that this approach assumes the two addresses do actually correspond to the first and last addresses of the network, otherwise an expanded network will be returned (see help("common_network") for details).

Is an address in a network?

A very common task is to check if an address is within a network, so the ipaddress package provides a couple of different functions to help with this workflow: is_within() and is_within_any(). We also provide is_subnet() and is_supernet() to test if a network is within another network.

To see how these functions can be used in practice, let’s consider a couple of IP networks:

my_networks <- tibble(
  network = ip_network(c("192.168.0.0/16", "2001:db8::/32")),
  label = c("Private", "Documentation")
)

my_networks
#> # A tibble: 2 x 2
#>          network label        
#>       <ip_netwk> <chr>        
#> 1 192.168.0.0/16 Private      
#> 2  2001:db8::/32 Documentation

and a handful of addresses:

my_addresses <- tibble(
  address = ip_address(c("192.168.100.1", "1.2.3.4", "2001:db8::8a2e:370:7334", "::1"))
)

First, we’ll check if each address is in any of our networks.

my_addresses %>%
  mutate(in_network = is_within_any(address, my_networks$network))
#> # A tibble: 4 x 2
#>                   address in_network
#>                 <ip_addr> <lgl>     
#> 1           192.168.100.1 TRUE      
#> 2                 1.2.3.4 FALSE     
#> 3 2001:db8::8a2e:370:7334 TRUE      
#> 4                     ::1 FALSE

But what if we need to know which of our networks the address was found in? We can do that using the excellent fuzzyjoin package together with the is_within() function.

my_addresses %>%
  fuzzyjoin::fuzzy_left_join(my_networks, c("address" = "network"), is_within)
#> # A tibble: 4 x 3
#>                   address        network label        
#>                 <ip_addr>     <ip_netwk> <chr>        
#> 1           192.168.100.1 192.168.0.0/16 Private      
#> 2                 1.2.3.4             NA <NA>         
#> 3 2001:db8::8a2e:370:7334  2001:db8::/32 Documentation
#> 4                     ::1             NA <NA>

Randomly generate public addresses

ipaddress provides functions to sample from a specific network (sample_network()) or the entire address space (sample_ipv4() and sample_ipv6()). However, it can be more difficult to sample from the majority of address space, while excluding certain networks.

A good example is sampling public IPv4 addresses. The simplest solution is to use an accept-reject algorithm – sampling the entire IPv4 address space and rejecting addresses that are reserved.

sample_public <- function(size) {
  result <- sample_ipv4(size)
  
  all_public <- FALSE
  while (!all_public) {
    public <- is_global(result)
    n_replace <- sum(!public)
    
    if (n_replace == 0) {
      all_public <- TRUE
    } else {
      result[!public] <- sample_ipv4(n_replace)
    }
  }
  
  result
}

We now sample 10 addresses and make sure they are all public addresses.

tibble(address = sample_public(10)) %>%
  mutate(is_public = is_global(address))
#> # A tibble: 10 x 2
#>           address is_public
#>         <ip_addr> <lgl>    
#>  1 151.37.179.166 TRUE     
#>  2  132.76.167.37 TRUE     
#>  3 202.175.181.26 TRUE     
#>  4  86.165.227.31 TRUE     
#>  5   97.195.64.24 TRUE     
#>  6    91.23.82.36 TRUE     
#>  7 74.241.184.229 TRUE     
#>  8  41.247.131.85 TRUE     
#>  9  233.24.194.48 TRUE     
#> 10 27.222.125.228 TRUE