#include <linux/tcp.h>
#include <linux/if_ether.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include <netinet/ip.h>
#include <stddef.h>
#include "mtcp_epoll.h"
#include <stdbool.h>

Include dependency graph for mos_api.h:

Data Structures
struct	pkt_info
	struct pkt_info is the struct that is actually exposed to the monitor application. More...

struct	pkt_ctx
	PACKET CONTEXT is the packet structure that goes through the mOS core... More...

struct	seq_remap_info

struct	filter_arg

struct	tcp_buf_info
	MOS tcp buf info structure. More...

struct	tcp_ring_fragment
	Structure to expose TCP ring buffer's fragment information. More...

union	monitor_filter

Macros
#define	__MTCP_MANAGER

#define	__SOCKET_MAP

#define	MOS_ETH_HDR (1 << 0)

#define	MOS_IP_HDR (1 << 1)

#define	MOS_TCP_HDR (1 << 2)

#define	MOS_TCP_PAYLOAD (1 << 3)

#define	MOS_UPDATE_IP_CHKSUM (1 << 4)

#define	MOS_UPDATE_TCP_CHKSUM (1 << 5)

#define	MOS_DROP (1 << 6)

#define	MOS_OVERWRITE (1 << 7)

#define	MOS_CHOMP (1 << 8)

#define	MOS_INSERT (1 << 9)

#define	PKT_INFO_LEN offsetof(struct pkt_info, ethh)

#define	SOL_SOCKET 0xffff /* options for socket level */
	The available level number in the POSIX library for sockets is on SOL_SOCKET. More...

#define	SOL_MONSOCKET 0xfffe /* MOS monitor socket level */

#define	MTCP_CB_GETCURPKT_CREATE_COPY

Typedefs
typedef struct mtcp_manager *	mtcp_manager_t

typedef struct socket_map *	socket_map_t

typedef struct filter_arg	filter_arg_t

typedef uint64_t	event_t
	Definition of event type. More...

typedef void(*	callback_t) (mctx_t mctx, int sock, int side, event_t event, filter_arg_t *arg)
	Prototype of callback function. More...

typedef bool(*	filter_t) (mctx_t mctx, int sock, int side, event_t event, filter_arg_t *arg)
	Prototype of UDE's filter function. More...

typedef union monitor_filter *	monitor_filter_t

Enumerations
enum	mtcp_hook_point { MOS_NULL = (1 << 29), MOS_HK_RCV = (1 << 30), MOS_HK_SND = (1 << 31) }
	Available hooking points. More...

enum	mos_event_type { MOS_NULL_EVENT = (0), MOS_ON_PKT_IN = (0x1<<0), MOS_ON_PKT_OUT = (0x1<<1), MOS_ON_CONN_START = (0x1<<2), MOS_ON_CONN_SETUP = (0x1<<3), MOS_ON_CONN_NEW_DATA = (0x1<<4), MOS_ON_ERROR = (0x1<<5), MOS_ON_TIMEOUT = (0x1<<6), MOS_ON_TCP_STATE_CHANGE = (0x1<<7), MOS_ON_ORPHAN = (0x1<<8), MOS_ON_REXMIT = (0x1<<9), MOS_ON_CONN_END = (0x1<<10), MOS_ON_DEBUG_MESSAGE = (0x1<<11) }
	Built-in events provided by mOS. More...

enum	mos_socket_opts { MOS_FRAGINFO_CLIBUF = 0x01, MOS_FRAGINFO_SVRBUF = 0x02, MOS_INFO_CLIBUF = 0x03, MOS_INFO_SVRBUF = 0x04, MOS_TCP_STATE_CLI = 0x05, MOS_TCP_STATE_SVR = 0x06, MOS_TIMESTAMP = 0x07, MOS_MONLEVEL = 0x08, MOS_CLIBUF = 0x09, MOS_SVRBUF = 0x0a, MOS_SEQ_REMAP = 0x0b, MOS_STOP_MON = 0x0c, MOS_FRAG_CLIBUF = 0x0d, MOS_FRAG_SVRBUF = 0x0e, MOS_CLIOVERLAP = 0x0f, MOS_SVROVERLAP = 0x10 }
	MOS monitor socket option names (and values) This will contain options pertaining to monitor stream sockets. More...

