yum-software-management/en_US yum-software-management.xml,NONE,1.1

Author: elliss

Update of /cvs/docs/yum-software-management/en_US
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv22620

Added Files:
    yum-software-management.xml 
Log Message:
- Moved main file to en_US/ directory.

--- NEW FILE yum-software-management.xml ---
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!ENTITY % FEDORA-ENTITIES-EN SYSTEM "../../docs-common/common/fedora-entities-en.ent">
%FEDORA-ENTITIES-EN;

<!ENTITY DOCNAME "yum-software-management">
<!ENTITY DOCVERSION "1.0.5">
<!ENTITY DOCDATE "2005-11-28">
<!ENTITY DOCID "&DOCNAME;-&DOCVERSION; (&DOCDATE;)">
<!-- this will soon vanish -->
<!ENTITY BOOKID "&DOCNAME;-&DOCVERSION; (&DOCDATE;)">

<!ENTITY FCLOCALVER "4">
]>

<article id="yum-software-management" lang="en">

<xi:include href="fdp-info.xml" xmlns:xi="http://www.w3.org/2001/XInclude%22%3E
    xi:fallbackWHERE IS MY FDP-INFO, DUDE</xi:fallback>
  </xi:include>

<section id="sn-introduction">
    <title>Introduction</title>

<section id="sn-purpose">
      <title>Purpose</title>

<para>
        This document presents basic concepts of software management on
        &FED; systems. It outlines the major functions of
        <command>yum</command>, the recommended software management tool
        for &FED;.
      </para>
    </section>

<section id="sn-software-management-audience">
      <title>Audience</title>

<para>
        This document is intended for &FED; users of all levels of
        experience.
      </para>
    </section>

<section id="sn-software-management-usingdoc">
      <title>Using This Document</title>

<para>
        This document is a reference for using <command>yum</command>.
        You may wish to read some or all of the sections, depending upon
        your needs and level of experience. If you are a new user, read
        the <xref
      linkend="sn-software-management-concepts"/>
        before using <command>yum</command> for the first time.
        Experienced Linux users should start with
        <xref linkend="sn-managing-packages"/>.
      </para>

<note>
        <title>Previous Versions of &FC;</title>

<para>
          This document describes the configuration of
          <command>yum</command> on &FC; &FCLOCALVER; systems. You must
          perform the additional step noted in
          <xref linkend="sn-authorizing-package-sources" /> to enable
          <command>yum</command> on &FC; 3.
        </para>
      </note>

<para>
        Most of the examples in this document use the package
        <filename>tsclient</filename>, which is included with &FC;. The
        <filename>tsclient</filename> package provides an application
        for remote desktop access. If you install it successfully you
        may start the application by choosing
        <menuchoice><guimenu>Applications</guimenu><guisubmenu>Internet</guisubmenu><guimenuitem>Terminal
        Server Client</guimenuitem></menuchoice>. To use the examples,
        substitute the name of the relevant package for
        <filename>tsclient</filename>. The example commands for &FED;
        package groups use the <filename>MySQL Database</filename>
        group.
      </para>

<important>
        <title>Avoid Logging in with the Root Account</title>

<para>
          You do not need to log in with the
          <systemitem class="username">root</systemitem> account in
          order to manage your &FED; system. All of the commands shown
          in this tutorial that require
          <systemitem class="username">root</systemitem> access will
          prompt you for the
          <systemitem class="username">root</systemitem> password. The
          example terminal commands use <command>su
          <option>-c</option></command> to provide this facility.
        </para>
      </important>
    </section>

<section id="sn-yum-additional-resources">
      <title>Additional Resources</title>
      <indexterm>
        <primary>yum</primary>
        <secondary>documentation</secondary>
      </indexterm>
      <indexterm>
        <primary>yum</primary>
        <secondary>man pages</secondary>
      </indexterm>
      <para>
        The <command>yum</command> utility has features and options not
        discussed in this document. Read the <command>man</command>
        pages for <command>yum(8)</command> and
        <filename>yum.conf(5)</filename> to learn more, using the
        following commands:
      </para>
<screen>
<userinput>man yum
man yum.conf</userinput>
</screen>
      <indexterm>
        <primary>yum</primary>
        <secondary>web sites</secondary>
      </indexterm>
      <indexterm>
        <primary>yum</primary>
        <secondary>mailing lists</secondary>
      </indexterm>
      <para>
        Other useful <command>yum</command> resources on the Internet
        include:
      </para>

<variablelist>
        <varlistentry>
          <term>
        Project web site
      </term>
          <listitem>
            <para>
              <ulink url="http://linux.duke.edu/projects/yum/"/>
            </para>
          </listitem>
        </varlistentry>

<varlistentry>
          <term>
        Users mailing list
      </term>
          <listitem>
            <para>
              <ulink url="https://lists.dulug.duke.edu/mailman/listinfo/yum/"/>
            </para>
          </listitem>
        </varlistentry>

<varlistentry>
          <term>
        Development mailing list
      </term>
          <listitem>
            <para>
              <ulink url="https://lists.dulug.duke.edu/pipermail/yum-devel/"/>
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
      <tip>
        <title>Check &BZ; First</title>
        <para>
          If you encounter a persistent error with a specific operation,
          visit &BZ-URL; and review the bug reports for the package or
          packages involved. An error in a package may cause all
          <command>yum</command> operations that rely on that package to
          fail. Please file bug reports for &FED; packages, including
          <command>yum</command>, on this &BZ; web site.
        </para>
      </tip>
    </section>
  </section>

<section id="sn-software-management-concepts">
    <title>Software Management Concepts</title>

<section id="sn-about-packages">
      <title>About Packages</title>
      <indexterm>
        <primary>packages</primary>
        <secondary>defined</secondary>
      </indexterm>
      <para>
        &FED; software and documentation is supplied in the form of
        files called RPM <firstterm>packages</firstterm>. Each package
        is a compressed archive containing product information, program
        files, icons, documentation and management scripts. Management
        applications use these files to safely locate, install, update
        and remove software. For example, the &FED; installation process
        uses the packages supplied with &FC; to build or upgrade a
        system to your requirements.
      </para>

