Nawin
Nawin is a .NET 9 implementation of the 9P2000 protocol for connecting Windows/Linux systems to 9front (Plan 9) file servers. It provides clients, servers, authentication, and CPU remote shell capabilities.
Instructions
When helping users with Nawin, follow these guidelines:
- Project Location: The codebase is at
/home/matt/Git/Nawin - Running Tools: Use
dotnet run --project Nawin.<Project>to run tools - Privileged Ports: Port 564 requires root. Use
sudo $(which dotnet) runor use a high port like 5640 - Authentication: Support for
none,simple:user:pass,p9sk1(Plan 9), anddp9ik(9front modern) - 9front Testing: CPU into 9front using the auth server at localhost:17019
Available Tools
| Project | Purpose | Default Port |
|---|---|---|
| Nawin.Cli | Interactive 9P client (ls, cat, mount, copy) | connects to 564 |
| Nawin.Serve | Serve local directories over 9P (U9FS replacement) | 564 |
| Nawin.Cpu | CPU client - remote shell with namespace export | 17010 |
| Nawin.CpuServer | Accept inbound CPU connections | 17010 |
| Nawin.Auth | Authentication server (p9sk1/dp9ik) | 567 |
| Nawin.Jerq | Graphics app with /dev/draw export | N/A |
Examples
Example 1: Serve a Directory (U9FS Replacement)
User: How do I share a directory over 9P?
Claude: Use Nawin.Serve to expose a local directory:
# Serve current directory on high port (no root needed)
dotnet run --project Nawin.Serve -- -p 5640 .
# Serve with simple auth
dotnet run --project Nawin.Serve -- -p 5640 --auth simple:matt:secret /home/matt/share
# On port 564 (requires root)
sudo $(which dotnet) run --project Nawin.Serve -- /home/matt/share
Example 2: Connect to 9front
User: How do I list files on a 9front server?
Claude: Use Nawin.Cli with dp9ik auth:
dotnet run --project Nawin.Cli -- -H 9front.local -u glenda -p password -a dp9ik ls /
# Read a file
dotnet run --project Nawin.Cli -- -H 9front.local -u glenda -p password -a dp9ik cat /lib/motd
# Copy file from remote
dotnet run --project Nawin.Cli -- -H 9front.local -u glenda -p password -a dp9ik cp :/etc/profile ./profile
Example 3: CPU into 9front
User: How do I get a remote shell on 9front?
Claude: Use Nawin.Cpu for Plan 9 style CPU connection:
# Interactive shell
dotnet run --project Nawin.Cpu -- --host 9front.local --user glenda --password secret --protocol dp9ik
# Run a command
dotnet run --project Nawin.Cpu -- --host 9front.local -u glenda -P secret --protocol dp9ik "cat /dev/sysname"
# With local auth server (p9sk1)
dotnet run --project Nawin.Cpu -- --host localhost --port 17019 --user glenda --password test1234 --protocol p9sk1 "echo hello"
Example 4: Run the Auth Server
User: How do I start the authentication server?
Claude: Nawin.Auth runs as a systemd service or manually:
# Check status
systemctl status nawin-auth
# Restart
sudo systemctl restart nawin-auth && sleep 2 && systemctl status nawin-auth 2>&1 | head -15
# Run manually
dotnet run --project Nawin.Auth -- serve --port 567 --authdom mydom --keys ~/.nawin/keys
# Manage users
dotnet run --project Nawin.Auth -- adduser glenda
dotnet run --project Nawin.Auth -- listusers
Example 5: Mount Remote Filesystem
User: Can I mount a 9P filesystem locally?
Claude: Yes, Nawin.Cli supports mounting via FUSE (Linux) or ProjFS (Windows):
# Linux (FUSE) - runs in foreground with -f
dotnet run --project Nawin.Cli -- -H 9front.local -u glenda -a dp9ik mount -f /mnt/9front
# Windows (ProjFS)
dotnet run --project Nawin.Cli -- -H 9front.local -u glenda -a dp9ik mount C:\9front
Reference Implementation Details
Project Structure
Nawin/
├── Nawin.Protocol/ # Wire format, message serialization, Qid/Stat types
├── Nawin.Transport/ # TCP connection, tag multiplexing
├── Nawin.Client/ # High-level client API, sessions, file handles
├── Nawin.Server/ # Server-side: listener, file tree interface
├── Nawin.Auth/ # p9sk1 and dp9ik authentication
├── Nawin.Cli/ # Command-line client
├── Nawin.Cpu/ # CPU client (rcpu equivalent)
├── Nawin.CpuServer/ # CPU server
├── Nawin.Serve/ # File server (U9FS replacement)
├── Nawin.Jerq/ # Graphics with /dev/draw export
├── Nawin.Mount.Linux/ # FUSE integration
├── Nawin.Mount.Windows/# ProjFS integration
└── Nawin.Tests/ # Unit and integration tests
Authentication Protocols
| Protocol | Description | Use Case |
|---|---|---|
none | No authentication | Trusted networks |
simple | Username/password (plaintext) | Simple setups |
p9sk1 | DES-based Plan 9 auth | Original Plan 9 |
dp9ik | ChaCha20-Poly1305 + PBKDF2 | Modern 9front |
Nawin.Serve Options
bash1dotnet run --project Nawin.Serve -- [options] <directory> 2 3Options: 4 -p, --port <port> Port to listen on (default: 564) 5 -a, --address <addr> Address to bind (default: 0.0.0.0) 6 --auth <type> Auth: none, simple:user:pass (default: none)
Nawin.Cli Options
bash1dotnet run --project Nawin.Cli -- [options] <command> [args] 2 3Options: 4 -H, --host <host> Server hostname (default: localhost) 5 -P, --port <port> Server port (default: 564) 6 -u, --user <user> Username 7 -p, --password <pass> Password 8 -a, --auth <type> Auth: none, simple, p9sk1, dp9ik 9 --authserver <h:p> Auth server for p9sk1/dp9ik 10 --aname <name> Attach name (file tree) 11 12Commands: 13 ls [-l] <path> List directory 14 cat <path> Read file 15 write <path> <text> Write to file 16 stat <path> Show file metadata 17 mkdir <path> Create directory 18 rm <path> Remove file/directory 19 cp [-r] <src> <dst> Copy (: prefix for remote) 20 mount [-f] <path> Mount filesystem 21 shell Interactive shell
Nawin.Cpu Options
bash1dotnet run --project Nawin.Cpu -- [options] [command] 2 3Options: 4 --host <host> CPU server hostname 5 --port <port> CPU server port (default: 17010) 6 -u, --user <user> Username 7 -P, --password <pass> Password 8 --protocol <proto> Auth: p9sk1, dp9ik 9 -e, --export <dir> Export local directory to remote 10 --jerq Enable graphics mode
Testing with 9front
The local 9front VM (barn) can be started with:
bash1/opt/isos/9front.sh
9front source code is available at:
bash1/mnt/ # When /opt/isos/9front-11321.amd64.iso is mounted
CPU into 9front with local auth server:
bash1dotnet run --project Nawin.Cpu -- --host localhost --port 17019 --user glenda --password test1234 --protocol p9sk1 "command"
Troubleshooting
"dotnet: command not found" with sudo
bash1# Use full path 2sudo $(which dotnet) run --project Nawin.Serve 3 4# Or preserve PATH 5sudo env "PATH=$PATH" dotnet run --project Nawin.Serve
Permission denied on port 564
Use a high port or grant capability:
bash1# Option 1: Use high port 2dotnet run --project Nawin.Serve -- -p 5640 . 3 4# Option 2: Grant capability to published binary 5dotnet publish -c Release Nawin.Serve 6sudo setcap 'cap_net_bind_service=+ep' ./Nawin.Serve/bin/Release/net9.0/publish/Nawin.Serve
Auth server not running
bash1sudo systemctl restart nawin-auth && sleep 2 && systemctl status nawin-auth 2>&1 | head -15
