.. _network_configuration_guide:

Network Configuration Guide
###########################

.. contents::
    :local:
    :depth: 2

This document describes how various network configuration options can be
set according to available resources in the system.

Network Buffer Configuration Options
************************************

The network buffer configuration options control how much data we
are able to either send or receive at the same time.

:kconfig:option:`CONFIG_NET_PKT_RX_COUNT`
  Maximum amount of network packets we can receive at the same time.

:kconfig:option:`CONFIG_NET_PKT_TX_COUNT`
  Maximum amount of network packet sends pending at the same time.

:kconfig:option:`CONFIG_NET_BUF_RX_COUNT`
  How many network buffers are allocated for receiving data.
  Each net_buf contains a small header and either a fixed or variable
  length data buffer. The :kconfig:option:`CONFIG_NET_BUF_DATA_SIZE`
  is used when :kconfig:option:`CONFIG_NET_BUF_FIXED_DATA_SIZE` is set.
  This is the default setting. The default size of the buffer is 128 bytes.

  The :kconfig:option:`CONFIG_NET_BUF_VARIABLE_DATA_SIZE` is an experimental
  setting. There each net_buf data portion is allocated from a memory pool and
  can be the amount of data we have received from the network.
  When data is received from the network, it is placed into net_buf data portion.
  Depending on device resources and desired network usage, user can tweak
  the size of the fixed buffer by setting :kconfig:option:`CONFIG_NET_BUF_DATA_SIZE`, and
  the size of the data pool size by setting :kconfig:option:`CONFIG_NET_BUF_DATA_POOL_SIZE`
  if variable size buffers are used.

  When using the fixed size data buffers, the memory consumption of network buffers
  can be tweaked by selecting the size of the data part according to what kind of network
  data we are receiving. If one sets the data size to 256, but only receives packets
  that are 32 bytes long, then we are "wasting" 224 bytes for each packet because we
  cannot utilize the remaining data. One should not set the data size too low because
  there is some overhead involved for each net_buf. For these reasons the default
  network buffer size is set to 128 bytes.

  The variable size data buffer feature is marked as experimental as it has not
  received as much testing as the fixed size buffers. Using variable size data
  buffers tries to improve memory utilization by allocating minimum amount of
  data we need for the network data. The extra cost here is the amount of time
  that is needed when dynamically allocating the buffer from the memory pool.

  For example, in Ethernet the maximum transmission unit (MTU) size is 1500 bytes.
  If one wants to receive two full frames, then the net_pkt RX count should be set to 2,
  and net_buf RX count to (1500 / 128) * 2 which is 24.
  If TCP is being used, then these values need to be higher because we can queue the
  packets internally before delivering to the application.

:kconfig:option:`CONFIG_NET_BUF_TX_COUNT`
  How many network buffers are allocated for sending data. This is similar setting
  as the receive buffer count but for sending.


Connection Options
******************

:kconfig:option:`CONFIG_NET_MAX_CONN`
  This option tells how many network connection endpoints are supported.
  For example each TCP connection requires one connection endpoint. Similarly
  each listening UDP connection requires one connection endpoint.
  Also various system services like DHCP and DNS need connection endpoints to work.
  The network shell command **net conn** can be used at runtime to see the
  network connection information.

:kconfig:option:`CONFIG_NET_MAX_CONTEXTS`
  Number of network contexts to allocate. Each network context describes a network
  5-tuple that is used when listening or sending network traffic. Each BSD socket in the
  system uses one network context.


Socket Options
**************

:kconfig:option:`CONFIG_NET_SOCKETS_POLL_MAX`
  Maximum number of supported poll() entries. One needs to select proper value here depending
  on how many BSD sockets are polled in the system.

:kconfig:option:`CONFIG_POSIX_MAX_FDS`
  Maximum number of open file descriptors, this includes files, sockets, special devices, etc.
  One needs to select proper value here depending on how many BSD sockets are created in
  the system.

:kconfig:option:`CONFIG_NET_SOCKETPAIR_BUFFER_SIZE`
  This option is used by socketpair() function. It sets the size of the
  internal intermediate buffer, in bytes. This sets the limit how large
  messages can be passed between two socketpair endpoints.


