CSC4140 - Course Assignment

Building a realistic broadband router platform.

Abstract

Nowadays, most of us are using broadband connections at home. Usually, we deploy

a broadband router, which is abundant in the market, to allow multiple computers to
share the broadband connection.
As a matter of fact, building such a device is not a tough task. In this assignment,
we are going to build the software part of the device.

1 Overview

Nowadays, you should have heard of a computing device called the broadband router.
Famous vendors including D-link, Buffalo, and Linksys are manufacturing those computing
devices.

A broadband router is just a computer, usually running an operating system (OS). The
device itself is also a hardware, including all the circuitry for the networking purpose. In
this assignment, you are required to implement the software side of a broadband router.

1.1 What is a broadband router?

1.1.1 Hardware side

Figure 1 shows an example layout of an interconnected network. The broadband router

sits in the middle of two networks: the ISP network on the left and the home network on

1
 ISP Network
Broadband
modem Broadband Network
(provided by Router Switch
ISP)

NIC #1 NIC #2 Home PC #1

(WAN) (LAN)

Home PC #2

ISP Network Internal Network

Figure 1: A typical layout with a broadband router deployed.

the right. Typically, a broadband router has at least two network interface cards (for short
NICs). The naming of the NICs is based on which network it is designed for. Usually, the
ISP network is called the WAN while the home network is called the LAN.

Such a layout exists for a reason: the ISP usually gives you ONE Ethernet connection
in the broadband modem for a home network to access the ISP network. If the user (or the
family) has more than one PC, then there will be only one of them can access the network.
This creates a chance for the market of the broadband router1 .

As you can see from the figure, the broadband router is acting as a bridge between the
ISP network and the home network. It is not only simply a network bridge, but is a mini-
-firewall indeed. The router itself is usually an embedded system (or, just, a computer)
running a miniaturized version of Linux.

1.1.2 Software side

Several pieces of software are running on top of the OS, including a network connection
sharing tool, a packet filtering tool, a web server, and sometimes a printer sharing tool.
1
The ISP used by the lecturer is a good one: they provide a broadband modem that has 4 Ethernet
sockets!

2
1.2 Working of a broadband router

Obviously, the internal of a broadband router is controlled by a set of software. In the

following, we list the roles and the functionalities of the vital software inside a broadband
router.

1.2.1 Network sharing

The most basic function of a broadband router is to share the connection provided by the
ISP. Since the ISP is giving you only one IP address, because one network plug means one
IP address, and such an IP address cannot be used by all the home PCs simultaneously, the
job of the broadband router is to share the IP address obtained.

To do this, a system software called “iptables” is used inside the broadband router and
this software employs a mechanism called the network address translation2 (NAT for
short) to share the only IP address provided by the ISP.

1.2.2 Internal network management

Another thing is that the user of the broadband router are certainly not knowledgeable
enough to configure the iptables; a broadband router is supposed to be as user-friendly as
possible. As a result, the broadband router has to manage the internal LAN on behalf of
the user.

You don’t need to worry much; a network protocol called dynamic host configuration
protocol (DHCP for short) can help. In other words, the broadband router is required to
install a software which provides the DHCP service.
2
The details of iptables and NAT are covered in the tutorials.

3
1.2.3 Management user interface

Last but not least, the broadband router usually behaves as autonomous as possible, meaning
that when the user turns it on, the home PC users can access to the outside network without
any configurations.

Nevertheless, it’d be nice to provide an easy-to-use configuration interface for advanced

users. However, you can’t find any VGA, keyboard, nor mouse input ports on a broadband
router! How can one tweak the configurations of the router?

Usually, an user interface (UI for short) is provided in the form of a web-based application.
A user can visit the UI using the browser in the home PCs. In this way, the home PCs are not
required to install extra software in order to access the management system of the broadband
router.

As a result, the broadband router has to include a HTTP server program and the most
famous one is called Apache, which is a piece of open source software. In addition, in order
to prevent unintended changes on the router’s configurations, such an UI system is usually
protected under a login mechanism.

2 Assignment’s Networking Environment

