passt-repair(1)

✨ passt-repair — the little helper that fixes TCP sockets for its bestie 💅

okay so this is the passt-repair(1) page from the General Commands Manual, and bestie, it's short but it's mighty. it's a whole manual about one tiny privileged helper. let's get into it 🫶

🎀 NAME 🎀

passt-repair — the helper that sets TCP_REPAIR socket options for passt(1). that's it, that's the job, and she does it flawlessly 💖

🌸 SYNOPSIS 🌸

passt-repair PATH

one argument. one path. iconic minimalism ✨

🦋 DESCRIPTION 🦋

so passt-repair is a privileged helper whose whole entire personality is setting and clearing repair mode on TCP sockets on behalf of passt(1). how does it know what to do? instructions arrive as single-byte commands over a UNIX domain socket. cute, efficient, no notes 💅

why does this exist? because it lets you migrate TCP connections between guests without handing extra capabilities to passt(1) itself. like, to migrate TCP connections, passt(1) leverages repair mode, and repair mode needs the CAP_NET_ADMIN capability (see capabilities(7)) just to be set or cleared. so instead of giving passt(1) the keys to the kingdom, you let this separate helper do the privileged bit. queen behavior, honestly 👑

now, PATH does two different things depending on what it is, so pay attention bestie:

• if PATH represents a UNIX domain socket, passt-repair(1) attempts to connect to it. simple. direct. she's on her way 🏃‍♀️
• if it's a directory, passt-repair(1) waits until a file ending with .repair appears in it, and then attempts to connect to it. patient queen. she'll wait, but she will show up 🌈

💜 PROTOCOL 💜

passt-repair(1) connects to passt(1) using the socket specified via the --repair-path option in passt(1) itself. by default, that name is the same as the UNIX domain socket used for guest communication, suffixed by .repair. so if you know one, you know the other. iykyk 😌

now the messages, and bestie this part is precise so don't skim:

the messages consist of one 8-bit signed integer that can be:

• TCP_REPAIR_ON (1)
• TCP_REPAIR_OFF (0)
• TCP_REPAIR_OFF_NO_WP (-1)

all as defined by the Linux kernel user API. and then, along with that, one to SCM_MAX_FD (253) sockets sent as an SCM_RIGHTS (see unix(7)) ancillary message. and who sends all this? the server, passt(1). she's the one initiating, fr fr 📨

the client, passt-repair(1), then replies with the same byte — and no ancillary message — to indicate success. if it fails, it just closes the connection. no drama, no explanation, just gone 💀

and the server closes the connection on error or completion. everyone knows when the conversation is over. communication skills: immaculate ✨

🌟 NOTES 🌟

passt-repair(1) can be granted the CAP_NET_ADMIN capability — which is preferred, because it limits privileges to the strictly necessary ones — or it can be run as root.

bestie, lowkey take the CAP_NET_ADMIN route. it's the preferred one for a reason: it keeps the privileges to the strict minimum instead of handing over the whole root situation 🙈

👑 AUTHOR 👑

Stefano Brivio <sbrivio@redhat.com>. thank you for your service, king 🫡💖

🐛 REPORTING BUGS 🐛

found something cursed? please report issues on the bug tracker at https://bugs.passt.top/, or send a message to the passt-user@passt.top mailing list — see https://lists.passt.top/. they want to hear from you, no cap 🫶

📜 COPYRIGHT 📜

Copyright (c) 2025 Red Hat GmbH.

passt-repair is free software: you can redistribute them and/or modify them under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version. slay, and also legally binding 💅

🌈 SEE ALSO 🌈

• passt(1)
• qemu(1)
• capabilities(7)
• unix(7)

and that's the whole page bestie!! 🎀 that was passt-repair(1) from the General Commands Manual — go forth and repair some sockets responsibly, mwah 💖✨🦋🌸