TLS Options
***********

:kconfig:option:`CONFIG_NET_SOCKETS_TLS_MAX_CONTEXTS`
  Maximum number of TLS/DTLS contexts. Each TLS/DTLS connection needs one context.

:kconfig:option:`CONFIG_NET_SOCKETS_TLS_MAX_CREDENTIALS`
  This variable sets maximum number of TLS/DTLS credentials that can be
  used with a specific socket.

:kconfig:option:`CONFIG_NET_SOCKETS_TLS_MAX_CIPHERSUITES`
  Maximum number of TLS/DTLS ciphersuites per socket.
  This variable sets maximum number of TLS/DTLS ciphersuites that can
  be used with specific socket, if set explicitly by socket option.
  By default, all ciphersuites that are available in the system are
  available to the socket.

:kconfig:option:`CONFIG_NET_SOCKETS_TLS_MAX_APP_PROTOCOLS`
  Maximum number of supported application layer protocols.
  This variable sets maximum number of supported application layer
  protocols over TLS/DTLS that can be set explicitly by a socket option.
  By default, no supported application layer protocol is set.

:kconfig:option:`CONFIG_NET_SOCKETS_TLS_MAX_CLIENT_SESSION_COUNT`
  This variable specifies maximum number of stored TLS/DTLS sessions,
  used for TLS/DTLS session resumption.

:kconfig:option:`CONFIG_TLS_MAX_CREDENTIALS_NUMBER`
   Maximum number of TLS credentials that can be registered.
   Make sure that this value is high enough so that all the
   certificates can be loaded to the store.


IPv4/6 Options
**************

:kconfig:option:`CONFIG_NET_IF_MAX_IPV4_COUNT`
   Maximum number of IPv4 network interfaces in the system.
   This tells how many network interfaces there will be in the system
   that will have IPv4 enabled.
   For example if you have two network interfaces, but only one of them
   can use IPv4 addresses, then this value can be set to 1.
   If both network interface could use IPv4, then the setting should be
   set to 2.

:kconfig:option:`CONFIG_NET_IF_MAX_IPV6_COUNT`
   Maximum number of IPv6 network interfaces in the system.
   This is similar setting as the IPv4 count option but for IPv6.


TCP Options
***********

:kconfig:option:`CONFIG_NET_TCP_TIME_WAIT_DELAY`
  How long to wait in TCP *TIME_WAIT* state (in milliseconds).
  To avoid a (low-probability) issue when delayed packets from
  previous connection get delivered to next connection reusing
  the same local/remote ports,
  `RFC 793 <https://www.rfc-editor.org/rfc/rfc793>`_ (TCP) suggests
  to keep an old, closed connection in a special *TIME_WAIT* state for
  the duration of 2*MSL (Maximum Segment Lifetime). The RFC
  suggests to use MSL of 2 minutes, but notes

  *This is an engineering choice, and may be changed if experience indicates
  it is desirable to do so.*

  For low-resource systems, having large MSL may lead to quick
  resource exhaustion (and related DoS attacks). At the same time,
  the issue of packet misdelivery is largely alleviated in the modern
  TCP stacks by using random, non-repeating port numbers and initial
  sequence numbers. Due to this, Zephyr uses much lower value of 1500ms
  by default. Value of 0 disables *TIME_WAIT* state completely.

:kconfig:option:`CONFIG_NET_TCP_RETRY_COUNT`
  Maximum number of TCP segment retransmissions.
  The following formula can be used to determine the time (in ms)
  that a segment will be be buffered awaiting retransmission:

  .. math::

     \sum_{n=0}^{\mathtt{NET\_TCP\_RETRY\_COUNT}} \bigg(1 \ll n\bigg)\times
     \mathtt{NET\_TCP\_INIT\_RETRANSMISSION\_TIMEOUT}

  With the default value of 9, the IP stack will try to
  retransmit for up to 1:42 minutes.  This is as close as possible
  to the minimum value recommended by
  `RFC 1122 <https://www.rfc-editor.org/rfc/rfc1122>`_ (1:40 minutes).
  Only 5 bits are dedicated for the retransmission count, so accepted
  values are in the 0-31 range.  It's highly recommended to not go
  below 9, though.

  Should a retransmission timeout occur, the receive callback is
  called with :code:`-ETIMEDOUT` error code and the context is dereferenced.

