View source for XS Installing Software 0.5

{{translations}}
{{OLPC}}
[[Category:Software]]
[[Category:Developers]]
[[Category:SchoolServer]]

This page describes how to obtain a copy of the [[XS_Server_Software|XS school server software]], load it onto media, and install it onto a system.  A more [[XS Software Repositories|complete description of the software repositories]], [[XS_Configuration_Management|configuration information]], and [[Schoolserver_Testing|testing instructions]] are also available.

This page covers XS 0.5.x . For other releases, see [[XS_Installing_Software]]

=Downloading the System Image=
 
You can obtain 0.5.x image from [http://xs-dev.laptop.org/xs/ http://xs-dev.laptop.org/xs/]

This can be copied onto a '''CD''' or '''DVD''' using your favorite software.

You can also [[XS_Techniques_and_Configuration#Installing_from_USB|install it from USB]] (warning: unsupported!)

=Installing the Software=

'''Please read the [[XS Release Notes|release notes]] for the version you are installing.'''

The install from a '''CD''' or '''USB''' key will eventually be automatic upon booting.   While the install is currently mostly automated (not interactive), it is not performed automatically upon boot.

# Boot from the USB Key or CD-ROM 
# Press enter to start the graphical boot menu.
# Select "Install using kickstart" at the initial boot screen.
## "Install using kickstart" is the last menu item. Do not use the other "Install" options on this menu as they only install Fedora 9 without the olpc scripts. The Anaconda installer will install 537 packages. If it announces it is installing 407 packages, the olpc scripts are missing. Start again.
# '''Note: the default graphical installer can be unstable at times. You can press tab and add 'text' at the end of the line to request the text-based installer.'''
# '''If booting from a USB key please note the following!'''
## Before installing 0.5, put the ISO imaged USB key into a normal computer, and edit the ks.cfg file. You'll need to delete "--driveorder=sda" (otherwise the installer will fail, although I am uncertain of why).
## When it asks for the ks.cfg file with "cdrom:/ks.cfg" and replace with "hd:sdb1/ks.cfg" and it'll work fine.
## When it asks what the media to install from is, choose "HD" and then it'll automatically choose /dev/sdb1 and you need to type "iso" into the folder option.
# Anaconda (the Fedora installer) takes over and you will be prompted for the standard questions - these are preset to the correct defaults for the School Server configuration. You will want to set keyboard type, the time zone, and a root password for your specific system.
# When prompted to add specific packages just leave the default and click next.
# When it has finished installing, you will be prompted to reboot.  Remove the CD-ROM or USB key after power-down, but before the boot process begins.

You should now have a school server! It needs initial configuration before it starts providing services to the laptops.

== Initial Configuration ==

===Setting hostname and domain===
Login as root, with whatever password you assigned during installation.

Right after installation, you '''must'''
* Set the server domain name (the hostname is always 'schoolserver') using:
 /etc/sysconfig/olpc-scripts/domain_config example.org
* <small>(not needed in latest versions - covered by step above)</small> Set the fully qualified hostname of the machine by editing '''/etc/sysconfig/network''' as follows:
 '''HOSTNAME=schoolserver.example.org'''
** Note that the hostname is '''always''' the domain name with "schoolserver." prepended.
* Enable the ejabberd service to automatically start at boot as follows:
 chkconfig --level 345 ejabberd on
* Reboot the machine so the hostname change can take effect:
 shutdown -r now
* When the machine is back online, log in to the console as root again

===Basic ejabberd Configuration===

* Check the status of ejabberd, which should have started on boot, as follows:
 ejabberdctl status
* You should get a report indicating that the node is started and the service is running, like this (If you get an error, see [[#Troubleshooting |Troubleshooting]] for potential help)
 Node ejabberd@schoolserver is started. Status: started
 ejabberd is running
* Create an account on ejabberd for the administrator account:
 ejabberdctl register admin ''' ''schoolserver.example.org'' ''' password

===Setup Shared Roster Groups for ejabberd===

# Go to the web-based administration interface for ejabberd at <tt>http://schoolserver.example.org:5280/admin/</tt>, or <tt>http://172.18.0.1:5280/admin/</tt> (default IP address of XS)
# Login as "admin@schoolserver.example.org" with the password "password" (the administrator username and password you created in the previous section)
# Click on "Virtual Hosts", then your hostname ('''schoolserver.example.org'''), then "Shared Roster Groups". Type "Online" in the text box at the top of the screen and click '''Add New'''.
# Click on the newly created roster group called "Online" and enter "Online" for Name, "@online@" for Members, and "Online" for Displayed Groups. Click Submit. 
## Note: In XS v0.5 and v0.5.1, the @online@ directive does not function properly (see [http://dev.laptop.org/ticket/9272 defect ticket #9272]).  A workaround is given in the referenced ticket report, but it has been fixed in XS v0.5.2+.

===Optional: Enable Squid transparent proxy===

The school server is currently using Squid for web caching.  This is not enabled by default, but may easily be turned on.  As root, type:
 [http://dev.laptop.org/git?p=projects/xs-config;a=blob;f=fsroot.olpc.img/etc/sysconfig/olpc-scripts/TURN_SQUID_ON;hb=HEAD /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:
 [http://dev.laptop.org/git?p=projects/xs-config;a=blob;f=fsroot.olpc.img/etc/sysconfig/olpc-scripts/TURN_SQUID_OFF;hb=HEAD /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 <tt>/library/cache</tt> to free this disk space.

The configuration files for squid are found in <tt>/etc/squid/</tt>.  OLPC provides a custom configuration file [http://dev.laptop.org/git?p=projects/xs-config;a=blob;f=fsroot.olpc.img/etc/squid/squid.conf;hb=HEAD /etc/squid/squid-xs.conf] through the xs-config package.

=Network Configuration=

The default server setup is to connect to the Internet on the '''first wired ethernet network interface''', using IPv4 DHCP.  Laptops connect to the server over Access Points (APs) connected to the '''second wired ethernet network interface''' or via the wireless mesh using one or more [[Active Antenna]], connected through USB interfaces.  

If your XS has 2 network interfaces and you would like to reverse their (WAN, LAN) roles you can use the xs-swapnics utility. If you get your WAN via some other interface (e.g., ppp0) then you need to change the iptables NAT rule in '''/etc/sysconfig/olpc-scripts/iptables.principal'''

IPv6 is not enabled by default and not needed -- to enable external IPv6 you will have to [[XS_Configuration_Management#IPv6|configure the global address of the machine and setup an IPv6 tunnel]].

The XS runs a fully-fledged DNS server internally, therefore there is no need to enter the DNS servers from your ISP into the configuration.

==Configuring A Static IP Address==

To setup your server with a static IP address on the "first wired ethernet network interface" (eth0):
* The following is noted in '''/etc/sysconfig/network-scripts/ifcfg-eth0''':
<blockquote>
“If this is the main or only school server, then eth0 defaults to looking for a DHCP lease – if you want to set a static address, create a file called ifcfg-eth0-local in this directory – look at the example file provided under /usr/share/doc/xs-config-*/ifcfg-eth0-local.example”
</blockquote>
* 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 the authoritative DNS server for the domain name (example.org) that you have configured returns an accurate record for your hostname (schoolserver.example.org), then you do not need to do anything. However, if this is not the case (e.g. if you made the hostname up), then you will have to modify /etc/hosts, appending your hostname to the 127.0.0.1 entry, e.g.:
 127.0.0.1      localhost.localdomain localhost '''schoolserver.example.org'''
* If you can only resolve hostnames on the schoolserver but not from other computers using the schoolserver as a gateway then you may have to force use of your ISP's DNS servers. [http://www.mail-archive.com/server-devel@lists.laptop.org/msg02381.html Add your ISP's nameservers to /etc/named-xs.conf file as forwarders.] To preserve your configuration changes across upgrades, also '''cd /etc; make -f xs-config.make named-xs.conf'''.



== Access Points ==

[[Image:XS_Usage_APNormal.png|600px]]

Most access points are compatible with the XO.  For a list of ones which have been shown to work see [[Wireless Access Point Compatibility]].  Unless a single access point is being used (not recommended for more than forty to fifty laptops), a network switch of some sort will also be needed.

Make sure your AP is configured to act as an Access Point, with no added features or smarts. The AP should not be a DHCP server and should not act as a router. 

Some tips on configuring APs at [[XS_Techniques_and_Configuration]].

== Active Antennae ==
'''Important note: Active Antennae is not supported or available from OLPC at this time'''

If you have active antenna(e) to use, simply plug them in and reboot the XS. It will detect them and allocate them to mshbond0, mshbond1 and mshbond2. It should just work and XOs will see "School server mesh" when they connect to the mesh served by the XS. You may need to manually allocate different frequencies per antenna.

=More configuration options=

For more information on keeping your XS up to date, Internet content filtering, alternative networking/routing setups, and a lot of other advanced configuration topics see [[XS_Techniques_and_Configuration]].

=Upgrading from XS 0.4 or earlier=

If you are upgrading from XS 0.4 or earlier, the process is similar to a new installation, with some minor changes. In the menu shown right after booting, you should choose one of the 'Install or upgrade an existing system' options, press the Tab key, and add 'upgradeany' to the boot configuration line. After adding that line, press enter twice. 

With this extra option, Anaconda will recognise the old installation and will offer to upgrade.

Notes:

* Right after the upgrade, you '''must''' re-run the /etc/sysconfig/olpc-scripts/domain_config script with the appropriate domain name for the machine.
* The new OS may detect your network cards differently -- the roles of WAN and LAN cards may end up swapped from what they were under 0.4. If that happens, use the xs-swapnics script and reboot. 


=Upgrading from XS 0.5 or later=

If you have internet access and you wish to update just the xs-server packages you can use yum:

yum --disablerepo=* --enablerepo=olpcxs update


= See also =
* [[XS Techniques and Configuration]]
* [[XS Troubleshooting]]

[[Category:SchoolServer]]