pesto(1)

🌸 pesto(1) — General Commands Manual 🌸

okay bestie, sit down, hydrate, and let me tell you about pesto, a whole entire vibe from the General Commands Manual section 1. she's a client, she's a baddie, she talks to sockets. let's go 💅

---

✨ NAME ✨

pesto — Configure a running passt(1) or pasta(1) instance. 🫶

---

🎀 SYNOPSIS 🎀

pesto [OPTION]... PATH

---

🦋 DESCRIPTION 🦋

pesto is a client that lets you view and update the port forwarding configuration of a running passt(1) or pasta(1) instance. it's giving remote control for your port table, no cap.

PATH gives the path to the UNIX domain socket created by passt or pasta. lowkey important: it should match the -c command line option given to that instance. match it or it simply will not work, periodt.

---

👑 OPTIONS 👑

• -d, --debug — Be verbose. she will talk, and honestly? we love that for her. 🗣️
• -h, --help — Display a help message and exit. classic, iconic, always there for you. ✨
• -s, --show — Show the forwarding configuration before and after changes are applied. before-and-after pics but for your routing table 📸
• -A, --add — Add the port forwarding specifiers following this option to the current forwarding table, rather than replacing it.

This option can be given multiple times, as it might follow previous deletions (see --delete below), and implies that all the specifiers following it, before a further --delete option occurs, will be handled as additions.

See the section Adding, deleting, clearing rules in the NOTES for more details. iykyk 💜

• -D, --delete — Delete the port forwarding specifiers following this option from the current forwarding table, rather than adding them to it.

This option can be given multiple times, as it might follow previous additions (see --add above), and implies that all the specifiers following it, before a further --add option occurs, will be handled as deletions.

See the section Adding, deleting, clearing rules in the NOTES for more details. 🧹

• -C, --clear pif — Clear the forwarding table associated to a given pif, that is, a conceptual type of interface in passt(1) or pasta(1) representing a specific data path and direction.

The available pif names can be obtained by querying the current forwarding configuration, which can be done by calling pesto(1) without options. yes bestie, just run it with zero flags and read. that's the trick. 🙈

See the section Adding, deleting, clearing rules in the NOTES for more details.

• -t, --tcp-ports spec — Configure TCP port forwarding to guest or namespace. spec can be one of:
  • none — Don't forward any ports. nope. none. zero. blocking that energy 🚫
  • [address[%interface]/]ports ... — Specific ports to forward. Optionally, a specific listening address and interface name (since Linux 5.7) can be specified. ports may be either:
    • all — Forward all unbound, non-ephemeral ports, as permitted by current capabilities. No failures are reported for unavailable ports, unless no ports could be forwarded at all.
    • or a comma-separated list of entries which may be any of:
      • first[-last][:tofirst[-tolast]] — Include range. Forward port numbers between first and last (inclusive) to ports between tofirst and tolast. If tofirst and tolast are omitted, assume the same as first and last. If last is omitted, assume the same as first.
      • ~first[-last] — Exclude range. Don't forward port numbers between first and last. This takes precedences over include ranges. ⚠️ she said precedences, and she meant it.
      • auto — pasta only. Only forward ports in the specified set if the target ports are bound in the namespace. The list of ports is periodically derived (every second) from listening sockets reported by /proc/net/tcp and /proc/net/tcp6, see proc(5). she's checking on you every single second, bestie ⏰

Specifying excluded ranges only implies that all other non-ephemeral ports are forwarded. Specifying no ranges at all implies forwarding all non-ephemeral ports permitted by current capabilities. In this case, no failures are reported for unavailable ports, unless no ports could be forwarded at all.

Examples, and yes we're doing all of them 💖:

