Added documentation for client config IP based configuration

Signed-off-by: Ido Barnea <[email protected]>

diff --git a/doc/trex_book.asciidoc b/doc/trex_book.asciidoc
index ec66190..ad92436 100755 (executable)
--- a/doc/trex_book.asciidoc
+++ b/doc/trex_book.asciidoc
@@ -869,30 +869,28 @@ asr1k(config)#ipv6 route 5000::/64 3001::2
 
 
 === Client clustering configuration
-TRex supports testing complex topologies, using a feature called "client clustering".
-This feature allows more detailed clustering of clients.
+TRex supports testing complex topologies, with more than one DUT, using a feature called "client clustering".
+This feature allows specifying the distribution of clients TRex emulates.
 
 Let's look at the following topology:
 
 .Topology Example 
 image:images/topology.png[title="Client Clustering",width=850]
 
+We have two clusters of DUTs.
+Using config file, you can partition TRex emulated clients to groups, and define
+how they will be spread between the DUT clusters.
 
-We would like to configure two clusters and direct traffic to them.
-
-Using config file, you can instruct TRex to generate clients
-with specific configuration per cluster.
-
-Cluster configuration includes:
+Group configuration includes:
 
 * IP start range.
 * IP end range.
-* Initiator side configuration.
-* Responder side configuration.
+* Initiator side configuration. - These are the parameters affecting packets sent from client side.
+* Responder side configuration. - These are the parameters affecting packets sent from server side.
 
 [NOTE]
 It is important to understand that this is *complimentary* to the client generator
-configured per profile - it only defines how the generator will be clustered.
+configured per profile - it only defines how the clients will be spread between clusters.
 
 Let's look at an example.
 
@@ -908,11 +906,7 @@ $cat cap2/dns.yaml
           clients_end   : "16.0.0.255"   
           servers_start : "48.0.0.1"
           servers_end   : "48.0.0.255"   
-          clients_per_gb : 201
-          min_clients    : 101
           dual_port_mask : "1.0.0.0" 
-          tcp_aging      : 1
-          udp_aging      : 1
   cap_info : 
      - name: cap2/dns.pcap
        cps : 1.0          
@@ -921,8 +915,10 @@ $cat cap2/dns.yaml
        w   : 1            
 ----
 
-We want to create two clusters with 4 devices each.
-We also want to divide *80%* of the traffic to the upper cluster and *20%* to the lower cluster.
+We want to create two clusters with 4 and 3 devices respectively.
+We also want to send *80%* of the traffic to the upper cluster and *20%* to the lower cluster.
+We can specify to which DUT the packet will be sent by MAC address or IP. We will present a MAC
+based example, and then see how to change to be IP based.
 
 We will create the following cluster configuration file.
 
@@ -938,13 +934,11 @@ We will create the following cluster configuration file.
 #
 # 'groups' - each client group must contain range of IPs
 #            and initiator and responder section
-#            'count' represents the number of different MACs
-#            addresses in the group.
-#
-# initiator and responder can contain 'vlan', 'src_mac', 'dst_mac'
+#            'count' represents the number of different DUTs
+#            in the group.
 #
 
-# each group contains a double way VLAN configuration
+# 'true' means each group must contain VLAN configuration. 'false' means no VLAN config allowed.
 vlan: true
 
 groups:
@@ -956,7 +950,7 @@ groups:
                  dst_mac : "00:00:00:01:00:00"
      responder :
                  vlan    : 200
-                 dst_mac : "00:00:00:01:00:00"
+                 dst_mac : "00:00:00:02:00:00"
 
      count     : 4
 
@@ -964,43 +958,74 @@ groups:
      ip_end    : 16.0.0.255
      initiator :
                  vlan    : 101
-                 dst_mac : "01:00:00:00:01:01"
+                 dst_mac : "00:00:01:00:00:00"
 
      responder:
                  vlan    : 201
-                 dst_mac : "01:00:00:00:02:01"
+                 dst_mac : "00:00:02:00:00:00"
 
-     count     : 4
+     count     : 3
 
 ----
 
-The above configuration will divide the generator range of 255 clients to two clusters,
-each with 4 devices and VLAN in both directions.
+The above configuration will divide the generator range of 255 clients to two clusters. The range
+of IPs in all groups in the client config file together, must cover the entire range of client IPs
+from the traffic profile file.
 
