# &application; Manual

&application; is a suite of tools for integration with the GNOME desktop.

2008
Richard Hughes (richard@hughsie.com)
Richard Hughes

&legal;

Richard
Hughes
richard@hughsie.com
3.0
2008-03-31

Rahul Sundaram sundaram@fedoraproject.org

Rahul Sundaram

2.0
2007-08-30

Richard Hughes richard@hughsie.com

Richard Hughes

## Feedback

To report a bug or make a suggestion regarding the &app; application or this manual, follow the directions in the &application; Contact Page.

## Introduction

&app; is a suite of tools for the GNOME desktop

PackageKit is designed to unify all the software graphical tools used in different distributions. It abstracts the various underlying package management technologies like yum, apt, smart etc. and provides unified graphical and command line frontends. It also provides a framework that includes programming interfaces that other software applications can take advantage of. It is not a replacement for existing package managers like yum.

Some of the architectural advantages of PackageKit over other package management solutions are that the PackageKit daemon runs as a system process that is not tied to any user session, which means that a long-running update or installation will not be interrupted if the user who started it logs out. Tasks are queued up, meaning that a user can initiate multiple tasks which will be executed one by one and also that multiple users can also use PackageKit in parallel without completely locking each other out. Access to all privileged operations is controlled via PolicyKit.

### PolicyKit Permissions UI

## Applications

packagekitd is started automatically when it is needed. `pkcon` offers a versatile commandline interface to PackageKit.

Below is a list containing the names and a short description of the utilities included in the gnome-packagekit pack:

Command line

  `gpk-application`: Add/Remove Software

Command line

  `gpk-update-viewer`: Updating your system. Also can view the history of updates.

Command line

  `gpk-prefs`: Configuring software updates preferences

Command line

  `gpk-repo`: Enabling or disabling software repositories

Command line

  `gpk-log`: History of updates including installing, removing or updating any software

Command line

  `gpk-install-file`: Installs locally available software packages. This also gets run if you double-click on a package in your desktop or within a file manager.

Command line

  `gpk-update-icon`: When PackageKit is installed, it starts the session icon automatically when you log in. This application displays an icon in the notification area of your panel when software updates are available, and is responsible for showing notifications about PackageKit operations and events.

Command line

  `gpk-backend-status`: Shows technical status of support for the underlying package management backend. Only useful for developers.

## Add/Remove Software

Add/Remove software application accessed via System Administration Add/Remove Software allows you to search the software repository easily or browse through the different groups like multimedia or office and select software packages to install or remove from your system. You can find more information about any package such as description and dependencies by just clicking on it. Before installing a package, you also can visit the home page of the software projects easily for getting any additional details.

### Searching for a group with filters

Typically, you can find several thousands of software packages under different groups available. Since this can be overwhelming you can choose to filter the lists of software packages based on several criteria such as whether the package is already installed, whether it is a development or graphical application and based on the software license. See for more information about filters.

A software source configuration is available in the system menu that allows you to enable or disable a existing software repository. You can also refresh the application lists for displaying the latest information about software packages available in the repository.

### Filters

You can limit the amount of software packages that is shown by several criteria.

To see only installed or only uninstalled software, choose the corresponding menuitem in the Filters Installed menu.

To see only software containing applications with a graphical user interface or only applications with a commandline interface, choose a filter from the Filters Graphical menu.

Note that PackageKit uses a heuristic to determine if a package is a 'graphical' application and can get this wrong when a package has dependencies like gtk2+.

To see only software that qualify as free software, choose the corresponding menu item from the Filters Free menu. Currently, PackageKit considers a package to be free software if its license is listed as such in the Fedora Licensing page.

### Searching for software

The search entry and Find button let you search for software. The icon inside the entry indicates what kind of search is performed. By clicking on it, you can select to search for a string that is contained in package name, the package description, or search for the name of a file contained in the package.

## Software Sources

The software repository viewer allows you to enable or disable software sources - also known as repositories. Repositories are collections of software that are known to work together and are compatible with your operating system. Apart from the repositories for the operating system itself, there are third-party repositories offering additional software for many Linux distributions - check your distribution-specific documentation for more information.

### Software Sources UI

At this time, PackageKit does not offer a way to add new repositories to your system. It only allows you to enable or disable known repositories. However, it is often possible to make a new repository known to PackageKit by installing a package with the necessary information. These are usually called (foo)-release, where foo is the name of the repository.

## File Handler Helper

Sometimes you will not have the software on your system to open a particular file. If the file type is not recognised, then applications that can open this file type are shown.

At this time, only a limited number of results will be shown, as they will need to be rebuilt by the distro to support the extra data needed by PackageKit. This will happen automatically, and soon all suitable applications will be shown.

## Update Viewer

