% asplinux 8.0 User Guide % Copyright (C) 2008-2008 Douglas Jerome % % This document is derived from the asplinux 7.0 User Guide written % by Pascal Schmidt; most text copyright (C) Pascal Schmidt. % $RCSfile:$ % $Revision:$ % $Date:$ % ***************************************************************************** % Preamble % ***************************************************************************** \documentclass[12pt]{article} % Use some packages % \usepackage[headings]{fullpage} \usepackage{url,fancyhdr} \ifx\pdfoutput\undefined \usepackage[dvips]{color} \else \usepackage[pdftex]{color} \fi \usepackage{listings} % Setup the page characteristics. % \pagestyle{fancy} \setlength\topmargin{-0.50in} \setlength\textheight{8.75in} \parindent=0pt \parskip=12pt % Setuup header and footer using the fancyhdr package. % \renewcommand\headrulewidth{0.4pt} \fancyhead{} \fancyhead[R]{\thepage} \fancyhead[L]{\nouppercase{\leftmark}} \renewcommand\footrulewidth{0.4pt} \fancyfoot{} \fancyfoot[R]{\thepage} \fancyfoot[L]{asplinux 8.0} \footskip=48pt % Sans serif typeface is the default. % \renewcommand\familydefault{\sfdefault} % These colors are intended for listing use. % \definecolor{lightblue}{rgb}{0.80,0.80,1.00} \definecolor{lightgray}{rgb}{0.90,0.90,0.90} \definecolor{darkgray}{rgb}{0.40,0.40,0.40} % Setup listings package. % \lstset{language=ksh} % Doesn't know bash nor sh. \lstset{rulesepcolor=\color{darkgray}} \lstset{aboveskip=12pt} \lstset{belowskip=0pt} \lstset{basicstyle=\ttfamily\small} \title{asplinux Version 8.0\\User Guide} \author{Douglas Jerome\\(Based on Previous Work by Pascal Schmidt)} % ***************************************************************************** % Body % ***************************************************************************** \begin{document} \maketitle \thispagestyle{empty} \newpage \tableofcontents \newpage % ***************************************************************************** % % ***************************************************************************** \section{Introduction} This section gives an overview of asplinux, what it is and is not, and what it it might be used for. \subsection{What is asplinux?} asplinux is a small, minimal Linux distribution. It is available as a bootable CD-ROM image and an entire source distribution that builds the bootable CD-ROM image. asplinux tries to have as much as possible in as little space as possible. It provides multi-tasking, multi-user Linux with networking capabilities in 8 megabytes of disk space. It is prepared for Internet access by Ethernet and dial-up via modem or ISDN. A text-based web browser and command-line remote login secure client and server are a part of asplinux. asplinux can be manually installed onto a hard disk or USB flash drive, or by using an installer script that is included on the CD-ROM. Both installation methods, automated script or manual, can be done by asplinux or a different Linux system. However, asplinux can provide only the lilo boot loader. The asplinux file system, excluding the Linux kernel, is 8 MB in size. Using an installer script provided on the bootable CD-ROM, a Linux kernel of about 2.2 MB will also be installed. This makes a minimum workable size of about 12 MB for a hard disk partition to install asplinux on. asplinux includes a package management script capable of installing, removing and querying software packages and their files. This is useful for adapting asplinux to specific needs. \subsection{What is asplinux not?} asplinux is not a typical Linux distribution; it does not have a graphical user interface, software development tools, document preparation and printing tools, databases nor network services such as BIND, News Server, Mail Transfer Agents and file servers. \subsection{What can asplinux be used for?} asplinux is useful on computers which are considered obsolete, such as 486SX PC; it is for people who want to have a minimal Linux distribution to run when little space is available or needed. On a modern computer, one interesting use for asplinux is as a tool for putting together a more complete Linux system. With its small size asplinux boots quickly from CR-ROM and USB flash drives; it has been used as a system fix/repair tool, and is a good basis for a rescue or installation CD-ROM. asplinux provides a working Linux environment with its boot image, and custom task-specific scripts can mount other parts of the file system from its boot USB flash drive or CD-ROM to provide a larger system. Some users may want to use the asplinux file system and configure and build their own Linux kernel. asplinux can serve as a rough prototype of a larger system, since it uses the same C library, glibc, as full Linux systems, compiling programs on a different Linux computer and copying them over to the asplinux file system can result in working programs. {\bf This is not a supported feature.} Programs compiled outside the normal asplinux build process may require libraries not present in asplinux. Worse, they may be compiled on a computer with different Linux kernel capabilities and make system calls not present in asplinux. Note: asplinux is for people who have Linux experience; it is not for beginners, unless you want to learn how a Linux system works underneath the Graphical User Interfaces. You must be able to use the interactive shell command-line, and it helps to know your way around Linux system. Most of the programs are smaller versions of the common Unix utilities. \subsection{Licenses} The software packages that are part of asplinux are licensed under a number of different open source licenses, as listed below. The initialization and system service scripts developed by the asplinux project are licensed under the GNU General Public License; a copy of this license is included in the file \url{COPYING}. \begin{center} \begin{tabular}{l|l|l} Package & Version & License \\ \hline bash & 3.2 & GPL \\ busybox & 1.13.1 & GPL \\ dropbear & 0.51 & MIT \\ e2fsprogs & 1.41.3 & GPL \\ glibc & 2.7 & LGPL \\ iptables & 1.4.2 & GPL \\ isdn4k-utils & 3.2p1 & GPL \\ lilo & 22.8 & BSD \\ ncurses & 5.6 & MIT \\ ppp & 2.4.4 & BSD \\ retawq & 0.2.6c & GPL \\ \end{tabular} \end{center} For more information on the licenses, please visit the \url{opensource.org} website. \section{Starting with asplinux} This section has a general overview of the asplinux download image and also describes the system hardware requirements for using asplinux, where to download asplinux from, what to download and how to use the downloaded images. asplinux has three basic parts: a boot loader, a Linux kernel, and a root file system. All three of these are in the CD-ROM image; the CD-ROM image can be burned onto a blank CD-ROM disc and then booted. When booted, the root file system from the CD-ROM is decompressed and becomes a read/write root file system in a RAM disk in memory. Note that changes to any of the files while running asplinux are lost, as they are in a RAM disk. Booting the asplinux CD-ROM is described in section \ref{bootcd}. Installing asplinux from the bootable CD-ROM onto a disk is described in section \ref{installation}. Installation makes a system different from the bootable CD-ROM; the installed asplinux has a read/write root file system directly on hard disk or flash disk, not in a RAM disk. The advantage of an installed asplinux system over the RAM disk system is that file changes are not lost. asplinux can be put onto a flash disk, such as a USB drive, which can be made bootable. This copies the RAM disk boot method to the flash disk; when the flash disk is booted, the root file system from the flash disk is decompressed and becomes a read/write root file system in a RAM disk in memory. Changes to files are lost when the system shuts down. The process of putting asplinux onto a flash disk described in more detail in section \ref{bootflash}. The asplinux root file system is a file on the CD-ROM; it can be copied and used with a different custom kernel, one that you make, and put onto other media, or file system image, with your boot loader of choice. This process is beyond the scope of this document, but the requirements for a asplinux custom kernel are described in more detail in section \ref{customkernel}. \subsection{System Requirements} asplinux is intended to eventually run on several different CPU architectures; however, version 8 directly supports only the Linux i386 CPU architecture, this is the x86 architecture for PC compatible computers, specifically the i486 CPU instruction set. {\bf CPU and Computer}\\ asplinux 8 requires i486SX or newer processor in a PC compatible computer. It will not work with the i386 CPU; the glibc version in asplinux uses CPU instructions the i386 CPU does not have. Any x86 compatible CPU supporting i486, and upward compatible, that is in a {\it PC compatible} computer should work. {\bf Memory}\\ asplinux uses an 8 MB RAM disk when booted from CD-ROM, so at least 24 MB of memory are required. The kernel on the CD-ROM is fairly large; it supports a broad range of hardware. Using a custom kernel supporting only hardware for a particular computer, a asplinux system may require as little as 16 MB of memory. If the file system is installed onto a read/write disk drive, spinning or flash, and a custom kernel is used, asplinux will run within 8 MB of RAM. \subsubsection{Custom Kernel Requirements} \label{customkernel} The asplinux root file system is an 8 MB ext2 file system; the file system image is compressed and resides in the CD-ROM image. After burning the CD-ROM image to a blank CD-ROM disc, or mounting the CD-ROM image via loop device, you can find the compressed root file system; it is \url{isolinux/filesys.gz}. This root file system can be used with a different custom kernel. All of asplinux 8 is built with {\bf Linux 2.6.20} header files. Linux kernels are not backwards-compatible; software using the capabilities of a given kernel version cannot be {\it expected} to work with any previous kernel version. Using an old kernel cannot be supported in any way. With that described, with the small number of packages in the asplinux system, asplinux is known to work to some extent with any Linux kernel from 2.4.4 upwards. The asplinux firewall script does not work with a 2.2.x kernel. The kernel you use needs to support all the hardware you want to use, plus some additional requirements for asplinux itself. A kernel used for running asplinux needs to have {\bf ramdisk} support, {\bf initial ramdisk} support, and a default ramdisk size of at least {\bf 8192}. Note the kernel configuration has a default ramdisk size of 4096, which is not big enough. If you want to use the basic firewall script of asplinux, your kernel also needs iptables support with the {\bf netlink} interface. If you want to use the telnet server in asplinux, your kernel will need to have Unix98 pseudo terminal support and support for the {\bf devpts} file system. A asplinux kernel needs to support {\bf ext2 file systems}. \subsection{File Downloads} The main asplinux web site is accessed at \url{http://asplinux.org/}. The web site is hosted at \url{http://www.asplinux.com/}, which is very much appreciated. The asplinux web site has a Download page that has several files available for downloading. {\bf Bootable CD-ROM Image}\\ The bootable CD-ROM ISO image for the i486-PC build of asplinux is intended to be booted on any PC that can boot from CD-ROM. This file is an image of an El Torito bootable CD-ROM ISO 9660 file system with the Rock Ridge extension. El Torito enables CD-ROM to be bootable on PC. The Rock Ridge extension adds longer file names to the ISO 9660 file system capabilities. {\bf Source Distribution}\\ The asplinux distribution build system, including its source code packages, is available; it has a file \url{How_To_Build_asplinux.txt} that describes the build process. {\bf Binary Run-time Packages}\\ The packages that make up the entire CD-ROM asplinux run-time are available. Packages are available in the case any were removed from a asplinux system and there is a desire or need to reinstall the removed packages. After downloading, a package is installed with \url{pacman}, the asplinux package manager. {\bf Previous Versions}\\ At least one previous asplinux version should be available. \subsection{Booting the CD-ROM Image} \label{bootcd} This version of asplinux is intended to boot on any x86 PC that can boot from a CD-ROM drive. It can be used as a rescue system or simply for trying asplinux. Download the CD-ROM ISO image file and burn it onto a blank CD-ROM disc, as an ISO image. Then boot put the disc into a PC CD-ROM drive and boot the PC; asplinux should boot up automatically. A computer's BIOS setup may not be set up to allow booting from CD-ROM; in that case you need to go into the BIOS setup screen(s) and make changes that allow the computer to boot from CD-ROM. If the computer has an old BIOS that is not able to boot from a CD-ROM device, there is software called {\it Smart Boot Manager} that may help. It can currently be found at: \url{http://btmgr.sourceforge.net/about.html} Once asplinux has booted, and you see the login prompt, login as user name "root", the administrator account, password "password". Read the rest of this user guide for pointers about what you can do with the system. After booting, the program \url{/sbin/asplinux-installer} can be used to install asplinux from the CD-ROM onto a hard disk or flash disk, such as a USB drive. \subsection{Making a Bootable Flash or USB Disk from the asplinux CD-ROM} \label{bootflash} Making a bootable flash or USB disk from the asplinux CD-ROM makes a asplinux system different from an {\it installed} system; when the flash disk is booted, the root file system from the flash disk is decompressed and becomes a read/write root file system in a RAM disk in memory. Changes to files are lost when the system shuts down. A Linux system, either asplinux or some other Linux system, can by used to make a asplinux bootable flash disk. The asplinux CD-ROM or the CD-ROM image file or even the kernel and file system image files removed from the CD-ROM and in a directory somewhere can be used as the source, depending upon which Linux system is to be used. The complete process is described in a text file, \url{Flash_Disk_Howto.txt}, in the asplinux CD-ROM image; you can find it the root (top-level) directory of the CD-ROM. Also in the root directory of the CD-ROM is a shell script that automates the process of transferring the asplinux system from the CD-ROM onto a flash disk and making the flash disk bootable. The \url{Flash_Disk_Howto.txt} file has a short description of using this shell script. This shell script depends upon both the CD-ROM and flash disk being mounted; the CD-ROM should be mounted with option {\tt -t iso9660} to specify the correct file system type, and USB disks are usually FAT32 and those should be mounted with option {\tt -t vfat} to specify the correct file system type. \section{Installation Guide} \label{installation} This section describes how to customize and install asplinux. \subsection{Installing from CD-ROM} WARNING: Running the installer can easily destroy all operating systems, and anything else, currently present on the target machine. Proceed with caution and backup all {\it important} data before installing asplinux. Really. To install asplinux onto disk from the bootable CD-ROM, you first need to burn the asplinux CD-ROM ISO image onto a blank CD-ROM disc and boot into it as described in the previous section \ref{bootcd}. Once logged in as the "root" user, you can start the installation. You need to know three things to run the installer: what your CD-ROM device is, which disk partition you want to install asplinux and where you want to put the boot loader. If you don't know the answers to those three questions after reading the following instructions, the safe bet would be {\bf not} to proceed with installation; the asplinux installer is not yet automated or user-friendly enough for you. \subsubsection{Source CD-ROM Device} The CD-ROM device depends on whether the drive is an IDE or SATA device. If your system uses IDE, the following device names are possible: \begin{center} \begin{tabular}{l|l} Device Name & Description \\ \hline /dev/hda & Master Device on First IDE Controller \\ /dev/hdb & Slave Device on First IDE Controller \\ /dev/hdc & Master Device on Second IDE Controller \\ /dev/hdd & Slave Device on Second IDE Controller \\ \end{tabular} \end{center} Among the above, /dev/hda is not likely to be your CD-ROM device unless you are using a modern laptop. A more likely possibility is /dev/hdc. /dev/hda normally is the device name of your hard disk, but a modern computer will use SATA for the hard drive, but many with IDE CD-ROM drive. If your system uses SATA (Serial ATA), use this table: \begin{center} \begin{tabular}{l|l} Device Name & Description \\ \hline /dev/scd0 & First SATA CD-ROM Device \\ /dev/scd1 & Second SATA CD-ROM Device \\ /dev/scd2 & Third SATA CD-ROM Device \\ /dev/scd3 & Fourth SATA CD-ROM Device \\ \end{tabular} \end{center} Usually the SATA CD-ROM device will be /dev/scd0. \subsubsection{Target Partition Device} You need to know, or find out, the device name for the hard disk or flash disk partition on which you want to install asplinux. The device names for disk partitions are formed by appending a number to the device name of the corresponding disk. For example, if your disk device is /dev/hda, the device /dev/hda3 is the third partition on that disk. Numbers 1-4 are the primary partitions, extended partitions start at 5. If you plan on installing onto a USB disk, or some other frequently moved disk device, use the instructions in section \ref{bootflash}. The disk and partition devices used by this installation process will likely need to be different on a different computer. Because the installation disk and partition device numbers are subsequently used by the installed asplinux, it will not boot, or possible not work right, when booted on a computer other than the computer on which the installation is performed. Due to the combined space requirements of the 8 MB asplinux file system and the over 2 MB asplinux kernel, and considering some margin, the minimum partition size you can install asplinux on and have it work is about 12 MB. IDE disks use the same device names as given for IDE CD-ROM devices above. For SATA, the names are as follows: \begin{center} \begin{tabular}{l|l} Device Name & Description \\ \hline /dev/sda & First SATA Disk Device \\ /dev/sdb & Second SATA Disk Device \\ /dev/sdc & Third SATA Disk Device \\ /dev/sdd & Fourth SATA Disk Device \\ \end{tabular} \end{center} Note that if you want to create a dual-boot setup with Windows and asplinux on the same disk, a topic not covered here, you can't use the first partition /dev/hda1 or /dev/sda1 as your target partition, because that is where Windows needs to be installed to work. Here are some examples of possible device names for your target partition: \begin{center} \begin{tabular}{l|l} Device Name & Description \\ \hline /dev/hda1 & First Primary Partition on Primary IDE Master \\ /dev/hdb5 & First Extended Partition on Primary IDE Slave \\ /dev/sda2 & Second Primary Partition on First SATA Disk \\ /dev/sdc6 & Second Extended Partition on Third SATA Disk \\ \end{tabular} \end{center} Note that depending on the BIOS, booting might be possible only from the first two disks installed in the system. What to do if your target disk is not partitioned yet? asplinux includes the \url{fdisk} program that can be used to partition disks. For example, to partition a disk connected as master to the first IDE controller, use: \begin{lstlisting} fdisk /dev/hda \end{lstlisting} The user interface of \url{fdisk} is somewhat primitive, {\it so be careful}. If you haven't used it before, a good idea would be to search the Internet for instructions. The basic commands you may need are "d" to delete a partition, "n" to create a new partition, "p" to print the current partition table, and "w" to write the edited partition table to disk. You can also use "q" to exit \url{fdisk} without saving your changes. \subsubsection{Boot Loader Location} The LILO boot loader is installed in one of two places: either the Master Boot Record (MBR) of the {\it disk device} or the boot sector of the {\it partition device} in which asplinux is being installed. With LILO installed in the MBR of the first disk, it will completely take over the entire boot process of the computer. If there are other operating systems installed on the computer they need to be specified in the LILO configuration file, \url{/etc/lilo.conf}, in order to boot them. With LILO installed in the boot sector of the target partition or in the MBR of a disk other than the first one in your computer, the bootloader installed in the MBR of the first disk needs to be configured to boot the asplinux target partition. \subsubsection{Running the Installer} Once you have decided on target device and boot loader location, you can run the installer. The script is called \url{asplinux-installer} and can be invoked as follows, the square brackets indicate an optional parameter, the {\it partition} device is used for the installation target: \begin{lstlisting} asplinux-installer [-m] \end{lstlisting} For example, to install from the CD-ROM device /dev/hdc into partition device /dev/hda2 and placing LILO on the MBR, /dev/hda disk device, you would use: \begin{lstlisting} asplinux-installer -m /dev/hdc /dev/hda2 \end{lstlisting} Another example, installing from the second SATA CD-ROM device /dev/scd1 into the third partition device of the second SATA disk and placing LILO on the boot sector {\it of the target partition}: \begin{lstlisting} asplinux-installer /dev/scd1 /dev/sdb3 \end{lstlisting} The installer checks if the source CR-ROM device contains a asplinux CD-ROM; if the CD-ROM is found then a summary of what is to be installed on which device is printed and you are given a choice of continuing or aborting. Enter "yes" to continue the installation. The installer creates an ext2 file system on the target partition then copies the asplinux distribution files onto the new file system, and then installs the LILO bootloader. After the installer is finished you can remove the CD-ROM from your computer and reboot. \subsection{Manual Installation} This description uses \url{LILO} for boot loading; other boot loaders such as \url{grub} and maybe \url{loadlin} and \url{syslinux} will also work. There are two files to take from the asplinux CD-ROM image, either by burning the image to a blank CD-ROM disc and mounting it, or mounting the CR-ROM image via loop device. The asplinux version 8.0 CD-ROM image file is named \url{bootcd-i486-8.0.iso.gz}; decompress it and mount it via loop device with the following commands. \begin{lstlisting} mkdir -p mnt/asplinux gunzip bootcd-i486-8.0.iso.gz mount -t iso9660 -o loop bootcd-i486-8.0.iso mnt/asplinux \end{lstlisting} The two files needed from the CD-ROM are the asplinux root file system, \url{isolinux/filesys.gz}, and the Linux kernel, \url{isolinux/vmlinuz}. You can, of course, use a different Linux kernel, following the asplinux custom kernel requirements described in section \ref{customkernel}. There are two ways to install asplinux for booting, one is to have the asplinux root file system in RAM disk, the other is to install the root file system directory onto a disk. {\bf Install a asplinux to Boot Using RAM Disk} Copy the asplinux file system \url{filesys.gz} image and the desired Linux kernel into your boot files directory; probably, this directory is \url{/boot}. After copying the two files, unmount the loop device with the following command. \begin{lstlisting} umount -d mnt/asplinux \end{lstlisting} These two files, the kernel and the file system image, can have names other than the file names from the asplinux CD-ROM. For this example the file names are changed from the names on the CD-ROM: the compressed asplinux file system image file is called \url{asplinux-filesys.gz}, the Linux kernel is called \url{asplinux-vmlinuz} and the boot dirctory is \url{/boot}. Add the following section to \url{/etc/lilo.conf}: \begin{lstlisting} image = /boot/asplinux-vmlinuz label = asplinux initrd = /boot/asplinux-filesys.gz root = /dev/ram0 read-only \end{lstlisting} Run the \url{LILO} boot loader installer by typing \url{/sbin/lilo}. The next boot will have the option of selecting \url{asplinux} at the \url{LILO} boot prompt. {\bf Install a asplinux to Boot with File System on Disk} A hard disk partition, or a flash disk partition, of at least 8 MB is needed to install asplinux. For this example asplinux is being installed on disk partition device /dev/hda8 and the kernel and file system files are available via the loop device instructions above. A loop device also is used to mount the asplinux file system image file. \begin{lstlisting} cp mnt/asplinux/isolinux/filesys.gz filesys.gz umount -d mnt/asplinux gunzip filesys.gz mkdir -p mnt/filesys mkdir -p mnt/newroot mount -t ext2 -o loop ./filesys mnt/filesys mount -t ext2 /dev/hda8 mnt/newroot cp -aR mnt/filesys/* mnt/newroot umount -d mnt/filesys \end{lstlisting} The new asplinux root file system is still mounted; it needs to be customized before booting. Customization is described in the following section \ref{customization}; it includes a description of a \url{LILO} configuration for booting the new asplinux installation. After customization unmount mnt/newroot. \subsection{Customization} \label{customization} This section covers the minimum customization needed to run asplinux. More system configuration and customization can be done; see the system guide, section \ref{sysguide}, below for information. The configuration files and options described in this section are present in a asplinux system installed from the bootable CD-ROM. Following the installation instructions above, the file system is in \url{mnt/newroot}, that is the example starting point for the following customization descriptions. {\bf /etc/fstab} \url{/etc/fstab} needs to have the correct device for the root directory, the manually installed asplinux \url{/etc/fstab} still specifies a RAM disk device for the root directory. Change the RAM disk device, /dev/ram0, to be the disk partition device in which the asplinux root file system was installed. In the above example /dev/hda8 was used, so for that example the root directory in \url{/etc/fstab} would be specified as: \begin{lstlisting} /dev/hda8 / ext2 defaults 0 0 \end{lstlisting} {\bf Boot Loader} The boot loader needs to be aware of the asplinux kernel and root file system device. Following the installation instructions above, the \url{LILO} configuration file \url{/etc/lilo.conf} would include the following. Note the {\it initrd} specifier is removed and the {\it root} specifier is changed to /dev/hda8. \begin{lstlisting} image = /boot/asplinux-vmlinuz label = asplinux root = /dev/hda8 read-only \end{lstlisting} {\bf Keyboard Map and Timezone} To use the current keyboard map and timezone from the Linux computer being used to install asplinux, use the following commands. \begin{lstlisting} rm mnt/newroot/etc/localtime cat /etc/localtime > mnt/newroot/etc/localtime mnt/newroot/bin/dumpkmap > mnt/newroot/etc/i18n/kmap \end{lstlisting} {\bf Dial-up Network Information} [The asplinux PPP and ISDN structure is being re-organized.] To set up the dial information for an Internet provider, you need to know the following: \begin{itemize} \item the device your modem is connected to, i.e. {\tt /dev/ttyS1} \item the init string for your modem, i.e. {\tt ATZ} \item the speed your modem can talk to the computer, i.e. {\tt 115200} \item the phone number of your ISP, i.e. {\tt 1-800-LETMEIN} \item your user name at the ISP, i.e. {\tt joeuser} \item your password at the ISP, i.e. {\tt joepass} \end{itemize} The above is for dialup using a modem. If you want to use ISDN dialup, you need to know the following: \begin{itemize} \item the phone number of your ISP, i.e. {\tt 1-800-12345678} \item your user name at the ISP, i.e. {\tt joeuser} \item your password at the ISP, i.e. {\tt joepass} \item the phone number you want to use for dialing out \item whether you want to use automatic or manual dialing \end{itemize} Edit the file \url{mnt/newroot/etc/ttyisp.conf} and make the appropriate changes. asplinux works only with providers that launch a PPP session immediately after dialup, which should be true for almost all providers; if a different procedure is needed to login, your Internet connection will not work with asplinux. The asplinux approach will work with almost all providers in Germany. [The creator and original maintainer of asplinux is Pascal Schmidt who lives in Germany.] For asplinux to use ISDN, you need to have \url{USE_ISDN=yes} in \url{/etc/ttyisp.conf}, the default is not to use ISDN. Also needed is a kernel with ISDN support and hardware support for your ISDN hardware. If you need kernel modules to run your ISDN hardware, you will also need to add those and a suitable \url{/etc/modules.conf} to the asplinux file system. \section{Add-ons} Add-ons may be available at the asplinux web site. Previous asplinux add-ons may no longer be supported and no longer be available at the asplinux web site. Previous add-ons may become unsupported because they do not properly build in the asplinux 8 build environment, or because their run-time environment is not supported in the asplinux 8 run-time environment. Corrected and new add-ons submitted to asplinux will be considered for inclusion at the web site. \section{System Guide} \label{sysguide} This section gives a short overview of the asplinux system, its configuration and some of the installed programs. \subsection{Basic Features} Upon boot-up, asplinux provides 6 text consoles for login. There is one initial user account: \url{root}, the administrator account, with password \url{password}. The \url{syslogd} and \url{klog} daemons are running and logging kernel and system messages to the file \url{/var/log/messages}. The available text editor is \url{vi}; invoke it by typing \url{vi} \url{/path/to/filename}. This version of \url{vi} is a minimal version provided by \url{busybox}. Documentation and help for using \url{vi} is available in many places on the web. For manipulation of users, groups and passwords, the tools \url{adduser}, \url{addgroup}, \url{deluser}, \url{delgroup} and \url{passwd} are present. If you have not changed the timezone and keyboard settings as outlined in the customization section, section \ref{customization} above, asplinux will use its default settings. The default timezone is UTC, the default keyboard mapping is for a US keyboard. The \url{inetd} super-server and the \url{dropbear} SSH server are running by default. A telnet server will be forked by \url{inetd} when a telnet connection comes in. asplinux includes a basic packet filtering firewall which is enabled by default on the dialup interface. Note that the telnet server is not visible from the external side of the dialup interface in the default firewall configuration. \subsection{Bootup, Shutdown and System Configuration} On system bootup, the init process runs the \url{/etc/rc.d/rc.sysinit} script to setup the system, such as setting the clock, system font, keyboard map and checking the file systems. \url{rc.sysinit} also runs all the programs in the \url{/etc/rc.d/rc.startup} directory {\it and then} runs the \url{/etc/rc.d/rc.local} script, all with the command line parameter {\tt start}. On system shutdown, the script \url{/etc/rc.d/rc.sysdone} runs. This scripts runs all the programs in the \url{/etc/rc.d/rc.shutdown} directory {\it and then} runs the \url{/etc/rc.d/rc.local} script, all with the command line parameter {\tt stop}. All the programs in \url{/etc/rc.d/rc.startup} and \url{/etc/rc.d/rc.shutdown} are symbolic links that reference actual shell scripts or binary programs; they are run in the ASCII order of their file names. These symbolic links are named with leading numbers to help control their ordering e.g., \url{10.network} is the symbolic link the the network startup program. The actual programs are in \url{/etc/rc.d/init.d}. Removing a symbolic link disables the program from starting up. These programs typically are shell scripts; they are commonly called {\it initscripts}. Initscripts can be interactively invoked. The following command runs the network script \url{/etc/rc.d/init.d/syslog} with the command line option \url{stop}. \begin{lstlisting} service syslog stop \end{lstlisting} All scripts use the command line options \url{start}, \url{stop}, \url{reload}, \url{restart} and \url{status}. They print a list of supported options if they are called with no option present. The initscripts define the basic asplinux bootup system configuration. The initscripts are configurable, to an extent; thus the bootup configuration is configurable, to an extent. The bootup system configuration is specified in ASCII text files in the \url{/etc/sysconfig} directory; this directory is intended to have only files that are read by the various initscripts. All files read by initscripts for configuration options should reside in \url{/etc/sysconfig}. \subsection{Shell Environment} The default shell used by asplinux is GNU bash. The shell environment of aliases and variables is in \url{/etc/bashrc}; view this file after login to become familiar with the default shell environment. Upon login, the \url{PATH} environmental variable has the following paths in the order listed. \begin{lstlisting} /bin /usr/bin /sbin /usr/sbin \end{lstlisting} Put additional, or overriding, shell environment in scripts in the \url{/etc/profile.d} directory; do not change \url{/etc/bashrc} in order to avoid losing changes when updating asplinux. \subsection{Using the Dropbear for SSH} SSH, or secure shell, is a protocol for remote login with an advantage over telnet being that it can use public key authentication instead of passwords. Another advantage over the telnet protocol is that plain text is not transfered; the data sent between the host connections is encrypted. \url{dropbear} is a small SSH v2 server and client package. The server is started on system bootup by default. It allows password and public key authentication. Public key authentication can use DSS and RSA keys and works with keys generated by the popular OpenSSH package. Having a public key from OpenSSH in the file \url{.ssh/authorized_keys} should allow secure login from the machine that has the corresponding private key. The permissions on the \url{.ssh} directory must not include group or other write permission, otherwise \url{dropbear} will refuse public key authentication. The SSH client program is called \url{dbclient}. It is different from the server in that it cannot use keys in OpenSSH format. You can use the \url{dropbearconvert} program to convert an OpenSSH format key for use by \url{dbclient} or you can use \url{dropbearkey} to create a new key. To convert an OpenSSH key stored in \url{~/.ssh/id_rsa}, do: \begin{lstlisting} dropbearconvert openssh dropbear \ ~/.ssh/id_rsa ~/.ssh/id_rsa.db \end{lstlisting} The new key will be stored in \url{~/.ssh/id_rsa.db}. You can use the \url{-i} switch to \url{dbclient} to make it use your new key for authentication. The public key part of the old OpenSSH key can be used as-is for pasting into your \url{~/.ssh/authorized_keys} file. Conversion is only needed for the private key. To create a new RSA key to store in \url{~/.ssh/id_rsa.db}, you can use the following command: \begin{lstlisting} dropbearkey -t rsa -f ~/.ssh/id_rsa.db \end{lstlisting} The public key part of the new key will be printed to the screen. You can put it into the \url{~/.ssh/authorized_keys} file on all machines where you want to be able to login using your new private key stored in \url{~/.ssh/id_rsa.db}. You can create a DSS key instead of an RSA key by using \url{-t} \url{dss} instead of \url{-t} \url{rsa}. Should you lose the public key, you can always get it back by using the private key and the \url{-y} switch to \url{dropbearkey}: \begin{lstlisting} dropbearkey -y -f ~/.ssh/id_rsa.db \end{lstlisting} If you want to use \url{scp} to copy files from another machine, the standard \url{scp} program from OpenSSH is included with \url{dropbear} and asplinux. \subsection{Using an Ethernet Network} asplinux is ready to use Ethernet networking. DHCP will be used when starting up the Ethernet network, unless configured otherwise. The Ethernet network interface configuration is specified in the text file: \begin{lstlisting} /etc/sysconfig/network-scripts/ifcfg-eth0 \end{lstlisting} This file has specification in the form of "ITEM=value". Edit this file to set the proper Ethernet interface IP addresses, change the Ethernet DHCP usage and to enable Ethernet networking. To enable Ethernet networking, the line \url{ENABLE=no} must be changed to \url{ENABLE=yes}. To disable DHCP, the line \url{DHCP=yes} must be changed to \url{DHCP=no}. After configuring the Ethernet network interface, restart the networking subsystem with the following command. \begin{lstlisting} service network restart \end{lstlisting} See the description of the \url{/sbin/sysconfig} script in section \ref{sysconfig} for scripted help in setting up the Ethernet network interface configuration. The Ethernet network interface, commonly referred to as eth0, can be started and stopped independently from the entire network subsystem with the following commands. Startup eth0 with: \begin{lstlisting} ifup eth0 \end{lstlisting} Shutdown eth0 with: \begin{lstlisting} ifdown eth0 \end{lstlisting} \subsection{Using the Firewall} [The asplinux firewall structure is being re-organized.] The default settings of the asplinux firewall script assume that the network interface to the rest of the world is called \url{ippp0} or \url{ppp0}, depending on whether you use ISDN or modem dialup. By default, the firewall will allow the world to access the SSH server, but will deny access to the telnet server. Other incoming connection attempts will also be denied and logged, rate limited to an average of 3 messages per hour, except for connections to the \url{ftp-data} port, which is used for active FTP sessions and allowed in. This applies to TCP connections. For the UDP protocol, incoming packets to ports above 1024 are allowed. Also, the outside world is not allowed to ping the asplinux machine. Outgoing traffic is not firewalled at all. You can change the settings of the firewall in \url{/etc/firewall.conf}. The only configuration options are whether to allow or deny access to the SSH and telnet servers. Note that this firewall script is very simple and assumes that local users are always trusted. There is no protection against users running server daemons on UDP ports above 1024. If you don't trust your users, this firewall script is not good enough. Also note that only the \url{ppp0} or \url{ippp0} device is protected, all other interfaces are not firewalled at all. \subsection{Using Dialup} [The asplinux PPP and ISDN structure is being re-organized.] What to put into \url{/etc/isp.conf} to configure the dailup information is outlined above in the customization section (\ref{customization}, above). What you will find here is an overview of how to actually use the PPP subsystem for Internet dialup. Assuming \url{/etc/isp.conf} was setup correctly before boot, you only need one command to start up the Internet connection: \begin{lstlisting} ppp-up \end{lstlisting} If you use ISDN with autodialing enabled (\url{ISDN_MODE=auto} set in \url{/etc/isp.conf}), you do not need to run \url{ppp-up}. Just run a program that sends packets to an Internet host. \url{ppp-up} triggers the PPP daemon, which will dial the provider and try to login. \url{ppp-up} can be run by any user in the \url{ppp} group. In the default asplinux configuration, the \url{ppp} group has no members, so only \url{root} can start and stop the internet connection. You can watch \url{/var/log/messages} (using \url{tail} \url{-f}) to see when the connection is up and running. After that, the Internet connection is ready for use. For example, the SSH server will be reachable from the outside world. You can browse the web by using the \url{retawq} web browser. Use the \url{g} key to enter a URL, then navigate around using the cursor and return keys. You can leave the browser by pressing \url{Shift-Q}. If you use ISDN, you can enable and disable channel bundling by calling the \url{bundle} and \url{unbundle} scripts while the connection is up. The default for new connections is to always use a single channel, even if channel bundling was enabled before. To check whether channel bundling is currently enabled, use the command: \begin{lstlisting} service isdn status \end{lstlisting} If you decide that you want to cut the Internet link, just issue: \begin{lstlisting} ppp-down \end{lstlisting} This will take the connection down. Once again, this can be done by \url{root} or a user from the \url{ppp} group, in this case only the user who started the connection. If you change any of the settings in \url{/etc/isp.conf}, you need to update the PPP configuration files by running the following command: \begin{lstlisting} ppprestart \end{lstlisting} Note that if you want to switch from using a modem to using ISDN or vice versa, you need to take down the Internet connection before running \url{ppprestart}. After that, you can again use \url{ppp-up} and \url{ppp-down}. Note that running \url{ppprestart} only works for \url{root}, not ordinary users. In previous asplinux versions (2.5 and older), rebooting also updated the PPP configuration files. This is no longer the case to allow manual modifications of the files. They will only be created on boot if they don't exist. Users in the \url{ppp} group will be able to read the file \url{/etc/isp.conf} which contains your dialup password. This may or may not be a good idea, depending on how much you trust your users. If you only wish to use ISDN, you can remove the group read permission with \begin{lstlisting} chmod g-r /etc/isp.conf \end{lstlisting} \subsection{Package Management} Package management is handled by shell script \url{/usr/bin/pacman}; since the directory \url{/usr/bin} is in the PATH, pacman is invoked from the shell command line by typing its name, \url{pacman}. Its options are somewhat similar to Red Hat's package manager RPM. Use \url{pacman} to install and remove packages, and to query the database of installed packages and files. The binary packages used by asplinux are \url{tar} archives compressed with the {\tt bzip2} algorithm. All the packages that normally come with the asplinux distribution are available on the download page at the asplinux web site; this is for reinstalling any packages that may have been removed from a asplinux system. To install the package \url{bash-3.2-i486.tbz}, you would use the following command: \begin{lstlisting} pacman -i pkg-bash-3.2.tbz \end{lstlisting} \url{pacman} can install a package from standard input. This is useful for forming a pipe with the \url{wget} program, which allows installing a package from the network without having to store it. For example, use the following to download and install the \url{bash} package from a asplinux web site \url{asplinux.net}: \begin{lstlisting} wget http://asplinux.net/Download/bash-3.2-i486.tbz -O - | pacman -i - \end{lstlisting} Three different options are available for querying the database of installed packages and files. To get a list of all installed packages, run \begin{lstlisting} pacman -qa \end{lstlisting} To find out which package the file \url{/bin/login} belongs to, use \begin{lstlisting} pacman -qf /bin/login \end{lstlisting} To list all files from the \url{e2fsprogs-1.41.3} package, run \begin{lstlisting} pacman -ql e2fsprogs-1.41.3 \end{lstlisting} If you want to remove a package, you can do so by use of the \url{-e} option. To remove the \url{isdn4k-utils.v3.2p1} package, you would use the following command: \begin{lstlisting} pacman -e isdn4k-utils.v3.2p1 \end{lstlisting} You can also use the \url{-v} option to get verbose output during installation and removal of packages. \url{pacman} will then list all the files it has installed or removed. {\bf pacman Database}\\ The \url{pacman} script uses directory \url{/usr/share/asplinux} which has one file per installed package, each file containing a listing of all the files that belong to the installed package. \subsection{Using the sysconfig Script} \label{sysconfig} The \url{/sbin/sysconfig} shell script can be used to set, and to show, the fields in various asplinux system configuration files; it can set or show any value for any "ITEM=value" line in any configuration file in the \url{/etc/sysconfig} and \url{/etc/sysconfig/network-scripts} directories. The following commands sets "ENABLE=yes" and "DHCP=yes" in the \url{/etc/sysconfig/network-scripts/ifcfg-eth0} file. \begin{lstlisting} sysconfig -nc ifcfg-eth0.enable=yes sysconfig -nc ifcfg-eth0.dhcp=yes \end{lstlisting} The "-nc" option in the above examples tells the sysconfig script to work on files in the \url{/etc/sysconfig/network-scripts} directory. The second option is in the form file.item=value. To change the IP address of the Ethernet network interface, with 192.168.1.100 as the example IP address, with a netmask of 255.255.255.0 and standard subnet gateway and broadcast addresses, use the following sequence of sysconfig script commands. \begin{lstlisting} sysconfig -nc ifcfg-eth0.ipaddress=192.168.1.100 sysconfig -nc ifcfg-eth0.network=192.168.1.0 sysconfig -nc ifcfg-eth0.netmaks=255.255.255.0 sysconfig -nc ifcfg-eth0.gateway=192.168.1.1 sysconfig -nc ifcfg-eth0.broadcast=192.168.1.255 \end{lstlisting} Use "-sc" for the first option to the \url{sysconfig} script in order to work with system configuration files in the \url{/etc/sysconfig} directory. Use the following command to get complete, up-to-date help description directly from \url{/sbin/sysconfig} \begin{lstlisting} sysconfig --help \end{lstlisting} \subsection{Depricated and Legacy Items} \subsubsection{devfs} Support for \url{devfs} was removed from asplinux Version 4.0, in Aug 2004. There is no current plan to use a dynamic device file system. \section{Contact and Help} Reporting bugs in asplinux and its documents is appreciated. For bug reports, suggestions, or anything else about asplinux that you think is important, feel free to contact me. You can reach me by email at: \hspace{0.5in}Douglas Jerome \url{} There is a web-based forum that is active from time to time; it is active when this was written, December 2008, and is intended to be active as long as minimalinux is supporting asplinux, barring spammer abuse. \hspace{0.5in}\url{http://www.asplinux.com/forum/} Help may be available on irc, although it is very low bandwith and usually more appropriate for inane banter. \hspace{0.5in}\url{irc.freenode.net} \#\url{asplinux} \appendix \section{asplinux-specific Commands Overview} Separate from the initscripts in \url{/etc/rc.d/initd} directory, the following table lists the asplinux-specific scripts intended to be available for asplinux root users. \begin{center} \begin{tabular}{l|l|l} Script & Directory & Usage \\ \hline asplinux-flash & CD-ROM & Copy asplinux to Flash Disk \\ ifdown & /sbin & Shutdown Ethernet Network Interface \\ ifup & /sbin & Startup Ethernet Network Interface \\ service & /sbin & Execute a script in \url{/etc/rc.d/init.d} \\ sysconfig & /sbin & Modify a System Configuration File \\ asplinux-installer & /sbin & Install asplinux onto A Disk \\ pacman & /usr/bin & asplinux Package Manager \\ \end{tabular} \end{center} \end{document}