XS Community Edition/0.4/Configuring

This IIAB XSCE content does not reflect the opinion of OLPC. These pages were created by members of a volunteer community supporting OLPC and deployments.

Initial Setup

1. Use "ifconfig" to determine the ip address of the XS.
   Take note of its eth0-ip-address = WAN-ip.
   If you've inserted the USB Ethernet Adapter above (serving the LAN/Intranet) also take note of the school server's eth1-ip-address = LAN-ip = 172.18.96.1
2. If you inserted the USB Ethernet Adapter above, configure its own Wifi Access Point (AP) to properly serve other LAN/Intranet client XOs. (If the Wifi AP is a router, DO NOT plug into its "WAN" port -- instead use any of its LAN/normal ports. And be sure to enable the AP's "bridge mode" or similar, or specifically disable the AP's own DHCP)

Access Point Setup

It's best to start with your AP set to factory settings. You can search the model number to find reset instructions for your particular AP, as well as the IP of the administrative interface and the login credentials.

Once you've connected to the AP and logged into the administrative interface, turn off wifi security. You can always reenable it once you've made sure it's working with the XSCE.

Next, disable NAT and the DHCP server. Last, set the IP address of the AP to an IP in the 172.18.126.0/24 range and the netmask to 255.255.224.0. That IP range is set aside on the XSCE for static network devices. Be sure to make a note of what you set the IP to so you can get to it later when it's connected to the XSCE.

At this point, most APs require a reboot for the changes to go into effect.

Once you've got it connected to the XSCE and passing traffic, you can change the administrative password and enable wifi security if desired.

Dynamic Host Configuration Protocol (dhcpd)

MAC filtering creates additional security for a password protected wifi network. However, if your wifi network is not already password protected, MAC filtering can prevent most unauthorized devices from accessing the network. In situations where you can't expect XO users to type in wifi passwords, MAC filtering is an option to enable password free wifi access. And if the wifi password becomes an "open secret," admins are still able to control access per device.

This dhcpd configuration example only hands out IP addresses to XOs as well as known clients identified by MAC addresses.

Please backup /etc/dhcpd-xs.conf.in file before editing.

#
# School server 1 DHCP Server Configuration file.
#
ddns-update-style interim;
#ignore client-updates;

option domain-name "@@BASEDNSNAME@@";
option domain-name-servers      172.18.96.1;
option ntp-servers		172.18.96.1;

subnet 172.18.96.0 netmask 255.255.224.0 {
	option routers			172.18.96.1;
	option subnet-mask		255.255.224.0;
	option broadcast-address	172.18.127.255;
	class "xo" {
	match if substring (hardware,1,3) = 00:17:c4
    	or substring (hardware,1,3) = 20:7c:8f
    	or substring (hardware,1,3) = 20:16:d8;
    	}
	# this is the whole range we have available - 8K addresses
	# range                           172.18.96.2 172.18.127.254;
	# instead, we'll save 510 addresses for later. 
	# range                           172.18.96.2 172.18.125.254;
	# the other /24s:
	# -> 172.18.126.0/24 for static IP addresses
	#    for printers, AP management consoles, etc.
	# -> 172.18.127.0/24 for temporary addresses for 
	#    XO activation
	
        # As this subnet is wired or wifi a/b/g, these lease 
	#    times are on the long side
	default-lease-time 	10800;
	max-lease-time 		21600;
 	# Address pool for just XOs
    	pool {
        allow members of "xo";
        range 172.18.100.2 172.18.100.254;
    		}
    	# Address pool for known clients specified at the bottom
    	pool {
        range 172.18.101.2 172.18.101.254;
        deny members of "xo";
        deny unknown-clients;
    		}
    	# Address pool for unknown clients, uncomment the below stanza, run xs-domain-config
	# and restart dhcpd if it's a special free wifi day
    	#pool {
        #range 172.18.102.2 172.18.102.254;
        #deny members of "xo";
	#deny known-clients;
	#allow unknown-clients;
    	#	}
	}

host N900 {hardware ethernet 5c:57:c8:77:fe:45;}

If you need someone's MAC address to add to the dhcp config file, ask them to try to connect while you look at /var/log/messages. You should see something like:

Aug 25 01:44:03 schoolserver dhcpd: DHCPDISCOVER from f0:a2:25:18:53:00 via eth2: network 172.18.96.0/19: no free leases

Now that you have the MAC address, you can add it to the bottom of /etc/dhcpd-xs.conf.in:

host kindle-fire {hardware ethernet f0:a2:25:18:53:00;}

Then run 'xs-domain-config' and 'systemctl restart dhcpd.service' and they'll be able to connect their device to the XSCE as a "known client."