<para>
        Packages also include a digital signature to prove their source.
        Software management utilities verify this digital signature by
        using a GPG <firstterm>public key</firstterm>. The
        <command>yum</command> and <command>rpm</command> utilities
        share a common <firstterm>keyring</firstterm> that stores all of
        the public keys for approved package sources. The system
        administrator configures these approved package sources.
      </para>

<note>
        <title>All &FED; Packages are Open Source Software</title>

<para>
          All of the software provided by the &FP; is open source
          software. You may download and install &FED; packages on as
          many systems as desired.
        </para>
      </note>
    </section>

<section id="sn-about-repositories">
      <title>About Repositories</title>
      <indexterm>
        <primary>repositories</primary>
        <secondary>defined</secondary>
      </indexterm>
      <para>
        A <firstterm>repository</firstterm> is a prepared directory or
        web site that contains software packages and index files.
        Software management utilities such as <command>yum</command>
        automatically locate and obtain the correct RPM packages from
        these repositories. This method frees you from having to
        manually find and install new applications or updates. You may
        use a single command to update all system software, or search
        for new software by specifying criteria.
      </para>

<para>
        A network of servers provide several repositories for each
        version of &FC;. The package management utilities in &FC; are
        already configured to use three of these repositories:
      </para>

<variablelist>
        <varlistentry>
          <term>
        Base
      </term>
          <listitem>
            <para>
              The packages that make up a &FC; release, as it is on disc
            </para>
          </listitem>
        </varlistentry>

<varlistentry>
          <term>
        Updates
      </term>
          <listitem>
            <para>
              Updated versions of packages that are provided in Base
            </para>
          </listitem>
        </varlistentry>

<varlistentry>
          <term>
        &EX;
      </term>
          <listitem>
            <para>
              Packages for a large selection of additional software
            </para>
          </listitem>
        </varlistentry>
      </variablelist>

<note>
        <title>Previous Versions of &FC;</title>

<para>
          &FC; &FCLOCALVER; automatically supports the three
          repositories listed above. You must manually configure &FC; 3
          systems to use &FEX;, as noted in
          <xref linkend="sn-using-repositories"/>.
        </para>
      </note>

<warning>
        <title>&FED; Development Repositories</title>

<para>
          &FC; also includes settings for several alternative
          repositories. These provide packages for various types of test
          system, and replace one or more of the standard repositories.
          Only enable support for one of the following repositories if
          you test or develop &FED; software:
          <filename>fedora-devel</filename> (Rawhide),
          <filename>fedora-extras-devel</filename>, and
          <filename>updates-testing</filename>.
        </para>
      </warning>

<para>
        Third-party software developers also provide repositories for
        their &FED; compatible packages. To learn how to configure your
        &FED; system to use third-party repositories, read
        <xref linkend="sn-using-repositories"/>.
      </para>
      <indexterm>
        <primary>package groups</primary>
        <secondary>defined</secondary>
      </indexterm>
      <para>
        You may also use the <firstterm>package groups</firstterm>
        provided by the &FED; repositories to manage related packages as
        sets. Some third-party repositories add packages to these
        groups, or provide their packages as additional groups.
      </para>
<!-- SE: Some repositories use groups and some don't: I've tried to put this nicely. -->
<!-- SE: Using the admonition for this is not optimal, it just doesn't fit anywhere else. -->
      <note>
        <title>Available Package Groups</title>

<para>
          To view a list of all of the available package groups for your
          &FED; system, run the command <command>su -c 'yum
          grouplist'</command>.
        </para>
      </note>

<para>
        Use repositories to ensure that you always receive current
        versions of software. If several versions of the same package
        are available, your management utility automatically selects the
        latest version.
      </para>

<caution>
        <title>Installing Software not from a Repository</title>

<para>
          Install software using manual methods only when you are
          confident there is no repository which can currently provide
          it. You may have to manage that software with manual methods,
          instead of with &FED; software management utilities.
        </para>

<para>
          The <command>yum</command> commands shown in this document use
          repositories as package sources. Refer to
          <xref linkend="sn-yum-installing-frompackage"/> for details of
          using <command>yum</command> to install software from a
          package file.
        </para>
      </caution>
    </section>

<section id="sn-about-dependencies">
      <title>About Dependencies</title>
      <indexterm>
        <primary>dependencies</primary>
        <secondary>defined</secondary>
      </indexterm>
      <para>
        Some of the files installed on a &FED; distribution are
        <firstterm>libraries</firstterm> which may provide functions to
        multiple applications. When an application requires a specific
        library, the package which contains that library is a
        <firstterm>dependency</firstterm>. To properly install a
        package, &FED; must first satisfy its dependencies. The
        dependency information for a RPM package is stored within the
        RPM file.
      </para>

<para>
        The <command>yum</command> utility uses package dependency data
        to ensure that all of requirements for an application are met
        during installation. It automatically installs the packages for
        any dependencies not already present on your system. If a new
        application has requirements that conflict with existing
        software, <command>yum</command> aborts without making any
        changes to your system.
      </para>
    </section>

<section id="sn-package-names">
      <title>Understanding Package Names</title>
      <indexterm>
        <primary>packages</primary>
        <secondary>hardware compatibility</secondary>
      </indexterm>
      <indexterm>
        <primary>packages</primary>
        <secondary>naming</secondary>
      </indexterm>
      <para>
        Each package file has a long name that indicates several key
        pieces of information. For example, this is the full name of a
        <filename>tsclient</filename> package:
      </para>
<screen>
<filename>tsclient-0.132-6.i386.rpm</filename>
</screen>
      <para>
        Management utilities commonly refer to packages with one of
        three formats:
      </para>

<itemizedlist>
        <listitem>
          <para>
            Package name: <filename>tsclient</filename>
          </para>
        </listitem>
        <listitem>
          <para>
            Package name with version and release numbers:
            <filename>tsclient-0.132-6</filename>
          </para>
<!-- In what instances is the release number not needed?  For many -->
<!-- package updates, only the release number might change. Although it -->
<!-- might be superfluous, it's never *bad* to include it, right? [PWF] -->
        </listitem>
        <listitem>
          <para>
            Package name with hardware architecture:
            <filename>tsclient.i386</filename>
          </para>
        </listitem>
      </itemizedlist>

