1.. _socks5_interface:
2
3SOCKS5 Proxy Support
4####################
5
6.. contents::
7    :local:
8    :depth: 2
9
10Overview
11********
12
13The SOCKS library implements SOCKS5 support, which allows Zephyr to connect
14to peer devices via a network proxy.
15
16See this
17`SOCKS5 Wikipedia article <https://en.wikipedia.org/wiki/SOCKS#SOCKS5>`_
18for a detailed overview of how SOCKS5 works.
19
20For more information about the protocol itself, see
21`IETF RFC1928 SOCKS Protocol Version 5 <https://tools.ietf.org/html/rfc1928>`_.
22
23SOCKS5 API
24**********
25
26The SOCKS5 support is enabled by :kconfig:option:`CONFIG_SOCKS` Kconfig variable.
27Application wanting to use the SOCKS5 must set the SOCKS5 proxy host address
28by calling :c:func:`setsockopt()` like this:
29
30.. code-block:: c
31
32    static int set_proxy(int sock, const struct sockaddr *proxy_addr,
33                         socklen_t proxy_addrlen)
34    {
35        int ret;
36
37        ret = setsockopt(sock, SOL_SOCKET, SO_SOCKS5,
38                         proxy_addr, proxy_addrlen);
39        if (ret < 0) {
40                return -errno;
41        }
42
43        return 0;
44    }
45
46SOCKS5 Proxy Usage in MQTT
47**************************
48
49For MQTT client, there is :c:func:`mqtt_client_set_proxy()` API that the
50application can call to setup SOCKS5 proxy. See :zephyr:code-sample:`mqtt-publisher`
51sample application for usage example.
52