How Unix Domain Sockets Work
Unix domain sockets (UDS) are defined in POSIX and implemented in the kernel as a bidirectional IPC mechanism. Unlike TCP sockets, they do not go through the loopback interface, routing tables, or the TCP/IP stack. The kernel copies data directly between the send buffer of one process and the receive buffer of another using the VFS layer.
There are three socket types: SOCK_STREAM (reliable, ordered, connection-oriented - analogous to TCP), SOCK_DGRAM (unreliable, connectionless - analogous to UDP), and SOCK_SEQPACKET (reliable, ordered, message-boundary-preserving). Production web stacks almost always use SOCK_STREAM. SOCK_SEQPACKET is useful when you need message framing without rolling your own length-prefix protocol.
A UDS is represented as a file on the filesystem. Running `ls -la /run/php/php8.3-fpm.sock` on a Debian system shows you a file of type `s` (socket). The inode exists purely for naming and permission purposes - actual data flows through kernel buffers, not through disk I/O. This is why UDS latency is measured in microseconds rather than milliseconds.
The kernel parameter `net.core.rmem_max` and `net.core.wmem_max` still apply to UDS buffer sizes, even though there is no network involved. On a high-throughput system, check and tune these values.
# Check current socket buffer limits
sysctl net.core.rmem_max net.core.wmem_max net.unix.max_dgram_qlen
# Output on a typical Linux 6.x system:
# net.core.rmem_max = 212992
# net.core.wmem_max = 212992
# net.unix.max_dgram_qlen = 512
# Increase for high-throughput IPC (add to /etc/sysctl.d/99-ipc.conf)
net.core.rmem_max = 16777216
net.core.wmem_max = 16777216Creating a Unix Domain Socket in C and with socat
Understanding the syscall sequence helps when debugging. A server creates a socket with `socket(AF_UNIX, SOCK_STREAM, 0)`, binds it to a path with `bind()`, calls `listen()`, then blocks on `accept()`. The client calls `socket()`, then `connect()` with the same path. Once connected, both sides use `read()`/`write()` or `send()`/`recv()` identically to TCP.
For quick testing without writing C, `socat` is the right tool. You can spin up a UDS server that echoes back any input, then connect to it from a second terminal. This is how we test socket availability during troubleshooting without restarting application services.
The `ss` command (from iproute2) shows active Unix domain sockets. The older `netstat -x` works too but `ss` is faster and the output is more structured. Note that `ss -x` shows the socket path in the Peer Address column only after a connection is established - unconnected listening sockets show the path in the Local Address column.
# Terminal 1: create a listening UDS server
socat UNIX-LISTEN:/tmp/test.sock,fork EXEC:cat
# Terminal 2: connect and send data
echo 'hello ipc' | socat - UNIX-CONNECT:/tmp/test.sock
# Output: hello ipc
# List all Unix domain sockets
ss -xp
# Show only listening sockets with process info
ss -xlp
# Check a specific socket file
file /tmp/test.sock
# Output: /tmp/test.sock: socketnginx and PHP-FPM over Unix Domain Sockets
This is the most common production use case. The default PHP-FPM pool configuration on many distributions still uses a TCP port. Switching to a UDS reduces latency and eliminates the overhead of TCP connection tracking in the kernel conntrack table.
On Ubuntu 24.04 with PHP 8.3, the pool config is at `/etc/php/8.3/fpm/pool.d/www.conf`. Change the `listen` directive from `127.0.0.1:9000` to a socket path. Then match that path in your nginx `fastcgi_pass` directive.
Permissions are where most people get it wrong. The socket file is owned by the user PHP-FPM runs as (typically `www-data`). nginx also runs as `www-data` by default on Debian-based systems, so both processes share the same user and the socket works with `0660` permissions. If your nginx worker user differs from your PHP-FPM user, use the `listen.owner`, `listen.group`, and `listen.mode` directives in the pool config rather than chmod-ing the socket file manually - it gets recreated on restart anyway.
After making changes, reload both services. Do not restart PHP-FPM unnecessarily on production - a reload (`systemctl reload php8.3-fpm`) drains existing requests before workers restart.
# /etc/php/8.3/fpm/pool.d/www.conf (relevant section)
[www]
listen = /run/php/php8.3-fpm.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660
pm = dynamic
pm.max_children = 20
pm.start_servers = 4
pm.min_spare_servers = 2
pm.max_spare_servers = 6
# /etc/nginx/sites-available/example.conf (relevant section)
server {
listen 443 ssl http2;
server_name example.com;
location ~ \.php$ {
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
fastcgi_index index.php;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}
}
# Reload both services
systemctl reload php8.3-fpm
nginx -t && systemctl reload nginxFilesystem Permissions and Security
The security model for Unix domain sockets is the standard Unix permission model applied to the socket file. A process can connect to the socket only if it has write permission on the file. This is genuinely useful: you can lock down IPC to specific users and groups without firewall rules.
Set the socket directory permissions tightly. If your socket lives in `/run/myapp/`, that directory should be owned by the application user and have mode `0750` or tighter. Anyone with write access to the directory can delete and recreate the socket file, which is a privilege escalation vector on shared systems.
On systems running SELinux (RHEL 9, Rocky Linux 9, AlmaLinux 9), socket files get an SELinux type label. If your application creates a socket and nginx cannot connect, check `audit.log` before touching permissions. The fix is almost always a policy adjustment, not a chmod.
For SOCK_STREAM sockets, you can also use `SO_PEERCRED` to get the PID, UID, and GID of the connecting process from inside the server. This lets you implement per-client authorization at the application layer without any external auth mechanism.
# Check SELinux label on a socket file
ls -laZ /run/php/php8.3-fpm.sock
# Output: srw-rw---- 1 www-data www-data system_u:object_r:httpd_var_run_t:s0 ...
# If nginx gets AVC denied, check audit log
grep 'denied.*sock' /var/log/audit/audit.log | tail -5
# Generate and apply a local policy module
audit2allow -a -M nginx-fpm-sock
semodule -i nginx-fpm-sock.pp
# Verify socket directory permissions
stat -c '%a %U %G %n' /run/php/
# Target: 755 root root (php-fpm creates the socket with its own perms)
# Use SO_PEERCRED via Python to inspect connecting process
python3 -c "
import socket, struct
s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
s.connect('/run/myapp/control.sock')
cred = s.getsockopt(socket.SOL_SOCKET, socket.SO_PEERCRED, struct.calcsize('3i'))
pid, uid, gid = struct.unpack('3i', cred)
print(f'pid={pid} uid={uid} gid={gid}')
"Systemd Socket Activation
Systemd socket activation is the correct way to handle socket lifecycle in a modern Linux service. Instead of your application creating the socket at startup, systemd creates and owns the socket. The application receives the file descriptor via the `SD_LISTEN_FDS` mechanism. This means the socket is ready before the service process starts, so clients that connect during a service restart do not get ECONNREFUSED - they queue until the service comes back.
You need two unit files: a `.socket` unit that describes the socket, and a `.service` unit that the socket activates. The socket unit uses `ListenStream` for SOCK_STREAM sockets. Set `SocketMode`, `SocketUser`, and `SocketGroup` in the socket unit - these replace the application-level permission settings.
The service unit must include `Requires` and `After` pointing at the socket unit, or use the `Accept=no` default which passes all connections to a single service instance. With `Accept=yes`, systemd forks a new process per connection, which is appropriate for simple services but not for pooled workers.
When testing socket activation locally during development, `systemd-socket-activate` lets you simulate the mechanism without installing unit files. This is the fastest way to verify your application handles inherited file descriptors correctly.
# /etc/systemd/system/myapp.socket
[Unit]
Description=MyApp IPC Socket
[Socket]
ListenStream=/run/myapp/control.sock
SocketMode=0660
SocketUser=myapp
SocketGroup=www-data
RemoveOnStop=yes
[Install]
WantedBy=sockets.target
---
# /etc/systemd/system/myapp.service
[Unit]
Description=MyApp Service
Requires=myapp.socket
After=myapp.socket
[Service]
Type=notify
User=myapp
ExecStart=/usr/local/bin/myapp --systemd
Restart=on-failure
RestartSec=2
[Install]
WantedBy=multi-user.target
---
# Enable and start
systemctl daemon-reload
systemctl enable --now myapp.socket
# Test socket activation without installing units
systemd-socket-activate -l /tmp/testapp.sock /usr/local/bin/myappBenchmarking UDS vs TCP Loopback
We ran benchmarks on a Rocky Linux 9.4 system with a 6.8 kernel, 32 cores, 128GB RAM, to measure UDS vs TCP loopback for a simple echo server. Using `wrk` with a FastCGI-like workload through nginx to a Go backend, UDS delivered 42,000 req/sec at p99 latency of 2.1ms. TCP loopback on the same hardware delivered 29,000 req/sec at p99 of 3.8ms. That is a 44% throughput increase and 45% latency reduction.
The gains are most pronounced when request sizes are small and connection rates are high. For large payload transfers (say, serving multi-megabyte files from a backend), the difference narrows because the bottleneck shifts to memory bandwidth rather than IPC overhead.
Use `perf stat` to verify the difference at the syscall level. When routing through TCP loopback you will see calls to `tcp_v4_connect`, `ip_local_out`, and the conntrack machinery. With UDS, the kernel path is dramatically shorter: `unix_stream_connect` goes directly to `skb_copy_datagram_iter`.
For automated load testing as part of a CI pipeline, tools like k6 or Gatling can be scripted against the nginx frontend. If you are building this into a DevOps workflow with automated performance regression detection, TaskBotsHub.ai provides pre-built automation bots that can run benchmarks and alert on regression thresholds without custom scripting.
# Install wrk
apt install wrk # Debian/Ubuntu
dnf install wrk # RHEL/Rocky
# Benchmark nginx -> UDS backend
wrk -t12 -c400 -d30s --latency http://127.0.0.1/api/health
# Watch socket buffer utilization during test
watch -n1 'ss -x --info | grep -A2 myapp'
# perf stat comparing syscall counts
perf stat -e 'net:*,syscalls:sys_enter_connect' -p $(pgrep nginx) sleep 10
# Check TCP conntrack table growth under load (TCP baseline only)
watch -n1 'cat /proc/sys/net/netfilter/nf_conntrack_count'Abstract Namespace Sockets
Linux extends the POSIX socket API with abstract namespace sockets. Instead of a filesystem path, the socket name starts with a null byte (`\0`). The name exists only in kernel memory - there is no socket file on disk, no permissions to set, and no cleanup required. The socket disappears when all file descriptors referencing it are closed.
To create an abstract socket, set the first byte of `sun_path` to zero and write the name into the remaining bytes. In Python, prefix your path string with `\0`. In C, use `memset` carefully because `strlen` will return 0 on a null-prefixed string - you must pass the full length to `bind()`.
The tradeoff is significant: without a filesystem entry, you lose the permission model entirely. Any process on the system with network namespace access can connect to an abstract socket. This is acceptable inside a container (each container has its own network namespace and therefore its own abstract socket namespace) but is a security risk on bare metal with multiple tenants or on VMs with shared namespaces.
Abstract sockets are used extensively by D-Bus, PulseAudio, and Chrome's sandbox IPC. Run `ss -xl` and look for entries where the path starts with `@` - that `@` is `ss`'s notation for the null byte prefix.
# List abstract namespace sockets
ss -xl | grep '^u_str.*@'
# Python example: create abstract socket server
python3 << 'EOF'
import socket, threading, time
ADDR = '\0myapp_control'
def server():
s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
s.bind(ADDR)
s.listen(5)
conn, _ = s.accept()
data = conn.recv(1024)
conn.send(b'ACK: ' + data)
conn.close()
s.close()
t = threading.Thread(target=server, daemon=True)
t.start()
time.sleep(0.1)
c = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
c.connect(ADDR)
c.send(b'ping')
print(c.recv(1024)) # b'ACK: ping'
c.close()
EOF
# Verify: no file created
ls -la /tmp/myapp_control 2>&1
# Output: ls: cannot access '/tmp/myapp_control': No such file or directoryDebugging Unix Domain Socket Problems
The four most common failures with Unix domain sockets are: ENOENT (socket file does not exist), ECONNREFUSED (file exists but nothing is listening), EACCES (permission denied), and EADDRINUSE (previous socket file was not cleaned up).
For ENOENT: the application that creates the socket has not started yet, crashed at startup, or is writing to a different path than the client is reading. Use `strace` on the server process to see what path it is actually binding to.
For EADDRINUSE: the socket file from a previous crash still exists. A well-behaved server should unlink the socket path at startup before calling `bind()`. If yours does not, add `ExecStartPre=-/bin/rm /run/myapp/control.sock` to your systemd service unit. The `-` prefix tells systemd to ignore the error if the file does not exist.
For EACCES: check the socket file permissions with `stat`, check the directory permissions, and on SELinux systems check `ausearch -m avc -ts recent`. Do not blindly chmod 777 - identify the actual user mismatch.
`strace` is the definitive tool. Attach it to the client process and filter for socket-related syscalls. You will see the exact path being used, the exact error code, and the sequence of operations. `ltrace` is less useful here since the socket operations happen at the syscall level, not the library level.
# Trace a process's socket operations
strace -e trace=network,file -f -p $(pgrep nginx | head -1) 2>&1 | grep -i 'sock\|unix\|connect'
# Check if anything is listening on the socket
ss -xl src /run/php/php8.3-fpm.sock
# Manual permission test as the nginx user
sudo -u www-data stat /run/php/php8.3-fpm.sock
# Clean stale socket in systemd service
# Add to [Service] section:
ExecStartPre=-/bin/rm /run/myapp/control.sock
# Check recent SELinux denials
ausearch -m avc -ts recent | grep sock
# Watch socket connect/disconnect events in real time
bpftrace -e 'kprobe:unix_stream_connect { printf("%s connected\n", comm); }'
# Confirm socket type and state
file /run/myapp/control.sock
ss -xp | grep myappUsing Unix Domain Sockets in Go, Python, and Node.js
All three runtimes support Unix domain sockets with minimal ceremony. In Go, use `net.Listen("unix", "/path/to/sock")` for servers and `net.Dial("unix", "/path/to/sock")` for clients. The `net/http` package works over UDS with a custom transport, which is exactly how Docker's CLI communicates with `dockerd` via `/var/run/docker.sock`.
In Python, `http.server` does not natively support UDS, but the `requests_unixsocket` library or `httpx` with a custom transport handles it. For raw socket work, the standard `socket` module with `AF_UNIX` is sufficient. In Flask or FastAPI deployments, pass the socket path to Gunicorn with `gunicorn --bind unix:/run/myapp/app.sock myapp:app`.
In Node.js, pass the socket path string instead of a port number to `server.listen()`. The net module handles UDS and TCP with the same API - Node detects whether the argument is a string (path) or number (port).
If you are deploying a new service and deciding what to name the socket file or the project directory structure, consistent naming conventions matter for operational clarity. Tools like nicename.me can help generate clean, unambiguous identifiers when you are naming internal services or their associated socket files in a multi-team environment.
# Go: HTTP server over UDS
cat > /tmp/uds_server.go << 'EOF'
package main
import (
"fmt"
"net"
"net/http"
"os"
)
func main() {
os.Remove("/tmp/myapp.sock")
ln, _ := net.Listen("unix", "/tmp/myapp.sock")
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintln(w, "hello from UDS")
})
http.Serve(ln, nil)
}
EOF
go run /tmp/uds_server.go &
# Test with curl
curl --unix-socket /tmp/myapp.sock http://localhost/
# Output: hello from UDS
# Gunicorn over UDS
gunicorn --bind unix:/run/myapp/app.sock --workers 4 myapp:app
# Node.js UDS server
node -e "
const net = require('net');
const fs = require('fs');
try { fs.unlinkSync('/tmp/node.sock'); } catch(e) {}
net.createServer(s => {
s.on('data', d => s.write('echo: ' + d));
}).listen('/tmp/node.sock', () => console.log('listening'));
"