Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

feat(packaging): ship Vector in every Linux artifact

shukieshah2a7cdc4f4bee
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a613b43d..542a6f47 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -519,6 +519,16 @@ jobs:
# build-release-collectors.sh stages, so the before-hook finds it under either script.
mkdir -p dist/beacon-otelcol/windows_amd64
cp dist/beacon-otelcol/linux_amd64/beacon-otelcol dist/beacon-otelcol/windows_amd64/beacon-otelcol.exe
+ # The real Vector build, not a stand-in: the smoke test runs it and checks it is static.
+ # Cached by the script's hash, which is where the version is pinned.
+ - uses: actions/cache@v4
+ id: vector-cache
+ with:
+ path: cli/beacon/release-vector
+ key: release-vector-${{ hashFiles('packaging/linux/fetch-vector.sh') }}
+ - name: Download Vector for the Linux packages
+ if: steps.vector-cache.outputs.cache-hit != 'true'
+ run: sh packaging/linux/fetch-vector.sh
- uses: goreleaser/goreleaser-action@v6
with:
version: latest
@@ -530,6 +540,12 @@ jobs:
env:
BEACON_SMOKE_ARCH: amd64
run: sh packaging/linux/smoke-package.sh
+ # Rocky 9, because RHEL and its rebuilds are where RPM fleets run.
+ - name: Install the .rpm and verify the endpoint
+ env:
+ BEACON_SMOKE_ARCH: amd64
+ BEACON_SMOKE_FORMAT: rpm
+ run: sh packaging/linux/smoke-package.sh
package-smoke:
runs-on: macos-latest
diff --git a/.github/workflows/release-check.yml b/.github/workflows/release-check.yml
index 3d0f08c0..6af747fa 100644
--- a/.github/workflows/release-check.yml
+++ b/.github/workflows/release-check.yml
@@ -11,6 +11,7 @@ on:
- "cli/beacon/.goreleaser.yaml"
- "collector-builder/**"
- "packaging/macos/**"
+ - "packaging/linux/**"
- ".github/workflows/release.yml"
- ".github/workflows/release-check.yml"
@@ -59,6 +60,9 @@ jobs:
END { exit !(beaconjson && falcon_hec) }
'
+ - name: Download Vector for the Linux packages
+ run: sh packaging/linux/fetch-vector.sh
+
- name: Check GoReleaser config
working-directory: cli/beacon
env:
@@ -99,6 +103,18 @@ jobs:
}
'
+ # Vector ships in the Linux archives only, as beacon-vector.
+ has_vector=0
+ if tar -tzf "$archive" | awk '/(^|\/)beacon-vector$/ { found = 1 } END { exit !found }'; then
+ has_vector=1
+ fi
+ case "$archive" in
+ *_linux_*.tar.gz)
+ [ "$has_vector" = 1 ] || { echo "$archive is missing beacon-vector"; exit 1; } ;;
+ *)
+ [ "$has_vector" = 0 ] || { echo "$archive should not carry beacon-vector"; exit 1; } ;;
+ esac
+
case "$archive" in
*linux_amd64.tar.gz)
linux_archive="$archive"
@@ -114,3 +130,4 @@ jobs:
extract_dir="$(mktemp -d)"
tar -xzf "$linux_archive" -C "$extract_dir"
"$extract_dir/beacon" version
+ "$extract_dir/beacon-vector" --version
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index a3ab6a7f..3751b704 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -58,6 +58,11 @@ jobs:
END { exit !(beaconjson && falcon_hec) }
'
+ # The .deb, .rpm, and Linux archives carry Vector. The goreleaser before-hook fails the
+ # release if this did not stage both arches.
+ - name: Download Vector for the Linux packages
+ run: sh packaging/linux/fetch-vector.sh
+
- name: Check GoReleaser config
working-directory: cli/beacon
env:
@@ -215,6 +220,13 @@ jobs:
sh packaging/macos/build-signed-notarized-pkg.sh
done
ls -la dist/macos
+ # build-pkg.sh leaves Vector out when BEACON_VECTOR_BIN is unset, which is right for a
+ # local skeleton build and wrong for a release. awk rather than grep -q, which exits on
+ # the first match and fails the pipeline under pipefail.
+ for pkg in dist/macos/*.pkg; do
+ pkgutil --payload-files "$pkg" | awk '$0 == "./opt/beacon/bin/vector" { found = 1 } END { exit !found }' || {
+ echo "$pkg has no /opt/beacon/bin/vector" >&2; exit 1; }
+ done
- name: Generate update manifest
env:
diff --git a/.gitignore b/.gitignore
index f889419c..648f585a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -57,3 +57,4 @@ collector-builder/dist/
# Staged by the goreleaser before-hook; holds ~100MB of collector binaries.
cli/beacon/release-collectors/
+cli/beacon/release-vector/
diff --git a/CLAUDE.md b/CLAUDE.md
index 9b18b2b0..147786af 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -290,6 +290,15 @@ before running `packaging/macos/build-pkg.sh` or
`/opt/beacon/bin/vector` so packaged Jamf/Fleet forwarder helpers work without a
separate Vector install.
+The Linux `.deb`, `.rpm`, and release archives carry Vector too. Run
+`sh packaging/linux/fetch-vector.sh` before GoReleaser: it downloads the static
+(musl) build for both arches, checks it against Vector's published checksums and
+for a program interpreter, and stages it under `cli/beacon/release-vector/`. The
+GoReleaser before-hook fails without it. The packages install it as
+`/opt/beacon/bin/vector`; the archives carry it as `beacon-vector`, which the
+Homebrew formula installs on Linux. The version is pinned in that script; keep
+it in step with the tap's `beacon-vector` formula.
+
### Preferred CI Release
CI release automation should:
@@ -325,6 +334,14 @@ gh api repos/Asymptote-Labs/homebrew-tap/contents/Formula/beacon.rb --jq '.conte
gh api repos/Asymptote-Labs/homebrew-tap/commits/main --jq '.sha + " " + .commit.message'
```
+Check Homebrew on Linux with a real install, since formula changes only take effect
+once a release publishes them. It should print a Vector version:
+
+```bash
+docker run --rm --platform linux/amd64 homebrew/brew sh -c \
+ 'brew install asymptote-labs/tap/beacon && "$(brew --prefix)/bin/beacon-vector" --version'
+```
+
The release should include the five GoReleaser CLI archives (four `.tar.gz` plus
`beacon_<version>_windows_amd64.zip`), `checksums.txt`, `threat-rules.tar.gz`,
`BeaconEndpointAgent-<version>-arm64.pkg`, its `.sha256`, `update-manifest.json`,
@@ -380,6 +397,7 @@ cp collector-builder/dist/beacon-otelcol/darwin_amd64/beacon-otelcol .tmp/releas
cp collector-builder/dist/beacon-otelcol/darwin_arm64/beacon-otelcol .tmp/release-<tag>/collector-builder/dist/beacon-otelcol/darwin_arm64/beacon-otelcol
cp collector-builder/dist/beacon-otelcol/linux_amd64/beacon-otelcol .tmp/release-<tag>/collector-builder/dist/beacon-otelcol/linux_amd64/beacon-otelcol
cp collector-builder/dist/beacon-otelcol/linux_arm64/beacon-otelcol .tmp/release-<tag>/collector-builder/dist/beacon-otelcol/linux_arm64/beacon-otelcol
+sh packaging/linux/fetch-vector.sh "$PWD/.tmp/release-<tag>/cli/beacon/release-vector"
```
Tag and publish from the clean release checkout. Prefer explicitly exported
diff --git a/cli/beacon/.goreleaser.yaml b/cli/beacon/.goreleaser.yaml
index bc2552f3..7a3275f6 100644
--- a/cli/beacon/.goreleaser.yaml
+++ b/cli/beacon/.goreleaser.yaml
@@ -16,6 +16,9 @@ before:
# .exe because that is the name the target needs, which build-release-collectors.sh already
# stages -- the collector builder itself emits an extensionless PE binary.
- cp ../../collector-builder/dist/beacon-otelcol/windows_amd64/beacon-otelcol.exe ./release-collectors/windows_amd64/beacon-otelcol.exe
+ # Vector for the Linux packages and archives, staged by packaging/linux/fetch-vector.sh. Checked
+ # here so a missing download fails the release instead of shipping packages without Vector.
+ - bash -c 'for a in amd64 arm64; do test -x release-vector/linux_$a/beacon-vector || { echo "release-vector/linux_$a/beacon-vector is missing; run packaging/linux/fetch-vector.sh" >&2; exit 1; }; done'
# Package the external threat-rule pack (repo rules/, not embedded in the binary)
# as a release asset users install with `beacon rules pull <asset-url>`.
- bash -c 'mkdir -p release-rules && COPYFILE_DISABLE=1 tar --exclude="._*" --exclude=".DS_Store" -czf release-rules/threat-rules.tar.gz -C ../.. rules'
@@ -107,6 +110,11 @@ archives:
# collector sitting beside the CLI that was run.
- src: release-collectors/{{ .Os }}_{{ .Arch }}/beacon-otelcol*
strip_parent: true
+ # Linux archives only: release-vector has no darwin or windows directory, so the glob matches
+ # nothing there. Named beacon-vector so that unpacking the archive into a directory on PATH
+ # does not shadow a Vector the user already has. FindVector looks for it beside the CLI.
+ - src: release-vector/{{ .Os }}_{{ .Arch }}/beacon-vector*
+ strip_parent: true
nfpms:
# Native packages are the Linux counterpart of the signed macOS .pkg: installing one should
@@ -137,6 +145,14 @@ nfpms:
dst: /opt/beacon/bin/beacon-otelcol
file_info:
mode: 0755
+ # Vector runs every forwarder Beacon renders (Beacon Managed, S3, GCS, CloudWatch, Sumo Logic,
+ # Rapid7, Falcon). Same path as the macOS package, which is where FindVector looks. It does not
+ # run unless one of those is configured. /opt/beacon/bin is not on PATH, so it cannot shadow
+ # another Vector.
+ - src: release-vector/linux_{{ .Arch }}/beacon-vector
+ dst: /opt/beacon/bin/vector
+ file_info:
+ mode: 0755
- src: ../../packaging/linux/install-endpoint.sh
dst: /opt/beacon/scripts/install-endpoint.sh
file_info:
@@ -237,10 +253,11 @@ brews:
# which Homebrew never links into the prefix -- so it cannot collide on a bin/vector
# symlink either. FindVector looks there first; see internal/endpoint/asymptote.
#
- # os: mac because Beacon only bundles the tap's Vector mirror for macOS.
- # Homebrew-on-Linux installs Beacon with no dependency and uses the vector.dev
- # package, as the docs say. The mirror formula itself still carries Linux URLs
- # so Homebrew's cross-platform tap validation can load it.
+ # os: mac because Linux needs no dependency: the Linux release archive already
+ # carries Vector as beacon-vector, and the install block below puts it beside
+ # beacon, where FindVector looks first. That is the same Vector build the .deb
+ # and .rpm ship. The mirror formula itself still carries Linux URLs so
+ # Homebrew's cross-platform tap validation can load it.
dependencies:
- name: asymptote-labs/tap/beacon-vector
os: mac
@@ -248,15 +265,15 @@ brews:
bin.install "beacon"
bin.install "beacon-hooks"
bin.install "beacon-otelcol"
+ bin.install "beacon-vector" if OS.linux?
caveats: |
To configure local endpoint telemetry, run:
beacon endpoint install
To forward telemetry to the Asymptote dashboard (opt-in, revocable), run:
beacon endpoint connect
- On macOS that needs no extra step: this formula installs its own Vector as
- beacon-vector, kept out of PATH so it never collides with a Vector you
- already have. On Linux, install Vector 0.50 or newer from https://vector.dev.
+ That needs no extra step: this formula installs its own Vector as
+ beacon-vector, so it never collides with a Vector you already have.
test: |
system "#{bin}/beacon", "version"
diff --git a/cli/beacon/goreleaser_brew_test.go b/cli/beacon/goreleaser_brew_test.go
index 33568726..64e2e1f7 100644
--- a/cli/beacon/goreleaser_brew_test.go
+++ b/cli/beacon/goreleaser_brew_test.go
@@ -70,9 +70,9 @@ func TestHomebrewFormulaNeverDependsOnAFormulaNamedVector(t *testing.T) {
// nothing else finds it. Renaming the formula on either side alone leaves `brew install
// beacon` installing a Vector that `beacon endpoint connect` cannot see.
//
-// The dependency is macOS-only because Beacon bundles the tap's Vector mirror only on
-// macOS. Homebrew-on-Linux installs Beacon without a Vector dependency and uses the
-// vector.dev package path documented for Linux instead. The mirror formula itself still
+// The dependency is macOS-only because Linux needs none: the Linux archive the formula
+// installs from already carries Vector as beacon-vector (see
+// TestLinuxReleaseArtifactsCarryVectorWhereFindVectorLooks). The mirror formula itself still
// carries Linux URLs so Homebrew's cross-platform tap validation can load it.
func TestHomebrewFormulaDependsOnTheVectorMirrorFindVectorLooksFor(t *testing.T) {
want := "asymptote-labs/tap/" + asymptote.TapVectorFormula
@@ -87,9 +87,8 @@ func TestHomebrewFormulaDependsOnTheVectorMirrorFindVectorLooksFor(t *testing.T)
}
found = true
if dep.OS != "mac" {
- t.Errorf("brew %q depends on %q with os %q, want %q: Beacon bundles the "+
- "tap's Vector mirror only on macOS; Homebrew-on-Linux installs Beacon "+
- "without a Vector dependency and uses the vector.dev package path instead",
+ t.Errorf("brew %q depends on %q with os %q, want %q: on Linux the release "+
+ "archive already carries Vector, so the dependency would install a second copy",
brew.Name, dep.Name, dep.OS, "mac")
}
}
@@ -102,3 +101,69 @@ func TestHomebrewFormulaDependsOnTheVectorMirrorFindVectorLooksFor(t *testing.T)
}
t.Fatal(`no brews entry named "beacon" in .goreleaser.yaml`)
}
+
+// releaseVectorConfig is the slice of .goreleaser.yaml that puts Vector into Linux artifacts.
+type releaseVectorConfig struct {
+ Archives []struct {
+ // Either a bare glob or a {src, strip_parent, ...} entry.
+ Files []any `yaml:"files"`
+ } `yaml:"archives"`
+ NFPMs []struct {
+ Contents []struct {
+ Src string `yaml:"src"`
+ Dst string `yaml:"dst"`
+ } `yaml:"contents"`
+ } `yaml:"nfpms"`
+ Brews []struct {
+ Name string `yaml:"name"`
+ Install string `yaml:"install"`
+ } `yaml:"brews"`
+}
+
+// TestLinuxReleaseArtifactsCarryVectorWhereFindVectorLooks keeps each Linux artifact's copy of
+// Vector at a path FindVector searches. The .deb and .rpm install it at the packaged path. The
+// archive carries it beside beacon under the archive name, and the Homebrew formula has to
+// install it from there or Homebrew-on-Linux has no Vector at all, since its tap dependency is
+// macOS-only.
+func TestLinuxReleaseArtifactsCarryVectorWhereFindVectorLooks(t *testing.T) {
+ raw, err := os.ReadFile(".goreleaser.yaml")
+ if err != nil {
+ t.Fatal(err)
+ }
+ var config releaseVectorConfig
+ if err := yaml.Unmarshal(raw, &config); err != nil {
+ t.Fatal(err)
+ }
+
+ var packaged bool
+ for _, nfpm := range config.NFPMs {
+ for _, c := range nfpm.Contents {
+ if c.Dst == asymptote.PackagedVectorPath && strings.HasSuffix(c.Src, "/"+asymptote.ArchiveVectorName) {
+ packaged = true
+ }
+ }
+ }
+ if !packaged {
+ t.Errorf("no nfpm content installs Vector at %s", asymptote.PackagedVectorPath)
+ }
+
+ var archived bool
+ for _, archive := range config.Archives {
+ for _, f := range archive.Files {
+ entry, _ := f.(map[string]any)
+ src, _ := entry["src"].(string)
+ if path.Base(strings.TrimSuffix(src, "*")) == asymptote.ArchiveVectorName {
+ archived = true
+ }
+ }
+ }
+ if !archived {
+ t.Errorf("the release archive does not carry %s", asymptote.ArchiveVectorName)
+ }
+
+ for _, brew := range config.Brews {
+ if brew.Name == "beacon" && !strings.Contains(brew.Install, `bin.install "`+asymptote.ArchiveVectorName+`" if OS.linux?`) {
+ t.Errorf("the beacon formula does not install %s on Linux:\n%s", asymptote.ArchiveVectorName, brew.Install)
+ }
+ }
+}
diff --git a/cli/beacon/internal/endpoint/asymptote/vector.go b/cli/beacon/internal/endpoint/asymptote/vector.go
index ca78d656..c94d82bf 100644
--- a/cli/beacon/internal/endpoint/asymptote/vector.go
+++ b/cli/beacon/internal/endpoint/asymptote/vector.go
@@ -19,9 +19,15 @@ const MinVectorVersion = "0.50.0"
// VectorBinEnv names an explicit Vector binary, ahead of every search location.
const VectorBinEnv = "BEACON_VECTOR_BIN"
-// PackagedVectorPath is where the signed macOS package installs Vector.
+// PackagedVectorPath is where the macOS package and the Linux .deb and .rpm install Vector.
const PackagedVectorPath = "/opt/beacon/bin/vector"
+// ArchiveVectorName is what the Linux release archive calls Vector, next to the beacon binary.
+// Homebrew-on-Linux installs it under the same name. Not "vector", because people unpack the
+// archive into a directory on PATH, and a file named vector there would shadow the Vector they
+// already use.
+const ArchiveVectorName = "beacon-vector"
+
// TapVectorFormula is the Homebrew formula the tap mirrors Vector as, and the name of the
// keg `brew install beacon` pulls in on macOS.
//
@@ -40,13 +46,30 @@ type VectorInfo struct {
}
// ErrVectorNotFound is returned when no usable Vector binary exists.
+var ErrVectorNotFound = errors.New(vectorNotFoundMessage(runtime.GOOS))
+
+// vectorNotFoundMessage says where Vector should have come from on this platform.
//
// The Homebrew hint names the tap's own formula rather than a bare "brew install vector":
// Vector is not in homebrew-core, so the bare name is ambiguous once both vectordotdev/brew
-// and asymptote-labs/tap are tapped, and Homebrew refuses an ambiguous name. Any Vector at
-// or above MinVectorVersion satisfies FindVector, whichever tap or package it came from.
-var ErrVectorNotFound = errors.New("vector was not found; install it from https://vector.dev " +
- "(macOS: brew install asymptote-labs/tap/" + TapVectorFormula + ") or set " + VectorBinEnv)
+// and asymptote-labs/tap are tapped, and Homebrew refuses an ambiguous name. On Linux every
+// Beacon artifact ships Vector, so a missing one means Beacon was installed some other way or
+// the file was removed. Any Vector at or above MinVectorVersion satisfies FindVector.
+func vectorNotFoundMessage(goos string) string {
+ switch goos {
+ case "darwin":
+ return "vector was not found; install it with `brew install asymptote-labs/tap/" + TapVectorFormula +
+ "` or from https://vector.dev, or set " + VectorBinEnv
+ case "linux":
+ return "vector was not found; the Beacon .deb and .rpm install it as " + PackagedVectorPath +
+ " and the release archive carries it as " + ArchiveVectorName + " beside beacon. " +
+ "Reinstall Beacon from one of those, install Vector " + MinVectorVersion +
+ " or newer from https://vector.dev, or set " + VectorBinEnv
+ default:
+ return "vector was not found; install Vector " + MinVectorVersion +
+ " or newer from https://vector.dev or set " + VectorBinEnv
+ }
+}
// runCommandOutput is swapped by tests to fake `vector --version`.
var runCommandOutput = func(bin string, args ...string) ([]byte, error) {
@@ -61,9 +84,9 @@ var (
// FindVector locates a Vector binary of at least MinVectorVersion.
//
-// Order: the explicit argument, BEACON_VECTOR_BIN, the packaged /opt/beacon/bin/vector, the
-// beacon-vector keg in each Homebrew prefix, a linked vector in each Homebrew prefix, then
-// PATH. The first candidate that exists is checked for version; a too-old binary is an error
+// Order: the explicit argument, BEACON_VECTOR_BIN, beacon-vector beside the running CLI, the
+// packaged /opt/beacon/bin/vector, the beacon-vector keg in each Homebrew prefix, a linked
+// vector in each Homebrew prefix, then PATH. The first candidate that exists is checked for version; a too-old binary is an error
// rather than a reason to keep searching, because silently running a different Vector than the
// one the operator pointed at would be worse. That is also why the beacon-vector keg is tried
// ahead of any other Homebrew Vector: it is the copy whose version the tap pins, so it cannot
@@ -100,8 +123,19 @@ func FindVector(explicit string) (VectorInfo, error) {
// does not leak into a test that expects none.
var vectorSearchPaths = defaultVectorSearchPaths
+// currentExecutable is swapped by tests.
+var currentExecutable = os.Executable
+
func defaultVectorSearchPaths() []string {
- paths := []string{PackagedVectorPath}
+ var paths []string
+ // Beside the CLI first, which is what an extracted Linux release archive and a
+ // Homebrew-on-Linux install look like. Only under ArchiveVectorName: a plain vector beside
+ // the CLI in a Homebrew bin directory is whatever Vector the user linked there, and it
+ // must not outrank the pinned keg below.
+ if executable, err := currentExecutable(); err == nil {
+ paths = append(paths, filepath.Join(filepath.Dir(executable), ArchiveVectorName))
+ }
+ paths = append(paths, PackagedVectorPath)
prefixes := homebrewPrefixes()
// Every beacon-vector keg first, then every linked vector. Interleaving the two per
// prefix would let an old linked Vector in the first prefix mask the pinned keg in the
diff --git a/cli/beacon/internal/endpoint/asymptote/vector_test.go b/cli/beacon/internal/endpoint/asymptote/vector_test.go
index 119aad50..57ecdb8d 100644
--- a/cli/beacon/internal/endpoint/asymptote/vector_test.go
+++ b/cli/beacon/internal/endpoint/asymptote/vector_test.go
@@ -127,10 +127,19 @@ func TestEnrollmentStoreUsesPrivatePermissionsAndAtomicWrites(t *testing.T) {
// than a reason to keep looking.
func TestDefaultVectorSearchPathsPrefersTheBeaconVectorKeg(t *testing.T) {
t.Setenv("HOMEBREW_PREFIX", filepath.Join("/fake", "brew"))
+ cliDir := t.TempDir()
+ oldExe := currentExecutable
+ currentExecutable = func() (string, error) { return filepath.Join(cliDir, "beacon"), nil }
+ t.Cleanup(func() { currentExecutable = oldExe })
paths := defaultVectorSearchPaths()
- if len(paths) == 0 || paths[0] != PackagedVectorPath {
- t.Fatalf("defaultVectorSearchPaths() = %q, want the packaged Vector first", paths)
+ if len(paths) < 2 || paths[0] != filepath.Join(cliDir, ArchiveVectorName) || paths[1] != PackagedVectorPath {
+ t.Fatalf("defaultVectorSearchPaths() = %q, want %s beside the CLI, then the packaged Vector",
+ paths, ArchiveVectorName)
+ }
+ if slices.Contains(paths, filepath.Join(cliDir, "vector")) {
+ t.Fatalf("defaultVectorSearchPaths() = %q: a plain vector beside a Homebrew beacon is the "+
+ "user's own, and must not outrank the pinned keg", paths)
}
keg := filepath.Join("/fake", "brew", "opt", TapVectorFormula, "libexec", "vector")
if !slices.Contains(paths, keg) {
@@ -175,3 +184,43 @@ func TestHomebrewPrefixesDeduplicates(t *testing.T) {
t.Errorf("homebrewPrefixes() = %q, want the same %d prefixes as the unset default %q", got, len(prefixes), prefixes)
}
}
+
+// An extracted Linux release archive, or Homebrew-on-Linux, puts Vector beside beacon as
+// beacon-vector. FindVector has to find it there without PATH or BEACON_VECTOR_BIN, or
+// forwarding from a tarball install asks the user to install a Vector they already have.
+func TestFindVectorFindsTheArchiveCopyBesideTheCLI(t *testing.T) {
+ isolateVectorDiscovery(t)
+ vectorSearchPaths = defaultVectorSearchPaths
+ cliDir := t.TempDir()
+ sibling := filepath.Join(cliDir, ArchiveVectorName)
+ if err := os.Rename(fakeVector(t, "0.58.0", 0), sibling); err != nil {
+ t.Fatal(err)
+ }
+ oldExe := currentExecutable
+ currentExecutable = func() (string, error) { return filepath.Join(cliDir, "beacon"), nil }
+ t.Cleanup(func() { currentExecutable = oldExe })
+
+ got, err := FindVector("")
+ if err != nil || got.Path != sibling || got.Version != "0.58.0" {
+ t.Fatalf("FindVector() = %+v, %v; want %s", got, err, sibling)
+ }
+}
+
+func TestVectorNotFoundMessageNamesWhereVectorComesFrom(t *testing.T) {
+ cases := map[string][]string{
+ "darwin": {"brew install asymptote-labs/tap/" + TapVectorFormula, VectorBinEnv},
+ "linux": {PackagedVectorPath, ArchiveVectorName, "https://vector.dev", VectorBinEnv},
+ "windows": {"https://vector.dev", VectorBinEnv},
+ }
+ for goos, want := range cases {
+ msg := vectorNotFoundMessage(goos)
+ for _, part := range want {
+ if !strings.Contains(msg, part) {
+ t.Errorf("%s: %q does not mention %q", goos, msg, part)
+ }
+ }
+ }
+ if strings.Contains(vectorNotFoundMessage("linux"), "brew install") {
+ t.Error("the Linux message should not send people to a macOS install command")
+ }
+}
diff --git a/docs/cli/endpoint-connect.mdx b/docs/cli/endpoint-connect.mdx
index 3f92d64f..d06c4bb9 100644
--- a/docs/cli/endpoint-connect.mdx
+++ b/docs/cli/endpoint-connect.mdx
@@ -23,7 +23,7 @@ beacon endpoint disconnect [flags]
- Beacon endpoint installed (`beacon endpoint install`) and writing local JSONL.
- A current `beacon login` session with `device:enroll` scope for user mode.
-- Vector 0.50 or newer on the machine (Apple Silicon gets 0.58 from Homebrew or the package; Intel Macs get 0.50.0, the last x86_64 build Vector published). The signed macOS package installs it at `/opt/beacon/bin/vector`; on macOS Homebrew installs it with Beacon, as the tap's `beacon-vector` keg (named that rather than `vector` so it coexists with a Vector from `vectordotdev/brew`, and kept in `libexec` so it stays off your PATH); on Linux install the `vector` package from [vector.dev](https://vector.dev). `connect` stops before opening a browser if no usable Vector is found or if Vector rejects the forwarder config.
+- Vector 0.50 or newer on the machine (Apple Silicon gets 0.58 from Homebrew or the package; Intel Macs get 0.50.0, the last x86_64 build Vector published). The signed macOS package installs it at `/opt/beacon/bin/vector`; on macOS Homebrew installs it with Beacon, as the tap's `beacon-vector` keg (named that rather than `vector` so it coexists with a Vector from `vectordotdev/brew`, and kept in `libexec` so it stays off your PATH); on Linux the `.deb` and `.rpm` install it at `/opt/beacon/bin/vector`, the release archive carries it as `beacon-vector` next to `beacon`, and Homebrew on Linux installs that same `beacon-vector`. `connect` stops before opening a browser if no usable Vector is found or if Vector rejects the forwarder config.
- System mode only: a browser where an organization member can approve the device.
## What connect does
diff --git a/docs/log-forwarding/index.mdx b/docs/log-forwarding/index.mdx
index 2a7c9fad..5fa1ce24 100644
--- a/docs/log-forwarding/index.mdx
+++ b/docs/log-forwarding/index.mdx
@@ -293,7 +293,7 @@ beacon endpoint gcs install-pack --system --output ./beacon-gcs-pack
The generated `vector.toml` files use the selected Beacon log path, parse each JSONL line into the original Beacon event, and send JSON with destination-appropriate framing. Vector owns checkpointing in its `data_dir`, batching, retries, destination URLs, CloudWatch log streams, S3 and GCS object keys, and destination-specific headers or settings such as `X-Sumo-Category`, `X-Sumo-Fields`, `x-sumo-token`, `Content-Type: application/x-ndjson`, `BEACON_FALCON_HEC_ENDPOINT`, `BEACON_CLOUDWATCH_LOG_GROUP`, `BEACON_CLOUDWATCH_LOG_STREAM_PREFIX`, `BEACON_S3_BUCKET`, `BEACON_S3_PREFIX`, `AWS_REGION`, `BEACON_GCS_BUCKET`, and `BEACON_GCS_PREFIX`.
-For managed endpoint deployments, install Vector through your normal endpoint tooling, copy the generated config into Vector's config directory, and provide `SUMO_URL`, optional `SUMO_TOKEN`, `RAPID7_WEBHOOK_URL`, `BEACON_FALCON_HEC_ENDPOINT`, `BEACON_FALCON_HEC_TOKEN`, `BEACON_CLOUDWATCH_LOG_GROUP`, optional `BEACON_CLOUDWATCH_LOG_STREAM_PREFIX`, `BEACON_S3_BUCKET`, optional `BEACON_S3_PREFIX`, `AWS_REGION`, `BEACON_GCS_BUCKET`, optional `BEACON_GCS_PREFIX`, and destination credentials through the Vector service environment, host identity, or your MDM/secret tooling.
+Beacon's macOS package and Linux `.deb` and `.rpm` already install Vector at `/opt/beacon/bin/vector`, and the Linux release archive carries it as `beacon-vector`. Otherwise, for managed endpoint deployments, install Vector through your normal endpoint tooling. Then copy the generated config into Vector's config directory, and provide `SUMO_URL`, optional `SUMO_TOKEN`, `RAPID7_WEBHOOK_URL`, `BEACON_FALCON_HEC_ENDPOINT`, `BEACON_FALCON_HEC_TOKEN`, `BEACON_CLOUDWATCH_LOG_GROUP`, optional `BEACON_CLOUDWATCH_LOG_STREAM_PREFIX`, `BEACON_S3_BUCKET`, optional `BEACON_S3_PREFIX`, `AWS_REGION`, `BEACON_GCS_BUCKET`, optional `BEACON_GCS_PREFIX`, and destination credentials through the Vector service environment, host identity, or your MDM/secret tooling.
### Customer-managed forwarding
diff --git a/docs/platforms/linux.mdx b/docs/platforms/linux.mdx
index 71093b84..448539d4 100644
--- a/docs/platforms/linux.mdx
+++ b/docs/platforms/linux.mdx
@@ -46,7 +46,7 @@ curl -fsSLO "${BASE}/checksums.txt"
grep " ${ARCHIVE}$" checksums.txt | sha256sum --check -
tar -xzf "${ARCHIVE}"
-mkdir -p ~/.local/bin && mv beacon beacon-hooks beacon-otelcol ~/.local/bin/
+mkdir -p ~/.local/bin && mv beacon beacon-hooks beacon-otelcol beacon-vector ~/.local/bin/
# ~/.local/bin is already on PATH on most distributions; if `beacon version` fails, add it:
# echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && exec $SHELL
@@ -56,7 +56,7 @@ beacon endpoint install
The version comes from the current release rather than a number you have to keep up to date, and the architecture comes from `uname -m`: `x86_64` maps to the published `amd64` archive and `aarch64` to `arm64`. An architecture Beacon does not publish stops the run before anything is downloaded.
-The archive contains three binaries: the `beacon` CLI, the `beacon-hooks` adapter that captures tool activity, and the `beacon-otelcol` collector. All three are needed, and all three are statically linked with no shared-library dependencies.
+The archive contains four binaries: the `beacon` CLI, the `beacon-hooks` adapter that captures tool activity, the `beacon-otelcol` collector, and `beacon-vector`, which is [Vector](https://vector.dev) for forwarding (see [Forwarding](#forwarding)). The first three are needed. `beacon-vector` only runs if you set up a destination that uses it, and it is named that so it cannot shadow a `vector` you already have on PATH. All four are statically linked with no shared-library dependencies.
See [User-mode install](#user-mode-install) for what this sets up and its one caveat.
@@ -145,11 +145,25 @@ beacon token-usage # token and cost rollups
See the [event schema](/telemetry-schema/event-schema) for the full field reference.
+## Forwarding
+
+A new install is local-only. Nothing leaves the machine until you set up a destination, and each one reads the same local log.
+
+| Destination | What ships the events |
+|---|---|
+| [Splunk](/log-forwarding/splunk) | The collector, over HEC |
+| [Elastic](/log-forwarding/elastic), [Datadog](/log-forwarding/datadog), [Wazuh](/log-forwarding/wazuh) | That product's own agent, tailing the log |
+| [Microsoft Sentinel](/log-forwarding/microsoft-sentinel) | Azure Monitor Agent, tailing the log |
+| [S3](/log-forwarding#aws-s3), [GCS](/log-forwarding#google-cloud-storage), [CloudWatch](/log-forwarding/cloudwatch), [Sumo Logic](/log-forwarding/sumo), [Rapid7](/log-forwarding/rapid7), [CrowdStrike Falcon](/log-forwarding/falcon) | Vector |
+| [Beacon Managed](/log-forwarding/asymptote) | Vector, set up by `beacon endpoint connect` |
+
+Vector comes with Beacon. The `.deb` and `.rpm` install it at `/opt/beacon/bin/vector`, and the tarball carries it as `beacon-vector`. Neither is on PATH by default, and neither runs until a destination needs it. `beacon endpoint connect` finds it on its own. For the other Vector destinations, run the generated `vector.toml` with `/opt/beacon/bin/vector`, or with your own Vector 0.50 or newer.
+
## What the install does
| Step | Result |
|---|---|
-| Unpack | `beacon`, `beacon-hooks` and `beacon-otelcol` under `/opt/beacon/bin` |
+| Unpack | `beacon`, `beacon-hooks`, `beacon-otelcol` and `vector` under `/opt/beacon/bin` |
| System install | Config and collector config under `/etc/beacon/endpoint` |
| Service | `/etc/systemd/system/beacon-collector.service`, enabled and started |
| Runtime log | `/var/log/beacon-agent/runtime.jsonl` |
diff --git a/packaging/linux/fetch-vector.sh b/packaging/linux/fetch-vector.sh
new file mode 100755
index 00000000..da9b00c0
--- /dev/null
+++ b/packaging/linux/fetch-vector.sh
@@ -0,0 +1,85 @@
+#!/bin/sh
+# Downloads the Vector build that Beacon's Linux packages and archives ship, checks it, and stages
+# it where goreleaser picks it up.
+#
+# packaging/linux/fetch-vector.sh [out-dir] [arch...]
+#
+# out-dir defaults to cli/beacon/release-vector and arch to "amd64 arm64". Each binary lands at
+# <out-dir>/linux_<arch>/beacon-vector. The .deb and .rpm install it as /opt/beacon/bin/vector;
+# the release archive keeps the beacon-vector name so unpacking it into a directory on PATH never
+# shadows a Vector the user already has.
+#
+# The musl build, not the gnu one. The gnu build links glibc dynamically, and every Linux binary
+# Beacon ships is static so it runs on stripped and custom-built hosts without caring which libc
+# they carry. The script fails unless the binary has no program interpreter.
+#
+# Set VECTOR_VERSION to change the version. Keep it in step with the tap's beacon-vector formula.
+set -eu
+
+VECTOR_VERSION="${VECTOR_VERSION:-0.58.0}"
+ROOT_DIR="$(CDPATH='' cd -- "$(dirname -- "$0")/../.." && pwd)"
+OUT_DIR="${1:-$ROOT_DIR/cli/beacon/release-vector}"
+[ "$#" -gt 0 ] && shift
+ARCHES="${*:-amd64 arm64}"
+BASE_URL="https://packages.timber.io/vector/${VECTOR_VERSION}"
+
+for tool in curl tar; do
+ command -v "$tool" >/dev/null 2>&1 || { echo "fetch-vector: $tool is required" >&2; exit 1; }
+done
+command -v readelf >/dev/null 2>&1 || command -v file >/dev/null 2>&1 || {
+ echo "fetch-vector: readelf or file is required to check the binary is static" >&2; exit 1; }
+if command -v sha256sum >/dev/null 2>&1; then
+ sha256_check() { sha256sum -c -; }
+else
+ sha256_check() { shasum -a 256 -c -; }
+fi
+
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT INT TERM
+sums="vector-${VECTOR_VERSION}-SHA256SUMS"
+curl -fsSL --retry 3 -o "$work/$sums" "$BASE_URL/$sums"
+
+for arch in $ARCHES; do
+ case "$arch" in
+ amd64) triple=x86_64-unknown-linux-musl ;;
+ arm64) triple=aarch64-unknown-linux-musl ;;
+ *) echo "fetch-vector: unsupported arch $arch" >&2; exit 1 ;;
+ esac
+ archive="vector-${VECTOR_VERSION}-${triple}.tar.gz"
+ curl -fsSL --retry 3 -o "$work/$archive" "$BASE_URL/$archive"
+ line="$(awk -v a="$archive" '$2 == a { print }' "$work/$sums")"
+ [ -n "$line" ] || { echo "fetch-vector: no checksum for $archive in $sums" >&2; exit 1; }
+ (cd "$work" && printf '%s\n' "$line" | sha256_check)
+
+ mkdir -p "$work/$arch"
+ tar -xzf "$work/$archive" -C "$work/$arch"
+ bin="$(find "$work/$arch" -path '*/bin/vector' -type f | head -n 1)"
+ [ -n "$bin" ] || { echo "fetch-vector: no bin/vector in $archive" >&2; exit 1; }
+
+ # A dynamic binary has an INTERP program header and a static one does not. The headers must be
+ # read successfully and include a LOAD segment first, or a file readelf cannot parse would pass.
+ # Without readelf (macOS), file(1) has to say static outright; anything else fails.
+ if command -v readelf >/dev/null 2>&1; then
+ headers="$(readelf -lW "$bin")" || { echo "fetch-vector: readelf could not read $bin" >&2; exit 1; }
+ case "$headers" in
+ *LOAD*) ;;
+ *) echo "fetch-vector: no program headers in $bin" >&2; exit 1 ;;
+ esac
+ case "$headers" in
+ *INTERP*)
+ echo "fetch-vector: $archive is dynamically linked; Beacon ships only static Linux binaries" >&2
+ exit 1 ;;
+ esac
+ else
+ kind="$(file -b "$bin")"
+ case "$kind" in
+ ELF*"static-pie linked"*|ELF*"statically linked"*) ;;
+ *) echo "fetch-vector: $archive is not a static ELF binary: $kind" >&2; exit 1 ;;
+ esac
+ fi
+
+ mkdir -p "$OUT_DIR/linux_$arch"
+ cp "$bin" "$OUT_DIR/linux_$arch/beacon-vector"
+ chmod 755 "$OUT_DIR/linux_$arch/beacon-vector"
+ echo "staged $OUT_DIR/linux_$arch/beacon-vector (Vector $VECTOR_VERSION, $triple, static)"
+done
diff --git a/packaging/linux/smoke-package.sh b/packaging/linux/smoke-package.sh
index e0e9812d..87470e4a 100755
--- a/packaging/linux/smoke-package.sh
+++ b/packaging/linux/smoke-package.sh
@@ -42,14 +42,17 @@ cleanup() { docker rm -f "$CONTAINER" >/dev/null 2>&1 || true; }
trap cleanup EXIT INT TERM
cleanup
+# binutils is for readelf, which checks the packaged Vector is static. Rocky rather than Fedora for
+# the rpm lane because RHEL and Rocky are what RPM fleets actually run; its image already has
+# curl-minimal, which conflicts with the curl package.
case "$FORMAT" in
deb) IMAGE=beacon-package-smoke-deb
- BASE=ubuntu:24.04
- INSTALL_PKGS="systemd systemd-sysv dbus curl ca-certificates iproute2"
+ BASE="${BEACON_SMOKE_BASE:-ubuntu:24.04}"
+ INSTALL_PKGS="systemd systemd-sysv dbus curl ca-certificates iproute2 binutils"
PKGMGR_INSTALL="apt-get install -y -qq /var/tmp/beacon.deb" ;;
rpm) IMAGE=beacon-package-smoke-rpm
- BASE=fedora:40
- INSTALL_PKGS="systemd dbus curl ca-certificates iproute"
+ BASE="${BEACON_SMOKE_BASE:-rockylinux/rockylinux:9}"
+ INSTALL_PKGS="systemd dbus ca-certificates iproute binutils"
PKGMGR_INSTALL="dnf install -y -q /var/tmp/beacon.rpm" ;;
*) echo "unsupported format $FORMAT" >&2; exit 1 ;;
esac
@@ -184,6 +187,26 @@ docker exec "$CONTAINER" su - "$SMOKE_USER" -c 'beacon --version' >/dev/null 2>&
echo "beacon resolves on PATH but does not execute" >&2; exit 1; }
echo "ok: beacon is reachable by name, as the documentation says it is"
+# Vector ships in the package for the forwarders Beacon renders, at the path FindVector looks.
+# It must run, and be static like every other Linux binary Beacon ships, or a stripped host with a
+# different libc gets a Vector that cannot start. The headers must be read and include a LOAD
+# segment before the missing INTERP counts, so a file readelf cannot parse does not pass.
+docker exec "$CONTAINER" test -x /opt/beacon/bin/vector || {
+ echo "/opt/beacon/bin/vector is missing, so no forwarder can run" >&2; exit 1; }
+vector_version="$(docker exec "$CONTAINER" /opt/beacon/bin/vector --version 2>&1)" || {
+ echo "/opt/beacon/bin/vector does not run: $vector_version" >&2; exit 1; }
+headers="$(docker exec "$CONTAINER" readelf -lW /opt/beacon/bin/vector 2>&1)" || {
+ echo "could not read /opt/beacon/bin/vector's program headers: $headers" >&2; exit 1; }
+case "$headers" in *LOAD*) ;; *) echo "no program headers in /opt/beacon/bin/vector" >&2; exit 1 ;; esac
+case "$headers" in *INTERP*) echo "/opt/beacon/bin/vector is dynamically linked" >&2; exit 1 ;; esac
+# /opt/beacon/bin is not on PATH, and the package must not put a vector there: it would shadow one
+# the user already runs.
+if docker exec "$CONTAINER" sh -c 'command -v vector' >/dev/null 2>&1; then
+ echo "the package put a vector on PATH: $(docker exec "$CONTAINER" sh -c 'command -v vector')" >&2
+ exit 1
+fi
+echo "ok: packaged Vector runs, is static, and stays off PATH ($vector_version)"
+
# The two commands the docs tell a new user to run. Both must report healthy with no manual setup.
if ! docker exec "$CONTAINER" /opt/beacon/bin/beacon endpoint status --system --json >/tmp/beacon-status.json 2>&1; then
echo "endpoint status failed:" >&2; cat /tmp/beacon-status.json >&2; exit 1
@@ -260,7 +283,22 @@ if ! docker exec "$CONTAINER" test -f /etc/beacon/endpoint/config.json; then
echo "removal deleted the config; only a purge should do that" >&2
exit 1
fi
-echo "ok: removal kept config and logs (purge removes them)"
+if docker exec "$CONTAINER" test -e /opt/beacon/bin/vector; then
+ echo "removal left /opt/beacon/bin/vector behind" >&2; exit 1
+fi
+echo "ok: removal took the binaries and kept config and logs"
+
+# rpm has no purge, so this half is deb only. It is what makes "only a purge deletes it" true.
+if [ "$FORMAT" = deb ]; then
+ docker exec "$CONTAINER" apt-get purge -y -qq beacon >/dev/null 2>&1 || {
+ echo "apt-get purge failed" >&2; exit 1; }
+ for d in /etc/beacon/endpoint /var/log/beacon-agent; do
+ if docker exec "$CONTAINER" test -e "$d"; then
+ echo "purge left $d behind" >&2; exit 1
+ fi
+ done
+ echo "ok: purge removed config and logs"
+fi
echo
echo "package smoke test passed ($FORMAT/$ARCH)"