libssh2_channel_direct_tcpip_ex(3)

💖 libssh2_channel_direct_tcpip_ex — the libssh2 bestie handbook 💖

okay so. bestie. say it with me: tunnel a TCP connection through an SSH session. that's the whole vibe. this page lives in the libssh2 manual (yes, the libssh2 manual, the one we all pretend we read) and it's about yeeting a TCP connection through your SSH session so the remote host does the legwork for you. lowkey iconic. 🫶

---

✨ NAME ✨

libssh2_channel_direct_tcpip_ex — Tunnel a TCP connection through an SSH session

like literally that's it. that's the job. tunnel the TCP. through the SSH session. no cap.

---

🌸 SYNOPSIS 🌸

#include <libssh2.h>

LIBSSH2_CHANNEL *
libssh2_channel_direct_tcpip_ex(LIBSSH2_SESSION *session,
                                const char *host, int port,
                                const char *shost, int sport);

LIBSSH2_CHANNEL *
libssh2_channel_direct_tcpip(LIBSSH2_SESSION *session,
                             const char *host, int port);

so there's two of them: the _ex one that takes all five args (she's the main character 👑) and the plain one that's just the chill three-arg version. copy them character for character bestie, don't freestyle the signature, that's not the vibe. 💅

---

🦋 DESCRIPTION 🦋

okay let's go through the cast of characters one by one, because every single one matters:

• session — Session instance as returned by libssh2_session_init_ex(3). you already have one of these, she's your ride or die.
• host — Third party host to connect to using the SSH host as a proxy. so like, not the SSH server itself, the other person you're trying to reach through it.
• port — Port on third party host to connect to. obviously. the door number on that third party host.
• shost — Host to tell the SSH server the connection originated on. it's a little white lie you're telling the server about where you came from 🙈.
• sport — Port to tell the SSH server the connection originated from. same energy, but the port version.

and now the actual plot:

Tunnel a TCP/IP connection through the SSH transport via the remote host to a third party. Communication from the client to the SSH server remains encrypted, communication from the server to the 3rd party host travels in cleartext.

bestie read that last part again. cleartext. the client→SSH-server hop is encrypted, gorgeous, protected. but the SSH-server→third-party hop? that's out in the open, naked, no encryption at all. it's giving "trust the middleman" and you should know that before you ship it. 🚨

---

🌈 RETURN VALUE 🌈

Pointer to a newly allocated LIBSSH2_CHANNEL instance, or NULL on errors.

so: you get a fresh LIBSSH2_CHANNEL pointer when it slays, and NULL when it doesn't. check it. always check it. ✨

---

💀 ERRORS 💀

• LIBSSH2_ERROR_ALLOC — An internal memory allocation call failed. the malloc said no. it happens to the best of us. 😭

---

👑 SEE ALSO 👑

• libssh2_session_init_ex(3)

go read that one too, you need the session before you can do literally any of this. iykyk. 💜

---

that's the whole page bestie, every flag, every arg, every error, nothing skipped, periodt. 🎀

this absolute banger of a manual page comes from libssh2 0.15, dated 1 Jun 2007 — yeah she's vintage but she still ate. mwah. 💅