Development Environment and Course Setup

# Development Environment and Course Setup

## CS 315 Computer Architecture

---

## Learning Objectives

- Explain why CS 315 uses remote RISC-V hardware and an optional local VM
- Describe how SSH public-key cryptography enables passwordless login
- Generate an Ed25519 SSH key pair and protect it with a passphrase
- Write an `~/.ssh/config` that connects through Stargate to a Beagle board
- Set correct file permissions and diagnose common SSH failures
- Configure GitHub SSH access from the Beagle machines

---

## The CS 315 Development Topology

Two paths to a RISC-V environment:

1. **Remote BeagleV-Ahead boards (required)** — five real RISC-V boards (`beagle1`–`beagle5`) behind the CS network
2. **Local RISC-V VM with QEMU (optional)** — convenient offline, not a substitute for Beagle

<div class="info-box">
Beagle boards are not directly reachable from the internet. You must hop through <strong>Stargate</strong>.
</div>

---

## Network Topology

<div class="mermaid">
flowchart LR
    subgraph You["Your Laptop"]
        L["Terminal\n(PRIVATE key)"]
    end
    subgraph CSnet["CS Department Network"]
        S["Stargate\nstargate.cs.usfca.edu\n(PUBLIC key)"]
        B1["beagle1"]
        B2["beagle2"]
        B3["beagle3"]
        B4["beagle4"]
        B5["beagle5"]
    end
    L -->|ssh| S
    S --> B1
    S --> B2
    S --> B3
    S --> B4
    S --> B5
</div>

---

## Key Topology Facts

- The **private key never leaves your laptop**
- Your **public key is copied to Stargate** (`~/.ssh/authorized_keys`)
- Stargate and all five Beagle machines **share the same home directory** (network filesystem)
- Configuring keys on Stargate makes them work on every Beagle board automatically
- Off campus: connect to **USF VPN** first

---

## Command Line Refresher: Reading the Prompt

```text
benson@m2a ~ %            # zsh on my laptop, home directory
[benson@stargate ~]$      # bash on Stargate, home directory
benson@beagle2:~$         # bash on a Beagle board, home directory
```

<div class="highlight-box">
Read the prompt before every command. The most common mistake is running a step on the wrong machine.
</div>

---

## Essential Shell Commands

```bash
pwd                 # print working directory
cd                  # go to home directory
ls -al              # long listing, shows dotfiles + permissions
mkdir cs315         # make a directory
cp src dst          # copy a file
mv old new          # move/rename a file
cat file            # dump file to screen
less file           # page through a file (q = quit)
chmod 600 *         # set permissions: owner read/write only
```

- `~` expands to your home directory (`~/.ssh/config`)
- Dotfiles (starting with `.`) are hidden — use `ls -al` to see them

---

## SSH and Public-Key Cryptography

| Half of the pair | Where it lives | Role |
|------------------|----------------|------|
| **Private key** (`id_ed25519_cs315_key`) | Your laptop only | Proves your identity; never share |
| **Public key** (`id_ed25519_cs315_key.pub`) | Copied to servers | Lets a server verify your private key |

The public key is like a padlock you hand out freely — only your private key can open it.

---

## SSH Authentication Flow

<div class="mermaid">
sequenceDiagram
    participant L as Laptop (private key)
    participant S as Stargate (authorized_keys)
    L->>S: I want to log in as benson
    S->>L: Challenge: prove you have the private key
    L->>L: Sign challenge with private key
    L->>S: Here is my signature
    S->>S: Verify with stored public key
    S->>L: Verified - session granted (no password)
</div>

---

## Key Passphrase vs Account Password

- **Account password** (CWID): authenticates to the OS — replaced by key auth
- **Key passphrase**: a *local* secret that decrypts your private key on your laptop — the server never sees it

<div class="info-box">
Use a long English sentence as your passphrase ("correct horse battery staple"). The SSH agent caches it after the first login, so you only type it once per session.
</div>

---

## Step-by-Step: SSH Key Setup

<div class="mermaid">
flowchart TD
    A["Step 1: ssh-keygen on laptop"] --> B["Step 2: edit ~/.ssh/config"]
    B --> C["Step 3: chmod 600 ~/.ssh/*"]
    C --> D["Step 4: scp .pub to Stargate"]
    D --> E["Step 5: cat .pub >> authorized_keys on Stargate"]
    E --> F["Step 6: ssh stargate — passphrase once"]
    F --> G["ssh stargate again — silent = success"]
