Project #2:

KENS Tutorial & Part 1

CS341 Fall 2016
2016. 09. 20

What is KENS?
KAIST Educational Networking System
A programming environment to build and test network protocols
KENSv3 Features:

Discrete event simulator

Virtual network devices
Virtual system call layer
Automated test suite for easy grading
Ethernet / IP / TCP

KENSv3 Framework

Install KENS
Visit and clone (and star!)

https://github.com/ANLAB-KAIST/KENSv3
Please DO NOT FORK

Or simply use terminal

$git clone https://github.com/ANLAB-KAIST/KENSv3

$tar xzvf kens-v3.skeleton.tar.gz

Currently supports Cygwin, Linux, OS X

We highly recommend Ubuntu 16.04
gcc 5.x is required
C++ 11+ is required (+gnu extensions)

Install Google Test

You need this test to run KENS and evaluate your own code
Gtest
Googles framework for C++ tests

https://code.google.com/p/googletest/
http://askubuntu.com/questions/145887/why-no-library-files-installedfor-google-test

Components

Test cases based on GoogleTest

(read if you want to)

Components

Your assignment: implement TCP module

Components
Solution that evaluates your implementation

Run test cases

$make all

Then testTCP binary will be generated in build/

$./testTCP

Will generate test results in gtest format.

Run partial test cases

$make test_part1
$make test_part2
$make test_part3
$make test_part4

Run reference solution

/app/TestTCP/testenv.hpp: line 385
Remove the comment at line 385
Run reference solution

Keep the comment at line 385

Run your solution

10

Your task is to implement TCP module

TCP module (class TCPAssignment)

HostModule: interact with other modules like IP

NetworkModule: create/delete packets
SystemCallInterface: interact with system calls like socket, bind, connect,
accept, listen, etc
TimerModule: handle timeouts

You are asked to build TCP stack

KENS project will be split into 3 parts
Connection open/close
Reliable data transfer
Congestion control

11

Project #2
Get familiar with KENS
Implement open and bind

KENS Projects
Your job is to complete TCPAssignment.cpp & TCPAssignment.hpp
*** This project is incremental! ***
Your implementation on part1 will affect implementation of part2, and so on.

Project 2: KENS #1
Run reference solution
Implement socket, bind, getsockname and close

13