<para>
        For clarity, <command>yum</command> lists packages in the format
        <filename>name.architecture</filename>. Repositories also
        commonly store packages in separate directories by architecture.
        In each case, the hardware architecture specified for the
        package is the <emphasis>minimum</emphasis> type of machine
        required to use the package.
      </para>

<variablelist>
        <varlistentry>
          <term>
        i386
      </term>
          <listitem>
            <para>
              Suitable for any current Intel-compatible computer
            </para>
          </listitem>
        </varlistentry>

<varlistentry>
          <term>
        noarch
      </term>
          <listitem>
            <para>
              Compatible with all computer architectures
            </para>
          </listitem>
        </varlistentry>

<varlistentry>
          <term>
        ppc
      </term>
          <listitem>
            <para>
              Suitable for PowerPC systems, such as Apple Power
              Macintosh
            </para>
          </listitem>
        </varlistentry>

<varlistentry>
          <term>
        x86_64
      </term>
          <listitem>
            <para>
              Suitable for 64-bit Intel-compatible processors, such as
              Opterons
            </para>
          </listitem>
        </varlistentry>
      </variablelist>

<para>
        Some software may be optimized for particular types of
        Intel-compatible machine. Separate packages may be provided for
        <option>i386</option>, <option>i586</option>,
        <option>i686</option> and <option>x86_64</option> computers. A
        machine with at least an Intel Pentium, VIA C3 or compatible CPU
        may use <option>i586</option> packages. Computers with an Intel
        Pentium Pro and above, or a current model of AMD chip, may use
        <option>i686</option> packages.
      </para>

<para>
        Use the short name of the package for <command>yum</command>
        commands. This causes <command>yum</command> to automatically
        select the most recent package in the repositories that matches
        the hardware architecture of your computer.
      </para>

<para>
        Specify a package with other name formats to override the
        default behavior and force <command>yum</command> to use the
        package that matches that version or architecture. Only override
        <command>yum</command> when you know that the default package
        selection has a bug or other fault that makes it unsuitable for
        installation.
      </para>
      <tip>
        <title>Package Names</title>
        <para>
          You may use any of the following formats to specify a package
          in a <command>yum</command> operation:
          <replaceable>name</replaceable>,
          <replaceable>name.architecture</replaceable>,
          <replaceable>name-version</replaceable>,
          <replaceable>name-version-release</replaceable>,
          <replaceable>name-version-release.architecture</replaceable>,
          and
          <replaceable>epoch:name-version-release.architecture</replaceable>.
        </para>
      </tip>
    </section>
  </section>

<section id="sn-software-management-tools">
    <title>Software Management Tools in &FC;</title>
    <indexterm>
      <primary>Add/Remove Applications utility</primary>
    </indexterm>
    <indexterm>
      <primary>Alert Icon</primary>
    </indexterm>
    <indexterm>
      <primary>up2date</primary>
    </indexterm>
    <para>
      The <command>yum</command> utility is a complete software
      management system. &FC; also includes several other applications
      that can supplement <command>yum</command>.
    </para>

<para>
      On your desktop is an <application>Alert Icon</application> that
      keeps you informed about package updates. Until your system is
      updated the icon appears as a red circle with a flashing
      exclamation mark. The Alert Icon is part of the
      <application>up2date</application> application, which enables you
      to easily install system updates.
    </para>

<para>
      &FC; also includes
      <application>system-config-packages</application>. To run this
      application from the graphical interface, select <menuchoice>
      <guimenu>Desktop</guimenu> <guisubmenu>System
      Settings</guisubmenu> <guimenuitem>Add/Remove
      Applications</guimenuitem> </menuchoice>. Unlike
      <application>up2date</application> and <command>yum</command>,
      <application>system-config-packages</application> installs
      software packages from your &FC; installation discs only, and does
      not use repositories. This application is used on systems that do
      not have a network connection.
    </para>

<para>
      The <command>rpm</command> command-line utility has many functions
      for working with individual RPM packages. You may use it to
      manually install and remove packages from your system. If you
      install software with the <command>rpm</command> utility, you must
      manually check and install any dependencies. For this reason,
      <command>yum</command> is the recommended method for installing
      software.
    </para>

<caution>
      <title>Current Package Versions</title>

<para>
        The <application>up2date</application> and
        <command>yum</command> utilities ensure that you have the most
        recent version of software packages. Other methods do not
        guarantee that the packages are current.
      </para>
    </caution>
  </section>

<section id="sn-managing-packages">
    <title>Managing Software with <command>yum</command></title>
    <indexterm>
      <primary>yum</primary>
      <secondary>software management</secondary>
    </indexterm>
    <para>
      Use the <command>yum</command> utility to modify the software on
      your system in four ways:
    </para>

<para>
      <itemizedlist>
        <listitem>
          <para>
            To install new software from package repositories
          </para>
        </listitem>
        <listitem>
          <para>
            To install new software from an individual package file
          </para>
        </listitem>
        <listitem>
          <para>
            To update existing software on your system
          </para>
        </listitem>
        <listitem>
          <para>
            To remove unwanted software from your system
          </para>
        </listitem>
      </itemizedlist>
    </para>
<!-- SE: This duplicates text from the admonition in sn-about-repositories.  It's here as well because the Fedora site has a link straight to this section -->
    <important>
      <title>Installing Software from a Package File</title>

<para>
        The <command>yum</command> commands shown in this section use
        repositories as package sources. Refer to
        <xref linkend="sn-yum-installing-frompackage"/> for details of
        using <command>yum</command> to install software from an
        individual package file.
      </para>
    </important>

<para>
      To use <command>yum</command>, specify a function and one or more
      packages or package groups. Each section below gives some
      examples.
    </para>

<para>
      For each operation, <command>yum</command> downloads the latest
      package information from the configured repositories. If your
      system uses a slow network connection <command>yum</command> may
      require several seconds to download the repository indexes and the
      header files for each package.
    </para>

<para>
      The <command>yum</command> utility searches these data files to
      determine the best set of actions to produce the required result,
      and displays the transaction for you to approve. The transaction
      may include the installation, update, or removal of additional
      packages, in order to resolve software dependencies.
    </para>

<example id="yum-transaction-format">
      <title>Format of <command>yum</command> Transaction Reports</title>

