Documentation - Turtle Kevux - System Configuration
Author: Kevin Day
Description: Turtle Kevux Documentation for system configuration.
Keywords: Kevin Day, Kevux, FLL, Featureless, Linux, Library, Distribution, Open-Source, Turtle, Documentation

# System Configuration

## First Time Running Configuration

The very first time the system is run, there are some important things to do.
Most important of all is changing the root password and adding users.
If you do not change your root password immediately, your system is vulnerable to hacks.
If you do not add users, then your users will not be able to use your system unless they run as the root user.
WARNING: Running as the root user is dangerous, do so at your own lethal risk.
Changing the root user password is simple:
- Login to your root user (by default this is turtle).
- In a command-line prompt (or a terminal), run the command passwd.
- NOTE: the command passwd must not contain the "or", passwd is exactly as the command should be spelled.
- Follow the instructions and your done.

## Setting Up Usernames and Passwords

To add a user to the system, use the command line program called adduser, which requires root user access.
NOTE: In previous versions the gadduser program was supplied as a graphical user interface to adding users, but this has been removed for the time being.

To add a user, open up a terminal and switch to root access.
Simply specify the username followed by the permissions group they should belong to.
There are 3 major permissions groups: admin, power, and desktop.
The admin user has the most priviledges on the system and can gain root access, there is little this user cannot do.
The power user is a slightly weakened version of admin and the power user cannot gain root access.
The desktop user has the standard permissions needed for standard desktop usage and has no heightened priviledges beyond that.

After you begin the add user process you will be prompted for a password.
Following this, if everything went well the user will have been added to the system.
If you ever need to remove a user, the deluser program can be used and functions in an almost identical fassion.
NOTE: By default the deluser program will remove all files own by the deleted user, to prevent this from happing use the unsetup script called none.
For example, normally to delete the user BOB the command would be 'deluser BOB'.
To delete BOB without removing BOB's files, the command would be: 'deluser BOB none'.

## Setting Up the Network

Configuration Path: /etc/network/
The Files:

1. default-blacklist
2. default-firewall
3. default-device
4. example-device
5. example-device-firewall
6. example-device-wpa
7. example-wireless
8. example-bridge
9. hostname
10. hosts
11. proc_settings
12. resolution
13. protocols
14. services
15. gre0, tunl0

- File 1, default-blacklist:
  This is a list of all ip-addresses that the firewall deny access to this machine.
  A single white space (space, tab, or new line) is all that is needed to setup the addresses.
  A default whitelist can be created and used as well.
- File 2, default-firewall:
  Defines all of the firewall rules.
  The firewall syntax is broken up into terms: direction, device, action, rule, ip_list.
  All of the terms reflect iptables syntax.
  Terms must all be lowercase.
  When one of the terms direction, device, and action are set, their data is applied to all rules below that line until another term of the same type is set.
  What this means is that if a direction of "input" is specified, every rule (or ip_list) following that direction command will apply the direction of "input" until the next direction command is specified.
  This file is broken up into two different sections: first and last.
  For each ethernet device on the system there may exist a single firewall rule for that device, such as: net0123456789ab-firewall.
  The firewall wall rules are applied in this order: default-firewall's section called first, then all ethernet device firewall sections called main, and finally default-firewall's section called last
  Terminology breakdown:
  direction:
  - Valid directions are: input, output, forward, postrouting, prerouting
  - Direction specifies the direction in which the connection is coming from
  - The direction stays in effect until another direction is specified
  device:
  - Valid devices are: all, this, and the name of any device
  - all is generally used within the default-firewall and applies to all network devices on the system
  - this can only be used in a device-specific firewall file and refers to the name of the device that the specified file belongs to (for the file net0123456789ab-firewall, 'this' would refer to the device called net0123456789ab)
  - instead of 'all' or 'this', one can explicitly use the name of a device
  - The device stays in effect until another device is specified
  action:
  - Valid actions are: append, insert, and policy
  - Action specifies how a particular rule gets added to the firewall, see the iptables documentation on the details.
  - The action stays in effect until another action is specified
  rule:
  - Rules are the raw iptable commands, minus the direction, device, and action
  - The rule is applied immediately and does not carry over to any line beyond its own.
  ip_list:
  - IP Lists are the rules applied to multiple ip addresses
  - The ip_list is applied immediately and does not carry over to any line beyond its own.
  Example comparison between raw iptables command and the default-firewall syntax:
  Raw Iptables Syntax:
  `/sbin/iptables -A INPUT -i eth0 -p tcp --dport 47288 -j ACCEPT
  /sbin/iptables -A INPUT -i eth0 -p udp --sport 47288:47544 -j ACCEPT
  /sbin/iptables -A INPUT -i eth0 -p udp --dport 47288:47544 -j ACCEPT
  /sbin/iptables -A OUTPUT -o eth0 -p udp --sport 123 --dport 123 -j ACCEPT
  `
  default-firewall Syntax:
  `direction input
  device eth0
  action append
  rule -p tcp --dport 47288 -j ACCEPT
  rule -p udp --sport 47288:47544 -j ACCEPT
  rule -p udp --dport 47288:47544 -j ACCEPT
  direction output
  rule -p udp --sport 123 --dport 123 -j ACCEPT
  `