You can update your system via System Administration Update System or by selecting Show Updates from the update icon in the notification area. When you do this, the update viewer application launches and immediately starts checking for updates. Once this check completes, it shows you an overview of available updates, grouped by severity. The severities range from security updates over important updates to bug fix updates and finally enhancements.

Note that the severity information must be provided by the software repositories where the software packages originate. This information may not be available for development branches of distributions.

### Updates overview

Below the summary of available updates, the update viewer gives and indication how long ago the last check (or refresh) for new updates happened, and when updates where last installed.

You can choose to manually refresh and verify the presence of updates by clicking the Refresh button.

You can change how often PackageKit refreshes on its own in the Software Update Preferences.

There is a option to view the history of updates including previous installations, removal or updates of software.

Use the Update System button to install all available updates or use the Review button to review and select individual updates. If you do not want to install updates at this time, you can just close the window.

### Detailed information about updates

The Review button brings up a listing of the individual updates that are available. The area below the list displays detailed information about the selected update. The information may include references to bugs and vulnerability reports that are fixed by the update.

Note that the detailed update information must be provided by the software repositories where the software packages originate. This information may not be available for development branches of distributions.

The checkboxes next to each package in the list allow to select individual updates for installation. Use the Apply Updates button to install only the selected updates. If you do not want to install updates at this time, you can just close the window.

#### Update viewer tool

You can uncheck all the updates quickly by right clicking on the list and selecting the menu item Unselect all.

## Software Updates Preferences

### Preferences tool

Preferences can be configured via System Preferences System Software Updates. You can configure it to check for updates on a daily, hourly or weekly basis or never. Note that these frequencies are only approximate, and checks for updates can be triggered by other events, such as the screen being unlocked, network becoming available, or another user checking for updates. The default setting is to check for updates daily. You can also configure it to automatically install all updates or just the ones that fix security issues. These settings are per-user and effective only for the current user logged in the system.

## Software Log Viewer

### Log viewer

This tool can be opened using Applications System Tools Software Log Viewer.

The log viewer can be used to find out what updates were downloaded and installed. The filter will match on the package name, version or architecture.

It can also can be used to roll back to a specific point for package backends that support `RollBack`.

## Service Pack Creator

### Service pack creator

This tool can be opened using Applications System Tools Service Pack Creator.

A service pack is a tarball which contains a set of packages and their dependencies. To explain better what a service pack is, it is best to show a few use-cases.

You can add multiple packages to a service pack by separating the package names with a comma, for instance `hal,gnome-power-manager`.

1. You have seven desktops you've just installed with Fedora 9. Each one needs to have 204Mb of updates installed.

2. You have a laptop that needs network drivers before it can download updates, and you have a similar up to date laptop with internet access nearby. The network drivers require a few dependencies, and other packages to be upgraded before they will install.

3. You frequently install Linux on other peoples computers. You carry around a live-cd and a pendrive with a single 204Mb file `Fedora-updates-SP1.servicepack` which contains all the updates since last week.

4. A free software magazine wants to distribute patent encumbered multimedia plugins and programs with the latest Fedora release DVD. They want a way in which even the most lazy user can get the things installed without much fuss.

Internally, the pack file is just an uncompressed tarball, with the packages and a single metadata.conf file inside. The metadata file is just the distribution identifier and the time of creation. This ensures you don't try installing a `fedora-9-i386` service pack on a `ubuntu-intrepid-ppc` machine.

We need a destination file list because we not know what packages are installed on the destination computer. For example:

### Two example computers

Computer A has the following packages installed, and has internet access.

- `glib`

- `dbus`

- `dbus-glib`

- `libgnome`

Computer B has the following packages installed, and does not have internet access.

- `glib`

- `dbus`

- `kdebase`

- `kdeapps`

Computer B wants to have a service pack containing a new version of `k3b` so that it can burn DVD-RWs.

The `k3b` program has dependancies of `dbus`, `dbus-glib` and `kdebase`. Now, if we asked computer A to download `k3b`, it would download `k3b` and `kdebase` but not `dbus-glib`. We need to provide computer A with the information about what packages computer B has got installed before we can create the service pack.

If we generate a package list on computer B, and the transfer it to computer A on a USB pendrive or CDRW we can download the correct packages. In this case we would download `k3b` and `dbus-glib` and pack it into the new service pack.

The service pack can now be transferred from computer A to computer B on the USB pendrive.

The `pkgenpack` command line tool can also be used for creating service pack files.

## Automatic Updates

Automatic updates can be performed in the background system wide using the PackageKit-cron package. The settings are controlled via the configuration file at `/etc/sysconfig/packagekit-background`. You can set it to just check for updates or perform the updates automatically and notify any email address.

## Update Icon

The icon offers menu items for installing the available updates or for starting the update viewer, which allows you to obtain detailed information about the available updates before installing them. See for more information.

### Preferences tool

## Agreeing to EULAs

A license agreement is a contract between a producer and a user of software which grants the user a software license. A software license agreement defines the legal terms under which a user may use the software. This is called an end-user license agreement or EULA for short.

