path: root/src/vnet/ipfix-export/ipfix_doc.md

# IPFIX support {#ipfix_doc}

VPP includes a high-performance IPFIX record exporter. This note
explains how to use the internal APIs to export IPFIX data, and how to
configure and send the required IPFIX templates.

As you'll see, a bit of typing is required. 

## First: create an ipfix "report"

Include the flow report header file, fill out a @ref
vnet_flow_report_add_del_args_t structure, and call vnet_flow_report_add_del.

```{.c}
   #include <vnet/ipfix-export/flow_report.h>
   /* Defined in flow_report.h, of interest when constructing reports */

   /* ipfix field definitions for a particular report */
   typedef struct
   {
     u32 info_element;
     u32 size;
   } ipfix_report_element_t;

   /* Report add/del argument structure */
   typedef struct
   {
     /* Callback to flush current ipfix packet / frame */
     vnet_flow_data_callback_t *flow_data_callback;

     /* Callback to build the template packet rewrite string */
     vnet_flow_rewrite_callback_t *rewrite_callback;

     /* List of ipfix elements in the report */
     ipfix_report_element_t *report_elements;
     u32 n_report_elements;
     /* Kept in flow report, used e.g. by flow classifier */
     opaque_t opaque;
     /* Add / delete a report */
     int is_add;
     /* Ipfix "domain-ID", see RFC, set as desired */
     u32 domain_id;
     /* ipfix packet source port, often set to UDP_DST_PORT_ipfix */
     u16 src_port;
     /* Set by ipfix infra, needed to send data packets */
     u32 *stream_indexp;
   } vnet_flow_report_add_del_args_t;

   /* Private header file contents */

   /* Report ipfix element definition */
   #define foreach_simple_report_ipfix_element     \
   _(sourceIPv4Address, 4)                         \
   _(destinationIPv4Address, 4)                    \
   _(sourceTransportPort, 2)                       \
   _(destinationTransportPort, 2)                  \
   _(protocolIdentifier, 1)                        \
   _(flowStartMicroseconds, 8)                     \
   _(flowEndMicroseconds, 8)

   static ipfix_report_element_t simple_report_elements[] = {
   #define _(a,b) {a,b},
     foreach_simple_report_ipfix_element
   #undef _
   };

   typedef struct
   {
     /** Buffers and frames, per thread */
     vlib_buffer_t **buffers_by_thread;
     vlib_frame_t **frames_by_thread;
     u32 *next_record_offset_by_thread;

     /** Template ID's */
     u16 *template_ids;

     /** Time reference pair */
     u64 usec_time_0;
     f64 vlib_time_0;

     /** Stream index */
     u32 stream_index;

     /* Convenience */
     flow_report_main_t *flow_report_main;
     vlib_main_t *vlib_main;
     vnet_main_t *vnet_main;
   } my_logging_main_t;
   
   extern my_logging_main_t my_logging_main;

   ...

   /* Recitations */
   flow_report_main_t *frm = &flow_report_main;
   my_logging_main_t *mlm = &my_logging_main;
   vnet_flow_report_add_del_args_t a;
   int rv;
   u16 template_id;

   ... 

   /* Init function: set up time reference pair */
   mlm->vlib_time_0 = vlib_time_now (vm);
   mlm->milisecond_time_0 = unix_time_now_nsec () * 1e-6;

   ...

   /* Create a report */
   memset (&a, 0, sizeof (a));
   a.is_add = 1 /* to enable the report */;
   a.domain_id = 1 /* pick a domain ID */;
   a.src_port = UDP_DST_PORT_ipfix /* src port for reports */;

   /* Use the generic template packet rewrite string generator */
   a.rewrite_callback = vnet_flow_rewrite_generic_callback;

   /* Supply a list of ipfix report elements */
   a.report_elements = simple_report_elements;
   a.n_report_elements = ARRAY_LEN (simple_report_elements);

   /* Pointer to the ipfix stream index, set by the report infra */
   a.stream_indexp = &mlm->stream_index;
   a.flow_data_callback = my_flow_data_callback;

   /* Create the report */
   rv = vnet_flow_report_add_del (frm, &a, &template_id);
   if (rv) 
     oops...

   /* Save the template-ID for later use */
   mlm->template_id = template_id;

```