</div>

---

## Step 1: Generate the Key Pair (ON YOUR LAPTOP)

```bash
cd ~/.ssh
ssh-keygen -t ed25519 -C "username@dons.usfca.edu" -f id_ed25519_cs315_key
```

| Flag | Meaning |
|------|---------|
| `-t ed25519` | Modern elliptic-curve algorithm |
| `-C "..."` | Comment label in the public key |
| `-f id_ed25519_cs315_key` | Output filename |

Result: two files — `id_ed25519_cs315_key` (private) and `id_ed25519_cs315_key.pub` (public)

---

## Step 2: Create the SSH Config (ON YOUR LAPTOP)

`~/.ssh/config`:

```text
IgnoreUnknown UseKeychain
UseKeychain yes

Host stargate
  HostName stargate.cs.usfca.edu
  AddKeysToAgent yes
  ForwardAgent yes
  IdentityFile ~/.ssh/id_ed25519_cs315_key
  User <your_username>
```

Now `ssh stargate` replaces the full command. `ForwardAgent yes` lets your GitHub key work after hopping to a Beagle board.

---

## Steps 3–5: Permissions and Copy

**Step 3: Fix permissions (ON YOUR LAPTOP)**
```bash
cd ~/.ssh && chmod 600 *
```

**Step 4: Copy public key to Stargate (ON YOUR LAPTOP)**
```bash
scp id_ed25519_cs315_key.pub <username>@stargate.cs.usfca.edu:.ssh
```

**Step 5: Authorize the key (ON STARGATE)**
```bash
ssh stargate          # still uses password this time
cd .ssh
cat id_ed25519_cs315_key.pub >> authorized_keys
chmod 600 *  &&  exit
```

<div class="highlight-box">
Use <code>>></code> (append), NOT <code>></code> (overwrite) — overwriting deletes existing keys!
</div>

---

## Step 6: Test It (ON YOUR LAPTOP)

```bash
ssh stargate   # First login: prompts for KEY PASSPHRASE
exit
ssh stargate   # Second login: silent = success
```

The silent second login confirms key auth is working. The SSH agent cached the passphrase — no more prompts this session.

---

## Reaching the Beagle Machines

**Method A: Two hops** (works immediately after Stargate setup)

```bash
ssh stargate
ssh beagle       # lands on one of beagle1...beagle5
```

**Method B: One hop with ProxyCommand (recommended)**

Add to `~/.ssh/config` on your laptop:
```text
Host beagle
  HostName beagle
  AddKeysToAgent yes
  ForwardAgent yes
  IdentityFile ~/.ssh/id_ed25519_cs315_key
  User <your_username>
  ProxyCommand ssh stargate -W %h:%p
```

Then: `ssh beagle` — one command, two hops, no second login.

---

## ProxyCommand Explained

<div class="mermaid">
flowchart LR
    A["ssh beagle\n(on laptop)"] --> B{"ProxyCommand"}
    B -->|"ssh stargate -W beagle:22"| C["Stargate"]
    C -->|"forward to"| D["beagle1-5"]
    A -.->|"single command"| D
</div>

`-W %h:%p` tells SSH: forward this TCP connection to host `%h` on port `%p` through Stargate.

---

## Agent Forwarding for GitHub

To use your GitHub key from a Beagle board, add to `~/.ssh/config` **on Stargate**:

```text
Host *
    ForwardAgent yes
```

This forwards your laptop's SSH agent through both hops so `git clone` over SSH works on the Beagle board without copying your private key there.

---

## Editing Files Remotely with micro

`micro` is the required editor for CS 315 (not `nano`):

```bash
micro hello.c       # open or create a file
```

| Keys | Action |
|------|--------|
| `Ctrl-S` | Save |
| `Ctrl-Q` | Quit |
| `Ctrl-C` / `Ctrl-X` / `Ctrl-V` | Copy / Cut / Paste |
| `Ctrl-F` | Find |
| `Tab` / `Shift-Tab` | Indent / unindent |

`~/.config/micro/settings.json`:
```json
{ "tabstospaces": true, "ft:c": { "tabsize": 4 }, "softwrap": true }
```

---

## GitHub over SSH

Add to `~/.ssh/config` on your laptop:
```text
Host github.com
  AddKeysToAgent yes
  ForwardAgent yes
  IdentityFile ~/.ssh/id_ed25519_cs315_key
  User git
```