• -t all — Forward all unbound, non-ephemeral ports as permitted by current capabilities to the corresponding port on the guest or namespace
• -t ::1/all — For the local address ::1, forward all unbound, non-ephemeral ports as permitted by current capabilities
• -t 22 — Forward local port 22 to port 22 on the guest or namespace
• -t 22:23 — Forward local port 22 to port 23 on the guest or namespace
• -t 22,25 — Forward local ports 22 and 25 to ports 22 and 25 on the guest or namespace
• -t 22-80 — Forward local ports between 22 and 80 to corresponding ports on the guest or namespace
• -t 22-80:32-90 — Forward local ports between 22 and 80 to ports between 32 and 90 on the guest or namespace
• -t 192.0.2.1/22 — Forward local port 22, bound to 192.0.2.1, to port 22 on the guest or namespace
• -t 192.0.2.1%eth0/22 — Forward local port 22, bound to 192.0.2.1 and interface eth0, to port 22
• -t %eth0/22 — Forward local port 22, bound to any address on interface eth0, to port 22
• -t 2000-5000,~3000-3010 — Forward local ports between 2000 and 5000, except for those between 3000 and 3010
• -t 192.0.2.1/20-30,~25 — For the local address 192.0.2.1, forward ports between 20 and 24 and between 26 and 30
• -t ~20000-20010 — Forward all ports to the guest, except for the range from 20000 to 20010
• -t auto — Automatically forward any ports which are bound in the namespace
• -t ::1/auto — Automatically forward any ports which are bound in the namespace, listening only on local address ::1
• -t 8000-8010,auto — Forward ports in the range 8000-8010 if and only if they are bound in the namespace

• -u, --udp-ports spec — Configure UDP port forwarding to guest. spec is as described for TCP above. same energy, different protocol 💫
• -T, --tcp-ns spec — Configure TCP port forwarding from target namespace to init namespace. spec is as described above.
• -U, --udp-ns spec — Configure UDP port forwarding from target namespace to init namespace. spec is as described above.
• --version — Show version and exit. quick lil flex, then she's out 🎬

---

📝 NOTES 📝

🧚 Adding, deleting, clearing rules 🧚

The options --add, --delete, and --clear are handled as sequential commands to manipulate the current forwarding tables. If none of them is given, forwarding specifiers for a given table are intended as replacement of the corresponding table. That is:

pesto -t 1024 -U 1025

will replace the current TCP inbound port forwarding table with a single rule, forwarding port 1024, and will similarly replace the UDP outbound forwarding table with a single forwarding rule for port 1025. This usage is a short-hand form for:

pesto -C HOST -t 1024 -C SPLICE -U 1025

The options --add and --delete are used to add new specific rules or delete existing ones, instead of replacing tables. For example:

pesto -A -t 2000 -D -t 3000 -U 5000

will add a forwarding rule for inbound TCP port 2000, and delete inbound TCP port 3000 as well as outbound UDP port 5000 from the existing set of rules. she's editing, not rewriting. main character editor energy 📝✨

All these options are interpreted as sequential commands and can be arbitrarily combined. For example:

pesto -A -t 2000 -C HOST -A -T 3000 -t 2001 -D -u 5000

will, in order:

1. add inbound TCP port 2000
2. clear inbound ports, reverting the addition above
3. add outbound TCP port 3000
4. add inbound TCP port 2001
5. delete inbound UDP port 5000

⚠️ bestie please read these in order. they are sequential. the order is the whole point. order matters the way outfits matter. 💅

---

💜 AUTHORS 💜

Stefano Brivio <sbrivio@redhat.com>, David Gibson <david@gibson.dropbear.id.au>.

absolute legends, we stan 🫶

---

😭 REPORTING BUGS 😭

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/.

found a bug? tell them!! they want to know, fr fr. do not suffer in silence, that's not the vibe 🙈

---

⭐ COPYRIGHT ⭐

Copyright Red Hat

pesto is free software: you can redistribute it and/or modify it 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.

free software, free as in slay 👑

---

🌈 SEE ALSO 🌈

passt(1), pasta(1), unix(7).

go read those next, bestie, they're the whole lore 🦋

---

and that's the tea — this was the pesto(1) page from the General Commands Manual, section 1, brought to you with love, sockets and zero chill. stay configured, stay gorgeous, and remember: match your PATH to the -c option. periodt. 💖✨🎀