User:Holt/XS Community Edition/Documentation/Hacking

Summary

This is the Documentation for initial version of the School Server - Community Edition, Version 0.1.

The target audience will be the 7 people working from Holt's home. Experienced Linux users and admin with a strong interest in hacking. Enough interest that they made the trip to Toronto February 6-10th, 2013. Stage 2, hopefully for version 0.2 will include the larger school server development community. Stage 3, hopefully for version 0.3 will begin the emphasis on end user documentation.

Based on practical experience and this document a hacker should be able to download the XS code, modify the code, build an rpm, and install an RPM. Secondary goals will be to download a RPM and install a fully functioning School Server.

Purpose

The purpose of this iteration of documentation will be to provide a stable enough starting point from which hackers can load and modify it for their individual purposes.

Design and architecture

Conceptually, the school server is a collection of common network services which can be easily installed and configured as necessary. Modularity is important in order to provide a core base of services on top of which extended service modules can be installed. Their is an ongoing discussion about what are Core Services versus Extended Services, previewed below. Over time this should settle down.

Code layout

Currently the code lives in the xs-config/ dir. Consider these 3 subdirectories of xs-config:

1. scripts/
   Configuration consists of a series of scripts which live in the scripts/ dir. The process is kicked off by running xs-setup. xs-setup calls a series of scripts with the naming convention the xs-[ServiceName] each of which set up an individual service.
2. cfg/etc/
   When necessary, the xs-[ServiceName] scripts installs files from under cfg/etc as necessary.
3. cfg/html/top/
   The web based GUI is located under cfg/html/top/

Core Services

• Dynamic Host Configuration Protocol (dhcpd) DHCP (Dynamic Host Configuration Protocol) allows the school server to assign IP addresses to connected XOs. DHCP is a network protocol used to configure network devices so that they can connect and communicate over an IP network.
• Internet Domain Name Server (named) The Domain Name System (DNS) converts the name of a Web site (www.google.com) to an IP address (65.115.71.34). Named is a daemon within BIND that responds to DNS queries from remote machines.
• Network Address Translation/NAT, Gateway, IP Masquerading, Firewall (iptables) NAT. The School Server used Network Address Translation to provide security, privacy, and scalability. NAT enables all of the XOs within a school to appear to the world as a single machine. As a security measure all packets pass through the server. This can be further augmented by additional filtering. Privacy in enhance because students machines are not directly accessible from the public internet. Finally NAT enhances scalability as an entire school only needs a single IP address.
• XMPP server (ejabberd) Extensible Messaging and Presence Protocol (XMPP)is a communications protocol for near real-time, instant messaging (IM), presence information, and contact list maintenance. In the classroom environment it's used to give support to XO Collaboration features through Gabble.
• IDMGR : The Identity Manager is a service which accepts requests for registration from laptops School_Identity_Manager

Try it

Downloading code

$ git clone http://dev.sugardextrose.org/xs-config

$ git clone git://dev.sugardextrose.org/xs-config <-- (Shows progress through git:// protocol)

or for commit access (requires login and password)

$ git clone http://dev.sugardextrose.org/git/xs-config

Building

$ make rpm

Install Prereqs

This recipe installs XS Community Edition on XO-1.75 (ARM) running OLPC OS 12.1.0 (http://wiki.laptop.org/go/Release_notes/12.1.0) with power management turned off within My Settings | Power.

During the install process, your XS server must be connected to the Internet, via its built-in Wifi adapter/ears (it may NOT connect to the Internet thru a USB Ethernet Adapter during your install). After the install process, your XS server may connect to the Internet using others mean.

Also required is a USB Ethernet Adapter connected to a separate Wifi access point (call it AP-LAN) so kids' XOs can later connect their XOs to the server.

Repeat any of the download steps below if they fail due to Internet/DNS glitches.

Install Recipe

1. Ensure USB Ethernet Adapters are NOT connected.
2. Launch Terminal Activity (unhide Terminal if necessary, clicking List View in the top right of Home View).
3. Change to user root by typing "su".
4. Set date using "date mmddhhmmyyyy" where mm=month, dd=day, hh=hour, mm=minute, yyyy=year. This is required for yum to work correctly.
5. Change directory by typing "cd /etc/yum.repos.d"
6. Download the needed yum repo by typing "wget http://georgejhunt.com/olpc/files/xsce.repo" (downloads 200+ bytes).
7. Install xs-config-xo by typing "yum -y install xs-config-xo" (downloads 17+ MB).
8. Type "bootstrap-xo" (downloads 34+ MB).
9. Press [Enter] to reboot.
10. Launch Terminal Activity.
11. Change to user root by typing "su".
12. Type the command "xs-setup" . This generates a long list of "yum" install requests, similar to the normal adding of functions that you would do if you loaded a minimal "network" install CD from Fedora, and then added additional functions one at a time. (downloads 200+ MB)
13. "INSERT USB ETHERNET ADAPTER NOW" warning will appear. Insert it as instructed.
    Type "y" to continue. 40+ minutes later, your XS should return to a root prompt with the message "XS configured; services are ready to use." (downloads about 200 MB !)
14. Remove any USB Ethernet Adapter
15. Reboot.
16. Re-insert USB Ethernet Adapter.
17. ?? why ?? 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
18. ?? 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, to disable the AP's own DHCP)