mtcp_init - initialize the mOS stack #include <mtcp_api.h> "int mtcp_init(char *" "config_file" ); mtcp_init () call is used to set the stack parameters of an mOS-based application. These parameters are loaded inside the process via a startup configuration file, config_file. A developer is required to first call mtcp_init () function before he/she can invoke any follow-up mOS functions in his/her application. A typical config_file is composed of at least two mOS configuration blocks. The app block sets the configuration parameters of the application that employs the underlying mOS stack. A typical instance of an app block is illustrated below. ####################### # APPLICATION OPTIONS # ####################### # application to run application { type = end run = epwget core_mask = 0x000F } A user can populate the app block with the following parameters:

17

The type of application that the user wants to run. An application can either be an endpoint application ('end') such as an mTCP client or mTCP server, or be a middlebox application ('monitor'). The name of the binary to execute. The CPU bitmask where you want to run the application. The mask 0x000F denotes that the user wants to run a single-process, 4-threaded application on the first four cores of the CPU (CPU 0~3).

The user can run one or more monitoring applications at the same time. A mos block adjusts the internal parameters of the mOS stack. ####################### # MOS-RELATED OPTIONS # ####################### mos { forward = 1 ####################### ##### I/O OPTIONS ##### ####################### # number of memory channels per socket [mandatory for DPDK] nb_mem_channels = 4 # devices used for MOS applications [mandatory] netdev { dpdk0 0x000F dpdk1 0x000F } ####################### ### LOGGING OPTIONS ### ####################### # NICs to print network statistics per second # if enabled, mTCP will print xx Gbps and xx pps for RX and TX stat_print = dpdk0 dpdk1 # A directory contains MOS system log files mos_log = logs/ # dpdk0 and dpdk1 will forward traffic in either direction nic_forward_table { dpdk0 dpdk1 } } A user can populate an mOS configuration block with the following parameters:

23

Setting this option to 1 enables packet forwarding (for middlebox operations). Keep this value to 0 for endpoint mTCP applications. (Mandatory for DPDK) nb_mem_channels parameter specifies the number of memory channels per CPU socket. Please refer to DPDK user guide, on tuning this parameter for performance optimizations. netdev parameter block specifies the network interfaces (or device ports) used for mOS applications. Each line contains the mapping of a network interface and CPU core mask. In the example above, it uses two DPDK-assisted network interfaces (dpdk0 and dpdk1), and CPU cores 0~3 receive/transmit traffic from/to the first 4 (0~3) hardware queues of the NIC. We program our DPDK driver to use symmetric RSS algorithm to distribute traffic across the cores. This ensures that the same CPU gets to examine packets of both flows of the connection. stat_print parameter specifies the network interfaces which the application is interested in displaying runtime monitor statistics. mos_log parameter specifies the path to a directory where the mOS system writes extra logging data. nic_forward_table parameter block specifies the static Ethernet traffic forwarding rules when the mOS middlebox application is set in inline mode (Running Monitor Applications in Inline Mode). If enabled, each line accepts a pair of DPDK-registered NIC interfaces via which the traffic can later be forwarded in either direction. Each interface should have one-to-one mapping with another. In the example above, traffic is switched from dpdk0 to dpdk1 and vice versa. The middlebox is configured as a 'bump-in-the-wire'. max_concurrency specifies the maximum number of concurrent flows a middlebox can examine per CPU core. This parameter is used for preallocating the memory for flows. [default value: 100000] no_ring_buffers determines whether the TCP ring buffer should be disabled. For mOS endpoint (mTCP) applications, mOS always require the socket buffers for the application. For middlebox applications, you can disable the receive-side socket buffer by putting no_ring_buffers = 1. [default value: 0 (ring buffer is enabled by default)] Specifies the size of receive buffer per socket in bytes [default value: 8192 B]. Specifies the size of send buffer per socket in bytes [default value: 8192 B]. Specifies the TCP timewait interval value in seconds. TCP timewait interval is the allowed time for a connection to be in the TIME_WAIT state. For mOS endpoint (mTCP) applications, user can set it as an arbitrary value larger than 0 to guarantee graceful shutdown. For monitoring applications, the user may set it to 0 if she is not interested in monitoring the flow after TIME_WAIT state. [default value: 0s] Specifies the TCP timeout value in seconds. This parameter determines the maximum allowed time for any flows to exist without any packet reception. In other words, mOS middlebox stops monitoring the connection after tcp_timeout idle period. You can set tcp_timeout = -1 to disable the timeout checking. For mOS endpoint (mTCP) applications, tcp_timeout serves as a timeout period for connections that are in active open states (SYN_SENT states). [default value: 30s] """""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Returns 0 on success; -1 on failure. """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""".
"""".SH CONFORMING TO
""""POSIX.1-2001.
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
See "http://mos.kaist.edu/guide/walkthrough/05_configuration.html" to view example startup mOS configuration file. """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
mOS development team <[email protected]> """""""""""""""""""""""""""""""""""""""""""""""""""""
mtcp_destroy () """""""""""""""""""""""""""""""""""""""""""""""""""""
This page is part of mOS release 0.3 "docs" section. A description of the project, and information about reporting bugs, can be found at \%http://mos.kaist.edu/. """""""""""""""""""""""""""""""""""""""""""""""""""""