Many EULAs assert extensive liability limitations for the software. Typically a EULA will hold the software producer immune in the event that the software causes damage to the computer hardware or data. Some software also includes limitations if the user can be held liable for damage that arises through improper use of the software.

### Example EULA

Be sure to carefully read and accept the EULA text before continuing with the install or update.

## Accepting a security signature

Packages from a software source are typically signed by the project managing the repository or packages. This allows users to be sure a package signed with a security key is actually from the software source it claims to be.

For a package management infrastructure to operate effectively, it has to trust repositories so that updates can be downloaded and installed automatically. The other benefit is that signed packages can be installed without using the administrator password, assuming your admin has enabled this option.

### Example signature prompt

To trust a repository, you should verify the details of the signing key. Normally the best way to do this is to go to the web page of the software source, and try to find details about the key used to sign the packages. This is normally called a `GPG key`.

You should only proceed with this dialog if you are happy to trust packages from this software source.

## Common Dialogs Explained

This application tries to reuse dialogs as much as possible, so that there is a repeatable and consistent user interface when managing packages. In the following subsections, some of the dialogs will be explained further, often with examples or web links.

### Copying Files To Another Location

#### Example dialog

If a file has been downloaded to your home directory, it is usually downloaded to a location similar to `/home/hughsie/Downloads`. The PackageKit service is not run as the same user as the the normal desktop user, and so the daemon would not normally be able to access this file. If the download folder cannot be read by the root user then it is copied to a temporary directory so it can be accessed.

### Installing Local Files

An application has asked to install local files on your system. If you initiated the action, please click the install button.

### Installing Catalogs

A package catalog is a simple file that indicates that other packages should be installed. There are no optional packages, as a catalog file is designed to be simple and need no user interaction. Using a catalog file allows you to install different packages quickly and easily.

To find more information about catalogs, please visit the FAQ.

### No Packages Required

The catalog that you tried to install made no changes to your system as you already have the required packages installed. No further actions are required.

To find more information about catalogs, please visit the FAQ.

### Confirmation Required

#### Example plugin dialog

An application needs your permission before modifying packages on your system. The program name and the icon is from the application asking for permission.

### Finding Other Required Packages

Other packages may depend on this package to operate correctly. This application is searching for other packages that require the package you are trying to remove. No changes are being made, and you will be prompted later if this is required.

### Finding Other Dependent Packages

This package may require resources in other packages to operate correctly. This application is searching for other required packages of the package you are trying to install.

### Removing Other Packages

#### Example dialog when removing rarian

Other packages need to be removed if this package is to be removed. If you remove these packages you may loose functionality in other applications.

If you are unsure you should not remove the package.

### Installing Other Packages

#### Example dialog when installing xfce-utils

Other packages need to be installed if this package is to be installed. If you remove these packages you may loose functionality in other applications. Downloading and installing extra packages will increase the time it takes to install this package.

### Finding Packages

The package database is being searched for your query. This may take some time if new package lists need to be downloaded from the Internet.

### Package Not Found

No packages could be found in any remote software source. This normally means that you do not have any third party repositories enabled or installed. These extra repositories can often be found using search engines or forums.

Only install packages from reputable software sources.

### Progress Window

If we start an action automatically, we typically do it non-interactively. If this task starts doing something using the network, or that will take a long time, then a new dialog will appear. This gives you the opportunity to cancel the task if this is not desired.

### No Privileges

#### PolicyKit Permissions UI

You don't have the necessary privileges to perform this action. This can happen when you fail to authenticate correctly, for instance by entering your password correctly twice in a row. NOTE: you also need to enter the root password on some distributions, not your own password.

If you cannot authenticate, you need to speak to your systems administrator.

### No PackageKit Service Running

The core PackageKit service could not be started. This will only happen when you have a serious system error. You can get more information about the error by running (as the root user): `/usr/sbin/packagekitd --verbose`

### Update System

All the packages that can be updated on your system are now being updated. You can cancel the update if the cancel button is not insensitive.

### Update Packages

Some packages on your system are now being upgraded. You can cancel the update if the cancel button is not insensitive.

### Refreshing Package Lists

Once a week (although this can be changed in the preferences) you will automatically have the latest package lists downloaded. This means that when you search for a package you do not have installed, you will get any new software that was added to a software source.

Once the package lists are downloaded, the installed and available packages will be cached so client tools can auto-complete. When this is completed, any new applications are scanned and added to a client database.

## About

&app; is maintained Richard Hughes richard@hughsie.com and developed along with several others. To find more information about &app;, please visit the &application; web page.

To report a bug or make a suggestion regarding this application or this manual, follow the directions at the &application; Bug Page.

This program is distributed under the terms of the GNU General Public license as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. A copy of this license can be found at this link, or in the file COPYING included with the source code of this program.