The Dexing Teahouse stood on a narrow street in the south of the city and had not closed for a single day in forty years. Across the street a new building had gone up — thicker beams, a firmer foundation, room in the back to tie up horses. Old Lei, the proprietor, decided to move into it.

The moving was not the hard part. The hard part was this: he would not close.

Old Lei had one iron rule — no guest’s tea goes cold, no storyteller stops mid-tale, no abacus at the counter falls silent. So he could not wait for closing time to move. He would have to move the teahouse while every seat was full.

He began with something strange. To every object in the building — every table, every jar, every ledger, every drawer in the kitchen — he attached a copper token the size of a palm, painted red on one side and white on the other. Whenever a waiter touched a thing, he flipped its token to red. And at the fourth watch each night, Old Lei sent an apprentice round the whole house to write down every red token he found, and flip them all back to white.

The first night, the porters copied the entire teahouse from the inventory: object by object across the street, set down in exactly the same place. It took the whole night. By dawn, an identical Dexing Teahouse stood across the street — except that it was last night’s teahouse.

And all through that night, the old house had been open for business. When the apprentice finished his round, he had written down three hundred-odd red tokens.

The second night, the porters carried only those three hundred. Much faster. By dawn, some eighty were red.

The third night, twenty. The fourth night, eleven.

Each round was shorter than the last, and the shorter the round, the less the guests had time to disturb — a snowball rolling downhill.

But by the seventh night, it stopped rolling. Nine. Ten. Nine. Stuck. Old Lei went to see what those nine things were: the running ledger at the counter, the stockpot muttering on the stove, the wooden tube of waiting-numbers by the door, the coin purse in the head waiter’s apron. Every one of them a thing that was never, for a single moment, not being touched. They were not heavy. They simply went stale the instant they crossed the street.

And so Old Lei understood: this last handful would never be caught.

He had three remedies, and used all of them that night.

First, he hired two more teams of porters — twice as much carried per night.

Second, he told the staff: for these few nights, slow your hands. Bring the tea a beat late. Let the guests wait a beat longer. Business suffered a little — and the red tokens grew fewer each night.

Third, and last: he stopped trying.

At the third watch, Old Lei stood in the middle of the hall, clapped his hands twice, and called out: “One moment, please.”

The lamps stayed lit, but everything stopped. The storyteller folded his fan. A hand came down flat on the abacus. The pot came off the fire. The porters rushed in, gathered up the last nine things, ran them across the street, and set them down. Old Lei finished the last line in the ledger, closed it, and crossed the street himself.

The whole thing took less time than it takes to drink half a cup of tea.

Then he did one last thing. He took the Dexing board down from above the old door and hung it above the new one, and pasted a sheet of paper on the old door: the teahouse is across the street. From then on the water carriers, the charcoal men and the errand boys all walked to the new building.

The next morning, not one guest noticed he was sitting in a different house. A few dimly recalled that the storyteller had seemed to pause, once, in the middle of a tale.

Whenever Old Lei told this story afterwards, he added a coda. He had considered another route entirely: open the empty new house immediately, seat the guests there, and send a boy running back to the old house for whatever turned out to be missing. The first quarter-hour would be chaos, but the closure would be essentially zero. He had not dared. Because if the old house happened to collapse in that window, both teahouses would be lost at once — half of it here, half of it there, and no complete one anywhere.

— By now you have probably recognized it: this is not a story about a teahouse. The copper tokens are the dirty bits on memory pages, the nightly rounds are the iterations of pre-copy, the half-cup “one moment please” is the stop-and-copy downtime window, and the sheet of paper on the door is a gratuitous ARP. This is the story of virtual machine live migration.

What it is

Live migration attempts something that sounds unreasonable: move a running virtual machine from one physical host to another with the guest OS and its applications never going down — an interruption of only a few hundred milliseconds.

The dominant technique is pre-copy, which is exactly Old Lei’s scheme:

