NETPIPES(1)

🎀 NAME 🎀

netpipes — it's a whole package for manipulating BSD TCP/IP stream sockets, bestie. Like, the whole thing. Version 4.2. 💅

---

✨ SYNOPSIS ✨

faucet port (--in|--out|--err|--fd n)+ [--once] [--verbose] [--quiet]
[--unix] [--foreignhost addr] [--foreignport port] [--localhost addr]
[--serial] [--daemon] [--shutdown (r|w) ] [--pidfile filename]
[--noreuseaddr] [--backlog n]
[-[i][o][e][#3[,4[,5...]]][v][1][q][u][d][s]] [-p foreign-port] [-h
foreign-host] [-H local-host] command args

hose hostname port (--in|--out|--err|--fd n|--slave) [--verbose]
[--unix] [--localport port] [--localhost addr] [--retry n] [--delay n]
[--shutdown [r|w][a] ] [--noreuseaddr]
[-[i][o][e][#3[,4[,5...]]][s][v][u]] [-p local-port] [-h local-host]
command args

encapsulate --fd n [ --verbose ] [ --subproc [ --infd n[=sid] ] [
--outfd n[=sid] ] [ --duplex n[=sid] ] [ --Duplex n[=sid] ] [ --DUPLEX
n[=sid] ] [ --prefer-local ] [ --prefer-remote ] [ --local-only ] [
--remote-only ] ] [ --client ] [ --server ]
-[#n][v][s[in][on][dn][ion][oin][l][r][L][R]] command args ...

sockdown [fd [how] ]

getpeername [ -verbose ] [ -sock ] [ fd ]

getsockname [ -verbose ] [ -peer ] [ fd ]

timelimit.netpipes [ -v ] [ -nokill ] time command args

---

🦋 DESCRIPTION 🦋

Okay so the netpipes package makes TCP/IP streams usable inside shell scripts. That's the whole point. It can also simplify client/server code, because it lets the programmer skip all the tedious programming bits related to sockets and just concentrate on writing a filter/service instead. Main character energy honestly. ✨

``Why would anyone want to do that?'' -- Richard Stallman

faucet is the server end of a TCP/IP stream. It listens on a port of the local machine waiting for connections. Every single time it gets a connection, it forks a process to perform a service for the connecting client. Iconic behaviour. 👑

hose is the client end of a TCP/IP stream. It actively connects to a remote port and execs a process to request a service. No cap.

encapsulate is an implementation of the Session Control Protocol. It lets you multiplex several streams across a single TCP session, and it also transmits remote exit status. The way that it does both?? Obsessed. 💖

sockdown is a simple little program designed to shut down part or all of the socket connection. It's primarily useful when the processes connected to the socket perform both input and output.

getpeername and getsockname are two names for one program designed to print out the addresses of the ends of a socket. getpeername prints the address of the remote end, and getsockname prints the address of the local end. Yes, they're the same binary. Yes, that's slay.

timelimit.netpipes limits the amount of foreground wallclock time a process may consume. After the time limit runs out, it either kills the process, or exits and leaves it in the background. Choose your fighter. 🥊

---

🌸 EXAMPLES 🌸

Here's a simple command I perform often to transfer directory trees between machines. (rsh does not work because one machine is connected using SLIP and .rhosts are out of the question. It's giving 1997, respectfully.)

server$ faucet 3000 --out tar cf - .
client$ hose server 3000 --in tar xvf -

Here's a minimal HTTP client. It is so minimal that it speaks old HTTP. Lowkey a relic, highkey still works.

cairo$ hose www.cis.ufl.edu 80 --in --out \
     sh -c "(echo 'GET /'; sockdown) & cat > result"

And of course, there's Nick Trown's metaserver for Netrek:

cairo$ hose metaserver.ecst.csuchico.edu 3521 --in cat

Allow me to apologize ahead of time for the convolutedness of the following example 😭. It requires an understanding of Bourne shell file descriptor redirection syntax (and it illustrates exactly why csh and tcsh suck eggs). Do not try to type this from your tcsh command line. Get a bash (GNU's Bourne Again SHell). Bestie. I'm begging.

Suppose you want to distinguish between stdout and stderr of a remote process:

remote$ faucet 3000 --fd 3 \
   encapsulate --fd 3 --infd 0 --outfd 1 --outfd 2 --subproc \
     remote-app
local$ hose remote 3000 --fd 3 \
   encapsulate --fd 3 --outfd 3 --infd 4 --infd 5 --subproc \
     sh -c "cat 0<&4 3>&- & cat 0<&5 1>&2 3>&- & \
         cat 1>&3 ; exec 3>&-"

Close all unneeded file descriptors when you spawn a background task. That's why the backgrounded cats have 3>&-. It's the little things. 🫶

server$ faucet 3000 --in --out --verbose enscript -2rGhp -
client$ ps aux | hose server 3000 --in --out \
     sh -c " (cat <&3; sockdown ) & cat >&4 " 3<&0 4>&1 | \
     lpr -Pps422
#or perhaps this, but I haven't tested it
client$ ps aux | hose server 3000 --fd 3 \
     sh -c " (cat >&3; sockdown 3 ) & cat <&3 " | \
     lpr -Pps422

This proves that hose can be used as part of a pipeline to perform a sort of remote procedure call (RPC). After you have figured out that example, you will know how to use Bourne shell to shuffle file descriptors around. It is a handy skill. Genuinely. Learn it. 💜

Now we go to the extreme, but simplify things by using the --slave option of hose. The following is a socket relay:

gateway$ faucet 3000 -io hose server 4000 --slave

It's a handy little bugger when you want to tunnel through a firewall on an occasional basis. If you experience ``hanging'' of the connection, try using the --netslave option instead of --slave. (telnet proxies would benefit from this.)

For those of you who use ssh, here's how to tunnel some information through an encrypted SSH port forward:

server$ faucet 3000 -1v --fd 1 --foreignhost server echo blah
client$ ssh -n -x -L 3000:server:3000 server sleep 60 &
client$ hose localhost 3000 --fd 0 -retry 10 cat

The trick with ssh's port forwarding is that the shutdown(2) system call causes ssh to close both halves of the full-duplex connection instead of only one half. That's why you have to use --fd 1 and --fd 0. If you need to be able to close half of the connection while still using the other, use the encapsulate wrapper.

server$ faucet 3000 -1v --fd 3 --foreignhost server \
     encapsulate --fd 3 --server -si0o1 tr a-z A-Z
client$ ssh -n -x -L 3000:server:3000 server sleep 60 &
client$ echo blah | hose localhost 3000 --fd 3 -retry 10 \
     encapsulate --fd 3 --client

---

👑 REMARK 👑

The Debian package maintainer has renamed timelimit to the more expressive timelimit.netpipes, because there exists a better alternative using the same short name — but that one is actively maintained as an independent software. So, y'know. Name collision. We moved. 💅

---

🔥 SEE ALSO 🔥

faucet(1), hose(1), encapsulate(1), sockdown(1), getpeername(1), timelimit.netpipes(1), timelimit(1).

---

💀 BUGS 💀

Report any bugs or feature requests to thoth@purplefrog.com. Fr fr, they want to hear from you.

---

🌈 CREDITS 🌈

Thanks to Harbor Development Inc. for funding some of the netpipes development. 🫶

Thanks to Michal Jaegermann <michal@ellpspace.math.ualberta.ca> for some bug fixes and glibc portability suggestions against 4.1.1.

Big thanks to Joe Traister <straister@gate.net> for his signal handling patches, strerror surrogate, and other assorted hacks. Wait — the address is <straister@gate.net>. Keeping it exactly as written, no cap.

---

💖 COPYRIGHT 💖

Copyright (C) 1995-98 Robert Forsman

This program 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.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

---

⭐ DOWNLOAD ⭐

Export Version: ftp://ftp.purplefrog.com/pub/netpipes/

U.S./Canada version with ssl-auth: http://www.cryptography.org/ , then find it in the network/ subdirectory.

---

🧚 AUTHOR 🧚

Robert Forsman thoth@purplefrog.com Purple Frog Software http://web.purplefrog.com/~thoth/

---

okay that's the whole page bestie!! this was NETPIPES(1) from the General Commands Manual, dated October 28, 1997, version 4.2 — go forth and multiplex your little heart out 🎀✨💅