Lab 01 — SSH config and connection multiplexing

Goal

Get your laptop and Unity talking to each other securely, automatically, and with only one Duo prompt per session. By the end of this lab, you should be able to type ssh unity and land on the cluster in under two seconds, without typing a password or approving Duo for every connection.

This lab is the foundation for every later lab in this practicum. Don’t skip steps.

Reading

Before starting, read these two chapters of the BuckAI HPC Handbook:

  1. SSH Setup for ASC and Unity — sections 1–7 in detail; skim 8 (compute-node aliases — we’ll touch on that at the end).
  2. SSH Keys — Concepts & Best Practices — read end-to-end; it’s short.

The reading is ~25 minutes; budget that plus ~45 minutes for the lab itself.

Learning objectives

By the end of this lab you will be able to:

  1. Generate an Ed25519 SSH key pair and explain what each half does.
  2. Install your public key on the ASC jumphost and the Unity login node with ssh-copy-id.
  3. Write a ~/.ssh/config that automates the two-hop journey (laptop → jumphost → Unity).
  4. Enable connection multiplexing so subsequent SSH sessions reuse the first authenticated connection — drastically reducing Duo prompts.

Setup / prerequisites

  • A laptop running macOS (preferred) or Linux. Windows users: do this lab inside WSL2.
  • An ASC / Unity account — make sure you can log in with your OSU credentials somewhere (e.g. through ASC’s web portal). If you can’t, request an account before continuing.
  • A terminal app: Terminal.app on macOS, any terminal emulator on Linux.
  • Your OSU username in the form lastname.## (e.g. smith.123).

Throughout this lab, replace:

  • yourname.## → your real OSU username
  • buckai_key → whatever you name your key file (it’s just a filename)

Tasks

1. Create the ~/.ssh/ infrastructure (5 min)

Open Terminal on your Mac:

mkdir -p ~/.ssh
chmod 700 ~/.ssh
mkdir -p ~/.ssh/sockets
chmod 700 ~/.ssh/sockets
touch ~/.ssh/config
chmod 600 ~/.ssh/config

The sockets/ directory is where multiplexed connections will live — this is what makes the “one Duo per ten minutes” magic work.

✅ Self-check: ls -ld ~/.ssh ~/.ssh/sockets should both show drwx------.

2. Generate your SSH key (5 min)

ssh-keygen -t ed25519 -C "yourname@osu.edu" -f ~/.ssh/buckai_key

When prompted for a passphrase: for this course, leave it blank (press Enter twice). For real long-term use, a passphrase is more secure — see Handbook §2 of SSH Keys for the tradeoff and how to use the macOS Keychain to remember it.

You should now have:

  • ~/.ssh/buckai_key — your private key. Treat like a password. Never share.
  • ~/.ssh/buckai_key.pub — your public key. Safe to share. Goes on the clusters.
chmod 600 ~/.ssh/buckai_key
chmod 644 ~/.ssh/buckai_key.pub

✅ Self-check: cat ~/.ssh/buckai_key.pub should print one line starting with ssh-ed25519 AAAAC3....

3. Install your public key on the ASC jumphost (5 min)

ssh-copy-id -i ~/.ssh/buckai_key.pub yourname.##@jump.asc.ohio-state.edu -p 2200

Enter your OSU password when prompted. This is the last time you’ll type your OSU password for SSH. You’ll also get one Duo prompt — approve it.

✅ Self-check: Re-running the command should say All keys were skipped because they already exist on the remote system.

4. Install your public key on Unity (5 min)

ssh-copy-id -i ~/.ssh/buckai_key.pub yourname.##@unity.asc.ohio-state.edu

This one won’t prompt for a separate Duo because you’ll be authenticating via the jumphost session you just opened.

5. Write your ~/.ssh/config (15 min)

Open the file:

nano ~/.ssh/config

Paste this template, replacing yourname.## with your real OSU username and buckai_key if you named your key differently:

### Global defaults: apply to ALL hosts
Host *
    # Connection multiplexing: authenticate once, reuse the connection
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h:%p
    ControlPersist 10m

    # Keepalives: prevent firewalls/NAT from dropping idle connections
    ServerAliveInterval 30
    ServerAliveCountMax 4
    TCPKeepAlive yes

    # Prefer your SSH agent + macOS Keychain
    AddKeysToAgent yes
    UseKeychain yes

### ASC Jumphost (requires Duo MFA)
Host ascjumphost
    HostName jump.asc.ohio-state.edu
    User yourname.##
    Port 2200
    IdentityFile ~/.ssh/buckai_key
    IdentitiesOnly yes

### Unity Login Node (via jump host)
Host unity
    HostName unity.asc.ohio-state.edu
    User yourname.##
    IdentityFile ~/.ssh/buckai_key
    IdentitiesOnly yes
    ProxyJump ascjumphost
    # Older HPC SSH daemons may need these for key-based auth to work:
    HostKeyAlgorithms +ssh-rsa
    PubkeyAcceptedAlgorithms +ssh-rsa

Save with Ctrl+O, exit with Ctrl+X.

