XS Installing Software 0.6

  This page is monitored by the OLPC team.

This page describes how to obtain a copy of the XS school server software, load it onto media, and install it onto a system. A more complete description of the software repositories, configuration information, and testing instructions are also available.

This page covers XS 0.5 and newer. For older releases, see XS_Installing_Software_0.4.

Downloading the System Image

You can obtain the latest image from http://xs-dev.laptop.org/xs/:

wget http://xs-dev.laptop.org/xs/OLPC_XS_LATEST.iso

This can be copied onto a CD or DVD using your favorite software.

Optional: Using a USB key/disk for installation

With version 0.5.x, USB installs are not fully supported, and are reported to fail on a variety of hardware. In case of seeing problems, retry with a normal CD-ROM based installation.

Using a USB key to install this version of the XS involves several additional steps.

• First, ensure you have syslinux installed, and that your USB key is both bootable (you can use gparted to make it bootable) and unmounted.
• Then, copy the installation using the 'mkusbinstall' script you can download here (click on the 'plain' link). Assuming your usb key is /dev/sdb, you can invoke it like this:

mkusbinstall OLPC_XS_LATEST.iso /dev/sdb1

• You may need to configure your machine to boot from USB - see XS_Boot_from_USB for details.
• Early in the installation , anaconda will say that it cannot find its kickstart file. Change the path from 'cdrom:/ks.cfg' to 'hd:sdb1:/ks.cfg'. You will get prompted again for the path to the ISO - set it to Hard Drive, device: '/dev/sdb1' and directory: 'iso'. If the machine has more than one hard drive, then the device might be sdc1 instead of sdb1.

This process has worked on Ubuntu and Fedora systems.

Installing the Software

Please read the release notes for the version you are installing.

The install from a CD or USB key will eventually be automatic upon booting. While the install is currently mostly automated (not interactive), it is not performed automatically upon boot.

1. Boot from the USB Key or CD-ROM
2. Select "Install using kickstart" at the initial boot screen.
   1. "Install using kickstart" is the last menu item. Do not use the other "Install" options on this menu as they only install Fedora 9 without the olpc scripts. The Anaconda installer will install 537 packages. If it announces it is installing 407 packages, the olpc scripts are missing. Start again.
3. Note: the default graphical installer can be unstable at times. You can press tab and add 'text' at the end of the line to request the text-based installer.
4. If booting from a USB key please note the following!
   1. Before installing 0.5, put the ISO imaged USB key into a normal computer, and edit the ks.cfg file. You'll need to delete "--driveorder=sda" (otherwise the installer will fail, although I am uncertain of why).
   2. When it asks for the ks.cfg file with "cdrom:/ks.cfg" and replace with "hd:sdb1/ks.cfg" and it'll work fine.
   3. When it asks what the media to install from is, choose "HD" and then it'll automatically choose /dev/sdb1 and you need to type "iso" into the folder option.
5. Anaconda (the Fedora installer) takes over and you will be prompted for the standard questions - these are preset to the correct defaults for the School Server configuration. You will want to set keyboard type, the time zone, and a root password for your specific system.
6. When prompted to add specific packages just leave the default and click next.
7. When it has finished installing, you will be prompted to reboot. Remove the CD-ROM or USB key after power-down, but before the boot process begins.

You should now have a school server! It needs initial configuration before it starts providing services to the laptops.

Initial Configuration

Basic ejabberd Configuration

Right after installation, you must

• Set the fully qualified hostname of the machine by editing /etc/sysconfig/network as follows:

HOSTNAME=schoolserver.example.org

• Configure ejabberd to use the new hostname by editing /etc/ejabberd/ejabberd.cfg and ensuring the following entry is present in the SERVED HOSTNAMES section:

{hosts, ["schoolserver.example.org"]}.

• Read the Notes about Hostname
• Enable the ejabberd service to automatically start at boot as follows:

chkconfig --level 345 ejabberd on

