User:Holt/XS Community Edition/0.2/Hacking

Summary

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

The target audience will be experienced Linux users and admin with a strong interest in the School Server.

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 documentation will be to provide a stable enough starting point from which hackers can view, modify, and install the server code 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 and modified. Their is an ongoing discussion about what are Core Services versus Extended Services, previewed below. Over time this should settle down.

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 : TODO fix The Identity Manager is a service which accepts requests for registration from laptops School_Identity_Manager

Extended Services

• Web server (apache) A web server enables the school server to generate and deliver web pages at the request of client Laptop. The web server is a building block for many other extended services.
• Proxy server and web cache (squid) A proxy server and web cache reduces the overall bandwidth needs of the school. All Laptops requests pass through the proxy and are temporarily stored. If more than one student requests the same file, the proxy only has to go out to the public internet once.
• OLPC-update (rsync) OLPC-update is necessary to update the kernel of XO due to modifications that have been made to the kernel which prevent standard package management systems from working correctly.
• Activity update (activity updater) The activity updater enables teachers to easily distribute new or updated activities to their students
• Virtual Private Network (open vpn) The Virtual private Network is useful for creating secure point-to-point connections in routed or bridged configurations which makes is possible for remote access facilities

The Code

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

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/

Building

$ make rpm

Installing

XS-CE 0.2 will run on XO 1.75 and standard x-86 machines.

XO 1.75 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.

Installing

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 "http://build.activitycentral.com/xs-extra/xs-config.repo".
7. Download the needed yum repo by typing "http://build.activitycentral.com/xs-extra/xs-extra.repo".
8. Install xs-config-xo by typing "yum -y install xs-config-xo" (downloads 17+ MB).
9. Type "bootstrap-xo" (downloads 34+ MB).
10. Press [Enter] to reboot.
11. Launch Terminal Activity.
12. Change to user root by typing "su".
13. 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)
14. "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 !)
15. Remove any USB Ethernet Adapter
16. Reboot.
17. Re-insert USB Ethernet Adapter.

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, to disable the AP's own DHCP)

Commodity X86 machine

TODO finish

Prereqs

This recipe installs the XS Community Edition on a commodity x86 machine running fedora 17.

During the install process, your XS server must be connected to the Internet, via its built-in Wifi adapter/ears. After the install process, your XS server may connect to the Internet using others mean.

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

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://build.activitycentral.com/xs-extra/xs-extra.repo".
7. Download the needed yum repo by typing "wget http://build.activitycentral.com/xs-extra/xs-config.repo".
8. Launch Terminal.
9. Change to user root by typing "su".
10. 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)
11. Reboot.
12. ?? 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
13. ?? 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)