EMBS/remote-access-setup.md

EMBS — Remote access to the Xilinx tools (macOS)

Source material: working-remotely.md, vlab-quickstart-guide.md, using-the-vlab.md, plus the EMBS docs (Practical 1a, "Working Remotely", "Vivado Licencing and Installation").

Why we cannot run the tools on this Mac

Vivado / Vitis 2025.1 have no macOS build at all — AMD ship Linux (x86-64) and Windows only. On top of that this is an Apple Silicon machine (arm64, macOS 27.0.1), so even a VM/emulation route would be a fight. The tools therefore have to run on a Linux machine at York, and we drive them over SSH with the GUI forwarded to this Mac with X11.

The three machines involved

Machine	Role
ssh.york.ac.uk	IT Services SSH gateway. The only York host reachable from off campus.
csteach0.york.ac.uk	CS teaching Linux server. This is where Vivado/Vitis actually run. Home dir = your university filestore.
rts001.cs.york.ac.uk:2222	VLAB relay — the rack of real Zybo Z7-10 boards. Only reachable through the gateway.
this Mac	X server (XQuartz) + terminal. Runs no Xilinx software.

Verified by probing from this Mac:

• ssh.york.ac.uk:22 — reachable.
• rts001.cs.york.ac.uk:22 and :2222 — timed out (firewalled, as documented).
• csteach0.york.ac.uk:22 — timed out (must go via the gateway).
• csteach0.york.ac.uk resolves to 144.32.125.156.

So the gateway hop is mandatory, not optional.

What is already done on this Mac

• ~/.ssh/config already contains the York blocks for user brs544 (ssh.york.ac.uk, and rts001.cs.york.ac.uk csteach0.york.ac.uk with the ProxyCommand).
• An SSH key pair exists: ~/.ssh/id_ed25519 / ~/.ssh/id_ed25519.pub.
• Python 3 (Homebrew) and OpenSSH 10.3 are available.

Current status

• ✅ SSH key authorised — login to csteach0.york.ac.uk works.
• ✅ XQuartz installed.
• ⬜ No VLAB keyfile (*.vlabkey) anywhere under $HOME. This must come from Ian.
• ⬜ Xilinx PATH / licence lines on the server (one-off, step 4) — verify with vivado -version.

Two gotchas found by testing

1. The SSH gateway demands a second factor every time. The gateway accepts the key (debug1: Server accepts key) and then still asks for another method (gssapi-with-mic,password,keyboard-interactive). That is the university's 2FA (AuthenticationMethods publickey,keyboard-interactive), not a broken key. Expect a password / Duo prompt on every connection through the gateway. ssh -o BatchMode=yes will never work, so unattended or scripted logins are not possible.

2. DISPLAY is not exported on this Mac. After installing XQuartz, echo $DISPLAY prints nothing and launchctl getenv DISPLAY is empty — so a plain ssh -Y forwards nothing and the windows silently never appear. Starting XQuartz does create a working server (verified: xdpyinfo -display :0 succeeds and /tmp/.X11-unix/X0 exists). embs.sh below sets DISPLAY=:0 itself, which is exactly why it is safer than typing ssh -Y by hand. (Logging out and back in also fixes it permanently.)

Step 1 — Authorise our key at York

ssh-copy-id csteach0.york.ac.uk

This goes through the ProxyCommand to the gateway and then to csteach0. Expect to be asked for your password several times (gateway, then csteach0). The gateway reads ~/.ssh/authorized_keys from your university Linux home directory, so copying the key to csteach0 also unlocks key-based auth on the gateway.

Verify — this should print a hostname and your username with no password prompt:

ssh -o BatchMode=yes csteach0.york.ac.uk 'echo OK $(hostname) as $(whoami)'

Step 2 — Install XQuartz

brew install --cask xquartz

