Project 3: Socket-Activated Server

Build a socket-activated echo or tiny HTTP server that starts on demand, consumes pre-opened sockets from systemd, and handles concurrency correctly.

Quick Reference

Attribute	Value
Difficulty	Level 2: Beginner-Intermediate
Time Estimate	6-12 hours
Main Programming Language	C (Alternatives: Rust, Go)
Alternative Programming Languages	Rust, Go, Python
Coolness Level	Level 3: Clever and Practical
Business Potential	Level 2: Internal Tool / Service Prototype
Prerequisites	TCP sockets, read/write loops, basic systemd unit files
Key Topics	socket activation, FD passing, concurrency models

---

1. Learning Objectives

By completing this project, you will:

1. Create .socket and .service unit pairs for on-demand activation.
2. Consume pre-opened sockets using LISTEN_FDS and sd_listen_fds.
3. Choose and implement a concurrency model appropriate for Accept mode.
4. Build a server that logs connections and shuts down cleanly.
5. Debug socket activation failures using systemd tooling.

---

2. All Theory Needed (Per-Concept Breakdown)

Concept 1: Socket Activation Contract (LISTEN_FDS and FD 3)

Fundamentals

Socket activation means systemd opens the listening socket and starts your service only when a connection arrives. The service does not call bind() or listen(); it receives already-opened file descriptors inherited across execve(). The environment variable LISTEN_FDS tells you how many descriptors were passed, and the first one is always file descriptor 3 (because 0-2 are stdin, stdout, stderr). A socket-activated service must validate these descriptors and use them for accept(). If the service is started manually, no sockets are passed. Understanding this contract is essential because it controls when your service starts and how it accepts connections.

Deep Dive into the Concept

systemd’s socket activation model decouples socket availability from process lifetime. The socket unit (.socket) declares the listening endpoints. systemd opens those sockets during startup and keeps them open, even if the service is not running. When a client connects, systemd either (a) starts the service and hands it the listening socket (Accept=no) or (b) accepts the connection itself and starts a per-connection service instance (Accept=yes). This is implemented by inheriting file descriptors across exec. systemd sets LISTEN_FDS to the number of descriptors, LISTEN_PID to the target process PID, and expects the service to consume descriptors starting at SD_LISTEN_FDS_START (3).

A robust service should validate LISTEN_PID to ensure the descriptors are meant for the current process. This prevents subtle bugs if the service was forked or if the environment was reused. It should also verify that the FDs are sockets of the expected type using sd_is_socket or sd_is_socket_inet. Another detail: systemd can pass multiple listening sockets, for example one for IPv4 and one for IPv6, or multiple ports. Your service must iterate through LISTEN_FDS and handle each socket appropriately.

Socket activation is designed for reliability. If your service crashes, systemd still owns the listening socket. Clients will connect successfully and systemd will spawn a new instance. This provides a form of zero-downtime restart. It also improves boot speed, because services are not started until they are needed. However, it imposes constraints: you must not close the listening FD prematurely, and you must avoid re-binding to the same port, or you will get “address in use” errors.

There are security implications as well. If you accept arbitrary passed FDs without validation, a compromised environment could trick your service into reading from an unintended file or socket. Always validate socket type and address family. Also remember that socket activation implies that your service might start in response to untrusted input; input validation and resource limits are crucial.

Operational configuration matters too. Socket units can set options such as Backlog, KeepAlive, ReusePort, and NoDelay, and those options are applied by systemd before your service starts. If the backlog is too small, connections can be dropped under burst load before your service is even awake. If ReusePort is enabled, multiple instances can accept in parallel, but your server must be prepared for that behavior. Socket units also define permissions for Unix domain sockets and can bind to specific addresses or interfaces, which can be important for security and multi-homing. Because systemd owns the listening socket, your service does not control these low-level details unless you configure the .socket unit. A reliable socket-activated service treats socket configuration as part of its runtime contract and documents the expected socket settings.

How this fit on projects

