diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 47 |
1 files changed, 43 insertions, 4 deletions
@@ -69,20 +69,57 @@ list of what's deliberately not implemented (and why), see ## Install / build -Requires Go 1.26.5+ (see `go.mod`). +Requires Go 1.26.5+ (see `go.mod`). No other dependencies - the SQLite +driver ([modernc.org/sqlite](https://pkg.go.dev/modernc.org/sqlite)) is +pure Go, so there's no C toolchain to install and nothing to link +against, on any platform. ```sh git clone <this repo> cd mitmux +make build # -> bin/mitmuxd, bin/mitmux +``` + +`make build` covers the common case; see the [`Makefile`](Makefile) +itself for the rest - `make install` (via `go install`, respecting +`GOBIN`/`GOPATH` as usual), `make release` (cross-compiles both +binaries for every platform in `PLATFORMS` into `dist/`), `make test` +(the same build/vet/gofmt/test checks expected before every commit - +see `PLAN.md`). Building without `make` works identically: + +```sh go build -o bin/mitmuxd ./cmd/mitmuxd go build -o bin/mitmux ./cmd/mitmux ``` +### Platforms + +Linux is the primary target and the only one this has actually run on +during development - every feature in this document was verified live +against a real daemon and real traffic there. macOS, Windows, and +FreeBSD all cross-compile cleanly with `CGO_ENABLED=0` and pass `go +vet` (`make release` builds all of them), and the code itself has +nothing Linux-specific in it - CA/history storage uses Go's own +cross-platform `os.UserConfigDir()`, not a hardcoded XDG path - but +they haven't been run on real hardware, so treat them as "should work, +not yet verified" rather than a tested claim. If you try one and hit +something, that's useful to know about. + +One concrete thing worth knowing on macOS specifically: its Unix +domain socket path limit is shorter than Linux's, and the default +control-socket location lives under `~/Library/Application +Support/mitmux/` - a deeper path than Linux's usual +`$XDG_RUNTIME_DIR`. A long username or home directory path could push +past the limit; if `mitmuxd` fails to bind its control socket, pass a +shorter `-socket /tmp/mitmux.sock` (and the matching `-socket` to +`mitmux`) to both binaries. + ## Quick start 1. **Start the daemon.** By default it listens on `127.0.0.1:8080` and - stores its CA and history database under `~/.config/mitmux` (XDG - config dir): + stores its CA and history database under your OS's standard config + directory (Linux: `~/.config/mitmux`, macOS: `~/Library/Application + Support/mitmux`, Windows: `%AppData%\mitmux`): ```sh ./bin/mitmuxd @@ -124,7 +161,9 @@ go build -o bin/mitmux ./cmd/mitmux Both binaries take flags for non-default setups - `-listen`, `-socket`, `-ca-dir`, `-db`, `-upstream-proxy` on `mitmuxd`; `-socket` on `mitmux`. -Run either with `-h` for the full list. +Both also take `-version` (prints version/commit/date and exits - `dev` +for a plain `go build`; `make build`/`make release` fill it in from +`git describe`) and `-h` for the full list. `-listen` takes a comma-separated list to bind more than one address (`-listen "127.0.0.1:8080,127.0.0.1:8081"`) - one logical proxy on |