Due to the hardware restriction in our department, it is hard to have a large set of computers
containing two NICs installed. As an alternative, the environment that you will be working
on is different from that in Figure 1: we will be using one physical machine only with
a virtual network deployed by VMware and the corresponding network layout is shown in
Figure 2.

The comparisons between the two setups are given in Table 1. Note that the physical
machine is just a computer connected to the outside network while the virtual PCs rely on
the configuration of the physical machine to reach the outside network.

4
 Virtual
NICs

Filtering
Outside Network and
Connection
Sharing
(iptables)

Virtual Machines
Physical
NIC OS of the
physical machine

Virtual
NICs

Virtual Internal Network

Physical Machine
(Your Removable Hard Disk)

Figure 2: The network layout used and restricted in our assignment.

Real-life setup Assignment’s setup

Machines The broadband router and the The physical machine hosts ev-
home PCs are distinct entities. erything: it is the broadband
router; the home PCs become
virtual machines and are run-
ning inside the physical ma-
chine.
Networking: It is constructed using wires and It is a virtual network provided
Internal Net- switches (may be wireless net- by VMware.
work work, too).
Networking: It is connected to the ISP, local LAN, etc.
Outside Net-
work

Table 1: Differences between the real-life network layout and the assignment’s network
layout.

5
2.1 VMware configuration

VMware has been doing really great in facilitating virtual machine supports. It provides a
virtual network environment for the virtual machines in the following three ways:

1. Bridged. (Not for networking newbies:) It means the virtual machines can own a
network address that belongs to the outside network. In other words, outsiders can
locate a virtual machine using a true IP address.

2. Host-only*. It means the virtual machine can communicate with the host, or the
physical machine, only. That means it cannot communicate to the outside world.
(* This will be the networking mode that you must use in this assignment.)

3. NAT. It stands for network address translation. This mode is the half way between
the bridged mode and the host-only mode.

• One one hand, the virtual machine can access the outside world. (So, same as the
bridged mode.)
• One the other hand, a computer in the outside network only knows the physical
machine, but not the virtual machines. (Oh, same as the host-only mode.)

In other words, the physical machine is sending and receiving network traffic on behalf
of the virtual machines.

2.1.1 Virtual machine networking configuration

The virtual machine should have the following networking configuration:

IP address Using DHCP, and the DHCP service should be provided

by the physical machine.
Default gateway The IP address of the virtual NIC of the physical ma-
chine, and it should be obtained by using DHCP.
DNS server The IP address of the virtual NIC of the physical ma-
chine, and it should be obtained by using DHCP.

6
2.1.2 Software

• The virtual machine is not restricted to any type of OS: it can be running Windows,
Linux, Mac, etc.

• Depending on your working environment, your browser needs the same HTTP proxy
setting as the physical machine.

2.2 Physical machine configuration

The physical machine is required to be running Linux. It is because of the supporting

software needed.

2.2.1 Physical machine network configuration

The physical machine has two NICs, namely the physical NIC and the virtual NIC.

Physical NIC Virtual NIC

IP address Use DHCP if the out- You can use any IP address.
side network provides the
DHCP service. Else, use a
static IP address which is
assigned by your local LAN
admin

A piece of note for the virtual NIC: you have to configure the VMware so that it has the
host-only network is enabled. To check whether the host-only NIC is up or not, run the
command:

ifconfig vmnet1

7
where “vmnet1” is the interface name of the host-only network. If the interface is not there,
an error message will be shown and you should re-configure your VMware.

2.2.2 Software

Despite of hosting the virtual machines, the physical machine is also the broadband router.
As mentioned before, the broadband router is running Linux and so does the physical machine
in our assignment’s execution environment. In addition, the physical machine must have the
following set of software installed:

1. The iptables. It is the software for network sharing between the physical and the
virtual machines. In simple words, the iptables software allows a network of virtual
machines, specified by a network address to access the outside network.
As a matter fact, this software is also installed in real-life broadband routers.

2. The Apache. It is the famous open-source web (or HTTP) server. Apache is required
because a broadband router provides a web interface that allows the home PCs to
configure the router’s settings. This web server is to host the web interface.

