diff --git a/doc/reference/networking/apis.rst b/doc/reference/networking/apis.rst index 40771298822..207f88fb3d7 100644 --- a/doc/reference/networking/apis.rst +++ b/doc/reference/networking/apis.rst @@ -15,5 +15,6 @@ Network APIs net_context.rst promiscuous.rst sntp.rst + socks5.rst trickle.rst websocket.rst diff --git a/doc/reference/networking/socks5.rst b/doc/reference/networking/socks5.rst new file mode 100644 index 00000000000..c76a1da3a27 --- /dev/null +++ b/doc/reference/networking/socks5.rst @@ -0,0 +1,51 @@ +.. _socks5_interface: + +SOCKS5 Proxy Support +#################### + +.. contents:: + :local: + :depth: 2 + +Overview +******** + +The SOCKS library implements SOCKS5 support, which allows Zephyr to connect +to peer devices via a network proxy. + +See this +`SOCKS5 Wikipedia article `_ +for a detailed overview of how SOCKS5 works. + +For more information about the protocol itself, see +`IETF RFC1928 SOCKS Protocol Version 5 `_. + +SOCKS5 API +********** + +The SOCKS5 support is enabled by :option:`CONFIG_SOCKS` Kconfig variable. +Application wanting to use the SOCKS5 must set the SOCKS5 proxy host adddress +by calling :c:func:`setsockopt()` like this: + +.. code-block:: c + + static int set_proxy(int sock, const struct sockaddr *proxy_addr, + socklen_t proxy_addrlen) + { + int ret; + + ret = setsockopt(sock, SOL_SOCKET, SO_SOCKS5, + proxy_addr, proxy_addrlen); + if (ret < 0) { + return -errno; + } + + return 0; + } + +SOCKS5 Proxy Usage in MQTT +************************** + +For MQTT client, there is :c:func:`mqtt_client_set_proxy()` API that the +application can call to setup SOCKS5 proxy. See :ref:`mqtt-publisher-sample` +for usage example.