Installing and using Syllable Server 0.4 **************************************** Copyright (c) 2007,2008,2010,2011 Kaj de Vos 23 January 2011 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 Configuring the file systems table Setting your keyboard language Configuring the network Installing and configuring the GrUB boot loader 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 Restarting the network Editing text files File management Using sound Running graphical programs Surfing the Web Gaming Transferring files Links2 Midnight Commander Secure SHell cURL INetUtilities FTP BitTorrent Storing your files on the Amazon Simple Storage Service (S3) Other programs Installing additional software Burning CDs Virtualisation with QEmu Using Syllable Server as a server Using the OpenSSH remote log-in server Using the CUPS print server Setting up a firewall Running a DHCP network configuration server Running a domain name server (DNS) Running a web server Cheyenne QuarterMaster Apache Running an FTP file server INetUtilities FTPD Very Secure FTP Daemon (VSFTPD) Running the SaMBa Windows-compatible file server Running an RSync file synchronisation server Programming "Scripting" REBOL, Boron & ORCA Ruby 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, many applications need more memory. You also need more memory during installation for unpacking the files: probably more than 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 drive to another computer and install the files there. (In that case, don't run the installed Syllable Server system on the temporary machine, because hardware detection may conflict with the target machine.) Storage space: around a gigabyte. The installation currently takes around 480 MB, so you probably need a gigabyte to leave some 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 quickly 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 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 file system, 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 a recent Linux system that includes the XZ-Utils package. Make sure you are the root user and unpack Syllable Server: xzcat /path/to/SyllableServer-0.4.i486.tar.xz | sudo tar -xp Provide the correct path to the archive file. It is essential that you do this as the root (administrative) user. If you can't log in to the root account, use the mentioned "sudo" command. If you are logged in to the super user account, you may leave this out. It's a large archive, so unpacking will take a fair amount of time. Please be patient. If you don't have enough working memory on the system you use for installation (64 MB or less), and no swap partition, but you do have enough disk space, you can unpack the file in two steps to use less memory. First unpack the archive - maybe on another system - but be aware that the result is large: unxz /path/to/SyllableServer-0.4.i486.tar.xz Then unpack the tarball in the target location: sudo tar -xpf /path/to/SyllableServer-0.4.i486.tar - If you prepared a separate home partition, mount it. Then move the users/ directory from the first installation partition you mounted to the root directory of this home partition. Configuration before starting the system ======================================== Configuring the filesystems 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 file system and you don't need a swap partition. Setting your keyboard language ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - The default keyboard setting is for a United States keyboard layout (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 for 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. Installing and configuring the GrUB boot loader ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Syllable uses GrUB as its boot loader to start the system, so you need to install and configure it. GrUB has a startup menu that you have to configure. 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. Modify them accordingly if you are installing Syllable Server somewhere else. There are 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. Another is for chainloading another system that has its own boot loader, such as Windows, from the first partition. There's also 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. - Now you have to install the boot loader. 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/Desktop/Installation.html). Syllable Server can be started from a standard GrUB, but Syllable Desktop needs 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, either from Syllable Desktop or Syllable Server. 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. The following instructions apply to GrUB 1 (0.x versions). GrUB 2 can also be used, but the instructions would be partly different and you'd have to consult the GrUB manual. Other boot loaders can also be used, but then, too, you would have to consult their manuals. 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. Be aware 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. Again, modify this accordingly if you are installing Syllable Server somewhere else than the first partition of the first hard disk: setup (hd0,0) In either case, you should see GrUB install itself and embed several modules for different filesystem types. Review the messages, and 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. 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, which both have 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 as a semi-regular user account. (There are other accounts used for system purposes.) The log-in name of this account is just "administrator". Log in by typing in this log-in name and once asked the password, which is "OpenSesame" by default. Please note that capitalisation is significant. Note that there is also a privileged system account. Most Linux and Unix systems traditionally call this "root", but Syllable calls it "system" (which should be more intuitively understandable for most people). On many systems, you're supposed to log into this account to perform administrator tasks, but this is insecure and dangerous, because there are no limits imposed on what this account can do. On Syllable, log-in to the "system" account is disabled, and you're supposed to use the "administrator" account for administrative tasks, where you're shielded from accidentally disrupting the system. 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 ip address or just ip a The IP number is listed as "inet" under the first physical network interface, eth0. If you don't have a keyboard and monitor connected to Syllable Server, you will have to consult your DHCP server to find out what IP number it gave 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 "administrator". If you are using the OpenSSH client, you can do this from a command line by typing ssh -l administrator 192.168.0.9 Substitute the proper IP number. The first time, the SSH client will warn you 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 its first start. After this, you will be asked for the administrator password on the Syllable Server machine, so enter "OpenSesame" 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.4.txt You don't have to type out the full name and path to files. 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 press 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. Although storage media are stopped orderly this way, it is advisable to quit any running programs and to log out from any user sessions before restarting or shutting down, to give them the chance to finish orderly as well. For example, the history of the commands you used is not kept properly if the session is interrupted. Configuration of the running system =================================== Changing the administrator password ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If this installation is important, you should change the password of the administrator user account right away. Every new Syllable installation has the same one, so someone else could log into your 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 Accessing your administrator privileges ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Because the administrator account is basically a regular user account, it is normally not allowed to do the things that the system account can do. To do many administrative tasks that require higher privileges, the administrator account enables you to execute commands as the unlimited "system" account. You can do this by prefixing a command with the "sudo" command, which means to "Switch User" account or do as "Super User", or on Syllable, "System User". For example, try the command that reminds you of your user account name: whoami And then with super user privileges: sudo whoami This separation of the system and administrator accounts serves to improve security, but Syllable also aims to be comfortable, so it does not require you to enter your password again to use the sudo command. Because this command will be needed a lot, there is also a shorter alias for it, just "s": s whoami Configuring the time ~~~~~~~~~~~~~~~~~~~~ For proper accounting of time and dates, you have to tell Syllable how your hardware clock is configured and which time zone you are in. - Syllable Server is set to use UTC, universal time, by default (equivalent to GMT, Greenwich Mean Time). If the hardware clock is set to local time instead of UTC (this would probably be the case if you are also running Windows on the same computer), change this setting by editing the /etc/sysconfig/clock file. The system configuration files are owned by the system user, so this must be done via the sudo/s command: s mcedit /etc/sysconfig/clock - To set the time zone, you have to create a symbolic link (symlink) from the system's settings directory (/etc/) to the file that contains the timezone information: s ln -sf /system/index/data/zoneinfo/Europe/Amsterdam /etc/localtime Instead of "Europe/Amsterdam", choose your own time zone from the available files. Remember that you can use the Tab key to help with completing long file names. You also need to enter the time zone at the top of the file /etc/profile by uncommenting the line that sets the TZ environment variable: s mcedit /etc/profile To check that the time settings are correct, show the time and date with the command date Be aware that a system has a hardware clock and a software clock. Syllable Server sets the hardware clock from the software clock when it shuts down (or restarts). If you have changed the UTC setting, this will change the interpretation of the software clock, such that it may result in a shift in the hardware clock. On the next system start, the software clock is set from the hardware clock and you can notice the difference. This can be used to change the hardware clock. If you change the software clock, the hardware clock will be set accordingly when the system shuts down: s date -s Creating an extra user account ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You should normally not work in the administrator account, except for special system-related tasks. Even though the administrator account is separated from the privileged system account, logged in as the administrator user you still have more power over the system than regular user activities require. The administrator has easy access to the system account, and the system user has the power to change all files in the system, so you could easily damage it by accident. Programs that you run as the administrator user get the same powers, so they can have similar destructive effects if they are defective or malicious. Further, someone who has access to your computer could do the same things when you're not watching. The simplest form of creating an extra user account is this: s useradd -m someone This creates a new user account called "someone". The -m option creates a home directory for it in /users/someone/. To neatly capitalise your home directory name, use this instead: s useradd -m -d /users/Someone someone (Traditional standards want the log-in name to still be in lowercase.) Now set the password for the new account like this: s passwd someone You can delete a user account this way: s userdel someone 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.5, 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 (using the same or 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 someone You will be asked for the password of the target 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 are logged in to an account where you have the privilege to use the system account through the sudo command, such as the administrator account, you can make the switch without providing the password for the target account: s su -l someone 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. Restarting the network ~~~~~~~~~~~~~~~~~~~~~~ Sometimes you may need to restart the network, for example after you have changed its configuration, or when it fails to get an IP number from the DHCP server during start-up. You can restart it with the network initialisation script: s /etc/rc.d/init.d/network restart (Please note that this currently doesn't shut down running instances of network servers started through Syllable's own start scripts, such as the Cheyenne web server.) Editing text files ~~~~~~~~~~~~~~~~~~ When you need to edit text files in Syllable Server, you can use the included editor of Midnight Commander: mcedit example-file (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 ~~~~~~~~~~~~~~~ Apart from using the command line for manipulating files, Midnight Commander is included for comfortable and powerful file management in a semi-graphical interface: mc Using sound ~~~~~~~~~~~ If you have a supported sound device, 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 back 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 use DirectFB programs, you have to run them as the system user, so you will have to start them through the sudo/s command. Surfing the Web ~~~~~~~~~~~~~~~ Included is the Links2 web browser, which can run both in text mode: links syllable.org and in graphics mode: s linksg rebol.net You have to run the graphical version as the system user. 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: s pengupop Maybe you will even be pitted against another Syllable Server tester. :-) 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 if you have multiple installed on your computer. Syllable also includes several programs for transferring files over the network. Links2 ------ The Links2 web browser is capable of downloading files on web pages when you activate their links: links Midnight Commander ------------------ Midnight Commander can access files remotely through several protocols: mc Secure SHell ------------ The safest way to transfer files over a network is with SSH, the Secure SHell protocol. This encrypts all your communication, including your password, so it can be used over untrusted networks such as the public Internet. With the OpenSSH set of tools, you can use this from the command line. An SSH server needs to be running on the remote machine. This is the case with Syllable Server, so you can log in to it from another machine or transfer files safely. For example, you could copy a single file from the home directory of the "administrator" user on a Syllable Server machine onto another machine that also has SSH, such as Syllable Desktop: scp administrator@192.168.0.9:example-file . This copies the remote example-file to your local current directory. If you have created extra user accounts, you can exchange "administrator" for another account. You can modify the IP number if the server has a different one, or use a network domain name if the server has one. The first time you access a particular server through SSH, you will be asked to confirm the server's credentials. Do this only if you trust them. The scp command works much like the regular cp command to copy files, so you can copy a whole directory tree recursively like this: scp -r administrator@192.168.0.9:example-folder . Transferring files also works in the other direction with SSH, so you can upload a local file to the remote server like this: scp example-file administrator@192.168.0.9:path/to/destination cURL ---- cURL is a command line tool that allows you to do many network operations, including downloading single files: curl -O web.syllable.org/pages/about.html INetUtilities FTP ----------------- A traditional FTP command line environment 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. You have to download the torrent definition file first and feed that to Transmission: curl -O downloads.syllable.org/Syllable/i586/systems/Desktop/0.6.7/SyllableDesktop-0.6. 7.i586.iso.7z?torrent transmissioncli SyllableDesktop-0.6.7.i586.iso.7z\?torrent After Transmission finishes downloading, it keeps uploading the download to other downloaders. You can stop Transmission by pressing Control-C. 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: s mcedit /etc/s3conf/s3config.yml Keep in mind that this account information is secret and you should protect it. For example, you should set the access permissions for this configuration file to a setting that is secure in your environment. 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 INetUtilities 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. If you want to use some of the extra programs via the sudo/s command, it may be necessary to run s ldconfig after installation. In most cases, this is not needed. 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: s cdrecord SyllableDesktop-0.6.7.i586.iso This searches for your burner device automatically. You can also specify a specific device, for example assuming 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. To also eject the disk when done: s cdrecord dev=/dev/hdc -eject SyllableDesktop-0.6.7.i586.iso Virtualisation with QEmu ~~~~~~~~~~~~~~~~~~~~~~~~ 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), by using virtualisation instead of emulation. To run an image of a live CD, for example the Amiga Research Operating System [http://aros.org]: s qemu -k en-us -kernel-kqemu -cdrom AROS-pc-i386-boot.iso The -k option is necessary to set your keyboard layout. Choose your keyboard code from the file names in /resources/QEmulator/data/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, using the accelerator. It doesn't work with all operating systems. Please consult the documentation on the QEmu site [http://qemu.org]. 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. To run Syllable Desktop, you can use the VMware image with QEmu [http://web.syllable.org/pages/get-Syllable.html#emulate]. Oddly, Syllable Desktop runs slightly slower with virtualisation instead of faster, so it should better be turned off: s 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 networking 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. 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. Those things require extra configuration. Running most Linux distributions on QEmu is slow, but provides a lot of functionality. Wolvix [http://wolvix.org] and SliTaz are good choices [http://slitaz.org]: s qemu -k en-us -kernel-kqemu -soundhw es1370 -cdrom wolvix-cub.iso s qemu -k en-us -kernel-kqemu -soundhw es1370 -cdrom slitaz-loram-cdrom.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: s qemu -k en-us -soundhw es1370 SyllableServer-0.4.i486.qcow2 Using Syllable Server as a server ================================= Besides a few server processes that the system uses, basically three servers (also known as daemons) are running on Syllable Server by default: the CUPS print server (cupsd), the OpenSSH remote log-in server (sshd) 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/index/tasks/start/ 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 (or network name if you have set up naming on your network) 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 command line by typing ssh -l administrator 192.168.0.9 Substitute the proper IP number, and the user name if you don't want to log in to the administrator account. The first time, the SSH client will warn you 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 its first start. 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/index/cups/documentation/ You can try to print a test page with lp /system/index/data/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 network configuration 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), because 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/software/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/software/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. It needs to be started under the system account: s rebol -s /resources/index/framework/REBOL/Cheyenne/cheyenne.r You'll probably want to do it this way to detach it from the interactive process, so the server runs in the background: s rebol -s /resources/index/framework/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 launch automatically when Syllable Server starts by editing its start script and uncommenting the line that runs Cheyenne. Remove the hash character (#) in front of the line: s mcedit /resources/index/tasks/start/web-server.sh The content of the website is in /resources/Cheyenne/framework/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/ The configuration of the web server can be edited in this file: s mcedit /resources/Cheyenne/framework/REBOL/Cheyenne/httpd.cfg If needed, you can make Cheyenne reload its configuration after you have changed it without restarting the web server. First, use the ps command to find the process ID of the main Cheyenne process. There are several running Cheyenne and UniServe processes that belong to the web server. Take the ID of the first Cheyenne process and use it to send a reload signal: s kill -s HUP 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/framework/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/ See further "The QuarterMaster Model/View/Controller framework" in the section "Developing web applications". 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/documentation/manual/ Here's the Apache website: http://httpd.apache.org Running an FTP file server ~~~~~~~~~~~~~~~~~~~~~~~~~~ INetUtilities FTPD ------------------ A simple FTP server is included as part of the GNU INetUtils package. You can start it like this: s /resources/index/framework/executables/ftpd -D If you start it under the system account like this, 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 localhost 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/index/framework/executables/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 under the system account. You can make the FTP server launch automatically when Syllable Server starts by editing its start script and uncommenting the line that runs ftpd. Remove the hash character (#) in front of the line: s mcedit /resources/index/tasks/start/FTP-file-server.sh Very Secure FTP Daemon (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/RSynchronise/ Here's the RSync website: http://rsync.samba.org Programming =========== "Scripting" ~~~~~~~~~~~ REBOL, Boron & ORCA ------------------- 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] and its open source clones Boron [http://urlan.sourceforge.net] and its predecessor ORCA are all included: rebol boron orca In REBOL you can use the "help" or just "?" command to search for available functions. Use the command "q" to quit the language interpreter environments. Starting to write programs in REBOL and Boron 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 If you leave out the REBOL header, like this: #! /usr/bin/env boron print "Hello, world!" you can execute it with Boron: boron test.b 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 Ruby ---- The Ruby language is also available: ruby -v irb However, Ruby is not considered part of the system and is not guaranteed to be included in all future versions of Syllable Server. Press Control-D to leave the Ruby interpreter environment again. Compiling programs ~~~~~~~~~~~~~~~~~~ If you want to compile C and C++ programs, you need to install both 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 other, individual software packages. The packages and installation instructions are available on the Syllable Server website: http://web.syllable.org/Linux/downloads.html Syllable has its own software build system that knows how to compile many popular (and less popular) program packages that were ported from other operating systems. 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 Cheyenne WebSockets framework --------------------------------- The Cheyenne web server includes a programming framework for easily developing web applications that make use of the new WebSocket communication framework that is introduced in the HTML 5 standards. As such, it allows advanced new web applications, but if you only support WebSocket communication, they will need a recent web browser to be used. 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/framework/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 each other, both locally and over networks. The framework is in /resources/REBOL-Services/framework/REBOL/Services/ The documentation is in /resources/REBOL-Services/documentation/ 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 software 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 start 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. - Only limited attention has been paid to security so far. Access to the system (root) account is protected, and just 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. - Sound has been observed not to work on an ESS Maestro 2 sound chip. - DirectFB has been observed to hang on start-up of a DirectFB program (Links) with an Nvidia GeForce 2 video chip.