Skip to content

Latest commit

 

History

History
145 lines (88 loc) · 5.68 KB

INSTALL.md

File metadata and controls

145 lines (88 loc) · 5.68 KB
Raw

Get PcapInspect's dependencies

PcapInspect requires python3, matplotlib, numpy and tshark.

I've found it handy to develop PcapInspect in Jupyter which enables interactive development in a browser, including embedded display of any graphics generated by PcapInspect.

Strictly speaking, Jupyter itself is not a dependency, but I'd recommend it for interactive development, and because its docker image comes with some of PcapInspect's dependencies (matplotlib and numpy) pre-installed.

Clone the PcapInspect repo in the container

For each of the installation types below, you'll need to clone the PcapInspect repo via passwordless HTTPS:

git clone https://github.com/aristanetworks/pcapinspect.git

Or ssh (Requires SSH key):

git clone git@github.com:aristanetworks/pcapinspect.git

Ubuntu (Tried on 18.04.5 LTS)

sudo apt-get install -y python3-pip tshark
sudo -H pip3 install matplotlib numpy

When running pip3 using sudo in the past, I have seen a warning suggesting I use pip3 install --user instead of sudo. Perhaps these instructions should be updated accordingly.

macOS (Tried on Mojave 10.14.6)

There are other ways to get tshark, but I did it using Homebrew. Here it's part of wireshark.

pip3 install numpy matplotlib
brew cask install wireshark
export PATH=/Applications/Wireshark.app/Contents/MacOS:$PATH

Jupyter

Note that:

  • The Jupyter container comes with matplotlib and numpy pre-installed.
  • As of 16-Oct-2020, the Jupyter docker images are based on Ubuntu 20.04.1 LTS.

Setup Docker

If your system doesn't already have Docker, you'll need to setup it up first to be able follow these instructions. See, for example, Docker's 'get started' page. Although these instructions run Jupyter in a Docker container, that is not a requirement in order to be able to use PcapInspect with Jupyter - it should work in any environment that Jupyter runs in.

Installing and starting Jupyter

I used the jupyter/scipy-notebook image from the list of variants decribed here.

Run this command to get the docker image:

docker pull jupyter/scipy-notebook:latest

See also the Jupyter docker quickstart guide.

To start Jupyter, run this command:

docker run -d --restart unless-stopped --name pcapinspect --publish 16681:8888 --volume $HOME/path/to/a/directory:/pcapinspect jupyter/scipy-notebook

On my server (us124), this makes Jupyter accessible via http://us124:16681/

The user in the container is jovyan - see https://jupyter.readthedocs.io/en/latest/community/content-community.html#what-is-a-jovyan

Be careful giving a container access to your home-directory like this via --volume! This makes the specified directory available at /pcapinspect within the container which makes it easy to get data into and out of the container.

Granting jovyan sudo privileges

For doing things like installing packages, it can be handy for jovyan to have sudo privileges.

  1. Via /etc/sudoers (This used to work for me, but didn't the last time I tried it 😞️)

    Set jovyan's password and add to sudo group:

    ~ @us124>  docker exec -it --user root pcapinspect /bin/bash
(base) root@4b041e205c76:~# passwd jovyan
(base) root@4b041e205c76:~# usermod -aG sudo jovyan

    Edit /etc/sudoers to "allow members of group sudo to execute any command":

    (base) jovyan@4b041e205c76:~$ sudo diff --unified /etc/sudoers.orig /etc/sudoers
--- /etc/sudoers.orig   2020-10-15 16:12:51.406019658 +0000
+++ /etc/sudoers        2020-10-15 16:17:04.512175793 +0000
@@ -23,7 +23,7 @@
 #%admin ALL=(ALL) ALL

 # Allow members of group sudo to execute any command
-#%sudo ALL=(ALL:ALL) ALL
+%sudo  ALL=(ALL:ALL) ALL

 # See sudoers(5) for more information on "#include" directives:

  2. Via GRANT_SUDO (not tried yet)

    Alternatively, for passwordless sudo, set the GRANT_SUDO env var when starting the container: jupyter/docker-stacks#408 (comment)

tshark

To enter the container as jovyan and install tshark run the following commands:

docker exec -it --user jovyan pcapinspect /bin/bash
sudo apt update
sudo apt-get install -y tshark

Other packages possibly needed in the container

ping is not provided in the container by default. To get it, run:

sudo apt-get install -y iputils-ping

If you want to push changes to a fork of PcapInspect from within the Jupyter container, you'll need an SSH key. To generate the SSH key, you'll need to install openssh-client to get ssh-keygen:

sudo apt-get install -y openssh-client

Accessing Jupyter

To access Jupyter via a browser, you need a token. To see the token, do this:

docker exec pcapinspect jupyter notebook list

This prints something like:

http://0.0.0.0:8888/?token=2ce42b6b124948850309877863683a44698c926e618a96b4 :: /home/jovyan

So, to access Jupyter, as I'm on the server called us124 and with the port setting in the docker run command above, I use this instead:

http://us124:16681/?token=2ce42b6b124948850309877863683a44698c926e618a96b4

So far, the token has changed each time I have restarted the container.