This concept defines the core activation behavior. You will use it in Section 3.2 (Functional Requirements), Section 4.4 (Algorithm Overview), and Section 5.10 Phase 2.

Definitions & key terms

• Socket activation -> systemd opens sockets and starts services on demand.
• LISTEN_FDS -> Environment variable with number of passed FDs.
• LISTEN_PID -> PID that the descriptors are intended for.
• SD_LISTEN_FDS_START -> First FD number (3).
• Accept -> socket unit setting controlling per-connection behavior.

Mental model diagram (ASCII)

client -> systemd socket (listening)
               |
               +--> starts service
                        |
                        +--> service accepts on FD 3

How it works (step-by-step)

1. systemd opens the listening socket(s).
2. Client connects, systemd decides to start service.
3. Service receives FDs at 3..3+N-1 with LISTEN_FDS set.
4. Service validates FDs and accepts connections.
5. Service handles requests and exits or stays running.

Invariants: FD 3 is the first passed socket; LISTEN_PID matches the service PID.
Failure modes: service started manually (no FDs), invalid socket types, or premature FD close.

Minimal concrete example

int n = sd_listen_fds(0);
if (n < 1) exit(3);
for (int i = 0; i < n; i++) {
    int fd = SD_LISTEN_FDS_START + i;
    /* accept on fd */
}

Common misconceptions

• “The service should bind() anyway” -> It must use passed sockets instead.
• “FDs always start at 0” -> They start at 3 by contract.
• “LISTEN_FDS is always set” -> Only when systemd starts the service.

Check-your-understanding questions

1. Why do passed sockets start at FD 3?
2. What happens if you run the service manually?
3. Why should you check LISTEN_PID?
4. How do you handle multiple FDs?

Check-your-understanding answers

1. FDs 0-2 are reserved for stdin/out/err.
2. No sockets are passed; the service should error out or self-bind.
3. To ensure the FDs belong to the current process.
4. Iterate from FD 3 through FD 3+LISTEN_FDS-1.

Real-world applications

• On-demand daemons that reduce boot time.
• Zero-downtime restarts of network services.

Where you’ll apply it

• This project: Section 3.2, Section 4.4, Section 5.10 Phase 2.
• Also used in: P01-service-health-dashboard.md to detect socket-activated units.

References

• systemd.socket manual.
• sd_listen_fds documentation.

Key insights

Socket activation shifts listening responsibility from your app to systemd.

Summary

If you honor the socket activation contract, your service starts on demand and stays resilient.

Homework/exercises to practice the concept

1. Create a .socket unit and log LISTEN_FDS in the service.
2. Start the service manually and confirm LISTEN_FDS=0.
3. Validate sockets with sd_is_socket_inet.

Solutions to the homework/exercises

1. Print the environment variable at startup.
2. Run the binary directly; LISTEN_FDS will be empty.
3. Call sd_is_socket_inet(fd, AF_INET, SOCK_STREAM, 1).

---

Concept 2: Accept Modes and Concurrency Models

Fundamentals

Accept mode determines who accepts connections and how services scale. With Accept=no, systemd passes the listening socket to one service process that handles all connections. With Accept=yes, systemd accepts connections itself and starts a new service instance per connection, passing a connected socket. Accept mode directly impacts concurrency, performance, and isolation. If you choose Accept=no, you must implement a concurrency strategy (threads, fork, or event-driven). If you choose Accept=yes, you must ensure the service handles exactly one connection and exits cleanly. The choice also affects observability and logging patterns.

Deep Dive into the Concept

Accept=no is the common choice for high-throughput servers. The service owns the listening socket and can decide how to handle concurrency: a single-threaded loop, a thread pool, or an event loop with epoll. Event-driven designs scale well to many concurrent clients with low overhead. The downside is complexity: you must handle partial reads, timeouts, and backpressure. If you block in a read, you can stall the server unless you use non-blocking I/O.

