mkunit socket

Create a systemd socket unit for socket activation.

mkunit socket <name> [flags]

Description

The socket command creates a .socket unit file for socket-based activation. Systemd listens on the socket and starts the associated service only when a connection is received. This enables on-demand service startup and can improve boot times and resource usage.

Arguments

Argument Description
<name> Name of the socket unit (without .socket extension)

Flags

Flag Description Default
--unit <name> Service unit to activate <name>.service
--listen-stream <addr> TCP stream socket (port or address:port) —
--listen-datagram <addr> UDP datagram socket —
--listen-unix <path> Unix stream socket path —
--listen-unix-datagram <path> Unix datagram socket path —
--accept Spawn instance per connection false
--max-connections <n> Max simultaneous connections (with --accept) 64
--backlog <n> Socket backlog queue size 128
--socket-user <user> Socket file owner (Unix sockets) —
--socket-group <group> Socket file group (Unix sockets) —
--socket-mode <mode> Socket file permissions (octal) 0666
--description <text> Human-readable description Auto-generated
--system Create a system socket false
--install Install the unit file false
--start Start listening on the socket false
--enable Enable on boot false
--dry-run Print without writing false

Socket Types

Type Use Case
ListenStream (TCP) Web servers, APIs, databases
ListenDatagram (UDP) DNS, logging, metrics
ListenStream (Unix) Local IPC, container communication
ListenSequentialPacket Message-oriented Unix sockets

Examples

TCP socket activation on port 8080

mkunit socket myapp \
  --listen-stream 8080 \
  --install --start

Unix socket for local IPC

mkunit socket myapp \
  --listen-unix /run/myapp/myapp.sock \
  --socket-mode 0660 \
  --socket-group myapp \
  --install --start

Accept mode (instance per connection)

mkunit socket ssh-proxy \
  --listen-stream 2222 \
  --accept \
  --max-connections 100 \
  --unit ssh-proxy@.service \
  --install

Multiple listen addresses

mkunit socket multi-listener \
  --listen-stream 8080 \
  --listen-stream 8443 \
  --listen-unix /run/myapp.sock \
  --install

Bind to specific interface

mkunit socket internal-api \
  --listen-stream 127.0.0.1:9000 \
  --install --start
How socket activation works

When using socket activation, your service receives the socket file descriptor from systemd (typically as FD 3). Many applications support this via the sd_listen_fds() API or by listening on $LISTEN_FDS.

See Also

  • mkunit service - Create the activated service
  • mkunit status - Check socket status
  • man systemd.socket - Full socket unit documentation