Adding Dockerfile and docker documentation

[komish]

Fixes #22

Thanks for the opportunity to work on this!

Operating System

# lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Description:    Ubuntu 18.04.1 LTS
Release:    18.04
Codename:   bionic

Docker-CE versioning

# dpkg -l | grep docker
ii  docker-ce                            18.06.1~ce~3-0~ubuntu                  amd64        Docker: the open-source application container engine

Dockerfile contents (for reference)

# cat Dockerfile
FROM python:3

ADD . /opt/get-mac
WORKDIR /opt/get-mac

RUN python setup.py install

ENTRYPOINT ["get-mac"]

Build command

# docker build . -t get-mac

Sample Execution

Equivalent of running this with no arguments

# docker run -it get-mac:latest
02:42:ac:11:00:02

Running with --help

# docker run -it get-mac:latest --help
usage: get-mac [-h] [--version] [-d] [--no-network-requests]
               [-i INTERFACE | -4 IP | -6 IP6 | -n HOSTNAME]

Get the MAC address of system network interfaces or remote hosts on the LAN

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  -d, --debug           Enable debugging output. Add characters to increase
                        verbosity of output, e.g. '-dd'.
  --no-network-requests
                        Do not send a UDP packet to refresh the ARP table
  -i INTERFACE, --interface INTERFACE
                        Name of a network interface on the system
  -4 IP, --ip IP        IPv4 address of a remote host
  -6 IP6, --ip6 IP6     IPv6 address of a remote host
  -n HOSTNAME, --hostname HOSTNAME
                        Hostname of a remote host

Running against named targets

# docker run -it get-mac -4 172.17.0.1
02:42:26:40:4f:c9

# docker run -it get-mac -n localhost
00:00:00:00:00:00

This provides some interesting solutions which are difficult to demonstrate in my lab, but you could essentially run some ad-hoc container introspection using this utility by wrapping your docker run function in some logic allowing you to specify any of your container networks and targets.

# alias getmac='docker run -it get-mac'
# getmac
02:42:ac:11:00:02
# getmac -n localhost
00:00:00:00:00:00

Most of my testing was done on docker0 with a flat network but the application should be the same in other network structures. The key thing is remembering what networking looks like in your container which can be abstracted enough such that using this utility might be confusing at first glance.

If you wanted to run this on a workstation that had docker running, you could attach the container to your host network. You wouldn't be able to use NAT networking in that case, I imagine, as what the container sees is limited to the private network that only docker0 knows.

At any rate, a majority of this contribution is the Dockerfile which can be used to build a local image or one on Docker Hub under your ownership if that's your goal. I've updated the documentation to include usage examples

[GhostofGoes]

Wow, this is beyond awesome. Thank you Jose!