Accept=yes is the classic inetd-style model. systemd accepts each connection and starts a new service instance. This is simple and isolates clients, but it is expensive under load because each connection creates a new process. It is suitable for low-traffic services or for programs that are not written to be concurrent. You can use service@.service templates to configure per-connection limits and logging. However, you must be careful about resource exhaustion: an attacker can open many connections and force many processes to spawn. Use systemd rate limits or socket options to mitigate this.

The two modes also affect logging and service names. With Accept=yes, each connection creates an instance unit like myservice@12345.service. Your logging and status queries must account for instance names. With Accept=no, there is one service unit, making logs and status simpler.

Another trade-off is resource control. With Accept=yes, you can apply per-connection resource limits using template unit properties such as MemoryMax or CPUQuota. With Accept=no, you must implement resource limits inside your process or rely on OS-wide limits. Accept=yes also interacts with systemd rate limits: you can cap the number of instances or throttle activation, which protects against overload or abuse. If you implement Accept=no with an event loop, you should implement explicit connection limits and timeouts to avoid slow-client resource exhaustion. These operational details often matter more than raw throughput in production.

A key design decision is whether you want to implement concurrency in your own code or outsource it to systemd. For this project, implement both or at least understand the trade-offs. You can implement Accept=no with a simple single-threaded loop for learning, then extend to epoll for concurrency. If you choose Accept=yes, implement a per-connection protocol and ensure the process exits after serving one request.

How this fit on projects

Accept mode determines your architecture. You will decide it in Section 3.2 (Functional Requirements) and implement it in Section 4.4 and Section 5.10 Phase 2.

Definitions & key terms

• Accept=yes -> systemd spawns one instance per connection.
• Accept=no -> service process handles all connections.
• Event loop -> Non-blocking I/O with epoll or select.
• Backpressure -> Limiting acceptance to avoid overload.

Mental model diagram (ASCII)

Accept=no:
client -> listening socket -> server process -> threads/epoll

Accept=yes:
client -> systemd accept -> per-connection service

How it works (step-by-step)

1. systemd receives a connection.
2. If Accept=yes, it accepts and spawns a service instance.
3. If Accept=no, it starts the service (once) and passes the listening socket.
4. The service handles one or many clients based on its model.

Invariants: Accept=yes services handle a single connection; Accept=no services own the listener.
Failure modes: process storms under load, blocking I/O causing stalls, or connection leaks.

Minimal concrete example

# socket unit
[Socket]
ListenStream=9999
Accept=no

Common misconceptions

• “Accept=yes is always better” -> It can be slow and expensive at scale.
• “Accept=no is too complex” -> A simple event loop is manageable.

Check-your-understanding questions

1. Which mode is closer to inetd?
2. Which mode is better for high concurrency?
3. Why might Accept=yes be safer for untrusted clients?

Check-your-understanding answers

1. Accept=yes.
2. Accept=no with an event loop.
3. Each connection is isolated in its own process.

Real-world applications

• SSH and legacy services often use per-connection models.
• HTTP servers use Accept=no with event loops.

Where you’ll apply it

• This project: Section 3.2, Section 4.4, Section 5.10 Phase 2.
• Also used in: P05-systemd-controlled-development-environment-manager.md for template unit concepts.

References

• systemd.socket documentation (Accept= section).
• “UNIX Network Programming” (server models).

Key insights

Accept mode is a design decision that defines your server’s concurrency strategy.

Summary

Choose Accept mode deliberately and implement a concurrency model that matches it.

Homework/exercises to practice the concept

1. Implement Accept=no with a single-threaded loop.
2. Switch to Accept=yes and compare resource usage.
3. Measure latency under 100 concurrent connections.

Solutions to the homework/exercises

1. Accept connections and echo responses in one process.
2. Configure a template service and observe instance units.
3. Use wrk or ab and compare results.

---

Concept 3: File Descriptor Lifecycle and Safety

Fundamentals