• Reboot the machine so the hostname change can take effect:

shutdown -r now

• When the machine is back online, login to the console as root again
• Check the status of ejabberd, which should have started on boot, as follows:

ejabberdctl status

• You should get a report indicating that the node is started and the service is running, like this (If you get an error, see Troubleshooting for potential help)

Node ejabberd@schoolserver is started. Status: started
ejabberd is running

• Create an account on ejabberd for the administrator account:

ejabberdctl register administrator  schoolserver.example.org  password

• Configure new administrator user account as an "admin" in ejabberd by editing /etc/ejabberd/ejabberd.cfg and ensuring the following entry exists in the ACCESS CONTROL LISTS section:

{acl, admin, {user, "administrator", "schoolserver.example.org"}}.

• (NOTE: The username and servername for this user must match the one you registered in the previous step)
• Restart ejabberd as follows:

ejabberdctl restart

• Check the status of ejabberd as follows:

ejabberdctl status

• You should get a report indicating that the node is started and the service is running, like this (If you get an error, see Troubleshooting for potential help):

Node ejabberd@schoolserver is started. Status: started
ejabberd is running

Setup Shared Roster Groups for ejabberd

Shared Roster Groups as defined by the ejabberd documentation:

".. you can create groups of people that can see members from (other) groups in their rosters. The big advantages of this feature are that end users do not need to manually add all users to their rosters, and that they cannot permanently delete users from the shared roster groups. A shared roster group can have members from any Jabber server, but the presence will only be available from and to members of the same virtual host where the group is created."

To setup the needed Shared Roster Group for XS:

