Installing and using Syllable Server 0.3
****************************************

Copyright (c) 2007,2008 Kaj de Vos
Frisian Fox IT

11 September 2008

http://syllable.org


Preface
=======

This is the manual I wish I would have had when I started my forays into Linux
and BSD many years ago.


Contents
========

  System requirements
  Installation
    Preparing partitions
    Installing the system files
  Configuration before starting the system
    Installing and configuring the GrUB boot loader
    Configuring the file systems table
    Setting your keyboard language
    Configuring the network
  Starting the system for the first time
    Logging in
    Logging in via the network
    Reading this manual on Syllable Server
    Logging out
    Shutting down and restarting
  Configuration of the running system
    Changing the administrator password
    Configuring the time
    Creating an extra user account
    Further configuration
  Using Syllable Server
    Using the text console
    Switching between user accounts
    Editing text files
    File management
    Installing additional software
    Using sound
    Running graphical programs
    Surfing the Web
    Gaming
    Running Genode's Nitpicker windowing system
    Virtualisation
    Burning CDs
    Downloading files
      Links2
      cURL
      INetUtils FTP
      BitTorrent
      Other programs
    Storing your files on the Amazon Simple Storage Service (S3)
  Using Syllable Server as a, well, server
    Using the OpenSSH remote log-in server
    Using the CUPS print server
    Setting up a firewall
    Running a DHCP server
    Running a domain name server (DNS)
    Running a web server
      Cheyenne
      QuarterMaster
      Apache
    Running an FTP file server
      INetUtils FTPD
      VSFTPD
    Running the SaMBa Windows-compatible file server
    Running an RSync file synchronisation server
  Programming
    "Scripting"
    Compiling programs
    Developing web applications with the QuarterMaster Model/View/Controller
framework
    Developing network applications with the REBOL/Services Service Oriented
Architecture
  Known issues


System requirements
===================

Processor: Intel 486 or better.

Memory: 16 MB or more.

  You could probably go lower; maybe to 8 MB if you configure a swap partition
before starting the system. Of course, some applications need more memory. If
you want to run the Genode windowing system, a minimum of 32 MB memory is
required. You also need more memory during installation for unpacking the
files: probably 64 MB, or virtual memory (a mounted swap partition). If you
don't have enough memory and no swap space on the target computer, for example
on an embedded machine, you could connect the disk to another computer and
install the files there.

Disk space: at least half a gigabyte.

  The installation currently takes around 370 MB, so this would leave little
space for working in. If needed, the installation size could be cut down
considerably, by removing packages and files you don't need after installation.


Installation
============

Installing Syllable Server is still a bit primitive. There is no installer
yet; it's a manual process for which you must partly use the command line.
Other than that, it's not very difficult, though. There are few steps and most
settings have sensible default configurations, so in most cases, several steps
can even be skipped. The goal of this manual, and indeed of Syllable Server
itself, is to get you up and running as soon as possible.

Use an existing Linux installation or a Linux live CD to install Syllable
Server. You need to execute most of the following actions as the root
(administrator) user. How you need to perform the first steps, before you
start Syllable Server, depends a lot on the system you are running, so consult
its documentation if you need to.)

Preparing partitions
~~~~~~~~~~~~~~~~~~~~

- Create a free partition (or select an existing one you can use). You need a
minimum space of about a half gigabyte.

- The first releases of Syllable Server will not have an official upgrade
path. If you want to upgrade across versions anyway, the easiest way is to
create a separate home partition now (which will be mounted in the /users/
directory, or possibly in one of the individual user directories in there). If
you don't consider this important, you can skip this step.

- Format the partition(s). Preferably with the ReiserFS3 format, although
Ext3FS and Ext2FS can also be used. If you want to use an existing partition
and it is already formatted with the right filesystem, you can also free it up
by deleting all files on it.

- Create a Linux swap partition if you don't already have one (or select an
existing partition and format it as Linux swap). You can also use the same
swap partition as another Linux installation, in which case you don't have to
format it again. You could skip this step and run Syllable Server without a
swap partition, but there will be no virtual memory, so it will limit the
amount of memory you can use.

Installing the system files
~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Mount the new installation partition.

- Go into a terminal and change the working directory to the root of the
mounted partition. Where this is depends on how you mounted it (and that
depends a lot on the system you are using).

