Skip to content

Distribute and run LLMs with a single file.

fix(server): bind the listening socket before the sandbox (#1072)

Pablo De Chiaro Rosaaec705e84c31
diff --git a/docs/security.md b/docs/security.md
index 3bcfcc13..232fc00b 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -25,6 +25,9 @@ The `llamafile --server` process runs under `stdio anet rpath` on Linux
- **No outbound network.** `anet` allows `accept()` but not `connect()`, so
the only networking the server can do is answer connections it received.
+ The listening socket is bound before the sandbox is installed, which is
+ also what lets `--host /path/to/server.sock` serve over a Unix domain
+ socket: `anet` covers only IPv4/IPv6, so one couldn't be created later.
If the server is ever compromised (say, through a bug in the GGUF parser
or an HTTP handler), this is the single most valuable restriction: it cuts
the attacker's ability to exfiltrate anything over the network.
diff --git a/llama.cpp.patches/README.md b/llama.cpp.patches/README.md
index bf58872b..6a3d180a 100644
--- a/llama.cpp.patches/README.md
+++ b/llama.cpp.patches/README.md
@@ -204,7 +204,8 @@ These patches integrate llamafile's file handling APIs for loading models from b
| Patch | Description |
|-------|-------------|
-| `tools_server_server.cpp.patch` | Renames upstream's `llama_server()` to `server_main()` and adds `on_ready`/`on_shutdown_available` callbacks for combined TUI+server mode; adds Metal/GPU backend trigger before `common_init()`; installs the sandbox (`llamafile_sandbox_server()`, issue #930) — the mechanism lives in `llamafile/sandbox.c`; the patch fills a `llamafile_sandbox_spec` with the on-disk paths the loader opens after the lock (model, mmproj, media dir, LoRA, draft model, control vectors, public path as read; slot-save and prompt cache as read-write), detects outbound-needing features (`--rpc` via argv/env, MCP proxy, server tools) to relax `anet`→`inet`, passes `FLAG_confine_reads` for opt-in unveil(), quiesces the log worker (`common_log_pause`/`resume`, so no thread escapes the per-thread filter) around the call, before the HTTP listener spawns and before model load, and skips it in combined/GPU modes; adds Cosmopolitan-specific standalone `main()` with `cosmo_args`, verbose flag handling, `--unsecure` consumption (`llamafile_consume_flag`), and GPU pre-initialization; handles `LLAMAFILE_TUI` exit to avoid Metal cleanup crashes |
+| `tools_server_server.cpp.patch` | Renames upstream's `llama_server()` to `server_main()` and adds `on_ready`/`on_shutdown_available` callbacks for combined TUI+server mode; adds Metal/GPU backend trigger before `common_init()`; installs the sandbox (`llamafile_sandbox_server()`, issue #930) — the mechanism lives in `llamafile/sandbox.c`; the patch fills a `llamafile_sandbox_spec` with the on-disk paths the loader opens after the lock (model, mmproj, media dir, LoRA, draft model, control vectors, public path as read; slot-save and prompt cache as read-write), detects outbound-needing features (`--rpc` via argv/env, MCP proxy, server tools) to relax `anet`→`inet`, passes `FLAG_confine_reads` for opt-in unveil(), binds the listening socket first (`ctx_http.bind_socket()`, so a `--host /path.sock` Unix socket exists before `anet` forbids creating one, issue #971), quiesces the log worker (`common_log_pause`/`resume`, so no thread escapes the per-thread filter) around the call, before the HTTP listener spawns and before model load, and skips it in combined/GPU modes; adds Cosmopolitan-specific standalone `main()` with `cosmo_args`, verbose flag handling, `--unsecure` consumption (`llamafile_consume_flag`), and GPU pre-initialization; handles `LLAMAFILE_TUI` exit to avoid Metal cleanup crashes |
+| `tools_server_server-http.h.patch` / `tools_server_server-http.cpp.patch` | Splits the bind out of `server_http_context::start()` into `bind_socket()`, which `start()` calls if it hasn't run yet, so the server can bind before installing the sandbox (issue #971) |
**GPU decode must stay on the main thread** (`tools_server_server-queue.cpp.patch`).
b10441 moved `llama_decode()` off the main thread: `update_slots()` now hands
diff --git a/llama.cpp.patches/patches/tools_server_server-http.cpp.patch b/llama.cpp.patches/patches/tools_server_server-http.cpp.patch
index 67583e77..c3319387 100644
--- a/llama.cpp.patches/patches/tools_server_server-http.cpp.patch
+++ b/llama.cpp.patches/patches/tools_server_server-http.cpp.patch
@@ -10,3 +10,39 @@ diff --git a/tools/server/server-http.cpp b/tools/server/server-http.cpp
if (!params.ssl_file_key.empty() && !params.ssl_file_cert.empty()) {
SRV_TRC("running with SSL: key = %s, cert = %s\n", params.ssl_file_key.c_str(), params.ssl_file_cert.c_str());
srv = std::make_unique<httplib::SSLServer>(
+@@ -429,12 +429,15 @@ bool server_http_context::init(const common_params & params) {
+ return true;
+ }
+
+-bool server_http_context::start() {
++bool server_http_context::bind_socket() {
++ if (is_bound) {
++ return true;
++ }
++
+ // Bind and listen
+
+ const auto & srv = pimpl->srv;
+ auto was_bound = false;
+- auto is_sock = false;
+ if (string_ends_with(std::string(hostname), ".sock")) {
+ is_sock = true;
+ SRV_TRC("%s", "setting address family to AF_UNIX\n");
+@@ -461,6 +464,17 @@ bool server_http_context::start() {
+ return false;
+ }
+
++ is_bound = true;
++ return true;
++}
++
++bool server_http_context::start() {
++ if (!bind_socket()) {
++ return false;
++ }
++
++ const auto & srv = pimpl->srv;
++
+ // run the HTTP server in a thread
+ thread = std::thread([this] { pimpl->srv->listen_after_bind(); });
+ srv->wait_until_ready();
diff --git a/llama.cpp.patches/patches/tools_server_server-http.h.patch b/llama.cpp.patches/patches/tools_server_server-http.h.patch
new file mode 100644
index 00000000..39c7a976
--- /dev/null
+++ b/llama.cpp.patches/patches/tools_server_server-http.h.patch
@@ -0,0 +1,21 @@
+diff --git a/tools/server/server-http.h b/tools/server/server-http.h
+--- a/llama.cpp/tools/server/server-http.h
++++ b/llama.cpp/tools/server/server-http.h
+@@ -79,11 +79,17 @@ struct server_http_context {
+ std::string hostname;
+ int port = 8080;
+ bool is_ssl = false;
++ bool is_sock = false; // listening on a Unix domain socket
++ bool is_bound = false;
+
+ server_http_context();
+ ~server_http_context();
+
+ bool init(const common_params & params);
++ // creates and binds the listening socket; start() calls it if needed.
++ // llamafile binds early so the socket exists before the sandbox is
++ // installed (a Unix domain socket can't be created under pledge "anet")
++ bool bind_socket();
+ bool start();
+ void stop() const;
+
diff --git a/llama.cpp.patches/patches/tools_server_server.cpp.patch b/llama.cpp.patches/patches/tools_server_server.cpp.patch
index e6b7e53d..21e6da5d 100644
--- a/llama.cpp.patches/patches/tools_server_server.cpp.patch
+++ b/llama.cpp.patches/patches/tools_server_server.cpp.patch
@@ -85,7 +85,7 @@ diff --git a/tools/server/server.cpp b/tools/server/server.cpp
bool is_run_by_cli = (argv == nullptr);
common_models_handler models_handler;
-@@ -457,6 +491,92 @@ int llama_server(common_params & params, int argc, char ** argv) {
+@@ -457,6 +491,103 @@ int llama_server(common_params & params, int argc, char ** argv) {
llama_backend_free();
};
@@ -154,6 +154,17 @@ diff --git a/tools/server/server.cpp b/tools/server/server.cpp
+ rw_paths.data(), (int) rw_paths.size(),
+ FLAG_confine_reads, needs_outbound,
+ };
++ // Bind the listening socket now: pledge "anet" only covers
++ // IPv4/IPv6, so a Unix domain socket (--host /path.sock) can't be
++ // created once the sandbox is on, while accept() on one that is
++ // already bound stays allowed (llamafile issue #971). Binding
++ // spawns no threads; ctx_http.start() reuses the socket.
++ if (!ctx_http.bind_socket()) {
++ clean_up();
++ SRV_ERR("%s", "exiting due to HTTP server error\n");
++ return 1;
++ }
++
+ char promises[64];
+ common_log_pause(common_log_main());
+ server_stream_session_manager_stop();
@@ -178,7 +189,7 @@ diff --git a/tools/server/server.cpp b/tools/server/server.cpp
// start the HTTP server before loading the model to be able to serve /health requests
if (!ctx_http.start()) {
clean_up();
-@@ -490,6 +610,13 @@ int llama_server(common_params & params, int argc, char ** argv) {
+@@ -490,6 +621,13 @@ int llama_server(common_params & params, int argc, char ** argv) {
// this will unblock start_loop()
ctx_server.terminate();
};
@@ -192,7 +203,7 @@ diff --git a/tools/server/server.cpp b/tools/server/server.cpp
}
// register signal handler if not running by CLI
-@@ -530,6 +657,11 @@ int llama_server(common_params & params, int argc, char ** argv) {
+@@ -530,6 +668,11 @@ int llama_server(common_params & params, int argc, char ** argv) {
// when the HTTP server stops, clean up and exit
clean_up();
} else {
@@ -204,7 +215,7 @@ diff --git a/tools/server/server.cpp b/tools/server/server.cpp
// optionally, notify router server that this instance is ready
std::thread monitor_thread;
if (child.is_child()) {
-@@ -554,5 +686,56 @@ int llama_server(common_params & params, int argc, char ** argv) {
+@@ -554,5 +697,56 @@ int llama_server(common_params & params, int argc, char ** argv) {
}
}
diff --git a/tests/integration/tests/test_sandbox.py b/tests/integration/tests/test_sandbox.py
index 6b5f86a4..99b967e9 100644
--- a/tests/integration/tests/test_sandbox.py
+++ b/tests/integration/tests/test_sandbox.py
@@ -29,7 +29,9 @@ unveil() path confinement directly.
import os
import platform
import shutil
+import socket
import subprocess
+import tempfile
import time
from pathlib import Path
@@ -137,6 +139,38 @@ def _resolve_server_pid(pid: int) -> int:
return pid
+def _unix_http_get(sock_path: str, path: str, timeout: float) -> tuple[int, bytes]:
+ """Minimal HTTP/1.1 GET over a Unix domain socket: (status, body)."""
+ with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as s:
+ s.settimeout(timeout)
+ s.connect(sock_path)
+ s.sendall(
+ f"GET {path} HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n".encode()
+ )
+ data = b""
+ while chunk := s.recv(65536):
+ data += chunk
+ head, _, body = data.partition(b"\r\n\r\n")
+ return int(head.split(b" ", 2)[1]), body
+
+
+def _wait_for_unix_server(sock_path: str, timeout: float, proc) -> bool:
+ """Poll GET /health on a Unix socket until it answers 200, the process
+ exits, or the timeout expires."""
+ deadline = time.time() + timeout
+ while time.time() < deadline:
+ if proc.poll() is not None:
+ return False
+ if os.path.exists(sock_path):
+ try:
+ if _unix_http_get(sock_path, "/health", 5)[0] == 200:
+ return True
+ except OSError:
+ pass
+ time.sleep(0.5)
+ return False
+
+
def _stop_hard(proc):
"""Terminate a process without ever hanging the test: SIGTERM first
(llamafile shuts down gracefully), SIGKILL if it doesn't oblige."""
@@ -216,6 +250,32 @@ class TestServerSandbox:
log = LlamafileRunner.read_log_file(log_file)
assert 'sandbox: pledge("' in log, "server should log the active promise set"
+ @requires_linux
+ def test_unix_socket_server_sandboxed(self, cpu_runner, server_port, timeouts):
+ """--host /path.sock serves over a Unix domain socket under the
+ sandbox (issue #971): "anet" forbids creating an AF_UNIX socket, so
+ the server must bind it before pledge()."""
+ # short path under /tmp: sun_path is limited to 108 bytes
+ sock_dir = tempfile.mkdtemp(prefix="lf_uds_")
+ sock_path = os.path.join(sock_dir, "server.sock")
+ log_file = os.path.join(sock_dir, "server.log")
+ proc = cpu_runner.start_server(
+ port=server_port, log_file=log_file, extra_args=["--host", sock_path]
+ )
+ try:
+ assert _wait_for_unix_server(
+ sock_path, timeout=timeouts.server_ready, proc=proc
+ ), "Server did not become ready on the Unix socket"
+ _assert_sandbox_installed(_resolve_server_pid(proc.pid))
+ status, body = _unix_http_get(sock_path, "/v1/models", timeouts.http_request)
+ assert status == 200 and b'"data"' in body
+ finally:
+ _stop_hard(proc)
+ log = LlamafileRunner.read_log_file(log_file)
+ shutil.rmtree(sock_dir, ignore_errors=True)
+
+ assert 'sandbox: pledge("' in log, "server should log the active promise set"
+
@requires_linux
def test_unsecure_flag_disables_sandbox(self, cpu_runner, server_port, timeouts, tmp_path):
"""--unsecure opts out: no SECCOMP filter, and the log says why."""
diff --git a/tests/sandbox_test.c b/tests/sandbox_test.c
index fec0f2c2..648d9783 100644
--- a/tests/sandbox_test.c
+++ b/tests/sandbox_test.c
@@ -45,6 +45,7 @@
#include <stdlib.h>
#include <string.h>
#include <sys/socket.h>
+#include <sys/un.h>
#include <sys/wait.h>
#include <unistd.h>
@@ -154,6 +155,44 @@ static void child_anet_promises(void) {
_exit(0);
}
+// Socket path for child_unix_listener, under a temp dir that main() creates
+// and removes: the sandboxed child can't, as it has no cpath.
+static char unix_sock_path[PATH_MAX];
+
+// what --server --host /path.sock relies on: anet doesn't cover AF_UNIX, so
+// the server binds its Unix domain socket before pledge() and only accepts
+// on it afterwards
+static void child_unix_listener(void) {
+ int server = socket(AF_UNIX, SOCK_STREAM, 0);
+ CHECK(server != -1, "pre-pledge AF_UNIX socket");
+ struct sockaddr_un addr;
+ memset(&addr, 0, sizeof(addr));
+ addr.sun_family = AF_UNIX;
+ strlcpy(addr.sun_path, unix_sock_path, sizeof(addr.sun_path));
+ CHECK(!bind(server, (struct sockaddr *)&addr, sizeof(addr)),
+ "pre-pledge AF_UNIX bind");
+ CHECK(!listen(server, 1), "pre-pledge AF_UNIX listen");
+
+ CHECK(llamafile_sandbox_apply("stdio anet rpath") == LLAMAFILE_SANDBOX_ACTIVE,
+ "apply stdio anet rpath");
+
+ // accept() on the already-bound socket is permitted
+ int flags = fcntl(server, F_GETFL);
+ CHECK(flags != -1 && fcntl(server, F_SETFL, flags | O_NONBLOCK) != -1,
+ "set O_NONBLOCK");
+ errno = 0;
+ CHECK(accept(server, 0, 0) == -1, "accept with no client");
+ CHECK(errno == EAGAIN || errno == EWOULDBLOCK,
+ "AF_UNIX accept() allowed by filter (EAGAIN, not EPERM)");
+
+ // creating one after pledge() is not, which is why the bind comes first
+ errno = 0;
+ CHECK(socket(AF_UNIX, SOCK_STREAM, 0) == -1, "AF_UNIX socket() blocked under anet");
+ CHECK(errno == EPERM, "AF_UNIX socket() fails with EPERM");
+
+ _exit(0);
+}
+
// unveil() confinement: reads under an unveiled directory succeed while
// the rest of the filesystem is denied. Landlock accepts rules on any
// filesystem but enforces on only some (see llamafile_sandbox_server's
@@ -270,6 +309,18 @@ int main(void) {
rc |= run_case("stdio+rpath (cli promises)", child_rpath_promises);
rc |= run_case("stdio only (embedded weights)", child_stdio_only);
rc |= run_case("stdio+anet+rpath (server promises)", child_anet_promises);
+
+ char unix_dir[] = "/tmp/lf_unix_XXXXXX";
+ if (!mkdtemp(unix_dir)) {
+ perror("mkdtemp");
+ return 1;
+ }
+ snprintf(unix_sock_path, sizeof(unix_sock_path), "%s/server.sock", unix_dir);
+ rc |= run_case("stdio+anet+rpath (unix socket bound before pledge)",
+ child_unix_listener);
+ unlink(unix_sock_path);
+ rmdir(unix_dir);
+
rc |= run_case("unveil confinement", child_unveil);
return rc;
}