3. DHCP server. The DHCP server is to assign IP addresses to the virtual machines
automatically, and as a result, creates a virtual network.

4. DNS server. The physical machine should also act as a DNS server for the home
PCs.

3 Requirements of the assignment

The requirements of this assignment only focuses on the software side of the computer you
are working on. Despite the computing environment (VMware for example), you are required
to implement your own set of software to allow users to control the broadband router. The
high-level view of the software involved is shown in Figure 3.

In the following context, we will use the following set of terms interchangeablely:

8
 Apache

Hosting Execution
mode
Credential

Web-based read/write
Management iptables Network
System. Setting* Setting*

Logging
Configure

Permanent Storage
iptables
*optional

Figure 3: The big picture of the design of the system of software involved in this assignment.

• “broadband router” and “physical machine”;

• “home PC” and “virtual machine;
• “WAN” and “outside network;
• “internal network, “LAN”, and private network.

3.1 Execution mode of the broadband router

In order to let you experience different deployment scenarios of a broadband router, you are
required to implement two different execution mode of the broadband router.

3.1.1 What is the execution mode?

The execution mode describes the way the broadband router shares the connection provided
by the ISP. The two modes are:

9
 • Transparent mode. It means that the broadband router is transparent to all the
users. When the broadband router is turned on, every home PC will be able to access
the ISP network automatically.

• Login mode. It means that the broadband router is no longer transparent to the
users. Rather, it by default stops all the home PCs from accessing the outside network.
After the user of a home PC has logged in the web-based management interface of the
broadband router with a valid credential, then the concerned home PC can now access
the ISP network.

3.1.2 How to toggle different execution modes?

The broadband router is allowed to be running in either one of the above execution modes. In
order to toggle the execution mode, the user of a home PC has to provide the administrator
credential to the broadband router. We will discuss the different credentials soon.

3.2 Web-based management system

The management system is hosted in the broadband router. You have the freedom to im-
plement any kinds of interfaces using any kinds of technique, e.g., Perl-CGI programming,
PHP programming, using AJAX technique, etc. Nevertheless, your web-based system should
provide the following required components.

3.2.1 Login interface, credential storage, as well as identity and credential man-
agement

The credentials for both types of identities are login-password pairs. For each credential,
the login name must be distinct and non-empty while the password should not be empty.
The type of the credential storage is not restricted as long as the storage itself is a permanent
one.

The execution flow of the login interface is given in Figure 4. To unify (maybe, to

10
 Login page

Is the logging-in user

the adminstrator?

Yes No

Is the password No Is the password

correct? correct?

Yes Yes

Logging
Is the exeution mode Yes Logging
the "Login Mode"?

Logout
No
Log management Allow the user to
access to the
iptables Management Logging outside world.

Normal User Management Login Successful

Notification
Miscellaneous Management Login attempt is
rejected with an
appropriate
Adminstrator Login Interface error message

Figure 4: The big picture of the design of the login system.

11
complicate) the login system, you must follow the flow state in Figure 4.

The web-based system has to maintain mainly two sets of identities: the administrator
and the normal user.

• Administrator. You have to decide a login name for the administrator. Together
with the corresponding password, the login-password credential should be stored in the
permanent storage of the broadband router.

• Normal user. A normal user is only effective under the login mode. That means,
when the system is running under the transparent mode, the system should reject any
login attempts from the normal users.

Note importantly that the system should allow HTTP requests for the login interface from
the internal network only. This requires the configurations on either the Apache web
server, the iptables, or both. Please think of the correct answer by yourself.

3.2.2 Log in the system

The login interface is always there no matter what the execution mode is. The administrator
can log in the system under any one of the execution modes. Remember, the purpose of the
login action of the administrator is to manage the broadband router, not to access the
ISP network. If the administrator wants to so, then he/she should create another normal
user to do so. The function of the administration login action is different from that of a
normal user.

When the execution mode is the login mode, a normal user can log in to the system
through two methods:

• The user goes directly to the login page described in Figure 4, using a web browser.

• The user is forwarded to the said login page when the user launches a web browser and
is going to visit an arbitrary site, say “URL A”.