- You will need 7-Zip and TAr. TAr is probably installed on your system, but
you may have to install the portable version of 7-Zip
[http://p7zip.sourceforge.net, http://www.7-zip.org]. Make sure you are the
root user and unpack Syllable Server:

  7za x -so /path/to/SyllableServer-0.3.i486.tar.7z | tar -xvp

  Provide the correct path to the archive file. If you don't have a root
account, you can prefix this command with the "sudo" command.

- If you prepared a separate home partition, mount it, and move the users/
directory from the first installation partition you mounted to the root
directory of this home partition.


Configuration before starting the system
========================================

Installing and configuring the GrUB boot loader
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Syllable uses GrUB as its boot loader, so you need to install it. A
relatively easy way to do this is with a Syllable installation or live CD (see
chapter 3 of the Syllable Desktop installation manual:
http://web.syllable.org/documentation/Install.txt). Syllable Server uses a
standard GrUB, but Syllable Desktop has its own version. If you also want to
start Syllable Desktop on the same computer with the same GrUB boot loader,
you need Syllable's version. If you only want to start Syllable Server, you
can use a GrUB version from any other system, for example a Linux live CD. You
may skip this installation step if you can use a GrUB installation from an
existing Syllable or Linux installation.

  Assuming you have a bootable CD with GrUB on it, boot it and press the C key
while in the GrUB menu. This should bring you to the GrUB command line. You
can use the "help" command here to get information about available commands.

  Keep in mind that numbering of disks and partitions is different between
GrUB and the Linux kernel of Syllable Server. GrUB starts numbering both disks
and partitions from 0 and gets its list of disks from the computer's BIOS.
Linux numbers partitions starting from 1, and maps disks with letters starting
with "a" corresponding to their place on the IDE controller cables. For
example, if a second disk is configured as the master drive on the secondary
channel of the IDE controller, the Linux kernel would call the first partition
on it /dev/hdc1, skipping the letter "b" for the slave drive on the primary
channel. If there is an extended partition on a disk, Linux numbers the
logical partitions in it from 5, while GrUB would usually number them from 4
on.

  Assuming you are installing Syllable Server on the first partition of the
first hard disk, type the following command to tell GrUB where your
installation is. Modify it accordingly if you are installing Syllable Server
somewhere else:

  root (hd0,0)

  Now you have to decide where you want to install the boot loader itself.
Normally that would be on the Master Boot Record (MBR) of the first disk. You
can install GrUB there with this command:

  setup (hd0)

  If you have more systems than just Syllable Server installed on this disk,
you may have a different boot loader already in the MBR. If you don't want to
replace that, you can make that boot loader chainload to the boot loader for
Syllable. In that case, you have to install GrUB on the partition where
Syllable is installed:

  setup (hd0,0)

  In either case, you should see GrUB install itself and embed several modules
for different file system types. If something went wrong, check the disk and
partition numbers you are using. If you installed GrUB on the Syllable
partition, you have to configure the boot loader in the MBR to chainload to
it, according to its documentation.

- Now you have to configure the GrUB boot menu. There are examples of GrUB
menu entries for Syllable Server in the boot/grub/menu.lst file. Use a text
editor to edit the menu.lst file. If you are using GrUB on a different
partition, copy these example entries to the menu.lst file you are using. The
examples are for an installation on the first partition of the first hard
disk. Again, modify them accordingly if you are installing Syllable Server
somewhere else.

  There are three more examples in case you want to start another system
installed next to Syllable Server. One is for Syllable Desktop on the first
partition, in case you are installing Syllable Server and Syllable Desktop on
the same computer. The second is for chainloading another system that has its
own boot loader, such as Windows, from the first partition. The third is a
generic example for a different Linux than Syllable Server, installed on the
second partition (assuming that some other system such as Syllable or Windows
is on the first partition). If you use these examples to start another system,
you have to make sure that they each point to the correct partitions and files.

Configuring the file systems table
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- You have to assign your partitions to mount points and specify their
parameters. Edit the etc/fstab file to do so. There are example lines that you
can uncomment for the root (main) partition, an optional swap partition, an
optional separate home partition, an optional FAT partition (if you have a
Windows partition with the FAT format, for example, or for exchanging data),
and for mounting a CD or DVD drive. If you are using mount points that are not
already in etc/fstab as examples, you need to create empty subdirectories for
them, preferably in the media/ directory. You may skip this step if you are
installing Syllable Server on the first partition on the first hard disk
formatted with the ReiserFS3 filesystem and you don't need a swap partition.

Setting your keyboard language
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- The default keyboard setting is for a United States keyboard (also used in
some other countries, such as the Netherlands). If you have a different
keyboard, you need to configure it by editing the etc/sysconfig/console file.
A few common examples are already in there.

Configuring the network
~~~~~~~~~~~~~~~~~~~~~~~

Configuring the network before the first start of Syllable Server is important
if you can only control the Syllable computer remotely through a network
connection. If you are setting up the system from the computer itself, you may
delay these steps until later and do them from within Syllable Server itself.

Syllable Server is preconfigured to use Dynamic Host Configuration Protocol
(DHCP) on the first network interface (eth0) to try to get its network
settings. If a DHCP server is running on your network, for example in the
Internet router/firewall, no configuration should be necessary. Otherwise, you
have to set a static network configuration manually. The default static
configuration is for a gateway and domain name server (DNS) at IP number
192.168.0.1, so if this happens to be your router configuration, you only have
to switch off DHCP in Syllable Server. The default static IP number for
Syllable Server is 192.168.0.9. If these defaults don't suffice, you have to
edit a few text files and replace the example values.

- The DHCP client can be switched off in the file
etc/sysconfig/network-devices/ifconfig.eth0/ipv4. Change the service type from
"dhclient" to "ipv4-static".

- The IP numbers for the network interface, the gateway and the broadcast
address can also be changed in this file. The PREFIX variable needs to contain
the number of bits needed to create the mask value for the subnet you are
using (24 in the common case of the 192.168.<n> private subnets). Only one
network interface is configured by default (eth0).

- The default name of the computer is "syllable-server". You may change this
in etc/sysconfig/network.

- The full name of the computer on the network, including the domain name, can
be set in the etc/hosts file. It is mapped there to the IP number of the
computer, so the name of the computer can be known from its IP number without
the use of a DNS server.

- The IP numbers of the DNS name server(s) can be changed in the
etc/resolv.conf file. A domain for the computer or network may also be set
there, which will be used as default domain to search for machines on the
network.


Starting the system for the first time
======================================

- Restart your computer and select Syllable Server from the GrUB menu you
installed. There are several options for different screen sizes or settings
that are needed when running in certain emulators (instead of on real
hardware). If the first option doesn't work, please choose a more appropriate
one or try them in order.

When the system starts, you will see several failure messages towards the end
of the process. This is normal. They are from network services that are not
activated or not installed. You can activate them if you want to use these
services. Future releases of Syllable Server will handle these messages more
elegantly.

- The first time Syllable Server starts, it generates security keys that
uniquely identify this computer. They are stored in the files
/etc/ssh/ssh_host_*_key.*. There are keys for the RSA and DSA encryption
algorithms, and they both consist of a pair of public and private keys. If
this installation is important, you should make backups of these keys, but the
private keys are secret, so you should always keep them protected. When the
keys are generated during the first start, a shorter fingerprint for the
public keys is also printed to the screen. It is good practice to make a note
of these fingerprints. You will be asked to compare them if you want to log in
to Syllable Server from another computer through SSH, to make sure that the
network connection is not intercepted.

Logging in
~~~~~~~~~~

- At the end of the start-up process, you should get a text prompt asking you
to log in to a user account. Just after installation, only the administrator
account exists. The log-in name of the administrator account is "root". Log in
by typing in this log-in name and the password, which is also "root" by
default.

Logging in via the network
~~~~~~~~~~~~~~~~~~~~~~~~~~

The OpenSSH program package is included in Syllable Server and its server is
started by default. This means that besides logging in from a keyboard
connected to the computer, you can also log in remotely from another computer
via a network connection. You need to have an SSH (Secure Shell) client on the
other computer, and you need to know the IP number Syllable Server has on your
network. If you configured a static network connection, you know the fixed IP
number. If you let Syllable Server get its network configuration through DHCP,
you can find the IP number it got by logging in directly on the computer first
and typing the command

  ifconfig

The IP number is listed as "inet addr" under the first network interface,
eth0. If you don't have a keyboard or monitor connected to Syllable Server,
you will have to consult your DHCP server to find out what IP number it has
given out to the Syllable computer.

To log in to Syllable Server from another computer, start an SSH client on the
other computer and give it the Syllable Server IP number and the user name
"root". If you are using the OpenSSH client, you can do this from a terminal
by typing

  ssh -l root 192.168.0.9

Substitute the proper IP number. The SSH client will warn you the first time
that it doesn't know the computer you connect to, and show you its
"fingerprint" code. This is a security key that Syllable Server generated the
first time it was started, so it is unique to the computer. Accept this
fingerprint. If you need to make sure that your network connection is not
intercepted, you can check that this is really the Syllable Server computer by
comparing the fingerprint with the one Syllable printed on its screen during
starting.

After this, you will be asked for the root password on the Syllable Server
machine, so enter "root" if you haven't changed it yet.

Reading this manual on Syllable Server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The main documentation in Syllable is available in the /Documentation/
directory. This manual is there in text format, so you kan keep reading it
during configuration of the system. You can view text files with a program
called a pager, which will let you go through documents one page at a time.
The traditional pager is called "more". Syllable includes an improved version
called "less". Don't look at us, we didn't come up with these names. :-) We
did come up with a handy alias for this command just called "m":

  m /Documentation/README-SyllableServer-0.3.txt

You don't have to type out the full name to files like this. If you type the
first few characters of a file or directory name and then press the Tab key,
the name will be completed automatically or you will get a list of multiple
possible files that match.

You can use the space bar key to go to the next page, or you can use the
cursor keys and Page Up/Down to scroll around in the document. Press the Q key
to quit the pager program.

Logging out
~~~~~~~~~~~

You can log out from a user session by typing the command

  exit

or just by pressing Control-D on an empty command line.

Shutting down and restarting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can safely restart Syllable Server by pressing the Control, Alt and Delete
keys simultaneously. If you are logged in via the network you can't do this,
so you will have to use the "reboot" command. You can turn the computer off
with the "poweroff" or "halt" commands.


Configuration of the running system
===================================

Changing the administrator password
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You should change the password of the root user account right away. Every new
Syllable installation has the same one, so someone else could log into your
administrator account. It is also important that you choose a strong password
for the administrator account: difficult to guess and not too short. Change it
with this command:

  passwd

Configuring the time
~~~~~~~~~~~~~~~~~~~~

For proper accounting of time and dates, you have to tell Syllable how your
hardware clock is configured and which timezone you are in.

- Syllable Server is set to use UTC, universal time, by default. If the
hardware clock is set to local time instead of UTC (this would probably be the
case if you are also running Windows or Syllable Desktop on the same
computer), change this setting by editing the /etc/sysconfig/clock file:

  mcedit /etc/sysconfig/clock

- To set the timezone, you have to create a symbolic link (symlink) from the
system's configuration directory (/etc/) to the file that contains the
timezone information:

  ln -sf /system/indexes/share/zoneinfo/Europe/Amsterdam /etc/localtime

  Instead of "Europe/Amsterdam", choose your own timezone from the available
files. Remember that you can use the Tab key to help with completing long file
names.

To check that the time configurations are correct, show the time and date with
the command

  date

Creating an extra user account
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You should normally not work in the root (administrator) account, except for
special system-related tasks. Logged in as the root user, you have full power
to change all files in the system, so you could easily damage it by accident.
Programs you run as the root user get the same powers, so they can have
similar destructive effects if they are defective or malicious.

The simplest form of creating an extra user account is this:

  useradd -m me

This creates a new user account called "me". The -m option creates a home
directory for it in /users/me/. To neatly capitalise your home directory name,
use this instead:

  useradd -m -d /users/Me me

(Traditional standards want the log-in name to still be in lowercase.) Now set
the password for the new account like this:

  passwd me

You can delete a user account this way:

  userdel me

Please note that this also deletes the home directory of the account and all
files in it.

Further configuration
~~~~~~~~~~~~~~~~~~~~~

As Syllable Server currently uses start and configuration scripts from Linux
From Scratch 6.3, further configuration, besides using the Syllable tools, can
often be done in a similar way as on LFS
[http://www.linuxfromscratch.org/lfs/view/stable/,
http://www.linuxfromscratch.org/blfs/view/svn/].


Using Syllable Server
=====================

Using the text console
~~~~~~~~~~~~~~~~~~~~~~

Linux has multiple virtual screens, called consoles. In its default
configuration, Syllable Server provides log-in processes on the first six of
them. You can make use of them by switching between them with the Alt-F1
through Alt-F6 function key combinations, or with Alt-Cursor Right/Left. In
each one, you can log in to a separate user session (possibly using multiple
user accounts).

The text console can be scrolled with Shift-Page Up/Down.

Switching between user accounts
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The simplest way to log in to another user account is to log out from the
account you're in, by giving the "exit" command or by pressing Control-D. You
will be presented with the log-in prompt again.

You can also switch to another user account while staying logged in to the
first, by giving the "Switch User" command and the log-in name:

  su -l me

If you were logged in to the root account, the switch will happen immediately.
If you were logged in to a regular user account, you will first be asked for
the password of the "me" user account. The -l option causes a full log-in to
the other account. Without it, the account is switched, but you stay within
the environment of the previous account.

If you enter just

  su -l

you will switch to the root account, so you can think of this as the "Super
User" command.

When you log out of the account (again, by giving the "exit" command or
pressing Control-D), you will return to the previous log-in account. In this
way, these active user sessions are nested.

You can also log in to multiple user accounts and keep an eye on all of them
by using multiple virtual consoles to log in. This way, these multiple active
user sessions exist next to each other on the same level.

Editing text files
~~~~~~~~~~~~~~~~~~

When you need to edit text files in Syllable Server, you can use the included
editor of Midnight Commander:

    mcedit /etc/fstab

There may be a delay because MCEdit causes a network connection. You can also
install other text editors such as Nano and VIm.

File management
~~~~~~~~~~~~~~~

Midnight Commander is included for comfortable and powerful file management:

  mc

Installing additional software
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Extra software is available on the Syllable website:

  http://web.syllable.org/Linux/downloads.html

Please follow the installation instructions there.

Using sound
~~~~~~~~~~~

If you have a supported sound chip, you can set the volume levels with the
program

  alsamixer

Running graphical programs
~~~~~~~~~~~~~~~~~~~~~~~~~~

Syllable Server contains basic graphical support in the forms of the DirectFB
and SDL subsystems running on the framebuffer device. You can run DirectFB and
SDL programs in graphical mode.

When a graphical program starts, it usually switches to a different virtual
console, usually number 7. You can switch back to one of the text consoles
with the Control-Alt-F1 through Control-Alt-F6 key combinations. You can
usually switch to the graphical program again with Alt-F7. Beware that this
doesn't work with some screen modes.

If a graphical program doesn't offer an option to quit, you can force it to
stop by switching to the console you started it from and pressing Control-C.

To run DirectFB programs, you have to be logged in as the root user.

Surfing the Web
~~~~~~~~~~~~~~~

Included is the Links2 web browser, which can run both in text mode:

  links syllable.org

and in graphics mode:

  linksg rebol.net

You have to be logged in as the root user for the graphical version. Press the
Q key to quit the browser.

Gaming
~~~~~~

As a special feature, this release of Syllable Server contains the Pengupop
game. :-) Of course, this is strictly for functional purposes. You can test
the network connection with it, by engaging in a multi-player game:

  pengupop

Maybe you will even be pitted against another Syllable Server tester. :-)

