README.md
1# `sockaddr(1)`
2
3`sockaddr` is a CLI utility that wraps and exposes `go-sockaddr` functionality
4from the command line.
5
6```text
7$ go get -u github.com/hashicorp/go-sockaddr/cmd/sockaddr
8```
9
10```text
11% sockaddr -h
12usage: sockaddr [--version] [--help] <command> [<args>]
13
14Available commands are:
15 dump Parses IP addresses
16 eval Evaluates a sockaddr template
17 rfc Test to see if an IP is part of a known RFC
18 version Prints the sockaddr version
19```
20
21## `sockaddr dump`
22
23```text
24Usage: sockaddr dump [options] input [...]
25
26 Parse address(es) or interface and dumps various output.
27
28Options:
29
30 -4 Parse the input as IPv4 only
31 -6 Parse the input as IPv6 only
32 -H Machine readable output
33 -I Parse the argument as an interface name
34 -i Parse the input as IP address (either IPv4 or IPv6)
35 -n Show only the value
36 -o Name of an attribute to pass through
37 -u Parse the input as a UNIX Socket only
38```
39
40### `sockaddr dump` example output
41
42By default it prints out all available information unless the `-o` flag is
43specified.
44
45```text
46% sockaddr dump 127.0.0.2/8
47Attribute Value
48type IPv4
49string 127.0.0.2/8
50host 127.0.0.2
51address 127.0.0.2
52port 0
53netmask 255.0.0.0
54network 127.0.0.0/8
55mask_bits 8
56binary 01111111000000000000000000000010
57hex 7f000002
58first_usable 127.0.0.1
59last_usable 127.255.255.254
60octets 127 0 0 2
61size 16777216
62broadcast 127.255.255.255
63uint32 2130706434
64DialPacket "udp4" ""
65DialStream "tcp4" ""
66ListenPacket "udp4" ""
67ListenStream "tcp4" ""
68$ sockaddr dump -H -o host,address,port -o mask_bits 127.0.0.3:8600
69host 127.0.0.3:8600
70address 127.0.0.3
71port 8600
72mask_bits 32
73$ sockaddr dump -H -n -o host,address,port -o mask_bits 127.0.0.3:8600
74127.0.0.3:8600
75127.0.0.3
768600
7732
78$ sockaddr dump -o type,address,hex,network '[2001:db8::3/32]'
79Attribute Value
80type IPv6
81address 2001:db8::3
82network 2001:db8::/32
83hex 20010db8000000000000000000000003
84$ sockaddr dump /tmp/example.sock
85Attribute Value
86type UNIX
87string "/tmp/example.sock"
88path /tmp/example.sock
89DialPacket "unixgram" "/tmp/example.sock"
90DialStream "unix" "/tmp/example.sock"
91ListenPacket "unixgram" "/tmp/example.sock"
92ListenStream "unix" "/tmp/example.sock"
93```
94
95## `sockaddr eval`
96
97```text
98Usage: sockaddr eval [options] [template ...]
99
100 Parse the sockaddr template and evaluates the output.
101
102 The `sockaddr` library has the potential to be very complex,
103 which is why the `sockaddr` command supports an `eval`
104 subcommand in order to test configurations from the command
105 line. The `eval` subcommand automatically wraps its input
106 with the `{{` and `}}` template delimiters unless the `-r`
107 command is specified, in which case `eval` parses the raw
108 input. If the `template` argument passed to `eval` is a
109 dash (`-`), then `sockaddr eval` will read from stdin and
110 automatically sets the `-r` flag.
111
112Options:
113
114 -d Debug output
115 -n Suppress newlines between args
116 -r Suppress wrapping the input with {{ }} delimiters
117```
118
119Here are a few impractical examples to get you started:
120
121```text
122$ sockaddr eval 'GetAllInterfaces | include "flags" "forwardable" | include "up" | sort "default,type,size" | include "RFC" "6890" | attr "address"'
123172.14.6.167
124$ sockaddr eval 'GetDefaultInterfaces | sort "type,size" | include "RFC" "6890" | limit 1 | join "address" " "'
125172.14.6.167
126$ sockaddr eval 'GetPublicIP'
127203.0.113.4
128$ sockaddr eval 'GetPrivateIP'
129172.14.6.167
130$ sockaddr eval 'GetInterfaceIP "eth0"'
131172.14.6.167
132$ sockaddr eval 'GetAllInterfaces | include "network" "172.14.6.0/24" | attr "address"'
133172.14.6.167
134$ sockaddr eval 'GetPrivateInterfaces | join "type" " "'
135IPv4 IPv6
136$ sockaddr eval 'GetAllInterfaces | include "flags" "forwardable" | join "address" " "'
137203.0.113.4 2001:0DB8::1
138$ sockaddr eval 'GetAllInterfaces | include "name" "lo0" | include "type" "IPv6" | sort "address" | join "address" " "'
139100:: fe80::1
140$ sockaddr eval '. | include "rfc" "1918" | print | len | lt 2'
141true
142$ sockaddr eval -r '{{with $ifSet := include "name" "lo0" . }}{{ range include "type" "IPv6" $ifSet | sort "address" | reverse}}{{ . }} {{end}}{{end}}'
143fe80::1/64 {1 16384 lo0 up|loopback|multicast} 100:: {1 16384 lo0 up|loopback|multicast}
144$ sockaddr eval '. | include "name" "lo0" | include "type" "IPv6" | sort "address" | join "address" " "'
145100:: fe80::1
146$ cat <<'EOF' | sockaddr eval -
147{{. | include "name" "lo0" | include "type" "IPv6" | sort "address" | join "address" " "}}
148EOF
149100:: fe80::1
150$ sockaddr eval 'GetPrivateInterfaces | include "flags" "forwardable|up" | include "type" "IPv4" | math "network" "+2" | attr "address"'
151172.14.6.2
152$ cat <<'EOF' | sudo tee -a /etc/profile
153export CONSUL_HTTP_ADDR="http://`sockaddr eval 'GetInterfaceIP \"eth0\"'`:8500"
154EOF
155```
156
157## `sockaddr rfc`
158
159```text
160$ sockaddr rfc
161Usage: sockaddr rfc [RFC Number] [IP Address]
162
163 Tests a given IP address to see if it is part of a known
164 RFC. If the IP address belongs to a known RFC, return exit
165 code 0 and print the status. If the IP does not belong to
166 an RFC, return 1. If the RFC is not known, return 2.
167
168Options:
169
170 -s Silent, only return different exit codes
171$ sockaddr rfc 1918 192.168.1.10
172192.168.1.10 is part of RFC 1918
173$ sockaddr rfc 6890 '[::1]'
174100:: is part of RFC 6890
175$ sockaddr rfc list
176919
1771112
1781122
1791918
1802544
1812765
1822928
1833056
1843068
1853171
1863330
1873849
1883927
1894038
1904193
1914291
1924380
1934773
1944843
1955180
1965735
1975737
1986052
1996333
2006598
2016666
2026890
2037335
204```
205
206## `sockaddr tech-support`
207
208If one of the helper methods that derives its output from `GetDefaultInterfaces`
209is misbehaving, submit the output from this command as an issue along with
210any miscellaneous details that are specific to your environment.
211
212```text
213Usage: sockaddr tech-support [options]
214
215 Print out network diagnostic information that can be used by
216 support.
217
218 The `sockaddr` library relies on OS-specific commands and
219 output which can potentially be brittle. The `tech-support`
220 subcommand emits all of the platform-specific network
221 details required to debug why a given `sockaddr` API call is
222 behaving differently than expected. The `-output` flag
223 controls the output format. The default output mode is
224 Markdown (`md`) however a raw mode (`raw`) is available to
225 obtain the original output.
226
227Options:
228
229 -output Encode the output using one of Markdown ("md") or Raw ("raw")
230```
231
232## `sockaddr version`
233
234The lowly version stub.
235
236```text
237$ sockaddr version
238sockaddr 0.1.0-dev
239```
240