12
 You may have experienced such a scenario. Yes, the ERGWAVE login methodology
in the Faulty of Engineering, CUHK. The merit of such a mechanism is that the user
is not required to memorize the internal IP address of the broadband router. In other
words, the broadband router is, kind of, hiding itself.
[A challenging point.] Note that after a successful login, the login system should
lead the user back to “URL A”.

[Hint]. HTTP cookie may be helpful.

3.2.3 Logout and timeout

The system should provide a way for the administrator to log out the system. If the admin-
istrator forgets to log out before closing the web browser, the web-based system should be
able to accept the returning administrator automatically. This implies the use of HTTP
cookie. For how long should the HTTP cookie expire? The choice should be configurable
in the web-based system.

For normal users, they don’t have any incentives to log out the system. Instead of
providing a logout page that the users would never visit, the web-based system should
timeout the login session for normal users. The timeout period should be configured by the
administrator. When such a timeout period is reached, the client will be requested to login
again.

Hint. HTTP cookie is useless in this case. Instead, cron in Linux can fulfill the job.

3.2.4 Execution mode management

The execution mode management is as simple as toggling the value in the permanent storage.
Why does it reside in the permanent storage? It is because the system has to be able to
start with the previous execution mode after bootup. There are important points to note:

• If the system is in a transition from the transparent mode to the login mode but there

13
 are normal users using the NAT service, then what is the fate of the users?

The connected users need to log in to the system because there are
no login records of those users.

• If the system is in a transition from the login mode to the transparent mode but there
are logged-in, normal users using the NAT service, then what is the fate of the users?

The connected users still enjoy the NAT service with their login
records erased.

3.2.5 User management

You have to maintain a list of normal users. This is a part of the credential storage also.

This is similar to a typical user account management system but with a trimmed set of
functionalities and information to store. You only need to allow the administrator to view,
to add, to modify, and to delete a normal user. Plus, you are required to store at least
the following two pieces of information about a normal user:

username password login status

Note that “login status” states whether a user is logged in or not.

3.2.6 iptables management

The iptables management is the core function of the broadband router. The basic function
is to provide the network address translation (NAT) support. Plus, you are required to
implement to extra services: packet filtering and port forwarding.

Network address translation. The NAT should function according to the execution mode
of the system.

14
 Transparent Mode Login Mode
Default: On; Default: Off;
All computers in the internal network When a user has logged in to the sys-
can use the NAT service. tem, the home PC that the user is
using is allowed to use the NAT ser-
vice.

By default, the broadband router will forward all kinds of traffics for the computers inside
the internal network. Nevertheless, the broadband router should allow the administrator to
filter out certain services.

Filtering. This is another mechanism provided by the iptables. In this assignment, you
have to use the web-based system to control the setting of the iptables. One of those
selected settings is packet filtering.

The packet filtering function applies to both execution modes. This is set by the admin-
istrator. The web-based management system allows the administrator to view, to add, to
modify, and to delete the filtering rules. By default, there is no rules set after the system
has finished bootup. On the other hand, because the system would never know which users
and how many users are using the broadband router, the filtering function should apply to
all computers in the internal network.

One of the realistic requirements is that you have to assume that the administrator
knows what the meaning of packet filtering is. Nevertheless, he/she knows nothing about
the iptables. So, your job is to provide a user-friendly interface for the administrator. The
following table shows the target services (or traffic) that you allow the administrator to filter:

Target Services to Filter

FTP (21); SSH (22); TELNET (23); HTTP (80); HTTPS (443)

To simplify the scenario, we restrict your system to block the traffics going out of and
going into the internal network at the same time. But, the system may be filtering multiple
kinds of traffic at the same time. Note very importantly that your system should be smart
enough to avoid filtering out the HTTP traffic going between the web-based system and the

15
home PCs.

Port forwarding. If you have taken any one of the networking courses, you will understand
the fact that computers inside the internal network cannot provide any services to the outside
world. (Else, you now has acquired this fact.) In this assignment, you have to utilize the
iptables so that a home PC can provide services to the outside world. This feature is called
port forwarding.

