XS Techniques and Configuration

This page lists various techniques and configuration options available for the XS.

If you are changing this page, mention it on server-devel@lists.laptop.org .

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 If you are tracking a development/testing version, you should do yum --enablerepo=olpcxs-testing -y upgrade

Moodle

First user to login to Moodle is has Course Creator role!

After initial installation, the first XO successfully login to Moodle will be granted the "course creator" role, which grants access to safe administration options. The user must

• Associate successfully to the AP that is controlled by the XS.
• Register
• Reboot
• Open Browse.xo and follow the "Local Schoolserver" link

More Course Creators

If there are other users in the school that should also have course creator rights, the existing course creator can assign the role to them visiting Admin->Users->Permissions->Assign system roles . The other users need to be registered before this can happen.

Controlling Course Creators directly

If you want to override the default "first user is course creator" policy, you can provide a static list of usernames (the Serial Number, in the case of XOs), in a newline-delimited file, readable by apache:

echo 'SERIALNUMBER' >> /etc/moodle/coursecreators
chmod ugo+r /etc/moodle/coursecreators

If the file is empty (touch /etc/moodle/coursecreators) then no user will be granted the coursecreator role.

Logging in from non-XO computers

If you want to login from a non-XO computer...

• From the XO with course creator rights, login and create a new user account manually. Select username, password, etc.
• On the non-XO computer, visit http://schoolserver/ and login

Alternatively, you can use the special admin account. This is not recommended.

Logging in with the admin account

Use at your own risk! Direct access to the admin account is not recommended. It may break your Moodle-on-XS today, or it may lead to breakage on upgrades.

• Normally the account is disabled (and only enabled at upgrade time). Enable the account with

sudo -u apache php /var/www/moodle/web/local/scripts/adminuser-enable.php

• After each upgrade, the account will be disabled again.
• Look at the password - it is different for every XS:

cat /etc/moodle/adminpw

• Login with the username admin.
• If you are logging in from an XO which auto-logins using your registered account, you can access the login page directly by editing the URL to say http://servername/moodle/login/. You can use this form even if you are logged in.

Change language

To change the language of the moodle interface:

1. Follow the process above to login as admin
2. Go to Site Administration > Language > Language packs in the Moodle interface
3. Use this page to download and install a language pack from here.
4. You can now change the default language to the language pack that you just installed.

Moodle Initialization Fails

During the first boot after an installation or upgrade Moodle will run its initialization/upgrade scripts. These scripts are triggered by the existence of /etc/moodle/needsupgrade and when they execute, they log to /var/log/moodle-instupg.log.

If there is no /etc/moodle/needsupgrade file and the log ends with a line saying 'Success', Moodle should be installed and running correctly.

In case the initialization/upgrade has failed

• Make sure to report the situation to the server-devel mailing list, attaching /var/log/moodle-instupg.log, and a description of the situation.
• Drop the database: sudo -u postgres dropdb moodle-xs (this will lose all the data in Moodle, so it is only safe in case of new installations).
• Start the Moodle 'service': service moodle-xs start. This may take a while (specially on XS-on-XO) and you can trace the execution by 'tailing' the logfile with tail -f /var/log/moodle-instupg.log from a different console.

Segregating presence by course groups

This technique is for schools where the number of XOs is larger than ~60. When you use this approach, you manage groups ("courses") within Moodle, and the Neighbourhood view of XOs will show only fellow members of courses the user belongs to.

1. Make sure you are using a recent Browse.xo (101 at least, I think)
2. The first XO to register (reboot) and visit moodle successfully gets some extra rights (is an 'admin' of sorts). So get an XO reg'd and visiting Moodle -- it will auto-authenticate into Moodle. Should see a 'site administration' block on the left.
3. Create some courses (Site Administration->courses->Add/edit->Add new), assign teachers and students. In the long and confusing "new course" form, all you need to set is Full Name and Short Name. Please ignore every other option. Note: when it comes to enrolling, setup some courses for XOs you have registered already -- this is mainly to have something to work with! You can add more courses & enrolments later. Might help: http://docs.moodle.org/en/Enrolment#Manual_enrolment
4. In 'Site Administration', go to Courses->Presence Service, and set presencebycourse to Yes.
5. Within 10 minutes, issuing the same ejabberdctl queries as above should show that Online has been replaced by several SRGs -- one per course. Asking for the 'info' of those, will show you their membership.
6. When you make the switch from one mode to the other on the XS side, the situation will be confusing for the XOs, so they might need to re-associate to the Access Point (so they re-query their group membership) before they see the changes.

Note: All changes to the course membership take 5~10 minutes to appear in ejabberd on the XOs, and some changes may also need an XO to reassociate to the AP.

Presence Service (ejabberd)

Troubleshooting

If XOs are appearing when they should not, or not appearing when they should in an XS-hosted network, the following commands help understand what is happening.

On the XS,