Read each section and make sure you understand what it does. The handbook’s Section 5 and 6 of SSH Setup explains every line — don’t move on until you can explain ControlMaster auto and why ServerAliveInterval 30 is more protective than ServerAliveInterval 240.

6. Test the connection (5 min)

ssh unity

What should happen:

  1. You see “Connecting to jump.asc.ohio-state.edu…” (or similar)
  2. One Duo prompt on your phone → approve it
  3. You’re sitting at a Unity prompt: [yourname.##@unity ~]$

If you got that, you’re 80% done.

7. Test multiplexing — the headline of this lab (5 min)

Without closing the first SSH session, open a new Terminal tab (Cmd+T) and run:

ssh unity

What should happen:

  • ✅ You land on Unity instantly with no Duo prompt.

That’s connection multiplexing working. Your second SSH connection reused the authenticated socket from the first one.

If the second connection prompts you for Duo again, multiplexing is broken — see “Common issues” below.

Deliverables

Save each of the following as evidence of completing this lab:

  1. Your sanitized ~/.ssh/config — paste it into a file lab01/ssh_config.txt, but redact your username by replacing it with yourname.## everywhere. The structure is what we want to see.

  2. A terminal transcript showing one Duo, two logins. From a fresh Terminal (close any existing SSH sessions first):

    $ date
$ ssh unity   # (approve Duo)
$ exit
$ ssh unity   # should be instant, no Duo
$ exit
$ date

    Save the whole transcript to lab01/multiplex_demo.txt. The two date outputs should be less than 30 seconds apart.

  3. A short reflection (3–5 sentences) in lab01/reflection.md answering:

    • Why does ControlPersist 10m exist — what would happen if it were 0?
    • Why is ServerAliveInterval 30 more protective against disconnects than ServerAliveInterval 240?

Self-check

Before moving on, you should be able to:

Common issues

❌ “Permission denied (publickey)”

Most likely causes, in order of frequency:

  • Wrong permissions. Run chmod 700 ~/.ssh && chmod 600 ~/.ssh/buckai_key && chmod 600 ~/.ssh/config. SSH silently refuses world-readable key files.
  • Public key not installed. Re-run ssh-copy-id -i ~/.ssh/buckai_key.pub yourname.##@unity.asc.ohio-state.edu.
  • Wrong key name in ~/.ssh/config (the IdentityFile line).

❌ Duo prompts on every connection (multiplexing not working)

  • Check ~/.ssh/sockets/ exists and is writable: ls -ld ~/.ssh/sockets.
  • Check there’s no stale lock: ls ~/.ssh/sockets/ after a failed connection. If you see leftover files, rm ~/.ssh/sockets/* and retry.
  • Run ssh -v unity for verbose output. Look for lines containing mux or ControlMaster — they tell you what SSH is actually doing.

❌ “no matching host key type found. Their offer: ssh-rsa”

The cluster’s SSH server uses an algorithm modern OpenSSH disabled. Make sure the HostKeyAlgorithms +ssh-rsa and PubkeyAcceptedAlgorithms +ssh-rsa lines are in your Unity Host block.

❌ “Bad owner or permissions on ~/.ssh/config”

chmod 600 ~/.ssh/config
chmod 700 ~/.ssh

❌ SSH hangs forever on connect

A stale socket from a previous failed connection. Fix:

rm ~/.ssh/sockets/*
ssh unity

Time estimate

  • Reading: ~25 minutes
  • Lab tasks: ~45 minutes if everything works first try, up to 90 minutes if you hit issues
  • Reflection: ~5 minutes

Total: ~1.5 hours, but the time spent debugging here teaches you more than any other lab — pay attention to error messages.

Extensions (optional)

If you finished quickly and want to go deeper:

Add a compute-node Host block

Once you have access to a specific Unity compute node (e.g. via sinteractive later in this course, or via your lab’s reserved partition), add a Host block for it:

Host mynode
    HostName <real-node-hostname>.asc.ohio-state.edu
    User yourname.##
    IdentityFile ~/.ssh/buckai_key
    IdentitiesOnly yes
    HostKeyAlgorithms +ssh-rsa
    PubkeyAcceptedAlgorithms +ssh-rsa
    ProxyJump unity

On Unity, real node hostnames follow the pattern uXXX (u101, u250, u500, etc.). With this block, ssh mynode does three hops behind the scenes (laptop → jumphost → unity → node) — and thanks to multiplexing, still only one Duo prompt per ten-minute window.

Add an OSC entry

If you also have an OSC account (Pitzer / Cardinal / Owens):

Host pitzer
    HostName pitzer.osc.edu
    User <your-osc-username>
    IdentityFile ~/.ssh/osc_key
    IdentitiesOnly yes

OSC doesn’t use a jumphost — direct connection is fine. Most everything you learn for Unity will also work on OSC.

Read about ssh-agent in more depth

The AddKeysToAgent yes + UseKeychain yes combination is doing a lot of work for you. Read Handbook SSH Keys §5 for the full story of how macOS’s Keychain remembers your key passphrase across reboots — useful if you decide to add a passphrase to your key later.

What’s next?

Once SSH is working, move on to Lab 02 — VS Code Remote-SSH + an AI coding assistant, where you’ll turn this raw SSH access into a full editor + AI-assistant development environment.