This function should be provided under both execution modes. Again, the administrator
is assumed that he/she knows nothing about the iptables but he/she knows what port
forwarding is. As a result, the web-based management system should be providing a user-
-friendly interface for the administrator to view, to add, to modify, and to delete the port-
forwarding rules. The following is the services to be forwarded.

Target Services to Forward

FTP (21); SSH (22); TELNET (23); HTTP (80); HTTPS (443)

Be aware that there can be more than one port-forwarding rules working at the same
time and the web-based system should be able to list them out to the administrator.

Note importantly that due the limitation of the iptables, for each service mentioned,
the broadband route can only forward the corresponding traffic to one home PC only. E.g.,
there are two computers A and B which both provide the HTTP service at port 80. Then,
the broadband router can only choose either A or B, not both, to be the port-forwarding
target.

3.2.7 Logging

Last but not least, the system has to log nearly every action taken by the administrator and
the normal users. The log should store in the permanent storage in the broadband router.
A log entry should at least record the following data:

Time Referral Page Action Input arguments Result

16
 The locations that the web-based system should create a log and the contents is given as
following.

Referral Page Things to be logged

Login page Login attempts;
Administration page Changing execution mode;
Changing filtering rule;
Changing port forwarding rule;

For example, the following is an example log entry:

1234567890 Login page Login login=tywong, password=sosad attempt failed

Of course, you are free to design your logging style. However, the system should be
providing an interface to display the log, with the following requirements:

1. The log entries should be sorted by time in descending order, i.e., the earliest entry is
the last entry, and vice versa.

2. The interface should break the logs into pages. This is a technical concern because if
the browser is trying to download and to output a lot of contents, the browser will
probably become non-responsive, or frozen.

3.2.8 Miscellaneous

There are some miscellaneous management you need to pay attention to. The following is
the complete list of the subtle managements.

• Changing password for administrator.

• Changing password for normal users.

17
 • Setting the expiry of the HTTP cookie for administrator login. Note that you are free
to set any default value.

• Setting the expiry period for normal users login under the login mode. Note that you
are free to set any default value.

4 Mark Distribution

We are employing a functional marking scheme, meaning that you will score marks for each
function implemented.

4.1 Networking setup - 5%

You have to set up a network that is the same as the one described in Figure 2 on page 5.
The networking setup is designated as follows:

• Virtual network address: 192.168.1.0/24;

• IP address of the virtual NIC of the physical machine: 192.168.1.1;

• For each virtual PC:

– Gateway IP address: 192.168.1.1;

– DNS server address: 192.168.1.1;

Note that the above two addresses should be retrieved using DHCP and the DHCP
server should be the physical host, i.e., 192.168.1.1.

4.2 Gateway function in transparent mode - 5%

This is the transparent mode setup, i.e., the basic NAT setup. Note that the system must
allow connections within the private network. For instance, it is allowed for a client in one of

18
the home PC to connect to 192.168.1.1 using SSH. Of course, this example assumes there
is a SSH server running in 192.168.1.1.

4.3 Gateway function in login mode - 20%

The expected functionalities include:

• (2%) Disabled the NAT function. We will test it by using protocols other than HTTP,
before the users has logged in.

• (3%) Redirecting to the login page. We will test this feature using a standard browser.

• (2%) Validating the user login.

• (3%) Enabling NAT for that authorized user (or the home PC) only. We will also test
this feature using protocols other than HTTP.

• (10%) Redirecting to the previously-requested page after a successful login.

4.4 Web interfaces for administrator - 27%

This is only about all the interfaces involved in the web system. In other words, we are not
talking about the actual functions, e.g., invoking iptables, to be carried out.

• Execution mode management (2% in total)

There should be an interface showing the current execution mode and another inter-
face allowing the administrator to switch from one mode to another. Note that the
modifying function does not exist.

• User management (6% in total)

– (2%) An interface for listing all the users in the system. If the system is in the
login mode, then the system should show that whether a particular user is online
or not.

19
 – (2%) An interface for adding a new user. The change should be reflected by using
the user-listing function.
– (2%)An interface for deleting a new user. The change should be reflected by using
the user-listing function.

