---

name: Nawin description: 9P2000 protocol implementation for .NET - connect to 9front/Plan9, serve files, CPU remote shell, authentication servers

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:

1. Project Location: The codebase is at /home/matt/Git/Nawin
2. Running Tools: Use dotnet run --project Nawin.<Project> to run tools
3. Privileged Ports: Port 564 requires root. Use sudo $(which dotnet) run or use a high port like 5640
4. Authentication: Support for none, simple:user:pass, p9sk1 (Plan 9), and dp9ik (9front modern)
5. 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

dotnet run --project Nawin.Serve -- [options] <directory>

Options:
  -p, --port <port>      Port to listen on (default: 564)
  -a, --address <addr>   Address to bind (default: 0.0.0.0)
  --auth <type>          Auth: none, simple:user:pass (default: none)

Nawin.Cli Options

dotnet run --project Nawin.Cli -- [options] <command> [args]

Options:
  -H, --host <host>      Server hostname (default: localhost)
  -P, --port <port>      Server port (default: 564)
  -u, --user <user>      Username
  -p, --password <pass>  Password
  -a, --auth <type>      Auth: none, simple, p9sk1, dp9ik
  --authserver <h:p>     Auth server for p9sk1/dp9ik
  --aname <name>         Attach name (file tree)

Commands:
  ls [-l] <path>         List directory
  cat <path>             Read file
  write <path> <text>    Write to file
  stat <path>            Show file metadata
  mkdir <path>           Create directory
  rm <path>              Remove file/directory
  cp [-r] <src> <dst>    Copy (: prefix for remote)
  mount [-f] <path>      Mount filesystem
  shell                  Interactive shell

Nawin.Cpu Options

dotnet run --project Nawin.Cpu -- [options] [command]

Options:
  --host <host>          CPU server hostname
  --port <port>          CPU server port (default: 17010)
  -u, --user <user>      Username
  -P, --password <pass>  Password
  --protocol <proto>     Auth: p9sk1, dp9ik
  -e, --export <dir>     Export local directory to remote
  --jerq                 Enable graphics mode

Testing with 9front

The local 9front VM (barn) can be started with:

/opt/isos/9front.sh

9front source code is available at:

/mnt/  # When /opt/isos/9front-11321.amd64.iso is mounted

CPU into 9front with local auth server:

dotnet run --project Nawin.Cpu -- --host localhost --port 17019 --user glenda --password test1234 --protocol p9sk1 "command"

Troubleshooting

"dotnet: command not found" with sudo

# Use full path
sudo $(which dotnet) run --project Nawin.Serve

# Or preserve PATH
sudo env "PATH=$PATH" dotnet run --project Nawin.Serve

Permission denied on port 564

Use a high port or grant capability:

# Option 1: Use high port
dotnet run --project Nawin.Serve -- -p 5640 .

# Option 2: Grant capability to published binary
dotnet publish -c Release Nawin.Serve
sudo setcap 'cap_net_bind_service=+ep' ./Nawin.Serve/bin/Release/net9.0/publish/Nawin.Serve

Auth server not running

sudo systemctl restart nawin-auth && sleep 2 && systemctl status nawin-auth 2>&1 | head -15