Arch Linux 0.8 (Voodoo) Installation Guide

Summary

This is the general user documentation for the Arch Linux distribution, version 0.8 (Voodoo). It covers obtaining the necessary files, installing the distribution and setting up a basic, bootable system. Additionally a short reference for the system layout and Arch-specific tools is supplied, ie. the pacman package manager and ABS.

Table Of Contents

Introduction

What is Arch Linux?

Arch Linux is an i686-optimized linux distribution that was originally based on ideas from CRUX, a great distribution developed by Per Lidén.

Arch is fast, lightweight, flexible and simple. Those aren't very fancy buzzwords but they're all true. Arch is optimized for the i686 processor, so you get more for your cpu cycle. It's lightweight compared to RedHat et al., and its simple design makes it easy to extend and mold into whatever kind of system you're building.

This is backed by an easy-to-use binary package system that allows you to upgrade your entire system with one command. Arch also uses a ports-like package build system (the Arch Build System - ABS) to make it easy to build packages, which can also be synchronized with one command. Oh yeah, and you can rebuild your entire system with one command, too. Everything is done quite simply and transparently.

Arch Linux strives to maintain the latest stable version of its software. We currently support a fairly streamlined core package set with a growing collection of extra packages maintained by AL developers, as well as literally thousands of additional packages submitted by trusted members of the community to our AUR for everyone to use as they see fit.

In it's goal to be simple and lightweight, the relatively useless portions of a linux system have been left out, things like /usr/doc and the info pages. In my own personal experience these are rarely used, and equivalent information can be obtained from the net if need be. Manpages all the way!

Arch Linux also strives to use some of the newer features that are available to linux users, such as hotplug and udev support. Arch Linux 0.8 (Voodoo) of course uses the 2.6 Linux kernel and udev by default, and has support for XFS/JFS, RAID/LVM, and encrypted filesystems.

License

Arch Linux, pacman, documentation, and scripts are copyright ©2002-2006 by Judd Vinet and are licensed under the GNU Public License.

Credits and Feedback

This document is heavily based on the works of Judd Vinet judd@archlinux.org. Minor corrections and a good bunch of modifications and additions have been made by Dennis Herbrich dennis@archlinux.org. Corrections and feedback should be fed into the bugtracker. An uncountable lot of people have contributed and will contribute to the evolution of the official Arch Linux Documentation by submitting corrections and suggesting improvement, it's way too unpractical to list them all. However, you know who you are, and without your help this would be near impossible to maintain and improve. Thank you!

Installing Arch Linux

Pre-Installation

Arch Linux is optimized for the i686 processor and therefore will not run on any lower or incompatible generations of x86 CPUs (i386,i486,i586). A Pentium II or AMD K6-2 processor or higher is required.

Before installing Arch Linux, you should decide which installation method you would like to use. Arch Linux provides three different bootable ISO images for a CD-ROM installation, as well as floppy disk images for Floppy-based installation.

As the preferred method of installation is the flexible CD-ROM based installation, we offer you three variants of the installation medium which only differ in terms of supplied packages. You can instruct the installer to obtain the packages via FTP using any of these images, and all images can also be used as a last-resort recovery cd.

• The full 550 MB arch-0.8.iso contains the whole current package repository at the time of release. For details on which packages are included, check out the package list available online. Using this image to create your installation medium, you'll be able to install a fully working linux system including some bells and whistles like a window manager and a good bunch of helper applications that are usually not considered mandatory, yet it might not include just those applications you would like to have used.

  If you generally do not have internet access from your target machine, it's most likely a good idea to obtain this variant to maximize the amount of packages you have available on CD.

• The considerably smaller arch-0.8-base.iso (150MB) only contains the base and kernels package categories and is otherwise identical. Please note that it is no longer necessary to download the full iso image if you plan using RAID/LVM during setup, as the necessary packages have been moved to base a while ago. Installing from a medium created with this image results in a completely functional linux system, without any frills, expecting to be used from the command line.

  This image is ideally suited for minimalists or experts who only want a basic, working system and go from there, and have a rather slow or difficult to set up internet connection to make an FTP install unfeasible.

• Finally, there is a new option available to the bandwith-conscious, the tiny 12 MB arch-0.8-ftp.iso containing only the bare minimum to get the installer process running. This variant contains no packages at all, and is therefore only useful for an FTP installation, if you've got a fast and easy to setup internet connection or a package repository server on a LAN.

  With only 12MB this is the fastest way to start installing ArchLinux, and has the additional advantage of using the newest packages available at the time of installation instead of the release snapshot package versions included in the other images. Of course all packages you choose to install have to be downloaded from somewhere, but at least you don't have to update the system directly after installation, and safe yourself some hassle. If your network connection is cheap and fast, choose this image.

If you do not have a CD-ROM drive attached to your computer, you're naturally stuck with the floppy variant and an installation via FTP. If you see any way of connecting a CD-ROM to the target machine, though, try to do that and use one of the CD-ROM images for installation, as floppy disks are painfully slow and exceedingly error prone nowadays.

Usage of floppy disks for installation (or anything else, really) is strongly discouraged!

Now obtain a bootable Arch installation CD image, either by downloading and burning one of the latest ISOs from one of the mirrors listed, or by letting someone else burn a copy if your dialup connection simply doesn't cut it, or you don't own a CD-ROM writer. You can also purchase a cd online from OSDisc, shipping nearly world-wide.

Furthermore you should not worry about using an old ISO for installation, as upgrading the system to the current branch is a breeze once you've got your basic system set up. At least if you've got a broadband connection!

For a successful FTP install you must have a gateway in your LAN that is actually connected to the internet and routes any requests from the PC to be installed into the internet and back. Or, alternatively, you can of course have a properly set up FTP server in your LAN to install from. Point is that you cannot attach a modem to your PC and set up a connection with your provider with the installer. It won't work.

The newbie-friendliest method of installing Arch Linux surely is installing the base system and all you need to get online from the CD, and then run a complete system upgrade and add any other packages you want or need once you set up your internet connection.

What You Will Need

• a working knowledge of Linux and your system, especially your hardware
• Arch Linux installation media (see the mirror list)
  • either an Arch Linux Install CD, or
  • 2-7 floppy disks, depending on what kinds of hardware you need supported during the installation: SCSI, exotic ethernet cards, etc.
• an i686-based computer (PPro, Pentium 2 or higher, Athlon/Duron, etc. Note that AMD K6, Transmeta Crusoe, CyrixIII, and VIA-C3 are NOT supported.)
• some time to kill

Acquiring Arch Linux

You can download Arch Linux from any of the sources listed on the download page. The static mirrors are listed below for reference (note that these may be out of date; consult the webpage for a current list):

Preparing Installation Media

Floppy Install

1. Download images/boot.img (path is relative to the mirror root)
2. Download images/root.img
3. Download any add-on images you need from the images/addons/ subdirectory:

   ethernet.img

   Ethernet modules

   fs1.img

   XFS/JFS modules, Ext2 extra utilities

   fs2.img

   XFS/JFS extra utilities

   keymaps_usb_firewire.img

   Additional keymaps/consolefonts, USB/Firewire modules

   ntfs_fdisk.img

   NTFS modules and utilities, fdisk

   pcmcia_wlan.img

   PCMCIA modules, wireless utilities

   raid_lvm.img

   RAID/LVM modules and utilities

   scsi.img

   SCSI modules

