LIBVDESTACK(3)

💖 LIBVDESTACK — the libvdestack manual page, bestie edition 💖

okay so. this is a library functions manual page for libvdestack, and it is genuinely one of the coolest little libraries out here. sit down, grab a boba, we're learning 🧋✨

---

✨ NAME ✨

vde_addstack, vde_delstack, vde_stackcmd, vde_msocket — a vde network namespace living inside your program like a user library 🫶

---

🌸 SYNOPSIS 🌸

#include <vdestack.h>

struct vdestack *vde_addstack(char *vdenet, char *ifname);

void vde_delstack(struct vdestack *stack);

int vde_stackcmd(struct vdestack *stack, char *stackcmd);

int vde_msocket(struct vdestack *stack,int domain, int type, int
protocol);

void vde_default_stack(struct vdestack *stack);

---

🦋 DESCRIPTION 🦋

Libvdestack is the whole Internet of Threads dream made real through network namespaces. the way that a program can just… have one (or even several 👀) private networking protocol stack(s) of its very own? iconic. that means your program can get assigned its own IP address(es), its own routing, all of it. main character energy, no cap 💅

• vde_addstack — creates a private network namespace 🎀 vdenet is the URL-like specification of a vde network, as described in :vde_plug(1). ifname is the name of the interface in the network namespace. and when ifname is NULL, the default interface :name is vde0.
• vde_delstack — destroys a vdestack once you don't need it anymore. it's giving cleanup era 🧹
• vde_stackcmd — runs a command, or a comma separated sequence of commands, inside the private network namespace. the whole point of this one is configuring your networking parameters and options (think IP address, routing, that vibe). ⚠️ for security reasons, commands must be specified using full pathnames. and do not use this function to start long lasting or non terminating programs — the caller waits for the termination of the command sequence, so it will simply sit there. it's giving "waiting for your situationship to text back" 😭
• vde_msocket — same semantics as socket(2), except the socket is defined in the scope of the network namespace whose descriptor is the first argument. the remaining arguments are exactly those defined in socket(2). slay 🌈
• vde_default_stack — defines the default stack: any successive socket(2) call will use the stack you passed as a parameter to vde_default_stack. pass NULL to undefine the default stack. bye bestie 👋

---

⭐ RETURN VALUE ⭐

vde_addstack returns a struct vdestack pointer, which gets used as a descriptor and therefore passed as an argument to the other functions in this library. NULL is returned in case of error. 🙈

vde_stackcmd returns the exit status of the command. and if the stackcmd argument is a comma separated sequence of commands, execution terminates upon the first command whose exit status is not zero, and the exit status of that command is what comes back. so when vde_stackcmd returns zero, the entire sequence was successfully executed. periodt 💯

On success, vde_msocket returns a valid file descriptor. -1 is returned elseways, and errno is set appropriately as described in socket(2).

---

💀 NOTES 💀

Libvdestack fails if user namespaces have not been configured in the running kernel and enabled for users. lowkey crucial. in Debian, the sysctl knob kernel.unprivileged_userns_clone must be set to 1. 🫡

---

👑 EXAMPLE 👑

here's an excerpt of C code showing libvdestack in the wild:

...
int fd;
int exit_status;
struct vdestack *stack = vde_addstack("vde://", NULL);
if (stack == NULL)
    ... error management
exit_status = vde_stackcmd(stack,
          "/bin/ip link set vde0 up;"
          "/bin/ip addr add 10.0.0.1/24 dev vde0;"
          "/bin/ip route add default via 10.0.0.254");
if (exit_status != 0)
   ... error management
fd = vde_msocket(stack, AF_INET, SOCK_STREAM, 0);
   ... fd can be used in any context in which a file descriptor returned by socket(2) can.
e.g. bind, accept, connect, read/write, send/recv ...
vde_delstack(stack);

ate, honestly 🔥

---

🔍 SEE ALSO 🔍

socket(2), vde_plug(1)

---

🐛 BUGS 🐛

Bug reports should be addressed to info@virtualsquare.org — they want to hear from you bestie, fr fr 📬

---

💜 AUTHOR 💜

VirtualSquare. Project leader: Renzo Davoli.

---

and that's the whole page! this gem comes to you from VirtualSquare, dated August 2024 💖 go forth and namespace responsibly, bestie 🎀✨🦋