# System Administrator's Guide {#idp3453488}
## Deployment, Configuration, and Administration of Fedora 20
###
### Jaromír Hradílek
Red Hat
Engineering Content Services
<[jhradilek@redhat.com](mailto:jhradilek@redhat.com)>
### Douglas Silas
Red Hat
Engineering Content Services
<[silas@redhat.com](mailto:silas@redhat.com)>
### Martin Prpič
Red Hat
Engineering Content Services
<[mprpic@redhat.com](mailto:mprpic@redhat.com)>
### Stephen Wadeley
Red Hat
Engineering Content Services
<[swadeley@redhat.com](mailto:swadeley@redhat.com)>
### Eliška Slobodová
Red Hat
Engineering Content Services
<[eslobodo@redhat.com](mailto:eslobodo@redhat.com)>
### Tomáš Čapek
Red Hat
Engineering Content Services
<[tcapek@redhat.com](mailto:tcapek@redhat.com)>
### Petr Kovář
Red Hat
Engineering Content Services
<[pkovar@redhat.com](mailto:pkovar@redhat.com)>
### Miroslav Svoboda
Red Hat
Engineering Content Services
<[msvoboda@redhat.com](mailto:msvoboda@redhat.com)>
### John Ha
Red Hat
Engineering Content Services
### David O'Brien
Red Hat
Engineering Content Services
### Michael Hideo
Red Hat
Engineering Content Services
### Don Domingo
Red Hat
Engineering Content Services
Copyright © 2014 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 . 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](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.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
All other trademarks are the property of their respective owners.
Abstract
The _System Administrator's Guide_ documents relevant information regarding the deployment, configuration, and administration of Fedora 20. It is oriented towards system administrators with a basic understanding of the system.
----
# Preface {#idm105236496}
The _System Administrator's Guide_ contains information on how to customize the Fedora 20 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:
* Installing and managing packages using Yum
* Configuring Apache HTTP Server, Postfix, Sendmail and other enterprise-class servers and software
* Gathering information about your system, including obtaining user-space crash data with the Automatic Bug Reporting Tool, and kernel-space crash data with `kdump`
* Working with kernel modules and upgrading the kernel
## 1\. Target Audience {#sect-Preface-Target_Audience}
The _System Administrator's Guide_ assumes you have a basic understanding of the Fedora operating system. If you need help with the installation of this system, refer to the [Fedora 20 Installation Guide](http://docs.fedoraproject.org/en-US/Fedora/19/html/Installation_Guide/index.html).
## 2\. How to Read this Book {#sect-Preface-Book_Organization}
This manual is divided into the following main categories:
[Part I, “Basic System Configuration”](#part-Basic_System_Configuration "Part I. Basic System Configuration")
: This part covers basic system administration tasks such as keyboard configuration, date and time configuration, and managing users and groups.
[Chapter 2, _Configuring the Language and Keyboard_](#ch-Configuring_the_Language_and_Keyboard "Chapter 2. Configuring the Language and Keyboard") covers basic language and keyboard setup. Read this chapter if you need to configure the language of your desktop, change the keyboard layout, or add the keyboard layout indicator to the panel.
[Chapter 3, _Configuring the Date and Time_](#ch-Configuring_the_Date_and_Time "Chapter 3. Configuring the Date and Time") covers the configuration of the system date and time. Read this chapter if you need to set or change the date and time.
[Chapter 4, _Managing Users and Groups_](#ch-Managing_Users_and_Groups "Chapter 4. Managing Users and Groups") covers the management of users and groups in a graphical user interface and on the command line. Read this chapter if you need to manage users and groups on your system, or enable password aging.
[Part II, “Package Management”](#part-Package_Management "Part II. Package Management")
: This part describes how to manage software packages on Fedora using Yum.
[Chapter 5, _Yum_](#ch-yum "Chapter 5. Yum") describes the Yum package manager. Read this chapter for information how to search, install, update, and uninstall packages on the command line.
[Part III, “Infrastructure Services”](#part-Infrastructure_Services "Part III. Infrastructure Services")
: This part provides information on how to configure services and daemons, configure authentication, and enable remote logins.
[Chapter 6, _Services and Daemons_](#ch-Services_and_Daemons "Chapter 6. Services and Daemons") covers the configuration of the services to be run when a system is started, and provides information on how to start, stop, and restart the services on the command line using the **systemctl** utility.
[Chapter 7, _Configuring Authentication_](#ch-Configuring_Authentication "Chapter 7. Configuring Authentication") describes how to configure user information retrieval from Lightweight Directory Access Protocol (LDAP), Network Information Service (NIS), and Winbind user account databases, and provides an introduction to the System Security Services Daemon (SSSD). Read this chapter if you need to configure authentication on your system.
[Chapter 8, _OpenSSH_](#ch-OpenSSH "Chapter 8. OpenSSH") describes how to enable a remote login via the SSH protocol. It covers the configuration of the `sshd` service, as well as a basic usage of the **ssh**, **scp**, **sftp** client utilities. Read this chapter if you need a remote access to a machine.
[Part IV, “Servers”](#part-Servers "Part IV. Servers")
: This part discusses various topics related to servers such as how to set up a Web server or share files and directories over the network.
[Chapter 9, _Web Servers_](#ch-Web_Servers "Chapter 9. Web Servers") focuses on the Apache HTTP Server 2.2, a robust, full-featured open source web server developed by the Apache Software Foundation. Read this chapter if you need to configure a web server on your system.
[Chapter 10, _Mail Servers_](#ch-Mail_Servers "Chapter 10. Mail Servers") reviews modern email protocols in use today, and some of the programs designed to send and receive email, including Postfix, Sendmail, Fetchmail, and Procmail. Read this chapter if you need to configure a mail server on your system.
[Chapter 11, _Directory Servers_](#ch-Directory_Servers "Chapter 11. Directory Servers") covers the installation and configuration of OpenLDAP 2.4, an open source implementation of the LDAPv2 and LDAPv3 protocols. Read this chapter if you need to configure a directory server on your system.
[Chapter 12, _File and Print Servers_](#ch-File_and_Print_Servers "Chapter 12. File and Print Servers") guides you through the installation and configuration of Samba, an open source implementation of the Server Message Block (SMB) protocol, and vsftpd, the primary FTP server shipped with Fedora. Additionally, it explains how to use the Printer Configuration tool to configure printers. Read this chapter if you need to configure a file or print server on your system.
[Chapter 13, _Configuring NTP Using the chrony Suite_](#ch-Configuring_NTP_Using_the_chrony_Suite "Chapter 13. Configuring NTP Using the chrony Suite") covers the installation and configuration of the chrony suite, a client and a server for the Network Time Protocol (`NTP`). Read this chapter if you need to configure the system to synchronize the clock with a remote `NTP` server, or set up an `NTP` server on this system.
[Chapter 14, _Configuring NTP Using ntpd_](#ch-Configuring_NTP_Using_ntpd "Chapter 14. Configuring NTP Using ntpd") covers the installation and configuration of the `NTP` daemon, `ntpd`, for the Network Time Protocol (`NTP`). Read this chapter if you need to configure the system to synchronize the clock with a remote `NTP` server, or set up an `NTP` server on this system, and you prefer not to use the chrony application.
[Chapter 15, _Configuring PTP Using ptp4l_](#ch-Configuring_PTP_Using_ptp4l "Chapter 15. Configuring PTP Using ptp4l") covers the installation and configuration of the Precision Time Protocol application, ptp4l, an application for use with network drivers that support the Precision Network Time Protocol (`PTP`). Read this chapter if you need to configure the system to synchronize the system clock with a master `PTP` clock.
[Part V, “Monitoring and Automation”](#part-Monitoring_and_Automation "Part V. Monitoring and Automation")
: This part describes various tools that allow system administrators to monitor system performance, automate system tasks, and report bugs.
[Chapter 16, _System Monitoring Tools_](#ch-System_Monitoring_Tools "Chapter 16. System Monitoring Tools") discusses applications and commands that can be used to retrieve important information about the system. Read this chapter to learn how to gather essential system information.
[Chapter 17, _Viewing and Managing Log Files_](#ch-Viewing_and_Managing_Log_Files "Chapter 17. Viewing and Managing Log Files") describes the configuration of the `rsyslog` daemon, and explains how to locate, view, and monitor log files. Read this chapter to learn how to work with log files.
[Chapter 18, _Automating System Tasks_](#ch-Automating_System_Tasks "Chapter 18. Automating System Tasks") provides an overview of the **cron**, **at**, and **batch** utilities. Read this chapter to learn how to use these utilities to perform automated tasks.
[Chapter 19, _OProfile_](#ch-OProfile "Chapter 19. OProfile") covers OProfile, a low overhead, system-wide performance monitoring tool. Read this chapter for information on how to use OProfile on your system.
[Part VI, “Kernel, Module and Driver Configuration”](#part-Kernel_Module_and_Driver_Configuration "Part VI. Kernel, Module and Driver Configuration")
: This part covers various tools that assist administrators with kernel customization.
[Chapter 20, _Manually Upgrading the Kernel_](#ch-Manually_Upgrading_the_Kernel "Chapter 20. Manually Upgrading the Kernel") provides important information on how to manually update a kernel package using the **rpm** command instead of **yum**. Read this chapter if you cannot update a kernel package with the Yum package manager.
[Chapter 21, _Working with Kernel Modules_](#ch-Working_with_Kernel_Modules "Chapter 21. Working with Kernel Modules") explains how to display, query, load, and unload kernel modules and their dependencies, and how to set module parameters. Additionally, it covers specific kernel module capabilities such as using multiple Ethernet cards and using channel bonding. Read this chapter if you need to work with kernel modules.
[Chapter 22, _The kdump Crash Recovery Service_](#ch-kdump "Chapter 22. The kdump Crash Recovery Service") explains how to configure, test, and use the `kdump` service in Fedora, and provides a brief overview of how to analyze the resulting core dump using the crash debugging utility. Read this chapter to learn how to enable `kdump` on your system.
[Appendix A, _RPM_](#ch-RPM "Appendix A. RPM")
: This appendix concentrates on the RPM Package Manager (RPM), an open packaging system used by Fedora, and the use of the **rpm** utility. Read this appendix if you need to use **rpm** instead of **yum**.
[Appendix B, _The X Window System_](#ch-The_X_Window_System "Appendix B. The X Window System")
: This appendix covers the configuration of the X Window System, the graphical environment used by Fedora. Read this appendix if you need to adjust the configuration of your X Window System.
## 3\. Document Conventions {#idm96752896}
This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.
### 3\.1. Typographic Conventions {#idm22783776}
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 keys 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 key, all presented in mono-spaced bold and all distinguishable thanks to context.
Key combinations can be distinguished from an individual key by the plus sign that connects each part of a key combination. For example:
> Press **Enter** to execute the command.
>
> Press **Ctrl**+**Alt**+**F2** to switch to a virtual terminal.
The first example highlights a particular key to press. The second example highlights a key combination: a set of three keys 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 submenu titles. For example:
> Choose System → Preferences → Mouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, select 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 Applications → Accessories → Character Map from the main menu bar. Next, choose Search → Find… 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 Edit → Paste 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.
### 3\.2. Pull-quote Conventions {#idm78015184}
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"));
}
}
### 3\.3. Notes and Warnings {#idm31856816}
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” will not cause data loss but may cause irritation and frustration.
### Warning
Warnings should not be ignored. Ignoring warnings will most likely cause data loss.
## 4\. We Need Feedback! {#idm98027440}
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: [https://bugzilla.redhat.com/enter\_bug.cgi?product=Fedora Documentation&component=system-administrator's-guide](https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora Documentation&component=system-administrator's-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.
## 5\. Acknowledgments {#pref-Acknowledgments}
Certain portions of this text first appeared in the _Deployment Guide_, copyright © 2007 Red Hat, Inc., available at [https://access.redhat.com/site/documentation/en-US/Red\_Hat\_Enterprise\_Linux/5/html/Deployment\_Guide/index.html](https://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/5/html/Deployment_Guide/index.html).
[Section 16.6, “Monitoring Performance with Net-SNMP”](#sect-System_Monitoring_Tools-Net-SNMP "16.6. Monitoring Performance with Net-SNMP") is based on an article written by Michael Solberg.
The authors of this book would like to thank the following people for their valuable contributions: Adam Tkáč, Andrew Fitzsimon, Andrius Benokraitis, Brian Cleary Edward Bailey, Garrett LeSage, Jeffrey Fearn, Joe Orton, Joshua Wulf, Karsten Wade, Lucy Ringland, Marcela Mašláňová, Mark Johnson, Michael Behm, Miroslav Lichvár, Radek Vokál, Rahul Kavalapara, Rahul Sundaram, Sandra Moore, Zbyšek Mráz, Jan Včelák, Peter Hutterer, T.C. Hollingsworth, and James Antill, among many others.
# Part I. Basic System Configuration {#part-Basic_System_Configuration}
This part covers basic system administration tasks such as keyboard configuration, date and time configuration, installation and initial setup of an NTP server, and managing users and groups.
## Chapter 1. Opening Graphical Applications {#ch-Opening_GUI_Applications}
Fedora provides graphical applications in addition to command line utilities for configuring many features. This chapter describes methods for opening `Graphical User Interface`, or _GUI_, applications in various environments.
## 1\.1. Opening graphical applications from the command line {#gui-from_cli}
Graphical applications can be launched from a terminal window or console session by simply typing the name of the application.
[fedorauser@localhost]$ **firefox**
### File names vs Application names
Programs are opened from the command line using the name of the executable file provided in the program's package. An entry in the desktop menu will often be named differently from the file it executes. For example, the GNOME disk management utility appears in the menu as Disks, and the file it executes is `/usr/bin/gnome-disks`.
When a program is executed on the command line, the terminal is occupied until the program completes. When a graphical application is executed from the command line, the program's error output, or `STDERR`, is sent to the terminal window. This can be especially useful when troubleshooting.
Example 1.1. Viewing errors by launching graphical applications from the command line
[fedorauser@localhost]$ **astromenace-wrapper**
AstroMenace 1.3.1 121212
Open XML file: /home/fedorauser/.config/astromenace/amconfig.xml
VFS file was opened /usr/share/astromenace/gamedata.vfs
Vendor : OpenAL Community
Renderer : OpenAL Soft
Version : 1.1 ALSOFT 1.15.1
ALut ver : 1.1
Font initialized: DATA/FONT/LiberationMono-Bold.ttf
Current Video Mode: 3200x1080 32bit
Xinerama/TwinView detected.
Screen count: 2
Screen #0: (0, 0) x (1920, 1080)
Screen #1: (1920, 0) x (1280, 1024)
Supported resolutions list:
640x480 16bit
640x480 32bit
640x480 0bit
768x480 16bit
<output truncated>
To launch a graphical application, but fork the additional output into the background and return the terminal for immediate use, use the shell's `job control` feature.
[fedorauser@localhost]$ **emacs foo.txt &**
### Ending a session
Applications that hold the command line prompt until they complete will close when the terminal session ends, even if they are forked into the background.
GUI programs can also be launched on one `TTY` and displayed on another by specifying the `DISPLAY` variable. This can be useful when running multiple graphical sessions, or for troubleshooting problems with a desktop session.
1. Switch to another TTY using the key combination **Ctrl**-**Alt**-**F2** and log in. Note that consoles are available by default with **F2** through **F6**.
1. Identify the X session you want to target. The `DISPLAY` variable is always an integer preceded by a colon, and will be _:0_ in most cases. Check the arguments of the currently running X process to verify the value. The command below shows both the `DISPLAY` variable as well as the TTY that X is running on, `tty1`.
[fedorauser@localhost]$ **ps aux|grep /usr/bin/X**
root 1498 7.1 1.0 521396 353984 `tty1` Ss+ 00:04 66:34 /usr/bin/X `:0` vt1 -background none -nolisten tcp -auth /var/run/kdm/A:0-22Degc
root 23874 0.0 0.0 109184 900 pts/21 S+ 15:35 0:00 grep --color=auto /usr/bin/X
1. Specify the `DISPLAY` variable when executing the program.
[fedorauser@localhost]$ **DISPLAY=:0 gnome-shell --replace &**
1. Switch back to the TTY the graphical session is running on. Since the example above shows X running on `vt1`, pressing **Ctrl**+**Alt**+**F1** will return to the desktop environment.
## 1\.2. Launching Applications with **Alt**+**F2** {#gui-alt_f2}
Most desktop environments follow the convention of using the key combination **Alt**+**F2** for opening new applications. Pressing **Alt**+**F2** brings up a prompt for a command to be entered into.
Commands entered into this dialog box function much as they would if entered in a terminal. Applications are known by their file name, and can accept arguments.
Figure 1.1. Using **Alt**+**F2** with GNOME
![Using AltF2 with GNOME][1]
[[D](ld-idm108867008.html)]
Figure 1.2. Using **Alt**+**F2** with KDE
![Using AltF2 with KDE][2]
[[D](ld-idm46477104.html)]
Figure 1.3. Using **Alt**+**F2** with LXDE
![Using AltF2 with LXDE][3]
[[D](ld-idm116012800.html)]
Figure 1.4. Using **Alt**+**F2** with MATE
![Using AltF2 with MATE][4]
[[D](ld-idm32963888.html)]
Figure 1.5. Using **Alt**+**F2** with XFCE
![Using AltF2 with XFCE][5]
[[D](ld-idm64159296.html)]
## 1\.3. Launching applications from the Desktop Menu {#gui-from_menu}
Applications can also be opened from the menu system provided by the desktop environment in use. While the presentation may vary between desktop environments, the menu entries and their categories are provided by the individual application and standardized by the [freedesktop.org Desktop Menu Specification](http://standards.freedesktop.org/menu-spec/menu-spec-latest.html). Some desktop environments also provide search functionality in their menu system to allow quick and easy access to applications.
### 1\.3.1. Using GNOME menus {#gui-from_menu-gnome}
The GNOME menu, called the overview, can be accessed by either clicking the Activities button in the top left of the primary display, by moving the mouse past the top left `hot corner`, or by pressing the **Super** ( **Windows** ) key. The overview presents documents in addition to applications.
Selecting an item from the menu is best accomplished using the search box. Simply bring up the overview, and begin typing the name of the application you want to launch. Pressing enter will launch the highlighted application, or you can use the arrow keys or mouse to choose an alternative.
Figure 1.6. Using the GNOME search box
![Using the GNOME search box][6]
[[D](ld-idm116949232.html)]
The overview can also be browsed. The bar on the left, called the dash, shows frequently used applications and a grid icon. Clicking on the grid icon brings up a grid in the center of the window that displays frequently used applications. The grid will display all available applications if selected using the All button at the bottom of the screen.
Figure 1.7. Browsing GNOME menu entries
![Browsing GNOME menu entries][7]
[[D](ld-idm93579952.html)]
To learn more about using GNOME shell, visit
### 1\.3.2. Using KDE menus {#gui-from_menu-kde}
The KDE menu is opened by clicking the Fedora button at the bottom left corner of the screen. The menu initially displays favorite applications, which can be added to by right clicking any menu entry. Hovering over the icons in the lower portion of the menu will display applications, file systems, recently used applications, or options for logging out of the system.
Figure 1.8. The KDE desktop menu.
![The KDE desktop menu.][8]
[[D](ld-idm95382864.html)]
Search functionality is also available in the KDE menu system. To search for applications, open the menu and begin typing. The menu will display matching entries.
Figure 1.9. Searching with the KDE menu.
![Searching with the KDE menu.][9]
[[D](ld-idm92461104.html)]
### 1\.3.3. Using menus in LXDE, MATE, and XFCE {#idm57324224}
Menus in LXDE, MATE, and XFCE have a varied appearance but a very similar structure. They categorize applications, and the contents of a category are displayed by hovering the cursor over the entry. Applications are launched by clicking on an entry.
Figure 1.10. The LXDE menu
![The LXDE menu][10]
[[D](ld-idm80123344.html)]
Figure 1.11. MATE menu
![MATE menu][11]
[[D](ld-idm72929776.html)]
Figure 1.12. XFCE Menu
![XFCE Menu][12]
[[D](ld-idm61924992.html)]
## Chapter 2. Configuring the Language and Keyboard {#ch-Configuring_the_Language_and_Keyboard}
Fedora 20 is shipped with the Region and Language configuration tool, which allows you to configure keyboard layouts, the language of your desktop environment, and other regional settings. To start the tool, open the System Settings window by selecting Applications → System Tools → System Settings from the Activities menu, and click Region and Language.
## 2\.1. Changing the Language {#sect-Configuring_the_Language_and_Keyboard-Language}
To configure the language of your desktop, select the Language tab of the Region and Language application. You will be presented with a short list of common languages.
Figure 2.1. Changing the language
![Changing the language][13]
[[D](ld-idm105588720.html)]
By default, this list only contains a few of the available languages. To add another language, click the + (the plus sign) button below the list. A dialog window appears, allowing you to select the desired language. The input field at the bottom part of the dialog window allows you to reduce the number of displayed items by first few letters part of the language name in it (for example, “slov” for the Slovak language). Once you select a language, click the Select button to confirm your choice.
Figure 2.2. Adding another language
![Adding another language][14]
[[D](ld-idm14258688.html)]
To choose a particular language from the list, click its name to select it. The changes will take effect the next time you log in to the system.
## 2\.2. Changing the Date, Time, and Numeric Format {#sect-Configuring_the_Language_and_Keyboard-Formats}
To change the default date, time, number, and currency format, select the Formats tab of the Region and Language application. You will be presented with a short list of available formats.
Figure 2.3. Changing the date, time, and numeric format
![Changing the date, time, and numeric format][15]
[[D](ld-idm66993504.html)]
By default, this list only contains a few of the available formats. To add another format, click the + (the plus sign) button below the list. A dialog window appears, allowing you to select the desired format according to a region. The input field at the bottom part of the dialog window allows you to reduce the number of displayed items by typing first few letters of the region name in it (for example, “slov” for Slovakia). Once you select a region, click the Select button to confirm your choice.
Figure 2.4. Adding a format
![Adding a format][16]
[[D](ld-idm38616048.html)]
To choose a particular format from the list, click its name to select it. The changes will take effect the next time you log in to the system.
## 2\.3. Changing the Keyboard Layout {#sect-Configuring_the_Language_and_Keyboard-Layouts}
Although the installation program allows a system administrator to configure a keyboard layout during the system installation, the default settings may not always suit your current needs. To change the default keyboard layout, select the Layouts tab of the Region and Language application. You will be presented with a list of currently enabled layouts.
Figure 2.5. Changing the keyboard layout
![Changing the keyboard layout][17]
[[D](ld-idm93138992.html)]
To add a layout to the list, click the + (the plus sign) button below the list. A dialog window appears, allowing you to select the desired keyboard layout. The input field at the bottom part of the dialog window allows you to reduce the number of displayed items by typing first few letters of the layout name in it (for example, “slov” for a Slovak layout). Once you select a layout, click the Add button to confirm your choice.
Figure 2.6. Adding a keyboard layout
![Adding a keyboard layout][18]
[[D](ld-idm97128976.html)]
The first layout in the list is always considered the default. To move a particular layout up or down in the list, select it and click the ∧ (the upwards arrow) or ∨ (the downwards arrow) buttons respectively. To remove a layout, click the − (that is, the minus sign) button. Additionally, by selecting an option button on the right side of the window, you can choose if you want to use different keyboard layouts for individual windows, or a single layout for all windows.
When more than one layout is enabled, a keyboard indicator appears on the panel in order to allow you to switch between the layouts.
Figure 2.7. The keyboard layout indicator
![The keyboard layout indicator][19]
[[D](ld-idm128824656.html)]
## 2\.4. Viewing the Current Configuration {#sect-Configuring_the_Language_and_Keyboard-System}
To view the current configuration, select the System tab of the Region and Language application. You will be presented with a comparison of your own configuration and system-wide settings.
Figure 2.8. Viewing the current configuration
![Viewing the current configuration][20]
[[D](ld-idm94139104.html)]
## Chapter 3. Configuring the Date and Time {#ch-Configuring_the_Date_and_Time}
This chapter covers setting the system date and time in Fedora, both manually and using the _Network Time Protocol_ (NTP), as well as setting the time zone. Two methods are covered: setting the date and time using the Date and Time configuration tool, and doing so on the command line.
## 3\.1. Using the Date and Time Configuration Tool {#sect-Configuring_the_Date_and_Time-Date_and_Time}
Fedora 20 is shipped with the Date and Time configuration tool, which allows you to change the date and time of the system, to configure the time zone used by the system, and to set up the Network Time Protocol daemon to synchronize the system clock with a time server. To start the tool, either select Applications → System Tools → System Settings from the Activities menu and click the Date and Time icon, or click the time in the panel and select Date and Time Settings from the drop-down menu.
Figure 3.1. The Date and Time configuration tool
![The Date and Time configuration tool][21]
[[D](ld-idm34983056.html)]
By default, the tool only allows you to review the current settings. This is because only `root` is allowed to set the system date and time. To unlock the configuration tool for changes, click the Unlock button in the top-right corner of the window, and provide the correct password when prompted.
To change the current time of your system, either configure the system to synchronize it over the network by clicking the Network Time switch, or set it manually by clicking the up and down arrows above and below the numbers. You can also select 24-hour or AM/PM to enable or disable the 24-hour time format.
To change the time zone, either click on the map, or select the region and city from the Region and City drop-down lists.
To change the current date of your system, select a month from the drop-down list below the time, and use the up and down arrows to choose the day and year.
The changes take effect immediately.
## 3\.2. Using the Command Line Tools {#sect-Configuring_the_Date_and_Time-Command_Line_Configuration}
Fedora 20 provides command line tools that allow you to configure the date and time both manually and using the `NTP` protocol.
### 3\.2.1. Changing the Date {#sect-Configuring_the_Date_and_Time-Command_Line_Configuration-Date}
To change the system date, type the following at a shell prompt as `root`:
**date +%D -s _`YYYY-MM-DD`_**
…where _`YYYY`_ is a four-digit year, _`MM`_ is a two-digit month, and _`DD`_ is a two-digit day of the month. For example, to change the date to 2 June 2010, type:
~]# **date +%D -s 2010-06-02**
You can verify the current settings by running **date** without any additional argument.
### 3\.2.2. Changing the Time {#sect-Configuring_the_Date_and_Time-Command_Line_Configuration-Time}
To change the current time, run the following command as `root`:
**date +%T -s _`HH:MM:SS`_**
…where _`HH`_ stands for an hour, _`MM`_ is a minute, and _`SS`_ is a second, all typed in a two-digit form. If your system clock is set to use UTC (Coordinated Universal Time), also add the following option:
**date +%T -s _`HH:MM:SS`_ -u**
For instance, to set the system clock to 11:26 PM using the UTC, type:
~]# **date +%T -s 23:26:00 -u**
You can verify the current settings by running **date** without any additional argument. You should not use this command to set the time if the system clock is being maintained by chrony, `ntpd`, or any other similar automated process.
### 3\.2.3. Configuring the Network Time Protocol {#sect-Configuring_the_Date_and_Time-Command_Line_Configuration-Network_Time_Protocol}
Fedora includes the chrony suite of programs to automatically adjust the system clock using the _Network Time Protocol_ (NTP). See [Chapter 13, _Configuring NTP Using the chrony Suite_](#ch-Configuring_NTP_Using_the_chrony_Suite "Chapter 13. Configuring NTP Using the chrony Suite") for information on configuring and enabling chrony.
It is also possible to use `ntpd` to adjust the system clock using the _Network Time Protocol_ (NTP). See [Chapter 14, _Configuring NTP Using ntpd_](#ch-Configuring_NTP_Using_ntpd "Chapter 14. Configuring NTP Using ntpd") for information on configuring `ntpd`.
## 3\.3. Additional Resources {#sect-Configuring_the_Date_and_Time-Additional_Resources}
For more information about the date and time configuration, refer to the following resources.
### 3\.3.1. Installed Documentation {#sect-Configuring_the_Date_and_Time-Additional_Resources-Installed_Documentation}
* `date`(1) — The manual page for the date utility.
## Chapter 4. Managing Users and Groups {#ch-Managing_Users_and_Groups}
The control of users and groups is a core element of Fedora system administration. This chapter explains how to add, manage, and delete users and groups in the graphical user interface and on the command line, and covers advanced topics, such as enabling password aging or creating group directories.
## 4\.1. Introduction to Users and Groups {#s1-users-groups-introduction}
While users can be either people (meaning accounts tied to physical users) or accounts which exist for specific applications to use, groups are logical expressions of organization, tying users together for a common purpose. Users within a group can read, write, or execute files owned by that group.
Each user is associated with a unique numerical identification number called a _user ID_ (UID). Likewise, each group is associated with a _group ID_ (GID). A user who creates a file is also the owner and group owner of that file. The file is assigned separate read, write, and execute permissions for the owner, the group, and everyone else. The file owner can be changed only by `root`, and access permissions can be changed by both the `root` user and file owner.
Additionally, Fedora supports _access control lists_ (ACLs) for files and directories which allow permissions for specific users outside of the owner to be set. See For more information about this feature, refer to the [_Access Control Lists_](http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/6/html/Storage_Administration_Guide/ch-acls.html) chapter of the [_Storage Administration Guide_](http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/6/html/Storage_Administration_Guide/index.html).
### 4\.1.1. User Private Groups {#s2-users-groups-private-groups}
Fedora uses a _user private group_ (_UPG_) scheme, which makes UNIX groups easier to manage. A user private group is created whenever a new user is added to the system. It has the same name as the user for which it was created and that user is the only member of the user private group.
User private groups make it safe to set default permissions for a newly created file or directory, allowing both the user and _the group of that user_ to make modifications to the file or directory.
The setting which determines what permissions are applied to a newly created file or directory is called a _umask_ and is configured in the `/etc/bashrc` file. Traditionally on UNIX systems, the **umask** is set to **022**, which allows only the user who created the file or directory to make modifications. Under this scheme, all other users, _including members of the creator's group_, are not allowed to make any modifications. However, under the UPG scheme, this “group protection” is not necessary since every user has their own private group.
### 4\.1.2. Shadow Passwords {#s2-users-groups-shadow-utilities}
Especially in environments with multiple users, it is very important to use _shadow passwords_ provided by the shadow-utils package to enhance the security of system authentication files. For this reason, the installation program enables shadow passwords by default.
The following is a list of the advantages shadow passwords have over the traditional way of storing passwords on UNIX-based systems:
* Shadow passwords improve system security by moving encrypted password hashes from the world-readable `/etc/passwd` file to `/etc/shadow`, which is readable only by the `root` user.
* Shadow passwords store information about password aging.
* Shadow passwords allow the `/etc/login.defs` file to enforce security policies.
Most utilities provided by the shadow-utils package work properly whether or not shadow passwords are enabled. However, since password aging information is stored exclusively in the `/etc/shadow` file, any commands which create or modify password aging information do not work. The following is a list of utilities and commands that do not work without first enabling shadow passwords:
* The **chage** utility.
* The **gpasswd** utility.
* The **usermod** command with the `-e` or `-f` option.
* The **useradd** command with the `-e` or `-f` option.
## 4\.2. Using the User Accounts Tool {#sect-Managing_Users_and_Groups-User_Accounts}
The User Accounts configuration tool allows you to view, modify, add, and delete local users. To run the tool, select Applications → System Tools → System Settings from the Activities menu and click the User Accounts icon.
Figure 4.1. The User Accounts configuration tool
![The User Accounts configuration tool][22]
[[D](ld-idm93147536.html)]
By default, the tool only allows you to change certain settings regarding your account. This is because only the `root` user is allowed to configure users and groups. To unlock the configuration tool for all kinds of changes, click the Unlock button in the top-right corner of the window, and provide the correct password when prompted.
### 4\.2.1. Configuring an Account {#sect-Managing_Users_and_Groups-User_Accounts-Configuring_an_Account}
To change the image associated with an account, click the icon next to the account name and either select a picture from the pulldown list, or click Browse for more pictures... to use an image from your local drive.
To change the name associated with an account, click the name next to the icon to edit it.
To change the account type, click the text next to the Account type label. Note that this change requires the configuration tool to be unlocked even if you are changing your own account.
To change the default language for an account, click the text next to the Language label and select a language from the list.
To change the password, click the field next to the Password label. A dialog box appears, allowing you to set the new password. Note that the current password must be provided in order to confirm the change. Once done, click the Change button to save the change.
Figure 4.2. Changing the password
![Changing the password][23]
[[D](ld-idm30040576.html)]
### Password security advice
It is advisable to use a much longer password, as this makes it more difficult for an intruder to guess it and access the account without permission. It is also recommended that the password not be based on a dictionary term: use a combination of letters, numbers and special characters.
Finally, to set up automatic login for a particular account, enable the Automatic Login switch. The configuration tool must be unlocked to make this change.
### 4\.2.2. Adding a New User {#sect-Managing_Users_and_Groups-User_Accounts-Adding_a_New_User}
To add a new user, make sure the configuration tool is unlocked, and click the + button (that is, the plus sign) below the account list. A dialog window appears, allowing you to supply user details.
Figure 4.3. Creating a new account
![Creating a new account][24]
[[D](ld-idm58562528.html)]
Take the following steps to create an account:
1. Select an account type from the Account type pulldown list. Available account types are `Administrator` and `Standard` (the default option).
1. Fill in the Full name input field to set the name associated with the account. This name will be used by the login manager, and will be displayed on the panel.
1. Either select a suggested username from the Username pulldown list, or fill in the corresponding input field.
1. Click the Create button to confirm the settings.
Fedora uses a _user private group_ (UPG) scheme. The UPG scheme does not add or change anything in the standard UNIX way of handling groups; it offers a new convention. Whenever you create a new user, a unique group with the same name as the user is created.
When a new account is created, default configuration files are copied from the `/etc/skel/` directory into the new home directory.
### 4\.2.3. Removing a User {#sect-Managing_Users_and_Groups-User_Accounts-Removing_a_User}
To remove a user, make sure the configuration tool is unlocked, select the desired account from the account list, and click the − button (that is, the minus sign) below the account list. A dialog window appears, allowing you to confirm or cancel the change.
Figure 4.4. Removing an account
![Removing an account][25]
[[D](ld-idm127439712.html)]
To delete files and directories that belong to the user (that is, the home directory, mail spool, and temporary files), click the Delete Files button. To keep these files intact and only delete the user account, click Keep Files. To abort the deletion, click Cancel.
## 4\.3. Using the User Manager Tool {#s1-users-configui}
The User Manager application allows you to view, modify, add, and delete local users and groups in the graphical user interface. To start the application, either select Applications → Other → Users and Groups from the Activities menu, or type **system-config-users** at a shell prompt. Note that unless you have superuser privileges, the application will prompt you to authenticate as `root`.
### 4\.3.1. Viewing Users and Groups {#s2-redhat-config-users-list}
The main window of the User Manager is divided into two tabs: The Users tab provides a list of local users along with additional information about their user ID, primary group, home directory, login shell, and full name. The Groups tab provides a list of local groups with information about their group ID and group members.
Figure 4.5. Viewing users and groups
![Viewing users and groups][26]
[[D](ld-idm29184544.html)]
To find a specific user or group, type the first few letters of the name in the Search filter field and either press **Enter**, or click the Apply filter button. You can also sort the items according to any of the available columns by clicking the column header.
Fedora reserves user and group IDs below 1000 for system users and groups. By default, the User Manager does not display the system users. To view all users and groups, select Edit → Preferences to open the Preferences dialog box, and clear the Hide system users and groups check box.
### 4\.3.2. Adding a New User {#s2-redhat-config-users-user-new}
To add a new user, click the Add User button. A window as shown in [Figure 4.6, “Adding a new user”](#user-new-fig "Figure 4.6. Adding a new user") appears.
Figure 4.6. Adding a new user
![Adding a new user][27]
[[D](ld-idp2353264.html)]
The Add New User dialog box allows you to provide information about the newly created user. In order to create a user, enter the username and full name in the appropriate fields and then type the user's password in the Password and Confirm Password fields. The password must be at least six characters long.
### Password security advice
It is advisable to use a much longer password, as this makes it more difficult for an intruder to guess it and access the account without permission. It is also recommended that the password not be based on a dictionary term: use a combination of letters, numbers and special characters.
The Login Shell pulldown list allows you to select a login shell for the user. If you are not sure which shell to select, accept the default value of /bin/bash.
By default, the User Manager application creates the home directory for a new user in ``/home/_`username`_/``. You can choose not to create the home directory by clearing the Create home directory check box, or change this directory by editing the content of the Home Directory text box. Note that when the home directory is created, default configuration files are copied into it from the `/etc/skel/` directory.
Fedora uses a user private group (UPG) scheme. Whenever you create a new user, a unique group with the same name as the user is created by default. If you do not want to create this group, clear the Create a private group for the user check box.
To specify a user ID for the user, select Specify user ID manually. If the option is not selected, the next available user ID above 1000 is assigned to the new user. Because Fedora reserves user IDs below 1000 for system users, it is not advisable to manually assign user IDs 1–999.
Clicking the OK button creates the new user. To configure more advanced user properties, such as password expiration, modify the user's properties after adding the user.
### 4\.3.3. Adding a New Group {#s2-redhat-config-users-group-new}
To add a new user group, select Add Group from the toolbar. A window similar to [Figure 4.7, “New Group”](#group-new-fig "Figure 4.7. New Group") appears. Type the name of the new group. To specify a group ID for the new group, select Specify group ID manually and select the GID. Note that Fedora also reserves group IDs lower than 1000 for system groups.
Figure 4.7. New Group
![New Group][28]
[[D](ld-idm28496544.html)]
Click OK to create the group. The new group appears in the group list.
### 4\.3.4. Modifying User Properties {#s2-redhat-config-users-user-properties}
To view the properties of an existing user, click on the Users tab, select the user from the user list, and click Properties from the menu (or choose File → Properties from the pulldown menu). A window similar to [Figure 4.8, “User Properties”](#user-properties-fig "Figure 4.8. User Properties") appears.
Figure 4.8. User Properties
![User Properties][29]
[[D](ld-idm73656768.html)]
The User Properties window is divided into multiple tabbed pages:
* User Data — Shows the basic user information configured when you added the user. Use this tab to change the user's full name, password, home directory, or login shell.
* Account Info — Select Enable account expiration if you want the account to expire on a certain date. Enter the date in the provided fields. Select Local password is locked to lock the user account and prevent the user from logging into the system.
* Password Info — Displays the date that the user's password last changed. To force the user to change passwords after a certain number of days, select Enable password expiration and enter a desired value in the Days before change required: field. The number of days before the user's password expires, the number of days before the user is warned to change passwords, and days before the account becomes inactive can also be changed.
* Groups — Allows you to view and configure the Primary Group of the user, as well as other groups that you want the user to be a member of.
### 4\.3.5. Modifying Group Properties {#s2-redhat-config-users-group-properties}
To view the properties of an existing group, select the group from the group list and click Properties from the menu (or choose File → Properties from the pulldown menu). A window similar to [Figure 4.9, “Group Properties”](#group-properties-fig "Figure 4.9. Group Properties") appears.
Figure 4.9. Group Properties
![Group Properties][30]
[[D](ld-idm40473568.html)]
The Group Users tab displays which users are members of the group. Use this tab to add or remove users from the group. Click OK to save your changes.
## 4\.4. Using Command Line Tools {#s1-users-tools}
The easiest say to manage users and groups on Fedora is to use the User Manager application as described in [Section 4.3, “Using the User Manager Tool”](#s1-users-configui "4.3. Using the User Manager Tool"). However, if you prefer command line tools or do not have the X Window System installed, you can use command line utilities that are listed in [Table 4.1, “Command line utilities for managing users and groups”](#table-users-tools "Table 4.1. Command line utilities for managing users and groups").
Table 4.1. Command line utilities for managing users and groups
|Utilities|Description|
|-|
|**useradd**, **usermod**, **userdel**|Standard utilities for adding, modifying, and deleting user accounts.|
|**groupadd**, **groupmod**, **groupdel**|Standard utilities for adding, modifying, and deleting groups.|
|**gpasswd**|Standard utility for administering the `/etc/group` configuration file.|
|**pwck**, **grpck**|Utilities that can be used for verification of the password, group, and associated shadow files.|
|**pwconv**, **pwunconv**|Utilities that can be used for the conversion of passwords to shadow passwords, or back from shadow passwords to standard passwords.|
### 4\.4.1. Adding a New User {#s2-users-tools-users-add}
To add a new user to the system, typing the following at a shell prompt as `root`:
**useradd** [_`options`_] _`username`_
…where _`options`_ are command line options as described in [Table 4.2, “useradd command line options”](#table-useradd-options "Table 4.2. useradd command line options").
By default, the **useradd** command creates a locked user account. To unlock the account, run the following command as `root` to assign a password:
**passwd** _`username`_
Optionally, you can set password aging policy. See [Section 4.4.3, “Enabling Password Aging”](#s2-users-tools-password-aging "4.4.3. Enabling Password Aging") for information on how to enable password aging.
Table 4.2. useradd command line options
|Option|Description|
|-|
|`-c` '_`comment`_'|_`comment`_ can be replaced with any string. This option is generally used to specify the full name of a user.|
|`-d` _`home_directory`_|Home directory to be used instead of default ``/home/_`username`_/``.|
|`-e` _`date`_|Date for the account to be disabled in the format YYYY-MM-DD.|
|`-f` _`days`_|Number of days after the password expires until the account is disabled. If `0` is specified, the account is disabled immediately after the password expires. If `-1` is specified, the account is not be disabled after the password expires.|
|`-g` _`group_name`_|Group name or group number for the user's default group. The group must exist prior to being specified here.|
|`-G` _`group_list`_|List of additional (other than default) group names or group numbers, separated by commas, of which the user is a member. The groups must exist prior to being specified here.|
|`-m`|Create the home directory if it does not exist.|
|`-M`|Do not create the home directory.|
|`-N`|Do not create a user private group for the user.|
|`-p` _`password`_|The password encrypted with **crypt**.|
|`-r`|Create a system account with a UID less than 1000 and without a home directory.|
|`-s`|User's login shell, which defaults to **/bin/bash**.|
|`-u` _`uid`_|User ID for the user, which must be unique and greater than 999.|
#### Explaining the Process {#bh-users-tools-users-add-explanation}
The following steps illustrate what happens if the command **useradd juan** is issued on a system that has shadow passwords enabled:
1. A new line for `juan` is created in `/etc/passwd`:
juan:x:501:501::/home/juan:/bin/bash
The line has the following characteristics:
* It begins with the username `juan`.
* There is an `x` for the password field indicating that the system is using shadow passwords.
* A UID greater than 999 is created. Under Fedora, UIDs below 1000 are reserved for system use and should not be assigned to users.
* A GID greater than 999 is created. Under Fedora, GIDs below 1000 are reserved for system use and should not be assigned to users.
* The optional _GECOS_ information is left blank.
* The home directory for `juan` is set to `/home/juan/`.
* The default shell is set to **/bin/bash**.
1. A new line for `juan` is created in `/etc/shadow`:
juan:!!:14798:0:99999:7:::
The line has the following characteristics:
* It begins with the username `juan`.
* Two exclamation marks (`!!`) appear in the password field of the `/etc/shadow` file, which locks the account.
### Note
If an encrypted password is passed using the `-p` flag, it is placed in the `/etc/shadow` file on the new line for the user.
* The password is set to never expire.
1. A new line for a group named `juan` is created in `/etc/group`:
juan:x:501:
A group with the same name as a user is called a _user private group_. For more information on user private groups, refer to [Section 4.1.1, “User Private Groups”](#s2-users-groups-private-groups "4.1.1. User Private Groups").
The line created in `/etc/group` has the following characteristics:
* It begins with the group name `juan`.
* An `x` appears in the password field indicating that the system is using shadow group passwords.
* The GID matches the one listed for user `juan` in `/etc/passwd`.
1. A new line for a group named `juan` is created in `/etc/gshadow`:
juan:!::
The line has the following characteristics:
* It begins with the group name `juan`.
* An exclamation mark (`!`) appears in the password field of the `/etc/gshadow` file, which locks the group.
* All other fields are blank.
1. A directory for user `juan` is created in the `/home/` directory:
~]# **ls -l /home**
total 4
drwx------. 4 juan juan 4096 Mar 3 18:23 juan
This directory is owned by user `juan` and group `juan`. It has _read_, _write_, and _execute_ privileges _only_ for the user `juan`. All other permissions are denied.
1. The files within the `/etc/skel/` directory (which contain default user settings) are copied into the new `/home/juan/` directory. The contents of `/etc/skel/` may vary depending on installed applications.
~]# **ls -la /home/juan**
total 28
drwx------. 4 juan juan 4096 Mar 3 18:23 .
drwxr-xr-x. 5 root root 4096 Mar 3 18:23 ..
-rw-r--r--. 1 juan juan 18 Jul 09 08:43 .bash_logout
-rw-r--r--. 1 juan juan 176 Jul 09 08:43 .bash_profile
-rw-r--r--. 1 juan juan 124 Jul 09 08:43 .bashrc
drwxr-xr-x. 4 juan juan 4096 Jul 09 08:43 .mozilla
-rw-r--r--. 1 juan juan 658 Jul 09 08:43 .zshrc
At this point, a locked account called `juan` exists on the system. To activate it, the administrator must next assign a password to the account using the **passwd** command and, optionally, set password aging guidelines.
### 4\.4.2. Adding a New Group {#s2-users-tools-groups-add}
To add a new group to the system, type the following at a shell prompt as `root`:
**groupadd** [_`options`_] _`group_name`_
…where _`options`_ are command line options as described in [Table 4.3, “groupadd command line options”](#table-groupadd-options "Table 4.3. groupadd command line options").
Table 4.3. groupadd command line options
|Option|Description|
|-|
|`-f`, `--force`|When used with `-g` _`gid`_ and _`gid`_ already exists, **groupadd** will choose another unique _`gid`_ for the group.|
|`-g` _`gid`_|Group ID for the group, which must be unique and greater than 999.|
|`-K`, `--key` _`key`_=_`value`_|Override `/etc/login.defs` defaults.|
|`-o`, `--non-unique`|Allow to create groups with duplicate.|
|`-p`, `--password` _`password`_|Use this encrypted password for the new group.|
|`-r`|Create a system group with a GID less than 1000.|
### 4\.4.3. Enabling Password Aging {#s2-users-tools-password-aging}
For security reasons, it is advisable to require users to change their passwords periodically. This can either be done when adding or editing a user on the Password Info tab of the User Manager application, or by using the **chage** command.
### Shadow passwords must be enabled to use chage
Shadow passwords must be enabled to use the **chage** command. For more information, see [Section 4.1.2, “Shadow Passwords”](#s2-users-groups-shadow-utilities "4.1.2. Shadow Passwords").
To configure password expiration for a user from a shell prompt, run the following command as `root`:
**chage** [_`options`_] _`username`_
…where _`options`_ are command line options as described in [Table 4.4, “chage command line options”](#table-chage-options "Table 4.4. chage command line options"). When the **chage** command is followed directly by a username (that is, when no command line options are specified), it displays the current password aging values and allows you to change them interactively.
Table 4.4. chage command line options
|Option|Description|
|-|
|`-d` _`days`_|Specifies the number of days since January 1, 1970 the password was changed.|
|`-E` _`date`_|Specifies the date on which the account is locked, in the format YYYY-MM-DD. Instead of the date, the number of days since January 1, 1970 can also be used.|
|`-I` _`days`_|Specifies the number of inactive days after the password expiration before locking the account. If the value is `0`, the account is not locked after the password expires.|
|`-l`|Lists current account aging settings.|
|`-m` _`days`_|Specify the minimum number of days after which the user must change passwords. If the value is `0`, the password does not expire.|
|`-M` _`days`_|Specify the maximum number of days for which the password is valid. When the number of days specified by this option plus the number of days specified with the `-d` option is less than the current day, the user must change passwords before using the account.|
|`-W` _`days`_|Specifies the number of days before the password expiration date to warn the user.|
You can configure a password to expire the first time a user logs in. This forces users to change passwords immediately.
1. Set up an initial password. There are two common approaches to this step: you can either assign a default password, or you can use a null password.
To assign a default password, type the following at a shell prompt as `root`:
**passwd** _`username`_
To assign a null password instead, use the following command:
**passwd** `-d` _`username`_
### Avoid using null passwords whenever possible
Using a null password, while convenient, is a highly insecure practice, as any third party can log in first and access the system using the insecure username. Always make sure that the user is ready to log in before unlocking an account with a null password.
1. Force immediate password expiration by running the following command as `root`:
**chage** `-d` `0` _`username`_
This command sets the value for the date the password was last changed to the epoch (January 1, 1970). This value forces immediate password expiration no matter what password aging policy, if any, is in place.
Upon the initial log in, the user is now prompted for a new password.
### 4\.4.4. Enabling Automatic Logouts {#s2-users-tools-users-logout}
Especially when the user is logged in as `root`, an unattended login session may pose a significant security risk. To reduce this risk, you can configure the system to automatically log out idle users after a fixed period of time:
1. Make sure the screen package is installed. You can do so by running the following command as `root`:
**yum** `install` `screen`
For more information on how to install packages in Fedora, refer to [Section 5.2.4, “Installing Packages”](#sec-Installing "5.2.4. Installing Packages").
1. As `root`, add the following line at the beginning of the `/etc/profile` file to make sure the processing of this file cannot be interrupted:
trap "" 1 2 3 15
1. Add the following lines at the end of the `/etc/profile` file to start a **screen** session each time a user logs in to a virtual console or remotely:
SCREENEXEC="screen"
if [ -w $(tty) ]; then
trap "exec $SCREENEXEC" 1 2 3 15
echo -n 'Starting session in 10 seconds'
sleep 10
exec $SCREENEXEC
fi
Note that each time a new session starts, a message will be displayed and the user will have to wait ten seconds. To adjust the time to wait before starting a session, change the value after the **sleep** command.
1. Add the following lines to the `/etc/screenrc` configuration file to close the **screen** session after a given period of inactivity:
idle 120 quit
autodetach off
This will set the time limit to 120 seconds. To adjust this limit, change the value after the `idle` directive.
Alternatively, you can configure the system to only lock the session by using the following lines instead:
idle 120 lockscreen
autodetach off
This way, a password will be required to unlock the session.
The changes take effect the next time a user logs in to the system.
### 4\.4.5. Creating Group Directories {#s2-users-tools-groups-directories}
System administrators usually like to create a group for each major project and assign people to the group when they need to access that project's files. With this traditional scheme, file managing is difficult; when someone creates a file, it is associated with the primary group to which they belong. When a single person works on multiple projects, it becomes difficult to associate the right files with the right group. However, with the UPG scheme, groups are automatically assigned to files created within a directory with the _setgid_ bit set. The setgid bit makes managing group projects that share a common directory very simple because any files a user creates within the directory are owned by the group which owns the directory.
For example, a group of people need to work on files in the `/opt/myproject/` directory. Some people are trusted to modify the contents of this directory, but not everyone.
1. As `root`, create the `/opt/myproject/` directory by typing the following at a shell prompt:
**mkdir /opt/myproject**
1. Add the `myproject` group to the system:
**groupadd myproject**
1. Associate the contents of the `/opt/myproject/` directory with the `myproject` group:
**chown root:myproject /opt/myproject**
1. Allow users to create files within the directory, and set the setgid bit:
**chmod 2775 /opt/myproject**
At this point, all members of the `myproject` group can create and edit files in the `/opt/myproject/` directory without the administrator having to change file permissions every time users write new files. To verify that the permissions have been set correctly, run the following command:
~]# **ls -l /opt**
total 4
drwxrwsr-x. 3 root myproject 4096 Mar 3 18:31 myproject
## 4\.5. Additional Resources {#s1-users-groups-additional-resources}
See the following resources for more information about managing users and groups.
### 4\.5.1. Installed Documentation {#s2-users-groups-documentation}
For information about various utilities for managing users and groups, refer to the following manual pages:
* **chage**(1) — A command to modify password aging policies and account expiration.
* **gpasswd**(1) — A command to administer the `/etc/group` file.
* **groupadd**(8) — A command to add groups.
* **grpck**(8) — A command to verify the `/etc/group` file.
* **groupdel**(8) — A command to remove groups.
* **groupmod**(8) — A command to modify group membership.
* **pwck**(8) — A command to verify the `/etc/passwd` and `/etc/shadow` files.
* **pwconv**(8) — A tool to convert standard passwords to shadow passwords.
* **pwunconv**(8) — A tool to convert shadow passwords to standard passwords.
* **useradd**(8) — A command to add users.
* **userdel**(8) — A command to remove users.
* **usermod**(8) — A command to modify users.
For information about related configuration files, see:
* **group**(5) — The file containing group information for the system.
* **passwd**(5) — The file containing user information for the system.
* **shadow**(5) — The file containing passwords and account expiration information for the system.
# Part II. Package Management {#part-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 Yum.
## Chapter 5. Yum {#ch-yum}
Yum is the The Fedora Project 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 plug-ins 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 {#important-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. See [Section 5.3, “Configuring Yum and Yum Repositories”](#sec-Configuring_Yum_and_Yum_Repositories "5.3. Configuring Yum and Yum Repositories") for details on enabling signature-checking with Yum, or [Section A.3, “Checking a Package's Signature”](#s1-check-rpm-sig "A.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.
### Yum and superuser privileges {#note-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.
## 5\.1. Checking For and Updating Packages {#sec-Checking_For_and_Updating_Packages}
### 5\.1.1. Checking For Updates {#sec-Checking_For_Updates}
To see which installed packages on your system have updates available, use the following command:
**yum** `check-update`
For example:
~]# **yum check-update**
Loaded plugins: langpacks, presto, refresh-packagekit
PackageKit.x86_64 0.6.14-2.fc15 fedora
PackageKit-command-not-found.x86_64 0.6.14-2.fc15 fedora
PackageKit-device-rebind.x86_64 0.6.14-2.fc15 fedora
PackageKit-glib.x86_64 0.6.14-2.fc15 fedora
PackageKit-gstreamer-plugin.x86_64 0.6.14-2.fc15 fedora
PackageKit-gtk-module.x86_64 0.6.14-2.fc15 fedora
PackageKit-gtk3-module.x86_64 0.6.14-2.fc15 fedora
PackageKit-yum.x86_64 0.6.14-2.fc15 fedora
PackageKit-yum-plugin.x86_64 0.6.14-2.fc15 fedora
gdb.x86_64 7.2.90.20110429-36.fc15 fedora
kernel.x86_64 2.6.38.6-26.fc15 fedora
rpm.x86_64 4.9.0-6.fc15 fedora
rpm-libs.x86_64 4.9.0-6.fc15 fedora
rpm-python.x86_64 4.9.0-6.fc15 fedora
yum.noarch 3.2.29-5.fc15 fedora
The packages in the above output are listed as having updates available. The first package in the list is PackageKit, the graphical package manager. The line in the example output tells us:
* `PackageKit` — the name of the package
* `x86_64` — the CPU architecture the package was built for
* `0.6.14` — 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**.
### 5\.1.2. Updating Packages {#sec-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.
#### Updating a Single Package {#bh-Updating_a_Single_Package}
To update a single package, run the following command as `root`:
**yum** `update` _`package_name`_
For example, to update the udev package, type:
~]# **yum update udev**
Loaded plugins: langpacks, presto, refresh-packagekit
Updating Red Hat repositories.
INFO:rhsm-app.repolib:repos updated: 0
Setting up Update Process
Resolving Dependencies
--> Running transaction check
---> Package gdb.x86_64 0:7.2.90.20110411-34.fc15 will be updated
---> Package gdb.x86_64 0:7.2.90.20110429-36.fc15 will be an update
--> Finished Dependency Resolution
Dependencies Resolved
================================================================================
Package Arch Version Repository Size
================================================================================
Updating:
gdb x86_64 7.2.90.20110429-36.fc15 fedora 1.9 M
Transaction Summary
================================================================================
Upgrade 1 Package(s)
Total download size: 1.9 M
Is this ok [y/N]:
This output contains several items of interest:
1. `Loaded plugins:` — **yum** always informs you which Yum plug-ins are installed and enabled. Here, **yum** is using the langpacks, presto, and refresh-packagekit plug-ins. See [Section 5.4, “Yum Plug-ins”](#sec-Yum_Plugins "5.4. Yum Plug-ins") for general information on Yum plug-ins, or to [Section 5.4.3, “Plug-in Descriptions”](#sec-Plugin_Descriptions "5.4.3. Plug-in Descriptions") for descriptions of specific plug-ins.
1. `gdb.x86_64` — you can download and install new gdb package.
1. **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 transaction history by using the **yum history** command as described in [Section 5.2.6, “Working with Transaction History”](#sec-Yum-Transaction_History "5.2.6. Working with Transaction History").
### Updating and installing kernels with Yum {#important-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). See [Section A.2.2, “Installing and Upgrading”](#sec-Installing_and_Upgrading "A.2.2. Installing and Upgrading") for more information on installing/updating kernels with RPM.
#### Updating All Packages and Their Dependencies {#bh-Updating_All_Packages_and_Their_Dependencies}
To update all packages and their dependencies, simply enter **yum update** (without any arguments):
**yum update**
#### Updating Security-Related Packages {#bh-Updating_Security-Related_Packages}
Discovering which packages have security updates available and then updating those packages quickly and easily is important. Yum provides the plug-in for this purpose. The security plug-in extends the **yum** command with a set of highly-useful security-centric commands, subcommands and options. See [Section 5.4.3, “Plug-in Descriptions”](#sec-Plugin_Descriptions "5.4.3. Plug-in Descriptions") for specific information.
### 5\.1.3. Preserving Configuration File Changes {#sec-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. See [Section A.2.2, “Installing and Upgrading”](#sec-Installing_and_Upgrading "A.2.2. Installing and Upgrading") for details on how to manage changes to configuration files across package upgrades.
## 5\.2. Packages and Package Groups {#sec-Packages_and_Package_Groups}
### 5\.2.1. Searching Packages {#sec-Searching_Packages}
You can search all RPM package names, descriptions and summaries by using the following command:
**yum** `search` _`term`_…
This command displays the list of matches for each term. For example, to list all packages that match “meld” or “kompare”, type:
~]# **yum search meld kompare**
Loaded plugins: langpacks, presto, refresh-packagekit
============================== N/S Matched: meld ===============================
meld.noarch : Visual diff and merge tool
python-meld3.x86_64 : HTML/XML templating system for Python
============================= N/S Matched: kompare =============================
komparator.x86_64 : Kompare and merge two folders
Name and summary matches only, use "search all" for everything.
The **yum search** command is useful for searching for packages you do not know the name of, but for which you know a related term.
### 5\.2.2. Listing Packages {#sec-Listing_Packages}
**yum list** and related commands provide information about packages, package groups, and repositories.
All of Yum's list commands allow you to filter the results by appending one or more _glob expressions_ as arguments. Glob expressions are normal strings of characters which contain one or more of the wildcard characters **\*** (which expands to match any character multiple times) and **?** (which expands to match any one character).
### Filtering results with glob expressions {#note-Tip-Filtering_Results_with_Glob_Expressions}
Be careful to escape the glob expressions when passing them as arguments to a **yum** command, otherwise the Bash shell will interpret these expressions as _pathname expansions_, and potentially pass all files in the current directory that match the globs to **yum**. To make sure the glob expressions are passed to **yum** as intended, either:
* escape the wildcard characters by preceding them with a backslash character
* double-quote or single-quote the entire glob expression.
See [Example 5.1, “Listing all ABRT addons and plug-ins using glob expressions”](#ex-Listing_all_ABRT_addons_and_plugins_using_glob_expressions "Example 5.1. Listing all ABRT addons and plug-ins using glob expressions") and [Example 5.4, “Listing available packages using a single glob expression with escaped wildcard characters”](#ex-Listing_available_packages_using_a_single_glob_expression_with_escaped_wildcards "Example 5.4. Listing available packages using a single glob expression with escaped wildcard characters") for an example usage of both these methods.
**yum list _`glob_expression`_…**
: Lists information on installed and available packages matching all glob expressions.
Example 5.1. Listing all ABRT addons and plug-ins using glob expressions
Packages with various ABRT addons and plug-ins either begin with “abrt-addon-”, or “abrt-plugin-”. To list these packages, type the following at a shell prompt:
~]# **yum list abrt-addon\* abrt-plugin\***
Loaded plugins: langpacks, presto, refresh-packagekit
Installed Packages
abrt-addon-ccpp.x86_64 2.0.2-5.fc15 @fedora
abrt-addon-kerneloops.x86_64 2.0.2-5.fc15 @fedora
abrt-addon-python.x86_64 2.0.2-5.fc15 @fedora
abrt-plugin-bugzilla.x86_64 2.0.2-5.fc15 @fedora
abrt-plugin-logger.x86_64 2.0.2-5.fc15 @fedora
Available Packages
abrt-plugin-mailx.x86_64 2.0.2-5.fc15 updates
abrt-plugin-reportuploader.x86_64 2.0.2-5.fc15 updates
abrt-plugin-rhtsupport.x86_64 2.0.2-5.fc15 updates
**yum list all**
: Lists all installed _and_ available packages.
Example 5.2. Listing all installed and available packages
~]# **yum list all**
Loaded plugins: langpacks, presto, refresh-packagekit
Installed Packages
ConsoleKit.x86_64 0.4.4-1.fc15 @fedora
ConsoleKit-libs.x86_64 0.4.4-1.fc15 @fedora
ConsoleKit-x11.x86_64 0.4.4-1.fc15 @fedora
GConf2.x86_64 2.32.3-1.fc15 @fedora
GConf2-gtk.x86_64 2.32.3-1.fc15 @fedora
ModemManager.x86_64 0.4-7.git20110201.fc15 @fedora
NetworkManager.x86_64 1:0.8.998-4.git20110427.fc15 @fedora
NetworkManager-glib.x86_64 1:0.8.998-4.git20110427.fc15 @fedora
NetworkManager-gnome.x86_64 1:0.8.998-4.git20110427.fc15 @fedora
NetworkManager-openconnect.x86_64 0.8.1-9.git20110419.fc15 @fedora
_[output truncated]_
**yum list installed**
: Lists all packages installed on your system. The rightmost column in the output lists the repository from which the package was retrieved.
Example 5.3. Listing installed packages using a double-quoted glob expression
To list all installed packages that begin with “krb” followed by exactly one character and a hyphen, type:
~]# **yum list installed "krb?-*"**
Loaded plugins: langpacks, presto, refresh-packagekit
Installed Packages
krb5-libs.x86_64 1.9-7.fc15 @fedora
**yum list available**
: Lists all available packages in all enabled repositories.
Example 5.4. Listing available packages using a single glob expression with escaped wildcard characters
To list all available packages with names that contain “gstreamer” and then “plugin”, run the following command:
~]# **yum list available gstreamer\*plugin\***
Loaded plugins: langpacks, presto, refresh-packagekit
Available Packages
gstreamer-plugin-crystalhd.x86_64 3.5.1-1.fc14 fedora
gstreamer-plugins-bad-free.x86_64 0.10.22-1.fc15 updates
gstreamer-plugins-bad-free-devel.x86_64 0.10.22-1.fc15 updates
gstreamer-plugins-bad-free-devel-docs.x86_64 0.10.22-1.fc15 updates
gstreamer-plugins-bad-free-extras.x86_64 0.10.22-1.fc15 updates
gstreamer-plugins-base.x86_64 0.10.33-1.fc15 updates
gstreamer-plugins-base-devel.x86_64 0.10.33-1.fc15 updates
gstreamer-plugins-base-devel-docs.noarch 0.10.33-1.fc15 updates
gstreamer-plugins-base-tools.x86_64 0.10.33-1.fc15 updates
gstreamer-plugins-espeak.x86_64 0.3.3-3.fc15 fedora
gstreamer-plugins-fc.x86_64 0.2-2.fc15 fedora
gstreamer-plugins-good.x86_64 0.10.29-1.fc15 updates
gstreamer-plugins-good-devel-docs.noarch 0.10.29-1.fc15 updates
**yum grouplist**
: Lists all package groups.
Example 5.5. Listing all package groups
~]# **yum grouplist**
Loaded plugins: langpacks, presto, refresh-packagekit
Setting up Group Process
Installed Groups:
Administration Tools
Design Suite
Dial-up Networking Support
Fonts
GNOME Desktop Environment
_[output truncated]_
**yum repolist**
: Lists the repository ID, name, and number of packages it provides for each _enabled_ repository.
Example 5.6. Listing enabled repositories
~]# **yum repolist**
Loaded plugins: langpacks, presto, refresh-packagekit
repo id repo name status
fedora Fedora 15 - i386 19,365
updates Fedora 15 - i386 - Updates 3,848
repolist: 23,213
### 5\.2.3. Displaying Package Information {#sec-Displaying_Package_Information}
To display information about one or more packages (glob expressions are valid here as well), use the following command:
**yum** `info` _`package_name`_…
For example, to display information about the abrt package, type:
~]# **yum info abrt**
Loaded plugins: langpacks, presto, refresh-packagekit
Installed Packages
Name : abrt
Arch : x86_64
Version : 2.0.1
Release : 2.fc15
Size : 806 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 a bug report with all informations needed by maintainer
: to fix it. It uses plugin system to extend its functionality.
The **yum info _`package_name`_** command 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).
You can also query the Yum database for alternative and useful information about a package by using the following command:
**yumdb** `info` _`package_name`_
This command provides additional information about a package, including the checksum of the package (and algorithm used to produce it, such as SHA-256), the command given on the command line that was invoked to install the package (if any), and the reason that the package is installed on the system (where `user` indicates it was installed by the user, and `dep` means it was brought in as a dependency). For example, to display additional information about the yum package, type:
~]# **yumdb info yum**
Loaded plugins: langpacks, presto, refresh-packagekit
yum-3.2.29-4.fc15.noarch
checksum_data = 249f21fb43c41381c8c9b0cd98d2ea5fa0aa165e81ed2009cfda74c05af67246
checksum_type = sha256
from_repo = fedora
from_repo_revision = 1304429533
from_repo_timestamp = 1304442346
installed_by = 0
reason = user
releasever = $releasever
For more information on the **yumdb** command, refer to the **yumdb**(8) manual page.
### 5\.2.4. Installing Packages {#sec-Installing}
Yum allows you to install both a single package and multiple packages, as well as a package group of your choice.
#### Installing Individual Packages {#bh-Installing_Individual_packages}
To install a single package and all of its non-installed dependencies, enter a command in the following form:
**yum** `install` _`package_name`_
You can also install multiple packages simultaneously by appending their names as arguments:
**yum** `install` _`package_name`_ _`package_name`_…
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 is available in an enabled repository) by appending _`.arch`_ to the package name. For example, to install the sqlite2 package for `i586`, type:
~]# **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.
### Finding which package owns a file {#note-Finding_which_package_owns_a_file}
If you know you want to install the package that contains the `named` binary, but you do not know in which `bin` or `sbin` directory is the file installed, use the **yum provides** command with a glob expression:
~]# **yum provides "*bin/named"**
Loaded plugins: langpacks, presto, refresh-packagekit
32:bind-9.8.0-3.P1.fc15.i686 : The Berkeley Internet Name Domain (BIND) DNS
: (Domain Name System) server
Repo : fedora
Matched from:
Filename : /usr/sbin/named
**yum provides "\*/_`file_name`_"** is a common and useful trick to find the packages that contain _`file_name`_.
#### Installing a Package Group {#bh-Installing_a_Package_Group}
A package group is similar to a package: it is not useful by itself, but installing one pulls 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` in the following example:
~]# **yum -v grouplist kde\***
Not loading "blacklist" plugin, as it is disabled
Loading "langpacks" plugin
Loading "presto" plugin
Loading "refresh-packagekit" plugin
Not loading "whiteout" plugin, as it is disabled
Adding en_US to language list
Config time: 0.900
Yum Version: 3.2.29
Setting up Group Process
rpmdb time: 0.002
group time: 0.995
Available Groups:
KDE Software Compilation (kde-desktop)
KDE Software Development (kde-software-development)
Done
You can install a package group by passing its full group name (without the groupid part) to **groupinstall**:
**yum** `groupinstall` _`group_name`_
You can also install by groupid:
**yum** `groupinstall` _`groupid`_
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` @_`group`_
For example, the following are alternative but equivalent ways of installing the `KDE Desktop` group:
~]# **yum groupinstall "KDE Desktop"**
~]# **yum groupinstall kde-desktop**
~]# **yum install @kde-desktop**
### 5\.2.5. Removing Packages {#sec-Removing}
Similarly to package installation, Yum allows you to uninstall (remove in RPM and Yum terminology) both individual packages and a package group.
#### Removing Individual Packages {#bh-Removing_Individual_Packages}
To uninstall a particular package, as well as any packages that depend on it, run the following command as `root`:
**yum** `remove` _`package_name`_…
As when you install multiple packages, you can remove several at once by adding more package names to the command. For example, to remove totem, rhythmbox, and sound-juicer, type the following at a shell prompt:
~]# **yum remove totem rhythmbox sound-juicer**
Similar to **install**, **remove** can take these arguments:
* package names
* glob expressions
* file lists
* package provides
### Removing a package when other packages depend on it {#warning-WarningRemoving_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 A.2.4, “Uninstalling”](#s2-rpm-uninstalling "A.2.4. Uninstalling") in the RPM chapter.
#### Removing a Package Group {#bh-Removing_a_Package_Group}
You can remove a package group using syntax congruent with the **install** syntax:
**yum** `groupremove` _`group`_
**yum** `remove` @_`group`_
The following are alternative but equivalent ways of removing the `KDE Desktop` group:
~]# **yum groupremove "KDE Desktop"**
~]# **yum groupremove kde-desktop**
~]# **yum remove @kde-desktop**
### Intelligent package group removal {#important-Package_Group_Removal}
When you tell yum to remove a package group, it will remove every package in that group, even if those packages are members of other package groups or dependencies of other installed packages. However, you can instruct **yum** to remove only those packages which are not required by any other packages or groups by adding the `groupremove_leaf_only=1` directive to the `[main]` section of the `/etc/yum.conf` configuration file. For more information on this directive, refer to [Section 5.3.1, “Setting [main] Options”](#sec-Setting_main_Options "5.3.1. Setting [main] Options").
### 5\.2.6. Working with Transaction History {#sec-Yum-Transaction_History}
The **yum history** command allows users to review information about a timeline of Yum transactions, the dates and times on when they occurred, the number of packages affected, whether transactions succeeded or were aborted, and if the RPM database was changed between transactions. Additionally, this command can be used to undo or redo certain transactions.
#### Listing Transactions {#bh-Yum-Transaction_History-Listing}
To display a list of twenty most recent transactions, as `root`, either run **yum history** with no additional arguments, or type the following at a shell prompt:
**yum** `history` `list`
To display all transactions, add the `all` keyword:
**yum** `history` `list` `all`
To display only transactions in a given range, use the command in the following form:
**yum** `history` `list` _`start_id`_.._`end_id`_
You can also list only transactions regarding a particular package or packages. To do so, use the command with a package name or a glob expression:
**yum** `history` `list` _`glob_expression`_…
For example, the list of first five transactions may look as follows:
~]# **yum history list 1..5**
Loaded plugins: langpacks, presto, refresh-packagekit
ID | Login user | Date and time | Action(s) | Altered
-------------------------------------------------------------------------------
5 | Jaromir ... <jhradilek> | 2011-07-29 15:33 | Install | 1
4 | Jaromir ... <jhradilek> | 2011-07-21 15:10 | Install | 1
3 | Jaromir ... <jhradilek> | 2011-07-16 15:27 | I, U | 73
2 | System <unset> | 2011-07-16 15:19 | Update | 1
1 | System <unset> | 2011-07-16 14:38 | Install | 1106
history list
All forms of the **yum history list** command produce tabular output with each row consisting of the following columns:
* `ID` — an integer value that identifies a particular transaction.
* `Login user` — the name of the user whose login session was used to initiate a transaction. This information is typically presented in the ``_`Full Name`_ <_`username>`_`` form. For transactions that were not issued by a user (such as an automatic system update), `System ` is used instead.
* `Date and time` — the date and time when a transaction was issued.
* `Action(s)` — a list of actions that were performed during a transaction as described in [Table 5.1, “Possible values of the Action(s) field”](#tabl-Yum-Transaction_History-Actions "Table 5.1. Possible values of the Action(s) field").
* `Altered` — the number of packages that were affected by a transaction, possibly followed by additional information as described in [Table 5.2, “Possible values of the Altered field”](#tabl-Yum-Transaction_History-Altered "Table 5.2. Possible values of the Altered field").
Table 5.1. Possible values of the Action(s) field
|Action|Abbreviation|Description|
|-|
|`Downgrade`|`D`|At least one package has been downgraded to an older version.|
|`Erase`|`E`|At least one package has been removed.|
|`Install`|`I`|At least one new package has been installed.|
|`Obsoleting`|`O`|At least one package has been marked as obsolete.|
|`Reinstall`|`R`|At least one package has been reinstalled.|
|`Update`|`U`|At least one package has been updated to a newer version.|
Table 5.2. Possible values of the Altered field
|Symbol|Description|
|-|
|`<`|Before the transaction finished, the `rpmdb` database was changed outside Yum.|
|`>`|After the transaction finished, the `rpmdb` database was changed outside Yum.|
|`*`|The transaction failed to finish.|
|`#`|The transaction finished successfully, but **yum** returned a non-zero exit code.|
|`E`|The transaction finished successfully, but an error or a warning was displayed.|
|`P`|The transaction finished successfully, but problems already existed in the `rpmdb` database.|
|`s`|The transaction finished successfully, but the `--skip-broken` command line option was used and certain packages were skipped.|
Yum also allows you to display a summary of all past transactions. To do so, run the command in the following form as `root`:
**yum** `history` `summary`
To display only transactions in a given range, type:
**yum** `history` `summary` _`start_id`_.._`end_id`_
Similarly to the **yum history list** command, you can also display a summary of transactions regarding a certain package or packages by supplying a package name or a glob expression:
**yum** `history` `summary` _`glob_expression`_…
For instance, a summary of the transaction history displayed above would look like the following:
~]# **yum history summary 1..5**
Loaded plugins: langpacks, presto, refresh-packagekit
Login user | Time | Action(s) | Altered
-------------------------------------------------------------------------------
Jaromir ... <jhradilek> | Last day | Install | 1
Jaromir ... <jhradilek> | Last week | Install | 1
Jaromir ... <jhradilek> | Last 2 weeks | I, U | 73
System <unset> | Last 2 weeks | I, U | 1107
history summary
All forms of the **yum history summary** command produce simplified tabular output similar to the output of **yum history list**.
As shown above, both **yum history list** and **yum history summary** are oriented towards transactions, and although they allow you to display only transactions related to a given package or packages, they lack important details, such as package versions. To list transactions from the perspective of a package, run the following command as `root`:
**yum** `history` `package-list` _`glob_expression`_…
For example, to trace the history of subscription-manager and related packages, type the following at a shell prompt:
~]# **yum history package-list subscription-manager\***
Loaded plugins: langpacks, presto, refresh-packagekit
ID | Action(s) | Package
-------------------------------------------------------------------------------
3 | Updated | subscription-manager-0.95.11-1.el6.x86_64
3 | Update | 0.95.17-1.el6_1.x86_64
3 | Updated | subscription-manager-firstboot-0.95.11-1.el6.x86_64
3 | Update | 0.95.17-1.el6_1.x86_64
3 | Updated | subscription-manager-gnome-0.95.11-1.el6.x86_64
3 | Update | 0.95.17-1.el6_1.x86_64
1 | Install | subscription-manager-0.95.11-1.el6.x86_64
1 | Install | subscription-manager-firstboot-0.95.11-1.el6.x86_64
1 | Install | subscription-manager-gnome-0.95.11-1.el6.x86_64
history package-list
In this example, three packages were installed during the initial system installation: subscription-manager, subscription-manager-firstboot, and subscription-manager-gnome. In the third transaction, all these packages were updated from version 0.95.11 to version 0.95.17.
#### Examining Transactions {#bh-Yum-Transaction_History-Examining}
To display the summary of a single transaction, as `root`, use the **yum history summary** command in the following form:
**yum** `history` `summary` _`id`_
To examine a particular transaction or transactions in more detail, run the following command as `root`:
**yum** `history` `info` _`id`_…
The _`id`_ argument is optional and when you omit it, **yum** automatically uses the last transaction. Note that when specifying more than one transaction, you can also use a range:
**yum** `history` `info` _`start_id`_.._`end_id`_
The following is sample output for two transactions, each installing one new package:
~]# **yum history info 4..5**
Loaded plugins: langpacks, presto, refresh-packagekit
Transaction ID : 4..5
Begin time : Thu Jul 21 15:10:46 2011
Begin rpmdb : 1107:0c67c32219c199f92ed8da7572b4c6df64eacd3a
End time : 15:33:15 2011 (22 minutes)
End rpmdb : 1109:1171025bd9b6b5f8db30d063598f590f1c1f3242
User : Jaromir Hradilek <jhradilek>
Return-Code : Success
Command Line : install screen
Command Line : install yum-plugin-fs-snapshot
Transaction performed with:
Installed rpm-4.8.0-16.el6.x86_64
Installed yum-3.2.29-17.el6.noarch
Installed yum-metadata-parser-1.1.2-16.el6.x86_64
Packages Altered:
Install screen-4.0.3-16.el6.x86_64
Install yum-plugin-fs-snapshot-1.1.30-6.el6.noarch
history info
You can also view additional information, such as what configuration options were used at the time of the transaction, or from what repository and why were certain packages installed. To determine what additional information is available for a certain transaction, type the following at a shell prompt as `root`:
**yum** `history` `addon-info` _`id`_
Similarly to **yum history info**, when no _`id`_ is provided, **yum** automatically uses the latest transaction. Another way to refer to the latest transaction is to use the `last` keyword:
**yum** `history` `addon-info` `last`
For instance, for the first transaction in the previous example, the **yum history addon-info** command would provide the following output:
~]# **yum history addon-info 4**
Loaded plugins: langpacks, presto, refresh-packagekit
Transaction ID: 4
Available additional history information:
config-main
config-repos
saved_tx
history addon-info
In this example, three types of information are available:
* `config-main` — global Yum options that were in use during the transaction. See [Section 5.3.1, “Setting [main] Options”](#sec-Setting_main_Options "5.3.1. Setting [main] Options") for information on how to change global options.
* `config-repos` — options for individual Yum repositories. See [Section 5.3.2, “Setting [repository] Options”](#sec-Setting_repository_Options "5.3.2. Setting [repository] Options") for information on how to change options for individual repositories.
* `saved_tx` — the data that can be used by the **yum load-transaction** command in order to repeat the transaction on another machine (see below).
To display selected type of additional information, run the following command as `root`:
**yum** `history` `addon-info` _`id`_ _`information`_
#### Reverting and Repeating Transactions {#bh-Yum-Transaction_History-Reverting}
Apart from reviewing the transaction history, the **yum history** command provides means to revert or repeat a selected transaction. To revert a transaction, type the following at a shell prompt as `root`:
**yum** `history` `undo` _`id`_
To repeat a particular transaction, as `root`, run the following command:
**yum** `history` `redo` _`id`_
Both commands also accept the `last` keyword to undo or repeat the latest transaction.
Note that both **yum history undo** and **yum history redo** commands merely revert or repeat the steps that were performed during a transaction: if the transaction installed a new package, the **yum history undo** command will uninstall it, and vice versa. If possible, this command will also attempt to downgrade all updated packages to their previous version, but these older packages may no longer be available. If you need to be able to restore the system to the state before an update, consider using the fs-snapshot plug-in described in [Section 5.4.3, “Plug-in Descriptions”](#sec-Plugin_Descriptions "5.4.3. Plug-in Descriptions").
When managing several identical systems, Yum also allows you to perform a transaction on one of them, store the transaction details in a file, and after a period of testing, repeat the same transaction on the remaining systems as well. To store the transaction details to a file, type the following at a shell prompt as `root`:
**yum** `-q` `history` `addon-info` _`id`_ `saved_tx` > `file_name`
Once you copy this file to the target system, you can repeat the transaction by using the following command as `root`:
**yum** `load-transaction` _`file_name`_
Note, however that the `rpmdb` version stored in the file must by identical to the version on the target system. You can verify the `rpmdb` version by using the **yum version nogroups** command.
#### Starting New Transaction History {#bh-Yum-Transaction_History-New}
Yum stores the transaction history in a single SQLite database file. To start new transaction history, run the following command as `root`:
**yum** `history` `new`
This will create a new, empty database file in the `/var/lib/yum/history/` directory. The old transaction history will be kept, but will not be accessible as long as a newer database file is present in the directory.
## 5\.3. Configuring Yum and Yum Repositories {#sec-Configuring_Yum_and_Yum_Repositories}
The configuration file for **yum** and related utilities is located at `/etc/yum.conf`. This file contains one mandatory `[main]` section, which allows you to set Yum options that have global effect, and may also contain one or more ``[_`repository`_]`` sections, which allow you to set repository-specific options. However, best practice is to define individual repositories in new or existing `.repo` files in the `/etc/yum.repos.d/`directory. The values you define in the `[main]` section of the `/etc/yum.conf` file may override values set in individual ``[_`repository`_]`` sections.
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 the `/etc/yum.repos.d/` directory so that dynamic version and architecture values are handled correctly;
* add, enable, and disable Yum repositories on the command line; and,
* set up your own custom Yum repository.
### 5\.3.1. Setting [main] Options {#sec-Setting_main_Options}
The `/etc/yum.conf` configuration file contains exactly one `[main]` section, and while some of the key-value pairs in this section affect how **yum** operates, others affect how Yum treats repositories. You can add many additional options under the `[main]` section heading in `/etc/yum.conf`.
A sample `/etc/yum.conf` configuration file can look like this:
[main]
cachedir=/var/cache/yum/$basearch/$releasever
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
The following are the most commonly-used options in the `[main]` section:
`assumeyes`=_`value`_
: …where _`value`_ is one of:
`0` — **yum** should prompt for confirmation of critical actions it performs. This is the default.
`1` — Do not prompt for confirmation of critical **yum** actions. If `assumeyes=1` is set, **yum** behaves in the same way that the command line option `-y` does.
`cachedir`=_`directory`_
: …where _`directory`_ is an absolute path to the directory where Yum should store its cache and database files. By default, Yum's cache directory is `/var/cache/yum/$basearch/$releasever`.
See [Section 5.3.3, “Using Yum Variables”](#sec-Using_Yum_Variables "5.3.3. Using Yum Variables") for descriptions of the `$basearch` and `$releasever` Yum variables.
`debuglevel`=_`value`_
: …where _`value`_ is an integer between `1` and `10`. Setting a higher `debuglevel` value causes **yum** to display more detailed debugging output. `debuglevel=0` disables debugging output, while `debuglevel=2` is the default.
`exactarch`=_`value`_
: …where _`value`_ is one of:
`0` — Do not take into account the exact architecture when updating packages.
`1` — Consider the exact architecture when updating packages. With this setting, **yum** will not install an i686 package to update an i386 package already installed on the system. This is the default.
`exclude`=_`package_name`_ [_`more_package_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.
`gpgcheck`=_`value`_
: …where _`value`_ is one of:
`0` — Disable GPG signature-checking on packages in all repositories, including local package installation.
`1` — Enable GPG signature-checking on all packages in all repositories, including local package installation. `gpgcheck=1` is the default, and thus all packages' signatures are checked.
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 ``gpgcheck=_`value`_`` for individual repositories instead; that is, you can enable GPG-checking on one repository while disabling it on another. Setting ``gpgcheck=_`value`_`` for an individual repository in its corresponding `.repo` file overrides the default if it is present in `/etc/yum.conf`.
For more information on GPG signature-checking, refer to [Section A.3, “Checking a Package's Signature”](#s1-check-rpm-sig "A.3. Checking a Package's Signature").
`groupremove_leaf_only`=_`value`_
: …where _`value`_ is one of:
`0` — **yum** should _not_ check the dependencies of each package when removing a package group. With this setting, **yum** removes all packages in a package group, regardless of whether those packages are required by other packages or groups. `groupremove_leaf_only=0` is the default.
`1` — **yum** should check the dependencies of each package when removing a package group, and remove only those packages which are not not required by any other package or group.
For more information on removing packages, refer to [Intelligent package group removal](#important-Package_Group_Removal "Intelligent package group removal").
`installonlypkgs`=_`space`_ _`separated`_ _`list`_ _`of`_ _`packages`_
: Here you can provide a space-separated list of packages which **yum** can _install_, but will never _update_. See the **yum.conf**(5) manual page for the list of packages which are install-only by default.
If you add the `installonlypkgs` directive to `/etc/yum.conf`, you should ensure that you list _all_ of the packages that should be install-only, including any of those listed under the `installonlypkgs` section of **yum.conf**(5). In particular, kernel packages should always be listed in `installonlypkgs` (as they are by default), and `installonly_limit` should always be set to a value greater than `2` so that a backup kernel is always available in case the default one fails to boot.
`installonly_limit`=_`value`_
: …where _`value`_ is an integer representing the maximum number of versions that can be installed simultaneously for any single package listed in the `installonlypkgs` directive.
The defaults for the `installonlypkgs` directive include several different kernel packages, so be aware that changing the value of `installonly_limit` will also affect the maximum number of installed versions of any single kernel package. The default value listed in `/etc/yum.conf` is `installonly_limit=3`, and it is not recommended to decrease this value, particularly below `2`.
`keepcache`=_`value`_
: …where _`value`_ is one of:
`0` — Do not retain the cache of headers and packages after a successful installation. This is the default.
`1` — Retain the cache after a successful installation.
`logfile`=_`file_name`_
: …where _`file_name`_ is an absolute path to the file in which **yum** should write its logging output. By default, **yum** logs to `/var/log/yum.log`.
`multilib_policy`=_`value`_
: …where _`value`_ is one of:
`best` — install the best-choice architecture for this system. For example, setting `multilib_policy=best` on an AMD64 system causes **yum** to install 64-bit versions of all packages.
`all` — always install every possible architecture for every package. For example, with `multilib_policy` set to `all` on an AMD64 system, **yum** would install both the i586 and AMD64 versions of a package, if both were available.
`obsoletes`=_`value`_
: …where _`value`_ is one of:
`0` — Disable **yum**'s obsoletes processing logic when performing updates.
`1` — Enable **yum**'s obsoletes processing logic when performing updates. When one package declares in its spec file that it _obsoletes_ another package, the latter package will be replaced by the former package when the former package is installed. Obsoletes are declared, for example, when a package is renamed. `obsoletes=1` the default.
`plugins`=_`value`_
: …where _`value`_ is one of:
`0` — Disable all Yum plug-ins globally.
### Disabling all plug-ins is not advised {#important-Disabling_all_plugins_is_not_advised-main_options}
Disabling all plug-ins is not advised because certain plug-ins provide important **Yum** services. Disabling plug-ins globally is provided as a convenience option, and is generally only recommended when diagnosing a potential problem with **Yum**.
`1` — Enable all Yum plug-ins globally. With `plugins=1`, you can still disable a specific Yum plug-in by setting `enabled=0` in that plug-in's configuration file.
For more information about various Yum plug-ins, refer to [Section 5.4, “Yum Plug-ins”](#sec-Yum_Plugins "5.4. Yum Plug-ins"). For further information on controlling plug-ins, see [Section 5.4.1, “Enabling, Configuring, and Disabling Yum Plug-ins”](#sec-Enabling_Configuring_and_Disabling_Yum_Plugins "5.4.1. Enabling, Configuring, and Disabling Yum Plug-ins").
`reposdir`=_`directory`_
: …where _`directory`_ is an absolute path to the directory where `.repo` files are located. All `.repo` files contain repository information (similar to the ``[_`repository`_]`` sections 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. If `reposdir` is not set, **yum** uses the default directory `/etc/yum.repos.d/`.
`retries`=_`value`_
: …where _`value`_ is an integer `0` or greater. This value 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 `10`.
For a complete list of available `[main]` options, refer to the `[main] OPTIONS` section of the **yum.conf**(5) manual page.
### 5\.3.2. Setting [repository] Options {#sec-Setting_repository_Options}
The ``[_`repository`_]`` sections, where _`repository`_ is a unique repository ID such as `my_personal_repo` (spaces are not permitted), allow you to define individual Yum repositories.
The following is a bare-minimum example of the form a ``[_`repository`_]`` section takes:
[_`repository`_]
name=_`repository_name`_
baseurl=_`repository_url`_
Every ``[_`repository`_]`` section must contain the following directives:
`name`=_`repository_name`_
: …where _`repository_name`_ is a human-readable string describing the repository.
`baseurl`=_`repository_url`_
: …where _`repository_url`_ is a URL to the directory where the repodata directory of a repository is located:
* If the repository is available over HTTP, use: `http://path/to/repo`
* 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 by prepending it to the URL 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 could be specified as ``http://**`user`**:**`password`**@www.example.com/repo/``.
Usually this URL is an HTTP link, such as:
baseurl=http://path/to/repo/releases/$releasever/server/$basearch/os/
Note that Yum always expands the `$releasever`, `$arch`, and `$basearch` variables in URLs. For more information about Yum variables, refer to [Section 5.3.3, “Using Yum Variables”](#sec-Using_Yum_Variables "5.3.3. Using Yum Variables").
Another useful ``[_`repository`_]`` directive is the following:
`enabled`=_`value`_
: …where _`value`_ is one of:
`0` — Do not include this 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 or installs.
`1` — Include this repository as a package source.
Turning repositories on and off can also be performed by passing either the ``--enablerepo=_`repo_name`_`` or ``--disablerepo=_`repo_name`_`` option to **yum**, or through the Add/Remove Software window of the PackageKit utility.
Many more ``[_`repository`_]`` options exist. For a complete list, refer to the `[repository] OPTIONS` section of the **yum.conf**(5) manual page.
### 5\.3.3. Using Yum Variables {#sec-Using_Yum_Variables}
You can use and reference the following built-in variables in **yum** commands and in all Yum configuration files (that is, `/etc/yum.conf` and all `.repo` files in the `/etc/yum.repos.d/` directory):
`$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.
To define a custom variable or to override the value of an existing one, create a file with the same name as the variable (without the “`$`” sign) in the `/etc/yum/vars/` directory, and add the desired value on its first line.
For example, repository descriptions often include the operating system name. To define a new variable called `$osname`, create a new file with “Fedora” on the first line and save it as `/etc/yum/vars/osname`:
~]# **echo "Fedora" > /etc/yum/vars/osname**
Instead of “Fedora 20”, you can now use the following in the `.repo` files:
name=$osname $releasever
### 5\.3.4. Viewing the Current Configuration {#sec-Viewing_the_Current_Configuration}
To display the current values of global Yum options (that is, the options specified in the `[main]` section of the `/etc/yum.conf` file), run the **yum-config-manager** with no command line options:
**yum-config-manager**
To list the content of a different configuration section or sections, use the command in the following form:
**yum-config-manager** _`section`_…
You can also use a glob expression to display the configuration of all matching sections:
**yum-config-manager** _`glob_expression`_…
For example, to list all configuration options and their corresponding values, type the following at a shell prompt:
~]$ **yum-config-manager main \***
Loaded plugins: langpacks, presto, refresh-packagekit
================================== main ===================================
[main]
alwaysprompt = True
assumeyes = False
bandwith = 0
bugtracker_url = https://bugzilla.redhat.com/enter_bug.cgi?product=Red%20Hat%20Enterprise%20Linux%206&component=yum
cache = 0
_[output truncated]_
### 5\.3.5. Adding, Enabling, and Disabling a Yum Repository {#sec-Managing_Yum_Repositories}
[Section 5.3.2, “Setting [repository] Options”](#sec-Setting_repository_Options "5.3.2. Setting [repository] Options") described various options you can use to define a Yum repository. This section explains how to add, enable, and disable a repository by using the **yum-config-manager** command.
#### Adding a Yum Repository {#bh-Managing_Yum_Repositories-Adding}
To define a new repository, you can either add a ``[_`repository`_]`` section to the `/etc/yum.conf` file, or to a `.repo` file in the `/etc/yum.repos.d/` directory. All files with the `.repo` file extension in this directory are read by **yum**, and best practice is to define your repositories here instead of in `/etc/yum.conf`.
### Be careful when using untrusted software sources
Obtaining and installing software packages from unverified or untrusted software sources constitutes a potential security risk, and could lead to security, stability, compatibility maintainability issues.
Yum repositories commonly provide their own `.repo` file. To add such a repository to your system and enable it, run the following command as `root`:
**yum-config-manager** `--add-repo` _`repository_url`_
…where _`repository_url`_ is a link to the `.repo` file. For example, to add a repository located at http://www.example.com/example.repo, type the following at a shell prompt:
~]# **yum-config-manager --add-repo http://www.example.com/example.repo**
Loaded plugins: langpacks, presto, refresh-packagekit
adding repo from: http://www.example.com/example.repo
grabbing file http://www.example.com/example.repo to /etc/yum.repos.d/example.repo
example.repo | 413 B 00:00
repo saved to /etc/yum.repos.d/example.repo
#### Enabling a Yum Repository {#bh-Managing_Yum_Repositories-Enabling}
To enable a particular repository or repositories, type the following at a shell prompt as `root`:
**yum-config-manager** `--enable` _`repository`_…
…where _`repository`_ is the unique repository ID (use **yum repolist all** to list available repository IDs). Alternatively, you can use a glob expression to enable all matching repositories:
**yum-config-manager** `--enable` _`glob_expression`_…
For example, to disable repositories defined in the `[example]`, `[example-debuginfo]`, and `[example-source]`sections, type:
~]# **yum-config-manager --enable example\***
Loaded plugins: langpacks, presto, refresh-packagekit
============================== repo: example ==============================
[example]
bandwidth = 0
base_persistdir = /var/lib/yum/repos/x86_64/6Server
baseurl = http://www.example.com/repo/6Server/x86_64/
cache = 0
cachedir = /var/cache/yum/x86_64/6Server/example
_[output truncated]_
When successful, the **yum-config-manager --enable** command displays the current repository configuration.
#### Disabling a Yum Repository {#bh-Managing_Yum_Repositories-Disabling}
To disable a Yum repository, run the following command as `root`:
**yum-config-manager** `--disable` _`repository`_…
…where _`repository`_ is the unique repository ID (use **yum repolist all** to list available repository IDs). Similarly to **yum-config-manager --enable**, you can use a glob expression to disable all matching repositories at the same time:
**yum-config-manager** `--disable` _`glob_expression`_…
When successful, the **yum-config-manager --disable** command displays the current configuration.
### 5\.3.6. Creating a Yum Repository {#sec-Creating_a_Yum_Repository}
To set up a Yum repository, follow these steps:
1. Install the createrepo package:
~]# **yum install createrepo**
1. Copy all of the packages into one directory, such as `/mnt/local_repo/`.
1. Run the **createrepo --database** command on that directory:
~]# **createrepo --database /mnt/local_repo**
This creates the necessary metadata for your Yum repository, as well as the sqlite database for speeding up **yum** operations.
## 5\.4. Yum Plug-ins {#sec-Yum_Plugins}
Yum provides plug-ins that extend and enhance its operations. Certain plug-ins are installed by default. Yum always informs you which plug-ins, if any, are loaded and active whenever you call any **yum** command. For example:
~]# **yum info yum**
Loaded plugins: langpacks, presto, refresh-packagekit
_[output truncated]_
Note that the plug-in names which follow **Loaded plugins** are the names you can provide to the ``--disableplugin=_`plugin_name`_`` option.
### 5\.4.1. Enabling, Configuring, and Disabling Yum Plug-ins {#sec-Enabling_Configuring_and_Disabling_Yum_Plugins}
To enable Yum plug-ins, 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 plug-ins by changing this line to **plugins=0**.
### Disabling all plug-ins is not advised {#important-Disabling_all_plugins_is_not_advised-plugins}
Disabling all plug-ins is not advised because certain plug-ins provide important **Yum** services. Disabling plug-ins globally is provided as a convenience option, and is generally only recommended when diagnosing a potential problem with **Yum**.
Every installed plug-in has its own configuration file in the `/etc/yum/pluginconf.d/` directory. You can set plug-in specific options in these files. For example, here is the refresh-packagekit plug-in's `refresh-packagekit.conf` configuration file:
[main]
enabled=1
Plug-in 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 plug-in is enabled when you run **yum** commands.
If you disable all plug-ins by setting **enabled=0** in `/etc/yum.conf`, then all plug-ins are disabled regardless of whether they are enabled in their individual configuration files.
If you merely want to disable all Yum plug-ins for a single **yum** command, use the `--noplugins` option.
If you want to disable one or more Yum plug-ins for a single **yum** command, add the ``--disableplugin=_`plugin_name`_`` option to the command. For example, to disable the presto plug-in while updating a system, type:
~]# **yum update --disableplugin=presto**
The plug-in 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 plug-ins by separating their names with commas. In addition, you can match multiple plug-in names or shorten long ones by using glob expressions:
~]# **yum update --disableplugin=presto,refresh-pack***
### 5\.4.2. Installing Additional Yum Plug-ins {#sec-Installing_More_Yum_Plugins}
Yum plug-ins usually adhere to the ``yum-plugin-_`plugin_name`_`` package-naming convention, but not always: the package which provides the presto plug-in is named `yum-presto`, for example. You can install a Yum plug-in in the same way you install other packages. For instance, to install the security plug-in, type the following at a shell prompt:
~]# **yum install yum-plugin-security**
### 5\.4.3. Plug-in Descriptions {#sec-Plugin_Descriptions}
The following list provides descriptions of a few useful Yum plug-ins:
fs-snapshot (yum-plugin-fs-snapshot)
: The fs-snapshot plug-in extends Yum to create a snapshot of a file system before proceeding with a transaction such as a system update or package removal. When a user decides that the changes made by the transaction are unwanted, this mechanism allows the user to roll back to the changes that are stored in a snapshot.
In order for the plug-in to work, the root file system (that is, `/`) must be on an `LVM` (Logical Volume Manager) or `Btrfs` volume. To use the fs-snapshot plug-in on an LVM volume, take the following steps:
1. Make sure that the volume group with the root file system has enough free extents. The required size is a function of the amount of changes to the original logical volume that is expected during the life of the snapshot. The reasonable default is 50–80 % of the original logical volume size.
To display detailed information about a particular volume group, run the **vgdisplay** command in the following form as `root`:
**vgdisplay** _`volume_group`_
The number of free extents is listed on the `Free PE / Size` line.
1. If the volume group with the root file system does not have enough free extents, add a new physical volume:
1. As `root`, run the **pvcreate** command in the following form to initialize a physical volume for use with the Logical Volume Manager:
**pvcreate** _`device`_
1. Use the **vgextend** command in the following form as `root` to add the physical volume to the volume group:
**vgextend** _`volume_group`_ _`physical_volume`_
1. Edit the configuration file located in `/etc/yum/pluginconf.d/fs-snapshot.conf`, and make the following changes to the `[lvm]` section:
1. Change the value of the `enabled` option to `1`:
enabled = 1
1. Remove the hash sign (that is, `#`) from the beginning of the `lvcreate_size_args` line, and adjust the number of logical extents to be allocated for a snapshot. For example, to allocate 80 % of the size of the original logical volume, use:
lvcreate_size_args = -l 80%ORIGIN
See [Table 5.3, “Supported `fs-snapshot.conf` directives”](#tabl-Yum-Plugin_Descriptions-fs-snapshot "Table 5.3. Supported fs-snapshot.conf directives") for a complete list of available configuration options.
1. Run the desired **yum** command, and make sure fs-snapshot is included in the list of loaded plug-ins (the `Loaded plugins` line) before you confirm the changes and proceed with the transaction. The fs-snapshot plug-in displays a line in the following form for each affected logical volume:
fs-snapshot: snapshotting _`file_system`_ (/dev/_`volume_group`_/_`logical_volume`_): _`logical_volume`__yum__`timestamp`_
1. Verify that the system is working as expected:
* If you decide to keep the changes, remove the snapshot by running the **lvremove** command as `root`:
**lvremove** /dev/_`volume_group`_/_`logical_volume`__yum__`timestamp`_
* If you decide to revert the changes and restore the file system to a state that is saved in a snapshot, take the following steps:
1. As `root`, run the command in the following form to merge a snapshot into its original logical volume:
**lvconvert** `--merge` /dev/_`volume_group`_/_`logical_volume`__yum__`timestamp`_
The **lvconvert** command will inform you that a restart is required in order for the changes to take effect.
1. Restart the system as instructed. You can do so by typing the following at a shell prompt as `root`:
**reboot**
To use the fs-snapshot plug-in on a Btrfs file system, take the following steps:
1. Run the desired **yum** command, and make sure fs-snapshot is included in the list of loaded plug-ins (the `Loaded plugins` line) before you confirm the changes and proceed with the transaction. The fs-snapshot plug-in displays a line in the following form for each affected file system:
fs-snapshot: snapshotting _`file_system`_: _`file_system`_/yum__`timestamp`_
1. Verify that the system is working as expected:
* If you decide to keep the changes, you can optionally remove unwanted snapshots. To remove a Btrfs snapshot, use the command in the following form as `root`:
**btrfs** `subvolume` `delete` _`file_system`_/yum__`timestamp`_
* If you decide to revert the changes and restore a file system to a state that is saved in a snapshot, take the following steps:
1. Determine the identifier of a particular snapshot by using the following command as `root`:
**btrfs** `subvolume` `list` _`file_system`_
1. As `root`, configure the system to mount this snapshot by default:
**btrfs** `subvolume` `set-default` _`id`_ _`file_system`_
1. Restart the system. You can do so by typing the following at a shell prompt as `root`:
**reboot**
For more information on logical volume management, Btrfs, and file system snapshots, see the [_Fedora 20 Storage Administration Guide_](https://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/6/html/Storage_Administration_Guide/). For additional information about the plug-in and its configuration, refer to the **yum-fs-snapshot**(1) and **yum-fs-snapshot.conf**(5) manual pages.
Table 5.3. Supported `fs-snapshot.conf` directives
|Section|Directive|Description|
|-|
|`[main]`|`enabled`=_`value`_|Allows you to enable or disable the plug-in. The _`value`_ must be either `1` (enabled), or `0` (disabled). When installed, the plug-in is enabled by default.|
|`exclude`=_`list`_|Allows you to exclude certain file systems. The value must be a space-separated _`list`_ of mount points you do _not_ want to snapshot (for example, `/srv /mnt/backup`). This option is not included in the configuration file by default.|
|`[lvm]`|`enabled`=_`value`_|Allows you to enable or disable the use of the plug-in on LVM volumes. The _`value`_ must be either `1` (enabled), or `0` (disabled). This option is disabled by default.|
|`lvcreate_size_args`=_`value`_|Allows you to specify the size of a logical volume snapshot. The _`value`_ must be the `-l` or `-L` command line option for the lvcreate utility followed by a valid argument (for example, `-l 80%ORIGIN`).|
presto (yum-presto)
: The presto plug-in 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 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 to apply the difference to the currently-installed package and thus create the full, updated package. This process takes CPU time on the installing machine. 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 plug-in 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, that is, by disabling presto.
refresh-packagekit (PackageKit-yum-plugin)
: The refresh-packagekit plug-in updates metadata for PackageKit whenever **yum** is run. The refresh-packagekit plug-in is installed by default.
rhnplugin (yum-rhn-plugin)
: The rhnplugin provides support for connecting to `RHN Classic`. This allows systems registered with `RHN Classic` to update and install packages from this system.
See the **rhnplugin**(8) manual page for more information about the plug-in.
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 plug-in, which extends **yum** with a set of highly-useful security-related commands, subcommands and options.
You can check for security-related updates as follows:
~]# **yum check-update --security**
Loaded plugins: langpacks, presto, refresh-packagekit, security
Limiting package lists to security relevant ones
updates-testing/updateinfo | 329 kB 00:00
9 package(s) needed for security, out of 270 available
ConsoleKit.x86_64 0.4.5-1.fc15 updates
ConsoleKit-libs.x86_64 0.4.5-1.fc15 updates
ConsoleKit-x11.x86_64 0.4.5-1.fc15 updates
NetworkManager.x86_64 1:0.8.999-2.git20110509.fc15 updates
NetworkManager-glib.x86_64 1:0.8.999-2.git20110509.fc15 updates
_[output truncated]_
You can then use either **yum update --security** or **yum update-minimal --security** to update those packages which are affected by security advisories. Both of these commands update all packages on the system for which a security advisory has been issued. **yum update-minimal --security** updates them to the latest packages which were released as part of a security advisory, while **yum update --security** will update all packages affected by a security advisory _to the latest version of that package available_.
In other words, if:
* the kernel-2.6.38.4-20 package is installed on your system;
* the kernel-2.6.38.6-22 package was released as a security update;
* then kernel-2.6.38.6-26 was released as a bug fix update,
...then **yum update-minimal --security** will update you to kernel-2.6.38.6-22, and **yum update --security** will update you to kernel-2.6.38.6-26. Conservative system administrators may want to use **update-minimal** to reduce the risk incurred by updating packages as much as possible.
See the **yum-security**(8) manual page for usage details and further explanation of the enhancements the security plug-in adds to **yum**.
## 5\.5. Additional Resources {#sec-Additional_Resources}
: The `Yum Guides` section of the Yum wiki contains more documentation.
# Part III. Infrastructure Services {#part-Infrastructure_Services}
This part provides information on how to configure services and daemons, configure authentication, and enable remote logins.
## Chapter 6. Services and Daemons {#ch-Services_and_Daemons}
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.
This chapter covers the configuration of the services to be run when a system is started, and provides information on how to start, stop, and restart the services on the command line using the systemctl utility.
### Keep the system secure
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. For more information, refer to the Fedora 20 _Security Guide_.
## 6\.1. Configuring Services {#s1-services-configuring}
To allow you to configure which services are started at boot time, Fedora is shipped with the systemctl command line tool.
### Do not use the ntsysv and chkconfig utilities
Although it is still possible to use the ntsysv and chkconfig utilities to manage services that have init scripts installed in the `/etc/rc.d/init.d/` directory, it is advised that you use the systemctl utility.
### Enabling the irqbalance service
To ensure optimal performance on POWER architecture, it is recommended that the `irqbalance` service is enabled. In most cases, this service is installed and configured to run during the Fedora 20 installation. To verify that `irqbalance` is running, type the following at a shell prompt:
**systemctl status irqbalance.service**
### 6\.1.1. Enabling the Service {#s3-services-configuration-enabling}
To configure a service to be automatically started at boot time, use the **systemctl** command in the following form:
**systemctl** `enable` ``_`service_name`_.service``
The service will be started the next time you boot the system. For information on how to start the service immediately, refer to [Section 6.2.2, “Running the Service”](#s3-services-running-running "6.2.2. Running the Service").
Example 6.1. Enabling the httpd service
Imagine you want to run the Apache HTTP Server on your system. Provided that you have the httpd package installed, you can enable the `httpd` service by typing the following at a shell prompt as `root`:
~]# **systemctl enable httpd.service**
### 6\.1.2. Disabling the Service {#s3-services-configuration-disabling}
To disable starting a service at boot time, use the **systemctl** command in the following form:
**systemctl** `disable` ``_`service_name`_.service``
The next time you boot the system, the service will _not_ be started. For information on how to stop the service immediately, refer to [Section 6.2.3, “Stopping the Service”](#s3-services-running-stopping "6.2.3. Stopping the Service").
Example 6.2. Disabling the telnet service
In order to secure the system, users are advised to disable insecure connection protocols such as Telnet. You can make sure that the `telnet` service is disabled by running the following command as `root`:
~]# **systemctl disable telnet.service**
## 6\.2. Running Services {#s1-services-running}
The systemctl utility also allows you to determine the status of a particular service, as well as to start, stop, or restart a service.
### Do not use the service utility
Although it is still possible to use the service utility to manage services that have init scripts installed in the `/etc/rc.d/init.d/` directory, it is advised that you use the systemctl utility.
### 6\.2.1. Checking the Service Status {#s3-services-running-checking}
To determine the status of a particular service, use the **systemctl** command in the following form:
**systemctl** `status` ``_`service_name`_.service``
This command provides detailed information on the service's status. However, if you merely need to verify that a service is running, you can use the **systemctl** command in the following form instead:
**systemctl** `is-active` ``_`service_name`_.service``
Example 6.3. Checking the status of the httpd service
[Example 6.1, “Enabling the httpd service”](#exam-services-configuration-enabling "Example 6.1. Enabling the httpd service") illustrated how to enable starting the `httpd` service at boot time. Imagine that the system has been restarted and you need to verify that the service is really running. You can do so by typing the following at a shell prompt:
~]$ **systemctl is-active httpd.service**
active
You can also display detailed information about the service by running the following command:
~]$ **systemctl status httpd.service**
httpd.service - LSB: start and stop Apache HTTP Server
Loaded: loaded (/etc/rc.d/init.d/httpd)
Active: active (running) since Mon, 23 May 2011 21:38:57 +0200; 27s ago
Process: 2997 ExecStart=/etc/rc.d/init.d/httpd start (code=exited, status=0/SUCCESS)
Main PID: 3002 (httpd)
CGroup: name=systemd:/system/httpd.service
├ 3002 /usr/sbin/httpd
├ 3004 /usr/sbin/httpd
├ 3005 /usr/sbin/httpd
├ 3006 /usr/sbin/httpd
├ 3007 /usr/sbin/httpd
├ 3008 /usr/sbin/httpd
├ 3009 /usr/sbin/httpd
├ 3010 /usr/sbin/httpd
└ 3011 /usr/sbin/httpd
To display a list of all active system services, use the following command:
**systemctl list-units --type=service**
This command provides a tabular output with each line consisting of the following columns:
* `UNIT` — A `systemd` unit name. In this case, a service name.
* `LOAD` — Information whether the `systemd` unit was properly loaded.
* `ACTIVE` — A high-level unit activation state.
* `SUB` — A low-level unit activation state.
* `JOB` — A pending job for the unit.
* `DESCRIPTION` — A brief description of the unit.
Example 6.4. Listing all active services
You can list all active services by using the following command:
~]$ **systemctl list-units --type=service**
UNIT LOAD ACTIVE SUB JOB DESCRIPTION
abrt-ccpp.service loaded active exited LSB: Installs coredump handler which saves segfault data
abrt-oops.service loaded active running LSB: Watches system log for oops messages, creates ABRT dump directories for each oops
abrtd.service loaded active running ABRT Automated Bug Reporting Tool
accounts-daemon.service loaded active running Accounts Service
atd.service loaded active running Job spooling tools
_[output truncated]_
In the example above, the `abrtd` service is loaded, active, and running, and it does not have any pending jobs.
### 6\.2.2. Running the Service {#s3-services-running-running}
To run a service, use the **systemctl** command in the following form:
**systemctl** `start` ``_`service_name`_.service``
This will start the service in the current session. To configure the service to be started at boot time, refer to [Section 6.1.1, “Enabling the Service”](#s3-services-configuration-enabling "6.1.1. Enabling the Service").
Example 6.5. Running the httpd service
[Example 6.1, “Enabling the httpd service”](#exam-services-configuration-enabling "Example 6.1. Enabling the httpd service") illustrated how to run the `httpd` service at boot time. You can start the service immediately by typing the following at a shell prompt as `root`:
~]# **systemctl start httpd.service**
### 6\.2.3. Stopping the Service {#s3-services-running-stopping}
To stop a service, use the **systemctl** command in the following form:
**systemctl** `stop` ``_`service_name`_.service``
This will stop the service in the current session. To disable starting the service at boot time, refer to [Section 6.1.1, “Enabling the Service”](#s3-services-configuration-enabling "6.1.1. Enabling the Service").
Example 6.6. Stopping the telnet service
[Example 6.2, “Disabling the telnet service”](#exam-services-configuration-disabling "Example 6.2. Disabling the telnet service") illustrated how to disable starting the `telnet` service at boot time. You can stop the service immediately by running the following command as `root`:
~]# **systemctl stop telnet.service**
### 6\.2.4. Restarting the Service {#s3-services-running-restarting}
To restart a service, use the **systemctl** command in the following form:
**systemctl** `restart` ``_`service_name`_.service``
Example 6.7. Restarting the sshd service
For any changes in the `/etc/ssh/sshd_config` configuration file to take effect, it is required that you restart the `sshd` service. You can do so by typing the following at a shell prompt as `root`:
~]# **systemctl restart sshd.service**
## 6\.3. Additional Resources {#s1-services-additional-resources}
### 6\.3.1. Installed Documentation {#s2-services-additional-resources-installed}
* `systemctl`(1) — The manual page for the systemctl utility.
### 6\.3.2. Related Books {#s2-services-additional-resources-books}
_Fedora 20 Security Guide_
: A guide to securing Fedora. It contains valuable information on how to set up the firewall, as well as the configuration of SELinux.
## Chapter 7. Configuring Authentication {#ch-Configuring_Authentication}
_Authentication_ is the way that a user is identified and verified to a system. The authentication process requires presenting some sort of identity and credentials, like a username and password. The credentials are then compared to information stored in some data store on the system. In Fedora, the Authentication Configuration Tool helps configure what kind of data store to use for user credentials, such as LDAP.
For convenience and potentially part of single sign-on, Fedora can use a central daemon to store user credentials for a number of different data stores. The System Security Services Daemon (SSSD) can interact with LDAP, Kerberos, and external applications to verify user credentials. The Authentication Configuration Tool can configure SSSD along with NIS, Winbind, and LDAP, so that authentication processing and caching can be combined.
## 7\.1. Configuring System Authentication {#sect-The_Authentication_Configuration_Tool}
When a user logs into a Fedora system, that user presents some sort of _credential_ to establish the user identity. The system then checks those credentials against the configured authentication service. If the credentials match and the user account is active, then the user is _authenticated_. (Once a user is authenticated, then the information is passed to the access control service to determine what the user is permitted to do. Those are the resources the user is _authorized_ to access.)
The information to verify the user can be located on the local system or the local system can reference a user database on a remote system, such as LDAP or Kerberos.
The system must have a configured list of valid account databases for it to check for user authentication. On Fedora, the Authentication Configuration Tool has both GUI and command-line options to configure any user data stores.
A local system can use a variety of different data stores for user information, including Lightweight Directory Access Protocol (LDAP), Network Information Service (NIS), and Winbind. Additionally, both LDAP and NIS data stores can use Kerberos to authenticate users.
### Important
If a medium or high security level is set during installation or with the Security Level Configuration Tool, then the firewall prevents NIS authentication. For more information about firewalls, see the "Firewalls" section of the _Security Guide_.
### 7\.1.1. Launching the Authentication Configuration Tool UI {#launching-authconfig}
1. Log into the system as root.
1. Open the System.
1. Select the Administration menu.
1. Select the Authentication item.
![][31]
Alternatively, run the **system-config-authentication** command.
### Important
Any changes take effect immediately when the Authentication Configuration Tool UI is closed.
There are two configuration tabs in the Authentication dialog box:
* Identity & Authentication, which configures the resource used as the identity store (the data repository where the user IDs and corresponding credentials are stored).
* Advanced Options, which allows authentication methods other than passwords or certificates, like smart cards and fingerprint.
### 7\.1.2. Selecting the Identity Store for Authentication {#Setting-Auth-Stores}
The Identity & Authentication tab sets how users should be authenticated. The default is to use local system authentication, meaning the users and their passwords are checked against local system accounts. A Fedora machine can also use external resources which contain the users and credentials, including LDAP, NIS, and Winbind.
Figure 7.1. Local Authentication
![Local Authentication][32]
#### 7\.1.2.1. Configuring LDAP Authentication {#configuring-ldap-auth}
Either the `openldap-clients` package or the `sssd` package is used to configure an LDAP server for the user database. Both packages are installed by default.
1. Open the Authentication Configuration Tool, as in [Section 7.1.1, “Launching the Authentication Configuration Tool UI”](#launching-authconfig "7.1.1. Launching the Authentication Configuration Tool UI").
1. Select LDAP in the User Account Database drop-down menu.
![][33]
1. Set the information that is required to connect to the LDAP server.
* LDAP Search Base DN gives the root suffix or _distinguished name_ (DN) for the user directory. All of the user entries used for identity/authentication will exist below this parent entry. For example, _ou=people,dc=example,dc=com_.
This field is optional. If it is not specified, then SSSD attempts to detect the search base using the _`namingContexts`_ and _`defaultNamingContext`_ attributes in the LDAP server's configuration entry.
* LDAP Server gives the URL of the LDAP server. This usually requires both the hostname and port number of the LDAP server, such as _ldap://ldap.example.com:389_.
Entering the secure protocol in the URL, **ldaps://**, enables the Download CA Certificate button.
* Use TLS to encrypt connections sets whether to use Start TLS to encrypt the connections to the LDAP server. This enables a secure connection over a standard port.
Selecting TLS enables the Download CA Certificate button, which retrieves the issuing CA certificate for the LDAP server from whatever certificate authority issued it. The CA certificate must be in the privacy enhanced mail (PEM) format.
### Important
_Do not_ select Use TLS to encrypt connections if the server URL uses a secure protocol (**ldaps**). This option uses Start TLS, which initiates a secure connection over a standard port; if a secure port is specified, then a protocol like SSL must be used instead of Start TLS.
1. Select the authentication method. LDAP allows simple password authentication or Kerberos authentication.
Using Kerberos is described in [Section 7.1.2.4, “Using Kerberos with LDAP or NIS Authentication”](#using-kerb-ldap-nis "7.1.2.4. Using Kerberos with LDAP or NIS Authentication").
The LDAP password option uses PAM applications to use LDAP authentication. This option requires either a secure (**ldaps://**) URL or the TLS option to connect to the LDAP server.
#### 7\.1.2.2. Configuring NIS Authentication {#configuring-nis-auth}
1. Install the `ypbind` package. This is required for NIS services, but is not installed by default.
[root@server ~]# yum install ypbind
When the `ypbind` service is installed, the `portmap` and `ypbind` services are started and enabled to start at boot time.
1. Open the Authentication Configuration Tool, as in [Section 7.1.1, “Launching the Authentication Configuration Tool UI”](#launching-authconfig "7.1.1. Launching the Authentication Configuration Tool UI").
1. Select NIS in the User Account Database drop-down menu.
![][34]
1. Set the information to connect to the NIS server, meaning the NIS domain name and the server hostname. If the NIS server is not specified, the **authconfig** daemon scans for the NIS server.
1. Select the authentication method. NIS allows simple password authentication or Kerberos authentication.
Using Kerberos is described in [Section 7.1.2.4, “Using Kerberos with LDAP or NIS Authentication”](#using-kerb-ldap-nis "7.1.2.4. Using Kerberos with LDAP or NIS Authentication").
For more information about NIS, see the "Securing NIS" section of the _Security Guide_.
#### 7\.1.2.3. Configuring Winbind Authentication {#winbind-auth}
Using Winbind as an authentication provider requires the `samba-winbind` package, which is installed by default.
1. Open the Authentication Configuration Tool, as in [Section 7.1.1, “Launching the Authentication Configuration Tool UI”](#launching-authconfig "7.1.1. Launching the Authentication Configuration Tool UI").
1. Select Winbind in the User Account Database drop-down menu.
![][35]
1. Set the information that is required to connect to the Microsoft Active Directory domain controller.
* Winbind Domain gives the Windows domain to connect to.
This should be in the Windows 2000 format, such as **DOMAIN**.
* Security Model sets the security model to use for Samba clients. **authconfig** supports four types of security models:
* ads configures Samba to act as a domain member in an Active Directory Server realm. To operate in this mode, the `krb5-server` package must be installed and Kerberos must be configured properly.
* domain has Samba validate the username/password by authenticating it through a Windows primary or backup domain controller, much like a Windows server.
* server has a local Samba server validate the username/password by authenticating it through another server, such as a Windows server. If the server authentication attempt fails, the system then attempts to authentication using **user** mode.
* user requires a client to log in with a valid username and password. This mode does support encrypted passwords.
The username format must be _domain\\user_, such as **EXAMPLE\\jsmith**.
### Note
When verifying that a given user exists in the Windows domain, always use Windows 2000-style formats and escape the backslash (\\) character. For example:
[root@server ~]# getent passwd domain\\user DOMAIN\user:*:16777216:16777216:Name Surname:/home/DOMAIN/user:/bin/bash
This is the default option.
* Winbind ADS Realm gives the Active Directory realm that the Samba server will join. This is only used with the ads security model.
* Winbind Domain Controllers gives the domain controller to use. For more information about domain controllers, refer to [Section 12.1.6.3, “Domain Controller”](#s3-samba-domain-controller "12.1.6.3. Domain Controller").
* Template Shell sets which login shell to use for Windows user account settings.
* Allow offline login allows authentication information to be stored in a local cache. The cache is referenced when a user attempts to authenticate to system resources while the system is offline.
For more information about the **winbindd** service, refer to [Section 12.1.2, “Samba Daemons and Related Services”](#s2-samba-daemons "12.1.2. Samba Daemons and Related Services").
#### 7\.1.2.4. Using Kerberos with LDAP or NIS Authentication {#using-kerb-ldap-nis}
Both LDAP and NIS authentication stores support Kerberos authentication methods. Using Kerberos has a couple of benefits:
* It uses a security layer for communication while still allowing connections over standard ports.
* It automatically uses credentials caching with SSSD, which allows offline logins.
Using Kerberos authentication requires the `krb5-libs` and `krb5-workstation` packages.
The Kerberos password option from the Authentication Method drop-down menu automatically opens the fields required to connect to the Kerberos realm.
Figure 7.2. Kerberos Fields
![Kerberos Fields][36]
* Realm gives the name for the realm for the Kerberos server. The realm is the network that uses Kerberos, composed of one or more _key distribution centers_ (KDC) and a potentially large number of clients.
* KDCs gives a comma-separated list of servers that issue Kerberos tickets.
* Admin Servers gives a list of administration servers running the **kadmind** process in the realm.
* Optionally, use DNS to resolve server hostname and to find additional KDCs within the realm.
For more information about Kerberos, refer to section "Using Kerberos" of the Fedora 20 _Managing Single Sign-On and Smart Cards_ guide.
### 7\.1.3. Configuring Alternative Authentication Features {#sect-The_Authentication_Configuration_Tool-Advanced_Options}
The Authentication Configuration Tool also configures settings related to authentication behavior, apart from the identity store. This includes entirely different authentication methods (fingerprint scans and smart cards) or local authentication rules. These alternative authentication options are configured in the Advanced Options tab.
Figure 7.3. Advanced Options
![Advanced Options][37]
#### 7\.1.3.1. Using Fingerprint Authentication {#authconfig-fingerprint}
When there is appropriate hardware available, the Enable fingerprint reader support option allows fingerprint scans to be used to authenticate local users in addition to other credentials.
#### 7\.1.3.2. Setting Local Authentication Parameters {#authconfig-local-auth}
There are two options in the Local Authentication Options area which define authentication behavior on the local system:
* Enable local access control instructs the `/etc/security/access.conf` file to check for local user authorization rules.
* Password Hashing Algorithm sets the hashing algorithm to use to encrypt locally-stored passwords.
#### 7\.1.3.3. Enabling Smart Card Authentication {#authconfig-smartcard}
When there are appropriate smart card readers available, a system can accept smart cards (or _tokens_) instead of other user credentials to authenticate.
Once the Enable smart card support option is selected, then the behaviors of smart card authentication can be defined:
* Card Removal Action tells the system how to respond when the card is removed from the card reader during an active session. A system can either ignore the removal and allow the user to access resources as normal, or a system can immediately lock until the smart card is supplied.
* Require smart card login sets whether a smart card is required for logins or simply allowed for logins. When this option is selected, all other methods of authentication are immediately blocked.
### Warning
Do not select this option until you have successfully authenticated to the system using a smart card.
Using smart cards requires the `pam_pkcs11` package.
#### 7\.1.3.4. Creating User Home Directories {#authconfig-homedirs}
There is an option (Create home directories on the first login) to create a home directory automatically the first time that a user logs in.
This option is beneficial with accounts that are managed centrally, such as with LDAP. However, this option should not be selected if a system like automount is used to manage user home directories.
### 7\.1.4. Setting Password Options {#authconfig-passwordoptions}
Through the Authentication Configuration Tool, it is possible to set requirements of passwords and the classes of characters it will contain. Also, it can determine how consecutive characteres will be repeated within a password. This options are configured in the Password Options tab.
Figure 7.4. Password Options
![Password Options][38]
The Lenght option allows a maximun of 30 characters and the Character Classes option allows to choose from one to four according the classes: Lowercase, Uppercase, Digits and Other characters which are going to be required to create a password if they are enabled.
### Important
An adecuated election to the lenght of password must be done correspondinly to the classes chossen. For example, the password _FeDOrAwOrld_ which has two character classes contains eleven characters and The password _FeD2rA1_ contains seven characteres but has three character classes.
The maximun amount of consecutive character repetition is set to characters and classes. Both, the Same Character option and the Same Class option have the lenght of 30 as character repetition allowed.
### 7\.1.5. Configuring Authentication from the Command Line {#sect-The_Authentication_Configuration_Tool-Command_Line_Version}
The **authconfig** command-line tool updates all of the configuration files and services required for system authentication, according to the settings passed to the script. Along with allowing all of the identity and authentication configuration options that can be set through the UI, the **authconfig** tool can also be used to create backup and kickstart files.
For a complete list of **authconfig** options, check the help output and the man page.
#### 7\.1.5.1. Tips for Using authconfig {#tips-for-authconfig}
There are some things to remember when running **authconfig**:
* With every command, use either the `--update` or `--test` option. One of those options is required for the command to run successfully. Using `--update` writes the configuration changes. `--test` prints the changes to stdout but does not apply the changes to the configuration.
* Each enable option has a corresponding disable option.
#### 7\.1.5.2. Configuring LDAP User Stores {#authconfig-ldap-cmd}
To use an LDAP identity store, use the `--enableldap`. To use LDAP as the authentication source, use `--enableldapauth` and then the requisite connection information, like the LDAP server name, base DN for the user suffix, and (optionally) whether to use TLS. The **authconfig** command also has options to enable or disable RFC 2307bis schema for user entries, which is not possible through the Authentication Configuration UI.
Be sure to use the full LDAP URL, including the protocol (**ldap** or **ldaps**) and the port number. Do _not_ use a secure LDAP URL (**ldaps**) with the `--enableldaptls` option.
authconfig --enableldap --enableldapauth --ldapserver=ldap://ldap.example.com:389,ldap://ldap2.example.com:389 --ldapbasedn="ou=people,dc=example,dc=com" --enableldaptls --ldaploadcacert=https://ca.server.example.com/caCert.crt --update
Instead of using `--ldapauth` for LDAP password authentication, it is possible to use Kerberos with the LDAP user store. These options are described in [Section 7.1.5.5, “Configuring Kerberos Authentication”](#authconfig-kerberos-cmd "7.1.5.5. Configuring Kerberos Authentication").
#### 7\.1.5.3. Configuring NIS User Stores {#authconfig-nis-cmd}
To use a NIS identity store, use the `--enablenis`. This automatically uses NIS authentication, unless the Kerberos parameters are explicitly set, so it uses Kerberos authentication ([Section 7.1.5.5, “Configuring Kerberos Authentication”](#authconfig-kerberos-cmd "7.1.5.5. Configuring Kerberos Authentication")). The only parameters are to identify the NIS server and NIS domain; if these are not used, then the `authconfig` service scans the network for NIS servers.
authconfig --enablenis --nisdomain=EXAMPLE --nisserver=nis.example.com --update
#### 7\.1.5.4. Configuring Winbind User Stores {#authconfig-winbind-cmd}
Windows domains have several different security models, and the security model used in the domain determines the authentication configuration for the local system.
For user and server security models, the Winbind configuration requires only the domain (or workgroup) name and the domain controller hostnames.
authconfig --enablewinbind --enablewinbindauth --smbsecurity=user|server --enablewinbindoffline --smbservers=ad.example.com --smbworkgroup=EXAMPLE --update
### Note
The username format must be _domain\\user_, such as **EXAMPLE\\jsmith**.
When verifying that a given user exists in the Windows domain, always use Windows 2000-style formats and escape the backslash (\\) character. For example:
[root@server ~]# getent passwd domain\\user DOMAIN\user:*:16777216:16777216:Name Surname:/home/DOMAIN/user:/bin/bash
For ads and domain security models, the Winbind configuration allows additional configuration for the template shell and realm (ads only). For example:
authconfig --enablewinbind --enablewinbindauth --smbsecurity ads --enablewinbindoffline --smbservers=ad.example.com --smbworkgroup=EXAMPLE --smbrealm EXAMPLE.COM --winbindtemplateshell=/bin/sh --update
There are a lot of other options for configuring Windows-based authentication and the information for Windows user accounts, such as name formats, whether to require the domain name with the username, and UID ranges. These options are listed in the **authconfig** help.
#### 7\.1.5.5. Configuring Kerberos Authentication {#authconfig-kerberos-cmd}
Both LDAP and NIS allow Kerberos authentication to be used in place of their native authentication mechanisms. At a minimum, using Kerberos authentication requires specifying the realm, the KDC, and the administrative server. There are also options to use DNS to resolve client names and to find additional admin servers.
authconfig _`NIS or LDAP options`_ --enablekrb5 --krb5realm EXAMPLE --krb5kdc kdc.example.com:88,server.example.com:88 --krb5adminserver server.example.com:749 --enablekrb5kdcdns --enablekrb5realmdns --update
#### 7\.1.5.6. Configuring Local Authentication Settings {#authconfig-local-cmd}
The Authentication Configuration Tool can also control some user settings that relate to security, such as creating home directories, setting password hash algorithms, and authorization. These settings are done independently of identity/user store settings.
For example, to create user home directories:
authconfig --enablemkhomedir --update
To set or change the hash algorithm used to encrypt user passwords:
authconfig --passalgo=sha512 --update
#### 7\.1.5.7. Configuring Fingerprint Authentication {#authconfig-fingerprint-cmd}
There is one option to enable support for fingerprint readers. This option can be used alone or in conjunction with other `authconfig` settings, like LDAP user stores.
authconfig --enablefingerprint --update
#### 7\.1.5.8. Configuring Smart Card Authentication {#authconfig-smartcards-cmd}
All that is required to use smart cards with a system is to set the `--enablesmartcard` option:
authconfig --enablesmartcard --update
There are other configuration options for smart cards, such as changing the default smart card module, setting the behavior of the system when the smart card is removed, and requiring smart cards for login.
For example, this command instructs the system to lock out a user immediately if the smart card is removed (a setting of 1 ignores it if the smart card is removed):
authconfig --enablesmartcard --smartcardaction=0 --update
Once smart card authentication has been successfully configured and tested, then the system can be configured to require smart card authentication for users rather than simple password-based authentication.
authconfig --enablerequiresmartcard --update
### Warning
Do not use the `--enablerequiresmartcard` option until you have successfully authenticated to the system using a smart card. Otherwise, users may be unable to log into the system.
#### 7\.1.5.9. Managing Kickstart and Configuration Files {#authconfig-kickstart-cmd}
The `--update` option updates all of the configuration files with the configuration changes. There are a couple of alternative options with slightly different behavior:
* `--kickstart` writes the updated configuration to a kickstart file.
* `--test` prints the full configuration, with changes, to stdout but does not edit any configuration files.
Additionally, `authconfig` can be used to back up and restore previous configurations. All archives are saved to a unique subdirectory in the `/var/lib/authconfig/` directory. For example, the `--savebackup` option gives the backup directory as **2011-07-01**:
authconfig --savebackup=2011-07-01
This backs up all of the authentication configuration files beneath the `/var/lib/authconfig/backup-2011-07-01` directory.
Any of the saved backups can be used to restore the configuration using the `--restorebackup` option, giving the name of the manually-saved configuration:
authconfig --restorebackup=2011-07-01
Additionally, **authconfig** automatically makes a backup of the configuration before it applies any changes (with the `--update` option). The configuration can be restored from the most recent automatic backup, without having to specify the exact backup, using the `--restorelastbackup` option.
### 7\.1.6. Using Custom Home Directories {#idm80228272}
If LDAP users have home directories that are not in `/home` and the system is configured to create home directories the first time users log in, then these directories are created with the wrong permissions.
1. Apply the correct SELinux context and permissions from the `/home` directory to the home directory that is created on the local system. For example:
# semanage fcontext -a -e /home /home/locale
1. Install the `oddjob-mkhomedir` package on the system.
This package provides the `pam_oddjob_mkhomedir.so` library, which the Authentication Configuration Tool uses to create home directories. The `pam_oddjob_mkhomedir.so` library, unlike the default `pam_mkhomedir.so` library, can create SELinux labels.
The Authentication Configuration Tool automatically uses the `pam_oddjob_mkhomedir.so` library if it is available. Otherwise, it will default to using `pam_mkhomedir.so`.
1. Make sure the `oddjobd` service is running.
1. Re-run the Authentication Configuration Tool and enable home directories, as in [Section 7.1.3, “Configuring Alternative Authentication Features”](#sect-The_Authentication_Configuration_Tool-Advanced_Options "7.1.3. Configuring Alternative Authentication Features").
If home directories were created before the home directory configuration was changed, then correct the permissions and SELinux contexts. For example:
# semanage fcontext -a -e /home /home/locale
# restorecon -R -v /home/locale
## 7\.2. Using and Caching Credentials with SSSD {#SSSD-Introduction}
The System Security Services Daemon (SSSD) provides access to different identity and authentication providers. SSSD is an intermediary between local clients and any configured data store. The local clients connect to SSSD and then SSSD contacts the external providers. This brings a number of benefits for administrators:
* _Reducing the load on identification/authentication servers._ Rather than having every client service attempt to contact the identification server directly, all of the local clients can contact SSSD which can connect to the identification server or check its cache.
* _Permitting offline authentication._ SSSD can optionally keep a cache of user identities and credentials that it retrieves from remote services. This allows users to authenticate to resources successfully, even if the remote identification server is offline or the local machine is offline.
* _Using a single user account._ Remote users frequently have two (or even more) user accounts, such as one for their local system and one for the organizational system. This is necessary to connect to a virtual private network (VPN). Because SSSD supports caching and offline authentication, remote users can connect to network resources simply by authenticating to their local machine and then SSSD maintains their network credentials.
The System Security Services Daemon does not require any additional configuration or tuning to work with the Authentication Configuration Tool. However, SSSD can work with other applications, and the daemon may require configuration changes to improve the performance of those applications.
### 7\.2.1. About the sssd.conf File {#about-sssd}
SSSD services and domains are configured in a `.conf` file. The default file is `/etc/sssd/sssd.conf`, although alternative files can be passed to SSSD by using the `-c` option with the **sssd** command:
# sssd -c /etc/sssd/customfile.conf
Both services and domains are configured individually, in separate sections on the configuration identified by _[type/name]_ divisions, such as **[domain/LDAP]**. The configuration file uses simple _key = value_ lines to set the configuration. Comment lines are set by either a hash sign (#) or a semicolon (;)
For example:
[section]
# Comment line
key1 = val1
key10 = val1,val2
### 7\.2.2. Starting and Stopping SSSD {#Installing_SSSD-Starting_and_Stopping_SSSD}
### Note
Configure at least one domain before starting SSSD for the first time. See [Section 7.2.4, “Creating Domains”](#Configuring_Domains "7.2.4. Creating Domains").
Either the **service** command or the `/etc/init.d/sssd` script can start SSSD. For example:
# service sssd start
By default, SSSD is configured not to start automatically. There are two ways to change this behavior:
* Using the **authconfig** command:
[root@server ~]# authconfig --enablesssd --enablesssdauth --update
* Using the **chkconfig** command:
[root@server ~]# chkconfig sssd on
### 7\.2.3. Configuring SSSD to Work with System Services {#Configuring_Services}
SSSD worked with specialized services that run in tandem with the SSSD process itself. SSSD and its associated services are configured in the `sssd.conf` file. The `[sssd]` section also lists the services that are active and should be started when `sssd` starts within the **services** directive.
SSSD currently provides several services:
* A Name Service Switch (NSS) provider service that answers name service requests from the `sssd_nss` module. This is configured in the **[nss]** section of the SSSD configuration.
* A PAM provider service that manages a PAM conversation through the `sssd_pam` module. This is configured in the **[pam]** section of the configuration.
* `monitor`, a special service that monitors and starts or restarts all other SSSD services. Its options are specified in the `[sssd]` section of the `/etc/sssd/sssd.conf` configuration file.
### Note
If a DNS lookup fails to return an IPv4 address for a hostname, SSSD attempts to look up an IPv6 address before returning a failure. This only ensures that the asynchronous resolver identifies the correct address.
The hostname resolution behavior is configured in the _`lookup family order`_ option in the `sssd.conf` configuration file.
#### 7\.2.3.1. Configuring NSS Services {#Configuration_Options-NSS_Configuration_Options}
SSSD provides an NSS module, `sssd_nss`, which instructs the system to use SSSD to retrieve user information. The NSS configuration must include a reference to the SSSD module, and then the SSSD configuration sets how SSSD interacts with NSS.
##### 7\.2.3.1.1. About NSS Service Maps and SSSD {#nss-maps}
The Name Service Switch (NSS) provides a central configuration for services to look up a number of configuration and name resolution services. NSS provides one method of mapping system identities and services with configuration sources.
SSSD works with NSS as a provider services for several types of NSS maps:
* Passwords (**passwd**)
* User groups (**shadow**)
* Groups (**groups**)
* Netgroups (**netgroups**)
* Services (**services**)
##### 7\.2.3.1.2. Configuring NSS Services to Use SSSD {#nss-sssd}
NSS can use multiple identity and configuration providers for any and all of its service maps. The default is to use system files for services; for SSSD to be included, the **nss\_sss** module has to be included for the desired service type.
1. Use the Authentication Configuration tool to enable SSSD. This automatically configured the `nsswitch.conf` file to use SSSD as a provider.
[root@server ~]# authconfig --enablesssd --update
This automatically configures the password, shadow, group, and netgroups services maps to use the SSSD module:
passwd: files sss
shadow: files sss
group: files sss
netgroup: files sss
1. The services map is not enabled by default when SSSD is enabled with **authconfig**. To include that map, open the `nsswitch.conf` file and add the **sss** module to the **services** map:
[root@server ~]# vim /etc/nsswitch.conf
...
services: file **`sss`**
...
##### 7\.2.3.1.3. Configuring SSSD to Work with NSS {#nss-sssd-config}
The options and configuration that SSSD uses to service NSS requests are configured in the SSSD configuration file, in the **[nss]** services section.
1. Open the `sssd.conf` file.
[root@server ~]# vim /etc/sssd/sssd.conf
1. Make sure that NSS is listed as one of the services that works with SSSD.
[sssd]
config_file_version = 2
reconnection_retries = 3
sbus_timeout = 30
services = **`nss`**, pam
1. In the **[nss]** section, change any of the NSS parameters. These are listed in [Table 7.1, “SSSD [nss] Configuration Parameters”](#tab.nss-sssd "Table 7.1. SSSD [nss] Configuration Parameters").
[nss]
filter_groups = root
filter_users = root
reconnection_retries = 3
entry_cache_timeout = 300
entry_cache_nowait_percentage = 75
1. Restart SSSD.
[root@server ~]# service sssd restart
Table 7.1. SSSD [nss] Configuration Parameters
|Parameter|Value Format|Description|
|-|
|enum\_cache\_timeout|integer|Specifies how long, in seconds, `sssd_nss` should cache requests for information about all users (enumerations).|
|entry\_cache\_nowait\_percentage|integer|Specifies how long `sssd_nss` should return cached entries before refreshing the cache. Setting this to zero (`0`) disables the entry cache refresh.
This configures the entry cache to update entries in the background automatically if they are requested if the time before the next update is a certain percentage of the next interval. For example, if the interval is 300 seconds and the cache percentage is 75, then the entry cache will begin refreshing when a request comes in at 225 seconds — 75% of the interval.
The allowed values for this option are 0 to 99, which sets the percentage based on the `entry_cache_timeout` value. The default value is 50%.|
|entry\_negative\_timeout|integer|Specifies how long, in seconds, `sssd_nss` should cache _negative_ cache hits. A negative cache hit is a query for an invalid database entries, including non-existent entries.|
|filter\_users, filter\_groups|string|Tells SSSD to exclude certain users from being fetched from the NSS database. This is particularly useful for system accounts such as `root`.|
|filter\_users\_in\_groups|Boolean|Sets whether users listed in the `filter_users` list appear in group memberships when performing group lookups. If set to `FALSE`, group lookups return all users that are members of that group. If not specified, this value defaults to `true`, which filters the group member lists.|
|debug\_level|integer, 0 - 9|Sets a debug logging level.|
#### 7\.2.3.2. Configuring the PAM Service {#Configuration_Options-PAM_Configuration_Options}
### Warning
A mistake in the PAM configuration file can lock users out of the system completely. Always back up the configuration files before performing any changes, and keep a session open so that any changes can be reverted.
SSSD provides a PAM module, `sssd_pam`, which instructs the system to use SSSD to retrieve user information. The PAM configuration must include a reference to the SSSD module, and then the SSSD configuration sets how SSSD interacts with PAM.
To configure the PAM service:
1. Use **authconfig** to enable SSSD for system authentication.
# authconfig --update --enablesssd --enablesssdauth
This automatically updates the PAM configuration to reference all of the SSSD modules:
#%PAM-1.0
# This file is auto-generated.
# User changes will be destroyed the next time authconfig is run.
auth required pam_env.so
auth sufficient pam_unix.so nullok try_first_pass
auth requisite pam_succeed_if.so uid >= 500 quiet
**`auth sufficient pam_sss.so use_first_pass`**
auth required pam_deny.so
account required pam_unix.so
account sufficient pam_localuser.so
account sufficient pam_succeed_if.so uid < 500 quiet
**`account [default=bad success=ok user_unknown=ignore] pam_sss.so`**
account required pam_permit.so
password requisite pam_cracklib.so try_first_pass retry=3
password sufficient pam_unix.so sha512 shadow nullok try_first_pass use_authtok
**`password sufficient pam_sss.so use_authtok`**
password required pam_deny.so
session optional pam_keyinit.so revoke
session required pam_limits.so
session [success=1 default=ignore] pam_succeed_if.so service in crond quiet use_uid
**`session sufficient pam_sss.so`**
session required pam_unix.so
These modules can be set to `include` statements, as necessary.
1. Open the `sssd.conf` file.
# vim /etc/sssd/sssd.conf
1. Make sure that PAM is listed as one of the services that works with SSSD.
[sssd]
config_file_version = 2
reconnection_retries = 3
sbus_timeout = 30
services = nss, **`pam`**
1. In the **[pam]** section, change any of the PAM parameters. These are listed in [Table 7.2, “SSSD [pam] Configuration Parameters”](#tab.pam-sssd "Table 7.2. SSSD [pam] Configuration Parameters").
[pam]
reconnection_retries = 3
offline_credentials_expiration = 2
offline_failed_login_attempts = 3
offline_failed_login_delay = 5
1. Restart SSSD.
[root@server ~]# service sssd restart
Table 7.2. SSSD [pam] Configuration Parameters
|Parameter|Value Format|Description|
|-|
|offline\_credentials\_expiration|integer|Sets how long, in days, to allow cached logins if the authentication provider is offline. This value is measured from the last successful online login. If not specified, this defaults to zero (`0`), which is unlimited.|
|offline\_failed\_login\_attempts|integer|Sets how many failed login attempts are allowed if the authentication provider is offline. If not specified, this defaults to zero (`0`), which is unlimited.|
|offline\_failed\_login\_delay|integer|Sets how long to prevent login attempts if a user hits the failed login attempt limit. If set to zero (`0`), the user cannot authenticate while the provider is offline once he hits the failed attempt limit. Only a successful online authentication can re-enable offline authentication. If not specified, this defaults to five (`5`).|
### 7\.2.4. Creating Domains {#Configuring_Domains}
SSSD recognizes _domains_, which are associated with the different identity servers. Domains are a combination of an identity provider and an authentication method. SSSD works with LDAP identity providers (including OpenLDAP, Red Hat Directory Server, and Microsoft Active Directory) and can use native LDAP authentication or Kerberos authentication.
As long as they belong to different domains, SSSD can recognize different users with the same username. For example, SSSD can successfully authenticate both `jsmith` in the `ldap.example.com` domain and `jsmith` in the `ldap.otherexample.com` domain. SSSD allows requests using fully-qualified domain names, so requesting information for `jsmith@ldap.example.com` returns the proper user account. Specifying only the username returns the user for whichever domain comes first in the lookup order.
### Tip
SSSD has a `filter_users` option, which excludes the specified users from being returned in a search.
Configuring a domain defines both _where_ user information is stored and _how_ those users are allowed to authenticate to the system. The possible combinations are listed in [Table 7.3, “Identity Store and Authentication Type Combinations”](#tab.domain-combo "Table 7.3. Identity Store and Authentication Type Combinations").
* [Section 7.2.4.1, “General Rules and Options for Configuring a Domain”](#Configuring_Domains-Domain_Configuration_Options "7.2.4.1. General Rules and Options for Configuring a Domain")
* [Section 7.2.4.2, “Configuring an LDAP Domain”](#Configuring_Domains-Configuring_a_Native_LDAP_Domain "7.2.4.2. Configuring an LDAP Domain")
* [Section 7.2.4.3, “Configuring Kerberos Authentication with a Domain”](#Configuring_Domains-Setting_up_Kerberos_Authentication "7.2.4.3. Configuring Kerberos Authentication with a Domain")
* [Section 7.2.4.4, “Configuring a Proxy Domain”](#Domain_Configuration_Options-Configuring_a_Proxy_Domain "7.2.4.4. Configuring a Proxy Domain")
Table 7.3. Identity Store and Authentication Type Combinations
|Identification Provider|Authentication Provider|
|-|
|LDAP|LDAP|
|LDAP|Kerberos|
|proxy|LDAP|
|proxy|Kerberos|
|proxy|proxy|
#### 7\.2.4.1. General Rules and Options for Configuring a Domain {#Configuring_Domains-Domain_Configuration_Options}
A domain configuration defines the _identity provider_, the _authentication provider_, and any specific configuration to access the information in those providers. There are two types of identity providers — LDAP and proxy —three types of authentication providers — LDAP, Kerberos, and proxy. The identity and authentication providers can be configured in any combination in a domain entry.
Along with the domain entry itself, the domain name must be added to the list of domains that SSSD will query. For example:
domains = LOCAL,_`Name`_
[domain/_`Name`_]
id_provider = _`type`_
auth_provider = _`type`_
_`provider_specific = value`_
_`global = value`_
_global_ attributes are available to any type of domain, such as cache and time out settings. Each identity and authentication provider has its own set of required and optional configuration parameters.
Table 7.4. General [domain] Configuration Parameters
|Parameter|Value Format|Description|
|-|
|id\_provider|string|Specifies the data provider identity backend to use for this domain. The supported identity backends are:
* ldap
* ipa, compatible with FreeIPA version 2.x and Identity Management in Fedora
* proxy for a legacy NSS provider, such as `nss_nis`. Using a proxy ID provider also requires specifying the legacy NSS library to load to start successfully, set in the `proxy_lib_name` option.
* local, the SSSD internal local provider|
|auth\_provider|string|Sets the authentication provider used for the domain. The default value for this option is the value of `id_provider`. The supported authentication providers are ldap, ipa, krb5 (Kerberos), proxy, and none.|
|min\_id,max\_id|integer|_Optional._ Specifies the UID and GID range for the domain. If a domain contains entries that are outside that range, they are ignored. The default value for `min_id` is `1`; the default value for `max_id` is `0`, which is unlimited.
### Important
The default `min_id` value is the same for all types of identity provider. If LDAP directories are using UID numbers that start at one, it could cause conflicts with users in the local `/etc/passwd` file. To avoid these conflicts, set `min_id` to `1000` or higher as possible.|
|enumerate|Boolean|_Optional._ Specifies whether to list the users and groups of a domain. Enumeration means that the entire set of available users and groups on the remote source is cached on the local machine. When enumeration is disabled, users and groups are only cached as they are requested.
### Warning
When enumeration is enabled, reinitializing a client results in a complete refresh of the entire set of available users and groups from the remote source. Similarly, when SSSD is connected to a new server, the entire set of available users and groups from the remote source is pulled and cached on the local machine. In a domain with a large number of clients connected to a remote source, this refresh process can harm the network performance because of frequent queries from the clients. If the set of available users and groups is large enough, it degrades client performance as well.
The default value for this parameter is `false`, which disables enumeration.|
|cache\_credentials|Boolean|_Optional._ Specifies whether to store user credentials in the local SSSD domain database cache. The default value for this parameter is `false`. Set this value to `true` for domains other than the LOCAL domain to enable offline authentication.|
|entry\_cache\_timeout|integer|_Optional._ Specifies how long, in seconds, SSSD should cache _positive_ cache hits. A positive cache hit is a successful query.|
|use\_fully\_qualified\_names|Boolean|_Optional._ Specifies whether requests to this domain require fully-qualified domain names. If set to `true`, all requests to this domain must use fully-qualified domain names. It also means that the output from the request displays the fully-qualified name. Restricting requests to fully-qualified user names allows SSSD to differentiate between domains with users with conflicting usernames.
If _`use_fully_qualified_names`_ is set to `false`, it is possible to use the fully-qualified name in the requests, but only the simplified version is displayed in the output.
SSSD can only parse names based on the domain name, not the realm name. The same name can be used for both domains and realms, however.|
#### 7\.2.4.2. Configuring an LDAP Domain {#Configuring_Domains-Configuring_a_Native_LDAP_Domain}
An LDAP domain simply means that SSSD uses an LDAP directory as the identity provider (and, optionally, also as an authentication provider). SSSD supports several major directory services:
* Red Hat Directory Server
* OpenLDAP
* Microsoft Active Directory 2008, with Subsystem for UNIX-based Applications
### Note
DNS service discovery allows the LDAP backend to find the appropriate DNS servers to connect to automatically using a special DNS query.
* [Section 7.2.4.2.1, “Parameters for Configuring an LDAP Domain”](#ldap-domain-param "7.2.4.2.1. Parameters for Configuring an LDAP Domain")
* [Section 7.2.4.2.2, “LDAP Domain Example”](#ldap-domain-example "7.2.4.2.2. LDAP Domain Example")
* [Section 7.2.4.2.3, “Active Directory Domain Example”](#ad2008-example "7.2.4.2.3. Active Directory Domain Example")
* [Section 7.2.4.2.4, “Using IP Addresses in Certificate Subject Names”](#sssd-ldap-domain-ip "7.2.4.2.4. Using IP Addresses in Certificate Subject Names")
##### 7\.2.4.2.1. Parameters for Configuring an LDAP Domain {#ldap-domain-param}
An LDAP directory can function as both an identity provider and an authentication provider. The configuration requires enough information to identify and connect to the user directory in the LDAP server, but the way that those connection parameters are defined is flexible.
Other options are available to provide more fine-grained control, like specifying a user account to use to connect to the LDAP server or using different LDAP servers for password operations. The most common options are listed in [Table 7.5, “LDAP Domain Configuration Parameters”](#tab.sss-ldap-config "Table 7.5. LDAP Domain Configuration Parameters"). All of the options listed in [Section 7.2.4.1, “General Rules and Options for Configuring a Domain”](#Configuring_Domains-Domain_Configuration_Options "7.2.4.1. General Rules and Options for Configuring a Domain") are also available for LDAP domains.
### Tip
Many other options are listed in the man page for LDAP domain configuration, `sssd-ldap(5)`.
Table 7.5. LDAP Domain Configuration Parameters
|Parameter|Description|
|-|
|ldap\_uri|Gives a comma-separated list of the URIs of the LDAP servers to which SSSD will connect. The list is given in order of preference, so the first server in the list is tried first. Listing additional servers provides failover protection. This can be detected from the DNS SRV records if it is not given.|
|ldap\_search\_base|Gives the base DN to use for performing LDAP user operations.|
|ldap\_tls\_reqcert|Specifies how to check for SSL server certificates in a TLS session. There are four options:
* _never_ disables requests for certificates.
* _allow_ requests a certificate, but proceeds normally even if no certificate is given or a bad certificate is given.
* _try_ requests a certificate and proceeds normally if no certificate is given, If a bad certificate is given, the session terminates.
* _demand_ and _hard_ are the same option. This requires a valid certificate or the session is terminated.
The default is _hard_.|
|ldap\_tls\_cacert|Gives the full path and file name to the file that contains the CA certificates for all of the CAs that SSSD recognizes. SSSD will accept any certificate issued by these CAs.
This uses the OpenLDAP system defaults if it is not given explicitly.|
|ldap\_referrals|Sets whether SSSD will use LDAP referrals, meaning forwarding queries from one LDAP database to another. SSSD supports database-level and subtree referrals. For referrals within the same LDAP server, SSSD will adjust the DN of the entry being queried. For referrals that go to different LDAP servers, SSSD does an exact match on the DN. Setting this value to `true` enables referrals; this is the default.|
|ldap\_schema|Sets what version of schema to use when searching for user entries. This can be either `rfc2307` or `rfc2307bis`. The default is `rfc2307`.
In RFC 2307, group objects use a multi-valued attribute, _`memberuid`_, which lists the names of the users that belong to that group. In RFC 2307bis, group objects use the _`member`_ attribute, which contains the full distinguished name (DN) of a user or group entry. RFC 2307bis allows nested groups usning the _`member`_ attribute. Because these different schema use different definitions for group membership, using the wrong LDAP schema with SSSD can affect both viewing and managing network resources, even if the appropriate permissions are in place.
For example, with RFC 2307bis, all groups are returned when using nested groups or primary/secondary groups.
$ id
uid=500(myserver) gid=500(myserver) groups=500(myserver),510(myothergroup)
If SSSD is using RFC 2307 schema, only the primary group is returned.
This setting only affects how SSSD determines the group members. It does not change the actual user data.|
|ldap\_search\_timeout|Sets the time, in seconds, that LDAP searches are allowed to run before they are canceled and cached results are returned. This defaults to five when the `enumerate` value is false and defaults to 30 when `enumerate` is true.
When an LDAP search times out, SSSD automatically switches to offline mode.|
|ldap\_network\_timeout|Sets the time, in seconds, SSSD attempts to poll an LDAP server after a connection attempt fails. The default is six seconds.|
|ldap\_opt\_timeout|Sets the time, in seconds, to wait before aborting synchronous LDAP operations if no response is received from the server. This option also controls the timeout when communicating with the KDC in case of a SASL bind. The default is five seconds.|
##### 7\.2.4.2.2. LDAP Domain Example {#ldap-domain-example}
The LDAP configuration is very flexible, depending on your specific environment and the SSSD behavior. These are some common examples of an LDAP domain, but the SSSD configuration is not limited to these examples.
### Note
Along with creating the domain entry, add the new domain to the list of domains for SSSD to query in the `sssd.conf` file. For example:
domains = LOCAL,LDAP1,AD,PROXYNIS
Example 7.1. A Basic LDAP Domain Configuration
An LDAP domain requires three things:
* An LDAP server
* The search base
* A way to establish a secure connection
The last item depends on the LDAP environment. SSSD requires a secure connection since it handles sensitive information. This connection can be a dedicated TLS/SSL connection or it can use Start TLS.
Using a dedicated TLS/SSL connection simply uses an LDAPS connection to connect to the server and is therefore set as part of the `ldap_uri` option:
# An LDAP domain
[domain/LDAP]
enumerate = false
cache_credentials = true
id_provider = ldap
auth_provider = ldap
ldap_uri = ldaps://ldap.example.com:636
ldap_search_base = dc=example,dc=com
Using Start TLS requires a way to input the certificate information to establish a secure connection dynamically over an insecure port. This is done using the `ldap_id_use_start_tls` option to use Start TLS and then `ldap_tls_cacert` to identify the CA certificate which issued the SSL server certificates.
# An LDAP domain
[domain/LDAP]
enumerate = false
cache_credentials = true
id_provider = ldap
auth_provider = ldap
ldap_uri = ldap://ldap.example.com
ldap_search_base = dc=example,dc=com
ldap_id_use_start_tls = true
ldap_tls_reqcert = demand
ldap_tls_cacert = /etc/pki/tls/certs/ca-bundle.crt
##### 7\.2.4.2.3. Active Directory Domain Example {#ad2008-example}
For SSSD to work with an Active Directory domain, both the Active Directory domain and the local system have to be configured specially to communicate with one another.
### Note
The Microsoft Active Directory documentation has complete procedures for configuring the Active Directory domain.
1. Using **authconfig**, set the Linux client to use Active Directory as its LDAP identity provider. For example:
authconfig --enableldap --enableldapauth --ldapserver=ldap://ad.example.com:389 --enablekrb5 --krb5realm AD-REALM.EXAMPLE.COM --krb5kdc ad-kdc.example.com:88 --krb5adminserver ad-kdc.example.com:749 --update
The **authconfig** command is described in [Section 7.1, “Configuring System Authentication”](#sect-The_Authentication_Configuration_Tool "7.1. Configuring System Authentication").
1. Create the Active Directory Domain Services role.
1. Add the Identity Management for UNIX service to the Active Directory Domain Services role. Use the Unix NIS domain as the domain name in the configuration.
1. On the Active Directory server, create a new Computer object with the name of the Linux client.
1. In the Administrative Tools menu, select the Active Directory Users and Computers application.
1. Expand the Active Directory root object, such as **ad.example.com**.
1. Right-click Computers, and select the New and the Computer item.
1. Enter the name for the Linux client, such as **rhel-server**, and click OK.
1. Expand the Computers object.
1. Right-click the **rhel-server** object, and select Properties.
1. In the UNIX Attributes, enter the name of the Linux NIS domain and the IP address of the Linux server.
Click OK.
1. From the command prompt on the Active Directory server, create a machine account, password, and UPN for the Linux host principal.
C:\> setspn -A host/rhel-server.example.com@AD-REALM.EXAMPLE.COM rhel-server
Registering ServicePrincipalNames for CN=rhel server,CN=Computers,DC=ad,DC=example,DC=com
host/rhel server.example.com@AD-REALM.EXAMPLE.COM
Updated object
C:\> setspn -L rhel-server
Registered ServicePrincipalNames for CN=rhel server,CN=Computers,DC=ad,DC=example,DC=com:
host/rhel server.example.com@AD-REALM.EXAMPLE.COM
C:\> ktpass /princ host/rhel-server.example.com@AD-REALM.EXAMPLE.COM /out rhel-server.keytab /crypto all /ptype KRB5_NT_PRINCIPAL -desonly /mapuser AD\rhel-server$ +rndPass
Targeting domain controller:
ad.example.com
Using legacy password setting method
Successfully mapped host/rhel server.redhat.com
... 8< ...
1. Copy the keytab from the Active Directory server to the Linux client, and save it as `/etc/krb5.keytab`.
1. On the Linux system, reset the permissions and owner for the keytab file.
[root@rhel-server ~]# chown root:root /etc/krb5.keytab
[root@rhel-server ~]# chmod 0600 /etc/krb5.keytab
1. Restore the SELinux file permissions for the keytab.
[root@rhel-server ~]# restorecon /etc/krb5.keytab
1. Verify that the host can connect to the Active Directory domain.
[root@rhel-server ~]# kinit -k -t /etc/krb5.keytab host/rhel-server.example.com@AD-REALM.EXAMPLE.COM
1. On the Active Directory server, create a a group for the Linux users.
1. Create a new group named _unixusers_.
1. Open the unixusers group and open the Unix Attributes tab.
1. Configure the Unix settings:
* The NIS domain
* The UID
* The login shell, to **/bin/bash**
* The home directory, to **/home/aduser**
* The primary group name, to **unixusers**
1. Then, configure the SSSD domain on the Linux machine.
Example 7.2. An Active Directory 2008 Domain
[root@rhel-server ~]# vim /etc/sssd/sssd.conf
[sssd]
config_file_version = 2
domains = ad.example.com
services = nss, pam
[nss]
[pam]
[domain/ad.example.com]
cache_credentials = true
enumerate = false
id_provider = ldap
auth_provider = krb5
chpass_provider = krb5
access_provider = ldap
ldap_sasl_mech = GSSAPI
ldap_sasl_authid = host/rhel-server.example.com@AD-REALM.EXAMPLE.COM
ldap_schema = rfc2307bis
ldap_user_search_base = ou=user accounts,dc=ad,dc=example,dc=com
ldap_user_object_class = user
ldap_user_home_directory = unixHomeDirectory
ldap_user_principal = userPrincipalName
ldap_user_name = sAMAccountName
ldap_group_search_base = ou=groups,dc=ad,dc=example,dc=com
ldap_group_object_class = group
ldap_access_order = expire
ldap_account_expire_policy = ad
ldap_force_upper_case_realm = true
ldap_disable_referrals = true
#krb5_server = server.ad.example.com
krb5_realm = AD-REALM.EXAMPLE.COM
These options are described in the man page for LDAP domain configuration, `sssd-ldap(5)`.
1. Restart SSSD.
[root@rhel-server ~]# service sssd restart
##### 7\.2.4.2.4. Using IP Addresses in Certificate Subject Names {#sssd-ldap-domain-ip}
Using an IP address in the `ldap_uri` option instead of the server name may cause the TLS/SSL connection to fail. TLS/SSL certificates contain the server name, not the IP address. However, the _subject alternative name_ field in the certificate can be used to include the IP address of the server, which allows a successful secure connection using an IP address.
1. Convert an existing certificate into a certificate request. The signing key (`-signkey`) is the key of the issuer of whatever CA originally issued the certificate. If this is done by an external CA, it requires a separate PEM file; if the certificate is self-signed, then this is the certificate itself. For example:
openssl x509 -x509toreq -in old_cert.pem -out req.pem -signkey key.pem
With a self-signed certificate:
openssl x509 -x509toreq -in old_cert.pem -out req.pem -signkey old_cert.pem
1. Edit the `/etc/pki/tls/openssl.cnf` configuration file to include the server's IP address under the _`[ v3_ca ]`_ section:
subjectAltName = IP:10.0.0.10
1. Use the generated certificate request to generate a new self-signed certificate with the specified IP address:
openssl x509 -req -in req.pem -out new_cert.pem -extfile ./openssl.cnf -extensions v3_ca -signkey old_cert.pem
The `-extensions` option sets which extensions to use with the certificate. For this, it should be v3\_ca to load the appropriate section.
1. Copy the private key block from the `old_cert.pem` file into the `new_cert.pem` file to keep all relevant information in one file.
When creating a certificate through the certutil utility provided by the `nss-utils` package, note that certutil supports DNS subject alternative names for certificate creation only.
#### 7\.2.4.3. Configuring Kerberos Authentication with a Domain {#Configuring_Domains-Setting_up_Kerberos_Authentication}
Both LDAP and proxy identity providers can use a separate Kerberos domain to supply authentication. Configuring a Kerberos authentication provider requires the _key distribution center_ (KDC) and the Kerberos domain. All of the principal names must be available in the specified identity provider; if they are not, SSSD constructs the principals using the format _username@REALM_.
### Note
Kerberos can only provide authentication; it cannot provide an identity database.
SSSD assumes that the Kerberos KDC is also a Kerberos kadmin server. However, production environments commonly have multiple, read-only replicas of the KDC and only a single kadmin server. Use the `krb5_kpasswd` option to specify where the password changing service is running or if it is running on a non-default port. If the `krb5_kpasswd` option is not defined, SSSD tries to use the Kerberos KDC to change the password.
The basic Kerberos configuration options are listed in [Table 7.6, “Kerberos Authentication Configuration Parameters”](#tab.sssd-krb-params "Table 7.6. Kerberos Authentication Configuration Parameters"). The `sssd-krb5(5)` man page has more information about Kerberos configuration options.
Example 7.3. Basic Kerberos Authentication
# A domain with identities provided by LDAP and authentication by Kerberos
[domain/KRBDOMAIN]
enumerate = false
id_provider = ldap
chpass_provider = krb5
ldap_uri = ldap://ldap.example.com
ldap_search_base = dc=example,dc=com
ldap-tls_reqcert = demand
ldap_tls_cacert = /etc/pki/tls/certs/ca-bundle.crt
auth_provider = krb5
krb5_server = 192.168.1.1, kerberos.example.com
krb5_realm = EXAMPLE.COM
krb5_kpasswd = kerberos.admin.example.com
krb5_auth_timeout = 15
Table 7.6. Kerberos Authentication Configuration Parameters
|Parameter|Description|
|-|
|chpass\_provider|Specifies which service to use for password change operations. This is assumed to be the same as the authentication provider. To use Kerberos, set this to _krb5_.|
|krb5\_server|Gives a comma-separated list of IP addresses or hostnames of Kerberos servers to which SSSD will connect. The list is given in order of preference, so the first server in the list is tried first. Listing additional servers provides failover protection.
When using service discovery for KDC or kpasswd servers, SSSD first searches for DNS entries that specify UDP as the connection protocol, and then falls back to TCP.|
|krb5\_realm|Identies the Kerberos realm served by the KDC.|
|krb5\_lifetime|Requests a Kerberos ticket with the specified lifetime in seconds (s), minutes (m), hours (h) or days (d).|
|krb5\_renewable\_lifetime|Requests a renewable Kerberos ticket with a total lifetime that is specified in seconds (s), minutes (m), hours (h) or days (d).|
|krb5\_renew\_interval|Sets the time, in seconds, for SSSD to check if tickets should be renewed. Tickets are renewed automatically once they exceed half their lifetime. If this option is missing or set to zero, then automatic ticket renewal is disabled.|
|krb5\_store\_password\_if\_offline|Sets whether to store user passwords if the Kerberos authentication provider is offline, and then to use that cache to request tickets when the provider is back online. The default is **false**, which does not store passwords.|
|krb5\_kpasswd|Lists alternate Kerberos kadmin servers to use if the change password service is not running on the KDC.|
|krb5\_ccname\_template|Gives the directory to use to store the user's credential cache. This can be templatized, and the following tokens are supported:
* _%u_, the user's login name
* _%U_, the user's login UID
* _%p_, the user's principal name
* _%r_, the realm name
* _%h_, the user's home directory
* _%d_, the value of the `krb5ccache_dir` parameter
* _%P_, the process ID of the SSSD client.
* _%%_, a literal percent sign (%)
* _XXXXXX_, a string at the end of the template which instructs SSSD to create a unique filename safely
For example:
krb5_ccname_template = FILE:%d/krb5cc_%U_XXXXXX|
|krb5\_ccachedir|Specifies the directory to store credential caches. This can be templatized, using the same tokens as `krb5_ccname_template`, except for `%d` and `%P`. If `%u`, `%U`, `%p`, or `%h` are used, then SSSD creates a private directory for each user; otherwise, it creates a public directory.|
|krb5\_auth\_timeout|Gives the time, in seconds, before an online authentication or change password request is aborted. If possible, the authentication request is continued offline. The default is 15 seconds.|
#### 7\.2.4.4. Configuring a Proxy Domain {#Domain_Configuration_Options-Configuring_a_Proxy_Domain}
A proxy with SSSD is just a relay, an intermediary configuration. SSSD connects to its proxy service, and then that proxy loads the specified libraries. This allows SSSD to use some resources that it otherwise would not be able to use. For example, SSSD only supports LDAP and Kerberos as authentication providers, but using a proxy allows SSSD to use alternative authentication methods like a fingerprint scanner or smart card.
Table 7.7. Proxy Domain Configuration Parameters
|Parameter|Description|
|-|
|proxy\_pam\_target|Specifies the target to which PAM must proxy as an authentication provider. The PAM target is a file containing PAM stack information in the default PAM directory, `/etc/pam.d/`.
This is used to proxy an authentication provider.
### Important
Ensure that the proxy PAM stack does _not_ recursively include `pam_sss.so`.|
|proxy\_lib\_name|Specifies which existing NSS library to proxy identity requests through.
This is used to proxy an identity provider.|
Example 7.4. Proxy Identity and Kerberos Authentication
The proxy library is loaded using the `proxy_lib_name` parameter. This library can be anything as long as it is compatible with the given authentication service. For a Kerberos authentication provider, it must be a Kerberos-compatible library, like NIS.
[domain/PROXY_KRB5]
auth_provider = krb5
krb5_server = 192.168.1.1
krb5_realm = EXAMPLE.COM
id_provider = proxy
proxy_lib_name = nis
enumerate = true
cache_credentials = true
Example 7.5. LDAP Identity and Proxy Authentication
The proxy library is loaded using the `proxy_pam_target` parameter. This library must be a PAM module that is compatible with the given identity provider. For example, this uses a PAM fingerprint module with LDAP:
[domain/LDAP_PROXY]
id_provider = ldap
ldap_uri = ldap://example.com
ldap_search_base = dc=example,dc=com
auth_provider = proxy
proxy_pam_target = sssdpamproxy
enumerate = true
cache_credentials = true
After the SSSD domain is configured, make sure that the specified PAM files are configured. In this example, the target is **sssdpamproxy**, so create a `/etc/pam.d/sssdpamproxy` file and load the PAM/LDAP modules:
auth required pam_frprint.so
account required pam_frprint.so
password required pam_frprint.so
session required pam_frprint.so
Example 7.6. Proxy Identity and Authentication
SSSD can have a domain with both identity and authentication proxies. The only configuration given then are the proxy settings, `proxy_pam_target` for the authentication PAM module and `proxy_lib_name` for the service, like NIS or LDAP.
_This example illustrates a possible configuration, but this is not a realistic configuration. If LDAP is used for identity and authentication, then both the identity and authentication providers should be set to the LDAP configuration, not a proxy._
[domain/PROXY_PROXY]
auth_provider = proxy
id_provider = proxy
proxy_lib_name = ldap
proxy_pam_target = sssdproxyldap
enumerate = true
cache_credentials = true
Once the SSSD domain is added, then update the system settings to configure the proxy service:
1. Create a `/etc/pam.d/sssdproxyldap` file which requires the **pam\_ldap.so** module:
auth required pam_ldap.so
account required pam_ldap.so
password required pam_ldap.so
session required pam_ldap.so
1. Make sure the `nss-pam-ldap` package is installed.
[root@server ~]# yum install nss-pam-ldap
1. Edit the `/etc/nslcd.conf` file, the configuration file for the LDAP name service daemon, to contain the information for the LDAP directory:
uid nslcd
gid ldap
uri ldaps://ldap.example.com:636
base dc=example,dc=com
ssl on
tls_cacertdir /etc/openldap/cacerts
### 7\.2.5. Configuring Access Control for SSSD Domains {#config-sssd-domain-access}
SSSD provides a rudimentary access control for domain configuration, allowing either simple user allow/deny lists or using the LDAP backend itself.
#### 7\.2.5.1. Using the Simple Access Provider {#simple-access}
The _Simple Access Provider_ allows or denies access based on a list of usernames or groups.
The Simple Access Provider is a way to restrict access to certain, specific machines. For example, if a company uses laptops, the Simple Access Provider can be used to restrict access to only a specific user or a specific group, even if a different user authenticated successfully against the same authentication provider.
The most common options are `simple_allow_users` and `simple_allow_groups`, which grant access explicitly to specific users (either the given users or group members) and deny access to everyone else. It is also possible to create deny lists (which deny access only to explicit people and implicitly allow everyone else access).
The Simple Access Provider adheres to the following four rules to determine which users should or should not be granted access:
* If both the allow and deny lists are empty, access is granted.
* If any list is provided, allow rules are evaluated first, and then deny rules. Practically, this means that deny rules supersede allow rules.
* If an allowed list is provided, then all users are denied access unless they are in the list.
* If only deny lists are provided, then all users are allowed access unless they are in the list.
This example grants access to two users and anyone who belongs to the IT group; implicitly, all other users are denied:
[domain/example.com]
access_provider = simple
simple_allow_users = jsmith,bjensen
simple_allow_groups = itgroup
### Note
The LOCAL domain in SSSD does not support `simple` as an access provider.
Other options are listed in the `sssd-simple` man page, but these are rarely used.
#### 7\.2.5.2. Using the LDAP Access Filter {#idm83582048}
The LDAP server itself can provide the access control rules. The associated filter option (`ldap_access_filter`) specifies which users are granted access to the specified host. The user filter must be used or all users are denied access.
For example:
[domain/example.com]
access_provider = ldap
ldap_access_filter = memberOf=cn=allowedusers,ou=Groups,dc=example,dc=com
### Note
Offline caching for LDAP access providers is limited to determining whether the user's last online login attempt was successful. Users that were granted access during their last login will continue to be granted access while offline.
SSSD can also check results by the account expiration policy and the _`authorizedService`_ attribute.
### 7\.2.6. Configuring Domain Failover {#Configuring_Failover}
SSSD attempts to connect to machines and to services separately.
When SSSD tries to connect to one of its domain backends, it first tries to resolve the hostname of a given machine. If this resolution attempt fails, the machine is considered offline, and SSSD no longer attempts to connect to this machine for any other service.
If the resolution attempt succeeds, the backend tries to connect to a service on this machine. If the service connection attempt fails, then only this particular service is considered offline and the backend automatically switches over to the next service. The machine is still considered online and might still be tried for another service.
SSSD only tries the first IP address given in the DNS A record. To find multiple servers with a single request, SSSD relies on SRV records.
Connections are retried to offline machines or services every 30 seconds, until SSSD can successfully connect to the backend.
#### 7\.2.6.1. Configuring Failover {#config-failover}
Configuring failover allows SSSD to switch automatically to a different server if the primary server fails. These servers are entered as a case-insensitive, comma-separated list in the _[domain/Name]_ sections of the `/etc/sssd/sssd.conf` file. The servers are listed in order of preference. This list can contain any number of servers.
For example, for a native LDAP domain:
ldap_uri = ldap://ldap0.example.com, ldap://ldap1.example.com, ldap://ldap2.example.com
The first entry, ldap://ldap0.example.com, is the primary server. If this server fails, SSSD first attempts to connect to ldap1.example.com and then ldap2.example.com.
If the server parameter is not specified, then SSSD uses service discovery to try to find another server on the network.
### Important
The failover servers must be entered as a comma-separated list of values for a single key. If there are multiple keys, SSSD only recognizes the last entry.
#### 7\.2.6.2. Using SRV Records with Failover {#Using_SRV_Records_with_Failover}
SSSD supports SRV records in its failover configuration. The SSSD configuration can specify a server that is later resolved into a list of specific servers using SRV requests.
For every service with which to use service discovery, add a special DNS record to the DNS server:
__`service`_.__`protocol`_.__`domain TTL priority weight port hostname`_
The _priority_ and _weight_ attributes of SRV records provide fine-grained control over which servers to contact first if the primary server fails.
A typical configuration contains multiple such records, each with a different priority for failover and different weights for load balancing.
For more information on SRV records, see [RFC 2782](http://tools.ietf.org/html/rfc2782).
### 7\.2.7. Managing the SSSD Cache {#sssd-cache}
SSSD can define multiple domains of the same type and different types of domain. SSSD maintains a separate database file for each domain, meaning each domain has its own cache. These cache files are stored in the `/var/lib/sss/db/` directory.
#### 7\.2.7.1. Purging the SSSD Cache {#sssd-cache-purge}
As LDAP updates are made to the identity provider for the domains, it can be necessary to clear the cache to reload the new information quickly.
The cache purge utility, **sss\_cache**, invalidates records in the SSSD cache for a user, a domain, or a group. Invalidating the current records forces the cache to retrieve the updated records from the identity provider, so changes can be realized quickly.
Most commonly, this is used to clear the cache and update the records for an entire domain:
Example 7.7. Purging Domain Records
[root@server ~]# sss_cache -d LDAP1
If the administrator knows that a specific record (user, group, or netgroup) has been updated, then **sss\_cache** can purge the records for that specific account, and leave the rest of the cache intact.
Example 7.8. Purging a User Record
[root@server ~]# sss_cache -u jsmith
Table 7.8. sss\_cache Options
|Short Argument|Long Argument|Description|
|-|
|-d _name_|--domain _name_|Invalidates cache entries for users, groups, and other entries only within the specified domain.|
|-G|--groups|Invalidates all group records. If `-g` is also used, `-G` takes precedence and `-g` is ignored.|
|-g _name_|--group _name_|Invalidates the cache entry for the specified group.|
|-N|--netgroups|Invalidates cache entries for all netgroup cache records. If `-n` is also used, `-N` takes precedence and `-n` is ignored.|
|-n _name_|--netgroup _name_|Invalidates the cache entry for the specified netgroup.|
|-U|--users|Invalidates cache entries for all user records. If the `-u` option is also used, `-U` takes precedence and `-u` is ignored.|
|-u _name_|--user _name_|Invalidates the cache entry for the specified user.|
#### 7\.2.7.2. Deleting Domain Cache Files {#domain-sssd-delete-cache}
All cache files are named for the domain. For example, for a domain named **exampleldap**, the cache file is named `cache_exampleldap.ldb`.
**Be careful when you delete a cache file.** This operation has significant effects:
* Deleting the cache file deletes all user data, both identification and cached credentials. Consequently, do not delete a cache file unless the system is online and can authenticate with a username against the domain's servers. Without a credentials cache, offline authentication will fail.
* If the configuration is changed to reference a different identity provider, SSSD will recognize users from both providers until the cached entries from the original provider time out.
It is possible to avoid this by purging the cache, but the better option is to use a different domain name for the new provider. When SSSD is restarted, it creates a new cache file with the new name and the old file is ignored.
### 7\.2.8. Configuring OpenSSH to Check SSSD for Cached Keys (TECH PREVIEW) {#openssh-sssd}
OpenSSH creates secure, encrypted connections between two systems. One machine authenticates to another machine to allow access; the authentication can be of the machine itself for server connections or of a user on that machine. OpenSSH is described in more detail in [Chapter 8, _OpenSSH_](#ch-OpenSSH "Chapter 8. OpenSSH").
This authentication is performed through _public-private key pairs_ that identify the authenticating user or machine. The remote machine or user attempting to access the machine presents a key pair. The local machine then elects whether to trust that remote entity; if it is trusted, the public key for that remote machine is stored in the `known_hosts` file or for the remote user in `authorized_keys`. Whenever that remote machine or user attempts to authenticate again, the local system simply checks the `known_hosts` or `authorized_keys` file first to see if that remote entity is recognized and trusted. If it is, then access is granted.
The first problem comes in verifying those identities reliably.
The `known_hosts` file is a triplet of the machine name, its IP address, and its public key:
server.example.com,255.255.255.255 ssh-rsa AbcdEfg1234ZYX098776/AbcdEfg1234ZYX098776/AbcdEfg1234ZYX098776=
The `known_hosts` file can quickly become outdated for a number of different reasons: systems using DHCP cycle through IP addresses, new keys can be re-issued periodically, or virtual machines or services can be brought online and removed. This changes the hostname, IP address, and key triplet.
Administrators have to clean and maintain a current `known_hosts` file to maintain security. (Or system users get in the habit of simply accepting any machine and key presented, which negates the security benefits of key-based security.)
Additionally, problem for both machines and users is distributing keys in a scalable way. Machines can send their keys are part of establishing an encrypted session, but users have to supply their keys in advance. Simply propagating and then updating keys consistently is a difficult administrative task.
Lastly, SSH key and machine information are only maintained locally. There may be machines or users on the network which are recognized and trusted by some systems and not by others because the `known_hosts` file has not been updated uniformly.
The goal of SSSD is to server as a credentials cache. This includes working as a credentials cache for SSH public keys for machines and users. OpenSSH is configured to reference SSSD to check for cached keys; SSSD uses Red Hat Linux's Identity Management (IPA) domain as an identity, and IPA actually stores the public keys and host information.
### NOTE
Only Linux machines enrolled, or joined, in the IPA domain can use SSSD as a key cache for OpenSSH. Other Unix machines and Windows machines must use the regular authentication mechanisms with the `known_hosts` file.
#### 7\.2.8.1. Configuring OpenSSH to Use SSSD for Host Keys {#openssh-sssd-hosts}
OpenSSH is configured in either a user-specific configuration file (`~/.ssh/config`) or a system-wide configuration file (`/etc/ssh/ssh_config`). The user file has precedence over the system settings and the first obtained value for a paramter is used. The formatting and conventions for this file are covered in [Chapter 8, _OpenSSH_](#ch-OpenSSH "Chapter 8. OpenSSH").
In order to manage host keys, SSSD has a tool, **sss\_ssh\_knownhostsproxy**, which performs three operations:
1. Retrieves the public host key from the enrolled Linux system.
1. Stores the host key in a custom hosts file, `.ssh/sss_known_hosts`.
1. Establishes a connection with the host machine, either a socket (the default) or a secure connection.
This tool has the format:
sss_ssh_knownhostsproxy [-d _`sssd_domain`_] [-p _`ssh_port`_] _`HOST`_ [_`PROXY_COMMAND`_]
Table 7.9. sss\_ssh\_knownhostsproxy Options
|Short Argument|Long Argument|Description|
|-|
||_HOSTNAME_|Gives the hostname of the host to check and connect to. In the OpenSSH configuration file, this can be a token, **%h**.|
||_PROXY\_COMMAND_|Passes a proxy command to use to connect to the SSH client. This is similar to running **ssh -o ProxyCommand=**_value_. This option is used when running **sss\_ssh\_knownhostsproxy** from the command line or through another script, but is not necessary in the OpenSSH configuration file.|
|-d _sssd\_domain_|--domain _sssd\_domain_|Only searches for public keys in entries in the specified domain. If not given, SSSD searches for keys in all configured domains.|
|-p _port_|--port _port_|Uses this port to connect to the SSH client. By default, this is port 22.|
To use this SSSD tool, add or edit two parameters to the `ssh_config` or `~/.ssh/config` file:
* Specify the command to use to connect to the SSH client (**ProxyCommand**). This is the **sss\_ssh\_knownhostsproxy**, with the desired arguments and hostname.
* Specify the location of the SSSD hosts file, rather than the default `known_hosts` file (**UserKnownHostsFile**). The SSSD hosts file is `.ssh/sss_known_hosts`.
For example, this looks for public keys in the **IPA1** SSSD domain and connects over whatever port and host are supplied:
ProxyCommand /usr/bin/sss_ssh_knownhostsproxy -p %p -d IPA1 %h
UserKnownHostsFile2 .ssh/sss_known_hosts
#### 7\.2.8.2. Configuring OpenSSH to Use SSSD for User Keys {#openssh-sssd-users}
User keys are stored on a local system in the `authorized_keys` file for OpenSSH. As with hosts, SSSD can maintain and automatically update a separate cache of user public keys for OpenSSH to refer to. This is kept in the `.ssh/sss_authorized_keys` file.
OpenSSH is configured in either a user-specific configuration file (`~/.ssh/config`) or a system-wide configuration file (`/etc/ssh/ssh_config`). The user file has precedence over the system settings and the first obtained value for a paramter is used. The formatting and conventions for this file are covered in [Chapter 8, _OpenSSH_](#ch-OpenSSH "Chapter 8. OpenSSH").
In order to manage user keys, SSSD has a tool, **sss\_ssh\_authorizedkeys**, which performs two operations:
1. Retrieves the user's public key from the user entries in the Identity Management (IPA) domain.
1. Stores the user key in a custom file, `.ssh/sss_authorized_keys`, in the standard authorized keys format.
This tool has the format:
sss_ssh_authorizedkeys [-d _`sssd_domain`_] _`USER`_
Table 7.10. sss\_ssh\_authorizedkeys Options
|Short Argument|Long Argument|Description|
|-|
||_USER_|Gives the username or account name for which to obtain the public key. In the OpenSSH configuration file, this can be represented by a token, **%u**.|
|-d _sssd\_domain_|--domain _sssd\_domain_|Only searches for public keys in entries in the specified domain. If not given, SSSD searches for keys in all configured domains.|
There are two possible options for how to configure OpenSSH to use SSSD for user keys, depending on the SSH deployment:
* Most commonly, SSH supports the authorized key command. In that case, it is necessary only to specify the command to run to retrieve user keys. For example:
AuthorizedKeysCommand /usr/bin/sss_ssh_authorizedkeys
* SSH can also support a public key agent. In that case, give the command to use to retrieve agent keys, including tokens for required arguments (such as the username):
PubKeyAgent /usr/bin/sss_ssh_authorizedkeys %u
### 7\.2.9. Using NSCD with SSSD {#usingnscd-sssd}
SSSD is not designed to be used with the NSCD daemon. Even though SSSD does not directly conflict with NSCD, using both services can result in unexpected behavior, especially with how long entries are cached.
The most common evidence of a problem is conflicts with NFS. When using Network Manager to manage network connections, it may take several minutes for the network interface to come up. During this time, various services attempt to start. If these services start before the network is up and the DNS servers are available, these services fail to identify the forward or reverse DNS entries they need. These services will read an incorrect or possibly empty `resolv.conf` file. This file is typically only read once, and so any changes made to this file are not automatically applied. This can cause NFS locking to fail on the machine where the NSCD service is running, unless that service is manually restarted.
To avoid this problem, enable caching for hosts and services in the `/etc/nscd.conf` file and rely on the SSSD cache for the `passwd`, `group`, and `netgroup` entries.
Change the `/etc/nscd.conf` file:
enable-cache hosts yes
enable-cache passwd no
enable-cache group no
enable-cache netgroup no
With NSCD answering hosts requests, these entries will be cached by NSCD and returned by NSCD during the boot process. All other entries are handled by SSSD.
### 7\.2.10. Troubleshooting SSSD {#SSSD-Troubleshooting}
#### 7\.2.10.1. Setting Debug Logs for SSSD Domains {#sssd-debug}
Each domain sets its own debug log level. Increasing the log level can provide more information about problems with SSSD or with the domain configuration.
To change the log level, set the _`debug_level`_ parameter for each section in the `sssd.conf` file for which to produce extra logs. For example:
[domain/LDAP]
enumerate = false
cache_credentials = true
**`debug_level = 9`**
Table 7.11. Debug Log Levels
|Level|Description|
|-|
|0|Fatal failures. Anything that would prevent SSSD from starting up or causes it to cease running.|
|1|Critical failures. An error that doesn't kill the SSSD, but one that indicates that at least one major feature is not going to work properly.|
|2|Serious failures. An error announcing that a particular request or operation has failed.|
|3|Minor failures. These are the errors that would percolate down to cause the operation failure of 2.|
|4|Configuration settings.|
|5|Function data.|
|6|Trace messages for operation functions.|
|7|Trace messages for internal control functions.|
|8|Contents of function-internal variables that may be interesting.|
|9|Extremely low-level tracing information.|
### NOTE
In versions of SSSD older than 1.8, debug log levels could be set globally in the **[sssd]** section. Now, each domain and service must configure its own debug log level.
To copy the global SSSD debug log levels into each configuration area in the SSSD configuration file, use the `sssd_update_debug_levels.py` script.
python /usr/lib/python2.6/site-packages/sssd_update_debug_levels.py
#### 7\.2.10.2. Checking SSSD Log Files {#Troubleshooting-Using_SSSD_Log_Files}
SSSD uses a number of log files to report information about its operation, located in the `/var/log/sssd/` directory. SSSD produces a log file for each domain, as well as an `sssd_pam.log` and an `sssd_nss.log` file.
Additionally, the `/var/log/secure` file logs authentication failures and the reason for the failure.
#### 7\.2.10.3. Problems with SSSD Configuration {#Troubleshooting-Problems_with_SSSD_Configuration}
SSSD fails to start. SSSD requires that the configuration file be properly set up, with all the required entries, before the daemon will start.
* SSSD requires at least one properly configured domain before the service will start. Without a domain, attempting to start SSSD returns an error that no domains are configured:
# sssd -d4
[sssd] [ldb] (3): server_sort:Unable to register control with rootdse!
[sssd] [confdb_get_domains] (0): No domains configured, fatal error!
[sssd] [get_monitor_config] (0): No domains configured.
Edit the `/etc/sssd/sssd.conf` file and create at least one domain.
* SSSD also requires at least one available service provider before it will start. If the problem is with the service provider configuration, the error message indicates that there are no services configured:
[sssd] [get_monitor_config] (0): No services configured!
Edit the `/etc/sssd/sssd.conf` file and configure at least one service provider.
### Important
SSSD requires that service providers be configured as a comma-separated list in a single _`services`_ entry in the `/etc/sssd/sssd.conf` file. If services are listed in multiple entries, only the last entry is recognized by SSSD.
I don't see any groups with 'id' or group members with 'getent group'. This may be due to an incorrect **ldap\_schema** setting in the **[domain/DOMAINNAME]** section of `sssd.conf`.
SSSD supports RFC 2307 and RFC 2307bis schema types. By default, SSSD uses the more common RFC 2307 schema.
The difference between RFC 2307 and RFC 2307bis is the way which group membership is stored in the LDAP server. In an RFC 2307 server, group members are stored as the multi-valued _`memberuid`_ attribute, which contains the name of the users that are members. In an RFC2307bis server, group members are stored as the multi-valued _`member`_ or _`uniqueMember`_ attribute which contains the DN of the user or group that is a member of this group. RFC2307bis allows nested groups to be maintained as well.
If group lookups are not returning any information:
1. Set **ldap\_schema** to **rfc2307bis**.
1. Delete `/var/lib/sss/db/cache_DOMAINNAME.ldb`.
1. Restarting SSSD.
If that doesn't work, add this line to `sssd.conf`:
ldap_group_name = uniqueMember
Then delete the cache and restart SSSD again.
Authentication fails against LDAP. To perform authentication, SSSD requires that the communication channel be encrypted. This means that if `sssd.conf` is configured to connect over a standard protocol (`ldap://`), it attempts to encrypt the communication channel with Start TLS. If `sssd.conf` is configured to connect over a secure protocol (`ldaps://`), then SSSD uses SSL.
This means that the LDAP server must be configured to run in SSL or TLS. TLS must be enabled for the standard LDAP port (389) or SSL enabled on the secure LDAPS port (636). With either SSL or TLS, the LDAP server must also be configured with a valid certificate trust.
An invalid certificate trust is one of the most common issues with authenticating against LDAP. If the client does not have proper trust of the LDAP server certificate, it is unable to validate the connection, and SSSD refuses to send the password. The LDAP protocol requires that the password be sent in plaintext to the LDAP server. Sending the password in plaintext over an unencrypted connection is a security problem.
If the certificate is not trusted, a `syslog` message is written, indicating that TLS encryption could not be started. The certificate configuration can be tested by checking if the LDAP server is accessible apart from SSSD. For example, this tests an anonymous bind over a TLS connection to **test.example.com**:
$ ldapsearch -x -ZZ -h test.example.com -b dc=example,dc=com
If the certificate trust is not properly configured, the test fails with this error:
ldap_start_tls: Connect error (-11) additional info: TLS error -8179:Unknown code ___f 13
To trust the certificate:
1. Obtain a copy of the public CA certificate for the certificate authority used to sign the LDAP server certificate and save it to the local system.
1. Add a line to the `sssd.conf` file that points to the CA certificate on the filesystem.
ldap_tls_cacert = /path/to/cacert
1. If the LDAP server uses a self-signed certificate, remove the **ldap\_tls\_reqcert** line from the `sssd.conf` file.
This parameter directs SSSD to trust any certificate issued by the CA certificate, which is a security risk with a self-signed CA certificate.
Connecting to LDAP servers on non-standard ports fail. When running SELinux in enforcing mode, the client's SELinux policy has to be modified to connect to the LDAP server over the non-standard port. For example:
# semanage port -a -t ldap_port_t -p tcp 1389
NSS fails to return user information. This usually means that SSSD cannot connect to the NSS service.
* Ensure that NSS is running:
# service sssd status
* If NSS is running, make sure that the provider is properly configured in the `[nss]` section of the `/etc/sssd/sssd.conf` file. Especially check the _`filter_users`_ and _`filter_groups`_ attributes.
* Make sure that NSS is included in the list of services that SSSD uses.
* Check the configuration in the `/etc/nsswitch.conf` file.
NSS returns incorrect user information . If searches are returning the incorrect user information, check that there are not conflicting usernames in separate domains. When there are multiple domains, set the _`use_fully_qualified_domains`_ attribute to `true` in the `/etc/sssd/sssd.conf` file. This differentiates between different users in different domains with the same name.
Setting the password for the local SSSD user prompts twice for the password. When attempting to change a local SSSD user's password, it may prompt for the password twice:
[root@clientF11 tmp]# passwd user1000
Changing password for user user1000.
New password:
Retype new password:
New Password:
Reenter new Password:
passwd: all authentication tokens updated successfully.
This is the result of an incorrect PAM configuration. Ensure that the _`use_authtok`_ option is correctly configured in your `/etc/pam.d/system-auth` file.
## Chapter 8. OpenSSH {#ch-OpenSSH}
`SSH` (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.
The ssh program 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.
Fedora includes the general OpenSSH package (openssh) as well as the OpenSSH server (openssh-server) and client (openssh-clients) packages. Note that the OpenSSH packages require the OpenSSL package (openssl), which installs several important cryptographic libraries, enabling OpenSSH to provide encrypted communications.
## 8\.1. The SSH Protocol {#s1-ssh-protocol}
### 8\.1.1. Why Use SSH? {#s2-ssh-why}
Potential intruders 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
: The attacker can be somewhere on the network between the communicating parties, copying any information passed between them. He may intercept and keep the information, or alter the information and send it on to the intended recipient.
This attack is usually performed using a _packet sniffer_, a rather common network utility that captures each packet flowing through the network, and analyzes its content.
Impersonation of a particular host
: 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 performed using a technique known as _DNS poisoning_, or via so-called _IP spoofing_. In the first case, the intruder uses a cracked DNS server to point client systems to a maliciously duplicated host. In the second case, the intruder sends falsified network packets that appear to be from a trusted host.
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\.1.2. Main Features {#s2-ssh-features}
The SSH protocol provides the following safeguards:
No one can pose as the intended server
: After an initial connection, the client can verify that it is connecting to the same server it had connected to previously.
No one can capture the authentication information
: The client transmits its authentication information to the server using strong, 128-bit encryption.
No one can intercept the communication
: All data sent and received during a session is transferred using 128-bit encryption, making intercepted transmissions extremely difficult to decrypt and read.
Additionally, it also offers the following options:
It provides secure means to use graphical applications over a network
: Using a technique called _X11 forwarding_, the client can forward _X11_ (_X Window System_) applications from the server.
It provides a way to secure otherwise insecure protocols
: The SSH protocol encrypts everything it sends and receives. 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.
It can be used to create a secure channel
: The OpenSSH server and client can be configured to create a tunnel similar to a virtual private network for traffic between server and client machines.
It supports the Kerberos authentication
: OpenSSH servers and clients can be configured to authenticate using the GSSAPI (Generic Security Services Application Program Interface) implementation of the Kerberos network authentication protocol.
### 8\.1.3. Protocol Versions {#s2-ssh-versions}
Two varieties of SSH currently exist: version 1, and newer version 2. The OpenSSH suite under Fedora uses SSH version 2, which has an enhanced key exchange algorithm not vulnerable to the known exploit in version 1. However, for compatibility reasons, the OpenSSH suite does support version 1 connections as well.
### Avoid using SSH version 1
To ensure maximum security for your connection, it is recommended that only SSH version 2-compatible servers and clients are used whenever possible.
### 8\.1.4. Event Sequence of an SSH Connection {#s2-ssh-conn}
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.
1. The transport layer of the connection between the client and remote host is encrypted using a symmetric cipher.
1. The client authenticates itself to the server.
1. The remote client interacts with the remote host over the encrypted connection.
#### 8\.1.4.1. Transport Layer {#s2-ssh-protocol-conn-transport}
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.
### Always verify the integrity of a new SSH server
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\.1.4.2. Authentication {#s2-ssh-protocol-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\.1.4.3. Channels {#s2-ssh-protocol-connection}
After a successful authentication over the SSH transport layer, multiple channels are opened via a technique called _multiplexing_[[1]](#ftn.idm92836176). 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\.2. An OpenSSH Configuration {#s1-ssh-configuration}
In order to perform tasks described in this section, you must have superuser privileges. To obtain them, log in as `root` by typing:
**su -**
### 8\.2.1. Configuration Files {#s2-ssh-configuration-configs}
There are two different sets of configuration files: those for client programs (that is, **ssh**, **scp**, and **sftp**), and those for the server (the **sshd** daemon).
System-wide SSH configuration information is stored in the `/etc/ssh/` directory. See [Table 8.1, “System-wide configuration files”](#table-ssh-configuration-configs-system "Table 8.1. System-wide configuration files") for a description of its content.
Table 8.1. System-wide configuration files
|Configuration File|Description|
|-|
|`/etc/ssh/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.|
|`/etc/ssh/ssh_config`|The default SSH client configuration file. Note that it is overridden by `~/.ssh/config` if it exists.|
|`/etc/ssh/sshd_config`|The configuration file for the **sshd** daemon.|
|`/etc/ssh/ssh_host_dsa_key`|The DSA private key used by the **sshd** daemon.|
|`/etc/ssh/ssh_host_dsa_key.pub`|The DSA public key used by the **sshd** daemon.|
|`/etc/ssh/ssh_host_key`|The RSA private key used by the **sshd** daemon for version 1 of the SSH protocol.|
|`/etc/ssh/ssh_host_key.pub`|The RSA public key used by the **sshd** daemon for version 1 of the SSH protocol.|
|`/etc/ssh/ssh_host_rsa_key`|The RSA private key used by the **sshd** daemon for version 2 of the SSH protocol.|
|`/etc/ssh/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. See [Table 8.2, “User-specific configuration files”](#table-ssh-configuration-configs-user "Table 8.2. User-specific configuration files") for a description of its content.
Table 8.2. User-specific configuration files
|Configuration File|Description|
|-|
|`~/.ssh/authorized_keys`|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.|
|`~/.ssh/id_dsa`|Contains the DSA private key of the user.|
|`~/.ssh/id_dsa.pub`|The DSA public key of the user.|
|`~/.ssh/id_rsa`|The RSA private key used by **ssh** for version 2 of the SSH protocol.|
|`~/.ssh/id_rsa.pub`|The RSA public key used by **ssh** for version 2 of the SSH protocol|
|`~/.ssh/identity`|The RSA private key used by **ssh** for version 1 of the SSH protocol.|
|`~/.ssh/identity.pub`|The RSA public key used by **ssh** for version 1 of the SSH protocol.|
|`~/.ssh/known_hosts`|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.|
See the **ssh\_config** and **sshd\_config** man pages for information concerning the various directives available in the SSH configuration files.
### 8\.2.2. Starting an OpenSSH Server {#s2-ssh-configuration-sshd}
### Make sure you have relevant packages installed
To run an OpenSSH server, you must have the openssh-server and openssh packages installed. See [Section 5.2.4, “Installing Packages”](#sec-Installing "5.2.4. Installing Packages") for more information on how to install new packages in Fedora.
To start the **sshd** daemon, type the following at a shell prompt:
**systemctl start sshd.service**
To stop the running **sshd** daemon, use the following command:
**systemctl stop sshd.service**
If you want the daemon to start automatically at the boot time, type:
**systemctl enable sshd.service**
See [Chapter 6, _Services and Daemons_](#ch-Services_and_Daemons "Chapter 6. Services and Daemons") for more information on how to configure services in Fedora.
Note that if you reinstall the system, a new set of identification keys will be created. As a result, 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.
To prevent this, you can back up the relevant files from the `/etc/ssh/` directory (see [Table 8.1, “System-wide configuration files”](#table-ssh-configuration-configs-system "Table 8.1. System-wide configuration files") for a complete list), and restore them whenever you reinstall the system.
### 8\.2.3. Requiring SSH for Remote Connections {#s2-ssh-configuration-requiring}
For SSH to be truly effective, using insecure connection protocols 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**, and **vsftpd**.
To make sure these services are not running, type the following commands at a shell prompt:
**systemctl stop telnet.service**
**systemctl stop rsh.service**
**systemctl stop rlogin.service**
**systemctl stop vsftpd.service**
To disable running these services at startup, type:
**systemctl disable telnet.service**
**systemctl disable rsh.service**
**systemctl disable rlogin.service**
**systemctl disable vsftpd.service**
See [Chapter 6, _Services and Daemons_](#ch-Services_and_Daemons "Chapter 6. Services and Daemons") for more information on how to configure services in Fedora.
### 8\.2.4. Using a Key-Based Authentication {#s2-ssh-configuration-keypairs}
To improve the system security even further, you can enforce the key-based authentication by disabling the standard password authentication. To do so, open the `/etc/ssh/sshd_config` configuration file in a text editor, and change the `PasswordAuthentication` option as follows:
PasswordAuthentication no
To be able to use **ssh**, **scp**, or **sftp** to connect to the server from a client machine, generate an authorization key pair by following the steps below. Note that keys must be generated for each user separately.
Fedora 20 uses SSH Protocol 2 and RSA keys by default (see [Section 8.1.3, “Protocol Versions”](#s2-ssh-versions "8.1.3. Protocol Versions") for more information).
### Do not generate key pairs as root
If you complete the steps as `root`, only `root` will be able to use the keys.
### Backup your ~/.ssh/ directory
If you reinstall your system and want to keep previously generated key pair, backup the `~/.ssh/` directory. After reinstalling, copy it back to your home directory. This process can be done for all users on your system, including `root`.
#### 8\.2.4.1. Generating Key Pairs {#s3-ssh-configuration-keypairs-generating}
To generate an RSA key pair for version 2 of the SSH protocol, follow these steps:
1. Generate an RSA key pair by typing the following at a shell prompt:
~]$ **ssh-keygen -t rsa**
Generating public/private rsa key pair.
Enter file in which to save the key (/home/john/.ssh/id_rsa):
1. Press **Enter** to confirm the default location (that is, `~/.ssh/id_rsa`) for the newly created key.
1. Enter a passphrase, and confirm it by entering it again when prompted to do so. For security reasons, avoid using the same password as you use to log in to your account.
After this, you will be presented with a message similar to this:
Your identification has been saved in /home/john/.ssh/id_rsa.
Your public key has been saved in /home/john/.ssh/id_rsa.pub.
The key fingerprint is:
e7:97:c7:e2:0e:f9:0e:fc:c4:d7:cb:e5:31:11:92:14 john@penguin.example.com
The key's randomart image is:
+--[ RSA 2048]----+
| E. |
| . . |
| o . |
| . .|
| S . . |
| + o o ..|
| * * +oo|
| O +..=|
| o* o.|
+-----------------+
1. Change the permissions of the `~/.ssh/` directory:
~]$ **chmod 755 ~/.ssh**
1. Copy the content of `~/.ssh/id_rsa.pub` into the `~/.ssh/authorized_keys` on the machine to which you want to connect, appending it to its end if the file already exists.
1. Change the permissions of the `~/.ssh/authorized_keys` file using the following command:
~]$ **chmod 644 ~/.ssh/authorized_keys**
To generate a DSA key pair for version 2 of the SSH protocol, follow these steps:
1. Generate a DSA key pair by typing the following at a shell prompt:
~]$ **ssh-keygen -t dsa**
Generating public/private dsa key pair.
Enter file in which to save the key (/home/john/.ssh/id_dsa):
1. Press **Enter** to confirm the default location (that is, `~/.ssh/id_dsa`) for the newly created key.
1. Enter a passphrase, and confirm it by entering it again when prompted to do so. For security reasons, avoid using the same password as you use to log in to your account.
After this, you will be presented with a message similar to this:
Your identification has been saved in /home/john/.ssh/id_dsa.
Your public key has been saved in /home/john/.ssh/id_dsa.pub.
The key fingerprint is:
81:a1:91:a8:9f:e8:c5:66:0d:54:f5:90:cc:bc:cc:27 john@penguin.example.com
The key's randomart image is:
+--[ DSA 1024]----+
| .oo*o. |
| ...o Bo |
| .. . + o. |
|. . E o |
| o..o S |
|. o= . |
|. + |
| . |
| |
+-----------------+
1. Change the permissions of the `~/.ssh/` directory:
~]$ **chmod 775 ~/.ssh**
1. Copy the content of `~/.ssh/id_dsa.pub` into the `~/.ssh/authorized_keys` on the machine to which you want to connect, appending it to its end if the file already exists.
1. Change the permissions of the `~/.ssh/authorized_keys` file using the following command:
~]$ **chmod 644 ~/.ssh/authorized_keys**
To generate an RSA key pair for version 1 of the SSH protocol, follow these steps:
1. Generate an RSA key pair by typing the following at a shell prompt:
~]$ **ssh-keygen -t rsa1**
Generating public/private rsa1 key pair.
Enter file in which to save the key (/home/john/.ssh/identity):
1. Press **Enter** to confirm the default location (that is, `~/.ssh/identity`) for the newly created key.
1. Enter a passphrase, and confirm it by entering it again when prompted to do so. For security reasons, avoid using the same password as you use to log into your account.
After this, you will be presented with a message similar to this:
Your identification has been saved in /home/john/.ssh/identity.
Your public key has been saved in /home/john/.ssh/identity.pub.
The key fingerprint is:
cb:f6:d5:cb:6e:5f:2b:28:ac:17:0c:e4:62:e4:6f:59 john@penguin.example.com
The key's randomart image is:
+--[RSA1 2048]----+
| |
| . . |
| o o |
| + o E |
| . o S |
| = + . |
| . = . o . .|
| . = o o..o|
| .o o o=o.|
+-----------------+
1. Change the permissions of the `~/.ssh/` directory:
~]$ **chmod 755 ~/.ssh**
1. Copy the content of `~/.ssh/identity.pub` into the `~/.ssh/authorized_keys` on the machine to which you want to connect, appending it to its end if the file already exists.
1. Change the permissions of the `~/.ssh/authorized_keys` file using the following command:
~]$ **chmod 644 ~/.ssh/authorized_keys**
See [Section 8.2.4.2, “Configuring ssh-agent”](#s3-ssh-configuration-keypairs-agent "8.2.4.2. Configuring ssh-agent") for information on how to set up your system to remember the passphrase.
### Never share your private key
The private key is for your personal use only, and it is important that you never give it to anyone.
#### 8\.2.4.2. Configuring ssh-agent {#s3-ssh-configuration-keypairs-agent}
To store your passphrase so that you do not have to enter it each time you initiate a connection with a remote machine, you can use the **ssh-agent** authentication agent. To save your passphrase for a certain shell prompt, use the following command:
~]$ **ssh-add**
Enter passphrase for /home/john/.ssh/id_rsa:
Note that when you log out, your passphrase will be forgotten. You must execute the command each time you log in to a virtual console or a terminal window.
## 8\.3. OpenSSH Clients {#s1-ssh-clients}
### Make sure you have relevant packages installed
To connect to an OpenSSH server from a client machine, you must have the openssh-clients and openssh packages installed. See [Section 5.2.4, “Installing Packages”](#sec-Installing "5.2.4. Installing Packages") for more information on how to install new packages in Fedora.
### 8\.3.1. Using the ssh Utility {#s2-ssh-clients-ssh}
**ssh** allows you to log in to a remote machine and execute commands there. It is a secure replacement for the **rlogin**, **rsh**, and **telnet** programs.
Similarly to **telnet**, to log in to a remote machine named `penguin.example.com`, type the following command at a shell prompt:
~]$ **ssh penguin.example.com**
This will log you in with the same username you are using on a local machine. If you want to specify a different one, use a command in the **ssh _`username`_@_`hostname`_** form. For example, to log in as `john`, type:
~]$ **ssh john@penguin.example.com**
The first time you initiate a connection, you will be presented with a message similar to this:
The authenticity of host 'penguin.example.com' can't be established.
RSA 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 confirm. You will see a notice that the server has been added to the list of known hosts, and a prompt asking for your password:
Warning: Permanently added 'penguin.example.com' (RSA) to the list of known hosts.
john@penguin.example.com's password:
### Updating the host key of an SSH server
If the SSH server's host key changes, the client notifies the user that the connection cannot proceed until the server's host key is deleted from the `~/.ssh/known_hosts` file. To do so, open the file in a text editor, and remove a line containing the remote machine name at the beginning. Before doing this, however, contact the system administrator of the SSH server to verify the server is not compromised.
After entering the password, you will be provided with a shell prompt for the remote machine.
Alternatively, the **ssh** program can be used to execute a command on the remote machine without logging in to a shell prompt. The syntax for that is **ssh [_`username`_@]_`hostname`_ _`command`_**. For example, if you want to execute the **whoami** command on `penguin.example.com`, type:
~]$ **ssh john@penguin.example.com whoami**
john@penguin.example.com's password:
john
After you enter the correct password, the username will be displayed, and you will return to your local shell prompt.
### 8\.3.2. Using the **scp** Utility {#s2-ssh-clients-scp}
**scp** can be used to transfer files between machines over a secure, encrypted connection. In its design, it is very similar to **rcp**.
To transfer a local file to a remote system, use a command in the following form:
**scp _`localfile`_ _`username`_@_`hostname`_:_`remotefile`_**
For example, if you want to transfer `taglist.vim` to a remote machine named `penguin.example.com`, type the following at a shell prompt:
~]$ **scp taglist.vim john@penguin.example.com:.vim/plugin/taglist.vim**
john@penguin.example.com's password:
taglist.vim 100% 144KB 144.5KB/s 00:00
Multiple files can be specified at once. To transfer the contents of `.vim/plugin/` to the same directory on the remote machine `penguin.example.com`, type the following command:
~]$ **scp .vim/plugin/* john@penguin.example.com:.vim/plugin/**
john@penguin.example.com's password:
closetag.vim 100% 13KB 12.6KB/s 00:00
snippetsEmu.vim 100% 33KB 33.1KB/s 00:00
taglist.vim 100% 144KB 144.5KB/s 00:00
To transfer a remote file to the local system, use the following syntax:
**scp _`username`_@_`hostname`_:_`remotefile`_ _`localfile`_**
For instance, to download the `.vimrc` configuration file from the remote machine, type:
~]$ **scp john@penguin.example.com:.vimrc .vimrc**
john@penguin.example.com's password:
.vimrc 100% 2233 2.2KB/s 00:00
### 8\.3.3. Using the **sftp** Utility {#s2-ssh-clients-sftp}
The **sftp** utility can be used to open a secure, interactive FTP session. In its design, it is similar to **ftp** except that it uses a secure, encrypted connection.
To connect to a remote system, use a command in the following form:
**sftp _`username`_@_`hostname`_**
For example, to log in to a remote machine named `penguin.example.com` with `john` as a username, type:
~]$ **sftp john@penguin.example.com**
john@penguin.example.com's password:
Connected to penguin.example.com.
sftp>
After you enter the correct password, you will be presented with a prompt. The **sftp** utility accepts a set of commands similar to those used by **ftp** (see [Table 8.3, “A selection of available sftp commands”](#table-ssh-clients-sftp "Table 8.3. A selection of available sftp commands")).
Table 8.3. A selection of available sftp commands
|Command|Description|
|-|
|**ls** [_`directory`_]|List the content of a remote _`directory`_. If none is supplied, a current working directory is used by default.|
|**cd** _`directory`_|Change the remote working directory to _`directory`_.|
|**mkdir** _`directory`_|Create a remote _`directory`_.|
|**rmdir** _`path`_|Remove a remote _`directory`_.|
|**put** _`localfile`_ [_`remotefile`_]|Transfer _`localfile`_ to a remote machine.|
|**get** _`remotefile`_ [_`localfile`_]|Transfer _`remotefile`_ from a remote machine.|
For a complete list of available commands, refer to the **sftp** man page.
## 8\.4. More Than a Secure Shell {#s1-ssh-beyondshell}
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\.4.1. X11 Forwarding {#s2-ssh-beyondshell-x11}
To open an X11 session over an SSH connection, use a command in the following form:
**ssh -Y _`username`_@_`hostname`_**
For example, to log in to a remote machine named `penguin.example.com` with `john` as a username, type:
~]$ **ssh -Y john@penguin.example.com**
john@penguin.example.com's password:
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 utility. To do this, connect to the server using ssh and type:
~]$ **system-config-printer &**
The Printer Configuration Tool will appear, allowing the remote user to safely configure printing on the remote system.
### 8\.4.2. Port Forwarding {#s2-ssh-beyondshell-tcpip}
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.
### Using reserved port numbers
Setting up port forwarding to listen on ports below 1024 requires root level access.
To create a TCP/IP port forwarding channel which listens for connections on the `localhost`, use a command in the following form:
**ssh -L _`local-port`_:_`remote-hostname`_:_`remote-port`_ _`username`_@_`hostname`_**
For example, 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 email. Any requests sent to port `1100` on the client system will be 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 email. Note that 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 (that is, 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.
### A connection is only as secure as a client system
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\.5. Additional Resources {#s1-openssh-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\.5.1. Installed Documentation {#s2-openssh-installed-docs}
**man ssh**
: The manual page for ssh containing the full documentation on its usage.
**man scp**
: The manual page for scp containing the full documentation on its usage.
**man sftp**
: The manual page for sftp containing the full documentation on its usage.
**man sshd**
: The manual page for sshd containing the full documentation on its usage.
**man ssh-keygen**
: The manual page for ssh-keygen containing the full documentation on its usage.
**man ssh\_config**
: The manual page with full description of available SSH client configuration options.
**man sshd\_config**
: The manual page with full description of available SSH daemon configuration options.
### 8\.5.2. Useful Websites {#s2-openssh-useful-websites}
: The OpenSSH home page containing further documentation, frequently asked questions, links to the mailing lists, bug reports, and other useful resources.
: The OpenSSL home page containing further documentation, frequently asked questions, links to the mailing lists, and other useful resources.
: Another implementation of an SSH server.
----
[[1] ](#idm92836176) 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.
# Part IV. Servers {#part-Servers}
This part discusses various topics related to servers such as how to set up a Web server or share files and directories over the network.
## Chapter 9. Web Servers {#ch-Web_Servers}
`HTTP` (Hypertext Transfer Protocol) server, or a _web server_, is a network service that serves content to a client over the web. This typically means web pages, but any other documents can be served as well.
## 9\.1. The Apache HTTP Server {#s1-The_Apache_HTTP_Server}
The web server available in Fedora 20 is the Apache HTTP server daemon, `httpd`, an open source web server developed by the [Apache Software Foundation](http://www.apache.org/). In Fedora 20 the Apache server has been updated to Apache HTTP Server 2.4. This section describes the basic configuration of the `httpd` service, and covers some advanced topics such as adding server modules, setting up virtual hosts, or configuring the secure HTTP server.
There are important differences between the Apache HTTP Server 2.4 and version 2.2, and if you are upgrading from a previous release of Fedora, you will need to update the `httpd` service configuration accordingly. This section reviews some of the newly added features, outlines important changes, and guides you through the update of older configuration files.
### 9\.1.1. Notable Changes {#s2-apache-changes}
The Apache HTTP Server version 2.4 has the following changes:
httpd Service Control
: With the migration away from SysV init scripts, server administrators should switch to using the **apachectl** and **systemctl** commands to control the service, in place of the **service** command. The following examples are specific to the `httpd` service. The command:
service httpd graceful
is replaced by
apachectl graceful
The command:
service httpd configtest
is replaced by
apachectl configtest
The `systemd` unit file for `httpd` has different behavior from the init script as follows:
* A graceful restart is used by default when the service is reloaded.
* A graceful stop is used by default when the service is stopped.
Private /tmp
: To enhance system security, the `systemd` unit file runs the `httpd` daemon using a private `/tmp` directory, separate to the system `/tmp` directory.
Configuration Layout
: Configuration files which load modules are now placed in the `/etc/httpd/conf.modules.d` directory. Packages, such as php, which provide additional loadable modules for `httpd` will place a file in this directory. Any configuration files in the `conf.modules.d` are processed before the main body of `httpd.conf`. Configuration files in the `/etc/httpd/conf.d` directory are now processed after the main body of `httpd.conf`.
Some additional configuration files are provided by the httpd package itself:
* /etc/httpd/conf.d/autoindex.conf
This configures mod\_autoindex directory indexing.
* /etc/httpd/conf.d/userdir.conf
This configures access to user directories, for example, `http://example.com/~username/`; such access is disabled by default for security reasons.
* /etc/httpd/conf.d/welcome.conf
As in previous releases, this configures the welcome page displayed for `http://localhost/` when no content is present.
Default Configuration
: A minimal default `httpd.conf` is now provided by default. Many common configuration settings, such as `Timeout` or `KeepAlive` are no longer explicitly configured in the default configuration; hard-coded settings will be used instead, by default. The hard-coded default settings for all configuration directives are specified in the manual. See [Section 9.1.8.1, “Installed Documentation”](#s3-apache-resources-installed "9.1.8.1. Installed Documentation") for more information.
Configuration Changes
: A number of backwards-incompatible changes to the `httpd` configuration syntax were made which will require changes if migrating an existing configuration from httpd 2.2 to httpd 2.4. See the following Apache document for more information on upgrading
Processing Model
: In previous releases of Fedora, different _multi-processing models_ (MPM) were made available as different `httpd` binaries: the forked model, “prefork”, as `/usr/sbin/httpd`, and the thread-based model “worker” as `/usr/sbin/httpd.worker`.
In Fedora 20, only a single `httpd` binary is used, and three MPMs are available as loadable modules: worker, prefork (default), and event. The configuration file `/etc/httpd/conf.modules.d/00-mpm.conf` can be changed to select which of the three MPM modules is loaded.
Packaging Changes
: The LDAP authentication and authorization modules are now provided in a separate sub-package mod\_ldap. The new module mod\_session and associated helper modules are provided in a new sub-package, mod\_session. The new modules mod\_proxy\_html and mod\_xml2enc are provided in a new sub-package, mod\_proxy\_html.
Packaging Filesystem Layout
: The `/var/cache/mod_proxy` directory is no longer provided; instead, the `/var/cache/httpd/` directory is packaged with a `proxy` and `ssl` subdirectory.
Packaged content provided with `httpd` has been moved from `/var/www/` to `/usr/share/httpd/`:
* /usr/share/httpd/icons/
The `/var/www/icons/` has moved to `/usr/share/httpd/icons`. This directory contains a set of icons used with directory indices. Available at `http://localhost/icons/` in the default configuration, via `/etc/httpd/conf.d/autoindex.conf`.
* /usr/share/httpd/manual/
The `/var/www/manual/` has moved to `/usr/share/httpd/manual/`. This directory, contained in the httpd-manual package, contains the HTML version of the manual for `httpd`. Available at `http://localhost/manual/` if the package is installed, via `/etc/httpd/conf.d/manual.conf`.
* /usr/share/httpd/error/
The `/var/www/error/` has moved to `/usr/share/httpd/error/`. Custom multi-language HTTP error pages. Not configured by default, the example configuration file is provided at ``/usr/share/doc/httpd-_`VERSION`_/httpd-multilang-errordoc.conf``.
Authentication, Authorization and Access Control
: The configuration directives used to control authentication, authorization and access control have changed significantly. Existing configuration files using the `Order`, `Deny` and `Allow` directives should be adapted to use the new `Require` syntax. See the following Apache document for more information
suexec
: To improve system security, the suexec binary is no longer installed `setuid root`; instead, it has file system capability bits set which allow a more restrictive set of permissions. In conjunction with this change, the suexec binary no longer uses the `/var/log/httpd/suexec.log` logfile. Instead, log messages are sent to syslog; by default these will appear in the `/var/log/secure` log file.
Module Interface
: Due to changes to the `httpd` module interface, httpd 2.4 is not compatible with third-party binary modules built against httpd 2.2. Such modules will need to be adjusted as necessary for the httpd 2.4 module interface, and then rebuilt. A detailed list of the API changes in version `2.4` is available here: [http://httpd.apache.org/docs/2.4/developer/new\_api\_2\_4.html](http://httpd.apache.org/docs/2.4/developer/new_api_2_4.html).
The apxs binary used to build modules from source has moved from `/usr/sbin/apxs` to `/usr/bin/apxs`.
Removed modules
: List of `httpd` modules removed in Fedora 20:
mod\_auth\_mysql, mod\_auth\_pgsql
: httpd 2.4 provides SQL database authentication support internally in the mod\_authn\_dbd module.
mod\_perl
: mod\_perl is not officially supported with httpd 2.4 by upstream.
mod\_authz\_ldap
: httpd 2.4 provides LDAP support internally using mod\_authnz\_ldap.
### 9\.1.2. Updating the Configuration {#s2-apache-version2-migrating}
To update the configuration files from the Apache HTTP Server version 2.2, take the following steps:
1. Make sure all module names are correct, since they may have changed. Adjust the `LoadModule` directive for each module that has been renamed.
1. Recompile all third party modules before attempting to load them. This typically means authentication and authorization modules.
1. If you use the `mod_userdir` module, make sure the `UserDir` directive indicating a directory name (typically `public_html`) is provided.
1. If you use the Apache HTTP Secure Server, edit the `/etc/httpd/conf.d/ssl.conf` to enable the Secure Sockets Layer (SSL) protocol.
Note that you can check the configuration for possible errors by using the following command:
~]# **apachectl configtest**
Syntax OK
For more information on upgrading the Apache HTTP Server configuration from version 2.2 to 2.4, see .
### 9\.1.3. Running the httpd Service {#s2-apache-running}
This section describes how to start, stop, restart, and check the current status of the Apache HTTP Server. To be able to use the `httpd` service, make sure you have the httpd installed. You can do so by using the following command:
~]# **yum install httpd**
For more information on the concept of targets and how to manage system services in Fedora in general, see [Chapter 6, _Services and Daemons_](#ch-Services_and_Daemons "Chapter 6. Services and Daemons").
#### 9\.1.3.1. Starting the Service {#s3-apache-running-starting}
To run the `httpd` service, type the following at a shell prompt as `root`:
~]# **systemctl start httpd.service**
If you want the service to start automatically at the boot time, use the following command:
~]# **systemctl enable httpd.service**
ln -s '/usr/lib/systemd/system/httpd.service' '/etc/systemd/system/multi-user.target.wants/httpd.service'
### Using the secure server
If running the Apache HTTP Server as a secure server, a password may be required after the machine boots if using an encrypted private SSL key.
#### 9\.1.3.2. Stopping the Service {#s3-apache-running-stopping}
To stop the running `httpd` service, type the following at a shell prompt as `root`:
~]# **systemctl stop httpd.service**
To prevent the service from starting automatically at the boot time, type:
~]# **systemctl disable httpd.service**
rm '/etc/systemd/system/multi-user.target.wants/httpd.service'
#### 9\.1.3.3. Restarting the Service {#s3-apache-running-restarting}
There are three different ways to restart a running `httpd` service:
1. To restart the service completely, type the following at a shell prompt as `root`:
~]# **systemctl restart httpd.service**
This stops the running `httpd` service and immediately starts it again. Use this command after installing or removing a dynamically loaded module such as PHP.
1. To only reload the configuration, as `root`, type:
~]# **systemctl reload httpd.service**
This causes the running `httpd` service to reload its configuration file. Any requests being currently processed will be interrupted, which may cause a client browser to display an error message or render a partial page.
1. To reload the configuration without affecting active requests, run the following command as `root`:
~]# **service httpd graceful**
This cause the running `httpd` service to reload its configuration file. Any requests being currently processed will use the old configuration.
#### 9\.1.3.4. Verifying the Service Status {#s3-apache-running-status}
To verify that the `httpd` service is running, type the following at a shell prompt:
~]# **systemctl is-active httpd.service**
active
### 9\.1.4. Editing the Configuration Files {#s2-apache-editing}
When the `httpd` service is started, by default, it reads the configuration from locations that are listed in [Table 9.1, “The httpd service configuration files”](#table-apache-editing-files "Table 9.1. The httpd service configuration files").
Table 9.1. The httpd service configuration files
|Path|Description|
|-|
|`/etc/httpd/conf/httpd.conf`|The main configuration file.|
|`/etc/httpd/conf.d/`|An auxiliary directory for configuration files that are included in the main configuration file.|
Although the default configuration should be suitable for most situations, it is a good idea to become at least familiar with some of the more important configuration options. Note that for any changes to take effect, the web server has to be restarted first. See [Section 9.1.3.3, “Restarting the Service”](#s3-apache-running-restarting "9.1.3.3. Restarting the Service") for more information on how to restart the `httpd` service.
To check the configuration for possible errors, type the following at a shell prompt:
~]# **apachectl configtest**
Syntax OK
To make the recovery from mistakes easier, it is recommended that you make a copy of the original file before editing it.
#### 9\.1.4.1. Common httpd.conf Directives {#s3-apache-httpdconf-directives}
The following directives are commonly used in the `/etc/httpd/conf/httpd.conf` configuration file:
``
: The `` directive allows you to apply certain directives to a particular directory only. It takes the following form:
<Directory _`directory`_>
_`directive`_
…
</Directory>
The _`directory`_ can be either a full path to an existing directory in the local file system, or a wildcard expression.
This directive can be used to configure additional `cgi-bin` directories for server-side scripts located outside the directory that is specified by `ScriptAlias`. In this case, the `ExecCGI` and `AddHandler` directives must be supplied, and the permissions on the target directory must be set correctly (that is, `0755`).
Example 9.1. Using the <Directory> directive
<Directory /var/www/html>
Options Indexes FollowSymLinks
AllowOverride None
Order allow,deny
Allow from all
</Directory>
``
: The `IfDefine` directive allows you to use certain directives only when a particular parameter is supplied on the command line. It takes the following form:
<IfDefine [!]_`parameter`_>
_`directive`_
…
</IfDefine>
The _`parameter`_ can be supplied at a shell prompt using the `-D`_`parameter`_ command line option (for example, **httpd -DEnableHome**). If the optional exclamation mark (that is, `!`) is present, the enclosed directives are used only when the parameter is _not_ specified.
Example 9.2. Using the <IfDefine> directive
<IfDefine EnableHome>
UserDir public_html
</IfDefine>
``
: The `` directive allows you to use certain directive only when a particular module is loaded. It takes the following form:
<IfModule [!]_`module`_>
_`directive`_
…
</IfModule>
The _`module`_ can be identified either by its name, or by the file name. If the optional exclamation mark (that is, `!`) is present, the enclosed directives are used only when the module is _not_ loaded.
Example 9.3. Using the <IfModule> directive
<IfModule mod_disk_cache.c>
CacheEnable disk /
CacheRoot /var/cache/mod_proxy
</IfModule>
``
: The `` directive allows you to apply certain directives to a particular URL only. It takes the following form:
<Location _`url`_>
_`directive`_
…
</Location>
The _`url`_ can be either a path relative to the directory specified by the `DocumentRoot` directive (for example, `/server-info`), or an external URL such as `http://example.com/server-info`.
Example 9.4. Using the <Location> directive
<Location /server-info>
SetHandler server-info
Order deny,allow
Deny from all
Allow from .example.com
</Location>
``
: The `` directive allows you to apply certain directives to the proxy server only. It takes the following form:
<Proxy _`pattern`_>
_`directive`_
…
</Proxy>
The _`pattern`_ can be an external URL, or a wildcard expression (for example, `http://example.com/*`).
Example 9.5. Using the <Proxy> directive
<Proxy *>
Order deny,allow
Deny from all
Allow from .example.com
</Proxy>
``
: The `` directive allows you apply certain directives to particular virtual hosts only. It takes the following form:
<VirtualHost _`address`_[:_`port`_]…>
_`directive`_
…
</VirtualHost>
The _`address`_ can be an IP address, a fully qualified domain name, or a special form as described in [Table 9.2, “Available <VirtualHost> options”](#table-apache-httpdconf-virtualhost "Table 9.2. Available options").
Table 9.2. Available <VirtualHost> options
|Option|Description|
|-|
|`*`|Represents all IP addresses.|
|`_default_`|Represents unmatched IP addresses.|
Example 9.6. Using the <VirtualHost> directive
<VirtualHost *:80>
ServerAdmin webmaster@penguin.example.com
DocumentRoot /www/docs/penguin.example.com
ServerName penguin.example.com
ErrorLog logs/penguin.example.com-error_log
CustomLog logs/penguin.example.com-access_log common
</VirtualHost>
`AccessFileName`
: The `AccessFileName` directive allows you to specify the file to be used to customize access control information for each directory. It takes the following form:
AccessFileName _`filename`_…
The _`filename`_ is a name of the file to look for in the requested directory. By default, the server looks for `.htaccess`.
For security reasons, the directive is typically followed by the `Files` tag to prevent the files beginning with `.ht` from being accessed by web clients. This includes the `.htaccess` and `.htpasswd` files.
Example 9.7. Using the AccessFileName directive
AccessFileName .htaccess
<Files ~ "^\.ht">
Order allow,deny
Deny from all
Satisfy All
</Files>
`Action`
: The `Action` directive allows you to specify a CGI script to be executed when a certain media type is requested. It takes the following form:
Action _`content-type`_ _`path`_
The _`content-type`_ has to be a valid MIME type such as `text/html`, `image/png`, or `application/pdf`. The _`path`_ refers to an existing CGI script, and must be relative to the directory specified by the `DocumentRoot` directive (for example, `/cgi-bin/process-image.cgi`).
Example 9.8. Using the Action directive
Action image/png /cgi-bin/process-image.cgi
`AddDescription`
: The `AddDescription` directive allows you to specify a short description to be displayed in server-generated directory listings for a given file. It takes the following form:
AddDescription "_`description`_" _`filename`_…
The _`description`_ should be a short text enclosed in double quotes (that is, `"`). The _`filename`_ can be a full file name, a file extension, or a wildcard expression.
Example 9.9. Using the AddDescription directive
AddDescription "GZIP compressed tar archive" .tgz
`AddEncoding`
: The `AddEncoding` directive allows you to specify an encoding type for a particular file extension. It takes the following form:
AddEncoding _`encoding`_ _`extension`_…
The _`encoding`_ has to be a valid MIME encoding such as `x-compress`, `x-gzip`, etc. The _`extension`_ is a case sensitive file extension, and is conventionally written with a leading dot (for example, `.gz`).
This directive is typically used to instruct web browsers to decompress certain file types as they are downloaded.
Example 9.10. Using the AddEncoding directive
AddEncoding x-gzip .gz .tgz
`AddHandler`
: The `AddHandler` directive allows you to map certain file extensions to a selected handler. It takes the following form:
AddHandler _`handler`_ _`extension`_…
The _`handler`_ has to be a name of previously defined handler. The _`extension`_ is a case sensitive file extension, and is conventionally written with a leading dot (for example, `.cgi`).
This directive is typically used to treat files with the `.cgi` extension as CGI scripts regardless of the directory they are in. Additionally, it is also commonly used to process server-parsed HTML and image-map files.
Example 9.11. Using the AddHandler option
AddHandler cgi-script .cgi
`AddIcon`
: The `AddIcon` directive allows you to specify an icon to be displayed for a particular file in server-generated directory listings. It takes the following form:
AddIcon _`path`_ _`pattern`_…
The _`path`_ refers to an existing icon file, and must be relative to the directory specified by the `DocumentRoot` directive (for example, `/icons/folder.png`). The _`pattern`_ can be a file name, a file extension, a wildcard expression, or a special form as described in the following table:
Table 9.3. Available AddIcon options
|Option|Description|
|-|
|`^^DIRECTORY^^`|Represents a directory.|
|`^^BLANKICON^^`|Represents a blank line.|
Example 9.12. Using the AddIcon directive
AddIcon /icons/text.png .txt README
`AddIconByEncoding`
: The `AddIconByEncoding` directive allows you to specify an icon to be displayed for a particular encoding type in server-generated directory listings. It takes the following form:
AddIconByEncoding _`path`_ _`encoding`_…
The _`path`_ refers to an existing icon file, and must be relative to the directory specified by the `DocumentRoot` directive (for example, `/icons/compressed.png`). The _`encoding`_ has to be a valid MIME encoding such as `x-compress`, `x-gzip`, etc.
Example 9.13. Using the AddIconByEncoding directive
AddIconByEncoding /icons/compressed.png x-compress x-gzip
`AddIconByType`
: The `AddIconByType` directive allows you to specify an icon to be displayed for a particular media type in server-generated directory listings. It takes the following form:
AddIconByType _`path`_ _`content-type`_…
The _`path`_ refers to an existing icon file, and must be relative to the directory specified by the `DocumentRoot` directive (for example, `/icons/text.png`). The _`content-type`_ has to be either a valid MIME type (for example, `text/html` or `image/png`), or a wildcard expression such as `text/*`, `image/*`, etc.
Example 9.14. Using the AddIconByType directive
AddIconByType /icons/video.png video/*
`AddLanguage`
: The `AddLanguage` directive allows you to associate a file extension with a specific language. It takes the following form:
AddLanguage _`language`_ _`extension`_…
The _`language`_ has to be a valid MIME language such as `cs`, `en`, or `fr`. The _`extension`_ is a case sensitive file extension, and is conventionally written with a leading dot (for example, `.cs`).
This directive is especially useful for web servers that serve content in multiple languages based on the client's language settings.
Example 9.15. Using the AddLanguage directive
AddLanguage cs .cs .cz
`AddType`
: The `AddType` directive allows you to define or override the media type for a particular file extension. It takes the following form:
AddType _`content-type`_ _`extension`_…
The _`content-type`_ has to be a valid MIME type such as `text/html`, `image/png`, etc. The _`extension`_ is a case sensitive file extension, and is conventionally written with a leading dot (for example, `.cs`).
Example 9.16. Using the AddType directive
AddType application/x-gzip .gz .tgz
`Alias`
: The `Alias` directive allows you to refer to files and directories outside the default directory specified by the `DocumentRoot` directive. It takes the following form:
Alias _`url-path`_ _`real-path`_
The _`url-path`_ must be relative to the directory specified by the `DocumentRoot` directive (for example, `/images/`). The _`real-path`_ is a full path to a file or directory in the local file system.
This directive is typically followed by the `Directory` tag with additional permissions to access the target directory. By default, the `/icons/` alias is created so that the icons from `/var/www/icons/` are displayed in server-generated directory listings.
Example 9.17. Using the Alias directive
Alias /icons/ /var/www/icons/
<Directory "/var/www/icons">
Options Indexes MultiViews FollowSymLinks
AllowOverride None
Order allow,deny
Allow from all
<Directory>
`Allow`
: The `Allow` directive allows you to specify which clients have permission to access a given directory. It takes the following form:
Allow from _`client`_…
The _`client`_ can be a domain name, an IP address (both full and partial), a _`network`_/_`netmask`_ pair, or `all` for all clients.
Example 9.18. Using the Allow directive
Allow from 192.168.1.0/255.255.255.0
`AllowOverride`
: The `AllowOverride` directive allows you to specify which directives in a `.htaccess` file can override the default configuration. It takes the following form:
AllowOverride _`type`_…
The _`type`_ has to be one of the available grouping options as described in [Table 9.4, “Available AllowOverride options”](#table-apache-httpdconf-allowoverride "Table 9.4. Available AllowOverride options").
Table 9.4. Available AllowOverride options
|Option|Description|
|-|
|`All`|All directives in `.htaccess` are allowed to override earlier configuration settings.|
|`None`|No directive in `.htaccess` is allowed to override earlier configuration settings.|
|`AuthConfig`|Allows the use of authorization directives such as `AuthName`, `AuthType`, or `Require`.|
|`FileInfo`|Allows the use of file type, metadata, and `mod_rewrite` directives such as `DefaultType`, `RequestHeader`, or `RewriteEngine`, as well as the `Action` directive.|
|`Indexes`|Allows the use of directory indexing directives such as `AddDescription`, `AddIcon`, or `FancyIndexing`.|
|`Limit`|Allows the use of host access directives, that is, `Allow`, `Deny`, and `Order`.|
|`Options`[=_`option`_,…]|Allows the use of the `Options` directive. Additionally, you can provide a comma-separated list of options to customize which options can be set using this directive.|
Example 9.19. Using the AllowOverride directive
AllowOverride FileInfo AuthConfig Limit
`BrowserMatch`
: The `BrowserMatch` directive allows you to modify the server behavior based on the client's web browser type. It takes the following form:
BrowserMatch _`pattern`_ _`variable`_…
The _`pattern`_ is a regular expression to match the User-Agent HTTP header field. The _`variable`_ is an environment variable that is set when the header field matches the pattern.
By default, this directive is used to deny connections to specific browsers with known issues, and to disable keepalives and HTTP header flushes for browsers that are known to have problems with these actions.
Example 9.20. Using the BrowserMatch directive
BrowserMatch "Mozilla/2" nokeepalive
`CacheDefaultExpire`
: The `CacheDefaultExpire` option allows you to set how long to cache a document that does not have any expiration date or the date of its last modification specified. It takes the following form:
CacheDefaultExpire _`time`_
The _`time`_ is specified in seconds. The default option is `3600` (that is, one hour).
Example 9.21. Using the CacheDefaultExpire directive
CacheDefaultExpire 3600
`CacheDisable`
: The `CacheDisable` directive allows you to disable caching of certain URLs. It takes the following form:
CacheDisable _`path`_
The _`path`_ must be relative to the directory specified by the `DocumentRoot` directive (for example, `/files/`).
Example 9.22. Using the CacheDisable directive
CacheDisable /temporary
`CacheEnable`
: The `CacheEnable` directive allows you to specify a cache type to be used for certain URLs. It takes the following form:
CacheEnable _`type`_ _`url`_
The _`type`_ has to be a valid cache type as described in [Table 9.5, “Available cache types”](#table-apache-httpdconf-cacheenable "Table 9.5. Available cache types"). The _`url`_ can be a path relative to the directory specified by the `DocumentRoot` directive (for example, `/images/`), a protocol (for example, `ftp://`), or an external URL such as `http://example.com/`.
Table 9.5. Available cache types
|Type|Description|
|-|
|`mem`|The memory-based storage manager.|
|`disk`|The disk-based storage manager.|
|`fd`|The file descriptor cache.|
Example 9.23. Using the CacheEnable directive
CacheEnable disk /
`CacheLastModifiedFactor`
: The `CacheLastModifiedFactor` directive allows you to customize how long to cache a document that does not have any expiration date specified, but that provides information about the date of its last modification. It takes the following form:
CacheLastModifiedFactor _`number`_
The _`number`_ is a coefficient to be used to multiply the time that passed since the last modification of the document. The default option is `0.1` (that is, one tenth).
Example 9.24. Using the CacheLastModifiedFactor directive
CacheLastModifiedFactor 0.1
`CacheMaxExpire`
: The `CacheMaxExpire` directive allows you to specify the maximum amount of time to cache a document. It takes the following form:
CacheMaxExpire _`time`_
The _`time`_ is specified in seconds. The default option is `86400` (that is, one day).
Example 9.25. Using the CacheMaxExpire directive
CacheMaxExpire 86400
`CacheNegotiatedDocs`
: The `CacheNegotiatedDocs` directive allows you to enable caching of the documents that were negotiated on the basis of content. It takes the following form:
CacheNegotiatedDocs _`option`_
The _`option`_ has to be a valid keyword as described in [Table 9.6, “Available CacheNegotiatedDocs options”](#table-apache-httpdconf-cachenegotiateddocs "Table 9.6. Available CacheNegotiatedDocs options"). Since the content-negotiated documents may change over time or because of the input from the requester, the default option is `Off`.
Table 9.6. Available CacheNegotiatedDocs options
|Option|Description|
|-|
|`On`|Enables caching the content-negotiated documents.|
|`Off`|Disables caching the content-negotiated documents.|
Example 9.26. Using the CacheNegotiatedDocs directive
CacheNegotiatedDocs On
`CacheRoot`
: The `CacheRoot` directive allows you to specify the directory to store cache files in. It takes the following form:
CacheRoot _`directory`_
The _`directory`_ must be a full path to an existing directory in the local file system. The default option is `/var/cache/mod_proxy/`.
Example 9.27. Using the CacheRoot directive
CacheRoot /var/cache/mod_proxy
`CustomLog`
: The `CustomLog` directive allows you to specify the log file name and the log file format. It takes the following form:
CustomLog _`path`_ _`format`_
The _`path`_ refers to a log file, and must be relative to the directory that is specified by the `ServerRoot` directive (that is, `/etc/httpd/` by default). The _`format`_ has to be either an explicit format string, or a format name that was previously defined using the `LogFormat` directive.
Example 9.28. Using the CustomLog directive
CustomLog logs/access_log combined
`DefaultIcon`
: The `DefaultIcon` directive allows you to specify an icon to be displayed for a file in server-generated directory listings when no other icon is associated with it. It takes the following form:
DefaultIcon _`path`_
The _`path`_ refers to an existing icon file, and must be relative to the directory specified by the `DocumentRoot` directive (for example, `/icons/unknown.png`).
Example 9.29. Using the DefaultIcon directive
DefaultIcon /icons/unknown.png
`DefaultType`
: The `DefaultType` directive allows you to specify a media type to be used in case the proper MIME type cannot be determined by the server. It takes the following form:
DefaultType _`content-type`_
The _`content-type`_ has to be a valid MIME type such as `text/html`, `image/png`, `application/pdf`, etc.
Example 9.30. Using the DefaultType directive
DefaultType text/plain
`Deny`
: The `Deny` directive allows you to specify which clients are denied access to a given directory. It takes the following form:
Deny from _`client`_…
The _`client`_ can be a domain name, an IP address (both full and partial), a _`network`_/_`netmask`_ pair, or `all` for all clients.
Example 9.31. Using the Deny directive
Deny from 192.168.1.1
`DirectoryIndex`
: The `DirectoryIndex` directive allows you to specify a document to be served to a client when a directory is requested (that is, when the URL ends with the `/` character). It takes the following form:
DirectoryIndex _`filename`_…
The _`filename`_ is a name of the file to look for in the requested directory. By default, the server looks for `index.html`, and `index.html.var`.
Example 9.32. Using the DirectoryIndex directive
DirectoryIndex index.html index.html.var
`DocumentRoot`
: The `DocumentRoot` directive allows you to specify the main directory from which the content is served. It takes the following form:
DocumentRoot _`directory`_
The _`directory`_ must be a full path to an existing directory in the local file system. The default option is `/var/www/html/`.
Example 9.33. Using the DocumentRoot directive
DocumentRoot /var/www/html
`ErrorDocument`
: The `ErrorDocument` directive allows you to specify a document or a message to be displayed as a response to a particular error. It takes the following form:
ErrorDocument _`error-code`_ _`action`_
The _`error-code`_ has to be a valid code such as `403` (Forbidden), `404` (Not Found), or `500` (Internal Server Error). The _`action`_ can be either a URL (both local and external), or a message string enclosed in double quotes (that is, `"`).
Example 9.34. Using the ErrorDocument directive
ErrorDocument 403 "Access Denied"
ErrorDocument 404 /404-not_found.html
`ErrorLog`
: The `ErrorLog` directive allows you to specify a file to which the server errors are logged. It takes the following form:
ErrorLog _`path`_
The _`path`_ refers to a log file, and can be either absolute, or relative to the directory that is specified by the `ServerRoot` directive (that is, `/etc/httpd/` by default). The default option is `logs/error_log`
Example 9.35. Using the ErrorLog directive
ErrorLog logs/error_log
`ExtendedStatus`
: The `ExtendedStatus` directive allows you to enable detailed server status information. It takes the following form:
ExtendedStatus _`option`_
The _`option`_ has to be a valid keyword as described in [Table 9.7, “Available ExtendedStatus options”](#table-apache-httpdconf-extendedstatus "Table 9.7. Available ExtendedStatus options"). The default option is `Off`.
Table 9.7. Available ExtendedStatus options
|Option|Description|
|-|
|`On`|Enables generating the detailed server status.|
|`Off`|Disables generating the detailed server status.|
Example 9.36. Using the ExtendedStatus directive
ExtendedStatus On
`Group`
: The `Group` directive allows you to specify the group under which the `httpd` service will run. It takes the following form:
Group _`group`_
The _`group`_ has to be an existing UNIX group. The default option is `apache`.
Note that `Group` is no longer supported inside ``, and has been replaced by the `SuexecUserGroup` directive.
Example 9.37. Using the Group directive
Group apache
`HeaderName`
: The `HeaderName` directive allows you to specify a file to be prepended to the beginning of the server-generated directory listing. It takes the following form:
HeaderName _`filename`_
The _`filename`_ is a name of the file to look for in the requested directory. By default, the server looks for `HEADER.html`.
Example 9.38. Using the HeaderName directive
HeaderName HEADER.html
`HostnameLookups`
: The `HostnameLookups` directive allows you to enable automatic resolving of IP addresses. It takes the following form:
HostnameLookups _`option`_
The _`option`_ has to be a valid keyword as described in [Table 9.8, “Available HostnameLookups options”](#table-apache-httpdconf-hostnamelookup "Table 9.8. Available HostnameLookups options"). To conserve resources on the server, the default option is `Off`.
Table 9.8. Available HostnameLookups options
|Option|Description|
|-|
|`On`|Enables resolving the IP address for each connection so that the hostname can be logged. However, this also adds a significant processing overhead.|
|`Double`|Enables performing the double-reverse DNS lookup. In comparison to the above option, this adds even more processing overhead.|
|`Off`|Disables resolving the IP address for each connection.|
Note that when the presence of hostnames is required in server log files, it is often possible to use one of the many log analyzer tools that perform the DNS lookups more efficiently.
Example 9.39. Using the HostnameLookups directive
HostnameLookups Off
`Include`
: The `Include` directive allows you to include other configuration files. It takes the following form:
Include _`filename`_
The `filename` can be an absolute path, a path relative to the directory specified by the `ServerRoot` directive, or a wildcard expression. All configuration files from the `/etc/httpd/conf.d/` directory are loaded by default.
Example 9.40. Using the Include directive
Include conf.d/*.conf
`IndexIgnore`
: The `IndexIgnore` directive allows you to specify a list of file names to be omitted from the server-generated directory listings. It takes the following form:
IndexIgnore _`filename`_…
The _`filename`_ option can be either a full file name, or a wildcard expression.
Example 9.41. Using the IndexIgnore directive
IndexIgnore .??* *~ *# HEADER* README* RCS CVS *,v *,t
`IndexOptions`
: The `IndexOptions` directive allows you to customize the behavior of server-generated directory listings. It takes the following form:
IndexOptions _`option`_…
The _`option`_ has to be a valid keyword as described in [Table 9.9, “Available directory listing options”](#table-apache-httpdconf-indexoptions "Table 9.9. Available directory listing options"). The default options are `Charset=UTF-8`, `FancyIndexing`, `HTMLTable`, `NameWidth=*`, and `VersionSort`.
Table 9.9. Available directory listing options
|Option|Description|
|-|
|`Charset`=_`encoding`_|Specifies the character set of a generated web page. The _`encoding`_ has to be a valid character set such as `UTF-8` or `ISO-8859-2`.|
|`Type`=_`content-type`_|Specifies the media type of a generated web page. The _`content-type`_ has to be a valid MIME type such as `text/html` or `text/plain`.|
|`DescriptionWidth`=_`value`_|Specifies the width of the description column. The _`value`_ can be either a number of characters, or an asterisk (that is, `*`) to adjust the width automatically.|
|`FancyIndexing`|Enables advanced features such as different icons for certain files or possibility to re-sort a directory listing by clicking on a column header.|
|`FolderFirst`|Enables listing directories first, always placing them above files.|
|`HTMLTable`|Enables the use of HTML tables for directory listings.|
|`IconsAreLinks`|Enables using the icons as links.|
|`IconHeight`=_`value`_|Specifies an icon height. The _`value`_ is a number of pixels.|
|`IconWidth`=_`value`_|Specifies an icon width. The _`value`_ is a number of pixels.|
|`IgnoreCase`|Enables sorting files and directories in a case-sensitive manner.|
|`IgnoreClient`|Disables accepting query variables from a client.|
|`NameWidth`=_`value`_|Specifies the width of the file name column. The _`value`_ can be either a number of characters, or an asterisk (that is, `*`) to adjust the width automatically.|
|`ScanHTMLTitles`|Enables parsing the file for a description (that is, the `title` element) in case it is not provided by the `AddDescription` directive.|
|`ShowForbidden`|Enables listing the files with otherwise restricted access.|
|`SuppressColumnSorting`|Disables re-sorting a directory listing by clicking on a column header.|
|`SuppressDescription`|Disables reserving a space for file descriptions.|
|`SuppressHTMLPreamble`|Disables the use of standard HTML preamble when a file specified by the `HeaderName` directive is present.|
|`SuppressIcon`|Disables the use of icons in directory listings.|
|`SuppressLastModified`|Disables displaying the date of the last modification field in directory listings.|
|`SuppressRules`|Disables the use of horizontal lines in directory listings.|
|`SuppressSize`|Disables displaying the file size field in directory listings.|
|`TrackModified`|Enables returning the `Last-Modified` and `ETag` values in the HTTP header.|
|`VersionSort`|Enables sorting files that contain a version number in the expected manner.|
|`XHTML`|Enables the use of XHTML 1.0 instead of the default HTML 3.2.|
Example 9.42. Using the IndexOptions directive
IndexOptions FancyIndexing VersionSort NameWidth=* HTMLTable Charset=UTF-8
`KeepAlive`
: The `KeepAlive` directive allows you to enable persistent connections. It takes the following form:
KeepAlive _`option`_
The _`option`_ has to be a valid keyword as described in [Table 9.10, “Available KeepAlive options”](#table-apache-httpdconf-keepalive "Table 9.10. Available KeepAlive options"). The default option is `Off`.
Table 9.10. Available KeepAlive options
|Option|Description|
|-|
|`On`|Enables the persistent connections. In this case, the server will accept more than one request per connection.|
|`Off`|Disables the keep-alive connections.|
Note that when the persistent connections are enabled, on a busy server, the number of child processes can increase rapidly and eventually reach the maximum limit, slowing down the server significantly. To reduce the risk, it is recommended that you set `KeepAliveTimeout` to a low number, and monitor the `/var/log/httpd/logs/error_log` log file carefully.
Example 9.43. Using the KeepAlive directive
KeepAlive Off
`KeepAliveTimeout`
: The `KeepAliveTimeout` directive allows you to specify the amount of time to wait for another request before closing the connection. It takes the following form:
KeepAliveTimeout _`time`_
The _`time`_ is specified in seconds. The default option is `15`.
Example 9.44. Using the KeepAliveTimeout directive
KeepAliveTimeout 15
`LanguagePriority`
: The `LanguagePriority` directive allows you to customize the precedence of languages. It takes the following form:
LanguagePriority _`language`_…
The _`language`_ has to be a valid MIME language such as `cs`, `en`, or `fr`.
This directive is especially useful for web servers that serve content in multiple languages based on the client's language settings.
Example 9.45. Using the LanguagePriority directive
LanguagePriority sk cs en
`Listen`
: The _`Listen`_ directive allows you to specify IP addresses or ports to listen to. It takes the following form:
Listen [_`ip-address`_:]_`port`_ [_`protocol`_]
The _`ip-address`_ is optional and unless supplied, the server will accept incoming requests on a given _`port`_ from all IP addresses. Since the _`protocol`_ is determined automatically from the port number, it can be usually omitted. The default option is to listen to port `80`.
Note that if the server is configured to listen to a port under 1024, only superuser will be able to start the `httpd` service.
Example 9.46. Using the Listen directive
Listen 80
`LoadModule`
: The `LoadModule` directive allows you to load a _Dynamic Shared Object_ (DSO) module. It takes the following form:
LoadModule _`name`_ _`path`_
The _`name`_ has to be a valid identifier of the required module. The _`path`_ refers to an existing module file, and must be relative to the directory in which the libraries are placed (that is, `/usr/lib/httpd/` on 32-bit and `/usr/lib64/httpd/` on 64-bit systems by default).
See [Section 9.1.5, “Working with Modules”](#s2-apache-dso "9.1.5. Working with Modules") for more information on the Apache HTTP Server's DSO support.
Example 9.47. Using the LoadModule directive
LoadModule php5_module modules/libphp5.so
`LogFormat`
: The _`LogFormat`_ directive allows you to specify a log file format. It takes the following form:
LogFormat _`format`_ _`name`_
The _`format`_ is a string consisting of options as described in [Table 9.11, “Common LogFormat options”](#table-apache-httpdconf-logformat "Table 9.11. Common LogFormat options"). The _`name`_ can be used instead of the format string in the `CustomLog` directive.
Table 9.11. Common LogFormat options
|Option|Description|
|-|
|`%b`|Represents the size of the response in bytes.|
|`%h`|Represents the IP address or hostname of a remote client.|
|`%l`|Represents the remote log name if supplied. If not, a hyphen (that is, `-`) is used instead.|
|`%r`|Represents the first line of the request string as it came from the browser or client.|
|`%s`|Represents the status code.|
|`%t`|Represents the date and time of the request.|
|`%u`|If the authentication is required, it represents the remote user. If not, a hyphen (that is, `-`) is used instead.|
|``%{_`field`_}``|Represents the content of the HTTP header _`field`_. The common options include `%{Referer}` (the URL of the web page that referred the client to the server) and `%{User-Agent}` (the type of the web browser making the request).|
Example 9.48. Using the LogFormat directive
LogFormat "%h %l %u %t \"%r\" %>s %b" common
`LogLevel`
: The `LogLevel` directive allows you to customize the verbosity level of the error log. It takes the following form:
LogLevel _`option`_
The _`option`_ has to be a valid keyword as described in [Table 9.12, “Available LogLevel options”](#table-apache-httpdconf-loglevel "Table 9.12. Available LogLevel options"). The default option is `warn`.
Table 9.12. Available LogLevel options
|Option|Description|
|-|
|`emerg`|Only the emergency situations when the server cannot perform its work are logged.|
|`alert`|All situations when an immediate action is required are logged.|
|`crit`|All critical conditions are logged.|
|`error`|All error messages are logged.|
|`warn`|All warning messages are logged.|
|`notice`|Even normal, but still significant situations are logged.|
|`info`|Various informational messages are logged.|
|`debug`|Various debugging messages are logged.|
Example 9.49. Using the LogLevel directive
LogLevel warn
`MaxKeepAliveRequests`
: The `MaxKeepAliveRequests` directive allows you to specify the maximum number of requests for a persistent connection. It takes the following form:
MaxKeepAliveRequests _`number`_
A high _`number`_ can improve the performance of the server. Note that using `0` allows unlimited number of requests. The default option is `100`.
Example 9.50. Using the MaxKeepAliveRequests option
MaxKeepAliveRequests 100
`NameVirtualHost`
: The `NameVirtualHost` directive allows you to specify the IP address and port number for a name-based virtual host. It takes the following form:
NameVirtualHost _`ip-address`_[:_`port`_]
The _`ip-address`_ can be either a full IP address, or an asterisk (that is, `*`) representing all interfaces. Note that IPv6 addresses have to be enclosed in square brackets (that is, `[` and `]`). The _`port`_ is optional.
Name-based virtual hosting allows one Apache HTTP Server to serve different domains without using multiple IP addresses.
### Using secure HTTP connections
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.
Example 9.51. Using the NameVirtualHost directive
NameVirtualHost *:80
`Options`
: The `Options` directive allows you to specify which server features are available in a particular directory. It takes the following form:
Options _`option`_…
The _`option`_ has to be a valid keyword as described in [Table 9.13, “Available server features”](#table-apache-httpdconf-options "Table 9.13. Available server features").
Table 9.13. Available server features
|Option|Description|
|-|
|`ExecCGI`|Enables the execution of CGI scripts.|
|`FollowSymLinks`|Enables following symbolic links in the directory.|
|`Includes`|Enables server-side includes.|
|`IncludesNOEXEC`|Enables server-side includes, but does not allow the execution of commands.|
|`Indexes`|Enables server-generated directory listings.|
|`MultiViews`|Enables content-negotiated “MultiViews”.|
|`SymLinksIfOwnerMatch`|Enables following symbolic links in the directory when both the link and the target file have the same owner.|
|`All`|Enables all of the features above with the exception of `MultiViews`.|
|`None`|Disables all of the features above.|
Example 9.52. Using the Options directive
Options Indexes FollowSymLinks
`Order`
: The `Order` directive allows you to specify the order in which the `Allow` and `Deny` directives are evaluated. It takes the following form:
Order _`option`_
The _`option`_ has to be a valid keyword as described in [Table 9.14, “Available Order options”](#table-apache-httpdconf-order "Table 9.14. Available Order options"). The default option is `allow,deny`.
Table 9.14. Available Order options
|Option|Description|
|-|
|`allow,deny`|`Allow` directives are evaluated first.|
|`deny,allow`|`Deny` directives are evaluated first.|
Example 9.53. Using the Order directive
Order allow,deny
`PidFile`
: The `PidFile` directive allows you to specify a file to which the _process ID_ (PID) of the server is stored. It takes the following form:
PidFile _`path`_
The _`path`_ refers to a pid file, and can be either absolute, or relative to the directory that is specified by the `ServerRoot` directive (that is, `/etc/httpd/` by default). The default option is `run/httpd.pid`.
Example 9.54. Using the PidFile directive
PidFile run/httpd.pid
`ProxyRequests`
: The `ProxyRequests` directive allows you to enable forward proxy requests. It takes the following form:
ProxyRequests _`option`_
The _`option`_ has to be a valid keyword as described in [Table 9.15, “Available ProxyRequests options”](#table-apache-httpdconf-proxyrequests "Table 9.15. Available ProxyRequests options"). The default option is `Off`.
Table 9.15. Available ProxyRequests options
|Option|Description|
|-|
|`On`|Enables forward proxy requests.|
|`Off`|Disables forward proxy requests.|
Example 9.55. Using the ProxyRequests directive
ProxyRequests On
`ReadmeName`
: The `ReadmeName` directive allows you to specify a file to be appended to the end of the server-generated directory listing. It takes the following form:
ReadmeName _`filename`_
The _`filename`_ is a name of the file to look for in the requested directory. By default, the server looks for `README.html`.
Example 9.56. Using the ReadmeName directive
ReadmeName README.html
`Redirect`
: The `Redirect` directive allows you to redirect a client to another URL. It takes the following form:
Redirect [_`status`_] _`path`_ _`url`_
The _`status`_ is optional, and if provided, it has to be a valid keyword as described in [Table 9.16, “Available status options”](#table-apache-httpdconf-redirect "Table 9.16. Available status options"). The _`path`_ refers to the old location, and must be relative to the directory specified by the `DocumentRoot` directive (for example, `/docs`). The _`url`_ refers to the current location of the content (for example, `http://docs.example.com`).
Table 9.16. Available status options
|Status|Description|
|-|
|`permanent`|Indicates that the requested resource has been moved permanently. The `301` (Moved Permanently) status code is returned to a client.|
|`temp`|Indicates that the requested resource has been moved only temporarily. The `302` (Found) status code is returned to a client.|
|`seeother`|Indicates that the requested resource has been replaced. The `303` (See Other) status code is returned to a client.|
|`gone`|Indicates that the requested resource has been removed permanently. The `410` (Gone) status is returned to a client.|
Note that for more advanced redirection techniques, you can use the `mod_rewrite` module that is part of the Apache HTTP Server installation.
Example 9.57. Using the Redirect directive
Redirect permanent /docs http://docs.example.com
`ScriptAlias`
: The `ScriptAlias` directive allows you to specify the location of CGI scripts. It takes the following form:
ScriptAlias _`url-path`_ _`real-path`_
The _`url-path`_ must be relative to the directory specified by the `DocumentRoot` directive (for example, `/cgi-bin/`). The _`real-path`_ is a full path to a file or directory in the local file system.
This directive is typically followed by the `Directory` tag with additional permissions to access the target directory. By default, the `/cgi-bin/` alias is created so that the scripts located in the `/var/www/cgi-bin/` are accessible.
The `ScriptAlias` directive is used for security reasons to prevent CGI scripts from being viewed as ordinary text documents.
Example 9.58. Using the ScriptAlias directive
ScriptAlias /cgi-bin/ /var/www/cgi-bin/
<Directory "/var/www/cgi-bin">
AllowOverride None
Options None
Order allow,deny
Allow from all
</Directory>
`ServerAdmin`
: The `ServerAdmin` directive allows you to specify the email address of the server administrator to be displayed in server-generated web pages. It takes the following form:
ServerAdmin _`email`_
The default option is `root@localhost`.
This directive is commonly set to ``webmaster@_`hostname`_``, where _`hostname`_ is the address of the server. Once set, alias `webmaster` to the person responsible for the web server in `/etc/aliases`, and as superuser, run the **newaliases** command.
Example 9.59. Using the ServerAdmin directive
ServerAdmin webmaster@penguin.example.com
`ServerName`
: The `ServerName` directive allows you to specify the hostname and the port number of a web server. It takes the following form:
ServerName _`hostname`_[:_`port`_]
The _`hostname`_ has to be a _fully qualified domain name_ (FQDN) of the server. The _`port`_ is optional, but when supplied, it has to match the number specified by the `Listen` directive.
When using this directive, make sure that the IP address and server name pair are included in the `/etc/hosts` file.
Example 9.60. Using the ServerName directive
ServerName penguin.example.com:80
`ServerRoot`
: The `ServerRoot` directive allows you to specify the directory in which the server operates. It takes the following form:
ServerRoot _`directory`_
The _`directory`_ must be a full path to an existing directory in the local file system. The default option is `/etc/httpd/`.
Example 9.61. Using the ServerRoot directive
ServerRoot /etc/httpd
`ServerSignature`
: The `ServerSignature` directive allows you to enable displaying information about the server on server-generated documents. It takes the following form:
ServerSignature _`option`_
The _`option`_ has to be a valid keyword as described in [Table 9.17, “Available ServerSignature options”](#table-apache-httpdconf-serversignature "Table 9.17. Available ServerSignature options"). The default option is `On`.
Table 9.17. Available ServerSignature options
|Option|Description|
|-|
|`On`|Enables appending the server name and version to server-generated pages.|
|`Off`|Disables appending the server name and version to server-generated pages.|
|`EMail`|Enables appending the server name, version, and the email address of the system administrator as specified by the `ServerAdmin` directive to server-generated pages.|
Example 9.62. Using the ServerSignature directive
ServerSignature On
`ServerTokens`
: The `ServerTokens` directive allows you to customize what information are included in the Server response header. It takes the following form:
ServerTokens _`option`_
The _`option`_ has to be a valid keyword as described in [Table 9.18, “Available ServerTokens options”](#table-apache-httpdconf-servertokens "Table 9.18. Available ServerTokens options"). The default option is `OS`.
Table 9.18. Available ServerTokens options
|Option|Description|
|-|
|`Prod`|Includes the product name only (that is, `Apache`).|
|`Major`|Includes the product name and the major version of the server (for example, `2`).|
|`Minor`|Includes the product name and the minor version of the server (for example, `2.2`).|
|`Min`|Includes the product name and the minimal version of the server (for example, `2.2.15`).|
|`OS`|Includes the product name, the minimal version of the server, and the type of the operating system it is running on (for example, `Red Hat`).|
|`Full`|Includes all the information above along with the list of loaded modules.|
Note that for security reasons, it is recommended to reveal as little information about the server as possible.
Example 9.63. Using the ServerTokens directive
ServerTokens Prod
`SuexecUserGroup`
: The `SuexecUserGroup` directive allows you to specify the user and group under which the CGI scripts will be run. It takes the following form:
SuexecUserGroup _`user`_ _`group`_
The _`user`_ has to be an existing user, and the _`group`_ must be a valid UNIX group.
For security reasons, the CGI scripts should not be run with `root` privileges. Note that in ``, `SuexecUserGroup` replaces the `User` and `Group` directives.
Example 9.64. Using the SuexecUserGroup directive
SuexecUserGroup apache apache
`Timeout`
: The `Timeout` directive allows you to specify the amount of time to wait for an event before closing a connection. It takes the following form:
Timeout _`time`_
The _`time`_ is specified in seconds. The default option is `60`.
Example 9.65. Using the Timeout directive
Timeout 60
`TypesConfig`
: The `TypesConfig` allows you to specify the location of the MIME types configuration file. It takes the following form:
TypesConfig _`path`_
The _`path`_ refers to an existing MIME types configuration file, and can be either absolute, or relative to the directory that is specified by the `ServerRoot` directive (that is, `/etc/httpd/` by default). The default option is `/etc/mime.types`.
Note that instead of editing `/etc/mime.types`, the recommended way to add MIME type mapping to the Apache HTTP Server is to use the `AddType` directive.
Example 9.66. Using the TypesConfig directive
TypesConfig /etc/mime.types
`UseCanonicalName`
: The `UseCanonicalName` allows you to specify the way the server refers to itself. It takes the following form:
UseCanonicalName _`option`_
The _`option`_ has to be a valid keyword as described in [Table 9.19, “Available UseCanonicalName options”](#table-apache-httpdconf-usecanonicalname "Table 9.19. Available UseCanonicalName options"). The default option is `Off`.
Table 9.19. Available UseCanonicalName options
|Option|Description|
|-|
|`On`|Enables the use of the name that is specified by the `ServerName` directive.|
|`Off`|Disables the use of the name that is specified by the `ServerName` directive. The hostname and port number provided by the requesting client are used instead.|
|`DNS`|Disables the use of the name that is specified by the `ServerName` directive. The hostname determined by a reverse DNS lookup is used instead.|
Example 9.67. Using the UseCanonicalName directive
UseCanonicalName Off
`User`
: The `User` directive allows you to specify the user under which the `httpd` service will run. It takes the following form:
User _`user`_
The _`user`_ has to be an existing UNIX user. The default option is `apache`.
For security reasons, the `httpd` service should not be run with `root` privileges. Note that `User` is no longer supported inside ``, and has been replaced by the `SuexecUserGroup` directive.
Example 9.68. Using the User directive
User apache
`UserDir`
: The `UserDir` directive allows you to enable serving content from users' home directories. It takes the following form:
UserDir _`option`_
The _`option`_ can be either a name of the directory to look for in user's home directory (typically `public_html`), or a valid keyword as described in [Table 9.20, “Available UserDir options”](#table-apache-httpdconf-userdir "Table 9.20. Available UserDir options"). The default option is `disabled`.
Table 9.20. Available UserDir options
|Option|Description|
|-|
|`enabled` _`user`_…|Enables serving content from home directories of given _`user`_s.|
|`disabled` [_`user`_…]|Disables serving content from home directories, either for all users, or, if a space separated list of _`user`_s is supplied, for given users only.|
### Set the correct permissions
In order for the web server to access the content, the permissions on relevant directories and files must be set correctly. Make sure that all users are able to access the home directories, and that they can access and read the content of the directory specified by the `UserDir` directive. For example, to allow access to `public_html/` in the home directory of user `joe`, type the following at a shell prompt as `root`:
~]# **chmod a+x /home/joe/**
~]# **chmod a+rx /home/joe/public_html/**
All files in this directory must be set accordingly.
Example 9.69. Using the UserDir directive
UserDir public_html
#### 9\.1.4.2. Common ssl.conf Directives {#s3-apache-sslconf-common}
The _Secure Sockets Layer_ (SSL) directives allow you to customize the behavior of the Apache HTTP Secure Server, and in most cases, they are configured appropriately during the installation. Be careful when changing these settings, as incorrect configuration can lead to security vulnerabilities.
The following directive is commonly used in `/etc/httpd/conf.d/ssl.conf`:
`SetEnvIf`
: The `SetEnvIf` directive allows you to set environment variables based on the headers of incoming connections. It takes the following form:
SetEnvIf _`option`_ _`pattern`_ [!]_`variable`_[=_`value`_]…
The _`option`_ can be either a HTTP header field, a previously defined environment variable name, or a valid keyword as described in [Table 9.21, “Available SetEnvIf options”](#table-apache-sslconf-setenvif "Table 9.21. Available SetEnvIf options"). The _`pattern`_ is a regular expression. The _`variable`_ is an environment variable that is set when the option matches the pattern. If the optional exclamation mark (that is, `!`) is present, the variable is removed instead of being set.
Table 9.21. Available SetEnvIf options
|Option|Description|
|-|
|`Remote_Host`|Refers to the client's hostname.|
|`Remote_Addr`|Refers to the client's IP address.|
|`Server_Addr`|Refers to the server's IP address.|
|`Request_Method`|Refers to the request method (for example, `GET`).|
|`Request_Protocol`|Refers to the protocol name and version (for example, `HTTP/1.1`).|
|`Request_URI`|Refers to the requested resource.|
The `SetEnvIf` directive is used to disable HTTP keepalives, and to allow SSL to close the connection without a closing notification from the client browser. This is necessary for certain web browsers that do not reliably shut down the SSL connection.
Example 9.70. Using the SetEnvIf directive
SetEnvIf User-Agent ".*MSIE.*" \
nokeepalive ssl-unclean-shutdown \
downgrade-1.0 force-response-1.0
Note that for the `/etc/httpd/conf.d/ssl.conf` file to be present, the mod\_ssl needs to be installed. See [Section 9.1.7, “Setting Up an SSL Server”](#s2-apache-mod_ssl "9.1.7. Setting Up an SSL Server") for more information on how to install and configure an SSL server.
#### 9\.1.4.3. Common Multi-Processing Module Directives {#s3-apache-mpm-common}
The _Multi-Processing Module_ (MPM) directives allow you to customize the behavior of a particular MPM specific server-pool. Since its characteristics differ depending on which MPM is used, the directives are embedded in `IfModule`. By default, the server-pool is defined for both the `prefork` and `worker` MPMs.
The following MPM directives are commonly used in `/etc/httpd/conf/httpd.conf`:
`MaxClients`
: The `MaxClients` directive allows you to specify the maximum number of simultaneously connected clients to process at one time. It takes the following form:
MaxClients _`number`_
A high _`number`_ can improve the performance of the server, although it is not recommended to exceed `256` when using the `prefork` MPM.
Example 9.71. Using the MaxClients directive
MaxClients 256
`MaxRequestsPerChild`
: The `MaxRequestsPerChild` directive allows you to specify the maximum number of request a child process can serve before it dies. It takes the following form:
MaxRequestsPerChild _`number`_
Setting the _`number`_ to `0` allows unlimited number of requests.
The `MaxRequestsPerChild` directive is used to prevent long-lived processes from causing memory leaks.
Example 9.72. Using the MaxRequestsPerChild directive
MaxRequestsPerChild 4000
`MaxSpareServers`
: The `MaxSpareServers` directive allows you to specify the maximum number of spare child processes. It takes the following form:
MaxSpareServers _`number`_
This directive is used by the `prefork` MPM only.
Example 9.73. Using the MaxSpareServers directive
MaxSpareServers 20
`MaxSpareThreads`
: The `MaxSpareThreads` directive allows you to specify the maximum number of spare server threads. It takes the following form:
MaxSpareThreads _`number`_
The _`number`_ must be greater than or equal to the sum of `MinSpareThreads` and `ThreadsPerChild`. This directive is used by the `worker` MPM only.
Example 9.74. Using the MaxSpareThreads directive
MaxSpareThreads 75
`MinSpareServers`
: The `MinSpareServers` directive allows you to specify the minimum number of spare child processes. It takes the following form:
MinSpareServers _`number`_
Note that a high _`number`_ can create a heavy processing load on the server. This directive is used by the `prefork` MPM only.
Example 9.75. Using the MinSpareServers directive
MinSpareServers 5
`MinSpareThreads`
: The `MinSpareThreads` directive allows you to specify the minimum number of spare server threads. It takes the following form:
MinSpareThreads _`number`_
This directive is used by the `worker` MPM only.
Example 9.76. Using the MinSpareThreads directive
MinSpareThreads 75
`StartServers`
: The `StartServers` directive allows you to specify the number of child processes to create when the service is started. It takes the following form:
StartServers _`number`_
Since the child processes are dynamically created and terminated according to the current traffic load, it is usually not necessary to change this value.
Example 9.77. Using the StartServers directive
StartServers 8
`ThreadsPerChild`
: The `ThreadsPerChild` directive allows you to specify the number of threads a child process can create. It takes the following form:
ThreadsPerChild _`number`_
This directive is used by the `worker` MPM only.
Example 9.78. Using the ThreadsPerChild directive
ThreadsPerChild 25
### 9\.1.5. Working with Modules {#s2-apache-dso}
Being a modular application, the `httpd` service is distributed along with a number of _Dynamic Shared Objects_ (DSOs), which can be dynamically loaded or unloaded at runtime as necessary. By default, these modules are located in `/usr/lib/httpd/modules/` on 32-bit and in `/usr/lib64/httpd/modules/` on 64-bit systems.
#### 9\.1.5.1. Loading a Module {#s3-apache-dso-loading}
To load a particular DSO module, use the `LoadModule` directive as described in [Section 9.1.4.1, “Common httpd.conf Directives”](#s3-apache-httpdconf-directives "9.1.4.1. Common httpd.conf Directives"). Note that modules provided by a separate package often have their own configuration file in the `/etc/httpd/conf.d/` directory.
Example 9.79. Loading the mod\_ssl DSO
LoadModule ssl_module modules/mod_ssl.so
Once you are finished, restart the web server to reload the configuration. See [Section 9.1.3.3, “Restarting the Service”](#s3-apache-running-restarting "9.1.3.3. Restarting the Service") for more information on how to restart the `httpd` service.
#### 9\.1.5.2. Writing a Module {#s3-apache-dso-writing}
If you intend to create a new DSO module, make sure you have the httpd-devel package installed. To do so, type the following at a shell prompt as `root`:
~]# **yum install httpd-devel**
This package contains the include files, the header files, and the APache eXtenSion (**apxs**) utility required to compile a module.
Once written, you can build the module with the following command:
~]# **apxs -i -a -c _`module_name`_.c**
If the build was successful, you should be able to load the module the same way as any other module that is distributed with the Apache HTTP Server.
### 9\.1.6. Setting Up Virtual Hosts {#s2-apache-virtualhosts}
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.
To create a name-based virtual host, copy the example configuration file ``/usr/share/doc/httpd-_`VERSION`_/httpd-vhosts.conf`` into the `/etc/httpd/conf.d/` directory, and replace the `@@Port@@` and `@@ServerRoot@@` placeholder values. Customize the options according to your requirements as shown in [Example 9.80, “Example virtual host configuration”](#example-apache-virtualhosts-config "Example 9.80. Example virtual host configuration").
Example 9.80. Example virtual host configuration
<VirtualHost *:80>
ServerAdmin webmaster@penguin.example.com
DocumentRoot "/www/docs/penguin.example.com"
ServerName penguin.example.com
ServerAlias www.penguin.example.com
ErrorLog "/var/log/httpd/dummy-host.example.com-error_log"
CustomLog "/var/log/httpd/dummy-host.example.com-access_log" common
</VirtualHost>
Note that `ServerName` must be a valid DNS name assigned to the machine. The `` container is highly customizable, and accepts most of the directives available within the main server configuration. Directives that are _not_ supported within this container include `User` and `Group`, which were replaced by `SuexecUserGroup`.
### Changing the port number
If you configure a virtual host to listen on a non-default port, make sure you update the `Listen` directive in the global settings section of the `/etc/httpd/conf/httpd.conf` file accordingly.
To activate a newly created virtual host, the web server has to be restarted first. See [Section 9.1.3.3, “Restarting the Service”](#s3-apache-running-restarting "9.1.3.3. Restarting the Service") for more information on how to restart the `httpd` service.
### 9\.1.7. Setting Up an SSL Server {#s2-apache-mod_ssl}
_Secure Sockets Layer_ (SSL) is a cryptographic protocol that allows a server and a client to communicate securely. Along with its extended and improved version called _Transport Layer Security_ (TLS), it ensures both privacy and data integrity. The Apache HTTP Server in combination with `mod_ssl`, a module that uses the OpenSSL toolkit to provide the SSL/TLS support, is commonly referred to as the _SSL server_.
Unlike a regular HTTP connection that can be read and possibly modified by anybody who is able to intercept it, the use of `mod_ssl` prevents any inspection or modification of the transmitted content. This section provides basic information on how to enable this module in the Apache HTTP Server configuration, and guides you through the process of generating private keys and self-signed certificates.
#### 9\.1.7.1. An Overview of Certificates and Security {#s3-apache-mod_ssl-certificates}
Secure communication is based on the use of keys. In conventional or _symmetric cryptography_, both ends of the transaction have the same key they can use to decode each other's transmissions. On the other hand, in public or _asymmetric cryptography_, two keys co-exist: a _private key_ that is kept a secret, and a _public key_ that is usually shared with the public. While the data encoded with the public key can only be decoded with the private key, data encoded with the private key can in turn only be decoded with the public key.
To provide secure communications using SSL, an SSL server must use a digital certificate signed by a _Certificate Authority_ (CA). The certificate lists various attributes of the server (that is, the server hostname, the name of the company, its location, etc.), and the signature produced using the CA's private key. This signature ensures that a particular certificate authority has issued the certificate, and that the certificate has not been modified in any way.
When a web browser establishes a new SSL connection, it checks the certificate provided by the web server. If the certificate does not have a signature from a trusted CA, or if the hostname listed in the certificate does not match the hostname used to establish the connection, it refuses to communicate with the server and usually presents a user with an appropriate error message.
By default, most web browsers are configured to trust a set of widely used certificate authorities. Because of this, an appropriate CA should be chosen when setting up a secure server, so that target users can trust the connection, otherwise they will be presented with an error message, and will have to accept the certificate manually. Since encouraging users to override certificate errors can allow an attacker to intercept the connection, you should use a trusted CA whenever possible. For more information on this, see [Table 9.22, “CA lists for most common web browsers”](#table-apache-mod_ssl-certificates-authorities "Table 9.22. CA lists for most common web browsers").
Table 9.22. CA lists for most common web browsers
|Web Browser|Link|
|-|
|Mozilla Firefox|[Mozilla root CA list](http://www.mozilla.org/projects/security/certs/included/).|
|Opera|[Root certificates used by Opera](http://www.opera.com/docs/ca/).|
|Internet Explorer|[Windows root certificate program members](http://support.microsoft.com/kb/931125).|
When setting up an SSL server, you need to generate a certificate request and a private key, and then send the certificate request, proof of the company's identity, and payment to a certificate authority. Once the CA verifies the certificate request and your identity, it will send you a signed certificate you can use with your server. Alternatively, you can create a self-signed certificate that does not contain a CA signature, and thus should be used for testing purposes only.
#### 9\.1.7.2. Enabling the mod\_ssl Module {#s3-apache-mod_ssl-enabling}
If you intend to set up an SSL server, make sure you have the mod\_ssl (the `mod_ssl` module) and openssl (the OpenSSL toolkit) packages installed. To do so, type the following at a shell prompt as `root`:
~]# **yum install mod_ssl openssl**
This will create the `mod_ssl` configuration file at `/etc/httpd/conf.d/ssl.conf`, which is included in the main Apache HTTP Server configuration file by default. For the module to be loaded, restart the `httpd` service as described in [Section 9.1.3.3, “Restarting the Service”](#s3-apache-running-restarting "9.1.3.3. Restarting the Service").
#### 9\.1.7.3. Using an Existing Key and Certificate {#s3-apache-mod_ssl-keypair}
If you have a previously created key and certificate, you can configure the SSL server to use these files instead of generating new ones. There are only two situations where this is not possible:
1. _You are changing the IP address or domain name._
Certificates are issued for a particular IP address and domain name pair. If one of these values changes, the certificate becomes invalid.
1. _You have a certificate from VeriSign, and you are changing the server software._
VeriSign, a widely used certificate authority, issues certificates for a particular software product, IP address, and domain name. Changing the software product renders the certificate invalid.
In either of the above cases, you will need to obtain a new certificate. For more information on this topic, see [Section 9.1.7.4, “Generating a New Key and Certificate”](#s3-apache-mod_ssl-genkey "9.1.7.4. Generating a New Key and Certificate").
If you wish to use an existing key and certificate, move the relevant files to the `/etc/pki/tls/private/` and `/etc/pki/tls/certs/` directories respectively. You can do so by running the following commands as `root`:
~]# **mv** ``_`key_file`_.key`` ``/etc/pki/tls/private/_`hostname`_.key``
~]# **mv** ``_`certificate`_.crt`` ``/etc/pki/tls/certs/_`hostname`_.crt``
Then add the following lines to the `/etc/httpd/conf.d/ssl.conf` configuration file:
SSLCertificateFile /etc/pki/tls/certs/_`hostname`_.crt
SSLCertificateKeyFile /etc/pki/tls/private/_`hostname`_.key
To load the updated configuration, restart the `httpd` service as described in [Section 9.1.3.3, “Restarting the Service”](#s3-apache-running-restarting "9.1.3.3. Restarting the Service").
Example 9.81. Using a key and certificate from the Red Hat Secure Web Server
~]# **mv /etc/httpd/conf/httpsd.key /etc/pki/tls/private/penguin.example.com.key**
~]# **mv /etc/httpd/conf/httpsd.crt /etc/pki/tls/certs/penguin.example.com.crt**
#### 9\.1.7.4. Generating a New Key and Certificate {#s3-apache-mod_ssl-genkey}
In order to generate a new key and certificate pair, you must to have the crypto-utils package installed in your system. As `root`, you can install it by typing the following at a shell prompt:
~]# **yum install crypto-utils**
This package provides a set of tools to generate and manage SSL certificates and private keys, and includes genkey, the Red Hat Keypair Generation utility that will guide you through the key generation process.
### Replacing an existing certificate
If the server already has a valid certificate and you are replacing it with a new one, specify a different serial number. This ensures that client browsers are notified of this change, update to this new certificate as expected, and do not fail to access the page. To create a new certificate with a custom serial number, as `root`, use the following command instead of genkey:
~]# **openssl req -x509 -new -set_serial _`number`_ -key _`hostname`_.key -out _`hostname`_.crt**
### Remove a previously created key
If there already is a key file for a particular hostname in your system, genkey will refuse to start. In this case, remove the existing file using the following command as `root`:
~]# **rm /etc/pki/tls/private/_`hostname`_.key**
To run the utility, as `root`, run the **genkey** command followed by the appropriate host name (for example, `penguin.example.com`):
~]# **genkey** _`hostname`_
To complete the key and certificate creation, take the following steps:
1. Review the target locations in which the key and certificate will be stored.
Figure 9.1. Running the genkey utility
![Running the genkey utility][39]
[[D](ld-idm15430176.html)]
Use the **Tab** key to select the Next button, and press **Enter** to proceed to the next screen.
1. Using the **Up** and **down** arrow keys, select the suitable key size. Note that while the large key increases the security, it also increases the response time of your server. The NIST recommends using `2048 bits`. See [_NIST Special Publication 800-131A_](http://csrc.nist.gov/publications/nistpubs/800-131A/sp800-131A.pdf).
Figure 9.2. Selecting the key size
![Selecting the key size][40]
[[D](ld-idm122715296.html)]
Once finished, use the **Tab** key to select the Next button, and press **Enter** to initiate the random bits generation process. Depending on the selected key size, this may take some time.
1. Decide whether you wish to send a certificate request to a certificate authority.
Figure 9.3. Generating a certificate request
![Generating a certificate request][41]
[[D](ld-idm75477472.html)]
Use the **Tab** key to select Yes to compose a certificate request, or No to generate a self-signed certificate. Then press **Enter** to confirm your choice.
1. Using the **Spacebar** key, enable (`[*]`) or disable (`[ ]`) the encryption of the private key.
Figure 9.4. Encrypting the private key
![Encrypting the private key][42]
[[D](ld-idm85304128.html)]
Use the **Tab** key to select the Next button, and press **Enter** to proceed to the next screen.
1. If you have enabled the private key encryption, enter an adequate passphrase. Note that for security reasons, it is not displayed as you type, and it must be at least five characters long.
Figure 9.5. Entering a passphrase
![Entering a passphrase][43]
[[D](ld-idm106914048.html)]
Use the **Tab** key to select the Next button, and press **Enter** to proceed to the next screen.
### Do not forget the passphrase
Entering the correct passphrase is required in order for the server to start. If you lose it, you will need to generate a new key and certificate.
1. Customize the certificate details.
Figure 9.6. Specifying certificate information
![Specifying certificate information][44]
[[D](ld-idm56796384.html)]
Use the **Tab** key to select the Next button, and press **Enter** to finish the key generation.
1. If you have previously enabled the certificate request generation, you will be prompted to send it to a certificate authority.
Figure 9.7. Instructions on how to send a certificate request
![Instructions on how to send a certificate request][45]
[[D](ld-idm40614080.html)]
Press **Enter** to return to a shell prompt.
Once generated, add the key and certificate locations to the `/etc/httpd/conf.d/ssl.conf` configuration file:
SSLCertificateFile /etc/pki/tls/certs/_`hostname`_.crt
SSLCertificateKeyFile /etc/pki/tls/private/_`hostname`_.key
Finally, restart the `httpd` service as described in [Section 9.1.3.3, “Restarting the Service”](#s3-apache-running-restarting "9.1.3.3. Restarting the Service"), so that the updated configuration is loaded.
### 9\.1.8. Additional Resources {#s2-apache-resources}
To learn more about the Apache HTTP Server, see the following resources.
#### 9\.1.8.1. Installed Documentation {#s3-apache-resources-installed}
: The official documentation for the Apache HTTP Server with the full description of its directives and available modules. Note that in order to access this documentation, you must have the httpd-manual package installed, and the web server must be running.
`/usr/share/doc/httpd/`
: The directory containing a number of example configurations files.
**man httpd**
: The manual page for the `httpd` service containing the complete list of its command line options.
**man apachectl**
: The manual page for the Apache HTTP Server Control Interface.
**man genkey**
: The manual page for **genkey** containing the full documentation on its usage.
#### 9\.1.8.2. Useful Websites {#s3-apache-resources-web}
: The official website for the Apache HTTP Server with documentation on all the directives and default modules.
: The official website for the mod\_ssl module.
: The OpenSSL home page containing further documentation, frequently asked questions, links to the mailing lists, and other useful resources.
## Chapter 10. Mail Servers {#ch-Mail_Servers}
_Email_ was born in the 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.
## 10\.1. Email Protocols {#s1-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.
### 10\.1.1. Mail Transport Protocols {#s2-email-protocols-send}
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_).
#### 10\.1.1.1. SMTP {#s3-email-protocols-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 and Sendmail SMTP programs.
### 10\.1.2. Mail Access Protocols {#s2-email-protocols-client}
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_).
#### 10\.1.2.1. POP {#s3-email-protocols-pop}
The default POP server under Fedora is Dovecot and is provided by the dovecot package.
### Installing the dovecot package
In order to use Dovecot, first ensure the **dovecot** package is installed on your system by running, as `root`:
**yum install dovecot**
For more information on installing packages with Yum, refer to [Section 5.2.4, “Installing Packages”](#sec-Installing "5.2.4. Installing Packages").
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` (Monash Directory Service) 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.
* _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 **pop3s** service, or by using the **/usr/sbin/stunnel** application. For more information on securing email communication, refer to [Section 10.5.1, “Securing Communication”](#s2-email-security "10.5.1. Securing Communication").
#### 10\.1.2.2. IMAP {#s3-email-protocols-imap}
The default `IMAP` server under Fedora is Dovecot and is provided by the dovecot package. See [Section 10.1.2.1, “POP”](#s3-email-protocols-pop "10.1.2.1. POP") for information on how to install Dovecot.
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 users 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. For more information on securing email communication, refer to [Section 10.5.1, “Securing Communication”](#s2-email-security "10.5.1. Securing Communication").
Other free, as well as commercial, IMAP clients and servers are available, many of which extend the IMAP protocol and provide additional functionality.
#### 10\.1.2.3. Dovecot {#s3-mail-server-dovecot}
The **imap-login** and **pop3-login** processes which implement the `IMAP` and `POP3` protocols are spawned by the master `dovecot` daemon included in the dovecot package. The use of `IMAP` and `POP` is configured through the `/etc/dovecot/dovecot.conf` configuration file; by default **dovecot** runs `IMAP` and `POP3` together with their secure versions using `SSL`. To configure **dovecot** to use `POP`, complete the following steps:
1. Edit the `/etc/dovecot/dovecot.conf` configuration file to make sure the `protocols` variable is uncommented (remove the hash sign (**\#**) at the beginning of the line) and contains the `pop3` argument. For example:
protocols = imap imaps pop3 pop3s
When the `protocols` variable is left commented out, **dovecot** will use the default values specified for this variable.
1. Make that change operational for the current session by running the following command as `root`:
**systemctl restart dovecot.service**
1. Make that change operational after the next reboot by running the command:
**systemctl enable dovecot.service**
### The dovecot service starts the POP3 server
Please note that **dovecot** only reports that it started the `IMAP` server, but also starts the `POP3` server.
Unlike `SMTP`, both `IMAP` and `POP3` 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 `/etc/pki/dovecot/dovecot-openssl.conf` configuration file 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/libexec/dovecot/mkcert.sh` script which creates the **dovecot** self signed certificates. These certificates are copied in the `/etc/pki/dovecot/certs` and `/etc/pki/dovecot/private` directories. To implement the changes, restart **dovecot** by typing the following at a shell prompt as `root`:
**systemctl restart dovecot.service**
More details on **dovecot** can be found online at .
## 10\.2. Email Program Classifications {#s1-email-types}
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.
### 10\.2.1. Mail Transport Agent {#s2-email-types-mta}
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 offers two MTAs—_Postfix_ and _Sendmail_—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 Postfix, Sendmail, and Fetchmail, refer to [Section 10.3, “Mail Transport Agents”](#s1-email-mta "10.3. Mail Transport Agents").
### 10\.2.2. Mail Delivery Agent {#s2-email-types-mda}
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.
### 10\.2.3. Mail User Agent {#s2-email-types-mua}
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.
## 10\.3. Mail Transport Agents {#s1-email-mta}
Fedora offers two primary MTAs: Postfix and Sendmail. Postfix is configured as the default MTA, although it is easy to switch the default MTA to Sendmail. To switch the default MTA to Sendmail, as `root`, you can either uninstall Postfix or use the following command to switch to Sendmail:
**alternatives --config mta**
You can also use the following command to enable/disable the desired service:
**systemctl enable|disable _`service`_.service**
### 10\.3.1. Postfix {#s2-email-mta-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 changed root 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.
#### 10\.3.1.1. The Default Postfix Installation {#s3-email-mta-postfix-default}
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.
* `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.
The `aliases` file can be found in the `/etc/` directory. This file is shared between Postfix and Sendmail. It is a configurable list required by the mail protocol that describes user ID aliases.
### Configuring Postfix as a server for other clients
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 10.3.1.2, “Basic Postfix Configuration”](#s3-email-mta-postfix-conf "10.3.1.2. Basic Postfix Configuration").
Restart the `postfix` service after changing any options in the configuration files under the `/etc/postfix` directory in order for those changes to take effect. To do so, run the following command as `root`:
**systemctl restart postfix.service**
#### 10\.3.1.2. Basic Postfix Configuration {#s3-email-mta-postfix-conf}
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 sign (**\#**), 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 the `/etc/postfix/main.cf` configuration file. Additional resources including information about Postfix configuration, SpamAssassin integration, or detailed descriptions of the `/etc/postfix/main.cf` parameters are available online at .
#### 10\.3.1.3. Using Postfix with LDAP {#using-postfix-with-ldap}
Postfix can use an `LDAP` directory as a source for various lookup tables (e.g.: `aliases`, `virtual`, `canonical`, etc.). This allows `LDAP` to store hierarchical user information and Postfix to only be given the result of `LDAP` queries when needed. By not storing this information locally, administrators can easily maintain it.
##### 10\.3.1.3.1. The /etc/aliases lookup example {#aliases-example}
The following is a basic example for using `LDAP` to look up the `/etc/aliases` file. Make sure your `/etc/postfix/main.cf` contains the following:
alias_maps = hash:/etc/aliases, ldap:/etc/postfix/ldap-aliases.cf
Create a `/etc/postfix/ldap-aliases.cf` file if you do not have one created already and make sure it contains the following:
server_host = _`ldap.example.com`_
search_base = dc=_`example`_, dc=_`com`_
where _`ldap.example.com`_, _`example`_, and _`com`_ are parameters that need to be replaced with specification of an existing available `LDAP` server.
### The /etc/postfix/ldap-aliases.cf file
The `/etc/postfix/ldap-aliases.cf` file can specify various parameters, including parameters that enable `LDAP` `SSL` and `STARTTLS`. For more information, refer to the **ldap\_table(5)** man page.
For more information on `LDAP`, refer to [Section 11.1, “OpenLDAP”](#s1-OpenLDAP "11.1. OpenLDAP").
### 10\.3.2. Sendmail {#s2-email-mta-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.
#### 10\.3.2.1. Purpose and Limitations {#s3-email-mta-sendmail-purpose}
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. See the [Section 10.6, “Additional Resources”](#s1-email-additional-resources "10.6. 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)_.
#### 10\.3.2.2. The Default Sendmail Installation {#s3-email-mta-sendmail-default}
In order to use Sendmail, first ensure the sendmail package is installed on your system by running, as `root`:
**yum install sendmail**
In order to configure Sendmail, ensure the sendmail-cf package is installed on your system by running, as `root`:
**yum install sendmail-cf**
For more information on installing packages with Yum, refer to [Section 5.2.4, “Installing Packages”](#sec-Installing "5.2.4. Installing Packages").
Before using Sendmail, the default MTA has to be switched from Postfix. For more information how to switch the default MTA refer to [Section 10.3, “Mail Transport Agents”](#s1-email-mta "10.3. Mail Transport Agents").
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 **systemctl start|restart|reload sendmail.service**.
* Alternatively you may use the **m4** macro processor to create a new `/etc/mail/sendmail.cf`. The **m4** macro processor is not installed by default. Before using it to create `/etc/mail/sendmail.cf`, install the m4 package as `root`:
**yum install m4**
More information on configuring Sendmail can be found in [Section 10.3.2.3, “Common Sendmail Configuration Changes”](#s3-email-mta-sendmail-changes "10.3.2.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, as `root`:
**makemap hash /etc/mail/_`name`_ < /etc/mail/_`name`_**
where _`name`_ represents the name of the configuration file to be updated. You may also restart the `sendmail` service for the changes to take effect by running:
**systemctl restart sendmail.service**
For example, to have all emails addressed to the `example.com` domain delivered to <[bob@other-example.com](mailto:bob@other-example.com)>, 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:
**makemap hash /etc/mail/virtusertable < /etc/mail/virtusertable**
Sendmail will create an updated `virtusertable.db` file containing the new configuration.
#### 10\.3.2.3. Common Sendmail Configuration Changes {#s3-email-mta-sendmail-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.
### Backup the sendmail.cf file before changing its content
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 `root`. Once you are finished, restart the `sendmail` service and, if the m4 package is installed, the **m4** macro processor will automatically generate a new `sendmail.cf` configuration file:
**systemctl restart sendmail.service**
### Configuring Sendmail as a server for other clients
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 restarting the service:
**systemctl restart sendmail.service**
The default configuration which ships with Fedora works for most `SMTP`-only sites. However, it does not work for _UUCP_ (_UNIX-to-UNIX Copy Protocol_) sites. If using UUCP mail transfers, the `/etc/mail/sendmail.mc` file must be reconfigured and a new `/etc/mail/sendmail.cf` file 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 the `/etc/mail/sendmail.cf` file.
#### 10\.3.2.4. Masquerading {#s3-email-sendmail-changes-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 the **m4** macro processor, this configuration makes all mail from inside the network appear as if it were sent from `bigcorp.com`.
#### 10\.3.2.5. Stopping Spam {#s3-email-sendmail-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:
**systemctl restart sendmail.service**
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" 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 the `/etc/mail/access.db` file is a database, use the **makemap** command to update 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 email's 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 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. See 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. See [Section 10.4.2.6, “Spam Filters”](#s3-email-mda-spam "10.4.2.6. Spam Filters") for more information about using SpamAssassin.
#### 10\.3.2.6. Using Sendmail with LDAP {#s3-email-mta-sendmail-ldap}
Using `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 `/etc/aliases` and `/etc/mail/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
### Advanced configuration
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 the **m4** macro processor and again restarting Sendmail. See [Section 10.3.2.3, “Common Sendmail Configuration Changes”](#s3-email-mta-sendmail-changes "10.3.2.3. Common Sendmail Configuration Changes") for instructions.
For more information on `LDAP`, refer to [Section 11.1, “OpenLDAP”](#s1-OpenLDAP "11.1. OpenLDAP").
### 10\.3.3. Fetchmail {#s2-email-mta-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.
### Installing the fetchmail package
In order to use Fetchmail, first ensure the fetchmail package is installed on your system by running, as `root`:
**yum install fetchmail**
For more information on installing packages with Yum, refer to [Section 5.2.4, “Installing Packages”](#sec-Installing "5.2.4. Installing Packages").
Fetchmail is configured for each user through the use of a `.fetchmailrc` file in the user's home directory. If it does not already exist, create the `.fetchmailrc` file in your 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.
#### 10\.3.3.1. Fetchmail Configuration Options {#s3-email-mda-fetchmail-configuration}
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 the `.fetchmailrc` file because it only checks skipped servers when specifically invoked, and does not affect any currently working configurations.
The following is a sample example of a `.fetchmailrc` file:
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.
### Omitting the password from the configuration
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 in the following three sections.
#### 10\.3.3.2. Global Options {#s3-email-mda-fetchmail-configuration-global}
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`.
#### 10\.3.3.3. Server Options {#s3-email-mda-fetchmail-configuration-server}
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.
#### 10\.3.3.4. User Options {#s3-email-fetchmail-configuration-user}
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._
#### 10\.3.3.5. Fetchmail Command Options {#s3-email-mda-fetchmail-commands}
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.
#### 10\.3.3.6. Informational or Debugging Options {#s3-email-mda-fetchmail-commands-info}
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.
#### 10\.3.3.7. Special Options {#s3-email-mda-fetchmail-commands-special}
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.
### 10\.3.4. Mail Transport Agent (MTA) Configuration {#s2-email-switchmail}
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 20 provides two MTAs: Postfix and Sendmail. If both are installed, Postfix is the default MTA.
## 10\.4. Mail Delivery Agents {#s1-email-mda}
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 (**man mail**).
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.
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.
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 a `/etc/procmailrc` file 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.
### 10\.4.1. Procmail Configuration {#s2-email-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 the `~/.procmailrc` file 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
To turn off Procmail filtering of email lists but leaving spam control in place, comment out the first **INCLUDERC** line with a hash sign (**\#**).
* **LOCKSLEEP** — Sets the amount of time, in seconds, between attempts by Procmail to use a particular lockfile. The default is `8` 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.
### 10\.4.2. Procmail Recipes {#s2-email-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 10.4.2.5, “Recipe Examples”](#s3-email-procmail-recipes-examples "10.4.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 asterisk character (**\***) can further control the condition.
The **_`action-to-perform`_** argument 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. See [Section 10.4.2.4, “Special Conditions and Actions”](#s3-email-procmail-recipes-special "10.4.2.4. Special Conditions and Actions") for more information.
#### 10\.4.2.1. Delivering vs. Non-Delivering Recipes {#s2-email-procmail-recipes-delivering}
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 email address. A non-delivering recipe covers any other actions, such as a _nesting block_. A nesting block is a set of actions, contained in braces **\{** **\}**, that are performed on messages which match the recipe's conditions. Nesting blocks can be nested inside one another, providing greater control for identifying and performing actions on messages.
When messages match a delivering recipe, Procmail performs the specified action and stops comparing the message against any other recipes. Messages that match non-delivering recipes continue to be compared against other recipes.
#### 10\.4.2.2. Flags {#s3-email-procmail-recipes-flags}
Flags are essential to determine how or if a recipe's conditions are compared to a message. The following flags are commonly used:
* **A** — Specifies that this recipe is only used if the previous recipe without an **A** or **a** flag also matched this message.
* **a** — Specifies that this recipe is only used if the previous recipe with an **A** or **a** flag also matched this message _and_ was successfully completed.
* **B** — Parses the body of the message and looks for matching conditions.
* **b** — Uses the body in any resulting action, such as writing the message to a file or forwarding it. This is the default behavior.
* **c** — Generates a carbon copy of the email. This is useful with delivering recipes, since the required action can be performed on the message and a copy of the message can continue being processed in the `rc` files.
* **D** — Makes the **egrep** comparison case-sensitive. By default, the comparison process is not case-sensitive.
* **E** — While similar to the **A** flag, the conditions in the recipe are only compared to the message if the immediately preceding the recipe without an **E** flag did not match. This is comparable to an _else_ action.
* **e** — The recipe is compared to the message only if the action specified in the immediately preceding recipe fails.
* **f** — Uses the pipe as a filter.
* **H** — Parses the header of the message and looks for matching conditions. This is the default behavior.
* **h** — Uses the header in a resulting action. This is the default behavior.
* **w** — Tells Procmail to wait for the specified filter or program to finish, and reports whether or not it was successful before considering the message filtered.
* **W** — Is identical to **w** except that "Program failure" messages are suppressed.
For a detailed list of additional flags, refer to the `procmailrc` man page.
#### 10\.4.2.3. Specifying a Local Lockfile {#s3-email-procmail-recipes-lockfile}
Lockfiles are very useful with Procmail to ensure that more than one process does not try to alter a message simultaneously. Specify a local lockfile by placing a colon (**:**) after any flags on a recipe's first line. This creates a local lockfile based on the destination file name plus whatever has been set in the **LOCKEXT** global environment variable.
Alternatively, specify the name of the local lockfile to be used with this recipe after the colon.
#### 10\.4.2.4. Special Conditions and Actions {#s3-email-procmail-recipes-special}
Special characters used before Procmail recipe conditions and actions change the way they are interpreted.
The following characters may be used after the asterisk character (**\***) at the beginning of a recipe's condition line:
* **!** — In the condition line, this character inverts the condition, causing a match to occur only if the condition does not match the message.
* **<** — Checks if the message is under a specified number of bytes.
* **>** — Checks if the message is over a specified number of bytes.
The following characters are used to perform special actions:
* **!** — In the action line, this character tells Procmail to forward the message to the specified email addresses.
* **$** — Refers to a variable set earlier in the `rc` file. This is often used to set a common mailbox that is referred to by various recipes.
* **|** — Starts a specified program to process the message.
* **\{** and **\}** — Constructs a nesting block, used to contain additional recipes to apply to matching messages.
If no special character is used at the beginning of the action line, Procmail assumes that the action line is specifying the mailbox in which to write the message.
#### 10\.4.2.5. Recipe Examples {#s3-email-procmail-recipes-examples}
Procmail is an extremely flexible program, but as a result of this flexibility, composing Procmail recipes from scratch can be difficult for new users.
The best way to develop the skills to build Procmail recipe conditions stems from a strong understanding of regular expressions combined with looking at many examples built by others. A thorough explanation of regular expressions is beyond the scope of this section. The structure of Procmail recipes and useful sample Procmail recipes can be found at various places on the Internet (such as ). The proper use and adaptation of regular expressions can be derived by viewing these recipe examples. In addition, introductory information about basic regular expression rules can be found in the `grep` man page.
The following simple examples demonstrate the basic structure of Procmail recipes and can provide the foundation for more intricate constructions.
A basic recipe may not even contain conditions, as is illustrated in the following example:
:0: new-mail.spool
The first line specifies that a local lockfile is to be created but does not specify a name, so Procmail uses the destination file name and appends the value specified in the **LOCKEXT** environment variable. No condition is specified, so every message matches this recipe and is placed in the single spool file called `new-mail.spool`, located within the directory specified by the **MAILDIR** environment variable. An MUA can then view messages in this file.
A basic recipe, such as this, can be placed at the end of all `rc` files to direct messages to a default location.
The following example matched messages from a specific email address and throws them away.
:0 * ^From: spammer@domain.com /dev/null
With this example, any messages sent by `spammer@domain.com` are sent to the `/dev/null` device, deleting them.
### Sending messages to /dev/null
Be certain that rules are working as intended before sending messages to `/dev/null` for permanent deletion. If a recipe inadvertently catches unintended messages, and those messages disappear, it becomes difficult to troubleshoot the rule.
A better solution is to point the recipe's action to a special mailbox, which can be checked from time to time to look for false positives. Once satisfied that no messages are accidentally being matched, delete the mailbox and direct the action to send the messages to `/dev/null`.
The following recipe grabs email sent from a particular mailing list and places it in a specified folder.
:0: * ^(From|Cc|To).*tux-lug tuxlug
Any messages sent from the `tux-lug@domain.com` mailing list are placed in the `tuxlug` mailbox automatically for the MUA. Note that the condition in this example matches the message if it has the mailing list's email address on the `From`, `Cc`, or `To` lines.
Consult the many Procmail online resources available in [Section 10.6, “Additional Resources”](#s1-email-additional-resources "10.6. Additional Resources") for more detailed and powerful recipes.
#### 10\.4.2.6. Spam Filters {#s3-email-mda-spam}
Because it is called by Sendmail, Postfix, and Fetchmail upon receiving new emails, Procmail can be used as a powerful tool for combating spam.
This is particularly true when Procmail is used in conjunction with SpamAssassin. When used together, these two applications can quickly identify spam emails, and sort or destroy them.
SpamAssassin uses header analysis, text analysis, blacklists, a spam-tracking database, and self-learning Bayesian spam analysis to quickly and accurately identify and tag spam.
### Installing the spamassassin package
In order to use SpamAssassin, first ensure the spamassassin package is installed on your system by running, as `root`:
**yum install spamassassin**
For more information on installing packages with Yum, refer to [Section 5.2.4, “Installing Packages”](#sec-Installing "5.2.4. Installing Packages").
The easiest way for a local user to use SpamAssassin is to place the following line near the top of the `~/.procmailrc` file:
INCLUDERC=/etc/mail/spamassassin/spamassassin-default.rc
The `/etc/mail/spamassassin/spamassassin-default.rc` contains a simple Procmail rule that activates SpamAssassin for all incoming email. If an email is determined to be spam, it is tagged in the header as such and the title is prepended with the following pattern:
*****SPAM*****
The message body of the email is also prepended with a running tally of what elements caused it to be diagnosed as spam.
To file email tagged as spam, a rule similar to the following can be used:
:0 Hw * ^X-Spam-Status: Yes spam
This rule files all email tagged in the header as spam into a mailbox called `spam`.
Since SpamAssassin is a Perl script, it may be necessary on busy servers to use the binary SpamAssassin daemon (`spamd`) and the client application (spamc). Configuring SpamAssassin this way, however, requires `root` access to the host.
To start the `spamd` daemon, type the following command:
**systemctl start spamassassin.service**
To start the SpamAssassin daemon when the system is booted, run:
**systemctl enable spamassassin.service**
See [Chapter 6, _Services and Daemons_](#ch-Services_and_Daemons "Chapter 6. Services and Daemons") for more information on how to configure services in Fedora.
To configure Procmail to use the SpamAssassin client application instead of the Perl script, place the following line near the top of the `~/.procmailrc` file. For a system-wide configuration, place it in `/etc/procmailrc`:
INCLUDERC=/etc/mail/spamassassin/spamassassin-spamc.rc
## 10\.5. Mail User Agents {#s1-email-mua}
Fedora offers a variety of email programs, both, graphical email client programs, such as Evolution, and text-based email programs such as **mutt**.
The remainder of this section focuses on securing communication between a client and a server.
### 10\.5.1. Securing Communication {#s2-email-security}
Popular MUAs included with Fedora, such as Evolution and **mutt** offer SSL-encrypted email sessions.
Like any other service that flows over a network unencrypted, important email information, such as usernames, passwords, and entire messages, may be intercepted and viewed by users on the network. Additionally, since the standard `POP` and `IMAP` protocols pass authentication information unencrypted, it is possible for an attacker to gain access to user accounts by collecting usernames and passwords as they are passed over the network.
#### 10\.5.1.1. Secure Email Clients {#s3-email-security-clients}
Most Linux MUAs designed to check email on remote servers support SSL encryption. To use SSL when retrieving email, it must be enabled on both the email client and the server.
SSL is easy to enable on the client-side, often done with the click of a button in the MUA's configuration window or via an option in the MUA's configuration file. Secure `IMAP` and `POP` have known port numbers (`993` and `995`, respectively) that the MUA uses to authenticate and download messages.
#### 10\.5.1.2. Securing Email Client Communications {#s3-email-security-servers}
Offering SSL encryption to `IMAP` and `POP` users on the email server is a simple matter.
First, create an SSL certificate. This can be done in two ways: by applying to a _Certificate Authority_ (_CA_) for an SSL certificate or by creating a self-signed certificate.
### Avoid using self-signed certificates
Self-signed certificates should be used for testing purposes only. Any server used in a production environment should use an SSL certificate granted by a CA.
To create a self-signed SSL certificate for `IMAP` or `POP`, change to the `/etc/pki/dovecot/` directory, edit the certificate parameters in the `/etc/pki/dovecot/dovecot-openssl.conf` configuration file as you prefer, and type the following commands, as `root`:
dovecot]# **rm -f certs/dovecot.pem private/dovecot.pem**
dovecot]# **/usr/libexec/dovecot/mkcert.sh**
Once finished, make sure you have the following configurations in your `/etc/dovecot/conf.d/10-ssl.conf` file:
ssl_cert = </etc/pki/dovecot/certs/dovecot.pem
ssl_key = </etc/pki/dovecot/private/dovecot.pem
Execute the **systemctl restart dovecot.service** command to restart the **dovecot** daemon.
Alternatively, the **stunnel** command can be used as an SSL encryption wrapper around the standard, non-secure connections to `IMAP` or `POP` services.
The **stunnel** utility uses external OpenSSL libraries included with Fedora to provide strong cryptography and to protect the network connections. It is recommended to apply to a CA to obtain an SSL certificate, but it is also possible to create a self-signed certificate.
### Installing the stunnel package
In order to use **stunnel**, first ensure the stunnel package is installed on your system by running, as `root`:
**yum install stunnel**
For more information on installing packages with Yum, refer to [Section 5.2.4, “Installing Packages”](#sec-Installing "5.2.4. Installing Packages").
To create a self-signed SSL certificate, change to the `/etc/pki/tls/certs/` directory, and type the following command:
certs]# **make stunnel.pem**
Answer all of the questions to complete the process.
Once the certificate is generated, create an **stunnel** configuration file, for example `/etc/stunnel/mail.conf`, with the following content:
cert = /etc/pki/tls/certs/stunnel.pem
[pop3s]
accept = 995
connect = 110
[imaps]
accept = 993
connect = 143
Once you start **stunnel** with the created configuration file using the **/usr/bin/stunnel /etc/stunnel/mail.conf** command, it will be possible to use an `IMAP` or a `POP` email client and connect to the email server using SSL encryption.
For more information on **stunnel**, refer to the **stunnel** man page or the documents in the `/usr/share/doc/stunnel/` directory.
## 10\.6. Additional Resources {#s1-email-additional-resources}
The following is a list of additional documentation about email applications.
### 10\.6.1. Installed Documentation {#s2-email-installed-docs}
* Information on configuring Sendmail is included with the `sendmail` and `sendmail-cf` packages.
* `/usr/share/sendmail-cf/README` — Contains information on the **m4** macro processor, file locations for Sendmail, supported mailers, how to access enhanced features, and more.
In addition, the `sendmail` and `aliases` man pages contain helpful information covering various Sendmail options and the proper configuration of the Sendmail `/etc/mail/aliases` file.
* `/usr/share/doc/postfix/` — Contains a large amount of information about ways to configure Postfix.
* `/usr/share/doc/fetchmail/` — Contains a full list of Fetchmail features in the `FEATURES` file and an introductory `FAQ` document.
* `/usr/share/doc/procmail/` — Contains a `README` file that provides an overview of Procmail, a `FEATURES` file that explores every program feature, and an `FAQ` file with answers to many common configuration questions.
When learning how Procmail works and creating new recipes, the following Procmail man pages are invaluable:
* `procmail` — Provides an overview of how Procmail works and the steps involved with filtering email.
* `procmailrc` — Explains the `rc` file format used to construct recipes.
* `procmailex` — Gives a number of useful, real-world examples of Procmail recipes.
* `procmailsc` — Explains the weighted scoring technique used by Procmail to match a particular recipe to a message.
* `/usr/share/doc/spamassassin/` — Contains a large amount of information pertaining to SpamAssassin.
### 10\.6.2. Useful Websites {#s2-email-useful-websites}
* — Offers a thorough technical breakdown of Sendmail features, documentation and configuration examples.
* — Contains news, interviews and articles concerning Sendmail, including an expanded view of the many options available.
* — The Postfix project home page contains a wealth of information about Postfix. The mailing list is a particularly good place to look for information.
* — The home page for Fetchmail, featuring an online manual, and a thorough FAQ.
* — The home page for Procmail with links to assorted mailing lists dedicated to Procmail as well as various FAQ documents.
* — An excellent Procmail FAQ, offers troubleshooting tips, details about file locking, and the use of wildcard characters.
* — Contains dozens of tips that make using Procmail much easier. Includes instructions on how to test `.procmailrc` files and use Procmail scoring to decide if a particular action should be taken.
* — The official site of the SpamAssassin project.
### 10\.6.3. Related Books {#s2-email-related-books}
* _Sendmail Milters: A Guide for Fighting Spam_ by Bryan Costales and Marcia Flynt; Addison-Wesley — A good Sendmail guide that can help you customize your mail filters.
* _Sendmail_ by Bryan Costales with Eric Allman et al.; O'Reilly & Associates — A good Sendmail reference written with the assistance of the original creator of Delivermail and Sendmail.
* _Removing the Spam: Email Processing and Filtering_ by Geoff Mulligan; Addison-Wesley Publishing Company — A volume that looks at various methods used by email administrators using established tools, such as Sendmail and Procmail, to manage spam problems.
* _Internet Email Protocols: A Developer's Guide_ by Kevin Johnson; Addison-Wesley Publishing Company — Provides a very thorough review of major email protocols and the security they provide.
* _Managing IMAP_ by Dianna Mullet and Kevin Mullet; O'Reilly & Associates — Details the steps required to configure an IMAP server.
## Chapter 11. Directory Servers {#ch-Directory_Servers}
## 11\.1. OpenLDAP {#s1-OpenLDAP}
`LDAP` (Lightweight Directory Access Protocol) is a set of open protocols used to access centrally stored information over a network. It is based on the `X.500` standard for directory sharing, but is less complex and resource-intensive. For this reason, LDAP is sometimes referred to as “X.500 Lite”.
Like X.500, LDAP organizes information in a hierarchical manner using directories. These directories can store a variety of information such as names, addresses, or phone numbers, and can even be used in a manner similar to the _Network Information Service_ (NIS), enabling anyone to access their account from any machine on the LDAP enabled network.
LDAP is commonly used for centrally managed users and groups, user authentication, or system configuration. It can also serve as a virtual phone directory, allowing users to easily access contact information for other users. Additionally, it can refer a user to other LDAP servers throughout the world, and thus provide an ad-hoc global repository of information. However, it is most frequently used within individual organizations such as universities, government departments, and private companies.
This section covers the installation and configuration of OpenLDAP 2.4, an open source implementation of the LDAPv2 and LDAPv3 protocols.
### 11\.1.1. Introduction to LDAP {#s2-ldap-introduction}
Using a client/server architecture, LDAP provides reliable means to create a central information directory accessible from the network. When a client attempts to modify information within this directory, the server verifies the user has permission to make the change, and then adds or updates the entry as requested. To ensure the communication is secure, the _Secure Sockets Layer_ (SSL) or _Transport Layer Security_ (TLS) cryptographic protocols can be used to prevent an attacker from intercepting the transmission.
### Using Mozilla NSS
The OpenLDAP suite in Fedora 20 no longer uses OpenSSL. Instead, it uses the Mozilla implementation of _Network Security Services_ (NSS). OpenLDAP continues to work with existing certificates, keys, and other TLS configuration. For more information on how to configure it to use Mozilla certificate and key database, refer to [_How do I use TLS/SSL with Mozilla NSS_](http://www.openldap.org/faq/index.cgi?file=1514).
The LDAP server supports several database systems, which gives administrators the flexibility to choose the best suited solution for the type of information they are planning to serve. Because of a well-defined client _Application Programming Interface_ (API), the number of applications able to communicate with an LDAP server is numerous, and increasing in both quantity and quality.
#### 11\.1.1.1. LDAP Terminology {#s3-ldap-terminology}
The following is a list of LDAP-specific terms that are used within this chapter:
entry
: A single unit within an LDAP directory. Each entry is identified by its unique _Distinguished Name_ (DN).
attribute
: Information directly associated with an entry. For example, if an organization is represented as an LDAP entry, attributes associated with this organization might include an address, a fax number, etc. Similarly, people can be represented as entries with common attributes such as personal telephone number or email address.
An attribute can either have a single value, or an unordered space-separated list of values. While certain attributes are optional, other are required. Required attributes are specified using the `objectClass` definition, and can be found in schema files located in the `/etc/openldap/slapd.d/cn=config/cn=schema/` directory.
The assertion of an attribute and its corresponding value is also referred to as a _Relative Distinguished Name_ (RDN). Unlike distinguished names that are unique globally, a relative distinguished name is only unique per entry.
LDIF
: The _LDAP Data Interchange Format_ (LDIF) is a plain text representation of an LDAP entry. It takes the following form:
[_`id`_] dn: _`distinguished_name`_
_`attribute_type`_: _`attribute_value`_…
_`attribute_type`_: _`attribute_value`_…
…
The optional _`id`_ is a number determined by the application that is used to edit the entry. Each entry can contain as many _`attribute_type`_ and _`attribute_value`_ pairs as needed, as long as they are all defined in a corresponding schema file. A blank line indicates the end of an entry.
#### 11\.1.1.2. OpenLDAP Features {#s3-ldap-features}
OpenLDAP suite provides a number of important features:
* _LDAPv3 Support_ — Many of the changes in the protocol since LDAP version 2 are designed to make LDAP more secure. Among other improvements, this includes the support for Simple Authentication and Security Layer (SASL), Transport Layer Security (TLS), and Secure Sockets Layer (SSL) protocols.
* _LDAP Over IPC_ — The use of inter-process communication (IPC) enhances security by eliminating the need to communicate over a network.
* _IPv6 Support_ — OpenLDAP is compliant with Internet Protocol version 6 (IPv6), the next generation of the Internet Protocol.
* _LDIFv1 Support_ — OpenLDAP is fully compliant with LDIF version 1.
* _Updated C API_ — The current C API improves the way programmers can connect to and use LDAP directory servers.
* _Enhanced Standalone LDAP Server_ — This includes an updated access control system, thread pooling, better tools, and much more.
#### 11\.1.1.3. OpenLDAP Server Setup {#s3-ldap-setup}
The typical steps to set up an LDAP server on Fedora are as follows:
1. Install the OpenLDAP suite. See [Section 11.1.2, “Installing the OpenLDAP Suite”](#s2-ldap-installation "11.1.2. Installing the OpenLDAP Suite") for more information on required packages.
1. Customize the configuration as described in [Section 11.1.3, “Configuring an OpenLDAP Server”](#s2-ldap-configuration "11.1.3. Configuring an OpenLDAP Server").
1. Start the `slapd` service as described in [Section 11.1.4, “Running an OpenLDAP Server”](#s2-ldap-running "11.1.4. Running an OpenLDAP Server").
1. Use the **ldapadd** utility to add entries to the LDAP directory.
1. Use the **ldapsearch** utility to verify that the `slapd` service is accessing the information correctly.
### 11\.1.2. Installing the OpenLDAP Suite {#s2-ldap-installation}
The suite of OpenLDAP libraries and tools is provided by the following packages:
Table 11.1. List of OpenLDAP packages
|Package|Description|
|-|
|openldap|A package containing the libraries necessary to run the OpenLDAP server and client applications.|
|openldap-clients|A package containing the command line utilities for viewing and modifying directories on an LDAP server.|
|openldap-servers|A package containing both the services and utilities to configure and run an LDAP server. This includes the _Standalone LDAP Daemon_, `slapd`.|
|openldap-servers-sql|A package containing the SQL support module.|
Additionally, the following packages are commonly used along with the LDAP server:
Table 11.2. List of commonly installed additional LDAP packages
|Package|Description|
|-|
|nss-pam-ldapd|A package containing `nslcd`, a local LDAP name service that allows a user to perform local LDAP queries.|
|mod\_authz\_ldap|A package containing `mod_authz_ldap`, the LDAP authorization 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. Note that the `mod_ssl` module is required when using the `mod_authz_ldap` module.|
To install these packages, use the **yum** command in the following form:
**yum** `install` _`package`_…
For example, to perform the basic LDAP server installation, type the following at a shell prompt as `root`:
**yum install openldap openldap-clients openldap-servers**
Note that you must have superuser privileges (that is, you must be logged in as `root`) to run this command. For more information on how to install new packages in Fedora, refer to [Section 5.2.4, “Installing Packages”](#sec-Installing "5.2.4. Installing Packages").
#### 11\.1.2.1. Overview of OpenLDAP Server Utilities {#s3-ldap-packages-openldap-servers}
To perform administrative tasks, the openldap-servers package installs the following utilities along with the `slapd` service:
Table 11.3. List of OpenLDAP server utilities
|Command|Description|
|-|
|**slapacl**|Allows you to check the access to a list of attributes.|
|**slapadd**|Allows you to add entries from an LDIF file to an LDAP directory.|
|**slapauth**|Allows you to check a list of IDs for authentication and authorization permissions.|
|**slapcat**|Allows you to pull entries from an LDAP directory in the default format and save them in an LDIF file.|
|**slapdn**|Allows you to check a list of Distinguished Names (DNs) based on available schema syntax.|
|**slapindex**|Allows you to re-index the `slapd` directory based on the current content. Run this utility whenever you change indexing options in the configuration file.|
|**slappasswd**|Allows you to create an encrypted user password to be used with the **ldapmodify** utility, or in the `slapd` configuration file.|
|**slapschema**|Allows you to check the compliance of a database with the corresponding schema.|
|**slaptest**|Allows you to check the LDAP server configuration.|
For a detailed description of these utilities and their usage, refer to the corresponding manual pages as referred to in [Section 11.1.6.1, “Installed Documentation”](#s3-ldap-installed-docs "11.1.6.1. Installed Documentation").
### Make sure the files have correct owner
Although only `root` can run **slapadd**, the `slapd` service runs as the `ldap` user. Because of this, the directory server is unable to modify any files created by **slapadd**. To correct this issue, after running the **slapadd** utility, type the following at a shell prompt:
**chown -R ldap:ldap /var/lib/ldap**
### Stop slapd before using these utilities
To preserve the data integrity, stop the `slapd` service before using **slapadd**, **slapcat**, or **slapindex**. You can do so by typing the following at a shell prompt as `root`:
**systemctl stop slapd.service**
For more information on how to start, stop, restart, and check the current status of the `slapd` service, refer to [Section 11.1.4, “Running an OpenLDAP Server”](#s2-ldap-running "11.1.4. Running an OpenLDAP Server").
#### 11\.1.2.2. Overview of OpenLDAP Client Utilities {#s3-ldap-packages-openldap-clients}
The openldap-clients package installs the following utilities which can be used to add, modify, and delete entries in an LDAP directory:
Table 11.4. List of OpenLDAP client utilities
|Command|Description|
|-|
|**ldapadd**|Allows you to add entries to an LDAP directory, either from a file, or from standard input. It is a symbolic link to **ldapmodify -a**.|
|**ldapcompare**|Allows you to compare given attribute with an LDAP directory entry.|
|**ldapdelete**|Allows you to delete entries from an LDAP directory.|
|**ldapexop**|Allows you to perform extended LDAP operations.|
|**ldapmodify**|Allows you to modify entries in an LDAP directory, either from a file, or from standard input.|
|**ldapmodrdn**|Allows you to modify the RDN value of an LDAP directory entry.|
|**ldappasswd**|Allows you to set or change the password for an LDAP user.|
|**ldapsearch**|Allows you to search LDAP directory entries.|
|**ldapurl**|Allows you to compose or decompose LDAP URLs.|
|**ldapwhoami**|Allows you to perform a `whoami` operation on an LDAP server.|
With the exception of **ldapsearch**, each of these utilities is more easily used by referencing a file containing the changes to be made rather than typing a command for each entry to be changed within an LDAP directory. The format of such a file is outlined in the man page for each utility.
#### 11\.1.2.3. Overview of Common LDAP Client Applications {#s3-ldap-packages-applications}
Although there are various graphical LDAP clients capable of creating and modifying directories on the server, none of them is included in Fedora. Popular applications that can access directories in a read-only mode include Mozilla Thunderbird, Evolution, or Ekiga.
### 11\.1.3. Configuring an OpenLDAP Server {#s2-ldap-configuration}
By default, the OpenLDAP configuration is stored in the `/etc/openldap/` directory. The following table highlights the most important directories and files within this directory:
Table 11.5. List of OpenLDAP configuration files and directories
|Path|Description|
|-|
|`/etc/openldap/ldap.conf`|The configuration file for client applications that use the OpenLDAP libraries. This includes **ldapadd**, **ldapsearch**, Evolution, etc.|
|`/etc/openldap/slapd.d/`|The directory containing the `slapd` configuration.|
Note that OpenLDAP no longer reads its configuration from the `/etc/openldap/slapd.conf` file. Instead, it uses a configuration database located in the `/etc/openldap/slapd.d/` directory. If you have an existing `slapd.conf` file from a previous installation, you can convert it to the new format by running the following command as `root`:
**slaptest -f /etc/openldap/slapd.conf -F /etc/openldap/slapd.d/**
The `slapd` configuration consists of LDIF entries organized in a hierarchical directory structure, and the recommended way to edit these entries is to use the server utilities described in [Section 11.1.2.1, “Overview of OpenLDAP Server Utilities”](#s3-ldap-packages-openldap-servers "11.1.2.1. Overview of OpenLDAP Server Utilities").
### Do not edit LDIF files directly
An error in an LDIF file can render the `slapd` service unable to start. Because of this, it is strongly advised that you avoid editing the LDIF files within the `/etc/openldap/slapd.d/` directly.
#### 11\.1.3.1. Changing the Global Configuration {#s3-ldap-configuration-global}
Global configuration options for the LDAP server are stored in the `/etc/openldap/slapd.d/cn=config.ldif` file. The following directives are commonly used:
`olcAllows`
: The `olcAllows` directive allows you to specify which features to enable. It takes the following form:
`olcAllows`: _`feature`_…
It accepts a space-separated list of features as described in [Table 11.6, “Available olcAllows options”](#table-ldap-configuration-olcallows "Table 11.6. Available olcAllows options"). The default option is `bind_v2`.
Table 11.6. Available olcAllows options
|Option|Description|
|-|
|`bind_v2`|Enables the acceptance of LDAP version 2 bind requests.|
|`bind_anon_cred`|Enables an anonymous bind when the Distinguished Name (DN) is empty.|
|`bind_anon_dn`|Enables an anonymous bind when the Distinguished Name (DN) is _not_ empty.|
|`update_anon`|Enables processing of anonymous update operations.|
|`proxy_authz_anon`|Enables processing of anonymous proxy authorization control.|
Example 11.1. Using the olcAllows directive
olcAllows: bind_v2 update_anon
`olcConnMaxPending`
: The `olcConnMaxPending` directive allows you to specify the maximum number of pending requests for an anonymous session. It takes the following form:
`olcConnMaxPending`: _`number`_
The default option is `100`.
Example 11.2. Using the olcConnMaxPending directive
olcConnMaxPending: 100
`olcConnMaxPendingAuth`
: The `olcConnMaxPendingAuth` directive allows you to specify the maximum number of pending requests for an authenticated session. It takes the following form:
`olcConnMaxPendingAuth`: _`number`_
The default option is `1000`.
Example 11.3. Using the olcConnMaxPendingAuth directive
olcConnMaxPendingAuth: 1000
`olcDisallows`
: The `olcDisallows` directive allows you to specify which features to disable. It takes the following form:
`olcDisallows`: _`feature`_…
It accepts a space-separated list of features as described in [Table 11.7, “Available olcDisallows options”](#table-ldap-configuration-olcdisallows "Table 11.7. Available olcDisallows options"). No features are disabled by default.
Table 11.7. Available olcDisallows options
|Option|Description|
|-|
|`bind_anon`|Disables the acceptance of anonymous bind requests.|
|`bind_simple`|Disables the simple bind authentication mechanism.|
|`tls_2_anon`|Disables the enforcing of an anonymous session when the STARTTLS command is received.|
|`tls_authc`|Disallows the STARTTLS command when authenticated.|
Example 11.4. Using the olcDisallows directive
olcDisallows: bind_anon
`olcIdleTimeout`
: The `olcIdleTimeout` directive allows you to specify how many seconds to wait before closing an idle connection. It takes the following form:
`olcIdleTimeout`: _`number`_
This option is disabled by default (that is, set to `0`).
Example 11.5. Using the olcIdleTimeout directive
olcIdleTimeout: 180
`olcLogFile`
: The `olcLogFile` directive allows you to specify a file in which to write log messages. It takes the following form:
`olcLogFile`: _`file_name`_
The log messages are written to standard error by default.
Example 11.6. Using the olcLogFile directive
olcLogFile: /var/log/slapd.log
`olcReferral`
: The `olcReferral` option allows you to specify a URL of a server to process the request in case the server is not able to handle it. It takes the following form:
`olcReferral`: _`URL`_
This option is disabled by default.
Example 11.7. Using the olcReferral directive
olcReferral: ldap://root.openldap.org
`olcWriteTimeout`
: The `olcWriteTimeout` option allows you to specify how many seconds to wait before closing a connection with an outstanding write request. It takes the following form:
olcWriteTimeout
This option is disabled by default (that is, set to `0`).
Example 11.8. Using the olcWriteTimeout directive
olcWriteTimeout: 180
#### 11\.1.3.2. Changing the Database-Specific Configuration {#s3-ldap-configuration-database}
By default, the OpenLDAP server uses Berkeley DB (BDB) as a database back end. The configuration for this database is stored in the `/etc/openldap/slapd.d/cn=config/olcDatabase={1}bdb.ldif` file. The following directives are commonly used in a database-specific configuration:
`olcReadOnly`
: The `olcReadOnly` directive allows you to use the database in a read-only mode. It takes the following form:
`olcReadOnly`: _`boolean`_
It accepts either `TRUE` (enable the read-only mode), or `FALSE` (enable modifications of the database). The default option is `FALSE`.
Example 11.9. Using the olcReadOnly directive
olcReadOnly: TRUE
`olcRootDN`
: The `olcRootDN` directive allows you to specify the user that is unrestricted by access controls or administrative limit parameters set for operations on the LDAP directory. It takes the following form:
`olcRootDN`: _`distinguished_name`_
It accepts a _Distinguished Name_ (DN). The default option is `cn=Manager,dn=my-domain,dc=com`.
Example 11.10. Using the olcRootDN directive
olcRootDN: cn=root,dn=example,dn=com
`olcRootPW`
: The `olcRootPW` directive allows you to set a password for the user that is specified using the `olcRootDN` directive. It takes the following form:
`olcRootPW`: _`password`_
It accepts either a plain text string, or a hash. To generate a hash, use the **slappaswd** utility, for example:
~]$ **slappaswd**
New password:
Re-enter new password:
{SSHA}WczWsyPEnMchFf1GRTweq2q7XJcvmSxD
Example 11.11. Using the olcRootPW directive
olcRootPW: {SSHA}WczWsyPEnMchFf1GRTweq2q7XJcvmSxD
`olcSuffix`
: The `olcSuffix` directive allows you to specify the domain for which to provide information. It takes the following form:
`olcSuffix`: _`domain_name`_
It accepts a _fully qualified domain name_ (FQDN). The default option is `dc=my-domain,dc=com`.
Example 11.12. Using the olcSuffix directive
olcSuffix: dc=example,dc=com
#### 11\.1.3.3. Extending Schema {#s3-ldap-configuration-schema}
Since OpenLDAP 2.3, the `/etc/openldap/slapd.d/` directory also contains LDAP definitions that were previously located in `/etc/openldap/schema/`. It is possible to extend the schema used by OpenLDAP to support additional attribute types and object classes using the default schema files as a guide. However, this task is beyond the scope of this chapter. For more information on this topic, refer to .
### 11\.1.4. Running an OpenLDAP Server {#s2-ldap-running}
This section describes how to start, stop, restart, and check the current status of the Standalone LDAP Daemon. For more information on how to manage system services in general, refer to [Chapter 6, _Services and Daemons_](#ch-Services_and_Daemons "Chapter 6. Services and Daemons").
#### 11\.1.4.1. Starting the Service {#s3-ldap-running-starting}
To run the `slapd` service, type the following at a shell prompt as `root`:
**systemctl start slapd.service**
If you want the service to start automatically at the boot time, use the following command:
**systemctl enable slapd.service**
See [Chapter 6, _Services and Daemons_](#ch-Services_and_Daemons "Chapter 6. Services and Daemons") for more information on how to configure services in Fedora.
#### 11\.1.4.2. Stopping the Service {#s3-ldap-running-stopping}
To stop the running `slapd` service, type the following at a shell prompt as `root`:
**systemctl stop slapd.service**
To prevent the service from starting automatically at the boot time, type:
**systemctl disable slapd.service**
See [Chapter 6, _Services and Daemons_](#ch-Services_and_Daemons "Chapter 6. Services and Daemons") for more information on how to configure services in Fedora.
#### 11\.1.4.3. Restarting the Service {#s3-ldap-running-restarting}
To restart the running `slapd` service, type the following at a shell prompt as `root`:
**systemctl restart slapd.service**
This stops the service, and then starts it again. Use this command to reload the configuration.
#### 11\.1.4.4. Checking the Service Status {#s3-ldap-running-status}
To check whether the service is running, type the following at a shell prompt:
**systemctl is-active slapd.service**
### 11\.1.5. Configuring a System to Authenticate Using OpenLDAP {#s2-ldap-pam}
In order to configure a system to authenticate using OpenLDAP, make sure that the appropriate packages are installed on both LDAP server and client machines. For information on how to set up the server, follow the instructions in [Section 11.1.2, “Installing the OpenLDAP Suite”](#s2-ldap-installation "11.1.2. Installing the OpenLDAP Suite") and [Section 11.1.3, “Configuring an OpenLDAP Server”](#s2-ldap-configuration "11.1.3. Configuring an OpenLDAP Server"). On a client, type the following at a shell prompt as `root`:
**yum install openldap openldap-clients nss-pam-ldapd**
[Chapter 7, _Configuring Authentication_](#ch-Configuring_Authentication "Chapter 7. Configuring Authentication") provides detailed instructions on how to configure applications to use LDAP for authentication.
#### 11\.1.5.1. Migrating Old Authentication Information to LDAP Format {#s3-ldap-migrationtools}
The migrationtools package provides a set of shell and Perl scripts to help you migrate authentication information into an LDAP format. To install this package, type the following at a shell prompt as `root`:
**yum install migrationtools**
This will install the scripts to the `/usr/share/migrationtools/` directory. Once installed, edit the `/usr/share/migrationtools/migrate_common.ph` file and change the following lines to reflect the correct domain, for example:
# Default DNS domain
$DEFAULT_MAIL_DOMAIN = "example.com";
# Default base
$DEFAULT_BASE = "dc=example,dc=com";
Alternatively, you can specify the environment variables directly on the command line. For example, to run the `migrate_all_online.sh` script with the default base set to `dc=example,dc=com`, type:
**export DEFAULT_BASE="dc=example,dc=com" \**
**/usr/share/migrationtools/migrate_all_online.sh**
To decide which script to run in order to migrate the user database, refer to [Table 11.8, “Commonly used LDAP migration scripts”](#table-ldap-migrationtools "Table 11.8. Commonly used LDAP migration scripts").
Table 11.8. Commonly used LDAP migration scripts
|Existing Name Service|Is LDAP Running?|Script to Use|
|-|
|`/etc` flat files|yes|`migrate_all_online.sh`|
|`/etc` flat files|no|`migrate_all_offline.sh`|
|NetInfo|yes|`migrate_all_netinfo_online.sh`|
|NetInfo|no|`migrate_all_netinfo_offline.sh`|
|NIS (YP)|yes|`migrate_all_nis_online.sh`|
|NIS (YP)|no|`migrate_all_nis_offline.sh`|
For more information on how to use these scripts, refer to the `README` and the `migration-tools.txt` files in the `/usr/share/doc/migrationtools/` directory.
### 11\.1.6. Additional Resources {#s2-ldap-resources}
The following resources offer additional information on the Lightweight Directory Access Protocol. Before configuring LDAP on your system, it is highly recommended that you review these resources, especially the _OpenLDAP Software Administrator's Guide_.
#### 11\.1.6.1. Installed Documentation {#s3-ldap-installed-docs}
The following documentation is installed with the openldap-servers package:
`/usr/share/doc/openldap-servers/guide.html`
: A copy of the _OpenLDAP Software Administrator's Guide_.
`/usr/share/doc/openldap-servers/README.schema`
: A README file containing the description of installed schema files.
Additionally, there is also a number of manual pages that are installed with the openldap, openldap-servers, and openldap-clients packages:
Client Applications
: * **man ldapadd** — Describes how to add entries to an LDAP directory.
* **man ldapdelete** — Describes how to delete entries within an LDAP directory.
* **man ldapmodify** — Describes how to modify entries within an LDAP directory.
* **man ldapsearch** — Describes how to search for entries within an LDAP directory.
* **man ldappasswd** — Describes how to set or change the password of an LDAP user.
* **man ldapcompare** — Describes how to use the **ldapcompare** tool.
* **man ldapwhoami** — Describes how to use the **ldapwhoami** tool.
* **man ldapmodrdn** — Describes how to modify the RDNs of entries.
Server Applications
: * **man slapd** — Describes command line options for the LDAP server.
Administrative Applications
: * **man slapadd** — Describes command line options used to add entries to a **slapd** database.
* **man slapcat** — Describes command line options used to generate an LDIF file from a **slapd** database.
* **man slapindex** — Describes command line options used to regenerate an index based upon the contents of a **slapd** database.
* **man slappasswd** — Describes command line options used to generate user passwords for LDAP directories.
Configuration Files
: * **man ldap.conf** — Describes the format and options available within the configuration file for LDAP clients.
* **man slapd-config** — Describes the format and options available within the configuration directory.
#### 11\.1.6.2. Useful Websites {#s3-ldap-additional-resources-web}
: The current version of the _OpenLDAP Software Administrator's Guide_.
: Jeff Hodges' _LDAP Roadmap & FAQ_ containing links to several useful resources and emerging news concerning the LDAP protocol.
: A collection of articles that offer a good introduction to LDAP, including methods to design a directory tree and customizing directory structures.
: A website of developers of several useful LDAP tools.
#### 11\.1.6.3. Related Books {#s3-ldap-related-books}
_OpenLDAP by Example_ by John Terpstra and Benjamin Coles; Prentice Hall.
: A collection of practical exercises in the OpenLDAP deployment.
_Implementing LDAP_ by Mark Wilcox; Wrox Press, Inc.
: A book covering LDAP from both the system administrator's and software developer's perspective.
_Understanding and Deploying LDAP Directory Services_ by Tim Howes et al.; Macmillan Technical Publishing.
: A book covering LDAP design principles, as well as its deployment in a production environment.
## Chapter 12. File and Print Servers {#ch-File_and_Print_Servers}
This chapter guides you through the installation and configuration of Samba, an open source implementation of the _Server Message Block_ (SMB) and _common Internet file system_ (`CIFS`) protocol, and vsftpd, the primary FTP server shipped with Fedora. Additionally, it explains how to use the Printer Configuration tool to configure printers.
## 12\.1. Samba {#s1-Samba}
Samba is an open source implementation of the _server message block_ (`SMB`) protocol. Modern versions of this protocol are also known as the _common Internet file system_ (`CIFS`) 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.
### Installing the samba package
In order to use Samba, first ensure the samba package is installed on your system by running, as `root`:
~]# **yum install samba**
For more information on installing packages with Yum, see [Section 5.2.4, “Installing Packages”](#sec-Installing "5.2.4. Installing Packages").
### 12\.1.1. Introduction to Samba {#samba-rgs-overview}
Fedora includes Samba version `4.1`:
#### 12\.1.1.1. Samba Features {#s3-samba-abilities}
Samba is a powerful and versatile server application.
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/2008 PDC/Windows Server 2012
What Samba cannot do:
* Act as a BDC for a Windows PDC (and vice versa)
* Act as an Active Directory domain controller
### 12\.1.2. Samba Daemons and Related Services {#s2-samba-daemons}
The following is a brief introduction to the individual Samba daemons and services.
#### 12\.1.2.1. Samba Daemons {#s3-samba-services}
Samba is comprised of three daemons (**smbd**, **nmbd**, and **winbindd**). Three services (**smb**, **nmb**, and **winbind**) control how the daemons are started, stopped, and other service-related features. These services act as different init scripts. Each daemon is listed in detail below, as well as which specific service has control over it.
##### **smbd** {#s4-samba-daemon-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** {#s4-samba-daemon-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 **nmb** service.
##### **winbindd** {#s4-samba-daemon-winbindd}
The **winbind** service resolves user and group information received from a server running Windows NT, 2000, 2003, Windows Server 2008, or Windows Server 2012. This makes Windows user and 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 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 chapter.
### Obtaining a list of utilities that are shipped with Samba
See [Section 12.1.11, “Samba Distribution Programs”](#s2-samba-programs "12.1.11. Samba Distribution Programs") for a list of utilities included in the Samba distribution.
### 12\.1.3. Connecting to a Samba Share {#s2-samba-connect-share}
You can use Nautilus to view available Samba shares on your network. To view a list of Samba workgroups and domains on your network, select Applications → Accessories → Files from the Activities menu, and click Browse Network at the sidebar.
Figure 12.1. Browsing a network in Nautilus
![Browsing a network in Nautilus][46]
[[D](ld-idm34702880.html)]
An icon appears for each available `SMB` workgroup or domain on the network. Double-click one of the workgroup/domain icons to view a list of computers within the workgroup/domain.
Each machine within the workgroup is represented by its own icon. 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`_**
#### 12\.1.3.1. Command Line {#s3-samba-connect-share-cmdline}
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.
#### 12\.1.3.2. Mounting the Share {#s2-samba-mounting}
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 a directory to mount it to (if it does not already exist), and execute the following command as `root`:
**mount -t cifs //_`servername`_/_`sharename`_ _`/mnt/point/`_ -o username=_`username`_,password=_`password`_**
This command mounts _`sharename`_ from _`servername`_ in the local directory _`/mnt/point/`_.
### Installing cifs-utils package
The mount.cifs utility is a separate RPM (independent from Samba). In order to use mount.cifs, first ensure the cifs-utils package is installed on your system by running, as `root`:
~]# **yum install cifs-utils**
For more information on installing packages with Yum, see [Section 5.2.4, “Installing Packages”](#sec-Installing "5.2.4. Installing Packages").
Note that the cifs-utils package also contains the cifs.upcall binary called by the kernel in order to perform kerberized CIFS mounts. For more information on cifs.upcall, see **man cifs.upcall**.
For more information about mounting a samba share, see **man mount.cifs**.
### CIFS servers that require plain text passwords
Some CIFS servers require plain text passwords for authentication. Support for plain text password authentication can be enabled using the following command as `root`:
~]# **echo 0x37 > /proc/fs/cifs/SecurityFlags**
WARNING: This operation can expose passwords by removing password encryption.
### 12\.1.4. Configuring a Samba Server {#s2-samba-configuring}
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. You can attach a printer to the system and print to it from the Windows machines on your network.
#### 12\.1.4.1. Graphical Configuration {#s3-samba-configuring-gui}
To configure Samba using a graphical interface, use one of the available Samba graphical user interfaces. A list of available GUIs can be found at .
#### 12\.1.4.2. Command Line Configuration {#s3-samba-configuring-cmdline}
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 following command, as `root`:
~]# **systemctl restart smb.service**
To specify the Windows workgroup and a brief description of the Samba server, edit the following lines in your `/etc/samba/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 `/etc/samba/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.
#### 12\.1.4.3. Encrypted Passwords {#s3-samba-encrypted-passwords}
Encrypted passwords are enabled by default because it is more secure to use them. To create a user with an encrypted password, use the command **smbpasswd -a _`username`_**.
### 12\.1.5. Starting and Stopping Samba {#s2-samba-startstop}
To start a Samba server, type the following command in a shell prompt, as `root`:
~]# **systemctl start smb.service**
### Setting up a domain member server
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. Also, it is recommended to run `winbind` before `smbd`.
To stop the server, type the following command in a shell prompt, as `root`:
~]# **systemctl stop smb.service**
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, as `root`:
~]# **systemctl restart smb.service**
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.
### Applying the changes to the configuration
When the `/etc/samba/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`:
~]# **systemctl condrestart smb.service**
A manual reload of the `/etc/samba/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`:
**systemctl reload smb.service**
By default, the **smb** service does _not_ start automatically at boot time. To configure Samba to start at boot time, type the following at a shell prompt as `root`:
~]# **systemctl enable smb.service**
See [Chapter 6, _Services and Daemons_](#ch-Services_and_Daemons "Chapter 6. Services and Daemons") for more information regarding this tool.
### 12\.1.6. Samba Server Types and the `smb.conf` File {#s2-samba-servers}
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 `/etc/samba/smb.conf` file for a successful configuration.
#### 12\.1.6.1. Stand-alone Server {#s3-samba-standalone}
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 12.1.7, “Samba Security Modes”](#s2-samba-security-modes "12.1.7. Samba Security Modes").
##### 12\.1.6.1.1. Anonymous Read-Only {#s4-samba-standalone-anonreadonly}
The following `/etc/samba/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 `/etc/samba/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
##### 12\.1.6.1.2. Anonymous Read/Write {#s4-samba-standalone-anonreadwrite}
The following `/etc/samba/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.
### Do not use anonymous read/write servers
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 `/etc/samba/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
##### 12\.1.6.1.3. Anonymous Print Server {#s4-samba-standalone-anonprint}
The following `/etc/samba/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
##### 12\.1.6.1.4. Secure Read/Write File and Print Server {#s4-samba-standalone-readwriteall}
The following `/etc/samba/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
#### 12\.1.6.2. Domain Member Server {#s3-samba-domain-member}
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.
##### 12\.1.6.2.1. Active Directory Domain Member Server {#s4-samba-domain-member-ads}
The following `/etc/samba/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/2008 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 `/etc/samba/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/2008 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.
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.
### The security option
Since **security = ads** and not **security = user** is used, a local password back end 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.
##### 12\.1.6.2.2. Windows NT4-based Domain Member Server {#s4-samba-domain-member-nt4}
The following `/etc/samba/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 `/etc/samba/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 `/etc/samba/smb.conf` file to convert the server to a Samba-based PDC. If Windows NT-based servers are upgraded to Windows 2000/2003/2008, the `/etc/samba/smb.conf` file is easily modifiable to incorporate the infrastructure change to Active Directory if needed.
### Make sure you join the domain before starting Samba
After configuring the `/etc/samba/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 `/etc/samba/smb.conf` file instead of it being stated explicitly.
#### 12\.1.6.3. Domain Controller {#s3-samba-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.
### A mixed Samba/Windows domain controller environment
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.
##### 12\.1.6.3.1. Primary Domain Controller (PDC) using **tdbsam** {#s4-samba-pdc-tdbsam}
The simplest and most common implementation of a Samba PDC uses the new default **tdbsam** password database back end. Replacing the aging **smbpasswd** back end, **tdbsam** has numerous improvements that are explained in more detail in [Section 12.1.8, “Samba Account Information Databases”](#s2-samba-account-info-dbs "12.1.8. Samba Account Information Databases"). The **passdb backend** directive controls which back end is to be used for the PDC.
The following `/etc/samba/smb.conf` file shows a sample configuration needed to implement a **tdbsam** password database back end.
[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 ... ...
To provide a functional PDC system which uses the **tdbsam** follow these steps:
1. Use a configuration of the `smb.conf` file as shown in the example above.
1. Add the `root` user to the Samba password database:
**smbpasswd -a root**
1. Start the **smb** service.
1. Make sure all profile, user, and netlogon directories are created.
1. Add groups that users can be members of:
**groupadd -f users**
**groupadd -f nobody**
**groupadd -f ntadmins**
1. Associate the UNIX groups with their respective Windows groups:
**net groupmap add ntgroup="Domain Users" unixgroup=users**
**net groupmap add ntgroup="Domain Guests" unixgroup=nobody**
**net groupmap add ntgroup="Domain Admins" unixgroup=ntadmins**
1. Grant access rights to a user or a group. For example, to grant the right to add client machines to the domain on a Samba domain controller, to the members to the Domain Admins group, execute the following command:
**net rpc rights grant 'DOCS\Domain Admins' SetMachineAccountPrivilege -S PDC -U root**
Keep in mind that Windows systems prefer to have a primary group which is mapped to a domain group such as Domain Users.
Windows groups and users use the same namespace thus not allowing the existence of a group and a user with the same name like in UNIX.
### Limitations of the tdbsam authentication back end
If you need more than one domain controller or have more than 250 users, do _not_ use a **tdbsam** authentication back end. LDAP is recommended in these cases.
##### 12\.1.6.3.2. Primary Domain Controller (PDC) with Active Directory {#samba-rgs-pdc-ads}
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.
### 12\.1.7. Samba Security Modes {#s2-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__.
#### 12\.1.7.1. User-Level Security {#s3-samba-user-level}
User-level security is the default setting for Samba. Even if the **security = user** directive is not listed in the `/etc/samba/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 the `/etc/samba/smb.conf` file, the **security = user** directive that sets user-level security is:
[GLOBAL]
...
security = user
...
The following sections describe other implementations of user-level security.
##### 12\.1.7.1.1. Domain Security Mode (User-Level Security) {#s3-samba-domain-security-mode}
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 the `/etc/samba/smb.conf` file:
[GLOBAL]
...
security = domain
workgroup = MARKETING
...
##### 12\.1.7.1.2. Active Directory Security Mode (User-Level Security) {#s3-samba-ads-security-mode}
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 the `/etc/samba/smb.conf` file, the following directives make Samba an Active Directory member server:
[GLOBAL]
...
security = ADS
realm = EXAMPLE.COM
password server = kerberos.example.com
...
##### 12\.1.7.1.3. Server Security Mode (User-Level Security) {#s3-samba-server-security-mode}
Server security mode was previously used when Samba was not capable of acting as a domain member server.
### Avoid using the server security mode
It is highly recommended to _not_ use this mode since there are numerous security drawbacks.
In the `/etc/samba/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"
...
#### 12\.1.7.2. Share-Level Security {#s3-samba-share-level}
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 the `/etc/samba/smb.conf` file, the **security = share** directive that sets share-level security is:
[GLOBAL]
...
security = share
...
### 12\.1.8. Samba Account Information Databases {#s2-samba-account-info-dbs}
The latest release of Samba offers many new features including new password database back ends not previously available. Samba version 3.0.0 fully supports all databases used in previous versions of Samba. However, although supported, many back ends may not be suitable for production use.
The following is a list different back ends you can use with Samba. Other back ends not listed here may also be available.
Plain Text
: Plain text back ends are nothing more than the **/etc/passwd** type back ends. With a plain text back end, 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 back end used in previous Samba packages, the **smbpasswd** back end utilizes a plain ASCII text layout that includes the MS Windows LanMan and NT account, and encrypted password information. The **smbpasswd** back end lacks the storage of the Windows NT/2000/2003 SAM extended controls. The **smbpasswd** back end is not recommended because it does not scale well or hold any Windows information, such as RIDs for NT-based groups. The **tdbsam** back end solves these issues for use in a smaller database (250 users), but is still not an enterprise-class solution.
**ldapsam\_compat**
: The **ldapsam\_compat** back end allows continued OpenLDAP support for use with upgraded versions of Samba. This option is normally used when migrating to Samba 3.0.
**tdbsam**
: The new default **tdbsam** password back end provides an ideal database back end 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** back end 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/2008-based systems.
The **tdbsam** back end 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** back end 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 such as an OpenLDAP Server. LDAP databases are light-weight and scalable, and as such are preferred by large enterprises. For more information on LDAP, refer to [Section 11.1, “OpenLDAP”](#s1-OpenLDAP "11.1. OpenLDAP").
If you are upgrading from a previous version of Samba to 3.0, note that the OpenLDAP schema file (`/usr/share/doc/samba/LDAP/samba.schema`) has changed. These files contain the _attribute syntax definitions_ and _objectclass definitions_ that the **ldapsam** back end needs in order to function properly.
As such, if you are using the **ldapsam** back end for your Samba server, you will need to configure **slapd** to include one of these schema file. See [Section 11.1.3.3, “Extending Schema”](#s3-ldap-configuration-schema "11.1.3.3. Extending Schema") for directions on how to do this.
### Make sure the openldap-server package is installed
You need to have the `openldap-server` package installed if you want to use the **ldapsam** back end.
### 12\.1.9. Samba Network Browsing {#s2-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.
#### 12\.1.9.1. Domain Browsing {#s3-samba-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 `/etc/samba/smb.conf` file for a local master browser (or no browsing at all) in a domain controller environment is the same as workgroup configuration (see [Section 12.1.4, “Configuring a Samba Server”](#s2-samba-configuring "12.1.4. Configuring a Samba Server")).
#### 12\.1.9.2. WINS (Windows Internet Name Server) {#s3-samba-wins}
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/2008 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 `/etc/samba/smb.conf` file in which the Samba server is serving as a WINS server:
[global]
wins support = Yes
### Using WINS
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.
### 12\.1.10. Samba with CUPS Printing Support {#s2-samba-cups}
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.
#### 12\.1.10.1. Simple `smb.conf` Settings {#s3-samba-cups-smb.conf}
The following example shows a very basic `/etc/samba/smb.conf` configuration for CUPS support:
[global]
load printers = Yes
printing = cups
printcap name = cups
[printers]
comment = All Printers
path = /var/spool/samba
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$** directive contains printer drivers for clients to access if not available locally. The **print$** directive 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.
### 12\.1.11. Samba Distribution Programs {#s2-samba-programs}
#### `findsmb` {#s3-samba-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` {#s3-samba-programs-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/2008 uses **rpc**. If the protocol is omitted, **net** automatically tries to determine it.
The following example displays a list of 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` {#s3-samba-programs-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.
The following example displays the `IP` address of the NetBIOS name `trek`:
**`~]$ nmblookup trek`**
querying trek on 10.1.59.255
10.1.56.45 trek<00>
#### `pdbedit` {#s3-samba-programs-pdbedit}
**pdbedit _`options`_**
The **pdbedit** program manages accounts located in the SAM database. All back ends are supported including `smbpasswd`, LDAP, 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` {#s3-samba-programs-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` {#s3-samba-programs-smbcacls}
**smbcacls _`//server/share filename options`_**
The **smbcacls** program modifies Windows ACLs on files and directories shared by a Samba server or a Windows server.
#### `smbclient` {#s3-samba-programs-smbclient}
**smbclient _`//server/share password options`_**
The **smbclient** program is a versatile UNIX client which provides functionality similar to **ftp**.
#### `smbcontrol` {#s3-samba-programs-smbcontrol}
**smbcontrol -i _`options`_**
**smbcontrol _`options destination messagetype parameters`_**
The **smbcontrol** program sends control messages to running **smbd**, **nmbd**, or **winbindd** daemons. Executing **smbcontrol -i** runs commands interactively until a blank line or a _`'q'`_ is entered.
#### `smbpasswd` {#s3-samba-programs-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 and also by an ordinary user to change their own Samba password.
#### `smbspool` {#s3-samba-programs-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` {#s3-samba-programs-smbstatus}
**smbstatus _`options`_**
The **smbstatus** program displays the status of current connections to a Samba server.
#### `smbtar` {#s3-samba-programs-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` {#s3-samba-programs-testparm}
**testparm _`options filename hostname IP_address`_**
The **testparm** program checks the syntax of the `/etc/samba/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 host name 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 `/etc/samba/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
**``**
# 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` {#s3-samba-programs-wbinfo}
**wbinfo _`options`_**
The **wbinfo** program displays information from the **winbindd** daemon. The **winbindd** daemon must be running for **wbinfo** to work.
### 12\.1.12. Additional Resources {#s2-samba-resources}
The following sections give you the means to explore Samba in greater detail.
#### 12\.1.12.1. Installed Documentation {#s3-samba-resources-installed}
* `/usr/share/doc/samba/` — All additional files included with the Samba distribution. This includes all helper scripts, sample configuration files, and documentation.
See the following manual pages for detailed information about Samba:
* **smb.conf**
* **samba**
* **smbd**
* **nmbd**
* **winbind**
#### 12\.1.12.2. Related Books {#s3-samba-resources-published}
* _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.
#### 12\.1.12.3. Useful Websites {#s3-samba-resources-community}
* — 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 ](http://us1.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 [www.gmane.org](http://www.gmane.org/), that use the `NNTP` protocol are also available. This an alternative to receiving mailing list emails.
## 12\.2. FTP {#s1-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 section outlines the basics of the `FTP` protocol, as well as configuration options for the primary `FTP` server shipped with Fedora, **vsftpd**.
### 12\.2.1. The File Transfer Protocol {#s2-ftp-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\.2.1.1. Multiple Ports, Multiple Modes {#s3-ftp-protocol-multiport}
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. See [Section 12.2.5.8, “Network Options”](#s3-ftp-vsftpd-conf-opt-net "12.2.5.8. Network Options") for more information about limiting passive ports.
### 12\.2.2. FTP Servers {#s2-ftp-servers}
Fedora ships with two different `FTP` servers:
* **proftpd** - A fast, stable, and highly configurable FTP server.
* **vsftpd** — A fast, secure `FTP` daemon which is the preferred `FTP` server for Fedora. The remainder of this section focuses on **vsftpd**.
#### 12\.2.2.1. **vsftpd** {#s3-ftp-servers-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\.2.3. Files Installed with **vsftpd** {#s3-ftp-vsftpd-conf}
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 **systemctl** command to start, stop, or reload **vsftpd**. See [Section 12.2.4, “Starting and Stopping **vsftpd** ”](#s2-ftp-vsftpd-start "12.2.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 on PAM, refer to the _Using Pluggable Authentication Modules (PAM)_ chapter of the Fedora 20 _Managing Single Sign-On and Smart Cards_ guide.
* `/etc/vsftpd/vsftpd.conf` — The configuration file for **vsftpd**. See [Section 12.2.5, “ **vsftpd** Configuration Options”](#s2-ftp-vsftpd-conf "12.2.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\.2.4. Starting and Stopping **vsftpd** {#s2-ftp-vsftpd-start}
The `vsftpd` RPM installs the `/etc/rc.d/init.d/vsftpd` script, which can be accessed using the **systemctl** command.
To start the server, as `root` type:
**systemctl start vsftpd.service**
To stop the server, as `root` type:
**systemctl stop vsftpd.service**
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:
**systemctl restart vsftpd.service**
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:
**systemctl condrestart vsftpd.service**
By default, the **vsftpd** service does _not_ start automatically at boot time. To configure the **vsftpd** service to start at boot time, use a service manager such as **systemctl**. See [Chapter 6, _Services and Daemons_](#ch-Services_and_Daemons "Chapter 6. Services and Daemons") for more information on how to configure services in Fedora.
#### 12\.2.4.1. Starting Multiple Copies of **vsftpd** {#s3-ftp-vsftpd-start-multi}
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. For more information about configuring network devices, device aliases, and additional information about network configuration scripts, refer to the _Red Hat Enterprise Linux 7 Networking Guide_.
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 the _Red Hat Enterprise Linux 7 Networking Guide_.
If there is more configuration files present in the `/etc/vsftpd` directory, calling **systemctl start vsftpd.service** results in the `/etc/rc.d/init.d/vsftpd` initscript starting the same number of processes as the number of configuration files. Each configuration file must have a unique name in the `/etc/vsftpd/` directory and must be readable and writable only by `root`.
### 12\.2.5. **vsftpd** Configuration Options {#s2-ftp-vsftpd-conf}
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.
### Do not use spaces
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 sign (**\#**) and are ignored by the daemon.
For a complete list of all directives available, refer to the man page for `vsftpd.conf`.
### Securing the vsftpd service
For an overview of ways to secure **vsftpd**, refer to the Fedora 20 _Security Guide_.
The following is a list of some of the more important directives within `/etc/vsftpd/vsftpd.conf`. All directives not explicitly found or commented out within **vsftpd**'s configuration file are set to their default value.
#### 12\.2.5.1. Daemon Options {#s3-ftp-vsftpd-conf-opt-daemon}
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). For more information, refer to the _Using Pluggable Authentication Modules (PAM)_ chapter of the Red Hat Enterprise Linux 6 _Managing Single Sign-On and Smart Cards_ and the PAM man pages. . 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\.2.5.2. Log In Options and Access Controls {#s3-ftp-vsftpd-conf-opt-login}
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**.
See [Section 12.2.5.3, “Anonymous User Options”](#s3-ftp-vsftpd-conf-opt-anon "12.2.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**.
See [Section 12.2.5.4, “Local User Options”](#s3-ftp-vsftpd-conf-opt-usr "12.2.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\.2.5.3. Anonymous User Options {#s3-ftp-vsftpd-conf-opt-anon}
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\.2.5.4. Local User Options {#s3-ftp-vsftpd-conf-opt-usr}
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**.
### Avoid enabling the chroot\_local\_user option
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\.2.5.5. Directory Options {#s3-ftp-vsftpd-conf-opt-dir}
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, text 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\.2.5.6. File Transfer Options {#s3-ftp-vsftpd-conf-opt-file}
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\.2.5.7. Logging Options {#s3-ftp-vsftpd-conf-opt-log}
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**.
### Maintaining compatibility with older log file formats
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 sign (**\#**), or delete the line entirely.
#### 12\.2.5.8. Network Options {#s3-ftp-vsftpd-conf-opt-net}
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 ****, 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.
### Running multiple copies of vsftpd
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. See [Section 12.2.4.1, “Starting Multiple Copies of **vsftpd** ”](#s3-ftp-vsftpd-start-multi "12.2.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.
### Running multiple copies of vsftpd
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. See [Section 12.2.4.1, “Starting Multiple Copies of **vsftpd** ”](#s3-ftp-vsftpd-start-multi "12.2.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 ****, 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 ****, 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 ****, 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 ****, 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 ****, 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.
### Avoid enabling the pasv\_promiscuous option
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\.2.6. Additional Resources {#s2-ftp-resources}
For more information about **vsftpd**, refer to the following resources.
#### 12\.2.6.1. Installed Documentation {#s3-ftp-installed-documentation}
* The `/usr/share/doc/vsftpd/` directory — 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\.2.6.2. Useful Websites {#s3-ftp-useful-websites}
* — The **vsftpd** project page is a great place to locate the latest documentation and to contact the author of the software.
* — This website provides a concise explanation of the differences between active and passive mode `FTP`.
* — The original _Request for Comments_ (_RFC_) of the `FTP` protocol from the IETF.
## 12\.3. Printer Configuration {#sec-Printer_Configuration}
The Printer Configuration tool serves for printer configuring, maintenance of printer configuration files, print spool directories and print filters, and printer classes management.
The tool is based on the Common Unix Printing System (CUPS). If you upgraded the system from a previous Fedora version that used CUPS, the upgrade process preserved the configured printers.
### Using the CUPS web application or command line tools
You can perform the same and additional operations on printers directly from the CUPS web application or command line. To access the application, in a web browser, go to . For CUPS manuals refer to the links on the Home tab of the web site.
### 12\.3.1. Starting the Printer Configuration Tool {#sec-Starting_Printer_Config}
With the Printer Configuration tool you can perform various operations on existing printers and set up new printers.
On the upper panel, go to Activities, choose Applications and click Printing. Alternatively, run the **system-config-printer** command from the command line to start the tool.
The Printer Configuration window depicted in [Figure 12.2, “Printer Configuration window”](#fig-printconf-main "Figure 12.2. Printer Configuration window") appears.
Figure 12.2. Printer Configuration window
![Printer Configuration window][47]
[[D](ld-idm31992768.html)]
### 12\.3.2. Starting Printer Setup {#sec-Setting_Printer}
Printer setup process varies depending on the printer queue type.
If you are setting up a local printer connected with USB, the printer is discovered and added automatically. You will be prompted to confirm the packages to be installed and provide the root password. Local printers connected with other port types and network printers need to be set up manually.
Follow this procedure to start a manual printer setup:
1. Start the Printer Configuration tool (refer to [Section 12.3.1, “Starting the Printer Configuration Tool”](#sec-Starting_Printer_Config "12.3.1. Starting the Printer Configuration Tool")).
1. Go to Server → New → Printer.
1. In the Authentication Required box, type the root user password and confirm.
1. Select the printer connection type and provide its details in the area on the right.
### 12\.3.3. Adding a Local Printer {#sec-Adding_Other_Printer}
Follow this procedure to add a local printer connected with other than a serial port:
1. Open the `New Printer` dialog (refer to [Section 12.3.2, “Starting Printer Setup”](#sec-Setting_Printer "12.3.2. Starting Printer Setup")).
1. If the device does not appear automatically, select the port to which the printer is connected in the list on the left (such as Serial Port #1 or LPT #1).
1. On the right, enter the connection properties:
for Enter URI
: URI (for example file:/dev/lp0)
for Serial Port
: Baud Rate
Parity
Data Bits
Flow Control
Figure 12.3. Adding a local printer
![Adding a local printer][48]
[[D](ld-idm30108016.html)]
1. Click Forward.
1. Select the printer model. See [Section 12.3.8, “Selecting the Printer Model and Finishing”](#s1-printing-select-model "12.3.8. Selecting the Printer Model and Finishing") for details.
### 12\.3.4. Adding an AppSocket/HP JetDirect printer {#s1-printing-jetdirect-printer}
Follow this procedure to add an AppSocket/HP JetDirect printer:
1. Open the `New Printer` dialog (refer to [Section 12.3.1, “Starting the Printer Configuration Tool”](#sec-Starting_Printer_Config "12.3.1. Starting the Printer Configuration Tool")).
1. In the list on the left, select Network Printer → AppSocket/HP JetDirect.
1. On the right, enter the connection settings:
Hostname
: printer hostname or IP address
Port Number
: printer port listening for print jobs (`9100` by default)
Figure 12.4. Adding a JetDirect printer
![Adding a JetDirect printer][49]
[[D](ld-idm75968224.html)]
1. Click Forward.
1. Select the printer model. See [Section 12.3.8, “Selecting the Printer Model and Finishing”](#s1-printing-select-model "12.3.8. Selecting the Printer Model and Finishing") for details.
### 12\.3.5. Adding an IPP Printer {#s1-printing-ipp-printer}
An IPP printer is a printer attached to a different system on the same TCP/IP network. The system this printer is attached to may either be running CUPS or simply configured to use IPP.
If a firewall is enabled on the printer server, then the firewall must be configured to allow incoming TCP connections on port 631. Note that the CUPS browsing protocol allows client machines to discover shared CUPS queues automatically. To enable this, the firewall on the client machine must be configured to allow incoming UDP packets on port 631.
Follow this procedure to add an IPP printer:
1. Open the `New Printer` dialog (refer to [Section 12.3.2, “Starting Printer Setup”](#sec-Setting_Printer "12.3.2. Starting Printer Setup")).
1. In the list of devices on the left, select Network Printer and Internet Printing Protocol (ipp) or Internet Printing Protocol (https).
1. On the right, enter the connection settings:
Host
: the hostname for the system that controls the printer
Queue
: the queue name to be given to the new queue (if the box is left empty, a name based on the device node will be used)
Figure 12.5. Adding an IPP printer
![Adding an IPP printer][50]
[[D](ld-idm120533616.html)]
1. Optionally, click Verify to detect the printer.
1. Click Forward to continue.
1. Select the printer model. See [Section 12.3.8, “Selecting the Printer Model and Finishing”](#s1-printing-select-model "12.3.8. Selecting the Printer Model and Finishing") for details.
### 12\.3.6. Adding an LPD/LPR Host or Printer {#sec-printing-LPDLPR-printer}
Follow this procedure to add an LPD/LPR host or printer:
1. Open the `New Printer` dialog (refer to [Section 12.3.2, “Starting Printer Setup”](#sec-Setting_Printer "12.3.2. Starting Printer Setup")).
1. In the list of devices on the left, select Network Printer → LPD/LPR Host or Printer.
1. On the right, enter the connection settings:
Host
: the hostname of the LPD/LPR printer or host
Optionally, click Probe to find queues on the LPD host.
Queue
: the queue name to be given to the new queue (if the box is left empty, a name based on the device node will be used)
Figure 12.6. Adding an LPD/LPR printer
![Adding an LPD/LPR printer][51]
[[D](ld-idm17868992.html)]
1. Click Forward to continue.
1. Select the printer model. See [Section 12.3.8, “Selecting the Printer Model and Finishing”](#s1-printing-select-model "12.3.8. Selecting the Printer Model and Finishing") for details.
### 12\.3.7. Adding a Samba (SMB) printer {#s1-printing-smb-printer}
Follow this procedure to add a Samba printer:
### Installing the samba-client package
Note that in order to add a Samba printer, you need to have the samba-client package installed. You can do so by running, as `root`:
**yum install samba-client**
For more information on installing packages with Yum, refer to [Section 5.2.4, “Installing Packages”](#sec-Installing "5.2.4. Installing Packages").
1. Open the `New Printer` dialog (refer to [Section 12.3.2, “Starting Printer Setup”](#sec-Setting_Printer "12.3.2. Starting Printer Setup")).
1. In the list on the left, select Network Printer → Windows Printer via SAMBA.
1. Enter the SMB address in the smb:// field. Use the format _`computer name/printer share`_. In [Figure 12.7, “Adding a SMB printer”](#fig-printconf-smb "Figure 12.7. Adding a SMB printer"), the _`computer name`_ is **dellbox** and the _`printer share`_ is **r2**.
Figure 12.7. Adding a SMB printer
![Adding a SMB printer][52]
[[D](ld-idm17824496.html)]
1. Click Browse to see the available workgroups/domains. To display only queues of a particular host, type in the host name (NetBios name) and click Browse.
1. Select either of the options:
* Prompt user if authentication is required: username and password are collected from the user when printing a document.
* Set authentication details now: provide authentication information now so it is not required later. In the Username field, enter the username to access the printer. This user must exist on the SMB system, and the user must have permission to access the printer. The default user name is typically **`guest`** for Windows servers, or **`nobody`** for Samba servers.
1. Enter the Password (if required) for the user specified in the Username field.
### Be careful when choosing a password
Samba printer usernames and passwords are stored in the printer server as unencrypted files readable by root and lpd. Thus, other users that have root access to the printer server can view the username and password you use to access the Samba printer.
As such, when you choose a username and password to access a Samba printer, it is advisable that you choose a password that is different from what you use to access your local Fedora system.
If there are files shared on the Samba print server, it is recommended that they also use a password different from what is used by the print queue.
1. Click Verify to test the connection. Upon successful verification, a dialog box appears confirming printer share accessibility.
1. Click Forward.
1. Select the printer model. See [Section 12.3.8, “Selecting the Printer Model and Finishing”](#s1-printing-select-model "12.3.8. Selecting the Printer Model and Finishing") for details.
### 12\.3.8. Selecting the Printer Model and Finishing {#s1-printing-select-model}
Once you have properly selected a printer connection type, the system attempts to acquire a driver. If the process fails, you can locate or search for the driver resources manually.
Follow this procedure to provide the printer driver and finish the installation:
1. In the window displayed after the automatic driver detection has failed, select one of the following options:
* Select printer from database — the system chooses a driver based on the selected make of your printer from the list of Makes. If your printer model is not listed, choose Generic.
* Provide PPD file — the system uses the provided PostScript Printer Description (PPD) file for installation. A PPD file may also be delivered with your printer as being normally provided by the manufacturer. If the PPD file is available, you can choose this option and use the browser bar below the option description to select the PPD file.
* Search for a printer driver to download — enter the make and model of your printer into the Make and model field to search on OpenPrinting.org for the appropriate packages.
Figure 12.8. Selecting a printer brand
![Selecting a printer brand][53]
[[D](ld-idm19856880.html)]
1. Depending on your previous choice provide details in the area displayed below:
* Printer brand for the Select printer from database option
* PPD file location for the Provide PPD file option
* Printer make and model for the Search for a printer driver to download option
1. Click Forward to continue.
1. If applicable for your option, window shown in [Figure 12.9, “Selecting a printer model”](#fig-printconf-select-driver "Figure 12.9. Selecting a printer model") appears. Choose the corresponding model in the Models column on the left.
### Selecting a printer driver
On the right, the recommended printed driver is automatically selected; however, you can select another available driver. The print driver processes the data that you want to print into a format the printer can understand. Since a local printer is attached directly to your computer, you need a printer driver to process the data that is sent to the printer.
Figure 12.9. Selecting a printer model
![Selecting a printer model][54]
[[D](ld-idm66766544.html)]
1. Click Forward.
1. Under the `Describe Printer` enter a unique name for the printer in the Printer Name field. The printer name can contain letters, numbers, dashes (-), and underscores (\_); it _must not_ contain any spaces. You can also use the Description and Location fields to add further printer information. Both fields are optional, and may contain spaces.
Figure 12.10. Printer setup
![Printer setup][55]
[[D](ld-mediaobj-printconf-add-printer.html)]
1. Click Apply to confirm your printer configuration and add the print queue if the settings are correct. Click Back to modify the printer configuration.
1. After the changes are applied, a dialog box appears allowing you to print a test page. Click Print Test Page to print a test page now. Alternatively, you can print a test page also later, refer to [Section 12.3.9, “Printing a test page”](#s1-printing-test-page "12.3.9. Printing a test page") for details.
### 12\.3.9. Printing a test page {#s1-printing-test-page}
After you have set up a printer or changed a printer configuration, print a test page to make sure the printer is functioning properly:
1. Right-click the printer in the Printing window and click Properties.
1. In the Properties window, click Settings on the left.
1. On the displayed Settings tab, click the Print Test Page button.
### 12\.3.10. Modifying Existing Printers {#s1-printing-edit}
To delete an existing printer, in the Printer Configuration window, select the printer and go to Printer → Delete. Confirm the printer deletion. Alternatively, press the **Delete** key.
To set the default printer, right-click the printer in the printer list and click the Set As Default button in the context menu.
#### 12\.3.10.1. The Settings Page {#idm104586688}
To change printer driver configuration, double-click the corresponding name in the Printer list and click the Settings label on the left to display the Settings page.
You can modify printer settings such as make and model, print a test page, change the device location (URI), and more.
Figure 12.11. Settings page
![Settings page][56]
[[D](ld-idm17858288.html)]
#### 12\.3.10.2. The Policies Page {#idm36276368}
Click the Policies button on the left to change settings in printer state and print output.
You can select the printer states, configure the Error Policy of the printer (you can decide to abort the print job, retry, or stop it if an error occurs).
You can also create a _banner page_ (a page that describes aspects of the print job such as the originating printer, the username from the which the job originated, and the security status of the document being printed): click the Starting Banner or Ending Banner drop-menu and choose the option that best describes the nature of the print jobs (such as topsecret, classified, or confidential).
##### 12\.3.10.2.1. Sharing Printers {#sec-Sharing_Printers}
On the Policies page, you can mark a printer as shared: if a printer is shared, users published on the network can use it. To allow the sharing function for printers, go to Server → Settings and select Publish shared printers connected to this system.
Finally, ensure that the firewall allows incoming TCP connections to port 631, which is Network Printing Server (IPP) in system-config-firewall.
Figure 12.12. Policies page
![Policies page][57]
[[D](ld-idm76983568.html)]
##### 12\.3.10.2.2. The Access Control Page {#sec-The_Access_Control_Page}
You can change user-level access to the configured printer on the Access Control page. Click the Access Control label on the left to display the page. Select either Allow printing for everyone except these users or Deny printing for everyone except these users and define the user set below: enter the user name in the text box and click the Add button to add the user to the user set.
Figure 12.13. Access Control page
![Access Control page][58]
[[D](ld-idm26661760.html)]
##### 12\.3.10.2.3. The Printer Options Page {#sec-The_Printer_Options_Page}
The Printer Options page contains various configuration options for the printer media and output, and its content may vary from printer to printer. It contains general printing, paper, quality, and printing size settings.
Figure 12.14. Printer Options page
![Printer Options page][59]
[[D](ld-idm124114192.html)]
##### 12\.3.10.2.4. Job Options Page {#sec-Job_Options_Page}
On the Job Options page, you can detail the printer job options. Click the Job Options label on the left to display the page. Edit the default settings to apply custom job options, such as number of copies, orientation, pages per side,scaling (increase or decrease the size of the printable area, which can be used to fit an oversize print area onto a smaller physical sheet of print medium), detailed text options, and custom job options.
Figure 12.15. Job Options page
![Job Options page][60]
[[D](ld-idm109091168.html)]
##### 12\.3.10.2.5. Ink/Toner Levels Page {#sec-Ink_Toner_Levels_Page}
The Ink/Toner Levels page contains details on toner status if available and printer status messages. Click the Ink/Toner Levels label on the left to display the page.
Figure 12.16. Ink/Toner Levels page
![Ink/Toner Levels page][61]
[[D](ld-idm108118208.html)]
#### 12\.3.10.3. Managing Print Jobs {#s1-printing-managing}
When you send a print job to the printer daemon, such as printing a text file from Emacs or printing an image from GIMP, the print job is added to the print spool queue. The print spool queue is a list of print jobs that have been sent to the printer and information about each print request, such as the status of the request, the job number, and more.
During the printing process, messages informing about the process appear in the notification area.
Figure 12.17. GNOME Print Status
![GNOME Print Status][62]
[[D](ld-idm46277648.html)]
To cancel, hold, release, reprint or authenticate a print job, select the job in the GNOME Print Status and on the Job menu, click the respective command.
To view the list of print jobs in the print spool from a shell prompt, type the command **lpstat -o**. The last few lines look similar to the following:
Example 12.1. Example of lpstat -o output
$ **lpstat -o**
Charlie-60 twaugh 1024 Tue 08 Feb 2011 16:42:11 GMT
Aaron-61 twaugh 1024 Tue 08 Feb 2011 16:42:44 GMT
Ben-62 root 1024 Tue 08 Feb 2011 16:45:42 GMT
If you want to cancel a print job, find the job number of the request with the command **lpstat -o** and then use the command **cancel _`job number`_**. For example, **cancel 60** would cancel the print job in [Example 12.1, “Example of lpstat -o output”](#lpq-example "Example 12.1. Example of lpstat -o output"). You cannot cancel print jobs that were started by other users with the **cancel** command. However, you can enforce deletion of such job by issuing the **cancel -U root _`job_number`_** command. To prevent such canceling, change the printer operation policy to `Authenticated` to force root authentication.
You can also print a file directly from a shell prompt. For example, the command **lp sample.txt** prints the text file `sample.txt`. The print filter determines what type of file it is and converts it into a format the printer can understand.
### 12\.3.11. Additional Resources {#s1-printing-additional-resources}
To learn more about printing on Fedora, refer to the following resources.
#### 12\.3.11.1. Installed Documentation {#s2-printing-additional-resources-installed}
**man lp**
: The manual page for the **lpr** command that allows you to print files from the command line.
**man cancel**
: The manual page for the command line utility to remove print jobs from the print queue.
**man mpage**
: The manual page for the command line utility to print multiple pages on one sheet of paper.
**man cupsd**
: The manual page for the CUPS printer daemon.
**man cupsd.conf**
: The manual page for the CUPS printer daemon configuration file.
**man classes.conf**
: The manual page for the class configuration file for CUPS.
**man lpstat**
: The manual page for the **lpstat** command, which displays status information about classes, jobs, and printers.
#### 12\.3.11.2. Useful Websites {#s2-printing-additional-resources-websites}
: _GNU/Linux Printing_ contains a large amount of information about printing in Linux.
: Documentation, FAQs, and newsgroups about CUPS.
## Chapter 13. Configuring NTP Using the chrony Suite {#ch-Configuring_NTP_Using_the_chrony_Suite}
Accurate time keeping is important for a number of reasons in IT. In networking for example, accurate time stamps in packets and logs are required. In Linux systems, the `NTP` protocol is implemented by a daemon running in user space.
The user space daemon updates the system clock running in the kernel. The system clock can keep time by using various clock sources. Usually, the _Time Stamp Counter_ (TSC) is used. The TSC is a CPU register which counts the number of cycles since it was last reset. It is very fast, has a high resolution, and there are no interrupts.
There is a choice between the daemons `ntpd` and `chronyd`, which are available from the repositories in the ntp and chrony packages respectively. This section describes the use of the chrony suite of utilities to update the system clock on systems that do not fit into the conventional permanently networked, always on, dedicated server category.
## 13\.1. Introduction to the chrony Suite {#sect-Introduction_to_the_chrony_Suite}
Chrony consists of `chronyd`, a daemon that runs in user space, and chronyc, a command line program for making adjustments to `chronyd`. Systems which are not permanently connected, or not permanently powered up, take a relatively long time to adjust their system clocks with `ntpd`. This is because many small corrections are made based on observations of the clocks drift and offset. Temperature changes, which may be significant when powering up a system, affect the stability of hardware clocks. Although adjustments begin within a few milliseconds of booting a system, acceptable accuracy may take anything from ten seconds from a warm restart to a number of hours depending on your requirements, operating environment and hardware. chrony is a different implementation of the `NTP` protocol than `ntpd`, it can adjust the system clock more rapidly.
### 13\.1.1. Differences Between ntpd and chronyd {#sect-differences_between_ntpd_and_chronyd}
One of the main differences between `ntpd` and `chronyd` is in the algorithms used to control the computer's clock. Things `chronyd` can do better than `ntpd` are:
* `chronyd` can work well when external time references are only intermittently accessible, whereas `ntpd` needs regular polling of time reference to work well.
* `chronyd` can perform well even when the network is congested for longer periods of time.
* `chronyd` can usually synchronize the clock faster and with better time accuracy.
* `chronyd` quickly adapts to sudden changes in the rate of the clock, for example, due to changes in the temperature of the crystal oscillator, whereas `ntpd` may need a long time to settle down again.
* In the default configuration, `chronyd` never steps the time after the clock has been synchronized at system start, in order not to upset other running programs. `ntpd` can be configured to never step the time too, but it has to use a different means of adjusting the clock, which has some disadvantages.
* `chronyd` can adjust the rate of the clock on a Linux system in a larger range, which allows it to operate even on machines with a broken or unstable clock. For example, on some virtual machines.
Things `chronyd` can do that `ntpd` cannot do:
* `chronyd` provides support for isolated networks where the only method of time correction is manual entry. For example, by the administrator looking at a clock. `chronyd` can examine the errors corrected at different updates to estimate the rate at which the computer gains or loses time, and use this estimate to trim the computer clock subsequently.
* `chronyd` provides support to work out the rate of gain or loss of the real-time clock, the hardware clock, that maintains the time when the computer is turned off. It can use this data when the system boots to set the system time using an adjusted value of the time taken from the real-time clock. This is, at time of writing, only available in Linux.
Things `ntpd` can do that `chronyd` cannot do:
* `ntpd` fully supports `NTP` version 4 (_RFC 5905_), including broadcast, multicast, manycast clients and servers, and the orphan mode. It also supports extra authentication schemes based on public-key cryptography (_RFC 5906_). `chronyd` uses `NTP` version 3 (_RFC 1305_), which is compatible with version 4.
* `ntpd` includes drivers for many reference clocks whereas `chronyd` relies on other programs, for example gpsd, to access the data from the reference clocks.
### 13\.1.2. Choosing Between NTP Daemons {#sect-Choosing_between_NTP_daemon}
* Chrony should be considered for all systems which are frequently suspended or otherwise intermittently disconnected and reconnected to a network. Mobile and virtual systems for example.
* The `NTP` daemon (`ntpd`) should be considered for systems which are normally kept permanently on. Systems which are required to use broadcast or multicast `IP`, or to perform authentication of packets with the `Autokey` protocol, should consider using `ntpd`. Chrony only supports symmetric key authentication using a message authentication code (MAC) with MD5, SHA1 or stronger hash functions, whereas `ntpd` also supports the `Autokey` authentication protocol which can make use of the PKI system. `Autokey` is described in _RFC 5906_.
## 13\.2. Understanding chrony and Its Configuration {#sect-Understanding_chrony_and-its_configuration}
### 13\.2.1. Understanding chronyd {#sect-Understanding_chronyd}
The chrony daemon, `chronyd`, running in user space, makes adjustments to the system clock which is running in the kernel. It does this by consulting external time sources, using the `NTP` protocol, when ever network access allows it to do so. When external references are not available, `chronyd` will use the last calculated drift stored in the drift file. It can also be commanded manually to make corrections, by chronyc.
### 13\.2.2. Understanding chronyc {#sect-Understanding_chronyc}
The chrony daemon, `chronyd`, can be controlled by the command line utility chronyc. This utility provides a command prompt which allows entering of a number of commands to make changes to `chronyd`. The default configuration is for `chronyd` to only accept commands from a local instance of chronyc, but chronyc can be used to alter the configuration so that `chronyd` will allow external control. chronyc can be run remotely after first configuring `chronyd` to accept remote connections. The `IP` addresses allowed to connect to `chronyd` should be tightly controlled.
### 13\.2.3. Understanding the chrony Configuration Commands {#sect-Understanding_the_chrony_configuration_commands}
The default configuration file for `chronyd` is `/etc/chrony.conf`. The `-f` option can be used to specify an alternate configuration file path. See the `chronyd` man page for further options. For a complete list of the directives that can be used see [_http://chrony.tuxfamily.org/manual.html#Configuration-file_](http://chrony.tuxfamily.org/manual.html#Configuration-file). Below is a selection of configuration options:
Comments
: Comments should be preceded by #, %, ; or !
allow
: Optionally specify a host, subnet, or network from which to allow `NTP` connections to a machine acting as `NTP` server. The default is not to allow connections.
Examples:
1. allow server1.example.com
Use this form to specify a particular host, by its host name, to be allowed access.
1. allow 192.0.2.0/24
Use this form to specify a particular network to be allowed access.
1. allow 2001:db8::/32
Use this form to specify an `IPv6` address to be allowed access.
cmdallow
: This is similar to the **allow** directive (see section **allow**), except that it allows control access (rather than `NTP` client access) to a particular subnet or host. (By “control access” is meant that chronyc can be run on those hosts and successfully connect to `chronyd` on this computer.) The syntax is identical. There is also a **cmddeny all** directive with similar behavior to the **cmdallow all** directive.
dumpdir
: Path to the directory to save the measurement history across restarts of `chronyd` (assuming no changes are made to the system clock behavior whilst it is not running). If this capability is to be used (via the **dumponexit** command in the configuration file, or the **dump** command in chronyc), the **dumpdir** command should be used to define the directory where the measurement histories are saved.
dumponexit
: If this command is present, it indicates that `chronyd` should save the measurement history for each of its time sources recorded whenever the program exits. (See the **dumpdir** command above).
local
: The **local** keyword is used to allow `chronyd` to appear synchronized to real time (from the viewpoint of clients polling it), even if it has no current synchronization source. This option is normally used on computers in an isolated network, where several computers are required to synchronize to one other, this being the “master” which is kept vaguely in line with real time by manual input.
An example of the command is:
local stratum 10
A large value of 10 indicates that the clock is so many hops away from a reference clock that its time is unreliable. If the computer ever has access to another computer which is ultimately synchronized to a reference clock, it will almost certainly be at a stratum less than 10. Therefore, the choice of a high value like 10 for the **local** command prevents the machine’s own time from ever being confused with real time, were it ever to leak out to clients that have visibility of real servers.
log
: The **log** command indicates that certain information is to be logged. It accepts the following options:
measurements
: This option logs the raw `NTP` measurements and related information to a file called `measurements.log`.
statistics
: This option logs information about the regression processing to a file called `statistics.log`.
tracking
: This option logs changes to the estimate of the system’s gain or loss rate, and any slews made, to a file called `tracking.log`.
rtc
: This option logs information about the system’s real-time clock.
refclocks
: This option logs the raw and filtered reference clock measurements to a file called `refclocks.log`.
tempcomp
: This option logs the temperature measurements and system rate compensations to a file called `tempcomp.log`.
The log files are written to the directory specified by the **logdir** command. An example of the command is:
log measurements statistics tracking
logdir
: This directive allows the directory where log files are written to be specified. An example of the use of this directive is:
logdir /var/log/chrony
makestep
: Normally `chronyd` will cause the system to gradually correct any time offset, by slowing down or speeding up the clock as required. In certain situations, the system clock may be so far adrift that this slewing process would take a very long time to correct the system clock. This directive forces `chronyd` to step system clock if the adjustment is larger than a threshold value, but only if there were no more clock updates since `chronyd` was started than a specified limit (a negative value can be used to disable the limit). This is particularly useful when using reference clocks, because the **initstepslew** directive only works with `NTP` sources.
An example of the use of this directive is:
makestep 1000 10
This would step the system clock if the adjustment is larger than 1000 seconds, but only in the first ten clock updates.
maxchange
: This directive sets the maximum allowed offset corrected on a clock update. The check is performed only after the specified number of updates to allow a large initial adjustment of the system clock. When an offset larger than the specified maximum occurs, it will be ignored for the specified number of times and then `chronyd` will give up and exit (a negative value can be used to never exit). In both cases a message is sent to syslog.
An example of the use of this directive is:
maxchange 1000 1 2
After the first clock update, `chronyd` will check the offset on every clock update, it will ignore two adjustments larger than 1000 seconds and exit on another one.
maxupdateskew
: One of `chronyd`'s tasks is to work out how fast or slow the computer’s clock runs relative to its reference sources. In addition, it computes an estimate of the error bounds around the estimated value. If the range of error is too large, it indicates that the measurements have not settled down yet, and that the estimated gain or loss rate is not very reliable. The **maxupdateskew** parameter is the threshold for determining whether an estimate is too unreliable to be used. By default, the threshold is 1000 ppm. The format of the syntax is:
maxupdateskew _`skew-in-ppm`_
Typical values for _`skew-in-ppm`_ might be 100 for a dial-up connection to servers over a telephone line, and 5 or 10 for a computer on a LAN. It should be noted that this is not the only means of protection against using unreliable estimates. At all times, `chronyd` keeps track of both the estimated gain or loss rate, and the error bound on the estimate. When a new estimate is generated following another measurement from one of the sources, a weighted combination algorithm is used to update the master estimate. So if `chronyd` has an existing highly-reliable master estimate and a new estimate is generated which has large error bounds, the existing master estimate will dominate in the new master estimate.
noclientlog
: This directive, which takes no arguments, specifies that client accesses are not to be logged. Normally they are logged, allowing statistics to be reported using the clients command in chronyc.
reselectdist
: When `chronyd` selects synchronization source from available sources, it will prefer the one with minimum synchronization distance. However, to avoid frequent reselecting when there are sources with similar distance, a fixed distance is added to the distance for sources that are currently not selected. This can be set with the `reselectdist` option. By default, the distance is 100 microseconds.
The format of the syntax is:
reselectdist _`dist-in-seconds`_
stratumweight
: The **stratumweight** directive sets how much distance should be added per stratum to the synchronization distance when `chronyd` selects the synchronization source from available sources.
The format of the syntax is:
stratumweight _`dist-in-seconds`_
By default, _`dist-in-seconds`_ is 1 second. This means that sources with lower stratum are usually preferred to sources with higher stratum even when their distance is significantly worse. Setting **stratumweight** to 0 makes `chronyd` ignore stratum when selecting the source.
rtcfile
: The **rtcfile** directive defines the name of the file in which `chronyd` can save parameters associated with tracking the accuracy of the system’s real-time clock (RTC). The format of the syntax is:
rtcfile /var/lib/chrony/rtc
`chronyd` saves information in this file when it exits and when the **writertc** command is issued in chronyc. The information saved is the RTC’s error at some epoch, that epoch (in seconds since January 1 1970), and the rate at which the RTC gains or loses time. Not all real-time clocks are supported as their code is system-specific. Note that if this directive is used then the real-time clock should not be manually adjusted as this would interfere with chrony's need to measure the rate at which the real-time clock drifts if it was adjusted at random intervals.
rtcsync
: The **rtcsync** directive is present in the `/etc/chrony.conf` file by default. This will inform the kernel the system clock is kept synchronized and the kernel will update the real-time clock every 11 minutes.
### 13\.2.4. Security with chronyc {#sect-Security_with_chronyc}
As access to chronyc allows changing `chronyd` just as editing the configuration files would, access to chronyc should be limited. Passwords can be specified in the key file, written in ASCII or HEX, to restrict the use of chronyc. One of the entries is used to restrict the use of operational commands and is referred to as the command key. In the default configuration, a random command key is generated automatically on start. It should not be necessary to specify or alter it manually.
Other entries in the key file can be used as `NTP` keys to authenticate packets received from remote `NTP` servers or peers. The two sides need to share a key with identical ID, hash type and password in their key file. This requires manually creating the keys and copying them over a secure medium, such as `SSH`. If the key ID was, for example, 10 then the systems that act as clients must have a line in their configuration files in the following format:
server w.x.y.z key 10
peer w.x.y.z key 10
The location of the key file is specified in the `/etc/chrony.conf` file. The default entry in the configuration file is:
**keyfile** `/etc/chrony.keys`
The command key number is specified in `/etc/chrony.conf` using the **commandkey** directive, it is the key `chronyd` will use for authentication of user commands. The directive in the configuration file takes the following form:
commandkey 1
An example of the format of the default entry in the key file, `/etc/chrony.keys`, for the command key is:
1 SHA1 HEX:A6CFC50C9C93AB6E5A19754C246242FC5471BCDF
Where `1` is the key ID, SHA1 is the hash function to use, `HEX` is the format of the key, and `A6CFC50C9C93AB6E5A19754C246242FC5471BCDF` is the key randomly generated when chronyd was started for the first time. The key can be given in hexidecimal or ASCII format (the default).
A manual entry in the key file, used to authenticate packets from certain `NTP` servers or peers, can be as simple as the following:
20 foobar
Were `20` is the key ID and `foobar` is the secret authentication key. The default hash is MD5, and ASCII is the default format for the key.
By default, `chronyd` is configured to listen for commands only from `localhost` (`127.0.0.1` and `::1`) on port `323`. To access `chronyd` remotely with chronyc, any **bindcmdaddress** directives in the `/etc/chrony.conf` file should be removed to enable listening on all interfaces and the **cmdallow** directive should be used to allow commands from the remote `IP` address, network, or subnet. In addition, port `323` has to be opened in the firewall in order to connect from a remote system. Note that the **allow** directive is for `NTP` access whereas the **cmdallow** directive is to enable the receiving of remote commands. It is possible to make these changes temporarily using chronyc running locally. Edit the configuration file to make persistent changes.
The communication between chronyc and chronyd is done over `UDP`, so it needs to be authorized before issuing operational commands. To authorize, use the **authhash** and **password** commands as follows:
chronyc> **authhash SHA1**
chronyc> **password HEX:A6CFC50C9C93AB6E5A19754C246242FC5471BCDF**
200 OK
If chronyc is used to configure the local chronyd, the `-a` option will run the **authhash** and **password** commands automatically.
Only the following commands can be used without providing a password: **activity** , **authhash** , **dns** , **exit** , **help** , **password** , **quit** , **rtcdata** , **sources** , **sourcestats** , **tracking** , **waitsync** .
## 13\.3. Using chrony {#sect-Using_chrony}
### 13\.3.1. Checking if chrony is Installed {#sect-Checking_if_chrony_is_installed}
To check if chrony is installed, run the following command as `root`:
~]# **yum install chrony**
The default location for the chrony daemon is `/usr/sbin/chronyd`. The command line utility will be installed to `/usr/bin/chronyc`.
### 13\.3.2. Installing chrony {#sect-Installing_chrony}
To install chrony, run the following command as `root`:
~]# **yum install chrony -y**
The default location for the chrony daemon is `/usr/sbin/chronyd`. The command line utility will be installed to `/usr/bin/chronyc`.
### 13\.3.3. Checking the Status of chronyd {#sect-Checking_the_Status_of_chronyd}
To check the status of `chronyd`, issue the following command:
~]$ **systemctl status chronyd**
chronyd.service - NTP client/server
Loaded: loaded (/usr/lib/systemd/system/chronyd.service; enabled)
Active: active (running) since Wed 2013-06-12 22:23:16 CEST; 11h ago
### 13\.3.4. Starting chronyd {#sect-Starting_chronyd}
To start `chronyd`, issue the following command as `root`:
~]# **systemctl start chronyd**
To ensure `chronyd` starts automatically at system start, issue the following command as `root`:
~]# **systemctl enable chronyd**
### 13\.3.5. Stopping chronyd {#sect-Stopping_chronyd}
To stop `chronyd`, issue the following command as `root`:
~]# **systemctl stop chronyd**
To prevent `chronyd` from starting automatically at system start, issue the following command as `root`:
~]# **systemctl disable chronyd**
### 13\.3.6. Checking if chrony is Synchronized {#sect-Checking_if_chrony_is_synchronized}
To check if chrony is synchronized, make use of the **tracking**, **sources**, and **sourcestats** commands.
#### 13\.3.6.1. Checking chrony Tracking {#sect-Checking_chrony_tracking}
To check chrony tracking, issue the following command:
~]$ **chronyc tracking**
Reference ID : 1.2.3.4 (a.b.c)
Stratum : 3
Ref time (UTC) : Fri Feb 3 15:00:29 2012
System time : 0.000001501 seconds slow of NTP time
Last offset : -0.000001632 seconds
RMS offset : 0.000002360 seconds
Frequency : 331.898 ppm fast
Residual freq : 0.004 ppm
Skew : 0.154 ppm
Root delay : 0.373169 seconds
Root dispersion : 0.024780 seconds
Update interval : 64.2 seconds
Leap status : Normal
The fields are as follows:
Reference ID
: This is the reference ID and name (or `IP` address) if available, of the server to which the computer is currently synchronized. If this is `127.127.1.1` it means the computer is not synchronized to any external source and that you have the “local” mode operating (via the local command in chronyc, or the **local** directive in the `/etc/chrony.conf` file (see section **local**)).
Stratum
: The stratum indicates how many hops away from a computer with an attached reference clock we are. Such a computer is a stratum-1 computer, so the computer in the example is two hops away (that is to say, a.b.c is a stratum-2 and is synchronized from a stratum-1).
Ref time
: This is the time (UTC) at which the last measurement from the reference source was processed.
System time
: In normal operation, `chronyd` never steps the system clock, because any jump in the timescale can have adverse consequences for certain application programs. Instead, any error in the system clock is corrected by slightly speeding up or slowing down the system clock until the error has been removed, and then returning to the system clock’s normal speed. A consequence of this is that there will be a period when the system clock (as read by other programs using the `gettimeofday()` system call, or by the date command in the shell) will be different from `chronyd`'s estimate of the current true time (which it reports to `NTP` clients when it is operating in server mode). The value reported on this line is the difference due to this effect.
Last offset
: This is the estimated local offset on the last clock update.
RMS offset
: This is a long-term average of the offset value.
Frequency
: The “frequency” is the rate by which the system’s clock would be would be wrong if `chronyd` was not correcting it. It is expressed in ppm (parts per million). For example, a value of 1ppm would mean that when the system’s clock thinks it has advanced 1 second, it has actually advanced by 1.000001 seconds relative to true time.
Residual freq
: This shows the “residual frequency” for the currently selected reference source. This reflects any difference between what the measurements from the reference source indicate the frequency should be and the frequency currently being used. The reason this is not always zero is that a smoothing procedure is applied to the frequency. Each time a measurement from the reference source is obtained and a new residual frequency computed, the estimated accuracy of this residual is compared with the estimated accuracy (see `skew` next) of the existing frequency value. A weighted average is computed for the new frequency, with weights depending on these accuracies. If the measurements from the reference source follow a consistent trend, the residual will be driven to zero over time.
Skew
: This is the estimated error bound on the frequency.
Root delay
: This is the total of the network path delays to the stratum-1 computer from which the computer is ultimately synchronized. In certain extreme situations, this value can be negative. (This can arise in a symmetric peer arrangement where the computers’ frequencies are not tracking each other and the network delay is very short relative to the turn-around time at each computer.)
Root dispersion
: This is the total dispersion accumulated through all the computers back to the stratum-1 computer from which the computer is ultimately synchronized. Dispersion is due to system clock resolution, statistical measurement variations etc.
Leap status
: This is the leap status, which can be Normal, Insert second, Delete second or Not synchronized.
#### 13\.3.6.2. Checking chrony Sources {#sect-Checking_chrony_sources}
The sources command displays information about the current time sources that `chronyd` is accessing. The optional argument -v can be specified, meaning verbose. In this case, extra caption lines are shown as a reminder of the meanings of the columns.
~]$ **chronyc sources**
210 Number of sources = 3
MS Name/IP address Stratum Poll Reach LastRx Last sample
===============================================================================
#* GPS0 0 4 377 11 -479ns[ -621ns] +/- 134ns
^? a.b.c 2 6 377 23 -923us[ -924us] +/- 43ms
^+ d.e.f 1 6 377 21 -2629us[-2619us] +/- 86ms
The columns are as follows:
M
: This indicates the mode of the source. `^` means a server, `=` means a peer and `#` indicates a locally connected reference clock.
S
: This column indicates the state of the sources. “\*” indicates the source to which `chronyd` is currently synchronized. “+” indicates acceptable sources which are combined with the selected source. “-” indicates acceptable sources which are excluded by the combining algorithm. “?” indicates sources to which connectivity has been lost or whose packets do not pass all tests. “x” indicates a clock which `chronyd` thinks is a _falseticker_ ( its time is inconsistent with a majority of other sources). “~” indicates a source whose time appears to have too much variability. The “?” condition is also shown at start-up, until at least 3 samples have been gathered from it.
Name/IP address
: This shows the name or the `IP` address of the source, or reference ID for reference clocks.
Stratum
: This shows the stratum of the source, as reported in its most recently received sample. Stratum 1 indicates a computer with a locally attached reference clock. A computer that is synchronized to a stratum 1 computer is at stratum 2. A computer that is synchronized to a stratum 2 computer is at stratum 3, and so on.
Poll
: This shows the rate at which the source is being polled, as a base-2 logarithm of the interval in seconds. Thus, a value of 6 would indicate that a measurement is being made every 64 seconds. `chronyd` automatically varies the polling rate in response to prevailing conditions.
Reach
: This shows the source’s reach register printed as an octal number. The register has 8 bits and is updated on every received or missed packet from the source. A value of 377 indicates that a valid reply was received for all of the last eight transmissions.
LastRx
: This column shows how long ago the last sample was received from the source. This is normally in seconds. The letters `m`, `h`, `d` or `y` indicate minutes, hours, days or years. A value of 10 years indicates there were no samples received from this source yet.
Last sample
: This column shows the offset between the local clock and the source at the last measurement. The number in the square brackets shows the actual measured offset. This may be suffixed by `ns` (indicating nanoseconds), `us` (indicating microseconds), `ms` (indicating milliseconds), or `s` (indicating seconds). The number to the left of the square brackets shows the original measurement, adjusted to allow for any slews applied to the local clock since. The number following the `+/-` indicator shows the margin of error in the measurement. Positive offsets indicate that the local clock is fast of the source.
#### 13\.3.6.3. Checking chrony Source Statistics {#sect-Checking_chrony_Source_Statistics}
The **sourcestats** command displays information about the drift rate and offset estimation process for each of the sources currently being examined by `chronyd`. The optional argument `-v` can be specified, meaning verbose. In this case, extra caption lines are shown as a reminder of the meanings of the columns.
~]$ **chronyc sourcestats**
210 Number of sources = 1
Name/IP Address NP NR Span Frequency Freq Skew Offset Std Dev
===============================================================================
abc.def.ghi
The columns are as follows:
Name/IP address
: This is the name or `IP` address of the `NTP` server (or peer) or reference ID of the reference clock to which the rest of the line relates.
NP
: This is the number of sample points currently being retained for the server. The drift rate and current offset are estimated by performing a linear regression through these points.
NR
: This is the number of runs of residuals having the same sign following the last regression. If this number starts to become too small relative to the number of samples, it indicates that a straight line is no longer a good fit to the data. If the number of runs is too low, `chronyd` discards older samples and re-runs the regression until the number of runs becomes acceptable.
Span
: This is the interval between the oldest and newest samples. If no unit is shown the value is in seconds. In the example, the interval is 46 minutes.
Frequency
: This is the estimated residual frequency for the server, in parts per million. In this case, the computer’s clock is estimated to be running 1 part in 109 slow relative to the server.
Freq Skew
: This is the estimated error bounds on Freq (again in parts per million).
Offset
: This is the estimated offset of the source.
Std Dev
: This is the estimated sample standard deviation.
### 13\.3.7. Manually Adjusting the System Clock {#sect-Manually_Adjusting-the-System_Clock}
To update, or step, the system clock immediately, bypassing any adjustments in progress by slewing the clock, issue the following commands as `root`:
~]# **chronyc**
chrony> **password** _`commandkey-password`_
200 OK
chrony> **makestep**
200 OK
Where _`commandkey-password`_ is the command key or password stored in the key file.
The real-time clock should not be manually adjusted if the **rtcfile** directive is used as this would interfere with chrony's need to measure the rate at which the real-time clock drifts if it was adjusted at random intervals.
If chronyc is used to configure the local chronyd, the `-a` will run the **authhash** and **password** commands automatically. This means that the interactive session illustrated above can be replaced by:
chronyc -a makestep
## 13\.4. Setting Up chrony for Different Environments {#sect-Setting_up_chrony_for_different_environments}
### 13\.4.1. Setting Up chrony for a System Which is Infrequently Connected {#sect-Setting_up_chrony_for_a_system_which_is_infrequently_connected}
This example is intended for systems which use dial-on-demand connections. The normal configuration should be sufficient for mobile and virtual devices which connect intermittently. First, review and confirm that the default settings in the `/etc/chrony.conf` are similar to the following:
driftfile /var/lib/chrony/drift
commandkey 1
keyfile /etc/chrony.keys
The command key ID is generated at install time and should correspond with the **commandkey** value in the key file, `/etc/chrony.keys`.
Using your editor running as `root`, add the addresses of four `NTP` servers as follows:
server 0.pool.ntp.org offline
server 1.pool.ntp.org offline
server 2.pool.ntp.org offline
server 3.pool.ntp.org offline
The `offline` option can be useful in preventing systems from trying to activate connections. The chrony daemon will wait for chronyc to inform it that the system is connected to the network or Internet.
### 13\.4.2. Setting Up chrony for a System in an Isolated Network {#sect-Setting_up_chrony_for_a_system_in_an_isolated_network}
For a network that is never connected to the Internet, one computer is selected to be the master timeserver. The other computers are either direct clients of the master, or clients of clients. On the master, the drift file must be manually set with the average rate of drift of the system clock. If the master is rebooted it will obtain the time from surrounding systems and take an average to set its system clock. Thereafter it resumes applying adjustments based on the drift file. The drift file will be updated automatically when the **settime** command is used.
On the system selected to be the master, using a text editor running as `root`, edit the `/etc/chrony.conf` as follows:
driftfile /var/lib/chrony/drift
commandkey 1
keyfile /etc/chrony.keys
initstepslew 10 client1 client3 client6
local stratum 8
manual
allow 192.0.2.0
Where `192.0.2.0` is the network or subnet address from which the clients are allowed to connect.
On the systems selected to be direct clients of the master, using a text editor running as `root`, edit the `/etc/chrony.conf` as follows:
server master
driftfile /var/lib/chrony/drift
logdir /var/log/chrony
log measurements statistics tracking
keyfile /etc/chrony.keys
commandkey 24
local stratum 10
initstepslew 20 master
allow 192.0.2.123
Where `192.0.2.123` is the address of the master, and `master` is the host name of the master. Clients with this configuration will resynchronize the master if it restarts.
On the client systems which are not to be direct clients of the master, the `/etc/chrony.conf` file should be the same except that the `local` and `allow` directives should be omitted.
## 13\.5. Using chronyc {#sect-Using_chronyc}
### 13\.5.1. Using chronyc to Control chronyd {#sect-Using_chronyc_chronyc_to_control_chronyd}
To make changes using the command line utility chronyc in interactive mode, enter the following command as `root`:
~]# **chronyc**
chronyc must run as `root` if some of the restricted commands are to be used.
The chronyc command prompt will be displayed as follows:
chronyc>
You can type **help** to list all of the commands.
The utility can also be invoked in non-interactive command mode if called together with a command as follows:
~]# **chronyc _`command`_**
### 13\.5.2. Using chronyc for Remote Administration {#sect-Using_chronyc_for_remote_administration}
To configure chrony to connect to a remote instance of `chronyd`, issue a command as `root` in the following format:
~]# **chronyc `-h` _`hostname`_**
Where _`hostname`_ is the `hostname` of a system running `chronyd` to connect to in order to allow remote administration from that host. The default is to connect to the daemon on the localhost.
To configure chrony to connect to a remote instance of `chronyd` on a non-default port, issue a command as `root` in the following format:
~]# **chronyc `-h` _`hostname`_ `-p` _`port`_**
Where _`port`_ is the port in use for controlling and monitoring by the instance of `chronyd` to be connected to.
Note that commands issued at the chrony command prompt are not persistent. Only commands in the configuration file are persistent.
From the remote systems, the system administrator can issue commands after first using the **password** command, preceded by the **authhash** command if the key used a hash different from MD5, at the chronyc command prompt as follows:
chronyc> **password secretpasswordwithnospaces**
200 OK
The password or hash associated with the command key for a remote system is best obtained by `SSH`. An `SSH` connection should be established to the remote machine and the ID of the command key from `/etc/chrony.conf` and the command key in `/etc/chrony.keys` memorized or stored securely for the duration of the session.
## 13\.6. Additional Resources {#sect-additional_resources}
The following sources of information provide additional resources regarding chrony.
### 13\.6.1. Installed Documentation {#s2-chrony-docs-inst}
* `chrony(1)` man page — Introduces the chrony daemon and the command-line interface tool.
* `chronyc(1)` man page — Describes the chronyc command-line interface tool including commands and command options.
* `chronyd(1)` man page — Describes the chronyd daemon including commands and command options.
* `chrony.conf(5)` man page — Describes the chrony configuration file.
* `/usr/share/doc/chrony/chrony.txt` — User guide for the chrony suite.
### 13\.6.2. Online Documentation {#s2-chrony_Online_Documentation}
: The online user guide for chrony.
## Chapter 14. Configuring NTP Using ntpd {#ch-Configuring_NTP_Using_ntpd}
## 14\.1. Introduction to NTP {#s1-Introduction_to_NTP}
The _Network Time Protocol_ (NTP) enables the accurate dissemination of time and date information in order to keep the time clocks on networked computer systems synchronized to a common reference over the network or the Internet. Many standards bodies around the world have atomic clocks which may be made available as a reference. The satellites that make up the Global Position System contain more than one atomic clock, making their time signals potentially very accurate. Their signals can be deliberately degraded for military reasons. An ideal situation would be where each site has a server, with its own reference clock attached, to act as a site-wide time server. Many devices which obtain the time and date via low frequency radio transmissions or the Global Position System (GPS) exist. However for most situations, a range of publicly accessible time servers connected to the Internet at geographically dispersed locations can be used. These `NTP` servers provide “_Coordinated Universal Time_” (UTC). Information about these time servers can found at _www.pool.ntp.org_.
Accurate time keeping is important for a number of reasons in IT. In networking for example, accurate time stamps in packets and logs are required. Logs are used to investigate service and security issues and so timestamps made on different systems must be made by synchronized clocks to be of real value. As systems and networks become increasingly faster, there is a corresponding need for clocks with greater accuracy and resolution. In some countries there are legal obligations to keep accurately synchronized clocks. Please see _www.ntp.org_ for more information. In Linux systems, `NTP` is implemented by a daemon running in user space. The default `NTP` user space daemon in Fedora 20 is `chronyd`. It must be disabled if you want to use the `ntpd` daemon. See [Chapter 13, _Configuring NTP Using the chrony Suite_](#ch-Configuring_NTP_Using_the_chrony_Suite "Chapter 13. Configuring NTP Using the chrony Suite") for information on chrony.
The user space daemon updates the system clock, which is a software clock running in the kernel. Linux uses a software clock as its system clock for better resolution than the typical embedded hardware clock referred to as the “_Real Time Clock_” (RTC). See the `rtc(4)` and `hwclock(8)` man pages for information on hardware clocks. The system clock can keep time by using various clock sources. Usually, the _Time Stamp Counter_ (TSC) is used. The TSC is a CPU register which counts the number of cycles since it was last reset. It is very fast, has a high resolution, and there are no interrupts. On system start, the system clock reads the time and date from the RTC. The time kept by the RTC will drift away from actual time by up to 5 minutes per month due to temperature variations. Hence the need for the system clock to be constantly synchronized with external time references. When the system clock is being synchronized by `ntpd`, the kernel will in turn update the RTC every 11 minutes automatically.
## 14\.2. NTP Strata {#s1-NTP_Strata}
`NTP` servers are classified according to their synchronization distance from the atomic clocks which are the source of the time signals. The servers are thought of as being arranged in layers, or strata, from 1 at the top down to 15. Hence the word stratum is used when referring to a specific layer. Atomic clocks are referred to as Stratum 0 as this is the source, but no Stratum 0 packet is sent on the Internet, all stratum 0 atomic clocks are attached to a server which is referred to as stratum 1. These servers send out packets marked as Stratum 1. A server which is synchronized by means of packets marked stratum `n` belongs to the next, lower, stratum and will mark its packets as stratum `n+1`. Servers of the same stratum can exchange packets with each other but are still designated as belonging to just the one stratum, the stratum one below the best reference they are synchronized to. The designation Stratum 16 is used to indicate that the server is not currently synchronized to a reliable time source.
Note that by default `NTP` clients act as servers for those systems in the stratum below them.
Here is a summary of the `NTP` Strata:
Stratum 0:
: Atomic Clocks and their signals broadcast over Radio and GPS
* GPS (Global Positioning System)
* Mobile Phone Systems
* Low Frequency Radio Broadcasts WWVB (Colorado, USA.), JJY-40 and JJY-60 (Japan), DCF77 (Germany), and MSF (United Kingdom)
These signals can be received by dedicated devices and are usually connected by RS-232 to a system used as an organizational or site-wide time server.
Stratum 1:
: Computer with radio clock, GPS clock, or atomic clock attached
Stratum 2:
: Reads from stratum 1; Serves to lower strata
Stratum 3:
: Reads from stratum 2; Serves to lower strata
Stratum _`n+1`_:
: Reads from stratum _`n`_; Serves to lower strata
Stratum 15:
: Reads from stratum 14; This is the lowest stratum.
This process continues down to Stratum 15 which is the lowest valid stratum. The label Stratum 16 is used to indicated an unsynchronized state.
## 14\.3. Understanding NTP {#s1-Understanding_NTP}
The version of `NTP` used by Fedora is as described in [_RFC 1305 Network Time Protocol (Version 3) Specification, Implementation and Analysis_](http://www.rfc-editor.org/info/rfc1305) and [_RFC 5905 Network Time Protocol Version 4: Protocol and Algorithms Specification_](http://www.rfc-editor.org/info/rfc5905)
This implementation of `NTP` enables sub-second accuracy to be achieved. Over the Internet, accuracy to 10s of milliseconds is normal. On a Local Area Network (LAN), 1 ms accuracy is possible under ideal conditions. This is because clock drift is now accounted and corrected for, which was not done in earlier, simpler, time protocol systems. A resolution of 233 picoseconds is provided by using 64-bit timestamps: 32-bits for seconds, 32-bits for fractional seconds.
`NTP` represents the time as a count of the number of seconds since 00:00 (midnight) 1 January, 1900 GMT. As 32-bits is used to count the seconds, this means the time will “roll over” in 2036. However `NTP` works on the difference between timestamps so this does not present the same level of problem as other implementations of time protocols have done. If a hardware clock accurate to better than 68 years is available at boot time then `NTP` will correctly interpret the current date. The `NTP4` specification provides for an “Era Number” and an “Era Offset” which can be used to make software more robust when dealing with time lengths of more than 68 years. Note, please do not confuse this with the Unix Year 2038 problem.
The `NTP` protocol provides additional information to improve accuracy. Four timestamps are used to allow the calculation of round-trip time and server response time. In order for a system in its role as `NTP` client to synchronize with a reference time server, a packet is sent with an “originate timestamp”. When the packet arrives, the time server adds a “receive timestamp”. After processing the request for time and date information and just before returning the packet, it adds a “transmit timestamp”. When the returning packet arrives at the `NTP` client, a “receive timestamp” is generated. The client can now calculate the total round trip time and by subtracting the processing time derive the actual traveling time. By assuming the outgoing and return trips take equal time, the single-trip delay in receiving the `NTP` data is calculated. The full `NTP` algorithm is much more complex then presented here.
Each packet containing time information received is not immediately acted upon, but is subject to validation checks and then used together with several other samples to arrive at a reasonably good estimate of the time. This is then compared to the system clock to determine the time offset, that is to say, the difference between the system clock's time and what `ntpd` has determined the time should be. The system clock is adjusted slowly, at most at a rate of 0.5ms per second, to reduce this offset by changing the frequency of the counter being used. It will take at least 2000 seconds to adjust the clock by 1 second using this method. This slow change is referred to as slewing and cannot go backwards. If the time offset of the clock is more than 128ms (the default setting), `ntpd` can “step” the clock forwards or backwards. If the time offset at system start is greater than 1000 seconds then the user, or an installation script, should make a manual adjustment. See [Chapter 3, _Configuring the Date and Time_](#ch-Configuring_the_Date_and_Time "Chapter 3. Configuring the Date and Time"). With the `-g` option to the **ntpd** command (used by default), any offset at system start will be corrected, but during normal operation only offsets of up to 1000 seconds will be corrected.
Some software may fail or produce an error if the time is changed backwards. For systems that are sensitive to step changes in the time, the threshold can be changed to 600s instead of 128ms using the `-x` option (unrelated to the `-g` option). Using the `-x` option to increase the stepping limit from 0.128s to 600s has a drawback because a different method of controlling the clock has to be used. It disables the kernel clock discipline and may have a negative impact on the clock accuracy. The `-x` option can be added to the `/etc/sysconfig/ntpd` configuration file.
## 14\.4. Understanding the Drift File {#s1-Understanding_the_Drift_File}
The drift file is used to store the frequency offset between the system clock running at its nominal frequency and the frequency required to remain in synchronization with UTC. If present, the value contained in the drift file is read at system start and used to correct the clock source. Use of the drift file reduces the time required to achieve a stable and accurate time. The value is calculated, and the drift file replaced, once per hour by `ntpd`. The drift file is replaced, rather than just updated, and for this reason the drift file must be in a directory for which the `ntpd` has write permissions.
## 14\.5. UTC, Timezones, and DST {#s1-UTC_timezones_and_DST}
As `NTP` is entirely in UTC (Universal Time, Coordinated), Timezones and DST (Daylight Saving Time) are applied locally by the system. The file `/etc/localtime` is a copy of, or symlink to, a zone information file from `/usr/share/zoneinfo`. The RTC may be in localtime or in UTC, as specified by the 3rd line of `/etc/adjtime`, which will be one of LOCAL or UTC to indicate how the RTC clock has been set. Users can easily change this setting using the checkbox System Clock Uses UTC in the Date and Time graphical configuration tool. See [Chapter 3, _Configuring the Date and Time_](#ch-Configuring_the_Date_and_Time "Chapter 3. Configuring the Date and Time") for information on how to use that tool. Running the RTC in UTC is recommended to avoid various problems when daylight saving time is changed.
The operation of `ntpd` is explained in more detail in the man page `ntpd(8)`. The resources section lists useful sources of information. See [Section 14.20, “Additional Resources”](#s1-ntpd_additional-resources "14.20. Additional Resources").
## 14\.6. Authentication Options for NTP {#s1-Authentication_Options_for_NTP}
`NTPv4` added support for the Autokey Security Architecture, which is based on public asymmetric cryptography while retaining support for symmetric key cryptography. The Autokey Security Architecture is described in [_RFC 5906 Network Time Protocol Version 4: Autokey Specification_](http://www.rfc-editor.org/info/rfc5906). The man page `ntp_auth(5)` describes the authentication options and commands for `ntpd`.
An attacker on the network can attempt to disrupt a service by sending `NTP` packets with incorrect time information. On systems using the public pool of `NTP` servers, this risk is mitigated by having more than three `NTP` servers in the list of public `NTP` servers in `/etc/ntp.conf`. If only one time source is compromised or spoofed, `ntpd` will ignore that source. You should conduct a risk assessment and consider the impact of incorrect time on your applications and organization. If you have internal time sources you should consider steps to protect the network over which the `NTP` packets are distributed. If you conduct a risk assessment and conclude that the risk is acceptable, and the impact to your applications minimal, then you can choose not to use authentication.
The broadcast and multicast modes require authentication by default. If you have decided to trust the network then you can disable authentication by using **disable auth** directive in the `ntp.conf` file. Alternatively, authentication needs to be configured by using SHA1 or MD5 symmetric keys, or by public (asymmetric) key cryptography using the Autokey scheme. The Autokey scheme for asymmetric cryptography is explained in the `ntp_auth(8)` man page and the generation of keys is explained in `ntp-keygen(8`). To implement symmetric key cryptography, see [Section 14.17.12, “Configuring Symmetric Authentication Using a Key”](#s2_Configuring_Symmetric_Authentication_Using_a_Key "14.17.12. Configuring Symmetric Authentication Using a Key") for an explanation of the `key` option.
## 14\.7. Managing the Time on Virtual Machines {#s1-Managing_the_Time_on_Virtual_Machines}
Virtual machines cannot access a real hardware clock and a virtual clock is not stable enough as the stability is dependent on the host systems work load. For this reason, para-virtualized clocks should be provided by the virtualization application in use. On Fedora with KVM the default clock source is `kvm-clock`. See the [_KVM guest timing management_](http://docs.fedoraproject.org/en-US/Fedora/13/html/Virtualization_Guide/chap-Virtualization-KVM_guest_timing_management.html) chapter of the _Virtualization Host Configuration and Guest Installation Guide_.
## 14\.8. Understanding Leap Seconds {#s1-Understanding_Leap_Seconds}
Greenwich Mean Time (GMT) was derived by measuring the solar day, which is dependent on the Earth's rotation. When atomic clocks were first made, the potential for more accurate definitions of time became possible. In 1958, International Atomic Time (TAI) was introduced based on the more accurate and very stable atomic clocks. A more accurate astronomical time, Universal Time 1 (UT1), was also introduced to replace GMT. The atomic clocks are in fact far more stable than the rotation of the Earth and so the two times began to drift apart. For this reason UTC was introduced as a practical measure. It is kept within one second of UT1 but to avoid making many small trivial adjustments it was decided to introduce the concept of a _leap second_ in order to reconcile the difference in a manageable way. The difference between UT1 and UTC is monitored until they drift apart by more than half a second. Then only is it deemed necessary to introduce a one second adjustment, forward or backward. Due to the erratic nature of the Earth's rotational speed, the need for an adjustment cannot be predicted far into the future. The decision as to when to make an adjustment is made by the [_International Earth Rotation and Reference Systems Service (IERS)_](http://www.iers.org). However, these announcements are important only to administrators of Stratum 1 servers because `NTP` transmits information about pending leap seconds and applies them automatically.
## 14\.9. Understanding the ntpd Configuration File {#s1-Understanding_the_ntpd_Configuration_File}
The daemon, `ntpd`, reads the configuration file at system start or when the service is restarted. The default location for the file is `/etc/ntp.conf` and you can view the file by entering the following command:
~]$ **less /etc/ntp.conf**
The configuration commands are explained briefly later in this chapter, see [Section 14.17, “Configure NTP”](#s1-Configure_NTP "14.17. Configure NTP"), and more verbosely in the `ntp.conf(5)` man page.
Here follows a brief explanation of the contents of the default configuration file:
The driftfile entry
: A path to the drift file is specified, the default entry on Fedora is:
driftfile /var/lib/ntp/drift
If you change this be certain that the directory is writable by `ntpd`. The file contains one value used to adjust the system clock frequency after every system or service start. See [Understanding the Drift File](#s1-Understanding_the_Drift_File "14.4. Understanding the Drift File") for more information.
The access control entries
: The following line sets the default access control restriction:
restrict default kod nomodify notrap nopeer noquery
The `kod` option means a “Kiss-o'-death” packet is to be sent to reduce unwanted queries. The `nomodify` options prevents any changes to the configuration. The `notrap` option prevents `ntpdc` control message protocol traps. The `nopeer` option prevents a peer association being formed. The `noquery` option prevents `ntpq` and `ntpdc` queries, but not time queries, from being answered. The `ntpq` and `ntpdc` queries can be used in amplification attacks (see [_CVE-2013-5211_](https://access.redhat.com/security/cve/CVE-2013-5211) for more details), do not remove the `noquery` option from the **restrict default** command on publicly accessible systems.
Addresses within the range `127.0.0.0/8` range are sometimes required by various processes or applications. As the "restrict default" line above prevents access to everything not explicitly allowed, access to the standard loopback address for `IPv4` and `IPv6` is permitted by means of the following lines:
# the administrative functions.
restrict 127.0.0.1
restrict ::1
Addresses can be added underneath if specifically required by another application.
Hosts on the local network are not permitted because of the "restrict default" line above. To change this, for example to allow hosts from the `192.0.2.0/24` network to query the time and statistics but nothing more, a line in the following format is required:
restrict 192.0.2.0 mask 255.255.255.0 nomodify notrap nopeer
To allow unrestricted access from a specific host, for example `192.0.2.250/24`, a line in the following format is required:
restrict 192.0.2.250
A mask of `255.255.255.255` is applied if none is specified.
The restrict commands are explained in the `ntp_acc(5)` man page.
The public servers entry
: By default, the `ntp.conf` file contains four public server entries:
server 0.fedora.pool.ntp.org iburst
server 1.fedora.pool.ntp.org iburst
server 2.fedora.pool.ntp.org iburst
server 3.fedora.pool.ntp.org iburst
The broadcast multicast servers entry
: By default, the `ntp.conf` file contains some commented out examples. These are largely self explanatory. See the explanation of the specific commands [Section 14.17, “Configure NTP”](#s1-Configure_NTP "14.17. Configure NTP"). If required, add your commands just below the examples.
### Note
When the `DHCP` client program, dhclient, receives a list of `NTP` servers from the `DHCP` server, it adds them to `ntp.conf` and restarts the service. To disable that feature, add **PEERNTP=no** to `/etc/sysconfig/network`.
## 14\.10. Understanding the ntpd Sysconfig File {#s1-Understanding_the_ntpd_Sysconfig_File}
The file will be read by the `ntpd` init script on service start. The default contents is as follows:
# Command line options for ntpd
OPTIONS="-g"
The `-g` option enables `ntpd` to ignore the offset limit of 1000s and attempt to synchronize the time even if the offset is larger than 1000s, but only on system start. Without that option ntpd will exit if the time offset is greater than 1000s. It will also exit after system start if the service is restarted and the offset is greater than 1000s even with the `-g` option.
## 14\.11. Disabling chrony {#s1-Disabling_chrony}
In order to use `ntpd` the default user space daemon, `chronyd`, must be stopped and disabled. Issue the following command as `root`:
~]# **systemctl stop chronyd**
To prevent it restarting at system start, issue the following command as `root`:
~]# **systemctl disable chronyd**
To check the status of `chronyd`, issue the following command:
~]$ **systemctl status chronyd**
## 14\.12. Checking if the NTP Daemon is Installed {#s1-Checking_if_the_NTP_Daemon_is_Installed}
To check if `ntpd` is installed, enter the following command as `root`:
~]# **yum install ntp**
`NTP` is implemented by means of the daemon or service `ntpd`, which is contained within the ntp package.
## 14\.13. Installing the NTP Daemon (ntpd) {#s1-Installing_the_NTP_Daemon_ntpd}
To install `ntpd`, enter the following command as `root`:
~]# **yum install ntp**
To enable `ntpd` at system start, enter the following command as `root`:
~]# **systemctl enable ntpd**
## 14\.14. Checking the Status of NTP {#s1-Checking_the_status_of_NTP}
To check if `ntpd` is running and configured to run at system start, issue the following command:
~]$ **systemctl status ntpd**
To obtain a brief status report from `ntpd`, issue the following command:
~]$ **ntpstat**
unsynchronised
time server re-starting
polling server every 64 s
~]$ **ntpstat**
synchronised to NTP server (10.5.26.10) at stratum 2
time correct to within 52 ms
polling server every 1024 s
## 14\.15. Configure the Firewall to Allow Incoming NTP Packets {#s1-Configure_the_Firewall_to_Allow_Incoming_NTP_Packets}
The `NTP` traffic consists of `UDP` packets on port `123` and needs to be permitted through network and host-based firewalls in order for `NTP` to function.
Check if the firewall is configured to allow incoming `NTP` traffic for clients using the graphical Firewall Configuration tool.
To start the graphical firewall-config tool, press the **Super** key to enter the Activities Overview, type **firewall** and then press **Enter**. The firewall-config tool appears. You will be prompted for your user password.
To start the graphical firewall configuration tool using the command line, enter the following command as `root` user:
~]# **firewall-config**
The Firewall Configuration window opens. Note, this command can be run as normal user but you will then be prompted for the `root` password from time to time.
Look for the word “Connected” in the lower left corner. This indicates that the firewall-config tool is connected to the user space daemon, `firewalld`.
### 14\.15.1. Change the Firewall Settings {#s2-Change_the_firewall_settings}
To immediately change the current firewall settings, ensure the current view is set to Runtime Configuration. Alternatively, to edit the settings to be applied at the next system start, or firewall reload, select Permanent Configuration from the drop-down list.
### Note
When making changes to the firewall settings in Runtime Configuration mode, your selection takes immediate effect when you set or clear the check box associated with the service. You should keep this in mind when working on a system that may be in use by other users.
When making changes to the firewall settings in Permanent Configuration mode, your selection will only take effect when you reload the firewall or the system restarts. You can use the reload icon below the File menu, or click the Options menu and select Reload Firewall.
### 14\.15.2. Open Ports in the Firewall for NTP Packets {#s2-Open_Ports_in_the_firewall_for_ntp_packets}
To permit traffic through the firewall to a certain port, start the firewall-config tool and select the network zone whose settings you want to change. Select the Ports tab and the click the Add button on the right hand side. The Port and Protocol window opens.
Enter the port number `123` and select udp from the drop-down list.
## 14\.16. Configure ntpdate Servers {#s1-Configure_ntpdate_Servers}
The purpose of the `ntpdate` service is to set the clock during system boot. This was used previously to ensure that the services started after `ntpdate` would have the correct time and not observe a jump in the clock. The use of `ntpdate` and the list of step-tickers is considered deprecated and so Fedora uses the `-g` option to the **ntpd** command and not `ntpdate` by default.
The `ntpdate` service in Fedora is mostly useful only when used alone without `ntpd`. With systemd, which starts services in parallel, enabling the `ntpdate` service will not ensure that other services started after it will have correct time unless they specify an ordering dependency on `time-sync.target`, which is provided by the `ntpdate` service. The `ntp-wait` service (in the ntp-perl subpackage) provides the `time-sync` target for the `ntpd` service. In order to ensure a service starts with correct time, add `After=time-sync.target` to the service and enable one of the services which provide the target (`ntpdate` or sntp, or ntp-wait if `ntpd` is enabled). Some services on Fedora have the dependency included by default ( for example, `dhcpd`, `dhcpd6`, and `crond`).
To check if the `ntpdate` service is enabled to run at system start, issue the following command:
~]$ **systemctl status ntpdate**
To enable the service to run at system start, issue the following command as `root`:
~]# **systemctl enable ntpdate**
In Fedora the default `/etc/ntp/step-tickers` file contains `0.fedora.pool.ntp.org`. To configure additional `ntpdate` servers, using a text editor running as `root`, edit `/etc/ntp/step-tickers`. The number of servers listed is not very important as `ntpdate` will only use this to obtain the date information once when the system is starting. If you have an internal time server then use that host name for the first line. An additional host on the second line as a backup is sensible. The selection of backup servers and whether the second host is internal or external depends on your risk assessment. For example, what is the chance of any problem affecting the first server also affecting the second server? Would connectivity to an external server be more likely to be available than connectivity to internal servers in the event of a network failure disrupting access to the first server?
## 14\.17. Configure NTP {#s1-Configure_NTP}
To change the default configuration of the `NTP` service, use a text editor running as `root` user to edit the `/etc/ntp.conf` file. This file is installed together with `ntpd` and is configured to use time servers from the Fedora pool by default. The man page `ntp.conf(5)` describes the command options that can be used in the configuration file apart from the access and rate limiting commands which are explained in the `ntp_acc(5)` man page.
### 14\.17.1. Configure Access Control to an NTP Service {#s2-Configure_Access_Control_to_an_NTP_service}
To restrict or control access to the `NTP` service running on a system, make use of the **restrict** command in the `ntp.conf` file. See the commented out example:
# Hosts on local network are less restricted.
#restrict 192.168.1.0 mask 255.255.255.0 nomodify notrap
The **restrict** command takes the following form:
**restrict** _`option`_
where _`option`_ is one or more of:
* `ignore` — All packets will be ignored, including `ntpq` and `ntpdc` queries.
* `kod` — a “Kiss-o'-death” packet is to be sent to reduce unwanted queries.
* `limited` — do not respond to time service requests if the packet violates the rate limit default values or those specified by the **discard** command. `ntpq` and `ntpdc` queries are not affected. For more information on the **discard** command and the default values, see [Section 14.17.2, “Configure Rate Limiting Access to an NTP Service”](#s2_Configure_Rate_Limiting_Access_to_an_NTP_Service "14.17.2. Configure Rate Limiting Access to an NTP Service").
* `lowpriotrap` — traps set by matching hosts to be low priority.
* `nomodify` — prevents any changes to the configuration.
* `noquery` — prevents `ntpq` and `ntpdc` queries, but not time queries, from being answered.
* `nopeer` — prevents a peer association being formed.
* `noserve` — deny all packets except `ntpq` and `ntpdc` queries.
* `notrap` — prevents `ntpdc` control message protocol traps.
* `notrust` — deny packets that are not cryptographically authenticated.
* `ntpport` — modify the match algorithm to only apply the restriction if the source port is the standard `NTP` `UDP` port `123`.
* `version` — deny packets that do not match the current `NTP` version.
To configure rate limit access to not respond at all to a query, the respective **restrict** command has to have the `limited` option. If `ntpd` should reply with a `KoD` packet, the **restrict** command needs to have both `limited` and `kod` options.
The `ntpq` and `ntpdc` queries can be used in amplification attacks (see [_CVE-2013-5211_](https://access.redhat.com/security/cve/CVE-2013-5211) for more details), do not remove the `noquery` option from the **restrict default** command on publicly accessible systems.
### 14\.17.2. Configure Rate Limiting Access to an NTP Service {#s2_Configure_Rate_Limiting_Access_to_an_NTP_Service}
To enable rate limiting access to the `NTP` service running on a system, add the `limited` option to the **restrict** command as explained in [Section 14.17.1, “Configure Access Control to an NTP Service”](#s2-Configure_Access_Control_to_an_NTP_service "14.17.1. Configure Access Control to an NTP Service"). If you do not want to use the default discard parameters, then also use the **discard** command as explained here.
The **discard** command takes the following form:
**discard** [`average` _`value`_] [`minimum` _`value`_] [`monitor` _`value`_]
* `average` — specifies the minimum average packet spacing to be permitted, it accepts an argument in log2 seconds. The default value is 3 (23 equates to 8 seconds).
* `minimum` — specifies the minimum packet spacing to be permitted, it accepts an argument in log2 seconds. The default value is 1 (21 equates to 2 seconds).
* `monitor` — specifies the discard probability for packets once the permitted rate limits have been exceeded. The default value is 3000 seconds. This option is intended for servers that receive 1000 or more requests per second.
Examples of the **discard** command are as follows:
discard average 4
discard average 4 minimum 2
### 14\.17.3. Adding a Peer Address {#s2_Adding_a_Peer_Address}
To add the address of a peer, that is to say, the address of a server running an `NTP` service of the same stratum, make use of the **peer** command in the `ntp.conf` file.
The **peer** command takes the following form:
**peer** _`address`_
where _`address`_ is an `IP` unicast address or a `DNS` resolvable name. The address must only be that of a system known to be a member of the same stratum. Peers should have at least one time source that is different to each other. Peers are normally systems under the same administrative control.
### 14\.17.4. Adding a Server Address {#s2_Adding_a_Server_Address}
To add the address of a server, that is to say, the address of a server running an `NTP` service of a higher stratum, make use of the **server** command in the `ntp.conf` file.
The **server** command takes the following form:
**server** _`address`_
where _`address`_ is an `IP` unicast address or a `DNS` resolvable name. The address of a remote reference server or local reference clock from which packets are to be received.
### 14\.17.5. Adding a Broadcast or Multicast Server Address {#s2_Adding_a_Broadcast_or_Mutlticast_Server_Address}
To add a broadcast or multicast address for sending, that is to say, the address to broadcast or multicast `NTP` packets to, make use of the **broadcast** command in the `ntp.conf` file.
The broadcast and multicast modes require authentication by default. See [Section 14.6, “Authentication Options for NTP”](#s1-Authentication_Options_for_NTP "14.6. Authentication Options for NTP").
The **broadcast** command takes the following form:
**broadcast** _`address`_
where _`address`_ is an `IP` broadcast or multicast address to which packets are sent.
This command configures a system to act as an `NTP` broadcast server. The address used must be a broadcast or a multicast address. Broadcast address implies the `IPv4` address `255.255.255.255`. By default, routers do not pass broadcast messages. The multicast address can be an `IPv4` Class D address, or an `IPv6` address. The IANA has assigned `IPv4` multicast address `224.0.1.1` and `IPv6` address `FF05::101` (site local) to `NTP`. Administratively scoped`IPv4` multicast addresses can also be used, as described in [_RFC 2365 Administratively Scoped IP Multicast_](http://www.rfc-editor.org/info/rfc2365).
### 14\.17.6. Adding a Manycast Client Address {#s2_Adding_a_Manycast_Client_Address}
To add a manycast client address, that is to say, to configure a multicast address to be used for `NTP` server discovery, make use of the **manycastclient** command in the `ntp.conf` file.
The **manycastclient** command takes the following form:
**manycastclient** _`address`_
where _`address`_ is an `IP` multicast address from which packets are to be received. The client will send a request to the address and select the best servers from the responses and ignore other servers. `NTP` communication then uses unicast associations, as if the discovered `NTP` servers were listed in `ntp.conf`.
This command configures a system to act as an `NTP` client. Systems can be both client and server at the same time.
### 14\.17.7. Adding a Broadcast Client Address {#s2_Adding_a_Broadcastclient_Address}
To add a broadcast client address, that is to say, to configure a broadcast address to be monitored for broadcast `NTP` packets, make use of the **broadcastclient** command in the `ntp.conf` file.
The **broadcastclient** command takes the following form:
**broadcastclient**
Enables the receiving of broadcast messages. Requires authentication by default. See [Section 14.6, “Authentication Options for NTP”](#s1-Authentication_Options_for_NTP "14.6. Authentication Options for NTP").
This command configures a system to act as an `NTP` client. Systems can be both client and server at the same time.
### 14\.17.8. Adding a Manycast Server Address {#s2_Adding_a_manycastserver_Address}
To add a manycast server address, that is to say, to configure an address to allow the clients to discover the server by multicasting `NTP` packets, make use of the **manycastserver** command in the `ntp.conf` file.
The **manycastserver** command takes the following form:
**manycastserver** _`address`_
Enables the sending of multicast messages. Where _`address`_ is the address to multicast to. This should be used together with authentication to prevent service disruption.
This command configures a system to act as an `NTP` server. Systems can be both client and server at the same time.
### 14\.17.9. Adding a Multicast Client Address {#s2_Adding_a_multicastclient_Address}
To add a multicast client address, that is to say, to configure a multicast address to be monitored for multicast `NTP` packets, make use of the **multicastclient** command in the `ntp.conf` file.
The **multicastclient** command takes the following form:
**multicastclient** _`address`_
Enables the receiving of multicast messages. Where _`address`_ is the address to subscribe to. This should be used together with authentication to prevent service disruption.
This command configures a system to act as an `NTP` client. Systems can be both client and server at the same time.
### 14\.17.10. Configuring the Burst Option {#s2_Configuring_the_burst_option}
Using the **burst** option against a public server is considered abuse. Do not use this option with public `NTP` servers. Use it only for applications within your own organization.
To increase the average quality of time offset statistics, add the following option to the end of a server command:
**burst**
At every poll interval, send a burst of eight packets instead of one, when the server is responding. For use with the **server** command to improve the average quality of the time offset calculations.
### 14\.17.11. Configuring the iburst Option {#s2_Configuring_the_iburst_Option}
To improve the time taken for initial synchronization, add the following option to the end of a server command:
**iburst**
At every poll interval, send a burst of eight packets instead of one. When the server is not responding, packets are sent 16s apart. When the server responds, packets are sent every 2s. For use with the **server** command to improve the time taken for initial synchronization. This is now a default option in the configuration file.
### 14\.17.12. Configuring Symmetric Authentication Using a Key {#s2_Configuring_Symmetric_Authentication_Using_a_Key}
To configure symmetric authentication using a key, add the following option to the end of a server or peer command:
**key** _`number`_
where _`number`_ is in the range `1` to `65534` inclusive. This option enables the use of a _message authentication code_ (MAC) in packets. This option is for use with the **peer**, **server**, **broadcast**, and **manycastclient** commands.
The option can be used in the `/etc/ntp.conf` file as follows:
server 192.168.1.1 key 10
broadcast 192.168.1.255 key 20
manycastclient 239.255.254.254 key 30
See also [Section 14.6, “Authentication Options for NTP”](#s1-Authentication_Options_for_NTP "14.6. Authentication Options for NTP").
### 14\.17.13. Configuring the Poll Interval {#s2_Configuring_the_Poll_Interval}
To change the default poll interval, add the following options to the end of a server or peer command:
**minpoll** _`value`_ and **maxpoll** _`value`_
Options to change the default poll interval, where the interval in seconds will be calculated by raising 2 to the power of _`value`_, in other words, the interval is expressed in log2 seconds. The default `minpoll` value is 6, 26 equates to 64s. The default value for `maxpoll` is 10, which equates to 1024s. Allowed values are in the range 3 to 17 inclusive, which equates to 8s to 36.4h respectively. These options are for use with the **peer** or **server**. Setting a shorter `maxpoll` may improve clock accuracy.
### 14\.17.14. Configuring Server Preference {#s2_Configuring_Server_Preference}
To specify that a particular server should be preferred above others of similar statistical quality, add the following option to the end of a server or peer command:
**prefer**
Use this server for synchronization in preference to other servers of similar statistical quality. This option is for use with the **peer** or **server** commands.
### 14\.17.15. Configuring the Time-to-Live for NTP Packets {#s2_Configuring_the_Time-To-Live_for_NTP_Packets}
To specify that a particular _time-to-live_ (TTL) value should be used in place of the default, add the following option to the end of a server or peer command:
**ttl** _`value`_
Specify the time-to-live value to be used in packets sent by broadcast servers and multicast `NTP` servers. Specify the maximum time-to-live value to use for the “expanding ring search” by a manycast client. The default value is `127`.
### 14\.17.16. Configuring the NTP Version to Use {#s2_Configuring_The_Version_of_NTP_to_use}
To specify that a particular version of `NTP` should be used in place of the default, add the following option to the end of a server or peer command:
**version** _`value`_
Specify the version of `NTP` set in created `NTP` packets. The value can be in the range `1` to `4`. The default is `4`.
## 14\.18. Configuring the Hardware Clock Update {#s1-Configuring_the_Hardware_Clock_update}
To configure the system clock to update the hardware clock, also known as the real-time clock (RTC), once after executing ntpdate, add the following line to `/etc/sysconfig/ntpdate`:
SYNC_HWCLOCK=yes
To update the hardware clock from the system clock, issue the following command as `root`:
~]# **hwclock --systohc**
When the system clock is being synchronized by `ntpd`, the kernel will in turn update the RTC every 11 minutes automatically.
## 14\.19. Configuring Clock Sources {#s1-Configuring_Clock_Sources}
To list the available clock sources on your system, issue the following commands:
~]$ **cd /sys/devices/system/clocksource/clocksource0/**
clocksource0]$ **cat available_clocksource**
kvm-clock tsc hpet acpi_pm
clocksource0]$ **cat current_clocksource**
kvm-clock
In the above example, the kernel is using kvm-clock. This was selected at boot time as this is a virtual machine.
To override the default clock source, add a line similar to the following in `grub.conf`:
clocksource=tsc
The available clock source is architecture dependent.
## 14\.20. Additional Resources {#s1-ntpd_additional-resources}
The following sources of information provide additional resources regarding `NTP` and `ntpd`.
### 14\.20.1. Installed Documentation {#s2-ntpd-docs-inst}
* `ntpd(8)` man page — Describes `ntpd` in detail, including the command line options.
* `ntp.conf(5)` man page — Contains information on how to configure associations with servers and peers.
* `ntpq(8)` man page — Describes the `NTP` query utility for monitoring and querying an `NTP` server.
* `ntpdc(8)` man page — Describes the `ntpd` utility for querying and changing the state of `ntpd`.
* `ntp_auth(5)` man page — Describes authentication options, commands, and key management for `ntpd`.
* `ntp_keygen(8)` man page — Describes generating public and private keys for `ntpd`.
* `ntp_acc(5)` man page — Describes access control options using the **restrict** command.
* `ntp_mon(5)` man page — Describes monitoring options for the gathering of statistics.
* `ntp_clock(5)` man page — Describes commands for configuring reference clocks.
* `ntp_misc(5)` man page — Describes miscellaneous options.
* `ntp_decode(5)` man page — Lists the status words, event messages and error codes used for `ntpd` reporting and monitoring.
* `ntpstat(8)` man page — Describes a utility for reporting the synchronization state of the `NTP` daemon running on the local machine.
* `ntptime(8)` man page — Describes a utility for reading and setting kernel time variables.
* `tickadj(8)` man page — Describes a utility for reading, and optionally setting, the length of the tick.
### 14\.20.2. Useful Websites {#s2-ntpd_useful-websites}
: The NTP Documentation Archive
: Network Time Synchronization Research Project.
: Information on Automatic Server Discovery in `NTPv4`.
## Chapter 15. Configuring PTP Using ptp4l {#ch-Configuring_PTP_Using_ptp4l}
## 15\.1. Introduction to PTP {#sec-Introduction_to_PTP}
The _Precision Time Protocol_ (PTP) is a protocol used to synchronize clocks in a network. When used in conjunction with hardware support, `PTP` is capable of sub-microsecond accuracy, which is far better than is normally obtainable with `NTP`. `PTP` support is divided between the kernel and user space. The kernel in Fedora includes support for `PTP` clocks, which are provided by network drivers. The actual implementation of the protocol is known as linuxptp, a `PTPv2` implementation according to the IEEE standard 1588 for Linux.
The linuxptp package includes the ptp4l and phc2sys programs for clock synchronization. The ptp4l program implements the `PTP` boundary clock and ordinary clock. With hardware time stamping, it is used to synchronize the `PTP` hardware clock to the master clock, and with software time stamping it synchronizes the system clock to the master clock. The phc2sys program is needed only with hardware time stamping, for synchronizing the system clock to the `PTP` hardware clock on the _network interface card_ (NIC).
### 15\.1.1. Understanding PTP {#sec-Understanding_PTP}
The clocks synchronized by `PTP` are organized in a master-slave hierarchy. The slaves are synchronized to their masters which may be slaves to their own masters. The hierarchy is created and updated automatically by the _best master clock_ (BMC) algorithm, which runs on every clock. When a clock has only one port, it can be _master_ or _slave_, such a clock is called an _ordinary clock_ (OC). A clock with multiple ports can be master on one port and slave on another, such a clock is called a _boundary_ clock (BC). The top-level master is called the _grandmaster clock_, which can be synchronized by using a _Global Positioning System_ (GPS) time source. By using a GPS-based time source, disparate networks can be synchronized with a high-degree of accuracy.
Figure 15.1. PTP grandmaster, boundary, and slave Clocks
![PTP grandmaster, boundary, and slave Clocks][63]
[[D](ld-mediaobj-ptp_grandmaster_boundary_and_slaves.png.html)]
### 15\.1.2. Advantages of PTP {#sec-Advantages_of_PTP}
One of the main advantages that `PTP` has over the _Network Time Protocol_ (NTP) is hardware support present in various _network interface controllers_ (NIC) and network switches. This specialized hardware allows `PTP` to account for delays in message transfer, and greatly improves the accuracy of time synchronization. While it is possible to use non-PTP enabled hardware components within the network, this will often cause an increase in jitter or introduce an asymmetry in the delay resulting in synchronization inaccuracies, which add up with multiple non-PTP aware components used in the communication path. To achieve the best possible accuracy, it is recommended that all networking components between `PTP` clocks are `PTP` hardware enabled. Time synchronization in larger networks where not all of the networking hardware supports `PTP` might be better suited for `NTP`.
With hardware `PTP` support, the NIC has its own on-board clock, which is used to time stamp the received and transmitted `PTP` messages. It is this on-board clock that is synchronized to the `PTP` master, and the computer's system clock is synchronized to the `PTP` hardware clock on the NIC. With software `PTP` support, the system clock is used to time stamp the `PTP` messages and it is synchronized to the `PTP` master directly. Hardware `PTP` support provides better accuracy since the NIC can time stamp the `PTP` packets at the exact moment they are sent and received while software `PTP` support requires additional processing of the `PTP` packets by the operating system.
## 15\.2. Using PTP {#sec-Using_PTP}
In order to use `PTP`, the kernel network driver for the intended interface has to support either software or hardware time stamping capabilities.
### 15\.2.1. Checking for Driver and Hardware Support {#sec-Checking_for_Driver_and_Hardware_Support}
In addition to hardware time stamping support being present in the driver, the NIC must also be capable of supporting this functionality in the physical hardware. The best way to verify the time stamping capabilities of a particular driver and NIC is to use the ethtool utility to query the interface as follows:
~]# **ethtool -T _`em3`_**
Time stamping parameters for em3:
Capabilities:
hardware-transmit (SOF_TIMESTAMPING_TX_HARDWARE)
software-transmit (SOF_TIMESTAMPING_TX_SOFTWARE)
hardware-receive (SOF_TIMESTAMPING_RX_HARDWARE)
software-receive (SOF_TIMESTAMPING_RX_SOFTWARE)
software-system-clock (SOF_TIMESTAMPING_SOFTWARE)
hardware-raw-clock (SOF_TIMESTAMPING_RAW_HARDWARE)
PTP Hardware Clock: 0
Hardware Transmit Timestamp Modes:
off (HWTSTAMP_TX_OFF)
on (HWTSTAMP_TX_ON)
Hardware Receive Filter Modes:
none (HWTSTAMP_FILTER_NONE)
all (HWTSTAMP_FILTER_ALL)
Where _`em3`_ is the interface you wish to check.
For software time stamping support, the parameters list should include:
* `SOF_TIMESTAMPING_SOFTWARE `
* `SOF_TIMESTAMPING_TX_SOFTWARE `
* `SOF_TIMESTAMPING_RX_SOFTWARE `
For hardware time stamping support, the parameters list should include:
* `SOF_TIMESTAMPING_RAW_HARDWARE `
* `SOF_TIMESTAMPING_TX_HARDWARE `
* `SOF_TIMESTAMPING_RX_HARDWARE `
### 15\.2.2. Installing PTP {#sec-Installing_PTP}
The kernel in Fedora includes support for `PTP`. User space support is provided by the tools in the linuxptp package. To install linuxptp, issue the following command as `root`:
~]# **yum install linuxptp**
This will install ptp4l and phc2sys.
Do not run more than one service to set the system clock's time at the same time. If you intend to serve `PTP` time using `NTP`, see [Section 15.7, “Serving PTP Time with NTP”](#sec-Serving_PTP_Time_with_NTP "15.7. Serving PTP Time with NTP").
### 15\.2.3. Starting ptp4l {#sec-Starting_ptp4l}
The ptp4l program tries to use hardware time stamping by default. To use ptp4l with hardware time stamping capable drivers and NICs, you must provide the network interface to use with the `-i` option. Enter the following command as `root`:
~]# **ptp4l -i _`em3`_ -m**
Where _`em3`_ is the interface you wish to configure. Below is example output from ptp4l when the `PTP` clock on the NIC is synchronized to a master:
~]# **ptp4l -i _`em3`_ -m**
selected em3 as PTP clock
port 1: INITIALIZING to LISTENING on INITIALIZE
port 0: INITIALIZING to LISTENING on INITIALIZE
port 1: new foreign master 00a069.fffe.0b552d-1
selected best master clock 00a069.fffe.0b552d
port 1: LISTENING to UNCALIBRATED on RS_SLAVE
master offset -23947 s0 freq +0 path delay 11350
master offset -28867 s0 freq +0 path delay 11236
master offset -32801 s0 freq +0 path delay 10841
master offset -37203 s1 freq +0 path delay 10583
master offset -7275 s2 freq -30575 path delay 10583
port 1: UNCALIBRATED to SLAVE on MASTER_CLOCK_SELECTED
master offset -4552 s2 freq -30035 path delay 10385
The master offset value is the measured offset from the master in nanoseconds. The `s0`, `s1`, `s2` strings indicate the different clock servo states: `s0` is unlocked, `s1` is clock step and `s2` is locked. Once the servo is in the locked state (`s2`), the clock will not be stepped (only slowly adjusted) unless the `pi_offset_const` option is set to a positive value in the configuration file (described in the `ptp4l(8)` man page). The `adj` value is the frequency adjustment of the clock in parts per billion (ppb). The path delay value is the estimated delay of the synchronization messages sent from the master in nanoseconds. Port 0 is a Unix domain socket used for local `PTP` management. Port 1 is the `em3` interface (based on the example above.) INITIALIZING, LISTENING, UNCALIBRATED and SLAVE are some of possible port states which change on the INITIALIZE, RS\_SLAVE, MASTER\_CLOCK\_SELECTED events. In the last state change message, the port state changed from UNCALIBRATED to SLAVE indicating successful synchronization with a `PTP` master clock.
The ptp4l program can also be started as a service by running:
~]# **systemctl start ptp4l**
When running as a service, options are specified in the `/etc/sysconfig/ptp4l` file. More information on the different ptp4l options and the configuration file settings can be found in the `ptp4l(8)` man page.
By default, messages are sent to `/var/log/messages`. However, specifying the `-m` option enables logging to standard output which can be useful for debugging purposes.
To enable software time stamping, the `-S` option needs to be used as follows:
~]# **ptp4l -i _`em3`_ -m -S**
#### 15\.2.3.1. Selecting a Delay Measurement Mechanism {#sec-Selecting_a_Delay_Mechanism}
There are two different delay measurement mechanisms and they can be selected by means of an option added to the **ptp4l** command as follows:
`-P`
: The `-P` selects the _ peer-to-peer_ (P2P) delay measurement mechanism.
The P2P mechanism is preferred as it reacts to changes in the network topology faster, and may be more accurate in measuring the delay, than other mechanisms. The P2P mechanism can only be used in topologies where each port exchanges PTP messages with at most one other P2P port. It must be supported and used by all hardware, including transparent clocks, on the communication path.
`-E`
: The `-E` selects the _end-to-end_ (E2E) delay measurement mechanism. This is the default.
The E2E mechanism is also referred to as the delay “request-response” mechanism.
`-A`
: The `-A` enables automatic selection of the delay measurement mechanism.
The automatic option starts ptp4l in E2E mode. It will change to P2P mode if a peer delay request is received.
### Note
All clocks on a single `PTP` communication path must use the same mechanism to measure the delay. A warning will be printed when a peer delay request is received on a port using the E2E mechanism. A warning will be printed when a E2E delay request is received on a port using the P2P mechanism.
## 15\.3. Specifying a Configuration File {#sec-Specifying_a_Configuration_File}
The command line options and other options, which cannot be set on the command line, can be set in an optional configuration file.
No configuration file is read by default, so it needs to be specified at runtime with the `-f` option. For example:
~]# **ptp4l -f /etc/ptp4l.conf**
A configuration file equivalent to the **-i em3 -m -S** options shown above would look as follows:
~]# **cat /etc/ptp4l.conf**
[global]
verbose 1
time_stamping software
[em3]
## 15\.4. Using the PTP Management Client {#sec-Using_the_PTP_Management_Client}
The `PTP` management client, pmc, can be used to obtain additional information from ptp4l as follows:
~]# **pmc -u -b 0 'GET CURRENT_DATA_SET'**
sending: GET CURRENT_DATA_SET
90e2ba.fffe.20c7f8-0 seq 0 RESPONSE MANAGMENT CURRENT_DATA_SET
stepsRemoved 1
offsetFromMaster -142.0
meanPathDelay 9310.0
~]# **pmc -u -b 0 'GET TIME_STATUS_NP'**
sending: GET TIME_STATUS_NP
90e2ba.fffe.20c7f8-0 seq 0 RESPONSE MANAGMENT TIME_STATUS_NP
master_offset 310
ingress_time 1361545089345029441
cumulativeScaledRateOffset +1.000000000
scaledLastGmPhaseChange 0
gmTimeBaseIndicator 0
lastGmPhaseChange 0x0000'0000000000000000.0000
gmPresent true
gmIdentity 00a069.fffe.0b552d
Setting the `-b` option to `zero` limits the boundary to the locally running ptp4l instance. A larger boundary value will retrieve the information also from `PTP` nodes further from the local clock. The retrievable information includes:
* `stepsRemoved` is the number of communication paths to the grandmaster clock.
* `offsetFromMaster` and master\_offset is the last measured offset of the clock from the master in nanoseconds.
* `meanPathDelay` is the estimated delay of the synchronization messages sent from the master in nanoseconds.
* if `gmPresent` is true, the `PTP` clock is synchronized to a master, the local clock is not the grandmaster clock.
* `gmIdentity` is the grandmaster's identity.
For a full list of pmc commands, type the following as `root`:
~]# **pmc help**
Additional information is available in the `pmc(8)` man page.
## 15\.5. Synchronizing the Clocks {#sec-Synchronizing_the_Clocks}
The phc2sys program is used to synchronize the system clock to the `PTP` hardware clock (PHC) on the NIC. To start phc2sys, where _`em3`_ is the interface with the `PTP` hardware clock, enter the following command as `root`:
~]# **phc2sys -s _`em3`_ -w**
The `-w` option waits for the running ptp4l application to synchronize the `PTP` clock and then retrieves the TAI to UTC offset from ptp4l.
Normally, `PTP` operates in the _International Atomic Time_ (TAI) timescale, while the system clock is kept in _Coordinated Universal Time_ (UTC). The current offset between the TAI and UTC timescales is 35 seconds. The offset changes when leap seconds are inserted or deleted, which typically happens every few years. The `-O` option needs to be used to set this offset manually when the `-w` is not used, as follows:
~]# **phc2sys -s _`em3`_ -O -35**
Once the phc2sys servo is in a locked state, the clock will not be stepped, unless the `-S` option is used. This means that the phc2sys program should be started after the ptp4l program has synchronized the `PTP` hardware clock. However, with `-w`, it is not necessary to start phc2sys after ptp4l as it will wait for it to synchronize the clock.
The phc2sys program can also be started as a service by running:
~]# **systemctl start phc2sys**
When running as a service, options are specified in the `/etc/sysconfig/phc2sys` file. More information on the different phc2sys options can be found in the `phc2sys(8)` man page.
Note that the examples in this section assume the command is run on a slave system or slave port.
## 15\.6. Verifying Time Synchronization {#sec-Verifying_Time_Synchronization}
When `PTP` time synchronization is working properly, new messages with offsets and frequency adjustments will be printed periodically to the ptp4l and phc2sys (if hardware time stamping is used) outputs. These values will eventually converge after a short period of time. These messages can be seen in `/var/log/messages` file. An example of the output follows:
ptp4l[352.359]: selected /dev/ptp0 as PTP clock
ptp4l[352.361]: port 1: INITIALIZING to LISTENING on INITIALIZE
ptp4l[352.361]: port 0: INITIALIZING to LISTENING on INITIALIZE
ptp4l[353.210]: port 1: new foreign master 00a069.fffe.0b552d-1
ptp4l[357.214]: selected best master clock 00a069.fffe.0b552d
ptp4l[357.214]: port 1: LISTENING to UNCALIBRATED on RS_SLAVE
ptp4l[359.224]: master offset 3304 s0 freq +0 path delay 9202
ptp4l[360.224]: master offset 3708 s1 freq -29492 path delay 9202
ptp4l[361.224]: master offset -3145 s2 freq -32637 path delay 9202
ptp4l[361.224]: port 1: UNCALIBRATED to SLAVE on MASTER_CLOCK_SELECTED
ptp4l[362.223]: master offset -145 s2 freq -30580 path delay 9202
ptp4l[363.223]: master offset 1043 s2 freq -29436 path delay 8972
ptp4l[364.223]: master offset 266 s2 freq -29900 path delay 9153
ptp4l[365.223]: master offset 430 s2 freq -29656 path delay 9153
ptp4l[366.223]: master offset 615 s2 freq -29342 path delay 9169
ptp4l[367.222]: master offset -191 s2 freq -29964 path delay 9169
ptp4l[368.223]: master offset 466 s2 freq -29364 path delay 9170
ptp4l[369.235]: master offset 24 s2 freq -29666 path delay 9196
ptp4l[370.235]: master offset -375 s2 freq -30058 path delay 9238
ptp4l[371.235]: master offset 285 s2 freq -29511 path delay 9199
ptp4l[372.235]: master offset -78 s2 freq -29788 path delay 9204
An example of the phc2sys output follows:
phc2sys[526.527]: Waiting for ptp4l...
phc2sys[527.528]: Waiting for ptp4l...
phc2sys[528.528]: phc offset 55341 s0 freq +0 delay 2729
phc2sys[529.528]: phc offset 54658 s1 freq -37690 delay 2725
phc2sys[530.528]: phc offset 888 s2 freq -36802 delay 2756
phc2sys[531.528]: phc offset 1156 s2 freq -36268 delay 2766
phc2sys[532.528]: phc offset 411 s2 freq -36666 delay 2738
phc2sys[533.528]: phc offset -73 s2 freq -37026 delay 2764
phc2sys[534.528]: phc offset 39 s2 freq -36936 delay 2746
phc2sys[535.529]: phc offset 95 s2 freq -36869 delay 2733
phc2sys[536.529]: phc offset -359 s2 freq -37294 delay 2738
phc2sys[537.529]: phc offset -257 s2 freq -37300 delay 2753
phc2sys[538.529]: phc offset 119 s2 freq -37001 delay 2745
phc2sys[539.529]: phc offset 288 s2 freq -36796 delay 2766
phc2sys[540.529]: phc offset -149 s2 freq -37147 delay 2760
phc2sys[541.529]: phc offset -352 s2 freq -37395 delay 2771
phc2sys[542.529]: phc offset 166 s2 freq -36982 delay 2748
phc2sys[543.529]: phc offset 50 s2 freq -37048 delay 2756
phc2sys[544.530]: phc offset -31 s2 freq -37114 delay 2748
phc2sys[545.530]: phc offset -333 s2 freq -37426 delay 2747
phc2sys[546.530]: phc offset 194 s2 freq -36999 delay 2749
For ptp4l there is also a directive, `summary_interval`, to reduce the output and print only statistics, as normally it will print a message every second or so. For example, to reduce the output to every `1024` seconds, add the following line to the `/etc/ptp4l.conf` file:
summary_interval 10
An example of the ptp4l output, with `summary_interval 6`, follows:
ptp4l: [615.253] selected /dev/ptp0 as PTP clock
ptp4l: [615.255] port 1: INITIALIZING to LISTENING on INITIALIZE
ptp4l: [615.255] port 0: INITIALIZING to LISTENING on INITIALIZE
ptp4l: [615.564] port 1: new foreign master 00a069.fffe.0b552d-1
ptp4l: [619.574] selected best master clock 00a069.fffe.0b552d
ptp4l: [619.574] port 1: LISTENING to UNCALIBRATED on RS_SLAVE
ptp4l: [623.573] port 1: UNCALIBRATED to SLAVE on MASTER_CLOCK_SELECTED
ptp4l: [684.649] rms 669 max 3691 freq -29383 ± 3735 delay 9232 ± 122
ptp4l: [748.724] rms 253 max 588 freq -29787 ± 221 delay 9219 ± 158
ptp4l: [812.793] rms 287 max 673 freq -29802 ± 248 delay 9211 ± 183
ptp4l: [876.853] rms 226 max 534 freq -29795 ± 197 delay 9221 ± 138
ptp4l: [940.925] rms 250 max 562 freq -29801 ± 218 delay 9199 ± 148
ptp4l: [1004.988] rms 226 max 525 freq -29802 ± 196 delay 9228 ± 143
ptp4l: [1069.065] rms 300 max 646 freq -29802 ± 259 delay 9214 ± 176
ptp4l: [1133.125] rms 226 max 505 freq -29792 ± 197 delay 9225 ± 159
ptp4l: [1197.185] rms 244 max 688 freq -29790 ± 211 delay 9201 ± 162
To reduce the output from the phc2sys, it can be called it with the `-u` option as follows:
~]# **phc2sys -u _`summary-updates`_**
Where _`summary-updates`_ is the number of clock updates to include in summary statistics. An example follows:
~]# **phc2sys -s em3 -w -m -u 60**
phc2sys[700.948]: rms 1837 max 10123 freq -36474 ± 4752 delay 2752 ± 16
phc2sys[760.954]: rms 194 max 457 freq -37084 ± 174 delay 2753 ± 12
phc2sys[820.963]: rms 211 max 487 freq -37085 ± 185 delay 2750 ± 19
phc2sys[880.968]: rms 183 max 440 freq -37102 ± 164 delay 2734 ± 91
phc2sys[940.973]: rms 244 max 584 freq -37095 ± 216 delay 2748 ± 16
phc2sys[1000.979]: rms 220 max 573 freq -36666 ± 182 delay 2747 ± 43
phc2sys[1060.984]: rms 266 max 675 freq -36759 ± 234 delay 2753 ± 17
## 15\.7. Serving PTP Time with NTP {#sec-Serving_PTP_Time_with_NTP}
The `ntpd` daemon can be configured to distribute the time from the system clock synchronized by ptp4l or phc2sys by using the LOCAL reference clock driver. To prevent `ntpd` from adjusting the system clock, the `ntp.conf` file must not specify any `NTP` servers. The following is a minimal example of `ntp.conf`:
~]# **cat /etc/ntp.conf**
server 127.127.1.0
fudge 127.127.1.0 stratum 0
### Note
When the `DHCP` client program, dhclient, receives a list of `NTP` servers from the `DHCP` server, it adds them to `ntp.conf` and restarts the service. To disable that feature, add **PEERNTP=no** to `/etc/sysconfig/network`.
## 15\.8. Serving NTP Time with PTP {#sec-Serving_NTP_Time_with_PTP}
`NTP` to `PTP` synchronization in the opposite direction is also possible. When `ntpd` is used to synchronize the system clock, ptp4l can be configured with the `priority1` option (or other clock options included in the best master clock algorithm) to be the grandmaster clock and distribute the time from the system clock via `PTP`:
~]# **cat /etc/ptp4l.conf**
[global]
priority1 127
[em3]
# ptp4l -f /etc/ptp4l.conf
With hardware time stamping, phc2sys needs to be used to synchronize the `PTP` hardware clock to the system clock:
~]# **phc2sys -c _`em3`_ -s CLOCK_REALTIME -w**
To prevent quick changes in the `PTP` clock's frequency, the synchronization to the system clock can be loosened by using smaller `P` (proportional) and `I` (integral) constants of the PI servo:
~]# **phc2sys -c _`em3`_ -s CLOCK_REALTIME -w -P 0.01 -I 0.0001**
## 15\.9. Improving Accuracy {#sec-Improving_Accuracy}
Test results indicate that disabling the tickless kernel capability can significantly improve the stability of the system clock, and thus improve the `PTP` synchronization accuracy (at the cost of increased power consumption). The kernel tickless mode can be disabled by adding `nohz=off` to the kernel boot option parameters.
## 15\.10. Additional Resources {#sec-PTP_additional_resources}
The following sources of information provide additional resources regarding `PTP` and the ptp4l tools.
### 15\.10.1. Installed Documentation {#sec-PTP-docs-inst}
* `ptp4l(8)` man page — Describes ptp4l options including the format of the configuration file.
* `pmc(8)` man page — Describes the `PTP` management client and its command options.
* `phc2sys(8)` man page — Describes a tool for synchronizing the system clock to a `PTP` hardware clock (PHC).
### 15\.10.2. Useful Websites {#sec-PTP_useful-websites}
: The Linux PTP project.
: The IEEE 1588 Standard.
# Part V. Monitoring and Automation {#part-Monitoring_and_Automation}
This part describes various tools that allow system administrators to monitor system performance, automate system tasks, and report bugs.
## Chapter 16. System Monitoring Tools {#ch-System_Monitoring_Tools}
In order to configure the system, system administrators often need to determine the amount of free memory, how much free disk space is available, how the hard drive is partitioned, or what processes are running.
## 16\.1. Viewing System Processes {#s1-sysinfo-system-processes}
### 16\.1.1. Using the ps Command {#s2-sysinfo-system-processes-ps}
The **ps** command allows you to display information about running processes. It produces a static list, that is, a snapshot of what is running when you execute the command. If you want a constantly updated list of running processes, use the **top** command or the System Monitor application instead.
To list all processes that are currently running on the system including processes owned by other users, type the following at a shell prompt:
**ps** `ax`
For each listed process, the **ps ax** command displays the process ID (`PID`), the terminal that is associated with it (`TTY`), the current status (`STAT`), the cumulated CPU time (`TIME`), and the name of the executable file (`COMMAND`). For example:
~]$ **ps ax**
PID TTY STAT TIME COMMAND
1 ? Ss 0:02 /usr/lib/systemd/systemd --system --deserialize 20
2 ? S 0:00 [kthreadd]
3 ? S 0:00 [ksoftirqd/0]
5 ? S 0:00 [kworker/u:0]
6 ? S 0:00 [migration/0]
_[output truncated]_
To display the owner alongside each process, use the following command:
**ps** `aux`
Apart from the information provided by the **ps ax** command, **ps aux** displays the effective username of the process owner (`USER`), the percentage of the CPU (`%CPU`) and memory (`%MEM`) usage, the virtual memory size in kilobytes (`VSZ`), the non-swapped physical memory size in kilobytes (`RSS`), and the time or date the process was started. For instance:
~]$ **ps aux**
USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
root 1 0.0 0.3 53128 2988 ? Ss 13:28 0:02 /usr/lib/systemd/systemd --system --deserialize 20
root 2 0.0 0.0 0 0 ? S 13:28 0:00 [kthreadd]
root 3 0.0 0.0 0 0 ? S 13:28 0:00 [ksoftirqd/0]
root 5 0.0 0.0 0 0 ? S 13:28 0:00 [kworker/u:0]
root 6 0.0 0.0 0 0 ? S 13:28 0:00 [migration/0]
_[output truncated]_
You can also use the **ps** command in a combination with **grep** to see if a particular process is running. For example, to determine if Emacs is running, type:
~]$ **ps ax | grep emacs**
2625 ? Sl 0:00 emacs
For a complete list of available command line options, refer to the **ps**(1) manual page.
### 16\.1.2. Using the top Command {#s2-sysinfo-system-processes-top}
The **top** command displays a real-time list of processes that are running on the system. It also displays additional information about the system uptime, current CPU and memory usage, or total number of running processes, and allows you to perform actions such as sorting the list or killing a process.
To run the **top** command, type the following at a shell prompt:
**top**
For each listed process, the **top** command displays the process ID (`PID`), the effective username of the process owner (`USER`), the priority (`PR`), the nice value (`NI`), the amount of virtual memory the process uses (`VIRT`), the amount of non-swapped physical memory the process uses (`RES`), the amount of shared memory the process uses (`SHR`), the percentage of the CPU (`%CPU`) and memory (`%MEM`) usage, the cumulated CPU time (`TIME+`), and the name of the executable file (`COMMAND`). For example:
~]$ **top**
top - 19:22:08 up 5:53, 3 users, load average: 1.08, 1.03, 0.82
Tasks: 117 total, 2 running, 115 sleeping, 0 stopped, 0 zombie
Cpu(s): 9.3%us, 1.3%sy, 0.0%ni, 85.1%id, 0.0%wa, 1.7%hi, 0.0%si, 2.6%st
Mem: 761956k total, 617256k used, 144700k free, 24356k buffers
Swap: 1540092k total, 55780k used, 1484312k free, 256408k cached
PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
510 john 20 0 1435m 99m 18m S 9.0 13.3 3:30.52 gnome-shell
32686 root 20 0 156m 27m 3628 R 2.0 3.7 0:48.69 Xorg
2625 john 20 0 488m 27m 14m S 0.3 3.7 0:00.70 emacs
1 root 20 0 53128 2640 1152 S 0.0 0.3 0:02.83 systemd
2 root 20 0 0 0 0 S 0.0 0.0 0:00.01 kthreadd
3 root 20 0 0 0 0 S 0.0 0.0 0:00.18 ksoftirqd/0
5 root 20 0 0 0 0 S 0.0 0.0 0:00.00 kworker/u:0
6 root RT 0 0 0 0 S 0.0 0.0 0:00.00 migration/0
7 root RT 0 0 0 0 S 0.0 0.0 0:00.30 watchdog/0
8 root 0 -20 0 0 0 S 0.0 0.0 0:00.00 cpuset
9 root 0 -20 0 0 0 S 0.0 0.0 0:00.00 khelper
10 root 20 0 0 0 0 S 0.0 0.0 0:00.00 kdevtmpfs
11 root 0 -20 0 0 0 S 0.0 0.0 0:00.00 netns
12 root 20 0 0 0 0 S 0.0 0.0 0:00.11 sync_supers
13 root 20 0 0 0 0 S 0.0 0.0 0:00.00 bdi-default
14 root 0 -20 0 0 0 S 0.0 0.0 0:00.00 kintegrityd
15 root 0 -20 0 0 0 S 0.0 0.0 0:00.00 kblockd
[Table 16.1, “Interactive top commands”](#interactive-top-command "Table 16.1. Interactive top commands") contains useful interactive commands that you can use with **top**. For more information, refer to the **top**(1) manual page.
Table 16.1. Interactive top commands
|Command|Description|
|-|
|**Enter**, **Space**|Immediately refreshes the display.|
|**h**, **?**|Displays a help screen.|
|**k**|Kills a process. You are prompted for the process ID and the signal to send to it.|
|**n**|Changes the number of displayed processes. You are prompted to enter the number.|
|**u**|Sorts the list by user.|
|**M**|Sorts the list by memory usage.|
|**P**|Sorts the list by CPU usage.|
|**q**|Terminates the utility and returns to the shell prompt.|
### 16\.1.3. Using the System Monitor Tool {#s2-sysinfo-system-processes-system_monitor}
The Processes tab of the System Monitor tool allows you to view, search for, change the priority of, and kill processes from the graphical user interface.
To start the System Monitor tool, either select Applications → System Tools → System Monitor from the Activities menu, or type **gnome-system-monitor** at a shell prompt. Then click the Processes tab to view the list of running processes.
Figure 16.1. System Monitor — Processes
![System Monitor — Processes][64]
[[D](ld-idm73487200.html)]
For each listed process, the System Monitor tool displays its name (Process Name), current status (Status), percentage of the memory usage (% CPU), nice value (Nice), process ID (ID), memory usage (Memory), the channel the process is waiting in (Waiting Channel), and additional details about the session (Session). To sort the information by a specific column in ascending order, click the name of that column. Click the name of the column again to toggle the sort between ascending and descending order.
By default, the System Monitor tool displays a list of processes that are owned by the current user. Selecting various options from the View menu allows you to:
* view only active processes,
* view all processes,
* view your processes,
* view process dependencies,
* view a memory map of a selected process,
* view the files opened by a selected process, and
* refresh the list of processes.
Additionally, various options in the Edit menu allows you to:
* stop a process,
* continue running a stopped process,
* end a process,
* kill a process,
* change the priority of a selected process, and
* edit the System Monitor preferences, such as the refresh interval for the list of processes, or what information to show.
You can also end a process by selecting it from the list and clicking the End Process button.
## 16\.2. Viewing Memory Usage {#s1-sysinfo-memory-usage}
### 16\.2.1. Using the free Command {#s2-sysinfo-memory-usage-free}
The **free** command allows you to display the amount of free and used memory on the system. To do so, type the following at a shell prompt:
**free**
The **free** command provides information about both the physical memory (`Mem`) and swap space (`Swap`). It displays the total amount of memory (`total`), as well as the amount of memory that is in use (`used`), free (`free`), shared (`shared`), in kernel buffers (`buffers`), and cached (`cached`). For example:
~]$ **free**
total used free shared buffers cached
Mem: 761956 607500 154456 0 37404 156176
-/+ buffers/cache: 413920 348036
Swap: 1540092 84408 1455684
By default, **free** displays the values in kilobytes. To display the values in megabytes, supply the `-m` command line option:
**free** `-m`
For instance:
~]$ **free -m**
total used free shared buffers cached
Mem: 744 593 150 0 36 152
-/+ buffers/cache: 404 339
Swap: 1503 82 1421
For a complete list of available command line options, refer to the **free**(1) manual page.
### 16\.2.2. Using the System Monitor Tool {#s2-sysinfo-memory-usage-system_monitor}
The Resources tab of the System Monitor tool allows you to view the amount of free and used memory on the system.
To start the System Monitor tool, either select Applications → System Tools → System Monitor from the Activities menu, or type **gnome-system-monitor** at a shell prompt. Then click the Resources tab to view the system's memory usage.
Figure 16.2. System Monitor — Resources
![System Monitor — Resources][65]
[[D](ld-idm1791984.html)]
In the Memory and Swap History section, the System Monitor tool displays a graphical representation of the memory and swap usage history, as well as the total amount of the physical memory (Memory) and swap space (Swap) and how much of it is in use.
## 16\.3. Viewing CPU Usage {#s1-sysinfo-cpu}
### 16\.3.1. Using the System Monitor Tool {#s2-sysinfo-cpu-system_monitor}
The Resources tab of the System Monitor tool allows you to view the current CPU usage on the system.
To start the System Monitor tool, either select Applications → System Tools → System Monitor from the Activities menu, or type **gnome-system-monitor** at a shell prompt. Then click the Resources tab to view the system's CPU usage.
Figure 16.3. System Monitor — Resources
![System Monitor — Resources][66]
[[D](ld-idm122795904.html)]
In the CPU History section, the System Monitor tool displays a graphical representation of the CPU usage history and shows the percentage of how much CPU is currently in use.
## 16\.4. Viewing Block Devices and File Systems {#s1-sysinfo-filesystems}
### 16\.4.1. Using the lsblk Command {#s2-sysinfo-filesystems-lsblk}
The **lsblk** command allows you to display a list of available block devices. To do so, type the following at a shell prompt:
**lsblk**
For each listed block device, the **lsblk** command displays the device name (`NAME`), major and minor device number (`MAJ:MIN`), if the device is removable (`RM`), what is its size (`SIZE`), if the device is read-only (`RO`), what type is it (`TYPE`), and where the device is mounted (`MOUNTPOINT`). For example:
~]$ **lsblk**
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
sr0 11:0 1 1024M 0 rom
vda 252:0 0 20G 0 disk
|-vda1 252:1 0 500M 0 part /boot
`-vda2 252:2 0 19.5G 0 part
|-vg_fedora-lv_swap (dm-0) 253:0 0 1.5G 0 lvm [SWAP]
`-vg_fedora-lv_root (dm-1) 253:1 0 18G 0 lvm /
By default, **lsblk** lists block devices in a tree-like format. To display the information as an ordinary list, add the `-l` command line option:
**lsblk** `-l`
For instance:
~]$ **lsblk -l**
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
sr0 11:0 1 1024M 0 rom
vda 252:0 0 20G 0 disk
vda1 252:1 0 500M 0 part /boot
vda2 252:2 0 19.5G 0 part
vg_fedora-lv_swap (dm-0) 253:0 0 1.5G 0 lvm [SWAP]
vg_fedora-lv_root (dm-1) 253:1 0 18G 0 lvm /
For a complete list of available command line options, refer to the **lsblk**(8) manual page.
### 16\.4.2. Using the blkid Command {#s2-sysinfo-filesystems-blkid}
The **blkid** command allows you to display information about available block devices. To do so, type the following at a shell prompt as `root`:
**blkid**
For each listed block device, the **blkid** command displays available attributes such as its _universally unique identifier_ (`UUID`), file system type (`TYPE`), or volume label (`LABEL`). For example:
~]# **blkid**
/dev/vda1: UUID="4ea24c68-ab10-47d4-8a6b-b8d3a002acba" TYPE="ext4"
/dev/vda2: UUID="iJ9YwJ-leFf-A1zb-VVaK-H9t1-raLW-HoqlUG" TYPE="LVM2_member"
/dev/mapper/vg_fedora-lv_swap: UUID="d6d755bc-3e3e-4e8f-9bb5-a5e7f4d86ffd" TYPE="swap"
/dev/mapper/vg_fedora-lv_root: LABEL="_Fedora-17-x86_6" UUID="77ba9149-751a-48e0-974f-ad94911734b9" TYPE="ext4"
By default, the **lsblk** command lists all available block devices. To display information about a particular device only, specify the device name on the command line:
**blkid** _`device_name`_
For instance, to display information about `/dev/vda1`, type:
~]# **blkid /dev/vda1**
/dev/vda1: UUID="4ea24c68-ab10-47d4-8a6b-b8d3a002acba" TYPE="ext4"
You can also use the above command with the `-p` and `-o udev` command line options to obtain more detailed information. Note that `root` privileges are required to run this command:
**blkid** `-po` `udev` _`device_name`_
For example:
~]# **blkid -po udev /dev/vda1**
ID_FS_UUID=4ea24c68-ab10-47d4-8a6b-b8d3a002acba
ID_FS_UUID_ENC=4ea24c68-ab10-47d4-8a6b-b8d3a002acba
ID_FS_VERSION=1.0
ID_FS_TYPE=ext4
ID_FS_USAGE=filesystem
ID_PART_ENTRY_SCHEME=dos
ID_PART_ENTRY_TYPE=0x83
ID_PART_ENTRY_FLAGS=0x80
ID_PART_ENTRY_NUMBER=1
ID_PART_ENTRY_OFFSET=2048
ID_PART_ENTRY_SIZE=1024000
ID_PART_ENTRY_DISK=252:0
For a complete list of available command line options, refer to the **blkid**(8) manual page.
### 16\.4.3. Using the partx Command {#s2-sysinfo-filesystems-partx}
The **partx** command allows you to display a list of disk partitions. To list the partition table of a particular disk, as `root`, run this command with the `-s` option followed by the device name:
**partx** `-s` _`device_name`_
For example, to list partitions on `/dev/vda`, type:
~]# **partx -s /dev/vda**
NR START END SECTORS SIZE NAME UUID
1 2048 1026047 1024000 500M
2 1026048 41943039 40916992 19.5G
For a complete list of available command line options, refer to the **partx**(8) manual page.
### 16\.4.4. Using the findmnt Command {#s2-sysinfo-filesystems-findmnt}
The **findmnt** command allows you to display a list of currently mounted file systems. To do so, type the following at a shell prompt:
**findmnt**
For each listed file system, the **findmnt** command displays the target mount point (`TARGET`), source device (`SOURCE`), file system type (`FSTYPE`), and relevant mount options (`OPTIONS`). For example:
~]$ **findmnt**
TARGET SOURCE FSTYPE OPTIONS
/ /dev/mapper/vg_fedora-lv_root
ext4 rw,relatime,seclabel,data=o
|-/proc proc proc rw,nosuid,nodev,noexec,rela
| `-/proc/sys/fs/binfmt_misc systemd-1 autofs rw,relatime,fd=23,pgrp=1,ti
|-/sys sysfs sysfs rw,nosuid,nodev,noexec,rela
| |-/sys/kernel/security securityfs security rw,nosuid,nodev,noexec,rela
| |-/sys/fs/selinux selinuxfs selinuxf rw,relatime
| |-/sys/fs/cgroup tmpfs tmpfs rw,nosuid,nodev,noexec,secl
| | |-/sys/fs/cgroup/systemd cgroup cgroup rw,nosuid,nodev,noexec,rela
| | |-/sys/fs/cgroup/cpuset cgroup cgroup rw,nosuid,nodev,noexec,rela
| | |-/sys/fs/cgroup/cpu,cpuacct cgroup cgroup rw,nosuid,nodev,noexec,rela
| | |-/sys/fs/cgroup/memory cgroup cgroup rw,nosuid,nodev,noexec,rela
| | |-/sys/fs/cgroup/devices cgroup cgroup rw,nosuid,nodev,noexec,rela
| | |-/sys/fs/cgroup/freezer cgroup cgroup rw,nosuid,nodev,noexec,rela
| | |-/sys/fs/cgroup/net_cls cgroup cgroup rw,nosuid,nodev,noexec,rela
| | |-/sys/fs/cgroup/blkio cgroup cgroup rw,nosuid,nodev,noexec,rela
| | `-/sys/fs/cgroup/perf_event cgroup cgroup rw,nosuid,nodev,noexec,rela
| |-/sys/kernel/debug debugfs debugfs rw,relatime
| `-/sys/kernel/config configfs configfs rw,relatime
_[output truncated]_
By default, **findmnt** lists file systems in a tree-like format. To display the information as an ordinary list, add the `-l` command line option:
**findmnt** `-l`
For instance:
~]$ **findmnt -l**
TARGET SOURCE FSTYPE OPTIONS
/proc proc proc rw,nosuid,nodev,noexec,relatime
/sys sysfs sysfs rw,nosuid,nodev,noexec,relatime,s
/dev devtmpfs devtmpfs rw,nosuid,seclabel,size=370080k,n
/dev/pts devpts devpts rw,nosuid,noexec,relatime,seclabe
/dev/shm tmpfs tmpfs rw,nosuid,nodev,seclabel
/run tmpfs tmpfs rw,nosuid,nodev,seclabel,mode=755
/ /dev/mapper/vg_fedora-lv_root
ext4 rw,relatime,seclabel,data=ordered
/sys/kernel/security securityfs security rw,nosuid,nodev,noexec,relatime
/sys/fs/selinux selinuxfs selinuxf rw,relatime
/sys/fs/cgroup tmpfs tmpfs rw,nosuid,nodev,noexec,seclabel,m
/sys/fs/cgroup/systemd cgroup cgroup rw,nosuid,nodev,noexec,relatime,r
_[output truncated]_
You can also choose to list only file systems of a particular type. To do so, add the `-t` command line option followed by a file system type:
**findmnt** `-t` _`type`_
For example, to all list `ext4` file systems, type:
~]$ **findmnt -t ext4**
TARGET SOURCE FSTYPE OPTIONS
/ /dev/mapper/vg_fedora-lv_root ext4 rw,relatime,seclabel,data=ordered
/boot /dev/vda1 ext4 rw,relatime,seclabel,data=ordered
For a complete list of available command line options, refer to the **findmnt**(8) manual page.
### 16\.4.5. Using the df Command {#s2-sysinfo-filesystems-df}
The **df** command allows you to display a detailed report on the system's disk space usage. To do so, type the following at a shell prompt:
**df**
For each listed file system, the **df** command displays its name (`Filesystem`), size (`1K-blocks` or `Size`), how much space is used (`Used`), how much space is still available (`Available`), the percentage of space usage (`Use%`), and where is the file system mounted (`Mounted on`). For example:
~]$ **df**
Filesystem 1K-blocks Used Available Use% Mounted on
rootfs 18877356 4605476 14082844 25% /
devtmpfs 370080 0 370080 0% /dev
tmpfs 380976 256 380720 1% /dev/shm
tmpfs 380976 3048 377928 1% /run
/dev/mapper/vg_fedora-lv_root 18877356 4605476 14082844 25% /
tmpfs 380976 0 380976 0% /sys/fs/cgroup
tmpfs 380976 0 380976 0% /media
/dev/vda1 508745 85018 398127 18% /boot
By default, the **df** command shows the partition size in 1 kilobyte blocks and the amount of used and available disk space in kilobytes. To view the information in megabytes and gigabytes, supply the `-h` command line option, which causes **df** to display the values in a human-readable format:
**df** `-h`
For instance:
~]$ **df -h**
Filesystem Size Used Avail Use% Mounted on
rootfs 19G 4.4G 14G 25% /
devtmpfs 362M 0 362M 0% /dev
tmpfs 373M 256K 372M 1% /dev/shm
tmpfs 373M 3.0M 370M 1% /run
/dev/mapper/vg_fedora-lv_root 19G 4.4G 14G 25% /
tmpfs 373M 0 373M 0% /sys/fs/cgroup
tmpfs 373M 0 373M 0% /media
/dev/vda1 497M 84M 389M 18% /boot
Note that the `/dev/shm` entry represents the system's virtual memory file system, `/sys/fs/cgroup` is a cgroup file system, and `/run` contains information about the running system.
For a complete list of available command line options, refer to the **df**(1) manual page.
### 16\.4.6. Using the du Command {#s2-sysinfo-filesystems-du}
The **du** command allows you to displays the amount of space that is being used by files in a directory. To display the disk usage for each of the subdirectories in the current working directory, run the command with no additional command line options:
**du**
For example:
~]$ **du**
8 ./.gconf/apps/gnome-terminal/profiles/Default
12 ./.gconf/apps/gnome-terminal/profiles
16 ./.gconf/apps/gnome-terminal
_[output truncated]_
460 ./.gimp-2.6
68828 .
By default, the **du** command displays the disk usage in kilobytes. To view the information in megabytes and gigabytes, supply the `-h` command line option, which causes the utility to display the values in a human-readable format:
**du** `-h`
For instance:
~]$ **du -h**
8.0K ./.gconf/apps/gnome-terminal/profiles/Default
12K ./.gconf/apps/gnome-terminal/profiles
16K ./.gconf/apps/gnome-terminal
_[output truncated]_
460K ./.gimp-2.6
68M .
At the end of the list, the **du** command always shows the grand total for the current directory. To display only this information, supply the `-s` command line option:
**du** `-sh`
For example:
~]$ **du -sh**
68M .
For a complete list of available command line options, refer to the **du**(1) manual page.
### 16\.4.7. Using the System Monitor Tool {#s2-sysinfo-filesystems-system_monitor}
The File Systems tab of the System Monitor tool allows you to view file systems and disk space usage in the graphical user interface.
To start the System Monitor tool, either select Applications → System Tools → System Monitor from the Activities menu, or type **gnome-system-monitor** at a shell prompt. Then click the File Systems tab to view a list of file systems.
Figure 16.4. System Monitor — File Systems
![System Monitor — File Systems][67]
[[D](ld-idm60837040.html)]
For each listed file system, the System Monitor tool displays the source device (Device), target mount point (Directory), and file system type (Type), as well as its size (Total) and how much space is free (Free), available (Available), and used (Used).
## 16\.5. Viewing Hardware Information {#s1-sysinfo-hardware}
### 16\.5.1. Using the lspci Command {#s2-sysinfo-hardware-lspci}
The **lspci** command lists all PCI devices that are present in the system:
**lspci**
For example:
~]$ **lspci**
00:00.0 Host bridge: Intel Corporation 82X38/X48 Express DRAM Controller
00:01.0 PCI bridge: Intel Corporation 82X38/X48 Express Host-Primary PCI Express Bridge
00:1a.0 USB Controller: Intel Corporation 82801I (ICH9 Family) USB UHCI Controller #4 (rev 02)
00:1a.1 USB Controller: Intel Corporation 82801I (ICH9 Family) USB UHCI Controller #5 (rev 02)
00:1a.2 USB Controller: Intel Corporation 82801I (ICH9 Family) USB UHCI Controller #6 (rev 02)
_[output truncated]_
You can also use the `-v` command line option to display more verbose output, or `-vv` for very verbose output:
**lspci** `-v`|`-vv`
For instance, to determine the manufacturer, model, and memory size of a system's video card, type:
~]$ **lspci -v**
_[output truncated]_
01:00.0 VGA compatible controller: nVidia Corporation G84 [Quadro FX 370] (rev a1) (prog-if 00 [VGA controller])
Subsystem: nVidia Corporation Device 0491
Physical Slot: 2
Flags: bus master, fast devsel, latency 0, IRQ 16
Memory at f2000000 (32-bit, non-prefetchable) [size=16M]
Memory at e0000000 (64-bit, prefetchable) [size=256M]
Memory at f0000000 (64-bit, non-prefetchable) [size=32M]
I/O ports at 1100 [size=128]
Expansion ROM at <unassigned> [disabled]
Capabilities: <access denied>
Kernel driver in use: nouveau
Kernel modules: nouveau, nvidiafb
_[output truncated]_
For a complete list of available command line options, refer to the **lspci**(8) manual page.
### 16\.5.2. Using the lsusb Command {#s2-sysinfo-hardware-lsusb}
The **lsusb** command allows you to display information about USB buses and devices that are attached to them. To list all USB devices that are in the system, type the following at a shell prompt:
**lsusb**
This displays a simple list of devices, for example:
~]$ **lsusb**
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
_[output truncated]_
Bus 001 Device 002: ID 0bda:0151 Realtek Semiconductor Corp. Mass Storage Device (Multicard Reader)
Bus 008 Device 002: ID 03f0:2c24 Hewlett-Packard Logitech M-UAL-96 Mouse
Bus 008 Device 003: ID 04b3:3025 IBM Corp.
You can also use the `-v` command line option to display more verbose output:
**lsusb** `-v`
For instance:
~]$ **lsusb -v**
_[output truncated]_
Bus 008 Device 002: ID 03f0:2c24 Hewlett-Packard Logitech M-UAL-96 Mouse
Device Descriptor:
bLength 18
bDescriptorType 1
bcdUSB 2.00
bDeviceClass 0 (Defined at Interface level)
bDeviceSubClass 0
bDeviceProtocol 0
bMaxPacketSize0 8
idVendor 0x03f0 Hewlett-Packard
idProduct 0x2c24 Logitech M-UAL-96 Mouse
bcdDevice 31.00
iManufacturer 1
iProduct 2
iSerial 0
bNumConfigurations 1
Configuration Descriptor:
bLength 9
bDescriptorType 2
_[output truncated]_
For a complete list of available command line options, refer to the **lsusb**(8) manual page.
### 16\.5.3. Using the lspcmcia Command {#s2-sysinfo-hardware-lspcmcia}
The **lspcmcia** command allows you to list all PCMCIA devices that are present in the system. To do so, type the following at a shell prompt:
**lspcmcia**
For example:
~]$ **lspcmcia**
Socket 0 Bridge: [yenta_cardbus] (bus ID: 0000:15:00.0)
You can also use the `-v` command line option to display more verbose information, or `-vv` to increase the verbosity level even further:
**lspcmcia** `-v`|`-vv`
For instance:
~]$ **lspcmcia -v**
Socket 0 Bridge: [yenta_cardbus] (bus ID: 0000:15:00.0)
Configuration: state: on ready: unknown
For a complete list of available command line options, refer to the **pccardctl**(8) manual page.
### 16\.5.4. Using the lscpu Command {#s2-sysinfo-hardware-lscpu}
The **lscpu** command allows you to list information about CPUs that are present in the system, including the number of CPUs, their architecture, vendor, family, model, CPU caches, etc. To do so, type the following at a shell prompt:
**lscpu**
For example:
~]$ **lscpu**
Architecture: x86_64
CPU op-mode(s): 32-bit, 64-bit
Byte Order: Little Endian
CPU(s): 4
On-line CPU(s) list: 0-3
Thread(s) per core: 1
Core(s) per socket: 4
Socket(s): 1
NUMA node(s): 1
Vendor ID: GenuineIntel
CPU family: 6
Model: 23
Stepping: 7
CPU MHz: 1998.000
BogoMIPS: 4999.98
Virtualization: VT-x
L1d cache: 32K
L1i cache: 32K
L2 cache: 3072K
NUMA node0 CPU(s): 0-3
For a complete list of available command line options, refer to the **lscpu**(1) manual page.
## 16\.6. Monitoring Performance with Net-SNMP {#sect-System_Monitoring_Tools-Net-SNMP}
Fedora 20 includes the Net-SNMP software suite, which includes a flexible and extensible _Simple Network Management Protocol_ (SNMP) agent. This agent and its associated utilities can be used to provide performance data from a large number of systems to a variety of tools which support polling over the SNMP protocol.
This section provides information on configuring the Net-SNMP agent to securely provide performance data over the network, retrieving the data using the SNMP protocol, and extending the SNMP agent to provide custom performance metrics.
### 16\.6.1. Installing Net-SNMP {#sect-System_Monitoring_Tools-Net-SNMP-Installing}
The Net-SNMP software suite is available as a set of RPM packages in the Fedora software distribution. [Table 16.2, “Available Net-SNMP packages”](#tabl-System_Monitoring_Tools-Net-SNMP-Packages "Table 16.2. Available Net-SNMP packages") summarizes each of the packages and their contents.
Table 16.2. Available Net-SNMP packages
|Package|Provides|
|-|
|net-snmp|The SNMP Agent Daemon and documentation. This package is required for exporting performance data.|
|net-snmp-libs|The `netsnmp` library and the bundled management information bases (MIBs). This package is required for exporting performance data.|
|net-snmp-utils|SNMP clients such as **snmpget** and **snmpwalk**. This package is required in order to query a system's performance data over SNMP.|
|net-snmp-perl|The **mib2c** utility and the `NetSNMP` Perl module.|
|net-snmp-python|An SNMP client library for Python.|
To install any of these packages, use the **yum** command in the following form:
**yum** `install` _`package`_…
For example, to install the SNMP Agent Daemon and SNMP clients used in the rest of this section, type the following at a shell prompt:
~]# **yum install net-snmp net-snmp-libs net-snmp-utils**
Note that you must have superuser privileges (that is, you must be logged in as `root`) to run this command. For more information on how to install new packages in Fedora, refer to [Section 5.2.4, “Installing Packages”](#sec-Installing "5.2.4. Installing Packages").
### 16\.6.2. Running the Net-SNMP Daemon {#sect-System_Monitoring_Tools-Net-SNMP-Running}
The net-snmp package contains `snmpd`, the SNMP Agent Daemon. This section provides information on how to start, stop, and restart the `snmpd` service, and shows how to enable or disable it in the `multi-user` target unit. For more information on the concept of target units and how to manage system services in Fedora in general, refer to [Chapter 6, _Services and Daemons_](#ch-Services_and_Daemons "Chapter 6. Services and Daemons").
#### 16\.6.2.1. Starting the Service {#sect-System_Monitoring_Tools-Net-SNMP-Running-Starting}
To run the `snmpd` service in the current session, type the following at a shell prompt as `root`:
**systemctl** `start` `snmpd.service`
To configure the service to be automatically started at boot time, use the following command:
**systemctl** `enable` `snmpd.service`
This will enable the service in the `multi-user` target unit.
#### 16\.6.2.2. Stopping the Service {#sect-System_Monitoring_Tools-Net-SNMP-Running-Stopping}
To stop the running `snmpd` service, type the following at a shell prompt as `root`:
**systemctl** `stop` `snmpd.service`
To disable starting the service at boot time, use the following command:
**systemctl** `disable` `snmpd.service`
This will disable the service in the `multi-user` target unit.
#### 16\.6.2.3. Restarting the Service {#sect-System_Monitoring_Tools-Net-SNMP-Running-Restarting}
To restart the running `snmpd` service, type the following at a shell prompt:
**systemctl** `restart` `snmpd.service`
This will stop the service and start it again in quick succession. To only reload the configuration without stopping the service, run the following command instead:
**systemctl** `reload` `snmpd.service`
This will cause the running `snmpd` service to reload the configuration.
### 16\.6.3. Configuring Net-SNMP {#sect-System_Monitoring_Tools-Net-SNMP-Configuring}
To change the Net-SNMP Agent Daemon configuration, edit the `/etc/snmp/snmpd.conf` configuration file. The default `snmpd.conf` file shipped with Fedora 20 is heavily commented and serves as a good starting point for agent configuration.
This section focuses on two common tasks: setting system information and configuring authentication. For more information about available configuration directives, refer to the **snmpd.conf**(5) manual page. Additionally, there is a utility in the net-snmp package named **snmpconf** which can be used to interactively generate a valid agent configuration.
Note that the net-snmp-utils package must be installed in order to use the **snmpwalk** utility described in this section.
### Applying the changes
For any changes to the configuration file to take effect, force the `snmpd` service to re-read the configuration by running the following command as `root`:
**systemctl** `reload` `snmpd.service`
#### 16\.6.3.1. Setting System Information {#sect-System_Monitoring_Tools-Net-SNMP-Configuring-System_Information}
Net-SNMP provides some rudimentary system information via the `system` tree. For example, the following **snmpwalk** command shows the `system` tree with a default agent configuration.
~]# **snmpwalk -v2c -c public localhost system**
SNMPv2-MIB::sysDescr.0 = STRING: Linux localhost.localdomain 2.6.32-122.el6.x86_64 #1 SMP Wed Mar 9 23:54:34 EST 2011 x86_64
SNMPv2-MIB::sysObjectID.0 = OID: NET-SNMP-MIB::netSnmpAgentOIDs.10
DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (99554) 0:16:35.54
SNMPv2-MIB::sysContact.0 = STRING: Root <root@localhost> (configure /etc/snmp/snmp.local.conf)
SNMPv2-MIB::sysName.0 = STRING: localhost.localdomain
SNMPv2-MIB::sysLocation.0 = STRING: Unknown (edit /etc/snmp/snmpd.conf)
By default, the `sysName` object is set to the hostname. The `sysLocation` and `sysContact` objects can be configured in the `/etc/snmp/snmpd.conf` file by changing the value of the `syslocation` and `syscontact` directives, for example:
syslocation Datacenter, Row 3, Rack 2
syscontact UNIX Admin <admin@example.com>
After making changes to the configuration file, reload the configuration and test it by running the **snmpwalk** command again:
~]# **systemct reload snmpd.service**
~]# **snmpwalk -v2c -c public localhost system**
SNMPv2-MIB::sysDescr.0 = STRING: Linux localhost.localdomain 2.6.32-122.el6.x86_64 #1 SMP Wed Mar 9 23:54:34 EST 2011 x86_64
SNMPv2-MIB::sysObjectID.0 = OID: NET-SNMP-MIB::netSnmpAgentOIDs.10
DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (158357) 0:26:23.57
SNMPv2-MIB::sysContact.0 = STRING: UNIX Admin <admin@example.com>
SNMPv2-MIB::sysName.0 = STRING: localhost.localdomain
SNMPv2-MIB::sysLocation.0 = STRING: Datacenter, Row 3, Rack 2
#### 16\.6.3.2. Configuring Authentication {#sect-System_Monitoring_Tools-Net-SNMP-Configuring-Authentication}
The Net-SNMP Agent Daemon supports all three versions of the SNMP protocol. The first two versions (1 and 2c) provide for simple authentication using a _community string_. This string is a shared secret between the agent and any client utilities. The string is passed in clear text over the network however and is not considered secure. Version 3 of the SNMP protocol supports user authentication and message encryption using a variety of protocols. The Net-SNMP agent also supports tunneling over SSH, TLS authentication with X.509 certificates, and Kerberos authentication.
##### Configuring SNMP Version 2c Community {#brid-System_Monitoring_Tools-Net-SNMP-Configuring_Authentication-2c_community}
To configure an **SNMP version 2c community**, use either the `rocommunity` or `rwcommunity` directive in the `/etc/snmp/snmpd.conf` configuration file. The format of the directives is the following:
_`directive`_ _`community`_ [_`source`_ [_`OID`_]]
… where _`community`_ is the community string to use, _`source`_ is an IP address or subnet, and _`OID`_ is the SNMP tree to provide access to. For example, the following directive provides read-only access to the `system` tree to a client using the community string “redhat” on the local machine:
rocommunity redhat 127.0.0.1 .1.3.6.1.2.1.1
To test the configuration, use the **snmpwalk** command with the `-v` and `-c` options.
~]# **snmpwalk -v2c -c redhat localhost system**
SNMPv2-MIB::sysDescr.0 = STRING: Linux localhost.localdomain 2.6.32-122.el6.x86_64 #1 SMP Wed Mar 9 23:54:34 EST 2011 x86_64
SNMPv2-MIB::sysObjectID.0 = OID: NET-SNMP-MIB::netSnmpAgentOIDs.10
DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (158357) 0:26:23.57
SNMPv2-MIB::sysContact.0 = STRING: UNIX Admin <admin@example.com>
SNMPv2-MIB::sysName.0 = STRING: localhost.localdomain
SNMPv2-MIB::sysLocation.0 = STRING: Datacenter, Row 3, Rack 2
##### Configuring SNMP Version 3 User {#brid-System_Monitoring_Tools-Net-SNMP-Configuring_Authentication-3_user}
To configure an **SNMP version 3 user**, use the **net-snmp-create-v3-user** command. This command adds entries to the `/var/lib/net-snmp/snmpd.conf` and `/etc/snmp/snmpd.conf` files which create the user and grant access to the user. Note that the **net-snmp-create-v3-user** command may only be run when the agent is not running. The following example creates the “sysadmin” user with the password “redhatsnmp”:
~]# **systemctl stop snmpd.service**
~]# **net-snmp-create-v3-user**
Enter a SNMPv3 user name to create:
admin
Enter authentication pass-phrase:
redhatsnmp
Enter encryption pass-phrase:
[press return to reuse the authentication pass-phrase]
adding the following line to /var/lib/net-snmp/snmpd.conf:
createUser admin MD5 "redhatsnmp" DES
adding the following line to /etc/snmp/snmpd.conf:
rwuser admin
~]# **systemctl start snmpd.service**
The `rwuser` directive (or `rouser` when the `-ro` command line option is supplied) that **net-snmp-create-v3-user** adds to `/etc/snmp/snmpd.conf` has a similar format to the `rwcommunity` and `rocommunity` directives:
_`directive`_ _`user`_ [`noauth`|`auth`|`priv`] [_`OID`_]
… where _`user`_ is a username and _`OID`_ is the SNMP tree to provide access to. By default, the Net-SNMP Agent Daemon allows only authenticated requests (the `auth` option). The `noauth` option allows you to permit unauthenticated requests, and the `priv` option enforces the use of encryption. The `authpriv` option specifies that requests must be authenticated and replies should be encrypted.
For example, the following line grants the user “admin” read-write access to the entire tree:
rwuser admin authpriv .1
To test the configuration, create a `.snmp` directory in your user's home directory and a configuration file named `snmp.conf` in that directory (`~/.snmp/snmp.conf`) with the following lines:
defVersion 3
defSecurityLevel authPriv
defSecurityName admin
defPassphrase redhatsnmp
The **snmpwalk** command will now use these authentication settings when querying the agent:
~]$ **snmpwalk -v3 localhost system**
SNMPv2-MIB::sysDescr.0 = STRING: Linux localhost.localdomain 2.6.32-122.el6.x86_64 #1 SMP Wed Mar 9 23:54:34 EST 2011 x86_64
_[output truncated]_
### 16\.6.4. Retrieving Performance Data over SNMP {#sect-System_Monitoring_Tools-Net-SNMP-Retrieving}
The Net-SNMP Agent in Fedora provides a wide variety of performance information over the SNMP protocol. In addition, the agent can be queried for a listing of the installed RPM packages on the system, a listing of currently running processes on the system, or the network configuration of the system.
This section provides an overview of OIDs related to performance tuning available over SNMP. It assumes that the net-snmp-utils package is installed and that the user is granted access to the SNMP tree as described in [Section 16.6.3.2, “Configuring Authentication”](#sect-System_Monitoring_Tools-Net-SNMP-Configuring-Authentication "16.6.3.2. Configuring Authentication").
#### 16\.6.4.1. Hardware Configuration {#sect-System_Monitoring_Tools-Net-SNMP-Retrieving-Hardware}
The `Host Resources MIB` included with Net-SNMP presents information about the current hardware and software configuration of a host to a client utility. [Table 16.3, “Available OIDs”](#tabl-System_Monitoring_Tools-Net-SNMP-OIDs "Table 16.3. Available OIDs") summarizes the different OIDs available under that MIB.
Table 16.3. Available OIDs
|OID|Description|
|-|
|`HOST-RESOURCES-MIB::hrSystem`|Contains general system information such as uptime, number of users, and number of running processes.|
|`HOST-RESOURCES-MIB::hrStorage`|Contains data on memory and file system usage.|
|`HOST-RESOURCES-MIB::hrDevices`|Contains a listing of all processors, network devices, and file systems.|
|`HOST-RESOURCES-MIB::hrSWRun`|Contains a listing of all running processes.|
|`HOST-RESOURCES-MIB::hrSWRunPerf`|Contains memory and CPU statistics on the process table from HOST-RESOURCES-MIB::hrSWRun.|
|`HOST-RESOURCES-MIB::hrSWInstalled`|Contains a listing of the RPM database.|
There are also a number of SNMP tables available in the Host Resources MIB which can be used to retrieve a summary of the available information. The following example displays `HOST-RESOURCES-MIB::hrFSTable`:
~]$ **snmptable -Cb localhost HOST-RESOURCES-MIB::hrFSTable**
SNMP table: HOST-RESOURCES-MIB::hrFSTable
Index MountPoint RemoteMountPoint Type
Access Bootable StorageIndex LastFullBackupDate LastPartialBackupDate
1 "/" "" HOST-RESOURCES-TYPES::hrFSLinuxExt2
readWrite true 31 0-1-1,0:0:0.0 0-1-1,0:0:0.0
5 "/dev/shm" "" HOST-RESOURCES-TYPES::hrFSOther
readWrite false 35 0-1-1,0:0:0.0 0-1-1,0:0:0.0
6 "/boot" "" HOST-RESOURCES-TYPES::hrFSLinuxExt2
readWrite false 36 0-1-1,0:0:0.0 0-1-1,0:0:0.0
For more information about `HOST-RESOURCES-MIB`, see the `/usr/share/snmp/mibs/HOST-RESOURCES-MIB.txt` file.
#### 16\.6.4.2. CPU and Memory Information {#sect-System_Monitoring_Tools-Net-SNMP-Retrieving-CPU}
Most system performance data is available in the `UCD SNMP MIB`. The `systemStats` OID provides a number of counters around processor usage:
~]$ **snmpwalk localhost UCD-SNMP-MIB::systemStats**
UCD-SNMP-MIB::ssIndex.0 = INTEGER: 1
UCD-SNMP-MIB::ssErrorName.0 = STRING: systemStats
UCD-SNMP-MIB::ssSwapIn.0 = INTEGER: 0 kB
UCD-SNMP-MIB::ssSwapOut.0 = INTEGER: 0 kB
UCD-SNMP-MIB::ssIOSent.0 = INTEGER: 0 blocks/s
UCD-SNMP-MIB::ssIOReceive.0 = INTEGER: 0 blocks/s
UCD-SNMP-MIB::ssSysInterrupts.0 = INTEGER: 29 interrupts/s
UCD-SNMP-MIB::ssSysContext.0 = INTEGER: 18 switches/s
UCD-SNMP-MIB::ssCpuUser.0 = INTEGER: 0
UCD-SNMP-MIB::ssCpuSystem.0 = INTEGER: 0
UCD-SNMP-MIB::ssCpuIdle.0 = INTEGER: 99
UCD-SNMP-MIB::ssCpuRawUser.0 = Counter32: 2278
UCD-SNMP-MIB::ssCpuRawNice.0 = Counter32: 1395
UCD-SNMP-MIB::ssCpuRawSystem.0 = Counter32: 6826
UCD-SNMP-MIB::ssCpuRawIdle.0 = Counter32: 3383736
UCD-SNMP-MIB::ssCpuRawWait.0 = Counter32: 7629
UCD-SNMP-MIB::ssCpuRawKernel.0 = Counter32: 0
UCD-SNMP-MIB::ssCpuRawInterrupt.0 = Counter32: 434
UCD-SNMP-MIB::ssIORawSent.0 = Counter32: 266770
UCD-SNMP-MIB::ssIORawReceived.0 = Counter32: 427302
UCD-SNMP-MIB::ssRawInterrupts.0 = Counter32: 743442
UCD-SNMP-MIB::ssRawContexts.0 = Counter32: 718557
UCD-SNMP-MIB::ssCpuRawSoftIRQ.0 = Counter32: 128
UCD-SNMP-MIB::ssRawSwapIn.0 = Counter32: 0
UCD-SNMP-MIB::ssRawSwapOut.0 = Counter32: 0
In particular, the `ssCpuRawUser`, `ssCpuRawSystem`, `ssCpuRawWait`, and `ssCpuRawIdle` OIDs provide counters which are helpful when determining whether a system is spending most of its processor time in kernel space, user space, or I/O. `ssRawSwapIn` and `ssRawSwapOut` can be helpful when determining whether a system is suffering from memory exhaustion.
More memory information is available under the `UCD-SNMP-MIB::memory` OID, which provides similar data to the **free** command:
~]$ **snmpwalk localhost UCD-SNMP-MIB::memory**
UCD-SNMP-MIB::memIndex.0 = INTEGER: 0
UCD-SNMP-MIB::memErrorName.0 = STRING: swap
UCD-SNMP-MIB::memTotalSwap.0 = INTEGER: 1023992 kB
UCD-SNMP-MIB::memAvailSwap.0 = INTEGER: 1023992 kB
UCD-SNMP-MIB::memTotalReal.0 = INTEGER: 1021588 kB
UCD-SNMP-MIB::memAvailReal.0 = INTEGER: 634260 kB
UCD-SNMP-MIB::memTotalFree.0 = INTEGER: 1658252 kB
UCD-SNMP-MIB::memMinimumSwap.0 = INTEGER: 16000 kB
UCD-SNMP-MIB::memBuffer.0 = INTEGER: 30760 kB
UCD-SNMP-MIB::memCached.0 = INTEGER: 216200 kB
UCD-SNMP-MIB::memSwapError.0 = INTEGER: noError(0)
UCD-SNMP-MIB::memSwapErrorMsg.0 = STRING:
Load averages are also available in the `UCD SNMP MIB`. The SNMP table `UCD-SNMP-MIB::laTable` has a listing of the 1, 5, and 15 minute load averages:
~]$ **snmptable localhost UCD-SNMP-MIB::laTable**
SNMP table: UCD-SNMP-MIB::laTable
laIndex laNames laLoad laConfig laLoadInt laLoadFloat laErrorFlag laErrMessage
1 Load-1 0.00 12.00 0 0.000000 noError
2 Load-5 0.00 12.00 0 0.000000 noError
3 Load-15 0.00 12.00 0 0.000000 noError
#### 16\.6.4.3. File System and Disk Information {#sect-System_Monitoring_Tools-Net-SNMP-Retrieving-File_System}
The `Host Resources MIB` provides information on file system size and usage. Each file system (and also each memory pool) has an entry in the `HOST-RESOURCES-MIB::hrStorageTable` table:
~]$ **snmptable -Cb localhost HOST-RESOURCES-MIB::hrStorageTable**
SNMP table: HOST-RESOURCES-MIB::hrStorageTable
Index Type Descr
AllocationUnits Size Used AllocationFailures
1 HOST-RESOURCES-TYPES::hrStorageRam Physical memory
1024 Bytes 1021588 388064 ?
3 HOST-RESOURCES-TYPES::hrStorageVirtualMemory Virtual memory
1024 Bytes 2045580 388064 ?
6 HOST-RESOURCES-TYPES::hrStorageOther Memory buffers
1024 Bytes 1021588 31048 ?
7 HOST-RESOURCES-TYPES::hrStorageOther Cached memory
1024 Bytes 216604 216604 ?
10 HOST-RESOURCES-TYPES::hrStorageVirtualMemory Swap space
1024 Bytes 1023992 0 ?
31 HOST-RESOURCES-TYPES::hrStorageFixedDisk /
4096 Bytes 2277614 250391 ?
35 HOST-RESOURCES-TYPES::hrStorageFixedDisk /dev/shm
4096 Bytes 127698 0 ?
36 HOST-RESOURCES-TYPES::hrStorageFixedDisk /boot
1024 Bytes 198337 26694 ?
The OIDs under `HOST-RESOURCES-MIB::hrStorageSize` and `HOST-RESOURCES-MIB::hrStorageUsed` can be used to calculate the remaining capacity of each mounted file system.
I/O data is available both in `UCD-SNMP-MIB::systemStats` (`ssIORawSent.0` and `ssIORawRecieved.0`) and in `UCD-DISKIO-MIB::diskIOTable`. The latter provides much more granular data. Under this table are OIDs for `diskIONReadX` and `diskIONWrittenX`, which provide counters for the number of bytes read from and written to the block device in question since the system boot:
~]$ **snmptable -Cb localhost UCD-DISKIO-MIB::diskIOTable**
SNMP table: UCD-DISKIO-MIB::diskIOTable
Index Device NRead NWritten Reads Writes LA1 LA5 LA15 NReadX NWrittenX
...
25 sda 216886272 139109376 16409 4894 ? ? ? 216886272 139109376
26 sda1 2455552 5120 613 2 ? ? ? 2455552 5120
27 sda2 1486848 0 332 0 ? ? ? 1486848 0
28 sda3 212321280 139104256 15312 4871 ? ? ? 212321280 139104256
#### 16\.6.4.4. Network Information {#sect-System_Monitoring_Tools-Net-SNMP-Retrieving-Network}
Information on network devices is provided by the Interfaces MIB. `IF-MIB::ifTable` provides an SNMP table with an entry for each interface on the system, the configuration of the interface, and various packet counters for the interface. The following example shows the first few columns of `ifTable` on a system with two physical network interfaces:
~]$ **snmptable -Cb localhost IF-MIB::ifTable**
SNMP table: IF-MIB::ifTable
Index Descr Type Mtu Speed PhysAddress AdminStatus
1 lo softwareLoopback 16436 10000000 up
2 eth0 ethernetCsmacd 1500 0 52:54:0:c7:69:58 up
3 eth1 ethernetCsmacd 1500 0 52:54:0:a7:a3:24 down
Network traffic is available under the OIDs `IF-MIB::ifOutOctets` and `IF-MIB::ifInOctets`. The following SNMP queries will retrieve network traffic for each of the interfaces on this system:
~]$ **snmpwalk localhost IF-MIB::ifDescr**
IF-MIB::ifDescr.1 = STRING: lo
IF-MIB::ifDescr.2 = STRING: eth0
IF-MIB::ifDescr.3 = STRING: eth1
~]$ **snmpwalk localhost IF-MIB::ifOutOctets**
IF-MIB::ifOutOctets.1 = Counter32: 10060699
IF-MIB::ifOutOctets.2 = Counter32: 650
IF-MIB::ifOutOctets.3 = Counter32: 0
~]$ **snmpwalk localhost IF-MIB::ifInOctets**
IF-MIB::ifInOctets.1 = Counter32: 10060699
IF-MIB::ifInOctets.2 = Counter32: 78650
IF-MIB::ifInOctets.3 = Counter32: 0
### 16\.6.5. Extending Net-SNMP {#sect-System_Monitoring_Tools-Net-SNMP-Extending}
The Net-SNMP Agent can be extended to provide application metrics in addition to raw system metrics. This allows for capacity planning as well as performance issue troubleshooting. For example, it may be helpful to know that an email system had a 5-minute load average of 15 while being tested, but it is more helpful to know that the email system has a load average of 15 while processing 80,000 messages a second. When application metrics are available via the same interface as the system metrics, this also allows for the visualization of the impact of different load scenarios on system performance (for example, each additional 10,000 messages increases the load average linearly until 100,000).
A number of the applications that ship with Fedora extend the Net-SNMP Agent to provide application metrics over SNMP. There are several ways to extend the agent for custom applications as well. This section describes extending the agent with shell scripts and Perl plug-ins. It assumes that the net-snmp-utils and net-snmp-perl packages are installed, and that the user is granted access to the SNMP tree as described in [Section 16.6.3.2, “Configuring Authentication”](#sect-System_Monitoring_Tools-Net-SNMP-Configuring-Authentication "16.6.3.2. Configuring Authentication").
#### 16\.6.5.1. Extending Net-SNMP with Shell Scripts {#sect-System_Monitoring_Tools-Net-SNMP-Extending-Shell}
The Net-SNMP Agent provides an extension MIB (`NET-SNMP-EXTEND-MIB`) that can be used to query arbitrary shell scripts. To specify the shell script to run, use the `extend` directive in the `/etc/snmp/snmpd.conf` file. Once defined, the Agent will provide the exit code and any output of the command over SNMP. The example below demonstrates this mechanism with a script which determines the number of `httpd` processes in the process table.
### Using the proc directive
The Net-SNMP Agent also provides a built-in mechanism for checking the process table via the `proc` directive. See the **snmpd.conf**(5) manual page for more information.
The exit code of the following shell script is the number of **httpd** processes running on the system at a given point in time:
#!/bin/sh
NUMPIDS=`pgrep httpd | wc -l`
exit $NUMPIDS
To make this script available over SNMP, copy the script to a location on the system path, set the executable bit, and add an `extend` directive to the `/etc/snmp/snmpd.conf` file. The format of the `extend` directive is the following:
`extend` _`name`_ _`prog`_ _`args`_
… where _`name`_ is an identifying string for the extension, _`prog`_ is the program to run, and _`args`_ are the arguments to give the program. For instance, if the above shell script is copied to `/usr/local/bin/check_apache.sh`, the following directive will add the script to the SNMP tree:
extend httpd_pids /bin/sh /usr/local/bin/check_apache.sh
The script can then be queried at `NET-SNMP-EXTEND-MIB::nsExtendObjects`:
~]$ **snmpwalk localhost NET-SNMP-EXTEND-MIB::nsExtendObjects**
NET-SNMP-EXTEND-MIB::nsExtendNumEntries.0 = INTEGER: 1
NET-SNMP-EXTEND-MIB::nsExtendCommand."httpd_pids" = STRING: /bin/sh
NET-SNMP-EXTEND-MIB::nsExtendArgs."httpd_pids" = STRING: /usr/local/bin/check_apache.sh
NET-SNMP-EXTEND-MIB::nsExtendInput."httpd_pids" = STRING:
NET-SNMP-EXTEND-MIB::nsExtendCacheTime."httpd_pids" = INTEGER: 5
NET-SNMP-EXTEND-MIB::nsExtendExecType."httpd_pids" = INTEGER: exec(1)
NET-SNMP-EXTEND-MIB::nsExtendRunType."httpd_pids" = INTEGER: run-on-read(1)
NET-SNMP-EXTEND-MIB::nsExtendStorage."httpd_pids" = INTEGER: permanent(4)
NET-SNMP-EXTEND-MIB::nsExtendStatus."httpd_pids" = INTEGER: active(1)
NET-SNMP-EXTEND-MIB::nsExtendOutput1Line."httpd_pids" = STRING:
NET-SNMP-EXTEND-MIB::nsExtendOutputFull."httpd_pids" = STRING:
NET-SNMP-EXTEND-MIB::nsExtendOutNumLines."httpd_pids" = INTEGER: 1
NET-SNMP-EXTEND-MIB::nsExtendResult."httpd_pids" = INTEGER: 8
NET-SNMP-EXTEND-MIB::nsExtendOutLine."httpd_pids".1 = STRING:
Note that the exit code (“8” in this example) is provided as an INTEGER type and any output is provided as a STRING type. To expose multiple metrics as integers, supply different arguments to the script using the `extend` directive. For example, the following shell script can be used to determine the number of processes matching an arbitrary string, and will also output a text string giving the number of processes:
#!/bin/sh
PATTERN=$1
NUMPIDS=`pgrep $PATTERN | wc -l`
echo "There are $NUMPIDS $PATTERN processes."
exit $NUMPIDS
The following `/etc/snmp/snmpd.conf` directives will give both the number of `httpd` PIDs as well as the number of `snmpd` PIDs when the above script is copied to `/usr/local/bin/check_proc.sh`:
extend httpd_pids /bin/sh /usr/local/bin/check_proc.sh httpd
extend snmpd_pids /bin/sh /usr/local/bin/check_proc.sh snmpd
The following example shows the output of an **snmpwalk** of the `nsExtendObjects` OID:
~]$ **snmpwalk localhost NET-SNMP-EXTEND-MIB::nsExtendObjects**
NET-SNMP-EXTEND-MIB::nsExtendNumEntries.0 = INTEGER: 2
NET-SNMP-EXTEND-MIB::nsExtendCommand."httpd_pids" = STRING: /bin/sh
NET-SNMP-EXTEND-MIB::nsExtendCommand."snmpd_pids" = STRING: /bin/sh
NET-SNMP-EXTEND-MIB::nsExtendArgs."httpd_pids" = STRING: /usr/local/bin/check_proc.sh httpd
NET-SNMP-EXTEND-MIB::nsExtendArgs."snmpd_pids" = STRING: /usr/local/bin/check_proc.sh snmpd
NET-SNMP-EXTEND-MIB::nsExtendInput."httpd_pids" = STRING:
NET-SNMP-EXTEND-MIB::nsExtendInput."snmpd_pids" = STRING:
...
NET-SNMP-EXTEND-MIB::nsExtendResult."httpd_pids" = INTEGER: 8
NET-SNMP-EXTEND-MIB::nsExtendResult."snmpd_pids" = INTEGER: 1
NET-SNMP-EXTEND-MIB::nsExtendOutLine."httpd_pids".1 = STRING: There are 8 httpd processes.
NET-SNMP-EXTEND-MIB::nsExtendOutLine."snmpd_pids".1 = STRING: There are 1 snmpd processes.
### Integer exit codes are limited
Integer exit codes are limited to a range of 0–255. For values that are likely to exceed 256, either use the standard output of the script (which will be typed as a string) or a different method of extending the agent.
This last example shows a query for the free memory of the system and the number of `httpd` processes. This query could be used during a performance test to determine the impact of the number of processes on memory pressure:
~]$ **snmpget localhost \**
**'NET-SNMP-EXTEND-MIB::nsExtendResult."httpd_pids"' \**
**UCD-SNMP-MIB::memAvailReal.0**
NET-SNMP-EXTEND-MIB::nsExtendResult."httpd_pids" = INTEGER: 8
UCD-SNMP-MIB::memAvailReal.0 = INTEGER: 799664 kB
#### 16\.6.5.2. Extending Net-SNMP with Perl {#sect-System_Monitoring_Tools-Net-SNMP-Extending-Perl}
Executing shell scripts using the `extend` directive is a fairly limited method for exposing custom application metrics over SNMP. The Net-SNMP Agent also provides an embedded Perl interface for exposing custom objects. The net-snmp-perl package provides the `NetSNMP::agent` Perl module that is used to write embedded Perl plug-ins on Fedora.
The `NetSNMP::agent` Perl module provides an `agent` object which is used to handle requests for a part of the agent's OID tree. The `agent` object's constructor has options for running the agent as a sub-agent of `snmpd` or a standalone agent. No arguments are necessary to create an embedded agent:
use NetSNMP::agent (':all');
my $agent = new NetSNMP::agent();
The `agent` object has a `register` method which is used to register a callback function with a particular OID. The `register` function takes a name, OID, and pointer to the callback function. The following example will register a callback function named `hello_handler` with the SNMP Agent which will handle requests under the OID `.1.3.6.1.4.1.8072.9999.9999`:
$agent->register("hello_world", ".1.3.6.1.4.1.8072.9999.9999",
\&hello_handler);
### Obtaining a root OID
The OID `.1.3.6.1.4.1.8072.9999.9999` (`NET-SNMP-MIB::netSnmpPlaypen`) is typically used for demonstration purposes only. If your organization does not already have a root OID, you can obtain one by contacting your Name Registration Authority (ANSI in the United States).
The handler function will be called with four parameters, _`HANDLER`_, _`REGISTRATION_INFO`_, _`REQUEST_INFO`_, and _`REQUESTS`_. The _`REQUESTS`_ parameter contains a list of requests in the current call and should be iterated over and populated with data. The `request` objects in the list have get and set methods which allow for manipulating the OID and value of the request. For example, the following call will set the value of a request object to the string “hello world”:
$request->setValue(ASN_OCTET_STR, "hello world");
The handler function should respond to two types of SNMP requests: the GET request and the GETNEXT request. The type of request is determined by calling the `getMode` method on the `request_info` object passed as the third parameter to the handler function. If the request is a GET request, the caller will expect the handler to set the value of the `request` object, depending on the OID of the request. If the request is a GETNEXT request, the caller will also expect the handler to set the OID of the request to the next available OID in the tree. This is illustrated in the following code example:
my $request;
my $string_value = "hello world";
my $integer_value = "8675309";
for($request = $requests; $request; $request = $request->next()) {
my $oid = $request->getOID();
if ($request_info->getMode() == MODE_GET) {
if ($oid == new NetSNMP::OID(".1.3.6.1.4.1.8072.9999.9999.1.0")) {
$request->setValue(ASN_OCTET_STR, $string_value);
}
elsif ($oid == new NetSNMP::OID(".1.3.6.1.4.1.8072.9999.9999.1.1")) {
$request->setValue(ASN_INTEGER, $integer_value);
}
} elsif ($request_info->getMode() == MODE_GETNEXT) {
if ($oid == new NetSNMP::OID(".1.3.6.1.4.1.8072.9999.9999.1.0")) {
$request->setOID(".1.3.6.1.4.1.8072.9999.9999.1.1");
$request->setValue(ASN_INTEGER, $integer_value);
}
elsif ($oid < new NetSNMP::OID(".1.3.6.1.4.1.8072.9999.9999.1.0")) {
$request->setOID(".1.3.6.1.4.1.8072.9999.9999.1.0");
$request->setValue(ASN_OCTET_STR, $string_value);
}
}
}
When `getMode` returns `MODE_GET`, the handler analyzes the value of the `getOID` call on the `request` object. The value of the `request` is set to either `string_value` if the OID ends in “.1.0”, or set to `integer_value` if the OID ends in “.1.1”. If the `getMode` returns `MODE_GETNEXT`, the handler determines whether the OID of the request is “.1.0”, and then sets the OID and value for “.1.1”. If the request is higher on the tree than “.1.0”, the OID and value for “.1.0” is set. This in effect returns the “next” value in the tree so that a program like **snmpwalk** can traverse the tree without prior knowledge of the structure.
The type of the variable is set using constants from `NetSNMP::ASN`. See the **perldoc** for `NetSNMP::ASN` for a full list of available constants.
The entire code listing for this example Perl plug-in is as follows:
#!/usr/bin/perl
use NetSNMP::agent (':all');
use NetSNMP::ASN qw(ASN_OCTET_STR ASN_INTEGER);
sub hello_handler {
my ($handler, $registration_info, $request_info, $requests) = @_;
my $request;
my $string_value = "hello world";
my $integer_value = "8675309";
for($request = $requests; $request; $request = $request->next()) {
my $oid = $request->getOID();
if ($request_info->getMode() == MODE_GET) {
if ($oid == new NetSNMP::OID(".1.3.6.1.4.1.8072.9999.9999.1.0")) {
$request->setValue(ASN_OCTET_STR, $string_value);
}
elsif ($oid == new NetSNMP::OID(".1.3.6.1.4.1.8072.9999.9999.1.1")) {
$request->setValue(ASN_INTEGER, $integer_value);
}
} elsif ($request_info->getMode() == MODE_GETNEXT) {
if ($oid == new NetSNMP::OID(".1.3.6.1.4.1.8072.9999.9999.1.0")) {
$request->setOID(".1.3.6.1.4.1.8072.9999.9999.1.1");
$request->setValue(ASN_INTEGER, $integer_value);
}
elsif ($oid < new NetSNMP::OID(".1.3.6.1.4.1.8072.9999.9999.1.0")) {
$request->setOID(".1.3.6.1.4.1.8072.9999.9999.1.0");
$request->setValue(ASN_OCTET_STR, $string_value);
}
}
}
}
my $agent = new NetSNMP::agent();
$agent->register("hello_world", ".1.3.6.1.4.1.8072.9999.9999",
\&hello_handler);
To test the plug-in, copy the above program to `/usr/share/snmp/hello_world.pl` and add the following line to the `/etc/snmp/snmpd.conf` configuration file:
perl do "/usr/share/snmp/hello_world.pl"
The SNMP Agent Daemon will need to be restarted to load the new Perl plug-in. Once it has been restarted, an **snmpwalk** should return the new data:
~]$ **snmpwalk localhost NET-SNMP-MIB::netSnmpPlaypen**
NET-SNMP-MIB::netSnmpPlaypen.1.0 = STRING: "hello world"
NET-SNMP-MIB::netSnmpPlaypen.1.1 = INTEGER: 8675309
The **snmpget** should also be used to exercise the other mode of the handler:
~]$ **snmpget localhost \**
**NET-SNMP-MIB::netSnmpPlaypen.1.0 \**
**NET-SNMP-MIB::netSnmpPlaypen.1.1**
NET-SNMP-MIB::netSnmpPlaypen.1.0 = STRING: "hello world"
NET-SNMP-MIB::netSnmpPlaypen.1.1 = INTEGER: 8675309
## 16\.7. Additional Resources {#s1-sysinfo-additional-resources}
To learn more about gathering system information, refer to the following resources.
### 16\.7.1. Installed Documentation {#s2-sysinfo-installed-docs}
* **ps**(1) — The manual page for the **ps** command.
* **top**(1) — The manual page for the **top** command.
* **free**(1) — The manual page for the **free** command.
* **df**(1) — The manual page for the **df** command.
* **du**(1) — The manual page for the **du** command.
* **lspci**(8) — The manual page for the **lspci** command.
* **snmpd**(8) — The manual page for the `snmpd` service.
* **snmpd.conf**(5) — The manual page for the `/etc/snmp/snmpd.conf` file containing full documentation of available configuration directives.
## Chapter 17. Viewing and Managing Log Files {#ch-Viewing_and_Managing_Log_Files}
_Log files_ are files that contain messages about the system, including the kernel, services, and applications running on it. There are different log files for different information. For example, there is a default system log file, a log file just for security messages, and a log file for cron tasks.
Log files can be very useful when trying to troubleshoot a problem with the system such as trying to load a kernel driver or when looking for unauthorized login attempts to the system. This chapter discusses where to find log files, how to view log files, and what to look for in log files.
Some log files are controlled by a daemon called `rsyslogd`. A list of log files maintained by `rsyslogd` can be found in the `/etc/rsyslog.conf` configuration file.
rsyslog is an enhanced, multi-threaded syslog daemon which replaced the **sysklogd** daemon. rsyslog supports the same functionality as sysklogd and extends it with enhanced filtering, encryption protected relaying of messages, various configuration options, or support for transportation via the `TCP` or `UDP` protocols. Note that rsyslog is compatible with sysklogd.
## 17\.1. Configuring rsyslog {#s1-configuring-rsyslog}
The main configuration file for rsyslog is `/etc/rsyslog.conf`. It consists of _global directives_, _rules_ or comments (any empty lines or any text following a hash sign (`#`)). Both, global directives and rules are extensively described in the sections below.
### 17\.1.1. Global Directives {#s2-global-directives}
Global directives specify configuration options that apply to the `rsyslogd` daemon. They usually specify a value for a specific pre-defined variable that affects the behavior of the `rsyslogd` daemon or a rule that follows. All of the global directives must start with a dollar sign (`$`). Only one directive can be specified per line. The following is an example of a global directive that specifies the maximum size of the syslog message queue:
$MainMsgQueueSize 50000
The default size defined for this directive (`10,000` messages) can be overridden by specifying a different value (as shown in the example above).
You may define multiple directives in your `/etc/rsyslog.conf` configuration file. A directive affects the behavior of all configuration options until another occurrence of that same directive is detected.
A comprehensive list of all available configuration directives and their detailed description can be found in `/usr/share/doc/rsyslog/rsyslog_conf_global.html`.
### 17\.1.2. Modules {#s2-modules}
Due to its modular design, rsyslog offers a variety of _modules_ which provide dynamic functionality. Note that modules can be written by third parties. Most modules provide additional inputs (see _Input Modules_ below) or outputs (see _Output Modules_ below). Other modules provide special functionality specific to each module. The modules may provide additional configuration directives that become available after a module is loaded. To load a module, use the following syntax:
$ModLoad _``_
where `$ModLoad` is the global directive that loads the specified module and _``_ represents your desired module. For example, if you want to load the `Text File Input Module` (**imfile** — enables rsyslog to convert any standard text files into syslog messages), specify the following line in your `/etc/rsyslog.conf` configuration file:
$ModLoad imfile
rsyslog offers a number of modules which are split into these main categories:
* Input Modules — Input modules gather messages from various sources. The name of an input module always starts with the `im` prefix, such as **imfile**, **imrelp**, etc.
* Output Modules — Output modules provide a facility to store messages into various targets such as sending them across network, storing them in a database or encrypting them. The name of an output module always starts with the `om` prefix, such as **omsnmp**, **omrelp**, etc.
* Filter Modules — Filter modules provide the ability to filter messages according to specified rules. The name of a filter module always starts with the `fm` prefix.
* Parser Modules — Parser modules use the message parsers to parse message content of any received messages. The name of a parser module always starts with the `pm` prefix, such as **pmrfc5424**, **pmrfc3164**, etc.
* Message Modification Modules — Message modification modules change the content of a syslog message. The message modification modules only differ in their implementation from the output and filter modules but share the same interface.
* String Generator Modules — String generator modules generate strings based on the message content and strongly cooperate with the template feature provided by rsyslog. For more information on templates, refer to [Section 17.1.3.3, “Templates”](#s3-templates "17.1.3.3. Templates"). The name of a string generator module always starts with the `sm` prefix, such as **smfile**, **smtradfile**, etc.
* Library Modules — Library modules generally provide functionality for other loadable modules. These modules are loaded automatically by rsyslog when needed and cannot be configured by the user.
A comprehensive list of all available modules and their detailed description can be found at [http://www.rsyslog.com/doc/rsyslog\_conf\_modules.html](http://www.rsyslog.com/doc/rsyslog_conf_modules.html/)
### Make sure you use trustworthy modules only
Note that when rsyslog loads any modules, it provides them with access to some of its functions and data. This poses a possible security threat. To minimize security risks, use trustworthy modules only.
### 17\.1.3. Rules {#s2-rules}
A rule is specified by a _filter_ part, which selects a subset of syslog messages, and an _action_ part, which specifies what to do with the selected messages. To define a rule in your `/etc/rsyslog.conf` configuration file, define both, a filter and an action, on one line and separate them with one or more spaces or tabs. For more information on filters, refer to [Section 17.1.3.1, “Filter Conditions”](#s3-filter-conditions "17.1.3.1. Filter Conditions") and for information on actions, refer to [Section 17.1.3.2, “Actions”](#s3-actions "17.1.3.2. Actions").
#### 17\.1.3.1. Filter Conditions {#s3-filter-conditions}
rsyslog offers various ways how to filter syslog messages according to various properties. This sections sums up the most used filter conditions.
Facility/Priority-based filters
: The most used and well-known way to filter syslog messages is to use the facility/priority-based filters which filter syslog messages based on two conditions: _facility_ and _priority_. To create a selector, use the following syntax:
_``_._``_
where:
* _``_ specifies the subsystem that produces a specific syslog message. For example, the **mail** subsystem handles all mail related syslog messages. _``_ can be represented by one of these keywords: **auth**, **authpriv**, **cron**, **daemon**, **kern**, **lpr**, **mail**, **news**, **syslog**, **user**, **uucp**, and **local0** through **local7**.
* _``_ specifies a priority of a syslog message. _``_ can be represented by one of these keywords (listed in an ascending order): **debug**, **info**, **notice**, **warning**, **err**, **crit**, **alert**, and **emerg**.
By preceding any priority with an equal sign (`=`), you specify that only syslog messages with that priority will be selected. All other priorities will be ignored. Conversely, preceding a priority with an exclamation mark (`!`) selects all syslog messages but those with the defined priority. By not using either of these two extensions, you specify a selection of syslog messages with the defined or higher priority.
In addition to the keywords specified above, you may also use an asterisk (`*`) to define all facilities or priorities (depending on where you place the asterisk, before or after the dot). Specifying the keyword `none` serves for facilities with no given priorities.
To define multiple facilities and priorities, simply separate them with a comma (`,`). To define multiple filters on one line, separate them with a semi-colon (`;`).
The following are a few examples of simple facility/priority-based filters:
kern.* # Selects all kernel syslog messages with any priority
mail.crit # Selects all mail syslog messages with priority **crit** and higher.
cron.!info,!debug # Selects all cron syslog messages except those with the **info** or **debug** priority.
Property-based filters
: Property-based filters let you filter syslog messages by any property, such as _`timegenerated`_ or _`syslogtag`_. For more information on properties, refer to [Section 17.1.3.3.2, “Properties”](#s4-properties "17.1.3.3.2. Properties"). Each of the properties specified in the filters lets you compare it to a specific value using one of the compare-operations listed in [Table 17.1, “Property-based compare-operations”](#table-compare-operations "Table 17.1. Property-based compare-operations").
Table 17.1. Property-based compare-operations
|Compare-operation|Description|
|-|
|_`contains`_|Checks whether the provided string matches any part of the text provided by the property.|
|_`isequal`_|Compares the provided string against all of the text provided by the property.|
|_`startswith`_|Checks whether the provided string matches a prefix of the text provided by the property.|
|_`regex`_|Compares the provided POSIX BRE (Basic Regular Expression) regular expression against the text provided by the property.|
|_`ereregex`_|Compares the provided POSIX ERE (Extended Regular Expression) regular expression against the text provided by the property.|
To define a property-based filter, use the following syntax:
:_``_, [!]_``_, "_``_"
where:
* The _``_ attribute specifies the desired property (for example, _`timegenerated`_, _`hostname`_, etc.).
* The optional exclamation point (`!`) negates the output of the compare-operation (if prefixing the compare-operation).
* The _``_ attribute specifies one of the compare-operations listed in [Table 17.1, “Property-based compare-operations”](#table-compare-operations "Table 17.1. Property-based compare-operations").
* The _``_ attribute specifies the value that the text provided by the property is compared to. To escape certain character (for example a quotation mark (`"`)), use the backslash character (`\`).
The following are few examples of property-based filters:
* The following filter selects syslog messages which contain the string `error` in their message text:
:msg, contains, "error"
* The following filter selects syslog messages received from the hostname `host1`:
:hostname, isequal, "host1"
* The following filter selects syslog messages which do not contain any mention of the words `fatal` and `error` with any or no text between them (for example, `fatal lib error`):
:msg, !regex, "fatal .* error"
Expression-based filters
: Expression-based filters select syslog messages according to defined arithmetic, boolean or string operations. Expression-based filters use rsyslog's own scripting language. The syntax of this language is defined in `/usr/share/doc/rsyslog/rscript_abnf.html` along with examples of various expression-based filters.
To define an expression-based filter, use the following syntax:
if _``_ then _``_
where:
* The _``_ attribute represents an expression to be evaluated, for example: `$msg startswith 'DEVNAME'` or `$syslogfacility-text == 'local0'`.
* The _``_ attribute represents an action to be performed if the expression returns the value `true`.
### Define an expression-based filter on a single line
When defining an expression-based filter, it must be defined on a single line.
### Do not use regular expressions
Regular expressions are currently not supported in expression-based filters.
BSD-style blocks
: rsyslog supports BSD-style blocks inside the `/etc/rsyslog.conf` configuration file. Each block consists of rules which are preceded with a program or hostname label. Use the '!_``_' or '-_``_' labels to include or exclude programs, respectively. Use the '+_``_ ' or '-_``_ ' labels include or exclude hostnames, respectively.
[Example 17.1, “BSD-style block”](#example-bsd-block1 "Example 17.1. BSD-style block") shows a BSD-style block that saves all messages generated by yum to a file.
Example 17.1. BSD-style block
!yum
*.* /var/log/named.log
#### 17\.1.3.2. Actions {#s3-actions}
Actions specify what is to be done with the messages filtered out by an already-defined selector. The following are some of the actions you can define in your rule:
Saving syslog messages to log files
: The majority of actions specify to which log file a syslog message is saved. This is done by specifying a file path after your already-defined selector. The following is a rule comprised of a selector that selects all cron syslog messages and an action that saves them into the `/var/log/cron.log` log file:
cron.* /var/log/cron.log
Use a dash mark (`-`) as a prefix of the file path you specified if you want to omit syncing the desired log file after every syslog message is generated.
Your specified file path can be either static or dynamic. Static files are represented by a simple file path as was shown in the example above. Dynamic files are represented by a template and a question mark (`?`) prefix. For more information on templates, refer to [Section 17.1.3.3.1, “Generating dynamic file names”](#s4-generating-dynamic-fnames "17.1.3.3.1. Generating dynamic file names").
If the file you specified is an existing tty or `/dev/console` device, syslog messages are sent to standard output (using special tty-handling) or your console (using special `/dev/console`-handling) when using the X Window System, respectively.
Sending syslog messages over the network
: rsyslog allows you to send and receive syslog messages over the network. This feature allows to administer syslog messages of multiple hosts on one machine. To forward syslog messages to a remote machine, use the following syntax:
@[(_`