77 lines
4.4 KiB
Markdown
77 lines
4.4 KiB
Markdown
# Agent Guide
|
|
|
|
This repository builds and deploys OpenBSD VPN servers on Google Cloud. The goal is to make it easy to create multiple VPN VMs in two flavors:
|
|
|
|
- WireGuard, matching the existing historical deployment in `server/`.
|
|
- IPsec, using OpenBSD `iked`/`ipsecctl`.
|
|
|
|
Keep this repository focused on VPN server definitions, provisioning glue, firewall rules, and run commands. The local `skz-opack/` directory is an ignored dependency that provides the OpenBSD image/build/deploy Makefile interface. Read it when you need to understand `OPACK_*` variables or targets, but do not modify it unless the user explicitly asks for dependency work.
|
|
|
|
## Repository Shape
|
|
|
|
- `server/` is the current WireGuard deployment. It includes the OpenBSD install disklabel, provisioning script, GCP firewall overlay, and Makefile using `../skz-opack/src/opack.mk`.
|
|
- `src/` is early IPsec/iked work and should stay separate from WireGuard-specific provisioning.
|
|
- Future VPN servers should live in separate directories or separate Makefiles. Do not merge WireGuard and IPsec into one opaque shared Makefile until real duplication justifies it.
|
|
- Each server definition should declare its own `OPACK_TARGET`, hostname, GCP project/key settings, provision script, firewall rules, client list, and generated-state ignore patterns.
|
|
|
|
## Tools And Installation
|
|
|
|
Before build or deployment work, verify the required host tools:
|
|
|
|
```sh
|
|
for x in make jq python3 rg curl git ssh scp nc vagrant packer terraform gcloud qemu-system-x86_64; do command -v "$x" || echo "missing: $x"; done
|
|
```
|
|
|
|
In sloptrap/Codex containers, install missing third-party tools under `/sloptrap-tools` and expose executables through `/sloptrap-tools/bin`, which is already on `PATH`. Do not install toolchains into this repo, `$HOME`, or one-off directories.
|
|
|
|
Use `/sloptrap-tools` for SDKs, plugins, and caches when configurable. For example, a Google Cloud SDK install may live under `/sloptrap-tools/google-cloud-sdk` with `/sloptrap-tools/bin/gcloud` symlinked to the real executable. Keep Packer plugin caches and similar generated tool state under `/sloptrap-tools` when possible.
|
|
|
|
## Secrets And Live State
|
|
|
|
`server/` may contain ignored live credentials and generated deployment state:
|
|
|
|
- `id_ed25519`
|
|
- `skz-void-bbb88f038188.json`
|
|
- `opack-cloud`
|
|
- `opack_deploy_*`
|
|
- `opack_installer_*`
|
|
|
|
Never commit, print, copy into tracked files, rotate, delete, or regenerate these files unless the user explicitly asks. Treat them as live operational material.
|
|
|
|
Agents may SSH for read-only diagnostics when useful, using the ignored key and current deployed IP:
|
|
|
|
```sh
|
|
ssh -i server/id_ed25519 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null root@$(cat server/opack-cloud) 'uname -a; sysctl kern.version'
|
|
```
|
|
|
|
Do not change services, firewall rules, VPN keys, GCP resources, package state, or deployed configuration on the live VM without explicit user approval.
|
|
|
|
## Workflows
|
|
|
|
For existing WireGuard deployment work, the main entrypoint is:
|
|
|
|
```sh
|
|
make -C server void
|
|
```
|
|
|
|
This is not a harmless check. It may build an OpenBSD image, run Terraform, apply firewall rules, copy the external `skz-wg` tree to the live VM, and run remote provisioning. Use it only when the user wants deployment or provisioning work.
|
|
|
|
For read-only live inspection, prefer direct SSH commands and report exactly what was inspected. Avoid broad commands that dump secrets or large config files.
|
|
|
|
For future IPsec work, use OpenBSD-native `iked`/`ipsecctl` conventions. Keep IPsec provisioning, firewall rules, client/certificate generation, and run targets separate from WireGuard. Make IPsec firewall allowances explicit instead of reusing the WireGuard UDP rule.
|
|
|
|
For future multi-server work, prefer adding a new isolated server directory or Makefile that includes `../skz-opack/src/opack.mk` and overrides `OPACK_*` values before the include. Keep generated files ignored next to the server that creates them.
|
|
|
|
## Validation
|
|
|
|
For documentation-only changes, validate with:
|
|
|
|
```sh
|
|
sed -n '1,240p' AGENTS.md
|
|
git diff -- AGENTS.md
|
|
```
|
|
|
|
Do not run deployment targets as documentation validation.
|
|
|
|
For Makefile/provisioning changes, use the narrowest non-destructive validation first, such as reading expanded Make variables, shell syntax checks, or targeted dry-run inspection. Treat `make ... opack-cloud`, `make -C server void`, Terraform apply/destroy, and remote provisioning commands as live infrastructure changes.
|