Debian Reference ---------------- Osamu Aoki Editor: David Sewell Section A.1, `Authors' CVS, Sun, 13 Oct 2002 22:40:09 -0600 ------------------------------------------------------------------------------- Abstract -------- This Debian Reference (http://qref.sourceforge.net/) is intended to provide a broad overview of the Debian system as a _post-installation user's guide_. It covers many aspects of system administration through _shell-command_ examples. Basic tutorials, tips, and other information are provided for topics including fundamental concepts of the Debian system, system installation hints, Debian package management, the Linux kernel under Debian, system tuning, building a gateway, text editors, CVS, programming, and GnuPG for _non-developers_. Copyright Notice ---------------- Copyright (C) 2001--2002 by Osamu Aoki . Copyright (Chapter 2) (C) 1996--2001 by Software in the Public Interest. This document may used under the terms of the GNU General Public License version 2 or higher. (http://www.gnu.org/copyleft/gpl.html) Permission is granted to make and distribute verbatim copies of this document provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this document under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this document into another language, under the above conditions for modified versions, except that this permission notice may be included in translations approved by the Free Software Foundation instead of in the original English. ------------------------------------------------------------------------------- Contents -------- 1. Preface 1.1. Official document 1.2. Document conventions 1.3. Basic setup 1.4. Basics of the Debian distributions 2. Debian fundamentals 2.1. The Debian archives 2.1.1. Directory structures 2.1.2. Debian distributions 2.1.3. The `stable' distribution 2.1.4. The `testing' distribution 2.1.5. The `unstable' distribution 2.1.6. The `frozen' distribution 2.1.7. Debian distribution codenames 2.1.8. Codenames used in the past 2.1.9. The source for codenames 2.1.10. The `pool' directory 2.1.11. Historical notes about `sid' 2.1.12. Uploaded packages in `incoming' 2.1.13. Retrieving an older package 2.1.14. Architecture sections 2.1.15. The source code 2.2. The Debian package management system 2.2.1. Overview of Debian packages 2.2.2. Debian package format 2.2.3. Naming conventions for Debian package filenames 2.2.4. Preservation of the local configuration 2.2.5. Debian maintenance scripts 2.2.6. Package priorities 2.2.7. Virtual packages 2.2.8. Package dependencies 2.2.9. The meaning of "pre-depends" 2.2.10. Package status 2.2.11. Holding back packages from an upgrade 2.2.12. Source packages 2.2.13. Building binary packages from a source package 2.2.14. Creating new Debian packages 2.3. Upgrading a Debian system 2.3.1. Methods for upgrading a Debian system 2.3.2. Package management tools overview 2.3.3. `dpkg' 2.3.4. APT 2.3.5. `dselect' 2.3.6. Upgrading a running system 2.3.7. Downloaded and cached `.deb' archive files 2.3.8. Record-keeping for upgrades 2.4. The Debian boot process 2.4.1. The `init' program 2.4.2. Runlevels 2.4.3. Customizing the boot process 2.5. Supporting diversity 2.6. Internationalization 2.7. Debian and the kernel 2.7.1. Compiling a kernel from non-Debian source 2.7.2. Tools to build custom kernels 2.7.3. Alternative boot loaders 2.7.4. Custom boot floppies 2.7.5. Special provisions for dealing with modules 2.7.6. De-installing an old kernel package 3. Debian System installation hints 3.1. General Linux system installation hints 3.1.1. Hardware compatibility basics 3.1.2. Determining a PC's hardware and chip set 3.1.3. Determining a PC's hardware via Debian 3.1.4. Determining a PC's hardware via other OSs 3.1.5. A Lilo myth 3.1.6. Choice of boot floppies 3.1.7. Installation 3.1.8. Hosts and IP to use for LAN 3.1.9. User accounts 3.1.10. Creating file systems 3.1.11. DRAM memory guidelines 3.1.12. Swap space 3.2. Bash configuration 3.3. Mouse configuration 3.3.1. PS2 mice 3.3.2. USB mice 3.4. NFS configuration 3.5. Samba configuration 3.6. Printer configuration 3.6.1. `lpr'/`lpd' 3.6.2. CUPS(TM) 3.7. Other host installation hints 3.7.1. Install a few more packages after initial install 3.7.2. Modules 3.7.3. CD-RW basic setup 3.7.4. Large memory and auto power-off 3.7.5. Strange access problems with some websites 3.7.6. Dial-up PPP configuration 3.7.7. Other configuration files to tweak in `/etc' 4. Debian tutorials 4.1. Information sources 4.2. The Linux console 4.2.1. Login 4.2.2. Add a user account 4.2.3. How to shut down 4.2.4. Command-line editing 4.2.5. Very basic commands to remember 4.2.6. X Window System 4.2.7. Important keyboard commands 4.3. Midnight Commander (MC) 4.3.1. Install MC 4.3.2. Start MC 4.3.3. File manager 4.3.4. Command-line tricks 4.3.5. Editor 4.3.6. Viewer 4.3.7. Auto-start features 4.3.8. FTP virtual file system 4.4. Further study 5. Upgrading a distribution 5.1. Transition preparation ("stable" to "testing") 5.2. Upgrade to "testing" 5.2.1. Best upgrade practice using `dselect' 5.2.2. Deprecated upgrade practice using `apt-get' 5.3. Woody configuration 5.4. Optimized `sources.list' 6. Debian package management 6.1. Introduction 6.1.1. Main tools 6.1.2. Convenience tools 6.2. Debian survival commands 6.2.1. Install with `tasksel' 6.2.2. Install system with APT 6.2.3. Upgrade system with APT 6.2.4. Check bugs in Debian and seek help 6.2.5. APT upgrade troubleshooting 6.2.6. Rescue using `dpkg' 6.2.7. Rescue system after erasing `/var' 6.2.8. Install a package into an unbootable system 6.2.9. What to do if the `dpkg' command is broken 6.3. Debian nirvana commands 6.3.1. Information on a file 6.3.2. Information on a package 6.3.3. Reconfigure installed packages 6.3.4. Remove and purge packages 6.3.5. Holding older packages 6.3.6. `dselect' -- global configuration 6.3.7. Prune cached package files 6.3.8. Record/copy system configuration 6.3.9. Port a package to the `stable' system 6.3.10. Local package archive 6.3.11. Convert or install an alien binary package 6.3.12. Verify installed package files 6.4. Other Debian peculiarities 6.4.1. The `dpkg-divert' command 6.4.2. The `equivs' package 6.4.3. Alternative commands 6.4.4. System-V `init' and runlevels 6.4.5. Disabled daemon services 7. The Linux kernel under Debian 7.1. Kernel recompile 7.1.1. Debian standard method 7.1.2. Classic method 7.2. The modularized 2.4 kernel 7.2.1. PCMCIA 7.2.2. SCSI 7.2.3. Network function 7.2.4. EXT3 filesystem ( > 2.4.17) 7.2.5. Realtek RTL-8139 support in 2.4 8. Debian tips 8.1. Booting the system 8.1.1. "I forgot the root password!" (1) 8.1.2. "I forgot the root password!" (2) 8.1.3. Cannot boot the system 8.1.4. Other boot tricks with the boot prompt 8.2. Recording activities 8.2.1. Recording shell activities 8.2.2. Recording X activities 8.2.3. Recording changes to the configuration files 8.3. Copy and archive a whole subdirectory 8.3.1. Basic commands for copying a whole subdirectory 8.3.2. `cp' 8.3.3. `tar' 8.3.4. `pax' 8.3.5. `cpio' 8.3.6. `afio' 8.4. System freeze recovery 8.4.1. Kill a process 8.4.2. ALT-SysRq 8.5. Nifty little commands to remember 8.5.1. Pager 8.5.2. Free memory 8.5.3. Set time (BIOS) 8.5.4. Set time (NTP) 8.5.5. How to disable the screensaver 8.5.6. Search administrative database 8.5.7. Disable sound (beep) 8.5.8. Error messages on the console screen 8.5.9. Set console to the correct type 8.5.10. Get the console back to a sane state 8.5.11. Convert a text file from DOS to Unix style 8.5.12. Regular-expression substitution 8.5.13. Convert a large file into small files 8.5.14. Script snippets for piping commands 8.5.15. Get text or a mailing list archive from a Web page 8.5.16. Pretty print a Web page 8.5.17. Time a command 8.5.18. `nice' command 8.5.19. Schedule activity (`cron', `at') 8.5.20. Console switching with `screen' 8.5.21. Network testing basics 8.5.22. Flush mail from local spool 8.5.23. Remove frozen mail from local spool 8.5.24. Clear file contents 8.5.25. Dummy files 8.5.26. `chroot' 8.5.27. `mount' hard disk image file 8.5.28. Samba 9. Tuning a Debian system 9.1. System initialization hints 9.1.1. Customizing init scripts 9.1.2. Customizing system logging 9.1.3. Hardware access optimization 9.2. Access control 9.2.1. Access control through PAM and login 9.2.2. "Why GNU `su' does not support the `wheel' group" 9.2.3. Meaning of various groups 9.2.4. `sudo' -- a safer work environment 9.2.5. Access control to daemon programs 9.2.6. Lightweight Directory Access Protocol 9.3. CD-writer 9.3.1. Introduction 9.3.2. Approach 1: modules + `lilo' 9.3.3. Approach 2: recompile the kernel 9.3.4. Post-configuration steps 9.3.5. CD-image file (bootable) 9.3.6. Write to the CD-writer (R, R/W): 9.3.7. Make an image file of a CD 9.3.8. Debian CD images 9.3.9. Back up the system to CD-R 9.3.10. Copy a music CD to CD-R 9.4. The X program 9.4.1. X server 9.4.2. X client 9.4.3. TCP/IP connection to X 9.4.4. Remote X connection: `xhost' 9.4.5. Remote X connection: `ssh' 9.4.6. `xterm' 9.4.7. Gain root in X 9.4.8. TrueType fonts in X 9.4.9. Web Browser (graphical) 9.4.10. CJK and X 9.5. SSH 9.5.1. Basics 9.5.2. Port forwarding -- for SMTP/POP3 tunneling 9.5.3. Connect with fewer passwords 9.5.4. Foreign SSH clients 9.5.5. SSH agent 9.5.6. Troubleshooting 9.6. Mail programs 9.6.1. Mail transport agent (Exim) 9.6.2. Mail utility (Fetchmail) 9.6.3. Mail utility (Procmail) 9.6.4. Mail user agent (Mutt) 9.7. Localization and national language support 9.7.1. Language support 9.7.2. Locales 9.7.3. Activate locale support capability 9.7.4. Activate a particular locale 9.7.5. Beyond `locale' 10. Building a gateway with a Debian system 10.1. Network configuration 10.1.1. Host configuration for the gateway 10.1.2. Network configuration checkpoints 10.2. Netfilter configuration 10.2.1. Basics of netfilter 10.2.2. Netfilter table 10.2.3. Netfilter target 10.2.4. Netfilter command 10.2.5. IP-masquerade 10.2.6. Redirect SMTP connection (2.4) 10.3. Manage multiple net connections 11. Editors 11.1. Popular editors 11.2. Rescue editors 11.3. Emacs and Vim 11.3.1. Vim hints 11.3.2. Emacs hints 11.3.3. Starting the editor 11.3.4. Editor command summary (Emacs, Vim) 11.3.5. Vim configuration 11.3.6. Ctags 11.3.7. Convert a syntax-highlighted screen to HTML source 11.3.8. Split screen with `vim' 12. CVS 12.1. Installing a CVS server 12.2. CVS session examples 12.2.1. Anonymous CVS (download only) 12.2.2. Use local CVS server 12.2.3. Use remote CVS pserver 12.2.4. Use remote CVS through `ssh' 12.2.5. Create a new CVS archive 12.2.6. Work with CVS 12.2.7. Export files from CVS 12.2.8. Administer CVS 12.3. Troubleshooting CVS 12.3.1. File permissions in repository 12.3.2. Execution bit 12.4. CVS commands 13. Programming 13.1. Where to start 13.2. Shell 13.2.1. Bash -- _GNU_ standard interactive shell 13.2.2. POSIX shells 13.2.3. Shell parameters 13.2.4. Shell redirection 13.2.5. Shell conditionals 13.2.6. Command-line processing 13.3. Awk 13.4. Perl 13.5. Python 13.6. Make 13.7. C 13.7.1. Simple C program (`gcc') 13.7.2. Debugging 13.7.3. Flex -- a better Lex 13.7.4. Bison -- a better Yacc 13.7.5. Autoconf 13.8. Document preparation 13.8.1. `roff' typesetting 13.8.2. SGML 13.9. Packaging 14. GnuPG 14.1. Installing GnuPG 14.2. Using GnuPG 14.3. Managing GnuPG 14.4. Using GnuPG with applications 14.4.1. Using GnuPG with Mutt 14.4.2. Using GnuPG with Vim 15. Support for Debian 15.1. References 15.2. Finding the meaning of a word 15.3. Finding the popularity of a Debian package 15.4. The Debian bug tracking system 15.5. Mailing lists 15.6. Internet Relay Chat (IRC) 15.7. Search engines 15.8. Websites A. Appendix A.1. Authors A.2. Warranties A.3. Feedback A.4. Document format A.5. The Debian maze A.6. The Debian quotes ------------------------------------------------------------------------------- 1. Preface ---------- This Debian Reference (http://qref.sourceforge.net/) is intended to provide a broad overview of the Debian system as a _post-installation user's guide_. Its target reader is someone who is willing to read shell scripts. I expect the reader to have gained basic skills in Unix-like systems prior to reading this document. I made a conscious decision _not_ to explain everything in detail if it can be found in a _manual page_, an _info page_, or a _HOWTO document_. Instead of full explanations, I have tried to give more directly practical information by providing _exact command sequences_ or _example scripts_. Much of the information included consists of reminders or pointers to the authoritative references listed in Section 15.1, `References'. This is partly because this document originated as a "_quick reference_". _Keep it short and simple_ (KISS) is my guiding principle. For help with emergency system maintenance, proceed to Section 6.2, `Debian survival commands' immediately. 1.1. Official document ---------------------- The latest official document is in Debian archives with the package name `debian-reference' and is also available from http://www.debian.org/doc/manuals/debian-reference/. The latest development version is http://qref.sourceforge.net/Debian/. The project is hosted at http://qref.sourceforge.net/, where this document is available for download in plain text, HTML, PDF, SGML and PostScript formats. 1.2. Document conventions ------------------------- This "Debian Reference" document provides information through short Bash shell commands. Here are the conventions used: # command in root account $ command in user account ... description of action See Section 13.2.1, `Bash -- _GNU_ standard interactive shell' for more information on Bash. Reference to: * a _Unix manual_ page is given in the form bash(1). * a _GNU TEXINFO_ page is given in the form `info libc'. * a _book_ is given in the form _The C Programming Language_. * a _URL_ is given in the form http://www.debian.org/doc/manuals/debian-reference/. * a _file_ on the system is given in the form `/usr/share/doc/Debian/reference/'. The following abbreviations are used: * _LDP_: Linux Documentation Project (http://www.tldp.org/) * _DDP_: Debian Documentation Project (http://www.debian.org/doc/) In this document only URLs are shown for LDP documents, but they can also be obtained as a package and installed into `/usr/share/doc/HOWTO/'. See Section 15.1, `References'. Sample scripts are available in the examples subdirectory (examples/); for hidden files, the preceding "." in the filename is converted to underscore "_". 1.3. Basic setup ---------------- If the system is installed with the bare minimum of packages, make sure to execute the following commands to install some essential packages and a few key documents: # apt-get install info man-db doc-base dhelp apt apt-utils auto-apt \ dpkg less mc ssh nano-tiny elvis-tiny vim sash \ kernel-package \ manpages manpages-dev doc-debian doc-linux-text \ debian-policy developers-reference maint-guide \ apt-howto harden-doc install-doc \ libpam-doc glibc-doc samba-doc exim-doc cvsbook \ gnupg-doc # apt-get install debian-reference # for Sarge, do this too :) 1.4. Basics of the Debian distributions --------------------------------------- Debian comes in 3 release "flavors": * stable: Good to track on a production server. Boring for the workstation (WS). See Section 2.1.3, `The `stable' distribution'. * testing: Good to track on the WS. See Section 2.1.4, `The `testing' distribution'. * unstable: Never track this blindly. See Section 2.1.5, `The `unstable' distribution'. Read at least the key mailing list `debian-devel-announce@lists.debian.org' for updates on the status of Debian. In March 2002, these three release versions corresponded to `potato' (production quality), `woody' (beta-test, very stable then since release was imminent), and `sid' (alpha-test). In August 2002, right after the `woody' release, these corresponded to `woody' (production quality), `sarge' (beta-test, it will be a somewhat rough ride for some time), and `sid' (always alpha-test). When packages in `unstable' have no Release Critical (RC) bugs filed against them after the first week or so, they are automatically promoted to `testing'. See Section 2.1, `The Debian archives'. In theory, there are two things you can do get the latest versions of software running. * Section 6.2.2, `Install system with APT' (mainly for WS purposes) * Section 6.3.9, `Port a package to the `stable' system' (mainly for server purposes) After explaining some fundamentals of the Debian distribution in Chapter 2, `Debian fundamentals', I will present some basic information to help you live happily with the latest software, taking advantage of the `testing' and `unstable' distributions of Debian. The impatient should proceed to Section 6.2, `Debian survival commands' immediately. Happy upgrading! ------------------------------------------------------------------------------- 2. Debian fundamentals ---------------------- This chapter provides fundamental information on the Debian system for non-developers. For authoritative information, see: * Debian Policy Manual * Debian Packaging Manual (Potato) * Debian Developer's Reference * Debian New Maintainers' Guide listed under Section 15.1, `References'. If you are looking for less detailed "how-to" explanations, jump directly to Chapter 6, `Debian package management' or other relevant chapters. This chapter consists of documents taken from the "Debian FAQ", greatly reorganized to allow the ordinary Debian system administrator to get started. 2.1. The Debian archives ------------------------ 2.1.1. Directory structures --------------------------- The software that has been packaged for Debian is available in one of several directory trees on each Debian mirror site (http://www.debian.org/misc/README.mirrors) through FTP or HTTP. The following directories can be found on each Debian mirror site under the `/debian/' directory: `/dists/': This directory contains the "distributions", and this used to be the canonical way to access the currently available packages in Debian releases and pre-releases. Some old packages and `Packages.gz' files are still in here. `/pool/': The new physical location for all packages of Debian releases and pre-releases. `/tools/': DOS utilities for creating boot disks, partitioning your disk drive, compressing/decompressing files, and booting Linux. `/doc/': The basic Debian documentation, such as the FAQ, the bug reporting system instructions, etc. `/indices/': The Maintainers file and the override files. `/project/': mostly developer-only materials, such as: `project/experimental/': This directory contains packages and tools which are still being developed, and are still in the alpha testing stage. Users shouldn't be using packages from here, because they can be dangerous and harmful even for the most experienced. `project/orphaned/': Packages that have been orphaned by their old maintainers, and withdrawn from the distribution. 2.1.2. Debian distributions --------------------------- Normally there are three Debian distributions in the `dists' directory. They are named the "stable" distribution, the "testing" distribution, and the "unstable" distribution. Sometimes there is also a "frozen" distribution. Each distribution is defined as a symlink to the actual directory with a codename in the `dists' directory. 2.1.3. The `stable' distribution -------------------------------- Package entries for the `stable' distribution, Debian Woody (3.0r0), are recorded into the `stable' (symlink to `Woody') directory: * `stable/main/': This directory contains the packages which formally constitute the most recent release of the Debian system. These packages all comply with the Debian Free Software Guidelines (http://www.debian.org/social_contract#guidelines) (also available as `/usr/share/doc/debian/social-contract.txt' installed by `debian-doc'), and are all freely usable and distributable. * `stable/non-free/': This directory contains packages distribution of which is restricted in a way that requires that distributors take careful account of the specified copyright requirements. For example, some packages have licenses which prohibit commercial distribution. Others can be redistributed but are in fact shareware and not free software. The licenses of each of these packages must be studied, and possibly negotiated, before the packages are included in any redistribution (e.g., in a CD-ROM). * `stable/contrib/': This directory contains packages which are DFSG-free and _freely distributable_ themselves, but somehow depend on a package that is _not_ freely distributable and thus available only in the non-free section. Now, in addition to the above locations, new physical packages are located under the `pool' directory (Section 2.1.10, `The `pool' directory'). The current status of `stable' distribution bugs is reported on the Stable Problems (http://ftp-master.debian.org/testing/stable_probs.html) Web page. 2.1.4. The `testing' distribution --------------------------------- Package entries for the `testing' distribution, Debian Sarge, are recorded into the `testing' (symlink to `Sarge') directory after they have undergone some degree of testing in `unstable'. Now, in addition to the above locations, new physical packages are located under the `pool' directory (Section 2.1.10, `The `pool' directory'). There are also `main', `contrib' and `non-free' subdirectories in `testing', which serve the same functions as in `stable'. These packages must be in sync on all architectures where they have been built and mustn't have dependencies that make them uninstallable; they also have to have fewer release-critical bugs than the versions currently in `unstable'. This way, we hope that `testing' is always close to being a release candidate. More details of the testing mechanism are at http://ftp-master.debian.org/testing/. The latest status of the `testing' distribution is reported at these sites: * update excuses (http://ftp-master.debian.org/testing/update_excuses.html) * testing problems (http://ftp-master.debian.org/testing/testing_probs.html) * release-critical bugs (http://bugs.debian.org/release-critical/) * base system bugs (http://base.debian.net/) * bugs in standard and task packages (http://standard.debian.net/) * other bugs and bug-squashing party notes (http://bugs.debian.net/) 2.1.5. The `unstable' distribution ---------------------------------- Package entries for the `unstable' distribution, `sid', are recorded into the `unstable' (symlink to `sid') directory after they are uploaded to the Debian archive and stay here until they are moved to `testing'. New physical packages are located under the `pool' directory (Section 2.1.10, `The `pool' directory'). There are also `main', `contrib' and `non-free' subdirectories in `unstable', which serve the same functions as in `stable'. The `unstable' distribution contains a snapshot of the most current development system. Users are welcome to use and test these packages, but are warned about their state of readiness. The advantage of using the `unstable' distribution is that you are always up-to-date with the latest in the Debian software project---but if it breaks, you get to keep both parts :-) The current status of `unstable' distribution bugs is reported on the Unstable Problems (http://ftp-master.debian.org/testing/unstable_probs.html) Web page. 2.1.6. The `frozen' distribution -------------------------------- When the `testing' distribution is mature enough, it becomes frozen, meaning no new code is accepted anymore, just bugfixes, if necessary. Also, a new testing tree is created in the `dists' directory, assigned a new codename. The frozen distribution passes through a few months of testing, with intermittent updates and deep freezes called "test cycles". (The recent `woody' release process did not create a symbolic link `frozen', so `frozen' was not a distribution but just a development stage of the `testing' distribution.) We keep a record of bugs in the frozen distribution that can delay a package from being released or bugs that can hold back the whole release. Once that bug count lowers to maximum acceptable values, the frozen distribution becomes stable, it is released, and the previous stable distribution becomes obsolete (and moves to the archive). 2.1.7. Debian distribution codenames ------------------------------------ Physical directory names in the `dists' directory, such as `Woody' and `Sarge', are just "codenames". When a Debian distribution is in the development stage, it has no version number, but a codename instead. The purpose of these codenames is to make the mirroring of the Debian distributions easier (if a real directory like `unstable' suddenly changed its name to `stable', a lot of stuff would have to be needlessly downloaded again). Currently, `stable' is a symbolic link to `Woody', and `testing' is a symbolic link to `Sarge'. This means that `Woody' is the current stable distribution and `Sarge' is the current testing distribution. `unstable' is a permanent symbolic link to `sid', as `sid' is always the unstable distribution. 2.1.8. Codenames used in the past --------------------------------- Other codenames that have already been used are: `buzz' for release 1.1, `rex' for release 1.2, `bo' for releases 1.3.x, `hamm' for release 2.0, `slink' for release 2.1, and `potato' for release 2.2. 2.1.9. The source for codenames ------------------------------- So far they have been characters taken from the movie _Toy Story_ by Pixar. * _Buzz_ (Buzz Lightyear) was the spaceman, * _Rex_ was the tyrannosaurus, * _Bo_ (Bo Peep) was the girl who took care of the sheep, * _Hamm_ was the piggy bank, * _Slink_ (Slinky Dog) was the toy dog, * _Sarge_ was a leader of the Green Plastic Army Men, * _Potato_ was, of course, Mr. Potato Head, * _Woody_ was the cowboy. * _Sid_ was a boy next door who destroyed toys. 2.1.10. The `pool' directory ---------------------------- Historically, packages were kept in the subdirectory of `dists' corresponding to the distribution that contained them. This turned out to cause various problems, such as large bandwidth consumption on mirrors when major changes were made. Packages are now kept in a large "pool", structured according to the name of the source package. To make this manageable, the pool is subdivided by section (`main', `contrib' and `non-free') and by the first letter of the source package name. These directories contain several files: the binary packages for each architecture, and the source packages from which the binary packages were generated. You can find out where each package is placed by executing a command like `apt-cache showsrc ' and looking at the "Directory:" line. For example, the `apache' packages are stored in `pool/main/a/apache/'. Since there are so many `lib*' packages, these are treated specially: for instance, `libpaper' packages are stored in `pool/main/libp/libpaper/'. The `dists' directories are still used for the index files used by programs like `apt'. Also, at the time of writing, older distributions have not been converted to use pools, so you'll see paths containing distribution names such as `potato' or `woody' in the "Filename" header field. Normally, you won't have to worry about any of this, as new `apt' and probably older `dpkg-ftp' (see Section 2.3.1, `Methods for upgrading a Debian system') will handle it seamlessly. If you want more information, see the Debian Package Pools FAQ (http://people.debian.org/~joeyh/poolfaq). 2.1.11. Historical notes about `sid' ------------------------------------ When the present-day `sid' did not exist, the Debian archive site organization had one major flaw: there was an assumption that when an architecture was created in the current `unstable', it would be released when that distribution became the new `stable'. For many architectures that wasn't the case, with the result that those directories had to be moved at release time. This was impractical because the move would chew up lots of bandwidth. The archive administrators worked around this problem for several years by placing binaries for unreleased architectures in a special directory called `sid'. For those architectures not yet released, the first time they were released there was a link from the current `stable' to `sid', and from then on they were created inside the `unstable' tree as usual. This layout was somewhat confusing to users. With the advent of package pools (see Section 2.1.10, `The `pool' directory') during the `woody' distribution development, binary packages began to be stored in a canonical location in the pool, regardless of the distribution, so releasing a distribution no longer causes large bandwidth consumption on the mirrors (there is, however, a lot of gradual bandwidth consumption throughout the development process). 2.1.12. Uploaded packages in `incoming' --------------------------------------- Uploaded packages are first located at http://incoming.debian.org/ after being checked to insure that they really come from a Debian developer (and are put in the `DELAYED' subdirectory in the case of a Non-Maintainer Upload (NMU)). Once a day, they are moved out of `incoming' to `unstable'. In an emergency, you may want to install packages from `incoming' before they reach `unstable'. 2.1.13. Retrieving an older package ----------------------------------- While the most recent Debian distributions are kept under the `debian' directory on each Debian mirror site (http://www.debian.org/misc/README.mirrors), archives for older Debian distributions such as Slink are kept on http://archive.debian.org/ or under the `debian-archive' directory on each Debian mirror site. Older `testing' and `unstable' packages can be located at http://snapshot.debian.net/. 2.1.14. Architecture sections ----------------------------- Within each of the major directory trees (`dists/stable/main', `dists/stable/contrib', `dists/stable/non-free', `dists/unstable/main/', etc.), the binary package entries reside in subdirectories whose names indicate the chip architecture for which they were compiled. * `binary-all/', for packages which are architecture-independent. These include, for example, Perl scripts, or pure documentation. * `binary-/', for packages which execute on a particular binary platform. Please note that the actual binary packages for `testing' and `unstable' no longer reside in these directories, but in the top-level `pool' directory. The index files (`Packages' and `Packages.gz') have been kept, though, for backwards compatibility. For the actual binary architectures supported, see the Release Notes for each distribution. They can be located at the Release Notes sites for stable (http://www.debian.org/releases/stable/releasenotes) and testing (http://www.debian.org/releases/testing/releasenotes). 2.1.15. The source code ----------------------- Source code is included for everything in the Debian system. Moreover, the license terms of most programs in the system _require_ that source code be distributed along with the programs, or that an offer to provide the source code accompany the programs. Normally the source code is distributed in the `source' directories, which are parallel to all the architecture-specific binary directories, or more recently in the `pool' directory (see Section 2.1.10, `The `pool' directory'). To retrieve the source code without having to be familiar with the structure of the Debian archive, try a command like `apt-get source '. Some packages, notably `pine', are only available in a source package due to their licensing limitations. (Recently the `pine-tracker' package has been provided to facilitate Pine installation.) The procedures described in Section 6.3.9, `Port a package to the `stable' system' and Section 13.9, `Packaging' provide ways to build a package manually. Source code may or may not be available for packages in the `contrib' and `non-free' directories, which are not formally part of the Debian system. 2.2. The Debian package management system ----------------------------------------- 2.2.1. Overview of Debian packages ---------------------------------- Packages generally contain all of the files necessary to implement a set of related commands or features. There are two types of Debian packages: * _Binary packages_, which contain executables, configuration files, man/info pages, copyright information, and other documentation. These packages are distributed in a Debian-specific archive format (see Section 2.2.2, `Debian package format'); they are usually distinguished by having a `.deb' file extension. Binary packages can be unpacked using the Debian utility `dpkg'; details are given in its manual page. * _Source packages_, which consist of a `.dsc' file describing the source package (including the names of the following files), a `.orig.tar.gz' file that contains the original unmodified source in gzip-compressed tar format, and usually a `.diff.gz' file that contains the Debian-specific changes to the original source. The utility `dpkg-source' packs and unpacks Debian source archives; details are provided in its manual page. Installation of software by the package system uses "dependencies" which are carefully designed by the package maintainers. These dependencies are documented in the `control' file associated with each package. For example, the package containing the GNU C compiler (`gcc') "depends" on the package `binutils' which includes the linker and assembler. If a user attempts to install `gcc' without having first installed `binutils', the package management system (dpkg) will send an error message that it also needs `binutils', and stop installing `gcc'. (However, this facility can be overridden by the insistent user; see dpkg(8).) For additional details, see Section 2.2.8, `Package dependencies' below. Debian's packaging tools can be used to: * manipulate and manage packages or parts of packages, * aid the user in the splitting of packages that must be transmitted through a limited-size medium such as floppy disks, * aid developers in the construction of package archives, and * aid users in the installation of packages which reside on a remote Debian archive site. 2.2.2. Debian package format ---------------------------- A Debian "package", or a Debian archive file, contains the executable files, libraries, and documentation associated with a particular program suite or set of related programs. Normally, a Debian archive file has a filename that ends in `.deb'. The internals of this Debian binary package format are described in the deb(5) manual page. Because this internal format is subject to change (between major releases of Debian), always use dpkg-deb(8) for manipulating `.deb' files. Through at least the Woody distribution, all Debian archive files have been manipulable by the standard Unix commands `ar' and `tar', even when dpkg commands are not available. 2.2.3. Naming conventions for Debian package filenames ------------------------------------------------------ The Debian package filenames conform to the following convention: _-.deb where represents the package name. As a check, one can determine the package name associated with a particular Debian archive file (`.deb' file) in one of these ways: * inspect the "Packages" file in the directory where it was stored at a Debian archive site. This file contains a stanza describing each package; the first field in each stanza is the formal package name. * use the command `dpkg --info .deb' (where and are the version and revision of the package in question, respectively). This displays, among other things, the package name corresponding to the archive file being unpacked. The component is the version number specified by the upstream developer. There are no standards governing version numbers, so they may have formats as different as "19990513" and "1.3.8pre1". The component is the Debian revision number, and is specified by the Debian developer (or an individual user if he chooses to build the package himself). This number corresponds to the revision level of the Debian package; thus, a new revision level usually signifies changes in the Debian makefile (`debian/rules'), the Debian control file (`debian/control'), the installation or removal scripts (`debian/p*'), or in the configuration files used with the package. 2.2.4. Preservation of the local configuration ---------------------------------------------- Preservation of user-configurable files is enabled through Debian's "conffiles" mechanism. User configuration files (usually placed in `/etc') are specified in the `conffiles' within the Debian package system. The package management system guarantees not to overwrite these files when the package is upgraded. When it is possible to configure the system without modifying files that belong to various Debian packages, it is usually a good idea not to modify them even if they are "conffiles". This ensures faster and smoother upgrade operations. To determine exactly which files are preserved during an upgrade, run: dpkg --status and look under "Conffiles:". Specifics regarding the contents of a Debian `conffiles' file are provided in the Debian Policy Manual, section 11.7 (see Section 15.1, `References'). 2.2.5. Debian maintenance scripts --------------------------------- Debian maintenance scripts are executable scripts which are automatically run before or after a package is installed. Along with a file named `control', all of these files are part of the "control" section of a Debian archive file. The individual files are: preinst This script executes before its package is unpacked from its Debian archive (`.deb') file. Many "preinst" scripts stop services for packages which are being upgraded until their installation or upgrade is completed (following the successful execution of the "postinst" script). postinst This script typically completes any required configuration of a package once it has been unpacked from its Debian archive (`.deb') file. Often, "postinst" scripts ask the user for input, and/or warn the user that if he accepts default values, he should remember to go back and reconfigure the package as the situation warrants. Many "postinst" scripts then execute any commands necessary to start or restart a service once a new package has been installed or upgraded. prerm This script typically stops any daemons which are associated with a package. It is executed before the removal of files associated with the package. postrm This script typically modifies links or other files associated with a package, and/or removes files created by it. (Also see Section 2.2.7, `Virtual packages'.) Currently all of the control files can be found in the directory `/var/lib/dpkg/info'. The files relevant to package `foo' begin with the name "foo" and have file extensions of "preinst", "postinst", etc., as appropriate. The file `foo.list' in that directory lists all of the files that were installed with the package `foo'. (Note that the location of these files is a dpkg internal, and may be subject to change.) 2.2.6. Package priorities ------------------------- Each Debian package is assigned a _priority_ by the distribution maintainers, as an aid to the package management system. The priorities are: * _Required_ packages are necessary for the proper functioning of the system. This includes all tools that are necessary to repair system defects. You must not remove these packages or your system may become totally broken and you may not even be able to use `dpkg' to put restore things. Systems with only the Required packages are probably inadequate for most purposes, but they do have enough functionality to allow the sysadmin to boot and install more software. * _Important_ packages should be found on any Unix-like system. Other packages without which the system will not run well or be usable will carry this priority. This does _not_ include Emacs or X11 or TeX or any other large applications. These packages only constitute the bare infrastructure. * _Standard_ packages are standard on any Linux system, including a reasonably small but not too limited character-mode system. This is what will install by default if users do not select anything else. "Standard" does not include many large applications, but it does include Emacs (this is more a piece of infrastructure than an application) and a reasonable subset of TeX and LaTeX (if this turns out to be possible without X). * _Optional_ packages include all those that you might reasonably want to install even if you are unfamiliar with them, and if you don't have have specialized requirements. This includes X11, a full TeX distribution, and lots of applications. * _Extra_ packages either conflict with others with higher priorities, are only likely to be useful if you already know what they are, or have specialized requirements that make them unsuitable for "Optional". 2.2.7. Virtual packages ----------------------- A virtual package is a generic name that applies to any one of a group of packages, all of which provide similar basic functionality. For example, both the `tin' and `trn' programs are news readers, and either one should therefore satisfy any dependency of a program that requires a news reader on a system in order to work or to be useful. They are therefore both said to provide the "virtual package" called `news-reader'. Similarly, `exim' and `sendmail' both provide the functionality of a mail transport agent. They are therefore said to provide the virtual package "mail transport agent". If either one is installed, then any program depending on the installation of a `mail-transport-agent' will be satisfied by the existence of this virtual package. Debian has a mechanism so that, if more than one package which provides the same virtual package is installed on a system, the system administrator can set one as the preferred package. The relevant command is `update-alternatives', and is described further in Section 6.4.3, `Alternative commands'. 2.2.8. Package dependencies --------------------------- The Debian package system has a range of package "dependencies" which are designed to indicate (in a single flag) the level at which Program A can operate independently of the existence of Program B on a given system: * Package A _depends_ on Package B if B absolutely must be installed in order to run A. In some cases, A depends not only on B, but on a specific version of B. In this case, the version dependency is usually a lower limit, in the sense that A depends on any version of B more recent than some specified version. * Package A _recommends_ Package B if the package maintainer judges that most users would not want A without also having the functionality provided by B. * Package A _suggests_ Package B if B contains files that are related to (and usually enhance) the functionality of A. * Package A _conflicts_ with Package B when A will not operate if B is installed on the system. Most often, conflicts are cases where A contains files which are an improvement over those in B. "Conflicts" status is often combined with "replaces". * Package A _replaces_ Package B when files installed by B are removed and (in some cases) overwritten by files in A. * Package A _provides_ Package B when all of the files and functionality of B are incorporated into A. This mechanism provides a way for users with constrained disk space to get only that part of package A which they really need. More detailed information on the use of each these terms can be found in the Packaging Manual and the Policy Manual. Note that `dselect' has more fine-grained control over packages specified by _recommends_ and _suggests_ than `apt-get', which simply pulls all the packages specified by _depends_ and leaves all the packages specified by _recommends_ and _suggests_. Both programs in modern form use APT as their back end. 2.2.9. The meaning of "pre-depends" ----------------------------------- "Pre-depends" is a special dependency. In the case of an ordinary package, `dpkg' will unpack its archive file (i.e., its `.deb' file) independently of whether or not the files on which it depends exist on the system. Unpacking basically means that `dpkg' will extract the files from the archive file that were meant to be installed on your file system, and put them in place. If those packages _depend_ on the existence of some other packages on your system, `dpkg' will refuse to complete the installation (by executing its "configure" action) until the other packages are installed. However, there are some packages that `dpkg' will refuse even to unpack until certain dependencies are resolved. Such packages are said to "pre-depend" on the presence of some other package(s). The Debian project provided this mechanism to support the safe upgrading of systems from `a.out' format to ELF format, where the _order_ in which packages were unpacked was critical. There are other large upgrade situations where this method is useful, e.g., for packages with "required" priority and their libc dependency. Once again, more detailed information about this can be found in the Packaging Manual. 2.2.10. Package status ---------------------- Package status can be "unknown", "install", "remove", "purge", or "hold". These "want" flags indicate what the user wanted to do with a package (either by making choices in the "Select" section of `dselect', or by directly invoking `dpkg'). Their meanings are: * _unknown_ - the user has never indicated whether he wants the package. * _install_ - the user wants the package installed or upgraded. * _remove_ - the user wants the package removed, but does not want to remove any existing configuration files. * _purge_ - the user wants the package to be removed completely, including its configuration files. * _hold_ - the user wants this package not to be processed, i.e., he wants to keep the current version with the current status, whatever that is. 2.2.11. Holding back packages from an upgrade --------------------------------------------- There are two mechanisms for holding back packages from an upgrade, through `dpkg', or, in Woody, through APT. With `dpkg', first export the list of package selections: dpkg --get-selections \* > Then edit the resulting file `', changing the line containing the package you wish to hold, e.g. `libc6', from this: libc6 install to this: libc6 hold Save the file, and reload it into `dpkg' database with: dpkg --set-selections < Or, if you know the package name to hold, simply run: echo libc6 hold | dpkg --set-selections This procedure holds packages at the install process of each package file. The same effect can be obtained through `dselect'. Simply enter the [S]elect screen, find the package you wish to hold in its present state, and press the `=' key (or `H'). The changes will take effect immediately after you exit the [S]elect screen. The APT system in the Woody distribution has a new alternative mechanism for holding packages during the archive retrieval process using `Pin-Priority'. See the manual page apt_preferences(5), along with http://www.debian.org/doc/manuals/apt-howto/ or the `apt-howto' package. 2.2.12. Source packages ----------------------- Source packages are distributed in a directory called `source', and you can either download them manually, or use apt-get source to fetch them (see the apt-get(8) manual page on how to set up APT for doing that). 2.2.13. Building binary packages from a source package ------------------------------------------------------ For a package `', you will need all of `.dsc', `.tar.gz' and `.gz' to compile the source (note: there is no `.diff.gz' for a Debian native package). Once you have them, if you have the `dpkg-dev' package installed, the command $ dpkg-source -x .dsc will extract the package into a directory called `'. If you want just to compile the package, you may cd into the `foo-version' directory and issue the command $ fakeroot debian/rules build to build the program (you may need to install the `fakeroot' package first), then $ fakeroot debian/rules binary to build the package as root, and then # su -c "dpkg -i ../.deb" to install the newly built package. See Section 6.3.9, `Port a package to the `stable' system'. 2.2.14. Creating new Debian packages ------------------------------------ For detailed information on creating new packages, read the New Maintainers' Guide, available in the `maint-guide' package, or at http://www.debian.org/doc/manuals/maint-guide/. 2.3. Upgrading a Debian system ------------------------------ One of Debian's goals is to provide a consistent upgrade path and a secure upgrade process, and we always do our best to make a new release smoothly upgradable from the previous ones. Packages will alert the user when there are important notices during the upgrade process, and will often provide a solution to a possible problem. You should also read the Release Notes, the document that describes the details of specific upgrades, shipped on all Debian CDs, and available on the WWW at http://www.debian.org/releases/stable/releasenotes or http://www.debian.org/releases/testing/releasenotes. A practical guide to upgrades is provided in Chapter 6, `Debian package management'. This section describes the fundamental details. 2.3.1. Methods for upgrading a Debian system -------------------------------------------- One can always simply execute an anonymous FTP or `wget' call to a Debian archive, peruse the directories until one finds a desired file, fetch it, and finally install it using `dpkg'. (Note that `dpkg' will install upgrade files in place, even on a running system.) Sometimes, however, a revised package will require the installation of a newly revised version of another package, in which case the installation will fail until/unless the other package is installed. Many people find this manual approach much too time-consuming, since Debian evolves so quickly --- typically, a dozen or more new packages are uploaded every week. This number is larger just before a new major release. To deal with this avalanche, many people prefer to use an automated program for upgrading. Several specialized package management tools are available for this purpose. 2.3.2. Package management tools overview ---------------------------------------- The Debian package management system has two objectives: the manipulation of the package file itself and the retrieval of package files from the Debian archive. `dpkg' performs the former task, APT and `dselect' the latter. 2.3.3. `dpkg' ------------- This is the main program for manipulating package files; read dpkg(8) for a full description. `dpkg' comes with several primitive supplemental programs. * dpkg-deb: Manipulate `.deb' files. dpkg-deb(1) * dpkg-ftp: An older package file retrieval command. dpkg-ftp(1) * dpkg-mountable: An older package file retrieval command. dpkg-mountable(1) * dpkg-split: Splits a large package into smaller files. dpkg-split(1) `dpkg-ftp' and `dpkg-mountable' have been superseded by the introduction of the APT system. 2.3.4. APT ---------- APT (the Advanced Packaging Tool) is an advanced interface to the Debian packaging system consisting of several programs whose names typically begin with "apt-". `apt-get', `apt-cache' and `apt-cdrom' are the command-line tools for handling packages. These also function as the user's "back-end" programs to other tools, such as `dselect' and `aptitude'. For more information, install the `apt' package and read apt-get(8), apt-cache(8), apt-cdrom(8), apt.conf(5), sources.list(5), apt_preferences(5) (woody), and `/usr/share/doc/apt/guide.html/index.html'. An alternative source of information is the APT HOWTO (http://www.debian.org/doc/manuals/apt-howto/). This can be installed by `apt-howto' at `/usr/share/doc/apt-howto/en/apt-howto-en.html/index.html'. `apt-get upgrade' and `apt-get dist-upgrade' pull only the packages listed under "Depends:" and overlook all the packages listed under "Recommends:" and "Suggests:". To avoid this, use `dselect'. 2.3.5. `dselect' ---------------- This program is a menu-driven user interface to the Debian package management system. It is particularly useful for first-time installations and large-scale upgrades. See Section 6.3.6, ``dselect' -- global configuration'. For more information, install the `install-doc' package and read `/usr/share/doc/install-doc/dselect-beginner.en.html' or dselect Documentation for Beginners (http://www.debian.org/releases/woody/i386/dselect-beginner). 2.3.6. Upgrading a running system --------------------------------- The kernel (file system) in Debian systems supports replacing files even while they're being used. We also provide a program called `start-stop-daemon' which is used to start daemons at boot time or to stop daemons when the kernel runlevel is changed (e.g., from multi-user to single-user or to "halt"). The same program is used by installation scripts when a new package containing a daemon is installed, to stop running daemons, and to restart them as necessary. Note that the Debian system does not require use of the single-user mode to upgrade a running system. 2.3.7. Downloaded and cached `.deb' archive files ------------------------------------------------- If you have manually downloaded package files to your disk (which is not absolutely necessary, see above for the description of `dpkg-ftp' or APT), then after you have installed the packages, you can remove the `.deb' files from your system. If APT is used, these files are cached in the `/var/cache/apt/archives/' directory. You may erase them after installation (`apt-get clean') or copy them to another machine's `/var/cache/apt/archives/' directory to save downloading during subsequent installations. 2.3.8. Record-keeping for upgrades ---------------------------------- `dpkg' keeps a record of the packages that have been unpacked, configured, removed, and/or purged, but does not (currently) keep a log of terminal activity that occurred while a package was being so manipulated. The simplest way to work around this is to run your `dpkg', `dselect', `apt-get', etc., sessions within the script(1) program. 2.4. The Debian boot process ---------------------------- 2.4.1. The `init' program ------------------------- Like all Unices, Debian boots up by executing the program `init'. The configuration file for `init' (which is `/etc/inittab') specifies that the first script to be executed should be `/etc/init.d/rcS'. This script runs all of the scripts in `/etc/rcS.d/' by sourcing or forking a subprocess depending on their file extension to perform initialization such as checking and mounting file systems, loading modules, starting the network services, setting the clock, and performing other initialization. Then, for compatibility, it also runs the files (except those with a `.' in the filename) in `/etc/rc.boot/'. Any scripts in the latter directory are usually reserved for system administrator use, and using them in packages is deprecated. See Section 9.1, `System initialization hints' for more info. 2.4.2. Runlevels ---------------- After completing the boot process, `init' executes all start scripts in a directory specified by the default runlevel (this runlevel is given by the entry for `id' in `/etc/inittab'). Like most System V compatible Unices, Linux has 7 runlevels: * 0 (halt the system), * 1 (single-user mode), * 2 through 5 (various multi-user modes), and * 6 (reboot the system). Debian systems come with `id=2', which indicates that the default runlevel will be 2 when the multi-user state is entered, and the scripts in `/etc/rc2.d/' will be run. In fact, the scripts in any of the directories `/etc/rc.d/' are just symbolic links back to scripts in `/etc/init.d/'. However, the _names_ of the files in each of the `/etc/rc.d/' directories are selected to indicate the _way_ the scripts in `/etc/init.d/' will be run. Specifically, before entering any runlevel, all the scripts beginning with `K' are run; these scripts kill services. Then all the scripts beginning with `S' are run; these scripts start services. The two-digit number following the `K' or `S' indicates the order in which the script is run. Lower-numbered scripts are executed first. This approach works because the scripts in `/etc/init.d/' all take an argument which can be either "start", "stop", "reload", "restart" or "force-reload" and will then do the task indicated by the argument. These scripts can be used even after a system has been booted, to control various processes. For example, with the argument "reload" the command # /etc/init.d/sendmail reload sends the sendmail daemon a signal to reread its configuration file. 2.4.3. Customizing the boot process ----------------------------------- Debian does not use a BSD-style `rc.local' directory to customize the boot process; instead it provides the following mechanism for customization. Suppose a system needs to execute script `foo' on start-up, or on entry to a particular (System V) runlevel. Then the system administrator should: 1. Enter the script `foo' into the directory `/etc/init.d/'. 2. Run the Debian command `update-rc.d' with appropriate arguments, to set up links between the (command-line-specified) directories `rc.d' and `/etc/init.d/foo'. Here, is a number from 0 through 6 that corresponds to one of the System V runlevels. 3. Reboot the system. The command `update-rc.d' will set up links between files in the directories `rc.d' and the script in `/etc/init.d/'. Each link will begin with an `S' or a `K', followed by a number, followed by the name of the script. Scripts beginning with `S' in `/etc/rc.d/' are executed when runlevel is entered. Scripts beginning with a `K' are executed when leaving runlevel . One might, for example, cause the script `foo' to execute at boot-up, by putting it in `/etc/init.d/' and installing the links with `update-rc.d foo defaults 19'. The argument `defaults' refers to the default runlevels, which are 2 through 5. The argument `19' ensures that `foo' is called before any scripts containing numbers 20 or larger. 2.5. Supporting diversity ------------------------- Debian offers several avenues to accommodate any wishes of the system administrator without breaking the system. * `dpkg-divert', see Section 6.4.1, `The `dpkg-divert' command'. * `equivs', see Section 6.4.2, `The `equivs' package'. * `update-alternative', see Section 6.4.3, `Alternative commands'. * `make-kpkg' can accommodate many boot loaders. See make-kpkg(1) and Section 7.1.1, `Debian standard method'. Any files under `/usr/local/' belong to the system administrator and Debian will not touch them. Most (or all) files under `/etc' are `conffiles' and Debian will not overwrite them upon upgrade unless the system administrator requests so explicitly. 2.6. Internationalization ------------------------- The Debian system is internationalized and provides support for character display and entry in many languages, both within the console and under X. Many documents, manual pages, and system messages have been translated into a growing number of languages. During installation, Debian prompts the user to choose an installation language (and sometimes a local language variant). If your installed system does not support all the language features you need, or if you need to change languages or install a different keyboard to support your language, see Section 9.7, `Localization and national language support'. 2.7. Debian and the kernel -------------------------- See Chapter 7, `The Linux kernel under Debian'. 2.7.1. Compiling a kernel from non-Debian source ------------------------------------------------ One has to understand the Debian policy with respect to headers. The Debian C libraries are built with the most recent _stable_ releases of the _kernel_ headers. For example, the Debian-1.2 release used version 5.4.13 of the headers. This practice contrasts with the Linux kernel source packages distributed at all Linux FTP archive sites, which use even more recent versions of the headers. The kernel headers distributed with the kernel source are located in `/usr/include/linux/include/'. If you need to compile a program with kernel headers that are newer than those provided by `libc6-dev', then you must add `-I/usr/src/linux/include/' to your command line when compiling. This came up at one point, for example, with the packaging of the automounter daemon (`amd'). When new kernels changed some internals dealing with NFS, `amd' needed to know about them. This required the inclusion of the latest kernel headers. 2.7.2. Tools to build custom kernels ------------------------------------ Users who wish to (or must) build a custom kernel are encouraged to download the package `kernel-package'. This package contains the script to build the kernel package, and provides the capability to create a Debian kernel-image package just by running the command # make-kpkg kernel_image in the top-level kernel source directory. Help is available by executing the command # make-kpkg --help and through the manual page make-kpkg(8) and Chapter 7, `The Linux kernel under Debian'. Users must separately download the source code for the most recent kernel (or the kernel of their choice) from their favorite Linux archive site, unless a kernel-source- package is available (where stands for the kernel version). The Debian `initrd' boot script requires a special kernel patch called `initrd'; see http://bugs.debian.org/149236. Detailed instructions for using the `kernel-package' package are given in the file `/usr/doc/kernel-package/README'. 2.7.3. Alternative boot loaders ------------------------------- To employ alternative boot loaders such as `grub' or `loadlin', copy the compiled Linux kernel `bzimage' to other locations (e.g., to `/boot/grub' or to an MS-DOS partition). 2.7.4. Custom boot floppies --------------------------- The task of making a custom boot floppy is greatly aided by the Debian package `boot-floppies', normally found in the `admin' section of the Debian FTP archive. Shell scripts in this package produce boot floppies in `syslinux' format. These are MS-DOS formatted floppies whose master boot records have been altered so that they directly boot Linux (or whatever other operating system has been defined in the `syslinux.cfg' file on the floppy). Other scripts in this package produce emergency root disks and can even reproduce the base disks. You will find more information about this in the `/usr/doc/boot-floppies/README' file after installing the `boot-floppies' package. 2.7.5. Special provisions for dealing with modules -------------------------------------------------- Debian's `modconf' package provides a shell script (`/usr/sbin/modconf') which can be used to customize the configuration of modules. This script presents a menu-based interface, prompting the user for particulars on the loadable device drivers in his system. The responses are used to customize the file `/etc/modules.conf' (which lists aliases, and other arguments that must be used in conjunction with various modules) through files in `/etc/modutils/', and `/etc/modules' (which lists the modules that must be loaded at boot time). Like the (new) Configure.help files that are now available to support the construction of custom kernels, the `modconf' package comes with a series of help files (in `/usr/lib/modules_help/') which provide detailed information on appropriate arguments for each of the modules. See Section 7.2, `The modularized 2.4 kernel' for examples. 2.7.6. De-installing an old kernel package ------------------------------------------ The `kernel-image-.prerm' script checks to see whether the kernel you are currently running is the same as the kernel you are trying to de-install. Therefore you can safely remove unwanted kernel image packages using this command: dpkg --purge --force-remove-essential kernel-image- (Replace with your kernel version and revision number, of course.) ------------------------------------------------------------------------------- 3. Debian System installation hints ----------------------------------- Official documentation for installing Debian is located at http://www.debian.org/releases/stable/, and http://www.debian.org/releases/stable/installmanual. The development versions are located at http://www.debian.org/releases/testing/, and http://www.debian.org/releases/testing/installmanual (work in progress, sometimes this may not exist). Although "Debian Reference" was written during the days of the Potato release, most of its contents have been updated to Debian Woody (3.0r0) and Debian Sarge. 3.1. General Linux system installation hints -------------------------------------------- In order to minimize risks associated with "testing" and "unstable" packages, it is a good practice to set up your main Linux system for dual booting along with another small stable Linux system. 3.1.1. Hardware compatibility basics ------------------------------------ Linux is compatible with most PC hardware and can be installed to almost any system. For me it was as easy as installing Windows 95/98/Me. The hardware compatibility list just seems to keep growing. If you have a laptop PC, check Linux on Laptops (http://www.linux-laptop.net/) for installation pointers by brand and model. My recommendation for desktop PC hardware is "Just be conservative": * SCSI rather than IDE for work, IDE/ATAPI HD for private use. * IDE/ATAPI CD-ROM (or CD-RW). * PCI rather than ISA, especially for the network card (NIC). * Use a cheap NIC. Tulip for PCI, NE2000 for ISA are good. * Avoid PCMCIA (notebook) as your first Linux install. * No USB keyboard, mouse . . . unless you want a challenge. If you have a slow machine, yanking out the hard drive and plugging it into another faster machine for installation is a good idea. 3.1.2. Determining a PC's hardware and chip set ----------------------------------------------- During installation, one will be asked to identify the hardware or chip set of the PC. Sometimes that information may not seem easy to find. Here is one method: 1. Open your PC's case and look inside. 2. Record the numbers on the large chips on the graphics card, network card, chip near serial ports, chip near IDE ports. 3. Record card names printed on the back of the PCI and ISA cards. 3.1.3. Determining a PC's hardware via Debian --------------------------------------------- The following commands on a Linux system should give some idea of actual hardware and configuration. $ /sbin/lspci -v |pager $ pager /proc/pci $ pager /proc/interrupts $ pager /proc/ioports These commands can be run during the install process from the console screen by pressing ALT-F2. 3.1.4. Determining a PC's hardware via other OSs ------------------------------------------------ Hardware information can also be obtained from other OSs. Install another commercial Linux distribution. Hardware detection on those tends to be better than on Debian as of now. This may change as Woody evolves. Install Windows. Hardware configuration can be obtained by right-clicking "My Computer" to get to Properties / Device Manager. Record all resource information such as IRQ, I/O port address, and DMA. Some old ISA cards may need to be configured under DOS and used accordingly. 3.1.5. A Lilo myth ------------------ Lilo is limited to 1024 cylinders. ---WRONG ! The newer `lilo' used after Debian Potato has lba32 support. If the BIOS of your motherboard is recent enough to support lba32, `lilo' should be able to load beyond the old 1024-cylinder limitation. Just make sure to add a line reading "lba32" somewhere near the beginning of your `lilo.conf' file if you have kept an old `lilo.conf.' 3.1.6. Choice of boot floppies ------------------------------ For Potato, I liked the IDEPCI disk set for normal install to a desktop. For Woody, I like the bf2.4 boot disk set. They both use a version of `boot-floppies' to create boot floppies. If you have a PCMCIA network card, you need to use the standard boot disk set (largest number of floppies but all driver modules available) and configure the NIC in the PCMCIA setup; do not try to set up an NIC card in the standard network setup dialogue. For special systems, you may need to create a custom rescue disk. This can be done by replacing the kernel image named "linux" on the Debian rescue disk by overwriting it with another compressed kernel image compiled off-site for the machine. Details are documented in `readme.txt' on the rescue disk. The rescue floppy uses the MS-DOS file system, so you can use any system to read and edit it. This should make life easier for people with a special network card, etc. For Sarge, `debian-installer' and/or `pgi' is expected to be used for creating boot floppies. 3.1.7. Installation ------------------- Follow the official instructions found in http://www.debian.org/releases/stable/installmanual or http://www.debian.org/releases/testing/installmanual (work in progress, sometimes this may not exist). If you are installing a system using boot floppies in the testing distribution, you may need to open a console terminal during the install process by pressing `ALT-F2' and manually edit `/etc/sources.list' entries from `stable' to `testing' to adjust APT sources. I tend to install `lilo' into places like `/dev/hda3', while installing `mbr' into `/dev/hda'. This minimizes the risk of overwriting boot information. Here is what I choose during the install process. * MD5 passwords "yes" * shadow passwords "yes" * Install "advanced" (dselect **) and select * Exclude emacs (if selected), nvi, tex, telnet, talk(d); * Include mc, vim, either one of nano-tiny or elvis-tiny. See Section 6.3.6, ``dselect' -- global configuration'. Even if you are an Emacs fan, avoid it now and be content with nano during install. Also avoid installing other large packages such as TEX (Potato used to do this) at this stage. See Section 11.2, `Rescue editors' for the reason for installing nano-tiny or elvis-tiny here. * All configuration questions = "y" (replace current) during each package install dialog. * `exim': select 2 for machine since I send mail through my ISP's SMTP server. For more information on dselect, see Section 6.3.6, ``dselect' -- global configuration'. 3.1.8. Hosts and IP to use for LAN ---------------------------------- Example of LAN configuration (C subnet: 192.168.1.0/24): Internet | +--- External ISP provides POP service (accessed by fetchmail) | Access point ISP provides DHCP service and SMTP relay service | : Cable modem (Dial-up) | : LAN Gateway machine external port: eth0 (IP given by ISP's DHCP) use old notebook PC (IBM Thinkpad, 486 DX2 50 MHz, 20 MB RAM) run Linux 2.4 kernel with ext3 file system. run "ipmasq" package (with stronger patch, NAT and firewall) run "dhcp-client" package configured for eth0 (override DNS setting) run "dhcp" package configured for eth1 run "exim" as the smarthost (mode 2) run "fetchmail" with a long interval (fallback) run "bind" as the cache nameserver for Internet from LAN as authoritative nameserver for LAN domain from LAN run "ssh" on port 22 and 8080 (connect from anywhere) run "squid" as the cache server for the Debian archive (for APT) LAN Gateway machine internal port: eth1 (IP = 192.168.1.1, fixed) | +--- LAN Switch (10 base T) ---+ | | Some fixed IP clients on LAN Some DHCP clients on LAN (IP = 192.168.1.2-127, fixed) (IP = 192.168.1.128-200, dynamic) See Chapter 10, `Building a gateway with a Debian system' for the details of configuring the LAN gateway server. 3.1.9. User accounts -------------------- In order to have a consistent feel across machines, the first few accounts are always the same in my system. I always create a first user account with a name like "admin" (uid=1000). I forward all root email there. This account is given membership in the `adm' group (see Section 9.2.2, `"Why GNU `su' does not support the `wheel' group"'), which can be given a good amount of root privilege through `su' using PAM or the `sudo' command. See Section 4.2.2, `Add a user account' for details. 3.1.10. Creating file systems ----------------------------- 3.1.10.1. Hard disk partition ----------------------------- I prefer to use different partitions for different directory trees to limit damage upon system crash. E.g., / == (/ + /boot + /bin + /sbin) == 50MB+ /tmp == 100MB+ /var == 100MB+ /home == 100MB+ /usr == 700MB+ with X /usr/local == 100MB The size of the `/usr' directory is very dependent on X-window applications and documentation. `/usr' can be 300MB if one runs a console terminal only, whereas 2GB--3GB is not an unusual size if one has installed many Gnome applications. When `/usr' grows too big, moving out `/usr/share/' to a different partition is the most effective cure. With the new large prepackaged Linux 2.4 kernels, `/' may need more than 200MB. For example, the current status of my Internet gateway machine is as follows (output of the `df -h' command): Filesystem Size Used Avail Use% Mounted on /dev/hda3 300M 106M 179M 38% / /dev/hda7 100M 12M 82M 13% /home /dev/hda8 596M 53M 513M 10% /var /dev/hda6 100M 834k 94M 1% /var/lib/cvs /dev/hda9 596M 222M 343M 40% /usr /dev/hda10 596M 130M 436M 23% /var/cache/apt/archives /dev/hda11 1.5G 204M 1.2G 14% /var/spool/squid (The large area reserved for `/var/spool/squid' is for a proxy cache for package downloading.) Following is `fdisk -l' output to provide an idea of partition structure: # fdisk -l /dev/hda # comment /dev/hda1 1 41 309928+ 6 FAT16 # DOS /dev/hda2 42 84 325080 83 Linux # (not used) /dev/hda3 * 85 126 317520 83 Linux # Main /dev/hda4 127 629 3802680 5 Extended /dev/hda5 127 143 128488+ 82 Linux swap /dev/hda6 144 157 105808+ 83 Linux /dev/hda7 158 171 105808+ 83 Linux /dev/hda8 172 253 619888+ 83 Linux /dev/hda9 254 335 619888+ 83 Linux /dev/hda10 336 417 619888+ 83 Linux /dev/hda11 418 629 1602688+ 83 Linux A few unused partitions exist. These are for installing a second Linux distribution or as expansion space for growing directory trees. 3.1.10.2. Mount file systems ---------------------------- Mounting the above file systems properly is accomplished with the following `/etc/fstab': # /etc/fstab: static file system information. # # file system mount point type options dump pass /dev/hda3 / ext2 defaults,errors=remount-ro 0 1 /dev/hda5 none swap sw 0 0 proc /proc proc defaults 0 0 /dev/fd0 /floppy auto defaults,user,noauto 0 0 /dev/cdrom /cdrom iso9660 defaults,ro,user,noauto 0 0 # # keep partition separate /dev/hda7 /home ext2 rw 0 2 /dev/hda8 /var ext2 rw 0 2 /dev/hda6 /var/lib/cvs ext2 rw 0 2 /dev/hda9 /usr ext2 rw 0 2 /dev/hda10 /var/cache/apt/archives ext2 rw 0 2 # very big partition for proxy cache /dev/hda11 /var/spool/squid ext2 rw 0 2 # backup bootable DOS /dev/hda1 /mnt/dos vfat rw,noauto 0 0 # backup bootable Linux system (not done) /dev/hda2 /mnt/linux ext2 rw,noauto 0 0 # # nfs mounts mickey:/ /mnt/mickey nfs ro,noauto,intr 0 0 goofy:/ /mnt/goofy nfs ro,noauto,intr 0 0 # minnie:/ /mnt/minnie smbfs ro,soft,intr,credentials={filename} 0 2 For NFS, I use `noauto,intr' combined with the default `hard' option. This way, it is possible to recover from a hung process due to a dead connection using Control-C. For a Windows machine connected with Samba (smbfs), `rw,auto,soft,intr' may be good idea. See Section 3.5, `Samba configuration'. For a floppy drive, using `noauto,rw,sync,user,exec' instead prevents file corruption after accidental disk eject before unmount, but this slows the write process. 3.1.10.3. Autofs mount ---------------------- Key points to auto mount: * Load the `vfat' module to allow `/etc/auto.misc' to contain `-fstype=auto': # modprobe vfat # prior to the floppy access attempt ... or to automate this settings, # cat >>/etc/modules vfat ^D ... and reboot the system. * Set `/etc/auto.misc' as follows: floppy -fstype=auto,sync,nodev,nosuid,gid=100,umask=000 :/dev/fd0 ... where gid=100 is "users". * Create links in `/home/', `cdrom' and `floppy', that point to `/var/autofs/misc/cdrom' and `/var/autofs/misc/floppy' respectively. * Make as a member of "users" group. 3.1.10.4. NFS mount ------------------- The external Linux NFS server (goofy) resides behind a firewall (gateway). I have a very relaxed security policy on my LAN since I am the only user. To enable NFS access, the NFS server side needs to add `/etc/exports' as follows: # /etc/exports: the access control list for file systems which may be # exported to NFS clients. See exports(5). / (rw,no_root_squash) This is needed to activate the NFS server in addition to installing and activating the NFS server and client. For simplicity, I usually create a single partition of 2GB for an experimental or secondary lazy Linux install. I optionally share swap and `/tmp' partitions for these installs. A multi-partition scheme is too involved for these usages. If only a simple console system is needed, 500MB may be more than sufficient. 3.1.11. DRAM memory guidelines ------------------------------ Following are rough guidelines for DRAM. 4 MB: Bare minimum for Linux kernel to function. 16 MB: Minimum for reasonable console system. 32 MB: Minimum for simple X system. 64 MB: Minimum for X system with GNOME/KDE. 128 MB: Comfortable for X system with GNOME/KDE. 256+MB: Why not if you can afford it? DRAM is cheap. Using the boot option `mem=4m' (or lilo `append="mem=4m"') will show how the system would perform with 4MB of memory installed. A lilo boot parameter is needed for a system containing more than 64MB of memory with an old BIOS. 3.1.12. Swap space ------------------ I use the following guidelines for swap space: * Each swap partition is < 128 MB (if old 2.0 kernel), < 2 GB (in recent kernels) * Total = either (1 to 2 times installed RAM) or (128 MB to 2 GB) as a guideline * Spread them on different drives and mount all of them with `sw,pri=1' options in `/etc/fstab'. This ensures that the kernel does a striping RAID of the swap partitions and offers the maximum swap performance. * Use a central portion of the hard disk when possible. Even if you never need it, some swap space (128MB) is desirable so the system will slow down before it crashes hard with a program which leaks memory. 3.2. Bash configuration ----------------------- I modify shell start-up scripts to my taste across the system: /etc/bash.bashrc Replace with private one /etc/profile Keep distribution copy ( \w -> \W) /etc/skel/.bashrc Replace with private copy /etc/skel/.profile Replace with private copy /etc/skel/.bash_profile Replace with private copy ~/.bashrc Replace with private copy for all accounts ~/.profile Replace with private copy for all accounts ~/.bash_profile Replace with private copy for all accounts See details in my example scripts (examples/). I like a transparent system, so I set `umask' to 002 or 022. `PATH' is set by the following configuration files in this order: /etc/login.defs - before the shell sets PATH /etc/profile (may call /etc/bash.bashrc) ~/.bash_profile (may call ~/.bashrc) 3.3. Mouse configuration ------------------------ 3.3.1. PS2 mice --------------- In the case of a PS/2-connector mouse on an ATX motherboard, the signal flow should be: mouse -> /dev/psaux -> gpm -> /dev/gpmdata = /dev/mouse -> X This allows the keyboard and mouse to be unplugged and reinitialized by restarting gpm upon reconnect. X will stay alive! For a Logitech 3-button _PS2_ mice, configuration combinations should be: /etc/gpm.conf /etc/X11/X86Config or X86Config-4 ============================================================= device=/dev/psaux Section "Pointer" responsiveness= Protocol "IntelliMouse" repeat_type=ms3 Device "/dev/gpmdata" type=ps2auto (Woody) append="" -------------------------------------------------------------- device=/dev/psaux Section "Pointer" responsiveness= Protocol "IntelliMouse" repeat_type=raw Device "/dev/gpmdata" type=ps2auto (Woody) append="" If a normal 2-button PS2 mouse is used, set the X protocol to `Microsoft' and enable `Emulate3Buttons'. For a scroll mouse, you can adjust X to the real protocol, such as `IMPS/2'. Create a symlink `/dev/gpmdata' --> `/dev/mouse' to make some configuration utilities happy. See my example scripts for details (examples/). For some recent thin Toshiba notebook PCs: Activate `gpm' before PCMCIA in the System-V init script. This keeps `gpm' from crashing. Weird but true. 3.3.2. USB mice --------------- Make sure you have: * "Input Core Support" and "Input Core Support/Mouse Support" enabled in the kernel or as modules. * "Support for USB", "Preliminary USB device filesystem", "UHCI or OHCI", and "USB HID Support" enabled in the kernel or as modules. If you're not using devfs, create a device node `/dev/input/mice' with major 13 and minor 63 as follows: # cd /dev # mkdir input # mknod input/mice c 13 63 For Logitech 3-button _USB_ mice, configuration combinations should be: /etc/gpm.conf /etc/X11/X86Config or X86Config-4 =============================================================== device=/dev/input/mice Section "InputDevice" responsiveness= Option "Protocol" "ImPS/2" repeat_type=ms3 Option "Device" "/dev/input/mice" type=ps2 Option "ZAxisMapping" "4 5" append="" EndSection [This USB mouse section was written by Jan Michael C Alonzo .] See Linux USB Project (http://www.linux-usb.org/) for more information. 3.4. NFS configuration ---------------------- Set up NFS by setting `/etc/exports'. # echo "/ *.domainname-for-lan-hosts(rw,no_root_squash,nohide)" \ >> /etc/exports See my example scripts for details (examples/). 3.5. Samba configuration ------------------------ References: * http://www.samba.org/ * `samba-doc' package Setting up Samba with "share" mode is much easier since this creates WfW-type share drives. But it is preferable to set it up with "user" mode. Samba can be configured through `debconf' or `vi': # dpkg-reconfigure --priority= samba # in Woody # vi /etc/samba/smb.conf See my example scripts for details (examples/). Adding a new user to the smbpasswd file can be done via `smbpasswd': $su -c "smbpasswd -a username" Make sure to use encrypted passwords for optimum compatibility. Set `os level' according to the following system equivalences (the larger the number, the higher the priority as server): 0: Samba with a loose attitude (will never become a master browser) 1: Wfw 3.1, Win95, Win98, Win/me? 16: Win NT WS 3.51 17: Win NT WS 4.0 32: Win NT SVR 3.51 33: Win NT SVR 4.0 255: Samba with mighty power Make sure that users are members of the group owning the directory that gives shared access and that the directory path has its execution bit set to access. 3.6. Printer configuration -------------------------- The traditional method is `lpr'/`lpd'. There is a new CUPS(TM) system (Common UNIX Printing System). PDQ is another approach. See the Linux Printing HOWTO (http://www.tldp.org/HOWTO/Printing-HOWTO.html) for more information. 3.6.1. `lpr'/`lpd' ------------------ For the `lpr'/`lpd' type spoolers (`lpr', `lprng', and `gnulpr'), set up `/etc/printcap' as follows if they are connected to a PostScript or text-only printer (the basics): |:\ :sd=/var/spool/lpd/:\ :mx#0:\ :sh:\ :lp=/dev/lp0: Meaning of the above lines: * Head line: --- name of spool, = alias * mx#0 --- max file size unlimited * sh --- suppress printing of burst page header * lp=/dev/lp0 --- local printer device, or port@host for remote This is a good configuration if you are connected to a PostScript printer. Also, when printing from a Windows machine through Samba, this is a good configuration for any Windows-supported printer (no bidirectional communication is supported). You have to select the corresponding printer configuration on the Windows machine. If you do not have a PostScript printer, you need to set up a filtering system using `gs'. There are many auto-configuration tools provided for setting up `/etc/printcap'. Any of these combinations is an option: * `gnulpr', (`lpr-ppd') and `printtool' --- I use this. * `lpr' and `apsfilter' * `lpr' and `magicfilter' * `lprng' and `lprngtool' * `lprng' and `apsfilter' * `lprng' and `magicfilter' In order to run GUI configuration tools such as `printtool', see Section 9.4.7, `Gain root in X' to gain root privilege. Printer spools created with `printtool' use `gs' and act like PostScript printers. So when accessing them, use PostScript printer drivers. On the Windows side, "Apple LaserWriter" is the standard one. 3.6.2. CUPS(TM) --------------- Install the Common UNIX Printing System (or CUPS(TM)): # apt-get install cupsys cupsomatic-ppd # apt-get install cupsys-bsd cupsys-driver-gimpprint Then configure the system using any Web browser: $ http://localhost:631 3.7. Other host installation hints ---------------------------------- 3.7.1. Install a few more packages after initial install -------------------------------------------------------- Once you have made it this far, you have a small but functioning Debian system. It is a good time to install bigger packages. * Run `tasksel'. See Section 6.2.1, `Install with `tasksel''. You may choose these if you need them: * End-user --- X window system * Development --- C and C++ * Development --- Python * Development --- Tcl/Tk * Miscellaneous --- TeX/LaTeX environment * For others --- I prefer to use `tasksel' as a guide by looking into their components listed under and installing them selectively through `dselect'. * Run `dselect'. Here the first thing you may want to do is select your favorite editor and any programs you need. You can install many Emacs variants at the same time. See Section 6.3.6, ``dselect' -- global configuration' and Section 11.1, `Popular editors'. Also you may replace some of the default packages with full-featured ones. * lynx-ssh (instead of lynx) * ... * ... I usually edit `/etc/inittab' for easy shutdown. ... # What to do when CTRL-ALT-DEL is pressed. ca:12345:ctrlaltdel:/sbin/shutdown -t1 -a -h now ... 3.7.2. Modules -------------- Modules for the device drivers are configured during the initial installation. `modconf' provides menu-driven module configuration afterward. This program is quite useful when some modules were left out during the initial installation or a new kernel was installed after the initial installation. All preloading module names need to be listed in `/etc/modules'. I also use `lsmod' and `depmod' to control them manually. Also make sure to add a few lines in `/etc/modules' to handle ip-masquerading (ftp, etc.) for 2.4 kernels. See Section 7.2, `The modularized 2.4 kernel', specifically Section 7.2.3, `Network function'. 3.7.3. CD-RW basic setup ------------------------ Edit the following files: /etc/lilo.conf (add append="hdc=ide-scsi ignore=hdc", run lilo to activate) /dev/cdrom (symlink # cd /dev; ln -sf scd0 cdrom) /etc/modules (add "ide-scsi" and "sg". If needed "sr" after this.) See Section 9.3, `CD-writer' for details. 3.7.4. Large memory and auto power-off -------------------------------------- Edit `/etc/lilo.conf' as follows to set boot-prompt parameters for large memory (for 2.2 kernels) and auto power-off (for apm): append="mem=128M apm=on apm=power-off" Run `lilo' to install these settings. `apm=power-off' is needed for an SMP-kernel. The same can be done directly by entering options at the boot prompt. See Section 8.1.4, `Other boot tricks with the boot prompt'. If apm is compiled as a module, as in Debian default 2.4 kernels, run `# insmod apm power_off=1' after boot or set `/etc/modules' by: # echo "apm power_off=1" >>/etc/modules Alternatively, compiling ACPI support achieves the same goal with newer kernels and seems to be more SMP-friendly (this requires a newer motherboard). The 2.4 kernel on newer motherboards should detect large memory correctly. CONFIG_PM=y CONFIG_ACPI=y ... CONFIG_ACPI_BUSMGR=m CONFIG_ACPI_SYS=m and add the following lines in `/etc/modules' in this order: ospm_busmgr ospm_system Or recompile the kernel with all of the kernel options above set to "y". In any case, none of the boot-prompt parameters are needed with ACPI. 3.7.5. Strange access problems with some websites ------------------------------------------------- Recent Linux kernels enable ECN by default, which may cause access problems with some websites on bad routers. To check ECN status: # cat /proc/sys/net/ipv4/tcp_ecn ... or # sysctl net.ipv4.tcp_ecn To turn it off, use: # echo "0" > /proc/sys/net/ipv4/tcp_ecn ... or # sysctl -w net.ipv4.tcp_ecn=0 To disable TCP ECN on every boot, edit `/etc/sysctl.conf' and add: net.ipv4.tcp_ecn = 0 3.7.6. Dial-up PPP configuration -------------------------------- Install the `pppconfig' package to set up dial-up PPP access. # apt-get install pppconfig # pppconfig ... follow the directions to configure dial-up PPP # adduser dip ... allow to access dial-up PPP Dial-up PPP access can be initiated by the user (): $ pon # start PPP access to your ISP ... enjoy the Internet $ poff # stop PPP access, optional See `/usr/share/doc/ppp/README.Debian.gz' for more details. Alternatively, the `wvdial' package may be used to set up dial-up PPP access. 3.7.7. Other configuration files to tweak in `/etc' --------------------------------------------------- You may want to add an `/etc/cron.deny' file, missing from the standard Debian install (you can copy `/etc/at.deny'). ------------------------------------------------------------------------------- 4. Debian tutorials ------------------- This section provides a basic orientation to the Linux world for the real newbie. If you have been using Linux for a while, use it as a reality check. 4.1. Information sources ------------------------ Look into the Debian Documentation Project (DDP) (http://www.debian.org/doc/), which has the most authoritative references for Debian. Many of these documents are usually installed in `/usr/share/doc/'. Also look into `/usr/share/doc-base/', which provides pointers to the documents on the system. Add `export CDPATH=.:/usr/share/doc:/usr/src/local' to `~/.bash_profile' for easier access to documentation directories. The Linux Documentation Project (LDP) (http://www.tldp.org/) has the most authoritative general Linux references. LDP contents are usually installed in `/usr/share/doc/HOWTO/'. Navigate through documents on local and remote FTP sites using `F9' in Midnight Commander (see Section 4.3, `Midnight Commander (MC)'). 4.2. The Linux console ---------------------- 4.2.1. Login ------------ In an ordinary Linux system, there are 6 independent pseudo-terminals. Switch from one to another by pressing the `Left-Alt' key and `F1' - `F6' keys simultaneously. Each pseudo-terminal allows independent login to accounts. The multi-user environment is a great Unix feature, and very addictive. It is considered a good Unix habit to login to a regular user account for most purposes. I have to admit I used to use the superuser account (root) more than needed just because of its ease and my sloppiness. Now I usually use a regular account with the commands `sudo', `super' or `su -c' to gain limited root access. 4.2.2. Add a user account ------------------------- After system installation, I usually add a regular user account. If the username is "penguin", # adduser penguin will create it. I use the `vigr' command to edit `/etc/group' as follows: src:x:40:admin, debian, ... staff:x:50:admin ... I use the `staff' group for users who do administrative duties and have the exclusive `su' privilege (see Section 9.2.2, `"Why GNU `su' does not support the `wheel' group"') and `src' for CVS (see Chapter 12, `CVS'). In the default install system, the `staff' group owns `/home', making its members suitable for maintaining user accounts, while the `src' group owns `/usr/src', used for kernel compile, etc. Check out `adduser', `addgroup', `vipw', `vipw -s', `vigr', and `vigr -s' for configuring users and groups properly. 4.2.3. How to shut down ----------------------- Just like any modern OS where files are cached in memory, Linux needs a proper shutdown procedure before power can safely be turned off. Here is the command in multi-user mode: # shutdown -h now Here is the command in single-user mode: # poweroff -i -f Wait until the system displays "System halted" then shut off power. If apm has been turned on by the BIOS and Linux, the system will power down by itself. See Section 3.7.4, `Large memory and auto power-off' for details. 4.2.4. Command-line editing --------------------------- The default shell, `bash', has history-editing capability. Just use the up-arrow key to enter the history and then use cursor keys as you would expect. Other important keystrokes to remember: Ctrl-C: Terminate program Ctrl-D: Terminate input Ctrl-S: Halt output to screen Ctrl-Q: Reactivate output to screen Ctrl-Alt-Del: Reboot/halt system (see /etc/inittab) Lt-click-and-drag-mouse: Select and copy to the clipboard (gpm) Ctrl-click-mouse: Paste the clipboard to the cursor (gpm) On a normal Linux console, only the left-hand `Ctrl' and `Alt' keys work as expected. 4.2.5. Very basic commands to remember -------------------------------------- The following are very basic Unix commands: ls, ls -al, ls -d, pwd, cd, cd ~user, cd -, cat /etc/passwd, less, bg, fg, kill, killall, uname -a, type , sync, netstat, ping, traceroute, top, vi, ps aux, tar, zcat, grep, ifconfig, ... Check their meaning by entering the commands at a command prompt or by entering `man' or `info' plus the command name. Many Linux commands will display brief help information if you invoke them in one of the following ways: $ commandname --help $ commandname -h `whatis _commandname_' gives a one-line summary of any command on the system for which there is a manual entry. 4.2.6. X Window System ---------------------- To start the X Window System from the console: # exec startx Right-clicking the root window will bring up menu selections. 4.2.7. Important keyboard commands ---------------------------------- Some important keystrokes to remember for the Linux console: Alt-F1 thru F6: Switch to other pseudo-terminals Ctrl-Alt-F1 thru F6: Switch to other pseudo-terminals (from an X-window, DOSEMU, etc.) Alt-F7: Switch back to X-window Ctrl-Alt-minus: Change screen resolution in X-window Ctrl-Alt-plus: Change screen resolution opposite way in X-window Ctrl-Alt-Backspace: Terminate X-windows Alt-X, Alt-C, Alt-V: Usual Windows/Mac Cut, Copy, Paste key combinations with Ctrl- keys are replaced by these Alt- keys in some programs such as Netscape Composer. 4.3. Midnight Commander (MC) ---------------------------- Midnight Commander (MC) is a GNU "Swiss army knife" for the Linux console and other terminal environments. 4.3.1. Install MC ----------------- # apt-get install mc Then add the following function to `~/.bashrc' (or to `/etc/bash.bashrc', called from `.bashrc'). mc () { mkdir -p ~/.mc/tmp 2> /dev/null chmod 700 ~/.mc/tmp MC=~/.mc/tmp/mc-$$ /usr/bin/mc -P "$@" > "$MC" cd "$(cat $MC)" rm -f "$MC" unset MC; } This enables MC to change working directory upon exit. If one is in a terminal, like `kon' and `Kterm' for Japanese, which utilizes certain graphics characters, adding `-a' to MC's command line may help prevent problems. 4.3.2. Start MC --------------- $ mc MC takes care of all file operations through its menu, requiring minimal user effort. 4.3.3. File manager ------------------- The default is 2 directory panels containing file lists. Another useful mode is to set the right window to "information" to see file access privilege information, etc. Following are some essential keystrokes. With the `gpm' daemon running, one can use a mouse, too. (Make sure to press the shift key to obtain the normal behavior of cut and paste in MC.) * `F1': Help menu * `F3': Internal file viewer * `F4': Internal editor * `F9': Activate pulldown menu * `F10': Exit Midnight Commander * `Tab': Move between 2 windows * `Insert': Mark file for a multiple-file operation such as copy * `Del': Delete file (Be careful---set MC to safe delete mode.) * Cursor keys: Self-explanatory 4.3.4. Command-line tricks -------------------------- * Any `cd' command will change the directory shown on the selected screen. * `Control-Enter' or `Alt-Enter' will copy a filename to the command line. Use this with the `cp' or `mv' command together with command-line editing. * `Alt-Tab' will show shell filename expansion choices. * One can specify the starting directory for both windows as arguments to MC; for example, `mc /etc /root'. * `Esc' + == `Fn' (i.e., `Esc' + `1' = `F1,' etc.; `Esc' + `0' = `F10)' * `Esc' key == `Alt' key (= `Meta', `M-'); i.e., type `Esc' + `c' for `Alt-c' 4.3.5. Editor ------------- The internal editor has an interesting cut-and-paste scheme. Pressing `F3' marks the start of a selection, a second `F3' marks the end of selection and highlights the selection. Then you can move your cursor. If you press `F6', the selected area will be moved to the cursor location. If you press `F5', the selected area will be copied and inserted at the cursor location. `F2' will save the file. `F10' will get you out. Most cursor keys work intuitively. This editor can be directly started on a file: $ mc -e filename_to_edit $ mcedit filename_to_edit This is not a multi-window editor, but one can use multiple Linux consoles to achieve the same effect. To copy between windows, use `Alt-Fn' keys to switch virtual consoles and use "File->Insert file" or "File->Copy to file" to move a portion of a file to another file. This internal editor can be replaced with any external editor of choice. Also, many programs use environment variables `EDITOR' or `VISUAL' to decide which editor to use. If you are unconfortable with vim, set these to `mcedit' by adding these lines to `~/.bashrc': ... export EDITOR=mcedit export VISUAL=mcedit ... I do recommend setting these to `vim' if possible. Getting used to vi(m) commands is the right thing to do, since they are always there in the Linux/Unix world. 4.3.6. Viewer ------------- Very smart viewer. This is a great tool for searching words in documents. I always use this for files in the `/usr/share/doc' directory. This is the fastest way to browse through masses of Linux information. This viewer can be directly started like so: $ mc -v filename_to_view (Note that some packages violate policy and still store their documents under `/usr/doc'.) 4.3.7. Auto-start features -------------------------- Press `Enter' on a file, and the appropriate program will handle the content of the file. This is a very convenient MC feature. executable: Execute command man, html file: Pipe content to viewer software tar, gz, rpm file: Browse its contents as if subdirectory In order to allow these viewer/virtual file features to function, viewable files should not be set as executable. Change their status using the `chmod' command or via the MC file menu. 4.3.8. FTP virtual file system ------------------------------ MC can be used to access files over the Internet using FTP. Go to the menu by pressing `F9,' then type `p' to activate the FTP virtual file system. Enter a URL in the form `username:passwd@hostname.domainname', which will retrieve a remote directory that appears like a local one. 4.4. Further study ------------------ There are many good Unix entry-level references out there. O'Reilly's books are usually safe bets for good guidebooks in any field of computer topics. The LDP document Tips-HOWTO (http://www.tldp.org/HOWTO/Tips-HOWTO.html) is another resource to check. See Chapter 15, `Support for Debian' for more resources. ------------------------------------------------------------------------------- 5. Upgrading a distribution --------------------------- Official release notes for upgrading are located at http://www.debian.org/releases/stable/releasenotes and http://www.debian.org/releases/testing/releasenotes (work in progress). 5.1. Transition preparation ("stable" to "testing") --------------------------------------------------- Network upgrade to "testing" can be done as follows (run the script go-woody (examples/) to do this in one command): # cd /etc/apt # cp -f sources.list sources.old # :>sources.list # cd / # apt-setup noprobe ... select http or ftp # cd /etc/apt # grep -e "^deb " sources.list >sources.deb # grep -e "^deb-" sources.list >sources.src # sed -e "s/^d/#d/" \ /usr/share/doc/apt/examples/sources.list >sources.list # sed -e "s/stable/testing/" \ sources.deb >>sources.list # apt-get update # apt-get install apt apt-utils # cat >preferences <>sources.list # sed -e "s/stable/unstable/" sources.src | \ sed -e "s/^deb-/#deb-/" >>sources.list A guideline for `/etc/apt/preferences' (see apt_preferences(5)): track stable: change Pin-Priority of testing to 80 track testing: keep as is (install unstable by /unstable) track testing(unstable): change Pin-Priority of unstable to 600 track unstable(testing): change Pin-Priority of unstable to 800 A guideline for the choice of Pin-Priority is to move from the top to bottom in the above table as the time moves from a time immediately after a distribution release to a time of freeze for the next release. Examples of `/etc/apt/preferences' which lock some key packages to the more mature version while tracking the less mature version for other nonessential packages are available in the examples subdirectory (examples/) as `preferences.testing' and `preferences.unstable'. On the other hand, `preferences.stable' forces all packages to be downgraded to "stable". Make sure to set up APT to use a proxy, if necessary, by setting the `http_proxy' environment variable or set the http value in `/etc/apt/apt.conf'. The procedure described in this section only upgrades APT and a minimum set of packages to avoid dependency-related problems. 5.2. Upgrade to "testing" ------------------------- After the above preparation, the system can be upgraded. 5.2.1. Best upgrade practice using `dselect' -------------------------------------------- If a system has many packages which include `-dev' packages, etc., the following method using `dselect' is recommended for fine-grained package control. # dselect update # always do this before upgrade # dselect select # select packages in "suggests" and "recommends" # dselect install `dselect' always works :) 5.2.2. Deprecated upgrade practice using `apt-get' -------------------------------------------------- _The use of `apt-get' described below is widespread but it is _not_ recommended for system upgrades._ If you need to upgrade without `dselect' after Woody, consider `aptitudes' and other options. If a system does not have many packages or the Debian archive did not have major changes, the following may be sufficient (sometimes). # apt-get update # always do this before upgrade ... to upgrade the system with "depends" selections: # apt-get upgrade # always do this before upgrade ... to upgrade the whole system with "depends" selections: # apt-get -u dist-upgrade ... or to upgrade and stay with current dselect settings (new, better): # apt-get -u dselect-upgrade # use dselect setup result Since this upgrade method uses `apt-get', its handling of _recommends_ and _suggests_ is limited. See Section 2.2.8, `Package dependencies'. 5.3. Woody configuration ------------------------ For a freshly installed Woody system, edit `/etc/apt/sources.list', `/etc/apt/apt.conf', and `/etc/apt/preferences' to achieve the same structure as described in the above section. APT in Potato did not have the functions described in apt_preferences(5). 5.4. Optimized `sources.list' ----------------------------- Create `sources.list' automatically, based on latency and bandwidth. # apt-get install apt-spy # cd /etc/apt ; mv sources.list sources.list.org # apt-spy -d testing -l sources.apt `netselect-apt' is very similar to `apt-spy'. It creates a more complete `sources.list', but uses an inferior method of choosing the best mirror (ping time comparison). `apt-setup' is the manual method for selecting the mirrors in `sources.list', but is still the best way to choose mirrors until `apt-spy' improves. These optimization efforts did not produce significant improvement for me. Just using nearby sites chosen by `apt-setup' was sufficient. ------------------------------------------------------------------------------- 6. Debian package management ---------------------------- Make sure to set up a local HTTP proxy using `squid' for packages downloaded by APT. This greatly improves the performance of network upgrades, especially with multiple Debian boxes on the LAN. This chapter is based on a Woody system but most information also applies to a Potato system (except for apt_preferences(5) and topics related to `/etc/preferences'). 6.1. Introduction ----------------- If reading all the developer documentation is too much for you, read this chapter first and start enjoying the full power of Debian with `testing'/`unstable' :-) 6.1.1. Main tools ----------------- dselect --- menu-driven package management tool (top level) dpkg --- install package (package-file centric) apt-get --- install package (package-archive centric, CLI APT) tasksel --- install task (a set of packages) aptitude --- install package (package & task, ncurses APT) deity --- alternative ncurses APT synaptic, gsynaptic --- GUI APT alternatives These are not equal-level tools. `dselect' runs on the top of APT (the command-line command is `apt-get') and `dpkg'. APT uses `/var/lib/apt/lists/*' for tracking package status while `dpkg' uses `/var/lib/dpkg/status'. If you have installed packages directly using `apt-get' or similar programs such as `aptitude', make sure to update the `/var/lib/dpkg/status' file from the `[U]pdate' selection menu in `dselect' or from the shell command line "`dselect update'" prior to running `dselect select', `tasksel' or `dpkg -l'. As for package dependencies, `apt-get' automatically pulls in packages with _depends_ but leaves packages with _recommends_ and _suggests_, while `dselect' offers fine-grained control over choices of these packages and pulls in _depends_ and _recommends_ by default. See Section 2.2.8, `Package dependencies'. 6.1.2. Convenience tools ------------------------ apt-cache - check package archive in local cache dpkg-reconfigure - reconfigure an already installed package dpkg-source - manage source package file dpkg-buildpackage - automate the building of a package file ... 6.2. Debian survival commands ----------------------------- With this knowledge, one can live a life of _eternal_ "upgrade" :-) Also refer to Chapter 3, `Debian System installation hints', Chapter 5, `Upgrading a distribution' and Section 11.2, `Rescue editors'. 6.2.1. Install with `tasksel' ------------------------------------ `tasksel' is the _Debian Task Installer_, which is offered as the "`simple'" option during system installation. When one needs to install a common function which requires multiple packages, this is the best way to do it. Make sure to run the commands as follows: # dselect update # tasksel 6.2.2. Install system with APT ------------------------------ You can selectively install packages from different archives using newer versions of `apt-get' (>Woody). This enables, for example, selective upgrade to `unstable' and selective downgrade to `stable' while tracking `testing'. For selective upgrade, add the sources for `unstable' (`testing' if you use `stable') to your `/etc/apt/sources.list' and edit `/etc/apt/preferences' as follows: Package: * Pin: release a=unstable Pin-Priority: 50 (replace `unstable' with `testing' if you normally use `stable'). Now you can run `apt-get install /unstable' and install a package out of `unstable', with all its depends. But normal `apt-get upgrade' or `apt-get install ' does not install a package from `unstable' (or `testing'). # apt-cache policy libc6 libc6-dev locales # check status # apt-get install libc6=2.2.4-1 libc6-dev=2.2.4-1 locales=2.2.4-1 # apt-get install libc6/unstable libc6-dev/unstable locales/unstable # apt-get install -t unstable libc6 libc6-dev locales # apt-get -u install interesting-new-package remove-package- # apt-get remove useless-old-package # apt-get remove --purge really-useless-old-package To downgrade all packages to `stable', edit `/etc/apt/preferences' as follows: Package: * Pin: release a=stable Pin-Priority: 1001 and run "`apt-get upgrade'", which forces downgrade due to Pin-priority > 1000. 6.2.3. Upgrade system with APT ------------------------------ Upgrade system with APT: # apt-get update ... then do one of the following: # apt-get -u upgrade # pull all depends # apt-get -u dist-upgrade # pull all depends and resolve dependency # apt-get -u dselect-upgrade # follow selections set by dselect The following sets the `-u' option as the default action: $ cat >> /etc/apt/apt.conf // Always show packages to be upgraded (-u). APT::Get::Show-Upgraded "true"; ^D Use the `-s' option to simulate upgrade without actual upgrade. `dselect' offers a menu-driven interface over APT. `deity' and `aptitude' will offer alternatives to `dselect'. 6.2.4. Check bugs in Debian and seek help ----------------------------------------- If you are experiencing problems regarding a specific package, make sure to check out these sites first before you seek help or before you file a bug report. (`lynx', `links' and `w3m' work equally well): $ lynx http://bugs.debian.org/ $ lynx http://bugs.debian.org/ # if you know package name $ lynx http://bugs.debian.org/ # if you know bug number Search Google (www.google.com) with search words including "site:debian.org". When in doubt, read the fine manual. Set `CDPATH' as follows: export CDPATH=.:/usr/local:/usr/share/doc and type $ cd $ mc More support resources are listed at Chapter 15, `Support for Debian'. 6.2.5. APT upgrade troubleshooting ---------------------------------- Package dependency problems may occur when upgrading in `unstable'/`testing'. Most of the time, this is because a package that will be upgraded has a new dependency that isn't met. These problems are fixed by using # apt-get dist-upgrade If this does not work, then repeat one of the following until the problem resolves itself: # apt-get upgrade -f # continue upgrade even after error ... or # apt-get dist-upgrade -f # continue dist-upgrade even after error Some really broken upgrade scripts may cause persistent trouble. It is usually better to resolve this type of situation by inspecting the `/var/lib/dpkg/info/packagename.<{post-,pre-}{install,removal}>' scripts of the offending package and then running: # dpkg --configure -a # configures all partially installed packages If a script complains about a missing configuration file, look in `/etc' for the corresponding c