1. Go to the web-based administration interface for ejabberd at http://schoolserver.example.org:5280/admin/, or http://172.18.0.1:5280/admin/ (default IP address of XS)
2. Login as "administrator@schoolserver.example.org" with the password "password" (the administrator username and password you created in the previous section)
3. Click on "Virtual Hosts", then your hostname (schoolserver.example.org), then "Shared Roster Groups". Type "Online" in the text box at the top of the screen and click Add New.
4. Click on the newly created roster group called "Online" and enter "Online" for Name, "@online@" for Members, and "Online" for Displayed Groups. Click Submit.
   1. Note: In XS v0.5 and v0.5.1, the @online@ directive does not function properly (see defect ticket #9272). A workaround is given in the referenced ticket report, but it has been fixed in XS v0.5.2+.

Optional: Enable Squid transparent proxy

The school server is currently using Squid for web caching. This is not enabled by default, but may easily be turned on. As root, type:

/etc/sysconfig/olpc-scripts/TURN_SQUID_ON

Change DNS settings in /etc/squid/squid.conf to:

dns_nameservers  xx.xx.xx.xx xx.xx.xx.xx   (local and remote DNS servers)

If you need to make any modifications to the default Squid configuration make sure you make the modifications to the XS squid.conf file (called squid-xs.conf) not the default squid.conf file. To point to an external proxy server or a content filtering service simply add the following lines, inserting the appropriate proxy name:

cache_peer parentcache.foo.com parent 3128 0 no-query default
acl all src 0.0.0.0/0.0.0.0
never_direct allow all

Then restart Squid (or the server) and test.

Note: If user authentication is required for the network through a pop-up browser you may need to use Firefox rather than the default browse activity as it doesn't support popups. Also, if you have a PAC file you need to use you can distribute it by DHCP.

To disable web caching, type:

/etc/sysconfig/olpc-scripts/TURN_SQUID_OFF

This disables caching, but doesn't free up any disk space used by existing cached data. You can manually delete the cache, located at /library/cache to free this disk space.

The configuration files for squid are found in /etc/squid/. OLPC provides a custom configuration file /etc/squid/squid.conf through the xs-config package.

Network Configuration

The default server setup is to connect to the Internet on the first wired ethernet network interface, using IPv4 DHCP. Laptops connect to the server over Acceess Points (APs) connected to the second wired ethernet network interface or via the wireless mesh using one or more Active Antenna, connected through USB interfaces.

If your XS has 2 network interfaces and you would like to reverse their (WAN, LAN) roles you can use the xs-swapnics utility.

IPv6 is not enabled by default and not needed -- to enable external IPv6 you will have to configure the global address of the machine and setup an IPv6 tunnel.

Configuring A Static IP Address

To setup your server with a static IP address on the "first wired ethernet network interface" (eth0):

• The following is noted in /etc/sysconfig/network-scripts/ifcfg-eth0:

“If this is the main or only school server, then eth0 defaults to looking for a DHCP lease – if you want to set a static address, create a file called ifcfg-eth0-local in this directory – look at the example file provided under /usr/share/doc/xs-config-*/ifcfg-eth0-local.example”

• Edit the sample file /usr/share/doc/xs-config-*/ifcfg-eth0-local.example with the network configuration your XS server needs, for example:

IPADDR=192.168.12.34
IPV6ADDR=AAAA:BBBB:CCCC:1111:2222:3333/64
NETMASK=255.255.255.0
NETWORK=192.168.12.0
BROADCAST=192.168.12.255
GATEWAY=192.168.12.1

• Save the file as /etc/sysconfig/network-scripts/ifcfg-eth0-local
• Edit /etc/resolv.conf to reflect your DNS server and DNS domain suffix. Using our hostname of "schoolserver.example.org" and the network configuration above, here is an example:

search example.org
nameserver 192.168.12.1

Troubleshooting

Notes about Hostname

For the ejabberd service to run, the name of the ejabberd server (in our case "schoolserver.example.org") must be resolvable to it's IP address (e.g. DNS server alias records). If the ejabberd server name is not resolvable, it will not start and/or will provide some form of error when starting.

If using a static IP address instead of the default network configuration, this will be easily solved by updating "/etc/resolv.conf" with the proper DNS server and domain suffix. See Configuring A Static IP Address for instructions to set up a static IP address.

If using the default DHCP setup with no other special configuration, the normal location for specifying DNS server and domain suffix ("/etc/resolv.conf") is automatically overwritten by startup scripts. Any changes here will not persist on reboot of the XS machine. The startup scripts do not overwrite "/etc/resolv.conf" when there is a "/etc/sysconfig/network-scripts/ifcfg-eth0-local" file present (see Configuring A Static IP Address), but that would disable DHCP.

Hostname has been changed after initial configuration

If you have started ejabberd at one point on a server, and changed the fully qualified hostname (including domain), you must reinitialize the Mnesia configuration database that ejabberd uses. This database stores all configuration information as well as user data and more, but this means that the old hostname remains in the database even if you change it in the ejabberd configuration files. This will cause the ejabberd server to not run or not run properly when the hostname has been changed.

To change the hostname after ejabberd has been started initially, use this process:

• Stop ejabberd

ejabberdctl stop

• Update the fully qualified hostname of the machine by editing /etc/sysconfig/network as follows:

HOSTNAME=schoolserver.newdomain.org

• Configure ejabberd to use the new hostname by editing /etc/ejabberd/ejabberd.cfg and update the "hosts" entry in the SERVED HOSTNAMES section:

{hosts, ["schoolserver.newdomain.org"]}.

• Read the Notes about Hostname
• Follow procedure to refresh Mnesia configuration database Reinitialize ejabberd internal configuration database
• Reboot machine
• Make sure all DNS settings are correct, as mentioned in Notes about Hostname, such that the new hostname is resolvable through DNS or other means

Reinitialize ejabberd internal configuration database

When using the default setup of XS, ejabberd uses the internal Mnesia database for, among other things, storing configuration information. When troubleshooting problems with the intial configuration of ejabberd, this simple "refresh" process will clear out the Mnesia configuration database and when ejabberd starts again it will reinitialize the database based on the configuration files.

NOTE: This process will erase the entirety of ejabberd's Mnesia configuration database, which seems to include all user data. This may take care of the issue preventing ejabberd from running, but it may also be undesireable to lose all user information. It should only be done during the initial configuration of ejabberd when there are no user accounts added yet.

Potential Alternative: It may be possible to erase only a few specific spool files in order to allow reinitialization of the configuration information, but that is unknown at this time by this author. Please contribute that information here if you have it.

• Stop ejabberd

ejabberdctl stop

• Empty the /var/lib/ejabberd/spool/

rm /var/lib/ejabberd/spool/*

• Start ejabberd

ejabberdctl start

Access Points

Most access points are compatible with the XO. For a list of ones which have been shown to work see Wireless Access Point Compatibility. Unless a single access point is being used (not recommended for more than forty to fifty laptops), a network switch of some sort will also be needed.

Active Antennae

Important note: Active Antennae is not supported or available from OLPC at this time

If you have active antenna(e) to use, simply plug them in and reboot the XS. It will detect them and allocate them to mshbond0, mshbond1 and mshbond2. It should just work and XOs will see "School server mesh" when they connect to the mesh served by the XS. You may need to manually allocate different frequencies per antenna.

AP Configuration

The steps for setting up a wireless router access point vary based on the wireless router being using, but this serves as a rough guide for installation. These steps were run using a Zoom Wireless-G model 4400 router.

• Press the reset button on the wireless router to reset it and connect it to any computer. It's possible to do this setup with an XO or any other machine with linux installed.
• Open terminal and type

ifconfig eth0 IPaddress

Where IPaddress is in the same subnet as the default IP for the access point

• Connect to the access point by typing in the IP address in a web browser.
• Login to the access point using the default password (or skip entering a password if none is provided)
• Set the wireless channel to 1, 6 or 11 to minimize interference
• Set a unique name for the wireless network
• Make sure that the access point is NOT running as a DHCP server and it's not running NAT

Recommended Hardware Specifications

A number of computers may act as a school server, but it must be a Fedora-capable computer. Recommended minimum specifications for a school server are as follows:

Server	Laptops Supported	Processor	RAM	Storage
Small	<20-25	466 MHz	1 GB	40-120 GB
Large	<150	1 GHz	1 GB	320-750 GB

See XS Recommended Hardware for more information.

Installing additional software

If you wish to install packages that aren't part of the default school server distribution, you should first try using yum. The stable and testing school server repositories include all packages included in Fedora, even if they aren't installed by default. For third party software you should follow their installation procedure for Fedora 7 or for the XS Server specifically. For example, to install Moodle, follow these instructions: http://docs.moodle.org/en/OLPC_XS_installation#Install_Moodle_from_the_OLPC_XS_Image

Keeping your XS software up to date

Upgrading a server is done using the yum package interface provided by Fedora.

If you have an Internet connection, you can upgrade from the default servers at OLPC, or your own mirrors of them. This is done using yum:

 yum -y upgrade

Upgrading from XS 0.4 or earlier

If you are upgrading from XS 0.4 or earlier, the process is similar to a new installation, with some minor changes. In the menu shown right after booting, you should choose one of the 'Install or upgrade an existing system' options, press the Tab key, and add 'upgradeany' to the boot configuration line. After adding that line, press enter twice.

With this extra option, Anaconda will recognise the old installation and will offer to upgrade.

Notes:

• Right after the upgrade, you must re-run the /etc/sysconfig/olpc-scripts/domain_config script with the appropriate domain name for the machine.
• The new OS may detect your network cards differently -- the roles of WAN and LAN cards may end up swapped from what they were under 0.4. If that happens, use the xs-swapnics script and reboot.

Upgrading from XS 0.5 or later

If you have internet access and you wish to update just the xs-server packages you can use yum:

yum --disablerepo=* --enablerepo=olpcxs update

See also

• XS Server Installation