Deploy Xinu

By this point it is assumed you have obtained a supported router to use as a back end, have made the necessary modifications to use the serial port, have connected to your backend router using serial communication software (such as PICOCOM), and have built a cross-compiler (from your host computer's architecture to MIPS) and used it to build a XINU boot image to run on the back end (a file called xinu.boot should be in your compile directory). If you have not it is suggested you visit http://xinu.mscs.mu.edu/ to understand what you need and why.

TFTP Server

Installing the TFTP Server Package

The first step in running your XINU image is to run a TFTP Server on your front end so that it can transfer the boot image onto the back end via the network connection. Getting a TFTP Server running on your front end is a fairly simple process on Linux. Use your front end's package install commands to search for a tftp-server package and then install that package. Using Fedora 9 and the YUM package install command, we entered the command yum list | grep tftp and obtained the following output:

[root@argolis compile]# yum list | grep tftp
tftp.i386                                0.48-6.fc9             mulugupdates    
tftp-server.i386                         0.48-6.fc9             mulugupdates    
[root@argolis compile]#

This command tells the package installer to find any packages with "tftp" in the title. We want the package called tftp-server.i386 because this will allow us to run a TFTP-Server on our front end machine. Next, we need to actually install the package. Again we use our package install command to install the package. Using Fedora 9 and the YUM package install command, we entered the command yum install tftp-server and obtained the following output:

[root@argolis compile]# yum install tftp-server
Loaded plugins: refresh-packagekit
Setting up Install Process
Parsing package install arguments
Resolving Dependencies
--> Running transaction check
---> Package tftp-server.i386 0:0.48-6.fc9 set to be updated
--> Finished Dependency Resolution

Dependencies Resolved

=============================================================================
 Package                 Arch       Version          Repository        Size 
=============================================================================
Installing:
 tftp-server             i386       0.48-6.fc9       mulugupdates       35 k

Transaction Summary
==  What to do next? ==

Now that you have successfully booted and ran XINU on your backend router, you might want to try to [[HOWTO:Build_Backend_Pool|build a pool of backends]] to allow multiple users to each run their own version of XINU on a different backend.

For more information on the XINU operating system check out the [http://xinu.mscs.mu.edu/[Embedded XINU wiki]].


<hr/>
''This work is supported in part by NSF grant DUE-CCLI-0737476.''

=== Configuring the TFTP Server ===
Now that your '''TFTP Server''' package is installed, you need to configure some settings to get it to run properly. First open the file <code> /etc/xinetd.d/tftp</code>. ''xinetd'' is a server daemon that can run many different types of servers. Here, though, we're only interested in running a '''TFTP Server''', so we open the tftp configuration file for ''xinetd'' and make the necessary changes. At first, the file should look something like this:
<pre># default: off
# description: The tftp server serves files using the trivial file transfer \
#       protocol.  The tftp protocol is often used to boot diskless \
#       workstations, download configuration files to network-aware printers, \
#       and to start the installation process for some operating systems.
service tftp
{
        socket_type             = dgram
        protocol                = udp
        wait                    = yes
        user                    = root
        server                  = /usr/sbin/in.tftpd
        server_args             = -s /var/lib/tftpboot
        disable                 = yes
        per_source              = 11
        cps                     = 100 2
        flags                   = IPv4
}

You need to change the values of the disable and server_args variables. Change the value of disable to "no" and the value of server_args to point to the directory that will contain files you wish to share on your TFTP Server. In our lab we use the directory /tftpboot . You need to remember this directory because this is where you will need to put your xinu.boot file that you want to run on the back end. After you've made the necessary changes to the file /etc/xinetd.d/tftp , it should look like this:

# default: off
# description: The tftp server serves files using the trivial file transfer \
#       protocol.  The tftp protocol is often used to boot diskless \
#       workstations, download configuration files to network-aware printers, \
#       and to start the installation process for some operating systems.
service tftp
{
        socket_type             = dgram
        protocol                = udp
        wait                    = yes
        user                    = root
        server                  = /usr/sbin/in.tftpd
        server_args             = -s /tftpboot
        disable                 = no
        per_source              = 11
        cps                     = 100 2
        flags                   = IPv4
}

If you are going to use our approach you may need to create a /tftpboot directory. To do this execute the following command: mkdir /tftpboot . Then you'll want to check to make sure that the xinetd is running, and make sure that its running a TFTP Server. Execute the command chkconfig --list . You should get output that looks like this:

[root@argolis compile]# chkconfig --list
NetworkManager  0:off   1:off   2:off   3:off   4:off   5:off   6:off
acpid           0:off   1:off   2:on    3:on    4:on    5:on    6:off
anacron         0:off   1:off   2:on    3:on    4:on    5:on    6:off
atd             0:off   1:off   2:off   3:on    4:on    5:on    6:off
auditd          0:off   1:off   2:on    3:on    4:on    5:on    6:off
avahi-daemon    0:off   1:off   2:off   3:on    4:on    5:on    6:off
...
...
...
winbind         0:off   1:off   2:off   3:off   4:off   5:off   6:off
wpa_supplicant  0:off   1:off   2:off   3:off   4:off   5:off   6:off
xinetd          0:off   1:off   2:off   3:on    4:on    5:on    6:off
xinu-consoled   0:off   1:off   2:off   3:on    4:on    5:on    6:off
ypbind          0:off   1:off   2:off   3:off   4:off   5:off   6:off
yum-updatesd    0:off   1:off   2:on    3:on    4:on    5:on    6:off

xinetd based services:
        chargen-dgram:  off
        chargen-stream: off
        cvs:            off
        daytime-dgram:  off
        daytime-stream: off
        discard-dgram:  off
        discard-stream: off
        echo-dgram:     off
        echo-stream:    off
        rsync:          off
        tcpmux-server:  off
        tftp:           on
        time-dgram:     off
        time-stream:    off
[root@argolis compile]# 

The important lines in this output are the xinetd line in the list of services and the tftp line at the bottom section of xinetd based services. Make sure that the xinetd line says "on" for 3, 4, and 5. Also make sure that the tftp line says "on".

There are a couple other configurations that you may need to set up in order to get your TFTP Server running. If your front end is running a SE Linux firewall (our front end with a fresh install of Fedora 9 came running this firewall by default) you may have to configure it to allow clients to access your front end's TFTP Server running through xinetd. The simplest solution is to just tell the SE Linux firewall to allow any activity over the network connection your front end is using to connect to the back end. Our front end machine is set up with two network cards and configured so that eth0 is our network connection to the outside world and eth1 is our connection to our back end. To tell the firewall to accept all activity over our network connection with the backend we used the command iptables -I INPUT -i eth1 -j ACCEPT. NOTE: this could be very dangerous because the connection between your front end and back end is now insecure. This should only be done if you trust all possible users of the backend because they now have unchecked access to your frontend machine.

Also, you may need to configure your frontend's IP address. If you are using a DHCP server for your frontend machine you can simply execute ifconfig eth0 -auto on your backend's CFE prompt to obtain an IP for your backend automatically. However, most likely this is not the case and you will have to make sure that the network connection that your front end machine is using to communicate with the backend is configured with a static IP address in the 192.168.1.[2-255] range because your backend router will have a default IP address of 192.168.1.1 when it reboots. If it is the case that the IP address of your frontend machine's network connection with the backend is set outside of this range, then click here for a quick tutorial on changing the IP address of your network connection.

The last step before actually trying to boot your backend with a XINU image, is to copy the actual xinu.boot file to the directory from which the TFTP Server allows clients to get files. This is the directory that the /etc/xinetd.d/tftp file's server_args variable points to. In our example we used the directory /tftpboot. This is the directory where you need to copy the xinu.boot file. This is easily done by using a command like cp xinu.boot /tftpboot/xinu.boot, assuming that your current working directory contains the xinu.boot file and that /tftpboot is the directory from which your TFTP Server allows clients to get files.

Booting XINU on your Backend

By now your TFTP Server should be up and running correctly, your xinu.boot file should be in the correct directory so your backend can access it through the TFTP protocol, and your frontend machine should either be running as a DHCP server or (more likely) has a static IP address in the 192.168.1.[2-255] range on its network connection with the backend.

To boot your backend router running XINU, first make sure you are connected to the backend with some serial communication software and are at the CFE prompt. If you are not looking at the backend router's CFE prompt follow the instructions on how to connect to your backend router. In the CFE prompt type the command boot -elf [host ip]:xinu.boot where "[host ip]" is the IP address of the frontend machine's connection to the backend router. If all has gone correctly the router should now be running a XINU image and you will be greeted with a basic shell (xsh$ ). On our frontend machine running Fedora 9 with an IP address of 192.168.1.2 we optained the following output:

CFE> boot -elf 192.168.1.2:xinu.boot
Loader:elf Filesys:tftp Dev:eth0 File:192.168.1.2:xinu.boot Options:(null)
Loading: 0x80001000/114724 0x8001d024/18480 Entry at 0x80001000
Closing network.
Starting program at 0x80001000
(Mips XINU) #0 (root@argolis.mscs.mu.edu) Mon Jun 23 17:47:42 CDT 2008

  16777216 bytes physical memory.
      4096 bytes reserved system area.
    133204 bytes XINU code.
     32764 bytes stack space.
  16607152 bytes heap space.

______________________________________
    _    _  _____  ______   _     _ 
   \ \  / /(_____)|  ___ \ | |   | |
    \ \/ /    _   | |   | || |   | |
     )  (    | |  | |   | || |   | |
    / /\ \  _| |_ | |   | || |___| |
   /_/  \_\(_____)|_|   |_| \______|
______________________________________

Welcome to the wonderful world of XINU!
xsh$ 

Within the shell you have some basic commands: exit, gpiostat, help, kill, memstat, led, ps, reset, sleep, uartstat. Each can be described using [command] --help.

xsh$ help
Shell Commands:
        clear
        ethstat
        exit
        gpiostat
        help
        kill
        led
        memstat
        memdump
        ps
        reset
        sleep
        test
        testsuite
        uartstat
        nvram
        ?
xsh$ 

Congratulations, You now have a working backend running XINU! You can now make changes to the XINU code, recompile it using the make command to get a new xinu.boot image, copy that file into the /tftpboot directory (or whatever directory your TFTP Server uses to share files), and use the same boot -elf [host ip]:xinu.boot command to run your very own, modified version of the XINU operating system.

What to do next?

Now that you have successfully booted and ran XINU on your backend router, you might want to try to build a pool of backends to allow multiple users to each run their own version of XINU on a different backend.

For more information on the XINU operating system check out the Embedded XINU wiki [1].

---

This work is supported in part by NSF grant DUE-CCLI-0737476.