Network Address Translation/NAT (iptables)

The XSCE iptables configuration is managed by the /bin/xs-gen-iptables script. By default, the only port visible from the outside is ssh (port 22). To open other ports, say for the web server (port 80), or ejabberd (ports 5222 and 5223), look for this stanza in /bin/xs-gen-iptables:

if [ -f /etc/sysconfig/xs_httpcache_on -o -f /etc/sysconfig/olpc-scripts/setup.d/installed/gateway ] ; then
    $IPTABLES -A INPUT -p tcp --dport ssh -m state --state NEW -i $wan -j ACCEPT
fi

Below the ssh line, add the lines for the ports you would like to open. This example shows the XSCE open for the Apache web server and ejabberd.

if [ -f /etc/sysconfig/xs_httpcache_on -o -f /etc/sysconfig/olpc-scripts/setup.d/installed/gateway ] ; then
    $IPTABLES -A INPUT -p tcp --dport ssh -m state --state NEW -i $wan -j ACCEPT
    $IPTABLES -A INPUT -p tcp --dport 80 -m state --state NEW -i $wan -j ACCEPT
    $IPTABLES -A INPUT -p tcp --dport 5222 -m state --state NEW -i $wan -j ACCEPT
    $IPTABLES -A INPUT -p tcp --dport 5223 -m state --state NEW -i $wan -j ACCEPT
fi

To commit the changes to iptables, and thus open the additional ports to the outside, reboot.

XMPP server database backup and restore (ejabberd)

It's possible to run the XSCE as a public Jabber server, not just for XOs running Sugar, but also "regular" XMPP clients such as Pidgin, Gajim, Psi, Adium, Jaibiru (on Android), and others. Rather than force your users to redo their logins when reinstalling the XSCE, you can migrate the registrations and the ejabberd certificate. Upon server switchover, users should only see their clients disconnect and then reconnect, none the wiser.

Note: This only works if the "old" XSCE and the "new" XSCE were set up with the exact same hostname.

On the "old" XSCE, back up the ejabberd database in /tmp:

ejabberdctl backup /tmp/jabber.bak

From the "old" XSCE, transfer /tmp/jabber.bak and /etc/ejabberd/ejabberd.pem to the "new" XSCE. It's OK to just throw those two files into /root.

On the "new" XSCE, overwrite the cert:

cat ejabberd.pem > /etc/ejabberd/ejabberd.pem

On the "new" XSCE, restore the database (not sure why, but jabber.bak wants to be in /tmp):

mv jabber.bak /tmp
chown ejabberd:ejabberd /tmp/jabber.bak
ejabberdctl restore /tmp/jabber.bak

The ejabberdctl restore command might take a few minutes.

Web server (apache)

If you want to have simple password authentication to a web directory, it's fairly simple. Here's an example.

Say you'd like http://schoolserver/secret to be password protected. Create /etc/httpd/conf.d/secret.conf:

<Directory /var/www/html/secret>
  Options Indexes FollowSymLinks MultiViews
  AllowOverride AuthConfig
  AuthName "This is a secret dir, but the user/password is secret/phoebe"
  AuthType Basic
  AuthUserFile /home/admin/.htpasswd
  Require user secret
</Directory>

