dftp(8)

NAME

dftp - FTP Debian packages maintainer

SYNOPSIS

dftp action [--option [param]...]

DESCRIPTION

The purpose of this program is to make it easy to keep your local installation of Linux consistent with the Debian distribution available on many FTP sites, NFS mounts, or CD-ROM. It does this by comparing the list of installed packages with those available by FTP or at a specified directory. A list of packages, categorized to make selection easier, is then presented to the user to choose what to install. All selected packages are then fetched if necessary (using FTP), verified for correctness, and then installed.

If your Debian machine does not have FTP access, run dftp scaninst and copy the generated .installed file onto whatever (FTP ready) machine you plan to run this script from in the future. This file is needed to do intelligent package selection.

dftp supports two modes for selecting the packages for installation. The first (and older mode) brings up a list of all the available packages in your favorite editor and allows you to comment or uncomment the packages (their file lines) that you want installed. This mode remembers the packages that you didn't select for installation on the previous run and uses that information during the next run when it sorts the packages into the following categories:

NEW UPGRADES

available upgrade packages (where this upgrade (version) hasn't been refused before).

DOWNGRADES

available packages which represent version downgrades.

NEW PACKAGES

packages that have been added to the distribution since the last time you ran dftp getlist.

IGNORED UPGRADES

available package upgrades that were previously refused. Also called unwanted packages.

IGNORED PACKAGES

available packages that are you have previously chosen not to install.

The other selection mode is the interactive mode. It was created to speed the process of selection by providing sensible defaults, a (mostly) single key response interface, and (hopefully) a little more sophistication in remebering what you want. This mode is activiated with the --ask option when performing a dftp select. --ask allows you to specify which types of packages you want to be asked about. These types are similar to the ones for the editor selection mode, but there are some subtle and important differences. The types are:

new:

available packages that are not installed on this system, and which dftp hasn't seen before and hasn't been explicitly told to ignore before (i.e., packages that aren't unwanted or ignored).

upgrades:

available upgrade packages that dftp hasn't been explicitly told to ignore in a previous --ask session (i.e., packages that aren't unwanted or ignored).

unwanted:

available packages that are not installed on this system, and which dftp has been told not to install in a previous session ('no' answer). If you install an unwanted package between dftp runs, dftp will notice and move that package out of the unwanted state. dftp will also see when a previously known package disappears from the target system (isn't installed anymore), and makes it unwanted automatically.

ignored:

available packages that dftp has been explicitly told to ignore in a previous session. Ignoring a package is stronger than making it unwanted, such packages aren't automatically reconsidered if you install them manually. They're completely ignored by dftp until you explicitly move them out of the ignored state.

The default values if --ask is specified without an argument are --ask new and --ask upgrades. Specifying any value to --ask clears the defaults, so dftp select --ask new will only ask about new packages.

You can re-run select multiple times before you run getselect, and dftp will remember which packages you told it to ignore in the previous run.

Once the selection process starts running, you will be prompted for actions on each package of the types you have specified. The prompts should be self-explanatory, but the primary actions will be "yes" meaning install this package, "no" meaning don't install this package, and move it to the unwanted category, and "ignore" meaning don't install this package, and move it into the ignored category. (Exception: If you're asked what to do with a previously ignored package, both "no" and "ignore" leave the package in ignored state.) You can also choose to remove a package later during the installation stage. This may be conventient if an upgrade reminds you of an old, forgotten package that you don't want anymore. The --ask selection mode has been set up to have prompt defaults that allow you to just hit return most of the time.

After the package selection, dftp will check dependencies of packages. The first check is whether to-be-removed packages would leave any dependencies on the target system unsatisfied. If such cases are detected, you can choose either to "add" the to-be-removed package again (i.e., not to remove it), to "remove" the depending package also, or to skip the dependency failure alltogether. In latter case, expect error messages from dpkg later.

Next, all dependencies, conflicts, recommendations and suggestions of to-be-installed packages are checked. Recommendations and suggestions are optional, where the first are on by default, the latter of. You can change these defaults with the options --noask-recommends and --ask-suggests, resp. In case of an unsatisfied dependency, you have the following options: "add" the depended-on package, too, "omit" the depending package, or "force" the installation with the --force-depends option to dpkg. You can also answer "no" to ignore that dependency alltogether, but expect an dpkg error if it's not only a recommendation or suggestion. In case of a conflict between packages, the "add" option is replaced by "remove", which will remove the second of the conflicting packages. For special cases of conflicts that apply only to specific versions, also the "update" option can help. It will select the conflicting package for upgrade (if possible), which maybe can remove the conflict.

dftp can run on any un*x system (Linux or not) with proper access. The retrieved packages can then be archived and moved to the Debian system on which they are to be installed. Once moved to a Debian system and de-archived into a directory (usually ~/packages), everything can be unpacked with the unpack action and then configured:

cd ~/packages
tar xvf debian-archive.tar
dftp unpack

Since root priviledges are required for unpacking and configuring the packages, dftp will take special actions if not already called as root for the "unpack" action. It will use the command specified with the --root-cmd option to get root priviledges. Default is sudo. Alternatively, you could use the dselect utility with ~/packages as the source for new packages. The downloaded files can then be marked as installed and removed with:

dftp installed clean

The "installed" action will do the same as "scaninst", and additionally remember the currently available packages as "previously available", so that the intelligent package selection mechanisms can work right. The "clean" target removes several internal files of dftp and all packages that are fully installed. You have to call the "installed" or "scaninst" actions in advance to make the function correctly. It will also remove empty directories in the packages tree.

If you are running dftp on the target Debian system, all of these actions are done automatically as part of getnew.

If you change the machine you are running this script on, the only file you need to copy is .installed. This is the file that keeps a record of all the packages retrieved from the FTP site. If a .installed file is not available because the Debian system has not yet been set up, just create an empty file by typing

touch ~/packages/.installed

Of lesser importance is the file .prev-avail which contains the list of packages from the last time packages were installed. If this file is missing, all packages are assumed to be new. Any other files are wholly generated by the various actions and can be deleted/ignored. The interactive --ask selection mode depends on the two files .unwanted and .ignored in addition to .prev-avail.

If you want to run dftp on a non-Debian machine, you need to install the script itself there, and the .pm files that make up the pkg-order library, which is used by dftp. (And, of course, you need Perl 5 on that machine.) For such non-Debian installations, there is an archive dftp-version-standalone.tar.gz in project/misc on your Debian mirror. This tar file contains all necessary files for an installation, and instructions in a README file.

Once you have decided upon the configuration (command-line options) under which you wish to run this script, you would be wise to write these options into the /etc/dftp.conf or ~/.dftprc file in your home directory like this:

#
# These are my defaults for running dftp
#
tardesc
include: dists/unstable/main,dists/unstable/contrib,dists/unstable/non-free
exclude: tex,hamradio,news,electronics
email: [email protected]
ftpgate: EagleGate
ftpsite: sunsite.unc.edu
ftpdir: /pub/Linux/distributions/debian
arch: i386
ask: upgrades,new

This will ensure you do not forget an option sometime in the future and get unpredictable results.

Any files retrieved via dftp can be used as the basis of another dftp simply by pointing --pkgpath to the directory in which all the retrieved file are stored (usually $HOME/packages.

This script supports external FTP access through an Eagle Secure Gateway. To use this, simply provide the name of the gateway to the --ftpgate option or in the .dftprc file. When FTP runs, you will be prompted to enter your account password. --ftpgate should also work for many kinds of FTP proxies.

If errors should occur during the FTP stage, it will be caught by the verify action. getselect automatically skips any files that already exist locally, thus allowing an FTP session to be restarted without retrieving files previously downloaded. A transcript of the latest FTP session is available in .ftplog.

ACTIONS

scaninst

Build list of installed packages (Debian only)

getlist

Retrieve a list of Debian packages from an FTP site

install=package list

Install the packages in package list, additionally to those selected interactively if the select command is also given. The items of package list can be separated by commas and/or whitespace. (But it must be one parameter, i.e. surround it with quotes in the shell if you use spaces.) The packages are moved out of the unwanted or ignored state if there were in one of those states. If they're already installed, they're updated if necessary. This command is convenient if you want to install some previously unwanted or ignored package, and don't want to step through the big lists interactively.

select

Bring up an editor to select which packages to download, or enter an interactive selection mode (see --ask). (All packages are compared against the list of installed packages and only those newer or not installed will be listed for selection under select.) --ask has some more sophisticated behaviors, see above. After the selection, dependencies of packages will be checked.

getselect

Retrieve all selected packages from an FTP site

verify

Make sure FTP got all the files correctly

unpack

Call dpkg to unpack and install all the retrieved packages

archive

Tar all retrieved packages for moving to another machine

installed

Mark all successfully installed packages as installed.

clean

Remove all retrieved and installed packages as well as any archive and temporary package-info files.

getnew

Do scaninst through installed in the listed order

Multiple actions can be given, but it is generally unwise to skip any of the steps except for archive, or to wait too long between steps as changes in the distribution could force you to restart with getlist.

All actions happen in the order listed regardless of how they appear on the command line.

OPTIONS

--nodesc

Do not provide descriptions of packages in the selection list (editor-based selection only)

--tardesc

Include the package description files in the packages archive

--quiet

Print as little as possible during execution

--verbose

Print extra information during execution

--whatsnew

Print information about what is new in the current version

--help

Display general usage information

--password-prompt

dftp will ask you for your ftp password instead of making you keep it in a file.

--prefix pathname

Directory where all packages will be held

--include dir[,dir]

Comma-separated list of directories to scan

Parts of a directory can be enclosed in square brackets to fix Packages files with filenames not relative to the toplevel of the FTP archive. The part inside the brackets will be added to all paths in Filename: fields. This is currently often necessary for the nonUS archive, because that is usually mirrored to a subdirectory, and the Filename: fields are relative to that subdir instead of to the top. In that case, enclose the subdirs name into square brackets.

It is now allowed to list directories that refer to different distributions, for example:

include: dists/unstable/main,dists/frozen/main,dists/stable/main

(You can do the same for contrib, non-free, and non-US, too, of course; those are just omitted here for brevity.) If a package appears multiple times in the downloaded Packages files, dftp will pick the newest available version. (If the same version appears more than once, the first occurrence will be used, but this should make no difference.) This can be handy shortly after a release, when unstable usually isn't fully symlinked to the new stable. It also allows you to install packages that have been removed already in unstable, but are still available in, e.g., stable.

--exclude sec[,sec]

Comma-separated list of sections not to check

--pkgpath sitename

Local pathname where Debian packages can be found. If a --pkgpath is specified, it will take precedence over an FTP site.

--ftpsite sitename

Site from which to get Debian distribution packages

--ftpuser username

Optional username for login.

--ftpdir pathname

Path name to Debian distribution on FTP site

--ftpgate machine

Machine name of Eagle secure gateway to use (empty string means no gateway)

--email emailaddr

Your email address, used for anonymous password or a real password, used for --ftpuser login

--arch machine

The architecture of binary files to be retrieved

--tarfile pathname

Tar file in which to archive retrieved packages

--ask type

Used with the select action to enable interactive package selection. May be specified multiple times to select multiple types of packages to be asked about. (legal types: all, new, upgrades, ignored, and unwanted; default is upgrades and new)

--root-cmd cmd

The given cmd is used to get root priviledges for installing (`dpkg --install'), if dftp is run by a non-root user. All other operation don't need root priviledges. If dftp is run by root, the cmd is ignored. The default is sudo. The cmd must accept the command to be issue without any other special options. sudo and super are ok, but su is not, since it requires a -c option.

--preinst-cmd cmd

The cmd is executed before installing with dpkg. It can be used, for example, to remount /usr read-write if it is usually mounted read-only.

--postinst-cmd cmd

The reverse action to --preinst-cmd. It is executed after installation with dpkg is finished.

--correct-version-compare

dftp uses by default an internal function to do comparisons of package versions. This is much faster than calling dpkg for each single comparison. However, this method is not politically correct since dpkg is the only instance that really defines the order of versions. If there should be some change to the definition of ordering (like the introduction of epochs some time ago) that dftp doesn't understand (yet), you can force dftp to use dpkg for version comparison with this option. Of course, dpkg can be used only on Debian systems. On non-Debian machines, always the internal function is used.