<para>
        This is an example of the transaction for installing
        <filename>tsclient</filename>:
      </para>
<screen>
<computeroutput>=============================================================================
 Package                 Arch       Version          Repository        Size
=============================================================================
Installing:
 tsclient                i386       0.132-6          base              247 k
Installing for dependencies:
 rdesktop                i386       1.4.0-2          base              107 k

Transaction Summary
=============================================================================
Install      2 Package(s)
Update       0 Package(s)
Remove       0 Package(s)
Total download size: 355 k
Is this ok [y/N]:</computeroutput>
</screen>
    </example>

<para>
      Review the list of changes, and then press <keycap>y</keycap> to
      accept and begin the process. If you press <keycap>N</keycap> or
      <keycap>Enter</keycap>, <command>yum</command> does not download
      or change any packages.
    </para>

<note>
      <title>Package Versions</title>

<para>
        The <command>yum</command> utility only displays and uses the
        newest version of each package, unless you specify an older
        version.
      </para>
    </note>

<para>
      The <command>yum</command> utility also imports the repository
      public key if it is not already installed on the
      <command>rpm</command> keyring.
    </para>

<example id="yum-publickey-import">
      <title>Format of <command>yum</command> Public Key Import</title>

<para>
        This is an example of the public key import:
      </para>
<screen>
<computeroutput>warning: rpmts_HdrFromFdno: Header V3 DSA signature: NOKEY, key ID 4f2a6fd2
public key not available for tsclient-0.132-6.i386.rpm
Retrieving GPG key from file:///etc/pki/rpm-gpg/RPM-GPG-KEY-fedora
Importing GPG key 0x4F2A6FD2 "Fedora Project &lt;[e-mail]&gt;"
Is this ok [y/N]:</computeroutput>
</screen>
    </example>

<para>
      Check the public key, and then press <keycap>y</keycap> to import
      the key and authorize the key for use. If you press
      <keycap>N</keycap> or <keycap>Enter</keycap>,
      <command>yum</command> stops without installing any packages.
    </para>

<para>
      To ensure that downloaded packages are genuine,
      <command>yum</command> verifies the digital signature of each
      package against the public key of the provider. Once all of the
      packages required for the transaction are successfully downloaded
      and verified, <command>yum</command> applies them to your system.
    </para>

<para>
      Every completed transaction records the affected packages in the
      log file <filename>/var/log/yum.log</filename>. You may only read
      this file with <systemitem class="username">root</systemitem>
      access.
    </para>
    <tip>
      <title>Downloads are Cached</title>
      <para>
        The <command>yum</command> utility keeps downloaded data files
        and packages for reuse. You may copy packages from the
        repository cache directories under
        <filename>/var/cache/yum/</filename>, and use them elsewhere if
        you wish. If you remove a package from the cache, you do not
        affect the copy of the software installed on your system.
      </para>
    </tip>
    <section id="sn-yum-installing-withrepositories">
      <title>Installing New Software with <command>yum</command></title>
      <indexterm>
        <primary>installing software</primary>
        <see>software, installing</see>
      </indexterm>
      <indexterm>
        <primary>software</primary>
        <secondary>installing</secondary>
      </indexterm>
      <para>
        To install the package <filename>tsclient</filename>, enter the
        command:
      </para>
<screen>
<userinput>su -c 'yum install <replaceable>tsclient</replaceable>'</userinput>
</screen>
      <para>
        Enter the password for the
        <systemitem class="username">root</systemitem> account when
        prompted.
      </para>

<para>
        To install the package group <filename>MySQL
        Database</filename>, enter the command:
      </para>
<screen>
<userinput>su -c 'yum groupinstall "<replaceable>MySQL Database</replaceable>"'</userinput>
</screen>
      <para>
        Enter the password for the
        <systemitem class="username">root</systemitem> account when
        prompted.
      </para>

<important>
        <title>New Services Require Activation</title>

<para>
          When you install a service, &FED; does not activate or start
          it. To configure a new service to run on bootup, choose
          <menuchoice> <guimenu>Desktop</guimenu> <guisubmenu>System
          Settings</guisubmenu> <guisubmenu>Server Settings</guisubmenu>
          <guimenuitem>Services</guimenuitem> </menuchoice>, or use the
          <command>chkconfig</command> and <command>service</command>
          command-line utilities.
        </para>
      </important>
    </section>

<section id="sn-yum-updating-withrepositories">
      <title>Updating Software with <command>yum</command></title>
      <indexterm>
        <primary>updating</primary>
        <secondary>software packages</secondary>
      </indexterm>
      <indexterm>
        <primary>software</primary>
        <secondary>updating</secondary>
      </indexterm>
      <para>
        To update the <filename>tsclient</filename> package to the
        latest version, type:
      </para>
<screen>
<userinput>su -c 'yum update <replaceable>tsclient</replaceable>'</userinput>
</screen>
      <para>
        Enter the password for the
        <systemitem class="username">root</systemitem> account when
        prompted.
      </para>

<important>
        <title>New Software Versions Require Reloading</title>

<para>
          If a piece of software is in use when you update it, the old
          version remains active until the application or service is
          restarted. Kernel updates take effect when you reboot the
          system.
        </para>
      </important>

<para>
        To update all of the packages in the package group
        <filename>MySQL Database</filename>, enter the command:
      </para>
<screen>
<userinput>su -c 'yum groupupdate "<replaceable>MySQL Database</replaceable>"'</userinput>
</screen>
      <para>
        Enter the password for the
        <systemitem class="username">root</systemitem> account when
        prompted.
      </para>

<note>
        <title>Updating the Entire System</title>

<para>
          To update all of the packages on your &FED; system, use the
          commands described in
          <xref
      linkend="sn-updating-your-system"/>.
        </para>
      </note>
    </section>

<section id="sn-yum-removing-software">
      <title>Removing Software with <command>yum</command></title>
      <indexterm>
        <primary>removing software</primary>
      </indexterm>
      <indexterm>
        <primary>software</primary>
        <secondary>removing</secondary>
      </indexterm>
      <para>
        To remove software, <command>yum</command> examines your system
        for both the specified software, and any software which claims
        it as a dependency. The transaction to remove the software
        deletes both the software and the dependencies.
      </para>