Paste the contents of `id_ed25519_cs315_key.pub` into [github.com/settings/keys](https://github.com/settings/keys). Test:

```bash
ssh -T git@github.com
# Hi yourname! You've successfully authenticated...
```

That message means success — GitHub does not give shell access, only Git access.

---

## Cloning on a Beagle Board

After keys are configured end-to-end:

```bash
ssh beagle
mkdir -p cs315 && cd cs315
git clone https://github.com/phpeterson-usf/autograder
```

Add autograder to `PATH` in `~/.bash_profile`:
```bash
export PATH=~/cs315/autograder:$PATH
```

Log out and back in (or `source ~/.bash_profile`), then run `grade test`.

---

## Optional: Local RISC-V VM with QEMU

```bash
# macOS
brew install qemu

# Ubuntu / WSL
sudo apt install qemu qemu-system-misc
```

```bash
mkdir cs315 && cd cs315
curl https://www.cs.usfca.edu/~benson/cs315/files/ubuntu-22.04-riscv.zip --output ubuntu-22.04-riscv.zip
unzip ubuntu-22.04-riscv.zip && cd ubuntu-22.04-riscv
./start.sh
```

Add `Host riscv` to `~/.ssh/config` with `Port 4444` for convenience.

---

## Sanity Check: Compile on RISC-V

```c
#include <stdio.h>
int main(int argc, char *argv[]) {
    if (argc != 2) { fprintf(stderr, "Usage: %s <str>\n", argv[0]); return 1; }
    printf("Hello, %s!\n", argv[1]);
    return 0;
}
```

```bash
gcc -g -O2 -Wall -Wextra -o hello hello.c
./hello World       # Hello, World!
uname -m            # riscv64
file hello          # ELF 64-bit LSB ... RISC-V ...
```

Seeing `riscv64` confirms the full pipeline works on real hardware.

---

## Common Mistakes

| Symptom | Likely Cause | Fix |
|---------|--------------|-----|
| `Permissions 0644 ... are too open` | Key files world-readable | `chmod 600 ~/.ssh/*` |
| Still prompted for password | `.pub` not in `authorized_keys` | Re-check Step 5 on Stargate |
| `scp` fails "No such file" | `~/.ssh` missing on remote | `mkdir -p ~/.ssh && chmod 700 ~/.ssh` |
| Connection times out | Not on USF VPN | Connect to VPN, retry |
| `authorized_keys` lost other keys | Used `>` not `>>` | Re-append all keys with `>>` |
| Steps "hit the wrong host" | Wrong machine | Read the prompt; `exit` to laptop |
| GitHub clone asks for password on Beagle | Agent not forwarded | Add `Host * / ForwardAgent yes` on Stargate |

---

## Diagnosing SSH Failures

Verbose mode shows exactly which keys SSH tries and why the host rejects them:

```bash
ssh -v stargate
```

Look for lines like:
```text
debug1: Offering public key: /home/you/.ssh/id_ed25519_cs315_key
debug1: Authentications that can continue: publickey
debug1: No more authentication methods to try.
```

This tells you whether the key was offered, whether it was accepted, and what the server allows.

---

## Key Concepts Reference

| Concept | Role |
|---------|------|
| **Private key** | Stays on laptop; proves identity |
| **Public key** | Copied to servers; placed in `authorized_keys` |
| **Passphrase** | Unlocks private key locally; cached by SSH agent |
| **Stargate** | CS gateway: `stargate.cs.usfca.edu` |
| **BeagleV / Beagle** | Real RISC-V hardware, `beagle1`–`beagle5` |
| **ProxyCommand** | Hops through Stargate with one `ssh beagle` |
| **ForwardAgent** | Lets your local key work on intermediate hosts |
| **QEMU** | Emulates RISC-V on your laptop |

---

## Summary

1. **CS 315 uses real RISC-V hardware** — five BeagleV-Ahead boards behind Stargate, with optional local QEMU VM

2. **SSH public-key auth**: private key stays on your laptop; public key goes to `authorized_keys` on Stargate

3. **Setup recipe**: generate key → write `~/.ssh/config` → `chmod 600` → `scp .pub` to Stargate → `cat >> authorized_keys`

4. **ProxyCommand** collapses two hops into `ssh beagle`; **ForwardAgent** extends your key to GitHub on Beagle

5. **Read the prompt** before every command — wrong machine, `>` vs `>>`, and bad permissions cause most failures

6. **Verify the toolchain**: `uname -m` should report `riscv64` on a Beagle board