enum	tcpstate { TCP_CLOSED = 0, TCP_LISTEN = 1, TCP_SYN_SENT = 2, TCP_SYN_RCVD = 3, TCP_ESTABLISHED = 4, TCP_FIN_WAIT_1 = 5, TCP_FIN_WAIT_2 = 6, TCP_CLOSE_WAIT = 7, TCP_CLOSING = 8, TCP_LAST_ACK = 9, TCP_TIME_WAIT = 10 }
	mOS tcp stream states. More...

enum	{ MOS_OVERLAP_POLICY_FIRST =0, MOS_OVERLAP_POLICY_LAST, MOS_OVERLAP_CNT }
	mOS segment overlapping policies More...

enum	{ MOS_SIDE_CLI =0, MOS_SIDE_SVR, MOS_SIDE_BOTH }
	Definition of monitor side. More...

Functions
int	mtcp_bind_monitor_filter (mctx_t mctx, int sock, monitor_filter_t ft)

int	mtcp_register_callback (mctx_t mctx, int sock, event_t event, int hook_point, callback_t cb)
	Register a callback function in hook_point. More...

event_t	mtcp_alloc_event (event_t event)
	Allocate a child event. More...

event_t	mtcp_define_event (event_t event, filter_t filter, struct filter_arg *arg)
	Define a user-defined event function. More...

int	mtcp_raise_event (mctx_t mctx, event_t event)
	Raise a event. More...

void	mtcp_set_uctx (mctx_t mctx, int sock, void *uctx)
	Set user-level context (e.g., to store any per-flow user-defined meatadata) More...

void *	mtcp_get_uctx (mctx_t mctx, int sock)
	Get user-level context (e.g., to retrieve user-defined metadata stored in mtcp_set_uctx()) More...

ssize_t	mtcp_peek (mctx_t mctx, int sock, int side, char *buf, size_t len)
	Peeking bytestream from flow_context. More...

ssize_t	mtcp_ppeek (mctx_t mctx, int sock, int side, char *buf, size_t count, uint64_t off)
	The mtcp_ppeek() function reads up to count bytes from the TCP ring buffer of the monitor socket sock in mctx into buf, starting from the TCP sequence number seq_num. More...

int	mtcp_getlastpkt (mctx_t mctx, int sock, int side, struct pkt_info *p)
	Get current packet of mtcp context. More...

int	mtcp_settimer (mctx_t mctx, int id, struct timeval *timeout, callback_t cb)
	Register user's custom timer. More...

uint32_t	mtcp_cb_get_ts (mctx_t mctx)
	A sibling function to mtcp_settimer that returns the current timestamp of the machine in microseconds. More...

void	mtcp_app_join (mctx_t mctx)
	Pause mtcp application context since it is not running anything. More...

int	mtcp_getpeername (mctx_t mctx, int sock, struct sockaddr saddr, socklen_t addrlen, int side)
	Get IP addrs/ports for both sides. More...

int	mtcp_setlastpkt (mctx_t mctx, int sock, int side, off_t offset, byte *data, uint16_t datalen, int option)
	Updates the Ethernet frame at a given offset across datalen bytes. More...