Requirement #1
Run reference solution (refer to slides #10)
Open TestCongestion1.pcap with Wireshark
Statistic->IO Graph
Something like this, but use different colors

14

Requirement #2
Implement your own socket()/bind()/getsockname()/close()
Tests to be completed
$make test_part1 (refer to slides #9)
For these tests, you should implement socket/bind/getsockname/close
functions
However, passing test does not guarantee the full score

15

Team Assignment
Make a team of 1 or 2 students
Notice about project team will be on KLMS tonight
Write your team member information in a reply
Name, student ID of each member

Later on, we will announce the team ID

Use the team ID for your submission

16

Deliverables
Report + TCPAssignment.cpp, TCPAssignment.hpp and other source files you implemented.
File name: {Team_no}_Project2.zip
Ex) 03_Project2.zip, 32_Project2.zip, ..
32_Project2/

- report_proj2.pdf
- KENS1/ - TCPAssignment.cpp
- TCPAssignment.hpp
- mycode.cpp <- optional
- mycode.hpp <- optional

Content of report

Screenshot of the IO Graph

Explain your implementation of required functions

Format of report

PDF only, 12pt

At most 5 pages
ill-formatted submission wont be accepted

17

Submission Guideline
Team assignment! (or you can choose to work alone)
Due: 2:29pm on Tue, 10/4
Late submission is NOT allowed!
Late submission will get 0 point

Submit on KLMS

18

Tips for Project 2

KENS
You may not be familiar with the framework
Try really, really hard to understand how it works
Refer to KENS internals in the later section
Please, read carefully!!

Recommendations:
See how test cases work
Understand how socket APIs work
Refer to Project #1 slides supplementary material

Read the document at

http://anlab-kaist.github.io/KENSv3/doxygen/

20

testopen.cpp

21

testopen.cpp

22

socket()/bind()/getsockname()/close()
Does not actually generate network packets
Internal file descriptor/context management
Internal address management logic
Be familiar with KENS

23

Bind rule
Passive socket (server socket): need explicit bind
Active socket (client socket): need implicit bind
Address is consist of ip_address and port_number (sockaddr_in)
143.248.234.2:5555 and 10.0.0.2:5555 do not overlap
143.248.234.2:5555 and 0.0.0.0:5555 overlap (INADDR_ANY)
143.248.234.2:5555 and 143.248.234.3:5555 do not overlap
0.0.0.0:5555 and 0.0.0.0:5556 do not overlap (different port)
Closed sockets do not overlap with any socket

24

Context management
Implement bind rule for your bind
Will pass $make test_part1
Suggestion:
Make a global bound contexts list
Save whether a context is bound
Save the bounded address and port

25

Recommended books
TCP/IP Illrustrated, Vol 2, Stevens
Book about the actual implementation of TCP

26

KENS Internals
Supplementary Material

What is KENS?
KAIST Educational Networking System
A programming environment to build and test network protocols
KENSv3 Features:

Discrete Event simulator

Virtual network devices
Virtual system call layer
Automated test suite for easy grading
Ethernet / IP / TCP

28

KENSv3 Framework

29

KENSv3 Dataflow

Components

E: Event-based simulation framework

(do not have to read)

31

Components

Test cases based on GoogleTest

(read if you want to)

32

Components

Your assignment: implement TCP module

33

Components
Solution that evaluates your implementation

34

Convention
Packet :
If you have a packet (either received or allocated), you have to free it, or
pass it to other network module

Message:
If you allocated a message, you have to free it by yourselves
i.e. if you received a message, do not free it
If message is passed to the receiver, messageFinished callback or
messageCanceled are called to notify that the message is to be freed.

Detailed documentation at
http://anlab-kaist.github.io/KENSv3/doxygen/
35

HostModule
HostModule(std::string name, Host* host);
host: Host to insert this module
name: this modules name

Have to implement:
packetArrived(from_where, packet)
If IP layer passed the packet, from_where = IP

Optional implementation:
initialize(): automatically before host starts
finalize(): automatically when TCP have to clean up

36

HostModule
Provided utilities
(you can use them after you inherit this class)
(however, you cannot override them)
sendPacket(module_name, packet)
ex) sendPacket(IP, packet)
name is defined via HostModule(name, host)
getHost()
Current time (getCurrentTime)
Routing information

37

NetworkModule
You can allocate/deallocate packets
Provided utilities

You cannot directly allocate Packet

(via new Packet)

38

System Call Interface

Multiple protocols are distinguished by address family, and
protocol
Manages file descriptors and their domain
You have to implement:
systemCallback(UUID syscallUUID, int pid, const SystemCallParameter&
param)
Automatically called if system calls are raised
System calls are automatically blocks the application, you have to
unblock manually

39

System Call Interface

Provided utilities:
createFileDescriptor: allocate a new file descriptor
KENS framework handles fd number mapping to applications
removeFileDescriptor: deallocate fd
returnSystemCall(syscall_id, ret)
unblocks the system call with the return value

40

TimerModule
timerCallback(void* payload)
Automatically called with given paramter

addTimer(void* payload, Time timeAfter)

Create a timer with given parameter
timerCallback is automatically called after timeAfter
Returns a unique identifier of created timer

cancelTimer(UUID key)
Cancel the timer with the identifier

41

TCPModule is sum of:

HostModule: interact with other modules like IP
NetworkModule: create/delete packets
SystemCallInterface: interact with system calls like socket, bind,
connect, accept, listen, etc
TimerModule: handle timeouts
Please, refer to KENS doc

https://github.com/ANLAB-KAIST/KENSv3

42