]>
Commit | Line | Data |
---|---|---|
adcce4d5 TH |
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. |