aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/networking
diff options
context:
space:
mode:
authorJamal Hadi Salim <hadi@cyberus.ca>2006-04-14 18:05:16 -0400
committerDavid S. Miller <davem@davemloft.net>2006-04-14 18:05:16 -0400
commitb8a99520f78e23e47f9efffeb0060c1385064ff6 (patch)
tree49dab75993e179bc97d09d582bf4f5b444b09cdb /Documentation/networking
parent2717096ab41eacdbf07352dca6826b59470eb39a (diff)
[XFRM]: Add documentation for async events.
Documentation to describe asynchronous xfrm events to help people writting HA code in user space. Signed-off-by: Jamal Hadi Salim <hadi@cyberus.ca> Signed-off-by: David S. Miller <davem@davemloft.net>
Diffstat (limited to 'Documentation/networking')
-rw-r--r--Documentation/networking/xfrm_sync.txt166
1 files changed, 166 insertions, 0 deletions
diff --git a/Documentation/networking/xfrm_sync.txt b/Documentation/networking/xfrm_sync.txt
new file mode 100644
index 000000000000..8be626f7c0b8
--- /dev/null
+++ b/Documentation/networking/xfrm_sync.txt
@@ -0,0 +1,166 @@
1
2The sync patches work is based on initial patches from
3Krisztian <hidden@balabit.hu> and others and additional patches
4from Jamal <hadi@cyberus.ca>.
5
6The end goal for syncing is to be able to insert attributes + generate
7events so that the an SA can be safely moved from one machine to another
8for HA purposes.
9The idea is to synchronize the SA so that the takeover machine can do
10the processing of the SA as accurate as possible if it has access to it.
11
12We already have the ability to generate SA add/del/upd events.
13These patches add ability to sync and have accurate lifetime byte (to
14ensure proper decay of SAs) and replay counters to avoid replay attacks
15with as minimal loss at failover time.
16This way a backup stays as closely uptodate as an active member.
17
18Because the above items change for every packet the SA receives,
19it is possible for a lot of the events to be generated.
20For this reason, we also add a nagle-like algorithm to restrict
21the events. i.e we are going to set thresholds to say "let me
22know if the replay sequence threshold is reached or 10 secs have passed"
23These thresholds are set system-wide via sysctls or can be updated
24per SA.
25
26The identified items that need to be synchronized are:
27- the lifetime byte counter
28note that: lifetime time limit is not important if you assume the failover
29machine is known ahead of time since the decay of the time countdown
30is not driven by packet arrival.
31- the replay sequence for both inbound and outbound
32
331) Message Structure
34----------------------
35
36nlmsghdr:aevent_id:optional-TLVs.
37
38The netlink message types are:
39
40XFRM_MSG_NEWAE and XFRM_MSG_GETAE.
41
42A XFRM_MSG_GETAE does not have TLVs.
43A XFRM_MSG_NEWAE will have at least two TLVs (as is
44discussed further below).
45
46aevent_id structure looks like:
47
48 struct xfrm_aevent_id {
49 struct xfrm_usersa_id sa_id;
50 __u32 flags;
51 };
52
53xfrm_usersa_id in this message layout identifies the SA.
54
55flags are used to indicate different things. The possible
56flags are:
57 XFRM_AE_RTHR=1, /* replay threshold*/
58 XFRM_AE_RVAL=2, /* replay value */
59 XFRM_AE_LVAL=4, /* lifetime value */
60 XFRM_AE_ETHR=8, /* expiry timer threshold */
61 XFRM_AE_CR=16, /* Event cause is replay update */
62 XFRM_AE_CE=32, /* Event cause is timer expiry */
63 XFRM_AE_CU=64, /* Event cause is policy update */
64
65How these flags are used is dependent on the direction of the
66message (kernel<->user) as well the cause (config, query or event).
67This is described below in the different messages.
68
69The pid will be set appropriately in netlink to recognize direction
70(0 to the kernel and pid = processid that created the event
71when going from kernel to user space)
72
73A program needs to subscribe to multicast group XFRMNLGRP_AEVENTS
74to get notified of these events.
75
762) TLVS reflect the different parameters:
77-----------------------------------------
78
79a) byte value (XFRMA_LTIME_VAL)
80This TLV carries the running/current counter for byte lifetime since
81last event.
82
83b)replay value (XFRMA_REPLAY_VAL)
84This TLV carries the running/current counter for replay sequence since
85last event.
86
87c)replay threshold (XFRMA_REPLAY_THRESH)
88This TLV carries the threshold being used by the kernel to trigger events
89when the replay sequence is exceeded.
90
91d) expiry timer (XFRMA_ETIMER_THRESH)
92This is a timer value in milliseconds which is used as the nagle
93value to rate limit the events.
94
953) Default configurations for the parameters:
96----------------------------------------------
97
98By default these events should be turned off unless there is
99at least one listener registered to listen to the multicast
100group XFRMNLGRP_AEVENTS.
101
102Programs installing SAs will need to specify the two thresholds, however,
103in order to not change existing applications such as racoon
104we also provide default threshold values for these different parameters
105in case they are not specified.
106
107the two sysctls/proc entries are:
108a) /proc/sys/net/core/sysctl_xfrm_aevent_etime
109used to provide default values for the XFRMA_ETIMER_THRESH in incremental
110units of time of 100ms. The default is 10 (1 second)
111
112b) /proc/sys/net/core/sysctl_xfrm_aevent_rseqth
113used to provide default values for XFRMA_REPLAY_THRESH parameter
114in incremental packet count. The default is two packets.
115
1164) Message types
117----------------
118
119a) XFRM_MSG_GETAE issued by user-->kernel.
120XFRM_MSG_GETAE does not carry any TLVs.
121The response is a XFRM_MSG_NEWAE which is formatted based on what
122XFRM_MSG_GETAE queried for.
123The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs.
124*if XFRM_AE_RTHR flag is set, then XFRMA_REPLAY_THRESH is also retrieved
125*if XFRM_AE_ETHR flag is set, then XFRMA_ETIMER_THRESH is also retrieved
126
127b) XFRM_MSG_NEWAE is issued by either user space to configure
128or kernel to announce events or respond to a XFRM_MSG_GETAE.
129
130i) user --> kernel to configure a specific SA.
131any of the values or threshold parameters can be updated by passing the
132appropriate TLV.
133A response is issued back to the sender in user space to indicate success
134or failure.
135In the case of success, additionally an event with
136XFRM_MSG_NEWAE is also issued to any listeners as described in iii).
137
138ii) kernel->user direction as a response to XFRM_MSG_GETAE
139The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs.
140The threshold TLVs will be included if explicitly requested in
141the XFRM_MSG_GETAE message.
142
143iii) kernel->user to report as event if someone sets any values or
144thresholds for an SA using XFRM_MSG_NEWAE (as described in #i above).
145In such a case XFRM_AE_CU flag is set to inform the user that
146the change happened as a result of an update.
147The message will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs.
148
149iv) kernel->user to report event when replay threshold or a timeout
150is exceeded.
151In such a case either XFRM_AE_CR (replay exceeded) or XFRM_AE_CE (timeout
152happened) is set to inform the user what happened.
153Note the two flags are mutually exclusive.
154The message will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs.
155
156Exceptions to threshold settings
157--------------------------------
158
159If you have an SA that is getting hit by traffic in bursts such that
160there is a period where the timer threshold expires with no packets
161seen, then an odd behavior is seen as follows:
162The first packet arrival after a timer expiry will trigger a timeout
163aevent; i.e we dont wait for a timeout period or a packet threshold
164to be reached. This is done for simplicity and efficiency reasons.
165
166-JHS