XS Community Edition/0.3/Installing: Difference between revisions

From OLPC
Jump to navigation Jump to search
 
(24 intermediate revisions by 4 users not shown)
Line 1: Line 1:
==Summary==
====Prereqs====
This recipe installs XS Community Edition on an XO running OLPC OS 13.1.0 (http://wiki.laptop.org/go/Release_notes/13.1.0). It assumes that the XO will have two network connections, one for the Internet and one for client XOs.


You will need almost an 8gb hard disk in order to proceed with the installation. If the internal hard disk is less than that, you can use a sdcard to install the system, check the following instructions: http://activitycentral.com/community/news/installing-os-sd-card
This is the developer documentation for initial version of the School Server - Community Edition, Version 0.3.


During the install process, your XS server must be connected to the Internet either via its built-in Wifi adapter/ears or through a USB Ethernet Adapter. This will be the way that the server talks to the Internet.
The target audience will be experienced Linux users and admin with a strong interest in the School Server.


In order for the server to be able to talk to XOs it will need a USB ethernet adaptor connected to a separate Wifi access point (call it AP-LAN) so kids' XOs can later connect their XOs to the server. PLEASE NOTE: It is entirely possible to use an old router as an access point for the AP-LAN. BUT in order to do this, place a piece of tape over the WAN port of the router, and use the configuration mechanism of the router to turn of the internal DHCP server inside the router (The DHCP service must come from the XSCE for the system to work correctly).
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 on either XO-1.75 or commodity x86 hardware. Secondary goals will be to download a RPM and install a fully functioning School Server.


If you want an SD card for schoolserver storage, put the empty, vfat formatted SD card into the machine before starting the install process (may work if installed later -- but not tested, nor guaranteed). SD cards come from the factory vfat formatted.
==Purpose==


If you have difficulty, please [[submit_bugs | enter a bug report]].
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 needs.

==Design and architecture==

Conceptually, the school server is a collection of common network services which can be easily installed and configured as necessary. The server provides a core base of services on top of which extended service modules can be installed and modified.

==Core Services==

<ul>

<li>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.

<li>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.

<li>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.

<li>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.

<li>IDMGR : TODO fix The Identity Manager is a service which accepts requests for registration from laptops [[School_Identity_Manager]]

</ul>

==Extended Services==

<ul>

<li>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.

<li>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.

<li>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.

<li>Activity update (activity updater)

The activity updater enables teachers to easily distribute new or updated activities to their students

<li>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

</ul>

==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===

TODO new code layout.

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

<ol>

<li><code>scripts/</code>
<br>
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.

<li><code>cfg/etc/</code>
<br>
When necessary, the xs-[ServiceName] scripts installs files from under cfg/etc as necessary.

<li><code>cfg/html/top/</code>
<br>
The web based GUI is located under cfg/html/top/

</ol>

===Building===
'''$ make rpm'''

==Installing==

XS-CE 0.2 will run on XO 1.75.

TODO commodity x86.

===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 adaptors|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.
Repeat any of the download steps below if they fail due to Internet/DNS glitches.
Line 121: Line 16:
====Installing====
====Installing====
<ol>
<ol>
<li>Turn power management off within My Settings | Power. (This is not required but will make life easier as the machine will not turn off.)
<li>Ensure USB Ethernet Adapters are connected.
<li>If connecting to the Internet via WiFi, go to 'my neighborhood' and select a wireless network to connect to the Internet.
<li>Launch Terminal Activity (unhide Terminal if necessary, clicking List View in the top right of Home View).
<li>Ensure one or two USB Ethernet Adapters are connected, see above.
<Li>Change to user root by typing "su".
<li> Make sure that the USB stick you use to flash the XO is removed (this release will fail if USB is present).
<li>Make sure the date and time are set correctly. If not set it manually using "date mmddhhmmyyyy" where mm=month, dd=day, hh=hour, mm=minute, yyyy=year. This is required for yum to work correctly.
<li>Launch Terminal Activity (unhide Terminal if necessary, clicking List View in the top right of Home View).
<li>Change to user root by typing "su".
<li>Make sure the date and time are set correctly by typing "date" at the command prompt. If it is not, set it manually using "date mmddhhmmyyyy" where mm=month, dd=day, hh=hour, mm=minute, yyyy=year. This is required for yum to work correctly.
<li>Confirm your connectivity to the Internet by typing "yum repolist" (can be repeated if an error occurs.)
<li>Change directory by typing "cd /etc/yum.repos.d"
<li>Change directory by typing "cd /etc/yum.repos.d"
<li>Download the needed yum repo by typing "wget http://build.activitycentral.com/xsce.repo".
<li>Download the needed yum repo by typing "wget http://xsce.activitycentral.com/repos/xsce-release.repo".
<li>Install xs-config-xo by typing "yum -y install xs-config-xo" (downloads 17+ MB).
<li>Install xs-config-xo by typing "yum -y install xs-config-xo".
<li>(SD CARD?) if you want your XSCE server to use the storage on an SD card for content, swap file, Activity-server, put the device into the XO and run "prep-storage.sh" NOW! (Note: upgrading to 13.2.0 will break this feature -- firmware related, so reinstalling 13.1.0 will still be broken, unless firmware is also reverted)
<li>Type "bootstrap-xo" (downloads 34+ MB).
<li>Type "bootstrap-xo" to configure the XO with software necessary to install the Schoolserver.
<li>Press [Enter] to reboot.
<li>When you are prompted, Press [Enter] to reboot. (after the reboot, expect to continue in "text mode" rather than windows)
--------
<li>Launch Terminal Activity.
<li>When you are prompted, Press [Enter] to log in as root.
<li>Change to user root by typing "su".
<li>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)
<li>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.
<li>At the end the install script will declare, "XS configured; services should be active."
<li>"INSERT USB ETHERNET ADAPTER NOW" warning will appear. Insert it as instructed.<br>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 !)
<li>When you are prompted, Press [Enter] to log in as root.
<li>Remove any USB Ethernet Adapter
<li>Reboot.
<li>Type "reboot".
<li>Note that if during testing the networking seems not to be working (and you are sure that access points are set up correctly) it is possible to reconfigure the network by typing the command "xs-setup-network".
<li>Re-insert USB Ethernet Adapter.
<li>During the install, the graphical user interface (GUI) is turned off, in order to use valuable memory for server functions. If you need the GUI for setting up another access point, or other reasons, you can get the GUI back (until the next reboot) using the terminal command "init 5".
<li> Good server practice is to use "passwd" to apply a root password at the time of first install.
</ol>
</ol>

