fix(trip): various installer fixes and doc updates

2026-08-19 03:56:16 +00:00 · 2023-10-28 01:30:15 -06:00
parent f2b9533fd3
commit a22af8815e
3 changed files with 147 additions and 68 deletions
@@ -5,7 +5,27 @@ tagline: |
  Trippy: A tool that combines the functionality of traceroute and ping designed for networking issue analysis.
 ---

-To update or switch versions, run `webi trippy@stable` (or `@v2`, `@beta`, etc).
+To update or switch versions, run `webi trip@stable` (or `@v0.8`, `@beta`, etc).
+
+## Cheat Sheet
+
+> Trippy combines the functionality of `traceroute` and `ping` to assist in
+> analyzing networking issues. It supports multiple protocols such as ICMP, UDP,
+> and TCP, and is equipped with a Tui interface for detailed analysis.
+
+```sh
+sudo env PATH="$PATH" trip example.com
+```
+
+![](https://github.com/fujiapple852/trippy/blob/0.8.0/assets/0.8.0/hop_details.png?raw=true)
+
+## Table of Contents
+
+- Files
+- Granting Root
+- Tracing Protocols
+- Tracing Options
+- GoeIP Map

 ### Files

@@ -13,43 +33,75 @@ These are the files / directories that are created and/or modified with this
 install:

 ```text
-~/.config/trippy/config.toml
-~/.local/bin/trippy
-~/.local/opt/trippy-vX.X.X
+~/.config/trippy.toml
+~/.local/bin/trip
+<PROJECT-DIR>/.trippy.toml
+
+# Windows
+~/.local/bin/sudo.cmd
+/Windows/System32/vcruntime140.dll (msvc runtime)
 ```

-## Cheat Sheet
+### How to Always Run as Root

-> Trippy combines the functionality of traceroute and ping to assist in
-> analyzing networking issues. It supports multiple protocols such as ICMP, UDP,
-> and TCP, and is equipped with a Tui interface for detailed analysis.
+Due to the nature of raw network access, `trip` always needs to run with
+elevated network privileges.

-To run Trippy:
+On Linux `setcap` can be used to limit its root privileges to the network only.
+On other systems it may need full root access.
+
+**Linux**

 ```sh
-trippy [options]
+trip_bin="$( readlink -f "$( command -v trip )" )"
+
+sudo setcap 'CAP_NET_RAW+p' "${trip_bin}"
 ```

-### Trace Using Multiple Protocols
-
-To trace using ICMP:
+**macOS**

 ```sh
-trippy --protocol ICMP
+trip_bin="$( command -v trip )"
+
+sudo chown root "${trip_bin}" && \
+    sudo chmod +s "${trip_bin}"
 ```

-### Customizable Tracing Options
+**Windows**

-To set packet size & payload pattern:
+1. You need to add a firewall rule to allow ICMP
+   ```pwsh
+   New-NetFirewallRule -DisplayName "ICMP Trippy Allow" -Name ICMP_TRIPPY_ALLOW -Protocol ICMPv4 -Action Allow
+   ```
+2. You'll need to run with an Administrator shell, or `sudo.cmd` **every time**:
+   ```sh
+   sudo.cmd trip.exe example.com
+   ```
+
+### How to Trace with Various Protocols
+
+You can use `icmp`, `tcp`, or `udp`:

 ```sh
-trippy --packet-size 64 --payload-pattern "pattern"
+trip --protocol icmp example.com
 ```

-### Tui Interface
+### How to set Tracing Options

-Launch Trippy with the Tui interface:
+You can pick a payload byte pattern (0-255) and packet size:

 ```sh
-trippy --tui
+trip --packet-size 64 --payload-pattern 255
 ```
+
+### How to View GeoIP Mapping
+
+You'll need to download a geoip map database, such as this:
+
+- <https://dev.maxmind.com/geoip/geolite2-free-geolocation-data>
+
+```sh
+trip example.com --geoip-mmdb-file ./GeoLite2-City.mmdb --tui-geoip-mode long
+```
+
+![](https://github.com/fujiapple852/trippy/raw/0.8.0/assets/0.8.0/world_map.png)
@@ -5,57 +5,84 @@
 ##################

 # Every package should define these variables
-$pkg_cmd_name = "trippy"
+$pkg_cmd_name = "trip"

-$pkg_dst_cmd = "$Env:USERPROFILE\.local\bin\trippy.exe"
-$pkg_dst = "$pkg_dst_cmd"
+$pkg_dst_cmd = "$Env:USERPROFILE\.local\bin\trip.exe"
+$pkg_dst_bin = "$Env:USERPROFILE\.local\bin"
+$pkg_dst = "$pkg_dst_bin"

-$pkg_src_cmd = "$Env:USERPROFILE\.local\opt\trippy-v$Env:WEBI_VERSION\bin\trippy.exe"
+$pkg_src_cmd = "$Env:USERPROFILE\.local\opt\trippy-v$Env:WEBI_VERSION\bin\trip.exe"
 $pkg_src_bin = "$Env:USERPROFILE\.local\opt\trippy-v$Env:WEBI_VERSION\bin"
 $pkg_src_dir = "$Env:USERPROFILE\.local\opt\trippy-v$Env:WEBI_VERSION"
 $pkg_src = "$pkg_src_cmd"

-New-Item "$Env:USERPROFILE\Downloads\webi" -ItemType Directory -Force | out-null
+New-Item "$Env:USERPROFILE\Downloads\webi" -ItemType Directory -Force | Out-Null
 $pkg_download = "$Env:USERPROFILE\Downloads\webi\$Env:WEBI_PKG_FILE"

-# Fetch archive
-IF (!(Test-Path -Path "$Env:USERPROFILE\Downloads\webi\$Env:WEBI_PKG_FILE"))
-{
-    echo "Downloading trippy from $Env:WEBI_PKG_URL to $pkg_download"
-    & curl.exe -A "$Env:WEBI_UA" -fsSL "$Env:WEBI_PKG_URL" -o "$pkg_download.part"
-    & move "$pkg_download.part" "$pkg_download"
+# Fetch MSVC Runtime
+Write-Output "Checking for MSVC Runtime..."
+IF (-not (Test-Path "\Windows\System32\vcruntime140.dll")) {
+    & "$Env:USERPROFILE\.local\bin\webi-pwsh.ps1" vcruntime
 }

-IF (!(Test-Path -Path "$pkg_src_cmd"))
-{
-    echo "Installing trippy"
+# Fetch sudo Runtime
+Write-Output "Checking for sudo.cmd..."
+IF (-not (Test-Path "$Env:USERPROFILE\.local\bin\sudo.cmd")) {
+    Set-Content -Path "$Env:USERPROFILE\.local\bin\sudo.cmd" -Value "@echo off`r`npowershell -Command ""Start-Process cmd -Verb RunAs -ArgumentList '/c cd /d %CD% && %*'""`r`n@echo on"
+}
+
+# Fetch archive
+IF (!(Test-Path -Path "$pkg_download")) {
+    Write-Output "Downloading trippy from $Env:WEBI_PKG_URL to $pkg_download"
+    & curl.exe -A "$Env:WEBI_UA" -fsSL "$Env:WEBI_PKG_URL" -o "$pkg_download.part"
+    & Move-Item "$pkg_download.part" "$pkg_download"
+}
+
+IF (!(Test-Path -Path "$pkg_src_cmd")) {
+    Write-Output "Installing trippy"

    # TODO: create package-specific temp directory
    # Enter tmp
-    pushd .local\tmp
+    Push-Location .local\tmp

-        # Remove any leftover tmp cruft
-        Remove-Item -Path ".\trippy-v*" -Recurse -ErrorAction Ignore
-        Remove-Item -Path ".\trippy.exe" -Recurse -ErrorAction Ignore
+    # Remove any leftover tmp cruft
+    Remove-Item -Path ".\trippy-v*" -Recurse -ErrorAction Ignore
+    Remove-Item -Path ".\trip.exe" -Recurse -ErrorAction Ignore

-        # NOTE: DELETE THIS COMMENT IF NOT USED
-        # Move single binary into root of temporary folder
-        #& move "$pkg_download" "trippy.exe"
+    # NOTE: DELETE THIS COMMENT IF NOT USED
+    # Move single binary into root of temporary folder
+    #& move "$pkg_download" "trippy.exe"

-        # Unpack archive file into this temporary directory
-        # Windows BSD-tar handles zip. Imagine that.
-        echo "Unpacking $pkg_download"
-        & tar xf "$pkg_download"
+    # Unpack archive file into this temporary directory
+    # Windows BSD-tar handles zip. Imagine that.
+    Write-Output "Unpacking $pkg_download"
+    & tar xf "$pkg_download"

-        # Settle unpacked archive into place
-        echo "Install Location: $pkg_src_cmd"
-        New-Item "$pkg_src_bin" -ItemType Directory -Force | out-null
-        Move-Item -Path ".\trippy-*\trippy.exe" -Destination "$pkg_src_bin"
+    # Settle unpacked archive into place
+    Write-Output "Install Location: $pkg_src_cmd"
+    New-Item "$pkg_src_bin" -ItemType Directory -Force | Out-Null
+    Move-Item -Path ".\trippy-*\trip.exe" -Destination "$pkg_src_bin"

    # Exit tmp
-    popd
+    Pop-Location
 }

-echo "Copying into '$pkg_dst_cmd' from '$pkg_src_cmd'"
-Remove-Item -Path "$pkg_dst_cmd" -Recurse -ErrorAction Ignore | out-null
-Copy-Item -Path "$pkg_src" -Destination "$pkg_dst" -Recurse
+Write-Output "Copying into '$pkg_dst_cmd' from '$pkg_src_cmd'"
+Remove-Item -Path "$pkg_dst_cmd" -Recurse -ErrorAction Ignore | Out-Null
+New-Item "$pkg_dst_bin" -ItemType Directory -Force | Out-Null
+Copy-Item -Path "$pkg_src_cmd" -Destination "$pkg_dst_cmd" -Recurse
+
+Write-Output "IMPORTANT"
+Write-Output ""
+Write-Output "    1. Open PowerShell as Administrator"
+Write-Output ""
+Write-Output "       sudo.cmd powershell"
+Write-Output ""
+Write-Output "    2. As Administrator, set a firewall rule to allow ICMP"
+Write-Output ""
+Write-Output "       New-NetFirewallRule -DisplayName ""ICMP Trippy Allow"" -Name ICMP_TRIPPY_ALLOW -Protocol ICMPv4 -Action Allow"
+Write-Output ""
+Write-Output "    3. Run with sudo.cmd (or an Administrator shell)"
+Write-Output ""
+Write-Output "       sudo.cmd trip.exe example.com"
+Write-Output ""
@@ -3,44 +3,44 @@
 # shellcheck disable=SC2034
 # "'pkg_cmd_name' appears unused. Verify it or export it."

-__init_trippy() {
+__init_trip() {
    set -e
    set -u

-    ##################
-    # Install trippy #
-    ##################
+    ################
+    # Install trip #
+    ################

    # Every package should define these 6 variables
-    pkg_cmd_name="trippy"
+    pkg_cmd_name="trip"

-    pkg_dst_cmd="$HOME/.local/bin/trippy"
+    pkg_dst_cmd="$HOME/.local/bin/trip"
    pkg_dst="$pkg_dst_cmd"

-    pkg_src_cmd="$HOME/.local/opt/trippy-v$WEBI_VERSION/bin/trippy"
+    pkg_src_cmd="$HOME/.local/opt/trippy-v$WEBI_VERSION/bin/trip"
    pkg_src_dir="$HOME/.local/opt/trippy-v$WEBI_VERSION"
    pkg_src="$pkg_src_cmd"

    # pkg_install must be defined by every package
    pkg_install() {
-        # ~/.local/opt/trippy-v0.99.9/bin
+        # ~/.local/opt/trippy-v0.8.0/bin
        mkdir -p "$(dirname "${pkg_src_cmd}")"

-        # mv ./trippy-*/trippy ~/.local/opt/trippy-v0.99.9/bin/trippy
-        mv ./trippy-*/* "${pkg_src_cmd}"
+        # mv ./trippy-*/trip ~/.local/opt/trippy-v0.8.0/bin/trip
+        mv ./trippy-*/trip "${pkg_src_cmd}"
    }

    # pkg_get_current_version is recommended, but not required
    pkg_get_current_version() {
-        # 'trippy --version' has output in this format:
-        #       trippy 0.99.9 (rev abcdef0123)
+        # 'trip -V' has output in this format:
+        #       trip 0.8.0
        # This trims it down to just the version number:
-        #       0.99.9
-        trippy --version 2> /dev/null |
+        #       0.8.0
+        trip -V 2> /dev/null |
            head -n 1 |
            cut -d ' ' -f 2
    }

 }

-__init_trippy
+__init_trip