File descriptors (FDs) are references to kernel objects. In socket activation, systemd passes open FDs to your service. If you close the listening FD, you break activation; if you leak it to child processes, the socket might never close. Understanding FD inheritance, FD_CLOEXEC, and ownership is critical for correctness and security. You must also validate that the FDs are actually sockets of the expected type. Proper FD hygiene prevents subtle bugs that are hard to debug in production, and it helps you avoid hitting per-process FD limits under load.

Deep Dive into the Concept

FDs are inherited across fork() and exec() unless marked with FD_CLOEXEC. systemd intentionally leaves passed sockets open across exec to deliver them to your service. Once you receive them, you must decide ownership. The listening socket should remain open in the main server process. If you spawn workers, you should close the listening socket in children or set FD_CLOEXEC before exec so they do not inherit it. Otherwise, the socket may remain open after the server exits, preventing systemd from reclaiming it.

For Accept=yes, each service instance receives a connected socket, not a listening socket. In that case, the service should close all unrelated FDs and operate on the connected socket only. This is safer and avoids leaking file descriptors into the service.

Validation is important. Use sd_is_socket() or sd_is_socket_inet() to confirm that the FD is a socket, that it is in listening mode, and that it matches the expected address family. If the FD is not what you expect, you should exit with a clear error. This prevents misbehavior and potential security issues.

Shutdown behavior also depends on FD management. If you want a graceful shutdown, you should stop accepting new connections, close the listening socket, and finish existing clients with a timeout. But because systemd owns the listening socket, you must coordinate with it: you can close the FD and exit, but systemd will re-open the socket when the service restarts. If you want to keep the socket available during restart, do not close it prematurely.

Another subtlety: non-blocking mode. If systemd passes sockets, they may not have the flags you expect. Your service should set or verify flags like non-blocking mode and SO_REUSEADDR where appropriate. This ensures predictable behavior.

There are additional operational details. Inspecting /proc/self/fd at startup helps you confirm which descriptors are open and can reveal leaks. If you use an event loop, you should set non-blocking mode and use edge-triggered or level-triggered semantics consistently; otherwise, you may miss events or spin. When shutting down, close client sockets first, then stop accepting new connections, then exit. This order prevents dropped responses. If you log connection details, ensure that you do not log from signal handlers or other unsafe contexts. These practices make your server robust under load and during graceful shutdown.

How this fit on projects

FD hygiene is required for correctness and reliability. You will apply it in Section 4.2 (Key Components), Section 5.10 Phase 2, and Section 7.

Definitions & key terms

• FD_CLOEXEC -> Close FD on exec to prevent inheritance.
• Ownership -> Which process is responsible for closing an FD.
• Leak -> FD left open in unintended processes.
• Non-blocking -> I/O mode that does not block the event loop.

Mental model diagram (ASCII)

systemd -> FD 3 (listening)
  |
  +-- exec service
         |
         +-- accept -> FD 4 (client)

How it works (step-by-step)

1. systemd passes listening FD(s) to the service.
2. Service validates FD types and modes.
3. Service accepts connections and creates client FDs.
4. Client FDs are closed after use; listening FD stays open.

Invariants: Passed FDs are owned by the service; each client FD is closed exactly once.
Failure modes: FD leaks, accidental close of listener, or wrong FD type.

Minimal concrete example

int flags = fcntl(fd, F_GETFD);
fcntl(fd, F_SETFD, flags | FD_CLOEXEC);

Common misconceptions

• “Closing FD 3 is harmless” -> It breaks socket activation.
• “FD leaks do not matter” -> They keep sockets open forever.
• “Flags are already correct” -> Always verify non-blocking and close-on-exec.

Check-your-understanding questions

1. Why set FD_CLOEXEC before exec?
2. What happens if the listening FD is leaked to a child?
3. Why validate socket type?

Check-your-understanding answers

1. It prevents unintended inheritance of FDs.
2. The socket may stay open after the server exits.
3. To avoid reading from the wrong object or being tricked.

Real-world applications

• Secure network daemons.
• On-demand services with zero-downtime restarts.

