Differences

This shows you the differences between two versions of the page.

imara:platforms:hardware:communications:4gcube:new [2011/02/05 15:46] (current)
Paulo RESENDE created
Line 1: Line 1:
 +====== First things to do on a new 4G Cube ======
 +Hey! We just received a new [[imara:platforms:hardware:communications:4gcube]]! What should we do first?
 +
 +**Remember to add, and keep updated, the required information to the [[imara:platforms:hardware:communications:4gcube|4G Cubes summary page]].**
 +
 +===== Physical installation =====
 +==== Hardware wiring ====
 +The 4G Cubes have two MiniPCI slots on which we can plug WiFi cards.
 +
 +A default Wi-Fi card is usually supplied by 4G.
 +
 +{{:wiki:old: :themes:procedures:cube_default_802.11b_card.jpg?320 |Default 802.11b 4G card.}}
 +
 +One should check that this card is on the **lower** connector, and that its antenna is connected to the **right** of the front panel.
 +
 +{{:wiki:old:themes:procedures:cube_default_802.11b_card_in_situ.jpg?320 |The default WiFi card is on the lower MiniPCI slot.}}
 +{{:wiki:old: :themes:procedures:cube_default_802.11b_card_antenna.jpg?200|The default WiFi card is on the right antenna connector.}}
 +<html>
 +<br style="clear:both" />
 +</html>
 +
 +If another card has to be connected, the default one **is left untouched** and the new one is connected on the free slot and antenna connector.
 +
 +{{:wiki:old: :themes:procedures:cube_two_cards.jpg?320 |The default WiFi card plus another additional one.}}
 +
 +==== Labels ====
 +At least 2 labels are needed on the new Cube: its two interfaces' (ethernet and 802.11) names under Linux and MAC addresses.
 +
 +{{:wiki:old:themes:procedures:cube_label_eth0.jpg?320  |The eth0 label...}}
 +{{:wiki:old:  :themes:procedures:cube_label_ath0.jpg?320|... and the ath0 one.}}
 +
 +
 +
 +
 +===== Software setup =====
 +The Cubes run Nylon Linux. This distribution has an [[http://www.debian.org/doc/manuals/apt-howto/|APT]]-like system to handle package installations and keep the system up-to-date: [[http://www.handhelds.org/moin/moin.cgi/Ipkg|Ipkg]].
 +
 +
 +
 +
 +
 +==== Boot with single user mode ====
 +On the booting, Press Ctrl+C
 +
 +  Environment variable 'start' exists. After 4.0 seconds
 +  it will be interpreted as a YAMON command and executed.
 +  Press Ctrl-C to bypass this.
 +  General Purpuse Button is Released
 +  
 +  YAMON> $start init=/bin/sh
 +
 +When in the shell, remount the root partition rw
 +
 +  # mount / -o remount,rw
 +
 +==== First login ====
 +It is really possible thay a brand new cube won't be directly accessible through the mesh network nor provide DHCP and other shiny stuff to get connectivity to it. It is, however, shipped with a default configuration IPv4 address that is always accessible: 192.168.0.250. One should configure her computer to use an IP address in this range (say 192.168.0.1), and use a cross cable (or whatever seems appropriate) to connect to the cube. It is worth noting that there is absolutely no need to be on a dedicated network (unless the only one closeby uses the 192.168.0.0/24 range, which would imply the risk of address collisions) hence, it is possible (and recommended) to use the following setup:
 +
 +{{:wiki:old:  :themes:procedures:initial_setup.png  |Accessing a Cube for the first time can be done directly on a foreign network.}}
 +
 +:!: As every cube has the same configuration IP, one should take care of not plugging more than one Cube at a time on the ethernet segment when trying to access them this way. :!:
 +
 +Once IP connectivity is achieved, it is possible to get an SSH session to the Cube, logging in as root, with the password provided by 4G.
 +
 +Assuming the workstation is running a rather recent version of Linux, one can configure it, test the link to the Cube and connect to it in 3 simple steps. The additional fourth command shows how to transfer a file to the Cube using ''scp''.
 +<code>
 +$ sudo ifconfig eth0:lara 192.168.0.1
 +$ ping -c 1 192.168.0.250
 +PING 192.168.0.250 (192.168.0.250) 56(84) bytes of data.
 +64 bytes from 192.168.0.250: icmp_seq=1 ttl=64 time=0.199 ms
 +
 +--- 192.168.0.250 ping statistics ---
 +1 packets transmitted, 1 received, 0% packet loss, time 0ms
 +rtt min/avg/max/mdev = 0.199/0.199/0.199/0.000 ms
 +$ ssh root@192.168.0.250
 +$ scp remote:/path/to/file root@192.168.0.250
 +</code>
 +
 +
 +==== Fully automated boostrap ====
 +FIXME As of version 0.9.3.3svn2704, an malfunction exists in the ''madwifi-old-openhal'' modules which makes ath-based Wi-Fi card unusable. Be sure to put wlan-based (''kernel-module-hostap-pci'') in the Cubes before updating them or, do not upgrade them.
 +
 +A [[https://gforge.inria.fr/plugins/scmsvn/viewcvs.php/*checkout*/cubes/packages/lara-conf/bootstrap.sh?content-type=text%2Fplain&root=lara-com|bootstrap script]] is available in the ''lara-conf'' package and repository. This should be copied to the Cube using ''scp''. It may be necessary to give execution rights on the script using ''chmod''.
 +
 +It will setup a basic Internet connection, with user-provided parameters (those in the example work for the Inria network at Rocquencourt), update the repositories information, then pull and install all the updates for the distribution.
 +
 +<code>
 +$ scp bootstrap.sh root@192.168.0.250:
 +Password:
 +bootstrap.sh                                  100% 2650     2.6KB/s   00:00    
 +$ ssh root@192.168.0.25
 +Password:
 +root@mtx-1:~# ./bootstrap.sh
 +LaRA Mobile Router system bootstrap
 +(c) 2007 Inria, Olivier Mehani <olivier.mehani@inria.fr>
 +This program is distributed under the terms of the GNU GPL.
 +
 +Replacing the no longer available Nylon repos by mirrors at Imara...
 +Adding LaRA/Imara specific repo...
 +Configuring simple Internet access...
 +  Available network interfaces: ath0 eth0 lo.
 +  Enter interface to use: eth0
 +  Enter IP address for this node: 128.93.7.11
 +  Enter default gateway to the internet: 128.93.1.100
 +  Enter the IP of a DNS server: 128.93.1.23
 +Updating local package database and installing metapackage lara-conf...
 +[...]
 +Restoring previous configuration...
 +Done. It may be advisable to restart the router now.
 +</code>
 +Some errors (mainly ''iptables'' and missing ''depmod'' related) may occur during the first execution of ''lara-conf'', right at the end of the bootstrap process. They are due to modules having been updated while still running on the old kernel, they can be ignored.
 +
 +Before rebooting the Cube, one may like to edit the ''/etc/lara.conf'' configuration file to suit her needs, then run ''lara-conf'' to commit the changes, so that the Cube is in readiness next time it starts.
 +
 +The following two sections are deprecated but kept for reference as they describe the way to manually do what the boostrap script automatizes.
 +
 +==== Manual package system configuration (Kept for reference) ====
 +Imara now has a repository of specific packages (as well as a meshcube.org mirror) on [[http://imara-serv.inria.fr/pub/nylon-meshcubes|fylvestre]].
 +
 +As for APT, Ipkg has a list of repositories where it can search for available packages. These files (one per repository) are located in ''/etc/ipkg'' and are named ''*-feed.conf''. On a new cube, there are two of them: ''nylon-feed.conf'' and ''nylon-binary-feed.conf''.
 +
 +To enable our repository, we create a new file, with the appropriate information.
 +<code>
 +# cat > /etc/ipkg/imara-feed.conf << EOF
 +src imara http://imara-serv.inria.fr/pub/nylon-meshcubes/imara
 +EOF
 +</code>
 +
 +Additionally, since , the meshcube.org official website is down. What was possible to gather is [[http://fylvestre.inria.fr/pub/nylon-meshcubes/meshcube.org/|mirrored on fylvestre]] (but unfortunately uncomplete). Meshcube.org being down as the obnoxious side effect that the official package repositories are no longer available. It is then necessary to modify the basic Nylon repository entries in order to point to our mirror. This is done as follows.
 +<code>
 +# cat > /etc/ipkg/nylon-feed.conf << EOF
 +src/gz nylon http://imara-serv.inria.fr/pub/nylon-meshcubes/feed
 +EOF
 +# cat > /etc/ipkg/nylon-binarya-feed.conf << EOF
 +src/gz nylon-bin http://imara-serv.inria.fr/pub/nylon-meshcubes/binary-feed
 +EOF
 +</code>
 +
 +Finally, it is possible to update the local package database, and get ready to upgrade the system and install new packages (if it does not work, read the following section).
 +<code>
 +# ipkg update
 +Downloading http://imara-serv.inria.fr/pub/nylon-meshcubes/imara/Packages
 +Updated list of available packages in /usr/lib/ipkg/lists/imara
 +Downloading http://imara-serv.inria.fr/pub/nylon-meshcubes/binary-feed/Packages.gz
 +Inflating http://imara-serv.inria.fr/pub/nylon-meshcubes/binary-feed/Packages.gz
 +Updated list of available packages in /usr/lib/ipkg/lists/nylon-bin
 +Downloading http://imara-serv.inria.fr/pub/nylon-meshcubes/feed/Packages.gz
 +Inflating http://imara-serv.inria.fr/pub/nylon-meshcubes/feed/Packages.gz
 +Updated list of available packages in /usr/lib/ipkg/lists/nylon
 +</code>
 +
 +
 +==== Manual internet bootstrap (Kept for reference) ====
 +:!: This part is for reference only, as an automated setup procedure now exists, see below :!:
 +
 +To do everything which is related to distant repositories of packages (include the initial update of the database), the Internet uplink has to be configured manually. The following commands will set up the internet access for the cube using ''imara-olsr-gw'' (10.0.0.1) as an IPv4 uplink and DNS server. For information about the IP address to attribute to the Cube (using its CBID) please refer to [[:wiki:old:themes:architecture:4gcubes#generic_network_configuration|the generic network information about our mesh network]].
 +<code>
 +# cat > /etc/resolv/conf
 +search inria.fr
 +nameserver 10.0.0.1
 +# iwconfig wlan0 essid cube-mesh mode ad-hoc
 +# ifconfig wlan0 10.0.CB.ID
 +# route add -net default gw 10.0.0.1
 +</code>
 +
 +==== LaRA-specific packages ====
 +[[http://imara-serv.inria.fr/pub/nylon-meshcubes/imara]]
 +
 +=== Opening local ports on the cube ===
 +This section concerns the situation when a specific application is running directly on the cube and needs to receive incoming traffic (//e.g.// OLSR on port udp/698). This is regulated by the ''INPUT'' chain of netfilter, hence, the configuration file to edit is called ''lara-input.conf''.
 +
 +The format of this file is such that one "type of service" can be openned on each line, but every service can cover several ports. The syntax is
 +<file>
 +PORT[:PORTEND]    [tcp|udp|tcpdup]    TEXTUAL_DESCRIPTION
 +</file>
 +Empty lines and those starting with a hash sign are ignored (//i.e.// treated as comments).
 +
 +As an example, the default file looks like  the following.
 +<file>
 +# /etc/firewall/lara-input.conf
 +# Specify which connections _to_ the Cube (i.e. not forwarding) should be
 +# allowed.
 +# $Id: lara-input.conf 343 2007-12-07 09:46:24Z mehani $
 +#
 +# Port(s)       Prot.   Description
 +# Pbeg[:Pend]   tcp|udp|tcpudp
 +22              tcp     ssh
 +# DNS requests
 +53              tcpudp  domain
 +# DHCP requests
 +67              tcpudp  bootps
 +68              tcpudp  bootpc
 +#2004           tcp     dotdraw
 +#2006           tcp     route-stats
 +698             udp     olsr
 +</file>
 +===== System maintenance =====
 +==== Keeping track of new versions ====
 +The first thing to keep in mind is to use the package manager (''ipkg'') to install or upgrade whatever application is desired.
 +
 +The first thing to do is to synchronize the local package and versions database with the remote repositories.
 +  # ipkg update
 +Then, one can install a new package, say ''mynewpackage'' (if available in the repositories).
 +  # ipkg install mynewpackage
 +It is also possible to upgrade the whole system to the latest version (that is, of the installed packages).
 +  # ipkg upgrade
 +
 +==== Adding or removing application from the startup process ====
 +The Nylon distribution uses a startup system based on the LSB. Mainly, this means it uses a ''init.d'' directory for startup scripts and has tools to add or remove links to these scipts in the ''rc*.d'' directories.
 +
 +:!: This means the user should never have to modify the contents of the ''rc*.d'' scripts manually.
 +
 +To manipulate the startup process, the ''update-rc.d'' tool is provided. It can be used to enable a script (already present in ''init.d'').
 +  # update-rc.d SCRIPTNAME defaults
 +It can also be used to prevent a script from being called during bootup.
 +  # update-rc.d -f SCRIPTNAME remove
 +
 +==== Using the LaRA configuration tool ====
 +The ''lara-conf'' package is a specific metapackage which allows to easily setup a cube to one of the usual Imara/LaRA configurations. It is used to define which interface to use, how to do so, and so on. It also takes care of properly updating the firewall scripts and dependency applications (like ''olsrd'' or ''mip6d'').
 +
 +Everything that can be configured using this tool is in the ''/etc/lara.conf'' file.
 +<file>
 +# lara.conf
 +# Default configuration for the 4G Cubes with LaRA-specific setup
 +# $Id: lara.conf 448 2008-01-15 12:34:27Z mehani $
 +
 +# Interfaces information
 +VANET_IF="ath0"
 +WIFI_IF="wlan0"
 +
 +# Host type (modifies firewalling rules in use)
 +# MR: Mobile router (embedded in the vehicles)
 +# GW: VANET to Internet gateway
 +HOST_TYPE="MR"
 +
 +# Use #WIFI_IF# interface as an AP, incompatible with MIP6/NEMO
 +# The option if forced to yes, whatever the value below, when in GW mode
 +PROVIDE_AP="no"
 +
 +VANET_PFX="FD39:9BCD:A2CD:1"
 +# MIP6/NEMO options
 +HA_ADDR="2001:660:f183:f100::1"
 +HOME_PFX="2001:660:f183:f100"
 +NEMO_PFX="2001:660:f183"
 +
 +# Do not apply the changes directly (e.g. when they may freeze the machine)
 +DEFER_APPLY="no"
 +</file>
 +
 +Once the file has been updated to the needs, calling the ''lara-conf'' tool would reconfigure everything to the new parameters.
 +  # lara-conf
 +
 +==== Firewall configuration ====
 +With the LaRA-specific metapackage ''lara-conf'' is installed a firewalling script more suited to our needs. ''lara-firewall'' moreover disables the default Nylon firewall (''chmod a-x /etc/init.d/simple-firewall'') to become the only one in charge.
 +
 +The configuration of the LaRA firewall is done in three configuration files in directory ''/etc/firewall/'':
 +  - the default interfaces configuration, in ''lara-firewall.conf'';
 +  - the //local// ports configuration, in ''lara-input.conf'';
 +  - the ports connections that should be allowed accross networks, in ''lara-forward.conf''.
 +
 +After modifying any of these files, a restart of the firewall is required for the parameters to be applied.
 +<code>
 +# /etc/init.d/firewall restart
 +/etc/init.d/firewall
 +* stopping firewall: [...]
 +done.
 +* starting firewall: [...]
 +done.
 +</code>
 +
 +=== Allowing forwarding of certain protocols ===
 +By default, the cube blocks everything that is to be forwarded from one network to another. File ''lara-forward.conf'' allows to dig "holes" in this to allow //e.g.//, a computer on the local ethernet to connect to the web server (port tcp/80) of another node in the VANET. The syntax is the very same as for the ''lara-input.conf'' file.
 +
 +The default configuration looks as follows.
 +<file>
 +# /etc/firewall/lara-forward.conf
 +# Specify which connections to the Cube should forward to/from the wired
 +# network from/to the VANET.
 +# $Id: lara-forward.conf 342 2007-12-06 17:23:22Z mehani $
 +#
 +# Port(s)       Prot.   Description
 +# Pbeg[:Pend]   tcp|udp|tcpudp  
 +22              tcp     ssh
 +# DNS requests
 +53              tcpudp  ssh
 +80              tcp     http
 +443             tcp     https
 +123             udp     ntp
 +# Windows shares
 +#137            udp     ntb-ns
 +#138            udp     ntb-dgm
 +#139            tcp     ntb-ssn
 +#445            tcp     ms-ds
 +# Remote desktop
 +3389            tcp     rdp
 +# Jabber Instant messenging
 +5222            tcp     xmpp-client
 +# Com2React V2V
 +#2005:2006      tcpudp  c2r-v2v
 +</file>
 +
 +=== Adding more complex scripts ===
 +In case more complex things than just opening a port is needed, a script can be added to the ''/etc/init.d'' directory, with a name matching ''*-firewall''.
 +
 +The following is an example skeleton for this type of files.
 +<code bash>
 +#!/bin/sh
 +case $1 in
 +        start)
 +        #DO INITIALIZATION STUFF HERE
 +        ;;
 +
 +        stop)
 +        #DO CLEANUP STUFF HERE
 +        ;;
 +
 +        restart)
 +        $0 stop
 +        $0 start
 +        ;;
 +
 +        *)
 +        echo "usage: $0 start|stop|restart"
 +        ;;
 +esac
 +</code>
 +
 +
 +{{tag>hardware communications 4gcube procedure}}
 
imara/platforms/hardware/communications/4gcube/new.txt · Last modified: 2011/02/05 15:46 by Paulo RESENDE
Recent changes · Show pagesource · Login