Understanding websocketd

websocketd is small enough that you can hold all of it in your head, and these pages are how you get there. They explain the reasoning behind the behaviour rather than telling you which command to type.

Read this section when something websocketd does surprises you and you want to know whether it is a bug, a setting, or the design. Read it before you build anything larger than a demo, because two of the decisions here (one process per connection, and newline-delimited framing) shape what your application can be.

If you have a job to finish right now, the how-to guides give steps rather than reasons. If you want an exact value for a flag, a variable, or an exit code, it is in the reference .

If you are new to websocketd, start with the tutorial and come back.

• The process model — One process per WebSocket connection is the decision everything else follows from: it lets websocketd wrap any program, and it rules out shared state between connections.
• Message framing — A newline is what turns your program's output into a WebSocket message, and --binary changes the message type rather than turning websocketd into a terminal.
• Output buffering — Language runtimes withhold output when standard output is a pipe rather than a terminal, which is why a script that streams perfectly in a terminal can appear silent under websocketd.
• Process lifecycle — A wrapped program starts when the first client connects, and is shut down by an escalating ladder of stdin close, SIGINT, SIGTERM and SIGKILL that a long-running program has to cooperate with.
• The CGI environment — How an HTTP request becomes a child process's environment, which parts of it the client controls, and why the Proxy header is the one exception to the rule.
• The security model — websocketd executes a program on behalf of whoever connects, so its security posture is about who may connect, what the connection can reach, and which parts of the job belong to you.
• Design decisions — Why websocketd has no broadcast, no pty, no built-in authentication and no compression, and what was built and then deliberately removed.