1. Full round. The VM keeps running while every one of its memory pages is sent over the network to the destination.
2. Dirty tracking. Pages the guest modifies during that round must be recorded. The hardware does it for you — dirty bits in the EPT/NPT page table entries — and KVM gathers them into a dirty bitmap (newer kernels use a dirty ring to avoid the scan cost).
3. Iterative rounds. Send only the pages dirtied in the previous round. Shorter rounds mean fewer newly dirtied pages, so in theory the set shrinks geometrically.
4. Stop-and-copy. Once the remaining dirty set is small enough to ship within the target pause (QEMU’s default downtime-limit is 300ms), pause the vCPUs, transfer the last batch of pages plus CPU registers and device state, and resume execution on the destination.
5. Redirect traffic. The destination sends a gratuitous ARP / RARP; switches relearn the MAC, and packets start flowing to the new host.

Convergence has exactly one condition: dirty rate < transfer bandwidth. The handful you can never catch is the writable working set — the pages a process is always writing (stack, heap top, log buffers, locks). They are permanently dirty.

When it won’t converge, you have Old Lei’s three remedies: add bandwidth (multifd parallel connections), auto-converge (deliberately throttle the vCPUs so the guest dirties memory more slowly), or compress the delta (XBZRLE ships only the bytes that changed within a page).

If that still fails, switch to post-copy: start the VM at the destination immediately with empty memory, and let every touch of a missing page raise a fault that pulls it on demand from the source via userfaultfd. Downtime approaches zero — at the price that if the source host or the network dies mid-migration, the VM is gone for good, because no complete memory image exists on either side. That is the road Old Lei did not dare take.

Why it matters

This is the physical basis for “host maintenance the user never sees.” Kernel patching, firmware updates, draining a machine for decommission — all of it rests here.

In OpenShift it gets very concrete. OpenShift Virtualization / KubeVirt creates a VirtualMachineInstanceMigration for each VMI when a node is drained, and underneath it is QEMU pre-copy. The migrationConfiguration block in the KubeVirt CR is literally Old Lei’s set of dials: bandwidthPerMigration (how many porters), allowAutoConverge (whether the staff slow their hands), allowPostCopy (whether you dare take the risky road), and completionTimeoutPerGiB (how long before you give up).

And non-convergence is an operational symptom, not a theoretical one: a memory-hot VM — a database, a JVM with a large heap — will iterate forever, eventually time out, get cancelled, and stay on the original node. The drain stalls, and the whole maintenance window stalls with it. The judgement call at that moment is: raise the bandwidth? Allow auto-converge (that is, deliberately slow the guest down)? Or negotiate a window with the application owner and do a cold migration?

The same shape recurs elsewhere, incidentally: the catch-up phase of database log shipping before a failover, online storage volume migration, online rebuilds of a large table. All of it is one sentence — copy a stale full image, chase the delta round after round, then stop briefly and close the last gap.

Metaphor mapping

• The Dexing Teahouse — the running virtual machine (the guest)
• Old house / new house across the street — source host / destination host
• Tables, jars and ledgers inside — the guest’s memory pages
• Porters crossing the street — the migration network’s bandwidth
• The red-and-white copper tokens — the dirty bit in the page table entry
• The fourth-watch round recording the red ones — collecting the dirty bitmap / dirty ring
• Copying the whole house on the first night — the full pre-copy round
• Fewer things each night after — iterative rounds and geometric convergence
• Stuck at nine or ten — the writable working set, the floor convergence cannot cross
• The ledger, the stockpot, the coin purse — hot pages: log buffers, heap top, locks
• Hiring two more teams of porters — raising migration bandwidth / multifd
• Telling the staff to slow their hands — auto-converge, throttling the vCPUs
• “One moment, please” — stop-and-copy, pausing the vCPUs
• The last nine things plus the closed ledger — the final dirty pages plus CPU and device state
• Half a cup of tea — the downtime window (default target ~300ms)
• Moving the sign, pasting the note on the old door — gratuitous ARP / RARP, switches relearning the MAC
• The route he considered but did not take — post-copy with userfaultfd demand paging
• The old house collapsing in that window — source failure during post-copy, leaving the VM unrecoverable