Where you’ll apply it

• This project: Section 4.2, Section 5.10 Phase 2, Section 7.
• Also used in: P02-mini-process-supervisor.md for FD inheritance control.

References

• man 2 fcntl, man 2 accept, systemd socket activation docs.

Key insights

Correct FD hygiene is the difference between a reliable server and a flaky one.

Summary

Validate, manage, and close FDs deliberately to keep socket activation reliable.

Homework/exercises to practice the concept

1. Log all open FDs at startup.
2. Fork a worker and confirm it does not inherit the listener.
3. Check socket type with sd_is_socket_inet().

Solutions to the homework/exercises

1. Iterate /proc/self/fd and print entries.
2. Close the listening FD in the child or set FD_CLOEXEC.
3. Call sd_is_socket_inet(fd, AF_INET, SOCK_STREAM, 1).

---

Concept 4: Socket and Service Unit Semantics for Activation

Fundamentals

Socket activation is not just about passing file descriptors; it is about how two unit types coordinate through unit file semantics. A .socket unit defines the listening endpoint and activation behavior, while a .service unit defines the process that will handle connections. The Accept= setting determines whether systemd spawns one service per connection or a single service to handle all connections. The Service= directive wires a socket to its service, and unit installation (WantedBy, Also) determines how these units are enabled. If you do not understand these semantics, you will build a server that works in isolation but fails to integrate with systemd properly. For this project, the unit files are part of the deliverable, so you must understand what each field does and how it affects activation behavior.

Deep Dive into the Concept

A socket unit is a first-class systemd object that can exist without its service being active. It declares the listening address (ListenStream, ListenDatagram, ListenFIFO), optional access control (SocketUser, SocketGroup, SocketMode), and activation mode (Accept=yes/no). When a socket unit is started, systemd opens the listening socket and begins to accept connections. If the matching service is not running, systemd activates it when a connection arrives. The socket unit continues to own the listening socket even if the service exits, which is why socket activation can keep ports bound across restarts.

The Accept= setting defines how activation is handled. With Accept=no (the default for stream sockets), systemd passes the listening socket to a single service instance. The service is expected to accept and handle multiple connections. With Accept=yes, systemd accepts the connection itself and passes the connected socket to a new instance of the service. The service instance name includes the connection identifier (e.g., myecho@123.service). This mode is useful for short-lived per-connection handlers, but it creates more process churn and is less efficient for high-traffic servers. The decision affects your server design: with Accept=no, you need an accept loop; with Accept=yes, you must handle a single connection and exit.

The Service= directive links a socket unit to its service. If omitted, systemd will use a default service name derived from the socket unit (e.g., myecho.socket -> myecho.service). You can override this to point to a different service, which is useful for reuse or templating. When Accept=yes, the service should typically be a template unit (myecho@.service) because each connection spawns a new instance. When Accept=no, the service is a regular unit.

Unit installation semantics are often misunderstood. systemctl enable myecho.socket creates symlinks under the target you specify (often sockets.target), which ensures the socket is started at boot. Enabling the service unit is optional; for socket-activated services, the socket is the primary unit to enable. The Also= directive can ensure that enabling one unit enables its counterpart. For instance, you can set Also=myecho.service in the socket unit so both are enabled together. This is operationally helpful because it reduces the chance of misconfiguration.

Ordering and dependencies also matter. If your socket depends on network availability, you may add After=network.target to the socket unit. However, because network.target is a weak synchronization point, you might prefer After=network-online.target when appropriate. But that can delay boot and is sometimes undesirable. The practical rule is: use the minimal ordering needed for the listen address to be valid. For local Unix sockets, you may need After=local-fs.target so the filesystem path exists.

There are also security-related settings. Socket units can apply SocketUser, SocketGroup, and SocketMode to control permissions. Service units can run under a restricted user and use PrivateTmp, NoNewPrivileges, or ProtectSystem to harden the runtime. In a socket-activated design, the socket can be privileged (e.g., bound to port 80) while the service runs as an unprivileged user. systemd can pass the socket to the service with correct ownership, letting you avoid root in the service process. This separation is a core benefit of socket activation and should be emphasized in your design.