Several things are worth describing in more detail.

### vnet_flow_rewrite_generic_callback programming

This generic callback helps build ipfix template packets.  When
registering an ipfix report, pass an (array, count)
of ipfix elements as shown above. 

### my_flow_data_callback

The ipfix flow export infrastructure calls this callback to flush the
current ipfix packet; to make sure that ipfix data is not retained for
an unreasonably long period of time.

We typically code it as shown below, to call an application-specific
function with (uninteresting arguments), and "do_flush = 1":


```{.c}

      vlib_frame_t *my_flow_data_callback
                   (flow_report_main_t * frm,
	           flow_report_t * fr,
		   vlib_frame_t * f,
		   u32 * to_next, u32 node_index)
      { 

         my_buffer_flow_record (0, ... , 0, 1 /* do_flush */);
         return f;
      }
```

### my_flow_data_header

This function creates the packet header for an ipfix data packet

```{.c}

   static inline void
   my_flow_report_header (flow_report_main_t * frm,
			  vlib_buffer_t * b0, u32 * offset)
   {
      my_logging_main_t *mlm = &my_logging_main;
      flow_report_stream_t *stream;
      ip4_ipfix_template_packet_t *tp;
      ipfix_message_header_t *h = 0;


      ipfix_set_header_t *s = 0;
      ip4_header_t *ip;
      udp_header_t *udp;

      stream = &frm->streams[mlm->stream_index];

      b0->current_data = 0;
      b0->current_length = sizeof (*ip) + sizeof (*udp) + sizeof (*h) +
        sizeof (*s);
      b0->flags |= (VLIB_BUFFER_TOTAL_LENGTH_VALID | VNET_BUFFER_F_FLOW_REPORT);
      vnet_buffer (b0)->sw_if_index[VLIB_RX] = 0;
      vnet_buffer (b0)->sw_if_index[VLIB_TX] = frm->fib_index;
      tp = vlib_buffer_get_current (b0);
      ip = (ip4_header_t *) & tp->ip4;
      udp = (udp_header_t *) (ip + 1);
      h = (ipfix_message_header_t *) (udp + 1);
      s = (ipfix_set_header_t *) (h + 1);

      ip->ip_version_and_header_length = 0x45;
      ip->ttl = 254;
      ip->protocol = IP_PROTOCOL_UDP;
      ip->flags_and_fragment_offset = 0;
      ip->src_address.as_u32 = frm->src_address.as_u32;
      ip->dst_address.as_u32 = frm->ipfix_collector.as_u32;
      udp->src_port = clib_host_to_net_u16 (stream->src_port);
      udp->dst_port = clib_host_to_net_u16 (frm->collector_port);
      udp->checksum = 0;

      h->export_time = clib_host_to_net_u32 ((u32)
            				 (((f64) frm->unix_time_0) +
               				  (vlib_time_now (frm->vlib_main) -
               				   frm->vlib_time_0)));
         h->sequence_number = clib_host_to_net_u32 (stream->sequence_number++);
         h->domain_id = clib_host_to_net_u32 (stream->domain_id);

         *offset = (u32) (((u8 *) (s + 1)) - (u8 *) tp);
   }
   ```

   ### fixup and transmit a flow record

   ```{.c}
      
      static inline void
      my_send_ipfix_pkt (flow_report_main_t * frm,
           		 vlib_frame_t * f, vlib_buffer_t * b0, u16 template_id)
      {
        ip4_ipfix_template_packet_t *tp;
        ipfix_message_header_t *h = 0;
        ipfix_set_header_t *s = 0;
        ip4_header_t *ip;
        udp_header_t *udp;
        vlib_main_t *vm = frm->vlib_main;

        tp = vlib_buffer_get_current (b0);
        ip = (ip4_header_t *) & tp->ip4;
        udp = (udp_header_t *) (ip + 1);
        h = (ipfix_message_header_t *) (udp + 1);
        s = (ipfix_set_header_t *) (h + 1);

        s->set_id_length = ipfix_set_id_length (template_id,
      					  b0->current_length -
      					  (sizeof (*ip) + sizeof (*udp) +
      					   sizeof (*h)));
        h->version_length = version_length (b0->current_length -
      				      (sizeof (*ip) + sizeof (*udp)));

        ip->length = clib_host_to_net_u16 (b0->current_length);
        ip->checksum = ip4_header_checksum (ip);
        udp->length = clib_host_to_net_u16 (b0->current_length - sizeof (*ip));

        if (frm->udp_checksum)
          {
            udp->checksum = ip4_tcp_udp_compute_checksum (vm, b0, ip);
            if (udp->checksum == 0)
      	udp->checksum = 0xffff;
          }

        ASSERT (ip->checksum == ip4_header_checksum (ip));

        vlib_put_frame_to_node (vm, ip4_lookup_node.index, f);
      }  
   ```

   ### my_buffer_flow_record

   This is the key routine which paints individual flow records into
   an ipfix packet under construction. It's pretty straightforward
   (albeit stateful) vpp data-plane code. The code shown below is
   thread-safe by construction.

   ```{.c}
   static inline void
   my_buffer_flow_record_internal (my_flow_record_t * rp, int do_flush,
                                       u32 thread_index)
   {
     vlib_main_t *vm = vlib_mains[thread_index];
     my_logging_main_t *mlm = &jvp_ipfix_main;
     flow_report_main_t *frm = &flow_report_main;
     vlib_frame_t *f;
     vlib_buffer_t *b0 = 0;
     u32 bi0 = ~0;
     u32 offset;

     b0 = mlm->buffers_by_thread[thread_index];

     if (PREDICT_FALSE (b0 == 0))
       {
         if (do_flush)
   	return;

         if (vlib_buffer_alloc (vm, &bi0, 1) != 1)
   	{
   	  clib_warning ("can't allocate ipfix data buffer");
   	  return;
   	}

         b0 = vlib_get_buffer (vm, bi0);
         VLIB_BUFFER_TRACE_TRAJECTORY_INIT (b0);
         offset = 0;
         mlm->buffers_by_thread[thread_index] = b0;
       }
     else
       {
         bi0 = vlib_get_buffer_index (vm, b0);
         offset = mlm->next_record_offset_by_thread[thread_index];
       }

     f = mlm->frames_by_thread[thread_index];
     if (PREDICT_FALSE (f == 0))
       {
         u32 *to_next;
         f = vlib_get_frame_to_node (vm, ip4_lookup_node.index);
         mlm->frames_by_thread[thread_index] = f;
         to_next = vlib_frame_vector_args (f);
         to_next[0] = bi0;
         f->n_vectors = 1;
         mlm->frames_by_thread[thread_index] = f;
       }

     if (PREDICT_FALSE (offset == 0))
       my_flow_report_header (frm, b0, &offset);

     if (PREDICT_TRUE (do_flush == 0))
       {
         /* Paint the new ipfix data record into the buffer */
         clib_memcpy (b0->data + offset, rp, sizeof (*rp));
         offset += sizeof (*rp);
         b0->current_length += sizeof (*rp);
       }

     if (PREDICT_FALSE (do_flush || (offset + sizeof (*rp)) > frm->path_mtu))
       {
         /* Nothing to send? */
         if (offset == 0)
   	return;

         send_ipfix_pkt (frm, f, b0, mlm->template_ids[0]);
         mlm->buffers_by_thread[thread_index] = 0;
         mlm->frames_by_thread[thread_index] = 0;
         offset = 0;
       }
     mlm->next_record_offset_by_thread[thread_index] = offset;
   }  

   static void
   my_buffer_flow_record (my_flow_record_t * rp, int do_flush)
   {
     u32 thread_index = vlib_get_thread_index();
     my_buffer_flow_record_internal (rp, do_flush, thread_index);
   }  

```