feat(kernel): expand stock image, boot policy, and ecosystem integration
- Stock kernel: boot.policy v2 (maxExecLineDepth, denyEnvKeys, requireProcNodes);
richer BARE_OS_KERNEL_SELFTEST; example policy and timer drop-in samples
- Protocol: feature bits 28–30, seed RPCs (manifest_hints, peer_health, staging_slot)
- Booter: /proc mirrors, provenance, metrics_live, pear IPC registry, initd DAG,
suspend/resume wiring, exec budget, shell ${var} expansion, delegate limits,
telemetry v3 / OTel JSONL, ctx API 1.11.0
- Coreutils: /bin/timeout; seeder Pear/Bare: avoid bare process.env (globalThis.process?.env)
- CI: verify-ctx-api-feature-bits; docs: handbook, developer-guide, kernel-extensions,
capabilities index, environment appendix, READMEs
This commit is contained in:
Raven Scott
@@ -13,6 +13,7 @@ This directory holds the split **file-by-file inventory** that used to live in t
|
||||
| §13 | [Architecture: end-to-end data flow](architecture-data-flow.md) |
|
||||
| §14, §14a | [Environment variables and POSIX appendix](environment-and-posix-appendix.md) |
|
||||
| *(kernel feature bits & handshake)* | [Kernel extensions](kernel-extensions.md) |
|
||||
| *(bits → env → proc → ctx)* | [Kernel capabilities index](kernel-capabilities-index.md) |
|
||||
| *(roadmap)* | [Feature roadmap status](feature-roadmap.md) |
|
||||
| §§15–16 | [Out of scope and tooling](out-of-scope-and-tooling.md) |
|
||||
| *(HTTP clients)* | [curl and wget (delegation, fetch stack, policy)](http-curl-and-wget.md) |
|
||||
|
||||
@@ -18,7 +18,7 @@ Former **DOCUMENTATION.md** §14, §14a. [Reference index →](README.md)
|
||||
| `MANWIDTH` | `/bin/man` | Wrap width for manual text (default `72`; minimum `40`) |
|
||||
| `NO_COLOR` | `/bin/man` | If set, disable ANSI bold for section headings on a TTY |
|
||||
|
||||
**Host → session passthrough** (booter copies into **`shellEnv`** when the host sets a non-empty value): `BARE_OS_PIPELINE_MAX_STAGES`, `BARE_OS_PIPELINE_MAX_BYTES`, `BARE_OS_PIPELINE_MAX_LINES`, `BARE_OS_SHELL_STREAMING`, `BARE_OS_SHELL_STREAMING_MULT`, `BARE_OS_SHELL_CMDSUBST`, `BARE_OS_SHELL_CMDSUBST_MAX_BYTES`, `BARE_OS_BOOT_PROFILE`, `BARE_OS_ONBOOT`, `BARE_OS_BOOT_STRICT`, `BARE_OS_RC_D_SKIP`, `BARE_OS_BOOT_MINIMAL`, `BARE_OS_BOOT_SKIP`, `BARE_OS_BOOT_TRACE`, `BARE_OS_KERNEL_SELFTEST`, `BARE_OS_SELFTEST_FORMAT`, `BARE_OS_AUDIT`, `BARE_OS_AUDIT_JSON`, `BARE_OS_AUDIT_REDACT`, `BARE_OS_IMAGE_DIGEST`, `BARE_OS_EXEC_MAX_DEPTH`, `BARE_OS_IPC_MAX_BYTES`, `BARE_OS_IPC_CHANNEL_MAX_BYTES`, `BARE_OS_IPC_RPC_TOKEN`, `BARE_OS_IPC_FANOUT`, `BARE_OS_IPC_JSON_MAX_BYTES`, `BARE_OS_IPC_NAMESPACE`, `BARE_OS_VFS_WATCH`, `BARE_OS_VFS_UNION_PREFIXES`, `BARE_OS_VFS_UNION_WRITE_DENY`, `BARE_OS_VFS_BIN_CACHE`, `BARE_OS_BOOT_ALLOWLIST`, `BARE_OS_BOOT_MANIFEST`, `BARE_OS_BOOT_MANIFEST_SIGN`, `BARE_OS_BOOT_MANIFEST_PUBKEY_HEX`, `BARE_OS_BOOT_POLICY`, `BARE_OS_BOOT_POLICY_STRICT`, `BARE_OS_LAZY_PERSONAL_DRIVE`, `BARE_OS_SYSTEM_REVISION_ID`, `BARE_OS_SYSTEM_REVISION_PENDING`, `BARE_OS_SYSTEM_SLOT`, `BARE_OS_DELEGATE_ALLOW`, `BARE_OS_DNS_ALLOWLIST`, `BARE_OS_KERNEL_HOT_RELOAD`, `BARE_OS_SANDBOX_SCRIPT`, `BARE_OS_SANDBOX_WORKER`, `BARE_OS_INITD_MAX_PARALLEL`, `BARE_OS_INITD_JOURNAL_MAX_LINES`, `BARE_OS_URANDOM_CRYPTO`, `BARE_OS_TELEMETRY_NDJSON`, `BARE_OS_SEED_RPC_HANDSHAKE`, `BARE_OS_SEED_CAP_STRICT`, `BARE_OS_SEED_CAP_FAIL`, `BARE_OS_HTTP_ALLOWLIST`, `BARE_OS_HTTP_DENYLIST`, `BARE_OS_TLS_PIN_SHA256`, `BARE_OS_BARE_MODULES`, `BARE_OS_BARE_DRIVE_BUNDLES`, `BARE_OS_PEAR_CHANNEL`, `BARE_OS_PEAR_RELEASE`, `PEAR_CHANNEL`, `BARE_OS_FIND_EXEC_MAX`, `BARE_OS_YES_MAX_LINES`, `BARE_OS_SHUF_MAX_LINES`, `BARE_OS_SPLIT_MAX_FILES`, `BARE_OS_NPROC`, `BARE_OS_BLIND_BOOTSTRAP_URL`, `BARE_OS_BLIND_BOOTSTRAP_JSON`, `BARE_OS_MIRROR_READ_KEY`, **`TERM`**, **`COLORTERM`**.
|
||||
**Host → session passthrough** (booter copies into **`shellEnv`** when the host sets a non-empty value): `BARE_OS_PIPELINE_MAX_STAGES`, `BARE_OS_PIPELINE_MAX_BYTES`, `BARE_OS_PIPELINE_MAX_LINES`, `BARE_OS_SHELL_STREAMING`, `BARE_OS_SHELL_STREAMING_MULT`, `BARE_OS_SHELL_CMDSUBST`, `BARE_OS_SHELL_CMDSUBST_MAX_BYTES`, `BARE_OS_SHELL_PARAM_EXPANSION`, `BARE_OS_BOOT_PROFILE`, `BARE_OS_ONBOOT`, `BARE_OS_BOOT_STRICT`, `BARE_OS_RC_D_SKIP`, `BARE_OS_BOOT_MINIMAL`, `BARE_OS_BOOT_SKIP`, `BARE_OS_BOOT_TRACE`, `BARE_OS_KERNEL_SELFTEST`, `BARE_OS_SELFTEST_FORMAT`, `BARE_OS_AUDIT`, `BARE_OS_AUDIT_JSON`, `BARE_OS_AUDIT_REDACT`, `BARE_OS_IMAGE_DIGEST`, `BARE_OS_EXEC_MAX_DEPTH`, `BARE_OS_EXEC_LINE_BUDGET_MS`, `BARE_OS_IPC_MAX_BYTES`, `BARE_OS_IPC_CHANNEL_MAX_BYTES`, `BARE_OS_IPC_RPC_TOKEN`, `BARE_OS_IPC_FANOUT`, `BARE_OS_IPC_JSON_MAX_BYTES`, `BARE_OS_IPC_NAMESPACE`, `BARE_OS_VFS_WATCH`, `BARE_OS_VFS_UNION_PREFIXES`, `BARE_OS_VFS_UNION_WRITE_DENY`, `BARE_OS_VFS_BIN_CACHE`, `BARE_OS_BOOT_ALLOWLIST`, `BARE_OS_BOOT_MANIFEST`, `BARE_OS_BOOT_MANIFEST_SIGN`, `BARE_OS_BOOT_MANIFEST_PUBKEY_HEX`, `BARE_OS_BOOT_POLICY`, `BARE_OS_BOOT_POLICY_STRICT`, `BARE_OS_LAZY_PERSONAL_DRIVE`, `BARE_OS_SYSTEM_REVISION_ID`, `BARE_OS_SYSTEM_REVISION_PENDING`, `BARE_OS_SYSTEM_SLOT`, `BARE_OS_DELEGATE_ALLOW`, `BARE_OS_DELEGATE_MAX_PER_MIN`, `BARE_OS_DELEGATE_GIT_MAX_PER_MIN`, `BARE_OS_DELEGATE_CURL_MAX_PER_MIN`, `BARE_OS_DELEGATE_WGET_MAX_PER_MIN`, `BARE_OS_DELEGATE_SYSTEMCTL_MAX_PER_MIN`, `BARE_OS_DELEGATE_AUDIT_ONLY`, `BARE_OS_DNS_ALLOWLIST`, `BARE_OS_KERNEL_HOT_RELOAD`, `BARE_OS_SANDBOX_SCRIPT`, `BARE_OS_SANDBOX_WORKER`, `BARE_OS_INITD_MAX_PARALLEL`, `BARE_OS_INITD_JOURNAL_MAX_LINES`, `BARE_OS_URANDOM_CRYPTO`, `BARE_OS_TELEMETRY_NDJSON`, `BARE_OS_TELEMETRY_OTEL_JSONL`, `BARE_OS_PROC_POLL_MS`, `BARE_OS_SEED_RPC_HANDSHAKE`, `BARE_OS_SEED_CAP_STRICT`, `BARE_OS_SEED_CAP_FAIL`, `BARE_OS_HTTP_ALLOWLIST`, `BARE_OS_HTTP_DENYLIST`, `BARE_OS_TLS_PIN_SHA256`, `BARE_OS_BARE_MODULES`, `BARE_OS_BARE_DRIVE_BUNDLES`, `BARE_OS_PEAR_CHANNEL`, `BARE_OS_PEAR_RELEASE`, `PEAR_CHANNEL`, `BARE_OS_FIND_EXEC_MAX`, `BARE_OS_YES_MAX_LINES`, `BARE_OS_SHUF_MAX_LINES`, `BARE_OS_SPLIT_MAX_FILES`, `BARE_OS_NPROC`, `BARE_OS_BLIND_BOOTSTRAP_URL`, `BARE_OS_BLIND_BOOTSTRAP_JSON`, `BARE_OS_MIRROR_READ_KEY`, **`TERM`**, **`COLORTERM`**.
|
||||
|
||||
| Variable | Used by | Meaning |
|
||||
| -------- | ------- | ------- |
|
||||
@@ -29,7 +29,7 @@ Former **DOCUMENTATION.md** §14, §14a. [Reference index →](README.md)
|
||||
| `BARE_OS_BOOT_MANIFEST` | Stock kernel | Enable digest check of **`/etc/bare-os/boot.manifest.json`**. |
|
||||
| `BARE_OS_BOOT_MANIFEST_SIGN` | Stock kernel + booter | When **`1`**, require valid Ed25519 signature file **`/etc/bare-os/boot.manifest.sig`** (see **`BARE_OS_BOOT_MANIFEST_PUBKEY_HEX`**). |
|
||||
| `BARE_OS_BOOT_MANIFEST_PUBKEY_HEX` | Booter / kernel | 64 hex chars — public key for signed boot manifest verification. |
|
||||
| `BARE_OS_BOOT_POLICY` | Stock kernel | When **`1`** / **`true`**, merge **`skipPhases`** / **`denyBootPhases`** from **`/etc/bare-os/boot.policy.json`**; optional **`minKernelFeatureMask`** / **`requireSeedCaps`** vs **`ctx.bareOsAdvertisedKernelBits`** / **`ctx.bareOsSeedCapabilityBits`** (see **`kernel/etc/bare-os/boot.policy.example.json`**). |
|
||||
| `BARE_OS_BOOT_POLICY` | Stock kernel | When **`1`** / **`true`**, merge **`skipPhases`** / **`denyBootPhases`** from **`/etc/bare-os/boot.policy.json`**; optional **`minKernelFeatureMask`** / **`requireSeedCaps`**; v2 optional **`maxExecLineDepth`**, **`denyEnvKeys`**, **`requireProcNodes`** (see **`kernel/etc/bare-os/boot.policy.example.json`**). |
|
||||
| `BARE_OS_BOOT_POLICY_STRICT` | Stock kernel | When **`1`**, abort boot if **`minKernelFeatureMask`** or **`requireSeedCaps`** checks fail. |
|
||||
| `BARE_OS_LAZY_PERSONAL_DRIVE` | Booter | When **`1`**, defer mounting the personal Hyperdrive until session setup (after kernel bytes are loaded). |
|
||||
| `BARE_OS_SYSTEM_REVISION_ID` / `BARE_OS_SYSTEM_REVISION_PENDING` / `BARE_OS_SYSTEM_SLOT` | Booter | Pear-style hints exposed as **`ctx.bareOsSystemRevision`**. |
|
||||
@@ -41,7 +41,14 @@ Former **DOCUMENTATION.md** §14, §14a. [Reference index →](README.md)
|
||||
| `BARE_OS_SANDBOX_WORKER` | Booter | When **`1`**, defers **`bareOsSandboxRunScript`** on a **fresh microtask** (async boundary); **not** a separate thread or isolate. |
|
||||
| `BARE_OS_INITD_MAX_PARALLEL` | bare-initd | Max concurrent unit **starts** per DAG level (integer ≥ **1**; default **1**). |
|
||||
| `BARE_OS_INITD_JOURNAL_MAX_LINES` | bare-initd / unit journals | Cap lines retained per unit NDJSON journal under **`/run/bare-os/unit-journal/`**. |
|
||||
| `BARE_OS_TELEMETRY_NDJSON` | Booter | Absolute or **`~/…`** path in the **guest VFS**: append capped NDJSON telemetry records (**`{ telemetrySchemaVersion: 2, ts, … }`**) mirroring structured boot/kernel events. |
|
||||
| `BARE_OS_TELEMETRY_NDJSON` | Booter | Absolute or **`~/…`** path in the **guest VFS**: append capped NDJSON telemetry records (**`telemetrySchemaVersion` / `lifecycleSchemaVersion`: 3**, **`ts`**, …) mirroring structured boot/kernel events. |
|
||||
| `BARE_OS_TELEMETRY_OTEL_JSONL` | Booter / var-log | Guest VFS path for OTLP-inspired JSON lines (var-log mirrors). |
|
||||
| `BARE_OS_PROC_POLL_MS` | VFS | Coalescing interval for **`/proc/bare_os/metrics_live.json`** (250–60000). |
|
||||
| `BARE_OS_SHELL_PARAM_EXPANSION` | Shell | When **`1`**, enable **`${VAR:-word}`** and **`${VAR#prefix}`** in **`expandWord`**. |
|
||||
| `BARE_OS_EXEC_LINE_BUDGET_MS` | Booter | Reject top-level **`execLine`** when cumulative wall time exceeds budget. |
|
||||
| `BARE_OS_DELEGATE_MAX_PER_MIN` | Host delegates | Global per-minute cap (sliding window) on delegate invocations. |
|
||||
| `BARE_OS_DELEGATE_*_MAX_PER_MIN` | Host delegates | Per-kind override (**`GIT`**, **`CURL`**, **`WGET`**, **`SYSTEMCTL`**). |
|
||||
| `BARE_OS_DELEGATE_AUDIT_ONLY` | Host delegates | With **`BARE_OS_AUDIT`**, log delegate calls and skip execution (**exit 0**). |
|
||||
| `BARE_OS_SEED_RPC_HANDSHAKE` | Booter | Set **`0`** / **`false`** to skip the pre-MBR **`bare_os.capabilities`** RPC against the first peer. |
|
||||
| `BARE_OS_SEED_CAP_STRICT` | Booter | When **`1`** / **`true`**, require seeder feature **`bits`** to cover **`BARE_OS_KERNEL_FEATURES_STOCK_V1`** or throw. |
|
||||
| `BARE_OS_SEED_CAP_FAIL` | Booter | When **`1`** / **`true`**, rethrow after a failed handshake instead of recording the error and continuing. |
|
||||
@@ -75,9 +82,9 @@ Former **DOCUMENTATION.md** §14, §14a. [Reference index →](README.md)
|
||||
| Area | Status |
|
||||
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **VFS** | Two-drive unified paths; **`$HOME`** maps to the personal Hyperdrive; writable mounts under **`/mnt`** when HDMS allows. **`mkdir`/`rmdir`**, **`chmod`** (octal + symbolic subset), **`symlink`/`readlink`**, **`stat`/`lstat`**, **`rm`** recursive, **`watch()`** on Hyperdrive paths (optional host **`BARE_OS_VFS_WATCH=0`** to disable). Synthetic **`/proc`**, **`/sys`**, **`/run`**, **`/dev`** for introspection (quotas JSON, boot JSON, initd snapshot, union policy, seed handshake, virtual registry, etc.). Optional union read overlays (**`BARE_OS_VFS_UNION_PREFIXES`**) with optional write deny (**`BARE_OS_VFS_UNION_WRITE_DENY`**). Empty dirs use **`.bareos_empty`** (same idea as `git-fs-adapter`). |
|
||||
| **Shell** | Pipelines, **`;`**, **`&&`** / **`||`**, redirects, quoting, **`$VAR`**, **`$?`**, **`jobs`** / **`fg`** / **`wait`**, optional background **`&`** segments, builtins including bounded **`if`**, **`while`**, **`for`**, **`case`** (caps **`BARE_OS_SHELL_LOOP_MAX`**, **`BARE_OS_SHELL_CASE_MAX_BRANCHES`**). Optional bounded **`$(…)`** when **`BARE_OS_SHELL_CMDSUBST=1`**; optional larger pipeline capture via **`BARE_OS_SHELL_STREAMING`** / **`BARE_OS_SHELL_STREAMING_MULT`**. Branching uses **`ctx.exitCode`**. Bounded pipeline capture (**`BARE_OS_PIPELINE_*`**, **`ctx.bareOsRuntimeCaps`**); optional boot-snippet allowlist (**`BARE_OS_BOOT_ALLOWLIST`** + **`/etc/bare-os/boot.allow`**). No subshells or full POSIX **`sh`**. |
|
||||
| **Shell** | Pipelines, **`;`**, **`&&`** / **`||`**, redirects, quoting, **`$VAR`**, **`$?`**, optional **`${VAR:-word}`** / **`${VAR#prefix}`** when **`BARE_OS_SHELL_PARAM_EXPANSION=1`**, **`jobs`** / **`fg`** / **`wait`**, optional background **`&`** segments, builtins including bounded **`if`**, **`while`**, **`for`**, **`case`** (caps **`BARE_OS_SHELL_LOOP_MAX`**, **`BARE_OS_SHELL_CASE_MAX_BRANCHES`**). Optional bounded **`$(…)`** when **`BARE_OS_SHELL_CMDSUBST=1`**; optional larger pipeline capture via **`BARE_OS_SHELL_STREAMING`** / **`BARE_OS_SHELL_STREAMING_MULT`**. Branching uses **`ctx.exitCode`**. Bounded pipeline capture (**`BARE_OS_PIPELINE_*`**, **`ctx.bareOsRuntimeCaps`**); optional boot-snippet allowlist (**`BARE_OS_BOOT_ALLOWLIST`** + **`/etc/bare-os/boot.allow`**). No subshells or full POSIX **`sh`**. |
|
||||
| **Ownership** | Display and permission checks use **`UID`/`GID`** and mode bits; **`chown`/`chgrp`** update **`metadata.bareOs`** on the **personal** writable tree (not a multi-user host kernel). |
|
||||
| **Utilities** | Tier-1 JS **`/bin`** (**~112** commands; see [§12.10](package-bare-os-coreutils-and-ci.md#1210-package-bare-os-coreutils)): text tools include **`paste`**, **`split`**, **`tac`**, **`rev`**, **`expand`**, **`unexpand`**, **`fold`**, **`fmt`**, **`comm`**, **`cmp`**, **`join`**, **`pr`**, **`yes`** (line-capped via **`BARE_OS_YES_MAX_LINES`** / **`getconf`**), **`shuf`** (capped via **`BARE_OS_SHUF_MAX_LINES`**), **`tsort`**, **`factor`**, **`expr`** (integer-focused subset), **`numfmt`** (**`--to=iec`** / **`--to=si`**). Checksums: **`md5sum`** (bundled MD5), **`sha1sum`**, **`sha256sum`**, **`sha512sum`** (Web Crypto where available), **`sum`**, **`base32`**, **`basenc`** (**`--base16`**). Files: **`truncate`**, **`unlink`**, **`install`**, **`df`** (synthetic Hyperdrive row; **`-h`** human sizes), **`sync`** (no-op). Session stubs: **`arch`**, **`groups`**, **`hostid`**, **`nproc`**, **`uptime`**, **`users`**, **`who`**. Plus earlier parity: **`man`**, **`sed`** (including **`-z`**, **`BARE_OS_SED_NULL_MAX_RECORDS`**), **`awk`**, **`grep`** (**`-r`** with **`--include`/`--exclude`/`--exclude-dir`**, **`BARE_OS_GREP_FILTER_MAX`**), **`cp`** (**`-u`/`-v`/`-p`**), **`mv`**, **`find`** (**`-regex`**, **`-exec`/`-ok`**, **`BARE_OS_FIND_EXEC_MAX`**), **`mktemp`**, **`git-pear`**, **`cksum`**, **`getconf`** (includes pipeline / cap names + **`-a`**), **`xargs`**, **`dircolors`**, **`theme`**, **`ls`**, **`uniq`**, **`realpath`**, **`base64`**, **`rm`** **`-d`**, **`stat`** **`%F`**. **`dir`** / **`vdir`** call **`ls`**. Large **`sed`/`awk`** are not byte-identical to GNU on all inputs. **`mkfifo`** → **`/run/bare-os/ipc/`**. Online help: **`/share/man/man.json`** and **`man`**. |
|
||||
| **Utilities** | Tier-1 JS **`/bin`** (**~113** commands; see [§12.10](package-bare-os-coreutils-and-ci.md#1210-package-bare-os-coreutils)): text tools include **`paste`**, **`split`**, **`tac`**, **`rev`**, **`expand`**, **`unexpand`**, **`fold`**, **`fmt`**, **`comm`**, **`cmp`**, **`join`**, **`pr`**, **`yes`** (line-capped via **`BARE_OS_YES_MAX_LINES`** / **`getconf`**), **`shuf`** (capped via **`BARE_OS_SHUF_MAX_LINES`**), **`tsort`**, **`factor`**, **`expr`** (integer-focused subset), **`numfmt`** (**`--to=iec`** / **`--to=si`**). Checksums: **`md5sum`** (bundled MD5), **`sha1sum`**, **`sha256sum`**, **`sha512sum`** (Web Crypto where available), **`sum`**, **`base32`**, **`basenc`** (**`--base16`**). Files: **`truncate`**, **`unlink`**, **`install`**, **`df`** (synthetic Hyperdrive row; **`-h`** human sizes), **`sync`** (no-op), **`timeout`** (wall-clock cap; exit **124** on timeout when **`BARE_OS_FEATURE_ABORT_TIMEOUT`** is advertised). Session stubs: **`arch`**, **`groups`**, **`hostid`**, **`nproc`**, **`uptime`**, **`users`**, **`who`**. Plus earlier parity: **`man`**, **`sed`** (including **`-z`**, **`BARE_OS_SED_NULL_MAX_RECORDS`**), **`awk`**, **`grep`** (**`-r`** with **`--include`/`--exclude`/`--exclude-dir`**, **`BARE_OS_GREP_FILTER_MAX`**), **`cp`** (**`-u`/`-v`/`-p`**), **`mv`**, **`find`** (**`-regex`**, **`-exec`/`-ok`**, **`BARE_OS_FIND_EXEC_MAX`**), **`mktemp`**, **`git-pear`**, **`cksum`**, **`getconf`** (includes pipeline / cap names + **`-a`**), **`xargs`**, **`dircolors`**, **`theme`**, **`ls`**, **`uniq`**, **`realpath`**, **`base64`**, **`rm`** **`-d`**, **`stat`** **`%F`**. **`dir`** / **`vdir`** call **`ls`**. Large **`sed`/`awk`** are not byte-identical to GNU on all inputs. **`mkfifo`** → **`/run/bare-os/ipc/`**. Online help: **`/share/man/man.json`** and **`man`**. |
|
||||
|
||||
**Handbook:** [handbook/09-posix-utilities-shell-and-vfs.md](../../handbook/09-posix-utilities-shell-and-vfs.md) — narrative catalog, engine notes, and Issue 7 alignment. **Manual pages:** [handbook/10-manpages-and-online-help.md](../../handbook/10-manpages-and-online-help.md).
|
||||
|
||||
|
||||
@@ -28,7 +28,7 @@ Order for a simple command name:
|
||||
3. **`*.js` in `$PWD`** — before **`PATH`**.
|
||||
4. **`PATH`** on the **system** drive only — normal **`/bin`** utilities.
|
||||
|
||||
**`BARE_OS_DELEGATE_ALLOW`** (host → session passthrough) may restrict which delegate **kinds** run. When set to a comma- or whitespace-separated list (**`git`**, **`curl`**, **`wget`**, **`systemctl`**), only those kinds are allowed; a denied delegate logs a message and exits with **126**. When unset or empty, all registered delegates are allowed. Optional audit logging for delegate invocations is described in the security guide.
|
||||
**`BARE_OS_DELEGATE_ALLOW`** (host → session passthrough) may restrict which delegate **kinds** run. When set to a comma- or whitespace-separated list (**`git`**, **`curl`**, **`wget`**, **`systemctl`**), only those kinds are allowed; a denied delegate logs a message and exits with **126**. When unset or empty, all registered delegates are allowed. Optional **per-minute** rate limits use **`BARE_OS_DELEGATE_MAX_PER_MIN`** and per-kind **`BARE_OS_DELEGATE_*_MAX_PER_MIN`**. With **`BARE_OS_AUDIT=1`**, **`BARE_OS_DELEGATE_AUDIT_ONLY=1`** logs invocations and skips the host run (**exit 0**). Optional audit logging for delegate invocations is described in the security guide.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
# Kernel capabilities index (bits, env, `/proc`, `ctx`)
|
||||
|
||||
Single map from optional **feature bits** ([`packages/bare-os-protocol/lib/kernel-feature-bits.js`](../../packages/bare-os-protocol/lib/kernel-feature-bits.js)) to operator env vars, guest **`/proc`** paths, and **`ctx`** fields. Stock booter advertises `BARE_OS_KERNEL_FEATURES_STOCK_V1`. Governance: [`developer-guide/adr/001-kernel-feature-bits-governance.md`](../../developer-guide/adr/001-kernel-feature-bits-governance.md).
|
||||
|
||||
| Bit (export) | Env / behavior | `/proc` or RPC | `ctx` / notes |
|
||||
|--------------|----------------|----------------|---------------|
|
||||
| 0 `IPC_FANOUT` | `BARE_OS_IPC_FANOUT` | `/run/bare-os/ipc/` | `bareOsIpc` |
|
||||
| 1 `ABORT_TIMEOUT` | — | — | `execLine` / `readLine` opts |
|
||||
| 2 `HTTP_POLICY` | `BARE_OS_HTTP_*` | — | `httpFetch` |
|
||||
| 3 `VIRTUAL_FILES` | — | `/run/bare-os/virtual/` | `bareOsRegisterVirtualFile` |
|
||||
| 4 `HOST_STATS` | — | host bridge | `bareOsHostStats` |
|
||||
| 5 `CRYPTO_URANDOM` | `BARE_OS_URANDOM_CRYPTO=0` disables | `/dev/urandom` | — |
|
||||
| 6 `SANDBOX_SCRIPT` | `BARE_OS_SANDBOX_SCRIPT=0` | — | `bareOsSandboxRunScript` |
|
||||
| 7 `BOOT_PHASE_HOOKS` | — | — | `bareOsRegisterBootPhaseHook` |
|
||||
| 8 `IPC_DUPLEX` | — | — | `bareOsIpc.createDuplexBridge` |
|
||||
| 9 `VFS_UNION` | `BARE_OS_VFS_UNION_PREFIXES` | `/proc/bare_os_union` | — |
|
||||
| 10 `PROC_SWARM` | — | `/proc/bare_os_swarm` | — |
|
||||
| 11 `SHELL_STREAMING_PIPES` | `BARE_OS_SHELL_STREAMING` | `/proc/bare_os_quotas` | — |
|
||||
| 12 `SHELL_CMDSUBST` | `BARE_OS_SHELL_CMDSUBST` | — | — |
|
||||
| 13 `SEED_CAP_RPC` | `BARE_OS_SEED_RPC_HANDSHAKE` | `/proc/bare_os_seed_handshake` | `bareOsSeedCapabilityBits` |
|
||||
| 14 `EXTENDED_PROC` | — | `/proc/self/fd`, `/sys/devices` | — |
|
||||
| 15 `VIRTUAL_FILE_META` | — | `/proc/bare_os_virtual_registry` | virtual `mime` / `ttlMs` |
|
||||
| 16 `VFS_UNION_WRITE_POLICY` | `BARE_OS_VFS_UNION_WRITE_DENY` | `/proc/bare_os_union` | — |
|
||||
| 17 `IPC_PER_CHANNEL` | `BARE_OS_IPC_CHANNEL_MAX_BYTES` | — | `bareOsIpc.stats` |
|
||||
| 18 `SANDBOX_WORKER` | `BARE_OS_SANDBOX_WORKER` | — | microtask defer |
|
||||
| 19 `TELEMETRY_EXPORT` | `BARE_OS_TELEMETRY_NDJSON` | — | NDJSON v3 schema |
|
||||
| 20 `BOOT_POLICY` | `BARE_OS_BOOT_POLICY` | — | `kernel/init.js` |
|
||||
| 21 `SEED_REPLICATION_STATUS_RPC` | — | `/proc/bare_os_replication` | seed RPC |
|
||||
| 22 `LAZY_PERSONAL_DRIVE` | `BARE_OS_LAZY_PERSONAL_DRIVE` | — | — |
|
||||
| 23 `SYSTEM_REVISION_HOOKS` | `BARE_OS_SYSTEM_REVISION_*` | `/proc/bare_os/provenance` | `bareOsSystemRevision` |
|
||||
| 24 `BARE_MANIFEST_TIERS` | `BARE_OS_BUNDLE_TIER` | — | `ctx.bare` build |
|
||||
| 25 `HOST_DELEGATE_REGISTRY` | `BARE_OS_DELEGATE_*` | audit log | git/curl/wget/systemctl |
|
||||
| 26 `IPC_SESSION_NAMESPACE` | `BARE_OS_IPC_NAMESPACE` | — | FIFO key prefix |
|
||||
| 27 `PROC_BARE_OS_DIR` | — | `/proc/bare_os/index.json` | stable aliases |
|
||||
| 28 `SEED_MANIFEST_HINTS_RPC` | — | `/proc/bare_os/manifest_hints`, replication JSON | RPC `bare_os.manifest_hints` |
|
||||
| 29 `LIFECYCLE_TELEMETRY_V3` | telemetry NDJSON | — | `lifecycleSchemaVersion: 3` |
|
||||
| 30 `BOOT_POLICY_V2` | extended `boot.policy.json` | — | `maxExecLineDepth`, `denyEnvKeys`, `requireProcNodes` |
|
||||
|
||||
**Related `ctx` (1.11.0+):** `bareOsReadProcMetricsLive()` — parsed coalesced metrics (same as `/proc/bare_os/metrics_live.json`); Pear IPC channel names in [`bare-os-pear-ipc-registry.js`](../../packages/bare-os-booter/lib/bare-os-pear-ipc-registry.js).
|
||||
|
||||
**Handbook:** [handbook/09-posix-utilities-shell-and-vfs.md](../../handbook/09-posix-utilities-shell-and-vfs.md), [handbook/04-the-booter-runtime.md](../../handbook/04-the-booter-runtime.md).
|
||||
|
||||
**Extended reference:** [kernel-extensions.md](./kernel-extensions.md), [environment-and-posix-appendix.md](./environment-and-posix-appendix.md).
|
||||
@@ -2,15 +2,17 @@
|
||||
|
||||
This document complements the [handbook](../../handbook/09-posix-utilities-shell-and-vfs.md) with a single map of optional **booter + stock kernel** features added for richer POSIX-like behavior, protocol alignment, and operations.
|
||||
|
||||
## Governance (feature bits v2)
|
||||
## Governance (feature bits doc v3)
|
||||
|
||||
New capability bits are governed by [ADR 001 — Kernel feature bit governance](../../developer-guide/adr/001-kernel-feature-bits-governance.md). **`BARE_OS_KERNEL_FEATURE_BITS_DOC`** must bump when semantics change. Prefer bits **21–30** only (avoid `1 << 31` in JS without `>>> 0` discipline).
|
||||
New capability bits are governed by [ADR 001 — Kernel feature bit governance](../../developer-guide/adr/001-kernel-feature-bits-governance.md). **`BARE_OS_KERNEL_FEATURE_BITS_DOC`** must bump when semantics change. Bits **28–30** are assigned (see ADR); avoid `1 << 31` in JS without `>>> 0` discipline.
|
||||
|
||||
**Capability index:** [kernel-capabilities-index.md](./kernel-capabilities-index.md) (bits → env → `/proc` → `ctx`).
|
||||
|
||||
## Capability bitmask
|
||||
|
||||
Runtime bits are defined in `bare-os-protocol` (`kernel-feature-bits.js`) and surfaced under `/proc/bare_os_features` and the **`/proc/bare_os/`** tree. The stock booter advertises `BARE_OS_KERNEL_FEATURES_STOCK_V1`.
|
||||
|
||||
Seed RPC **`bare_os.capabilities`** includes **`protocolPackageVersion`**, **`featureBitsDoc`**, **`doc`**, **`bits`**, **`role`**, **`protocol`**. **`bare_os.replication_status`** returns seeder-side replication hints (manifest path count, local RAM block count).
|
||||
Seed RPC **`bare_os.capabilities`** includes **`protocolPackageVersion`**, **`featureBitsDoc`**, **`doc`**, **`bits`**, **`role`**, **`protocol`**. **`bare_os.replication_status`** returns seeder-side replication hints (manifest path count, local RAM block count). **`bare_os.manifest_hints`** returns a sample of manifest paths; **`bare_os.peer_health`** returns seeder health counters; **`bare_os.staging_slot`** returns optional A/B slot hints (seeder env `BARE_OS_SEED_STAGING_SLOT`, `BARE_OS_SEED_STAGING_PENDING`). Booter mirrors hints under **`/proc/bare_os/manifest_hints`**, **`peer_health`**, **`staging_slot`** and embeds them in **`/proc/bare_os_replication`** JSON.
|
||||
|
||||
## Environment quick reference
|
||||
|
||||
@@ -24,8 +26,14 @@ Seed RPC **`bare_os.capabilities`** includes **`protocolPackageVersion`**, **`fe
|
||||
| Union writes | `BARE_OS_VFS_UNION_WRITE_DENY` | Comma/colon list of path prefixes blocked for writes under union prefixes |
|
||||
| IPC | `BARE_OS_IPC_CHANNEL_MAX_BYTES` | JSON map `{"fifoName": 65536}` per-channel backlog cap |
|
||||
| Initd journal | `BARE_OS_INITD_JOURNAL_MAX_LINES` | Cap NDJSON lines per unit (default 400, max 20000) |
|
||||
| Telemetry | `BARE_OS_TELEMETRY_NDJSON` | Logical path; append NDJSON mirror of `appendVarLog` events |
|
||||
| Boot policy | `BARE_OS_BOOT_POLICY=1` | Merge `skipPhases` / `denyBootPhases` from `/etc/bare-os/boot.policy.json`; optional `minKernelFeatureMask` / `requireSeedCaps` |
|
||||
| Telemetry | `BARE_OS_TELEMETRY_NDJSON` | Logical path; append NDJSON mirror of `appendVarLog` events (`telemetrySchemaVersion` / `lifecycleSchemaVersion` **3**) |
|
||||
| Telemetry OTel | `BARE_OS_TELEMETRY_OTEL_JSONL` | Logical path; append OTLP-inspired JSON lines for var-log mirrors |
|
||||
| Proc poll | `BARE_OS_PROC_POLL_MS` | Min interval 250ms, max 60s, for coalesced **`/proc/bare_os/metrics_live.json`** |
|
||||
| Shell `${…}` | `BARE_OS_SHELL_PARAM_EXPANSION=1` | Enable `${VAR:-default}` and `${VAR#prefix}` (bounded prefix length) |
|
||||
| Exec budget | `BARE_OS_EXEC_LINE_BUDGET_MS` | Reject top-level `execLine` when session wall time exceeds budget |
|
||||
| Delegates | `BARE_OS_DELEGATE_MAX_PER_MIN`, `BARE_OS_DELEGATE_CURL_MAX_PER_MIN`, … | Per-minute caps on host delegates (sliding minute window) |
|
||||
| Delegates | `BARE_OS_DELEGATE_AUDIT_ONLY=1` | With `BARE_OS_AUDIT=1`, log delegate invocations and skip host run (exit 0) |
|
||||
| Boot policy | `BARE_OS_BOOT_POLICY=1` | Merge `skipPhases` / `denyBootPhases` from `/etc/bare-os/boot.policy.json`; optional `minKernelFeatureMask` / `requireSeedCaps`; v2 fields `maxExecLineDepth`, `denyEnvKeys`, `requireProcNodes` |
|
||||
| Boot policy strict | `BARE_OS_BOOT_POLICY_STRICT=1` | Abort boot when policy checks fail |
|
||||
| Lazy personal drive | `BARE_OS_LAZY_PERSONAL_DRIVE=1` | Mount personal Hyperdrive at session setup instead of immediately after kernel fetch |
|
||||
| System revision | `BARE_OS_SYSTEM_REVISION_ID`, `BARE_OS_SYSTEM_REVISION_PENDING`, `BARE_OS_SYSTEM_SLOT` | Exposed as `ctx.bareOsSystemRevision` (Pear OTA–style hints) |
|
||||
@@ -48,8 +56,10 @@ Seed RPC **`bare_os.capabilities`** includes **`protocolPackageVersion`**, **`fe
|
||||
1. **Boot phases** — Use `ctx.bareOsRegisterBootPhaseHook` (see stock `kernel/init.js` header).
|
||||
2. **Virtual files** — `ctx.bareOsRegisterVirtualFile(name, reader, { etag, mime, ttlMs })`; list via `/proc/bare_os_virtual_registry`.
|
||||
3. **IPC** — Named FIFOs under `/run/bare-os/ipc/`; optional `BARE_OS_IPC_NAMESPACE`; JSON-RPC and fan-out documented in the booter package README.
|
||||
4. **Initd drop-ins** — `After=` / `Before=` / `Wants=` / `Requires=`; `RestartMaxAttempts=` in `~/.config/bare-os/units/<name>.unit` (1–32).
|
||||
5. **`/proc/bare_os/`** — Stable aliases (`features`, `replication`, `index.json`, …) mirroring flat `/proc/bare_os_*` files.
|
||||
4. **Initd drop-ins** — `After=` / `Before=` / `Wants=` / `Requires=`; `RestartMaxAttempts=` in `~/.config/bare-os/units/<name>.unit` (1–32). **Timers** — `~/.config/bare-os/timers/*.timer`: `[Timer]` with `OnCalendar=` + `ExecLine=`, or `EveryMs=` (1000–86400000) + `ExecLine=` for fixed-interval jobs (max 8 files).
|
||||
5. **`/proc/bare_os/`** — Stable aliases (`features`, `replication`, `provenance`, `metrics_live.json`, `initd_dag.json`, `pear_ipc.json`, `manifest_hints`, …) mirroring flat `/proc/bare_os_*` files.
|
||||
6. **`ctx.bareOsReadProcMetricsLive()`** — Same JSON as **`/proc/bare_os/metrics_live.json`** without a VFS read.
|
||||
7. **Initd** — `bareOsRegisterSuspendHook` / `ResumeHook` stop and restart units with `stop` handlers around Bare mobile suspend (see **`bare-initd`**).
|
||||
|
||||
## Profiles
|
||||
|
||||
|
||||
Reference in New Issue
Block a user