Running Genode's Nitpicker windowing system
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A basic windowing environment with a few demo programs is included as an
experimental feature. To start it, type

  genode

You have to be logged in as the root user for this. Genode doesn't have a quit
function, so you have to switch back to the virtual console you came from and
press Control-C to stop it.

Genode is a novel operating system framework with a unique architecture for
greatly increased security and stability. For more information, see its
documentation in

  /resources/genode/documentation/

Here's the Genode website:

  http://genode.org

Virtualisation
~~~~~~~~~~~~~~

Syllable Server includes the QEmu emulator/virtualiser. With QEmu, you can run
CD ISO images and hard disk images of other operating systems in virtual
machines, including in graphics mode.

Integrated into the Syllable Server kernel is the KQEmu Accelerator. This is a
Linux kernel module that provides a huge speed increase when virtualising
another operating system that runs on the processor you have (x86 Intel
compatible). Load the kernel module first to use this feature. You have to be
logged in as the root user to do this:

  modprobe kqemu

To run an image of a live CD, for example the Amiga Research Operating System
[http://aros.org]:

  qemu -k en-us -kernel-kqemu -cdrom AROS-i386-pc-boot.iso

The -k option is necessary to set your keyboard layout. Choose your keyboard
code from the file names in /resources/qemu/share/qemu/keymaps/. The example
is for a US English keyboard. The -kernel-kqemu option makes the kernel of the
guest operating system (AROS in this case) run faster, under virtualisation
instead of emulation. It doesn't work with all operating systems. Please
consult the documentation on the QEmu site [http://bellard.org/qemu/].

When you click on the graphics screen, the emulator gets control over the
mouse. To switch control of the mouse and keyboard back to Syllable, press the
Control and Alt keys together.

You can run an operating system installed on a hard disk image, for example
Haiku [http://factory.haiku-os.org]. Haiku doesn't seem to work with kernel
acceleration:

  qemu -k en-us -hda Haiku.img

To run Syllable Desktop, you can use the VMware image with QEmu
[http://web.syllable.org/pages/get-Syllable.html#emulate]. Strangely, Syllable
runs slightly slower with virtualisation instead of faster, so it should
better be turned off:

  qemu -k en-us -no-kqemu -std-vga -soundhw es1370 Syllable.vmdk

It is best to run Syllable Desktop with the -std-vga option, as the default
Cirrus Logic video emulation is actually slower and limits the available
screen modes. The colour palette is still limited.

If you configured the network on Syllable Server, you will automatically have
network access from within the emulated guest system. This works with the
built-in DHCP server of QEmu, irrespective of whether you configured DHCP on
Syllable Server. If you are using the VMware image of Syllable Desktop 0.6.5,
you need to activate DHCP in the network preferences. The Syllable live CDs
and newer (development build) versions of Syllable Desktop have DHCP already
enabled. Note that with this default QEmu network configuration, you can't use
the ping command and you can't access the guest system over the network from
outside the virtual machine.

Running most Linux distributions on QEmu is slow, but provides a lot of
functionality. SliTaz [http://slitaz.org/en/] and Wolvix are good choices
[http://wolvix.org]:

  qemu -k en-us -kernel-kqemu -soundhw es1370 -cdrom
slitaz-loram-cdrom-sqfs.iso

  qemu -k en-us -kernel-kqemu -soundhw es1370 -cdrom Wolvix-Cub.iso

If you want to run Syllable Server itself on QEmu, you need to install it in a
disk image. One way to do that is by using QEmu with a Linux live CD or disk
image. Pre-installed virtual machine images for Syllable Server (for older
versions at the time of writing) are available on the Syllable website:

  http://web.syllable.org/Linux/downloads.html

Once you have a disk image with Syllable Server on it, start it like this.
Syllable Server currently doesn't work with kernel acceleration on QEmu yet:

  qemu -k en-us -soundhw es1370 SyllableServer-0.3.i486.qcow2

Burning CDs
~~~~~~~~~~~

The CDRTools suite of tools is included for burning CDs. For example, you can
burn an ISO CD image file to a CD-R like this:

  cdrecord dev=/dev/hdc -eject SyllableDesktop-0.6.5.i586.iso

  This assumes that you have an ATAPI CD burner connected as master device on
the secondary cable of the IDE controller. Adjust the device name (dev=)
accordingly if your hardware is different.

Transferring files
~~~~~~~~~~~~~~~~~~

Files can be transferred in many ways. You may have mounted extra partitions
during the system configuration, which you can use to exchange files with
other systems installed on your computer. Syllable Server also includes
several programs for transferring files over the network.

Links2
------

The Links2 web browser is capable of downloading files on web pages if you
activate their links:

  links

Midnight Commander
------------------

Midnight Commander can access files remotely via several protocols:

  mc

cURL
----

cURL is a command line tool that allows you to do many network operations,
including downloading single files:

  curl -O http://web.syllable.org/pages/about.html

INetUtils FTP
-------------

A traditional FTP command shell is included for transferring files with the
FTP protocol:

  ftp ftp.example.com

When in the FTP shell environment, you can use the "help" command to get an
overview of available commands. To list the files on the remote server:

  ls

To download a file:

  get example-file

To download multiple files:

  mget *

To upload a file:

  put example-file

To exit the FTP environment:

  quit

BitTorrent
----------

You can use the Transmission program to download BitTorrent files:

  transmissioncli
http://downloads.syllable.org/Syllable/i586/systems/Desktop/0.6.5/SyllableDeskt
op-0.6.5.i586.iso.7z?torrent

Storing your files on the Amazon Simple Storage Service (S3)
------------------------------------------------------------

Amazon S3 is a paid web service for storing files, for example for backups.
S3Sync is a program for synchronising your files with your S3 account, without
re-uploading files that haven't changed. S3Cmd is an accompanying program for
setting up and maintaining your storage space on S3 and handling single files.

If you want to use S3, you have to open an account. Here is the website:

  http://s3.amazonaws.com

Then you have to generate security keys at the Amazon web services website and
enter them in Syllable by editing this configuration file:

  mcedit /etc/s3conf/s3config.yml

Keep in mind that this account information is secret and you should protect
it. Now you should be able to use the command

  s3cmd.rb

You can create multiple storage "buckets", but they need to have a unique name
among all S3 customers, so it's best to include an Internet domain name that
you own:

  s3cmd.rb createbucket my-bucket.my-domain.com

You can verify the successful creation of your bucket by listing your buckets:

  s3cmd.rb listbuckets

Now you can for example upload your whole Documents folder:

  s3sync.rb -s -r -v --progress ~/Documents my-bucket.my-domain.com:

The -s option makes this an encrypted connection (using OpenSSL), so your data
is secured during the transfer over the network. (Ensuring that they are
secured when on S3 would require you to also encrypt the files themselves.) To
get the files back, for example when you've lost them on your local computer:

  s3sync.rb -s -r -v --progress my-bucket.my-domain.com:Documents/ ~/Documents/

Be careful with the exact options you use; they are tricky. The documentation
is in

  /resources/s3sync/documentation/

Other programs
--------------

Other networking tools are available on the Syllable website:

  http://web.syllable.org/Linux/resources.html

For example, WGet is more comfortable than cURL for downloading multiple
files. NcFTP is more comfortable than the INetUtils FTP shell.


Using Syllable Server as a, well, server
========================================

Basically three servers are running on Syllable Server by default: the CUPS
print server, the OpenSSH remote log-in server and the INetD super server that
can be used to start some other servers. You can check that these servers are
active by listing the running processes:

  ps ax

Some other servers are installed, but need to be activated in their start
script in

  /resources/indexes/init/

A few more servers have start scripts included in Syllable, but are not
installed. They will be started automatically on the next system start after
they are installed.

Using the OpenSSH remote log-in server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The OpenSSH server is running on Syllable Server by default, so you can use it
immediately to log in from another computer on the network. Start an SSH
(Secure Shell) client on the other computer and give it the Syllable Server IP
number and the user name of the account on Syllable you want to log in to. If
you are using the OpenSSH client, you can do this from a terminal by typing

  ssh -l root 192.168.0.9

Substitute the proper IP number, and the user name if you don't want to log in
to the root account. The SSH client will warn you the first time that it
doesn't know the computer you connect to, and show you its "fingerprint" code.
This is a security key that Syllable Server generated the first time it was
started, so it is unique to the computer. Accept this fingerprint. If you need
to make sure that your network connection is not intercepted, you can check
that this is really the Syllable Server computer by comparing the fingerprint
with the one Syllable printed on its screen during starting.

After this, you will be asked for the user password on the Syllable Server
machine and you will be logged in to a remote command line on Syllable.
Closing this command shell in the usual way, with the "exit" command or by
pressing Control-D, will also close the remote connection.

Using the CUPS print server
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The CUPS print server is running on Syllable Server by default so you can send
print jobs to printers, either directly connected ones or remotely connected
ones on the network. See the CUPS documentation for configuring one or more
printers:

  /system/resources/cups/1.3.4/documentation/

You can try to print a test page with

  lp /system/indexes/share/cups/data/testprint.ps

Setting up a firewall
~~~~~~~~~~~~~~~~~~~~~

IPTables is included for setting up a firewall to increase security from
attacks over the network. Look for documentation starting at its website:

  http://www.netfilter.org

Running a DHCP server
~~~~~~~~~~~~~~~~~~~~~

The ISC DHCP server is included, but not activated. You can complete its
configuration by editing the file

  /etc/dhcpd.conf

The server will then automatically be started at system start-up. Note that
you will first have to configure Syllable Server to use a static IP address
for its own configuration. Also, no other DHCP server may be running at the
same time in the same subnet (for example in your router/firewall), as they
would conflict and thus block machines on your network from receiving their
network settings.

See the ISC website for documentation on their DHCP server:

  http://www.isc.org/products/DHCP/

Running a domain name server (DNS)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Initialisation scripts for the ISC BIND server are included, but the server is
not available yet for Syllable at the time of writing. Until a preproduced
package becomes available, you can compile BIND from its source code. Follow
the documentation at its website:

  http://www.isc.org/products/BIND/

Running a web server
~~~~~~~~~~~~~~~~~~~~

Syllable Server includes a flexible, capable web server called Cheyenne. It's
an Apache-class server and is written in the REBOL programming language. Also
included is the QuarterMaster web application framework, configured to run on
Cheyenne. Installing Apache or other web servers is also possible.

Cheyenne
--------

The Cheyenne web server comes fully configured with Syllable Server. You have
to be logged in as the root user to start it:

  rebol -s /resources/indexes/lib/REBOL/Cheyenne/cheyenne.r

Or use this to detach it from the interactive process, so the server runs in
the background:

  rebol -s /resources/indexes/lib/REBOL/Cheyenne/cheyenne.r &

You can check that the Cheyenne server is running with this command:

  ps ax

You can test access locally by going to the preconfigured example website from
the same computer:

  links http://localhost

You should see a website with a few tests.

You can make Cheyenne start automatically when Syllable Server starts by
editing its initialisation script and uncommenting the line that starts
Cheyenne. Remove the hash character (#) in front of the line:

  mcedit /resources/indexes/init/cheyenne

The content of the website is in

  /resources/cheyenne/lib/REBOL/Cheyenne/www/

You can add your own files there to build your own website. For more
information, see the documentation in

  /resources/cheyenne/documentation/

Here's the Cheyenne website:

  http://cheyenne-server.org

QuarterMaster
-------------

QuarterMaster is a web application framework for developing websites and
complete web applications in the REBOL programming language. Syllable Server
comes with QuarterMaster fully configured to run on the Cheyenne web server.
When you have started Cheyenne, QuarterMaster is also available. You can test
access locally by going to the preconfigured example web application from the
same computer:

  links http://localhost/hello/world

You should see a simple greeting website.

The content of the web application is in

  /resources/cheyenne/lib/REBOL/QuarterMaster/

You can add your own files there to develop your own web application. For more
information, see the documentation in

  /resources/cheyenne/documentation/introduction.html

Here's the QuarterMaster website:

  http://www.ross-gill.com/QM/

Apache
------

Initialisation scripts for the Apache web server are included, but the server
itself is not. To use it, download and install the Apache package from the
Syllable website:

  http://web.syllable.org/Linux/resources.html

You also have to install the packages for the Apache Portable Runtime (apr),
APR Utilities (apr-util), PCRE and Expat, because the Apache package depends
on them. Once Apache is installed correctly, it will be started automatically
when Syllable Server starts.

The content of the example website is in

  /resources/apache/htdocs/

You can add your own files there to build your own website. For more
information, see the documentation in

  /resources/apache/manual/

Here's the Apache website:

  http://httpd.apache.org

Running an FTP file server
~~~~~~~~~~~~~~~~~~~~~~~~~~

INetUtils FTPD
--------------

A simple FTP server is included as part of the GNU INetUtils package. You can
start it like this:

  /resources/indexes/libexec/ftpd -D

If you start it from the root (administrator) user account, it will provide
access to the home directories of all user accounts on the computer, protected
by the passwords of those accounts. Please note that this is not a
particularly secure configuration.

You can check that the ftpd server is running with this command:

  ps ax

You can test access locally by logging in to the FTP server from the same
computer:

  ftp 127.0.0.1

Provide the user name and password of the account you want to access. You will
then be in an FTP command line. You can get an overview of available commands
with:

  help

Use

  quit

to exit back to the regular local command line.

It is also possible to provide anonymous access from the FTP server to a home
directory of only one user account. To do that, start the server like this:

  /resources/indexes/libexec/ftpd -DA

The anonymous access - as FTP user "anonymous", without providing a password -
will be to the home directory of the user account that you start the server
from. For security reasons, you should not do this from the root account.

You can make the FTP server start automatically when Syllable Server starts by
editing its initialisation script and uncommenting the line that starts ftpd.
Remove the hash character (#) in front of the line:

  mcedit /resources/indexes/init/ftpd

VSFTPD
------

Initialisation scripts for the Very Secure FTP Daemon are included, but the
server is not available yet for Syllable at the time of writing. Until a
preproduced package becomes available, you can compile VSFTPD from its source
code. Follow the documentation at its website:

  http://vsftpd.beasts.org

Running the SaMBa Windows-compatible file server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Initialisation scripts for the SaMBa file server are included, but the server
itself is not. To use it, download and install the SaMBa package from the
Syllable website:

  http://web.syllable.org/Linux/resources.html

Once SaMBa is installed correctly, it will be started automatically when
Syllable Server starts. For configuration information, see the documentation in

  /resources/samba/

Here's the SaMBa website:

  http://samba.org

Running an RSync file synchronisation server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Initialisation scripts for the RSync file synchronisation server are included,
but the server itself is not. To use it, download and install the RSync
package from the Syllable website:

  http://web.syllable.org/Linux/resources.html

Once RSync is installed correctly, it will be started automatically when
Syllable Server starts. For configuration information, see the documentation in

  /resources/rsync/

Here's the RSync website:

  http://rsync.samba.org

Programming
===========

"Scripting"
~~~~~~~~~~~

If you want to do some programming, the simplest way to do that is to use what
are nowadays called scripting languages. The REBOL/Core language
[http://rebol.com/tutorials.html, http://musiclessonz.com/rebol_tutorial.html]
and its open source ORCA clone [http://trac.geekisp.com/orca/wiki] are both
included:

  rebol

  orca

In REBOL you can use the "help" or just "?" command to search for available
functions.

Starting to write programs in ORCA and REBOL is as simple as editing a text
file with this:

  #! /usr/bin/env rebol
  REBOL []
  print "Hello, world!"

If you named the text file test.r you can execute it with REBOL:

  rebol test.r

or with ORCA:

  orca test.r

Or you can change the permissions (called the mode) of the file to make it
executable:

  chmod +x test.r

and execute it directly:

  ./test.r

The Ruby language is also available:

  irb

  ruby -v

However, Ruby is not considered part of the system and is not guaranteed to be
included in all future versions of Syllable Server.

Compiling programs
~~~~~~~~~~~~~~~~~~

If you want to compile C and C++ programs, you need to install the package
with the development files (headers and static libraries) that is specific to
this Syllable system version, and the Developer's Delight package collection.
The Shell Essentials, Network Necessities and Perl Pit packs are also often
needed, and you may sometimes need extra individual software packages.

The packages and installation instructions are available on the Syllable
Server website:

  http://web.syllable.org/Linux/downloads.html

For programs that were ported from other operating systems, Syllable has its
own build system that knows how to compile many popular (and less popular)
ones. It's called Builder and is included in the Developer's Delight pack.
After you have installed that, the manual is here:

  /resources/Builder/README

Developing web applications with the QuarterMaster Model/View/Controller
framework
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~

The QuarterMaster web application framework is based on the
Model/View/Controller architecture (like Ruby on Rails and many other web
frameworks). This allows a strong separation between the implementations of
business rules (the model), presentation in a web browser (the views), and the
glue that interfaces between them (the controllers). When developing such an
application, you should try to keep the controllers as small as possible.
Back-end programmers can concentrate on the data model and web designers can
concentrate on the views.

QuarterMaster is written in the REBOL programming language and even less
complex than Ruby on Rails. If you keep your MVC architecture properly
segmented, in the future it will even be possible to add native REBOL GUIs to
your applications.

The included starter web application contains just a controller:

  /resources/cheyenne/lib/REBOL/QuarterMaster/controllers/hello.r

It's as simple as this:

  REBOL [
    title: "Hello World"
    type:  'controller
  ]

  action "world" does [render "You are running the QuarterMaster web
framework."]

The base documentation is in

  /resources/cheyenne/documentation/introduction.html

More extensive example applications are available from the QuarterMaster
website, including a user management pattern and blog and wiki applications:

  http://www.ross-gill.com/QM/
  http://www.ross-gill.com/QM/users.html
  http://www.ross-gill.com/QM/journal.html
  http://www.ross-gill.com/QM/wiki.html

Developing network applications with the REBOL/Services Service Oriented
Architecture
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~

REBOL/Services is a Service Oriented Architecture implemented in the REBOL
programming language. It consists of a server and a client library that you
can use to develop your own smart servers and programs that communicate with
eachother, both locally and over networks. The framework is in

  /resources/rebol-services/lib/REBOL/

The documentation is in

  /resources/rebol-services/documentation/

Here is an extra introduction tutorial:

  http://hmkdesign.dk/rebol/files/0657c1b595c354065fa1e2d6e91cba8b-108.html


Known issues
============

- This is a development version of Syllable Server. It's not done yet. This
release is meant to provide a basic, but useful system.

- Most notably, Syllable Server doesn't have the graphical environment from
Syllable Desktop yet.

- Binary packages are not guaranteed to be compatible across Syllable Server
versions yet. They will be in most cases, but in future releases, binary
compatibility will specifically be maintained.

- Currently, Syllable Server uses both the boot and initialisation scripts
from Linux From Scratch and its own Syllable-specific initialisation scripts.
In the future, the LFS scripts will be replaced with something more integrated
with the Syllable scripts.

- Not much attention has been paid yet to security. Only a few services are
running by default, so the risk is limited, but don't expect it to be secure
yet for your sensitive date. In an open network environment or as a multi-user
system, extra security configuration and tests should be performed.

- Start-up of Syllable Server may hang sometimes on detection of USB devices
such as memory sticks. This is a bug in Linux. Please reset the computer and
try again, or remove the USB equipment.
