rpm-guide rpm-guide-transactions-en.xml,NONE,1.1
Stuart Ellis (elliss)
fedora-docs-commits at redhat.com
Tue Oct 4 02:05:10 UTC 2005
Author: elliss
Update of /cvs/docs/rpm-guide
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv2488
Added Files:
rpm-guide-transactions-en.xml
Log Message:
--- NEW FILE rpm-guide-transactions-en.xml ---
<!-- $Id: -->
<chapter id="ch-transactions">
<title>Transactions</title>
<para>
In This Chapter
</para>
<para>
*Understanding transactions
</para>
<para>
*Querying for packages based on transactions
</para>
<para>
*Rolling back transactions
</para>
<para>
*Saving old packages when upgrading
</para>
<para>
When packages depend on other packages, you may have to install
multiple packages to add a single application. Some of the packages
may install cleanly; others may not. But you have to install all of
the packages to get the complete application. The designers of the
RPM system understood this problem and added the concept of
transactions to RPM.
</para>
<para>
This chapter covers transactions and how they can help you cleanly
install a set of dependent packages. But transactions won’t solve
all your problems. You still have to resolve conflicts and
dependencies by using the techniques provided in the last three
chapters.
</para>
<sect1>
<title>Understanding Transactions</title>
<para>
A transaction is a way to delimit a set of operations. All the
operations can be undone, often called rolled back. Once rolled
back, the system is back in the same state it was prior to the
transaction. If all the operations succeed, though, the system
will be in a new state. The key issue is that all of the
operations must complete successfully, or you can roll back the
entire transaction. The assumption is that if any of the
operations fail, the system will be in an inconsistent or
erroneous state. Transactions are a way to prevent that.
</para>
<para>
Transactions are common when working with databases, but they are
just as important when working with packages.
</para>
<para>
Starting with RPM version 4.0.4, transactions and rollbacks became
a workable part of any administrator's toolkit. With RPM, the rpm
command sets up a transaction any time you attempt to install,
remove, or upgrade more than one package. The rpm command
automatically makes a transaction.
</para>
<sect2>
<title>When do you need transactions?</title>
<para>
Whenever you install or remove packages, the RPM system assigns
a transaction and a transaction ID to the set of packages. You
can then perform operations on the packages that share the same
ID, including rolling back the transaction.
</para>
<para>
Note
</para>
<para>
Rollbacks work only for package upgrades with the 4.1 version of
the RPM system, not package installs
</para>
<para>
The RPM system saves an image of the RPM package header for each
package installed or removed. You can use this image, along with
RPM transaction IDs, to back out of transactions should
something go wrong when setting up your system.
</para>
<para>
The main advantage of transactions with RPM, though, is the fact
that the rpm command automatically sets up a transaction for all
the packages on each command line and does not perform the
operation if any package fails. This ability to automatically
set up transactions for each call to the rpm command eliminates
many errors when working with packages.
</para>
<para>
Use a transaction when you need to be sure that a set of
packages install properly.
</para>
</sect2>
<sect2>
<title>Backing out of transactions</title>
<para>
With RPM, backing out of a transaction involves two operations:
rolling back the transaction and reinstalling the former
packages to restore the previous system state. In the simplest
case, the rpm command handles all the tasks for you. If you try
to install, upgrade, or remove multiple packages and any package
fails, the rpm command will restore the system state for you.
</para>
<para>
This automatic support for transactions is a great help to
system administrators, but it only applies when you first
install, upgrade, or remove the packages. If you have upgraded
your system and later discover problems, then you can also use
the --rollback option to roll the system back from a set of
upgrades, in a limited set of circumstances.
</para>
</sect2>
</sect1>
<sect1>
<title>Transactions with the rpm Command</title>
<para>
To set up an RPM transaction, you don't have to do much. All you
need to do is pass more than one RPM package on the rpm command
line. For example, to set up a transaction for installing three
packages, use a command like the following:
</para>
<para>
rpm -ihv package1.rpm package2.rpm package3.rpm
</para>
<para>
If any of the packages fail to install, the rpm command will not
install any packages. All of the packages will be installed, or
none.
</para>
<para>
This way, if you have a number of packages that together perform
some function, such as an Integrated Development Environment
(IDE), along with program-language compilers and other
software-development tools, you can ensure that all get installed.
</para>
<para>
As an example, say you need to install the gnorpm package, which
provides a graphical front end for the rpm command, and the
rpmrebuild package, which allows you to create RPMs from
already-installed packages.
</para>
<para>
Cross Reference
</para>
<para>
The gnorpm command is covered in Chapter 8. The rpmrebuild package
is covered in the "Saving Old Packages" section in this chapter.
</para>
<para>
You can install these packages with a transaction by using the
following command:
</para>
<para>
# rpm -ihv gnorpm-0.9-1.i386.rpm rpmrebuild-1.0-0.noarch.rpm
</para>
<para>
Preparing... ########################################### [100%]
</para>
<para>
package gnorpm-0.9-1 is already installed
</para>
<para>
The rpmrebuild package can be installed. (We know this since the
rpm command did not issue an error about this package.) But
because it was on the same command line as the gnorpm package, the
transaction failed. No packages were installed.
</para>
<para>
To check that the rpmrebuild package was not installed (that is,
to check that the transaction worked as expected), you can use the
rpm –q command to see if the rpmrebuild package was installed or
not. To do so, use a command like the following:
</para>
<para>
# rpm -q rpmrebuild
</para>
<para>
package rpmrebuild is not installed
</para>
<para>
This shows that the rpmrebuild package was not installed, even
though the package could be installed on its own. To check that
the package could be installed, you can use the --test option, as
shown following:
</para>
<para>
# rpm -i --test rpmrebuild-1.0-0.noarch.rpm
</para>
<para>
#
</para>
<para>
This command shows that the rpmrebuild package would install
successfully on its own. If there were problems, the rpm command
would have issued an error message.
</para>
<para>
This example shows that when you try to install multiple packages
with the rpm command, should any fail, the rpm command will not
install any.
</para>
<para>
The rpm command works similarly for removing packages and
upgrading packages. When removing packages, you’ll see an error
like the following if any of the packages on the command line
cannot be removed:
</para>
<para>
# rpm -e setup jikes-1.17
</para>
<para>
error: Failed dependencies:
</para>
<para>
setup is needed by (installed) basesystem-8.0-1
</para>
<para>
setup >= 2.0.3 is needed by (installed) initscripts-6.95-1
</para>
<para>
setup >= 2.5.4-1 is needed by (installed) filesystem-2.1.6-5
</para>
<para>
setup is needed by (installed) xinetd-2.3.7-2
</para>
<para>
setup is needed by (installed) dump-0.4b28-4
</para>
<para>
The setup package could not be removed because it had several
capabilities needed by other packages. You can check that the
jikes package was not removed by using the rpm –q command, even
though it had no failed dependencies:
</para>
<para>
# rpm -q jikes
</para>
<para>
jikes-1.17-1
</para>
<para>
This package was not removed because it appeared as part of the
same command that failed, so none of the operations were
performed.
</para>
<para>
When upgrading, you will also see an error message if any of the
package upgrades fail. For example:
</para>
<para>
# rpm -Uhv jikes-1.14-1.i386.rpm autoupdate-3.1.5-1.noarch.rpm
</para>
<para>
error: jikes-1.14-1.i386.rpm cannot be installed
</para>
<para>
You can then check that the jikes package, in this example, was
not downgraded to the earlier version with the rpm –q command:
</para>
<para>
# rpm -q jikes
</para>
<para>
jikes-1.17-1
</para>
<sect2>
<title>Transaction IDs</title>
<para>
The rpm command gives every package installed a transaction ID.
The transaction ID is a Unix time stamp (number of seconds since
January 1, 1970). You can then perform some operations on
packages based on the transaction ID.
</para>
<para>
Note
</para>
<para>
The fact that a transaction ID uses a Unix timestamp may change
in the future.
</para>
<para>
All the packages installed at the same time are given the same
transaction ID. This means that you can perform operations on a
set of packages, the packages that were installed together.
</para>
<para>
But there’s also a downside to this. All the packages
installed when you first installed or upgraded your Linux system
are given the same transaction ID. This means you cannot
selectively act on these packages using the transaction ID,
because you will likely get far more packages than you want to
work on.
</para>
<sect3>
<title>Viewing RPM Transaction IDs</title>
<para>
To view the install transaction ID (a date code) for a given
package, you can use a command like the following:
</para>
<para>
$ rpm -q --qf "%-20{NAME} %-20{INSTALLTID}\n" jikes
</para>
<para>
jikes 1035589778
</para>
<para>
This command uses the --qf or --queryformat option to specify
the data to return from the RPM query command. In this case,
the command requests the name of the package as well as the
transaction ID (TID) for installation.
</para>
<para>
Cross Reference
</para>
<para>
Chapter 5 describes the --queryformat option.
</para>
<para>
There is also a transaction ID for removal, the REMOVETID. You
can also query for this ID. For example, if a package hasn't
been removed, you'll see an entry like the following:
</para>
<para>
$ rpm -qa --qf "%-20{NAME} %-20{REMOVETID}\n" termcap
</para>
<para>
termcap (none)
</para>
</sect3>
<sect3>
<title>Viewing the Packages Associated with a Transaction ID</title>
<para>
Once you have a transaction ID, you can use the --tid option,
short for transaction ID, to query for the package associated
with a given transaction, using a command like the following:
</para>
<para>
$ rpm -q --tid 1035589778
</para>
<para>
jikes-1.17-1
</para>
<para>
This example uses the transaction ID that the earlier query
example returned. If you installed more than one package at
the same time, you will see a listing of all the packages that
share the transaction ID.
</para>
<para>
For example, to see many packages with one transaction ID, you
can query for packages installed when you installed or
upgraded your version of Linux. First, query for the
transaction ID of a package you know was installed with the
Linux distribution, such as setup on a Red Hat system:
</para>
<para>
$ rpm -q --qf "%-20{NAME} %-20{INSTALLTID}\n" setup
</para>
<para>
setup 1033838323
</para>
<para>
Second, use this transaction ID and query for all packages
with this ID, using code like the following:
</para>
<para>
$ rpm -q --tid 1033838323 | more
</para>
<para>
redhat-menus-0.26-1
</para>
<para>
glibc-2.2.93-5
</para>
<para>
cracklib-2.7-18
</para>
<para>
gdbm-1.8.0-18
</para>
<para>
gmp-4.1-4
</para>
<para>
libacl-2.0.11-2
</para>
<para>
libjpeg-6b-21
</para>
<para>
linc-0.5.2-2
</para>
<para>
pcre-3.9-5
</para>
<para>
shadow-utils-20000902-12
</para>
<para>
libtermcap-2.0.8-31
</para>
<para>
freetype-2.1.2-7
</para>
<para>
info-4.2-5
</para>
<para>
fileutils-4.1.9-11
</para>
<para>
psmisc-20.2-6
</para>
<para>
ntp-4.1.1a-9
</para>
<para>
mount-2.11r-10
</para>
<para>
cracklib-dicts-2.7-18
</para>
<para>
krb5-libs-1.2.5-6
</para>
<para>
cyrus-sasl-2.1.7-2
</para>
<para>
usermode-1.63-1
</para>
<para>
Xft-2.0-1
</para>
<para>
Note
</para>
<para>
Be sure to replace the transaction ID shown here with the
transaction ID obtained by querying your system.
</para>
<para>
This example shows just a few of the packages installed when
the Red Hat Linux was installed.
</para>
<para>
With these options, you can find the transaction IDs for given
packages and can use the rpm command to install, remove, or
otherwise modify the packages that share a transaction ID.
</para>
</sect3>
</sect2>
<sect2>
<title>Rolling Back Transactions</title>
<para>
The --rollback option to the rpm command allows you to roll back
upgrades based on a time. Use a command like the following:
</para>
<para>
# rpm –U --rollback "3 months ago"
</para>
<para/>
<para>
The --rollback option is very limited in what it can do. The
--rollback option works only for packages that have been
upgraded. You cannot rollback the initial installation of a
package. This is to prevent you from accidentally rolling back
all packages.
</para>
<para>
The --rollback option works best if you want to restore the
system to a previous state, prior to performing any other RPM
operations. That is, soon after you upgraded a package and
decide that it isn’t working right. If you have modified the
RPM system after performing the transaction you want to
rollback, there may be unintended consequences if any new
package depends on the packages you want to roll back. In
addition, the --rollback option only works in limited situations
but does not always report when these conditions are not met.
The rpm command may simply do nothing, or it may remove packages
you do not expect.
</para>
<para>
Warning
</para>
<para>
Before running the --rollback option, backup your RPM database
as described in Chapter 5.
</para>
<para>
Because of all these limitations, rollbacks do not work in all
situations. In place of the --rollback option, you can use the
query shortcuts introduced in Chapter 5 and find the packages
you have installed recently (if that is what you want to roll
back). In this case, you can use the rpm command to remove the
packages you want to get rid of and reinstall the packages you
want to restore.
</para>
<para>
In many cases, this manual approach is safest, and you will have
a clearer understanding about what was installed or upgraded on
your system.
</para>
</sect2>
</sect1>
<sect1>
<title>Saving Old Packages</title>
<para>
When installing, removing, or upgrading, you can use the
--repackage command-line option to save a version of something
like the old package to a file, making a backup of the older
package contents.
</para>
<para>
Warning
</para>
<para>
The package created by the --repackage option is not a complete
RPM package. You can use the rpmbuild command to make it into a
complete package, but by itself, it will not be a complete
package. See Chapters 10, 11, and 12 for more on building
packages.
</para>
<para/>
<para>
You can later reinstall the old files, once they have been made
into a complete package. This can be quite useful if something
goes wrong or the upgraded package has bugs. You can fall back to
the old package if needed.
</para>
<para>
By default, the --repackage option puts the old package in the
/var/spool/repackage directory. Other common directories are
/var/spool/up2date or /var/tmp. Your RPM configuration determines
the directory used by this option.
</para>
<para>
Note
</para>
<para>
The up2date name comes from the Red Hat service for keeping a
system up to date with regard to package versions.
</para>
<para>
For example, say you have a package, jikes (a Java programming
language compiler used in previous examples) that you want to
upgrade. But you are worried that the new version may not work
properly.
</para>
<para>
First, check the version you have. For example:
</para>
<para>
# rpm -q jikes
</para>
<para>
jikes-1.14-1
</para>
<para>
This shows you are at version 1.14 of the jikes Java compiler. You
can then upgrade to version 1.17 while repackaging the old
version, as shown following:
</para>
<para>
# rpm -Uhv --repackage jikes-1.17-glibc2.2-1.i386.rpm
</para>
<para>
Preparing... ########################################### [100%]
</para>
<para>
Repackaging...
</para>
<para>
1:jikes ########################################### [100%]
</para>
<para>
Upgrading...
</para>
<para>
1:jikes ########################################### [100%]
</para>
<para>
This upgrade has kept a copy of the old package in the
/var/spool/repackage directory. You can verify this with the
following command:
</para>
<para>
$ ls -l /var/spool/repackage/
</para>
<para>
total 692
</para>
<para>
-rw-r--r-- 1 root root 703037 Oct 25 18:49 jikes-1.14-1.i386.rpm
</para>
<para>
You can see a version of the old package, with the old version
number.
</para>
<para>
Warning
</para>
<para>
This is not the same as the original package. This is not a
complete package.
</para>
<para>
The repackaged RPM contains a snapshot of the package’s files as
they were on your hard disk, not as they were when you originally
installed the package. Thus, the contents may differ if the files
have changed on your hard disk. In addition, the --repackage
option may not properly sign the package as the original was.
</para>
<para>
In addition to the --repackage option with the rpm command, you
can use a free tool called rpmrebuild to make snapshots of any
installed packages.
</para>
<para>
Written by Eric Gerbier, rpmrebuild allows you to create an RPM
from the installed, and perhaps modified, version of a package.
You don’t have to upgrade, remove, or install a new package, as
you do with the --repackage option.
</para>
<para>
Download rpmrebuild from http://rpmrebuild.sourceforge.net/.
</para>
</sect1>
<sect1>
<title>Summary</title>
<para>
Transactions allow you to install multiple packages as a group and
know that either all the packages will succeed in installing or
none of them will. This is very important if you have a set of
interlocking packages that you need to install.
</para>
<para>
All the packages you install, remove, or upgrade on the same
command line are automatically made part of a transaction. The rpm
command will ensure that all packages can be installed, removed,
or upgraded, and will not perform the operation unless all will
succeed.
</para>
<para>
All packages installed or removed are given a transaction ID,
which uses a Unix timestamp (the number of seconds since January
1, 1970). All packages installed or removed at the same time are
given the same transaction ID. You can then query by transaction
IDs to perform operations on all the packages installed together.
</para>
<para>
The --repackage option tells the rpm command to make a backup RPM
of the current package when you are installing or upgrading a more
recent version or removing the package. By default, the backup RPM
is placed in the /var/spool/repackage directory. Note that a
package created this way is not exactly the same as the original
package. Files may have changed on disk. In addition, packages
created with the --repackage option are not real valid RPM
packages. You cannot install these packages without performing
extra operations to create a real RPM package from the repackaged
data.
</para>
<para/>
</sect1>
</chapter>
<!--
Local variables:
mode: xml
sgml-parent-document:("rpm-guide-en.xml" "book" "chapter")
fill-column: 72
End:
-->
More information about the Fedora-docs-commits
mailing list