From Nsnam
Jump to: navigation, search


The aim of this project is to add Network Address Translation (NAT) functionality to ns-3. Instead of just implementing NAT, we are working on introducing an extensible framework. This way, if firewall functionality needs to implemented in the future, the framework can be used to do that. The inspiration for such a framework comes from the netfilter in the Linux kernel.

Netfilter creates fives hooks in the Linux kernel networking stack. A developer can register functions at each of the hooks. These functions get called when a packet traverses the hook. While registering a function at a hook, a priority needs to be specified which will determine the order in which the function will be executed. Userspace utilities such as iptables do not interact directly with netfilter, rather, they interact with kernel modules which in turn interact with the netfilter framework.

We aim to implement something similar to netfilter framework for ns-3. This will make it easy to add firewall functionality to ns-3 in the future.


A Linux kernel module can register multiple functions at each of the netfilter hooks. The netfilter framework maintains a 2-dimensional array nf_hooks[NFPROTO_NUMPROTO][NF_MAXHOOKS] of circular linked lists. When a function is registered using nf_register_hook, a variable of type "struct nf_hook_ops" (which contains the function to be registered) is added to the appropriate list. The position within the list is determined by the priority specified in the "struct nf_hook_ops" type variable.

When a packet traverses the hook, for instance, in ip_rcv function, NF_HOOK macro is called which ends up invoking nf_hook_slow. This is the interface between the routing code and the netfilter framework. As this is the NF_PREROUTING hook, and assuming that IPv4 is being used, the linked list at nf_hooks[PF_INET][NF_PREROUTING] is consulted and the functions registered at the hook are invoked. The nf_iterate function is used to iterate through the linked list, invoking the "hook" member of the "struct nf_hook_ops" variable in turn.

The iptables userspace utility is used to add/remove/update the rules for the netfilter framework. It does not interact directly with the netfilter framework, instead, iptables works with kernel modules which in turn use the netfilter framework to implement the rule.

A rule is composed of two parts. A selection criterion and a verdict for the packet that matches the selection criteria. The verdict might entail dropping the packet, letting the packet go, changing the packet in a certain manner etc.


In order to implement Network Address Translation, we need to be able to defragment the IP packets. The implementation of this part has been postponed as the development can continue without it. However, IP packet defragmentation will be added to ns-3 later on.

Connection tracking implements protocol specific handlers for NAT. For instance, FTP, ICMP, SIP etc. Although this project will not implement the handlers themselves but it aims to provide an API so that developers can implement protocol specific connection tracking.

  • Five hooks (using ns-3 callbacks)
  • A class that stores the NAT mappings (7-tuples)
  • Connection tracking
  • Network Address Translation
  • A mechanism to configure NAT

More details regarding the implementation can be found at ns-3 Netfilter implementation details


The first two weeks will be spent studying the ns-3 networking stack and how a framework similar to netfilter can be implemented for ns-3.

  • Week 3: Implement and test IP packet defragmentation
  • Week 4,5: Implement hooks using ns-3 callbacks and a class for storing the created NAT mappings
  • Week 6: Test basic NAT functionality
  • Week 7-8: Implement Connection tracking API and start testing
  • Week 9: Implement any NAT helpers or user configuration options
  • Week 10: Merge with ns-3 codebase

Midterm Report

The midterm report for this project can be found at NAT Midterm Report