• Filtering management (8% in total)

– (2%) An interface for listing all the filtering rules set by the administrator. Note
that printing the output of “iptables -L” directly will get zero marks. Hint:
parsing such a printout is needed.
– (2%) An interface for adding a new rule. The change should be reflected by using
the rule-listing function.
– (2%) An interface for modifying an existing rule. The change should be reflected
by using the rule-listing function.
– (2%) An interface for deleting an existing rule. The change should be reflected
by using the rule-listing function.

Note that for the adding, the modifying, and the deleting interface, if those interfaces
are requesting the administrator to input any iptables commands, then you will zero
marks for each of the concerned interface.

• Port-forwarding management (4% in total)

The interfaces are nearly the same as those for filtering. So, each interface only carries
1 mark.

• Logging management (4% in total)

An interface for the administrator to display the logs. The display should be classified
by their types. As mentioned before, the display must break the logs into pages.
There is no need for the administrator to delete any log entries.

(3%) Note very important that you have to validate every input that will be input by the
users. For example, if there is a text box for the user to input an IP address, then the system
has to make sure that the input is a well-formatted IP address. You can choose to handle
the validation on the client side (using JavaScript) or on the server side (using server-side
scripting language).

20
4.5 Functions taken by the interfaces - 35%

These cover the actual functions that the web interfaces should drive.

• Execution mode management (2% in total)

As mentioned in Section 3.2.4 on page 13, you have to handle the cases that while
the system is in a transition from one mode to another, the users’ status has to be
administrated.

• User management (9% in total)

The interfaces will be involving reading, adding, deleting on the entries of the user
database (this does not imply a DBMS).

– (3%) Reading all the user entries in the database;

– (3%) Adding new entries into the database; and
– (3%) Deleting any existing entries in the database.

The database should be storing the credentials of the normal users. Whether the
credential should be stored in the same database is up to your implementation.

• Filtering management (12% in total)

The iptables should be driven in this stage. You may not need a database for storing
the status of the filtering rule because you can opt to parse the output of the iptables
command.

– (3%) Listing the filtering rules;

– (3%) Adding new rules;
– (3%) Modifying existing rules; and
– (3%) Deleting existing rules.

• Port-forwarding management (8% in total)

(4%) This involves a set of similar handling as those of the “filtering management”.
Marks are reduced to 1% for each function because it is only a duplicate of the “filtering
management”.

21
 (2 × 2%) Nevertheless, while the system is adding or modifying a rule, you have to
check if the to-be-added or the to-be-modified rule conflict with existing rules.

• Logging management (4% in total)

(2%) The log should be kept in the permanent storage. Again, whether it is stored in
a DBMS or not is up to your implementation. The system has to return the required
amount of log entries to the administrator.
(2%) Nonetheless, you have to implemented the location of logging as described in
Section 3.2.7 on page 16.

4.6 Miscellaneous - 8%

• (2%) The correct implementation of the login procedure described in Figure 4 on page
11.

• (2%) There should be a page for the administrator to change his/her own password.
Before the system sets a new password, the system should request and validate the old
password supplied by the administrator. Of course, this will trigger an update of the
administrator’s credential.

• (2%) There should be a page for a normal user to change his/her own password. The
process is similar to that for the administrator, but is only available under the login
mode.

• (2%) There should be a page for the administrator to set:

– the expiry of the HTTP cookie for the administrator’s login session; and
– the expiry period for normal users’ login sessions under the login mode.

Note that the above settings should be stored in a permanent storage.

22
5 Submission and Demonstration

You have to submit:

• All the configuration files concerning the network setup. It’d be nice to have a script
to automatic the setup;
• All the program codes and HTML files you written;
• NEVER submit any VMware images.

The marking of the assignment will be carried out in the form of demonstrations. During
the demonstration, we will prepare a clean system running Linux, with VMware software
and VMware images installed, for you to load your submission. Therefore, you have to make
sure that you have submitted all the necessary files.

During the demonstration, you can only configure the network setup. Although this will
not take any mark penalties, it wastes your and our time.

Deadline: 23:59, March 29, 2009.

23