# Culvert documentation

> Start with the [README](https://github.com/hyperi-io/culvert/blob/v2.1.30/README.md) for what culvert is and the
> five-minute `docker run`. This directory is everything past that.

Docs are grouped by what you are trying to do, not by feature.

## Connect a client

- [vpn-client-setup.md](/v/2.2.2/culvert/vpn-client-setup.md) - installing and connecting on
  macOS, Linux, Windows, iOS and Android, for both protocols and for the
  HTTPS-tunnelled variants. This one also ships inside the image at
  `/etc/vpn/docs/`, so it is available on the server itself.

## Deploy a shape

Each of these is a full walkthrough - deploy, issue a client, operate it -
for one of the opinionated `CULVERT_PROFILE=` presets.

- [use-case-home.md](/v/2.2.2/culvert/use-case-home.md) - home LAN or a lab VM. OpenVPN UDP,
  split tunnel, local PKI.
- [use-case-corporate.md](/v/2.2.2/culvert/use-case-corporate.md) - per-user certificates plus
  OIDC SSO, group gating, TCP fallback, offboarding.
- [use-case-travel.md](/v/2.2.2/culvert/use-case-travel.md) - the VPN over HTTPS, for networks
  that only pass web traffic. Includes what that does and does not defeat.
- [use-case-kubernetes.md](/v/2.2.2/culvert/use-case-kubernetes.md) - the published Helm chart,
  one replica: install values, the PKI volume, external PKI, probes, metrics.
- [use-case-edge-fleet.md](/v/2.2.2/culvert/use-case-edge-fleet.md) - an appliance fleet into a
  central receiver, with reverse admin back down the tunnels.

## Understand a decision

- [architecture.md](/v/2.2.2/culvert/architecture.md) - what is in the image, the startup order,
  the two iptables chains and why their order is what it is, and the PKI
  invariants. Start here before changing any of them.
- [addressing.md](/v/2.2.2/culvert/addressing.md) - why the tunnels default to `10.8.0.0/22`,
  and when to move to the CGNAT range instead.
- [performance.md](/v/2.2.2/culvert/performance.md) - the cipher stance (AES-256-GCM the
  compliance default, ChaCha20 offered), what the tuning profiles change, and
  the host-side throughput levers (DCO, sysctl).

## Look something up

- [supply-chain.md](https://github.com/hyperi-io/culvert/blob/v2.1.30/docs/supply-chain.md) - where every third-party binary comes
  from, what the build verifies, and what it does not.
- [ci-environment.md](https://github.com/hyperi-io/culvert/blob/v2.1.30/docs/ci-environment.md) - the secrets and variables CI needs.
- [scalo-reference.md](https://github.com/hyperi-io/culvert/blob/v2.1.30/docs/scalo-reference.md) - the scalo calls culvert actually
  makes. The [scalo repo](https://github.com/hyperi-io/scalo-py) is the API
  source of truth.

## Conventions

Filenames are lowercase-kebab because slugs are case-sensitive and static-site
generators lowercase them. Each doc covers one reader mode - follow a path, or
look a fact up - and says which at the top.