How to connect over Unix sockets with cURL

Connecting HTTP clients over Unix domain sockets using cURL keeps internal APIs bound to the local host and avoids exposing TCP ports on external interfaces. Many local daemons on Linux, such as container runtimes and reverse proxies, publish control-plane or status endpoints only on socket files. Using cURL against those sockets simplifies debugging, health checks, and automation for services that are not intended to be reachable over the network.

Unix domain sockets use filesystem paths like /var/run/docker.sock as addressing instead of IP and port pairs, while the higher-level protocol remains standard HTTP or HTTPS. When compiled with Unix socket support, cURL attaches a regular URL to a specific socket path via the --unix-socket option, so the URL continues to define scheme, host header, and request path while the bytes travel through the designated socket. On Linux, abstract namespace sockets can be reached with --abstract-unix-socket when services are configured with that style of endpoint.

Access to socket files is governed by standard Unix permissions, which often restrict powerful control-plane sockets to privileged users or groups such as docker. Reaching sensitive sockets like /var/run/docker.sock effectively grants full control over the associated service and may expose host-level operations or confidential data. The commands below use a local Unix socket at /tmp/sg-unix.sock and a cURL build that advertises UnixSockets support in its feature list.

1. Open a terminal with access to a user account that can reach the socket file.

   $ whoami
   root

2. Confirm that the installed cURL build includes Unix domain socket support.

   $ curl --version
   curl 8.5.0 (aarch64-unknown-linux-gnu) libcurl/8.5.0 OpenSSL/3.0.13 zlib/1.3 brotli/1.1.0 zstd/1.5.5 libidn2/2.3.7 libpsl/0.21.2 (+libidn2/2.3.7) libssh/0.10.6/openssl/zlib nghttp2/1.59.0 librtmp/2.3 OpenLDAP/2.6.7
   Release-Date: 2023-12-06, security patched: 8.5.0-2ubuntu10.6
   Protocols: dict file ftp ftps gopher gophers http https imap imaps ldap ldaps mqtt pop3 pop3s rtmp rtsp scp sftp smb smbs smtp smtps telnet tftp
   Features: alt-svc AsynchDNS brotli GSS-API HSTS HTTP2 HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM PSL SPNEGO SSL threadsafe TLS-SRP UnixSockets zstd
   ##### snipped #####

   Unix domain socket support is available when the Features line lists UnixSockets; abstract namespace sockets on Linux can be reached with --abstract-unix-socket when required.

3. Inspect the Unix socket file exposed by the target service to confirm its presence and permissions.

   $ ls -l /tmp/sg-unix.sock
   srwxr-xr-x 1 root root 0 Jan 10 06:25 /tmp/sg-unix.sock

   Access to privileged socket files grants control over the associated service; restrict permissions and group membership accordingly.

4. Send a basic HTTP request over the Unix socket using the --unix-socket option in cURL.

   $ curl --silent --unix-socket /tmp/sg-unix.sock http://localhost/ping
   OK

   The host portion http://localhost supplies the HTTP scheme and Host header, while the actual transport occurs entirely through the Unix socket at /tmp/sg-unix.sock.

5. Query a JSON API endpoint over the Unix socket and print the response body for inspection.

   $ curl --silent --unix-socket /tmp/sg-unix.sock \
     --header 'Accept: application/json' \
     http://localhost/health
   {"status": "ok", "service": "unix-socket-api"}

   Adding --header 'Accept: application/json' encourages APIs to return structured JSON suitable for parsing with tools such as jq.

6. Validate connectivity for automation by checking only the HTTP status code and cURL exit status.

   $ curl --unix-socket /tmp/sg-unix.sock \
     --silent --show-error \
     --output /dev/null \
     --write-out '%{http_code}\n' \
     http://localhost/ping
   200

   Successful Unix socket connectivity is indicated by an HTTP 2xx code, no error output on stderr, and a zero exit status; non-zero status or errors such as Permission denied usually indicate missing group membership or an inactive socket.