Finally, activation semantics affect observability and debugging. Because the socket stays active even if the service is down, tools like ss -tlnp will show the port as listening even when the service has crashed. Your tooling must interpret this correctly. In practice, you should use systemctl status myecho.socket to see if the listener is active and systemctl status myecho.service to check the worker process. This duality is a critical operational concept: socket state and service state are related but not identical.

How this fit on projects

This concept is central to your unit file design and activation flow. You will apply it in Section 3.2 (Functional Requirements: unit behaviors), Section 4.2 (Key Components: socket and service units), and Section 5.2 (Project Structure: unit files). It also informs the edge cases in Section 3.6.

Definitions & key terms

• Socket unit -> Unit that defines and listens on an IPC endpoint.
• Service unit -> Unit that defines the process handling requests.
• Accept -> Whether systemd spawns per-connection service instances.
• Service= -> Socket unit directive linking to the service.
• sockets.target -> Default target for enabling socket units.

Mental model diagram (ASCII)

myecho.socket (listening)
   |
   +-- connection --> systemd accepts (Accept=yes)
   |                 -> myecho@123.service
   |
   +-- connection --> myecho.service accepts (Accept=no)

How it works (step-by-step)

1. Start myecho.socket to bind the listen address.
2. On incoming connection, systemd activates myecho.service.
3. With Accept=no, service accepts on the listening socket.
4. With Accept=yes, systemd passes a connected socket to a new instance.
5. The socket remains open even if the service exits.

Invariants: The socket unit owns the listening socket; services are transient.
Failure modes: Service crashes but socket keeps accepting; wrong Accept mode causes protocol confusion.

Minimal concrete example

# myecho.socket
[Socket]
ListenStream=9999
Accept=no

[Install]
WantedBy=sockets.target

Common misconceptions

• “Enabling the service is required” -> For socket activation, the socket is the primary unit.
• “Accept=yes is always better” -> It is simpler but less efficient for high traffic.
• “A listening port means the service is running” -> The socket can listen even if the service is down.

Check-your-understanding questions

1. What does Accept=yes change about your server implementation?
2. Why might you add Also=myecho.service to a socket unit?
3. How can a privileged port be served by an unprivileged process?
4. What happens if the service crashes while the socket remains active?

Check-your-understanding answers

1. The server handles a single connection and exits; systemd accepts connections.
2. It enables both units together to avoid configuration drift.
3. systemd binds the socket as root and passes it to the service.
4. New connections still activate the service; the socket stays bound.

Real-world applications

• On-demand activation for rarely used services (cups, ssh).
• Privileged port binding with unprivileged worker processes.
• Scalable per-connection service instances for short-lived protocols.

Where you’ll apply it

• This project: Section 3.2, Section 4.2, Section 5.2, Section 3.6.
• Also used in: P05-systemd-controlled-development-environment-manager.md for user service unit wiring.

References

• systemd.socket(5) and systemd.service(5).
• “systemd for Administrators” guides (socket activation chapters).

Key insights

Socket activation is a unit-to-unit contract; your server behavior must match the unit semantics.

Summary

Understanding socket and service unit semantics lets you build activation flows that are correct, secure, and predictable.

Homework/exercises to practice the concept

1. Create both Accept=yes and Accept=no units and compare behavior.
2. Add Also= to your socket unit and verify enablement.
3. Configure a Unix domain socket with custom permissions.

Solutions to the homework/exercises

1. With Accept=yes, each connection spawns a service instance; Accept=no uses one process.
2. systemctl enable myecho.socket should also enable the service.
3. Use ListenStream=/run/myecho.sock and SocketMode=0660.

3. Project Specification

3.1 What You Will Build

A socket-activated echo or tiny HTTP server that:

