Distributed Text File System — Quickstart

This tree builds three binaries:

• name_server/ns_main
• storage_server/ss_main
• client/client_main

Each process persists state in its own working directory (files, metadata, logs, sockets). Launch every Name Server, Storage Server, and Client from separate directories—never share one directory or port pair between processes.

NOTE: All code was AI-generated. This has been included here to ommit the need for adding headers everywhere. The development process involved high level and low level design docs written by us. All system design choices were made by us.

repo/
  name_server/
  storage_server/
  client/
ns_1/      # run ns_main here
ss_1/      # run storage server #1 here
ss_2/
client_1/

Behavioral notes (TA guidance applied)

• EXEC commands run the fetched file via /bin/sh without sandboxing or enforced time/CPU/memory limits; output is streamed back verbatim. Safety was declared out of scope by the TAs.
• INFO <filename> is deliberately allowed for any logged-in user (matching the ambiguity in VIEW -a); ACLs are still enforced for READ/WRITE/STREAM/UNDO/EXEC tickets.
• Name Server logs every RX/TX with opcode name, corr_id, flags, status, and peer addresses by default to logs/ns.log plus stdout; no env toggle is needed.

Build

From the repo root:

make          # builds everything (proto regeneration happens automatically)

The shipped binaries already embed the generated protobuf stubs (proto/libnfsproto.a) and link statically, so running ns_main, ss_main, or client_main does not require protobuf-c on the target machine. If you want to clean-build from sources on a new box, install the compiler plugin once:

sudo apt-get update
sudo apt-get install protobuf-c-compiler libprotobuf-c-dev

That pulls in protoc-c (used by make proto) and the headers/libraries needed for recompilation on Linux, which is the grading OS.

Name Server (name_server/ns_main)

Launch the Name Server from a dedicated working directory (e.g., ns_1/). The process creates data/, logs/, run/, and tmp/ under its root.

mkdir ns_1
cd ns_1
../name_server/ns_main --client-port 7000 --ss-port 7001

CLI Flags

Flag	Argument	Description
--root-dir	<path>	Override the root used for data/, logs/, run/, tmp/. Defaults to name_server. When this is set, all sub directories are automatically re-derived.
--data-dir	<path>	Store snapshots/journals in this directory (default <root>/data).
--log-file	<file>	Path to ns.log (default <root>/logs/ns.log).
--snapshot	<file>	Snapshot file path (ns_state.bin).
--journal	<file>	WAL path (ns_journal.log).
--client-port	<port>	TCP port for Client⇄NS control (default 7000).
--ss-port	<port>	TCP port for Storage-Server control (default 7001).
--help	(none)	Print usage/exit.

Flag priority: defaults → environment variables (below) → CLI flags.

Environment Variables

You can tune runtime behavior without recompiling:

Variable	Purpose
NS_HEARTBEAT_INTERVAL	Override expected SS heartbeat period (seconds). Workers mark a server unhealthy if it is silent for NS_HEARTBEAT_MISSES * NS_HEARTBEAT_INTERVAL.
NS_HEARTBEAT_MISSES	Number of missed heartbeats tolerated before a server is treated as unavailable.
HEARTBEAT	Shortcut that sets both the interval and timeout (timeout = 2 × HEARTBEAT). Retained for compatibility; NS_HEARTBEAT_* is preferred.
NS_LOG_PERSISTENT	When compiled without -DNS_LOG_PERSISTENT=1, log files truncate on start. Exporting NS_LOG_PERSISTENT=1 forces append-only logging without recompiling.

Storage Server Environment Variables

ss_main calls apply_env_overrides during initialization, so the following variables are read before CLI parsing. All are optional; any CLI flag overrides the environment value.

   mkdir ss_1
   cd ss_1
   ../storage_server/ss_main --client-port 7300 --control-port 7301

   mkdir ss_2
   cd ss_2
   ../storage_server/ss_main --client-port 7400 --control-port 7401

Variable	Default	Purpose
SS_NS_HOST	127.0.0.1	Hostname / IP of the Name Server’s SS-control listener
SS_NS_PORT	7001	TCP port of the Name Server’s SS-control listener
SS_CLIENT_ADDR	0.0.0.0	Bind address for the SS client listener
SS_CLIENT_PORT	7200	Bind port for the SS client listener
SS_CONTROL_ADDR	0.0.0.0	Local address used when dialing the NS control socket
SS_CONTROL_PORT	auto-assigned	Local source port when dialing the NS control socket (set to pin)
SS_DATA_ROOT	. (cwd)	Root directory for per-file data and metadata
SS_LOG_DIR	$SS_DATA_ROOT/logs	Directory where ss.log is written
HEARTBEAT	5 (seconds)	Interval between NS heartbeats (read directly in runtime.c)

Logging persistence is controlled at compile time via SS_LOG_PERSISTENT (storage_server/src/log.c): set it to 0 to truncate ss.log on startup, 1 to append (default).

Storage Server CLI Flags

Long-form flags mirror the same settings and take precedence over env vars:

Flag	Argument	Meaning
--ns-host	<host>	Override Name Server host
--ns-port	<port>	Override Name Server port
--client-addr	<addr>	Bind address for SS client listener
--client-port	<port>	Bind port for SS client listener
--control-addr	<addr>	Local address used when dialing NS control
--control-port	<port>	Local source port when dialing NS control
--data-root	<path>	Filesystem root for the server’s data
--log-dir	<path>	Directory for ss.log
--help	(none)	Print usage and exit

Evaluation order: defaults → environment variables → CLI flags.

Client (client/client_main)

Launch each client from its own working directory (e.g., client_1/). The binary keeps its session log (client.log by default) alongside any scratch files created by your workflow:

mkdir c_1
cd c_1
../client/client_main -H 127.0.0.1 -P 7000

CLI Flags

Flag / Option	Argument	Description
-H, --ns-host	<host>	Name Server host (default 127.0.0.1).
-P, --ns-port	<port>	Name Server TCP port (default 7000).
-L, --log-file	<path>	Log file path (default client.log in the working directory).
-h, --help	(none)	Print usage and exit.

The flags override built-in defaults. Run client_main --help inside a client directory for an up-to-date synopsis.

Environment Variables

Variable	Purpose
CLI_LOG_PERSISTENT	Set to a truthy value (e.g., 1, true, yes, on) to preserve existing logs and append new entries. Unset, empty, or explicit “falsey” values (0, false, no, off) keep the default behavior: truncate the log once at startup for a clean run. Logs are never removed on shutdown or crash.

Run Order

1. Build: make (repo root).
2. Name Server: in its own directory (e.g., ns_1/):

   ../name_server/ns_main --client-port 7000 --ss-port 7001
   

3. Storage Servers: each runs in an isolated directory (ss_1/, ss_2/, …) with unique client/control port pairs:

   ../storage_server/ss_main --client-port 7300 --control-port 7301
   ../storage_server/ss_main --client-port 7400 --control-port 7401
   

4. Client: in another directory (e.g., c_1/):

   ../client/client_main
   

Important: Never reuse a working directory or a client/control port pair between two storage servers. Each process owns its directory and ports for the lifetime of the run.

NOTE:

• only .txt files are supported.
• file name cannot have double/single quotes.