====setup====
<ol>
<li>Use "ifconfig" to determine the ip address of the XS.<br>Take note of its eth0-ip-address = WAN-ip.<br>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

<li>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)
</ol>

==Hacking==

===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.

Project Link http://www.isc.org/software/dhcp

===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.

Project Link https://www.isc.org/software/bind

===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.

Project Link http://www.netfilter.org/projects/iptables/

===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.

Project Link http://www.ejabberd.im/

===IDMGR The Identity Manager is a service which accepts requests for registration from laptops [[School_Identity_Manager]]===

Project Link http://wiki.laptop.org/go/School_Identity_Manager

===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.

Project Link http://www.apache.org/

===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.

Project Link http://www.squid-cache.org/

===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.

Project Link http://wiki.laptop.org/go/Olpc-update

===Activity update (activity updater)===

The activity updater enables teachers to easily distribute new or updated activities to their students

Project Link ???

===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

Project Link http://openvpn.net/

===OOB===

Build system

===Offline Yum===

Offline set up

Latest revision as of 23:49, 8 August 2013

Prereqs

This recipe installs XS Community Edition on an XO running OLPC OS 13.1.0 (http://wiki.laptop.org/go/Release_notes/13.1.0). It assumes that the XO will have two network connections, one for the Internet and one for client XOs.

You will need almost an 8gb hard disk in order to proceed with the installation. If the internal hard disk is less than that, you can use a sdcard to install the system, check the following instructions: http://activitycentral.com/community/news/installing-os-sd-card

During the install process, your XS server must be connected to the Internet either via its built-in Wifi adapter/ears or through a USB Ethernet Adapter. This will be the way that the server talks to the Internet.

In order for the server to be able to talk to XOs it will need a USB ethernet adaptor connected to a separate Wifi access point (call it AP-LAN) so kids' XOs can later connect their XOs to the server. PLEASE NOTE: It is entirely possible to use an old router as an access point for the AP-LAN. BUT in order to do this, place a piece of tape over the WAN port of the router, and use the configuration mechanism of the router to turn of the internal DHCP server inside the router (The DHCP service must come from the XSCE for the system to work correctly).

If you want an SD card for schoolserver storage, put the empty, vfat formatted SD card into the machine before starting the install process (may work if installed later -- but not tested, nor guaranteed). SD cards come from the factory vfat formatted.

If you have difficulty, please enter a bug report.

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

Installing

  1. Turn power management off within My Settings | Power. (This is not required but will make life easier as the machine will not turn off.)
  2. If connecting to the Internet via WiFi, go to 'my neighborhood' and select a wireless network to connect to the Internet.
  3. Ensure one or two USB Ethernet Adapters are connected, see above.
  4. Make sure that the USB stick you use to flash the XO is removed (this release will fail if USB is present).
  5. Launch Terminal Activity (unhide Terminal if necessary, clicking List View in the top right of Home View).
  6. Change to user root by typing "su".
  7. Make sure the date and time are set correctly by typing "date" at the command prompt. If it is not, set it manually using "date mmddhhmmyyyy" where mm=month, dd=day, hh=hour, mm=minute, yyyy=year. This is required for yum to work correctly.
  8. Confirm your connectivity to the Internet by typing "yum repolist" (can be repeated if an error occurs.)
  9. Change directory by typing "cd /etc/yum.repos.d"
  10. Download the needed yum repo by typing "wget http://xsce.activitycentral.com/repos/xsce-release.repo".
  11. Install xs-config-xo by typing "yum -y install xs-config-xo".
  12. (SD CARD?) if you want your XSCE server to use the storage on an SD card for content, swap file, Activity-server, put the device into the XO and run "prep-storage.sh" NOW! (Note: upgrading to 13.2.0 will break this feature -- firmware related, so reinstalling 13.1.0 will still be broken, unless firmware is also reverted)
  13. Type "bootstrap-xo" to configure the XO with software necessary to install the Schoolserver.
  14. When you are prompted, Press [Enter] to reboot. (after the reboot, expect to continue in "text mode" rather than windows)
  15. When you are prompted, Press [Enter] to log in as root.
  16. 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.
  17. At the end the install script will declare, "XS configured; services should be active."
  18. When you are prompted, Press [Enter] to log in as root.
  19. Type "reboot".
  20. Note that if during testing the networking seems not to be working (and you are sure that access points are set up correctly) it is possible to reconfigure the network by typing the command "xs-setup-network".
  21. During the install, the graphical user interface (GUI) is turned off, in order to use valuable memory for server functions. If you need the GUI for setting up another access point, or other reasons, you can get the GUI back (until the next reboot) using the terminal command "init 5".
  22. Good server practice is to use "passwd" to apply a root password at the time of first install.
Retrieved from "http://wiki.laptop.org/mediawiki/index.php?title=XS_Community_Edition/0.3/Installing&oldid=291153"