- File 3, default-device:
  This supplies some default options for all devices.
  The term 'default' can be used to specify whether or not to attempt to obtain a dynamic address (DHCP) on all standard network devices if settings file for that device does not exist.
  The terms 'search', 'nameserver_1', 'nameserver_2', and 'nameserver_3' are used to enforce a search domain or nameserver.
  The enforced search domain and nameservers will override any device specific search domain or nameserver.
- File 4, example-device:
  This file is provided as an example on how to configure a particular network device.
  The actual device filename should be the name of the device.
  The core terms: type, signal, and master.
  The term 'type' has the following options: ignore, disable, static, and dynamic.
  The term type 'ignore' means that the networking tools will not touch that network device so that a user can manually configure without having the network tools change anything.
  The term type 'disable' means that under all circumstance that device should be disabled, if at any time the device is noticed as up it will be brought down.
  The term type 'static' means that the connection is a static connection (manually defined).
  The term type 'dynamic' means that the connection is a dynamic connection (DHCP/auto defined).
  The term 'signal' specifies whether or not the signal is 'wired' or 'wireless'.
  The term 'master' specifies whether or not this device is the master route, 'yes' or 'no'. If 'yes', then the terms 'search', 'nameserver_1', 'nameserver_2', and 'nameserver_3' will be processed and this device will be setup as the default route.
  The common terms are: bond tunnel mac search nameserver_1 nameserver_2 nameserver_3 firewall.
  The term 'bond' implies that this device should be bonded between multiple network devices.
  To syntax is: bond network_device_1 network_device_2
  Where the network_device_1 and network_device_2 are the names of the network devices to bond togethor.
  The term 'tunnel' is a works in progress, this could be removed in the future.
  The term 'mac' represents the devices mac address and provides the means to change the mac address to something different.
  In particular, you can specify random instead of a valid mac address to have the mac address be randomly generated every time the device gets enabled.
  For the terms 'search', 'nameserver_1', 'nameserver_2', 'nameserver_3', see the term 'master' above.
  The term 'firewall' can be either 'on' or 'off' and represents whether or not the device-specific firewall rules will be processed when the device gets enabled.
  The device-specific firewall rules are those specified in the file nameofdevice-firewall.
  The static terms are: ip, network, prefix, broadcast, metric, gateway, gtype, gmetric, and family.
  The gtype and gmetric represent the gateway type and gateway metric.
  The wireless terms are: essid, mode, channel, rate, enc, power, nick, nwid, ap, txpower, sens, retry, rts, frag, modulation, and wpa
  The term 'wpa' can be either 'yes' or 'no' and specifies whether or not the target wireless connection is using wpa.
  File 7 contains a small example on the using wireless.
  File 8 contains a small example on the using bridges.
- File 5, example-device-firewall:
  This is an example device-specific firewall rules file, see File 2 above for details.
- File 6, example-device-wpa:
  This is the wpa settings for a specific device, see the wpa_supplicant documentation on the web for how to configure this file (search for wpa_supplicant.conf).
- File 7, example-wireless:
  This is an example wireless device, see File 4 above for details.
- File 8, example-bridge:
  This is an example bridged device, see File 4 above for details.
- File 9, hostname:
  This file contains only the hostname, no extra syntax.
  This file is the new location and name of the /etc/hostname file
- File 10, hosts:
  This file is the new location and name of the /etc/hosts file
- File 11, proc_settings:
  This file represents proc-specific network settings and get applied at system start.
  To reprocess this file, run the command ngc -r net/network_proc.
- File 12, resolution:
  This file is the new location and name of the /etc/resolv.conf file
  This file should probably not be edited directly, instead edit either the default-device or the appropriate network file and set the search, nameserver_1, nameserver_2, and nameserver_3 appropriately.
- File 13, protocols:
  This file is the new location and name of the /etc/protocols file
- File 14, services:
  This file is the new location and name of the /etc/services file
- File 15, gre0, tunl0:
  The gre0 and tunl0 are disabled by default and these files are doing the disabling.
- Controlling the Network:
  To control the firewall you will need to use the console command: firewall.
  To control network devices you will need to use the console command: network.