## XOs need to be registered before they can use the XS-based
## collaboration protocol (gabble)

# List who is registered with the XS
/home/idmgr/list_registration

# List who is registered with ejabberd
# (this happens on the first reboot after the user has used the 'register' option)
ejabberdctl registered-users `hostname -f`

# List who is online
ejabberdctl connected-users

On the XOs, check that it has been registered & restarted, then open a Terminal and try

# Will report various settings, including which jabber server it connects to
# and whether the collaboration ("Telepathy") infrastructure is using
# "Gabble" (XS-based) or "Salut" (for networks without an XS)
olpc-netstatus

Performance Monitoring

You can monitor the CPU and memory use of the components of ejabberd by running etop like this

/sbin/runuser -s /bin/bash - ejabberd -c '/usr/bin/erl -sname ejabberdtop-1 -hidden -s etop -s erlang halt -output text -tracing off -node ejabberd@schoolserver '

Once it's running, press Control-G to get to an erlang commandline. There, q exits the Erlang environment

More info on etop at http://www.erlang.org/documentation/doc-5.2/lib/observer-0.9/doc/html/etop_ug.html

Internet Content Filtering

If you are going to encourage children to surf the Internet, you are strongly advised to arrange for some kind of content filtering. All filtering solutions are imperfect, it is important to emphasize user education -- see Online threats and security.

Use OpenDNS

Create your account with OpenDNS, configure it to your liking. Then set their DNS servers in a forwarders line in /etc/named-xs.conf.in -- look for the "options { " section, and add a line that says:

  forwarders {208.67.222.222; 208.67.220.220;};

and then

   /etc/sysconfig/olpc-scripts/domain_config
   /etc/init.d/named restart

OpenDNS is good, and for simple deployments it may be enough. Many schools use it and users can report urls for blocking, so its wide usage makes the filtering better.

When users report domains that are not blocked, report the domains to the OpenDNS and they will be blocked.

Planning for a content filter

For multiple school deployments

Run a filter at the ISP, or at the facilities of the Ministry of Education. Avoid running the filter on the XS itself. It is serious burden on the XS memory, CPU and Internet bandwidth. And administration on a per-school basis is awkward and inefficient.

Instead, get a machine co-located at the ISP, run a filtering proxy there (such as DansGuardian). Don't forget to tighten the rules to avoid running an open proxy. And on the XSs at schools, enable Squid and point it to the "upstream" proxy.

This means the filter is in one place, and there is only one blacklist (and whitelist) to maintain.

Running a local filter on the XS

Possible, but not recommended. Filters are not particularly smart, so they have to be complemented with human users reporting filtering errors. The amount and quality of that feedback makes the filtering better -- a local filter never gets enough input to get any good.

HTTP proxies

Transparent HTTP proxy (for reliable internet connections)

The school server is currently (0.4 to 0.6) 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

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-xs.conf through the xs-config package.

WWWOFFLE for unreliable or intermittent internet connections

• Make sure that squid is turned off

 /etc/sysconfig/olpc-scripts/TURN_SQUID_OFF]
 service iptables restart

• Create a directory for downloads (optional) and download  and install the wwwoffle file

 mkdir /downloads
 cd /downloads
 wget http://dl.atrpms.net/all/wwwoffle-2.8b-2.0.1.el5.i386.rpm
 yum --nogpgcheck localinstall /downloads/wwwoffle-2.8b-2.0.1.el5.i386.rpm

• When the installation finishes you need to edit the wwwoffle.conf file to configure it for the XS

ed /etc/wwwoffle.conf

• Change the line " http-port =     8080" to " http-port =     3128" using the

  search "/" and change "c" commands as follows:

  /http-port   /     (search till you get to the line " http-port =     8080")
  c
  http-port =    3128
  ^c       (<control-c> stops the changing)

• In a similar manner search for and change the following in the LocalHost

section substituting YourDomain with your own:
 " localhost" to "YourDomain.org"