:kconfig:option:`CONFIG_NET_TCP_MAX_SEND_WINDOW_SIZE`
  Maximum sending window size to use.
  This value affects how the TCP selects the maximum sending window
  size. The default value 0 lets the TCP stack select the value
  according to amount of network buffers configured in the system.
  Note that if there are multiple active TCP connections in the system,
  then this value might require finetuning (lowering), otherwise multiple
  TCP connections could easily exhaust net_buf pool for the queued TX data.

:kconfig:option:`CONFIG_NET_TCP_MAX_RECV_WINDOW_SIZE`
  Maximum receive window size to use.
  This value defines the maximum TCP receive window size. Increasing
  this value can improve connection throughput, but requires more
  receive buffers available in the system for efficient operation.
  The default value 0 lets the TCP stack select the value
  according to amount of network buffers configured in the system.

:kconfig:option:`CONFIG_NET_TCP_RECV_QUEUE_TIMEOUT`
  How long to queue received data (in ms).
  If we receive out-of-order TCP data, we queue it. This value tells
  how long the data is kept before it is discarded if we have not been
  able to pass the data to the application. If set to 0, then receive
  queueing is not enabled. The value is in milliseconds.

  Note that we only queue data sequentially in current version i.e.,
  there should be no holes in the queue. For example, if we receive
  SEQs 5,4,3,6 and are waiting SEQ 2, the data in segments 3,4,5,6 is
  queued (in this order), and then given to application when we receive
  SEQ 2. But if we receive SEQs 5,4,3,7 then the SEQ 7 is discarded
  because the list would not be sequential as number 6 is be missing.


Traffic Class Options
*********************

It is possible to configure multiple traffic classes (queues) when receiving
or sending network data. Each traffic class queue is implemented as a thread
with different priority. This means that higher priority network packet can
be placed to a higher priority network queue in order to send or receive it
faster or slower. Because of thread scheduling latencies, in practice the
fastest way to send a packet out, is to directly send the packet without
using a dedicated traffic class thread. This is why by default the
:kconfig:option:`CONFIG_NET_TC_TX_COUNT` option is set to 0 if userspace is
not enabled. If userspace is enabled, then the minimum TX traffic class
count is 1. Reason for this is that the userspace application does not
have enough permissions to deliver the message directly.

In receiving side, it is recommended to have at least one receiving traffic
class queue. Reason is that typically the network device driver is running
in IRQ context when it receives the packet, in which case it should not try
to deliver the network packet directly to the upper layers, but to place
the packet to the traffic class queue. If the network device driver is not
running in IRQ context when it gets the packet, then the RX traffic class
option :kconfig:option:`CONFIG_NET_TC_RX_COUNT` could be set to 0.


Stack Size Options
******************

There several network specific threads in a network enabled system.
Some of the threads might depend on a configure option which can be
used to enable or disable a feature. Each thread stack size is optimized
to allow normal network operations.

The network management API is using a dedicated thread by default. The thread
is responsible to deliver network management events to the event listeners that
are setup in the system if the :kconfig:option:`CONFIG_NET_MGMT` and
:kconfig:option:`CONFIG_NET_MGMT_EVENT` options are enabled.
If the options are enabled, the user is able to register a callback function
that the net_mgmt thread is calling for each network management event.
By default the net_mgmt event thread stack size is rather small.
The idea is that the callback function does minimal things so that new
events can be delivered to listeners as fast as possible and they are not lost.
The net_mgmt event thread stack size is controlled by
:kconfig:option:`CONFIG_NET_MGMT_EVENT_QUEUE_SIZE` option. It is recommended
to not do any blocking operations in the callback function.

The network thread stack utilization can be monitored from kernel shell by
the **kernel threads** command.