## Setting Up the Xorg Display

Configuration Path: /etc/X11/
The file to be configured is: /etc/X11/xorg.conf
The file /etc/X11/xorg.conf has examples and slight documentaton on how to configure the xorg display.
You can also visit http://www.x.org/ for details.
Alternatively visit http://die.net/ and search for xorg.conf.

If you need to use a different video driver, edit the /etc/X11/xorg.conf file.
Scroll to the bottom and uncomment and set the Driver to whatever you need it to be.
If you are on an OLPC, you could copy the pre-created olpc xorg configuration file:
`cd /etc/X11/
cp -v xorg.conf.olpc xorg.conf
`

## Updating the ClamAV Database

Configuration Path: /home/services/clamav/database/
You will need to open a terminal and switch to the clamav user.
Now execute the freshclam program.
NOTE: This requires network access, so this will fail if you have no working network active.

## Tweaking the Boot Process

Configuration Path: /etc/initng/
The file to be configured is: /etc/initng/runlevel/default.runlevel
The default.runlevel file specifies how the system boots, but not the order.
The order is handled by the individual dependencies.
Most of the available boot-time software have rules already created such that all you need to do is add them to the default runlevel.
To add/remove anything to the boot process, the syntax of the file requires the directory and then the filename (without the extension) on a line by itself.
If you wanted to add an SSH server to your boot process, then you would simple add target/ssh on any new line in the file.
The directory target/ can be found in the /etc/initng/ directory.
If you wish to boot using a runlevel other than default, look into the runlevel= boot option.
Once settings are changed, you can use the ngc program to start/stop and do other initng administrative commands.

## PCI and USB ID Updating

Configuration Path: /etc/
The files to be configured are: /etc/pci.ids and /etc/usb.ids
The /etc/pci.ids and /etc/usb.ids files specify vender-specific information on what any particular hardware device is.
In particular, the lspci and lsusb utilities read this information.
To update /etc/pci.ids to the latest version, download: http://pciids.sourceforge.net/v2.2/pci.ids
To update /etc/usb.ids to the latest version, download: http://www.linux-usb.org/usb.ids
Once this is done, make sure that the file permissions are correct:
`chgrp hardware_browse /etc/{pci,usb}.ids
chmod g-wx+r,o-rwx /etc/{pci,usb}.ids
`

## Using Turtle Kevux on the OLPC

The first step is to follow the instructions on the OLPC website to obtain the developer key.
This may take a while, so come back a few hours later.
There are two possible ways to boot kevux without touching the original OLPC system.
The first is to install Turtle Kevux onto a USB-Stick, whose partition should be labelled turtle-usb-olpc
The second is to install Turtle Kevux onto a MMC, whose partition should be labelled turtle-sd-olpc
If you do not know how to label or format the USB-Stick or MMC:

1. Read the partitioning tutorial
2. Make sure to properly select the correct USB-Stick or MMC.
3. Create a single partition and set the label to either turtle-usb-olpc or turtle-sd-olpc for USB-Stick and MMC respectively.

The next step is to obtain the custom compiled OLPC kernels from the kevux website.
Once you have the custom OLPC kernel and its appropriate kernel modules, put them on the system.
Lets say you downloaded the custom compiled OLPC kernel from kevux.org and it is called turtle-2.6.26.5-olpc and the maintenance kernel is called turtle-2.6.26.5-olpc-maintenance.
Lets say that you also dowloaded the appropriate kernel modules and it is called 2.6.26.5-olpc.tz2.
You will also need to extract the kernel modules to modules/
What you would do is:
`mv -v turtle-2.6.26.5-olpc boot/
ln -vs turtle-2.6.26.5-olpc boot/turtle-olpc
tar -xf 2.6.26.5-olpc.tz2 -C modules/
mv -v turtle-2.6.26.5-olpc-maintenance boot/
ln -vs turtle-2.6.26.5-olpc-maintenance boot/turtle-olpc-maintenance
`
Replace the default xorg.conf file with the the xorg.conf.olpc file so that you can get a working graphical display:
`cp -v etc/X11/xorg.conf.olpc etc/X11/xorg.conf
`
You are now ready to boot to the OLPC.
Plug your device into the OLPC and reboot the OLPC.
If all goes well, you should get a prompt where you can press a key to select the desired method of booting.
NOTE: Don't select the Squash or Squish boot methods unless you know what you are doing.
If all went well, you are sitting in a graphical environment.
You now have one more step at tweaking the system.

Open up the Applications->Settings->Appearance.

Select the Fonts tab.

Enable the Custom DPI Settings checkbox and set DPI to 140.
You should now be able to fully use OLPC.
NOTE: Use the TVCard Player called xawtv to access the camera.