-MACs will be allocated incrementaly, with a wrap around.
+MACs will be allocated incrementally, with a wrap around after count addresses.
 
 e.g.
 
-*Initiator side:*
+*Initiator side: (packets with source in 16.x.x.x net)*
 
-* 16.0.0.1 --> dst_mac: 00:00:00:01:00:00  valn: 100 
-* 16.0.0.2 --> dst_mac: 00:00:00:01:00:01  valn: 100 
-* 16.0.0.3 --> dst_mac: 00:00:00:01:00:02  valn: 100 
-* 16.0.0.4 --> dst_mac: 00:00:00:01:00:03  valn: 100 
-* 16.0.0.5 --> dst_mac: 00:00:00:01:00:00  valn: 100 
-* 16.0.0.6 --> dst_mac: 00:00:00:01:00:01  valn: 100 
+* 16.0.0.1 -> 48.x.x.x - dst_mac: 00:00:00:01:00:00  vlan: 100 
+* 16.0.0.2 -> 48.x.x.x - dst_mac: 00:00:00:01:00:01  vlan: 100 
+* 16.0.0.3 -> 48.x.x.x - dst_mac: 00:00:00:01:00:02  vlan: 100 
+* 16.0.0.4 -> 48.x.x.x - dst_mac: 00:00:00:01:00:03  vlan: 100 
+* 16.0.0.5 -> 48.x.x.x - dst_mac: 00:00:00:01:00:00  vlan: 100 
+* 16.0.0.6 -> 48.x.x.x - dst_mac: 00:00:00:01:00:01  vlan: 100 
 
-*responder side:* 
+*responder side: (packets with source in 48.x.x.x net)* 
 
+* 48.x.x.x -> 16.0.0.1  - dst_mac(from responder) : "00:00:00:02:00:00" , vlan:200
+* 48.x.x.x -> 16.0.0.2  - dst_mac(from responder) : "00:00:00:02:00:01" , vlan:200
 
+and so on. +
+This means that the DUT MACs of each cluster has to be changed to be sequential. Other option is to
+specify instead of ``dst_mac'', ip address, using ``next_hop''. +
+For example, config file first group will look like:
 
-* server ->16.0.0.1  dst_mac(from responder) : "01:00:00:00:02:01" , valn:201
-* server ->16.0.0.2  dst_mac(from responder) : "01:00:00:00:02:02" , valn:201
+----
+-    ip_start  : 16.0.0.1
+     ip_end    : 16.0.0.204
+     initiator :
+                 vlan     : 100
+                 next_hop : 1.1.1.1
+                 src_ip   : 1.1.1.100
+     responder :
+                 vlan     : 200
+                 next_hop : 2.2.2.1
+                 src_ip   : 2.2.2.100
 
-and so on.
+     count     : 4
+----
+
+In this case, TRex will try to resolve using ARP requests the addresses
+1.1.1.1, 1.1.1.2, 1.1.1.3, 1.1.1.4 (and the range 2.2.2.1-2.2.2.4). If not all IPs are resolved,
+TRex will exit with an error message. ``src_ip'' will be used for sending gratitues ARP, and
+for filling relevant fields in ARP request. If no ``src_ip'' given, TRex will look for source
+IP in the relevant port section in the platform config file (/etc/trex_cfg.yaml). If none is found, TRex
+will exit with an error message. +
+If client config file is given, the ``dest_mac'' and ``default_gw'' parameters from the platform config
+file are ignored.
 
-With this model every client (e.g. 16.0.0.1) will always have the same path, e.g.  
-c->s side will always have initiator VLAN and init-destination MAC and in the response side (s->c) alway responder-VLAN and responder-MAC
+
+[NOTE]
+It is important to understand that the ip to MAC coupling (both with MAC based config or IP based)
+is done at the beginning and never changes. Meaning, for example, for the MAC case, packets
+with source IP 16.0.0.2 will always have VLAN 100 and dst MAC 00:00:00:01:00:01.
+Packets with destination IP 16.0.0.2 will always have VLAN 200 and dst MAC "00:00:00:02:00:01.
+This way, you can predict exactly which packet (and how many packets) will go to each DUT.
 
 *Usage:*