About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / networking / strparser.txt




Custom Search

Based on kernel version 4.9. Page generated on 2016-12-21 14:36 EST.

1	Stream Parser
2	-------------
3	
4	The stream parser (strparser) is a utility that parses messages of an
5	application layer protocol running over a TCP connection. The stream
6	parser works in conjunction with an upper layer in the kernel to provide
7	kernel support for application layer messages. For instance, Kernel
8	Connection Multiplexor (KCM) uses the Stream Parser to parse messages
9	using a BPF program.
10	
11	Interface
12	---------
13	
14	The API includes a context structure, a set of callbacks, utility
15	functions, and a data_ready function. The callbacks include
16	a parse_msg function that is called to perform parsing (e.g.
17	BPF parsing in case of KCM), and a rcv_msg function that is called
18	when a full message has been completed.
19	
20	A stream parser can be instantiated for a TCP connection. This is done
21	by:
22	
23	strp_init(struct strparser *strp, struct sock *csk,
24		  struct strp_callbacks *cb)
25	
26	strp is a struct of type strparser that is allocated by the upper layer.
27	csk is the TCP socket associated with the stream parser. Callbacks are
28	called by the stream parser.
29	
30	Callbacks
31	---------
32	
33	There are four callbacks:
34	
35	int (*parse_msg)(struct strparser *strp, struct sk_buff *skb);
36	
37	    parse_msg is called to determine the length of the next message
38	    in the stream. The upper layer must implement this function. It
39	    should parse the sk_buff as containing the headers for the
40	    next application layer messages in the stream.
41	
42	    The skb->cb in the input skb is a struct strp_rx_msg. Only
43	    the offset field is relevant in parse_msg and gives the offset
44	    where the message starts in the skb.
45	
46	    The return values of this function are:
47	
48	    >0 : indicates length of successfully parsed message
49	    0  : indicates more data must be received to parse the message
50	    -ESTRPIPE : current message should not be processed by the
51	          kernel, return control of the socket to userspace which
52	          can proceed to read the messages itself
53	    other < 0 : Error is parsing, give control back to userspace
54	          assuming that synchronization is lost and the stream
55	          is unrecoverable (application expected to close TCP socket)
56	
57	    In the case that an error is returned (return value is less than
58	    zero) the stream parser will set the error on TCP socket and wake
59	    it up. If parse_msg returned -ESTRPIPE and the stream parser had
60	    previously read some bytes for the current message, then the error
61	    set on the attached socket is ENODATA since the stream is
62	    unrecoverable in that case.
63	
64	void (*rcv_msg)(struct strparser *strp, struct sk_buff *skb);
65	
66	    rcv_msg is called when a full message has been received and
67	    is queued. The callee must consume the sk_buff; it can
68	    call strp_pause to prevent any further messages from being
69	    received in rcv_msg (see strp_pause below). This callback
70	    must be set.
71	
72	    The skb->cb in the input skb is a struct strp_rx_msg. This
73	    struct contains two fields: offset and full_len. Offset is
74	    where the message starts in the skb, and full_len is the
75	    the length of the message. skb->len - offset may be greater
76	    then full_len since strparser does not trim the skb.
77	
78	int (*read_sock_done)(struct strparser *strp, int err);
79	
80	     read_sock_done is called when the stream parser is done reading
81	     the TCP socket. The stream parser may read multiple messages
82	     in a loop and this function allows cleanup to occur when existing
83	     the loop. If the callback is not set (NULL in strp_init) a
84	     default function is used.
85	
86	void (*abort_parser)(struct strparser *strp, int err);
87	
88	     This function is called when stream parser encounters an error
89	     in parsing. The default function stops the stream parser for the
90	     TCP socket and sets the error in the socket. The default function
91	     can be changed by setting the callback to non-NULL in strp_init.
92	
93	Functions
94	---------
95	
96	The upper layer calls strp_tcp_data_ready when data is ready on the lower
97	socket for strparser to process. This should be called from a data_ready
98	callback that is set on the socket.
99	
100	strp_stop is called to completely stop stream parser operations. This
101	is called internally when the stream parser encounters an error, and
102	it is called from the upper layer when unattaching a TCP socket.
103	
104	strp_done is called to unattach the stream parser from the TCP socket.
105	This must be called after the stream processor has be stopped.
106	
107	strp_check_rcv is called to check for new messages on the socket. This
108	is normally called at initialization of the a stream parser instance
109	of after strp_unpause.
110	
111	Statistics
112	----------
113	
114	Various counters are kept for each stream parser for a TCP socket.
115	These are in the strp_stats structure. strp_aggr_stats is a convenience
116	structure for accumulating statistics for multiple stream parser
117	instances. save_strp_stats and aggregate_strp_stats are helper functions
118	to save and aggregate statistics.
119	
120	Message assembly limits
121	-----------------------
122	
123	The stream parser provide mechanisms to limit the resources consumed by
124	message assembly.
125	
126	A timer is set when assembly starts for a new message. The message
127	timeout is taken from rcvtime for the associated TCP socket. If the
128	timer fires before assembly completes the stream parser is aborted
129	and the ETIMEDOUT error is set on the TCP socket.
130	
131	Message length is limited to the receive buffer size of the associated
132	TCP socket. If the length returned by parse_msg is greater than
133	the socket buffer size then the stream parser is aborted with
134	EMSGSIZE error set on the TCP socket. Note that this makes the
135	maximum size of receive skbuffs for a socket with a stream parser
136	to be 2*sk_rcvbuf of the TCP socket.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.