Installing and using Syllable Server 0.3 **************************************** Copyright (c) 2007,2008 Kaj de Vos Frisian Fox IT 16 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 Using sound Running graphical programs Surfing the Web Gaming Running Genode's Nitpicker windowing system Transferring files Links2 Midnight Commander cURL INetUtils FTP BitTorrent Storing your files on the Amazon Simple Storage Service (S3) Other programs Installing additional software Burning CDs Virtualisation 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 The QuarterMaster Model/View/Controller framework Developing network applications 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. 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 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 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. Installing additional software ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Extra software is available on the Syllable website: http://web.syllable.org/Linux/downloads.html Please follow the installation instructions there. 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. 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 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 data. 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.