• Search for and add a line in the "LocalNet" section substituting YourDomain with your own to get:

 LocalNet
 {
  *.YourDomain.org

• Search for and add lines in the "AllowConnectedHosts" section for your AP IP ranges:

  AllowedConnectedHosts
  {
    172.18.96.*

• Write the changes "w" to save them and quit the editor "q"

  w
  q

• Start the wwwoffle daemon (It will start automatically at reboot)

  wwwoffled -c /etc/wwwoffle.conf

• Go online or offline with the following commands

  wwwoffle -online
  wwwoffle -offline

• Turn your XO proxy settings on using Browse and going to the URL about:config

• filter the word "proxy" and double-click to adjust the settings to:

 network.proxy.http		(172.18.0.1)
 network.proxy.http_port	(3128)
 network.proxy.type		(1)

Setting a static IP address for eth0

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

• 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
• If you can only resolve hostnames on the schoolserver but not external hostnames (like 'laptop.org'), you may have to add your ISP's nameservers to /etc/named-xs.conf file as forwarders. See the next topic...

Use ISP-provided DNS servers

Set their DNS servers in a forwarders line in /etc/named-xs.conf.in -- look for the "options { " section, and add a line that says:

  forwarders {208.67.222.222; 208.67.220.220;};

replacing the IP addresses with the ones provided by your ISP, and then

   cd /etc
   make -f xs-config.make named-xs.conf
   /etc/init.d/named restart

Using a different WAN connection

If your WAN connection is not eth0, the NAT/masquerading firewall rules need to be told about it. For example, if it is wlan0:

 echo wlan0 > /etc/sysconfig/xs_wan_device
 service iptables restart

Using a wireless NIC for WAN

If you have a wireless NIC for your WAN port...

• Create /etc/sysconfig/network-scripts/ifcfg-wlan0, which should look like

 DEVICE=wlan0
 ONBOOT=yes
 BOOTPROTO=dhcp
 DHCP_HOSTNAME=schoolserver
 ESSID=YOURESSID
 TYPE=Wireless
 USERCTL=yes

• Tell the firewall that the WAN port is wlan0, with

 echo wlan0 > /etc/sysconfig/xs_wan_device
 service iptables restart

• If the network is encrypted, ensure wpa_supplicant service is set to run, and configure the right device and driver in /etc/sysconfig/wpa_supplicant. Usually you want:

 INTERFACES="-iwlan0"
 DRIVERS="-Dwext"

• Restart wpa_supplicant :-) -- enable logging (and look at the logs) if you need to debug.
• If the network is encrypted, you'll want to add the passphrase like this:

 wpa_passphrase ESSID mypassphrase >> /etc/wpa_supplicant/wpa_supplicant.conf

With this, ifup wlan0 should bring the wlan up.

For on-boot wlan0, you need to workaround this boot-order bug: https://bugzilla.redhat.com/show_bug.cgi?id=244029

Installing from USB

XS 0.5.x and 0.6.x series

On these versions 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.

1. First, ensure you have syslinux installed, and that your USB key is both bootable (you can use gparted to make it bootable) and unmounted.
2. 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

1. You may need to configure your machine to boot from USB - see XS_Boot_from_USB for details.

Fixing up the installation "sources" so that it works

In the resulting USB stick, the file syslinux/extlinux.conf needs editing. It will say

append initrd=initrd.img ks=hd:LABEL=XSRepo:/ks.cfg method=hd:LABEL=XSRepo:/iso

you need to make a good guess of the device and partition the USB disk will turn up as. If your machine has only one fixed hard drive, it will probably be sdb. If the installer is contained in the first partition of the disk, then it is sdb1. Now replace that line to say

append initrd=initrd.img ks=hd:sdb1:/ks.cfg method=hd:sdb1:/iso

Note: Anaconda scans and re-scans devices, so it may re-prompt for the location of the Kickstart file due to a timing issue. Normally waiting a second and hitting enter works. Similarly, you will probably get prompted again for the path to the ISO - set it to Hard Drive, device: '/dev/sdb1' and directory: 'iso'.

Making customisations to your install process

It is easy to add post-instalation configurations when you are using USB for installation.

On the USB disk, the kickstart file is extracted from the iso image, and you can just edit it in-place with a text editor (if on Windows, ensure your text editor uses Unix newlines). The name of the file is ks.cfg.

Most changes will be in a %post section, or a %post --nochroot section. In a %post --nochroot section, the USB disk is mounted in /mnt/isodir, and the disk you are installing to will be in /mnt/sysimage. Some basic utilities like tar and rpm are available.

Example: install static HTML content

Add a section at the end of the ks.cfg file containing

 %post --nochroot
 
 # copy the apache configuration file which should have an "Alias" line,
 # a Directory section, etc...
 cp /mnt/isodir/education_portal.conf /mnt/sysimage/etc/httpd/conf.d/education_portal.conf
 mkdir /mnt/sysimage/library/education_portal/html/
 tar -xzf /mnt/isodir/edu_portal.tar.gz -C /mnt/sysimage/library/education_portal/html/
 
 %end

The USB disk must contain the education_portal.conf and edu_portal.tar.gz file, together with the files that mkusbinstall put in place.

Testing/debugging trick for kickstart %post --nochroot

You can perform the kickstart installation, and when it ends (at the "restart" dialog), press Ctrl-Alt-F2 to get to the shell console. The commands and mountpoints you have there are exactly the same that your %post --nochroot script will see.

Access Points

Zoom Wireless-G 4400

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.

DD-WRT

• Turn off DNSmasq.
• Visit Advanced Routing / Operating Mode and change the mode from "Gateway" to "Router".
• Move all the interfaces to the same VLAN (you must change the operating mode first).

Fixed addresses for Access Points and other devices

The XS has a reserved range of IP addresses for devices that you manually configure to have a static IP address: 172.18.126.0/24.