• Starts on demand via a .socket unit.
• Consumes systemd-passed sockets.
• Handles multiple clients correctly.
• Logs connection details to journald.

Included: socket activation, concurrency model, simple protocol.
Excluded: TLS, authentication, advanced routing.

3.2 Functional Requirements

1. Socket Unit: .socket file with ListenStream and Accept mode.
2. Service Unit: .service that reads LISTEN_FDS and LISTEN_PID.
3. Server Loop: Accepts connections and responds with echo or HTTP.
4. Logging: Log client IP and bytes transferred.
5. Graceful Shutdown: Handle SIGTERM and close clients.

3.3 Non-Functional Requirements

• Performance: Handle 100 concurrent connections without crashing.
• Reliability: Restarts do not drop the listening socket.
• Usability: Clear logs on startup and shutdown.

3.4 Example Usage / Output

$ systemctl start myecho.socket
$ nc localhost 9999
hello
HELLO

3.5 Data Formats / Schemas / Protocols

Echo protocol: raw bytes, newline-terminated.
HTTP mode (optional):

GET /health HTTP/1.1
Host: localhost

HTTP/1.1 200 OK
Content-Type: text/plain

OK

3.6 Edge Cases

• Service started manually -> no LISTEN_FDS.
• Multiple FDs passed (IPv4 and IPv6).
• Slow clients causing blocking.

3.7 Real World Outcome

3.7.1 How to Run (Copy/Paste)

sudo cp myecho.socket /etc/systemd/system/
sudo cp myecho.service /etc/systemd/system/

sudo systemctl daemon-reload
sudo systemctl enable --now myecho.socket

3.7.2 Golden Path Demo (Deterministic)

• Use fixed port 9999 and fixed response HELLO.
• Keep one client connection for a deterministic transcript.

3.7.3 If CLI: exact terminal transcript

$ systemctl start myecho.socket
$ nc localhost 9999
hello
HELLO

Failure demo:

$ ./myecho
ERROR: no socket passed (LISTEN_FDS=0)
exit code: 3

Exit codes:

• 0 success
• 2 usage error
• 3 not socket-activated
• 4 listen FD invalid

---

4. Solution Architecture

4.1 High-Level Design

client -> systemd socket -> server loop -> response

4.2 Key Components

Component	Responsibility	Key Decisions
Socket Unit	Define ListenStream and Accept	Accept=yes vs Accept=no
Service Loop	Accept and handle connections	threaded vs event-driven
Logger	Record connections	stdout to journald

4.3 Data Structures (No Full Code)

struct Conn {
    int fd;
    struct sockaddr_storage addr;
    size_t bytes_read;
};

4.4 Algorithm Overview

Key Algorithm: Connection Handling

1. Read LISTEN_FDS and validate.
2. Accept connection(s).
3. Read input, write response.
4. Close connection.

Complexity Analysis:

• Time: O(N) per connection for echo
• Space: O(1) per connection

---

5. Implementation Guide

5.1 Development Environment Setup

sudo apt-get install -y build-essential libsystemd-dev

5.2 Project Structure

myecho/
├── src/
│   ├── main.c
│   └── server.c
├── units/
│   ├── myecho.socket
│   └── myecho.service
└── Makefile

5.3 The Core Question You’re Answering

“How can a service be started only when a connection arrives?”

5.4 Concepts You Must Understand First

1. Socket activation contract.
2. Accept modes and concurrency.
3. FD lifecycle and safety.

5.5 Questions to Guide Your Design

1. How will you handle slow or malicious clients?
2. Should you support multiple ListenStream sockets?
3. What should happen if LISTEN_FDS > 1?

5.6 Thinking Exercise

Draw the timeline of a client connecting to a socket-activated service and identify which process owns the FD at each step.

5.7 The Interview Questions They’ll Ask

1. “What is LISTEN_FDS?”
2. “Why do socket-activated services start on demand?”
3. “What is the difference between Accept=yes and Accept=no?”

5.8 Hints in Layers

