BaudBuddy

Running a TFTP server on a Mac

A switch wants its firmware over TFTP and macOS no longer makes that easy. What the built-in daemon still does, the two things that break uploads, and the 32 MB limit nobody mentions.

A switch wants its firmware over TFTP. You have a Mac. Fifteen years ago that was a checkbox in Sharing preferences; now it is a launchd plist you are not supposed to edit, on a volume you are not supposed to write to.

The daemon is still in there. Here is what still works, and the three things that will waste your afternoon if nobody warns you first.

Why network gear still speaks a protocol from 1981

TFTP is deliberately stupid. No authentication, no encryption, no directory listing, no way to resume. It runs over UDP and the whole implementation fits in a few kilobytes, which is exactly why it lives in the boot ROM of almost every switch, router, phone and PDU ever made.

That is the point. When a device has lost its operating system, the only code running is whatever the ROM holds, and the ROM has room for TFTP and not much else. You are not using it because it is good. You are using it because it is what answers when the box is otherwise dead.

The 32 MB wall

Start here, because it explains failures that look like something else.

Classic TFTP sends 512 byte blocks and numbers them with a 16 bit counter. 65535 blocks at 512 bytes is a hair under 32 MB, and that is the ceiling. Past it, implementations either roll the counter over, negotiate a bigger block size (RFC 2348), or fail.

Modern IOS and NX-OS images are comfortably larger than 32 MB. So a transfer that runs happily for two minutes and then dies at what looks like a random point is usually this, not your network. If both ends support blksize negotiation you will get past it. If the ROM monitor does not, you need a different protocol or a smaller image.

Getting the built-in daemon running

macOS ships tftpd at /usr/libexec/tftpd with a launchd job at /System/Library/LaunchDaemons/tftp.plist. Loading it has historically been:

sudo launchctl load -F /System/Library/LaunchDaemons/tftp.plist

The serving directory is /private/tftpboot.

Two caveats, both of which have caught people out on recent macOS. System Integrity Protection makes that plist read only, so the usual advice to edit it and change the root directory no longer applies. And the exact launchctl invocation has shifted across releases, so a command that worked on your last machine may not on this one.

Check it is listening:

sudo lsof -iUDP:69

If nothing comes back, the daemon is not running, whatever launchctl told you.

The thing that breaks uploads

Downloads usually work first time. Uploads fail, and the reason is not obvious: the target file must already exist and be writable before the device sends it.

The daemon will not create a file for you. It is a deliberate safety measure and it produces an error the switch reports as a vague failure.

sudo touch /private/tftpboot/switch-config.txt
sudo chmod 666 /private/tftpboot/switch-config.txt

Now the backup will land. Forget it and you get a switch reporting a permission error while the Mac logs nothing useful at all.

The firewall detail that catches everyone

TFTP does not stay on port 69. The client sends its first packet there, and the server replies from a fresh ephemeral port, which then carries the rest of the transfer.

Any firewall rule that opens UDP 69 and nothing else will let the request out, let the first reply in, and then silently drop the transfer. The symptom is a device that starts a download, reports one block, and hangs.

On the Mac, the application firewall will prompt the first time, and the answer is to allow it. Between VLANs, this is why TFTP needs a stateful helper or a wider rule than people expect.

The Cisco side

Pull an image onto flash:

copy tftp: flash:

It will ask for the server address and the filename. Push a config back:

copy running-config tftp:

And from a ROM monitor, when the device has no operating system left:

rommon 1 > IP_ADDRESS=10.0.0.2
rommon 2 > IP_SUBNET_MASK=255.255.255.0
rommon 3 > DEFAULT_GATEWAY=10.0.0.1
rommon 4 > TFTP_SERVER=10.0.0.10
rommon 5 > TFTP_FILE=c2960-lanbasek9-mz.150-2.SE11.bin
rommon 6 > tftpdnld

Type those carefully. ROM monitor has no command history worth the name and no forgiveness for a typo in a variable name.

When it does not work

Run through these in order. It is almost always one of the first three.

  • “File not found”: check the exact filename and case, and that it is in /private/tftpboot and world readable. TFTP does not list directories, so the device cannot tell you what it did find.
  • Upload fails, download works: the target file does not exist yet, or is not writable. See above.
  • Starts then stalls: firewall, or the 32 MB wall.
  • Nothing at all: the daemon is not actually listening. Check with lsof, not with whether the load command printed an error.
  • Works from a laptop on the same switch, not from your desk: something in between is not tracking the ephemeral port.

Doing it without any of that

BaudBuddy has a file server built in, which is the reason this page exists. Pick a folder, switch on the protocols you want, and it serves them: TFTP, HTTP, HTTPS, FTP and SFTP from the same directory.

The BaudBuddy file server, with TFTP, HTTP, HTTPS, FTP and SFTP each switchable, and a live console of incoming requests

One folder, five protocols. Each service is off until you start it, and every request appears in the console on the right.

Two things it fixes that matter here. Serving is separate from accepting uploads, so you turn on writes deliberately rather than discovering later that the folder was open. And every request, refusal and retry shows up in a live console, which turns “the switch says it failed” into a line telling you exactly what it asked for and what happened.

No sudo, no launchd, and the folder is one you chose rather than a directory at the root of the disk.

Sources