How to install (and maintain) a CONFINE research device: CONFINE@Home
Authors: Javi Jiménez <email@example.com>, Pau Escrich <firstname.lastname@example.org>, Roger Baig <email@example.com> (Fundació per a la Xarxa Oberta, Lliure i Neutral Guifi.net), Leandro Navarro <firstname.lastname@example.org> (DSG - UPC).
A research device (RD) or node is a computer which aims to serve as research infrastructure for the CONFINE project. The RD has a pre-installed software based in OpenWrt.
An experiment running in a CONFINE testbed has the formal name of slice. A slice is a collection of slivers that allow the execution of an experiment, each on a different node.
There are many types of research devices. The CONFINE software tries to be flexible enough to withstand the maximum possible number, but always respecting these restrictions:
An RD can be an old computer, an old laptop, a netbook, a multimedia device, a barebone computer etc …
The first step that must be done (just as we do in Guifi.net) is to register our new research device as a node in the testbed's central server.
After that you can download a firmware (operating system) for our node with everything you need to get into this testbed.
The first step is to register yourself in the testbed's control panel, a web interface to testbed administration tasks (if you already have a registered user you can skip this step).
Browse to http://panel.community-lab.net and click on “Create an account”.
Make sure the email address is correct.
Once the account is active, you can log into the control panel with your own data.
Now you may apply to join our group. You must first click on your username at the top as shown in the following image (in this case 'jjimenez').
TODO: Change username by a group username.
Clicking on the username moves to the management screen with several options. We go to “Roles (Request group membership).”
Select your group (e.g. Guifi.net) with the checkbox and the option “Request to join the selected group” from the “Action” dropdown and click on “Go”.
Your request reaches the administrators group and it will probably be accepted in a while.
Once you have been accepted in a group, go to the control panel dashboard and click on the icon “Nodes”.
At the top right you will see a button that says “Add Node”, click there. You will see the following screen.
The required fields to fill in are:
x86_64(for most Intel Atom CPUs, otherwise
i586for older boards like Alix).
Noneif the network that connects your community device (CD) to your research device (RD) does not use community IPv4 addresses (e.g.
DHCPif the CD assigns community addresses using DHCP.
Nis the number of community addresses that the CD may assign to slivers of this node.
Once done, click “Save” at the bottom.
A note on direct interfaces: Your node may be configured to provide slivers with support for isolated interfaces, which allow the arbitrary exchange of VLAN-tagged L2 traffic, e.g. for routing experiments. In that case you need to configure some of the network interfaces in your node as direct interfaces able to host the isolated interfaces. To do that you must list the names of these interfaces under “Direct network interfaces” and make sure that they are properly configured in OpenWrt, which may imply some manual intervention after installation. Please remember to include some note in the node's description referring to the configuration of direct interfaces, e.g. “Direct interface wlan0 is configured in ad-hoc mode with BSSID XX:XX:XX:XX:XX:XX and channel N.”. See Node architecture for more information on isolated interfaces.
At this point the node's customized firmware can be obtained from the control panel. It is the
confine-dist operating system with some configurations such as the hostname, VPN keys, IP configuration and so on.
Now you can check if the node is detected by the Controller checking it's “state link” column for your node, you get it going to the main menu and click on Nodes to get the list of nodes with their corresponding “state link” column, as you can see in the next image:
The node needs to be put in the “PRODUCTION” state, with that step it's allowed to researchers to create Slices and Slivers:
To install it into the RD you may want to use the USB installation method as shown in the next point.
First of all you have to get an USB pen ready to be deleted, because you need to delete the USB pen and copy there the node firmware to be installed to the new node.
Return to the home page and go again to the list of nodes (icon “Nodes”). Click on your newly created node and then on the “Download firmware”.
Select the three files that are available with a checkbox (these are the keys that authenticate your node). Select also the checkbox asking to build a USB Image and finally click on “Build firmware!”.
The process of creating the firmware can take a while, once done you'll get a link to download the file.
This resulting file is the CONFINE-install binary image, a tool that allows you to install the CONFINE system from a USB disk to the internal hard drive of the RD. To prepare the USB disk follow the next steps (assuming the name of the download file is
sudo gunzip -c confine-install.img.gz | dd of=/dev/sdX bs=1M ; sync
Now you have the USB CONFINE-install disk ready to install the system on your research device.
Connect a keyboard and monitor to the your RD, plug the USB CONFINE-install disk and boot. You should click the button “F2,” “F8”, “DELETE” or “ESC” to select the USB disk as the first boot in BIOS. Once you see that, it means you will be loading the small operating system in the USB disk.
When letters appearing on the screen stay still, press the “Enter” key. You're asked for confirmation to install the system by entering the letter “y” and pressing “Enter”. In a while the installation will be completed and you will be able to restart the node with the command
Remove the USB disk and wait for it to load the new system already installed on the internal hard drive of the device. When finished (it may take about 2 minutes), press “Enter” again to get to a management terminal. Run the command
confine.disk-parted to partition the internal disk and reboot when done with
Finally you'll see that this time it takes a little longer to boot and it even restarts on its own. It's normal, since the RD is creating and formatting new partitions. When you boot a second time, you will have the system ready! Now you only need to plug the RD's first Ethernet port to your Guifi.net node.
If your RD already has a customized or a generic CONFINE system installed, you can just upgrade it to a customized version of the system. Follow the same steps to generate the USB installation disk but do not select the checkbox “USB Image”. Then the resulting file will be the CONFINE system image ready to be installed in your node.
Upload it to the RD using for instance scp. All CONFINE RDs have a rescue IPv4 address which you can use to reach it. By default it is 192.168.241.130/25, so you need to configure another address of the same range in your computer, for instance 192.168.241.132/25. This can be achieved with the next command:
ip addr add 192.168.241.132/25 dev eth0
Copy the customized image (downloaded from the control panel) to the node's
scp confine-system-image.gz 192.168.241.130:/tmp/
Log into the node using the default password “confine”:
Upgrade the node by executing:
After some minutes your node should be upgraded and customized.
For other ways of upgrading your node, see Node upgrade.
Following the CONFINE Architecture, the node is a Research Device (RD) and it has to be connected to a Community Device (CD).
If you want, you don't need to enter to the RD to get the device ready for running experiments. You've only to plug the RD to the network after installing the node software to add it to the testbed.
In clear words, to connect the RD you only have to take an ethernet cable and plug it in the proper slot of your RD (default eth0, it's indicated the default slot when you receive the RD) and plug the cable in your guifi.net router or other router, this is the Community Device, which offers connection to the Community Network.
If your router offers guifi.net addresses it's OK, if your router offers private addresses it's OK too, because in some projects there are experiments for 'NAT traversal'. As a complement, if you want to be connected to guifi.net configuring a VPN connection to guifi.net you can configure your router, and at the moment offer private IPs to the internal network, using the project VPN keys. The referenced VPN connection is one of the of the available VPN options.