Generate the password hash (these aren't the usual instructions because of a bug in Apache 2.4.4):

htpasswd -nb secret phoebe > /home/admin/.htpasswd

Where secret is the user name (no, it's not a user on the XSCE) and phoebe is the password.

Restart the server:

systemctl restart httpd.service

Now when users go to http://schoolserver/secret, they'll have to enter the username and password in a login box.

Proxy server and web cache (squid)

To disable squid: (eg. on an XO-1 whose memory/storage can only handle minimal services)

systemctl stop squid.service
systemctl disable squid.service
rm /etc/sysconfig/xs_httpcache_on
xs-setup-network

Virtual Private Network (OpenVPN)

For release 0.4, software keys are provided which will enable you to connect to an OpenVPN server at xsce.activitycentral.com. This will create a worldwide party line which can potentially connect the school servers within a deployment with administrators and support people in other parts of the world, and to one another.

This "virtual private network" is really a public network. Anyone who installs XSCE can connect to the central server, and attempt to connect to any of the computers that are similarly connected. However, conversations on this "public" vpn will be encrypted by ssh, and only directed to the two machines that have established an ssh connection.

CAUTION: Since the XSCE has enabled passwords for ssh conversations, and has created the "admin" user, and a standardized password, It is vitally important to change the password for user: "admin". This can be done by becoming "root", and setting a new password by the terminal command "passwd admin".

A more secure approach would be to turn off password authentication completely, and use ssh_keygen to create your own set of public/private keys for use with your deployment and machines.

By default, the vpn software is loaded on the machine, but not activated. To work as a communication path, the openvpn tunnel must be turned on. The vpn tunnel is controlled by the following commands:

xs-vpn test
xs-vpn on
xs-vpn status
xs-vpn off

"xs-vpn test" will start up the vpn tunnel. The intention was to have the "xs-vpn on" issue a warning it it discovers that password authentication is being used, and to suggest that public/private keys be used in stead. (It was discovered late in the QA cycle that this error message ins not issued). It will be corrected for the next release.

If it is desireable to have the vpn-tunnel always open, so that remote administration is continuously available, you can put the following line in /etc/crontab

1 * * * * root xs-vpn on #for hourly vpn startup -- or
* 1 * * * root xs-vpn on #for daily startup

More details are available for Setting Up an XSCE VPN

Tiny Core Linux Customization tool

By copying the contents of the folder /usr/share/xs-config/tcccustomize to a USB stick, a small deployment can add or remove activities from a stock OS image (see http://dev.laptop.org/~quozl/mktinycorexo/HOWTO.xo-custom

To do this copy, insert a USB stick into the schoolserver, and at a terminal prompt, issue the command

ls /mnt/usb*

The USB stick is automatically mounted and will be listed. Note the path of the stick, and copy the customization program to the stick:

cp -rp /usr/share/xs-config/tccustomize/* <path of the target stick>

Note that this will require that the XO terminals be unsecured. You can determine if a laptop is secured by turning it on, and then immediately pressing the "esc" key in the upper left of the keyboard. If you get an "OK" prompt, the laptop is already security disabled. If no "OK", then obtain a Developer key, and issue "disable-security" at the OK bios prompt --http://wiki.laptop.org/go/Activation_and_developer_keys#Disabling_the_security_system).

Content Filtering with OpenDNS

There are two components to settting up content filtering with OpenDNS. First, the XSCE needs to look at OpenDNS's DNS IP addresses for DNS. Then there must be an OpenDNS account associated with the XSCE's public IP address. Simply specifying the OpenDNS servers as the XSCE's DNS servers doesn't filter any content. You need to set up an account and configure the content filter level so that OpenDNS knows what to block for your specific IP address.

You may wish to use the OpenDNS DNS servers instead of your ISPs DNS servers if your ISP's DNS servers are unreliable. If you don't need content filtering, no account is required.

To point the XSCE to the OpenDNS DNS servers, edit /etc/named-xs.conf.in for the forwarders line:

options
{
        /* make named use port 53 for the source of all queries, to allow
         * firewalls to block all ports except 53:
         */
        forwarders {208.67.222.222; 208.67.220.220;};

Run this command to write the change to named-xs.conf.in to named-xs.conf:
xs-domain-config

Restart the named service:
systemctl restart named.service

Now the XSCE is pointing to OpenDNS's DNS servers. However, internet content will not be filtered until you set up an account with OpenDNS and configure your filter level.

From the IP you wish to enable content filtering for, go to http://www.opendns.com and create an account. When setting a label (friendly name) for your network, it's best to avoid special characters and spaces.

Once your OpenDNS account is created and your network is listed in the settings tab, click on the network's IP to manage settings. Under "Web Content Filtering," select your desired content filter level and click Apply.

If you have a static IP, setup is complete. If your IP is dynamic, the ddclient service is necessary to update OpenDNS when your IP changes.

The ddclient service requires three pieces of information about your OpenDNS account: username, password, and network label. The network label can be found under the OpenDNS Dashboard, in the settings tab, listed in the "LABEL" column under "Your networks."

To install ddclient:
yum -y install ddclient

At the bottom of /etc/ddclient.conf, append the following lines:

##
## OpenDNS.com account-configuration
##
use=web, web=myip.dnsomatic.com
ssl=yes
server=updates.opendns.com
protocol=dyndns2
login=yourlogin
password=yourpassword
your-network-name

Remember how you needed three pieces of information about your OpenDNS account? Edit these three lines with your OpenDNS login credentials and your OpenDNS network label:

login=yourlogin
password=yourpassword
your-network-name

Enable the ddclient service, for all future boots:
systemctl enable ddclient.service

Start the ddclient service, during the current boot:
systemctl start ddclient.service

If ddclient fails to start with the above command, reboot the XSCE and verify that ddclient came up at boot:
systemctl status ddclient.service

The default ddclient update interval is 300 seconds, which you can change in /etc/ddclient.conf.