<para>
        To remove the <filename>tsclient</filename> package from your
        system, use the command:
      </para>
<screen>
<userinput>su -c 'yum remove <replaceable>tsclient</replaceable>'</userinput>
</screen>
      <para>
        Enter the password for the
        <systemitem class="username">root</systemitem> account when
        prompted.
      </para>

<para>
        To remove all of the packages in the package group
        <filename>MySQL Database</filename>, enter the command:
      </para>
<screen>
<userinput>su -c 'yum groupremove "<replaceable>MySQL Database</replaceable>"'</userinput>
</screen>
      <para>
        Enter the password for the
        <systemitem class="username">root</systemitem> account when
        prompted.
      </para>

<note>
        <title>Data and Configuration File Retention</title>

<para>
          The removal process leaves user data in place but may remove
          configuration files in some cases. If a package removal does
          not include the configuration file, and you reinstall the
          package later, it may reuse the old configuration file.
        </para>
      </note>
    </section>
  </section>

<section id="sn-searching-packages">
    <title>Searching for Packages with <command>yum</command></title>
    <indexterm>
      <primary>packages</primary>
      <secondary>locating</secondary>
    </indexterm>
    <indexterm>
      <primary>searching</primary>
      <secondary>for packages</secondary>
    </indexterm>
    <para>
      Use the search features of <command>yum</command> to find software
      that is available from the configured repositories, or already
      installed on your system. Searches automatically include both
      installed and available packages.
    </para>

<para>
      The format of the results depends upon the option. If the query
      produces no information, there are no packages matching the
      criteria.
    </para>

<section id="sn-searching-packages-byname">
      <title>Searching by Package Name and Attributes</title>

<para>
        To search for a specific package by name, use the
        <option>list</option> function. To search for the package
        <filename>tsclient</filename>, use the command:
      </para>
<screen>
<userinput>su -c 'yum list <replaceable>tsclient</replaceable>'</userinput>
</screen>
      <para>
        Enter the password for the
        <systemitem class="username">root</systemitem> account when
        prompted.
      </para>

<para>
        To make your queries more precise, specify packages with a name
        that include other attributes, such as version or hardware
        architecture. To search for version 0.132 of the application,
        use the command:
      </para>
<screen>
<userinput>su -c 'yum list <replaceable>tsclient-0.132</replaceable>'</userinput>
</screen>
      <note>
        <title>Valid Package Attributes</title>

<para>
          Refer to <xref linkend="sn-package-names" /> for information
          on package name formats and the attributes that they include.
        </para>
      </note>
    </section>

<section id="sn-searching-packages-advanced">
      <title>Advanced Searches</title>

<para>
        If you do not know the name of the package, use the
        <option>search</option> or <option>provides</option> options.
        Alternatively, use wild cards or regular expressions with any
        <command>yum</command> search option to broaden the search
        critieria.
      </para>

<para>
        The <option>search</option> option checks the names,
        descriptions, summaries and listed package maintainers of all of
        the available packages to find those that match. For example, to
        search for all packages that relate to PalmPilots, type:
      </para>
<screen>
<userinput>su -c 'yum search <replaceable>PalmPilot</replaceable>'</userinput>
</screen>
      <para>
        Enter the password for the
        <systemitem class="username">root</systemitem> account when
        prompted.
      </para>

<para>
        The <option>provides</option> function checks both the files
        included in the packages and the functions that the software
        provides. This option requires <command>yum</command> to
        download and read much larger index files than with the
        <option>search</option> option.
      </para>

<para>
        To search for all packages that include files called
        <filename>libneon</filename>, type:
      </para>
<screen>
<userinput>su -c 'yum provides <replaceable>libneon</replaceable>'</userinput>
</screen>
      <para>
        To search for all packages that either provide a MTA (Mail
        Transport Agent) service, or include files with
        <filename>mta</filename> in their name:
      </para>
<screen>
<userinput>su -c 'yum provides <replaceable>MTA</replaceable>'</userinput>
</screen>
      <para>
        For each command, at the prompt enter the password for the
        <systemitem class="username">root</systemitem> account.
      </para>

<para>
        Use the standard wildcard characters to run any search option
        with a partial word or name: <option>?</option> to represent any
        one character, and <option>*</option> to mean zero or more
        characters. Always add the escape character (<option></option>)
        before wildcards.
      </para>

<para>
        To <option>list</option> all packages with names that begin with
        <filename>tsc</filename>, type:
      </para>
<screen>
<userinput>su -c 'yum list <replaceable>tsc*</replaceable>'</userinput>
</screen>
      <tip>
        <title>Regular Expressions</title>
        <para>
          Use Perl or Python regular expressions to carry out more
          complex queries.
        </para>
      </tip>
    </section>

<section id="sn-package-matches">
      <title>Understanding Matches</title>

<para>
        Searches with <command>yum</command> show all of the packages
        that match your criteria. Packages must meet the terms of the
        search exactly to be considered matches, unless you use
        wildcards or a regular expression.
      </para>

<para>
        For example, a search query for <filename>shadowutils</filename>
        or <filename>shadow-util</filename> would not produce the
        package <filename>shadow-utils</filename>. This package would
        match and be shown if the query was
        <filename>shadow-util?</filename>, or
        <filename>shadow*</filename>.
      </para>
    </section>
  </section>

<section id="sn-updating-your-system">
    <title>Updating Your System with <command>yum</command></title>
    <indexterm>
      <primary>updating</primary>
      <secondary>full system</secondary>
    </indexterm>
    <indexterm>
      <primary>yum</primary>
      <secondary>updating full system</secondary>
    </indexterm>
    <para>
      Use the <option>update</option> option to upgrade all of your
      &FED; system software to the latest version with one operation.
    </para>

<para>
      To perform a full system update, type this command:
    </para>
<screen>
<userinput>su -c 'yum update'</userinput>
</screen>
    <para>
      At the prompt, enter the
      <systemitem
    class="username">root</systemitem> password.
    </para>

<section id="sn-automatic-updating">
      <title>Automatically Updating Your System</title>
      <indexterm>
        <primary>automatic updating</primary>
      </indexterm>
      <para>
        The <filename>yum</filename> package supplied with &FC; includes
        scripts to perform full system updates every day. To activate
        automatic daily updates, enter this command:
      </para>
<screen>
<userinput>su -c '/sbin/chkconfig --level 345 yum on; /sbin/service yum start'</userinput>
</screen>
      <para>
        At the prompt, enter the password for the
        <systemitem class="username">root</systemitem> account.
      </para>

<note>
        <title>How Daily Updates are Run</title>

<para>
          There is no separate <command>yum</command> service that runs
          on your system. The command given above enables the control
          script <filename>/etc/rc.d/init.d/yum</filename>. This control
          script activates the script
          <filename>/etc/cron.daily/yum.cron</filename>, which causes
          the <command>cron</command> service to perform the system
          update automatically at 4am each day.
        </para>
      </note>
    </section>
  </section>

<section id="sn-using-repositories">
    <title>Using Other Software Repositories</title>
    <indexterm>
      <primary>&FEX;</primary>
    </indexterm>
    <indexterm>
      <primary>repositories</primary>
      <secondary>finding</secondary>
    </indexterm>
    <indexterm>
      <primary>searching</primary>
      <secondary>for repositories</secondary>
    </indexterm>
    <para>
      &FED; systems automatically use the &FP; repositories. These
      include &FEX;, the default source of packages for software that is
      not included with &FC;.
    </para>

<note>
      <title>&FEX; Repositories for Previous Versions of &FC;</title>

<para>
        You must manually configure &FC; 3 systems to use &FEX;, using
        the instructions at
        <ulink
      url="http://fedora.redhat.com/projects/extras/"/>. For
        additional packages for &FC; 1 and &FC; 2, refer to
        <ulink
      url="http://www.fedora.us/"/>.
      </para>
    </note>

<para>
      If the &FP; does not supply packages for a product, the
      manufacturer may provide or recommend a separate repository.
      Members of the community also maintain repositories to provide
      packages for &FED; systems. For example,
      <ulink
  url="http://www.jpackage.org/"/> distributes popular Java
      software as packages.
    </para>

<section id="sn-adding-repositories">
      <title>Adding a Repository as a Package Source</title>
      <indexterm>
        <primary>repositories</primary>
        <secondary>adding to yum</secondary>
      </indexterm>
      <para>
        To add an extra repository, place a definition file in the
        <filename>/etc/yum.repos.d/</filename> directory on your system.
        Package providers make the definition files for their
        repositories available on their web sites.
      </para>
      <tip>
        <title>Definition File Extension</title>
        <para>
          The names of repository definition files end with
          <filename>.repo</filename>.
        </para>
      </tip>
      <para>
        You must have <systemitem class="username">root</systemitem>
        access to add a file to the definitions directory. To copy the
        definition file <filename>example.repo</filename>, type this
        command:
      </para>
<screen>
<userinput>su -c 'cp example.repo /etc/yum.repos.d/'</userinput>
</screen>
      <para>
        At the prompt, enter the password for the
        <systemitem class="username">root</systemitem> account.
      </para>

<para>
        The configuration file for each repository should include a
        <command>gpgkey</command> setting. This setting specifies the
        location of a public key that verifies the packages provided by
        that repository. This public key is automatically imported the
        first time that you install software from the repository. If the
        configuration file provided does not include this setting, refer
        to <xref linkend="sn-authorizing-package-sources"/>.
      </para>

<note>
        <title>Repositories and <application>up2date</application> Channels</title>

<para>
          Starting with &FC; 4, <command>yum</command> repositories are
          automatically used as <application>up2date</application>
          channels. On &FC; 3 and earlier systems, you must manually
          configure <application>up2date</application> to use these
          channels. To do so, edit the
          <filename>/etc/sysconfig/rhn/sources</filename> file.
        </para>
      </note>
    </section>

<section id="sn-authorizing-package-sources">
      <title>Manually Authorizing Package Sources</title>
      <indexterm>
        <primary>public keys</primary>
        <secondary>adding</secondary>
      </indexterm>
      <para>
        To manually add a public key to your <command>rpm</command>
        keyring, use the <option>import</option> feature of the
        <command>rpm</command> utility. To import the file
        <filename>GPG-PUB-KEY.asc</filename>, type the following
        command:
      </para>
<screen>
<userinput>su -c 'rpm --import <replaceable>GPG-PUB-KEY.asc</replaceable>'</userinput>
</screen>
      <para>
        At the prompt, enter the password for the
        <systemitem class="username">root</systemitem> account.
      </para>

<para>
        You may also import public keys directly from a web site. For
        example, to import the file <filename>GPG-PUB-KEY.asc</filename>
        on the web site <wordasword>www.therepository.com</wordasword>
        use this command:
      </para>
<screen>
<userinput>su -c 'rpm --import <replaceable>http://www.therepository.com/GPG-PUB-KEY.asc</replaceable>'</userinput>
</screen>
      <para>
        At the prompt, enter the
        <systemitem
    class="username">root</systemitem> password.
      </para>

<important>
        <title>Importing the &FED; Key on &FC; 3</title>

<para>
          To add the &FED; public key to the <command>rpm</command>
          keyring on &FC; 3 systems, run the command <command>su -c 'rpm
          --import /usr/share/rhn/RPM-GPG-KEY-fedora'</command>.
        </para>
      </important>
    </section>

<section id="sn-compat-repositories">
      <title>Understanding Repository Compatibility</title>
      <indexterm>
        <primary>packages</primary>
        <secondary>software compatibility</secondary>
      </indexterm>
      <indexterm>
        <primary>repositories</primary>
        <secondary>compatibility</secondary>
      </indexterm>
      <para>
        The &FEX; repository provides packages which are built to the
        same standards as &FC; packages. Third-party packages should be
        compatible with these &FP; packages, unless the provider
        specifically states otherwise.
      </para>

<para>
        Always read the web site of the repository for information on
        package compatibility before you add it as a package source.
        Separate repository providers may offer different and
        incompatible versions of the same software. Third-party
        repositories may also provide alternative packages for software
        that is included in &FED; repositories.
      </para>

<para>
        Alternative packages may contain versions of the software that
        function differently from the version in the &FP; packages.
        Determine the benefits and potential incompatibilities before
        replacing &FP; packages with alternative versions.
      </para>

<caution>
        <title>Incompatible Repositories</title>