4. Find some blank floppies and write the images to them:

   (insert first disk)
   # dd if=boot.img of=/dev/fd0
   (insert second disk)
   # dd if=root.img of=/dev/fd0
   
   (repeat for any additional add-on images)
   # dd if=scsi.img of=/dev/fd0

   If you need to write these images from a Windows box, you can download rawrite2.exe and use it instead of dd.
5. Write down all your network settings so you can enter them into setup later, if you want to install via FTP:
   • IP Address
   • Subnet Mask
   • Gateway
   • Ethernet Module for your network card (eg.: eepro100, 8139too, ne2k-pci, etc.)

CD Install

1. Download 0.8/iso/i686/arch-0.8.iso (path relative to mirror root)
2. Download 0.8/iso/i686/arch-0.8.md5sum
3. Verify the integrity of the .iso image using md5sum:

   # md5sum --check arch-0.8.md5sum
   arch-0.8.iso: OK

4. Burn the .iso image to a blank CD-R (this step varies depending on the OS/software you're using).
   If you want to download the base, ftp or a beta ISO instead, use the appropriate filename, ie: arch-0.8-base.iso instead of arch-0.8.iso, likewise for the md5sum.
5. Write down all your network settings so you can enter them into setup later, if you want to install via FTP:
   • IP Address
   • Subnet Mask
   • Gateway
   • Ethernet Module for your network card (eg.: eepro100, 8139too, ne2k-pci, etc.)

Using the CD-ROM

You should skip this section and go right to the Floppy Installation instructions if you are not using a CD-ROM to boot from. If you're already familiar with the boot process, you may skip all this babble as well, and jump to the Common Install Procedure, which outlines the actual process of installing Arch Linux.

Reboot your computer with the Arch Linux Installation CD in the drive. Make sure your BIOS is set in a way to allow booting from your CD-ROM. Refer to your motherboard manual or your system manufacturer for details if you have no clue how to do that. Once the CD is booted from, you will see a boot prompt waiting for you pressing a key indefinitely, explaining what your options are at this point. Most users can just hit Enter and select the second option in the following boot menu (Arch Linux Installation / Rescue System) to boot the default Arch install kernel with IDE and SCSI support. If, for some reason, the kernel does not boot for you, you can either try enabling some IDE legacy workarounds using the third option from the boot menu, or edit the boot command line as instructed.

At the end of the boot procedure, you should be dropped into a root shell with a handful of instructions filling the upper half of your screen. At this point you are ready to commence the actual installation, or do any manual preparation you consider necessary.

Using The Floppies

Reboot your computer with the boot disk in the floppy drive. After some disk-crunching noises, you should come to a boot prompt, waiting eagerly for your input. Press Enter to continue the boot process after adding any potentially needed kernel parameters.

Partway through the boot-up process, you will be prompted:

VFS: Insert root floppy disk to be loaded into RAM disk and press ENTER

Insert the root disk in the floppy drive and hit Enter. After some more chunking you will be given a shell. Since you'll be needing your ethernet module for the install, you should now load the modules from the ethernet disk. Put the disk in the drive and run:

# loaddisk /dev/fd0

After a while all ethernet modules will be extracted to the filesystem. If the directory /lib/modules/ is still empty after this command, and/or you got a couple of errors, your disk has most likely gone bad. Create a new modules disk, and try again. You do not need to reboot in this case, just reissue the loaddisk command. Don't be worried if you have several disks failing this way, it's unfortunately quite common. See why we recommend CDs?

You should also load any other add-on disks that you need, such as SCSI or RAID/LVM. Use the same loaddisk command as above for each disk, order does not matter.

If you know which ethernet module you need, you should load it now with the modprobe command. Don't worry too much if you don't, the installer program will probe for the right module automatically and is usually quite successful.

Common Installation Procedure

At this point your system should be booted, and the hard drive to which you'd like to install, as well as your installation source, must be accessible. Make sure all necessary modules are loaded from the add-on floppies, if you had to choose this route.

Installation Steps:

Using the available shell tools, experienced users are also able to prepare the hard drive or any devices needed for the installation before starting the installer. You may simply skip this paragraph if you don't see any immediate need for further manual interaction. Note that the Arch Linux installation media also contains a /arch/quickinst script for experienced users. This script installs the base set of packages to a user-specified destination directory. If you are doing an exotic install with fun things like RAID and LVM, or don't want to use the installer at all, you'll probably want to use the quickinst script. All the cool kids do it.

Loading a non-US Keymap

If you require a non-US keymap, you can use the km utility to load a new keymap. Just type km at the prompt, then use the arrow keys to navigate to the correct keymap and/or console font.

Running Setup

Now you can run /arch/setup to invoke the installer program. After an informational message you will be prompted for the installation method of your choice. If you have a fast internet connection, you might prefer the FTP installation to ensure you get the latest packages instead of using the potentially outdated CD contents. Please note that you will probably run into trouble if you have a complex proxy setup with authentication when using the FTP installation. If you can't use a CD-ROM, or any other medium you could mount at this stage, this is the only viable method of installing Arch Linux.

When choosing a CD-ROM or OTHER SOURCE install you will only be able to install packages contained on the CD, which may be quite old, or packages stored on a medium you were able to mount (DVD, USB stick or similar) somewhere in the filesystem tree manually. Of course it has the merit that you won't need an internet connection, and is therefore the recommended choice for dialup users or anyone else who does not feel like downloading about at least 100 MB of packages.

After choosing one of the two alternatives, you will be presented with the installer menu, listing the necessary steps in the order in which they should be completed.

Configure Network (FTP Install only)

Configure Network will allow you to install and configure your network device.

A list of all currently available network devices is presented to you. If no ethernet device is available yet, or not the one you want to use, you may choose to switch to another terminal first using ALT-F2 for example, and load the necessary modules manually. Alternatively, you may just do as instructed, hit OK, and probe for a network module in the following screen by selecting the Probe command. If the installer fails to find a matching network module, make sure you ran the loaddisk command correctly earlier to make the ethernet modules available, if you are using floppies. When booting from CD-ROM, this is not necessary. If your network card is still not found, make sure your card is properly physically installed and supported by the linux kernel at all. Sometimes it's necessary to obtain a binary, proprietary driver from the manufacturer of your network card, and somehow manage to copy it to the installation system and load it manually. This is usually nothing for the faint of heart, and using a different model of network card is advised.

When the correct module is loaded, and your desired network card is listed, you should Select the ethernet device you want to configure and you will be given the option to configure your network with DHCP. If you're connected to a DHCP server, hit YES and let the installer do the rest. If you select NO, you will be asked to enter the networking information manually, which you hopefully wrote down as you were told. Either way, your network should be successfully configured, and if you're of the skeptical kind, you may check connectivity using standard tools like ping on another console.

As automatisms are not perfect, you may not be able to successfully use the installer to set up your network. In these rare cases, don't bother, and set up you network device manually in one of the consoles. All the installer needs is a transparent connection to the ftp server you are going to select later during the installation.

Prepare Hard Drive

Prepare Hard Drive will lead you into a submenu offering two alternatives of preparing your target drive for installation.

The first choice is Auto-Prepare, which will automatically partition your hard drive into a /boot, swap, and root partition, and then create filesystems on all three. These partitions will also be automatically mounted in the proper place. To be exact, this option will create a

• 32 MB ext2 /boot partition
• 256 MB swap partition
• ext3 root partition with the remaining space

Actual sizes may vary slightly due to different hard disk geometries. You can choose this option if you don't know much about hard drive partitions, but be warned:

A way to verify your choice for a device to partition would be to open another terminal (ALT-F2, Enter) and enter

# cfdisk -P s <name of device>

there to display the current partition table of the selected device, which should suffice to identify the hard disk.

If no device name is shown ([nothing] will be COMPLETELY ERASED! ...), and the installer produces an Device not valid error after hitting YES, make sure you loaded all needed modules if it's a SCSI, RAID, etc. device. You can still load any modules now by changing to another terminal and issuing the commands there, then return to the installer process on terminal one (ALT-F1).

If you prefer to do the partitioning manually, use the other two options, Partition Hard Drives and Set Filesystem Mountpoints to prepare the target media according to your specifications as outlined below. Then Return to Main Menu after a successful preparation.

Partition Hard Drives

Partition Hard Drives should be skipped if you chose Auto-Prepare already!

Otherwise you should select the disk(s) you want to partition, and you'll be dropped into the cfdisk program where you can freely modify the partitioning information until you [Write] and [Quit].

Set Filesystem Mountpoints

Set Filesystem Mountpoints should also be skipped if you chose to Auto-Prepare your hard drive. You should select this choice once the partition information is edited to your liking with the previous menu selection, or already existent through whatever other means.

The first question to answer is what partition to use as swap. Select the previously created swap partition from the list, or NONE, if you don't want to use a swap partition. Using a swap file is not directly supported by the installer; Instead choose NONE here, finish the mountpoint associations, and activate a swap file on your desired, formatted partition with the swapon command.

After setting up the swap partition, you'll be asked to specify the partition to be used as the root partition. This is mandatory.

The association process is then repeated until you choose DONE from the list, ideally after all listed partitions have been associated with their intended mountpoints. The installer will suggest /boot for all following mountpoints after choosing swap and root.

Every time you specify a partition to mount, you will be asked if you want to create a filesystem on the respective partition. If you select YES, you will be asked what filesystem to create (a matter of taste, really. Choose ext3 if you have no clue), and the partition will be formatted with the chosen filesystem, destroying all data in the process. It should be no problem, however, to say NO at this point to preserve any existing files on the partition.

If you want to mount any other partitions, for example a separate /boot or /home partition, you will be able to do so. Simply

• select a partition to mount
• choose a filesystem (if you want to create one instead of keeping the data)
• enter a unique mountpoint for the partition

Repeat these steps until you're satisfied, then select DONE to create any filesystems and mount the partitions in their respective places. Before the actual formatting is done, the installer will present to you a list of all of your choices for review. After formatting and mounting all partitions, you may return to the Main Menu and proceed with the next step.

Select Packages

Select Packages will let you select the packages you wish to install from the CD or your FTP mirror.

If you chose CD-ROM installation, you have to tell the installer whether it should try to mount the CD itself, or whether you already mounted the source media on the /src directory. Select the option according to what you need; Normally you will want to choose CD, after which you will be given the possibility to choose a CD-ROM drive from the list of all detected devices.

If you chose FTP Installation, you will be asked to choose a mirror close to you from a list, or select Custom to enter your own fully qualified domain name (or IP address) to an FTP server containing the installation source packages, ie. a prepared server in your LAN, or a mirror that's not listed for whatever reason, and afterwards the full path to the directory on the server that contains the packages and specifically the file current.db.tar.gz. The installer will check your input for validity, and allow you to make corrections until you enter an address and path that are reachable and allow downloading of the package list.

Whatever source you chose, after fetching the package list you'll be dropped into the package category selection screen.

Now, once that is tackled, you have the opportunity to specify whole package groups from which you'd generally like to install packages, then fine-tune your coarse selection by (de)selecting individual packages from the groups you have chosen.

Any packages in the BASE category should stay selected under all circumstances, and you should select any other group which contains a package you might need. Please note that the upcoming individual package selection screen will only offer packages which are in the categories you select here, so if you only select BASE, you won't be able to add any other packages than those in the BASE category.

The Select all packages by default? question can be easily misunderstood; Basically you are asked whether you want all the packages in the categories you just chose to be selected or not.
If you select YES, the whole list of packages contained in the chosen categories will be displayed and selected, and your job will be to deselect what you do not want.
If you select NO, the same list of packages will displayed, but only packages of the BASE category will be selected, and you'll have to explicitly select any other packages you want to install.

It is recommended that you install all the BASE packages, but not anything else at this point. Don't worry about getting all the packages you want - you can easily install more of them once the basic system boots by itself. The only exception to this rule is installing any packages you need for setting up internet connectivity. These packages usually are:

dhcpcd (base)

Add if your machine is a DHCP client.

isdn4k-utils (network)

Add if you use ISDN for dialup.

ppp (base)

Add if you use an analog modem for dialup.

wvdial (network)

Add if you'd like to have an easy frontend to analog modem dialup setup.

rp-pppoe (base)

Add if you use DSL for pseudo-dialup.

Once you're done selecting the packages you need, leave the selection screen and continue to the next step, Install Packages.

Install Packages

Install Packages will now install pacman and any other packages you selected with resolved dependencies onto your harddisk. Don't be surprised if more packages are installed than you selected! Those packages are dependencies for your selection, and the installer will not explicitly ask for permission to install these extra packages, as it assumes you know what you're doing.

Error messages and debugging output is echoed as usual to terminal five (ALT-F5). During normal, successful operation, you shouldn't find much to read there, though. After the packages have been installed, proceed to the next step, Configure System.

Configure System

Configure System allows you to edit the configuration files crucial for your newly installed system. Initially you will be asked whether to allow the hwdetect script to try and detect your hardware, and produce some (even more) sensible defaults for your configuration files. Unless you're having problems/crashes, you should let it have it's way, and work from what it generates.

Answer the following questions about RAID, LVM and encrypted volumes with Yes, if your root partition resides on a RAID, LVM or encrypted volume, respectively, to automatically add the necessary HOOKS to the mkinitcpio.conf. Otherwise you will get a kernel panic during boot, as your root partition will not be accessible at the time of boot. Most people will answer these questions with No, though, and not waste a second thought about it.

After this automatic preconfiguration you'll be asked for your favourite editor to use for manually fine-tuning the generated configuration files, either VIM or nano. When in doubt, choose nano.

If you're in a real hurry, you may skip the following step of reviewing the configuration entirely and hope the defaults will work for you, but it's strongly recommended to iterate through the list of configuration files presented here and review the settings carefully. Please refer to the System Configuration section for detailed descriptions of the various files.

Install Kernel

Install Kernel will ask you which kernel image to install on your hard drive.

2.6

Install the stock 2.6 kernel with SCSI/SATA/IDE support. What exactly will be supported by the kernel during boot depends on how you configured your initial ramdisk, but the default has support for practically all SCSI, SATA, and IDE systems. See the System Configuration section for more information about the new initramfs, especially the potential pitfalls with the new PATA and ide legacy drivers.

Install Bootloader

Install Bootloader will install a bootloader on your hard drive, either GRUB (recommended) or LILO, depending on your personal preference.

Before installing the bootloader, the setup script will want you to examine the appropriate configuration file to confirm the proper settings. Make sure you know what your root (and /boot, if you have it) partitions are.

If you choose to install LILO, the bootloader will be automatically installed according to your settings in the configuration file, whilst GRUB demands the selection of a partition to install the bootloader to. Here you should choose what you would enter as the boot option of LILO, which is usually the entry named /dev/hda, as it refers the master boot record of the first hard disk. Detailed error messages can be found as usual on VC5 (virtual console 5), if anything goes wrong.

Exit Install

Exit Install now, remove the CD from the drive, type reboot at the command line and cross your fingers!

If your system boots up, you can log in as root without any password, so your first things to do are setting a password for root with the passwd command once you're logged in, add a user as outlined in the User Management section, and set up your Internet Connection.

Congratulations! Now you can proceed getting into the nitty-gritty of configuring the interesting parts of your system, and adapt it to your needs!

System Configuration

These are the core configuration files for Arch Linux. You should be comfortable hand-editing these files with a text-editor, because there aren't any GUI apps to help you out. Only the most basic configuration files are listed here. If you need help configuring a specific service, please read the appropriate manpage or refer to any online documentation you need. In many cases, the Archlinux Wiki and forums are a rich source for help as well.

Arch Linux does not use any abstraction layers to administrate your system. As a result, you can usually stick to any instructions published by the author of a software, or whatever you find in a search engine of your choice, and it'll work out without confusing your system, because your system just does not care.

Configuration Files

Before attempting to boot your newly installed system, you should at least glance over these files and make sure they are not too far off the mark.

List of Configuration Files

/etc/rc.conf

This is the main configuration file for Arch Linux. It allows you to set your keyboard, timezone, hostname, network, daemons to run and modules to load at bootup, profiles, and more. You should read through all the settings in this file and make sure you understand them, and change them where appropriate:

LOCALE

This sets your system language, which will be used by all i18n-friendly applications and utilities. You can get a list of the available locales by running locale -a from the command line. This setting's default is fine for US English users.

HARDWARECLOCK

Either UTC if your BIOS clock is set to UTC, or localtime if your BIOS clock is set to your local time. If you have an OS installed which cannot handle UTC BIOS times correctly, like Windows, choose localtime here, otherwise you should prefer UTC, which makes daylight savings time a non-issue and has a few other positive aspects.

TIMEZONE

Specifies your time zone. Possible time zones are the relative path to a zoneinfo file starting from the directory /usr/share/zoneinfo. For example, a german timezone would be Europe/Berlin, which refers to the file /usr/share/zoneinfo/Europe/Berlin. If you don't know the exact name of your timezone file, worry about it later.

KEYMAP

Defines the keymap to load with the loadkeys program on bootup. Possible keymaps are found in /usr/share/kbd/keymaps. Please note that this setting is only valid for your TTYs, not any graphical window managers or X! Again, the default is fine for US users.

CONSOLEFONT

Defines the console font to load with the setfont program on bootup. Possible fonts are found in /usr/share/kbd/consolefonts.

CONSOLEMAP

Defines the console map to load with the setfont program on bootup. Possible maps are found in /usr/share/kbd/consoletrans. You will want to set this to a map suitable for your locale (8859-1 for Latin1, for example) if you're using an utf8 locale above, and use programs that generate 8-bit output. If you're using X11 for everyday's work, don't bother, as it only affects the output of linux console applications.

USECOLOR

Enable (or disable) colorized status messages during boot-up.

MOD_AUTOLOAD

If set to "yes", Arch will scan your hardware at bootup and attempt to automatically load the proper modules for your system. This is done with the hwdetect utility.

MOD_BLACKLIST

This is an array of modules that you do not want to be loaded at bootup. For example, if you don't want that annoying PC speaker, you could blacklist the pcspkr module.

MODULES

In this array you can list the names of modules you want to load during bootup without the need to bind them to a hardware device as in the modprobe.conf. Simply add the name of the module here, and put any options into the modprobe.conf if need be. Prepending a module with a bang ('!') will not load the module during bootup (this is not the same as MOD_BLACKLIST!), thus allowing to "comment out" certain modules if necessary. A benefit of specifying networking modules here is that ethernet cards covered by the listed modules will always be detected in the order the modules are listed. This prevents the dreaded interface confusion where your ethernet hardware is assigned to seemingly random interfaces after each boot. An even better way to handle this is using static interface labels by configuring udev appropriately, though.

USELVM

Set to "YES" to run a vgchange during sysinit, thus activating any LVM groups. If you have no idea what this means, don't bother.

HOSTNAME

Set this to the hostname of the machine, without the domain part. This is totally your choice, as long as you stick to letters, digits and a few common special characters like the dash. Don't be too creative here, though, and when in doubt, use the default.

INTERFACES

Here you define the settings for your networking interfaces. The default lines and the included comments explain the setup well enough. If you do not use DHCP to configure a device, just keep in mind that the value of the variable (whose name must be equal to the name of the device which is supposed to be configured) equals the line which would be appended to the ifconfig command if you were to configure the device manually in the shell.

ROUTES

You can define your own static network routes with arbitrary names here. Look at the example for a default gateway to get the idea. Basically the quoted part is identical to what you'd pass to a manual route add command, therefore reading man route is recommended if you don't know what to write here, or simply leave this alone.

NET_PROFILES

Enables certain network profiles at bootup. Network profiles provide a convenient way of managing multiple network configurations, and are intended to replace the standard INTERFACES/ROUTES setup that is still recommended for systems with only one network configuration. If your computer will be participating in various networks at various times (eg, a laptop) then you should take a look at the /etc/network-profiles/ directory to set up some profiles. There is a template file included there that can be used to create new profiles.

DAEMONS

This array simply lists the names of those scripts contained in /etc/rc.d/ which are supposed to be started during the boot process. If a script name is prefixed with a bang (!), it is not executed. If a script is prefixed with an "at" symbol (@), then it will be executed in the background, ie. the startup sequence will not wait for successful completion before continuing. Usually you do not need to change the defaults to get a running system, but you are going to edit this array whenever you install system services like sshd, and want to start these automatically during bootup. This is basically Arch's way of handling what others handle with various symlinks to an init.d directory.

/etc/hosts

This is where you stick hostname/ip associations of computers on your network. If a hostname isn't known to your DNS, you can add it here to allow proper resolving, or override DNS replies. You usually don't need to change anything here, but you might want to add the hostname and hostname + domain of the local machine to this file, resolving to the IP of your network interface. Some services, postfix for example, will bomb otherwise. If you don't know what you're doing, leave this file alone until you read man hosts.

/etc/fstab

Your filesystem settings and mountpoints are configured here. The installer should have created the necessary entries for you, but you should look over it and make sure it's right, especially when using an encrypted root device, LVM or RAID.

/etc/mkinitcpio.conf

This file allows you to fine-tune the initial ramdisk (also commonly referred to as the "initrd") for your system. The initrd is a gzipped image that is read by the kernel during bootup. The purpose of the initrd is to bootstrap the system to the point where it can access the root filesystem. This means it has to load any modules that are required to "see" things like IDE, SCSI, or SATA drives (or USB/FW, if you are booting off a USB/FW drive). Once the initrd loads the proper modules, either manually or through udev, it passes control to the Arch system and your bootup continues. For this reason, the initrd only needs to contain the modules necessary to access the root filesystem. It does not need to contain every module you would ever want to use. The majority of your everyday modules will be loaded later on by udev and hotplug, during the init process.

By default, mkinitcpio.conf is configured to provide all known modules for IDE, SCSI, or SATA systems through so-called HOOKS. This means the default initrd should work for almost everybody. The downside to this is that there are many modules loaded that you will not need. This is easily visible by examining your module table after booting up (with the lsmod command). While this doesn't actually hurt anything, some people find it annoying. To cull this list down to only what you actually need, you can edit mkinitcpio.conf and remove the subsystem HOOKS (ie, IDE, SCSI, RAID, USB, etc) that you don't need.

You can customize even further by specifying the exact modules you need in the MODULES array and remove even more of the hooks, but take heed to the comments in the file, as this is a touchy place to go crazy with removing entries!

When you're finished tweaking mkinitcpio.conf, you must run mkinitcpio -p kernel26 as root to regenerate the images, unless you're still installing the system; In that case this step will be done automatically after choosing Install Kernel later in the process.

/etc/modprobe.conf

This tells the kernel which modules it needs to load for system devices, and what options to set. For example, to have the kernel load your Realtek 8139 ethernet module when it starts the network (ie. tries to setup eth0), use this line:

alias eth0 8139too

The syntax of this file is nearly identical to the old modules.conf scheme, unless you use some of the more exotic options like post-install. Then you should invest a little time into reading man modprobe.conf.

Most people will not need to edit this file.

/etc/resolv.conf

Use this file to manually setup your nameserver(s) that you want to use. It should basically look like this:

search domain.tld
nameserver 192.168.0.1
nameserver 192.168.0.2

Replace domain.tld and the ip addresses with your settings. The so-called search domain specifies the default domain that is appended to unqualified hostnames automatically. By setting this, a ping myhost will effectively become a ping myhost.domain.tld with the above values. These settings usually aren't mighty important, though, and most people should leave them alone for now. If you use DHCP, this file will be replaced with the correct values automatically when networking is started, meaning you can and should happily ignore this file.

/etc/locale.gen

This file contains a list of all supported locales and charsets available to you. When choosing a LOCALE in your /etc/rc.conf or when starting a program, it is required to uncomment the respective locale in this file, to make a "compiled" version available to the system, and run the locale-gen command as root to generate all uncommented locales and put them in their place afterwards. You should uncomment all locales you intend to use.

/boot/grub/menu.lst

GRUB is the default bootloader for Arch Linux. You should check and modify this file to accomodate your boot setup if you want to use GRUB, otherwise read on about the LILO configuration.

Configuring GRUB is quite easy, the biggest hurdle is that it uses yet another device naming scheme different from /dev; Your hard disks as a whole are referred to as (hd0), (hd1), etc., sequentially numbered in order of appearance on the IDE/SCSI bus, just like the hda, hdb, etc. names in Linux. The partitions of a disk are referred to with (hd0,0), (hd0,1) and so on, with 0 meaning the first partition. A few conversion examples are included in the default menu.lst to aid your understanding.

Once you grasped the concept of device naming, all you need to do is to choose a nice title for your boot section(s), supply the correct root partition device as a parameter to the root option to have it mounted as / on bootup, and create a kernel line that includes the partition and path where the kernel is located as well as any boot parameters. If using the stock Arch 2.6.x kernel, you'll also need an initrd line that points to the kernel26.img file in your /boot directory. The path you put on your initrd line should be the same as the path to vmlinuz26 that you provide on the kernel line. You should be fine with the defaults, just check whether the partition information is correct in the root and kernel lines, especially in regard to the pata issue!

To create a boot option that loads the bootsector of a different OS, the following example might be helpful. You will probably succeed in starting any Microsoft-based operating system with it, just add this block to the file after any other sections, and modify the partition device accordingly to refer to the partition containing the bootsector of the OS you are intending to boot.

# (1) Other OS
title My Other OS
rootnoverify (hd0,1)
makeactive
chainloader +1

For advanced configuration of other OSes, please refer to the online GRUB manual.

After checking your bootloader configuration for correctness, you'll be prompted for a partition to install the loader to. Unless you're using yet another boot loader, you should install GRUB to the MBR of the installation disk, which is usually represented by the appropriate device name without a number suffix.

/etc/lilo.conf

This is the configuration file for the LILO bootloader. Make sure you check this one and get it right if you want to use LILO to boot your system. See LILO documentation for help on this.

Things you should check are the root= lines in the image sections and the boot= line right at the beginning of the file. The root lines specify the device which shall be mounted as the root filesystem on bootup. If you don't know what is supposed to be entered here, change to another terminal and type mount to see a list of all currently mounted drives, and look for the line which displays a device name mounted on /mnt type [...]. The device path at the beginning of this very line should be entered in the root lines of your lilo.conf. Change if necessary, and keep the pata issue in mind!

The boot line should be okay by default in most cases. Unless you have a weird boot manager setup in mind with multiple OSes, the device referenced here should be having the same prefix your root lines have, but not end with a number. For example, a root of /dev/hda3 means you probably want to install LILO into the Master Boot Record of the hard disk, so you would set boot to /dev/hda, which references the disk as a whole. During installation, the boot device must be the current name of the device where you want to write the boot sector to; This may differ from the name of the device after the first boot, thanks to the pata transition! Check carefully what device to write to during the installation stage, for example with the mount command.

To be on the safe side, you should keep the option lba32 listed. This will prevent some geometry issues from happening.

In some cases, depending on your BIOS, LILO will not run on bootup and spill out an error code infinitely. In most cases you either removed the lba32 option, or your hardware setup is a little special, meaning that maybe your CD-ROM drive is primary master and the hard disk you installed secondary slave. This can very well confuse your BIOS, and thus stop the boot process. To prevent that you can try and make the install drive the primary master on your IDE bus. If you've got a mixed IDE and SCSI system and the problem persists, you'll probably need some experimentation with the disk and bios options of LILO to provide a working mapping; The disk drives in your system are numbered sequentially by your BIOS, starting with 0x80. If you're lucky your SCSI controller tells you which drive has which BIOS ID, but usually you're not. How the drives are effectively numbered is depending on your BIOS, so in the worst case you can only guess until it works. A typical disk line would look like this:

boot=/dev/hda
disk=/dev/hda bios=0x80

The disk option maps a BIOS ID to the disk device known to linux. Note that there is still no guarantee that things will work as other things can be wrong, so do not despair if all your tries fail, but rather try rearranging your hardware in a way that's not totally odd. In this area too much can go wrong and needs special handling to be explained here. In most cases the lba32 option will suffice anyway. Old hard drives will usually need a little more special care until they do as told.

How to recreate a LILO boot sector with only a rescue disk is explained later in this document.

/etc/conf.d/*

During setup, this is totally unimportant. Consider this as reference for the interested.

Some daemon scripts will have a matching configuration file in this directory that contains some more-or-less useful default values. When a daemon is started, it will first source the settings from it's config file within this directory, and then source the /etc/rc.conf. This means you can easily centralize all your daemon configuration options in your /etc/rc.conf simply by setting an appropriate variable value, or split up your configuration over multiple files if you prefer a decentralized approach to this issue. Isn't life great if it's all just simple scripting?

/etc/profile

This script is run on each user login to initialize the system. It is kept quite simple under Arch Linux, as most things are. You may wish to edit or customize it to suit your needs.

Boot Scripts

Arch Linux uses a fairly simple bootup sequence quite similar to *BSDs. The first boot script to run is /etc/rc.sysinit. When it's done, /etc/rc.multi will be called (in a normal bootup). The last script to run will be /etc/rc.local. When started in runlevel 1, the single user mode, the script /etc/rc.single is run instead of /etc/rc.multi. You will not find an endless symlink collection in the /etc/rc?.d/ directories to define the bootup sequence for all possible runleves. In fact, due to this approach Arch only really has three runlevels, if you take starting up X in runlevel 5 into account. The boot scripts are using the variables and definitions found in the /etc/rc.conf file and also a set of general functions defined in the /etc/rc.d/functions script. If you plan to write your own daemon files, you should consider having a look at this file and existing daemon scripts.

Boot Script Overview

/etc/rc.sysinit

The main system boot script. It does boot-critical things like mounting filesystems, running udev, activating swap, loading modules, setting localization parameters, etc. You will most likely never need to edit this file!

/etc/rc.single

Single-user startup. Not used in a normal boot-up. If the system is started in single-user mode, for example with the kernel parameter 1 before booting or during normal multi-user operation with the command init 1, this script makes sure no daemons are running except for the bare minimum; syslog-ng and udev. The single-user mode is useful if you need to make any changes to the system while making sure that no remote user can do anything that might cause data loss or damage.

For desktop users, this mode usually is useless as crud. You should have no need to edit this script, either.

/etc/rc.multi

Multi-user startup script. It starts all daemons you configured in the DAEMONS array (set in /etc/rc.conf) after which it calls /etc/rc.local. You shouldn't feel a pressing need to edit this file.

/etc/rc.local

Local multi-user startup script. It is a good place to put any last-minute commands you want the system to run at the very end of the bootup process. This is finally the one and only script you should modify if needed, and you have total freedom on what to add to this script.

/etc/rc.shutdown

System shutdown script. It stops daemons, unmounts filesystems, deactivates the swap, etc. Just don't touch.

/etc/rc.local.shutdown

Analogous to the /etc/rc.local file, this file may contain any commands you want to run right before the common rc.shutdown is executed. Please note that this file does not exist by default, and for it to work properly, it must be set as executable.

/etc/rc.d/*

This directory contains the daemon scripts referred to from the rc.conf's DAEMONS array. In addition to being called on bootup, you can use these scripts when the system is running to manage the services of your system. For example the command

# /etc/rc.d/postfix stop

will stop the postfix daemon. Of course a script only exists when the appropriate package has been installed (in this case postfix). With a basic system install, you don't have many scripts in here, but rest assured that all relevant daemon scripts end up here. This directory is pretty much the equivalent to the /etc/rc3.d/ or /etc/init.d/ directories of other distributions, without all the symlink hassle.

User Management

Users and groups can be added and deleted with the standard commands provided in the util-linux package: useradd, userdel, groupadd, groupdel, passwd, and gpasswd. The typical way of adding a user is similar to this procedure:

# useradd -m -s /bin/bash johndoe
# passwd johndoe

The first command will add the user named johndoe to the system, create a home directory for him at /home/johndoe, and place some default login files in his home directory. It will also set his login shell to be /bin/bash. The second command will ask you for a password for the johndoe user. A password is required to activate the account.

As an alternative to the useradd command, the adduser script is also available to interactively create new users on your system simply by answering questions.

See the manpages for more information on the remaining commands. It is a good idea to create one or multiple normal users for your day-to-day work to fully use the available security features and minimize potential damage that may be the result of using the root user for anything but system administration tasks.

Internet Access

Due to a lack of developers for dialup issues, connecting Arch to the Internet with a dialup line is requiring a lot of manual setup. If at all possible, set up a dedicated router which you can then use as a default gateway on the Arch box.

Analog Modem

To be able to use a Hayes-compatible, external, analog modem, you need to at least have the ppp package installed. Modify the file /etc/ppp/options to suit your needs and according to man pppd. You will need to define a chat script to supply your username and passwort to the ISP after the initial connection has been established. The manpages for pppd and chat have examples in them that should suffice to get a connection up and running if you're either experienced or stubborn enough. With udev, your serial ports usually are /dev/tts/0 and /dev/tts/1.

Instead of fighting a glorious battle with the plain pppd, you may opt to install wvdial or a similar tool to ease the setup process considerably.

ISDN

Setting up ISDN is done in three steps:

1. Install and configure hardware
2. Install and configure the ISDN utilities
3. Add settings for your ISP

The current Arch stock kernels include the necessary ISDN modules, meaning that you won't need to recompile your kernel unless you're about to use rather odd or old ISDN hardware. After physically installing your ISDN card in your machine or plugging in your USB ISDN-Box, you can try loading the modules with modprobe. Nearly all passive ISDN PCI cards are handled by the hisax module which needs two parameters; type and protocol. You must set protocol to '1' if your country uses the 1TR6 standard, '2' if it uses EuroISDN (EDSS1), '3' if you're hooked to a so called leased-line without D-channel, and '4' for US NI1.

Details on all those settings and how to set them is included in the kernel documentation, more specifically in the isdn subdirectory, available online. The type parameter depends on your card; A list of all possible types is to be found in the README.HiSax kernel documentation. Choose your card and load the module with the appropriate options like this:

# modprobe hisax type=18 protocol=2

This will load the hisax module for my (Dennis) ELSA Quickstep 1000PCI, being used in Germany with the EDSS1 protocol. You should find helpful debugging output in your /var/log/everything.log file in which you should see your card being prepared for action. Please note that you will probably need to load some usb modules before you can work with an external USB ISDN Adapter.

Once you confirmed that your card works with certain settings, you can add the module options to your /etc/modprobe.conf:

alias ippp0 hisax
options hisax type=18 protocol=2

Alternatively you can only add the options line here, and add hisax to your MODULES array in the rc.conf. Your choice, really, but this example has the advantage that the module will not be loaded until it's really needed.

That being done you should have working, supported hardware. Now you need the basic utilities to actually use it!

Install the isdn4k-utils package, and read the manpage to isdnctrl, it'll get you started. Further down in the manpage you will find explanations on how to create a configuration file that can be parsed by isdnctrl, as well as some helpful setup examples.

After you configured your ISDN card with the isdnctrl utility, you should be able to dial into the machine you specified with the PHONE_OUT parameter, but fail the username and password authentication. To make this work add your username and password to /etc/ppp/pap-secrets or /etc/ppp/chap-secrets as if you were configuring a normal analogous PPP link, depending on which protocol your ISP uses for authentication. If in doubt, put your data into both files.

If you set up everything correctly, you should now be able to establish a dialup connection with isdnctrl dial ippp0 as root. If you have any problems, remember to check the logfiles!

DSL (PPPoE)

Before you can use your DSL online connection, you will have to physically install the network card that is supposed to be connected to the DSL-Modem into your computer. After adding your newly installed network card to the modprobe.conf or the MODULES array, you should install the rp-pppoe package and run the pppoe-setup script to configure your connection. After you have entered all required data, you can connect and disconnect your line with

# /etc/rc.d/adsl start

and

# /etc/rc.d/adsl stop

respectively. The setup usually is rather easy and straightforward, but feel free to read the manpages for hints. If you want to automatically dial in on bootup, add adsl to your DAEMONS array.

Package Management

Pacman

pacman is the package manager which tracks all the software installed on your system. It has simple dependency support and uses the standard gzipped tar archive format for all packages. Some common tasks are explained below with the respective commands in long and short option form. For an up to date explanation of pacman's options, read man pacman. This overview is merely scratching the surface of pacman's current capabilities.

Typical tasks:

Adding a new package with a package file

# pacman --add foo.pkg.tar.gz
# pacman -A foo.pkg.tar.gz

This will install the foo.pkg.tar.gz package on the system. If dependencies are missing, pacman will exit with an error and report the missing deps, but not attempt to resolve the dependencies automatically. Look at the --sync option if you expect this functionality. Adding multiple package files is possible, and if the listed files depend on each other, the packages will be automatically installed in the correct order.

Upgrading a package with a package file

# pacman --upgrade foo.pkg.tar.gz
# pacman -U foo.pkg.tar.gz

This does essentially the same as the --add operation, but will additionally upgrade an already-installed package at no extra cost. I can personally not imagine a case where you'd prefer --add over this --upgrade function, unless you want pacman to exit if a package is already installed.

Removing packages

# pacman --remove foo
# pacman -R foo

This will remove all files belonging to the package named foo, except for configuration files that have been edited. Only supply the name of the package to this command, without the pkg.tar.gz suffix.

To remove any and all trace of a package, add the --nosave option to the above command.

Refreshing the package list

# pacman --sync --refresh
# pacman -Sy

This will retrieve a fresh master package list from the repositories defined in the /etc/pacman.conf file and uncompress it into the database area. You should use this before using --sysupgrade to make sure you get the newest packages. Depending on your pacman.conf settings, this command may require a working internet connection to access FTP/HTTP-based repositories. This option is quite similar to Debian's apt-get update command.

Upgrading the system

# pacman --sync --sysupgrade
# pacman -Su

This command will upgrade all packages that are out-of-date on your system by comparing the local package version to the versions in the master package list that gets downloaded with the --refresh command. It's a good idea to run this regularly to keep your system up to date. Note that this command does NOT implicitly refresh the master package list, so it's usually wiser to combine both commands into one like this:

# pacman --sync --refresh --sysupgrade
# pacman -Syu

With these options pacman will automatically retrieve the current master package list and do a full system upgrade to the latest packages with all dependencies being automagically resolved. You will want to run this quite often.

Adding/Upgrading a package from the repositories

# pacman --sync foo
# pacman -S foo

Retrieve and install package foo, complete with all dependencies it requires. Before using any sync option, make sure you refreshed the package list, or add --refresh or -y to the options to do it before the installation attempt. Unlike --add, the --sync option does not differ between installing and upgrading packages. Depending on your pacman.conf settings this function requires working internet access.

List installed packages

# pacman --query
# pacman -Q

Displays a list of all installed packages in the system.

Check if a specific package is installed

# pacman --query foo
# pacman -Q foo

Instead of grepping the full list for a name, you can append the name of the package you are looking for to the query command. This command will display the name and version of the foo package if it is installed, nothing otherwise.

Display specific package info

# pacman --query --info foo
# pacman -Qi foo

Displays information on the installed package foo (size, install date, build date, dependencies, conflicts, etc.). To display this information for a package file that is not yet installed, add the --file or -p option, respectively:

# pacman --query --info --file foo.pkg.tar.gz
# pacman -Qip foo.pkg.tar.gz

Display list of files contained in package

# pacman --query --list foo
# pacman -Ql foo

Lists all files belonging to package foo.

Find out which package a specific file belongs to

# pacman --query --owns /path/to/file
# pacman -Qo /path/to/file

This query displays the name and version of the package which contains the file referenced by it's full path as a parameter. Just using the file name without the path will not yield results.

Accessing Repositories

A package repository is a collection of packages and a package meta-info file that can reside in a local directory or on a remote FTP/HTTP server. The default repository for an Arch system is the current repository. This is kept up to date by developers with the latest version of most software and stays fairly bleeding-edge.

Many users also choose to activate the extra package repository which contains more packages that are not part of Arch's core package set. You can activate this repo by uncommenting the appropriate lines in your /etc/pacman.conf. This repository is activated by default.

You can also build, maintain and use your own package repositories. See the pacman manpage for instructions.

If you install from CD-ROM and end up having problems accessing the Internet, you may need to install additional packages from the CD. Refer to the FAQs, specifically FAQ #3 later in this document, to find out how to define a repository that uses the installation CD-ROM as a package source.

Arch Build System (ABS)

Binary vs. Source

Where pacman is responsible for the binary side of the package world, ABS is responsible for the source side: It helps you to build your own custom packages from source code, also letting you rebuild Arch Linux packages with your own customizations. The procedure usually goes as follows:

1. Synchronize your ABS tree with the server.
2. Create a new directory in /var/abs/local/ named after the package you are going to create.
3. Copy the PKGBUILD.proto prototype from /var/abs/ into your newly created directory, remove the .proto suffix, and edit it to fit the new package.
4. Run makepkg in the working directory with the PKGBUILD file.
5. Install the newly built package with pacman.
6. Send the package to your friends for bragging rights (or give it to an Archer so s/he can stick it in the master ABS tree).

Synchronizing Your ABS Tree

You can synchronize all the required package building files in /var/abs by running the abs script as root. It requires the cvsup package to operate and will complain if you don't have it installed. A working internet connection is also required, of course. Using CVS as the transfer medium allows you to follow different version trees within ABS - this can be configured in /etc/abs/supfile.arch. For example, the default supfile is set to track the current package tree, which is bleeding-edge and the recommended source to follow. You can also follow specific versions. See the comments in the supfiles for more info.

ABS supports multiple repositories, which can be enabled or disabled in /etc/abs/abs.conf. By default, abs will follow the current and extra repositories, but not anything else.

You will also see an /etc/abs/supfile.extra file. This will give you access to all the unofficial build scripts that were not included in the main ABS repository. If you do not want to use this repository, you can delete the file, but usually it makes more sense to edit abs.conf accordingly instead, and disable the repositories you don't need.

How to Build Packages

The build process is thoroughly explained in the makepkg manpage. Read it for instructions on building your own packages. If that's not helping you, keep your eyes peeled for tutorials in the Wiki, or ask for help in the forums or IRC.

Package Guidelines

When building package for Arch Linux, you should adhere to the package guidelines below, especially if you would like to contribute your new package to Arch Linux.

Package Naming

• Package names should consist of alphanumeric characters only; all letters should be lowercase.
• Package versions should be the same as the version released by the author. Versions can include letters if need be (eg, nmap's version was 2.54beta32 a good while ago). Version tags may not include hyphens! Letters, numbers, and periods only.
• Package releases are specific to Arch Linux packages. These allow users to differentiate between newer and older package builds. When a new package version is first released, the release count starts at 1. Then as fixes and optimizations are made, the package will be re-released to the AL public and the release number will increment. When a new version comes out, the release count resets to 1. Package release tags follow the same naming restrictions as version tags.

Directories

Configuration files should be placed in the /etc directory. If there's more than one configuration file, it's customary to use a subdirectory in order to keep the /etc area as clean as possible. Use /etc/{pkgname}/ where {pkgname} is the name of your package (or a suitable alternative, eg, apache uses /etc/httpd/).

Package files should follow these general directory guidelines:

makepkg Duties

When you use makepkg to build a package for you, it does the following automatically:

1. Checks if package dependencies are installed
2. Downloads source files from servers
3. Unpacks source files
4. Does any necessary patching
5. Builds the software and installs it in a fake root
6. Removes /usr/doc, /usr/info, /usr/share/doc, and /usr/share/info from the package
7. Strips symbols from binaries
8. Strips debugging symbols from libraries
9. Generates the package meta file which is included with each package
10. Compresses the fake root into the package file
11. Stores the package file in the configured destination directory (cwd by default)

Other

Do not introduce new variables into your PKGBUILD build scripts, unless the package cannot be built without doing so, as these could possibly conflict with variables used in makepkg itself. If a new variable is absolutely required, prefix the variable name with an underscore.

Avoid using /usr/libexec/ for anything. Use /usr/lib/{pkgname} instead.

The Packager field from the package meta file can be customized by the package builder by modifying the appropriate option in the /etc/makepkg.conf file, or alternatively by exporting the PACKAGER environment variable before building packages with makepkg:

# export PACKAGER="John Doe <your.email>"

Submitting Packages

If you'd like to submit packages, please take a look at the Arch User Repository and their guidelines. New packages should be submitted to the AUR.

If you're submitting a package, please do the following:

1. Please add a comment line to the top of your PKGBUILD file that follows this format:

   # Contributor: Your Name <your.email>

2. Verify the package dependencies (eg, run ldd on dynamic executables, check tools required by scripts, etc.). It's also a good idea to use the namcap utility, written by Jason Chu jason@archlinux.org, to analyze the sanity if your package. namcap will tell you about bad permissions, missing dependencies, un-needed dependencies, and other common mistakes. You can install the namcap package with pacman as usual.
3. All packages should come as a compressed tar file containing a directory with the newly built package, the PKGBUILD, filelist, and additional files (patches, install, ...) in it. The archive name should at least contain the name of the package.
4. Read the appropriate documents regarding the AUR, and the newest version of the packaging guildelines on the AUR Homepage.

Frequently Asked Questions

During package installation, pacman fails to resolve dependencies for package A because package B is not in the package set

Unless something is very broken and thus very likely to be reported by multiple people soon, you probably just forgot to mount your target partitions properly. This causes pacman to decompress the package database into the initial ramdisk, which fills up quite nicely and ultimatively leads to this error.

Make sure that you use the DONE and not the CANCEL option offered by the Filesystem Mountpoints menu to apply your choices. This error should not happen if you use the Auto-Prepare feature; If it does nevertheless, please report this as a bug.

How can I install packages from the install CD with pacman --sync (so it resolves dependencies for me)?

If you would rather have packages install from the CD instead of downloading them, then mount the install CD somewhere (eg. /mnt/cd) and add this line right below the [current] line in /etc/pacman.conf:

Server = file:///mnt/cd

Replace /mnt/cd with the mountpoint you chose. Then use pacman --sync as you normally would - It will now check the /mnt/cd directory first for packages.

How can I create multiple swap partitions during the install?

Naturally you won't be able to use the Auto-Prepare feature if you want to create and use multiple swap partitions. Create the partitions manually instead, and create as many swap partitions as your little heart desires. Go through the rest of the disk preparation steps, don't mind that you're only asked for one swap partition during the mount-point setting. Once you're through with the install and are about to edit your system configuration files, you can edit the fstab file and include a line for every swap device you created earlier. Simply copy the automatically generated swap line, and modify the referenced device according to your setup. The additional swaps will be activated after the bootup when swapon -a is being run by the initscripts. Make sure you ran mkswap on all of your swap partitions manually, or else your system will complain on bootup!

If, for any odd reason, you can not wait until after the installation with activating multiple swap partitions or files, you will have to open a shell on one of the virtual terminals and issue the swapon <device> for every swap drive or file you partitioned/readied before with mkswap. Then continue as explained above with the install.

In case you are honestly contemplating setting up multiple swap files or drives, you should keep in mind that a kernel that needs to swap is actually crying bitterly for more RAM, not more swap space. Please keep your penguin well fed. Thank you.

How do I reconfigure LILO from the rescue system?

As a first step you simply boot from the Arch Install CD or disks. If your partitions are intact and don't need checking, you can try choosing one of the recovery boot options according to your partition layout, or fiddle with the GRUB boot manager settings on your own to get your existing system to boot properly. That will boot directly into your system, and you can skip all but the last step of actually reconfiguring and running LILO.

If you cannot boot your old root directly, boot from the CD as if you were going to start an installation. Once you're in a shell, you mount the root partition of your harddisk into the /mnt directory, for example like this:

# mount /dev/hda3 /mnt

Then you mount any other partitions to their respective mount points within that root of yours, for example a /boot partition:

# mount /dev/hda1 /mnt/boot

Now you need to mount a /dev tree in the /mnt area, where LILO will be able to find it:

# /mnt/bin/mount --bind /dev /mnt/dev

Once everything is mounted, make this /mnt directory your new root with the chroot /mnt command. This will start a new shell and drop you into the /mnt directory, which will be considered your / from then on.

Now you can edit /etc/lilo.conf to your liking and run lilo to fix anything that needs fixing. Simply type exit when you want to break out of this root again, back into the original file tree. You can now reboot and test your changes.

I can't ssh into my machine!

Edit your /etc/hosts.deny file. The default configuration will reject all incoming connections, not only ssh connections.

How should I load modules during boot now?

If you want to load a module unconditionally without a specific device binding, add the name of the module to the MODULES array of your /etc/rc.conf. For on demand loading on device access, add it as usual with the alias and optioncommands to your /etc/modprobe.conf, in the rare cases that the automatisms employed by udev and hotplug don't cut it. To pass any options to a module you want to load through the MODULES array, only add the appropriate options line to your /etc/modprobe.conf.

Kernel refuses to boot because of lost interrupt

Kernel refuses to boot. It locks at:

IRQ probe failed for hda
hda lost interrupt

This or a similar error occurs for some HD controllers on kernel 2.6.x. A workaround is to pass the acpi=off option to the kernel at boot time.

I get access denied errors trying to play music or read DVDs

Add your user to the optical and audio groups.

# gpasswd -a johndoe optical
# gpasswd -a johndoe audio

Logout, then login again as that user (eg. johndoe) so the group changes can take effect, and the device permissions shouldn't be a problem anymore.

If you have a DVD drive, you may want to create a /dev/dvd symlink to your real DVD device. Usually udev does this for you already, but this will serve well as an example for setting up similar symlinks.

For example, if your DVD drive is accessible through /dev/sdc, you can do the following as root:

# cat >>/etc/udev/rules.d/00.rules <<EOF
> KERNEL="sdc", NAME="sdc", SYMLINK="dvd"
> EOF
# /etc/start_udev
# mount /dev/pts
# mount /dev/shm