int	mtcp_reset_conn (mctx_t mctx, int sock)
	Drop current packet (don't forward it to the peer node) More...

int	mtcp_set_debug_string (mtcp_manager_t mtcp, const char *fmt,...)

int	mtcp_get_debug_string (mctx_t mctx, char *buf, int len)

int	mtcp_sendpkt (mctx_t mctx, int sock, const struct pkt_info *pkt)
	Send a TCP packet of struct pkt_info. More...

Macro Definition Documentation

#define __MTCP_MANAGER

#define __SOCKET_MAP

#define MOS_CHOMP (1 << 8)

#define MOS_DROP (1 << 6)

#define MOS_ETH_HDR (1 << 0)

#define MOS_INSERT (1 << 9)

#define MOS_IP_HDR (1 << 1)

#define MOS_OVERWRITE (1 << 7)

#define MOS_TCP_HDR (1 << 2)

#define MOS_TCP_PAYLOAD (1 << 3)

#define MOS_UPDATE_IP_CHKSUM (1 << 4)

#define MOS_UPDATE_TCP_CHKSUM (1 << 5)

#define MTCP_CB_GETCURPKT_CREATE_COPY

#define PKT_INFO_LEN offsetof(struct pkt_info, ethh)

#define SOL_MONSOCKET 0xfffe /* MOS monitor socket level */

#define SOL_SOCKET 0xffff /* options for socket level */

The available level number in the POSIX library for sockets is on SOL_SOCKET.

Typedef Documentation

typedef void(* callback_t) (mctx_t mctx, int sock, int side, event_t event, filter_arg_t *arg)

Prototype of callback function.

typedef uint64_t event_t

Definition of event type.

typedef struct filter_arg filter_arg_t

typedef bool(* filter_t) (mctx_t mctx, int sock, int side, event_t event, filter_arg_t *arg)

Prototype of UDE's filter function.

typedef union monitor_filter* monitor_filter_t

typedef struct mtcp_manager* mtcp_manager_t

typedef struct socket_map* socket_map_t

Enumeration Type Documentation

anonymous enum

mOS segment overlapping policies

Enumerator
MOS_OVERLAP_POLICY_FIRST
MOS_OVERLAP_POLICY_LAST
MOS_OVERLAP_CNT

anonymous enum

Definition of monitor side.

Enumerator
MOS_SIDE_CLI
MOS_SIDE_SVR
MOS_SIDE_BOTH

enum mos_event_type

Built-in events provided by mOS.

Enumerator
MOS_NULL_EVENT	invalid event
MOS_ON_PKT_IN	A packet is coming in.
MOS_ON_PKT_OUT	A packet is going out.
MOS_ON_CONN_START	SYN packet as seen by the monitor client side: activated when the client state is set to SYN_SENT server side: activated when the server state is set to SYN_RCVD. Retransmitted SYN packets don't activate this event.
MOS_ON_CONN_SETUP	3-way handshake is finished. server side: ACK is coming in as a response of SYNACK. client side: SYNACK is coming in as a response of SYN.
MOS_ON_CONN_NEW_DATA	New data is now readable. This event is available in only MOS_NULL hook point. mOS raises this event only once while batched packet processing.
MOS_ON_ERROR	Abnormal behavior is detected. NOTE: This is not fully implemented yet.
MOS_ON_TIMEOUT	No packet is seen for a long time. This is implemented as mtcp_cb_settimer()
MOS_ON_TCP_STATE_CHANGE	TCP state is being changed.
MOS_ON_ORPHAN	A packet is not SYN and has no identified flow.
MOS_ON_REXMIT	Retransmission is detected.
MOS_ON_CONN_END	A flow is about to be destroyed. 4-way handshake, RST packet or timeout could be the reason. NOTE: In current implementation, mOS raises this event while destroying `struct tcp_stream`. There is possibility of false-positive especially when mOS is running out of memory.
MOS_ON_DEBUG_MESSAGE	This event is for debugging. We can easily mute this later.

enum mos_socket_opts

MOS monitor socket option names (and values) This will contain options pertaining to monitor stream sockets.

MOS_FRAGINFO_CLIBUF : Gives back offsets to fragments of buffers (optname) currently stored in client's TCP ring buffer. (getsockopt)

MOS_FRAGINFO_SVRBUF : Gives back offsets to fragments of buffers (optname) currently stored in server's TCP ring buffer. (getsockopt)

MOS_INFO_CLIBUF : Gives back tcp info for client-side ring buffer. (optname) (getsockopt)

MOS_INFO_SVRBUF : Gives back tcp info for server-side ring buffer. (optname) (getsockopt)

MOS_TCP_STATE_CLI : Retrieves current TCP state for client side (optname) (getsockopt)

MOS_TCP_STATE_SVR : Retrieves current TCP state for server side (optname) (getsockopt)

MOS_TIMESTAMP : Retrieves timestamp of last packet seen for (optname) given flow. (in usecs) (getsockopt)

MOS_SEQ_REMAP : Changes the sequence number change (optname) (setsockopt)

MOS_STOP_MON : Stop monitoring (optname) (setsockopt)

Enumerator
MOS_FRAGINFO_CLIBUF
MOS_FRAGINFO_SVRBUF
MOS_INFO_CLIBUF
MOS_INFO_SVRBUF
MOS_TCP_STATE_CLI
MOS_TCP_STATE_SVR
MOS_TIMESTAMP
MOS_MONLEVEL
MOS_CLIBUF
MOS_SVRBUF
MOS_SEQ_REMAP
MOS_STOP_MON
MOS_FRAG_CLIBUF
MOS_FRAG_SVRBUF
MOS_CLIOVERLAP
MOS_SVROVERLAP

enum mtcp_hook_point

Available hooking points.

Enumerator
MOS_NULL	Very first hooking point of incoming packet even before flow identification.
MOS_HK_RCV	Hooking point before TCP receiver.
MOS_HK_SND	Hooking point after TCP sender.

enum tcpstate

mOS tcp stream states.

used by the monitor application to retreive tcp_stream-state info. Usually called via getsockopt() function

Enumerator
TCP_CLOSED
TCP_LISTEN
TCP_SYN_SENT
TCP_SYN_RCVD
TCP_ESTABLISHED
TCP_FIN_WAIT_1
TCP_FIN_WAIT_2
TCP_CLOSE_WAIT
TCP_CLOSING
TCP_LAST_ACK
TCP_TIME_WAIT

Function Documentation

event_t mtcp_alloc_event ( event_t event )

Allocate a child event.

Parameters

[in] event event id

Returns: new event id on success, 0 on error

void mtcp_app_join ( mctx_t mctx )

Pause mtcp application context since it is not running anything.

Parameters

[in] mctx mtcp context

This is useful for running callback-only applications

int mtcp_bind_monitor_filter	(	mctx_t	mctx,
		int	sock,
		monitor_filter_t	ft
	)

uint32_t mtcp_cb_get_ts ( mctx_t mctx )

A sibling function to mtcp_settimer that returns the current timestamp of the machine in microseconds.

This avoids the monitor application to call current time getter functions (e.g. gettimeofday) that may incur overhead.

Parameters

[in] mctx mtcp context Returns timestamp on success, 0 on failure.

event_t mtcp_define_event	(	event_t	event,
		filter_t	filter,
		struct filter_arg *	arg
	)

Define a user-defined event function.

Parameters

[in]	event	event id
[in]	filter	filter fucntion for new event
[in]	arg	a filter argument to be delivered to the filter

Returns: new event id on success, 0 on error

(both for packet-level and flow-level)

int mtcp_get_debug_string	(	mctx_t	mctx,
		char *	buf,
		int	len
	)

void* mtcp_get_uctx	(	mctx_t	mctx,
		int	sock
	)

Get user-level context (e.g., to retrieve user-defined metadata stored in mtcp_set_uctx())

Parameters

[in]	mctx	mtcp context
[in]	sock	the monitor socket id

Returns: user-level context for input flow_ocntext

int mtcp_getlastpkt	(	mctx_t	mctx,
		int	sock,
		int	side,
		struct pkt_info *	p
	)

Get current packet of mtcp context.

Parameters

[in]	mctx	mTCP/mOS context
[in]	sock	monitoring stream socket id
[in]	side	side of monitoring (MOS_NULL for MOS_SOCK_MONITOR_RAW socket)
[in]	p	ptr to packet info ptr (only L2-L3 information is available for MOS_SOCK_MONITOR_RAW socket)

Returns: 0 on success, -1 on failure This is useful for running callback-only applications

int mtcp_getpeername	(	mctx_t	mctx,
		int	sock,
		struct sockaddr *	saddr,
		socklen_t *	addrlen,
		int	side
	)

Get IP addrs/ports for both sides.

(Server IP/port in 0th element) (Client IP/port in 1st element) Should only be called with MOS_SOCK_MONITOR_STREAM_ACTIVE socket Returns 0 on success, -1 on failure

ssize_t mtcp_peek	(	mctx_t	mctx,
		int	sock,
		int	side,
		char *	buf,
		size_t	len
	)

Peeking bytestream from flow_context.

Parameters

[in]	mctx	mtcp context
[in]	sock	monitoring stream socket id
[in]	side	side of monitoring (client side, server side or both)
[in]	buf	buffer for read byte stream
[in]	len	requested length

It will return the number of bytes actually read. It will return -1 if there is an error

ssize_t mtcp_ppeek	(	mctx_t	mctx,
		int	sock,
		int	side,
		char *	buf,
		size_t	count,
		uint64_t	off
	)

The mtcp_ppeek() function reads up to count bytes from the TCP ring buffer of the monitor socket sock in mctx into buf, starting from the TCP sequence number seq_num.

Note that seq_num can point the data in the fragmented buffer list of the TCP ring buffer. If there is no received byte with TCP sequence number seq_num in the TCP ring buffer, it returns error. If there are received bytes starting from seq_num, count is set to be the number of bytes read from the buffer. After mtcp_ppeek(), the data in the TCP ring buffer will not be flushed, and the monitor offset used by mtcp_peek() is not changed.

Parameters

[in]	mctx	mtcp context
[in]	sock	monitoring stream socket id
[in]	side	side of monitoring (client side, server side or both)
[in]	buf	buffer for read byte stream
[in]	count	No. of bytes to be read
[in]	seq_num	byte offset of the TCP bytestream (absolute offset: offset 0 = init_seq_num)

Returns: # of bytes actually read on success, -1 for error

int mtcp_raise_event	(	mctx_t	mctx,
		event_t	event
	)

Raise a event.

Parameters

[in]	mctx	mtcp context
[in]	event	event id

Returns: 0 on success, -1 on error

int mtcp_register_callback	(	mctx_t	mctx,
		int	sock,
		event_t	event,
		int	hook_point,
		callback_t	cb
	)

Register a callback function in hook_point.

Parameters

[in]	mctx	mtcp context
[in]	sock	socket id
[in]	event	event id
[in]	hook_point	MOS_HK_RCV, MOS_HK_SND, MOS_DONTCARE
[in]	cb	callback fucntion

Returns: zero on success, -1 on error

(both for packet-level and flow-level) for events in hook_point

int mtcp_reset_conn	(	mctx_t	mctx,
		int	sock
	)

Drop current packet (don't forward it to the peer node)

Parameters

[in] mctx mtcp context

This is useful for running callback-only applications This function is now deprecated...

int mtcp_sendpkt	(	mctx_t	mctx,
		int	sock,
		const struct pkt_info *	pkt
	)

Send a TCP packet of struct pkt_info.

Parameters

[in]	mctx	mTCP/mOS context
[in]	sock	monitoring stream socket id
[in]	pkt	ptr to packet info (e.g., captured by mtcp_getlastpkt)

Returns: 0 on success, -1 on failure (NOTE: this function supports only TCP packet for now. we will add the support for any ethernet packets when required)

int mtcp_set_debug_string	(	mtcp_manager_t	mtcp,
		const char *	fmt,
			...
	)

void mtcp_set_uctx	(	mctx_t	mctx,
		int	sock,
		void *	uctx
	)

Set user-level context (e.g., to store any per-flow user-defined meatadata)

Parameters

[in]	mctx	mtcp context
[in]	sock	the monitor socket id
[in]	uctx	user-level context

int mtcp_setlastpkt	(	mctx_t	mctx,
		int	sock,
		int	side,
		off_t	offset,
		byte *	data,
		uint16_t	datalen,
		int	option
	)

Updates the Ethernet frame at a given offset across datalen bytes.

Parameters

[in]	mctx	mtcp context
[in]	sock	monitoring socket
[in]	side	monitoring side (MOS_NULL for MOS_SOCK_MONITOR_RAW socket)
[in]	offset	the offset from where the data needs to be written
[in]	data	the data buffer that needs to be written
[in]	datalen	the length of data that needs to be written
[in]	option	disjunction of MOS_ETH_HDR, MOS_IP_HDR, MOS_TCP_HDR, MOS_TCP_PAYLOAD, MOS_DROP_PKT, MOS_UPDATE_TCP_CHKSUM, MOS_UPDATE_IP_CHKSUM

Returns: Returns 0 on success, -1 on failure

If you want to chomp/insert something in the payload: (i) first update the ip header to adjust iph->tot_len field; (MOS_OVERWRITE) (ii) then update the tcp payload accordingly (MOS_CHOMP or MOS_INSERT)

MOS_DROP, MOS_OVERWRITE, MOS_CHOMP and MOS_INSERT are mutually exclusive operations

At the moment, mtcp_setlastpkt() will only work if the pkt size is NOT modified.

int mtcp_settimer	(	mctx_t	mctx,
		int	id,
		struct timeval *	timeout,
		callback_t	cb
	)

Register user's custom timer.

Parameters

[in]	mctx	mtcp context
[in]	id	timer id
[in]	timeout	timeout length
[in]	cb	callback function

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation