diff options
Diffstat (limited to 'vendor/github.com/hashicorp/go-sockaddr/cmd/sockaddr/README.md')
| -rw-r--r-- | vendor/github.com/hashicorp/go-sockaddr/cmd/sockaddr/README.md | 234 |
1 files changed, 234 insertions, 0 deletions
diff --git a/vendor/github.com/hashicorp/go-sockaddr/cmd/sockaddr/README.md b/vendor/github.com/hashicorp/go-sockaddr/cmd/sockaddr/README.md new file mode 100644 index 000000000..cc247afb5 --- /dev/null +++ b/vendor/github.com/hashicorp/go-sockaddr/cmd/sockaddr/README.md @@ -0,0 +1,234 @@ +# `sockaddr(1)` + +`sockaddr` is a CLI utility that wraps and exposes `go-sockaddr` functionality +from the command line. + +```text +$ go get -u github.com/hashicorp/go-sockaddr/cmd/sockaddr +``` + +```text +% sockaddr -h +usage: sockaddr [--version] [--help] <command> [<args>] + +Available commands are: + dump Parses IP addresses + eval Evaluates a sockaddr template + rfc Test to see if an IP is part of a known RFC + version Prints the sockaddr version +``` + +## `sockaddr dump` + +```text +Usage: sockaddr dump [options] input [...] + + Parse address(es) or interface and dumps various output. + +Options: + + -4 Parse the input as IPv4 only + -6 Parse the input as IPv6 only + -H Machine readable output + -I Parse the argument as an interface name + -i Parse the input as IP address (either IPv4 or IPv6) + -n Show only the value + -o Name of an attribute to pass through + -u Parse the input as a UNIX Socket only +``` + +### `sockaddr dump` example output + +By default it prints out all available information unless the `-o` flag is +specified. + +```text +% sockaddr dump 127.0.0.2/8 +Attribute Value +type IPv4 +string 127.0.0.2/8 +host 127.0.0.2 +address 127.0.0.2 +port 0 +netmask 255.0.0.0 +network 127.0.0.0/8 +mask_bits 8 +binary 01111111000000000000000000000010 +hex 7f000002 +first_usable 127.0.0.1 +last_usable 127.255.255.254 +octets 127 0 0 2 +size 16777216 +broadcast 127.255.255.255 +uint32 2130706434 +DialPacket "udp4" "" +DialStream "tcp4" "" +ListenPacket "udp4" "" +ListenStream "tcp4" "" +$ sockaddr dump -H -o host,address,port -o mask_bits 127.0.0.3:8600 +host 127.0.0.3:8600 +address 127.0.0.3 +port 8600 +mask_bits 32 +$ sockaddr dump -H -n -o host,address,port -o mask_bits 127.0.0.3:8600 +127.0.0.3:8600 +127.0.0.3 +8600 +32 +$ sockaddr dump -o type,address,hex,network '[2001:db8::3/32]' +Attribute Value +type IPv6 +address 2001:db8::3 +network 2001:db8::/32 +hex 20010db8000000000000000000000003 +$ sockaddr dump /tmp/example.sock +Attribute Value +type UNIX +string "/tmp/example.sock" +path /tmp/example.sock +DialPacket "unixgram" "/tmp/example.sock" +DialStream "unix" "/tmp/example.sock" +ListenPacket "unixgram" "/tmp/example.sock" +ListenStream "unix" "/tmp/example.sock" +``` + +## `sockaddr eval` + +```text +Usage: sockaddr eval [options] [template ...] + + Parse the sockaddr template and evaluates the output. + + The `sockaddr` library has the potential to be very complex, + which is why the `sockaddr` command supports an `eval` + subcommand in order to test configurations from the command + line. The `eval` subcommand automatically wraps its input + with the `{{` and `}}` template delimiters unless the `-r` + command is specified, in which case `eval` parses the raw + input. If the `template` argument passed to `eval` is a + dash (`-`), then `sockaddr eval` will read from stdin and + automatically sets the `-r` flag. + +Options: + + -d Debug output + -n Suppress newlines between args + -r Suppress wrapping the input with {{ }} delimiters +``` + +Here are a few impractical examples to get you started: + +```text +$ sockaddr eval 'GetDefaultInterfaces | sort "type,size" | include "RFC" "6890" | attr "address"' +172.14.6.167 +$ sockaddr eval 'GetDefaultInterfaces | sort "type,size" | include "RFC" "6890" | limit 1 | join "address" " "' +172.14.6.167 +$ sockaddr eval 'GetPublicIP' +203.0.113.4 +$ sockaddr eval 'GetPrivateIP' +172.14.6.167 +$ sockaddr eval 'GetInterfaceIP "eth0"' +172.14.6.167 +$ sockaddr eval 'GetAllInterfaces | include "network" "172.14.6.0/24" | attr "address"' +172.14.6.167 +$ sockaddr eval 'GetPrivateInterfaces | join "type" " "' +IPv4 IPv6 +$ sockaddr eval 'GetPublicInterfaces | include "flags" "up|forwardable" | join "address" " "' +203.0.113.4 2001:0DB8::1 +$ sockaddr eval 'GetAllInterfaces | include "name" "lo0" | include "type" "IPv6" | sort "address" | join "address" " "' +100:: fe80::1 +$ sockaddr eval '. | include "rfc" "1918" | print | len | lt 2' +true +$ sockaddr eval -r '{{with $ifSet := include "name" "lo0" . }}{{ range include "type" "IPv6" $ifSet | sort "address" | reverse}}{{ . }} {{end}}{{end}}' +fe80::1/64 {1 16384 lo0 up|loopback|multicast} 100:: {1 16384 lo0 up|loopback|multicast} +$ sockaddr eval '. | include "name" "lo0" | include "type" "IPv6" | sort "address" | join "address" " "' +100:: fe80::1 +$ cat <<'EOF' | sockaddr eval - +{{. | include "name" "lo0" | include "type" "IPv6" | sort "address" | join "address" " "}} +EOF +100:: fe80::1 +``` + +## `sockaddr rfc` + +```text +$ sockaddr rfc +Usage: sockaddr rfc [RFC Number] [IP Address] + + Tests a given IP address to see if it is part of a known + RFC. If the IP address belongs to a known RFC, return exit + code 0 and print the status. If the IP does not belong to + an RFC, return 1. If the RFC is not known, return 2. + +Options: + + -s Silent, only return different exit codes +$ sockaddr rfc 1918 192.168.1.10 +192.168.1.10 is part of RFC 1918 +$ sockaddr rfc 6890 '[::1]' +100:: is part of RFC 6890 +$ sockaddr rfc list +919 +1112 +1122 +1918 +2544 +2765 +2928 +3056 +3068 +3171 +3330 +3849 +3927 +4038 +4193 +4291 +4380 +4773 +4843 +5180 +5735 +5737 +6052 +6333 +6598 +6666 +6890 +7335 +``` + +## `sockaddr tech-support` + +If one of the helper methods that derives its output from `GetDefaultInterfaces` +is misbehaving, submit the output from this command as an issue along with +any miscellaneous details that are specific to your environment. + +```text +Usage: sockaddr tech-support [options] + + Print out network diagnostic information that can be used by + support. + + The `sockaddr` library relies on OS-specific commands and + output which can potentially be brittle. The `tech-support` + subcommand emits all of the platform-specific network + details required to debug why a given `sockaddr` API call is + behaving differently than expected. The `-output` flag + controls the output format. The default output mode is + Markdown (`md`) however a raw mode (`raw`) is available to + obtain the original output. + +Options: + + -output Encode the output using one of Markdown ("md") or Raw ("raw") +``` + +## `sockaddr version` + +The lowly version stub. + +```text +$ sockaddr version +sockaddr 0.1.0-dev +``` |