Merge pull request #15 from siemens/fix/manual

doc: chores, resolves #12

docs/_footer.md

@@ -1,3 +1,3 @@
 <!-- markdownlint-disable MD022 MD041 -->
 ---
-Edgeshark manual ❖ © Siemens 2023 ❖ [siemens/edgeshark](https://github.com/siemens/edgeshark) on Github
+Edgeshark user manual ❖ © Siemens 2023 ❖ [siemens/edgeshark](https://github.com/siemens/edgeshark) on Github

docs/_sidebar.md

@@ -6,6 +6,7 @@
   * [Navigation](sidebar-navigation)
   * [Discovery](discovery)
   * [Wiring View](wiring)
+  * [Open & Forwarding Host Ports](open-house)
   * [Detail View](details)
   * [System Info](systeminfo)
   * [Snapshot](snapshot)

docs/details.md

@@ -141,6 +141,52 @@ the current location.
 > of current location container's virtual IP stack, it doesn't require any DNS
 > and IP tools (such as dig and ping) to be installed into containers.
 
+## Port Forwarding
+
+This section lists the TCP and UDP ports forwarded inside this specific
+(virtual) IP stack (network namespace). More precisely, this table covers TCP
+and UDP ports that undergo "destination NAT"
+([dNAT](https://en.m.wikipedia.org/wiki/Network_address_translation#DNAT)) for
+incoming packets, as well as the inverse translation for any replies.
+
+> [!NOTE] Please keep **port forwarding** apart from **source NAT**
+> ([sNAT](https://en.m.wikipedia.org/wiki/Network_address_translation#SNAT))
+> that instead covers traffic originating from a non-globally routable container
+> IP address and thus needs its source IP address replaced with one of the
+> host's externally facing IP addresses.
+
+**Edgeshark**'s port forwarding table covers both TCP and UDP ports forwarded
+using packet filter operations as well as via user-space [`docker-proxy`
+processes](https://windsock.io/the-docker-proxy/).
+
+In particular, **Edgeshark** detects (only)
+**[netfilter](https://en.m.wikipedia.org/wiki/Netfilter)-managed** packet
+mangling rules. However, as all relevant Linux distributions already have
+migrated to the netfilter framework years ago, this should not come as a real
+restriction. Interestingly, while Docker itself doesn't directly integrate with
+netfilter, it gets integrated via netfilter's iptables legacy integration layer.
+
+Edgeshark automatically detects **user-space [`docker-proxy` port forwarding
+processes](https://windsock.io/the-docker-proxy/)** that are [required under
+certain conditions](https://stackoverflow.com/a/49070640) for correctly
+forwarding traffic coming from a container into another container via (local)
+host port forwarding. These forwarded ports are aggregated with the ports
+discovered from packet-mangling rules and in particular, they are _not
+separately identified_.
+
+The port forwarding table not only shows the IP addresses and ports TCP and UDP
+ports get forwarded to, but additionally the containers/containees serving these
+ports.
+
+> [!NOTE] Docker users might notice TCP and UDP ports 53 getting forwarded
+> inside their containers soleley on the loopback address `127.0.0.11`. These
+> ports belong to Docker's embedded DNS service that resolves container and
+> service DNS names locally. In consequence, these forwarded ports are handled
+> by the `dockerd` daemon itself. These DNS service-related port forwardings are
+> only present if a container is attached to at least one custom (user-defined)
+> network, but not when a container is only attached to the `docker0`
+> default/legacy network.
+
 ## Transport
 
 This section is a special feature of Edgeshark (kind of

docs/getting-started.md

@@ -1,25 +1,34 @@
 <!-- markdownlint-disable MD029 -->
 # Getting Started
 
-Edgeshark consists of two services
-([Ghostwire](https://github.com/siemens/ghostwire) and
-[Packetflix](https://github.com/siemens/packetflix)), as  well as an _optional_
-Wireshark [csharg external capture
-plugin](https://github.com/siemens/cshargextcap) for live remote capture of
-network traffic.
+**Edgeshark** consists of
+1. two containerized 🛎 services named
+   [Ghostwire](https://github.com/siemens/ghostwire) and
+   [Packetflix](https://github.com/siemens/packetflix),
+2. as  well as an _optional_ Wireshark ⚙️ [csharg external capture
+   plugin](https://github.com/siemens/cshargextcap) for live remote capture of
+   network traffic.
 
-Siemens Industrial Edge users can simply deploy the Edgeshark App.
+## Service Deployment
 
-## Plain (Docker) Container Host
+We provide multi-architecture Docker images for the `linux/amd64` and
+`linux/arm64` architectures.
 
-We provide multi-architecture Docker images for linux/amd64 and linux/arm64.
-First, ensure that you have the Docker compose plugin v2 installed. For Debian
-users it is strongly recommended to install docker-ce instead of docker.io
-packages, as these are updated on a regular basis.
+<!-- tabs:start -->
+
+#### **Docker Compose v2**
+
+First, ensure that you have the Docker compose plugin v2 installed: `docker
+compose version` should display the compose plugin version, but not any error.
+For Debian users we recommend installing `docker-ce` instead of `docker.io`
+packages, as the `docker-ce` packages are updated on a regular basis.
+
+Then copy and paste the following command into a terminal to deploy the
+Edgeshark services:
 
 ```bash
 wget -q --no-cache -O - \
-  https://github.com/siemens/edgeshark/raw/main/deployments/wget/docker-compose.yaml \
+  https://github.com/siemens/edgeshark/raw/main/deployments/nocomposer/edgeshark.sh \
   | docker compose -f - up
 ```
 
@@ -30,15 +39,39 @@ host virtual networking.
 > clients external to your host. Make sure to have proper network protection in
 > place.
 
-## Industrial Edge App
+#### **Docker Bash**
+
+In case your particular system doesn't support Docker compose v2, we provide a
+simple fallback using a plain `bash` script.
+
+```bash
+wget -q --no-cache -O - \
+  https://github.com/siemens/edgeshark/raw/main/deployments/bash/docker-compose.yaml \
+  | bash -s up
+```
+
+The bash script takes a single argument, either `up` or `down`.
+
+Finally, visit http://localhost:5001 and start looking around your container
+host virtual networking.
+
+> [!WARNING] This quick start deployment will **expose TCP port 5001** also to
+> clients external to your host. Make sure to have proper network protection in
+> place.
+
+#### **Industrial Edge**
+
+1. Download the [latest Edgeshark app `.zip`
+   file](https://github.com/siemens/edgeshark/releases/latest) from the releases
+   section of this project. At the moment, we provide only app files for the
+   `linux/amd64` platform (a.k.a. `linux/x86-64`).
 
-> [!ATTENTION] Please note that we're working on providing in the future IE App
-> build artefacts in the download section of this project.
+2. Unpack the contained `edgeshark.app` file inside the `.zip` archive.
 
-1. Import the Edgeshark app (file named `edgeshark_*.app`) into your IEM
+3. Import the Edgeshark app file `edgeshark.app` into your IEM
    Industrial Edge Management system.
 
-2. Go to the catalog of your IEM and install the Edgeshark app onto your IED
+4. Go to the catalog of your IEM and deploy/install the Edgeshark app onto your IED
    Industrial Edge Device(s).
 
   > [!WARNING] The Edgeshark UI and services are exposed on port 5001 on your
@@ -47,7 +80,7 @@ host virtual networking.
   > nothing we can do until the IED-OS starts supporting session hand-overs from
   > a user web browser to an external application.)
 
-3. Navigate your browser to port HTTP 5001 on your IED:
+5. Navigate your browser to port HTTP 5001 on your IED:
    `http://`_ied-ip-address_`:5001` (please make sure to use `http:` and **not**
    `https:`). You should now see the "Edgeshark" user interface.
 
@@ -56,11 +89,13 @@ host virtual networking.
    > remote access to start remote captures (due to the aforementioned IED-OS
    > limitation).
 
+<!-- tabs:end -->
+
 Please see [Getting around](getting-around) for a tour of the user interface.
 
-Deploying Edgeshark on an Industrial Edge looks as below, with the service
-exposed via port `:443` (TLS, via the IED reverse proxy service) and directly
-HTTP-only on port `:5001`.
+Deploying Edgeshark creates the two services named packetflix and gostwire, and
+expose **port 5001** on the host as shown below. Please note that access via the
+Industrial Edge device reverse proxy is specific to this platform. 
 
 ![Edgeshark Services](_media/edgeshark-services.png)
 
@@ -71,50 +106,54 @@ Please note that you only need to install the external capture plugin
 intend to live capture container network traffic. Otherwise, you can completely
 ignore this section.
 
-### Windows 64 bit
+<!-- tabs:start -->
 
-We offer a Windows 64 bit installer (amd64 only) for the compiled plugin binary.
+#### **Windows 64bit**
 
-1. Make sure that you have Wireshark (64 bit) installed, at least version 3.0.2
-   or later is required (otherwise the plugin won't work correctly due to bugs
-   in Wireshark).
+We offer a Windows 64 bit installer for the `amd64` (`x86-64`) platform only.
 
-2. run the appropriate installer `csharg-*.exe` and follow the on-screen
-   instructions.
+1. Make sure that you have a sufficiently recent [Wireshark (64
+   bit)](https://wireshark.org) installed. At least version 3.0.2 or later is
+   required, as otherwise the plugin won't work correctly due to bugs in
+   Wireshark. Wireshark 4.x is also supported.
 
-Please see [Capturing](capture) for how to capture container network traffic
-using Wireshark with Edgeshark.
+2. [Download the latest Windows
+   installer](https://github.com/siemens/cshargextcap/releases/latest) `.zip`
+   file from the releases page of the siemens/csharkextcap project.
 
-### Debian/Ubuntu Linux 64 bit
+3. Double click on the downloaded `.zip` file to view its contents and then
+   simply run the included installer executable inside it. Next, follow the
+   on-screen instructions of the installer.
 
-As we don't offer an installer at this time, please install the plugin binary as
-follows:
+#### **Linux 64bit**
 
-1. install Wireshark `sudo apt-get install wireshark` and allow it to be used by
-   non-root users.
-2. [add your user to the wireshark group](https://askubuntu.com/a/461037):
+We offer distribution-specific packages in `.apk`, `.deb`, and `.rpm` formats
+for both `amd64` and `arm64` architectures.
+
+1. install Wireshark from your distribution repositories and allow it to be used
+   by non-root users.
+2. [add your user to the wireshark group](https://askubuntu.com/a/461037) (ask
+   Ubuntu):
 
    ```bash
    sudo gpasswd -a $USER wireshark
    ```
 
-   – Wireshark needs to run `dumpcap` from your
+   This is necessary so that Wireshark can correctly execute `dumpcap` for your
    non-root user in order to use the external capture plugin.
 3. log out of your session and then in again so that the new group assignment
    takes effect.
-4. to install the plugin package suitable for your Linux distribution, such as
-   on Debian-based distributions:
-
-   ```bash
-   sudo dpkg -i cshargextcap-*.deb
-   ```
-
-5. optionally: start Wireshark to check that the plugin was correctly detected
-   and queried: three new external capture targets should have been added
-   ("Docker host capture" and "packetflix:// remote cluster and container host
-   capture").
+4. [Download the latest plugin package](https://github.com/siemens/cshargextcap/releases/latest) suitable for your distribution and CPU architecture.
+5. install the downloaded plugin package.
+6. _optionally:_ start Wireshark to verify that the plugin was correctly
+   detected and queried: three new external capture targets should have been
+   added ("Docker host capture" and "packetflix:// remote cluster and container
+   host capture").
 
    ![external capture plugins](_images/wireshark-linux-extcaps-list.png
    ':class=scrshot')
 
-6. [starting a capture via Web UI](capture-ui).
+<!-- tabs:end -->
+
+Please see [Capturing](capture) for how to capture container network traffic
+using Wireshark with Edgeshark.

docs/index.html

@@ -146,6 +146,12 @@
         hideOtherSidebarContent: false,
         namespace: 'edgeshark',
       },
+
+      tabs: {
+        theme: 'classic',
+        persist: true,
+        sync: false,
+      },
     }
   </script>
   <!-- Docsify v4 -->
@@ -155,11 +161,12 @@
   <script src="//cdn.jsdelivr.net/npm/@alertbox/docsify-footer/dist/docsify-footer.min.js"></script>
   <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
   <script src="https://unpkg.com/docsify-plugin-flexible-alerts"></script>
+  <script src="//cdn.jsdelivr.net/npm/docsify-tabs@1"></script>
   <script src="//cdn.jsdelivr.net/npm/docsify-corner/dist/docsify-corner.min.js"></script>
   <script src="//cdn.jsdelivr.net/npm/docsify-darklight-theme@3/dist/docsify-themeable/main.min.js"
     type="text/javascript"></script>
   <script src="//cdn.jsdelivr.net/npm/docsify-darklight-theme@3/dist/docsify-themeable/index.min.js"
     type="text/javascript"></script>
 </body>
 
-</html>
+</html>

docs/introduction.md

@@ -2,10 +2,14 @@
 
 ![Edgeshark logo](_images/edgeshark.png ':no-zoom :size=100 :class=mascot')
 
-**Edgeshark** helps in diagnosing and optionally capturing the communication
-between containers and with their outside world in Linux stand-alone container
-hosts and KinD deployments. Not least, Edgeshark can easily be deployed to
-[Siemens Industrial
+> Quick, just get me 🚀 **[started](getting-started)!**
+
+**Edgeshark** visualizes the communication of containers and thus helps in
+diagnosing it, both in-between containers as well as with the "outside world".
+It can be deployed to Linux stand-alone container hosts, including
+[KinD](https://kind.sigs.k8s.io/) deployments. Edgeshark also supports capturing
+container traffic using [Wireshark](https://wireshark.org). Another natural
+habitat of Edgeshark are [Siemens Industrial
 Edge](https://new.siemens.com/global/en/products/automation/topic-areas/industrial-edge.html)
 devices.
 

docs/open-house.md

@@ -0,0 +1,18 @@
+# Open & Forwarding Ports
+
+This view shows all TCP and UDP transport ports of a host system that are either
+opened directly by processes, or host ports that are being forwarded to other IP
+addresses and ports, usually belonging to service containers.
+
+This view thus gives an overview on the externally accessible host ports in a
+single place – but please notice it can additionally include host-local services
+that aren't accessible from the outside. Such host-local services are bound to
+the loopback IP addresses `127.0.0.0/8` and/or `::1` in case of IPv6.
+
+Please note that this view **does not show any established TCP or UDP
+connections**, but only open in the sense of "listening" and forwarded ports.
+Information about established communication connections can be found instead in
+the [transport details](details#transport) of the corresponding containers, as
+well as the initial process (such as `systemd(1)`). For this, please navigate to
+the wiring view and then touch or click on a container/containee to see its
+details.

docs/settings.md

@@ -50,18 +50,24 @@ so-called "bind mounts".)
 ## Detail Sections Default Expansion
 
 The detail information about the communication of a virtual IP stack is divided
-into logical sections: container details, TCP/UDP transport ports, IP stack
-routes, and network interface addresses. As the information at least in some
-sections can get quite large, users might want to set their preferences as to
-when to collapse or expand the individual sections, based on the amount of
-information present.
+into logical sections:
+- [container (containee) details](details#containerscontainees),
+- [neighborhood services](details#neighborhood-services) (Docker only),
+- forwarded TCP/UDP ports,
+- [TCP/UDP transport ports](details#transport),
+- [IP stack routes](details#routing),
+- [network interfaces configuration](details#interface-configuration).
+
+As the information at least in some sections can get quite large, users might
+want to set their preferences as to when to collapse or expand the individual
+sections, based on the amount of information present.
 
 In general, user can control for each individual section:
 
-- always show collapsed (minimized),
-- always show expanded,
-- up to a threshold of 1-5, 10, 20, or 30 items expand the section, if above the
-  threshold then show the section collapsed.
+- **always show collapsed** (minimized),
+- **always show expanded**,
+- up to a **threshold** of 1-5, 10, 20, or 30 items expand the section, if above
+  the threshold then show the section collapsed.
 
 ## Siemens Industrial Edge