DCUT(1)

General Commands Manual

DCUT(1)

NAME¶

dcut - Debian command upload tool for the archive upload queue

SYNOPSIS¶

dcut [-Pds] [-c CONFIGFILE] [-k KEYID] [-m MAINTAINER] [-O COMMANDFILE] [ [--host] HOSTNAME] COMMAND [, COMMAND] ...

dcut [-Pds] [-c CONFIGFILE] [-k KEYID] [-m MAINTAINER] [-O COMMANDFILE] [ [--host] HOSTNAME] -i CHANGESFILE

dcut [-Pds] [-c CONFIGFILE] [ [--host] HOSTNAME] -U COMMANDFILE

dcut -h

dcut -v

DESCRIPTION¶

dcut creates and / or uploads Debian queue commands files for a Debian repository upload queue. It is a companion for dput(1) and uses dput configuration files (see FILES, below).

The normal workflow is:

•: Determine the queue control commands.
•: Compose the batch of commands to upload.
•: Determine the hostname of the queue host.
•: Upload the commands to the queue host.

Determine queue control commands¶

In the default command-line syntax, parse each command-line argument COMMAND, in the format needed by a Debian archive queue manager. Multiple queue commands must be separated by a comma (,) as a separate word between each command.

See COMMANDS below for valid queue commands.

When the CHANGESFILE parameter is specified, instead parse that file and compose a rm command for each file specified in CHANGESFILE.

If the --upload (-U) option is specified, instead read the queue control commands from the file COMMANDFILE.

Compose the batch of commands¶

The Uploader field in the batch is set to the package maintainer specification MAINTAINER. If not specified, the value of MAINTAINER is derived from environment variables (see ENVIRONMENT, below).

The Commands field in the batch is set to the sequence of queue control commands determined.

If the --output (-O) option is specified, write the batch to the file named by its COMMANDFILE argument. Otherwise, write the batch to a temporary file and remove it after upload.

After writing the batch of commands to a file, sign the file with debsign(1). The MAINTAINER and KEYID parameters, if specified, are passed to the debsign command.

If the --upload (-U) option is specified, do not compose the batch of commands; instead use the content of its COMMANDFILE argument as the name of the command file to upload to the queue host.

Determine the queue host¶

The HOSTNAME must match one of the named hosts in the configuration (see dput.cf(5)). The value is determined as follows:

•: If the --host option is specified, use that option's HOSTNAME argument.
•: If the first non-option argument is not a valid queue command, that is interpreted as the HOSTNAME.
•: Otherwise, HOSTNAME defaults to the value of the default_host_main configuration parameter.

Upload queue commands¶

Upload the composed batch of queue commands to the queue host HOSTNAME, using the parameters in the dput.cf(5) configuration for that host.

If the --output (-O) option is specified, do not upload the commands to the queue host. Instead, leave the composed file COMMANDFILE on the filesystem.

COMMANDS¶

The authoritative documentation for the queue commands interface can be found at https://salsa.debian.org/ftp-team/dak/-/raw/master/tools/debianqueued-0.9/Queue.README. Please refer to that document for explanation of queues (NEW, DELAYED, DEFERRED, etc.), and detailed discussion of queue commands.

With the understanding of the explanations in that document, use dcut to send a combination of these supported commands:

cancel CHANGESFILE_NAME: Cancel an upload from DEFERRED, removing it entirely from the queue.
reschedule CHANGESFILE_NAME DAYS-day: Move an upload from any DEFERRED queue to DAYS-day (use 0-day for immediate processing).

Both reschedule and cancel use the CHANGESFILE_NAME argument as the base filename of a changes file in the queue.

rm: Remove files from the UploadQueue directories. dcut generates commands that search the subdirectories automatically, but you can also specify --nosearchdirs and then target individual UploadQueue directories, i.e. either filenames without path for regular incoming or DELAYED/DAYS-day/filename. Wildcards are accepted.

OPTIONS¶

-c CONFIGFILE
--config CONFIGFILE: Use the file CONFIGFILE for configuration. See dput.cf(5) for the specification of this file format.
-d
--debug: Display debugging messages.
-h
--help: Display help information, then exit.
--host HOSTNAME: Specify the HOSTNAME unambiguously. This allows naming a host that may be ambiguous with a queue command.
-m MAINTAINER
--maintaineraddress MAINTAINER: Use MAINTAINER for the Uploader field and OpenPGP key selection. This has no effect when --upload is used.
-k KEYID
--keyid KEYID: Specify the OpenPGP key id KEYID to pass to the debsign(1) command. This has no effect when --upload is used.
-O COMMANDFILE
--output COMMANDFILE: Write commands file to COMMANDFILE instead of uploading. You should not specify a HOSTNAME when using this option. Also, this option should not be used with --upload.
-P
--passive: Use passive mode for FTP. If not specified, default for FTP is active mode.
-s
--simulate: Do not actually upload to the queue host.
-U COMMANDFILE
--upload COMMANDFILE: Instead of composing a new queue command file, upload the existing file COMMANDFILE. Note: No checks (syntax or presence/validity of signature) are currently performed.
-i CHANGESFILE
--input CHANGESFILE: Do not parse queue commands from the command line. Instead, read the package changes file CHANGESFILE and compose a rm command for each file specified in CHANGESFILE. This has no effect when --upload is used.
-v
--version: Display version information, then exit.

ENVIRONMENT¶

DEBEMAIL
EMAIL: If MAINTAINER is not specified, use the first of these which has a value to determine the email address portion of MAINTAINER.
DEBFULLNAME: If MAINTAINER is not specified, use this value to determine the full name portion of MAINTAINER.
USER: If no username is specified for authenticating to the remote host, use the value of this variable.

FILES¶

Configuration: See dput.cf(5) for the files to configure dcut.

EXAMPLES¶

To upload a GPG signed commands file that removes dput_1.2.3_all.deb file from the queue:

$ dcut rm dput_1.2.3_all.deb

This creates and uploads a commands file that looks like the following:

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512
Uploader: Foo Bar <foo@bar.org>
Commands:


 rm dput_1.2.3_all.deb
-----BEGIN PGP SIGNATURE-----
iQIzBAEBCgAdFiEEYVng8p4vpBLgeVxz+bRqrIRCDIIFAmdssocACgkQ+bRqrIRC
[…]
7ou1IjMZrvZ9gD3b4DMIKIzy2qWoCcOi+Ki5HQUbr52kJnVQGe4=
=7c4m

To upload a GPG signed commands file that removes files named in dput_1.2.3_amd64.changes from the queue:

$ dcut --input dput_1.2.3_amd64.changes