<para>
          If you configure your system to use incompatible repositories
          <command>yum</command> operations may fail.
        </para>
      </caution>

<para>
        Packages built for one version of &FED; are usually not
        compatible with other versions of &FED;. The web site of the
        provider should specifically state which versions of &FED; they
        support.
      </para>
      <tip>
        <title>Old Versions of <command>yum</command> and Current Repositories</title>
        <para>
          The data format for repository indexes changed with version
          2.1 of <command>yum</command>. This was the version supplied
          with &FC; 3. Repository providers should specify the versions
          of &FC; that they support. To confirm that an unlabeled
          repository is compatible with current versions of
          <command>yum</command>, check that it has a sub-directory
          called <filename>repodata/</filename>.
        </para>
      </tip>
    </section>
  </section>

<section id="sn-yum-installing-frompackage">
    <title>Installing Software from an Isolated Package</title>
    <indexterm>
      <primary>installing software</primary>
      <secondary>from a package</secondary>
      <see>software, installing from a package</see>
    </indexterm>
    <indexterm>
      <primary>software</primary>
      <secondary>installing from a package</secondary>
    </indexterm>
    <para>
      Use repositories and the standard <command>yum</command> commands
      to locate and install new software, unless the software package is
      not available from any repository. In these cases, use the
      <option>localinstall</option> function to install the software
      from the package file.
    </para>

<important>
      <title>Public Key is Required</title>

<para>
        Ensure that the public key for the package source has been
        imported before you install a package without a repository.
        Refer to <xref linkend="sn-authorizing-package-sources"/>.
      </para>
    </important>

<para>
      Enter this command to install the package
      <filename>tsclient-0.132-4.i386.rpm</filename>:
    </para>
<screen>
<userinput>su -c 'yum localinstall <replaceable>tsclient-0.132-4.i386.rpm</replaceable>'</userinput>
</screen>
    <para>
      At the prompt, enter the
      <systemitem
    class="username">root</systemitem> password.
    </para>

<note>
      <title>Previously Installed Software is Updated</title>

<para>
        If the package provides a later version of software that is
        already installed on your system, <command>yum</command> updates
        the installed software.
      </para>
    </note>

<para>
      If the package requires software that is not installed on your
      system, <command>yum</command> attempts to meet the dependencies
      with packages from the configured repositories. You may need to
      manually download and install additional packages in order to
      satisfy all of the dependencies.
    </para>

<caution>
      <title>Maintaining Manually Installed Software</title>

<para>
        If you install software that is not provided by a repository,
        <command>yum update</command> cannot automatically upgrade it as
        new versions become available. To ensure that you have the
        latest packages, subscribe to e-mail or RSS services that notify
        you when new versions are released.
      </para>
    </caution>
  </section>

<section id="sn-yum-maintenance">
    <title>Maintaining <command>yum</command></title>

<para>
      The <command>yum</command> system does not require any routine
      maintenance. To ensure that <command>yum</command> operations are
      carried out at optimal speed, disable or remove repository
      definitions which you no longer require. You may also clear the
      files from the <command>yum</command> caches in order to recover
      disk space.
    </para>

<section id="sn-removing-sources">
      <title>Disabling or Removing Package Sources</title>
      <indexterm>
        <primary>repositories</primary>
        <secondary>disabling in yum</secondary>
      </indexterm>
      <indexterm>
        <primary>repositories</primary>
        <secondary>removing from yum</secondary>
      </indexterm>
      <para>
        Set <command>enable=0</command> in a definition file to prevent
        <command>yum</command> from using that repository. The
        <command>yum</command> utility ignores any definition file with
        this setting.
      </para>

<para>
        To completely remove access to a repository:
      </para>
      <procedure>
        <step>
          <para>
            Delete the relevant file from
            <filename>/etc/yum.repos.d/</filename>.
          </para>
        </step>
        <step>
          <para>
            Delete the cache directory from
            <filename>/var/cache/yum/</filename>.
          </para>
        </step>
      </procedure>
<!-- What with the "web of trust," removing GPG keys is not really -->
<!-- something we should encourage. Having an extra GPG key in the RPM -->
<!-- database is not a vulnerability, nor does it hamper the system in -->
<!-- any way.  These are probably a couple of reasons Seth didn't build -->
<!-- this function into yum as part of "clean all," for example.  Since -->
<!-- we just had several admonitions against people running the rpm -->
<!-- command on its own anyway, I would just omit this part -->
<!-- completely. [PWF] -->
<!--

<important>
        <title>Remove Unneeded Public Keys</title>

<para>
          If you will not be using any further packages from a provider,
      remove their public key from the <command>rpm</command>
      keyring using the procedure described in
          <xref linkend="sn-removing-publickeys" />.
        </para>
      </important>
    </section>

<section id="sn-removing-publickeys">
      <title>Removing Public Keys</title>
      <indexterm>
        <primary>public keys, removing</primary>
      </indexterm>
      <para>
        To remove a public key from the keyring you first must determine
        the full name of the key, as it registered in
        <command>rpm</command>. Run this command to view the details of
        the public keys on the <command>rpm</command> keyring:
      </para>
<screen>
<userinput>rpm -qi gpg-pubkey-*</userinput>
</screen>
      <para>
        Locate the heading for the relevant public key. The public key
        headings follow this format:
      </para>

<example id="publickey-header-format">
        <title>Format of <command>rpm</command> Public Key Headers</title>
<screen>
<computeroutput>Name        : gpg-pubkey                   Relocations: (not relocatable)
Version     : 4f2a6fd2                          Vendor: (none)
Release     : 3f9d9d3b                      Build Date: Wed 15 Jun 2005 09:55:33 PM BST
Install Date: Wed 15 Jun 2005 09:55:33 PM BST      Build Host: localhost
Group       : Public Keys                   Source RPM: (none)
Size        : 0                                License: pubkey
Signature   : (none)
Summary     : gpg(Fedora Project &lt;[e-mail]&gt;)
Description :</computeroutput>
</screen>
      </example>

<para>
        Add the <option>Version</option> and <option>Release</option>
        attributes to <option>gpg-pubkey-</option> to make the complete
        name of the key, in the form
        <option>gpg-pubkey-Version_number-Release_number</option>. The
        <command>rpm</command> identification for the &FP; public key
        shown above is: <option>gpg-pubkey-4f2a6fd2-3f9d9d3b</option>.
      </para>