Hint 1: Implement a normal echo server first.
Hint 2: Replace bind/listen with sd_listen_fds().
Hint 3: Add .socket and .service units.
Hint 4: Add Accept mode options.

5.9 Books That Will Help

Topic	Book	Chapter
Sockets	“TCP/IP Sockets in C”	Ch. 2-4
System programming	“The Linux Programming Interface”	IPC chapters
Networking	“UNIX Network Programming”	server models

5.10 Implementation Phases

Phase 1: Foundation (2-3 hours)

Goals: simple echo server.
Checkpoint: server works when run manually.

Phase 2: Socket Activation (3-5 hours)

Goals: consume FD 3 and use socket unit.
Checkpoint: service starts only on connection.

Phase 3: Concurrency and polish (2-4 hours)

Goals: handle multiple clients, add logging.
Checkpoint: 100 concurrent connections succeed.

5.11 Key Implementation Decisions

Decision	Options	Recommendation	Rationale
Accept mode	yes/no	no	more efficient for concurrency
Concurrency	threads vs event loop	event loop	lower overhead

---

6. Testing Strategy

6.1 Test Categories

| Category | Purpose | Examples | |———|———|———-| | Unit Tests | FD validation | invalid LISTEN_FDS | | Integration Tests | systemd units | socket activation works | | Load Tests | concurrency | 100 connections |

6.2 Critical Test Cases

1. Service started manually returns error.
2. Accept=no handles multiple clients.
3. IPv4 and IPv6 sockets both accepted.

6.3 Test Data

Input: "hello\n" -> Output: "HELLO\n"

---

7. Common Pitfalls and Debugging

7.1 Frequent Mistakes

| Pitfall | Symptom | Solution | |——–|———|———-| | Forgetting LISTEN_PID | invalid socket error | verify LISTEN_PID == getpid() | | Blocking accept loop | hangs under load | use non-blocking + epoll | | Closing listening FD | socket no longer works | keep FD open until exit |

7.2 Debugging Strategies

• systemctl status myecho.socket to confirm listener.
• ss -tlnp to verify listening port.

7.3 Performance Traps

Using Accept=yes under high load creates too many processes.

---

8. Extensions and Challenges

8.1 Beginner Extensions

• Add a --upper flag for uppercase responses.
• Add a connection count in logs.

8.2 Intermediate Extensions

• Add HTTP mode with /health endpoint.
• Add request logging with latency.

8.3 Advanced Extensions

• Add TLS termination with stunnel or openssl.
• Add per-connection resource limits with templates.

---

9. Real-World Connections

9.1 Industry Applications

• On-demand API endpoints and internal tools.
• Low-memory embedded devices.

9.2 Related Open Source Projects

• systemd socket activation examples.
• inetd/xinetd (historical reference).

9.3 Interview Relevance

• Explain socket activation and FD passing clearly.

---

10. Resources

10.1 Essential Reading

• systemd socket activation docs.
• “UNIX Network Programming” (concurrency chapters).

10.2 Video Resources

• systemd talks on activation models.

10.3 Tools and Documentation

• systemctl, journalctl, ss.

10.4 Related Projects in This Series

• P01-service-health-dashboard.md for socket-activated states.
• P04-automated-backup-system-with-timers.md for activation parallels.

---

11. Self-Assessment Checklist

11.1 Understanding

• I can explain socket activation without notes.
• I can describe Accept=yes vs Accept=no.
• I can explain FD inheritance risks.

11.2 Implementation

• Socket unit starts service on demand.
• Server handles multiple clients.
• Logs show connection info.

11.3 Growth

• I can describe improvements for production readiness.

---

12. Submission / Completion Criteria

Minimum Viable Completion:

• Socket activation works for one client.
• Service handles at least one echo request.

Full Completion:

• Concurrency model implemented and tested.
• Logs and error handling are clean.

Excellence (Going Above and Beyond):

• Dual IPv4/IPv6 sockets and optional HTTP mode.