From ea8050b790029b354102a4fb1a1da595f243af04 Mon Sep 17 00:00:00 2001 From: Ron Frederick Date: Sat, 18 May 2024 16:58:14 -0700 Subject: [PATCH] Update documentation with more details about TUN/TAP support --- README.rst | 1 + docs/api.rst | 44 ++++++++++++++++++++++++++------------------ 2 files changed, 27 insertions(+), 18 deletions(-) diff --git a/README.rst b/README.rst index 2477e71..cfcbcb7 100644 --- a/README.rst +++ b/README.rst @@ -41,6 +41,7 @@ Features * Environment variables, terminal type, and window size * Direct and forwarded TCP/IP channels * OpenSSH-compatible direct and forwarded UNIX domain socket channels + * OpenSSH-compatible TUN/TAP channels and packet forwarding * Local and remote TCP/IP port forwarding * Local and remote UNIX domain socket forwarding * Dynamic TCP/IP port forwarding via SOCKS diff --git a/docs/api.rst b/docs/api.rst index 57344ba..fc96dc9 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -37,20 +37,23 @@ Once an SSH client connection is established and authentication is successful, multiple simultaneous channels can be opened on it. This is accomplished calling methods such as :meth:`create_session() `, :meth:`create_connection() -`, and :meth:`create_unix_connection() -` on the -:class:`SSHClientConnection` object. The client can also set up listeners on -remote TCP ports and UNIX domain sockets by calling :meth:`create_server() -` and :meth:`create_unix_server() -`. All of these methods take -``session_factory`` arguments that return :class:`SSHClientSession`, -:class:`SSHTCPSession`, or :class:`SSHUNIXSession` objects used to manage -the channels once they are open. Alternately, channels can be opened using -:meth:`open_session() `, -:meth:`open_connection() `, or +`, :meth:`create_unix_connection() +`, :meth:`create_tun() +`, and :meth:`create_tap() +` on the :class:`SSHClientConnection` object. +The client can also set up listeners on remote TCP ports and UNIX domain +sockets by calling :meth:`create_server() ` +and :meth:`create_unix_server() `. +All of these methods take ``session_factory`` arguments that return +:class:`SSHClientSession`, :class:`SSHTCPSession`, or :class:`SSHUNIXSession` +objects used to manage the channels once they are open. Alternately, channels +can be opened using :meth:`open_session() `, +:meth:`open_connection() `, :meth:`open_unix_connection() `, -which return :class:`SSHReader` and :class:`SSHWriter` objects that can be -used to perform I/O on the channel. The methods :meth:`start_server() +:meth:`open_tun() `, or +:meth:`open_tap() `, which return +:class:`SSHReader` and :class:`SSHWriter` objects that can be used to +perform I/O on the channel. The methods :meth:`start_server() ` and :meth:`start_unix_server() ` can be used to set up listeners on remote TCP ports or UNIX domain sockets and get back these :class:`SSHReader` @@ -84,17 +87,22 @@ to a UNIX domain socket or vice-versa can be set up using the functions :meth:`forward_remote_port_to_path() `, and :meth:`forward_remote_path_to_port() -`. - -In these cases, data transfer on -the channels is managed automatically by AsyncSSH whenever new connections -are opened, so custom session objects are not required. +`. In these cases, data +transfer on the channels is managed automatically by AsyncSSH whenever new +connections are opened, so custom session objects are not required. Dynamic TCP port forwarding can be set up by calling :meth:`forward_socks() `. The SOCKS listener set up by AsyncSSH on the requested port accepts SOCKS connect requests and is compatible with SOCKS versions 4, 4a, and 5. +Bidirectional packet forwarding at layer 2 or 3 is also supported using +the functions :meth:`forward_tun() ` and +:meth:`forward_tap() ` to set up tunnels +between local and remote TUN or TAP interfaces. Once a tunnel is established, +packets arriving on TUN/TAP interfaces on either side are sent over the +tunnel and automatically sent out the TUN/TAP interface on the other side. + When an SSH server receives a new connection and authentication is successful, handlers such as :meth:`session_requested() `, :meth:`connection_requested() `,