(or download XQuartz 2.8.6 from https://www.xquartz.org/ — it supports macOS 10.13+ and is arm64-native). Log out and back in after installing so DISPLAY is set up.

Step 3 — Connect (use embs.sh)

cd ~/Projects/EMBS
./embs.sh

This is a thin wrapper around:

ssh -Y -C -o ServerAliveInterval=60 csteach0.york.ac.uk

What it adds: it finds (or starts) XQuartz and exports DISPLAY=:0 — necessary because DISPLAY is unset on this Mac — then runs the ssh command above. Other modes:

./embs.sh --check                          # verify the X server, connect to nothing
./embs.sh 'vivado -version'                # run one remote command and exit
EMBS_HOST=csteach1.york.ac.uk ./embs.sh    # override the host

Once connected, sanity-check X11 before committing to a 60 GB tool launch:

xeyes      # a pair of eyes should appear on the Mac

What the flags mean

Flag	Meaning
-Y	Trusted X11 forwarding. Asks sshd to set the remote app's DISPLAY and proxy X11 traffic back down the SSH connection to the local X server. It does not talk to XQuartz itself — XQuartz is simply the endpoint the local DISPLAY points at.
-X	Untrusted forwarding: enables the X11 SECURITY extension, which restricts what the remote app may do and often breaks older Java/Tk toolkits. Vivado/Vitis misbehave under it, which is why the module docs use -Y.
-C	Compress the SSH connection. Worth it because X11 forwarding is chatty with small, repetitive drawing messages. Note the ProxyCommand's -o Compression=no applies only to the separate gateway hop.
-o ServerAliveInterval=60	Send a keepalive every 60 s of inactivity so an idle NAT/firewall does not silently drop a long synthesis run.

Making the name memorable

embs.sh gives you a short local command. If you would rather type just ssh embs, add this block to ~/.ssh/config:

Host embs
    HostName csteach0.york.ac.uk
    User brs544
    ProxyCommand ssh -A -T -o Compression=no ssh.york.ac.uk -W %h:%p
    ForwardX11Trusted yes
    Compression yes
    ServerAliveInterval 60

The ProxyCommand must be repeated here: ssh only merges options from blocks whose Host pattern matches, and the existing Host rts001.cs.york.ac.uk csteach0.york.ac.uk block does not match the name embs. Without it, ssh embs would try to reach csteach0 directly and hang until it timed out. (An alias alone also still leaves the DISPLAY problem above, which is why embs.sh remains the more robust route.)

Step 4 — One-off setup on the server

Per Practical 1a, add the tools to the PATH and point at the department's floating licence server (so no personal AMD licence is needed while working on the CS servers):

echo 'export LM_LICENSE_FILE=2100@cslm0.its.york.ac.uk' >> ~/.bashrc
echo 'export PATH=/opt/york/cs/net/xilinx_vivado-2025.1-x86_64-1/2025.1/Vivado/bin:$PATH' >> ~/.bashrc

Then reopen the terminal and check the version — it must be 2025.1, not an older 2020.x that may be earlier on the PATH:

vivado -version

Vitis is normally launched from inside Vivado (Tools -> Launch Vitis IDE), so no separate PATH entry is needed.

Step 5 — Get the VLAB keyfile (from Ian)

Everything on the VLAB side is blocked until we have this. Once we do:

scp ~/Downloads/<yourkey>.vlabkey csteach0.york.ac.uk:~/
ssh csteach0.york.ac.uk 'chmod 0600 ~/*.vlabkey'

vlab.py must run on the same machine as the tools (i.e. on csteach0, not on the Mac) — that is the whole point of the localhost:12345 tunnel. Full VLAB usage is the next conversation.

Gotchas worth knowing up front

• Expect X11 to be slow. Vivado's GUI over X11 from York is usable but sluggish; the new VS Code-based Vitis IDE is heavier still. Prefer a hardware lab PC when you can, and do long synthesis/implementation runs and come back.
• csteach0 is shared. The VLAB default local port 12345 will collide with other students. Pick your own with -l, e.g. vlab.py -k key.vlabkey -l 20041 -u brs544, and use the same port in Vivado/Vitis.
• Disk quota. Synthesis eats space; a full ~/.cache is the usual culprit. Check with quota -s; aim for ~500 MB free.
• No spaces in Vivado project paths or workspace names — this genuinely breaks the tools.
• Close the VLAB when done (Ctrl-a then k, confirm y) — the exclusive board lock expires 10 minutes after connecting anyway.
• Host key warnings about rts001 usually just mean the relay was rebuilt; clear the stale entry from ~/.ssh/known_hosts.
• The VLAB gives you UART only — no buttons, no LEDs, no live HDMI. Plan designs so they can be driven and observed over the serial line. (--capture can grab a JPEG of an AXI VDMA framebuffer.)
• The University VDS is not a route to the tools. Its UniDesktop software list (MATLAB, R, ArcGIS, VS Code, PuTTY, WinSCP, X2Go …) contains no Vivado/Vitis. It could only serve as a Windows jump box to reach csteach0.

Immediate next actions

1. ./embs.sh and confirm xeyes appears.
2. If not already done, add the PATH / licence lines on the server (step 4) and run vivado -version to confirm 2025.1.
3. Ask Ian for the VLAB keyfile.
4. Then the VLAB: vlab.py run on csteach0, board lock via -l <your own port>.