Product SiteDocumentation Site

Fedora 12

Deployment Guide

Deployment, configuration and administration of Fedora 12

Edition 0

Fedora Documentation Project

Douglas Silas

Red Hat, Inc Engineering Content Services

John Ha

System Administration, Kernel 
Red Hat, Inc Engineering Content Services

David O'Brien

Security 
Red Hat, Inc Engineering Content Services

Michael Hideo

System Administration 
Red Hat, Inc Engineering Content Services

Don Domingo

System Administration 
Red Hat, Inc Engineering Content Services

Michael Behm

System Administration 
Red Hat, Inc Engineering Content Services

Jeffrey Fearn

Garrett LeSage

Andrew Fitzsimon

Michael Behm

Sandra Moore

Edward Bailey

Karsten Wade

Mark Johnson

Andrius Benokraitis

Lucy Ringland


Legal Notice

Copyright © 2009 Red Hat, Inc. and others.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. The original authors of this document, and Red Hat, designate the Fedora Project as the "Attribution Party" for purposes of CC-BY-SA. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
For guidelines on the permitted uses of the Fedora trademarks, refer to https://fedoraproject.org/wiki/Legal:Trademark_guidelines.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
All other trademarks are the property of their respective owners.
Abstract
The Deployment Guide documents relevant information regarding the deployment, configuration and administration of Fedora 12.

Preface
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. We Need Feedback!
3. Acknowledgements
Introduction
I. Package Management
1. Yum
1.1. Checking For and Updating Packages
1.1.1. Checking For Updates
1.1.2. Updating Packages
1.1.3. Updating Security-Related Packages
1.1.4. Preserving Configuration File Changes
1.2. Packages and Package Groups
1.2.1. Searching, Listing and Displaying Package Information
1.2.2. Installing
1.2.3. Removing
1.3. Configuring Yum and Yum Repositories
1.3.1. Setting [main] Options
1.3.2. Setting [repository] Options
1.3.3. Using Yum Variables
1.3.4. Creating a Yum Repository
1.4. Yum Plugins
1.4.1. Enabling, Configuring and Disabling Yum Plugins
1.4.2. Installing More Yum Plugins
1.4.3. Plugin Descriptions
1.5. Additional Resources
2. PackageKit
2.1. Updating Packages with Software Update
2.2. Using Add/Remove Software
2.2.1. Refreshing Software Sources (Yum Repositories)
2.2.2. Finding Packages with Filters
2.2.3. Installing and Removing Packages (and Dependencies)
2.2.4. Installing and Removing Package Groups
2.2.5. Viewing the Transaction Log
2.3. PackageKit Architecture
2.4. Additional Resources
3. RPM
3.1. RPM Design Goals
3.2. Using RPM
3.2.1. Finding RPM Packages
3.2.2. Installing
3.2.3. Uninstalling
3.2.4. Upgrading
3.2.5. Freshening
3.2.6. Querying
3.2.7. Verifying
3.3. Checking a Package's Signature
3.3.1. Importing Keys
3.3.2. Verifying Signature of Packages
3.4. Practical and Common Examples of RPM Usage
3.5. Additional Resources
3.5.1. Installed Documentation
3.5.2. Useful Websites
3.5.3. Related Books
II. Network-Related Configuration
4. Network Interfaces
4.1. Network Configuration Files
4.2. Interface Configuration Files
4.2.1. Ethernet Interfaces
4.2.2. IPsec Interfaces
4.2.3. Channel Bonding Interfaces
4.2.4. Alias and Clone Files
4.2.5. Dialup Interfaces
4.2.6. Other Interfaces
4.3. Interface Control Scripts
4.4. Configuring Static Routes
4.5. Network Function Files
4.6. Additional Resources
4.6.1. Installed Documentation
5. Network Configuration
5.1. Overview
5.2. Establishing an Ethernet Connection
5.3. Establishing an ISDN Connection
5.4. Establishing a Modem Connection
5.5. Establishing an xDSL Connection
5.6. Establishing a Token Ring Connection
5.7. Establishing a Wireless Connection
5.8. Managing DNS Settings
5.9. Managing Hosts
5.10. Working with Profiles
5.11. Device Aliases
5.12. Saving and Restoring the Network Configuration
6. Controlling Access to Services
6.1. Runlevels
6.2. TCP Wrappers
6.2.1. xinetd
6.3. Services Configuration Tool
6.4. ntsysv
6.5. chkconfig
6.6. Additional Resources
6.6.1. Installed Documentation
6.6.2. Useful Websites
7. Berkeley Internet Name Domain (BIND)
7.1. Introduction to DNS
7.1.1. Nameserver Zones
7.1.2. Nameserver Types
7.1.3. BIND as a Nameserver
7.2. /etc/named.conf
7.2.1. Common Statement Types
7.2.2. Other Statement Types
7.2.3. Comment Tags
7.3. Zone Files
7.3.1. Zone File Directives
7.3.2. Zone File Resource Records
7.3.3. Example Zone File
7.3.4. Reverse Name Resolution Zone Files
7.4. Using rndc
7.4.1. Configuring /etc/named.conf
7.4.2. Configuring /etc/rndc.conf
7.4.3. Command Line Options
7.5. Advanced Features of BIND
7.5.1. DNS Protocol Enhancements
7.5.2. Multiple Views
7.5.3. Security
7.5.4. IP version 6
7.6. Common Mistakes to Avoid
7.7. Additional Resources
7.7.1. Installed Documentation
7.7.2. Useful Websites
7.7.3. Related Books
8. OpenSSH
8.1. Features of SSH
8.1.1. Why Use SSH?
8.2. SSH Protocol Versions
8.3. Event Sequence of an SSH Connection
8.3.1. Transport Layer
8.3.2. Authentication
8.3.3. Channels
8.4. Configuring an OpenSSH Server
8.4.1. Requiring SSH for Remote Connections
8.5. OpenSSH Configuration Files
8.6. Configuring an OpenSSH Client
8.6.1. Using the ssh Command
8.6.2. Using the scp Command
8.6.3. Using the sftp Command
8.7. More Than a Secure Shell
8.7.1. X11 Forwarding
8.7.2. Port Forwarding
8.7.3. Generating Key Pairs
8.8. Additional Resources
8.8.1. Installed Documentation
8.8.2. Useful Websites
9. Samba
9.1. Introduction to Samba
9.1.1. Samba Features
9.2. Samba Daemons and Related Services
9.2.1. Samba Daemons
9.3. Connecting to a Samba Share
9.3.1. Command Line
9.3.2. Mounting the Share
9.4. Configuring a Samba Server
9.4.1. Graphical Configuration
9.4.2. Command Line Configuration
9.4.3. Encrypted Passwords
9.5. Starting and Stopping Samba
9.6. Samba Server Types and the smb.conf File
9.6.1. Stand-alone Server
9.6.2. Domain Member Server
9.6.3. Domain Controller
9.7. Samba Security Modes
9.7.1. User-Level Security
9.7.2. Share-Level Security
9.8. Samba Account Information Databases
9.9. Samba Network Browsing
9.9.1. Domain Browsing
9.9.2. WINS (Windows Internetworking Name Server)
9.10. Samba with CUPS Printing Support
9.10.1. Simple smb.conf Settings
9.11. Samba Distribution Programs
9.12. Additional Resources
9.12.1. Installed Documentation
9.12.2. Related Books
9.12.3. Useful Websites
10. Dynamic Host Configuration Protocol (DHCP)
10.1. Why Use DHCP?
10.2. Configuring a DHCP Server
10.2.1. Configuration File
10.2.2. Lease Database
10.2.3. Starting and Stopping the Server
10.2.4. DHCP Relay Agent
10.3. Configuring a DHCP Client
10.4. Configuring a Multihomed DHCP Server
10.4.1. Host Configuration
10.5. Additional Resources
10.5.1. Installed Documentation
11. Apache HTTP Server
11.1. Apache HTTP Server 2.2
11.1.1. Features of Apache HTTP Server 2.2
11.2. Migrating Apache HTTP Server Configuration Files
11.2.1. Migrating Apache HTTP Server 2.0 Configuration Files
11.2.2. Migrating Apache HTTP Server 1.3 Configuration Files to 2.0
11.3. Starting and Stopping httpd
11.4. Apache HTTP Server Configuration
11.4.1. Basic Settings
11.4.2. Default Settings
11.5. Configuration Directives in httpd.conf
11.5.1. General Configuration Tips
11.5.2. Configuration Directives for SSL
11.5.3. MPM Specific Server-Pool Directives
11.6. Adding Modules
11.7. Virtual Hosts
11.7.1. Setting Up Virtual Hosts
11.8. Apache HTTP Secure Server Configuration
11.8.1. An Overview of Security-Related Packages
11.8.2. An Overview of Certificates and Security
11.8.3. Using Pre-Existing Keys and Certificates
11.8.4. Types of Certificates
11.8.5. Generating a Key
11.8.6. How to configure the server to use the new key
11.9. Additional Resources
11.9.1. Useful Websites
12. FTP
12.1. The File Transfer Protocol
12.1.1. Multiple Ports, Multiple Modes
12.2. FTP Servers
12.2.1. vsftpd
12.3. Files Installed with vsftpd
12.4. Starting and Stopping vsftpd
12.4.1. Starting Multiple Copies of vsftpd
12.5. vsftpd Configuration Options
12.5.1. Daemon Options
12.5.2. Log In Options and Access Controls
12.5.3. Anonymous User Options
12.5.4. Local User Options
12.5.5. Directory Options
12.5.6. File Transfer Options
12.5.7. Logging Options
12.5.8. Network Options
12.6. Additional Resources
12.6.1. Installed Documentation
12.6.2. Useful Websites
13. Email
13.1. Email Protocols
13.1.1. Mail Transport Protocols
13.1.2. Mail Access Protocols
13.2. Email Program Classifications
13.2.1. Mail Transport Agent
13.2.2. Mail Delivery Agent
13.2.3. Mail User Agent
13.3. Mail Transport Agents
13.3.1. Sendmail
13.3.2. Postfix
13.3.3. Fetchmail
13.4. Mail Transport Agent (MTA) Configuration
13.5. Mail Delivery Agents
13.5.1. Procmail Configuration
13.5.2. Procmail Recipes
13.6. Mail User Agents
13.6.1. Securing Communication
13.7. Additional Resources
13.7.1. Installed Documentation
13.7.2. Useful Websites
13.7.3. Related Books
14. Lightweight Directory Access Protocol (LDAP)
14.1. Why Use LDAP?
14.1.1. OpenLDAP Features
14.2. LDAP Terminology
14.3. OpenLDAP Daemons and Utilities
14.3.1. NSS, PAM, and LDAP
14.3.2. PHP4, LDAP, and the Apache HTTP Server
14.3.3. LDAP Client Applications
14.4. OpenLDAP Configuration Files
14.5. The /etc/openldap/schema/ Directory
14.6. OpenLDAP Setup Overview
14.6.1. Editing /etc/openldap/slapd.conf
14.7. Configuring a System to Authenticate Using OpenLDAP
14.7.1. PAM and LDAP
14.7.2. Migrating Old Authentication Information to LDAP Format
14.8. Migrating Directories from Earlier Releases
14.9. Additional Resources
14.9.1. Installed Documentation
14.9.2. Useful Websites
14.9.3. Related Books
15. Authentication Configuration
15.1. User Information
15.2. Authentication
15.3. Options
15.4. Command Line Version
III. System Configuration
16. Console Access
16.1. Disabling Shutdown Via Ctrl+Alt+Del
16.2. Disabling Console Program Access
16.3. Defining the Console
16.4. Making Files Accessible From the Console
16.5. Enabling Console Access for Other Applications
16.6. The floppy Group
17. The sysconfig Directory
17.1. Files in the /etc/sysconfig/ Directory
17.1.1. /etc/sysconfig/amd
17.1.2. /etc/sysconfig/apmd
17.1.3. /etc/sysconfig/arpwatch
17.1.4. /etc/sysconfig/authconfig
17.1.5. /etc/sysconfig/autofs
17.1.6. /etc/sysconfig/clock
17.1.7. /etc/sysconfig/desktop
17.1.8. /etc/sysconfig/dhcpd
17.1.9. /etc/sysconfig/exim
17.1.10. /etc/sysconfig/firstboot
17.1.11. /etc/sysconfig/gpm
17.1.12. /etc/sysconfig/hwconf
17.1.13. /etc/sysconfig/i18n
17.1.14. /etc/sysconfig/init
17.1.15. /etc/sysconfig/ip6tables-config
17.1.16. /etc/sysconfig/iptables-config
17.1.17. /etc/sysconfig/irda
17.1.18. /etc/sysconfig/keyboard
17.1.19. /etc/sysconfig/kudzu
17.1.20. /etc/sysconfig/named
17.1.21. /etc/sysconfig/network
17.1.22. /etc/sysconfig/ntpd
17.1.23. /etc/sysconfig/radvd
17.1.24. /etc/sysconfig/samba
17.1.25. /etc/sysconfig/selinux
17.1.26. /etc/sysconfig/sendmail
17.1.27. /etc/sysconfig/spamassassin
17.1.28. /etc/sysconfig/squid
17.1.29. /etc/sysconfig/system-config-securitylevel
17.1.30. /etc/sysconfig/system-config-selinux
17.1.31. /etc/sysconfig/system-config-users
17.1.32. /etc/sysconfig/system-logviewer
17.1.33. /etc/sysconfig/tux
17.1.34. /etc/sysconfig/vncservers
17.1.35. /etc/sysconfig/xinetd
17.2. Directories in the /etc/sysconfig/ Directory
17.3. Additional Resources
17.3.1. Installed Documentation
18. Date and Time Configuration
18.1. Time and Date Properties
18.2. Network Time Protocol (NTP) Properties
18.3. Time Zone Configuration
19. Keyboard Configuration
20. The X Window System
20.1. The X11R7.1 Release
20.2. Desktop Environments and Window Managers
20.2.1. Desktop Environments
20.2.2. Window Managers
20.3. X Server Configuration Files
20.3.1. xorg.conf
20.4. Fonts
20.4.1. Fontconfig
20.4.2. Core X Font System
20.5. Runlevels and X
20.5.1. Runlevel 3
20.5.2. Runlevel 5
20.6. Additional Resources
20.6.1. Installed Documentation
20.6.2. Useful Websites
21. X Window System Configuration
21.1. Display Settings
21.2. Display Hardware Settings
21.3. Dual Head Display Settings
22. Users and Groups
22.1. User and Group Configuration
22.1.1. Adding a New User
22.1.2. Modifying User Properties
22.1.3. Adding a New Group
22.1.4. Modifying Group Properties
22.2. User and Group Management Tools
22.2.1. Command Line Configuration
22.2.2. Adding a User
22.2.3. Adding a Group
22.2.4. Password Aging
22.2.5. Explaining the Process
22.3. Standard Users
22.4. Standard Groups
22.5. User Private Groups
22.5.1. Group Directories
22.6. Shadow Passwords
22.7. Additional Resources
22.7.1. Installed Documentation
23. Printer Configuration
23.1. Adding a Local Printer
23.2. Adding an IPP Printer
23.3. Adding a Samba (SMB) Printer
23.4. Adding a JetDirect Printer
23.5. Selecting the Printer Model and Finishing
23.5.1. Confirming Printer Configuration
23.6. Printing a Test Page
23.7. Modifying Existing Printers
23.7.1. The Settings Tab
23.7.2. The Policies Tab
23.7.3. The Access Control Tab
23.7.4. The Printer and Job OptionsTab
23.8. Managing Print Jobs
23.9. Additional Resources
23.9.1. Installed Documentation
23.9.2. Useful Websites
24. Automated Tasks
24.1. Cron
24.1.1. Configuring Cron Tasks
24.1.2. Controlling Access to Cron
24.1.3. Starting and Stopping the Service
24.2. At and Batch
24.2.1. Configuring At Jobs
24.2.2. Configuring Batch Jobs
24.2.3. Viewing Pending Jobs
24.2.4. Additional Command Line Options
24.2.5. Controlling Access to At and Batch
24.2.6. Starting and Stopping the Service
24.3. Additional Resources
24.3.1. Installed Documentation
25. Log Files
25.1. Locating Log Files
25.2. Viewing Log Files
25.3. Adding a Log File
25.4. Monitoring Log Files
IV. System Monitoring
26. Gathering System Information
26.1. System Processes
26.2. Memory Usage
26.3. File Systems
26.4. Hardware
26.5. Additional Resources
26.5.1. Installed Documentation
27. OProfile
27.1. Overview of Tools
27.2. Configuring OProfile
27.2.1. Specifying the Kernel
27.2.2. Setting Events to Monitor
27.2.3. Separating Kernel and User-space Profiles
27.3. Starting and Stopping OProfile
27.4. Saving Data
27.5. Analyzing the Data
27.5.1. Using opreport
27.5.2. Using opreport on a Single Executable
27.5.3. Getting more detailed output on the modules
27.5.4. Using opannotate
27.6. Understanding /dev/oprofile/
27.7. Example Usage
27.8. Graphical Interface
27.9. Additional Resources
27.9.1. Installed Docs
27.9.2. Useful Websites
28. ABRT
28.1. Overview
28.2. Installing and Starting the Daemon, Applet and GUI
28.3. Configuring
28.4. Plugins and Sending Crash Reports
28.4.1. Reporting to Bugzilla
28.4.2. Emailing the Report
28.4.3. Transferring via SCP or FTP
28.4.4. Other plugins
V. Kernel and Driver Configuration
29. Manually Upgrading the Kernel
29.1. Overview of Kernel Packages
29.2. Preparing to Upgrade
29.3. Downloading the Upgraded Kernel
29.4. Performing the Upgrade
29.5. Verifying the Initial RAM Disk Image
29.6. Verifying the Boot Loader
29.6.1. x86 Systems
29.6.2. Itanium Systems
29.6.3. IBM S/390 and IBM System z Systems
29.6.4. IBM eServer iSeries Systems
29.6.5. IBM eServer pSeries Systems
30. General Parameters and Modules
30.1. Kernel Module Utilities
30.2. Persistent Module Loading
30.3. Specifying Module Parameters
30.4. Storage parameters
30.5. Ethernet Parameters
30.5.1. Using Multiple Ethernet Cards
30.5.2. The Channel Bonding Module
30.6. Additional Resources
30.6.1. Installed Documentation
30.6.2. Useful Websites
A. Revision History
Index

Preface

1. Document Conventions

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.
In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.

1.1. Typographic Conventions

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.
Mono-spaced Bold
Used to highlight system input, including shell commands, file names and paths. Also used to highlight keycaps and key combinations. For example:
To see the contents of the file my_next_bestselling_novel in your current working directory, enter the cat my_next_bestselling_novel command at the shell prompt and press Enter to execute the command.
The above includes a file name, a shell command and a keycap, all presented in mono-spaced bold and all distinguishable thanks to context.
Key combinations can be distinguished from keycaps by the hyphen connecting each part of a key combination. For example:
Press Enter to execute the command.
Press Ctrl+Alt+F1 to switch to the first virtual terminal. Press Ctrl+Alt+F7 to return to your X-Windows session.
The first paragraph highlights the particular keycap to press. The second highlights two key combinations (each a set of three keycaps with each set pressed simultaneously).
If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in mono-spaced bold. For example:
File-related classes include filesystem for file systems, file for files, and dir for directories. Each class has its own associated set of permissions.
Proportional Bold
This denotes words or phrases encountered on a system, including application names; dialog box text; labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:
Choose SystemPreferencesMouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, click the Left-handed mouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).
To insert a special character into a gedit file, choose ApplicationsAccessoriesCharacter Map from the main menu bar. Next, choose SearchFind… from the Character Map menu bar, type the name of the character in the Search field and click Next. The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the Copy button. Now switch back to your document and choose EditPaste from the gedit menu bar.
The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context.
Mono-spaced Bold Italic or Proportional Bold Italic
Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:
To connect to a remote machine using ssh, type ssh username@domain.name at a shell prompt. If the remote machine is example.com and your username on that machine is john, type ssh john@example.com.
The mount -o remount file-system command remounts the named file system. For example, to remount the /home file system, the command is mount -o remount /home.
To see the version of a currently installed package, use the rpm -q package command. It will return a result as follows: package-version-release.
Note the words in bold italics above — username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:
Publican is a DocBook publishing system.

1.2. Pull-quote Conventions

Terminal output and source code listings are set off visually from the surrounding text.
Output sent to a terminal is set in mono-spaced roman and presented thus:
books        Desktop   documentation  drafts  mss    photos   stuff  svn
books_tests  Desktop1  downloads      images  notes  scripts  svgs

Source-code listings are also set in mono-spaced roman but add syntax highlighting as follows:
package org.jboss.book.jca.ex1;

import javax.naming.InitialContext;

public class ExClient
{
   public static void main(String args[]) 
       throws Exception
   {
      InitialContext iniCtx = new InitialContext();
      Object         ref    = iniCtx.lookup("EchoBean");
      EchoHome       home   = (EchoHome) ref;
      Echo           echo   = home.create();

      System.out.println("Created Echo");

      System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
   }
}

1.3. Notes and Warnings

Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.

Note

Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.

Important

Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled 'Important' won't cause data loss but may cause irritation and frustration.

Warning

Warnings should not be ignored. Ignoring warnings will most likely cause data loss.

2. We Need Feedback!

If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in Bugzilla: http://bugzilla.redhat.com/bugzilla/ against the product Fedora Documentation.
When submitting a bug report, be sure to mention the manual's identifier: Deployment_Guide
If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.

3. Acknowledgements

Certain portions of this text first appeared in the Deployment Guide, copyright © 2007 Red Hat, Inc., available at http://www.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/5.4/html/Deployment_Guide/index.html.

Introduction

Welcome to the Fedora Deployment Guide.
The Fedora Deployment Guide contains information on how to customize your Fedora system to fit your needs. If you are looking for a comprehensive, task-oriented guide for configuring and customizing your system, this is the manual for you.
This manual discusses many intermediate topics such as the following:
  • Setting up a network interface card (NIC)
  • Configuring a Virtual Private Network (VPN)
  • Configuring Samba shares
  • Managing your software with RPM
  • Determining information about your system
  • Upgrading your kernel
This manual is divided into the following main categories:
  • File systems
  • Package management
  • Network-related configuration
  • System configuration
  • System monitoring
  • Kernel and Driver Configuration
  • Security and Authentication
  • Red Hat Training and Certification
This guide assumes you have a basic understanding of your Fedora system. If you need help installing Fedora, refer to the Fedora Installation Guide.

Part I. Package Management

All software on a Fedora system is divided into RPM packages, which can be installed, upgraded, or removed. This part describes how to manage packages on Fedora using the Yum and RPM package managers and the PackageKit suite of graphical package management tools.

Chapter 1. Yum

Yum is the Fedora package manager that is able to query for information about packages, fetch packages from repositories, install and uninstall packages using automatic dependency resolution, and update an entire system to the latest available packages. Yum performs automatic dependency resolution on packages you are updating, installing or removing, and thus is able to automatically determine, fetch and install all available dependent packages. Yum can be configured with new, additional repositories, or package sources, and also provides many plugins which enhance and extend its capabilities. Yum is able to perform many of the same tasks that RPM can; additionally, many of the command line options are similar. Yum enables easy and simple package management on a single machine or on groups of them.

Secure Package Management with GPG-Signed Packages

Yum provides secure package management by enabling GPG (Gnu Privacy Guard; also known as GnuPG) signature verification on GPG-signed packages to be turned on for all package repositories (i.e. package sources), or for individual repositories. When signature verification is enabled, Yum will refuse to install any packages not GPG-signed with the correct key for that repository. This means that you can trust that the RPM packages you download and install on your system are from a trusted source, such as the Fedora Project, and were not modified during transfer. Refer to Section 1.3, “Configuring Yum and Yum Repositories” for details on enabling signature-checking with Yum, or Section 3.3, “Checking a Package's Signature” for information on working with and verifying GPG-signed RPM packages in general.
Yum also enables you to easily set up your own repositories of RPM packages for download and installation on other machines.
Learning Yum is a worthwhile investment because it is often the fastest way to perform system administration tasks, and it provides capabilities beyond those provided by the PackageKit graphical package management tools. Refer to Chapter 2, PackageKit for details on using PackageKit.

1.1. Checking For and Updating Packages

1.1.1. Checking For Updates

You can use the yum check-update command to see which installed packages on your system have updates available.

Note: Yum and Superuser Privileges

You must have superuser privileges in order to use yum to install, update or remove packages on your system. All examples in this chapter assume that you have already obtained superuser privileges by using either the su or sudo command.
~]# yum check-update
Loaded plugins: presto, refresh-packagekit, security
PackageKit.x86_64                  0.5.3-0.1.20090915git.fc12  fedora
PackageKit-glib.x86_64             0.5.3-0.1.20090915git.fc12  fedora
PackageKit-yum.x86_64              0.5.3-0.1.20090915git.fc12  fedora
PackageKit-yum-plugin.x86_64       0.5.3-0.1.20090915git.fc12  fedora
glibc.x86_64                       2.10.90-22                  fedora
glibc-common.x86_64                2.10.90-22                  fedora
kernel.x86_64                      2.6.31-14.fc12              fedora
kernel-firmware.noarch             2.6.31-14.fc12              fedora
rpm.x86_64                         4.7.1-5.fc12                fedora
rpm-libs.x86_64                    4.7.1-5.fc12                fedora
rpm-python.x86_64                  4.7.1-5.fc12                fedora
yum.noarch                         3.2.24-4.fc12               fedora

Twelve packages are listed as having updates available. The first package in the list is PackageKit, the graphical package manager. The first line of the above output tells us:
  • PackageKit — the name of the package
  • x86_64 — the CPU architecture the package was built for
  • 0.5.3-0.1.20090915git.fc12 — the version of the updated package to be installed
  • fedora — the repository in which the updated package is located
The output also shows us that we can update the kernel (the kernel package), Yum and RPM themselves (the yum and rpm packages), as well as their dependencies (such as the kernel-firmware, rpm-libs and rpm-python packages), all using yum.

1.1.2. Updating Packages

You can choose to update a single package, multiple packages, or all packages at once. If any dependencies of the package (or packages) you update have updates available themselves, then they are updated too. To update a single package, enter yum update <package_name>:
~]# yum update glibc
Loaded plugins: presto, refresh-packagekit, security
Setting up Install Process
Resolving Dependencies
--> Running transaction check
--> Processing Dependency: glibc = 2.10.90-21 for package: glibc-common-2.10.90-21.x86_64
---> Package glibc.x86_64 0:2.10.90-22 set to be updated
--> Running transaction check
---> Package glibc-common.x86_64 0:2.10.90-22 set to be updated
--> Finished Dependency Resolution
Dependencies Resolved
======================================================================
 Package            Arch         Version          Repository     Size
======================================================================
Updating:
 glibc              x86_64       2.10.90-22       fedora       2.7 M
Updating for dependencies:
 glibc-common       x86_64       2.10.90-22       fedora       6.0 M
Transaction Summary
======================================================================
Install       0 Package(s)
Upgrade       2 Package(s)
Total download size: 8.7 M
Is this ok [y/N]:

This output contains two further items of interest:
  1. Loaded plugins: presto, refresh-packagekit, securityyum always informs you which Yum plugins are installed and enabled. Here, yum is using the presto, refresh-packagekit and security plugins. Refer to Section 1.4, “Yum Plugins” for general information on Yum plugins, or to Section 1.4.3, “Plugin Descriptions” for descriptions of specific plugins.
  2. kernel.x86_64 — you can download and install new kernels safely with yum.

    Important: Updating and Installing Kernels with Yum

    Yum always installs a new kernel in the same sense that RPM installs a new kernel when you use the command rpm -i kernel. Therefore, you do not need to worry about the distinction between installing and upgrading a kernel package when you use yum: it will do the right thing, regardless of whether you are using the yum update or yum install command.
    When using RPM, on the other hand, it is important to use the rpm -i kernel command (which installs a new kernel) instead of rpm -u kernel (which replaces the current kernel). Refer to Section 3.2.2, “Installing” for more information on installing/updating kernels with RPM.
  3. yum presents the update information and then prompts you as to whether you want it to perform the update; yum runs interactively by default. If you already know which transactions yum plans to perform, you can use the -y option to automatically answer yes to any questions yum may ask (in which case it runs non-interactively). However, you should always examine which changes yum plans to make to the system so that you can easily troubleshoot any problems that might arise.
    If a transaction does go awry, you can view Yum's log of transactions by entering cat /var/log/yum.log at the shell prompt. The most recent transactions are listed at the end of the log file.

Updating All Packages and Their Dependencies

To update all packages and their dependencies, simply enter yum update (without any arguments):
~]# yum update

Example 1.1. Updating all packages at once

1.1.4. Preserving Configuration File Changes

You will inevitably make changes to the configuration files installed by packages as you use your Fedora system. RPM, which Yum uses to perform changes to the system, provides a mechanism for ensuring their integrity. Refer to Section 3.2.4, “Upgrading” for details on how to manage changes to configuration files across package upgrades.

1.2. Packages and Package Groups

1.2.1. Searching, Listing and Displaying Package Information

You can search all RPM package names, descriptions and summaries by using the yum search <term> [more_terms] command. yum displays the list of matches for each term:
~]# yum search meld kompare
Loaded plugins: presto, refresh-packagekit, security
=============================== Matched: kompare ===============================
kdesdk.x86_64 : The KDE Software Development Kit (SDK)
komparator.x86_64 : Kompare and merge two folders
================================ Matched: meld =================================
meld.noarch : Visual diff and merge tool
python-meld3.x86_64 : An HTML/XML templating system for Python

yum search is useful for searching for packages you do not know the name of, but for which you know a related term.

Listing Packages

yum list and related commands provide information about packages, package groups, and repositories.

Tip: Filtering Results with Glob Expressions

All of Yum's various list commands allow you to filter the results by appending one or more glob expressions as arguments. Glob expressions consist of the wildcard characters * (which expands to match any character multiple times) and ? (which expands to match any one character). Be careful to escape both of these glob characters when passing them as arguments to a yum command. If you do not, the bash shell will interpret the glob expressions as pathname expansions, and potentially pass all files in the current directory that match the globs to yum, which is not what you want. Instead, you want to pass the glob expressions themselves to yum, which you can do by either:
  • escaping the wildcard characters
  • double-quoting or single-quoting the entire glob expression.
The following examples show both methods:
~]# yum list available gimp\*plugin\*
Loaded plugins: presto, refresh-packagekit, security
Available Packages
gimp-fourier-plugin.x86_64       0.3.2-3.fc11        fedora
gimp-lqr-plugin.x86_64           0.6.1-2.fc11        updates

Example 1.2. Filtering results using a single glob expression with two escaped wildcard characters

~]# yum list installed "krb?-*"
Loaded plugins: presto, refresh-packagekit, security
Installed Packages
krb5-auth-dialog.x86_64         0.12-2.fc12         @fedora
krb5-libs.x86_64                1.7-8.fc12          @fedora
krb5-workstation.x86_64         1.7-8.fc12          @fedora

Example 1.3. Filtering results using a double-quoted glob expression:

  • yum list <glob_expr> [more_glob_exprs] — List information on installed and available packages matching all glob expressions.
    ~]# yum list abrt-addon\* abrt-plugin\*
    Loaded plugins: presto, refresh-packagekit, security
    Installed Packages
    abrt-addon-ccpp.x86_64                          0.0.9-2.fc12            @fedora
    abrt-addon-kerneloops.x86_64                    0.0.9-2.fc12            @fedora
    abrt-addon-python.x86_64                        0.0.9-2.fc12            @fedora
    abrt-plugin-bugzilla.x86_64                     0.0.9-2.fc12            @fedora
    abrt-plugin-kerneloopsreporter.x86_64           0.0.9-2.fc12            @fedora
    abrt-plugin-sqlite3.x86_64                      0.0.9-2.fc12            @fedora
    Available Packages
    abrt-plugin-filetransfer.x86_64                 0.0.9-2.fc12            fedora
    abrt-plugin-logger.x86_64                       0.0.9-2.fc12            fedora
    abrt-plugin-mailx.x86_64                        0.0.9-2.fc12            fedora
    abrt-plugin-runapp.x86_64                       0.0.9-2.fc12            fedora
    abrt-plugin-sosreport.x86_64                    0.0.9-2.fc12            fedora
    abrt-plugin-ticketuploader.x86_64               0.0.9-2.fc12            fedora
    
    Example 1.4. Listing all ABRT addons and plugins using glob expressions

  • yum list all — List all installed and available packages.
  • yum list installed — List all packages installed on your system. The rightmost column in the output lists the repository the package was retrieved from, where installed indicates the package came pre-installed as a component of the base system.
  • yum list available — List all available packages in all enabled repositories.
  • yum grouplist — List all package groups.
  • yum repolist — List the repository ID, name, and number of packages it provides for each enabled repository.

Displaying Package Info

yum info <package_name> [more_names] displays information about one or more packages (glob expressions are valid here as well):
~]# yum info abrt
Loaded plugins: presto, refresh-packagekit, security
Installed Packages
Name       : abrt
Arch       : x86_64
Version    : 0.0.9
Release    : 2.fc12
Size       : 525 k
Repo       : installed
From repo  : fedora
Summary    : Automatic bug detection and reporting tool
URL        : https://fedorahosted.org/abrt/
License    : GPLv2+
Description: abrt is a tool to help users to detect defects in applications and
           : to create bug reports that include all information required by the
           : maintainer to hopefully resolve it. It uses a plugin system to extend
           : its functionality.

yum info <package_name> is similar to the rpm -q --info <package_name> command, but provides as additional information the ID of the Yum repository the RPM package is found in (look for the From repo: line in the output).

1.2.2. Installing

You can install a package and all of its non-installed dependencies by entering:
#]$ yum install <package_name> 

You can install multiple packages simultaneously by appending their names as arguments: yum install <package_name> [more_names] .
If you are installing packages on a multilib system, such as an AMD64 or Intel64 machine, you can specify the architecture of the package (as long as it's available in an enabled repository) by appending .arch to the package name:
~]# yum install sqlite2.i586

You can use glob expressions to quickly install multiple similarly-named packages:
~]# yum install audacious-plugins-\*

In addition to package names and glob expressions, you can also provide file names to yum install. If you know the name of the binary you want to install, but not its package name, you can give yum install the path name:
#]$ yum install /usr/sbin/named

yum then searches through its package lists, finds the package which provides /usr/sbin/named, if any, and prompts you as to whether you want to install it.
What if you know you want to install the package that contains the named binary, but don't know in which bin or sbin directory that file lives? In that situation, you can give yum provides a glob expression:
~]# yum provides "*bin/named"
Loaded plugins: presto, refresh-packagekit, security
32:bind-9.6.1-0.3.b1.fc11.x86_64 : The Berkeley Internet Name Domain (BIND) DNS (Domain Name System) server
Repo        : fedora
Matched from:
Filename    : /usr/sbin/named
~]# yum install bind

Example 1.5. Finding which package owns a file and installing it

Note

yum provides is the same as yum whatprovides.

Tip: yum provides/whatprovides and Glob Expressions

yum provides "*/<file_name>" is a common and useful trick to quickly find the package(s) that contain <file_name>.

Installing a Package Group

A package group is similar to a package: it is not useful itself, but installing one also pulls in a group of dependent packages that serve a common purpose. A package group has a name and a groupid. The yum grouplist -v command lists the names of all package groups, and, next to each of them, their groupid in parentheses. The groupid is always the term in the last pair of parentheses, such as kde-desktop and kde-software-development in this example:
~]# yum -v grouplist kde\*
KDE (K Desktop Environment) (kde-desktop)
KDE Software Development (kde-software-development)

You can install a package group by passing its full group name (without the groupid part) to groupinstall:
~]# yum groupinstall "KDE (K Desktop Environment)"

You can also install by groupid:
~]# yum groupinstall kde-desktop

You can even pass the groupid (or quoted name) to the install command if you prepend it with an @-symbol (which tells yum that you want to perform a groupinstall):
~]# yum install @kde-desktop

1.2.3. Removing

yum remove <package_name> uninstalls (removes in RPM and Yum terminology) the package, as well as any packages that depend on it. As when you install multiple packages, you can remove several at once by adding more package names to the command:
~]# yum remove foo bar baz

Similar to the install command, remove can take, as arguments, package names, glob expressions, file lists or package provides.

Warning: Removing a Package when Other Packages Depend On It

Yum is not able to remove a package without also removing packages which depend on it. This type of operation can only be performed by RPM, is not advised, and can potentially leave your system in a non-functioning state or cause applications to misbehave and/or crash. For further information, refer to Section 3.2.3, “Uninstalling” in the RPM chapter.

Removing a Package Group

You can remove a package group using syntax congruent with the install syntax:
~]# yum groupremove "KDE (K Desktop Environment)"
~]# yum groupremove kde-desktop
~]# yum remove @kde-desktop

Example 1.6. Alternative but equivalent ways of removing a package group

1.3. Configuring Yum and Yum Repositories

This section shows you how to:
  • set global Yum options by editing the [main] section of the /etc/yum.conf configuration file;
  • set options for individual repositories by editing the [repository] sections in /etc/yum.conf and .repo files in the /etc/yum.repos.d/ directory;
  • use Yum variables in /etc/yum.conf and files in /etc/yum.repos.d/so that dynamic version and architecture values are handled correctly; and,
  • set up your own custom Yum repository.
The /etc/yum.conf configuration file contains one mandatory [main] section under which you can set Yum options. The values that you define in the [main] section of yum.conf have global effect, and may override values set any individual [repository] sections. You can also add [repository] sections to /etc/yum.conf; however, best practice is to define individual repositories in new or existing .repo files in the /etc/yum.repos.d/directory. Refer to Section 1.3.2, “Setting [repository] Options” if you need to add or edit repository-specific information.

1.3.1. Setting [main] Options

The /etc/yum.conf configuration file contains exactly one [main] section. You can add many additional options under the [main] section heading in /etc/yum.conf. Some of the key-value pairs in the [main] section affect how yum operates; others affect how Yum treats repositories. The best source of information for all Yum options is in the [main] OPTIONS and [repository] OPTIONS sections of man yum.conf.
Here is a sample /etc/yum.conf configuration file:
[main]
cachedir=/var/cache/yum
keepcache=0
debuglevel=2
logfile=/var/log/yum.log
exactarch=1
obsoletes=1
gpgcheck=1
plugins=1
installonly_limit=3
[comments abridged]
# PUT YOUR REPOS HERE OR IN separate files named file.repo
# in /etc/yum.repos.d

Here is a list of the most commonly-used options in the [main] section, and descriptions for each:
cachedir=/var/cache/yum
This option specifies the directory where Yum should store its cache and database files. By default, Yum's cache directory is /var/cache/yum.
keepcache=<1 or 0>
Setting keepcache=1 instructs yum to keep the cache of headers and packages after a successful installation. keepcache=1 is the default.
reposdir=<absolute path to directory of .repo files>
This option allows you to specify a directory where .repo files are located. .repo files contain repository information (similar to the [repository] section(s) of /etc/yum.conf). yum collects all repository information from .repo files and the [repository] section of the /etc/yum.conf file to create a master list of repositories to use for transactions. Refer to Section 1.3.2, “Setting [repository] Options” for more information about options you can use for both the [repository] section and .repo files. If reposdir is not set, yum uses the default directory /etc/yum.repos.d/.
gpgcheck=<1 or 0>
This enables or disables GPG signature checking on packages in all repositories, including local package installation. The default is gpgcheck=0, which disables GPG-checking. If this option is set in the [main] section of the /etc/yum.conf file, it sets the GPG-checking rule for all repositories. However, you can also set this on individual repositories instead; i.e., you can enable GPG-checking on one repository while disabling it on another. Setting gpgcheck= for individual repositories overrides the default if it is present in /etc/yum.conf. Refer to Section 3.3, “Checking a Package's Signature” for further information on GPG signature-checking.
assumeyes=<1 or 0>
This determines whether or not yum should prompt for confirmation of critical actions. The default is assumeyes=0, which means yum will prompt you for confirmation. If assumeyes=1 is set, yum behaves in the same way that the command line option -y does.
exclude="<package_name> [more_names]"
This option allows you to exclude packages by keyword during installation/updates. Listing multiple packages for exclusion can be accomplished by quoting a space-delimited list of packages. Shell globs using wildcards (for example, * and ?) are allowed.
retries=<number_of_retries>
This sets the number of times yum should attempt to retrieve a file before returning an error. Setting this to 0 makes yum retry forever. The default value is 6.

1.3.2. Setting [repository] Options

You can define individual Yum repositories by adding [repository] sections (where repository is a unique repository ID, such as [my_personal_repo]) to /etc/yum.conf or to .repo files in the /etc/yum.repos.d/directory. All .repo files in /etc/yum.repos.d/are read by yum; best practice is to define your repositories here instead of in /etc/yum.conf. You can create new, custom .repo files in this directory, add [repository] sections to those files, and the next time you run a yum command, it will take all newly-added repositories into account.
Here is a (bare-minimum) example of the form a .repo file should take:
[repository_ID]
name=A Repository Name
baseurl=http://path/to/repo or ftp://path/to/repo or file://path/to/local/repo

Every [repository] section must contain the following minimum parts:
[repository_ID]
The repository ID is a unique, one-word (no spaces; underscores are allowed) string of characters (enclosed by brackets) that serves as a repository identifier.
name=<My Repository Name>
This is a human-readable string describing the repository.
baseurl=http://path/to/repo, ftp://path/to/repo, file://path/to/local/repo
This is a URL to the directory where the repodata directory of a repository is located. Usually this URL is an HTTP link, such as:
    baseurl=http://download.fedoraproject.org/pub/fedora/linux/releases/$releasever/Everything/$basearch/os/

Yum always expands the $releasever, $arch and $basearch variables in URLs. See the following section for explanations of all Yum variables: Section 1.3.3, “Using Yum Variables”.
  • If the repository is available over FTP, use: ftp://path/to/repo
  • If the repository is local to the machine, use file://path/to/local/repo
  • If a specific online repository requires basic HTTP authentication, you can specify your username and password in the baseurl= line by prepending it as username:password@link. For example, if a repository on http://www.example.com/repo/ requires a username of "user" and a password of "password", then the baseurl link can be specified as baseurl=http://user:password@www.example.com/repo/
Here are some other useful-but-optional [repository] options:
enabled=<1 or 0>
Setting enabled=0 instructs yum not to include that repository as a package source when performing updates and installs. This is an easy way of quickly turning repositories on and off, which is useful when you desire a single package from a repository that you do not want to enable for updates, etc. Turning repositories on and off can also be performed quickly by passing either the --enablerepo=<repo_name> or --disablerepo=<repo_name> option to yum, or easily through PackageKit's Add/Remove Software window. For the latter, refer to Section 2.2.1, “Refreshing Software Sources (Yum Repositories)”.
Many more [repository] options exist. Refer to the [repository] OPTIONS section of man yum.conf for the exhaustive list.

1.3.3. Using Yum Variables

You can use and reference the following variables in yum commands and in all Yum configuration files (/etc/yum.conf and all .repo files in /etc/yum.repos.d/.
$releasever
You can use this variable to reference the release version of Fedora. Yum obtains the value of $releasever from the distroverpkg=<value> line in the /etc/yum.conf configuration file. If there is no such line in /etc/yum.conf, then yum infers the correct value by deriving the version number from the redhat-release package.
$arch
You can use this variable to refer to the system's CPU architecture as returned when calling Python's os.uname() function. Valid values for $arch include: i586, i686 and x86_64.
$basearch
You can use $basearch to reference the base architecture of the system. For example, i686 and i586 machines both have a base architecture of i386, and AMD64 and Intel64 machines have a base architecture of x86_64.
$YUM0-9
These ten variables are each replaced with the value of any shell environment variables with the same name. If one of these variables is referenced (in /etc/yum.conf for example) and a shell environment variable with the same name does not exist, then the configuration file variable is not replaced.

1.3.4. Creating a Yum Repository

To set up a Yum repository, follow these steps:
Procedure 1.1. Setting Up a Yum repository
  1. Install the createrepo package:
    ~]# yum install createrepo
    
    
  2. Copy all of the packages into one directory, such as /mnt/local_repo/.
  3. Run the createrepo --database command on that directory:
    ~]# createrepo --database /mnt/local_repo
    
    
This will create the necessary metadata for your Yum repository, as well as the sqlite database for speeding up yum operations.

1.4. Yum Plugins

Yum provides plugins that extend and enhance its operations. Certain plugins are installed by default. Yum always informs you which plugins, if any, are loaded and in effect whenever you call any yum command:
~]# yum info yum
Loaded plugins: presto, refresh-packagekit, security
[output truncated]

Note that the plugin names which follow Loaded plugins are the names you can provide to the --disableplugins=<plugin_name> option.

1.4.1. Enabling, Configuring and Disabling Yum Plugins

To enable Yum plugins, ensure that a line beginning with plugins= is present in the [main] section of /etc/yum.conf, and that its value is set to 1:
plugins=1

You can disable all plugins by changing this line to plugins=0.
Every installed plugin has its own configuration file in the /etc/yum/pluginconf.d/ directory. You can set plugin-specific options in these files. For example, here is the security plugin's security.conf configuration file:
[main]
enabled=1

Example 1.7. A minimal Yum plugin configuration file

Plugin configuration files always contain a [main] section (similar to Yum's /etc/yum.conf file) in which there is (or you can place if it is missing) an enabled= option that controls whether the plugin is enabled when you run yum commands.
If you disable all plugins by setting enabled=0 in /etc/yum.conf, then all plugins are disabled regardless of whether they are enabled in their individual configuration files.
If you merely want to disable all Yum plugins for a single yum command, use the --noplugins option.
If you simply want to disable one or more Yum plugins for a single yum command, then you can add the --disableplugin=<plugin_name> option to the command:
~]# yum update --disableplugin=presto

Example 1.8. Disabling the presto plugin while running yum update

The plugin names you provide to the --disableplugin= option are the same names listed after the Loaded plugins: line in the output of any yum command. You can disable multiple plugins by separating their names with commas. In addition, you can match multiple similarly-named plugin names or simply shorten long ones by using glob expressions: --disableplugin=presto,refresh-pack*.

1.4.2. Installing More Yum Plugins

Yum plugins usually adhere to the yum-plugin-<plugin_name> package-naming convention, but not always: the package which provides the presto plugin is named yum-presto, for example. You can install a Yum plugin in the same way you install other packages:
~]# yum install yum-plugin-security

1.4.3. Plugin Descriptions

Here are descriptions of a few useful Yum plugins:

presto (yum-presto)

The presto plugin adds support to Yum for downloading delta RPM packages, during updates, from repositories which have presto metadata enabled. Delta RPMs contain only the differences between the version of the the package installed on the client requesting the RPM package and the updated version in the repository. Downloading a delta RPM is much quicker than downloading the entire updated package, and can speed up updates considerably. Once the delta RPMs are downloaded, they must be rebuilt (the difference applied to the currently-installed package to create the full updated package) on the installing machine, which takes CPU time. Using delta RPMs is therefore a tradeoff between time-to-download, which depends on the network connection, and time-to-rebuild, which is CPU-bound. Using the presto plugin is recommended for fast machines and systems with slower network connections, while slower machines on very fast connections may benefit more from downloading normal RPM packages, i.e. by disabling presto. The presto plugin is enabled by default.

protect-packages (yum-plugin-protect-packages)

The protect-packages plugin prevents the yum package and all packages it depends on from being purposefully or accidentally removed. This simple scheme prevents many of the most important packages necessary for your system to run from being removed. In addition, you can list more packages, one per line, in the /etc/sysconfig/protected-packages file [1] (which you should create if it does not exist), and protect-packages will extend protection-from-removal to those packages as well. To temporarily override package protection, use the --override-protection option with an applicable yum command.

refresh-packagekit (PackageKit-yum-plugin)

This plugin updates metadata for PackageKit whenever yum is run. The refresh-packagkit plugin is installed by default.

security (yum-plugin-security)

Discovering information about and applying security updates easily and often is important to all system administrators. For this reason Yum provides the security plugin, which extends yum with a set of highly-useful security-related commands, subcommands and options.
You can check for all security-related updates as follows:
~]# yum check-update --security
Loaded plugins: presto, refresh-packagekit, security
Limiting package lists to security relevant ones
Needed 3 of 7 packages, for security
elinks.x86_64                   0.12-0.13.pre3.fc11       fedora
kernel.x86_64                   2.6.30.8-64.fc11          fedora
kernel-headers.x86_64           2.6.30.8-64.fc11          fedora
You can then update the system using only the security-related updates (and excluding all others, such as bug fix updates) with the command:
~]# yum update --security

Example 1.9. Updating only security-related packages

Refer to man yum-security for usage details and further explanation of the enhancements the security plugin adds to yum.

1.5. Additional Resources

The Yum home page and wiki — http://yum.baseurl.org/wiki/Guides
The Yum Guides section of the wiki contains more Yum documentation.
Managing Software with Yumhttp://docs.fedoraproject.org/yum/en/index.html
A useful resource that provides additional information about using the Yum package manager.


[1] You can also place files with the extension .list in the /etc/sysconfig/protected-packages.d/ directory (which you should create if it does not exist), and list packages—one per line—in these files. protect-packages will protect these too.

Chapter 2. PackageKit

Fedora provides PackageKit for viewing, managing, updating, installing and uninstalling packages compatible with your system. PackageKit consists of several graphical interfaces that can be opened from the GNOME panel menu, or from the Notification Area when PackageKit alerts you that updates are available. For more information on PackageKit's architecture and available front ends, refer to Section 2.3, “PackageKit Architecture”.

2.1. Updating Packages with Software Update

PackageKit displays a starburst icon in the Notification Area whenever updates are available to be installed on your system.
Clicking on the notification icon opens the Software Update window. Alternatively, you can open Software Updates by clicking SystemAdministrationSoftware Update from the GNOME panel, or running the gpk-update-viewer command at the shell prompt. In the Software Updates window, all available updates are listed along with the names of the packages being updated (minus the .rpm suffix, but including the CPU architecture), a short summary of the package, and, usually, short descriptions of the changes the update provides. Any updates you do not wish to install can be de-selected here by unchecking the checkbox corresponding to the update.
Installing updates with Software Update
installing 12 updates with packagekit's software update window
Figure 2.1. Installing updates with Software Update

The updates presented in the Software Updates window only represent the currently-installed packages on your system for which updates are available; dependencies of those packages, whether they are existing packages on your system or new ones, are not shown until you click Install Updates.
PackageKit utilizes the fine-grained user authentication capabilities provided by the PolicyKit toolkit whenever you request it to make changes to the system. Whenever you instruct PackageKit to update, install or remove packages, you will be prompted to enter the superuser password before changes are made to the system.
PackageKit uses PolicyKit to authenticate
packagekit defers to policykit to provide authentication in order to make changes to the system
Figure 2.2. PackageKit uses PolicyKit to authenticate

If you instruct PackageKit to update the kernel package, then it will prompt you after installation, asking you whether you want to reboot the system and thereby boot into the newly-installed kernel.

Setting the Update-Checking Interval

Right-clicking on PackageKit's Notification Area icon and clicking Preferences opens the Software Update Preferences window, where you can define the interval at which PackageKit checks for package updates, as well as whether or not to automatically install all updates or only security updates, and how often to check for major upgrades. Leaving the Check for updates when using mobile broadband box unchecked is handy for avoiding extraneous bandwidth usage when using a wireless connection on which you are charged for the amount of data you download.
Setting PackageKit's update-checking interval
Setting the update-checking interval for packagekit by right-clicking on the notification area applet
Figure 2.3. Setting PackageKit's update-checking interval

2.2. Using Add/Remove Software

PackageKit's Software Update GUI window is a separate application from its Add/Remove Software application, although the two have intuitively similar interfaces. To find and install a new package, on the GNOME panel click on SystemAdministrationAdd/Remove Software, or run the gpk-application command at the shell prompt.
PackageKit's Add/Remove Software window
viewing packagekit's add/remove softvware window
Figure 2.4. PackageKit's Add/Remove Software window

2.2.1. Refreshing Software Sources (Yum Repositories)

PackageKit refers to Yum repositories as software sources. It obtains all packages from enabled software sources. You can view the list of all configured and unfiltered (see below) Yum repositories by opening Add/Remove Software and clicking SystemSoftware sources. The Software Sources dialog shows the repository name, as written on the name=<My Repository Name> field of all [repository] sections in the /etc/yum.conf configuration file, and in all repository.repo files in the /etc/yum.repos.d/ directory.
Entries which are checked in the Enabled column indicate that the corresponding repository will be used to locate packages to satisfy all update and installation requests (including dependency resolution). The Enabledcolumn corresponds to the enabled=<1 or 0> field in [repository] sections. Checking an unchecked box enables the Yum repository, and unchecking it disables it. Performing either function causes PolicyKit to prompt for superuser authentication to enable or disable the repository. PackageKit actually inserts the enabled=<1 or 0> line into the correct [repository] section if it does not exist, or changes the value if it does. This means that enabling or disabling a repository through the Software Sources window causes that change to persist after closing the window or rebooting the system. The ability to quickly enable and disable repositories based on our needs is a highly-convenient feature of PackageKit.
Note that it is not possible to add or remove Yum repositories through PackageKit. Refer to Section 1.3, “Configuring Yum and Yum Repositories” for information on how to set up and configure Yum repositories.

Showing Source RPM, Test and Debuginfo Repositories

Checking the box at the bottom of the Software Sources window causes PackageKit to display source RPM, testing and debuginfo repositories as well. This box is unchecked by defaut.
After enabling and/or disabling the correct Yum repositories, ensure that you have the latest list of available packages. Click on SystemRefresh package lists and PackageKit will obtain the latest lists of packages from all enabled software sources, i.e. Yum repositories.

2.2.2. Finding Packages with Filters

Once the software sources have been updated, it is often beneficial to apply some filters so that PackageKit retrieves the results of our Find queries faster. This is especially helpful when performing many package searches. Four of the filters in the Filters drop-down menu are used to split results by matching or not matching a single criterium. By default when PackageKit starts, these filters are all unapplied (No filter), but once you do filter by one of them, that filter remains set until you either change it or close PackageKit.
Because you are usually searching for available packages that are not installed on the system, click FiltersInstalled and select the Only available radio button.
Filtering out already-installed packages
filtering out packages which are already installed
Figure 2.5. Filtering out already-installed packages

Also, unless we require development files such as C header files, we can filter for Only end user files and, in doing so, filter out all of the <package_name>-devel packages we are not interested in.
Filtering out development packages from the list of Find results
filtering out development packages from our results
Figure 2.6. Filtering out development packages from the list of Find results

The two remaining filters with submenus are:
Graphical
Narrows the search to either applications which provide a GUI interface or those that do not (Only text). This filter is useful when browsing for GUI applications that perform a specific function.
Free
Search for packages which are considered to be free software Refer to the Fedora Licensing List for details on licenses approved by the Fedora Project.
The remaining checkbox filters are always either checked or unchecked. They are:
Hide subpackages
Checking the Hide subpackages checkbox filters out generally-uninteresting packages that are typically only dependencies of other packages that we want. For example, checking Hide subpackages and searching for <package> would cause the following related packages to be filtered out of the Find results (if it exists):
  • <package>-devel
  • <package>-libs
  • <package>-libs-devel
  • <package>-debuginfo
Only newest items
Checking Only newest items filters out all older versions of the same package from the list of results, which is generally what we want.

Important: Using the Only newest items filter

Checking Only newest items filters out all but the most recent version of any package from the results list. This filter is often combined with the Only available filter to search for the latest available versions of new (not installed) packages.
Only native packages
Checking the Only native packages box on a multilib system causes PackageKit to omit listing results for packages compiled for the architecture that runs in compatibility mode. For example, enabling this filter on a 64-bit system with an AMD64 CPU would cause all packages built for the 32-bit x86 CPU architecture not to be shown in the list of results, even though those packages are able to run on an AMD64 machine. Packages which are architecture-agnostic (i.e. noarch packages such as crontabs-1.10-31.fc12.noarch.rpm) are never filtered out by checking Only native packages. This filter has no affect on non-multilib systems, such as x86 machines.

2.2.3. Installing and Removing Packages (and Dependencies)

With the two filters selected, Only available and Only end user files, search for the htop interactive process viewer and highlight the package. You now have access to some very useful information about it, including: a clickable link to the project homepage; the Yum package group it is found in, if any; the license of the package; a pointer to the GNOME menu location from where the application can be opened, if applicable (ApplicationsSystem ToolsHtop in our case); and the size of the package, which is relevant when we download and install it.
Viewing and installing a package with PackageKit's Add/Remove Software window
Viewing and installing a package with PackageKit's Add/Remove Software window
Figure 2.7. Viewing and installing a package with PackageKit's Add/Remove Software window

When the checkbox next to a package or group is checked, then that item is already installed on the system. Checking an unchecked box causes it to be marked for installation, which only occurs when the Apply button is clicked. In this way, you can search for and select multiple packages or package groups before performing the actual installation transactions. Additionally, you can remove installed packages by unchecking the checked box, and the removal will occur along with any pending installations when Apply is pressed. Dependency resolution, which may add additional packages to be installed or removed, is performed after pressing Apply. PackageKit will then display a window listing those additional packages to install or remove, and ask for confirmation to proceed.
Check htop and click the Apply button. You will then be prompted for the superuser password; enter it, and PackageKit will install htop. One nice feature of PackageKit is that, following installation, it sometimes presents you with a list of your newly-installed applications and offer you the choice of running them immediately. Alternatively, you will remember that finding a package and selecting it in the Add/Remove Software window shows you the Location of where in the GNOME menus its application shortcut is located, which is helpful when you want to run it.
Once it is installed, you can run htop, an colorful and enhanced version of the top process viewer, by opening a shell prompt and entering:
~]$ htop

Viewing processes with htop!
htop is nifty, but we decide that top is good enough for us and we want to uninstall it. Remembering that we need to change the Only installed filter we recently used to install it to Only installed in FiltersInstalled, we search for htop again and uncheck it. The program did not install any dependencies of its own; if it had, those would be automatically removed as well, as long as they were not also dependencies of any other packages still installed on our system.

Warning: Removing a Package when Other Packages Depend On It

Although PackageKit automatically resolves dependencies during package installation and removal, it is unable to remove a package without also removing packages which depend on it. This type of operation can only be performed by RPM, is not advised, and can potentially leave your system in a non-functioning state or cause applications to misbehave and/or crash. For further information, refer to Section 3.2.3, “Uninstalling”.
Removing a package with PackageKit's Add/Remove Software window
removing the htop package with packagekit's add/remove software window
Figure 2.8. Removing a package with PackageKit's Add/Remove Software window

2.2.4. Installing and Removing Package Groups

PackageKit also has the ability to install Yum package groups, which it calls Package collections. Clicking on Package collections in the top-left list of categories in the Software Updates window allows us to scroll through and find the package group we want to install. In this case, we want to install Czech language support (the Czech Support group). Checking the box and clicking apply informs us how many additional packages must be installed in order to fulfill the dependencies of the package group.
Installing the Czech Support package group
using packagekit to install czech language support with packagekit's add/remove software window
Figure 2.9. Installing the Czech Support package group

Similarly, installed package groups can be uninstalled by selecting Package collections, unchecking the appropriate checkbox, and Applying.

2.2.5. Viewing the Transaction Log

PackageKit maintains a log of the transactions that it performs. To view the log, from the Add/Remove Software window, click SystemSoftware log, or run the gpk-log command at the shell prompt.
The Software Log Viewer shows the Action, such as Updated System or Installed Packages, the Date on which that action was performed, the Username of the user who performed the action, and the front end Application the user used (such as Update Icon, or kpackagekit). The Details column provides the types of the transactions, such as Updated, Installed or Removed, as well as the list of packages the transactions were performed on.
Viewing the log of package management transactions with the Software Log Viewer
viewing the log of package management transactions with packagekit's loftware log viewer window
Figure 2.10. Viewing the log of package management transactions with the Software Log Viewer

Typing the name of a package in the top text entry field filters the list of transactions to those which affected that package.

2.3. PackageKit Architecture

Fedora provides the PackageKit suite of applications for viewing, updating, installing and uninstalling packages and package groups compatible with your system. Architecturally, PackageKit consists of several graphical front ends that communicate with the packagekitd daemon back end, which communicates with a package manager-specific back end that utilizes Yum (on Fedora) to perform the actual transactions, such as installing and removing packages, etc.
Table 2.1, “PackageKit GUI Windows, Menu Locations, and Shell Prompt Commands” shows the name of the GUI window, how to start the window from the GNOME desktop or from the Add/Remove Software window, and the name of the command line application that opens that window.
Window Title Function How to Open Shell Command
Add/Remove Software Install, remove or view package info
From the GNOME panel: SystemAdministrationAdd/Remove Software
gpk-application
Software Update Perform package updates
From the GNOME panel: SystemAdministrationSoftware Update
gpk-update-viewer
Software Sources Enable and disable Yum repositories
From Add/Remove Software: SystemSoftware sources
gpk-repo
Software Log Viewer View the transaction log
From Add/Remove Software: SystemSoftware log
gpk-log
Software Update Preferences Set PackageKit preferences gpk-prefs
(Notification Area Alert) Alerts you when updates are available
From the GNOME panel: SystemPreferencesSession and Startup, Application Autostart tab
gpk-update-icon
Table 2.1. PackageKit GUI Windows, Menu Locations, and Shell Prompt Commands

The packagekitd daemon runs outside the user session and communicates with the various graphical front ends. The packagekitd daemon[2] communicates via the DBus system message bus with another back end, which utilizes Yum's Python API to perform queries and make changes to the sytem. On Linux systems other than Fedora, packagekitd can communicate with other back ends that are able to utilize the native package manager for that system. This modular architecture provides the abstraction necessary for the graphical interfaces to work with many different package managers to perform essentially the same types of package management tasks. Learning how to use the PackageKit front ends means that you can use the same familiar graphical interface across many different Linux distributions, even when they utilize a native package manager other than Yum.
In addition, PackageKit's separation of concerns provides reliability in that a crash of one of the GUI windows—or even the user's X Window session—will not affect any package management tasks being supervised by the packagekitd daemon, which runs outside of the user session.
All of the front end graphical applications discussed in this chapter are provided by the gnome-packagekit package instead of by PackageKit and its dependencies. Users working in a KDE environment may prefer to install the kpackagekit package, which provides a KDE interface for PackageKit.
Finally, PackageKit also comes with a console-based frontend called pkcon.

2.4. Additional Resources

PackageKit home page — http://www.packagekit.org/index.html
Information about and mailing lists for PackageKit.
PackageKit FAQ — http://www.packagekit.org/pk-faq.html
An informative list of Frequently Asked Questions for the PackageKit software suite.
PackageKit Feature Matrix — http://www.packagekit.org/pk-matrix.html
Cross-reference PackageKit-provided features with the long list of package manager back ends.


[2] System daemons are typically long-running processes that provide services to the user or to other programs, and which are started, often at boot time, by special initialization scripts (often shortened to init scripts). Daemons respond to the service command and can be turned on or off permanently by using the chkconfig on or chkconfig offcommands. They can typically be recognized by a d appended to their name, such as the packagekitd daemon. Refer to Chapter 6, Controlling Access to Services for information about system services.

Chapter 3. RPM

The RPM Package Manager (RPM) is an open packaging system, which runs on Fedora as well as other Linux and UNIX systems. Red Hat, Inc. and the Fedora Project encourage other vendors to use RPM for their own products. RPM is distributed under the terms of the GPL (GNU General Public License).
The RPM Package Manager only works with packages built to work with the RPM format. RPM is itself provided as a pre-installed rpm package. For the end user, RPM makes system updates easy. Installing, uninstalling and upgrading RPM packages can be accomplished with short commands. RPM maintains a database of installed packages and their files, so you can invoke powerful queries and verifications on your system. If you prefer a graphical interface, you can use the PackageKit GUI to perform many RPM commands. Refer to Chapter 2, PackageKit for details.

Important

When installing a package, ensure it is compatible with your operating system and processor architecture. This can usually be determined by checking the package name. Many of the following examples show RPM packages compiled for the AMD64/Intel 64 computer architectures; thus, the RPM file name ends in x86_64.rpm.
During upgrades, RPM handles configuration files carefully, so that you never lose your customizations—something that you cannot accomplish with regular .tar.gz files.
For the developer, RPM allows you to take software source code and package it into source and binary packages for end users. This process is quite simple and is driven from a single file and optional patches that you create. This clear delineation between pristine sources and your patches along with build instructions eases the maintenance of the package as new versions of the software are released.

Note

Because RPM makes changes to your system, you must be logged in as root to install, remove, or upgrade an RPM package.

3.1. RPM Design Goals

To understand how to use RPM, it can be helpful to understand the design goals of RPM:
Upgradability
With RPM, you can upgrade individual components of your system without completely reinstalling. When you get a new release of an operating system based on RPM, such as Fedora, you do not need to reinstall a fresh copy of the operating system your machine (as you might need to with operating systems based on other packaging systems). RPM allows intelligent, fully-automated, in-place upgrades of your system. In addition, configuration files in packages are preserved across upgrades, so you do not lose your customizations. There are no special upgrade files needed to upgrade a package because the same RPM file is used to both install and upgrade the package on your system.
Powerful Querying
RPM is designed to provide powerful querying options. You can perform searches on your entire database for packages or even just certain files. You can also easily find out what package a file belongs to and from where the package came. The files an RPM package contains are in a compressed archive, with a custom binary header containing useful information about the package and its contents, allowing you to query individual packages quickly and easily.
System Verification
Another powerful RPM feature is the ability to verify packages. If you are worried that you deleted an important file for some package, you can verify the package. You are then notified of anomalies, if any—at which point you can reinstall the package, if necessary. Any configuration files that you modified are preserved during reinstallation.
Pristine Sources
A crucial design goal was to allow the use of pristine software sources, as distributed by the original authors of the software. With RPM, you have the pristine sources along with any patches that were used, plus complete build instructions. This is an important advantage for several reasons. For instance, if a new version of a program is released, you do not necessarily have to start from scratch to get it to compile. You can look at the patch to see what you might need to do. All the compiled-in defaults, and all of the changes that were made to get the software to build properly, are easily visible using this technique.
The goal of keeping sources pristine may seem important only for developers, but it results in higher quality software for end users, too.

3.2. Using RPM

RPM has five basic modes of operation (not counting package building): installing, uninstalling, upgrading, querying, and verifying. This section contains an overview of each mode. For complete details and options, try rpm --help or man rpm. You can also refer to Section 3.5, “Additional Resources” for more information on RPM.

3.2.1. Finding RPM Packages

Before using any RPM packages, you must know where to find them. An Internet search returns many RPM repositories, but if you are looking for RPM packages built by the Fedora Project, they can be found at the following locations:
  • The Fedora installation media contain many installable RPMs.
  • The initial RPM repositories provided with the YUM package manager. Refer to Chapter 1, Yum for details on how to use the official Fedora package repositories.
  • Unofficial, third-party repositories not affiliated with the Fedora Project also provide RPM packages.

    Important

    When considering third-party repositories for use with your Fedora system, pay close attention to the repository's web site with regard to package compatibility before adding the repository as a package source. Alternate package repositories may offer different, incompatible versions of the same software, including packages already included in the Fedora repositories.

3.2.2. Installing

RPM packages typically have file names like tree-1.5.2.2-4.fc12.x86_64.rpm. The file name includes the package name (tree), version (1.5.2.2), release (4), operating system major version (fc12) and CPU architecture (x86_64). Assuming the tree-1.5.2.2-4.fc12.x86_64.rpm package is in the current directory, log in as root and type the following command at a shell prompt to install it:
rpm -ivh tree-1.5.2.2-4.fc12.x86_64.rpm

The -i option tells rpm to install the package, and the v and h options, while aren't strictly necessary, increase output information and display a progress meter, respectively.
Alternatively, you can use the -U option, which upgrades the package if an older version is already installed, or simply installs it if not:
rpm -Uvh tree-1.5.2.2-4.fc12.x86_64.rpm

If the installation is successful, the following output is displayed:
Preparing...                ########################################### [100%]
   1:tree                   ########################################### [100%]
As you can see, RPM prints out the name of the package and then prints a succession of hash marks as a progress meter while the package is installed.
The signature of a package is checked automatically when installing or upgrading a package. The signature confirms that the package was signed by an authorized party. For example, if the verification of the signature fails, an error message such as the following is displayed:
error: tree-1.5.2.2-4.fc12.x86_64.rpm: Header V3 RSA/SHA256 signature: BAD, key ID
d22e77f2
If it is a new, header-only, signature, an error message such as the following is displayed:
error: tree-1.5.2.2-4.fc12.x86_64.rpm: Header V3 RSA/SHA256 signature: BAD,
key ID d22e77f2
If you do not have the appropriate key installed to verify the signature, the message contains the word NOKEY:
warning: tree-1.5.2.2-4.fc12.x86_64.rpm: Header V3 RSA/SHA1 signature: NOKEY, key ID 57bbccba
Refer to Section 3.3, “Checking a Package's Signature” for more information on checking a package's signature.

Warning

If you are installing a kernel package, you should always use the rpm -ivh command (simple install) instead of rpm -Uvh. The reason for this is that install (-i) and upgrade (-U) take on specific meanings when installing kernel packages. Refer to Chapter 29, Manually Upgrading the Kernel for details.

3.2.2.1. Package Already Installed

If a package of the same name and version is already installed, the following output is displayed:
Preparing...                ########################################### [100%]
	package tree-1.5.2.2-4.fc12.x86_64 is already installed
However, if you want to install the package anyway, you can use the --replacepkgs option, which tells RPM to ignore the error:
rpm -ivh --replacepkgs tree-1.5.2.2-4.fc12.x86_64.rpm

This option is helpful if files installed from the RPM were deleted or if you want the original configuration files from the RPM to be installed.

3.2.2.2. Conflicting Files

If you attempt to install a package that contains a file which has already been installed by another package, the following is displayed:
Preparing...                ##################################################
 file /usr/bin/foobar from install of foo-1.0-1.fc12 conflicts
with file from package bar-3.1.1.fc12
To make RPM ignore this error, use the --replacefiles option:
rpm -ivh --replacefiles foo-1.0-1.fc12.x86_64.rpm

3.2.2.3. Unresolved Dependency

RPM packages may sometimes depend on other packages, which means that they require other packages to be installed to run properly. If you try to install a package which has an unresolved dependency, output similar to the following is displayed:
error: Failed dependencies:
	bar.so.3()(64bit) is needed by foo-1.0-1.fc12.x86_64
    Suggested resolutions:
        bar-3.1.1.fc12.x86_64.rpm
If you are installing a package from the Fedora installation media, such as from a CD-ROM or DVD, it usually suggests the package or packages needed to resolve the dependency. Find the suggested package(s) on the Fedora installation media or on one of the active Fedora mirrors (http://mirrors.fedoraproject.org/publiclist/) and add it to the command:
rpm -ivh foo-1.0-1.fc12.x86_64.rpm    bar-3.1.1.fc12.x86_64.rpm

If installation of both packages is successful, output similar to the following is displayed:
Preparing...                ########################################### [100%]
   1:foo                   ########################################### [ 50%]
   2:bar                   ########################################### [100%]
If it does not suggest a package to resolve the dependency, you can try the --whatprovides option to determine which package contains the required file.
rpm -q --whatprovides "bar.so.3"

If the package that contains bar.so.3 is in the RPM database, the name of the package is displayed:
bar-3.1.1.fc12.i586.rpm

Warning: Forcing Package Installation

Although we can force rpm to install a package that gives us a Failed dependencies error (using the --nodeps option), this is not recommended, and will usually result in the installed package failing to run. Installing or removing packages with rpm --nodeps can cause applications to misbehave and/or crash, and can cause serious package management problems or, possibly, system failure. For these reasons, it is best to heed such warnings; the package manager—whether RPM, Yum or PackageKit—shows us these warnings and suggests possible fixes because accounting for dependencies is critical. The Yum package manager can perform dependency resolution and fetch dependencies from online repositories, making it safer, easier and smarter than forcing rpm to carry out actions without regard to resolving dependencies.

3.2.3. Uninstalling

Uninstalling a package is just as simple as installing one. Type the following command at a shell prompt:
rpm -e foo

Note

Notice that we used the package name foo, not the name of the original package file, foo-1.0-1.fc12.x86_64. If you attempt to uninstall a package using the rpm -e command and the original full file name, you will receive a package name error.
You can encounter dependency errors when uninstalling a package if another installed package depends on the one you are trying to remove. For example:
rpm -e ghostscript
error: Failed dependencies:
	libgs.so.8()(64bit) is needed by (installed) libspectre-0.2.2-3.fc12.x86_64
	libgs.so.8()(64bit) is needed by (installed) foomatic-4.0.3-1.fc12.x86_64
	libijs-0.35.so()(64bit) is needed by (installed) gutenprint-5.2.4-5.fc12.x86_64
	ghostscript is needed by (installed) printer-filters-1.1-4.fc12.noarch
Similar to how we searched for a shared object library (i.e. a <library_name>.so.<number> file) in Section 3.2.2.3, “Unresolved Dependency”, we can search for a 64-bit shared object library using this exact syntax (and making sure to quote the file name):
~]# rpm -q --whatprovides "libgs.so.8()(64bit)"
ghostscript-8.70-1.fc12.x86_64

Warning: Forcing Package Installation

Although we can force rpm to remove a package that gives us a Failed dependencies error (using the --nodeps option), this is not recommended, and may cause harm to other installed applications. Installing or removing packages with rpm --nodeps can cause applications to misbehave and/or crash, and can cause serious package management problems or, possibly, system failure. For these reasons, it is best to heed such warnings; the package manager—whether RPM, Yum or PackageKit—shows us these warnings and suggests possible fixes because accounting for dependencies is critical. The Yum package manager can perform dependency resolution and fetch dependencies from online repositories, making it safer, easier and smarter than forcing rpm to carry out actions without regard to resolving dependencies.

3.2.4. Upgrading

Upgrading a package (using the -U option) is similar to installing one (the -i option). If we have the RPM named tree-1.5.3.0-1.fc12.x86_64.rpm in our current directory, and tree-1.5.2.2-4.fc12.x86_64.rpm is already installed on our system (rpm -qi will tell us which version of the tree package we have installed on our system, if any), then the following command will upgrade tree to the newer version:
rpm -Uvh tree-1.5.3.0-1.fc12.x86_64.rpm

As part of upgrading a package, RPM automatically uninstalls any old versions of the foo package. Note that -U will also install a package even when there are no previous versions of the package installed.

Important

It is not advisable to use the -U option for installing kernel packages because RPM completely replaces the previous kernel package. This does not affect a running system, but if the new kernel is unable to boot during your next restart, there would be no other kernel to boot instead.
Using the -i option adds the kernel to your GRUB boot menu (/etc/grub.conf). Similarly, removing an old, unneeded kernel removes the kernel from GRUB.
Because RPM performs intelligent upgrading of packages with configuration files, you may see one or the other of the following messages:
saving /etc/foo.conf as /etc/foo.conf.rpmsave
This message means that changes you made to the configuration file may not be forward-compatible with the new configuration file in the package, so RPM saved your original file and installed a new one. You should investigate the differences between the two configuration files and resolve them as soon as possible, to ensure that your system continues to function properly.
Alternatively, RPM may save the package's new configuration file as, for example, foo.conf.rpmnew, and leave the configuration file you modified untouched. You should still resolve any conflicts between your modified configuration file and the new one, usually by merging changes from the old one to the new one with a diff program.
If you attempt to upgrade to a package with an older version number (that is, if a higher version of the package is already installed), the output is similar to the following:
package foo-2.0-1.fc12.x86_64.rpm (which is newer than foo-1.0-1) is already installed
To force RPM to upgrade anyway, use the --oldpackage option:
rpm -Uvh --oldpackage foo-1.0-1.fc12.x86_64.rpm

3.2.5. Freshening

Freshening is similar to upgrading, except that only existent packages are upgraded. Type the following command at a shell prompt:
rpm -Fvh foo-2.0-1.fc12.x86_64.rpm

RPM's freshen option checks the versions of the packages specified on the command line against the versions of packages that have already been installed on your system. When a newer version of an already-installed package is processed by RPM's freshen option, it is upgraded to the newer version. However, RPM's freshen option does not install a package if no previously-installed package of the same name exists. This differs from RPM's upgrade option, as an upgrade does install packages whether or not an older version of the package was already installed.
Freshening works for single packages or package groups. If you have just downloaded a large number of different packages, and you only want to upgrade those packages that are already installed on your system, freshening does the job. Thus, you do not have to delete any unwanted packages from the group that you downloaded before using RPM.
In this case, issue the following with the *.rpm glob:
rpm -Fvh *.rpm

RPM then automatically upgrades only those packages that are already installed.

3.2.6. Querying

The RPM database stores information about all RPM packages installed in your system. It is stored in the directory /var/lib/rpm/, and is used to query what packages are installed, what versions each package is, and to calculate any changes to any files in the package since installation, among other use cases.
To query this database, use the -q option. The rpm -q package name command displays the package name, version, and release number of the installed package <package_name>. For example, using rpm -q tree to query installed package tree might generate the following output:
tree-1.5.2.2-4.fc12.x86_64
You can also use the following Package Selection Options (which is a subheading in the RPM man page: see man rpm for details) to further refine or qualify your query:
  • -a — queries all currently installed packages.
  • -f <file_name> — queries the RPM database for which package owns <file_name> . Specify the absolute path of the file (for example, rpm -qf /bin/ls instead of rpm -qf ls).
  • -p <package_file> — queries the uninstalled package <package_file> .
There are a number of ways to specify what information to display about queried packages. The following options are used to select the type of information for which you are searching. These are called the Package Query Options.
  • -i displays package information including name, description, release, size, build date, install date, vendor, and other miscellaneous information.
  • -l displays the list of files that the package contains.
  • -s displays the state of all the files in the package.
  • -d displays a list of files marked as documentation (man pages, info pages, READMEs, etc.) in the package.
  • -c displays a list of files marked as configuration files. These are the files you edit after installation to adapt and customize the package to your system (for example, sendmail.cf, passwd, inittab, etc.).
For options that display lists of files, add -v to the command to display the lists in a familiar ls -l format.

3.2.7. Verifying

Verifying a package compares information about files installed from a package with the same information from the original package. Among other things, verifying compares the file size, MD5 sum, permissions, type, owner, and group of each file.
The command rpm -V verifies a package. You can use any of the Verify Options listed for querying to specify the packages you wish to verify. A simple use of verifying is rpm -V tree, which verifies that all the files in the tree package are as they were when they were originally installed. For example:
  • To verify a package containing a particular file:
    rpm -Vf /usr/bin/tree
    
    
    In this example, /usr/bin/tree is the absolute path to the file used to query a package.
  • To verify ALL installed packages throughout the system (which will take some time):
    rpm -Va
    
    
  • To verify an installed package against an RPM package file:
    rpm -Vp tree-1.5.2.2-4.fc12.x86_64.rpm
    
    
    This command can be useful if you suspect that your RPM database is corrupt.
If everything verified properly, there is no output. If there are any discrepancies, they are displayed. The format of the output is a string of eight characters (a "c" denotes a configuration file) and then the file name. Each of the eight characters denotes the result of a comparison of one attribute of the file to the value of that attribute recorded in the RPM database. A single period (.) means the test passed. The following characters denote specific discrepancies:
  • 5 — MD5 checksum
  • S — file size
  • L — symbolic link
  • T — file modification time
  • D — device
  • U — user
  • G — group
  • M — mode (includes permissions and file type)
  • ? — unreadable file (file permission errors, for example)
If you see any output, use your best judgment to determine if you should remove the package, reinstall it, or fix the problem in another way.

3.3. Checking a Package's Signature

If you wish to verify that a package has not been corrupted or tampered with, you can examine just the md5sum by entering this command at the shell prompt: (where <rpm_file> is the file name of the RPM package):
rpm -K --nosignature <rpm_file> 

The output <rpm_file>: rsa sha1 (md5) pgp md5 OK (specifically the OK part of it) indicates that the file was not corrupted during download. To see a more verbose message, replace -K with -Kvv in the command.
On the other hand, how trustworthy is the developer who created the package? If the package is signed with the developer's GnuPG key, you know that the developer really is who they say they are.
An RPM package can be signed using Gnu Privacy Guard (or GnuPG), to help you make certain your downloaded package is trustworthy.
GnuPG is a tool for secure communication; it is a complete and free replacement for the encryption technology of PGP, an electronic privacy program. With GnuPG, you can authenticate the validity of documents and encrypt/decrypt data to and from other recipients. GnuPG is capable of decrypting and verifying PGP 5.x files as well.
During installation, GnuPG is installed by defaut, which enables you to immediately start using it to verify any packages that you download from the Fedora Project. Before doing so, you first need to import the correct Fedora key.

3.3.1. Importing Keys

Fedora GnuPG keys are located in the /etc/pki/rpm-gpg/ directory. To verify a Fedora Project package, first import the correct key based on your processor architecture:
rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-x86_64

To display a list of all keys installed for RPM verification, execute the command:
rpm -qa gpg-pubkey*

For the Fedora Project key, the output states:
gpg-pubkey-57bbccba-4a6f97af
To display details about a specific key, use rpm -qi followed by the output from the previous command:
rpm -qi gpg-pubkey-57bbccba-4a6f97af

3.3.2. Verifying Signature of Packages

To check the GnuPG signature of an RPM file after importing the builder's GnuPG key, use the following command (replace <rpm_file> with the filename of the RPM package):
rpm -K <rpm_file> 

If all goes well, the following message is displayed: rsa sha1 (md5) pgp md5 OK. This means that the signature of the package has been verified, that it is not corrupt, and is therefore safe to install and use.
For more information, including a list of currently-used Fedora Project keys and their fingerprints, refer to http://fedoraproject.org/en/keys.

3.4. Practical and Common Examples of RPM Usage

RPM is a useful tool for both managing your system and diagnosing and fixing problems. The best way to make sense of all its options is to look at some examples.
  • Perhaps you have deleted some files by accident, but you are not sure what you deleted. To verify your entire system and see what might be missing, you could try the following command:
    rpm -Va
    
    
    If some files are missing or appear to have been corrupted, you should probably either re-install the package or uninstall and then re-install the package.
  • At some point, you might see a file that you do not recognize. To find out which package owns it, enter:
    rpm -qf /usr/bin/ghostscript
    
    
    The output would look like the following:
    ghostscript-8.70-1.fc12.x86_64
    
  • We can combine the above two examples in the following scenario. Say you are having problems with /usr/bin/paste. You would like to verify the package that owns that program, but you do not know which package owns paste. Enter the following command,
    rpm -Vf /usr/bin/paste
    
    
    and the appropriate package is verified.
  • Do you want to find out more information about a particular program? You can try the following command to locate the documentation which came with the package that owns that program:
    rpm -qdf /usr/bin/free
    
    
    The output would be similar to the following:
    /usr/share/doc/procps-3.2.8/BUGS
    /usr/share/doc/procps-3.2.8/FAQ
    /usr/share/doc/procps-3.2.8/NEWS
    /usr/share/doc/procps-3.2.8/TODO
    /usr/share/man/man1/free.1.gz
    /usr/share/man/man1/pgrep.1.gz
    /usr/share/man/man1/pkill.1.gz
    /usr/share/man/man1/pmap.1.gz
    /usr/share/man/man1/ps.1.gz
    /usr/share/man/man1/pwdx.1.gz
    /usr/share/man/man1/skill.1.gz
    /usr/share/man/man1/slabtop.1.gz
    /usr/share/man/man1/snice.1.gz
    /usr/share/man/man1/tload.1.gz
    /usr/share/man/man1/top.1.gz
    /usr/share/man/man1/uptime.1.gz
    /usr/share/man/man1/w.1.gz
    /usr/share/man/man1/watch.1.gz
    /usr/share/man/man5/sysctl.conf.5.gz
    /usr/share/man/man8/sysctl.8.gz
    /usr/share/man/man8/vmstat.8.gz
    
  • You may find a new RPM, but you do not know what it does. To find information about it, use the following command:
    rpm -qip crontabs-1.10-31.fc12.noarch.rpm
    
    
    The output would be similar to the following:
    Name        : crontabs                     Relocations: (not relocatable)
    Version     : 1.10                              Vendor: Fedora Project
    Release     : 31.fc12                       Build Date: Sat 25 Jul 2009 06:37:57 AM CEST
    Install Date: (not installed)               Build Host: x86-6.fedora.phx.redhat.com
    Group       : System Environment/Base       Source RPM: crontabs-1.10-31.fc12.src.rpm
    Size        : 2486                             License: Public Domain and GPLv2
    Signature   : RSA/SHA1, Tue 11 Aug 2009 01:11:19 PM CEST, Key ID 9d1cc34857bbccba
    Packager    : Fedora Project
    Summary     : Root crontab files used to schedule the execution of programs
    Description :
    The crontabs package contains root crontab files and directories.
    You will need to install cron daemon to run the jobs from the crontabs.
    The cron daemon such as cronie or fcron checks the crontab files to
    see when particular commands are scheduled to be executed.  If commands
    are scheduled, it executes them.
    
    Crontabs handles a basic system function, so it should be installed on
    your system.
    
  • Perhaps you now want to see what files the crontabs RPM package installs. You would enter the following:
    rpm -qlp crontabs-1.10-31.fc12.noarch.rpm
    
    
    The output is similar to the following:
    /etc/cron.daily
    /etc/cron.hourly
    /etc/cron.monthly
    /etc/cron.weekly
    /etc/crontab
    /usr/bin/run-parts
    /usr/share/man/man4/crontabs.4.gz
    
These are just a few examples. As you use RPM, you may find more uses for it.

3.5. Additional Resources

RPM is an extremely complex utility with many options and methods for querying, installing, upgrading, and removing packages. Refer to the following resources to learn more about RPM.

3.5.1. Installed Documentation

  • rpm --help — This command displays a quick reference of RPM parameters.
  • man rpm — The RPM man page gives more detail about RPM parameters than the rpm --help command.

3.5.2. Useful Websites

Part II. Network-Related Configuration

After explaining how to configure the network, this part discusses topics related to networking such as how to allow remote logins, share files and directories over the network, and set up a Web server.

Table of Contents

4. Network Interfaces
4.1. Network Configuration Files
4.2. Interface Configuration Files
4.2.1. Ethernet Interfaces
4.2.2. IPsec Interfaces
4.2.3. Channel Bonding Interfaces
4.2.4. Alias and Clone Files
4.2.5. Dialup Interfaces
4.2.6. Other Interfaces
4.3. Interface Control Scripts
4.4. Configuring Static Routes
4.5. Network Function Files
4.6. Additional Resources
4.6.1. Installed Documentation
5. Network Configuration
5.1. Overview
5.2. Establishing an Ethernet Connection
5.3. Establishing an ISDN Connection
5.4. Establishing a Modem Connection
5.5. Establishing an xDSL Connection
5.6. Establishing a Token Ring Connection
5.7. Establishing a Wireless Connection
5.8. Managing DNS Settings
5.9. Managing Hosts
5.10. Working with Profiles
5.11. Device Aliases
5.12. Saving and Restoring the Network Configuration
6. Controlling Access to Services
6.1. Runlevels
6.2. TCP Wrappers
6.2.1. xinetd
6.3. Services Configuration Tool
6.4. ntsysv
6.5. chkconfig
6.6. Additional Resources
6.6.1. Installed Documentation
6.6.2. Useful Websites
7. Berkeley Internet Name Domain (BIND)
7.1. Introduction to DNS
7.1.1. Nameserver Zones
7.1.2. Nameserver Types
7.1.3. BIND as a Nameserver
7.2. /etc/named.conf
7.2.1. Common Statement Types
7.2.2. Other Statement Types
7.2.3. Comment Tags
7.3. Zone Files
7.3.1. Zone File Directives
7.3.2. Zone File Resource Records
7.3.3. Example Zone File
7.3.4. Reverse Name Resolution Zone Files
7.4. Using rndc
7.4.1. Configuring /etc/named.conf
7.4.2. Configuring /etc/rndc.conf
7.4.3. Command Line Options
7.5. Advanced Features of BIND
7.5.1. DNS Protocol Enhancements
7.5.2. Multiple Views
7.5.3. Security
7.5.4. IP version 6
7.6. Common Mistakes to Avoid
7.7. Additional Resources
7.7.1. Installed Documentation
7.7.2. Useful Websites
7.7.3. Related Books
8. OpenSSH
8.1. Features of SSH
8.1.1. Why Use SSH?
8.2. SSH Protocol Versions
8.3. Event Sequence of an SSH Connection
8.3.1. Transport Layer
8.3.2. Authentication
8.3.3. Channels
8.4. Configuring an OpenSSH Server
8.4.1. Requiring SSH for Remote Connections
8.5. OpenSSH Configuration Files
8.6. Configuring an OpenSSH Client
8.6.1. Using the ssh Command
8.6.2. Using the scp Command
8.6.3. Using the sftp Command
8.7. More Than a Secure Shell
8.7.1. X11 Forwarding
8.7.2. Port Forwarding
8.7.3. Generating Key Pairs
8.8. Additional Resources
8.8.1. Installed Documentation
8.8.2. Useful Websites
9. Samba
9.1. Introduction to Samba
9.1.1. Samba Features
9.2. Samba Daemons and Related Services
9.2.1. Samba Daemons
9.3. Connecting to a Samba Share
9.3.1. Command Line
9.3.2. Mounting the Share
9.4. Configuring a Samba Server
9.4.1. Graphical Configuration
9.4.2. Command Line Configuration
9.4.3. Encrypted Passwords
9.5. Starting and Stopping Samba
9.6. Samba Server Types and the smb.conf File
9.6.1. Stand-alone Server
9.6.2. Domain Member Server
9.6.3. Domain Controller
9.7. Samba Security Modes
9.7.1. User-Level Security
9.7.2. Share-Level Security
9.8. Samba Account Information Databases
9.9. Samba Network Browsing
9.9.1. Domain Browsing
9.9.2. WINS (Windows Internetworking Name Server)
9.10. Samba with CUPS Printing Support
9.10.1. Simple smb.conf Settings
9.11. Samba Distribution Programs
9.12. Additional Resources
9.12.1. Installed Documentation
9.12.2. Related Books
9.12.3. Useful Websites
10. Dynamic Host Configuration Protocol (DHCP)
10.1. Why Use DHCP?
10.2. Configuring a DHCP Server
10.2.1. Configuration File
10.2.2. Lease Database
10.2.3. Starting and Stopping the Server
10.2.4. DHCP Relay Agent
10.3. Configuring a DHCP Client
10.4. Configuring a Multihomed DHCP Server
10.4.1. Host Configuration
10.5. Additional Resources
10.5.1. Installed Documentation
11. Apache HTTP Server
11.1. Apache HTTP Server 2.2
11.1.1. Features of Apache HTTP Server 2.2
11.2. Migrating Apache HTTP Server Configuration Files
11.2.1. Migrating Apache HTTP Server 2.0 Configuration Files
11.2.2. Migrating Apache HTTP Server 1.3 Configuration Files to 2.0
11.3. Starting and Stopping httpd
11.4. Apache HTTP Server Configuration
11.4.1. Basic Settings
11.4.2. Default Settings
11.5. Configuration Directives in httpd.conf
11.5.1. General Configuration Tips
11.5.2. Configuration Directives for SSL
11.5.3. MPM Specific Server-Pool Directives
11.6. Adding Modules
11.7. Virtual Hosts
11.7.1. Setting Up Virtual Hosts
11.8. Apache HTTP Secure Server Configuration
11.8.1. An Overview of Security-Related Packages
11.8.2. An Overview of Certificates and Security
11.8.3. Using Pre-Existing Keys and Certificates
11.8.4. Types of Certificates
11.8.5. Generating a Key
11.8.6. How to configure the server to use the new key
11.9. Additional Resources
11.9.1. Useful Websites
12. FTP
12.1. The File Transfer Protocol
12.1.1. Multiple Ports, Multiple Modes
12.2. FTP Servers
12.2.1. vsftpd
12.3. Files Installed with vsftpd
12.4. Starting and Stopping vsftpd
12.4.1. Starting Multiple Copies of vsftpd
12.5. vsftpd Configuration Options
12.5.1. Daemon Options
12.5.2. Log In Options and Access Controls
12.5.3. Anonymous User Options
12.5.4. Local User Options
12.5.5. Directory Options
12.5.6. File Transfer Options
12.5.7. Logging Options
12.5.8. Network Options
12.6. Additional Resources
12.6.1. Installed Documentation
12.6.2. Useful Websites
13. Email
13.1. Email Protocols
13.1.1. Mail Transport Protocols
13.1.2. Mail Access Protocols
13.2. Email Program Classifications
13.2.1. Mail Transport Agent
13.2.2. Mail Delivery Agent
13.2.3. Mail User Agent
13.3. Mail Transport Agents
13.3.1. Sendmail
13.3.2. Postfix
13.3.3. Fetchmail
13.4. Mail Transport Agent (MTA) Configuration
13.5. Mail Delivery Agents
13.5.1. Procmail Configuration
13.5.2. Procmail Recipes
13.6. Mail User Agents
13.6.1. Securing Communication
13.7. Additional Resources
13.7.1. Installed Documentation
13.7.2. Useful Websites
13.7.3. Related Books
14. Lightweight Directory Access Protocol (LDAP)
14.1. Why Use LDAP?
14.1.1. OpenLDAP Features
14.2. LDAP Terminology
14.3. OpenLDAP Daemons and Utilities
14.3.1. NSS, PAM, and LDAP
14.3.2. PHP4, LDAP, and the Apache HTTP Server
14.3.3. LDAP Client Applications
14.4. OpenLDAP Configuration Files
14.5. The /etc/openldap/schema/ Directory
14.6. OpenLDAP Setup Overview
14.6.1. Editing /etc/openldap/slapd.conf
14.7. Configuring a System to Authenticate Using OpenLDAP
14.7.1. PAM and LDAP
14.7.2. Migrating Old Authentication Information to LDAP Format
14.8. Migrating Directories from Earlier Releases
14.9. Additional Resources
14.9.1. Installed Documentation
14.9.2. Useful Websites
14.9.3. Related Books
15. Authentication Configuration
15.1. User Information
15.2. Authentication
15.3. Options
15.4. Command Line Version

Chapter 4. Network Interfaces

Under Fedora, all network communications occur between configured software interfaces and physical networking devices connected to the system.
The configuration files for network interfaces are located in the /etc/sysconfig/network-scripts/ directory. The scripts used to activate and deactivate these network interfaces are also located here. Although the number and type of interface files can differ from system to system, there are three categories of files that exist in this directory:
  1. Interface configuration files
  2. Interface control scripts
  3. Network function files
The files in each of these categories work together to enable various network devices.
This chapter explores the relationship between these files and how they are used.

4.1. Network Configuration Files

Before delving into the interface configuration files, let us first itemize the primary configuration files used in network configuration. Understanding the role these files play in setting up the network stack can be helpful when customizing a Fedora system.
The primary network configuration files are as follows:
/etc/hosts
The main purpose of this file is to resolve hostnames that cannot be resolved any other way. It can also be used to resolve hostnames on small networks with no DNS server. Regardless of the type of network the computer is on, this file should contain a line specifying the IP address of the loopback device (127.0.0.1) as localhost.localdomain. For more information, refer to the hosts man page.
/etc/resolv.conf
This file specifies the IP addresses of DNS servers and the search domain. Unless configured to do otherwise, the network initialization scripts populate this file. For more information about this file, refer to the resolv.conf man page.
/etc/sysconfig/network
This file specifies routing and host information for all network interfaces. For more information about this file and the directives it accepts, refer to Section 17.1.21, “ /etc/sysconfig/network.
/etc/sysconfig/network-scripts/ifcfg-<interface-name>
For each network interface, there is a corresponding interface configuration script. Each of these files provide information specific to a particular network interface. Refer to Section 4.2, “Interface Configuration Files” for more information on this type of file and the directives it accepts.

Warning

The /etc/sysconfig/networking/ directory is used by the Network Administration Tool (system-config-network) and its contents should not be edited manually. Using only one method for network configuration is strongly encouraged, due to the risk of configuration deletion.
For more information about configuring network interfaces using the Network Administration Tool, refer to Chapter 5, Network Configuration

4.2. Interface Configuration Files

Interface configuration files control the software interfaces for individual network devices. As the system boots, it uses these files to determine what interfaces to bring up and how to configure them. These files are usually named ifcfg-<name> , where <name> refers to the name of the device that the configuration file controls.

4.2.1. Ethernet Interfaces

One of the most common interface files is ifcfg-eth0, which controls the first Ethernet network interface card or NIC in the system. In a system with multiple NICs, there are multiple ifcfg-eth<X> files (where <X> is a unique number corresponding to a specific interface). Because each device has its own configuration file, an administrator can control how each interface functions individually.
The following is a sample ifcfg-eth0 file for a system using a fixed IP address:
DEVICE=eth0 BOOTPROTO=none ONBOOT=yes NETWORK=10.0.1.0 NETMASK=255.255.255.0 IPADDR=10.0.1.27 USERCTL=no
The values required in an interface configuration file can change based on other values. For example, the ifcfg-eth0 file for an interface using DHCP looks different because IP information is provided by the DHCP server:
DEVICE=eth0 BOOTPROTO=dhcp ONBOOT=yes
The Network Administration Tool (system-config-network) is an easy way to make changes to the various network interface configuration files (refer to Chapter 5, Network Configuration for detailed instructions on using this tool).
However, it is also possible to manually edit the configuration files for a given network interface.
Below is a listing of the configurable parameters in an Ethernet interface configuration file:
BONDING_OPTS=<parameters>
sets the configuration parameters for the bonding device, and is used in /etc/sysconfig/network-scripts/ifcfg-bond<N> (see Section 4.2.3, “Channel Bonding Interfaces”). These parameters are identical to those used for bonding devices in /sys/class/net/<bonding device>/bonding, and the module parameters for the bonding driver as described in bonding Module Directives.
This configuration method is used so that multiple bonding devices can have different configurations. If you use BONDING_OPTS in ifcfg-<name> , do not use /etc/modprobe.conf to specify options for the bonding device.
BOOTPROTO=<protocol>
where <protocol> is one of the following:
  • none — No boot-time protocol should be used.
  • bootp — The BOOTP protocol should be used.
  • dhcp — The DHCP protocol should be used.
BROADCAST=<address>
where <address> is the broadcast address. This directive is deprecated, as the value is calculated automatically with ifcalc.
DEVICE=<name>
where <name> is the name of the physical device (except for dynamically-allocated PPP devices where it is the logical name).
DHCP_HOSTNAME
Use this option only if the DHCP server requires the client to specify a hostname before receiving an IP address.
DNS{1,2}=<address>
where <address> is a name server address to be placed in /etc/resolv.conf if the PEERDNS directive is set to yes.
ETHTOOL_OPTS=<options>
where <options> are any device-specific options supported by ethtool. For example, if you wanted to force 100Mb, full duplex:
ETHTOOL_OPTS="autoneg off speed 100 duplex full"

Instead of a custom initscript, use ETHTOOL_OPTS to set the interface speed and duplex settings. Custom initscripts run outside of the network init script lead to unpredictable results during a post-boot network service restart.

Note

Changing speed or duplex settings almost always requires disabling autonegotiation with the autoneg off option. This needs to be stated first, as the option entries are order-dependent.
GATEWAY=<address>
where <address> is the IP address of the network router or gateway device (if any).
HWADDR=<MAC-address>
where <MAC-address> is the hardware address of the Ethernet device in the form AA:BB:CC:DD:EE:FF. This directive must be used in machines containing more than one NIC to ensure that the interfaces are assigned the correct device names regardless of the configured load order for each NIC's module. This directive should not be used in conjunction with MACADDR.
IPADDR=<address>
where <address> is the IP address.
MACADDR=<MAC-address>
where <MAC-address> is the hardware address of the Ethernet device in the form AA:BB:CC:DD:EE:FF. This directive is used to assign a MAC address to an interface, overriding the one assigned to the physical NIC. This directive should not be used in conjunction with HWADDR.
MASTER=<bond-interface>
where <bond-interface> is the channel bonding interface to which the Ethernet interface is linked.
This directive is used in conjunction with the SLAVE directive.
Refer to Section 4.2.3, “Channel Bonding Interfaces” for more information about channel bonding interfaces.
NETMASK=<mask>
where <mask> is the netmask value.
NETWORK=<address>
where <address> is the network address. This directive is deprecated, as the value is calculated automatically with ifcalc.
ONBOOT=<answer>
where <answer> is one of the following:
  • yes — This device should be activated at boot-time.
  • no — This device should not be activated at boot-time.
PEERDNS=<answer>
where <answer> is one of the following:
  • yes — Modify /etc/resolv.conf if the DNS directive is set. If using DHCP, then yes is the default.
  • no — Do not modify /etc/resolv.conf.
SLAVE=<bond-interface>
where <bond-interface> is one of the following:
  • yes — This device is controlled by the channel bonding interface specified in the MASTER directive.
  • no — This device is not controlled by the channel bonding interface specified in the MASTER directive.
This directive is used in conjunction with the MASTER directive.
Refer to Section 4.2.3, “Channel Bonding Interfaces” for more about channel bonding interfaces.
SRCADDR=<address>
where <address> is the specified source IP address for outgoing packets.
USERCTL=<answer>
where <answer> is one of the following:
  • yes — Non-root users are allowed to control this device.
  • no — Non-root users are not allowed to control this device.

4.2.2. IPsec Interfaces

The following example shows the ifcfg file for a network-to-network IPsec connection for LAN A. The unique name to identify the connection in this example is ipsec1, so the resulting file is named /etc/sysconfig/network-scripts/ifcfg-ipsec1.
TYPE=IPsec
ONBOOT=yes
IKE_METHOD=PSK
SRCNET=192.168.1.0/24
DSTNET=192.168.2.0/24
DST=X.X.X.X

In the example above, X.X.X.X is the publicly routable IP address of the destination IPsec router.
Below is a listing of the configurable parameters for an IPsec interface:
DST=<address>
where <address> is the IP address of the IPsec destination host or router. This is used for both host-to-host and network-to-network IPsec configurations.
DSTNET=<network>
where <network> is the network address of the IPsec destination network. This is only used for network-to-network IPsec configurations.
SRC=<address>
where <address> is the IP address of the IPsec source host or router. This setting is optional and is only used for host-to-host IPsec configurations.
SRCNET=<network>
where <network> is the network address of the IPsec source network. This is only used for network-to-network IPsec configurations.
TYPE=<interface-type>
where <interface-type> is IPSEC. Both applications are part of the ipsec-tools package.
If manual key encryption with IPsec is being used, refer to /usr/share/doc/initscripts-<version-number>/sysconfig.txt (replace <version-number> with the version of the initscripts package installed) for configuration parameters.
The racoon IKEv1 key management daemon negotiates and configures a set of parameters for IPSec. It can use preshared keys, RSA signatures, or GSS-API. If racoon is used to automatically manage key encryption, the following options are required:
IKE_METHOD=<encryption-method>
where <encryption-method> is either PSK, X509, or GSSAPI. If PSK is specified, the IKE_PSK parameter must also be set. If X509 is specified, the IKE_CERTFILE parameter must also be set.
IKE_PSK=<shared-key>
where <shared-key> is the shared, secret value for the PSK (preshared keys) method.
IKE_CERTFILE=<cert-file>
where <cert-file> is a valid X.509 certificate file for the host.
IKE_PEER_CERTFILE=<cert-file>
where <cert-file> is a valid X.509 certificate file for the remote host.
IKE_DNSSEC=<answer>
where <answer> is yes. The racoon daemon retrieves the remote host's X.509 certificate via DNS. If a IKE_PEER_CERTFILE is specified, do not include this parameter.
For more information about the encryption algorithms available for IPsec, refer to the setkey man page. For more information about racoon, refer to the racoon and racoon.conf man pages.

4.2.3. Channel Bonding Interfaces

Fedora allows administrators to bind multiple network interfaces together into a single channel using the bonding kernel module and a special network interface called a channel bonding interface. Channel bonding enables two or more network interfaces to act as one, simultaneously increasing the bandwidth and providing redundancy.
To create a channel bonding interface, create a file in the /etc/sysconfig/network-scripts/ directory called ifcfg-bond<N> , replacing <N> with the number for the interface, such as 0.
The contents of the file can be identical to whatever type of interface is getting bonded, such as an Ethernet interface. The only difference is that the DEVICE= directive must be bond<N> , replacing <N> with the number for the interface.
The following is a sample channel bonding configuration file:
DEVICE=bond0
BONDING_OPTS="mode=1 miimon=500"
BOOTPROTO=none
ONBOOT=yes
NETWORK=10.0.1.0
NETMASK=255.255.255.0
IPADDR=10.0.1.27
USERCTL=no

After the channel bonding interface is created, the network interfaces to be bound together must be configured by adding the MASTER= and SLAVE= directives to their configuration files. The configuration files for each of the channel-bonded interfaces can be nearly identical.
For example, if two Ethernet interfaces are being channel bonded, both eth0 and eth1 may look like the following example:
DEVICE=eth<N>
BOOTPROTO=none
ONBOOT=yes
MASTER=bond0
SLAVE=yes
USERCTL=no

In this example, replace <N> with the numerical value for the interface.

Important

Important aspects of the channel bonding interface are controlled through the kernel module. For more information about controlling the bonding modules, refer to Section 30.5.2, “The Channel Bonding Module”.

4.2.4. Alias and Clone Files

Two lesser-used types of interface configuration files are alias and clone files.
Alias interface configuration files, which are used to bind multiple addresses to a single interface, use the ifcfg-<if-name>:<alias-value> naming scheme.
For example, an ifcfg-eth0:0 file could be configured to specify DEVICE=eth0:0 and a static IP address of 10.0.0.2, serving as an alias of an Ethernet interface already configured to receive its IP information via DHCP in ifcfg-eth0. Under this configuration, eth0 is bound to a dynamic IP address, but the same physical network card can receive requests via the fixed, 10.0.0.2 IP address.

Caution

Alias interfaces do not support DHCP.
A clone interface configuration file should use the following naming convention: ifcfg-<if-name>-<clone-name> . While an alias file allows multiple addresses for an existing interface, a clone file is used to specify additional options for an interface. For example, a standard DHCP Ethernet interface called eth0, may look similar to this:
DEVICE=eth0 ONBOOT=yes BOOTPROTO=dhcp
Since the default value for the USERCTL directive is no if it is not specified, users cannot bring this interface up and down. To give users the ability to control the interface, create a clone by copying ifcfg-eth0 to ifcfg-eth0-user and add the following line to ifcfg-eth0-user:
USERCTL=yes
This way a user can bring up the eth0 interface using the /sbin/ifup eth0-user command because the configuration options from ifcfg-eth0 and ifcfg-eth0-user are combined. While this is a very basic example, this method can be used with a variety of options and interfaces.
The easiest way to create alias and clone interface configuration files is to use the graphical Network Administration Tool. For more information on using this tool, refer to Chapter 5, Network Configuration.

4.2.5. Dialup Interfaces

If you are connecting to the Internet via a dialup connection, a configuration file is necessary for the interface.
PPP interface files are named using the following format:
ifcfg-ppp<X>
where <X> is a unique number corresponding to a specific interface.
The PPP interface configuration file is created automatically when wvdial, the Network Administration Tool or Kppp is used to create a dialup account. It is also possible to create and edit this file manually.
The following is a typical ifcfg-ppp0 file:
DEVICE=ppp0
NAME=test
WVDIALSECT=test
MODEMPORT=/dev/modem
LINESPEED=115200
PAPNAME=test
USERCTL=true
ONBOOT=no
PERSIST=no
DEFROUTE=yes
PEERDNS=yes
DEMAND=no
IDLETIMEOUT=600
Serial Line Internet Protocol (SLIP) is another dialup interface, although it is used less frequently. SLIP files have interface configuration file names such as ifcfg-sl0.
Other options that may be used in these files include:
DEFROUTE=<answer>
where <answer> is one of the following:
  • yes — Set this interface as the default route.
  • no — Do not set this interface as the default route.
DEMAND=<answer>
where <answer> is one of the following:
  • yes — This interface allows pppd to initiate a connection when someone attempts to use it.
  • no — A connection must be manually established for this interface.
IDLETIMEOUT=<value>
where <value> is the number of seconds of idle activity before the interface disconnects itself.
INITSTRING=<string>
where <string> is the initialization string passed to the modem device. This option is primarily used in conjunction with SLIP interfaces.
LINESPEED=<value>
where <value> is the baud rate of the device. Possible standard values include 57600, 38400, 19200, and 9600.
MODEMPORT=<device>
where <device> is the name of the serial device that is used to establish the connection for the interface.
MTU=<value>
where <value> is the Maximum Transfer Unit (MTU) setting for the interface. The MTU refers to the largest number of bytes of data a frame can carry, not counting its header information. In some dialup situations, setting this to a value of 576 results in fewer packets dropped and a slight improvement to the throughput for a connection.
NAME=<name>
where <name> is the reference to the title given to a collection of dialup connection configurations.
PAPNAME=<name>
where <name> is the username given during the Password Authentication Protocol (PAP) exchange that occurs to allow connections to a remote system.
PERSIST=<answer>
where <answer> is one of the following:
  • yes — This interface should be kept active at all times, even if deactivated after a modem hang up.
  • no — This interface should not be kept active at all times.
REMIP=<address>
where <address> is the IP address of the remote system. This is usually left unspecified.
WVDIALSECT=<name>
where <name> associates this interface with a dialer configuration in /etc/wvdial.conf. This file contains the phone number to be dialed and other important information for the interface.

4.2.6. Other Interfaces

Other common interface configuration files include the following:
ifcfg-lo
A local loopback interface is often used in testing, as well as being used in a variety of applications that require an IP address pointing back to the same system. Any data sent to the loopback device is immediately returned to the host's network layer.

Warning

The loopback interface script, /etc/sysconfig/network-scripts/ifcfg-lo, should never be edited manually. Doing so can prevent the system from operating correctly.
ifcfg-irlan0
An infrared interface allows information between devices, such as a laptop and a printer, to flow over an infrared link. This works in a similar way to an Ethernet device except that it commonly occurs over a peer-to-peer connection.
ifcfg-plip0
A Parallel Line Interface Protocol (PLIP) connection works much the same way as an Ethernet device, except that it utilizes a parallel port.
ifcfg-tr0
Token Ring topologies are not as common on Local Area Networks (LANs) as they once were, having been eclipsed by Ethernet.

4.3. Interface Control Scripts

The interface control scripts activate and deactivated system interfaces. There are two primary interface control scripts that call on control scripts located in the /etc/sysconfig/network-scripts/ directory: /sbin/ifdown and /sbin/ifup.
The ifup and ifdown interface scripts are symbolic links to scripts in the /sbin/ directory. When either of these scripts are called, they require the value of the interface to be specified, such as:
ifup eth0

Caution

The ifup and ifdown interface scripts are the only scripts that the user should use to bring up and take down network interfaces.
The following scripts are described for reference purposes only.
Two files used to perform a variety of network initialization tasks during the process of bringing up a network interface are /etc/rc.d/init.d/functions and /etc/sysconfig/network-scripts/network-functions. Refer to Section 4.5, “Network Function Files” for more information.
After verifying that an interface has been specified and that the user executing the request is allowed to control the interface, the correct script brings the interface up or down. The following are common interface control scripts found within the /etc/sysconfig/network-scripts/ directory:
ifup-aliases
Configures IP aliases from interface configuration files when more than one IP address is associated with an interface.
ifup-ippp and ifdown-ippp
Brings ISDN interfaces up and down.
ifup-ipsec and ifdown-ipsec
Brings IPsec interfaces up and down.
ifup-ipv6 and ifdown-ipv6
Brings IPv6 interfaces up and down.
ifup-ipx
Brings up an IPX interface.
ifup-plip
Brings up a PLIP interface.
ifup-plusb
Brings up a USB interface for network connections.
ifup-post and ifdown-post
Contains commands to be executed after an interface is brought up or down.
ifup-ppp and ifdown-ppp
Brings a PPP interface up or down.
ifup-routes
Adds static routes for a device as its interface is brought up.
ifdown-sit and ifup-sit
Contains function calls related to bringing up and down an IPv6 tunnel within an IPv4 connection.
ifup-sl and ifdown-sl
Brings a SLIP interface up or down.
ifup-wireless
Brings up a wireless interface.

Warning

Removing or modifying any scripts in the /etc/sysconfig/network-scripts/ directory can cause interface connections to act irregularly or fail. Only advanced users should modify scripts related to a network interface.
The easiest way to manipulate all network scripts simultaneously is to use the /sbin/service command on the network service (/etc/rc.d/init.d/network), as illustrated the following command:
/sbin/service network <action> 

Here, <action> can be either start, stop, or restart.
To view a list of configured devices and currently active network interfaces, use the following command:
/sbin/service network status

4.4. Configuring Static Routes

Routing will be configured on routing devices, therefore it should not be necessary to configure static routes on Fedora servers or clients. However, if static routes are required they can be configured for each interface. This can be useful if you have multiple interfaces in different subnets. Use the route command to display the IP routing table.
Static route configuration is stored in a /etc/sysconfig/network-scripts/route-interface file. For example, static routes for the eth0 interface would be stored in the /etc/sysconfig/network-scripts/route-eth0 file. The route-interface file has two formats: IP command arguments and network/netmask directives.
IP Command Arguments Format
Define a default gateway on the first line. This is only required if the default gateway is not set via DHCP:
default X.X.X.X dev interface

X.X.X.X is the IP address of the default gateway. The interface is the interface that is connected to, or can reach, the default gateway.
Define a static route. Each line is parsed as an individual route:
X.X.X.X/X via X.X.X.X dev interface

X.X.X.X/X is the network number and netmask for the static route. X.X.X.X and interface are the IP address and interface for the default gateway respectively. The X.X.X.X address does not have to be the default gateway IP address. In most cases, X.X.X.X will be an IP address in a different subnet, and interface will be the interface that is connected to, or can reach, that subnet. Add as many static routes as required.
The following is a sample route-eth0 file using the IP command arguments format. The default gateway is 192.168.0.1, interface eth0. The two static routes are for the 10.10.10.0/24 and 172.16.1.0/24 networks:
default 192.168.0.1 dev eth0
10.10.10.0/24 via 192.168.0.1 dev eth0
172.16.1.0/24 via 192.168.0.1 dev eth0

Static routes should only be configured for other subnets. The above example is not necessary, since packets going to the 10.10.10.0/24 and 172.16.1.0/24 networks will use the default gateway anyway. Below is an example of setting static routes to a different subnet, on a machine in a 192.168.0.0/24 subnet. The example machine has an eth0 interface in the 192.168.0.0/24 subnet, and an eth1 interface (10.10.10.1) in the 10.10.10.0/24 subnet:
10.10.10.0/24 via 10.10.10.1 dev eth1

Duplicate Default Gateways

If the default gateway is already assigned from DHCP, the IP command arguments format can cause one of two errors during start-up, or when bringing up an interface from the down state using the ifup command: "RTNETLINK answers: File exists" or 'Error: either "to" is a duplicate, or "X.X.X.X" is a garbage.', where X.X.X.X is the gateway, or a different IP address. These errors can also occur if you have another route to another network using the default gateway. Both of these errors are safe to ignore.
Network/Netmask Directives Format
You can also use the network/netmask directives format for route-interface files. The following is a template for the network/netmask format, with instructions following afterwards:
ADDRESS0=X.X.X.X
NETMASK0=X.X.X.X
GATEWAY0=X.X.X.X

  • ADDRESS0=X.X.X.X is the network number for the static route.
  • NETMASK0=X.X.X.X is the netmask for the network number defined with ADDRESS0=X.X.X.X .
  • GATEWAY0=X.X.X.X is the default gateway, or an IP address that can be used to reach ADDRESS0=X.X.X.X
The following is a sample route-eth0 file using the network/netmask directives format. The default gateway is 192.168.0.1, interface eth0. The two static routes are for the 10.10.10.0/24 and 172.16.1.0/24 networks. However, as mentioned before, this example is not necessary as the 10.10.10.0/24 and 172.16.1.0/24 networks would use the default gateway anyway:
ADDRESS0=10.10.10.0
NETMASK0=255.255.255.0
GATEWAY0=192.168.0.1
ADDRESS1=172.16.1.0
NETMASK1=255.255.255.0
GATEWAY1=192.168.0.1

Subsequent static routes must be numbered sequentially, and must not skip any values. For example, ADDRESS0, ADDRESS1, ADDRESS2, and so on.
Below is an example of setting static routes to a different subnet, on a machine in the 192.168.0.0/24 subnet. The example machine has an eth0 interface in the 192.168.0.0/24 subnet, and an eth1 interface (10.10.10.1) in the 10.10.10.0/24 subnet:
ADDRESS0=10.10.10.0
NETMASK0=255.255.255.0
GATEWAY0=10.10.10.1

DHCP should assign these settings automatically, therefore it should not be necessary to configure static routes on Fedora servers or clients.

4.5. Network Function Files

Fedora makes use of several files that contain important common functions used to bring interfaces up and down. Rather than forcing each interface control file to contain these functions, they are grouped together in a few files that are called upon when necessary.
The /etc/sysconfig/network-scripts/network-functions file contains the most commonly used IPv4 functions, which are useful to many interface control scripts. These functions include contacting running programs that have requested information about changes in the status of an interface, setting hostnames, finding a gateway device, verifying whether or not a particular device is down, and adding a default route.
As the functions required for IPv6 interfaces are different from IPv4 interfaces, a /etc/sysconfig/network-scripts/network-functions-ipv6 file exists specifically to hold this information. The functions in this file configure and delete static IPv6 routes, create and remove tunnels, add and remove IPv6 addresses to an interface, and test for the existence of an IPv6 address on an interface.

4.6. Additional Resources

The following are resources which explain more about network interfaces.

4.6.1. Installed Documentation

/usr/share/doc/initscripts-<version>/sysconfig.txt
A guide to available options for network configuration files, including IPv6 options not covered in this chapter.
/usr/share/doc/iproute-<version>/ip-cref.ps
This file contains a wealth of information about the ip command, which can be used to manipulate routing tables, among other things. Use the ggv or kghostview application to view this file.

Chapter 5. Network Configuration

To communicate with each other, computers must have a network connection. This is accomplished by having the operating system recognize an interface card (such as Ethernet, ISDN modem, or token ring) and configuring the interface to connect to the network.
The Network Administration Tool can be used to configure the following types of network interfaces:
  • Ethernet
  • ISDN
  • modem
  • xDSL
  • token ring
  • CIPE
  • wireless devices
It can also be used to configure IPsec connections, manage DNS settings, and manage the /etc/hosts file used to store additional hostnames and IP address combinations.
To use the Network Administration Tool, you must have root privileges. To start the application, go to the Applications (the main menu on the panel) > System Settings > Network, or type the command system-config-network at a shell prompt (for example, in an XTerm or a GNOME terminal). If you type the command, the graphical version is displayed if X is running; otherwise, the text-based version is displayed.
To use the command line version, execute the command system-config-network-cmd --help as root to view all of the options.
Network Administration Tool
Main Window
Figure 5.1.  Network Administration Tool

Tip

Use the Red Hat Hardware Compatibility List (http://hardware.redhat.com/hcl/) to determine if Fedora supports your hardware device.

5.1. Overview

To configure a network connection with the Network Administration Tool, perform the following steps:
  1. Add a network device associated with the physical hardware device.
  2. Add the physical hardware device to the hardware list, if it does not already exist.
  3. Configure the hostname and DNS settings.
  4. Configure any hosts that cannot be looked up through DNS.
This chapter discusses each of these steps for each type of network connection.

5.2. Establishing an Ethernet Connection

To establish an Ethernet connection, you need a network interface card (NIC), a network cable (usually a CAT5 cable), and a network to connect to. Different networks are configured to use different network speeds; make sure your NIC is compatible with the network to which you want to connect.
To add an Ethernet connection, follow these steps:
  1. Click the Devices tab.
  2. Click the New button on the toolbar.
  3. Select Ethernet connection from the Device Type list, and click Forward.
  4. If you have already added the network interface card to the hardware list, select it from the Ethernet card list. Otherwise, select Other Ethernet Card to add the hardware device.

    Note

    The installation program detects supported Ethernet devices and prompts you to configure them. If you configured any Ethernet devices during the installation, they are displayed in the hardware list on the Hardware tab.
  5. If you selected Other Ethernet Card, the Select Ethernet Adapter window appears. Select the manufacturer and model of the Ethernet card. Select the device name. If this is the system's first Ethernet card, select eth0 as the device name; if this is the second Ethernet card, select eth1 (and so on). The Network Administration Tool also allows you to configure the resources for the NIC. Click Forward to continue.
  6. In the Configure Network Settings window shown in Figure 5.2, “Ethernet Settings”, choose between DHCP and a static IP address. If the device receives a different IP address each time the network is started, do not specify a hostname. Click Forward to continue.
  7. Click Apply on the Create Ethernet Device page.
Ethernet Settings
Ethernet Settings
Figure 5.2. Ethernet Settings

After configuring the Ethernet device, it appears in the device list as shown in Figure 5.3, “Ethernet Device”.
Ethernet Device
Ethernet Device
Figure 5.3. Ethernet Device

Be sure to select File > Save to save the changes.
After adding the Ethernet device, you can edit its configuration by selecting the device from the device list and clicking Edit. For example, when the device is added, it is configured to start at boot time by default. To change this setting, select to edit the device, modify the Activate device when computer starts value, and save the changes.
When the device is added, it is not activated immediately, as seen by its Inactive status. To activate the device, select it from the device list, and click the Activate button. If the system is configured to activate the device when the computer starts (the default), this step does not have to be performed again.
If you associate more than one device with an Ethernet card, the subsequent devices are device aliases. A device alias allows you to setup multiple virtual devices for one physical device, thus giving the one physical device more than one IP address. For example, you can configure an eth1 device and an eth1:1 device. For details, refer to Section 5.11, “Device Aliases”.

5.3. Establishing an ISDN Connection

An ISDN connection is an Internet connection established with a ISDN modem card through a special phone line installed by the phone company. ISDN connections are popular in Europe.
To add an ISDN connection, follow these steps:
  1. Click the Devices tab.
  2. Click the New button on the toolbar.
  3. Select ISDN connection from the Device Type list, and click Forward.
  4. Select the ISDN adapter from the pulldown menu. Then configure the resources and D channel protocol for the adapter. Click Forward to continue.
    ISDN Settings
    ISDN Settings
    Figure 5.4. ISDN Settings

  5. If your Internet Service Provider (ISP) is in the pre-configured list, select it. Otherwise, enter the required information about your ISP account. If you do not know the values, contact your ISP. Click Forward.
  6. In the IP Settings window, select the Encapsulation Mode and whether to obtain an IP address automatically or to set a static IP instead. Click Forward when finished.
  7. On the Create Dialup Connection page, click Apply.
After configuring the ISDN device, it appears in the device list as a device with type ISDN as shown in Figure 5.5, “ISDN Device”.
Be sure to select File > Save to save the changes.
After adding the ISDN device, you can edit its configuration by selecting the device from the device list and clicking Edit. For example, when the device is added, it is configured not to start at boot time by default. Edit its configuration to modify this setting. Compression, PPP options, login name, password, and more can be changed.
When the device is added, it is not activated immediately, as seen by its Inactive status. To activate the device, select it from the device list, and click the Activate button. If the system is configured to activate the device when the computer starts (the default), this step does not have to be performed again.
ISDN Device
ISDN Device
Figure 5.5. ISDN Device

5.4. Establishing a Modem Connection

A modem can be used to configure an Internet connection over an active phone line. An Internet Service Provider (ISP) account (also called a dial-up account) is required.
To add a modem connection, follow these steps:
  1. Click the Devices tab.
  2. Click the New button on the toolbar.
  3. Select Modem connection from the Device Type list, and click Forward.
  4. If there is a modem already configured in the hardware list (on the Hardware tab), the Network Administration Tool assumes you want to use it to establish a modem connection. If there are no modems already configured, it tries to detect any modems in the system. This probe might take a while. If a modem is not found, a message is displayed to warn you that the settings shown are not values found from the probe.
  5. After probing, the window in Figure 5.6, “Modem Settings” appears.
    Modem Settings
    Modem Settings
    Figure 5.6. Modem Settings

  6. Configure the modem device, baud rate, flow control, and modem volume. If you do not know these values, accept the defaults if the modem was probed successfully. If you do not have touch tone dialing, uncheck the corresponding checkbox. Click Forward.
  7. If your ISP is in the pre-configured list, select it. Otherwise, enter the required information about your ISP account. If you do not know these values, contact your ISP. Click Forward.
  8. On the IP Settings page, select whether to obtain an IP address automatically or whether to set one statically. Click Forward when finished.
  9. On the Create Dialup Connection page, click Apply.
After configuring the modem device, it appears in the device list with the type Modem as shown in Figure 5.7, “Modem Device”.
Modem Device
Modem Device
Figure 5.7. Modem Device

Be sure to select File > Save to save the changes.
After adding the modem device, you can edit its configuration by selecting the device from the device list and clicking Edit. For example, when the device is added, it is configured not to start at boot time by default. Edit its configuration to modify this setting. Compression, PPP options, login name, password, and more can also be changed.
When the device is added, it is not activated immediately, as seen by its Inactive status. To activate the device, select it from the device list, and click the Activate button. If the system is configured to activate the device when the computer starts (the default), this step does not have to be performed again.

5.5. Establishing an xDSL Connection

DSL stands for Digital Subscriber Lines. There are different types of DSL such as ADSL, IDSL, and SDSL. The Network Administration Tool uses the term xDSL to mean all types of DSL connections.
Some DSL providers require that the system is configured to obtain an IP address through DHCP with an Ethernet card. Some DSL providers require you to configure a PPPoE (Point-to-Point Protocol over Ethernet) connection with an Ethernet card. Ask your DSL provider which method to use.
If you are required to use DHCP, refer to Section 5.2, “Establishing an Ethernet Connection” to configure your Ethernet card.
If you are required to use PPPoE, follow these steps:
  1. Click the Devices tab.
  2. Click the New button.
  3. Select xDSL connection from the Device Type list, and click Forward as shown in Figure 5.8, “Select Device Type”.
    Select Device Type
    Select Device Type
    Figure 5.8. Select Device Type

  4. If your Ethernet card is in the hardware list, select the Ethernet Device from the pulldown menu from the page shown in Figure 5.9, “xDSL Settings”. Otherwise, the Select Ethernet Adapter window appears.

    Note

    The installation program detects supported Ethernet devices and prompts you to configure them. If you configured any Ethernet devices during the installation, they are displayed in the hardware list on the Hardware tab.
    xDSL Settings
    xDSL Settings
    Figure 5.9. xDSL Settings

  5. Enter the Provider Name, Login Name, and Password. If you are not setting up a T-Online account, select Normal from the Account Type pulldown menu.
    If you are setting up a T-Online account, select T-Online from the Account Type pulldown menu and enter any values in the Login name and Password field. You can further configure your T-Online account settings once the DSL connection has been fully configured (refer to Setting Up a T-Online Account).
  6. Click the Forward to go to the Create DSL Connection menu. Check your settings and click Apply to finish.
  7. After configuring the DSL connection, it appears in the device list as shown in Figure 5.10, “xDSL Device”.
    xDSL Device
    xDSL Device
    Figure 5.10. xDSL Device

  8. After adding the xDSL connection, you can edit its configuration by selecting the device from the device list and clicking Edit.
    xDSL Configuration
    xDSL Configuration
    Figure 5.11. xDSL Configuration

    For example, when the device is added, it is configured not to start at boot time by default. Edit its configuration to modify this setting. Click OK when finished.
  9. Once you are satisfied with your xDSL connection settings, select File > Save to save the changes.
Setting Up a T-Online Account
If you are setting up a T-Online Account, follow these additional steps:
  1. Select the device from the device list and click Edit.
  2. Select the Provider tab from the xDSL Configuration menu as shown in Figure 5.12, “xDSL Configuration - Provider Tab”.
    xDSL Configuration - Provider Tab
    xDSL Configuration - Provider Tab
    Figure 5.12. xDSL Configuration - Provider Tab

  3. Click the T-Online Account Setup button. This will open the Account Setup window for your T-Online account as shown in Figure 5.13, “Account Setup”.
    Account Setup
    Account Setup
    Figure 5.13. Account Setup

  4. Enter your Adapter identifier, Associated T-Online number, Concurrent user number/suffix, and Personal password.. Click OK when finished to close the Account Setup window.
  5. On the xDSL Configuration window, click OK. Be sure to select File > Save from the Network Administration Tool to save the changes.
When the device is added, it is not activated immediately, as seen by its Inactive status. To activate the device, select it from the device list, and click the Activate button. If the system is configured to activate the device when the computer starts (the default), this step does not have to be performed again.

5.6. Establishing a Token Ring Connection

A token ring network is a network in which all the computers are connected in a circular pattern. A token, or a special network packet, travels around the token ring and allows computers to send information to each other.

Tip

For more information on using token rings under Linux, refer to the Linux Token Ring Project website available at http://www.linuxtr.net/.
To add a token ring connection, follow these steps:
  1. Click the Devices tab.
  2. Click the New button on the toolbar.
  3. Select Token Ring connection from the Device Type list and click Forward.
  4. If you have already added the token ring card to the hardware list, select it from the Tokenring card list. Otherwise, select Other Tokenring Card to add the hardware device.
  5. If you selected Other Tokenring Card, the Select Token Ring Adapter window as shown in Figure 5.14, “Token Ring Settings” appears. Select the manufacturer and model of the adapter. Select the device name. If this is the system's first token ring card, select tr0; if this is the second token ring card, select tr1 (and so on). The Network Administration Tool also allows the user to configure the resources for the adapter. Click Forward to continue.
    Token Ring Settings
    Token Ring Settings
    Figure 5.14. Token Ring Settings

  6. On the Configure Network Settings page, choose between DHCP and static IP address. You may specify a hostname for the device. If the device receives a dynamic IP address each time the network is started, do not specify a hostname. Click Forward to continue.
  7. Click Apply on the Create Tokenring Device page.
After configuring the token ring device, it appears in the device list as shown in Figure 5.15, “Token Ring Device”.
Token Ring Device
Token Ring Device
Figure 5.15. Token Ring Device

Be sure to select File > Save to save the changes.
After adding the device, you can edit its configuration by selecting the device from the device list and clicking Edit. For example, you can configure whether the device is started at boot time.
When the device is added, it is not activated immediately, as seen by its Inactive status. To activate the device, select it from the device list, and click the Activate button. If the system is configured to activate the device when the computer starts (the default), this step does not have to be performed again.

5.7. Establishing a Wireless Connection

Wireless Ethernet devices are becoming increasingly popular. The configuration is similar to the Ethernet configuration except that it allows you to configure settings such as the SSID and key for the wireless device.
To add a wireless Ethernet connection, follow these steps:
  1. Click the Devices tab.
  2. Click the New button on the toolbar.
  3. Select Wireless connection from the Device Type list and click Forward.
  4. If you have already added the wireless network interface card to the hardware list, select it from the Wireless card list. Otherwise, select Other Wireless Card to add the hardware device.

    Note

    The installation program usually detects supported wireless Ethernet devices and prompts you to configure them. If you configured them during the installation, they are displayed in the hardware list on the Hardware tab.
  5. If you selected Other Wireless Card, the Select Ethernet Adapter window appears. Select the manufacturer and model of the Ethernet card and the device. If this is the first Ethernet card for the system, select eth0; if this is the second Ethernet card for the system, select eth1 (and so on). The Network Administration Tool also allows the user to configure the resources for the wireless network interface card. Click Forward to continue.
  6. On the Configure Wireless Connection page as shown in Figure 5.16, “Wireless Settings”, configure the settings for the wireless device.
    Wireless Settings
    Wireless Settings
    Figure 5.16. Wireless Settings

  7. On the Configure Network Settings page, choose between DHCP and static IP address. You may specify a hostname for the device. If the device receives a dynamic IP address each time the network is started, do not specify a hostname. Click Forward to continue.
  8. Click Apply on the Create Wireless Device page.
After configuring the wireless device, it appears in the device list as shown in Figure 5.17, “Wireless Device”.
Wireless Device
Wireless Device
Figure 5.17. Wireless Device

Be sure to select File > Save to save the changes.
After adding the wireless device, you can edit its configuration by selecting the device from the device list and clicking Edit. For example, you can configure the device to activate at boot time.
When the device is added, it is not activated immediately, as seen by its Inactive status. To activate the device, select it from the device list, and click the Activate button. If the system is configured to activate the device when the computer starts (the default), this step does not have to be performed again.

5.8. Managing DNS Settings

The DNS tab allows you to configure the system's hostname, domain, name servers, and search domain. Name servers are used to look up other hosts on the network.
If the DNS server names are retrieved from DHCP or PPPoE (or retrieved from the ISP), do not add primary, secondary, or tertiary DNS servers.
If the hostname is retrieved dynamically from DHCP or PPPoE (or retrieved from the ISP), do not change it.
DNS Configuration
DNS Configuration
Figure 5.18. DNS Configuration

Note

The name servers section does not configure the system to be a name server. Instead, it configures which name servers to use when resolving IP addresses to hostnames and vice-versa.

Warning

If the hostname is changed and system-config-network is started on the local host, you may not be able to start another X11 application. As such, you may have to re-login to a new desktop session.

5.9. Managing Hosts

The Hosts tab allows you to add, edit, or remove hosts from the /etc/hosts file. This file contains IP addresses and their corresponding hostnames.
When your system tries to resolve a hostname to an IP address or tries to determine the hostname for an IP address, it refers to the /etc/hosts file before using the name servers (if you are using the default Fedora configuration). If the IP address is listed in the /etc/hosts file, the name servers are not used. If your network contains computers whose IP addresses are not listed in DNS, it is recommended that you add them to the /etc/hosts file.
To add an entry to the /etc/hosts file, go to the Hosts tab, click the New button on the toolbar, provide the requested information, and click OK. Select File > Save or press Ctrl+S to save the changes to the /etc/hosts file. The network or network services do not need to be restarted since the current version of the file is referred to each time an address is resolved.

Warning

Do not remove the localhost entry. Even if the system does not have a network connection or have a network connection running constantly, some programs need to connect to the system via the localhost loopback interface.
Hosts Configuration
Hosts Configuration
Figure 5.19. Hosts Configuration

Tip

To change lookup order, edit the /etc/host.conf file. The line order hosts, bind specifies that /etc/hosts takes precedence over the name servers. Changing the line to order bind, hosts configures the system to resolve hostnames and IP addresses using the name servers first. If the IP address cannot be resolved through the name servers, the system then looks for the IP address in the /etc/hosts file.

5.10. Working with Profiles

Multiple logical network devices can be created for each physical hardware device. For example, if you have one Ethernet card in your system (eth0), you can create logical network devices with different nicknames and different configuration options, all to be specifically associated with eth0.
Logical network devices are different from device aliases. Logical network devices associated with the same physical device must exist in different profiles and cannot be activated simultaneously. Device aliases are also associated with the same physical hardware device, but device aliases associated with the same physical hardware can be activated at the same time. Refer to Section 5.11, “Device Aliases” for details about creating device aliases.
Profiles can be used to create multiple configuration sets for different networks. A configuration set can include logical devices as well as hosts and DNS settings. After configuring the profiles, you can use the Network Administration Tool to switch back and forth between them.
By default, there is one profile called Common. To create a new profile, select Profile > New from the pull-down menu, and enter a unique name for the profile.
You are now modifying the new profile as indicated by the status bar at the bottom of the main window.
Click on an existing device already in the list and click the Copy button to copy the existing device to a logical network device. If you use the New button, a network alias is created, which is incorrect. To change the properties of the logical device, select it from the list and click Edit. For example, the nickname can be changed to a more descriptive name, such as eth0_office, so that it can be recognized more easily.
In the list of devices, there is a column of checkboxes labeled Profile. For each profile, you can check or uncheck devices. Only the checked devices are included for the currently selected profile. For example, if you create a logical device named eth0_office in a profile called Office and want to activate the logical device if the profile is selected, uncheck the eth0 device and check the eth0_office device.
For example, Figure 5.20, “Office Profile” shows a profile called Office with the logical device eth0_office. It is configured to activate the first Ethernet card using DHCP.
Office Profile
Creating an Office Profile
Figure 5.20. Office Profile

Notice that the Home profile as shown in Figure 5.21, “Home Profile” activates the eth0_home logical device, which is associated with eth0.
Home Profile
Creating a Home Profile
Figure 5.21. Home Profile

You can also configure eth0 to activate in the Office profile only and to activate a PPP (modem) device in the Home profile only. Another example is to have the Common profile activate eth0 and an Away profile activate a PPP device for use while traveling.
To activate a profile at boot time, modify the boot loader configuration file to include the netprofile=<profilename> option. For example, if the system uses GRUB as the boot loader and /boot/grub/grub.conf contains:
title Red Hat Enterprise Linux (2.6.9-5.EL)
         root (hd0,0)
	 kernel /vmlinuz-2.6.9-5.EL ro root=/dev/VolGroup00/LogVol00 rhgb quiet
	 initrd /initrd-2.6.9-5.EL.img
Modify it to the following (where <profilename> is the name of the profile to be activated at boot time):
title Red Hat Enterprise Linux (2.6.9-5.EL)
         root (hd0,0)
	 kernel /vmlinuz-2.6.9-5.EL ro root=/dev/VolGroup00/LogVol00 \ 
	 	netprofile=<profilename>  \ 	  rhgb quiet
	 initrd /initrd-2.6.9-5.EL.img
To switch profiles after the system has booted, go to Applications (the main menu on the panel) > System Tools > Network Device Control (or type the command system-control-network) to select a profile and activate it. The activate profile section only appears in the Network Device Control interface if more than the default Common interface exists.
Alternatively, execute the following command to enable a profile (replace <profilename> with the name of the profile):
system-config-network-cmd --profile <profilename> --activate

5.11. Device Aliases

Device aliases are virtual devices associated with the same physical hardware, but they can be activated at the same time to have different IP addresses. They are commonly represented as the device name followed by a colon and a number (for example, eth0:1). They are useful if you want to have multiple IP addresses for a system that only has one network card.
After configuring the Ethernet device —such as eth0 —to use a static IP address (DHCP does not work with aliases), go to the Devices tab and click New. Select the Ethernet card to configure with an alias, set the static IP address for the alias, and click Apply to create it. Since a device already exists for the Ethernet card, the one just created is the alias, such as eth0:1.

Warning

If you are configuring an Ethernet device to have an alias, neither the device nor the alias can be configured to use DHCP. You must configure the IP addresses manually.
Figure 5.22, “Network Device Alias Example” shows an example of one alias for the eth0 device. Notice the eth0:1 device — the first alias for eth0. The second alias for eth0 would have the device name eth0:2, and so on. To modify the settings for the device alias, such as whether to activate it at boot time and the alias number, select it from the list and click the Edit button.
Network Device Alias Example
Network Alias Example
Figure 5.22. Network Device Alias Example

Select the alias and click the Activate button to activate the alias. If you have configured multiple profiles, select which profiles in which to include it.
To verify that the alias has been activated, use the command /sbin/ifconfig. The output should show the device and the device alias with different IP addresses:
eth0      Link encap:Ethernet
	HWaddr 00:A0:CC:60:B7:G4
	inet addr:192.168.100.5  Bcast:192.168.100.255  Mask:255.255.255.0
	UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
	RX packets:161930 errors:1 dropped:0 overruns:0 frame:0
	TX packets:244570 errors:0 dropped:0 overruns:0 carrier:0
	collisions:475 txqueuelen:100
	RX bytes:55075551 (52.5 Mb)  TX bytes:178108895 (169.8 Mb)
	Interrupt:10 Base address:0x9000  eth0:1    Link encap:Ethernet  HWaddr 00:A0:CC:60:B7:G4
	inet addr:192.168.100.42  Bcast:192.168.100.255  Mask:255.255.255.0
	UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
	Interrupt:10 Base address:0x9000  lo
	Link encap:Local Loopback
	inet addr:127.0.0.1  Mask:255.0.0.0
	UP LOOPBACK RUNNING  MTU:16436  Metric:1
	RX packets:5998 errors:0 dropped:0 overruns:0 frame:0
	TX packets:5998 errors:0 dropped:0 overruns:0 carrier:0
	collisions:0 txqueuelen:0
	RX bytes:1627579 (1.5 Mb)  TX bytes:1627579 (1.5 Mb)

5.12. Saving and Restoring the Network Configuration

The command line version of Network Administration Tool can be used to save the system's network configuration to a file. This file can then be used to restore the network settings to a Fedora system.
This feature can be used as part of an automated backup script, to save the configuration before upgrading or reinstalling, or to copy the configuration to a different Fedora system.
To save, or export, the network configuration of a system to the file /tmp/network-config, execute the following command as root:
system-config-network-cmd -e > /tmp/network-config

To restore, or import, the network configuration from the file created from the previous command, execute the following command as root:
system-config-network-cmd -i -c -f /tmp/network-config

The -i option means to import the data, the -c option means to clear the existing configuration prior to importing, and the -f option specifies that the file to import is as follows.

Chapter 6. Controlling Access to Services

Maintaining security on your system is extremely important, and one approach for this task is to manage access to system services carefully. Your system may need to provide open access to particular services (for example, httpd if you are running a Web server). However, if you do not need to provide a service, you should turn it off to minimize your exposure to possible bug exploits.
There are several different methods for managing access to system services. Choose which method of management to use based on the service, your system's configuration, and your level of Linux expertise.
The easiest way to deny access to a service is to turn it off. Both the services managed by xinetd and the services in the /etc/rc.d/init.d hierarchy (also known as SysV services) can be configured to start or stop using three different applications:
Services Configuration Tool
This is a graphical application that displays a description of each service, displays whether each service is started at boot time (for runlevels 3, 4, and 5), and allows services to be started, stopped, and restarted.
ntsysv
This is a text-based application that allows you to configure which services are started at boot time for each runlevel. Non-xinetd services can not be started, stopped, or restarted using this program.
chkconfig
This is a command line utility that allows you to turn services on and off for the different runlevels. Non-xinetd services can not be started, stopped, or restarted using this utility.
You may find that these tools are easier to use than the alternatives — editing the numerous symbolic links located in the directories below /etc/rc.d by hand or editing the xinetd configuration files in /etc/xinetd.d.
Another way to manage access to system services is by using iptables to configure an IP firewall. If you are a new Linux user, note that iptables may not be the best solution for you. Setting up iptables can be complicated, and is best tackled by experienced Linux system administrators.
On the other hand, the benefit of using iptables is flexibility. For example, if you need a customized solution which provides certain hosts access to certain services, iptables can provide it for you. Refer to and for more information about iptables.
Alternatively, if you are looking for a utility to set general access rules for your home machine, and/or if you are new to Linux, try the Security Level Configuration Tool (system-config-securitylevel), which allows you to select the security level for your system, similar to the Firewall Configuration screen in the installation program.
Refer to for more information.

Important

When you allow access for new services, always remember that both the firewall and SELinux need to be configured as well. One of the most common mistakes committed when configuring a new service is neglecting to implement the necessary firewall configuration and SELinux policies to allow access for it. Refer to for more information.

6.1. Runlevels

Before you can configure access to services, you must understand Linux runlevels. A runlevel is a state, or mode, that is defined by the services listed in the directory /etc/rc.d/rc<x>.d, where <x> is the number of the runlevel.
The following runlevels exist:
  • 0 — Halt
  • 1 — Single-user mode
  • 2 — Not used (user-definable)
  • 3 — Full multi-user mode
  • 4 — Not used (user-definable)
  • 5 — Full multi-user mode (with an X-based login screen)
  • 6 — Reboot
If you use a text login screen, you are operating in runlevel 3. If you use a graphical login screen, you are operating in runlevel 5.
The default runlevel can be changed by modifying the /etc/inittab file, which contains a line near the top of the file similar to the following:
id:5:initdefault:
Change the number in this line to the desired runlevel. The change does not take effect until you reboot the system.

6.2. TCP Wrappers

Many UNIX system administrators are accustomed to using TCP wrappers to manage access to certain network services. Any network services managed by xinetd (as well as any program with built-in support for libwrap) can use TCP wrappers to manage access. xinetd can use the /etc/hosts.allow and /etc/hosts.deny files to configure access to system services. As the names imply, hosts.allow contains a list of rules that allow clients to access the network services controlled by xinetd, and hosts.deny contains rules to deny access. The hosts.allow file takes precedence over the hosts.deny file. Permissions to grant or deny access can be based on individual IP address (or hostnames) or on a pattern of clients. Refer to hosts_access in section 5 of the man pages (man 5 hosts_access) for details.

6.2.1.  xinetd

To control access to Internet services, use xinetd, which is a secure replacement for inetd. The xinetd daemon conserves system resources, provides access control and logging, and can be used to start special-purpose servers. xinetd can also be used to grant or deny access to particular hosts, provide service access at specific times, limit the rate of incoming connections, limit the load created by connections, and more.
xinetd runs constantly and listens on all ports for the services it manages. When a connection request arrives for one of its managed services, xinetd starts up the appropriate server for that service.
The configuration file for xinetd is /etc/xinetd.conf, but the file only contains a few defaults and an instruction to include the /etc/xinetd.d directory. To enable or disable an xinetd service, edit its configuration file in the /etc/xinetd.d directory. If the disable attribute is set to yes, the service is disabled. If the disable attribute is set to no, the service is enabled. You can edit any of the xinetd configuration files or change its enabled status using the Services Configuration Tool, ntsysv, or chkconfig. For a list of network services controlled by xinetd, review the contents of the /etc/xinetd.d directory with the command ls /etc/xinetd.d.

6.3.  Services Configuration Tool

The Services Configuration Tool is a graphical application developed by Red Hat to configure which SysV services in the /etc/rc.d/init.d directory are started at boot time (for runlevels 3, 4, and 5) and which xinetd services are enabled. It also allows you to start, stop, and restart SysV services as well as reload xinetd.
To start the Services Configuration Tool from the desktop, go to the Applications (the main menu on the panel) > System Settings > Server Settings > Services or type the command system-config-services at a shell prompt (for example, in an XTerm or a GNOME terminal).
Services Configuration Tool
Configuring network services
Figure 6.1.  Services Configuration Tool

The Services Configuration Tool displays the current runlevel as well as the runlevel you are currently editing. To edit a different runlevel, select Edit Runlevel from the pulldown menu and select runlevel 3, 4, or 5. Refer to Section 6.1, “Runlevels” for a description of runlevels.
The Services Configuration Tool lists the services from the /etc/rc.d/init.d directory as well as the services controlled by xinetd. Click on the name of the service from the list on the left-hand side of the application to display a brief description of that service as well as the status of the service. If the service is not an xinetd service, the status window shows whether the service is currently running. If the service is controlled by xinetd, the status window displays the phrase xinetd service.
To start, stop, or restart a service immediately, select the service from the list and click the appropriate button on the toolbar (or choose the action from the Actions pulldown menu). If the service is an xinetd service, the action buttons are disabled because they cannot be started or stopped individually.
If you enable/disable an xinetd service by checking or unchecking the checkbox next to the service name, you must select File > Save Changes from the pulldown menu (or the Save button above the tabs) to reload xinetd and immediately enable/disable the xinetd service that you changed. xinetd is also configured to remember the setting. You can enable/disable multiple xinetd services at a time and save the changes when you are finished.
For example, assume you check rsync to enable it in runlevel 3 and then save the changes. The rsync service is immediately enabled. The next time xinetd is started, rsync is still enabled.

Note

When you save changes to xinetd services, xinetd is reloaded, and the changes take place immediately. When you save changes to other services, the runlevel is reconfigured, but the changes do not take effect immediately.
To enable a non-xinetd service to start at boot time for the currently selected runlevel, check the box beside the name of the service in the list. After configuring the runlevel, apply the changes by selecting File > Save Changes from the pulldown menu. The runlevel configuration is changed, but the runlevel is not restarted; thus, the changes do not take place immediately.
For example, assume you are configuring runlevel 3. If you change the value for the httpd service from checked to unchecked and then select Save Changes, the runlevel 3 configuration changes so that httpd is not started at boot time. However, runlevel 3 is not reinitialized, so httpd is still running. Select one of following options at this point:
  1. Stop the httpd service — Stop the service by selecting it from the list and clicking the Stop button. A message appears stating that the service was stopped successfully.
  2. Reinitialize the runlevel — Reinitialize the runlevel by going to a shell prompt and typing the command telinit x (where x is the runlevel number; in this example, 3.). This option is recommended if you change the Start at Boot value of multiple services and want to activate the changes immediately.
  3. Do nothing else — You do not have to stop the httpd service. You can wait until the system is rebooted for the service to stop. The next time the system is booted, the runlevel is initialized without the httpd service running.
To add a service to a runlevel, select the runlevel from the Edit Runlevel pulldown menu, and then select Actions > Add Service. To delete a service from a runlevel, select the runlevel from the Edit Runlevel pulldown menu, select the service to be deleted from the list on the left, and select Actions > Delete Service.

6.4.  ntsysv

The ntsysv utility provides a simple interface for activating or deactivating services. You can use ntsysv to turn an xinetd-managed service on or off. You can also use ntsysv to configure runlevels. By default, only the current runlevel is configured. To configure a different runlevel, specify one or more runlevels with the --level option. For example, the command ntsysv --level 345 configures runlevels 3, 4, and 5.
The ntsysv interface works like the text mode installation program. Use the up and down arrows to navigate up and down the list. The space bar selects/unselects services and is also used to "press" the Ok and Cancel buttons. To move between the list of services and the Ok and Cancel buttons, use the Tab key. An asterisk (*) signifies that a service is set to on. Pressing the F1 key displays a short description of the selected service.
The ntsysv utility
The ntsysv utility
Figure 6.2. The ntsysv utility

Warning

Services managed by xinetd are immediately affected by ntsysv. For all other services, changes do not take effect immediately. You must stop or start the individual service with the command service <daemon> stop (where <daemon> is the name of the service you want to stop; for example, httpd). Replace stop with start or restart to start or restart the service.

6.5.  chkconfig

The chkconfig command can also be used to activate and deactivate services. The chkconfig --list command displays a list of system services and whether they are started (on) or stopped (off) in runlevels 0-6. At the end of the list is a section for the services managed by xinetd.
If the chkconfig --list command is used to query a service managed by xinetd, it displays whether the xinetd service is enabled (on) or disabled (off). For example, the command chkconfig --list rsync returns the following output:
rsync on
As shown, rsync is enabled as an xinetd service. If xinetd is running, rsync is enabled.
If you use chkconfig --list to query a service in /etc/rc.d, that service's settings for each runlevel are displayed. For example, the command chkconfig --list httpd returns the following output:
httpd 0:off 1:off 2:on 3:on 4:on 5:on 6:off
chkconfig can also be used to configure a service to be started (or not) in a specific runlevel. For example, to turn nscd off in runlevels 3, 4, and 5, use the following command:
chkconfig --level 345 nscd off

Warning

Services managed by xinetd are immediately affected by chkconfig. For example, if xinetd is running while rsync is disabled, and the command chkconfig rsync on is executed, then rsync is immediately enabled without having to restart xinetd manually. Changes for other services do not take effect immediately after using chkconfig. You must stop or start the individual service with the command service <daemon> stop (where <daemon> is the name of the service you want to stop; for example, httpd). Replace stop with start or restart to start or restart the service.

6.6. Additional Resources

For more information, refer to the following resources.

6.6.1. Installed Documentation

  • The man pages for ntsysv, chkconfig, xinetd, and xinetd.conf.
  • man 5 hosts_access — The man page for the format of host access control files (in section 5 of the man pages).

6.6.2. Useful Websites

  • http://www.xinetd.org — The xinetd webpage. It contains sample configuration files and a more detailed list of features.

Chapter 7. Berkeley Internet Name Domain (BIND)

On most modern networks, including the Internet, users locate other computers by name. This frees users from the daunting task of remembering the numerical network address of network resources. The most effective way to configure a network to allow such name-based connections is to set up a Domain Name Service (DNS) or a nameserver, which resolves hostnames on the network to numerical addresses and vice versa.
This chapter reviews the nameserver included in Fedora and the Berkeley Internet Name Domain (BIND) DNS server, with an emphasis on the structure of its configuration files and how it may be administered both locally and remotely.

Note

BIND is also known as the service named in Fedora. You can manage it via the Services Configuration Tool (system-config-service).

7.1. Introduction to DNS

DNS associates hostnames with their respective IP addresses, so that when users want to connect to other machines on the network, they can refer to them by name, without having to remember IP addresses.
Use of DNS also has advantages for system administrators, allowing the flexibility to change the IP address for a host without affecting name-based queries to the machine. Conversely, administrators can shuffle which machines handle a name-based query.
DNS is normally implemented using centralized servers that are authoritative for some domains and refer to other DNS servers for other domains.
When a client host requests information from a nameserver, it usually connects to port 53. The nameserver then attempts to resolve the name requested. If the nameserver does not have an authoritative answer about the name the which host requested, or does not already have the answer cached from an earlier query, it queries other nameservers, called root nameservers, to determine which nameservers are authoritative for the name in question. Then, with that information, it queries the authoritative nameservers to get the requested name.

7.1.1. Nameserver Zones

In a DNS server such as BIND, all information is stored in basic data elements called resource records. A resource record is usually the fully qualified domain name (FQDN) of a host. Resource records are broken down into multiple sections. These sections are organized into a tree-like hierarchy consisting of a main trunk, primary branches, secondary branches, and so forth. Consider the following resource record:
bob.sales.example.com
When looking at how a resource record is resolved to find, for example, the IP address that relates to a particular system, read the name from right to left. Each level of the hierarchy is divided by a period (often called a "dot": . ). In this example, therefore, com defines the top-level domain for this resource record. The name example is a sub-domain under com, while sales is a sub-domain under example. The name furthest to the left, bob, identifies a resource record which is part of the sales.example.com domain.
Except for the first (leftmost) part of the resource record (bob), each section is called a zone. Zone defines a specific namespace. A zone contains definitions of resource records, which usually contain host-to-IP address mappings and IP address-to-host mappings, which are called reverse records).
Zones are defined on authoritative nameservers through the use of zone files, which define the resource records in that zone. Zone files are stored on primary nameservers (also called master nameservers), where changes are made to the files, and secondary nameservers (also called slave nameservers), which receive zone definitions from the primary nameservers. Both primary and secondary nameservers are authoritative for the zone and look the same to clients. Any nameserver can be a primary or secondary nameserver for multiple zones at the same time. It all depends on how the nameserver is configured.

7.1.2. Nameserver Types

There are two nameserver configuration types:
authoritative
This category includes both primary (master) and secondary (slave) servers. Those servers answer only for resource records which are part of their zones.
recursive
Offers resolution services, but is not authoritative for any zones. Answers for all resolutions are cached in memory for a fixed period of time, which is specified by the retrieved RR.
A nameserver may be one or both of these types. For example, a nameserver can be a master for some zones, a slave for others, and offer recursive services for others. However the best practice is not to combine authoritative and recursive servers due their absolutely different requirements. Authoritative servers are available for all clients and they should be available all the time otherwise it is not possible to resolve particular subtree of the DNS database. Recursive lookups take far more time than authoritative responses thus recursive servers should be available for a restricted number of clients. Otherwise recursive server could be easy target for distributed denial of service (DDoS) attack.

7.1.3. BIND as a Nameserver

BIND is set of DNS related programs. It contains a monolithic nameserver called /usr/sbin/named, an administration utility called /usr/sbin/rndc and DNS debugging utility called /usr/bin/dig. More information about rndc can be found in Section 7.4, “Using rndc.
BIND stores its configuration files in the following locations:
/etc/named.conf
The configuration file for the named daemon
/var/named/ directory
The named working directory which stores zone and statistic files

Note

If you have installed the bind-chroot package, the BIND service will run in the /var/named/chroot environment. All configuration files will be moved there. As such, named.conf will be located in /var/named/chroot/etc/named.conf, and so on.
The next few sections review the BIND configuration in more detail.

7.2.  /etc/named.conf

The named.conf file is a collection of statements using nested options surrounded by opening and closing ellipse characters, { }. Administrators must be careful when editing named.conf to avoid syntax errors as many seemingly minor errors prevent the named service from starting.
A typical named.conf file is organized similar to the following example:
<statement-1> ["<statement-1-name>"] [<statement-1-class>] { <option-1>; <option-2>; <option-N>; }; <statement-2> ["<statement-2-name>"] [<statement-2-class>] { <option-1>; <option-2>; <option-N>; }; <statement-N> ["<statement-N-name>"] [<statement-N-class>] { <option-1>; <option-2>; <option-N>; };

7.2.1. Common Statement Types

The following types of statements are commonly used in /etc/named.conf:

7.2.1.1.  acl Statement

The acl (Access Control List) statement defines groups of hosts which can then be permitted or denied access to the nameserver.
An acl statement takes the following form:
acl <acl-name> { <match-element>; [<match-element>; ...] };

In this statement, replace <acl-name> with the name of the access control list and replace <match-element> with a semi-colon separated list of IP addresses. Most of the time, an individual IP address or CIDR network notation (such as 10.0.1.0/24) is used to identify the IP addresses within the acl statement.
The following access control lists are already defined as keywords to simplify configuration:
  • any — Matches every IP address
  • localhost — Matches any IP address in use by the local system
  • localnets — Matches any IP address on any network to which the local system is connected
  • none — Matches no IP addresses
When used in conjunction with other statements (such as the options statement), acl statements can be very useful in preventing the misuse of a BIND nameserver.
The following example defines two access control lists and uses an options statement to define how they are treated by the nameserver:
	acl black-hats {
	10.0.2.0/24;     192.168.0.0/24;     1234:5678::9abc/24;};
	acl red-hats {     10.0.1.0/24;  };
options {
	blackhole { black-hats; };
	allow-query { red-hats; };
	allow-query-cache { red-hats; };
}

This example contains two access control lists, black-hats and red-hats. Hosts in the black-hats list are denied access to the nameserver, while hosts in the red-hats list are given normal access.

7.2.1.2.  include Statement

The include statement allows files to be included in a named.conf file. In this way, sensitive configuration data (such as keys) can be placed in a separate file with restrictive permissions.
An include statement takes the following form:
include "<file-name>"

In this statement, <file-name> is replaced with an absolute path to a file.

7.2.1.3.  options Statement

The options statement defines global server configuration options and sets defaults for other statements. It can be used to specify the location of the named working directory, the types of queries allowed, and much more.
The options statement takes the following form:
options { <option>; [<option>; ...] }; 

In this statement, the <option> directives are replaced with a valid option.
The following are commonly used options:
allow-query
Specifies which hosts are allowed to query this nameserver for authoritative RRs. By default, all hosts are allowed to query. An access control lists, or collection of IP addresses or networks, may be used here to allow only particular hosts to query the nameserver.
allow-query-cache
Similar to allow-query, this option applies to non-authoritative data, like recursive queries. By default, only localhost; and localnets; are allowed to obtain non-authoritative data.
blackhole
Specifies which hosts are banned from the server. This option should be used when particular host or network floods the server with requests. Default is none;
directory
Specifies the named working directory if different from the default value, /var/named/.
forwarders
Specifies a list of valid IP addresses for nameservers where requests should be forwarded for resolution.
forward
Specifies the forwarding behavior of a forwarders directive.
The following options are accepted:
  • first — Specifies that the nameservers listed in the forwarders directive be queried before named attempts to resolve the name itself.
  • only — Specifies that named does not attempt name resolution itself in the event that queries to nameservers specified in the forwarders directive fail.
listen-on
Specifies the IPv4 network interface on which named listens for queries. By default, all IPv4 interfaces are used.
Using this directive on a DNS server which also acts a gateway, BIND can be configured to only answer queries that originate from one of the networks.
The following is an example of a listen-on directive:
options { listen-on { 10.0.1.1; }; };

In this example, server listens only on (10.0.1.1) address.
listen-on-v6
Same as listen-on except for IPv6 interfaces.
The following is an example of a listen-on-v6 directive:
options { listen-on-v6 { 1234:5678::9abc; }; };

In this example, server listens only on (1234:5678::9abc) address.
max-cache-size
Specifies the maximum amount of memory to use for server caches. When the amount of data in the cache reaches this limit, the server will cause records to expire prematurely so that the limit is not exceeded. In a server with multiple views, the limit applies separately to the cache of each view. Default is 32M.
options { max-cache-size 256M; };

notify
Controls whether named notifies the slave servers when a zone is updated. It accepts the following options:
  • yes — Notifies slave servers.
  • no — Does not notify slave servers.
  • master-only - Send notify only when server is a master server for the zone.
  • explicit — Only notifies slave servers specified in an also-notify list within a zone statement.
pid-file
Specifies the location of the process ID file created by named.
recursion
Specifies if named acts as a recursive server. The default is yes.
options { recursion no; };

statistics-file
Specifies an alternate location for statistics files. By default, named statistics are saved to the /var/named/named.stats file.
There are many other options also available, many of which rely upon one another to work properly. Refer to the BIND 9 Administrator Reference Manual referenced in Section 7.7.1, “Installed Documentation” and the named.conf man page for more details.

7.2.1.4.  zone Statement

A zone statement defines the characteristics of a zone, such as the location of its configuration file and zone-specific options. This statement can be used to override the global options statements.
A zone statement takes the following form:
zone <zone-name> <zone-class> { <zone-options>; [<zone-options>; ...] };

In this statement, <zone-name> is the name of the zone, <zone-class> is the optional class of the zone, and <zone-options> is a list of options characterizing the zone.
The <zone-name> attribute for the zone statement is particularly important. It is the default value assigned for the $ORIGIN directive used within the corresponding zone file located in the /var/named/ directory. The named daemon appends the name of the zone to any non-fully qualified domain name listed in the zone file.
For example, if a zone statement defines the namespace for example.com, use example.com as the <zone-name> so it is placed at the end of hostnames within the example.com zone file.
For more information about zone files, refer to Section 7.3, “Zone Files”.
The most common zone statement options include the following:
allow-query
Specifies the clients that are allowed to request information about this zone. Setting of this option overrides global allow-query option. The default is to allow all query requests.
allow-transfer
Specifies the slave servers that are allowed to request a transfer of the zone's information. The default is to allow all transfer requests.
allow-update
Specifies the hosts that are allowed to dynamically update information in their zone. The default is to deny all dynamic update requests.
Be careful when allowing hosts to update information about their zone. Do not set IP addresses in this option unless the server is in the trusted network. Use TSIG key instead .
file
Specifies the name of the file in the named working directory that contains the zone's configuration data.
masters
Specifies the IP addresses from which to request authoritative zone information and is used only if the zone is defined as type slave.
notify
Specifies whether or not named notifies the slave servers when a zone is updated. This option has same parameters as a global notify parameter.
type
Defines the type of zone.
Below is a list of valid options:
  • delegation-only — Enforces the delegation status of infrastructure zones such as COM, NET, or ORG. Any answer that is received without an explicit or implicit delegation is treated as NXDOMAIN. This option is only applicable in TLDs or root zone files used in recursive or caching implementations.
  • forward — Forwards all requests for information about this zone to other nameservers.
  • hint — A special type of zone used to point to the root nameservers which resolve queries when a zone is not otherwise known. No configuration beyond the default is necessary with a hint zone.
  • master — Designates the nameserver as authoritative for this zone. A zone should be set as the master if the zone's configuration files reside on the system.
  • slave — Designates the nameserver as a slave server for this zone. Master server is specified in masters directive.

7.2.1.5. Sample zone Statements

Most changes to the /etc/named.conf file of a master or slave nameserver involves adding, modifying, or deleting zone statements. While these zone statements can contain many options, most nameservers require only a small subset to function efficiently. The following zone statements are very basic examples illustrating a master-slave nameserver relationship.
The following is an example of a zone statement for the primary nameserver hosting example.com (192.168.0.1):
zone "example.com" IN { type master; file "example.com.zone"; allow-transfer { 192.168.0.2; }; };

In the statement, the zone is identified as example.com, the type is set to master, and the named service is instructed to read the /var/named/example.com.zone file. It also allows only slave nameserver (192.168.0.2) to transfer the zone.
A slave server's zone statement for example.com is slightly different from the previous example. For a slave server, the type is set to slave and the masters directive is telling named the IP address of the master server.
The following is an example slave server zone statement for example.com zone:
zone "example.com" { type slave; file "slaves/example.com.zone"; masters { 192.168.0.1; }; };

This zone statement configures named on the slave server to query the master server at the 192.168.0.1 IP address for information about the example.com zone. The information that the slave server receives from the master server is saved to the /var/named/slaves/example.com.zone file. Make sure you put all slave zones to /var/named/slaves directory otherwise named will fail to transfer the zone.

7.2.2. Other Statement Types

The following is a list of lesser used statement types available within named.conf:
controls
Configures various security requirements necessary to use the rndc command to administer the named service.
Refer to Section 7.4.1, “Configuring /etc/named.conf to learn more about how the controls statement is structured and what options are available.
key "<key-name>"
Defines a particular key by name. Keys are used to authenticate various actions, such as secure updates or the use of the rndc command. Two options are used with key:
  • algorithm <algorithm-name> — The type of algorithm used, such as hmac-md5.
  • secret "<key-value>" — The encrypted key.
Refer to Section 7.4.2, “Configuring /etc/rndc.conf for instructions on how to write a key statement.
logging
Allows for the use of multiple types of logs, called channels. By using the channel option within the logging statement, a customized type of log can be constructed — with its own file name (file), size limit (size), versioning (version), and level of importance (severity). Once a customized channel is defined, a category option is used to categorize the channel and begin logging when named is restarted.
By default, named logs standard messages to the syslog daemon, which places them in /var/log/messages. This occurs because several standard channels are built into BIND with various severity levels, such as default_syslog (which handles informational logging messages) and default_debug (which specifically handles debugging messages). A default category, called default, uses the built-in channels to do normal logging without any special configuration.
Customizing the logging process can be a very detailed process and is beyond the scope of this chapter. For information on creating custom BIND logs, refer to the BIND 9 Administrator Reference Manual referenced in Section 7.7.1, “Installed Documentation”.
server
Specifies options that affect how named should respond to remote nameservers, especially with regard to notifications and zone transfers.
The transfer-format option controls whether one resource record is sent with each message (one-answer) or multiple resource records are sent with each message (many-answers). While many-answers is more efficient, only newer BIND nameservers understand it.
trusted-keys
Contains assorted public keys used for secure DNS (DNSSEC). Refer to Section 7.5.3, “Security” for more information concerning BIND security.
view "<view-name>"
Creates special views depending upon which network the host querying the nameserver is on. This allows some hosts to receive one answer regarding a zone while other hosts receive totally different information. Alternatively, certain zones may only be made available to particular trusted hosts while non-trusted hosts can only make queries for other zones.
Multiple views may be used, but their names must be unique. The match-clients option specifies the IP addresses that apply to a particular view. Any options statement may also be used within a view, overriding the global options already configured for named. Most view statements contain multiple zone statements that apply to the match-clients list. The order in which view statements are listed is important, as the first view statement that matches a particular client's IP address is used.
Refer to Section 7.5.2, “Multiple Views” for more information about the view statement.

7.2.3. Comment Tags

The following is a list of valid comment tags used within named.conf:
  • // — When placed at the beginning of a line, that line is ignored by named.
  • # — When placed at the beginning of a line, that line is ignored by named.
  • /* and */ — When text is enclosed in these tags, the block of text is ignored by named.

7.3. Zone Files

Zone files contain information about a namespace and are stored in the named working directory (/var/named/) by default. Each zone file is named according to the file option data in the zone statement, usually in a way that relates to the domain in question and identifies the file as containing zone data, such as example.com.zone.

Note

If you have installed the bind-chroot package, the BIND service will run in the /var/named/chroot environment. All configuration files will be moved there. As such, you can find the zone files in /var/named/chroot/var/named.
Each zone file may contain directives and resource records. Directives tell the nameserver to perform tasks or apply special settings to the zone. Resource records define the parameters of the zone and assign identities to individual hosts. Directives are optional, but resource records are required to provide name service to a zone.
All directives and resource records should be entered on individual lines.
Comments can be placed after semicolon characters (;) in zone files.

7.3.1. Zone File Directives

Directives begin with the dollar sign character ($) followed by the name of the directive. They usually appear at the top of the zone file.
The following are commonly used directives:
$INCLUDE
Configures named to include another zone file in this zone file at the place where the directive appears. This allows additional zone settings to be stored apart from the main zone file.
$ORIGIN
Appends the domain name to unqualified records, such as those with the hostname and nothing more.
For example, a zone file may contain the following line:
$ORIGIN example.com.

Any names used in resource records that do not end in a trailing period (.) are appended with example.com.

Note

The use of the $ORIGIN directive is unnecessary if the zone is specified in /etc/named.conf because the zone name is used as the value for the $ORIGIN directive by default.
$TTL
Sets the default Time to Live (TTL) value for the zone. This is the length of time, in seconds, that a zone resource record is valid. Each resource record can contain its own TTL value, which overrides this directive.
Increasing this value allows remote nameservers to cache the zone information for a longer period of time, reducing the number of queries for the zone and lengthening the amount of time required to proliferate resource record changes.

7.3.2. Zone File Resource Records

The primary component of a zone file is its resource records.
There are many types of zone file resource records. The following are used most frequently:
A
This refers to the Address record, which specifies an IP address to assign to a name, as in this example:
<host> IN A <IP-address> 

If the <host> value is omitted, then an A record points to a default IP address for the top of the namespace. This system is the target for all non-FQDN requests.
Consider the following A record examples for the example.com zone file:
server1	IN	A	10.0.1.3
		IN	A	10.0.1.5

Requests for example.com are pointed to 10.0.1.3 or 10.0.1.5.
CNAME
This refers to the Canonical Name record, which maps one name to another. This type of record can also be referred to as an alias record.
The next example tells named that any requests sent to the <alias-name> should point to the host, <real-name>. CNAME records are most commonly used to point to services that use a common naming scheme, such as www for Web servers.
<alias-name> IN CNAME <real-name> 

In the following example, an A record binds a hostname to an IP address, while a CNAME record points the commonly used www hostname to it.
server1 IN A 10.0.1.5
              www IN CNAME server1

MX
This refers to the Mail eXchange record, which tells where mail sent to a particular namespace controlled by this zone should go.
 IN MX <preference-value> <email-server-name> 

Here, the <preference-value> allows numerical ranking of the email servers for a namespace, giving preference to some email systems over others. The MX resource record with the lowest <preference-value> is preferred over the others. However, multiple email servers can possess the same value to distribute email traffic evenly among them.
The <email-server-name> may be a hostname or FQDN.
IN MX 10 mail.example.com.
              IN MX 20 mail2.example.com.

In this example, the first mail.example.com email server is preferred to the mail2.example.com email server when receiving email destined for the example.com domain.
NS
This refers to the NameServer record, which announces the authoritative nameservers for a particular zone.
The following illustrates the layout of an NS record:
 IN NS <nameserver-name> 

Here, <nameserver-name> should be an FQDN.
Next, two nameservers are listed as authoritative for the domain. It is not important whether these nameservers are slaves or if one is a master; they are both still considered authoritative.
IN NS dns1.example.com.
              IN NS dns2.example.com.

PTR
This refers to the PoinTeR record, which is designed to point to another part of the namespace.
PTR records are primarily used for reverse name resolution, as they point IP addresses back to a particular name. Refer to Section 7.3.4, “Reverse Name Resolution Zone Files” for more examples of PTR records in use.
SOA
This refers to the Start Of Authority resource record, which proclaims important authoritative information about a namespace to the nameserver.
Located after the directives, an SOA resource record is the first resource record in a zone file.
The following shows the basic structure of an SOA resource record:
@     IN     SOA    <primary-name-server>
              <hostmaster-email> (
	<serial-number>
              <time-to-refresh>
              <time-to-retry>
              <time-to-expire>
              <minimum-TTL> )

The @ symbol places the $ORIGIN directive (or the zone's name, if the $ORIGIN directive is not set) as the namespace being defined by this SOA resource record. The hostname of the primary nameserver that is authoritative for this domain is the <primary-name-server> directive, and the email of the person to contact about this namespace is the <hostmaster-email> directive.
The <serial-number> directive is a numerical value incremented every time the zone file is altered to indicate it is time for named to reload the zone. The <time-to-refresh> directive is the numerical value slave servers use to determine how long to wait before asking the master nameserver if any changes have been made to the zone. The <serial-number> directive is a numerical value used by the slave servers to determine if it is using outdated zone data and should therefore refresh it.
The <time-to-retry> directive is a numerical value used by slave servers to determine the length of time to wait before issuing a refresh request in the event that the master nameserver is not answering. If the master has not replied to a refresh request before the amount of time specified in the <time-to-expire> directive elapses, the slave servers stop responding as an authority for requests concerning that namespace.
In BIND 4 and 8, the <minimum-TTL> directive is the amount of time other nameservers cache the zone's information. However, in BIND 9, the <minimum-TTL> directive defines how long negative answers are cached for. Caching of negative answers can be set to a maximum of 3 hours (3H).
When configuring BIND, all times are specified in seconds. However, it is possible to use abbreviations when specifying units of time other than seconds, such as minutes (M), hours (H), days (D), and weeks (W). The table in Table 7.1, “Seconds compared to other time units” shows an amount of time in seconds and the equivalent time in another format.
Seconds Other Time Units
60 1M
1800 30M
3600 1H
10800 3H
21600 6H
43200 12H
86400 1D
259200 3D
604800 1W
31536000 365D
Table 7.1. Seconds compared to other time units

The following example illustrates the form an SOA resource record might take when it is populated with real values.
@     IN     SOA    dns1.example.com.     hostmaster.example.com. (
			2001062501 ; serial
			21600      ; refresh after 6 hours
			3600       ; retry after 1 hour
			604800     ; expire after 1 week
			86400 )    ; minimum TTL of 1 day

7.3.3. Example Zone File

Seen individually, directives and resource records can be difficult to grasp. However, when placed together in a single file, they become easier to understand.
The following example shows a very basic zone file.
$ORIGIN example.com.
$TTL 86400
@	SOA	dns1.example.com.	hostmaster.example.com. (
		2001062501 ; serial
		21600      ; refresh after 6 hours
		3600       ; retry after 1 hour
		604800     ; expire after 1 week
		86400 )    ; minimum TTL of 1 day
;
;
	NS	dns1.example.com.
	NS	dns2.example.com.
dns1	A	10.0.1.1
	AAAA	aaaa:bbbb::1
dns2	A	10.0.1.2
	AAAA	aaaa:bbbb::2
;
;
@	MX	10	mail.example.com.
	MX	20	mail2.example.com.
mail	A	10.0.1.5
	AAAA	aaaa:bbbb::5
mail2	A	10.0.1.6
	AAAA	aaaa:bbbb::6
;
;
; This sample zone file illustrates sharing the same IP addresses for multiple services:
;
services	A	10.0.1.10
		AAAA	aaaa:bbbb::10
		A	10.0.1.11
		AAAA	aaaa:bbbb::11

ftp	CNAME	services.example.com.
www	CNAME	services.example.com.
;
;

In this example, standard directives and SOA values are used. The authoritative nameservers are set as dns1.example.com and dns2.example.com, which have A records that tie them to 10.0.1.1 and 10.0.1.2, respectively.
The email servers configured with the MX records point to mail and mail2 via A records. Since the mail and mail2 names do not end in a trailing period (.), the $ORIGIN domain is placed after them, expanding them to mail.example.com and mail2.example.com. Through the related A resource records, their IP addresses can be determined.
Services available at the standard names, such as www.example.com (WWW), are pointed at the appropriate servers using a CNAME record.
This zone file would be called into service with a zone statement in the named.conf similar to the following:
zone "example.com" IN {
	type master;
	file "example.com.zone";
	allow-update { none; };
};

7.3.4. Reverse Name Resolution Zone Files

A reverse name resolution zone file is used to translate an IP address in a particular namespace into an FQDN. It looks very similar to a standard zone file, except that PTR resource records are used to link the IP addresses to a fully qualified domain name.
The following illustrates the layout of a PTR record:
<last-IP-digit> IN PTR <FQDN-of-system> 

The <last-IP-digit> is the last number in an IP address which points to a particular system's FQDN.
In the following example, IP addresses 10.0.1.1 through 10.0.1.6 are pointed to corresponding FQDNs. It can be located in /var/named/example.com.rr.zone.
$ORIGIN 1.0.10.in-addr.arpa.
$TTL 86400
@	IN	SOA	dns1.example.com.	hostmaster.example.com. (
			2001062501 ; serial
			21600      ; refresh after 6 hours
			3600       ; retry after 1 hour
			604800     ; expire after 1 week
			86400 )    ; minimum TTL of 1 day
;
;
1	IN	PTR	dns1.example.com.
2	IN	PTR	dns2.example.com.
;
5	IN	PTR    server1.example.com.
6	IN	PTR    server2.example.com.
;
3	IN	PTR    ftp.example.com.
4	IN	PTR    ftp.example.com.

This zone file would be called into service with a zone statement in the named.conf file similar to the following:
zone "1.0.10.in-addr.arpa" IN {
	type master;
	file "example.com.rr.zone";
	allow-update { none; };
};

There is very little difference between this example and a standard zone statement, except for the zone name. Note that a reverse name resolution zone requires the first three blocks of the IP address reversed followed by .in-addr.arpa. This allows the single block of IP numbers used in the reverse name resolution zone file to be associated with the zone.

7.4. Using rndc

BIND includes a utility called rndc which allows command line administration of the named daemon from the localhost or a remote host.
In order to prevent unauthorized access to the named daemon, BIND uses a shared secret key authentication method to grant privileges to hosts. This means an identical key must be present in both /etc/named.conf and the rndc configuration file, /etc/rndc.conf.

Note

If you have installed the bind-chroot package, the BIND service will run in the /var/named/chroot environment. All configuration files will be moved there. As such, the rndc.conf file is located in /var/named/chroot/etc/rndc.conf.
Note that since the rndc utility does not run in a chroot environment, /etc/rndc.conf is a symlink to /var/named/chroot/etc/rndc.conf.

7.4.1. Configuring /etc/named.conf

In order for rndc to connect to a named service, there must be a controls statement in the BIND server's /etc/named.conf file.
The controls statement, shown in the following example, allows rndc to connect from the localhost.
controls {
	inet 127.0.0.1
		allow { localhost; } keys { <key-name>; };
};

This statement tells named to listen on the default TCP port 953 of the loopback address and allow rndc commands coming from the localhost, if the proper key is given. The <key-name> specifies a name in the key statement within the /etc/named.conf file. The next example illustrates a sample key statement.
key "<key-name>" {
	algorithm hmac-md5;
	secret "<key-value>";
};

In this case, the <key-value> uses the HMAC-MD5 algorithm. Use the following command to generate keys using the HMAC-MD5 algorithm:
dnssec-keygen -a hmac-md5 -b <bit-length> -n HOST <key-file-name> 

A key with at least a 256-bit length is a good idea. The actual key that should be placed in the <key-value> area can be found in the <key-file-name> file generated by this command.

Warning

Because /etc/named.conf is world-readable, it is advisable to place the key statement in a separate file, readable only by root, and then use an include statement to reference it. For example:
include "/etc/rndc.key";

7.4.2. Configuring /etc/rndc.conf

The key is the most important statement in /etc/rndc.conf.
key "<key-name>" {
	algorithm hmac-md5;
	secret "<key-value>";
};

The <key-name> and <key-value> should be exactly the same as their settings in /etc/named.conf.
To match the keys specified in the target server's /etc/named.conf, add the following lines to /etc/rndc.conf.
options {
	default-server  localhost;
	default-key     "<key-name>";
};

This directive sets a global default key. However, the rndc configuration file can also specify different keys for different servers, as in the following example:
server localhost {
	key  "<key-name>";
};

Important

Make sure that only the root user can read or write to the /etc/rndc.conf file.
For more information about the /etc/rndc.conf file, refer to the rndc.conf man page.

7.4.3. Command Line Options

An rndc command takes the following form:
rndc <options> <command> <command-options> 

When executing rndc on a properly configured localhost, the following commands are available:
  • halt — Stops the named service immediately.
  • querylog — Logs all queries made to this nameserver.
  • refresh — Refreshes the nameserver's database.
  • reload — Reloads the zone files but keeps all other previously cached responses. This command also allows changes to zone files without losing all stored name resolutions.
    If changes made only affect a specific zone, reload only that specific zone by adding the name of the zone after the reload command.
  • stats — Dumps the current named statistics to the /var/named/named.stats file.
  • stop — Stops the server gracefully, saving any dynamic update and Incremental Zone Transfers (IXFR) data before exiting.
Occasionally, it may be necessary to override the default settings in the /etc/rndc.conf file. The following options are available:
  • -c <configuration-file> — Specifies the alternate location of a configuration file.
  • -p <port-number> — Specifies a port number to use for the rndc connection other than the default port 953.
  • -s <server> — Specifies a server other than the default-server listed in /etc/rndc.conf.
  • -y <key-name> — Specifies a key other than the default-key option in /etc/rndc.conf.
Additional information about these options can be found in the rndc man page.

7.5. Advanced Features of BIND

Most BIND implementations only use named to provide name resolution services or to act as an authority for a particular domain or sub-domain. However, BIND version 9 has a number of advanced features that allow for a more secure and efficient DNS service.

Caution

Some of these advanced features, such as DNSSEC, TSIG, and IXFR (which are defined in the following section), should only be used in network environments with nameservers that support the features. If the network environment includes non-BIND or older BIND nameservers, verify that each advanced feature is supported before attempting to use it.
All of the features mentioned are discussed in greater detail in the BIND 9 Administrator Reference Manual referenced in Section 7.7.1, “Installed Documentation”.

7.5.1. DNS Protocol Enhancements

BIND supports Incremental Zone Transfers (IXFR), where a slave nameserver only downloads the updated portions of a zone modified on a master nameserver. The standard transfer process requires that the entire zone be transferred to each slave nameserver for even the smallest change. For very popular domains with very lengthy zone files and many slave nameservers, IXFR makes the notification and update process much less resource-intensive.
Note that IXFR is only available when using dynamic updating to make changes to master zone records. If manually editing zone files to make changes, Automatic Zone Transfer (AXFR) is used. More information on dynamic updating is available in the BIND 9 Administrator Reference Manual referenced in Section 7.7.1, “Installed Documentation”.

7.5.2. Multiple Views

Through the use of the view statement in named.conf, BIND can present different information depending on which network a request originates from.
This is primarily used to deny sensitive DNS entries from clients outside of the local network, while allowing queries from clients inside the local network.
The view statement uses the match-clients option to match IP addresses or entire networks and give them special options and zone data.

7.5.3. Security

BIND supports a number of different methods to protect the updating and transfer of zones, on both master and slave nameservers:
DNSSEC
Short for DNS SECurity, this feature allows for zones to be cryptographically signed with a zone key.
In this way, the information about a specific zone can be verified as coming from a nameserver that has signed it with a particular private key, as long as the recipient has that nameserver's public key.
BIND version 9 also supports the SIG(0) public/private key method of message authentication.
TSIG
Short for Transaction SIGnatures, this feature allows a transfer from master to slave only after verifying that a shared secret key exists on both nameservers.
This feature strengthens the standard IP address-based method of transfer authorization. An attacker would not only need to have access to the IP address to transfer the zone, but they would also need to know the secret key.
BIND version 9 also supports TKEY, which is another shared secret key method of authorizing zone transfers.

7.5.4. IP version 6

BIND version 9 supports name service in IP version 6 (IPv6) environments through the use of A6 zone records.
If the network environment includes both IPv4 and IPv6 hosts, use the lwresd lightweight resolver daemon on all network clients. This daemon is a very efficient, caching-only nameserver which understands the new A6 and DNAME records used under IPv6. Refer to the lwresd man page for more information.

7.6. Common Mistakes to Avoid

It is very common for beginners to make mistakes when editing BIND configuration files. Be sure to avoid the following issues:
  • Take care to increment the serial number when editing a zone file.
    If the serial number is not incremented, the master nameserver has the correct, new information, but the slave nameservers are never notified of the change and do not attempt to refresh their data of that zone.
  • Be careful to use ellipses and semi-colons correctly in the /etc/named.conf file.
    An omitted semi-colon or unclosed ellipse section can cause named to refuse to start.
  • Remember to place periods (.) in zone files after all FQDNs and omit them on hostnames.
    A period at the end of a domain name denotes a fully qualified domain name. If the period is omitted, then named appends the name of the zone or the $ORIGIN value to complete it.
  • If a firewall is blocking connections from the named program to other nameservers, edit its configuration file.
    By default, BIND version 9 uses random ports above 1024 to query other nameservers. Some firewalls, however, expect all nameservers to communicate using only port 53. To force named to use port 53, add the following line to the options statement of /etc/named.conf:
    query-source address * port 53;
    
    

7.7. Additional Resources

The following sources of information provide additional resources regarding BIND.

7.7.1. Installed Documentation

BIND features a full range of installed documentation covering many different topics, each placed in its own subject directory. For each item below, replace <version-number> with the version of bind installed on the system:
/usr/share/doc/bind-<version-number>/
This directory lists the most recent features.
/usr/share/doc/bind-<version-number>/arm/
This directory contains the BIND 9 Administrator Reference Manual in HTML and SGML formats, which details BIND resource requirements, how to configure different types of nameservers, how to perform load balancing, and other advanced topics. For most new users of BIND, this is the best place to start.
/usr/share/doc/bind-<version-number>/draft/
This directory contains assorted technical documents that review issues related to DNS service and propose some methods to address them.
/usr/share/doc/bind-<version-number>/misc/
This directory contains documents designed to address specific advanced issues. Users of BIND version 8 should consult the migration document for specific changes they must make when moving to BIND 9. The options file lists all of the options implemented in BIND 9 that are used in /etc/named.conf.
/usr/share/doc/bind-<version-number>/rfc/
This directory provides every RFC document related to BIND.
There are also a number of man pages for the various applications and configuration files involved with BIND. The following lists some of the more important man pages.
Administrative Applications
  • man rndc — Explains the different options available when using the rndc command to control a BIND nameserver.
Server Applications
  • man named — Explores assorted arguments that can be used to control the BIND nameserver daemon.
  • man lwresd — Describes the purpose of and options available for the lightweight resolver daemon.
Configuration Files
  • man named.conf — A comprehensive list of options available within the named configuration file.
  • man rndc.conf — A comprehensive list of options available within the rndc configuration file.

7.7.2. Useful Websites

Chapter 8. OpenSSH

SSH™ (or Secure SHell) is a protocol which facilitates secure communications between two systems using a client/server architecture and allows users to log into server host systems remotely. Unlike other remote communication protocols, such as FTP or Telnet, SSH encrypts the login session, rendering the connection difficult for intruders to collect unencrypted passwords.
SSH is designed to replace older, less secure terminal applications used to log into remote hosts, such as telnet or rsh. A related program called scp replaces older programs designed to copy files between hosts, such as rcp. Because these older applications do not encrypt passwords transmitted between the client and the server, avoid them whenever possible. Using secure methods to log into remote systems decreases the risks for both the client system and the remote host.

8.1. Features of SSH

The SSH protocol provides the following safeguards:
  • After an initial connection, the client can verify that it is connecting to the same server it had connected to previously.
  • The client transmits its authentication information to the server using strong, 128-bit encryption.
  • All data sent and received during a session is transferred using 128-bit encryption, making intercepted transmissions extremely difficult to decrypt and read.
  • The client can forward X11[3] applications from the server. This technique, called X11 forwarding, provides a secure means to use graphical applications over a network.
Because the SSH protocol encrypts everything it sends and receives, it can be used to secure otherwise insecure protocols. Using a technique called port forwarding, an SSH server can become a conduit to securing otherwise insecure protocols, like POP, and increasing overall system and data security.
The OpenSSH server and client can also be configured to create a tunnel similar to a virtual private network for traffic between server and client machines.
Finally, OpenSSH servers and clients can be configured to authenticate using the GSSAPI implementation of the Kerberos network authentication protocol. For more information on configuring Kerberos authentication services, refer to .
Fedora includes the general OpenSSH package (openssh) as well as the OpenSSH server (openssh-server) and client (openssh-clients) packages. Note, the OpenSSH packages require the OpenSSL package (openssl) which installs several important cryptographic libraries, enabling OpenSSH to provide encrypted communications.

8.1.1. Why Use SSH?

Nefarious computer users have a variety of tools at their disposal enabling them to disrupt, intercept, and re-route network traffic in an effort to gain access to a system. In general terms, these threats can be categorized as follows:
  • Interception of communication between two systems — In this scenario, the attacker can be somewhere on the network between the communicating parties, copying any information passed between them. The attacker may intercept and keep the information, or alter the information and send it on to the intended recipient.
    This attack can be mounted through the use of a packet sniffer — a common network utility.
  • Impersonation of a particular host — Using this strategy, an attacker's system is configured to pose as the intended recipient of a transmission. If this strategy works, the user's system remains unaware that it is communicating with the wrong host.
    This attack can be mounted through techniques known as DNS poisoning[4] or IP spoofing[5].
Both techniques intercept potentially sensitive information and, if the interception is made for hostile reasons, the results can be disastrous.
If SSH is used for remote shell login and file copying, these security threats can be greatly diminished. This is because the SSH client and server use digital signatures to verify their identity. Additionally, all communication between the client and server systems is encrypted. Attempts to spoof the identity of either side of a communication does not work, since each packet is encrypted using a key known only by the local and remote systems.

8.2. SSH Protocol Versions

The SSH protocol allows any client and server programs built to the protocol's specifications to communicate securely and to be used interchangeably.
Two varieties of SSH (version 1 and version 2) currently exist. The OpenSSH suite under Fedora uses SSH version 2 which has an enhanced key exchange algorithm not vulnerable to the exploit in version 1. However, the OpenSSH suite does support version 1 connections.

Important

It is recommended that only SSH version 2-compatible servers and clients are used whenever possible.

8.3. Event Sequence of an SSH Connection

The following series of events help protect the integrity of SSH communication between two hosts.
  1. A cryptographic handshake is made so that the client can verify that it is communicating with the correct server.
  2. The transport layer of the connection between the client and remote host is encrypted using a symmetric cipher.
  3. The client authenticates itself to the server.
  4. The remote client interacts with the remote host over the encrypted connection.

8.3.1. Transport Layer

The primary role of the transport layer is to facilitate safe and secure communication between the two hosts at the time of authentication and during subsequent communication. The transport layer accomplishes this by handling the encryption and decryption of data, and by providing integrity protection of data packets as they are sent and received. The transport layer also provides compression, speeding the transfer of information.
Once an SSH client contacts a server, key information is exchanged so that the two systems can correctly construct the transport layer. The following steps occur during this exchange:
  • Keys are exchanged
  • The public key encryption algorithm is determined
  • The symmetric encryption algorithm is determined
  • The message authentication algorithm is determined
  • The hash algorithm is determined
During the key exchange, the server identifies itself to the client with a unique host key. If the client has never communicated with this particular server before, the server's host key is unknown to the client and it does not connect. OpenSSH gets around this problem by accepting the server's host key. This is done after the user is notified and has both accepted and verified the new host key. In subsequent connections, the server's host key is checked against the saved version on the client, providing confidence that the client is indeed communicating with the intended server. If, in the future, the host key no longer matches, the user must remove the client's saved version before a connection can occur.

Caution

It is possible for an attacker to masquerade as an SSH server during the initial contact since the local system does not know the difference between the intended server and a false one set up by an attacker. To help prevent this, verify the integrity of a new SSH server by contacting the server administrator before connecting for the first time or in the event of a host key mismatch.
SSH is designed to work with almost any kind of public key algorithm or encoding format. After an initial key exchange creates a hash value used for exchanges and a shared secret value, the two systems immediately begin calculating new keys and algorithms to protect authentication and future data sent over the connection.
After a certain amount of data has been transmitted using a given key and algorithm (the exact amount depends on the SSH implementation), another key exchange occurs, generating another set of hash values and a new shared secret value. Even if an attacker is able to determine the hash and shared secret value, this information is only useful for a limited period of time.

8.3.2. Authentication

Once the transport layer has constructed a secure tunnel to pass information between the two systems, the server tells the client the different authentication methods supported, such as using a private key-encoded signature or typing a password. The client then tries to authenticate itself to the server using one of these supported methods.
SSH servers and clients can be configured to allow different types of authentication, which gives each side the optimal amount of control. The server can decide which encryption methods it supports based on its security model, and the client can choose the order of authentication methods to attempt from the available options.

8.3.3. Channels

After a successful authentication over the SSH transport layer, multiple channels are opened via a technique called multiplexing [6]. Each of these channels handles communication for different terminal sessions and for forwarded X11 sessions.
Both clients and servers can create a new channel. Each channel is then assigned a different number on each end of the connection. When the client attempts to open a new channel, the clients sends the channel number along with the request. This information is stored by the server and is used to direct communication to that channel. This is done so that different types of sessions do not affect one another and so that when a given session ends, its channel can be closed without disrupting the primary SSH connection.
Channels also support flow-control, which allows them to send and receive data in an orderly fashion. In this way, data is not sent over the channel until the client receives a message that the channel is open.
The client and server negotiate the characteristics of each channel automatically, depending on the type of service the client requests and the way the user is connected to the network. This allows great flexibility in handling different types of remote connections without having to change the basic infrastructure of the protocol.

8.4. Configuring an OpenSSH Server

To run an OpenSSH server, you must first make sure that you have the proper RPM packages installed. The openssh-server package is required and is dependent on the openssh package.
The OpenSSH daemon uses the configuration file /etc/ssh/sshd_config. The default configuration file should be sufficient for most purposes. If you want to configure the daemon in ways not provided by the default sshd_config, read the sshd man page for a list of the keywords that can be defined in the configuration file.
To start the OpenSSH service, use the command /sbin/service sshd start. To stop the OpenSSH server, use the command /sbin/service sshd stop. If you want the daemon to start automatically at boot time, refer to Chapter 6, Controlling Access to Services for information on how to manage services.
If you reinstall, the reinstalled system creates a new set of identification keys. Any clients who had connected to the system with any of the OpenSSH tools before the reinstall will see the following message:
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that the RSA host key has just been changed.

If you want to keep the host keys generated for the system, backup the /etc/ssh/ssh_host*key* files and restore them after the reinstall. This process retains the system's identity, and when clients try to connect to the system after the reinstall, they will not receive the warning message.

8.4.1. Requiring SSH for Remote Connections

For SSH to be truly effective, using insecure connection protocols, such as Telnet and FTP, should be prohibited. Otherwise, a user's password may be protected using SSH for one session, only to be captured later while logging in using Telnet.
Some services to disable include:
  • telnet
  • rsh
  • rlogin
  • vsftpd
To disable insecure connection methods to the system, use the command line program chkconfig, the ncurses-based program /usr/sbin/ntsysv, or the Services Configuration Tool (system-config-services) graphical application. All of these tools require root level access.
For more information on runlevels and configuring services with chkconfig, /usr/sbin/ntsysv, and the Services Configuration Tool, refer to Chapter 6, Controlling Access to Services.

8.5. OpenSSH Configuration Files

OpenSSH has two different sets of configuration files: one for client programs (ssh, scp, and sftp) and one for the server daemon (sshd).
System-wide SSH configuration information is stored in the /etc/ssh/ directory:
  • moduli — Contains Diffie-Hellman groups used for the Diffie-Hellman key exchange which is critical for constructing a secure transport layer. When keys are exchanged at the beginning of an SSH session, a shared, secret value is created which cannot be determined by either party alone. This value is then used to provide host authentication.
  • ssh_config — The system-wide default SSH client configuration file. It is overridden if one is also present in the user's home directory (~/.ssh/config).
  • sshd_config — The configuration file for the sshd daemon.
  • ssh_host_dsa_key — The DSA private key used by the sshd daemon.
  • ssh_host_dsa_key.pub — The DSA public key used by the sshd daemon.
  • ssh_host_key — The RSA private key used by the sshd daemon for version 1 of the SSH protocol.
  • ssh_host_key.pub — The RSA public key used by the sshd daemon for version 1 of the SSH protocol.
  • ssh_host_rsa_key — The RSA private key used by the sshd daemon for version 2 of the SSH protocol.
  • ssh_host_rsa_key.pub — The RSA public key used by the sshd for version 2 of the SSH protocol.
User-specific SSH configuration information is stored in the user's home directory within the ~/.ssh/ directory:
  • authorized_keys — This file holds a list of authorized public keys for servers. When the client connects to a server, the server authenticates the client by checking its signed public key stored within this file.
  • id_dsa — Contains the DSA private key of the user.
  • id_dsa.pub — The DSA public key of the user.
  • id_rsa — The RSA private key used by ssh for version 2 of the SSH protocol.
  • id_rsa.pub — The RSA public key used by ssh for version 2 of the SSH protocol
  • identity — The RSA private key used by ssh for version 1 of the SSH protocol.
  • identity.pub — The RSA public key used by ssh for version 1 of the SSH protocol.
  • known_hosts — This file contains DSA host keys of SSH servers accessed by the user. This file is very important for ensuring that the SSH client is connecting the correct SSH server.

    Important

    If an SSH server's host key has changed, the client notifies the user that the connection cannot proceed until the server's host key is deleted from the known_hosts file using a text editor. Before doing this, however, contact the system administrator of the SSH server to verify the server is not compromised.
Refer to the ssh_config and sshd_config man pages for information concerning the various directives available in the SSH configuration files.

8.6. Configuring an OpenSSH Client

To connect to an OpenSSH server from a client machine, you must have the openssh-clients and openssh packages installed on the client machine.

8.6.1. Using the ssh Command

The ssh command is a secure replacement for the rlogin, rsh, and telnet commands. It allows you to log in to a remote machine as well as execute commands on a remote machine.
Logging in to a remote machine with ssh is similar to using telnet. To log in to a remote machine named penguin.example.net, type the following command at a shell prompt:
ssh penguin.example.net

The first time you ssh to a remote machine, you will see a message similar to the following:
The authenticity of host 'penguin.example.net' can't be established.
DSA key fingerprint is 94:68:3a:3a:bc:f3:9a:9b:01:5d:b3:07:38:e2:11:0c.
Are you sure you want to continue connecting (yes/no)?

Type yes to continue. This will add the server to your list of known hosts (~/.ssh/known_hosts) as seen in the following message:
Warning: Permanently added 'penguin.example.net' (RSA) to the list of known hosts.

Next, you will see a prompt asking for your password for the remote machine. After entering your password, you will be at a shell prompt for the remote machine. If you do not specify a username the username that you are logged in as on the local client machine is passed to the remote machine. If you want to specify a different username, use the following command:
ssh username@penguin.example.net

You can also use the syntax ssh -l username penguin.example.net.
The ssh command can be used to execute a command on the remote machine without logging in to a shell prompt. The syntax is ssh hostname command . For example, if you want to execute the command ls /usr/share/doc on the remote machine penguin.example.net, type the following command at a shell prompt:
ssh penguin.example.net ls /usr/share/doc

After you enter the correct password, the contents of the remote directory /usr/share/doc will be displayed, and you will return to your local shell prompt.

8.6.2. Using the scp Command

The scp command can be used to transfer files between machines over a secure, encrypted connection. It is similar to rcp.
The general syntax to transfer a local file to a remote system is as follows:
scp <localfile>
        username@tohostname:<remotefile>

The <localfile> specifies the source including path to the file, such as /var/log/maillog. The <remotefile> specifies the destination, which can be a new filename such as /tmp/hostname-maillog. For the remote system, if you do not have a preceding /, the path will be relative to the home directory of username, typically /home/username/.
To transfer the local file shadowman to the home directory of your account on penguin.example.net, type the following at a shell prompt (replace username with your username):
scp shadowman username@penguin.example.net:shadowman

This will transfer the local file shadowman to /home/username/shadowman on penguin.example.net. Alternately, you can leave off the final shadowman in the scp command.
The general syntax to transfer a remote file to the local system is as follows:
scp username@tohostname:<remotefile>
        <newlocalfile>

The <remotefile> specifies the source including path, and <newlocalfile> specifies the destination including path.
Multiple files can be specified as the source files. For example, to transfer the contents of the directory downloads/ to an existing directory called uploads/ on the remote machine penguin.example.net, type the following at a shell prompt:
scp downloads/* username@penguin.example.net:uploads/

8.6.3. Using the sftp Command

The sftp utility can be used to open a secure, interactive FTP session. It is similar to ftp except that it uses a secure, encrypted connection. The general syntax is sftp username@hostname.com . Once authenticated, you can use a set of commands similar to those used by FTP. Refer to the sftp man page for a list of these commands. To read the man page, execute the command man sftp at a shell prompt. The sftp utility is only available in OpenSSH version 2.5.0p1 and higher.

8.7. More Than a Secure Shell

A secure command line interface is just the beginning of the many ways SSH can be used. Given the proper amount of bandwidth, X11 sessions can be directed over an SSH channel. Or, by using TCP/IP forwarding, previously insecure port connections between systems can be mapped to specific SSH channels.

8.7.1. X11 Forwarding

Opening an X11 session over an SSH connection is as easy as connecting to the SSH server using the -Y option and running an X program on a local machine.
ssh -Y <user>@example.com

When an X program is run from the secure shell prompt, the SSH client and server create a new secure channel, and the X program data is sent over that channel to the client machine transparently.
X11 forwarding can be very useful. For example, X11 forwarding can be used to create a secure, interactive session of the Printer Configuration Tool. To do this, connect to the server using ssh and type:
system-config-printer &

After supplying the root password for the server, the Printer Configuration Tool appears and allows the remote user to safely configure printing on the remote system.

8.7.2. Port Forwarding

SSH can secure otherwise insecure TCP/IP protocols via port forwarding. When using this technique, the SSH server becomes an encrypted conduit to the SSH client.
Port forwarding works by mapping a local port on the client to a remote port on the server. SSH can map any port from the server to any port on the client; port numbers do not need to match for this technique to work.
To create a TCP/IP port forwarding channel which listens for connections on the localhost, use the following command:
ssh -L local-port:remote-hostname:remote-port
        username@hostname

Note

Setting up port forwarding to listen on ports below 1024 requires root level access.
To check email on a server called mail.example.com using POP3 through an encrypted connection, use the following command:
ssh -L 1100:mail.example.com:110 mail.example.com

Once the port forwarding channel is in place between the client machine and the mail server, direct a POP3 mail client to use port 1100 on the localhost to check for new mail. Any requests sent to port 1100 on the client system are directed securely to the mail.example.com server.
If mail.example.com is not running an SSH server, but another machine on the same network is, SSH can still be used to secure part of the connection. However, a slightly different command is necessary:
ssh -L 1100:mail.example.com:110 other.example.com

In this example, POP3 requests from port 1100 on the client machine are forwarded through the SSH connection on port 22 to the SSH server, other.example.com. Then, other.example.com connects to port 110 on mail.example.com to check for new mail. Note, when using this technique only the connection between the client system and other.example.com SSH server is secure.
Port forwarding can also be used to get information securely through network firewalls. If the firewall is configured to allow SSH traffic via its standard port (22) but blocks access to other ports, a connection between two hosts using the blocked ports is still possible by redirecting their communication over an established SSH connection.

Note

Using port forwarding to forward connections in this manner allows any user on the client system to connect to that service. If the client system becomes compromised, the attacker also has access to forwarded services.
System administrators concerned about port forwarding can disable this functionality on the server by specifying a No parameter for the AllowTcpForwarding line in /etc/ssh/sshd_config and restarting the sshd service.

8.7.3. Generating Key Pairs

If you do not want to enter your password every time you use ssh, scp, or sftp to connect to a remote machine, you can generate an authorization key pair.
Keys must be generated for each user. To generate keys for a user, use the following steps as the user who wants to connect to remote machines. If you complete the steps as root, only root will be able to use the keys.
Starting with OpenSSH version 3.0, ~/.ssh/authorized_keys2, ~/.ssh/known_hosts2, and /etc/ssh_known_hosts2 are obsolete. SSH Protocol 1 and 2 share the ~/.ssh/authorized_keys, ~/.ssh/known_hosts, and /etc/ssh/ssh_known_hosts files.
Fedora 12 uses SSH Protocol 2 and RSA keys by default.

Tip

If you reinstall and want to save your generated key pair, backup the .ssh directory in your home directory. After reinstalling, copy this directory back to your home directory. This process can be done for all users on your system, including root.

8.7.3.1. Generating an RSA Key Pair for Version 2

Use the following steps to generate an RSA key pair for version 2 of the SSH protocol. This is the default starting with OpenSSH 2.9.
  1. To generate an RSA key pair to work with version 2 of the protocol, type the following command at a shell prompt:
    ssh-keygen -t rsa
    
    
    Accept the default file location of ~/.ssh/id_rsa. Enter a passphrase different from your account password and confirm it by entering it again.
    The public key is written to ~/.ssh/id_rsa.pub. The private key is written to ~/.ssh/id_rsa. Never distribute your private key to anyone.
  2. Change the permissions of the .ssh directory using the following command:
    chmod 755 ~/.ssh
    
    
  3. Copy the contents of ~/.ssh/id_rsa.pub into the file ~/.ssh/authorized_keys on the machine to which you want to connect. If the file ~/.ssh/authorized_keys exist, append the contents of the file ~/.ssh/id_rsa.pub to the file ~/.ssh/authorized_keys on the other machine.
  4. Change the permissions of the authorized_keys file using the following command:
    chmod 644 ~/.ssh/authorized_keys
    
    
  5. If you are running GNOME or are running in a graphical desktop with GTK2+ libraries installed, skip to Section 8.7.3.4, “Configuring ssh-agent with a GUI”. If you are not running the X Window System, skip to Section 8.7.3.5, “Configuring ssh-agent.

8.7.3.2. Generating a DSA Key Pair for Version 2

Use the following steps to generate a DSA key pair for version 2 of the SSH Protocol.
  1. To generate a DSA key pair to work with version 2 of the protocol, type the following command at a shell prompt:
    ssh-keygen -t dsa
    
    
    Accept the default file location of ~/.ssh/id_dsa. Enter a passphrase different from your account password and confirm it by entering it again.

    Tip

    A passphrase is a string of words and characters used to authenticate a user. Passphrases differ from passwords in that you can use spaces or tabs in the passphrase. Passphrases are generally longer than passwords because they are usually phrases instead of a single word.
    The public key is written to ~/.ssh/id_dsa.pub. The private key is written to ~/.ssh/id_dsa. It is important never to give anyone the private key.
  2. Change the permissions of the .ssh directory with the following command:
    chmod 755 ~/.ssh
    
    
  3. Copy the contents of ~/.ssh/id_dsa.pub into the file ~/.ssh/authorized_keys on the machine to which you want to connect. If the file ~/.ssh/authorized_keys exist, append the contents of the file ~/.ssh/id_dsa.pub to the file ~/.ssh/authorized_keys on the other machine.
  4. Change the permissions of the authorized_keys file using the following command:
    chmod 644 ~/.ssh/authorized_keys
    
    
  5. If you are running GNOME or a graphical desktop environment with the GTK2+ libraries installed, skip to Section 8.7.3.4, “Configuring ssh-agent with a GUI”. If you are not running the X Window System, skip to Section 8.7.3.5, “Configuring ssh-agent.

8.7.3.3. Generating an RSA Key Pair for Version 1.3 and 1.5

Use the following steps to generate an RSA key pair, which is used by version 1 of the SSH Protocol. If you are only connecting between systems that use DSA, you do not need an RSA version 1.3 or RSA version 1.5 key pair.
  1. To generate an RSA (for version 1.3 and 1.5 protocol) key pair, type the following command at a shell prompt:
    ssh-keygen -t rsa1
    
    
    Accept the default file location (~/.ssh/identity). Enter a passphrase different from your account password. Confirm the passphrase by entering it again.
    The public key is written to ~/.ssh/identity.pub. The private key is written to ~/.ssh/identity. Do not give anyone the private key.
  2. Change the permissions of your .ssh directory and your key with the commands chmod 755 ~/.ssh and chmod 644 ~/.ssh/identity.pub.
  3. Copy the contents of ~/.ssh/identity.pub into the file ~/.ssh/authorized_keys on the machine to which you wish to connect. If the file ~/.ssh/authorized_keys does not exist, you can copy the file ~/.ssh/identity.pub to the file ~/.ssh/authorized_keys on the remote machine.
  4. If you are running GNOME, skip to Section 8.7.3.4, “Configuring ssh-agent with a GUI”. If you are not running GNOME, skip to Section 8.7.3.5, “Configuring ssh-agent.

8.7.3.4. Configuring ssh-agent with a GUI

The ssh-agent utility can be used to save your passphrase so that you do not have to enter it each time you initiate an ssh or scp connection. If you are using GNOME, the gnome-ssh-askpass package contains the application used to prompt you for your passphrase when you log in to GNOME and save it until you log out of GNOME. You will not have to enter your password or passphrase for any ssh or scp connection made during that GNOME session. If you are not using GNOME, refer to Section 8.7.3.5, “Configuring ssh-agent.
To save your passphrase during your GNOME session, follow the following steps:
  1. You will need to have the package gnome-ssh-askpass installed; you can use the command rpm -q openssh-askpass to determine if it is installed or not. If it is not installed, install it from your Fedora CD-ROM set, from a Red Hat FTP mirror site, or using Red Hat Network.
  2. Select Main Menu Button (on the Panel) > Preferences > More Preferences > Sessions, and click on the Startup Programs tab. Click Add and enter /usr/bin/ssh-add in the Startup Command text area. Set it a priority to a number higher than any existing commands to ensure that it is executed last. A good priority number for ssh-add is 70 or higher. The higher the priority number, the lower the priority. If you have other programs listed, this one should have the lowest priority. Click Close to exit the program.
  3. Log out and then log back into GNOME; in other words, restart X. After GNOME is started, a dialog box will appear prompting you for your passphrase(s). Enter the passphrase requested. If you have both DSA and RSA key pairs configured, you will be prompted for both. From this point on, you should not be prompted for a password by ssh, scp, or sftp.

8.7.3.5. Configuring ssh-agent

The ssh-agent can be used to store your passphrase so that you do not have to enter it each time you make a ssh or scp connection. If you are not running the X Window System, follow these steps from a shell prompt. If you are running GNOME but you do not want to configure it to prompt you for your passphrase when you log in (refer to Section 8.7.3.4, “Configuring ssh-agent with a GUI”), this procedure will work in a terminal window, such as an XTerm. If you are running X but not GNOME, this procedure will work in a terminal window. However, your passphrase will only be remembered for that terminal window; it is not a global setting.
  1. At a shell prompt, type the following command:
    exec /usr/bin/ssh-agent $SHELL
    
    
  2. Then type the command:
    ssh-add
    
    
    and enter your passphrase(s). If you have more than one key pair configured, you will be prompted for each one.
  3. When you log out, your passphrase(s) will be forgotten. You must execute these two commands each time you log in to a virtual console or open a terminal window.

8.8. Additional Resources

The OpenSSH and OpenSSL projects are in constant development, and the most up-to-date information for them is available from their websites. The man pages for OpenSSH and OpenSSL tools are also good sources of detailed information.

8.8.1. Installed Documentation

  • The ssh, scp, sftp, sshd, and ssh-keygen man pages — These man pages include information on how to use these commands as well as all the parameters that can be used with them.

8.8.2. Useful Websites



[3] X11 refers to the X11R7 windowing display system, traditionally referred to as the X Window System or X. Fedora includes X11R7, an open source X Window System.

[4] DNS poisoning occurs when an intruder cracks a DNS server, pointing client systems to a maliciously duplicated host.

[5] IP spoofing occurs when an intruder sends network packets which falsely appear to be from a trusted host on the network.

[6] A multiplexed connection consists of several signals being sent over a shared, common medium. With SSH, different channels are sent over a common secure connection.

Chapter 9. Samba

Samba is an open source implementation of the Server Message Block (SMB) protocol. It allows the networking of Microsoft Windows®, Linux, UNIX, and other operating systems together, enabling access to Windows-based file and printer shares. Samba's use of SMB allows it to appear as a Windows server to Windows clients.

9.1. Introduction to Samba

The third major release of Samba, version 3.0.0, introduced numerous improvements from prior versions, including:
  • The ability to join an Active Directory domain by means of LDAP and Kerberos
  • Built in Unicode support for internationalization
  • Support for Microsoft Windows XP Professional client connections to Samba servers without needing local registry hacking
  • Two new documents developed by the Samba.org team, which include a 400+ page reference manual, and a 300+ page implementation and integration manual. For more information about these published titles, refer to Section 9.12.2, “Related Books”.

9.1.1. Samba Features

Samba is a powerful and versatile server application. Even seasoned system administrators must know its abilities and limitations before attempting installation and configuration.
What Samba can do:
  • Serve directory trees and printers to Linux, UNIX, and Windows clients
  • Assist in network browsing (with or without NetBIOS)
  • Authenticate Windows domain logins
  • Provide Windows Internet Name Service (WINS) name server resolution
  • Act as a Windows NT®-style Primary Domain Controller (PDC)
  • Act as a Backup Domain Controller (BDC) for a Samba-based PDC
  • Act as an Active Directory domain member server
  • Join a Windows NT/2000/2003 PDC
What Samba cannot do:
  • Act as a BDC for a Windows PDC (and vice versa)
  • Act as an Active Directory domain controller

9.2. Samba Daemons and Related Services

The following is a brief introduction to the individual Samba daemons and services.

9.2.1. Samba Daemons

Samba is comprised of three daemons (smbd, nmbd, and winbindd). Two services (smb and windbind) control how the daemons are started, stopped, and other service-related features. Each daemon is listed in detail, as well as which specific service has control over it.
smbd
The smbd server daemon provides file sharing and printing services to Windows clients. In addition, it is responsible for user authentication, resource locking, and data sharing through the SMB protocol. The default ports on which the server listens for SMB traffic are TCP ports 139 and 445.
The smbd daemon is controlled by the smb service.
nmbd
The nmbd server daemon understands and replies to NetBIOS name service requests such as those produced by SMB/CIFS in Windows-based systems. These systems include Windows 95/98/ME, Windows NT, Windows 2000, Windows XP, and LanManager clients. It also participates in the browsing protocols that make up the Windows Network Neighborhood view. The default port that the server listens to for NMB traffic is UDP port 137.
The nmbd daemon is controlled by the smb service.
winbindd
The winbind service resolves user and group information on a server running Windows NT 2000 or Windows Server 2003. This makes Windows user / group information understandable by UNIX platforms. This is achieved by using Microsoft RPC calls, Pluggable Authentication Modules (PAM), and the Name Service Switch (NSS). This allows Windows NT domain users to appear and operate as UNIX users on a UNIX machine. Though bundled with the Samba distribution, the winbind service is controlled separately from the smb service.
The winbindd daemon is controlled by the winbind service and does not require the smb service to be started in order to operate. Winbindd is also used when Samba is an Active Directory member, and may also be used on a Samba domain controller (to implement nested groups and/or interdomain trust). Because winbind is a client-side service used to connect to Windows NT-based servers, further discussion of winbind is beyond the scope of this manual.

Note

You may refer to Section 9.11, “Samba Distribution Programs” for a list of utilities included in the Samba distribution.

9.3. Connecting to a Samba Share

You can use Nautilus to view available Samba shares on your network. Select Places (on the Panel) > Network Servers to view a list of Samba workgroups on your network. You can also type smb: in the File > Open Location bar of Nautilus to view the workgroups.
As shown in Figure 9.1, “SMB Workgroups in Nautilus”, an icon appears for each available SMB workgroup on the network.
SMB Workgroups in Nautilus
SMB Workgroups in Nautilus
Figure 9.1. SMB Workgroups in Nautilus

Double-click one of the workgroup icons to view a list of computers within the workgroup.
SMB Machines in Nautilus
SMB Machines in Nautilus
Figure 9.2. SMB Machines in Nautilus

As you can see from Figure 9.2, “SMB Machines in Nautilus”, there is an icon for each machine within the workgroup. Double-click on an icon to view the Samba shares on the machine. If a username and password combination is required, you are prompted for them.
Alternately, you can also specify the Samba server and sharename in the Location: bar for Nautilus using the following syntax (replace <servername> and <sharename> with the appropriate values):
smb://<servername>/<sharename> 

9.3.1. Command Line

To query the network for Samba servers, use the findsmb command. For each server found, it displays its IP address, NetBIOS name, workgroup name, operating system, and SMB server version.
To connect to a Samba share from a shell prompt, type the following command:
smbclient //<hostname>/<sharename> -U <username> 

Replace <hostname> with the hostname or IP address of the Samba server you want to connect to, <sharename> with the name of the shared directory you want to browse, and <username> with the Samba username for the system. Enter the correct password or press Enter if no password is required for the user.
If you see the smb:\> prompt, you have successfully logged in. Once you are logged in, type help for a list of commands. If you wish to browse the contents of your home directory, replace sharename with your username. If the -U switch is not used, the username of the current user is passed to the Samba server.
To exit smbclient, type exit at the smb:\> prompt.

9.3.2. Mounting the Share

Sometimes it is useful to mount a Samba share to a directory so that the files in the directory can be treated as if they are part of the local file system.
To mount a Samba share to a directory, create create a directory to mount it to (if it does not already exist), and execute the following command as root:
mount -t cifs -o <username>,<password> //<servername>/<sharename> /mnt/point/ 

This command mounts <sharename> from <servername> in the local directory /mnt/point/. For more information about mounting a samba share, refer to man mount.cifs.

9.4. Configuring a Samba Server

The default configuration file (/etc/samba/smb.conf) allows users to view their home directories as a Samba share. It also shares all printers configured for the system as Samba shared printers. In other words, you can attach a printer to the system and print to it from the Windows machines on your network.

9.4.1. Graphical Configuration

To configure Samba using a graphical interface, use the Samba Server Configuration Tool. For command line configuration, skip to Section 9.4.2, “Command Line Configuration”.
The Samba Server Configuration Tool is a graphical interface for managing Samba shares, users, and basic server settings. It modifies the configuration files in the /etc/samba/ directory. Any changes to these files not made using the application are preserved.
To use this application, you must be running the X Window System, have root privileges, and have the system-config-samba RPM package installed. To start the Samba Server Configuration Tool from the desktop, go to the System (on the Panel) > Administration > Server Settings > Samba or type the command system-config-samba at a shell prompt (for example, in an XTerm or a GNOME terminal).
Samba Server Configuration Tool
Samba Server Configuration Tool
Figure 9.3.  Samba Server Configuration Tool

Note

The Samba Server Configuration Tool does not display shared printers or the default stanza that allows users to view their own home directories on the Samba server.

9.4.1.1. Configuring Server Settings

The first step in configuring a Samba server is to configure the basic settings for the server and a few security options. After starting the application, select Preferences > Server Settings from the pulldown menu. The Basic tab is displayed as shown in Figure 9.4, “Configuring Basic Server Settings”.
Configuring Basic Server Settings
Configuring Basic Server Settings
Figure 9.4. Configuring Basic Server Settings

On the Basic tab, specify which workgroup the computer should be in as well as a brief description of the computer. They correspond to the workgroup and server string options in smb.conf.
Configuring Security Server Settings
Configuring Security Server Settings
Figure 9.5. Configuring Security Server Settings

The Security tab contains the following options:
  • Authentication Mode — This corresponds to the security option. Select one of the following types of authentication.
    • ADS — The Samba server acts as a domain member in an Active Directory Domain (ADS) realm. For this option, Kerberos must be installed and configured on the server, and Samba must become a member of the ADS realm using the net utility, which is part of the samba-client package. Refer to the net man page for details. This option does not configure Samba to be an ADS Controller. Specify the realm of the Kerberos server in the Kerberos Realm field.

      Note

      The Kerberos Realm field must be supplied in all uppercase letters, such as EXAMPLE.COM.
      Using a Samba server as a domain member in an ADS realm assumes proper configuration of Kerberos, including the /etc/krb5.conf file.
    • Domain — The Samba server relies on a Windows NT Primary or Backup Domain Controller to verify the user. The server passes the username and password to the Controller and waits for it to return. Specify the NetBIOS name of the Primary or Backup Domain Controller in the Authentication Server field.
      The Encrypted Passwords option must be set to Yes if this is selected.
    • Server — The Samba server tries to verify the username and password combination by passing them to another Samba server. If it can not, the server tries to verify using the user authentication mode. Specify the NetBIOS name of the other Samba server in the Authentication Server field.
    • Share — Samba users do not have to enter a username and password combination on a per Samba server basis. They are not prompted for a username and password until they try to connect to a specific shared directory from a Samba server.
    • User — (Default) Samba users must provide a valid username and password on a per Samba server basis. Select this option if you want the Windows Username option to work. Refer to Section 9.4.1.2, “Managing Samba Users” for details.
  • Encrypt Passwords — This option must be enabled if the clients are connecting from a system with Windows 98, Windows NT 4.0 with Service Pack 3, or other more recent versions of Microsoft Windows. The passwords are transfered between the server and the client in an encrypted format instead of as a plain-text word that can be intercepted. This corresponds to the encrypted passwords option. Refer to Section 9.4.3, “Encrypted Passwords” for more information about encrypted Samba passwords.
  • Guest Account — When users or guest users log into a Samba server, they must be mapped to a valid user on the server. Select one of the existing usernames on the system to be the guest Samba account. When guests log in to the Samba server, they have the same privileges as this user. This corresponds to the guest account option.
After clicking OK, the changes are written to the configuration file and the daemon is restarted; thus, the changes take effect immediately.

9.4.1.2. Managing Samba Users

The Samba Server Configuration Tool requires that an existing user account be active on the system acting as the Samba server before a Samba user can be added. The Samba user is associated with the existing user account.
Managing Samba Users
Managing Samba Users
Figure 9.6. Managing Samba Users

To add a Samba user, select Preferences > Samba Users from the pulldown menu, and click the Add User button. In the Create New Samba User window select a Unix Username from the list of existing users on the local system.
If the user has a different username on a Windows machine and needs to log into the Samba server from the Windows machine, specify that Windows username in the Windows Username field. The Authentication Mode on the Security tab of the Server Settings preferences must be set to User for this option to work.
Also, configure a Samba Password for the Samba User and confirm it by typing it again. Even if you opt to use encrypted passwords for Samba, it is recommended that the Samba passwords for all users are different from their system passwords.
To edit an existing user, select the user from the list, and click Edit User. To delete an existing Samba user, select the user, and click the Delete User button. Deleting a Samba user does not delete the associated system user account.
The users are modified immediately after clicking the OK button.

9.4.1.3. Adding a Share

To create a Samba share, click the Add button from the main Samba configuration window.
Adding a Share
Adding a Samba Share
Figure 9.7. Adding a Share

The Basic tab configures the following options:
  • Directory — The directory to share via Samba. The directory must exist before it can be entered here.
  • Share name — The actual name of the share that is seen from remote machines. By default, it is the same value as Directory, but can be configured.
  • Descriptions — A brief description of the share.
  • Writable — Enables users to read and write to the shared directory
  • Visible — Grants read-only rights to users for the shared directory.
On the Access tab, select whether to allow only specified users to access the share or whether to allow all Samba users to access the share. If you select to allow access to specific users, select the users from the list of available Samba users.
The share is added immediately after clicking OK.

9.4.2. Command Line Configuration

Samba uses /etc/samba/smb.conf as its configuration file. If you change this configuration file, the changes do not take effect until you restart the Samba daemon with the command service smb restart.
To specify the Windows workgroup and a brief description of the Samba server, edit the following lines in your smb.conf file:
workgroup = WORKGROUPNAME
server string = BRIEF COMMENT ABOUT SERVER

Replace WORKGROUPNAME with the name of the Windows workgroup to which this machine should belong. The BRIEF COMMENT ABOUT SERVER is optional and is used as the Windows comment about the Samba system.
To create a Samba share directory on your Linux system, add the following section to your smb.conf file (after modifying it to reflect your needs and your system):
[sharename]
comment = Insert a comment here
path = /home/share/
valid users = tfox carole
public = no
writable = yes
printable = no
create mask = 0765

The above example allows the users tfox and carole to read and write to the directory /home/share, on the Samba server, from a Samba client.

9.4.3. Encrypted Passwords

Encrypted passwords are enabled by default because it is more secure to do so. To create a user with an encrypted password, use the command smbpasswd -a <username> .

9.5. Starting and Stopping Samba

To start a Samba server, type the following command in a shell prompt while logged in as root:
/sbin/service smb start

Important

To set up a domain member server, you must first join the domain or Active Directory using the net join command before starting the smb service.
To stop the server, type the following command in a shell prompt while logged in as root:
/sbin/service smb stop

The restart option is a quick way of stopping and then starting Samba. This is the most reliable way to make configuration changes take effect after editing the configuration file for Samba. Note that the restart option starts the daemon even if it was not running originally.
To restart the server, type the following command in a shell prompt while logged in as root:
 /sbin/service smb restart 

The condrestart (conditional restart) option only starts smb on the condition that it is currently running. This option is useful for scripts, because it does not start the daemon if it is not running.

Note

When the smb.conf file is changed, Samba automatically reloads it after a few minutes. Issuing a manual restart or reload is just as effective.
To conditionally restart the server, type the following command as root:
 /sbin/service smb condrestart 

A manual reload of the smb.conf file can be useful in case of a failed automatic reload by the smb service. To ensure that the Samba server configuration file is reloaded without restarting the service, type the following command as root:
 /sbin/service smb reload 

By default, the smb service does not start automatically at boot time. To configure Samba to start at boot time, use an initscript utility, such as /sbin/chkconfig, /usr/sbin/ntsysv, or the Services Configuration Tool program. Refer to Chapter 6, Controlling Access to Services for more information regarding these tools.

9.6. Samba Server Types and the smb.conf File

Samba configuration is straightforward. All modifications to Samba are done in the /etc/samba/smb.conf configuration file. Although the default smb.conf file is well documented, it does not address complex topics such as LDAP, Active Directory, and the numerous domain controller implementations.
The following sections describe the different ways a Samba server can be configured. Keep in mind your needs and the changes required to the smb.conf file for a successful configuration.

9.6.1. Stand-alone Server

A stand-alone server can be a workgroup server or a member of a workgroup environment. A stand-alone server is not a domain controller and does not participate in a domain in any way. The following examples include several anonymous share-level security configurations and one user-level security configuration. For more information on share-level and user-level security modes, refer to Section 9.7, “Samba Security Modes”.

9.6.1.1. Anonymous Read-Only

The following smb.conf file shows a sample configuration needed to implement anonymous read-only file sharing. The security = share parameter makes a share anonymous. Note, security levels for a single Samba server cannot be mixed. The security directive is a global Samba parameter located in the [global] configuration section of the smb.conf file.
[global]
workgroup = DOCS
netbios name = DOCS_SRV
security = share
[data]
comment = Documentation Samba Server
path = /export
read only = Yes
guest only = Yes

9.6.1.2. Anonymous Read/Write

The following smb.conf file shows a sample configuration needed to implement anonymous read/write file sharing. To enable anonymous read/write file sharing, set the read only directive to no. The force user and force group directives are also added to enforce the ownership of any newly placed files specified in the share.

Note

Although having an anonymous read/write server is possible, it is not recommended. Any files placed in the share space, regardless of user, are assigned the user/group combination as specified by a generic user (force user) and group (force group) in the smb.conf file.
[global]
workgroup = DOCS
netbios name = DOCS_SRV
security = share
[data]
comment = Data
path = /export
force user = docsbot
force group = users
read only = No
guest ok = Yes

9.6.1.3. Anonymous Print Server

The following smb.conf file shows a sample configuration needed to implement an anonymous print server. Setting browseable to no as shown does not list the printer in Windows Network Neighborhood. Although hidden from browsing, configuring the printer explicitly is possible. By connecting to DOCS_SRV using NetBIOS, the client can have access to the printer if the client is also part of the DOCS workgroup. It is also assumed that the client has the correct local printer driver installed, as the use client driver directive is set to Yes. In this case, the Samba server has no responsibility for sharing printer drivers to the client.
[global]
workgroup = DOCS
netbios name = DOCS_SRV
security = share
printcap name = cups
disable spools= Yes
show add printer wizard = No
printing = cups
[printers]
comment = All Printers
path = /var/spool/samba
guest ok = Yes
printable = Yes
use client driver = Yes
browseable = Yes

9.6.1.4. Secure Read/Write File and Print Server

The following smb.conf file shows a sample configuration needed to implement a secure read/write print server. Setting the security directive to user forces Samba to authenticate client connections. Notice the [homes] share does not have a force user or force group directive as the [public] share does. The [homes] share uses the authenticated user details for any files created as opposed to the force user and force group in [public].
[global]
workgroup = DOCS
netbios name = DOCS_SRV
security = user
printcap name = cups
disable spools = Yes
show add printer wizard = No
printing = cups
[homes]
comment = Home Directories
valid users = %S
read only = No
browseable = No
[public]
comment = Data
path = /export
force user = docsbot
force group = users
guest ok = Yes
[printers]
comment = All Printers
path = /var/spool/samba
printer admin = john, ed, @admins
create mask = 0600
guest ok = Yes
printable = Yes
use client driver = Yes
browseable = Yes

9.6.2. Domain Member Server

A domain member, while similar to a stand-alone server, is logged into a domain controller (either Windows or Samba) and is subject to the domain's security rules. An example of a domain member server would be a departmental server running Samba that has a machine account on the Primary Domain Controller (PDC). All of the department's clients still authenticate with the PDC, and desktop profiles and all network policy files are included. The difference is that the departmental server has the ability to control printer and network shares.

9.6.2.1. Active Directory Domain Member Server

The following smb.conf file shows a sample configuration needed to implement an Active Directory domain member server. In this example, Samba authenticates users for services being run locally but is also a client of the Active Directory. Ensure that your kerberos realm parameter is shown in all caps (for example realm = EXAMPLE.COM). Since Windows 2000/2003 requires Kerberos for Active Directory authentication, the realm directive is required. If Active Directory and Kerberos are running on different servers, the password server directive may be required to help the distinction.
[global]
realm = EXAMPLE.COM
security = ADS
encrypt passwords = yes
# Optional. Use only if Samba cannot determine the Kerberos server automatically.
password server = kerberos.example.com

In order to join a member server to an Active Directory domain, the following steps must be completed:
  • Configuration of the smb.conf file on the member server
  • Configuration of Kerberos, including the /etc/krb5.conf file, on the member server
  • Creation of the machine account on the Active Directory domain server
  • Association of the member server to the Active Directory domain
To create the machine account and join the Windows 2000/2003 Active Directory, Kerberos must first be initialized for the member server wishing to join the Active Directory domain. To create an administrative Kerberos ticket, type the following command as root on the member server:
kinit administrator@EXAMPLE.COM
The kinit command is a Kerberos initialization script that references the Active Directory administrator account and Kerberos realm. Since Active Directory requires Kerberos tickets, kinit obtains and caches a Kerberos ticket-granting ticket for client/server authentication. For more information on Kerberos, the /etc/krb5.conf file, and the kinit command, refer to .
To join an Active Directory server (windows1.example.com), type the following command as root on the member server:
net ads join -S windows1.example.com -U administrator%password
Since the machine windows1 was automatically found in the corresponding Kerberos realm (the kinit command succeeded), the net command connects to the Active Directory server using its required administrator account and password. This creates the appropriate machine account on the Active Directory and grants permissions to the Samba domain member server to join the domain.

Note

Since security = ads and not security = user is used, a local password backend such as smbpasswd is not needed. Older clients that do not support security = ads are authenticated as if security = domain had been set. This change does not affect functionality and allows local users not previously in the domain.

9.6.2.2. Windows NT4-based Domain Member Server

The following smb.conf file shows a sample configuration needed to implement a Windows NT4-based domain member server. Becoming a member server of an NT4-based domain is similar to connecting to an Active Directory. The main difference is NT4-based domains do not use Kerberos in their authentication method, making the smb.conf file simpler. In this instance, the Samba member server functions as a pass through to the NT4-based domain server.
[global]
workgroup = DOCS
netbios name = DOCS_SRV
security = domain
[homes]
comment = Home Directories
valid users = %S
read only = No
browseable = No
[public]
comment = Data
path = /export
force user = docsbot
force group = users
guest ok = Yes

Having Samba as a domain member server can be useful in many situations. There are times where the Samba server can have other uses besides file and printer sharing. It may be beneficial to make Samba a domain member server in instances where Linux-only applications are required for use in the domain environment. Administrators appreciate keeping track of all machines in the domain, even if not Windows-based. In the event the Windows-based server hardware is deprecated, it is quite easy to modify the smb.conf file to convert the server to a Samba-based PDC. If Windows NT-based servers are upgraded to Windows 2000/2003, the smb.conf file is easily modifiable to incorporate the infrastructure change to Active Directory if needed.

Important

After configuring the smb.conf file, join the domain before starting Samba by typing the following command as root:
net rpc join -U administrator%password
Note that the -S option, which specifies the domain server hostname, does not need to be stated in the net rpc join command. Samba uses the hostname specified by the workgroup directive in the smb.conf file instead of it being stated explicitly.

9.6.3. Domain Controller

A domain controller in Windows NT is functionally similar to a Network Information Service (NIS) server in a Linux environment. Domain controllers and NIS servers both host user/group information databases as well as related services. Domain controllers are mainly used for security, including the authentication of users accessing domain resources. The service that maintains the user/group database integrity is called the Security Account Manager (SAM). The SAM database is stored differently between Windows and Linux Samba-based systems, therefore SAM replication cannot be achieved and platforms cannot be mixed in a PDC/BDC environment.
In a Samba environment, there can be only one PDC and zero or more BDCs.

Important

Samba cannot exist in a mixed Samba/Windows domain controller environment (Samba cannot be a BDC of a Windows PDC or vice versa). Alternatively, Samba PDCs and BDCs can coexist.

9.6.3.1. Primary Domain Controller (PDC) using tdbsam

The simplest and most common implementation of a Samba PDC uses the tdbsam password database backend. Planned to replace the aging smbpasswd backend, tdbsam has numerous improvements that are explained in more detail in Section 9.8, “Samba Account Information Databases”. The passdb backend directive controls which backend is to be used for the PDC.
[global]
workgroup = DOCS
netbios name = DOCS_SRV
passdb backend = tdbsam
security = user
add user script = /usr/sbin/useradd -m %u
delete user script = /usr/sbin/userdel -r %u
add group script = /usr/sbin/groupadd %g
delete group script = /usr/sbin/groupdel %g
add user to group script = /usr/sbin/usermod -G %g %u
add machine script = /usr/sbin/useradd -s /bin/false -d /dev/null  -g machines %u
# The following specifies the default logon script
# Per user logon scripts can be specified in the user
# account using pdbedit logon script = logon.bat
# This sets the default profile path.
# Set per user paths with pdbedit
logon drive = H:
domain logons = Yes
os level = 35
preferred master = Yes
domain master = Yes
[homes]
	comment = Home Directories
	valid users = %S
	read only = No
[netlogon]
	comment = Network Logon Service
	path = /var/lib/samba/netlogon/scripts
	browseable = No
	read only = No
# For profiles to work, create a user directory under the
# path shown.
mkdir -p /var/lib/samba/profiles/john
[Profiles]
	comment = Roaming Profile Share
	path = /var/lib/samba/profiles
	read only = No
	browseable = No
	guest ok = Yes
	profile acls = Yes
# Other resource shares ... ...

Note

If you need more than one domain controller or have more than 250 users, do not use a tdbsam authentication backend. LDAP is recommended in these cases.

9.6.3.2. Primary Domain Controller (PDC) with Active Directory

Although it is possible for Samba to be a member of an Active Directory, it is not possible for Samba to operate as an Active Directory domain controller.

9.7. Samba Security Modes

There are only two types of security modes for Samba, share-level and user-level, which are collectively known as security levels . Share-level security can only be implemented in one way, while user-level security can be implemented in one of four different ways. The different ways of implementing a security level are called security modes .

9.7.1. User-Level Security

User-level security is the default setting for Samba. Even if the security = user directive is not listed in the smb.conf file, it is used by Samba. If the server accepts the client's username/password, the client can then mount multiple shares without specifying a password for each instance. Samba can also accept session-based username/password requests. The client maintains multiple authentication contexts by using a unique UID for each logon.
In smb.conf, the security = user directive that sets user-level security is:
[GLOBAL]
...
security = user
...

The following sections describe other implementations of user-level security.

9.7.1.1. Domain Security Mode (User-Level Security)

In domain security mode, the Samba server has a machine account (domain security trust account) and causes all authentication requests to be passed through to the domain controllers. The Samba server is made into a domain member server by using the following directives in smb.conf:
[GLOBAL]
...
security = domain
workgroup = MARKETING
...

9.7.1.2. Active Directory Security Mode (User-Level Security)

If you have an Active Directory environment, it is possible to join the domain as a native Active Directory member. Even if a security policy restricts the use of NT-compatible authentication protocols, the Samba server can join an ADS using Kerberos. Samba in Active Directory member mode can accept Kerberos tickets.
In smb.conf, the following directives make Samba an Active Directory member server:
[GLOBAL]
...
security = ADS
realm = EXAMPLE.COM
password server = kerberos.example.com
...

9.7.1.3. Server Security Mode (User-Level Security)

Server security mode was previously used when Samba was not capable of acting as a domain member server.

Note

It is highly recommended to not use this mode since there are numerous security drawbacks.
In smb.conf, the following directives enable Samba to operate in server security mode:
[GLOBAL]
...
encrypt passwords = Yes
security = server
password server = "NetBIOS_of_Domain_Controller"
...

9.7.2. Share-Level Security

With share-level security, the server accepts only a password without an explicit username from the client. The server expects a password for each share, independent of the username. There have been recent reports that Microsoft Windows clients have compatibility issues with share-level security servers. Samba developers strongly discourage use of share-level security.
In smb.conf, the security = share directive that sets share-level security is:
[GLOBAL]
...
security = share
...

9.8. Samba Account Information Databases

The latest release of Samba offers many new features including new password database backends not previously available. Samba version 3.0.0 fully supports all databases used in previous versions of Samba. However, although supported, many backends may not be suitable for production use.
The following is a list different backends you can use with Samba. Other backends not listed here may also be available.
Plain Text
Plain text backends are nothing more than the /etc/passwd type backends. With a plain text backend, all usernames and passwords are sent unencrypted between the client and the Samba server. This method is very unsecure and is not recommended for use by any means. It is possible that different Windows clients connecting to the Samba server with plain text passwords cannot support such an authentication method.
smbpasswd
A popular backend used in previous Samba packages, the smbpasswd backend utilizes a plain ASCII text layout that includes the MS Windows LanMan and NT account, and encrypted password information. The smbpasswd backend lacks the storage of the Windows NT/2000/2003 SAM extended controls. The smbpasswd backend is not recommended because it does not scale well or hold any Windows information, such as RIDs for NT-based groups. The tdbsam backend solves these issues for use in a smaller database (250 users), but is still not an enterprise-class solution.
ldapsam_compat
The ldapsam_compat backend allows continued OpenLDAP support for use with upgraded versions of Samba. This option normally used when migrating to Samba 3.0.
tdbsam
The tdbsam backend provides an ideal database backend for local servers, servers that do not need built-in database replication, and servers that do not require the scalability or complexity of LDAP. The tdbsam backend includes all of the smbpasswd database information as well as the previously-excluded SAM information. The inclusion of the extended SAM data allows Samba to implement the same account and system access controls as seen with Windows NT/2000/2003-based systems.
The tdbsam backend is recommended for 250 users at most. Larger organizations should require Active Directory or LDAP integration due to scalability and possible network infrastructure concerns.
ldapsam
The ldapsam backend provides an optimal distributed account installation method for Samba. LDAP is optimal because of its ability to replicate its database to any number of servers using the OpenLDAP slurpd daemon. LDAP databases are light-weight and scalable, and as such are preferred by large enterprises.
If you are upgrading from a previous version of Samba to 3.0, note that the /usr/share/doc/samba-<version>/LDAP/samba.schema has changed. This file contains the attribute syntax definitions and objectclass definitions that the ldapsam backend will need in order to function properly.
As such, if you are using the ldapsam backend for your Samba server, you will need to configure slapd to include this schema file. Refer to Section 14.5, “The /etc/openldap/schema/ Directory” for directions on how to do this.

Note

You will need to have the openldap-server package installed if you want to use the ldapsam backend.
mysqlsam
The mysqlsam backend uses a MySQL-based database backend. This is useful for sites that already implement MySQL. At present, mysqlsam is now packed in a module separate from Samba, and as such is not officially supported by Samba.

9.9. Samba Network Browsing

Network browsing enables Windows and Samba servers to appear in the Windows Network Neighborhood. Inside the Network Neighborhood, icons are represented as servers and if opened, the server's shares and printers that are available are displayed.
Network browsing capabilities require NetBIOS over TCP/IP. NetBIOS-based networking uses broadcast (UDP) messaging to accomplish browse list management. Without NetBIOS and WINS as the primary method for TCP/IP hostname resolution, other methods such as static files (/etc/hosts) or DNS, must be used.
A domain master browser collates the browse lists from local master browsers on all subnets so that browsing can occur between workgroups and subnets. Also, the domain master browser should preferably be the local master browser for its own subnet.

9.9.1. Domain Browsing

By default, a Windows server PDC for a domain is also the domain master browser for that domain. A Samba server must not be set up as a domain master server in this type of situation
For subnets that do not include the Windows server PDC, a Samba server can be implemented as a local master browser. Configuring the smb.conf for a local master browser (or no browsing at all) in a domain controller environment is the same as workgroup configuration.

9.9.2. WINS (Windows Internetworking Name Server)

Either a Samba server or a Windows NT server can function as a WINS server. When a WINS server is used with NetBIOS enabled, UDP unicasts can be routed which allows name resolution across networks. Without a WINS server, the UDP broadcast is limited to the local subnet and therefore cannot be routed to other subnets, workgroups, or domains. If WINS replication is necessary, do not use Samba as your primary WINS server, as Samba does not currently support WINS replication.
In a mixed NT/2000/2003 server and Samba environment, it is recommended that you use the Microsoft WINS capabilities. In a Samba-only environment, it is recommended that you use only one Samba server for WINS.
The following is an example of the smb.conf file in which the Samba server is serving as a WINS server:
[global]
wins support = Yes

Tip

All servers (including Samba) should connect to a WINS server to resolve NetBIOS names. Without WINS, browsing only occurs on the local subnet. Furthermore, even if a domain-wide list is somehow obtained, hosts cannot be resolved for the client without WINS.

9.10. Samba with CUPS Printing Support

Samba allows client machines to share printers connected to the Samba server. In addition, Samba also allows client machines to send documents built in Linux to Windows printer shares. Although there are other printing systems that function with Fedora, CUPS (Common UNIX Print System) is the recommended printing system due to its close integration with Samba.

9.10.1. Simple smb.conf Settings

The following example shows a very basic smb.conf configuration for CUPS support:
[global]
load printers = Yes
printing = cups
printcap name = cups
[printers]
comment = All Printers
path = /var/spool/samba/print
printer = IBMInfoP
browseable = No
public = Yes
guest ok = Yes
writable = No
printable = Yes
printer admin = @ntadmins
[print$]
comment = Printer Drivers Share
path = /var/lib/samba/drivers
write list = ed, john
printer admin = ed, john

Other printing configurations are also possible. To add additional security and privacy for printing confidential documents, users can have their own print spooler not located in a public path. If a job fails, other users would not have access to the file.
The print$ share contains printer drivers for clients to access if not available locally. The print$ share is optional and may not be required depending on the organization.
Setting browseable to Yes enables the printer to be viewed in the Windows Network Neighborhood, provided the Samba server is set up correctly in the domain/workgroup.

9.11. Samba Distribution Programs

findsmb
findsmb <subnet_broadcast_address>
The findsmb program is a Perl script which reports information about SMB-aware systems on a specific subnet. If no subnet is specified the local subnet is used. Items displayed include IP address, NetBIOS name, workgroup or domain name, operating system, and version.
The following example shows the output of executing findsmb as any valid user on a system:
findsmb
IP ADDR       NETBIOS NAME  WORKGROUP/OS/VERSION
------------------------------------------------------------------
10.1.59.25    VERVE         [MYGROUP] [Unix] [Samba 3.0.0-15]
10.1.59.26    STATION22     [MYGROUP] [Unix] [Samba 3.0.2-7.FC1]
10.1.56.45    TREK         +[WORKGROUP] [Windows 5.0] [Windows 2000 LAN Manager]
10.1.57.94    PIXEL         [MYGROUP] [Unix] [Samba 3.0.0-15]
10.1.57.137   MOBILE001     [WORKGROUP] [Windows 5.0] [Windows 2000 LAN Manager]
10.1.57.141   JAWS         +[KWIKIMART] [Unix] [Samba 2.2.7a-security-rollup-fix]
10.1.56.159   FRED         +[MYGROUP] [Unix] [Samba 3.0.0-14.3E]
10.1.59.192   LEGION       *[MYGROUP] [Unix] [Samba 2.2.7-security-rollup-fix]
10.1.56.205   NANCYN       +[MYGROUP] [Unix] [Samba 2.2.7a-security-rollup-fix]

net
net <protocol> <function> <misc_options> <target_options>
The net utility is similar to the net utility used for Windows and MS-DOS. The first argument is used to specify the protocol to use when executing a command. The <protocol> option can be ads, rap, or rpc for specifying the type of server connection. Active Directory uses ads, Win9x/NT3 uses rap, and Windows NT4/2000/2003 uses rpc. If the protocol is omitted, net automatically tries to determine it.
The following example displays a list the available shares for a host named wakko:
net -l share -S wakko
Password:
Enumerating shared resources (exports) on remote server:
Share name   Type     Description
----------   ----     -----------
data         Disk     Wakko data share
tmp          Disk     Wakko tmp share
IPC$         IPC      IPC Service (Samba Server)
ADMIN$       IPC      IPC Service (Samba Server)

The following example displays a list of Samba users for a host named wakko:
net -l user -S wakko
root password:
User name             Comment
-----------------------------
andriusb              Documentation
joe                   Marketing
lisa                  Sales

nmblookup
nmblookup <options> <netbios_name>
The nmblookup program resolves NetBIOS names into IP addresses. The program broadcasts its query on the local subnet until the target machine replies.
Here is an example:
nmblookup trek
querying trek on 10.1.59.255
10.1.56.45 trek<00>

pdbedit
pdbedit <options>
The pdbedit program manages accounts located in the SAM database. All backends are supported including smbpasswd, LDAP, NIS+, and the tdb database library.
The following are examples of adding, deleting, and listing users:
pdbedit -a kristin
new password:
retype new password:
Unix username:        kristin
NT username:
Account Flags:        [U          ]
User SID:             S-1-5-21-1210235352-3804200048-1474496110-2012
Primary Group SID:    S-1-5-21-1210235352-3804200048-1474496110-2077
Full Name: Home Directory:       \\wakko\kristin
HomeDir Drive:
Logon Script:
Profile Path:         \\wakko\kristin\profile
Domain:               WAKKO
Account desc:
Workstations: Munged
dial:
Logon time:           0
Logoff time:          Mon, 18 Jan 2038 22:14:07 GMT
Kickoff time:         Mon, 18 Jan 2038 22:14:07 GMT
Password last set:    Thu, 29 Jan 2004 08:29:28
GMT Password can change:  Thu, 29 Jan 2004 08:29:28 GMT
Password must change: Mon, 18 Jan 2038 22:14:07 GMT
pdbedit -v -L kristin
Unix username:        kristin
NT username:
Account Flags:        [U          ]
User SID:             S-1-5-21-1210235352-3804200048-1474496110-2012
Primary Group SID:    S-1-5-21-1210235352-3804200048-1474496110-2077
Full Name:
Home Directory:       \\wakko\kristin
HomeDir Drive:
Logon Script:
Profile Path:         \\wakko\kristin\profile
Domain:               WAKKO
Account desc:
Workstations: Munged
dial:
Logon time:           0
Logoff time:          Mon, 18 Jan 2038 22:14:07 GMT
Kickoff time:         Mon, 18 Jan 2038 22:14:07 GMT
Password last set:    Thu, 29 Jan 2004 08:29:28 GMT
Password can change:  Thu, 29 Jan 2004 08:29:28 GMT
Password must change: Mon, 18 Jan 2038 22:14:07 GMT
pdbedit -L
andriusb:505:
joe:503:
lisa:504:
kristin:506:
pdbedit -x joe
pdbedit -L
andriusb:505: lisa:504: kristin:506:

rpcclient
rpcclient <server> <options>
The rpcclient program issues administrative commands using Microsoft RPCs, which provide access to the Windows administration graphical user interfaces (GUIs) for systems management. This is most often used by advanced users that understand the full complexity of Microsoft RPCs.
smbcacls
smbcacls <//server/share> <filename> <options>
The smbcacls program modifies Windows ACLs on files and directories shared by the Samba server.
smbclient
smbclient <//server/share> <password> <options>
The smbclient program is a versatile UNIX client which provides functionality similar to ftp.
smbcontrol
smbcontrol -i <options>
smbcontrol <options> <destination> <messagetype> <parameters>
The smbcontrol program sends control messages to running smbd or nmbd daemons. Executing smbcontrol -i runs commands interactively until a blank line or a 'q' is entered.
smbpasswd
smbpasswd <options> <username> <password>
The smbpasswd program manages encrypted passwords. This program can be run by a superuser to change any user's password as well as by an ordinary user to change their own Samba password.
smbspool
smbspool <job> <user> <title> <copies> <options> <filename>
The smbspool program is a CUPS-compatible printing interface to Samba. Although designed for use with CUPS printers, smbspool can work with non-CUPS printers as well.
smbstatus
smbstatus <options>
The smbstatus program displays the status of current connections to a Samba server.
smbtar
smbtar <options>
The smbtar program performs backup and restores of Windows-based share files and directories to a local tape archive. Though similar to the tar command, the two are not compatible.
testparm
testparm <options> <filename> <hostname IP_address>
The testparm program checks the syntax of the smb.conf file. If your smb.conf file is in the default location (/etc/samba/smb.conf) you do not need to specify the location. Specifying the hostname and IP address to the testparm program verifies that the hosts.allow and host.deny files are configured correctly. The testparm program also displays a summary of your smb.conf file and the server's role (stand-alone, domain, etc.) after testing. This is convenient when debugging as it excludes comments and concisely presents information for experienced administrators to read.
For example:
testparm
Load smb config files from /etc/samba/smb.conf
Processing section "[homes]"
Processing section "[printers]"
Processing section "[tmp]"
Processing section "[html]"
Loaded services file OK.
Server role: ROLE_STANDALONE
Press enter to see a dump of your service definitions
<enter>
# Global parameters
[global]
	workgroup = MYGROUP
	server string = Samba Server
	security = SHARE
	log file = /var/log/samba/%m.log
	max log size = 50
	socket options = TCP_NODELAY SO_RCVBUF=8192 SO_SNDBUF=8192
	dns proxy = No
[homes]
	comment = Home Directories
	read only = No
	browseable = No
[printers]
	comment = All Printers
	path = /var/spool/samba
	printable = Yes
	browseable = No
[tmp]
	comment = Wakko tmp
	path = /tmp
	guest only = Yes
[html]
	comment = Wakko www
	path = /var/www/html
	force user = andriusb
	force group = users
	read only = No
	guest only = Yes

wbinfo
wbinfo <options>
The wbinfo program displays information from the winbindd daemon. The winbindd daemon must be running for wbinfo to work.

9.12. Additional Resources

The following sections give you the means to explore Samba in greater detail.

9.12.1. Installed Documentation

  • /usr/share/doc/samba-<version-number>/ — All additional files included with the Samba distribution. This includes all helper scripts, sample configuration files, and documentation.
    This directory also contains online versions of The Official Samba-3 HOWTO-Collection and Samba-3 by Example, both of which are cited below.

9.12.2. Related Books

  • The Official Samba-3 HOWTO-Collection by John H. Terpstra and Jelmer R. Vernooij; Prentice Hall — The official Samba-3 documentation as issued by the Samba development team. This is more of a reference guide than a step-by-step guide.
  • Samba-3 by Example by John H. Terpstra; Prentice Hall — This is another official release issued by the Samba development team which discusses detailed examples of OpenLDAP, DNS, DHCP, and printing configuration files. This has step-by-step related information that helps in real-world implementations.
  • Using Samba, 2nd Edition by Jay T's, Robert Eckstein, and David Collier-Brown; O'Reilly — A good resource for novice to advanced users, which includes comprehensive reference material.

9.12.3. Useful Websites

  • http://www.samba.org/ — Homepage for the Samba distribution and all official documentation created by the Samba development team. Many resources are available in HTML and PDF formats, while others are only available for purchase. Although many of these links are not Fedora specific, some concepts may apply.
  • http://samba.org/samba/archives.html — Active email lists for the Samba community. Enabling digest mode is recommended due to high levels of list activity.
  • Samba newsgroups — Samba threaded newsgroups, such as gmane.org, that use the NNTP protocol are also available. This an alternative to receiving mailing list emails.
  • hhttp://sourceforge.net/projects/smbldap-tools/ — These are highly recommended for assisting in managing LDAP related resources. The scripts can be found at /usr/share/doc/samba-version_number/LDAP/smbldap-tools or can be downloaded from Sourceforge.

Chapter 10. Dynamic Host Configuration Protocol (DHCP)

Dynamic Host Configuration Protocol (DHCP) is a network protocol that automatically assigns TCP/IP information to client machines. Each DHCP client connects to the centrally located DHCP server, which returns that client's network configuration (including the IP address, gateway, and DNS servers).

10.1. Why Use DHCP?

DHCP is useful for automatic configuration of client network interfaces. When configuring the client system, the administrator chooses DHCP instead of specifying an IP address, netmask, gateway, or DNS servers. The client retrieves this information from the DHCP server. DHCP is also useful if an administrator wants to change the IP addresses of a large number of systems. Instead of reconfiguring all the systems, he can just edit one DHCP configuration file on the server for the new set of IP addresses. If the DNS servers for an organization changes, the changes are made on the DHCP server, not on the DHCP clients. When the administrator restarts the network or reboots the clients, the changes will go into effect.
If an organization has a functional DHCP server properly connected to a network, laptops and other mobile computer users can move these devices from office to office.

10.2. Configuring a DHCP Server

The dhcp package contains an ISC DHCP server. First, install the package as the superuser:
~]# yum install dhcp

Installing the dhcp package creates a file, /etc/dhcpd.conf, which is merely an empty configuration file:
~]# cat /etc/dhcpd.conf
#
# DHCP Server Configuration file.
#   see /usr/share/doc/dhcp*/dhcpd.conf.sample
The sample configuration file can be found at /usr/share/doc/dhcp-<version>/dhcpd.conf.sample. You should use this file to help you configure /etc/dhcpd.conf, which is explained in detail below.
DHCP also uses the file /var/lib/dhcpd/dhcpd.leases to store the client lease database. Refer to Section 10.2.2, “Lease Database” for more information.

10.2.1. Configuration File

The first step in configuring a DHCP server is to create the configuration file that stores the network information for the clients. Use this file to declare options and global options for client systems.
The configuration file can contain extra tabs or blank lines for easier formatting. Keywords are case-insensitive and lines beginning with a hash mark (#) are considered comments.
Two DNS update schemes are currently implemented — the ad-hoc DNS update mode and the interim DHCP-DNS interaction draft update mode. If and when these two are accepted as part of the Internet Engineering Task Force (IETF) standards process, there will be a third mode — the standard DNS update method. You must configure the DNS server for compatibility with these schemes. Version 3.0b2pl11 and previous versions used the ad-hoc mode; however, it has been deprecated. To keep the same behavior, add the following line to the top of the configuration file:
ddns-update-style ad-hoc;
To use the recommended mode, add the following line to the top of the configuration file:
ddns-update-style interim;
Refer to the dhcpd.conf man page for details about the different modes.
There are two types of statements in the configuration file:
  • Parameters — State how to perform a task, whether to perform a task, or what network configuration options to send to the client.
  • Declarations — Describe the topology of the network, describe the clients, provide addresses for the clients, or apply a group of parameters to a group of declarations.
The parameters that start with the keyword option are reffered to as options. These options control DHCP options; whereas, parameters configure values that are not optional or control how the DHCP server behaves.
Parameters (including options) declared before a section enclosed in curly brackets ({ }) are considered global parameters. Global parameters apply to all the sections below it.

Important

If the configuration file is changed, the changes do not take effect until the DHCP daemon is restarted with the command service dhcpd restart.

Tip

Instead of changing a DHCP configuration file and restarting the service each time, using the omshell command provides an interactive way to connect to, query, and change the configuration of a DHCP server. By using omshell, all changes can be made while the server is running. For more information on omshell, refer to the omshell man page.
In Example 10.1, “Subnet Declaration”, the routers, subnet-mask, domain-name, domain-name-servers, and time-offset options are used for any host statements declared below it.
Additionally, a subnet can be declared, a subnet declaration must be included for every subnet in the network. If it is not, the DHCP server fails to start.
In this example, there are global options for every DHCP client in the subnet and a range declared. Clients are assigned an IP address within the range.
subnet 192.168.1.0 netmask 255.255.255.0 {
        option routers                  192.168.1.254;
        option subnet-mask              255.255.255.0;

        option domain-name              "example.com";
        option domain-name-servers       192.168.1.1;

        option time-offset              -18000;     # Eastern Standard Time

	range 192.168.1.10 192.168.1.100;
}

Example 10.1. Subnet Declaration

All subnets that share the same physical network should be declared within a shared-network declaration as shown in Example 10.2, “Shared-network Declaration”. Parameters within the shared-network, but outside the enclosed subnet declarations, are considered to be global parameters. The name of the shared-network must be a descriptive title for the network, such as using the title 'test-lab' to describe all the subnets in a test lab environment.
shared-network name {
    option domain-name              "test.redhat.com";
    option domain-name-servers      ns1.redhat.com, ns2.redhat.com;
    option routers                  192.168.0.254;
    more parameters for EXAMPLE shared-network
    subnet 192.168.1.0 netmask 255.255.252.0 {
        parameters for subnet
        range 192.168.1.1 192.168.1.254;
    }
    subnet 192.168.2.0 netmask 255.255.252.0 {
        parameters for subnet
        range 192.168.2.1 192.168.2.254;
    }
}

Example 10.2. Shared-network Declaration

As demonstrated in Example 10.3, “Group Declaration”, the group declaration is used to apply global parameters to a group of declarations. For example, shared networks, subnets, and hosts can be grouped.
group {
   option routers                  192.168.1.254;
   option subnet-mask              255.255.255.0;

   option domain-name              "example.com";
   option domain-name-servers       192.168.1.1;

   option time-offset              -18000;     # Eastern Standard Time

   host apex {
      option host-name "apex.example.com";
      hardware ethernet 00:A0:78:8E:9E:AA;
      fixed-address 192.168.1.4;
   }

   host raleigh {
      option host-name "raleigh.example.com";
      hardware ethernet 00:A1:DD:74:C3:F2;
      fixed-address 192.168.1.6;
   }
}

Example 10.3. Group Declaration

To configure a DHCP server that leases a dynamic IP address to a system within a subnet, modify Example 10.4, “Range Parameter” with your values. It declares a default lease time, maximum lease time, and network configuration values for the clients. This example assigns IP addresses in the range 192.168.1.10 and 192.168.1.100 to client systems.
default-lease-time 600;
max-lease-time 7200;
option subnet-mask 255.255.255.0;
option broadcast-address 192.168.1.255;
option routers 192.168.1.254;
option domain-name-servers 192.168.1.1, 192.168.1.2;
option domain-name "example.com";

subnet 192.168.1.0 netmask 255.255.255.0 {
   range 192.168.1.10 192.168.1.100;
}

Example 10.4. Range Parameter

To assign an IP address to a client based on the MAC address of the network interface card, use the hardware ethernet parameter within a host declaration. As demonstrated in Example 10.5, “Static IP Address using DHCP”, the host apex declaration specifies that the network interface card with the MAC address 00:A0:78:8E:9E:AA always receives the IP address 192.168.1.4.
Note that the optional parameter host-name can also be used to assign a host name to the client.
host apex {
   option host-name "apex.example.com";
   hardware ethernet 00:A0:78:8E:9E:AA;
   fixed-address 192.168.1.4;
}

Example 10.5. Static IP Address using DHCP

Tip

The sample configuration file provided can be used as a starting point and custom configuration options can be added to it. To copy it to the proper location, use the following command:
cp /usr/share/doc/dhcp-<version-number>/dhcpd.conf.sample /etc/dhcpd.conf

(where <version-number> is the DHCP version number).
For a complete list of option statements and what they do, refer to the dhcp-options man page.

10.2.2. Lease Database

On the DHCP server, the file /var/lib/dhcpd/dhcpd.leases stores the DHCP client lease database. Do not change this file. DHCP lease information for each recently assigned IP address is automatically stored in the lease database. The information includes the length of the lease, to whom the IP address has been assigned, the start and end dates for the lease, and the MAC address of the network interface card that was used to retrieve the lease.
All times in the lease database are in Coordinated Universal Time (UTC), not local time.
The lease database is recreated from time to time so that it is not too large. First, all known leases are saved in a temporary lease database. The dhcpd.leases file is renamed dhcpd.leases~ and the temporary lease database is written to dhcpd.leases.
The DHCP daemon could be killed or the system could crash after the lease database has been renamed to the backup file but before the new file has been written. If this happens, the dhcpd.leases file does not exist, but it is required to start the service. Do not create a new lease file. If you do, all old leases are lost which causes many problems. The correct solution is to rename the dhcpd.leases~ backup file to dhcpd.leases and then start the daemon.

10.2.3. Starting and Stopping the Server

Important

When the DHCP server is started for the first time, it fails unless the dhcpd.leases file exists. Use the command touch /var/lib/dhcpd/dhcpd.leases to create the file if it does not exist.
If the same server is also running BIND as a DNS server, this step is not necessary, as starting the named service automatically checks for a dhcpd.leases file.
To start the DHCP service, use the command /sbin/service dhcpd start. To stop the DHCP server, use the command /sbin/service dhcpd stop.
By default, the DHCP service does not start at boot time. To configure the daemon to start automatically at boot time, refer to Chapter 6, Controlling Access to Services.
If more than one network interface is attached to the system, but the DHCP server should only be started on one of the interfaces, configure the DHCP server to start only on that device. In /etc/sysconfig/dhcpd, add the name of the interface to the list of DHCPDARGS:
# Command line options here
DHCPDARGS=eth0

This is useful for a firewall machine with two network cards. One network card can be configured as a DHCP client to retrieve an IP address to the Internet. The other network card can be used as a DHCP server for the internal network behind the firewall. Specifying only the network card connected to the internal network makes the system more secure because users can not connect to the daemon via the Internet.
Other command line options that can be specified in /etc/sysconfig/dhcpd include:
  • -p <portnum> — Specifies the UDP port number on which dhcpd should listen. The default is port 67. The DHCP server transmits responses to the DHCP clients at a port number one greater than the UDP port specified. For example, if the default port 67 is used, the server listens on port 67 for requests and responses to the client on port 68. If a port is specified here and the DHCP relay agent is used, the same port on which the DHCP relay agent should listen must be specified. Refer to Section 10.2.4, “DHCP Relay Agent” for details.
  • -f — Runs the daemon as a foreground process. This is mostly used for debugging.
  • -d — Logs the DHCP server daemon to the standard error descriptor. This is mostly used for debugging. If this is not specified, the log is written to /var/log/messages.
  • -cf <filename> — Specifies the location of the configuration file. The default location is /etc/dhcpd.conf.
  • -lf <filename> — Specifies the location of the lease database file. If a lease database file already exists, it is very important that the same file be used every time the DHCP server is started. It is strongly recommended that this option only be used for debugging purposes on non-production machines. The default location is /var/lib/dhcpd/dhcpd.leases.
  • -q — Do not print the entire copyright message when starting the daemon.

10.2.4. DHCP Relay Agent

The DHCP Relay Agent (dhcrelay) allows for the relay of DHCP and BOOTP requests from a subnet with no DHCP server on it to one or more DHCP servers on other subnets.
When a DHCP client requests information, the DHCP Relay Agent forwards the request to the list of DHCP servers specified when the DHCP Relay Agent is started. When a DHCP server returns a reply, the reply is broadcast or unicast on the network that sent the original request.
The DHCP Relay Agent listens for DHCP requests on all interfaces unless the interfaces are specified in /etc/sysconfig/dhcrelay with the INTERFACES directive.
To start the DHCP Relay Agent, use the command service dhcrelay start.

10.3. Configuring a DHCP Client

The first step for configuring a DHCP client is to make sure the kernel recognizes the network interface card. Most cards are recognized during the installation process and the system is configured to use the correct kernel module for the card. If a card is added after installation, Kudzu [7] will recognize it and prompt you for the proper kernel module (Be sure to check the Hardware Compatibility List at http://hardware.redhat.com/hcl/). If either the installation program or kudzu does not recognize the network card, you can load the correct kernel module (refer to Chapter 30, General Parameters and Modules for details).
To configure a DHCP client manually, modify the /etc/sysconfig/network file to enable networking and the configuration file for each network device in the /etc/sysconfig/network-scripts directory. In this directory, each device should have a configuration file named ifcfg-eth0, where eth0 is the network device name.
The /etc/sysconfig/network file should contain the following line:
NETWORKING=yes
The NETWORKING variable must be set to yes if you want networking to start at boot time.
The /etc/sysconfig/network-scripts/ifcfg-eth0 file should contain the following lines:
DEVICE=eth0
BOOTPROTO=dhcp
ONBOOT=yes

A configuration file is needed for each device to be configured to use DHCP.
Other options for the network script includes:
  • DHCP_HOSTNAME — Only use this option if the DHCP server requires the client to specify a hostname before receiving an IP address. (The DHCP server daemon in Fedora does not support this feature.)
  • PEERDNS=<answer> , where <answer> is one of the following:
    • yes — Modify /etc/resolv.conf with information from the server. If using DHCP, then yes is the default.
    • no — Do not modify /etc/resolv.conf.
  • SRCADDR=<address> , where <address> is the specified source IP address for outgoing packets.
  • USERCTL=<answer> , where <answer> is one of the following:
    • yes — Non-root users are allowed to control this device.
    • no — Non-root users are not allowed to control this device.
If you prefer using a graphical interface, refer to Chapter 5, Network Configuration for instructions on using the Network Administration Tool to configure a network interface to use DHCP.

Tip

For advanced configurations of client DHCP options such as protocol timing, lease requirements and requests, dynamic DNS support, aliases, as well as a wide variety of values to override, prepend, or append to client-side configurations, refer to the dhclient and dhclient.conf man pages.

10.4. Configuring a Multihomed DHCP Server

A multihomed DHCP server serves multiple networks, that is, multiple subnets. The examples in these sections detail how to configure a DHCP server to serve multiple networks, select which network interfaces to listen on, and how to define network settings for systems that move networks.
Before making any changes, back up the existing /etc/sysconfig/dhcpd and /etc/dhcpd.conf files.
The DHCP daemon listens on all network interfaces unless otherwise specified. Use the /etc/sysconfig/dhcpd file to specify which network interfaces the DHCP daemon listens on. The following /etc/sysconfig/dhcpd example specifies that the DHCP daemon listens on the eth0 and eth1 interfaces:
DHCPDARGS="eth0 eth1";

If a system has three network interfaces cards -- eth0, eth1, and eth2 -- and it is only desired that the DHCP daemon listens on eth0, then only specify eth0 in /etc/sysconfig/dhcpd:
DHCPDARGS="eth0";

The following is a basic /etc/dhcpd.conf file, for a server that has two network interfaces, eth0 in a 10.0.0.0/24 network, and eth1 in a 172.16.0.0/24 network. Multiple subnet declarations allow different settings to be defined for multiple networks:
ddns-update-style interim;
default-lease-time 600;
max-lease-time 7200;

subnet 10.0.0.0 netmask 255.255.255.0 {
	option subnet-mask 255.255.255.0;
	option routers 10.0.0.1;
	range 10.0.0.5 10.0.0.15;
}

subnet 172.16.0.0 netmask 255.255.255.0 {
	option subnet-mask 255.255.255.0;
	option routers 172.16.0.1;
	range 172.16.0.5 172.16.0.15;

}

subnet 10.0.0.0 netmask 255.255.255.0
A subnet declaration is required for every network your DHCP server is serving. Multiple subnets require multiple subnet declarations. If the DHCP server does not have a network interface in a range of a subnet declaration, the DHCP server does not serve that network.
If there is only one subnet declaration, and no network interfaces are in the range of that subnet, the DHCP daemon fails to start, and an error such as the following is logged to /var/log/messages:
dhcpd: No subnet declaration for eth0 (0.0.0.0).
dhcpd: ** Ignoring requests on eth0.  If this is not what
dhcpd:    you want, please write a subnet declaration
dhcpd:    in your dhcpd.conf file for the network segment
dhcpd:    to which interface eth1 is attached. **
dhcpd:
dhcpd:
dhcpd: Not configured to listen on any interfaces!

option subnet-mask 255.255.255.0;
The option subnet-mask option defines a subnet mask, and overrides the netmask value in the subnet declaration. In simple cases, the subnet and netmask values are the same.
option routers 10.0.0.1;
The option routers option defines the default gateway for the subnet. This is required for systems to reach internal networks on a different subnet, as well as external networks.
range 10.0.0.5 10.0.0.15;
The range option specifies the pool of available IP addresses. Systems are assigned an address from the range of specified IP addresses.
For further information, refer to the dhcpd.conf(5) man page.

Alias Interfaces

Alias interfaces are not supported by DHCP. If an alias interface is the only interface, in the only subnet specified in /etc/dhcpd.conf, the DHCP daemon fails to start.

10.4.1. Host Configuration

Before making any changes, back up the existing /etc/sysconfig/dhcpd and /etc/dhcpd.conf files.
Configuring a single system for multiple networks
The following /etc/dhcpd.conf example creates two subnets, and configures an IP address for the same system, depending on which network it connects to:
ddns-update-style interim;
default-lease-time 600;
max-lease-time 7200;

subnet 10.0.0.0 netmask 255.255.255.0 {
	option subnet-mask 255.255.255.0;
	option routers 10.0.0.1;
	range 10.0.0.5 10.0.0.15;
}

subnet 172.16.0.0 netmask 255.255.255.0 {
	option subnet-mask 255.255.255.0;
	option routers 172.16.0.1;
	range 172.16.0.5 172.16.0.15;

}

host example0 {
	hardware ethernet 00:1A:6B:6A:2E:0B;
	fixed-address 10.0.0.20;
}

host example1 {
	hardware ethernet 00:1A:6B:6A:2E:0B;
	fixed-address 172.16.0.20;
}

host example0
The host declaration defines specific parameters for a single system, such as an IP address. To configure specific parameters for multiple hosts, use multiple host declarations.
Most DHCP clients ignore the name in host declarations, and as such, this name can anything, as long as it is unique to other host declarations. To configure the same system for multiple networks, use a different name for each host declaration, otherwise the DHCP daemon fails to start. Systems are identified by the hardware ethernet option, not the name in the host declaration.
hardware ethernet 00:1A:6B:6A:2E:0B;
The hardware ethernet option identifies the system. To find this address, run the ifconfig command on the desired system, and look for the HWaddr address.
fixed-address 10.0.0.20;
The fixed-address option assigns a valid IP address to the system specified by the hardware ethernet option. This address must be outside the IP address pool specified with the range option.
If option statements do not end with a semicolon, the DHCP daemon fails to start, and an error such as the following is logged to /var/log/messages:
/etc/dhcpd.conf line 20: semicolon expected.
dhcpd: }
dhcpd: ^
dhcpd: /etc/dhcpd.conf line 38: unexpected end of file
dhcpd:
dhcpd: ^
dhcpd: Configuration file errors encountered -- exiting

Configuring systems with multiple network interfaces
The following host declarations configure a single system, that has multiple network interfaces, so that each interface receives the same IP address. This configuration will not work if both network interfaces are connected to the same network at the same time:
host interface0 {
	hardware ethernet 00:1a:6b:6a:2e:0b;
	fixed-address 10.0.0.18;
}

host interface1 {
	hardware ethernet 00:1A:6B:6A:27:3A;
	fixed-address 10.0.0.18;
}

For this example, interface0 is the first network interface, and interface1 is the second interface. The different hardware ethernet options identify each interface.
If such a system connects to another network, add more host declarations, remembering to:
  • assign a valid fixed-address for the network the host is connecting to.
  • make the name in the host declaration unique.
When a name given in a host declaration is not unique, the DHCP daemon fails to start, and an error such as the following is logged to /var/log/messages:
dhcpd: /etc/dhcpd.conf line 31: host interface0: already exists
dhcpd: }
dhcpd: ^
dhcpd: Configuration file errors encountered -- exiting

This error was caused by having multiple host interface0 declarations defined in /etc/dhcpd.conf.

10.5. Additional Resources

For additional configuration options, refer to the following resources.

10.5.1. Installed Documentation

  • dhcpd man page — Describes how the DHCP daemon works.
  • dhcpd.conf man page — Explains how to configure the DHCP configuration file; includes some examples.
  • dhcpd.leases man page — Explains how to configure the DHCP leases file; includes some examples.
  • dhcp-options man page — Explains the syntax for declaring DHCP options in dhcpd.conf; includes some examples.
  • dhcrelay man page — Explains the DHCP Relay Agent and its configuration options.
  • /usr/share/doc/dhcp-<version>/ — Contains sample files, README files, and release notes for current versions of the DHCP service.


[7] Kudzu is a hardware probing tool run at system boot time to determine what hardware has been added or removed from the system.

Chapter 11. Apache HTTP Server

The Apache HTTP Server is a robust, commercial-grade open source Web server developed by the Apache Software Foundation (http://www.apache.org/). Fedora 12 includes the Apache HTTP Server 2.2 as well as a number of server modules designed to enhance its functionality.
The default configuration file installed with the Apache HTTP Server works without alteration for most situations. This chapter outlines many of the directives found within its configuration file (/etc/httpd/conf/httpd.conf) to aid those who require a custom configuration or need to convert a configuration file from the older Apache HTTP Server 1.3 format.

Warning

If using the graphical HTTP Configuration Tool (system-config-httpd ), do not hand edit the Apache HTTP Server's configuration file as the HTTP Configuration Tool regenerates this file whenever it is used.

11.1. Apache HTTP Server 2.2

There are important differences between the Apache HTTP Server 2.2 and version 2.0.
This section reviews some of the features of Apache HTTP Server 2.2 and outlines important changes. If you are upgrading from version 1.3, you should also read the instructions on migrating from version 1.3 to version 2.0. For instructions on migrating a version 1.3 configuration file to the 2.0 format, refer to Section 11.2.2, “Migrating Apache HTTP Server 1.3 Configuration Files to 2.0”.

11.1.1. Features of Apache HTTP Server 2.2

Apache HTTP Server 2.2 features the following improvements over version 2.0 :
  • Improved caching modules (mod_cache, mod_disk_cache, mod_mem_cache).
  • A new structure for authentication and authorization support, replacing the authentication modules provided in previous versions.
  • Support for proxy load balancing (mod_proxy_balancer)
  • support for handling large files (namely, greater than 2GB) on 32-bit platforms
The following changes have been made to the default httpd configuration:
  • The mod_cern_meta and mod_asis modules are no longer loaded by default.
  • The mod_ext_filter module is now loaded by default.
If upgrading from a previous release of Fedora, the httpd configuration will need to be updated for httpd 2.2. For more information, refer to http://httpd.apache.org/docs/2.2/upgrading.html

11.2. Migrating Apache HTTP Server Configuration Files

11.2.1. Migrating Apache HTTP Server 2.0 Configuration Files

This section outlines migration from version 2.0 to 2.2. If you are migrating from version 1.3, please refer to Section 11.2.2, “Migrating Apache HTTP Server 1.3 Configuration Files to 2.0”.
  • Configuration files and startup scripts from version 2.0 need minor adjustments particularly in module names which may have changed. Third party modules which worked in version 2.0 can also work in version 2.2 but need to be recompiled before you load them. Key modules that need to be noted are authentication and authorization modules. For each of the modules which has been renamed the LoadModule line will need to be updated.
  • The mod_userdir module will only act on requests if you provide a UserDir directive indicating a directory name. If you wish to maintain the procedures used in version 2.0, add the directive UserDir public_html in your configuration file.
  • To enable SSL, edit the httpd.conf file adding the necessary mod_ssl directives. Use apachectl start as apachectl startssl is unavailable in version 2.2. You can view an example of SSL configuration for httpd in conf/extra/httpd-ssl.conf.
  • To test your configuration it is advisable to use service httpd configtest which will detect configuration errors.
More information on upgrading from version 2.0 to 2.2 can be found on http://httpd.apache.org/docs/2.2/upgrading.html.

11.2.2. Migrating Apache HTTP Server 1.3 Configuration Files to 2.0

This section details migrating an Apache HTTP Server 1.3 configuration file to be utilized by Apache HTTP Server 2.0.
If the /etc/httpd/conf/httpd.conf file is a modified version of the newly installed default and a saved a copy of the original configuration file is available, it may be easiest to invoke the diff command, as in the following example (logged in as root):
diff -u httpd.conf.orig httpd.conf | less

This command highlights any modifications made. If a copy of the original file is not available, extract it from an RPM package using the rpm2cpio and cpio commands, as in the following example:
rpm2cpio apache-<version-number>.i386.rpm | cpio -i --make

In the above command, replace <version-number> with the version number for the apache package.
Finally, it is useful to know that the Apache HTTP Server has a testing mode to check for configuration errors. To use access it, type the following command:
apachectl configtest

11.2.2.1. Global Environment Configuration

The global environment section of the configuration file contains directives which affect the overall operation of the Apache HTTP Server, such as the number of concurrent requests it can handle and the locations of the various files. This section requires a large number of changes and should be based on the Apache HTTP Server 2.0 configuration file, while migrating the old settings into it.
11.2.2.1.1. Interface and Port Binding
The BindAddress and Port directives no longer exist; their functionality is now provided by a more flexible Listen directive.
If Port 80 was set in the 1.3 version configuration file, change it to Listen 80 in the 2.0 configuration file. If Port was set to some value other than 80, then append the port number to the contents of the ServerName directive.
For example, the following is a sample Apache HTTP Server 1.3 directive:
Port 123 ServerName www.example.com

To migrate this setting to Apache HTTP Server 2.0, use the following structure:
Listen 123 ServerName www.example.com:123 

For more on this topic, refer to the following documentation on the Apache Software Foundation's website:
11.2.2.1.2. Server-Pool Size Regulation
When the Apache HTTP Server accepts requests, it dispatches child processes or threads to handle them. This group of child processes or threads is known as a server-pool. Under Apache HTTP Server 2.0, the responsibility for creating and maintaining these server-pools has been abstracted to a group of modules called Multi-Processing Modules (MPMs). Unlike other modules, only one module from the MPM group can be loaded by the Apache HTTP Server. There are three MPM modules that ship with 2.0: prefork, worker, and perchild. Currently only the prefork and worker MPMs are available, although the perchild MPM may be available at a later date.
The original Apache HTTP Server 1.3 behavior has been moved into the prefork MPM. The prefork MPM accepts the same directives as Apache HTTP Server 1.3, so the following directives may be migrated directly:
  • StartServers
  • MinSpareServers
  • MaxSpareServers
  • MaxClients
  • MaxRequestsPerChild
The worker MPM implements a multi-process, multi-threaded server providing greater scalability. When using this MPM, requests are handled by threads, conserving system resources and allowing large numbers of requests to be served efficiently. Although some of the directives accepted by the worker MPM are the same as those accepted by the prefork MPM, the values for those directives should not be transfered directly from an Apache HTTP Server 1.3 installation. It is best to instead use the default values as a guide, then experiment to determine what values work best.

Important

To use the worker MPM, create the file /etc/sysconfig/httpd and add the following directive:
HTTPD=/usr/sbin/httpd.worker

For more on the topic of MPMs, refer to the following documentation on the Apache Software Foundation's website:
11.2.2.1.3. Dynamic Shared Object (DSO) Support
There are many changes required here, and it is highly recommended that anyone trying to modify an Apache HTTP Server 1.3 configuration to suit version 2.0 (as opposed to migrating the changes into the version 2.0 configuration) copy this section from the stock Apache HTTP Server 2.0 configuration file.
Those who do not want to copy the section from the stock Apache HTTP Server 2.0 configuration should note the following:
  • The AddModule and ClearModuleList directives no longer exist. These directives where used to ensure that modules could be enabled in the correct order. The Apache HTTP Server 2.0 API allows modules to specify their ordering, eliminating the need for these two directives.
  • The order of the LoadModule lines are no longer relevant in most cases.
  • Many modules have been added, removed, renamed, split up, or incorporated into others.
  • LoadModule lines for modules packaged in their own RPMs (mod_ssl, php, mod_perl, and the like) are no longer necessary as they can be found in their relevant files within the /etc/httpd/conf.d/ directory.
  • The various HAVE_XXX definitions are no longer defined.

Important

If modifying the original file, note that it is of paramount importance that the httpd.conf contains the following directive:
Include conf.d/*.conf

Omission of this directive results in the failure of all modules packaged in their own RPMs (such as mod_perl, php, and mod_ssl).
11.2.2.1.4. Other Global Environment Changes
The following directives have been removed from Apache HTTP Server 2.0's configuration:
  • ServerType — The Apache HTTP Server can only be run as ServerType standalone making this directive irrelevant.
  • AccessConfig and ResourceConfig — These directives have been removed as they mirror the functionality of the Include directive. If the AccessConfig and ResourceConfig directives are set, replace them with Include directives.
    To ensure that the files are read in the order implied by the older directives, the Include directives should be placed at the end of the httpd.conf, with the one corresponding to ResourceConfig preceding the one corresponding to AccessConfig. If using the default values, include them explicitly as conf/srm.conf and conf/access.conf files.

11.2.2.2. Main Server Configuration

The main server configuration section of the configuration file sets up the main server, which responds to any requests that are not handled by a virtual host defined within a <VirtualHost> container. Values here also provide defaults for any <VirtualHost> containers defined.
The directives used in this section have changed little between Apache HTTP Server 1.3 and version 2.0. If the main server configuration is heavily customized, it may be easier to modify the existing configuration file to suit Apache HTTP Server 2.0. Users with only lightly customized main server sections should migrate their changes into the default 2.0 configuration.
11.2.2.2.1.  UserDir Mapping
The UserDir directive is used to enable URLs such as http://example.com/~bob/ to map to a subdirectory within the home directory of the user bob, such as /home/bob/public_html/. A side-effect of this feature allows a potential attacker to determine whether a given username is present on the system. For this reason, the default configuration for Apache HTTP Server 2.0 disables this directive.
To enable UserDir mapping, change the directive in httpd.conf from:
UserDir disable

to the following:
UserDir public_html 

For more on this topic, refer to the following documentation on the Apache Software Foundation's website:
11.2.2.2.2. Logging
The following logging directives have been removed:
  • AgentLog
  • RefererLog
  • RefererIgnore
However, agent and referrer logs are still available using the CustomLog and LogFormat directives.
For more on this topic, refer to the following documentation on the Apache Software Foundation's website:
11.2.2.2.3. Directory Indexing
The deprecated FancyIndexing directive has now been removed. The same functionality is available through the FancyIndexing option within the IndexOptions directive.
The VersionSort option to the IndexOptions directive causes files containing version numbers to be sorted in a more natural way. For example, httpd-2.0.6.tar appears before httpd-2.0.36.tar in a directory index page.
The defaults for the ReadmeName and HeaderName directives have changed from README and HEADER to README.html and HEADER.html.
For more on this topic, refer to the following documentation on the Apache Software Foundation's website:
11.2.2.2.4. Content Negotiation
The CacheNegotiatedDocs directive now takes the argument on or off. Existing instances of CacheNegotiatedDocs should be replaced with CacheNegotiatedDocs on.
For more on this topic, refer to the following documentation on the Apache Software Foundation's website:
11.2.2.2.5. Error Documents
To use a hard-coded message with the ErrorDocument directive, the message should be enclosed in a pair of double quotation marks ", rather than just preceded by a double quotation mark as required in Apache HTTP Server 1.3.
For example, the following is a sample Apache HTTP Server 1.3 directive:
ErrorDocument 404 "The document was not found

To migrate an ErrorDocument setting to Apache HTTP Server 2.0, use the following structure:
ErrorDocument 404 "The document was not found"

Note the trailing double quote in the previous ErrorDocument directive example.
For more on this topic, refer to the following documentation on the Apache Software Foundation's website:

11.2.2.3. Virtual Host Configuration

The contents of all <VirtualHost> containers should be migrated in the same way as the main server section as described in Section 11.2.2.2, “Main Server Configuration”.

Important

Note that SSL/TLS virtual host configuration has been moved out of the main server configuration file and into /etc/httpd/conf.d/ssl.conf.

11.2.2.4. Modules and Apache HTTP Server 2.0

In Apache HTTP Server 2.0, the module system has been changed to allow modules to be chained together or combined in new and interesting ways. Common Gateway Interface (CGI) scripts, for example, can generate server-parsed HTML documents which can then be processed by mod_include. This opens up a tremendous number of possibilities with regards to how modules can be combined to achieve a specific goal.
The way this works is that each request is served by exactly one handler module followed by zero or more filter modules.
Under Apache HTTP Server 1.3, for example, a Perl script would be handled in its entirety by the Perl module (mod_perl). Under Apache HTTP Server 2.0, the request is initially handled by the core module — which serves static files — and is then filtered by mod_perl.
Exactly how to use this, and all other new features of Apache HTTP Server 2.0, is beyond the scope of this document; however, the change has ramifications if the PATH_INFO directive is used for a document which is handled by a module that is now implemented as a filter, as each contains trailing path information after the true file name. The core module, which initially handles the request, does not by default understand PATH_INFO and returns 404 Not Found errors for requests that contain such information. As an alternative, use the AcceptPathInfo directive to coerce the core module into accepting requests with PATH_INFO.
The following is an example of this directive:
AcceptPathInfo on

For more on this topic, refer to the following documentation on the Apache Software Foundation's website:
11.2.2.4.1. The suexec Module
In Apache HTTP Server 2.0, the mod_suexec module uses the SuexecUserGroup directive, rather than the User and Group directives, which is used for configuring virtual hosts. The User and Group directives can still be used in general, but are deprecated for configuring virtual hosts.
For example, the following is a sample Apache HTTP Server 1.3 directive:
<VirtualHost vhost.example.com:80> User someone Group somegroup </VirtualHost>

To migrate this setting to Apache HTTP Server 2.0, use the following structure:
<VirtualHost vhost.example.com:80> SuexecUserGroup someone somegroup </VirtualHost>

11.2.2.4.2. The mod_ssl Module
The configuration for mod_ssl has been moved from the httpd.conf file into the /etc/httpd/conf.d/ssl.conf file. For this file to be loaded, and for mod_ssl to work, the statement Include conf.d/*.conf must be in the httpd.conf file as described in Section 11.2.2.1.3, “Dynamic Shared Object (DSO) Support”.
ServerName directives in SSL virtual hosts must explicitly specify the port number.
For example, the following is a sample Apache HTTP Server 1.3 directive:
<VirtualHost _default_:443> # General setup for the virtual host ServerName ssl.example.name ... </VirtualHost>

To migrate this setting to Apache HTTP Server 2.0, use the following structure:
<VirtualHost _default_:443> # General setup for the virtual host ServerName ssl.host.name:443 ... </VirtualHost>

It is also important to note that both the SSLLog and SSLLogLevel directives have been removed. The mod_ssl module now obeys the ErrorLog and LogLevel directives. Refer to ErrorLog and LogLevel for more information about these directives.
For more on this topic, refer to the following documentation on the Apache Software Foundation's website:
11.2.2.4.3. The mod_proxy Module
Proxy access control statements are now placed inside a <Proxy> block rather than a <Directory proxy:>.
The caching functionality of the old mod_proxy has been split out into the following three modules:
  • mod_cache
  • mod_disk_cache
  • mod_mem_cache
These generally use directives similar to the older versions of the mod_proxy module, but it is advisable to verify each directive before migrating any cache settings.
For more on this topic, refer to the following documentation on the Apache Software Foundation's website:
11.2.2.4.4. The mod_include Module
The mod_include module is now implemented as a filter and is therefore enabled differently. Refer to Section 11.2.2.4, “Modules and Apache HTTP Server 2.0” for more about filters.
For example, the following is a sample Apache HTTP Server 1.3 directive:
AddType text/html .shtml AddHandler server-parsed .shtml

To migrate this setting to Apache HTTP Server 2.0, use the following structure:
AddType text/html .shtml AddOutputFilter INCLUDES .shtml

Note that the Options +Includes directive is still required for the <Directory> container or in a .htaccess file.
For more on this topic, refer to the following documentation on the Apache Software Foundation's website:
11.2.2.4.5. The mod_auth_dbm and mod_auth_db Modules
Apache HTTP Server 1.3 supported two authentication modules, mod_auth_db and mod_auth_dbm, which used Berkeley Databases and DBM databases respectively. These modules have been combined into a single module named mod_auth_dbm in Apache HTTP Server 2.0, which can access several different database formats. To migrate from mod_auth_db, configuration files should be adjusted by replacing AuthDBUserFile and AuthDBGroupFile with the mod_auth_dbm equivalents, AuthDBMUserFile and AuthDBMGroupFile. Also, the directive AuthDBMType DB must be added to indicate the type of database file in use.
The following example shows a sample mod_auth_db configuration for Apache HTTP Server 1.3:
<Location /private/> AuthType Basic AuthName "My Private Files" AuthDBUserFile /var/www/authdb require valid-user </Location>

To migrate this setting to version 2.0 of Apache HTTP Server, use the following structure:
<Location /private/> AuthType Basic AuthName "My Private Files" AuthDBMUserFile /var/www/authdb AuthDBMType DB require valid-user </Location>

Note that the AuthDBMUserFile directive can also be used in .htaccess files.
The dbmmanage Perl script, used to manipulate username and password databases, has been replaced by htdbm in Apache HTTP Server 2.0. The htdbm program offers equivalent functionality and, like mod_auth_dbm, can operate a variety of database formats; the -T option can be used on the command line to specify the format to use.
Table 11.1, “Migrating from dbmmanage to htdbm shows how to migrate from a DBM-format database to htdbm format using dbmmanage.
Action dbmmanage command (1.3) Equivalent htdbm command (2.0)
Add user to database (using given password) dbmmanage authdb add username password htdbm -b -TDB authdb username password
Add user to database (prompts for password) dbmmanage authdb adduser username htdbm -TDB authdb username
Remove user from database dbmmanage authdb delete username htdbm -x -TDB authdb username
List users in database dbmmanage authdb view htdbm -l -TDB authdb
Verify a password dbmmanage authdb check username htdbm -v -TDB authdb username
Table 11.1. Migrating from dbmmanage to htdbm

The -m and -s options work with both dbmmanage and htdbm, enabling the use of the MD5 or SHA1 algorithms for hashing passwords, respectively.
When creating a new database with htdbm, the -c option must be used.
For more on this topic, refer to the following documentation on the Apache Software Foundation's website:
11.2.2.4.6. The mod_perl Module
The configuration for mod_perl has been moved from httpd.conf into the file /etc/httpd/conf.d/perl.conf. For this file to be loaded, and hence for mod_perl to work, the statement Include conf.d/*.conf must be included in httpd.conf as described in Section 11.2.2.1.3, “Dynamic Shared Object (DSO) Support”.
Occurrences of Apache:: in httpd.conf must be replaced with ModPerl::. Additionally, the manner in which handlers are registered has been changed.
This is a sample Apache HTTP Server 1.3 mod_perl configuration:
<Directory /var/www/perl> SetHandler perl-script PerlHandler Apache::Registry Options +ExecCGI </Directory>

This is the equivalent mod_perl for Apache HTTP Server 2.0:
<Directory /var/www/perl> SetHandler perl-script PerlResponseHandler ModPerl::Registry Options +ExecCGI </Directory>

Most modules for mod_perl 1.x should work without modification with mod_perl 2.x. XS modules require recompilation and may require minor Makefile modifications.
11.2.2.4.7. The mod_python Module
Configuration for mod_python has moved from httpd.conf to the /etc/httpd/conf.d/python.conf file. For this file to be loaded, and hence for mod_python to work, the statement Include conf.d/*.conf must be in httpd.conf as described in Section 11.2.2.1.3, “Dynamic Shared Object (DSO) Support”.
11.2.2.4.8. PHP
The configuration for PHP has been moved from httpd.conf into the file /etc/httpd/conf.d/php.conf. For this file to be loaded, the statement Include conf.d/*.conf must be in httpd.conf as described in Section 11.2.2.1.3, “Dynamic Shared Object (DSO) Support”.

Note

Any PHP configuration directives used in Apache HTTP Server 1.3 are now fully compatible, when migrating to Apache HTTP Server 2.0 on Fedora 12.
In PHP version 4.2.0 and later the default set of predefined variables which are available in the global scope has changed. Individual input and server variables are, by default, no longer placed directly into the global scope. This change may cause scripts to break. Revert to the old behavior by setting register_globals to On in the file /etc/php.ini.
For more on this topic, refer to the following URL for details concerning the global scope changes:
11.2.2.4.9. The mod_authz_ldap Module
Fedora ships with the mod_authz_ldap module for the Apache HTTP Server. This module uses the short form of the distinguished name for a subject and the issuer of the client SSL certificate to determine the distinguished name of the user within an LDAP directory. It is also capable of authorizing users based on attributes of that user's LDAP directory entry, determining access to assets based on the user and group privileges of the asset, and denying access for users with expired passwords. The mod_ssl module is required when using the mod_authz_ldap module.

Important

The mod_authz_ldap module does not authenticate a user to an LDAP directory using an encrypted password hash. This functionality is provided by the experimental mod_auth_ldap module. Refer to the mod_auth_ldap module documentation online at http://httpd.apache.org/docs-2.0/mod/mod_auth_ldap.html for details on the status of this module.
The /etc/httpd/conf.d/authz_ldap.conf file configures the mod_authz_ldap module.
Refer to /usr/share/doc/mod_authz_ldap-<version>/index.html (replacing <version> with the version number of the package) or http://authzldap.othello.ch/ for more information on configuring the mod_authz_ldap third party module.

11.3. Starting and Stopping httpd

After installing the httpd package, review the Apache HTTP Server's documentation available online at http://httpd.apache.org/docs/2.2/.
The httpd RPM installs the /etc/init.d/httpd script, which can be accessed using the /sbin/service command.
Starting httpd using the apachectl control script sets the environmental variables in /etc/sysconfig/httpd and starts httpd. You can also set the environment variables using the init script.
To start the server using the apachectl control script as root type:
apachectl start

You can also start httpd using /sbin/service httpd start. This starts httpd but does not set the environment variables. If you are using the default Listen directive in httpd.conf, which is port 80, you will need to have root privileges to start the apache server.
To stop the server, as root type:
apachectl stop

You can also stop httpd using /sbin/service httpd stop. The restart option is a shorthand way of stopping and then starting the Apache HTTP Server.
You can restart the server as root by typing:
apachectl restart
or:
/sbin/service httpd restart

Apache will display a message on the console or in the ErrorLog if it encounters an error while starting.
By default, the httpd service does not start automatically at boot time. If you would wish to have Apache startup at boot time, you will need to add a call to apachectl in your startup files within the rc.N directory. A typical file used is rc.local. As this starts Apache as root, it is recommended to properly configure your security and authentication before adding this call.
You can also configure the httpd service to start up at boot time, using an initscript utility, such as /sbin/chkconfig, /usr/sbin/ntsysv, or the Services Configuration Tool program.
You can also display the status of your httpd server by typing:
apachectl status

The status module mod_status however needs to be enabled in your httpd.conf configuration file for this to work. For more details on mod_status can be found on http://httpd.apache.org/docs/2.2/mod/mod_status.html.

Note

If running the Apache HTTP Server as a secure server, the secure server's password is required after the machine boots when using an encrypted private SSL key.
You can find more information on http://httpd.apache.org/docs/2.2/ssl

11.4. Apache HTTP Server Configuration

The HTTP Configuration Tool allows you to configure the /etc/httpd/conf/httpd.conf configuration file for the Apache HTTP Server. It does not use the old srm.conf or access.conf configuration files; leave them empty. Through the graphical interface, you can configure directives such as virtual hosts, logging attributes, and maximum number of connections. To start the HTTD Configuration Tool, click on System > Administration > Server Settings > HTTP.
Only modules provided with Fedora can be configured with the HTTP Configuration Tool. If additional modules are installed, they can not be configured using this tool.

Caution

Do not edit the /etc/httpd/conf/httpd.conf configuration file by hand if you wish to use this tool. The HTTP Configuration Tool generates this file after you save your changes and exit the program. If you want to add additional modules or configuration options that are not available in HTTP Configuration Tool, you cannot use this tool.
The general steps for configuring the Apache HTTP Server using the HTTP Configuration Tool are as follows:
  1. Configure the basic settings under the Main tab.
  2. Click on the Virtual Hosts tab and configure the default settings.
  3. Under the Virtual Hosts tab, configure the Default Virtual Host.
  4. To serve more than one URL or virtual host, add any additional virtual hosts.
  5. Configure the server settings under the Server tab.
  6. Configure the connections settings under the Performance Tuning tab.
  7. Copy all necessary files to the DocumentRoot and cgi-bin directories.
  8. Exit the application and select to save your settings.

11.4.1. Basic Settings

Use the Main tab to configure the basic server settings.
Basic Settings
Basic Settings
Figure 11.1. Basic Settings

Enter a fully qualified domain name that you have the right to use in the Server Name text area. This option corresponds to the ServerName directive in httpd.conf. The ServerName directive sets the hostname of the Web server. It is used when creating redirection URLs. If you do not define a server name, the Web server attempts to resolve it from the IP address of the system. The server name does not have to be the domain name resolved from the IP address of the server. For example, you might set the server name to www.example.com while the server's real DNS name is foo.example.com.
Enter the email address of the person who maintains the Web server in the Webmaster email address text area. This option corresponds to the ServerAdmin directive in httpd.conf. If you configure the server's error pages to contain an email address, this email address is used so that users can report a problem to the server's administrator. The default value is root@localhost.
Use the Available Addresses area to define the ports on which the server accepts incoming requests. This option corresponds to the Listen directive in httpd.conf. By default, Red Hat configures the Apache HTTP Server to listen to port 80 for non-secure Web communications.
Click the Add button to define additional ports on which to accept requests. A window as shown in Figure 11.2, “Available Addresses” appears. Either choose the Listen to all addresses option to listen to all IP addresses on the defined port or specify a particular IP address over which the server accepts connections in the Address field. Only specify one IP address per port number. To specify more than one IP address with the same port number, create an entry for each IP address. If at all possible, use an IP address instead of a domain name to prevent a DNS lookup failure. Refer to http://httpd.apache.org/docs/2.2/dns-caveats.html for more information about Issues Regarding DNS and Apache.
Entering an asterisk (*) in the Address field is the same as choosing Listen to all addresses. Clicking the Edit button in the Available Addresses frame shows the same window as the Add button except with the fields populated for the selected entry. To delete an entry, select it and click the Delete button.

Tip

If you set the server to listen to a port under 1024, you must be root to start it. For port 1024 and above, httpd can be started as a regular user.
Available Addresses
Available Addresses
Figure 11.2. Available Addresses

11.4.2. Default Settings

After defining the Server Name, Webmaster email address, and Available Addresses, click the Virtual Hosts tab. The figure below illustrates the Virtual Hosts tab.
Virtual Hosts Tab
Virtual Hosts Tab
Figure 11.3. Virtual Hosts Tab

Clicking on Edit will display the Virtual Host Properties window from which you can set your preferred settings. To add new settings, click on the Add button which will also display the Virtual Host Properties window. Clicking on the Edit Default Settings button, displays the Virtual Host Properties window without the General Options tab.
In the General Options tab, you can change the hostname, the document root directory and also set the webmaster's email address. In the Host information, you can set the Virtual Host's IP Address and Host Name. The figure below illustrates the General Options tab.
General Options
General Options
Figure 11.4. General Options

If you add a virtual host, the settings you configure for the virtual host take precedence for that virtual host. For a directive not defined within the virtual host settings, the default value is used.

11.4.2.1. Site Configuration

The figure below illustrates the Page Optionstab from which you can configure the Directory Page Search List and Error Pages. If you are unsure of these settings, do not modify them.
Site Configuration
Site Configuration
Figure 11.5. Site Configuration

The entries listed in the Directory Page Search List define the DirectoryIndex directive. The DirectoryIndex is the default page served by the server when a user requests an index of a directory by specifying a forward slash (/) at the end of the directory name.
For example, when a user requests the page http://www.example.com/this_directory/, they are going to get either the DirectoryIndex page, if it exists, or a server-generated directory list. The server tries to find one of the files listed in the DirectoryIndex directive and returns the first one it finds. If it does not find any of these files and if Options Indexes is set for that directory, the server generates and returns a list, in HTML format, of the subdirectories and files in the directory.
Use the Error Code section to configure Apache HTTP Server to redirect the client to a local or external URL in the event of a problem or error. This option corresponds to the ErrorDocument directive. If a problem or error occurs when a client tries to connect to the Apache HTTP Server, the default action is to display the short error message shown in the Error Code column. To override this default configuration, select the error code and click the Edit button. Choose Default to display the default short error message. Choose URL to redirect the client to an external URL and enter a complete URL, including the http://, in the Location field. Choose File to redirect the client to an internal URL and enter a file location under the document root for the Web server. The location must begin the a slash (/) and be relative to the Document Root.
For example, to redirect a 404 Not Found error code to a webpage that you created in a file called 404.html, copy 404.html to DocumentRoot/../error/404.html. In this case, DocumentRoot is the Document Root directory that you have defined (the default is /var/www/html/). If the Document Root is left as the default location, the file should be copied to /var/www/error/404.html. Then, choose File as the Behavior for 404 - Not Found error code and enter /error/404.html as the Location.
From the Default Error Page Footer menu, you can choose one of the following options:
  • Show footer with email address — Display the default footer at the bottom of all error pages along with the email address of the website maintainer specified by the ServerAdmin directive.
  • Show footer — Display just the default footer at the bottom of error pages.
  • No footer — Do not display a footer at the bottom of error pages.

11.4.2.2. SSL Support

The mod_ssl enables encryption of the HTTP protocol over SSL. SSL (Secure Sockets Layer) protocol is used for communication and encryption over TCP/IP networks. The SSL tab enables you to configure SSL for your server. To configure SSL you need to provide the path to your:
  • Certificate file - equivalent to using the SSLCertificateFile directive which points the path to the PEM (Privacy Enhanced Mail)-encoded server certificate file.
  • Key file - equivalent to using the SSLCertificateKeyFile directive which points the path to the PEM-encoded server private key file.
  • Certificate chain file - equivalent to using the SSLCertificateChainFile directive which points the path to the certificate file containing all the server's chain of certificates.
  • Certificate authority file - is an encrypted file used to confirm the authenticity or identity of parties communicating with the server.
You can find out more about configuration directives for SSL on http://httpd.apache.org/docs/2.2/mod/directives.html#S. You also need to determine which SSL options to enable. These are equivalent to using the SSLOptions with the following options:
  • FakeBasicAuth - enables standard authentication methods used by Apache. This means that the Client X509 certificate's Subject Distinguished Name (DN) is translated into a basic HTTP username.
  • ExportCertData - creates CGI environment variables in SSL_SERVER_CERT, SSL_CLIENT_CERT and SSL_CLIENT_CERT_CHAIN_n where n is a number 0,1,2,3,4... These files are used for more certificate checks by CGI scripts.
  • CompatEnvVars - enables backward compatibility for Apache SSL by adding CGI environment variables.
  • StrictRequire - enables strict access which forces denial of access whenever the SSLRequireSSL and SSLRequire directives indicate access is forbiden.
  • OptRenegotiate - enables avoidance of unnecessary handshakes by mod_ssl which also performs safe parameter checks. It is recommended to enable OptRenegotiate on a per directory basis.
More information on the above SSL options can be found on http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#ssloptions. The figure below illustrates the SSL tab and the options discussed above.
SSL
SSL
Figure 11.6. SSL

11.4.2.3. Logging

Use the Logging tab to configure options for specific transfer and error logs.
By default, the server writes the transfer log to the /var/log/httpd/access_log file and the error log to the /var/log/httpd/error_log file.
The transfer log contains a list of all attempts to access the Web server. It records the IP address of the client that is attempting to connect, the date and time of the attempt, and the file on the Web server that it is trying to retrieve. Enter the name of the path and file in which to store this information. If the path and file name do not start with a slash (/), the path is relative to the server root directory as configured. This option corresponds to the TransferLog directive.
Logging
Logging
Figure 11.7. Logging

You can configure a custom log format by checking Use custom logging facilities and entering a custom log string in the Custom Log String field. This configures the LogFormat directive. Refer to http://httpd.apache.org/docs/2.2/mod/mod_log_config.html#logformat for details on the format of this directive.
The error log contains a list of any server errors that occur. Enter the name of the path and file in which to store this information. If the path and file name do not start with a slash (/), the path is relative to the server root directory as configured. This option corresponds to the ErrorLog directive.
Use the Log Level menu to set the verbosity of the error messages in the error logs. It can be set (from least verbose to most verbose) to emerg, alert, crit, error, warn, notice, info or debug. This option corresponds to the LogLevel directive.
The value chosen with the Reverse DNS Lookup menu defines the HostnameLookups directive. Choosing No Reverse Lookup sets the value to off. Choosing Reverse Lookup sets the value to on. Choosing Double Reverse Lookup sets the value to double.
If you choose Reverse Lookup, your server automatically resolves the IP address for each connection which requests a document from your Web server. Resolving the IP address means that your server makes one or more connections to the DNS in order to find out the hostname that corresponds to a particular IP address.
If you choose Double Reverse Lookup, your server performs a double-reverse DNS. In other words, after a reverse lookup is performed, a forward lookup is performed on the result. At least one of the IP addresses in the forward lookup must match the address from the first reverse lookup.
Generally, you should leave this option set to No Reverse Lookup, because the DNS requests add a load to your server and may slow it down. If your server is busy, the effects of trying to perform these reverse lookups or double reverse lookups may be quite noticeable.
Reverse lookups and double reverse lookups are also an issue for the Internet as a whole. Each individual connection made to look up each hostname adds up. Therefore, for your own Web server's benefit, as well as for the Internet's benefit, you should leave this option set to No Reverse Lookup.

11.4.2.4. Environment Variables

Use the Environment tab to configure options for specific variables to set, pass, or unset for CGI scripts.
Sometimes it is necessary to modify environment variables for CGI scripts or server-side include (SSI) pages. The Apache HTTP Server can use the mod_env module to configure the environment variables which are passed to CGI scripts and SSI pages. Use the Environment Variables page to configure the directives for this module.
Use the Set for CGI Scripts section to set an environment variable that is passed to CGI scripts and SSI pages. For example, to set the environment variable MAXNUM to 50, click the Add button inside the Set for CGI Script section, as shown in Figure 11.8, “Environment Variables”, and type MAXNUM in the Environment Variable text field and 50 in the Value to set text field. Click OK to add it to the list. The Set for CGI Scripts section configures the SetEnv directive.
Use the Pass to CGI Scripts section to pass the value of an environment variable when the server is first started to CGI scripts. To see this environment variable, type the command env at a shell prompt. Click the Add button inside the Pass to CGI Scripts section and enter the name of the environment variable in the resulting dialog box. Click OK to add it to the list. The Pass to CGI Scripts section configures the PassEnv directive.
Environment Variables
Environment Variables
Figure 11.8. Environment Variables

To remove an environment variable so that the value is not passed to CGI scripts and SSI pages, use the Unset for CGI Scripts section. Click Add in the Unset for CGI Scripts section, and enter the name of the environment variable to unset. Click OK to add it to the list. This corresponds to the UnsetEnv directive.
To edit any of these environment values, select it from the list and click the corresponding Edit button. To delete any entry from the list, select it and click the corresponding Delete button.
To learn more about environment variables in the Apache HTTP Server, refer to the following: http://httpd.apache.org/docs/2.2/env.html

11.4.2.5. Directories

Use the Directories page in the Performance tab to configure options for specific directories. This corresponds to the <Directory> directive.
Directories
Directories
Figure 11.9. Directories

Click the Edit button in the top right-hand corner to configure the Default Directory Options for all directories that are not specified in the Directory list below it. The options that you choose are listed as the Options directive within the <Directory> directive. You can configure the following options:
  • ExecCGI — Allow execution of CGI scripts. CGI scripts are not executed if this option is not chosen.
  • FollowSymLinks — Allow symbolic links to be followed.
  • Includes — Allow server-side includes.
  • IncludesNOEXEC — Allow server-side includes, but disable the #exec and #include commands in CGI scripts.
  • Indexes — Display a formatted list of the directory's contents, if no DirectoryIndex (such as index.html) exists in the requested directory.
  • Multiview — Support content-negotiated multiviews; this option is disabled by default.
  • SymLinksIfOwnerMatch — Only follow symbolic links if the target file or directory has the same owner as the link.
To specify options for specific directories, click the Add button beside the Directory list box. A window as shown in Figure 11.10, “Directory Settings” appears. Enter the directory to configure in the Directory text field at the bottom of the window. Select the options in the right-hand list and configure the Order directive with the left-hand side options. The Order directive controls the order in which allow and deny directives are evaluated. In the Allow hosts from and Deny hosts from text field, you can specify one of the following:
  • Allow all hosts — Type all to allow access to all hosts.
  • Partial domain name — Allow all hosts whose names match or end with the specified string.
  • Full IP address — Allow access to a specific IP address.
  • A subnet — Such as 192.168.1.0/255.255.255.0
  • A network CIDR specification — such as 10.3.0.0/16
Directory Settings
Directory Settings
Figure 11.10. Directory Settings

If you check the Let .htaccess files override directory options, the configuration directives in the .htaccess file take precedence.

11.5. Configuration Directives in httpd.conf

The Apache HTTP Server configuration file is /etc/httpd/conf/httpd.conf. The httpd.conf file is well-commented and mostly self-explanatory. The default configuration works for most situations; however, it is a good idea to become familiar some of the more important configuration options.

Warning

With the release of Apache HTTP Server 2.2, many configuration options have changed. If migrating from version 1.3 to 2.2, please firstly read Section 11.2.2, “Migrating Apache HTTP Server 1.3 Configuration Files to 2.0”.

11.5.1. General Configuration Tips

If configuring the Apache HTTP Server, edit /etc/httpd/conf/httpd.conf and then either reload, restart, or stop and start the httpd process as outlined in Section 11.3, “Starting and Stopping httpd.
Before editing httpd.conf, make a copy the original file. Creating a backup makes it easier to recover from mistakes made while editing the configuration file.
If a mistake is made and the Web server does not work correctly, first review recently edited passages in httpd.conf to verify there are no typos.
Next look in the Web server's error log, /var/log/httpd/error_log. The error log may not be easy to interpret, depending on your level of expertise. However, the last entries in the error log should provide useful information.
The following subsections contain a list of short descriptions for many of the directives included in httpd.conf. These descriptions are not exhaustive. For more information, refer to the Apache documentation online at http://httpd.apache.org/docs/2.2/.
For more information about mod_ssl directives, refer to the documentation online at http://httpd.apache.org/docs/2.2/mod/mod_ssl.html.
AccessFileName
AccessFileName names the file which the server should use for access control information in each directory. The default is .htaccess.
Immediately after the AccessFileName directive, a set of Files tags apply access control to any file beginning with a .ht. These directives deny Web access to any .htaccess files (or other files which begin with .ht) for security reasons.
Action
Action specifies a MIME content type and CGI script pair, so that when a file of that media type is requested, a particular CGI script is executed.
AddDescription
When using FancyIndexing as an IndexOptions parameter, the AddDescription directive can be used to display user-specified descriptions for certain files or file types in a server generated directory listing. The AddDescription directive supports listing specific files, wildcard expressions, or file extensions.
AddEncoding
AddEncoding names file name extensions which should specify a particular encoding type. AddEncoding can also be used to instruct some browsers to uncompress certain files as they are downloaded.
AddHandler
AddHandler maps file extensions to specific handlers. For example, the cgi-script handler can be matched with the extension .cgi to automatically treat a file ending with .cgi as a CGI script. The following is a sample AddHandler directive for the .cgi extension.
AddHandler cgi-script .cgi

This directive enables CGIs outside of the cgi-bin to function in any directory on the server which has the ExecCGI option within the directories container. Refer to Directory for more information about setting the ExecCGI option for a directory.
In addition to CGI scripts, the AddHandler directive is used to process server-parsed HTML and image-map files.
AddIcon
AddIcon specifies which icon to show in server generated directory listings for files with certain extensions. For example, the Web server is set to show the icon binary.gif for files with .bin or .exe extensions.
AddIconByEncoding
This directive names icons which are displayed by files with MIME encoding in server generated directory listings. For example, by default, the Web server shows the compressed.gif icon next to MIME encoded x-compress and x-gzip files in server generated directory listings.
AddIconByType
This directive names icons which are displayed next to files with MIME types in server generated directory listings. For example, the server shows the icon text.gif next to files with a mime-type of text, in server generated directory listings.
AddLanguage
AddLanguage associates file name extensions with specific languages. This directive is useful for Apache HTTP Servers which serve content in multiple languages based on the client Web browser's language settings.
AddType
Use the AddType directive to define or override a default MIME type and file extension pairs. The following example directive tells the Apache HTTP Server to recognize the .tgz file extension:
AddType application/x-tar .tgz

Alias
The Alias setting allows directories outside the DocumentRoot directory to be accessible. Any URL ending in the alias automatically resolves to the alias' path. By default, one alias for an icons/ directory is already set up. An icons/ directory can be accessed by the Web server, but the directory is not in the DocumentRoot.
Allow
Allow specifies which client can access a given directory. The client can be all, a domain name, an IP address, a partial IP address, a network/netmask pair, and so on. The DocumentRoot directory is configured to Allow requests from all, meaning everyone has access.
AllowOverride
The AllowOverride directive sets whether any Options can be overridden by the declarations in an .htaccess file. By default, both the root directory and the DocumentRoot are set to allow no .htaccess overrides.
BrowserMatch
The BrowserMatch directive allows the server to define environment variables and take appropriate actions based on the User-Agent HTTP header field — which identifies the client's Web browser type. By default, the Web server uses BrowserMatch to deny connections to specific browsers with known problems and also to disable keepalives and HTTP header flushes for browsers that are known to have problems with those actions.
Cache Directives
A number of commented cache directives are supplied by the default Apache HTTP Server configuration file. In most cases, uncommenting these lines by removing the hash mark (#) from the beginning of the line is sufficient. The following, however, is a list of some of the more important cache-related directives.
  • CacheEnable — Specifies whether the cache is a disk, memory, or file descriptor cache. By default CacheEnable configures a disk cache for URLs at or below /.
  • CacheRoot — Specifies the name of the directory containing cached files. The default CacheRoot is the /var/httpd/proxy/ directory.
  • CacheSize — Specifies how much space the cache can use in kilobytes. The default CacheSize is 5 KB.
The following is a list of some of the other common cache-related directives.
  • CacheMaxExpire — Specifies how long HTML documents are retained (without a reload from the originating Web server) in the cache. The default is 24 hours (86400 seconds).
  • CacheLastModifiedFactor — Specifies the creation of an expiry (expiration) date for a document which did not come from its originating server with its own expiry set. The default CacheLastModifiedFactor is set to 0.1, meaning that the expiry date for such documents equals one-tenth of the amount of time since the document was last modified.
  • CacheDefaultExpire — Specifies the expiry time in hours for a document that was received using a protocol that does not support expiry times. The default is set to 1 hour (3600 seconds).
  • NoProxy — Specifies a space-separated list of subnets, IP addresses, domains, or hosts whose content is not cached. This setting is most useful for Intranet sites.
CacheNegotiatedDocs
By default, the Web server asks proxy servers not to cache any documents which were negotiated on the basis of content (that is, they may change over time or because of the input from the requester). If CacheNegotiatedDocs is set to on, this function is disabled and proxy servers are allowed to cache such documents.
CustomLog
CustomLog identifies the log file and the log file format. By default, the access log is recorded to the /var/log/httpd/access_log file while errors are recorded in the /var/log/httpd/error_log file.
The default CustomLog format is the combined log file format, as illustrated here:
remotehost rfc931 user date "request" status bytes referrer user-agent 

DefaultIcon
DefaultIcon specifies the icon displayed in server generated directory listings for files which have no other icon specified. The unknown.gif image file is the default.
DefaultType
DefaultType sets a default content type for the Web server to use for documents whose MIME types cannot be determined. The default is text/plain.
Deny
Deny works similar to Allow, except it specifies who is denied access. The DocumentRoot is not configured to Deny requests from anyone by default.
Directory
<Directory /path/to/directory> and </Directory> tags create a container used to enclose a group of configuration directives which apply only to a specific directory and its subdirectories. Any directive which is applicable to a directory may be used within Directory tags.
By default, very restrictive parameters are applied to the root directory (/), using the Options (refer to Options) and AllowOverride (refer to AllowOverride) directives. Under this configuration, any directory on the system which needs more permissive settings has to be explicitly given those settings.
In the default configuration, another Directory container is configured for the DocumentRoot which assigns less rigid parameters to the directory tree so that the Apache HTTP Server can access the files residing there.
The Directory container can be also be used to configure additional cgi-bin directories for server-side applications outside of the directory specified in the ScriptAlias directive (refer to ScriptAlias for more information).
To accomplish this, the Directory container must set the ExecCGI option for that directory.
For example, if CGI scripts are located in /home/my_cgi_directory, add the following Directory container to the httpd.conf file:
<Directory /home/my_cgi_directory> Options +ExecCGI </Directory>

Next, the AddHandler directive must be uncommented to identify files with the .cgi extension as CGI scripts. Refer to AddHandler for instructions on setting AddHandler.
For this to work, permissions for CGI scripts, and the entire path to the scripts, must be set to 0755.
DirectoryIndex
The DirectoryIndex is the default page served by the server when a user requests an index of a directory by specifying a forward slash (/) at the end of the directory name.
When a user requests the page http://example/this_directory/, they get either the DirectoryIndex page, if it exists, or a server-generated directory list. The default for DirectoryIndex is index.html and the index.html.var type map. The server tries to find either of these files and returns the first one it finds. If it does not find one of these files and Options Indexes is set for that directory, the server generates and returns a listing, in HTML format, of the subdirectories and files within the directory, unless the directory listing feature is turned off.
DocumentRoot
DocumentRoot is the directory which contains most of the HTML files which are served in response to requests. The default DocumentRoot, for both the non-secure and secure Web servers, is the /var/www/html directory. For example, the server might receive a request for the following document:
http://example.com/foo.html

The server looks for the following file in the default directory:
/var/www/html/foo.html

To change the DocumentRoot so that it is not shared by the secure and the non-secure Web servers, refer to Section 11.7, “Virtual Hosts”.
ErrorDocument
The ErrorDocument directive associates an HTTP response code with a message or a URL to be sent back to the client. By default, the Web server outputs a simple and usually cryptic error message when an error occurs. The ErrorDocument directive forces the Web server to instead output a customized message or page.

Important

To be valid, the message must be enclosed in a pair of double quotes ".
ErrorLog
ErrorLog specifies the file where server errors are logged. By default, this directive is set to /var/log/httpd/error_log.
ExtendedStatus
The ExtendedStatus directive controls whether Apache generates basic (off) or detailed server status information (on), when the server-status handler is called. The server-status handler is called using Location tags. More information on calling server-status is included in Location.
Group
Specifies the group name of the Apache HTTP Server processes.
This directive has been deprecated for the configuration of virtual hosts.
By default, Group is set to apache.
HeaderName
HeaderName names the file which, if it exists in the directory, is prepended to the start of server generated directory listings. Like ReadmeName, the server tries to include it as an HTML document if possible or in plain text if not.
HostnameLookups
HostnameLookups can be set to on, off, or double. If HostnameLookups is set to on, the server automatically resolves the IP address for each connection. Resolving the IP address means that the server makes one or more connections to a DNS server, adding processing overhead. If HostnameLookups is set to double, the server performs a double-reverse DNS look up adding even more processing overhead.
To conserve resources on the server, HostnameLookups is set to off by default.
If hostnames are required in server log files, consider running one of the many log analyzer tools that perform the DNS lookups more efficiently and in bulk when rotating the Web server log files.
IfDefine
The IfDefine tags surround configuration directives that are applied if the "test" stated in the IfDefine tag is true. The directives are ignored if the test is false.
The test in the IfDefine tags is a parameter name (for example, HAVE_PERL). If the parameter is defined, meaning that it is provided as an argument to the server's start-up command, then the test is true. In this case, when the Web server is started, the test is true and the directives contained in the IfDefine tags are applied.
IfModule
<IfModule> and </IfModule> tags create a conditional container which are only activated if the specified module is loaded. Directives within the IfModule container are processed under one of two conditions. The directives are processed if the module contained within the starting <IfModule> tag is loaded. Or, if an exclamation point ! appears before the module name, the directives are processed only if the module specified in the <IfModule> tag is not loaded.
For more information about Apache HTTP Server modules, refer to Section 11.6, “Adding Modules”.
Include
Include allows other configuration files to be included at runtime.
The path to these configuration files can be absolute or relative to the ServerRoot.

Important

For the server to use individually packaged modules, such as mod_ssl, mod_perl, and php, the following directive must be included in Section 1: Global Environment of httpd.conf:
Include conf.d/*.conf

IndexIgnore
IndexIgnore lists file extensions, partial file names, wildcard expressions, or full file names. The Web server does not include any files which match any of those parameters in server generated directory listings.
IndexOptions
IndexOptions controls the appearance of server generated directing listings, by adding icons, file descriptions, and so on. If Options Indexes is set (refer to Options), the Web server generates a directory listing when the Web server receives an HTTP request for a directory without an index.
First, the Web server looks in the requested directory for a file matching the names listed in the DirectoryIndex directive (usually, index.html). If an index.html file is not found, Apache HTTP Server creates an HTML directory listing of the requested directory. The appearance of this directory listing is controlled, in part, by the IndexOptions directive.
The default configuration turns on FancyIndexing. This means that a user can re-sort a directory listing by clicking on column headers. Another click on the same header switches from ascending to descending order. FancyIndexing also shows different icons for different files, based upon file extensions.
The AddDescription option, when used in conjunction with FancyIndexing, presents a short description for the file in server generated directory listings.
IndexOptions has a number of other parameters which can be set to control the appearance of server generated directories. The IconHeight and IconWidth parameters require the server to include HTML HEIGHT and WIDTH tags for the icons in server generated webpages. The IconsAreLinks parameter combines the graphical icon with the HTML link anchor, which contains the URL link target.
KeepAlive
KeepAlive sets whether the server allows more than one request per connection and can be used to prevent any one client from consuming too much of the server's resources.
By default Keepalive is set to off. If Keepalive is set to on and the server becomes very busy, the server can quickly spawn the maximum number of child processes. In this situation, the server slows down significantly. If Keepalive is enabled, it is a good idea to set the the KeepAliveTimeout low (refer to KeepAliveTimeout for more information about the KeepAliveTimeout directive) and monitor the /var/log/httpd/error_log log file on the server. This log reports when the server is running out of child processes.
KeepAliveTimeout
KeepAliveTimeout sets the number of seconds the server waits after a request has been served before it closes the connection. Once the server receives a request, the Timeout directive applies instead. The KeepAliveTimeout directive is set to 15 seconds by default.
LanguagePriority
LanguagePriority sets precedence for different languages in case the client Web browser has no language preference set.
Listen
The Listen command identifies the ports on which the Web server accepts incoming requests. By default, the Apache HTTP Server is set to listen to port 80 for non-secure Web communications and (in the /etc/httpd/conf.d/ssl.conf file which defines any secure servers) to port 443 for secure Web communications.
If the Apache HTTP Server is configured to listen to a port under 1024, only the root user can start it. For port 1024 and above, httpd can be started as a regular user.
The Listen directive can also be used to specify particular IP addresses over which the server accepts connections.
LoadModule
LoadModule is used to load Dynamic Shared Object (DSO) modules. More information on the Apache HTTP Server's DSO support, including instructions for using the LoadModule directive, can be found in Section 11.6, “Adding Modules”. Note, the load order of the modules is no longer important with Apache HTTP Server 2.0. Refer to Section 11.2.2.1.3, “Dynamic Shared Object (DSO) Support” for more information about Apache HTTP Server 2.0 DSO support.
Location
The <Location> and </Location> tags create a container in which access control based on URL can be specified.
For instance, to allow people connecting from within the server's domain to see status reports, use the following directives:
<Location /server-status> SetHandler server-status Order deny,allow Deny from all Allow from <.example.com> </Location>

Replace <.example.com> with the second-level domain name for the Web server.
To provide server configuration reports (including installed modules and configuration directives) to requests from inside the domain, use the following directives:
<Location /server-info> SetHandler server-info Order deny,allow Deny from all Allow from <.example.com> </Location>

Again, replace <.example.com> with the second-level domain name for the Web server.
LogFormat
The LogFormat directive configures the format of the various Web server log files. The actual LogFormat used depends on the settings given in the CustomLog directive (refer to CustomLog).
The following are the format options if the CustomLog directive is set to combined:
%h (remote host's IP address or hostname)
Lists the remote IP address of the requesting client. If HostnameLookups is set to on, the client hostname is recorded unless it is not available from DNS.
%l (rfc931)
Not used. A hyphen - appears in the log file for this field.
%u (authenticated user)
Lists the username of the user recorded if authentication was required. Usually, this is not used, so a hyphen - appears in the log file for this field.
%t (date)
Lists the date and time of the request.
%r (request string)
Lists the request string exactly as it came from the browser or client.
%s (status)
Lists the HTTP status code which was returned to the client host.
%b (bytes)
Lists the size of the document.
%\"%{Referer}i\" (referrer)
Lists the URL of the webpage which referred the client host to Web server.
%\"%{User-Agent}i\" (user-agent)
Lists the type of Web browser making the request.
LogLevel
LogLevel sets how verbose the error messages in the error logs are. LogLevel can be set (from least verbose to most verbose) to emerg, alert, crit, error, warn, notice, info, or debug. The default LogLevel is warn.
MaxKeepAliveRequests
This directive sets the maximum number of requests allowed per persistent connection. The Apache Project recommends a high setting, which improves the server's performance. MaxKeepAliveRequests is set to 100 by default, which should be appropriate for most situations.
NameVirtualHost
The NameVirtualHost directive associates an IP address and port number, if necessary, for any name-based virtual hosts. Name-based virtual hosting allows one Apache HTTP Server to serve different domains without using multiple IP addresses.

Note

Name-based virtual hosts only work with non-secure HTTP connections. If using virtual hosts with a secure server, use IP address-based virtual hosts instead.
To enable name-based virtual hosting, uncomment the NameVirtualHost configuration directive and add the correct IP address. Then add additional VirtualHost containers for each virtual host as is necessary for your configuration.
Options
The Options directive controls which server features are available in a particular directory. For example, under the restrictive parameters specified for the root directory, Options is only set to the FollowSymLinks directive. No features are enabled, except that the server is allowed to follow symbolic links in the root directory.
By default, in the DocumentRoot directory, Options is set to include Indexes and FollowSymLinks. Indexes permits the server to generate a directory listing for a directory if no DirectoryIndex (for example, index.html) is specified. FollowSymLinks allows the server to follow symbolic links in that directory.

Note

Options statements from the main server configuration section need to be replicated to each VirtualHost container individually. Refer to VirtualHost for more information.
Order
The Order directive controls the order in which allow and deny directives are evaluated. The server is configured to evaluate the Allow directives before the Deny directives for the DocumentRoot directory.
PidFile
PidFile names the file where the server records its process ID (PID). By default the PID is listed in /var/run/httpd.pid.
Proxy
<Proxy *> and </Proxy> tags create a container which encloses a group of configuration directives meant to apply only to the proxy server. Many directives which are allowed within a <Directory> container may also be used within <Proxy> container.
ProxyRequests
To configure the Apache HTTP Server to function as a proxy server, remove the hash mark (#) from the beginning of the <IfModule mod_proxy.c> line, the ProxyRequests, and each line in the <Proxy> stanza. Set the ProxyRequests directive to On, and set which domains are allowed access to the server in the Allow from directive of the <Proxy> stanza.
ReadmeName
ReadmeName names the file which, if it exists in the directory, is appended to the end of server generated directory listings. The Web server first tries to include the file as an HTML document and then tries to include it as plain text. By default, ReadmeName is set to README.html.
Redirect
When a webpage is moved, Redirect can be used to map the file location to a new URL. The format is as follows:
Redirect /<old-path>/<file-name> http://<current-domain>/<current-path>/<file-name> 

In this example, replace <old-path> with the old path information for <file-name> and <current-domain> and <current-path> with the current domain and path information for <file-name>.
In this example, any requests for <file-name> at the old location is automatically redirected to the new location.
For more advanced redirection techniques, use the mod_rewrite module included with the Apache HTTP Server. For more information about configuring the mod_rewrite module, refer to the Apache Software Foundation documentation online at http://httpd.apache.org/docs/2.2/mod/mod_rewrite.html.
ScriptAlias
The ScriptAlias directive defines where CGI scripts are located. Generally, it is not good practice to leave CGI scripts within the DocumentRoot, where they can potentially be viewed as text documents. For this reason, a special directory outside of the DocumentRoot directory containing server-side executables and scripts is designated by the ScriptAlias directive. This directory is known as a cgi-bin and is set to /var/www/cgi-bin/ by default.
It is possible to establish directories for storing executables outside of the cgi-bin/ directory. For instructions on doing so, refer to AddHandler and Directory.
ServerAdmin
Sets the ServerAdmin directive to the email address of the Web server administrator. This email address shows up in error messages on server-generated Web pages, so users can report a problem by sending email to the server administrator.
By default, ServerAdmin is set to root@localhost.
A common way to set up ServerAdmin is to set it to webmaster@example.com. Once set, alias webmaster to the person responsible for the Web server in /etc/aliases and run /usr/bin/newaliases.
ServerName
ServerName specifies a hostname and port number (matching the Listen directive) for the server. The ServerName does not need to match the machine's actual hostname. For example, the Web server may be www.example.com, but the server's hostname is actually foo.example.com. The value specified in ServerName must be a valid Domain Name Service (DNS) name that can be resolved by the system — do not make something up.
The following is a sample ServerName directive:
ServerName www.example.com:80

When specifying a ServerName, be sure the IP address and server name pair are included in the /etc/hosts file.
ServerRoot
The ServerRoot directive specifies the top-level directory containing website content. By default, ServerRoot is set to "/etc/httpd" for both secure and non-secure servers.
ServerSignature
The ServerSignature directive adds a line containing the Apache HTTP Server server version and the ServerName to any server-generated documents, such as error messages sent back to clients. ServerSignature is set to on by default.
ServerSignature can be set to EMail which adds a mailto:ServerAdmin HTML tag to the signature line of auto-generated responses. ServerSignature can also be set to Off to stop Apache from sending out its version number and module information. Please also check the ServerTokens settings.
ServerTokens
The ServerTokens directive determines if the Server response header field sent back to clients should include details of the Operating System type and information about compiled-in modules. By default, ServerTokens is set to Full which sends information about the Operating System type and compiled-in modules. Setting the ServerTokens to Prod sends the product name only and is recommended as many hackers check information in the Server header when scanning for vulnerabilities. You can also set the ServerTokens to Min (minimal) or to OS (operating system).
SuexecUserGroup
The SuexecUserGroup directive, which originates from the mod_suexec module, allows the specification of user and group execution privileges for CGI programs. Non-CGI requests are still processed with the user and group specified in the User and Group directives.

Note

From version 2.0, the SuexecUserGroup directive replaced the Apache HTTP Server 1.3 configuration of using the User and Group directives inside the configuration of VirtualHosts sections.
Timeout
Timeout defines, in seconds, the amount of time that the server waits for receipts and transmissions during communications. Timeout is set to 300 seconds by default, which is appropriate for most situations.
TypesConfig
TypesConfig names the file which sets the default list of MIME type mappings (file name extensions to content types). The default TypesConfig file is /etc/mime.types. Instead of editing /etc/mime.types, the recommended way to add MIME type mappings is to use the AddType directive.
For more information about AddType, refer to AddType.
UseCanonicalName
When set to on, this directive configures the Apache HTTP Server to reference itself using the value specified in the ServerName and Port directives. When UseCanonicalName is set to off, the server instead uses the value used by the requesting client when referring to itself.
UseCanonicalName is set to off by default.
User
The User directive sets the username of the server process and determines what files the server is allowed to access. Any files inaccessible to this user are also inaccessible to clients connecting to the Apache HTTP Server.
By default User is set to apache.
This directive has been deprecated for the configuration of virtual hosts.

Note

For security reasons, the Apache HTTP Server does not run as the root user.
UserDir
UserDir is the subdirectory within each user's home directory where they should place personal HTML files which are served by the Web server. This directive is set to disable by default.
The name for the subdirectory is set to public_html in the default configuration. For example, the server might receive the following request:
http://example.com/~username/foo.html

The server would look for the file:
/home/username/public_html/foo.html

In the above example, /home/username/ is the user's home directory (note that the default path to users' home directories may vary).
Make sure that the permissions on the users' home directories are set correctly. Users' home directories must be set to 0711. The read (r) and execute (x) bits must be set on the users' public_html directories (0755 also works). Files that are served in a users' public_html directories must be set to at least 0644.
VirtualHost
<VirtualHost> and </VirtualHost> tags create a container outlining the characteristics of a virtual host. The VirtualHost container accepts most configuration directives.
A commented VirtualHost container is provided in httpd.conf, which illustrates the minimum set of configuration directives necessary for each virtual host. Refer to Section 11.7, “Virtual Hosts” for more information about virtual hosts.

Note

The default SSL virtual host container now resides in the file /etc/httpd/conf.d/ssl.conf.

11.5.2. Configuration Directives for SSL

The directives in /etc/httpd/conf.d/ssl.conf file can be configured to enable secure Web communications using SSL and TLS.
SetEnvIf
SetEnvIf sets environment variables based on the headers of incoming connections. It is not solely an SSL directive, though it is present in the supplied /etc/httpd/conf.d/ssl.conf file. It's purpose in this context is to disable HTTP keepalive and to allow SSL to close the connection without a closing notification from the client browser. This setting is necessary for certain browsers that do not reliably shut down the SSL connection.
For more information on other directives within the SSL configuration file, refer to the following URLs:

Note

In most cases, SSL directives are configured appropriately during the installation of Fedora. Be careful when altering Apache HTTP Secure Server directives, misconfiguration can lead to security vulnerabilities.

11.5.3. MPM Specific Server-Pool Directives

As explained in Section 11.2.2.1.2, “Server-Pool Size Regulation”, the responsibility for managing characteristics of the server-pool falls to a module group called MPMs under Apache HTTP Server 2.0. The characteristics of the server-pool differ depending upon which MPM is used. For this reason, an IfModule container is necessary to define the server-pool for the MPM in use.
By default, Apache HTTP Server 2.0 defines the server-pool for both the prefork and worker MPMs.
The following section list directives found within the MPM-specific server-pool containers.
MaxClients
MaxClients sets a limit on the total number of server processes, or simultaneously connected clients, that can run at one time. The main purpose of this directive is to keep a runaway Apache HTTP Server from crashing the operating system. For busy servers this value should be set to a high value. The server's default is set to 150 regardless of the MPM in use. However, it is not recommended that the value for MaxClients exceeds 256 when using the prefork MPM.
MaxRequestsPerChild
MaxRequestsPerChild sets the total number of requests each child server process serves before the child dies. The main reason for setting MaxRequestsPerChild is to avoid long-lived process induced memory leaks. The default MaxRequestsPerChild for the prefork MPM is 4000 and for the worker MPM is 0.
MinSpareServers and MaxSpareServers
These values are only used with the prefork MPM. They adjust how the Apache HTTP Server dynamically adapts to the perceived load by maintaining an appropriate number of spare server processes based on the number of incoming requests. The server checks the number of servers waiting for a request and kills some if there are more than MaxSpareServers or creates some if the number of servers is less than MinSpareServers.
The default MinSpareServers value is 5; the default MaxSpareServers value is 20. These default settings should be appropriate for most situations. Be careful not to increase the MinSpareServers to a large number as doing so creates a heavy processing load on the server even when traffic is light.
MinSpareThreads and MaxSpareThreads
These values are only used with the worker MPM. They adjust how the Apache HTTP Server dynamically adapts to the perceived load by maintaining an appropriate number of spare server threads based on the number of incoming requests. The server checks the number of server threads waiting for a request and kills some if there are more than MaxSpareThreads or creates some if the number of servers is less than MinSpareThreads.
The default MinSpareThreads value is 25; the default MaxSpareThreads value is 75. These default settings should be appropriate for most situations. The value for MaxSpareThreads must be greater than or equal to the sum of MinSpareThreads and ThreadsPerChild, else the Apache HTTP Server automatically corrects it.
StartServers
The StartServers directive sets how many server processes are created upon startup. Since the Web server dynamically kills and creates server processes based on traffic load, it is not necessary to change this parameter. The Web server is set to start 8 server processes at startup for the prefork MPM and 2 for the worker MPM.
ThreadsPerChild
This value is only used with the worker MPM. It sets the number of threads within each child process. The default value for this directive is 25.

11.6. Adding Modules

The Apache HTTP Server is distributed with a number of modules. More information about Apache HTTP modules can be found on http://httpd.apache.org/docs/2.2/mod/.
The Apache HTTP Server supports Dynamically Shared Objects (DSOs), or modules, which can easily be loaded at runtime as necessary.
The Apache Project provides complete DSO documentation online at http://httpd.apache.org/docs/2.2/dso.html. Or, if the http-manual package is installed, documentation about DSOs can be found online at http://localhost/manual/mod/.
For the Apache HTTP Server to use a DSO, it must be specified in a LoadModule directive within /etc/httpd/conf/httpd.conf. If the module is provided by a separate package, the line must appear within the modules configuration file in the /etc/httpd/conf.d/ directory. Refer to LoadModule for more information.
If adding or deleting modules from http.conf, Apache HTTP Server must be reloaded or restarted, as referred to in Section 11.3, “Starting and Stopping httpd.
If creating a new module, first install the httpd-devel package which contains the include files, the header files, as well as the APache eXtenSion (/usr/sbin/apxs) application, which uses the include files and the header files to compile DSOs.
After writing a module, use /usr/sbin/apxs to compile the module sources outside the Apache source tree. For more information about using the /usr/sbin/apxs command, refer to the the Apache documentation online at http://httpd.apache.org/docs/2.2/dso.html as well as the apxs man page.
Once compiled, put the module in the /usr/lib/httpd/modules/ directory. For RHEL platforms using default-64-bit userspace (x86_64, ia64, ?) this path will be /usr/lib64/httpd/modules/. Then add a LoadModule line to the httpd.conf, using the following structure:
LoadModule <module-name> <path/to/module.so> 

Where <module-name> is the name of the module and <path/to/module.so> is the path to the DSO.

11.7. Virtual Hosts

The Apache HTTP Server's built in virtual hosting allows the server to provide different information based on which IP address, hostname, or port is being requested. A complete guide to using virtual hosts is available online at http://httpd.apache.org/docs/2.2/vhosts/.

11.7.1. Setting Up Virtual Hosts

To create a name-based virtual host, it is best to use the virtual host container provided in httpd.conf as an example.
The virtual host example read as follows:
#NameVirtualHost *:80 # #<VirtualHost *:80> # ServerAdmin webmaster@dummy-host.example.com # DocumentRoot /www/docs/dummy-host.example.com # ServerName dummy-host.example.com # ErrorLog logs/dummy-host.example.com-error_log # CustomLog logs/dummy-host.example.com-access_log common #</VirtualHost>

To activate name-based virtual hosting, uncomment the NameVirtualHost line by removing the hash mark (#) and replace the asterisk (*) with the IP address assigned to the machine.
Next, configure a virtual host by uncommenting and customizing the <VirtualHost> container.
On the <VirtualHost> line, change the asterisk (*) to the server's IP address. Change the ServerName to a valid DNS name assigned to the machine, and configure the other directives as necessary.
The <VirtualHost> container is highly customizable and accepts almost every directive available within the main server configuration.

Tip

If configuring a virtual host to listen on a non-default port, that port must be added to the Listen directive in the global settings section of /etc/httpd/conf/httpd.conf file.
To activate a newly created virtual host, the Apache HTTP Server must be reloaded or restarted. Refer to Section 11.3, “Starting and Stopping httpd for further instructions.
Comprehensive information about creating and configuring both name-based and IP address-based virtual hosts is provided online at http://httpd.apache.org/docs/2.2/vhosts/.

11.8. Apache HTTP Secure Server Configuration

This section provides basic information on the Apache HTTP Server with the mod_ssl security module enabled to use the OpenSSL library and toolkit. The combination of these three components are referred to in this section as the secure Web server or just as the secure server.
The mod_ssl module is a security module for the Apache HTTP Server. The mod_ssl module uses the tools provided by the OpenSSL Project to add a very important feature to the Apache HTTP Server — the ability to encrypt communications. In contrast, regular HTTP communications between a browser and a Web server are sent in plain text, which could be intercepted and read by someone along the route between the browser and the server.
This section is not meant to be complete and exclusive documentation for any of these programs. When possible, this guide points to appropriate places where you can find more in-depth documentation on particular subjects.
This section shows you how to install these programs. You can also learn the steps necessary to generate a private key and a certificate request, how to generate your own self-signed certificate, and how to install a certificate to use with your secure server.
The mod_ssl configuration file is located at /etc/httpd/conf.d/ssl.conf. For this file to be loaded, and hence for mod_ssl to work, you must have the statement Include conf.d/*.conf in the /etc/httpd/conf/httpd.conf file. This statement is included by default in the default Apache HTTP Server configuration file.

11.8.1. An Overview of Security-Related Packages

To enable the secure server, you must have the following packages installed at a minimum:
httpd
The httpd package contains the httpd daemon and related utilities, configuration files, icons, Apache HTTP Server modules, man pages, and other files used by the Apache HTTP Server.
mod_ssl
The mod_ssl package includes the mod_ssl module, which provides strong cryptography for the Apache HTTP Server via the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols.
openssl
The openssl package contains the OpenSSL toolkit. The OpenSSL toolkit implements the SSL and TLS protocols, and also includes a general purpose cryptography library.
Additionally, other software packages provide certain security functionalities (but are not required by the secure server to function):

11.8.2. An Overview of Certificates and Security

Your secure server provides security using a combination of the Secure Sockets Layer (SSL) protocol and (in most cases) a digital certificate from a Certificate Authority (CA). SSL handles the encrypted communications as well as the mutual authentication between browsers and your secure server. The CA-approved digital certificate provides authentication for your secure server (the CA puts its reputation behind its certification of your organization's identity). When your browser is communicating using SSL encryption, the https:// prefix is used at the beginning of the Uniform Resource Locator (URL) in the navigation bar.
Encryption depends upon the use of keys (think of them as secret encoder/decoder rings in data format). In conventional or symmetric cryptography, both ends of the transaction have the same key, which they use to decode each other's transmissions. In public or asymmetric cryptography, two keys co-exist: a public key and a private key. A person or an organization keeps their private key a secret and publishes their public key. Data encoded with the public key can only be decoded with the private key; data encoded with the private key can only be decoded with the public key.
To set up your secure server, use public cryptography to create a public and private key pair. In most cases, you send your certificate request (including your public key), proof of your company's identity, and payment to a CA. The CA verifies the certificate request and your identity, and then sends back a certificate for your secure server.
A secure server uses a certificate to identify itself to Web browsers. You can generate your own certificate (called a "self-signed" certificate), or you can get a certificate from a CA. A certificate from a reputable CA guarantees that a website is associated with a particular company or organization.
Alternatively, you can create your own self-signed certificate. Note, however, that self-signed certificates should not be used in most production environments. Self-signed certificates are not automatically accepted by a user's browser — users are prompted by the browser to accept the certificate and create the secure connection. Refer to Section 11.8.4, “Types of Certificates” for more information on the differences between self-signed and CA-signed certificates.
Once you have a self-signed certificate or a signed certificate from the CA of your choice, you must install it on your secure server.

11.8.3. Using Pre-Existing Keys and Certificates

If you already have an existing key and certificate (for example, if you are installing the secure server to replace another company's secure server product), you can probably use your existing key and certificate with the secure server. The following two situations provide instances where you are not able to use your existing key and certificate:
  • If you are changing your IP address or domain name — Certificates are issued for a particular IP address and domain name pair. You must get a new certificate if you are changing your IP address or domain name.
  • If you have a certificate from VeriSign and you are changing your server software — VeriSign is a widely used CA. If you already have a VeriSign certificate for another purpose, you may have been considering using your existing VeriSign certificate with your new secure server. However, you are not be allowed to because VeriSign issues certificates for one specific server software and IP address/domain name combination.
    If you change either of those parameters (for example, if you previously used a different secure server product), the VeriSign certificate you obtained to use with the previous configuration will not work with the new configuration. You must obtain a new certificate.
If you have an existing key and certificate that you can use, you do not have to generate a new key and obtain a new certificate. However, you may need to move and rename the files which contain your key and certificate.
Move your existing key file to:
/etc/pki/tls/private/server.key

Move your existing certificate file to:
/etc/pki/tls/certs/server.crt

If you are upgrading from the Red Hat Secure Web Server, your old key (httpsd.key) and certificate (httpsd.crt) are located in /etc/httpd/conf/. Move and rename your key and certificate so that the secure server can use them. Use the following two commands to move and rename your key and certificate files:
mv /etc/httpd/conf/httpsd.key /etc/pki/tls/private/server.key mv /etc/httpd/conf/httpsd.crt /etc/pki/tls/certs/server.crt

Then, start your secure server with the command:
/sbin/service httpd start

11.8.4. Types of Certificates

If you installed your secure server from the RPM package provided by Red Hat, a randomly generated private key and a test certificate are generated and put into the appropriate directories. Before you begin using your secure server, however, you must generate your own key and obtain a certificate which correctly identifies your server.
You need a key and a certificate to operate your secure server — which means that you can either generate a self-signed certificate or purchase a CA-signed certificate from a CA. What are the differences between the two?
A CA-signed certificate provides two important capabilities for your server:
  • Browsers (usually) automatically recognize the certificate and allow a secure connection to be made, without prompting the user.
  • When a CA issues a signed certificate, they are guaranteeing the identity of the organization that is providing the webpages to the browser.
If your secure server is being accessed by the public at large, your secure server needs a certificate signed by a CA so that people who visit your website know that the website is owned by the organization who claims to own it. Before signing a certificate, a CA verifies that the organization requesting the certificate was actually who they claimed to be.
Most Web browsers that support SSL have a list of CAs whose certificates they automatically accept. If a browser encounters a certificate whose authorizing CA is not in the list, the browser asks the user to either accept or decline the connection.
You can generate a self-signed certificate for your secure server, but be aware that a self-signed certificate does not provide the same functionality as a CA-signed certificate. A self-signed certificate is not automatically recognized by most Web browsers and does not provide any guarantee concerning the identity of the organization that is providing the website. A CA-signed certificate provides both of these important capabilities for a secure server. If your secure server is to be used in a production environment, a CA-signed certificate is recommended.
The process of getting a certificate from a CA is fairly easy. A quick overview is as follows:
  1. Create an encryption private and public key pair.
  2. Create a certificate request based on the public key. The certificate request contains information about your server and the company hosting it.
  3. Send the certificate request, along with documents proving your identity, to a CA. Red Hat does not make recommendations on which certificate authority to choose. Your decision may be based on your past experiences, on the experiences of your friends or colleagues, or purely on monetary factors.
    Once you have decided upon a CA, you need to follow the instructions they provide on how to obtain a certificate from them.
  4. When the CA is satisfied that you are indeed who you claim to be, they provide you with a digital certificate.
  5. Install this certificate on your secure server and begin handling secure transactions.
Whether you are getting a certificate from a CA or generating your own self-signed certificate, the first step is to generate a key. Refer to Section 11.8.5, “Generating a Key” for instructions.

11.8.5. Generating a Key

You must be root to generate a key.
First, use the cd command to change to the /etc/httpd/conf/ directory. Remove the fake key and certificate that were generated during the installation with the following commands:
rm ssl.key/server.key
        rm ssl.crt/server.crt

The crypto-utils package contains the genkey utility which you can use to generate keys as the name implies. To create your own private key, please ensure the crypto-utils package is installed. You can view more options by typing man genkey in your terminal. Assuming you wish to generate keys for www.example.com using the genkey utility, type in the following command in your terminal:
genkey www.example.com

Please note that the make based process is no longer shipped with RHEL 5. This will start the genkey graphical user interface. The figure below illustrates the first screen. To navigate, use the keyboard arrow and tab keys. This windows indicates where your key will be stored and prompts you to proceed or cancel the operation. To proceed to the next step, select Next and press the Return (Enter) key.
Keypair generation
Keypair generation
Figure 11.11. Keypair generation

The next screen prompts you to choose the size of your key. As indicated, the smaller the size of your key, the faster will the response from your server be and the lesser your level of security. On selecting your preferred, key size using the arrow keys, select Next to proceed to the next step. The figure below illustrates the key size selection screen.
Choose key size
Choose key size
Figure 11.12. Choose key size

Selecting the next step will initiate the random bits generation process which may take some time depending on the size of your selected key. The larger the size of your key, the longer it will take to generate it.
Generating random bits
Generating random bits
Figure 11.13. Generating random bits

On generating your key, you will be prompted to send a Certificate Request (CSR) to a Certificate Authority (CA).
Generate CSR
Generate CSR
Figure 11.14. Generate CSR

Selecting Yes will prompt you to select the Certificate Authority you wish to send your request to. Selecting No will allow you to generate a self-signed certificate. The next step for this is illustrated in Figure 11.17, “Generating a self signed certificate for your server”.
Choose Certificate Authority (CA)
Choose Certificate Authority (CA)
Figure 11.15. Choose Certificate Authority (CA)

On Selecting your preferred option, select Next to proceed to the next step. The next screen allows you to enter the details of your certificate.
Enter details for your certificate
Enter details for your certificate
Figure 11.16. Enter details for your certificate

If you prefer to generate a self signed cert key pair, you should not generate a CSR. To do this, select No as your preferred option in the Generate CSR screen. This will display the figure below from which you can enter your certificate details. Entering your certificate details and pressing the return key will display the Figure 11.19, “Protecting your private key” from which you can choose to encrypt your private key or not.
Generating a self signed certificate for your server
Generating a self signed certificate for your server
Figure 11.17. Generating a self signed certificate for your server

On entering the details of your certificate, select Next to proceed. The figure below illustrates an example of a the next screen displayed after completing the details for a certificate to be sent to Equifax. Please note that if you are generating a self signed key, for your server, this screen is not displayed.
Begin certificate request
Begin certificate request
Figure 11.18. Begin certificate request

Pressing the return key, will display the next screen from which you can enable or disable the encryption of the private key. Use the spacebar to enable or disable this. When enabled, a [*] character will be displayed. On selecting your preferred option, select Next to proceed to the next step.
Protecting your private key
Protecting your private key
Figure 11.19. Protecting your private key

The next screen allows you to set your key passphase. Please do not lose this pass phase as you will not be able to run the server without it. You will need to regenerate a new private or public key pair and request a new certificate from your CA as indicated. For security, the passphase is not displayed as you type. On typing your preferred passphase, select Next to go back to your terminal.
Set passphase
Set passphase
Figure 11.20. Set passphase

If you attempt to run genkey makeca on a server that has an existing key pair, an error message will be displayed as illustrated below. You need to delete your existing key file as indicated to generate a new key pair.
genkey error
genkey error
Figure 11.21. genkey error

11.8.6. How to configure the server to use the new key

The steps to configure the Apache HTTP Server to use the new key are:
  • Obtain the signed certificate from the CA after submitting the CSR.
  • Copy the certificate to the path, for example /etc/pki/tls/certs/www.example.com.crt
  • Edit /etc/httpd/conf.d/ssl.conf. Change the SSLCertificateFile and SSLCertificateKey lines to be.
    SSLCertificateFile /etc/pki/tls/certs/www.example.com.crt
    SSLCertificateKeyFile /etc/pki/tls/private/www.example.com.key
    
    
    where the "www.example.com" part should match the argument passed on the genkey command.

11.9. Additional Resources

To learn more about the Apache HTTP Server, refer to the following resources.

11.9.1. Useful Websites

Chapter 12. FTP

File Transfer Protocol (FTP) is one of the oldest and most commonly used protocols found on the Internet today. Its purpose is to reliably transfer files between computer hosts on a network without requiring the user to log directly into the remote host or have knowledge of how to use the remote system. It allows users to access files on remote systems using a standard set of simple commands.
This chapter outlines the basics of the FTP protocol, as well as configuration options for the primary FTP server shipped with Fedora, vsftpd.

12.1. The File Transfer Protocol

However, because FTP is so prevalent on the Internet, it is often required to share files to the public. System administrators, therefore, should be aware of the FTP protocol's unique characteristics.

12.1.1. Multiple Ports, Multiple Modes

Unlike most protocols used on the Internet, FTP requires multiple network ports to work properly. When an FTP client application initiates a connection to an FTP server, it opens port 21 on the server — known as the command port. This port is used to issue all commands to the server. Any data requested from the server is returned to the client via a data port. The port number for data connections, and the way in which data connections are initialized, vary depending upon whether the client requests the data in active or passive mode.
The following defines these modes:
active mode
Active mode is the original method used by the FTP protocol for transferring data to the client application. When an active mode data transfer is initiated by the FTP client, the server opens a connection from port 20 on the server to the IP address and a random, unprivileged port (greater than 1024) specified by the client. This arrangement means that the client machine must be allowed to accept connections over any port above 1024. With the growth of insecure networks, such as the Internet, the use of firewalls to protect client machines is now prevalent. Because these client-side firewalls often deny incoming connections from active mode FTP servers, passive mode was devised.
passive mode
Passive mode, like active mode, is initiated by the FTP client application. When requesting data from the server, the FTP client indicates it wants to access the data in passive mode and the server provides the IP address and a random, unprivileged port (greater than 1024) on the server. The client then connects to that port on the server to download the requested information.
While passive mode resolves issues for client-side firewall interference with data connections, it can complicate administration of the server-side firewall. You can reduce the number of open ports on a server by limiting the range of unprivileged ports on the FTP server. This also simplifies the process of configuring firewall rules for the server. Refer to Section 12.5.8, “Network Options” for more about limiting passive ports.

12.2. FTP Servers

Fedora ships with two different FTP servers:
  • Red Hat Content Accelerator — A kernel-based Web server that delivers high performance Web server and FTP services. Since speed as its primary design goal, it has limited functionality and runs only as an anonymous FTP server. For more information about configuring and administering Red Hat Content Accelerator, consult the documentation available online at http://www.redhat.com/docs/manuals/tux/.
  • vsftpd — A fast, secure FTP daemon which is the preferred FTP server for Fedora. The remainder of this chapter focuses on vsftpd.

12.2.1.  vsftpd

The Very Secure FTP Daemon (vsftpd) is designed from the ground up to be fast, stable, and, most importantly, secure. vsftpd is the only stand-alone FTP server distributed with Fedora, due to its ability to handle large numbers of connections efficiently and securely.
The security model used by vsftpd has three primary aspects:
  • Strong separation of privileged and non-privileged processes — Separate processes handle different tasks, and each of these processes run with the minimal privileges required for the task.
  • Tasks requiring elevated privileges are handled by processes with the minimal privilege necessary — By leveraging compatibilities found in the libcap library, tasks that usually require full root privileges can be executed more safely from a less privileged process.
  • Most processes run in a chroot jail — Whenever possible, processes are change-rooted to the directory being shared; this directory is then considered a chroot jail. For example, if the directory /var/ftp/ is the primary shared directory, vsftpd reassigns /var/ftp/ to the new root directory, known as /. This disallows any potential malicious hacker activities for any directories not contained below the new root directory.
Use of these security practices has the following effect on how vsftpd deals with requests:
  • The parent process runs with the least privileges required — The parent process dynamically calculates the level of privileges it requires to minimize the level of risk. Child processes handle direct interaction with the FTP clients and run with as close to no privileges as possible.
  • All operations requiring elevated privileges are handled by a small parent process — Much like the Apache HTTP Server, vsftpd launches unprivileged child processes to handle incoming connections. This allows the privileged, parent process to be as small as possible and handle relatively few tasks.
  • All requests from unprivileged child processes are distrusted by the parent process — Communication with child processes are received over a socket, and the validity of any information from child processes is checked before being acted on.
  • Most interaction with FTP clients is handled by unprivileged child processes in a chroot jail — Because these child processes are unprivileged and only have access to the directory being shared, any crashed processes only allows the attacker access to the shared files.

12.3. Files Installed with vsftpd

The vsftpd RPM installs the daemon (/usr/sbin/vsftpd), its configuration and related files, as well as FTP directories onto the system. The following lists the files and directories related to vsftpd configuration:
  • /etc/rc.d/init.d/vsftpd — The initialization script (initscript) used by the /sbin/service command to start, stop, or reload vsftpd. Refer to Section 12.4, “Starting and Stopping vsftpd for more information about using this script.
  • /etc/pam.d/vsftpd — The Pluggable Authentication Modules (PAM) configuration file for vsftpd. This file specifies the requirements a user must meet to login to the FTP server. For more information, refer to .
  • /etc/vsftpd/vsftpd.conf — The configuration file for vsftpd. Refer to Section 12.5, “ vsftpd Configuration Options” for a list of important options contained within this file.
  • /etc/vsftpd.ftpusers — A list of users not allowed to log into vsftpd. By default, this list includes the root, bin, and daemon users, among others.
  • /etc/vsftpd.user_list — This file can be configured to either deny or allow access to the users listed, depending on whether the userlist_deny directive is set to YES (default) or NO in /etc/vsftpd/vsftpd.conf. If /etc/vsftpd.user_list is used to grant access to users, the usernames listed must not appear in /etc/vsftpd.ftpusers.
  • /var/ftp/ — The directory containing files served by vsftpd. It also contains the /var/ftp/pub/ directory for anonymous users. Both directories are world-readable, but writable only by the root user.

12.4. Starting and Stopping vsftpd

The vsftpd RPM installs the /etc/rc.d/init.d/vsftpd script, which can be accessed using the /sbin/service command.
To start the server, as root type:
/sbin/service vsftpd start

To stop the server, as root type:
/sbin/service vsftpd stop

The restart option is a shorthand way of stopping and then starting vsftpd. This is the most efficient way to make configuration changes take effect after editing the configuration file for vsftpd.
To restart the server, as root type:
/sbin/service vsftpd restart

The condrestart (conditional restart) option only starts vsftpd if it is currently running. This option is useful for scripts, because it does not start the daemon if it is not running.
To conditionally restart the server, as root type:
/sbin/service vsftpd condrestart

By default, the vsftpd service does not start automatically at boot time. To configure the vsftpd service to start at boot time, use an initscript utility, such as /sbin/chkconfig, /usr/sbin/ntsysv, or the Services Configuration Tool program. Refer to Chapter 6, Controlling Access to Services for more information regarding these tools.

12.4.1. Starting Multiple Copies of vsftpd

Sometimes one computer is used to serve multiple FTP domains. This is a technique called multihoming. One way to multihome using vsftpd is by running multiple copies of the daemon, each with its own configuration file.
To do this, first assign all relevant IP addresses to network devices or alias network devices on the system. Refer to Chapter 5, Network Configuration for more information about configuring network devices and device aliases. Additional information can be found about network configuration scripts in Chapter 4, Network Interfaces.
Next, the DNS server for the FTP domains must be configured to reference the correct machine. For information about BIND and its configuration files, refer to Chapter 7, Berkeley Internet Name Domain (BIND).
For vsftpd to answer requests on different IP addresses, multiple copies of the daemon must be running. The first copy must be run using the vsftpd initscripts, as outlined in Section 12.4, “Starting and Stopping vsftpd. This copy uses the standard configuration file, /etc/vsftpd/vsftpd.conf.
Each additional FTP site must have a configuration file with a unique name in the /etc/vsftpd/ directory, such as /etc/vsftpd/vsftpd-site-2.conf. Each configuration file must be readable and writable only by root. Within each configuration file for each FTP server listening on an IPv4 network, the following directive must be unique:
listen_address=N.N.N.N 

Replace N.N.N.N with the unique IP address for the FTP site being served. If the site is using IPv6, use the listen_address6 directive instead.
Once each additional server has a configuration file, the vsftpd daemon must be launched from a root shell prompt using the following command:
vsftpd /etc/vsftpd/<configuration-file>  [amp   ]

In the above command, replace <configuration-file> with the unique name for the server's configuration file, such as /etc/vsftpd/vsftpd-site-2.conf.
Other directives to consider altering on a per-server basis are:
  • anon_root
  • local_root
  • vsftpd_log_file
  • xferlog_file
For a detailed list of directives available within vsftpd's configuration file, refer to Section 12.5, “ vsftpd Configuration Options”.
To configure any additional servers to start automatically at boot time, add the above command to the end of the /etc/rc.local file.

12.5.  vsftpd Configuration Options

Although vsftpd may not offer the level of customization other widely available FTP servers have, it offers enough options to fill most administrator's needs. The fact that it is not overly feature-laden limits configuration and programmatic errors.
All configuration of vsftpd is handled by its configuration file, /etc/vsftpd/vsftpd.conf. Each directive is on its own line within the file and follows the following format:
<directive>=<value>

For each directive, replace <directive> with a valid directive and <value> with a valid value.

Important

There must not be any spaces between the <directive>, equal symbol, and the <value> in a directive.
Comment lines must be preceded by a hash mark (#) and are ignored by the daemon.
For a complete list of all directives available, refer to the man page for vsftpd.conf.

Important

For an overview of ways to secure vsftpd, refer to .
The following is a list of some of the more important directives within /etc/vsftpd/vsftpd.conf. All directives not explicitly found within vsftpd's configuration file are set to their default value.

12.5.1. Daemon Options

The following is a list of directives which control the overall behavior of the vsftpd daemon.
  • listen — When enabled, vsftpd runs in stand-alone mode. Fedora sets this value to YES. This directive cannot be used in conjunction with the listen_ipv6 directive.
    The default value is NO.
  • listen_ipv6 — When enabled, vsftpd runs in stand-alone mode, but listens only to IPv6 sockets. This directive cannot be used in conjunction with the listen directive.
    The default value is NO.
  • session_support — When enabled, vsftpd attempts to maintain login sessions for each user through Pluggable Authentication Modules (PAM). Refer to for more information. If session logging is not necessary, disabling this option allows vsftpd to run with less processes and lower privileges.
    The default value is YES.

12.5.2. Log In Options and Access Controls

The following is a list of directives which control the login behavior and access control mechanisms.
  • anonymous_enable — When enabled, anonymous users are allowed to log in. The usernames anonymous and ftp are accepted.
    The default value is YES.
    Refer to Section 12.5.3, “Anonymous User Options” for a list of directives affecting anonymous users.
  • banned_email_file — If the deny_email_enable directive is set to YES, this directive specifies the file containing a list of anonymous email passwords which are not permitted access to the server.
    The default value is /etc/vsftpd.banned_emails.
  • banner_file — Specifies the file containing text displayed when a connection is established to the server. This option overrides any text specified in the ftpd_banner directive.
    There is no default value for this directive.
  • cmds_allowed — Specifies a comma-delimited list of FTP commands allowed by the server. All other commands are rejected.
    There is no default value for this directive.
  • deny_email_enable — When enabled, any anonymous user utilizing email passwords specified in the /etc/vsftpd.banned_emails are denied access to the server. The name of the file referenced by this directive can be specified using the banned_email_file directive.
    The default value is NO.
  • ftpd_banner — When enabled, the string specified within this directive is displayed when a connection is established to the server. This option can be overridden by the banner_file directive.
    By default vsftpd displays its standard banner.
  • local_enable — When enabled, local users are allowed to log into the system.
    The default value is YES.
    Refer to Section 12.5.4, “Local User Options” for a list of directives affecting local users.
  • pam_service_name — Specifies the PAM service name for vsftpd.
    The default value is ftp. Note, in Fedora, the value is set to vsftpd.
  • The default value is NO. Note, in Fedora, the value is set to YES.
  • userlist_deny — When used in conjunction with the userlist_enable directive and set to NO, all local users are denied access unless the username is listed in the file specified by the userlist_file directive. Because access is denied before the client is asked for a password, setting this directive to NO prevents local users from submitting unencrypted passwords over the network.
    The default value is YES.
  • userlist_enable — When enabled, the users listed in the file specified by the userlist_file directive are denied access. Because access is denied before the client is asked for a password, users are prevented from submitting unencrypted passwords over the network.
    The default value is NO, however under Fedora the value is set to YES.
  • userlist_file — Specifies the file referenced by vsftpd when the userlist_enable directive is enabled.
    The default value is /etc/vsftpd.user_list and is created during installation.

12.5.3. Anonymous User Options

The following lists directives which control anonymous user access to the server. To use these options, the anonymous_enable directive must be set to YES.
  • anon_mkdir_write_enable — When enabled in conjunction with the write_enable directive, anonymous users are allowed to create new directories within a parent directory which has write permissions.
    The default value is NO.
  • anon_root — Specifies the directory vsftpd changes to after an anonymous user logs in.
    There is no default value for this directive.
  • anon_upload_enable — When enabled in conjunction with the write_enable directive, anonymous users are allowed to upload files within a parent directory which has write permissions.
    The default value is NO.
  • anon_world_readable_only — When enabled, anonymous users are only allowed to download world-readable files.
    The default value is YES.
  • ftp_username — Specifies the local user account (listed in /etc/passwd) used for the anonymous FTP user. The home directory specified in /etc/passwd for the user is the root directory of the anonymous FTP user.
    The default value is ftp.
  • no_anon_password — When enabled, the anonymous user is not asked for a password.
    The default value is NO.
  • secure_email_list_enable — When enabled, only a specified list of email passwords for anonymous logins are accepted. This is a convenient way to offer limited security to public content without the need for virtual users.
    Anonymous logins are prevented unless the password provided is listed in /etc/vsftpd.email_passwords. The file format is one password per line, with no trailing white spaces.
    The default value is NO.

12.5.4. Local User Options

The following lists directives which characterize the way local users access the server. To use these options, the local_enable directive must be set to YES.
  • chmod_enable — When enabled, the FTP command SITE CHMOD is allowed for local users. This command allows the users to change the permissions on files.
    The default value is YES.
  • chroot_list_enable — When enabled, the local users listed in the file specified in the chroot_list_file directive are placed in a chroot jail upon log in.
    If enabled in conjunction with the chroot_local_user directive, the local users listed in the file specified in the chroot_list_file directive are not placed in a chroot jail upon log in.
    The default value is NO.
  • chroot_list_file — Specifies the file containing a list of local users referenced when the chroot_list_enable directive is set to YES.
    The default value is /etc/vsftpd.chroot_list.
  • chroot_local_user — When enabled, local users are change-rooted to their home directories after logging in.
    The default value is NO.

    Warning

    Enabling chroot_local_user opens up a number of security issues, especially for users with upload privileges. For this reason, it is not recommended.
  • guest_enable — When enabled, all non-anonymous users are logged in as the user guest, which is the local user specified in the guest_username directive.
    The default value is NO.
  • guest_username — Specifies the username the guest user is mapped to.
    The default value is ftp.
  • local_root — Specifies the directory vsftpd changes to after a local user logs in.
    There is no default value for this directive.
  • local_umask — Specifies the umask value for file creation. Note that the default value is in octal form (a numerical system with a base of eight), which includes a "0" prefix. Otherwise the value is treated as a base-10 integer.
    The default value is 022.
  • passwd_chroot_enable — When enabled in conjunction with the chroot_local_user directive, vsftpd change-roots local users based on the occurrence of the /./ in the home directory field within /etc/passwd.
    The default value is NO.
  • user_config_dir — Specifies the path to a directory containing configuration files bearing the name of local system users that contain specific setting for that user. Any directive in the user's configuration file overrides those found in /etc/vsftpd/vsftpd.conf.
    There is no default value for this directive.

12.5.5. Directory Options

The following lists directives which affect directories.
  • dirlist_enable — When enabled, users are allowed to view directory lists.
    The default value is YES.
  • dirmessage_enable — When enabled, a message is displayed whenever a user enters a directory with a message file. This message resides within the current directory. The name of this file is specified in the message_file directive and is .message by default.
    The default value is NO. Note, in Fedora, the value is set to YES.
  • force_dot_files — When enabled, files beginning with a dot (.) are listed in directory listings, with the exception of the . and .. files.
    The default value is NO.
  • hide_ids — When enabled, all directory listings show ftp as the user and group for each file.
    The default value is NO.
  • message_file — Specifies the name of the message file when using the dirmessage_enable directive.
    The default value is .message.
  • text_userdb_names — When enabled, test usernames and group names are used in place of UID and GID entries. Enabling this option may slow performance of the server.
    The default value is NO.
  • use_localtime — When enabled, directory listings reveal the local time for the computer instead of GMT.
    The default value is NO.

12.5.6. File Transfer Options

The following lists directives which affect directories.
  • download_enable — When enabled, file downloads are permitted.
    The default value is YES.
  • chown_uploads — When enabled, all files uploaded by anonymous users are owned by the user specified in the chown_username directive.
    The default value is NO.
  • chown_username — Specifies the ownership of anonymously uploaded files if the chown_uploads directive is enabled.
    The default value is root.
  • write_enable — When enabled, FTP commands which can change the file system are allowed, such as DELE, RNFR, and STOR.
    The default value is YES.

12.5.7. Logging Options

The following lists directives which affect vsftpd's logging behavior.
  • dual_log_enable — When enabled in conjunction with xferlog_enable, vsftpd writes two files simultaneously: a wu-ftpd-compatible log to the file specified in the xferlog_file directive (/var/log/xferlog by default) and a standard vsftpd log file specified in the vsftpd_log_file directive (/var/log/vsftpd.log by default).
    The default value is NO.
  • log_ftp_protocol — When enabled in conjunction with xferlog_enable and with xferlog_std_format set to NO, all FTP commands and responses are logged. This directive is useful for debugging.
    The default value is NO.
  • syslog_enable — When enabled in conjunction with xferlog_enable, all logging normally written to the standard vsftpd log file specified in the vsftpd_log_file directive (/var/log/vsftpd.log by default) is sent to the system logger instead under the FTPD facility.
    The default value is NO.
  • vsftpd_log_file — Specifies the vsftpd log file. For this file to be used, xferlog_enable must be enabled and xferlog_std_format must either be set to NO or, if xferlog_std_format is set to YES, dual_log_enable must be enabled. It is important to note that if syslog_enable is set to YES, the system log is used instead of the file specified in this directive.
    The default value is /var/log/vsftpd.log.
  • xferlog_enable — When enabled, vsftpd logs connections (vsftpd format only) and file transfer information to the log file specified in the vsftpd_log_file directive (/var/log/vsftpd.log by default). If xferlog_std_format is set to YES, file transfer information is logged but connections are not, and the log file specified in xferlog_file (/var/log/xferlog by default) is used instead. It is important to note that both log files and log formats are used if dual_log_enable is set to YES.
    The default value is NO. Note, in Fedora, the value is set to YES.
  • xferlog_file — Specifies the wu-ftpd-compatible log file. For this file to be used, xferlog_enable must be enabled and xferlog_std_format must be set to YES. It is also used if dual_log_enable is set to YES.
    The default value is /var/log/xferlog.
  • xferlog_std_format — When enabled in conjunction with xferlog_enable, only a wu-ftpd-compatible file transfer log is written to the file specified in the xferlog_file directive (/var/log/xferlog by default). It is important to note that this file only logs file transfers and does not log connections to the server.
    The default value is NO. Note, in Fedora, the value is set to YES.

Important

To maintain compatibility with log files written by the older wu-ftpd FTP server, the xferlog_std_format directive is set to YES under Fedora. However, this setting means that connections to the server are not logged.
To both log connections in vsftpd format and maintain a wu-ftpd-compatible file transfer log, set dual_log_enable to YES.
If maintaining a wu-ftpd-compatible file transfer log is not important, either set xferlog_std_format to NO, comment the line with a hash mark (#), or delete the line entirely.

12.5.8. Network Options

The following lists directives which affect how vsftpd interacts with the network.
  • accept_timeout — Specifies the amount of time for a client using passive mode to establish a connection.
    The default value is 60.
  • anon_max_rate — Specifies the maximum data transfer rate for anonymous users in bytes per second.
    The default value is 0, which does not limit the transfer rate.
  • connect_from_port_20 When enabled, vsftpd runs with enough privileges to open port 20 on the server during active mode data transfers. Disabling this option allows vsftpd to run with less privileges, but may be incompatible with some FTP clients.
    The default value is NO. Note, in Fedora, the value is set to YES.
  • connect_timeout — Specifies the maximum amount of time a client using active mode has to respond to a data connection, in seconds.
    The default value is 60.
  • data_connection_timeout — Specifies maximum amount of time data transfers are allowed to stall, in seconds. Once triggered, the connection to the remote client is closed.
    The default value is 300.
  • ftp_data_port — Specifies the port used for active data connections when connect_from_port_20 is set to YES.
    The default value is 20.
  • idle_session_timeout — Specifies the maximum amount of time between commands from a remote client. Once triggered, the connection to the remote client is closed.
    The default value is 300.
  • listen_address — Specifies the IP address on which vsftpd listens for network connections.
    There is no default value for this directive.

    Tip

    If running multiple copies of vsftpd serving different IP addresses, the configuration file for each copy of the vsftpd daemon must have a different value for this directive. Refer to Section 12.4.1, “Starting Multiple Copies of vsftpd for more information about multihomed FTP servers.
  • listen_address6 — Specifies the IPv6 address on which vsftpd listens for network connections when listen_ipv6 is set to YES.
    There is no default value for this directive.

    Tip

    If running multiple copies of vsftpd serving different IP addresses, the configuration file for each copy of the vsftpd daemon must have a different value for this directive. Refer to Section 12.4.1, “Starting Multiple Copies of vsftpd for more information about multihomed FTP servers.
  • listen_port — Specifies the port on which vsftpd listens for network connections.
    The default value is 21.
  • local_max_rate — Specifies the maximum rate data is transferred for local users logged into the server in bytes per second.
    The default value is 0, which does not limit the transfer rate.
  • max_clients — Specifies the maximum number of simultaneous clients allowed to connect to the server when it is running in standalone mode. Any additional client connections would result in an error message.
    The default value is 0, which does not limit connections.
  • max_per_ip — Specifies the maximum of clients allowed to connected from the same source IP address.
    The default value is 0, which does not limit connections.
  • pasv_address — Specifies the IP address for the public facing IP address of the server for servers behind Network Address Translation (NAT) firewalls. This enables vsftpd to hand out the correct return address for passive mode connections.
    There is no default value for this directive.
  • pasv_enable — When enabled, passive mode connects are allowed.
    The default value is YES.
  • pasv_max_port — Specifies the highest possible port sent to the FTP clients for passive mode connections. This setting is used to limit the port range so that firewall rules are easier to create.
    The default value is 0, which does not limit the highest passive port range. The value must not exceed 65535.
  • pasv_min_port — Specifies the lowest possible port sent to the FTP clients for passive mode connections. This setting is used to limit the port range so that firewall rules are easier to create.
    The default value is 0, which does not limit the lowest passive port range. The value must not be lower 1024.
  • pasv_promiscuous — When enabled, data connections are not checked to make sure they are originating from the same IP address. This setting is only useful for certain types of tunneling.

    Caution

    Do not enable this option unless absolutely necessary as it disables an important security feature which verifies that passive mode connections originate from the same IP address as the control connection that initiates the data transfer.
    The default value is NO.
  • port_enable — When enabled, active mode connects are allowed.
    The default value is YES.

12.6. Additional Resources

For more information about vsftpd, refer to the following resources.

12.6.1. Installed Documentation

  • The /usr/share/doc/vsftpd-<version-number>/ directory — Replace <version-number> with the installed version of the vsftpd package. This directory contains a README with basic information about the software. The TUNING file contains basic performance tuning tips and the SECURITY/ directory contains information about the security model employed by vsftpd.
  • vsftpd related man pages — There are a number of man pages for the daemon and configuration files. The following lists some of the more important man pages.
    Server Applications
    • man vsftpd — Describes available command line options for vsftpd.
    Configuration Files
    • man vsftpd.conf — Contains a detailed list of options available within the configuration file for vsftpd.
    • man 5 hosts_access — Describes the format and options available within the TCP wrappers configuration files: hosts.allow and hosts.deny.

12.6.2. Useful Websites

Chapter 13. Email

The birth of electronic mail (email) occurred in the early 1960s. The mailbox was a file in a user's home directory that was readable only by that user. Primitive mail applications appended new text messages to the bottom of the file, making the user wade through the constantly growing file to find any particular message. This system was only capable of sending messages to users on the same system.
The first network transfer of an electronic mail message file took place in 1971 when a computer engineer named Ray Tomlinson sent a test message between two machines via ARPANET — the precursor to the Internet. Communication via email soon became very popular, comprising 75 percent of ARPANET's traffic in less than two years.
Today, email systems based on standardized network protocols have evolved into some of the most widely used services on the Internet. Fedora offers many advanced applications to serve and access email.
This chapter reviews modern email protocols in use today and some of the programs designed to send and receive email.

13.1. Email Protocols

Today, email is delivered using a client/server architecture. An email message is created using a mail client program. This program then sends the message to a server. The server then forwards the message to the recipient's email server, where the message is then supplied to the recipient's email client.
To enable this process, a variety of standard network protocols allow different machines, often running different operating systems and using different email programs, to send and receive email.
The following protocols discussed are the most commonly used in the transfer of email.

13.1.1. Mail Transport Protocols

Mail delivery from a client application to the server, and from an originating server to the destination server, is handled by the Simple Mail Transfer Protocol (SMTP).

13.1.1.1. SMTP

The primary purpose of SMTP is to transfer email between mail servers. However, it is critical for email clients as well. To send email, the client sends the message to an outgoing mail server, which in turn contacts the destination mail server for delivery. For this reason, it is necessary to specify an SMTP server when configuring an email client.
Under Fedora, a user can configure an SMTP server on the local machine to handle mail delivery. However, it is also possible to configure remote SMTP servers for outgoing mail.
One important point to make about the SMTP protocol is that it does not require authentication. This allows anyone on the Internet to send email to anyone else or even to large groups of people. It is this characteristic of SMTP that makes junk email or spam possible. Imposing relay restrictions limits random users on the Internet from sending email through your SMTP server, to other servers on the internet. Servers that do not impose such restrictions are called open relay servers.
Fedora provides the Postfix, Sendmail and Exim SMTP programs.

13.1.2. Mail Access Protocols

There are two primary protocols used by email client applications to retrieve email from mail servers: the Post Office Protocol (POP) and the Internet Message Access Protocol (IMAP).

13.1.2.1. POP

The default POP server under Fedora is /usr/lib/cyrus-imapd/pop3d and is provided by the cyrus-imapd package. When using a POP server, email messages are downloaded by email client applications. By default, most POP email clients are automatically configured to delete the message on the email server after it has been successfully transferred, however this setting usually can be changed.
POP is fully compatible with important Internet messaging standards, such as Multipurpose Internet Mail Extensions (MIME), which allow for email attachments.
POP works best for users who have one system on which to read email. It also works well for users who do not have a persistent connection to the Internet or the network containing the mail server. Unfortunately for those with slow network connections, POP requires client programs upon authentication to download the entire content of each message. This can take a long time if any messages have large attachments.
The most current version of the standard POP protocol is POP3.
There are, however, a variety of lesser-used POP protocol variants:
  • APOP — POP3 with MDS authentication. An encoded hash of the user's password is sent from the email client to the server rather then sending an unencrypted password.
  • KPOP — POP3 with Kerberos authentication. Refer to for more information.
  • RPOP — POP3 with RPOP authentication. This uses a per-user ID, similar to a password, to authenticate POP requests. However, this ID is not encrypted, so RPOP is no more secure than standard POP.
For added security, it is possible to use Secure Socket Layer (SSL) encryption for client authentication and data transfer sessions. This can be enabled by using the ipop3s service or by using the /usr/sbin/stunnel program. Refer to Section 13.6.1, “Securing Communication” for more information.

13.1.2.2. IMAP

The default IMAP server under Fedora is /usr/lib/cyrus-imapd/imapd and is provided by the cyrus-imapd package. When using an IMAP mail server, email messages remain on the server where users can read or delete them. IMAP also allows client applications to create, rename, or delete mail directories on the server to organize and store email.
IMAP is particularly useful for those who access their email using multiple machines. The protocol is also convenient for users connecting to the mail server via a slow connection, because only the email header information is downloaded for messages until opened, saving bandwidth. The user also has the ability to delete messages without viewing or downloading them.
For convenience, IMAP client applications are capable of caching copies of messages locally, so the user can browse previously read messages when not directly connected to the IMAP server.
IMAP, like POP, is fully compatible with important Internet messaging standards, such as MIME, which allow for email attachments.
For added security, it is possible to use SSL encryption for client authentication and data transfer sessions. This can be enabled by using the imaps service, or by using the /usr/sbin/stunnel program. Refer to Section 13.6.1, “Securing Communication” for more information.
Other free, as well as commercial, IMAP clients and servers are available, many of which extend the IMAP protocol and provide additional functionality. A comprehensive list can be found online at http://www.imap.org/products/longlist.htm.

13.1.2.3. Dovecot

The imap-login and pop3-login daemons which implement the IMAP and POP3 protocols are included in the dovecot package. The use of IMAP and POP is configured through dovecot; by default dovecot runs only IMAP. To configure dovecot to use POP:
  1. Edit /etc/dovecot.conf to have the line:
    protocols = imap imaps pop3 pop3s
    
    
  2. Make that change operational for the current session by running the command:
    /sbin/service dovecot restart
    
    
  3. Make that change operational after the next reboot by running the command:
    chkconfig dovecot on
    
    
    Please note that dovecot only reports that it started the IMAP server, but also starts the POP3 server.
Unlike SMTP, both of these protocols require connecting clients to authenticate using a username and password. By default, passwords for both protocols are passed over the network unencrypted.
To configure SSL on dovecot:
  • Edit the dovecot configuration file /etc/pki/dovecot/dovecot-openssl.conf as you prefer. However in a typical installation, this file does not require modification.
  • Rename, move or delete the files /etc/pki/dovecot/certs/dovecot.pem and /etc/pki/dovecot/private/dovecot.pem.
  • Execute the /usr/share/doc/dovecot-1.0/examples/mkcert.sh script which creates the dovecot self signed certificates. The certificates are copied in the /etc/pki/dovecot/certs and /etc/pki/dovecot/private directories. To implement the changes, restart dovecot (/sbin/service dovecot restart).
More details on dovecot can be found online at http://www.dovecot.org.

13.2. Email Program Classifications

In general, all email applications fall into at least one of three classifications. Each classification plays a specific role in the process of moving and managing email messages. While most users are only aware of the specific email program they use to receive and send messages, each one is important for ensuring that email arrives at the correct destination.

13.2.1. Mail Transport Agent

A Mail Transport Agent (MTA) transports email messages between hosts using SMTP. A message may involve several MTAs as it moves to its intended destination.
While the delivery of messages between machines may seem rather straightforward, the entire process of deciding if a particular MTA can or should accept a message for delivery is quite complicated. In addition, due to problems from spam, use of a particular MTA is usually restricted by the MTA's configuration or the access configuration for the network on which the MTA resides.
Many modern email client programs can act as an MTA when sending email. However, this action should not be confused with the role of a true MTA. The sole reason email client programs are capable of sending email like an MTA is because the host running the application does not have its own MTA. This is particularly true for email client programs on non-UNIX-based operating systems. However, these client programs only send outbound messages to an MTA they are authorized to use and do not directly deliver the message to the intended recipient's email server.
Since Fedora installs three MTAs—Sendmail, Postfix and Exim—email client programs are often not required to act as an MTA. Fedora also includes a special purpose MTA called Fetchmail.
For more information on Sendmail, Postfix, and Fetchmail, refer to Section 13.3, “Mail Transport Agents”.

13.2.2. Mail Delivery Agent

A Mail Delivery Agent (MDA) is invoked by the MTA to file incoming email in the proper user's mailbox. In many cases, the MDA is actually a Local Delivery Agent (LDA), such as mail or Procmail.
Any program that actually handles a message for delivery to the point where it can be read by an email client application can be considered an MDA. For this reason, some MTAs (such as Sendmail and Postfix) can fill the role of an MDA when they append new email messages to a local user's mail spool file. In general, MDAs do not transport messages between systems nor do they provide a user interface; MDAs distribute and sort messages on the local machine for an email client application to access.

13.2.3. Mail User Agent

A Mail User Agent (MUA) is synonymous with an email client application. An MUA is a program that, at the very least, allows a user to read and compose email messages. Many MUAs are capable of retrieving messages via the POP or IMAP protocols, setting up mailboxes to store messages, and sending outbound messages to an MTA.
MUAs may be graphical, such as Evolution, or have simple text-based interfaces, such as pine.

13.3. Mail Transport Agents

Fedora includes three primary MTAs: Sendmail, Postfix and Exim. Sendmail is configured as the default MTA, although it is easy to switch the default MTA to Postfix or Exim.

13.3.1. Sendmail

Sendmail's core purpose, like other MTAs, is to safely transfer email among hosts, usually using the SMTP protocol. However, Sendmail is highly configurable, allowing control over almost every aspect of how email is handled, including the protocol used. Many system administrators elect to use Sendmail as their MTA due to its power and scalability.

13.3.1.1. Purpose and Limitations

It is important to be aware of what Sendmail is and what it can do, as opposed to what it is not. In these days of monolithic applications that fulfill multiple roles, Sendmail may seem like the only application needed to run an email server within an organization. Technically, this is true, as Sendmail can spool mail to each users' directory and deliver outbound mail for users. However, most users actually require much more than simple email delivery. Users usually want to interact with their email using an MUA, that uses POP or IMAP, to download their messages to their local machine. Or, they may prefer a Web interface to gain access to their mailbox. These other applications can work in conjunction with Sendmail, but they actually exist for different reasons and can operate separately from one another.
It is beyond the scope of this section to go into all that Sendmail should or could be configured to do. With literally hundreds of different options and rule sets, entire volumes have been dedicated to helping explain everything that can be done and how to fix things that go wrong. Refer to the Section 13.7, “Additional Resources” for a list of Sendmail resources.
This section reviews the files installed with Sendmail by default and reviews basic configuration changes, including how to stop unwanted email (spam) and how to extend Sendmail with the Lightweight Directory Access Protocol (LDAP).

13.3.1.2. The Default Sendmail Installation

The Sendmail executable is /usr/sbin/sendmail.
Sendmail's lengthy and detailed configuration file is /etc/mail/sendmail.cf. Avoid editing the sendmail.cf file directly. To make configuration changes to Sendmail, edit the /etc/mail/sendmail.mc file, back up the original /etc/mail/sendmail.cf, and use the following alternatives to generate a new configuration file:
  • Use the included makefile in /etc/mail (make all -C /etc/mail) to create a new /etc/mail/sendmail.cf configuration file. All other generated files in /etc/mail (db files) will be regenerated if needed. The old makemap commands are still usable. The make command will automatically be used by service sendmail start | restart | reload if the make package is installed.
  • Alternatively you may use the included m4 macro processor to create a new /etc/mail/sendmail.cf.
More information on configuring Sendmail can be found in Section 13.3.1.3, “Common Sendmail Configuration Changes”.
Various Sendmail configuration files are installed in the /etc/mail/ directory including:
  • access — Specifies which systems can use Sendmail for outbound email.
  • domaintable — Specifies domain name mapping.
  • local-host-names — Specifies aliases for the host.
  • mailertable — Specifies instructions that override routing for particular domains.
  • virtusertable — Specifies a domain-specific form of aliasing, allowing multiple virtual domains to be hosted on one machine.
Several of the configuration files in /etc/mail/, such as access, domaintable, mailertable and virtusertable, must actually store their information in database files before Sendmail can use any configuration changes. To include any changes made to these configurations in their database files, run the following command:
makemap hash /etc/mail/<name> < /etc/mail/<name>
where <name> is replaced with the name of the configuration file to convert.
For example, to have all emails addressed to the example.com domain delivered to , add the following line to the virtusertable file:
@example.com bob@other-example.com

To finalize the change, the virtusertable.db file must be updated using the following command as root:
makemap hash /etc/mail/virtusertable < /etc/mail/virtusertable

This creates an updated virtusertable.db file containing the new configuration.

13.3.1.3. Common Sendmail Configuration Changes

When altering the Sendmail configuration file, it is best not to edit an existing file, but to generate an entirely new /etc/mail/sendmail.cf file.

Caution

Before changing the sendmail.cf file, it is a good idea to create a backup copy.
To add the desired functionality to Sendmail, edit the /etc/mail/sendmail.mc file as the root user. When finished, use the m4 macro processor to generate a new sendmail.cf by executing the following command:
m4 /etc/mail/sendmail.mc > /etc/mail/sendmail.cf

By default, the m4 macro processor is installed with Sendmail but is part of the m4 package.
After creating a new /etc/mail/sendmail.cf file, restart Sendmail for the changes to take effect. The easiest way to do this is to type the following command:
/sbin/service sendmail restart

Important

The default sendmail.cf file does not allow Sendmail to accept network connections from any host other than the local computer. To configure Sendmail as a server for other clients, edit the /etc/mail/sendmail.mc file, and either change the address specified in the Addr= option of the DAEMON_OPTIONS directive from 127.0.0.1 to the IP address of an active network device or comment out the DAEMON_OPTIONS directive all together by placing dnl at the beginning of the line. When finished, regenerate /etc/mail/sendmail.cf by executing the following command:
m4 /etc/mail/sendmail.mc > /etc/mail/sendmail.cf

The default configuration which ships with Fedora works for most SMTP-only sites. However, it does not work for UUCP (UNIX to UNIX Copy) sites. If using UUCP mail transfers, the /etc/mail/sendmail.mc file must be reconfigured and a new /etc/mail/sendmail.cf must be generated.
Consult the /usr/share/sendmail-cf/README file before editing any files in the directories under the /usr/share/sendmail-cf directory, as they can affect the future configuration of /etc/mail/sendmail.cf files.

13.3.1.4. Masquerading

One common Sendmail configuration is to have a single machine act as a mail gateway for all machines on the network. For instance, a company may want to have a machine called mail.example.com that handles all of their email and assigns a consistent return address to all outgoing mail.
In this situation, the Sendmail server must masquerade the machine names on the company network so that their return address is user@example.com instead of user@host.example.com.
To do this, add the following lines to /etc/mail/sendmail.mc:
FEATURE(always_add_domain)dnl
FEATURE(`masquerade_entire_domain')dnl
FEATURE(`masquerade_envelope')dnl
FEATURE(`allmasquerade')dnl
MASQUERADE_AS(`bigcorp.com.')dnl
MASQUERADE_DOMAIN(`bigcorp.com.')dnl
MASQUERADE_AS(bigcorp.com)dnl

After generating a new sendmail.cf using m4, this configuration makes all mail from inside the network appear as if it were sent from bigcorp.com.

13.3.1.5. Stopping Spam

Email spam can be defined as unnecessary and unwanted email received by a user who never requested the communication. It is a disruptive, costly, and widespread abuse of Internet communication standards.
Sendmail makes it relatively easy to block new spamming techniques being employed to send junk email. It even blocks many of the more usual spamming methods by default. Main anti-spam features available in sendmail are header checks, relaying denial (default from version 8.9), access database and sender information checks.
For example, forwarding of SMTP messages, also called relaying, has been disabled by default since Sendmail version 8.9. Before this change occurred, Sendmail directed the mail host (x.edu) to accept messages from one party (y.com) and sent them to a different party (z.net). Now, however, Sendmail must be configured to permit any domain to relay mail through the server. To configure relay domains, edit the /etc/mail/relay-domains file and restart Sendmail.
However, many times users are bombarded with spam from other servers throughout the Internet. In these instances, Sendmail's access control features available through the /etc/mail/access file can be used to prevent connections from unwanted hosts. The following example illustrates how this file can be used to both block and specifically allow access to the Sendmail server:
badspammer.com ERROR:550 "Go away and do not spam us anymore" tux.badspammer.com OK 10.0 RELAY

This example shows that any email sent from badspammer.com is blocked with a 550 RFC-821 compliant error code, with a message sent back to the spammer. Email sent from the tux.badspammer.com sub-domain, is accepted. The last line shows that any email sent from the 10.0.*.* network can be relayed through the mail server.
Because /etc/mail/access.db is a database, use makemap to activate any changes. Do this using the following command as root:
makemap hash /etc/mail/access < /etc/mail/access

Message header analysis allows you to reject mail based on header contents. SMTP servers store information about an emails journey in the message header. As the message travels from one MTA to another, each puts in a "Received" header above all the other Received headers. It is however important to note that this information may be altered by spammers.
The above examples only represent a small part of what Sendmail can do in terms of allowing or blocking access. Refer to the /usr/share/sendmail-cf/README for more information and examples.
Since Sendmail calls the Procmail MDA when delivering mail, it is also possible to use a spam filtering program, such as SpamAssassin, to identify and file spam for users. Refer to Section 13.5.2.6, “Spam Filters” for more about using SpamAssassin.

13.3.1.6. Using Sendmail with LDAP

Using the Lightweight Directory Access Protocol (LDAP) is a very quick and powerful way to find specific information about a particular user from a much larger group. For example, an LDAP server can be used to look up a particular email address from a common corporate directory by the user's last name. In this kind of implementation, LDAP is largely separate from Sendmail, with LDAP storing the hierarchical user information and Sendmail only being given the result of LDAP queries in pre-addressed email messages.
However, Sendmail supports a much greater integration with LDAP, where it uses LDAP to replace separately maintained files, such as aliases and virtusertables, on different mail servers that work together to support a medium- to enterprise-level organization. In short, LDAP abstracts the mail routing level from Sendmail and its separate configuration files to a powerful LDAP cluster that can be leveraged by many different applications.
The current version of Sendmail contains support for LDAP. To extend the Sendmail server using LDAP, first get an LDAP server, such as OpenLDAP, running and properly configured. Then edit the /etc/mail/sendmail.mc to include the following:
LDAPROUTE_DOMAIN('yourdomain.com')dnl
FEATURE('ldap_routing')dnl

Note

This is only for a very basic configuration of Sendmail with LDAP. The configuration can differ greatly from this depending on the implementation of LDAP, especially when configuring several Sendmail machines to use a common LDAP server.
Consult /usr/share/sendmail-cf/README for detailed LDAP routing configuration instructions and examples.
Next, recreate the /etc/mail/sendmail.cf file by running m4 and restarting Sendmail. Refer to Section 13.3.1.3, “Common Sendmail Configuration Changes” for instructions.
For more information on LDAP, refer to Chapter 14, Lightweight Directory Access Protocol (LDAP).

13.3.2. Postfix

Originally developed at IBM by security expert and programmer Wietse Venema, Postfix is a Sendmail-compatible MTA that is designed to be secure, fast, and easy to configure.
To improve security, Postfix uses a modular design, where small processes with limited privileges are launched by a master daemon. The smaller, less privileged processes perform very specific tasks related to the various stages of mail delivery and run in a change rooted environment to limit the effects of attacks.
Configuring Postfix to accept network connections from hosts other than the local computer takes only a few minor changes in its configuration file. Yet for those with more complex needs, Postfix provides a variety of configuration options, as well as third party add ons that make it a very versatile and full-featured MTA.
The configuration files for Postfix are human readable and support upward of 250 directives. Unlike Sendmail, no macro processing is required for changes to take effect and the majority of the most commonly used options are described in the heavily commented files.

Important

Before using Postfix or Exim, the default MTA must be switched from Sendmail to the desired MTA.

13.3.2.1. The Default Postfix Installation

The Postfix executable is /usr/sbin/postfix. This daemon launches all related processes needed to handle mail delivery.
Postfix stores its configuration files in the /etc/postfix/ directory. The following is a list of the more commonly used files:
  • access — Used for access control, this file specifies which hosts are allowed to connect to Postfix.
  • aliases — A configurable list required by the mail protocol.
  • main.cf — The global Postfix configuration file. The majority of configuration options are specified in this file.
  • master.cf — Specifies how Postfix interacts with various processes to accomplish mail delivery.
  • transport — Maps email addresses to relay hosts.

Important

The default /etc/postfix/main.cf file does not allow Postfix to accept network connections from a host other than the local computer. For instructions on configuring Postfix as a server for other clients, refer to Section 13.3.2.2, “Basic Postfix Configuration”.
When changing some options within files in the /etc/postfix/ directory, it may be necessary to restart the postfix service for the changes to take effect. The easiest way to do this is to type the following command:
/sbin/service postfix restart

13.3.2.2. Basic Postfix Configuration

By default, Postfix does not accept network connections from any host other than the local host. Perform the following steps as root to enable mail delivery for other hosts on the network:
  • Edit the /etc/postfix/main.cf file with a text editor, such as vi.
  • Uncomment the mydomain line by removing the hash mark (#), and replace domain.tld with the domain the mail server is servicing, such as example.com.
  • Uncomment the myorigin = $mydomain line.
  • Uncomment the myhostname line, and replace host.domain.tld with the hostname for the machine.
  • Uncomment the mydestination = $myhostname, localhost.$mydomain line.
  • Uncomment the mynetworks line, and replace 168.100.189.0/28 with a valid network setting for hosts that can connect to the server.
  • Uncomment the inet_interfaces = all line.
  • Comment the inet_interfaces = localhost line.
  • Restart the postfix service.
Once these steps are complete, the host accepts outside emails for delivery.
Postfix has a large assortment of configuration options. One of the best ways to learn how to configure Postfix is to read the comments within /etc/postfix/main.cf. Additional resources including information about LDAP and SpamAssassin integration are available online at http://www.postfix.org/.

13.3.3. Fetchmail

Fetchmail is an MTA which retrieves email from remote servers and delivers it to the local MTA. Many users appreciate the ability to separate the process of downloading their messages located on a remote server from the process of reading and organizing their email in an MUA. Designed with the needs of dial-up users in mind, Fetchmail connects and quickly downloads all of the email messages to the mail spool file using any number of protocols, including POP3 and IMAP. It can even forward email messages to an SMTP server, if necessary.
Fetchmail is configured for each user through the use of a .fetchmailrc file in the user's home directory.
Using preferences in the .fetchmailrc file, Fetchmail checks for email on a remote server and downloads it. It then delivers it to port 25 on the local machine, using the local MTA to place the email in the correct user's spool file. If Procmail is available, it is launched to filter the email and place it in a mailbox so that it can be read by an MUA.

13.3.3.1. Fetchmail Configuration Options

Although it is possible to pass all necessary options on the command line to check for email on a remote server when executing Fetchmail, using a .fetchmailrc file is much easier. Place any desired configuration options in the .fetchmailrc file for those options to be used each time the fetchmail command is issued. It is possible to override these at the time Fetchmail is run by specifying that option on the command line.
A user's .fetchmailrc file contains three classes of configuration options:
  • global options — Gives Fetchmail instructions that control the operation of the program or provide settings for every connection that checks for email.
  • server options — Specifies necessary information about the server being polled, such as the hostname, as well as preferences for specific email servers, such as the port to check or number of seconds to wait before timing out. These options affect every user using that server.
  • user options — Contains information, such as username and password, necessary to authenticate and check for email using a specified email server.
Global options appear at the top of the .fetchmailrc file, followed by one or more server options, each of which designate a different email server that Fetchmail should check. User options follow server options for each user account checking that email server. Like server options, multiple user options may be specified for use with a particular server as well as to check multiple email accounts on the same server.
Server options are called into service in the .fetchmailrc file by the use of a special option verb, poll or skip, that precedes any of the server information. The poll action tells Fetchmail to use this server option when it is run, which checks for email using the specified user options. Any server options after a skip action, however, are not checked unless this server's hostname is specified when Fetchmail is invoked. The skip option is useful when testing configurations in .fetchmailrc because it only checks skipped servers when specifically invoked, and does not affect any currently working configurations.
A sample .fetchmailrc file looks similar to the following example:
set postmaster "user1" set bouncemail poll pop.domain.com proto pop3 user 'user1' there with password 'secret' is user1 here poll mail.domain2.com user 'user5' there with password 'secret2' is user1 here user 'user7' there with password 'secret3' is user1 here

In this example, the global options specify that the user is sent email as a last resort (postmaster option) and all email errors are sent to the postmaster instead of the sender (bouncemail option). The set action tells Fetchmail that this line contains a global option. Then, two email servers are specified, one set to check using POP3, the other for trying various protocols to find one that works. Two users are checked using the second server option, but all email found for any user is sent to user1's mail spool. This allows multiple mailboxes to be checked on multiple servers, while appearing in a single MUA inbox. Each user's specific information begins with the user action.

Note

Users are not required to place their password in the .fetchmailrc file. Omitting the with password '<password>' section causes Fetchmail to ask for a password when it is launched.
Fetchmail has numerous global, server, and local options. Many of these options are rarely used or only apply to very specific situations. The fetchmail man page explains each option in detail, but the most common ones are listed here.

13.3.3.2. Global Options

Each global option should be placed on a single line after a set action.
  • daemon <seconds> — Specifies daemon-mode, where Fetchmail stays in the background. Replace <seconds> with the number of seconds Fetchmail is to wait before polling the server.
  • postmaster — Specifies a local user to send mail to in case of delivery problems.
  • syslog — Specifies the log file for errors and status messages. By default, this is /var/log/maillog.

13.3.3.3. Server Options

Server options must be placed on their own line in .fetchmailrc after a poll or skip action.
  • auth <auth-type> — Replace <auth-type> with the type of authentication to be used. By default, password authentication is used, but some protocols support other types of authentication, including kerberos_v5, kerberos_v4, and ssh. If the any authentication type is used, Fetchmail first tries methods that do not require a password, then methods that mask the password, and finally attempts to send the password unencrypted to authenticate to the server.
  • interval <number> — Polls the specified server every <number> of times that it checks for email on all configured servers. This option is generally used for email servers where the user rarely receives messages.
  • port <port-number> — Replace <port-number> with the port number. This value overrides the default port number for the specified protocol.
  • proto <protocol> — Replace <protocol> with the protocol, such as pop3 or imap, to use when checking for messages on the server.
  • timeout <seconds> — Replace <seconds> with the number of seconds of server inactivity after which Fetchmail gives up on a connection attempt. If this value is not set, a default of 300 seconds is assumed.

13.3.3.4. User Options

User options may be placed on their own lines beneath a server option or on the same line as the server option. In either case, the defined options must follow the user option (defined below).
  • fetchall — Orders Fetchmail to download all messages in the queue, including messages that have already been viewed. By default, Fetchmail only pulls down new messages.
  • fetchlimit <number> — Replace <number> with the number of messages to be retrieved before stopping.
  • flush — Deletes all previously viewed messages in the queue before retrieving new messages.
  • limit <max-number-bytes> — Replace <max-number-bytes> with the maximum size in bytes that messages are allowed to be when retrieved by Fetchmail. This option is useful with slow network links, when a large message takes too long to download.
  • password '<password>' — Replace <password> with the user's password.
  • preconnect "<command>" — Replace <command> with a command to be executed before retrieving messages for the user.
  • postconnect "<command>" — Replace <command> with a command to be executed after retrieving messages for the user.
  • ssl — Activates SSL encryption.
  • user "<username>" — Replace <username> with the username used by Fetchmail to retrieve messages. This option must precede all other user options.

13.3.3.5. Fetchmail Command Options

Most Fetchmail options used on the command line when executing the fetchmail command mirror the .fetchmailrc configuration options. In this way, Fetchmail may be used with or without a configuration file. These options are not used on the command line by most users because it is easier to leave them in the .fetchmailrc file.
There may be times when it is desirable to run the fetchmail command with other options for a particular purpose. It is possible to issue command options to temporarily override a .fetchmailrc setting that is causing an error, as any options specified at the command line override configuration file options.

13.3.3.6. Informational or Debugging Options

Certain options used after the fetchmail command can supply important information.
  • --configdump — Displays every possible option based on information from .fetchmailrc and Fetchmail defaults. No email is retrieved for any users when using this option.
  • -s — Executes Fetchmail in silent mode, preventing any messages, other than errors, from appearing after the fetchmail command.
  • -v — Executes Fetchmail in verbose mode, displaying every communication between Fetchmail and remote email servers.
  • -V — Displays detailed version information, lists its global options, and shows settings to be used with each user, including the email protocol and authentication method. No email is retrieved for any users when using this option.

13.3.3.7. Special Options

These options are occasionally useful for overriding defaults often found in the .fetchmailrc file.
  • -a — Fetchmail downloads all messages from the remote email server, whether new or previously viewed. By default, Fetchmail only downloads new messages.
  • -k — Fetchmail leaves the messages on the remote email server after downloading them. This option overrides the default behavior of deleting messages after downloading them.
  • -l <max-number-bytes> — Fetchmail does not download any messages over a particular size and leaves them on the remote email server.
  • --quit — Quits the Fetchmail daemon process.
More commands and .fetchmailrc options can be found in the fetchmail man page.

13.4. Mail Transport Agent (MTA) Configuration

A Mail Transport Agent (MTA) is essential for sending email. A Mail User Agent (MUA) such as Evolution, Thunderbird, and Mutt, is used to read and compose email. When a user sends an email from an MUA, the message is handed off to the MTA, which sends the message through a series of MTAs until it reaches its destination.
Even if a user does not plan to send email from the system, some automated tasks or system programs might use the /bin/mail command to send email containing log messages to the root user of the local system.
Fedora 12 provides three MTAs: Sendmail, Postfix, and Exim. If all three are installed, sendmail is the default MTA. The Mail Transport Agent Switcher allows for the selection of either sendmail, postfix, or exim as the default MTA for the system.
The system-switch-mail RPM package must be installed to use the text-based version of the Mail Transport Agent Switcher program. If you want to use the graphical version, the system-switch-mail-gnome package must also be installed.

Note

For more information on installing RPM packages, refer to Part I, “Package Management”.
To start the Mail Transport Agent Switcher, select System (the main menu on the panel) > Administration > Mail Transport Agent Switcher, or type the command system-switch-mail at a shell prompt (for example, in an XTerm or GNOME terminal).
The program automatically detects if the X Window System is running. If it is running, the program starts in graphical mode as shown in Figure 13.1, “ Mail Transport Agent Switcher. If X is not detected, it starts in text-mode. To force Mail Transport Agent Switcher to run in text-mode, use the command system-switch-mail-nox.
Mail Transport Agent Switcher
Screenshot of Mail Transport Agent Switcher
Figure 13.1.  Mail Transport Agent Switcher

If you select OK to change the MTA, the selected mail daemon is enabled to start at boot time, and the unselected mail daemons are disabled so that they do not start at boot time. The selected mail daemon is started, and any other mail daemon is stopped; thus making the changes take place immediately.

13.5. Mail Delivery Agents

Fedora includes two primary MDAs, Procmail and mail. Both of the applications are considered LDAs and both move email from the MTA's spool file into the user's mailbox. However, Procmail provides a robust filtering system.
This section details only Procmail. For information on the mail command, consult its man page.
Procmail delivers and filters email as it is placed in the mail spool file of the localhost. It is powerful, gentle on system resources, and widely used. Procmail can play a critical role in delivering email to be read by email client applications.
Procmail can be invoked in several different ways. Whenever an MTA places an email into the mail spool file, Procmail is launched. Procmail then filters and files the email for the MUA and quits. Alternatively, the MUA can be configured to execute Procmail any time a message is received so that messages are moved into their correct mailboxes. By default, the presence of /etc/procmailrc or of a .procmailrc file (also called an rc file) in the user's home directory invokes Procmail whenever an MTA receives a new message.
Whether Procmail acts upon an email message depends upon whether the message matches a specified set of conditions or recipes in the rc file. If a message matches a recipe, then the email is placed in a specified file, is deleted, or is otherwise processed.
When Procmail starts, it reads the email message and separates the body from the header information. Next, Procmail looks for /etc/procmailrc and rc files in the /etc/procmailrcs directory for default, system-wide, Procmail environmental variables and recipes. Procmail then searches for a .procmailrc file in the user's home directory. Many users also create additional rc files for Procmail that are referred to within the .procmailrc file in their home directory.
By default, no system-wide rc files exist in the /etc/ directory and no .procmailrc files exist in any user's home directory. Therefore, to use Procmail, each user must construct a .procmailrc file with specific environment variables and rules.

13.5.1. Procmail Configuration

The Procmail configuration file contains important environmental variables. These variables specify things such as which messages to sort and what to do with the messages that do not match any recipes.
These environmental variables usually appear at the beginning of .procmailrc in the following format:
				<env-variable>="<value>"
In this example, <env-variable> is the name of the variable and <value> defines the variable.
There are many environment variables not used by most Procmail users and many of the more important environment variables are already defined by a default value. Most of the time, the following variables are used:
  • DEFAULT — Sets the default mailbox where messages that do not match any recipes are placed.
    The default DEFAULT value is the same as $ORGMAIL.
  • INCLUDERC — Specifies additional rc files containing more recipes for messages to be checked against. This breaks up the Procmail recipe lists into individual files that fulfill different roles, such as blocking spam and managing email lists, that can then be turned off or on by using comment characters in the user's .procmailrc file.
    For example, lines in a user's .procmailrc file may look like this:
    MAILDIR=$HOME/Msgs INCLUDERC=$MAILDIR/lists.rc INCLUDERC=$MAILDIR/spam.rc
    
    If the user wants to turn off Procmail filtering of their email lists but leave spam control in place, they would comment out the first INCLUDERC line with a hash mark character (#).
  • LOCKSLEEP — Sets the amount of time, in seconds, between attempts by Procmail to use a particular lockfile. The default is eight seconds.
  • LOCKTIMEOUT — Sets the amount of time, in seconds, that must pass after a lockfile was last modified before Procmail assumes that the lockfile is old and can be deleted. The default is 1024 seconds.
  • LOGFILE — The file to which any Procmail information or error messages are written.
  • MAILDIR — Sets the current working directory for Procmail. If set, all other Procmail paths are relative to this directory.
  • ORGMAIL — Specifies the original mailbox, or another place to put the messages if they cannot be placed in the default or recipe-required location.
    By default, a value of /var/spool/mail/$LOGNAME is used.
  • SUSPEND — Sets the amount of time, in seconds, that Procmail pauses if a necessary resource, such as swap space, is not available.
  • SWITCHRC — Allows a user to specify an external file containing additional Procmail recipes, much like the INCLUDERC option, except that recipe checking is actually stopped on the referring configuration file and only the recipes on the SWITCHRC-specified file are used.
  • VERBOSE — Causes Procmail to log more information. This option is useful for debugging.
Other important environmental variables are pulled from the shell, such as LOGNAME, which is the login name; HOME, which is the location of the home directory; and SHELL, which is the default shell.
A comprehensive explanation of all environments variables, as well as their default values, is available in the procmailrc man page.

13.5.2. Procmail Recipes

New users often find the construction of recipes the most difficult part of learning to use Procmail. To some extent, this is understandable, as recipes do their message matching using regular expressions, which is a particular format used to specify qualifications for a matching string. However, regular expressions are not very difficult to construct and even less difficult to understand when read. Additionally, the consistency of the way Procmail recipes are written, regardless of regular expressions, makes it easy to learn by example. To see example Procmail recipes, refer to Section 13.5.2.5, “Recipe Examples”.
Procmail recipes take the following form:
:0<flags>: <lockfile-name> * <special-condition-character>
        <condition-1> * <special-condition-character>
        <condition-2> * <special-condition-character>
        <condition-N>
        <special-action-character>
        <action-to-perform>

The first two characters in a Procmail recipe are a colon and a zero. Various flags can be placed after the zero to control how Procmail processes the recipe. A colon after the <flags> section specifies that a lockfile is created for this message. If a lockfile is created, the name can be specified by replacing <lockfile-name> .
A recipe can contain several conditions to match against the message. If it has no conditions, every message matches the recipe. Regular expressions are placed in some conditions to facilitate message matching. If multiple conditions are used, they must all match for the action to be performed. Conditions are checked based on the flags set in the recipe's first line. Optional special characters placed after the * character can further control the condition.
The <action-to-perform> specifies the action taken when the message matches one of the conditions. There can only be one action per recipe. In many cases, the name of a mailbox is used here to direct matching messages into that file, effectively sorting the email. Special action characters may also be used before the action is specified. Refer to Section 13.5.2.4, “Special Conditions and Actions” for more information.

13.5.2.1. Delivering vs. Non-Delivering Recipes

The action used if the recipe matches a particular message determines whether it is considered a delivering or non-delivering recipe. A delivering recipe contains an action that writes the message to a file, sends the message to another program, or forwards the message to another e