<para>
        Once you know the identification name of the key, use the
        command <command>rpm <option>-e</option></command> to remove it.
        To remove the &FP; public key shown above the exact command
        would be:
      </para>
<screen>
<userinput>su -c 'rpm -e <replaceable>gpg-pubkey-4f2a6fd2-3f9d9d3b</replaceable>'</userinput>
</screen>
      <para>
        Enter the password for the
        <systemitem class="username">root</systemitem> account when
        prompted.
      </para>

-->
    </section>

<section id="sn-yum-clearance">
      <title>Clearing the <command>yum</command> Caches</title>
      <indexterm>
        <primary>yum</primary>
        <secondary>cleaning caches</secondary>
      </indexterm>
      <para>
        By default, <command>yum</command> retains the packages and
        package data files that it downloads, so that they may be reused
        in future operations without being downloaded again. To purge
        the package data files, use this command:
      </para>
<screen>
<userinput>su -c 'yum clean headers'</userinput>
</screen>
      <para>
        Run this command to remove all of the packages held in the
        caches:
      </para>
<screen>
<userinput>su -c 'yum clean packages'</userinput>
</screen>
      <para>
        When using these commands, at the prompt, enter the password for
        the <systemitem class="username">root</systemitem> account.
      </para>

<para>
        Purging cached files causes those files to downloaded again the
        next time that they are required. This increases the amount of
        time required to complete the operation.
      </para>
    </section>
  </section>

<section id="sn-yum-proxy-server">
    <title>Using <command>yum</command> with a Proxy Server</title>
    <indexterm>
      <primary>proxy server</primary>
    </indexterm>
    <indexterm>
      <primary>yum</primary>
      <secondary>using with a proxy server</secondary>
    </indexterm>
    <para>
      By default, <command>yum</command> accesses network repositories
      with HTTP. All <command>yum</command> HTTP operations use
      HTTP/1.1, and are compatible with web proxy servers that support
      this standard. You may also access FTP repositories, and configure
      <command>yum</command> to use an FTP proxy server. The
      <filename>squid</filename> package provides a proxy service for
      both HTTP/1.1 and FTP connections.
    </para>
    <tip>
      <title>Modifying <command>yum</command> for Network Compatibility</title>
      <para>
        Refer to the <command>man</command> page for
        <filename>yum.conf</filename> for information on HTTP settings
        that may be modified for compatibility with nonstandard web
        proxy servers. Alternatively, configure <command>yum</command>
        to use an FTP proxy server, and access repositories that support
        FTP. The &FED; repositories support both HTTP and FTP.
      </para>
    </tip>
    <section id="sn-yum-proxy-server-global">
      <title>Configuring Proxy Server Access</title>

<para>
        To enable all <command>yum</command> operations to use a proxy
        server, specify the proxy server details in
        <filename>/etc/yum.conf</filename>. The <option>proxy</option>
        setting must specify the proxy server as a complete URL,
        including the TCP port number. If your proxy server requires a
        username and password, specify these by adding
        <option>proxy_username</option> and
        <option>proxy_password</option> settings.
      </para>

<para>
        The settings below enable <command>yum</command> to use the
        proxy server
        <systemitem
    class="systemname">mycache.mydomain.com</systemitem>,
        connecting to port 3128, with the username
        <systemitem
    class="username">yum-user</systemitem> and the
        password <systemitem>qwerty</systemitem>.
      </para>

<example id="config-file-httpproxy">
        <title>Configuration File Settings for Using A Proxy Server</title>
<screen>
<computeroutput># The proxy server - proxy server:port number
proxy=http://mycache.mydomain.com:3128
# The account details for yum connections
proxy_username=yum-user
proxy_password=qwerty</computeroutput>
</screen>
      </example>

<note>
        <title>Global Settings</title>

<para>
          If you define a proxy server in
          <filename>/etc/yum.conf</filename>, <emphasis>all</emphasis>
          users connect to the proxy server with those details when
          using <command>yum</command>.
        </para>
      </note>
    </section>

<section id="sn-yum-proxy-server-peruser">
      <title>Configuring Proxy Server Access for a Single User</title>

<para>
        To enable proxy access for a specific user, add the lines in the
        example box below to the user's shell profile. For the default
        <command>bash</command> shell, the profile is the file
        <filename>~/.bash_profile</filename>. The settings below enable
        <command>yum</command> to use the proxy server
        <systemitem
    class="systemname">mycache.mydomain.com</systemitem>,
        connecting to port 3128.
      </para>

<example id="profile-script-httpproxy">
        <title>Profile Settings for Using a Proxy Server</title>
<screen>
<computeroutput># The Web proxy server used by this account
http_proxy="http://mycache.mydomain.com:3128"
export http_proxy</computeroutput>
</screen>
      </example>

<para>
        If the proxy server requires a username and password, add these
        to the URL. To include the username
        <systemitem class="username">yum-user</systemitem> and the
        password <systemitem>qwerty</systemitem>, add these settings:
      </para>

<example id="profile-script-httpproxy-withpassword">
        <title>Profile Settings for a Secured Proxy Server</title>
<screen>
<computeroutput># The Web proxy server, with the username and password for this account
http_proxy="http://yum-user:[e-mail]:3128"
export http_proxy</computeroutput>
</screen>
      </example>

<note>
        <title>The <option>http_proxy</option> Environment Variable</title>

<para>
          The <command>http_proxy</command> environment variable is also
          used by <command>curl</command> and other utilities. Although
          <command>yum</command> itself may use
          <command>http_proxy</command> in either upper-case or
          lower-case, <command>curl</command> requires the name of the
          variable to be in lower-case.
        </para>
      </note>
    </section>
  </section>

<!-- SE: This is at the end of the document, since it looks out of place in section 1 -->

<section id="sn-acknowledgements">
    <title>Acknowledgements</title>

<para>
      Paul Frields edited this document. Timothy Murphy reviewed the
      beta release.
    </para>
  </section>

<index id="generated-index"></index>
</article>

<!--
Local variables:
mode: xml
fill-column: 72
End:
-->