dput(5)
NAME
dput - configuration file format for dput-ng
DESCRIPTION
dput supports two configuration file formats. The old-style configuration format was originally introduced by dput and is described in dput.cf(5). This manpage describes new-style configuration files only. All details are covered in in </usr/share/doc/dput-ng/html/reference/configs.html> which is available in the dput-ng-doc package.
FILES AND FORMAT
Upload targets are configured using JSON as described in RFC 4627. In a
nutshell, dput configuration allows insignificant whitespace before or
after any type statement. Each upload profile is stored in its own file
and is represented as a pair of curly brackets surrounding name/value
pairs described below. Both, name and values are strings. A single
colon separates the name from the value. A string begins and ends with
quotation marks and may be escaped. Booleans are either true or false
(mind these are not surrounded by quotation marks).
Some keys names are accepting lists as possible value. A list is
represented as square brackets surrounding zero or more values,
separated by commas.
dput reads, in order, these directories:
1. /usr/share/dput-ng/
2. /etc/dput.d/
3. ~/.dput.d/
4. The directory supplied via command line argument
Moreover, old-style configuration files are parsed and read. See
READING TRADITIONAL CONFIGURATION FILES below. In general, packages are
installing pre-defined defaults for popular upload targets to
/usr/share/dput-ng/profiles/. System administrators who wish to
override or create a new system-wide and shared target for many users
may choose /etc/dput.d/profiles. Finally, local targets may be written
to ~/.dput.d/profiles for personal upload targets.
Within each configuration directory, there may be another tier of
configuration directories. There, these actual configuration
directories may exist:
* metas/ define super-classes of upload profiles. They can define any
name and value known to profiles (see below) which are shared
across profiles.
* profiles/ define upload profiles. Files therein are looked-up by
their name as HOST argument by dput. This is, where upload hosts
are defined.
Moreover, these directories can exist and are documented here for the
sake of completeness. However, users typically do not need to touch
these unless you are developing or customizing existing plug-ins to
dput or dcut
* hooks/ define entry hooks to checker functions which are registered
for use with dput. See HOOKS below.
* commands/ define entry hooks to command functions which are
registered for use with dcut.
* interfaces/ define entry hooks to user interface functions which
are registered for use with dput and dcut. They are responsible to
retrieve data from the user.
By default all configuration file locations are parsed, and overlaid in
a additive manner. This way both, entire profiles and actual settings
within a profile is inherited from any parent location defining a key
within the current scope. Details are explained in the INHERITANCE OF
KEYS section.
PROFILES
Profiles are indexed as <profile name>.json within the profiles/
configuration directory. Every profile may define these keys.
Optionally a profile called DEFAULT.json can be defined as a superset
of all existing profiles. Any other profile will inherit values from
this profile. For a finer grained control see meta keyword and
META-CLASSES below.
Following is an example configuration for a local upload profile, named
"localhost.json".
{
"+hooks": [
"lintian"
],
"-hooks": [
"gpg"
],
"incoming": "~/incoming",
"meta": "debian",
"method": "local",
"run_lintian": true
}
Supported keys are:
allow_dcut (boolean)
This defines if you are allowed to upload a dcut changes file to
the queue to remove or move files. See dcut(1).
allow_unsigned_uploads (boolean)
This defines if you are allowed to upload files without a GnuPG
signature to this host or not.
allowed_distributions (string)
A regular expression (of Python re module syntax) that the
distribution field must match or dput will refuse the upload.
default_host_main (string)
This defines the default host for packages that are allowed to be
uploaded to the main archive. This variable is used when guessing
the host to upload to.
default_keyid (string)
This defines the default GPG key ID to be used to sign dcut
commands. This option can be overridden by -k parameter.
full_upload_log (boolean)
This defines the verbosity of upload logs. When set to true, logs
will include more details. This setting might be overridden on the
command line and defaults to false.
fqdn (string)
This is the fully qualified domain name that dput will connect to
as a target site.
distributions (string)
This defines a comma-separated list of distributions that this host
accepts, used to guess the host to use when none is given on the
command line.
hash (string)
The hash algorithm that should be used in calculating the checksum
of the files before uploading them. Currently, dput accepts the
following values for hash:
* sha1: Perform validation of the SHA-1 hash (default when
omitted)
* sha256: Perform validation of the SHA-256 hash
* md5: Perform validation of the MD5 hash
hooks (list of string)
Defines a list of checkers which are running before or after the
upload. See HOOKS below.
interface (string)
Not supported yet. This is a known limitation.
incoming (string)
The directory that dput should upload files to. Most upload sites
do not allow to write files in the log-in directory. Specify a path
here, to which dput should change the directory to, before starting
to write files.
method (string)
Use the specified method to upload your package. Currently these
alternatives are supported:
* ftp:: Use FTP to upload files
* http or https:: Use HTTP or HTTPS to upload files
* local:: Upload to a locally mounted location of the file
system. Internally this calls install(1).
* scp:: Use scp to upload files (requires python-paramiko). This
method is deprecated, use sftp instead when possible.
* sftp:: Use the sftp protocol (a secured file transfer via SSH,
requires python-paramiko).
* dput-ng does not support rsync.
login (string)
Your login on the machine named before. A single asterisk (*) will
cause the scp, sftp and uploaders to not supply a login name when
calling trying to authenticate.
meta (list of string)
Specify a list of super classes from which the profile should
inherit settings explicitly. This is different to the DEFAULT.json
profile in such that this defines settings conditionally, and not
for all profiles.
passive_ftp (boolean)
This option defines whether dput should use passive or active FTP
for uploading a package to one of the upload queues. This name is
only meaningful when method is set to ftp.
post_upload_command (string)
This option defines a command to be run by dput after a successful
upload. The command is invoked via the shell and does not get
passed any argument. See PROCESSORS for more sophisticated
approaches which are integrated in the upload process.
pre_upload_command (string)
This option defines a command to be run by dput before an upload.
The command is invoked via the shell and does not get passed any
argument. See HOOKS for more sophisticated approaches which are
integrated in the upload process and can gracefully interrupt the
upload process.
run_lintian (boolean)
This option defines if lintian should be run before the package
will be uploaded or not. This setting is deprecated but works as a
fallback to the corresponding HOOK. The Lintian hook allows much
more fine grained control over the Lintian invocation.
READING TRADITIONAL CONFIGURATION FILES
As outlined initially, dput reads and parses traditional INI style configuration files. It's format is documented in dput.cf(5). These files are deprecated, but for the time being read and parsed. We encourage the removal of these global and local configuration files entirely. Having that said, when in place old-style configuration files will overrule new style files, to preserve a possibly modified legacy behavior. That means, in order configuration values are inherited and keys are successively overwritten in this order: 1. /etc/dput.d/profiles 2. /etc/dput.cf 3. ~/.dput.d/profiles 4. ~/.dput.cf This means, old-style configuration files always take relative precedence when installed. Use them with caution.
INHERITANCE OF KEYS
By default, keys will override any previously defined value. However,
as a special case, there are three operators (=, + and -) that may be
prefixed to names to merge with existing inherited values. This is
beneficial when a profile wishes to add or remove values from an
existing key which accepts lists of values. This is mostly useful to
hooks which may want to extend an existing profile key that is
inheriting values via it's meta-class or parent.
* The = operator is the default operator when no operator was
explicitly provided. It overwrites any previous key.
* The + operator is additive. When set, it merges the supplied
value(s) with any previous value
* The - operator is subtractive. When set, it removes the supplied
value(s) from any previous value.
The DEFAULT Profile
There is a special profile called DEFAULT ("DEFAULT.json" in any
configuration location). This profile is the root profile. All profiles
are automatically inheriting values from this profile. Values set there
are global defaults. The profile itself is subject to the same
inheritance rules as any other profile itself as well.
All keys and values can be set in the DEFAULT profile.
META PROFILES
Configuration files may declare an optional meta key, who's value is
the name of a meta-configuration to be placed under this configuration.
You can check for meta-configuration in /usr/share/dput-ng/metas,
/etc/dput.d/metas or ~/.dput.d/metas. This helps declare common
settings (such as general Debian archive configuration values (GPG
requirements, enforcing that binary files exist, etc) without having to
maintain may of the same values in many places).
They are different to the DEFAULT profile in such, that no profile
automatically inherits values from a meta profile, but only upon
explicit request.
Meta profiles can in turn inherit itself values from other meta
profiles.
OVERRIDING SINGLE VALUES
Here's an example stanza from a local dput config to remove an annoying
hook from being run:
~/.dput.d/profiles/DEFAULT.json:
{
"hooks": [
"gpg",
"lintian"
]
}
At this point, every profile will invoke the hooks gpg, lintian
~/.dput.d/metas/my-defaults.json:
{
"hooks": [
"checksum",
]
}
This defines a meta profile named my-defaults, which will also invoke
the checksum hook. At this point this meta profile, inherits values
from DEFAULT and therefore invokes the hooks gpg, lintian and checksum.
~/.dput.d/profiles/ftp-master.json:
{
"-hooks": [
"lintian"
]
"meta": [
"my-defaults"
]
}
At this point, the profile ftp-master will inherit values from DEFAULT
and my-defaults. However, the - operator prefix removes lintian from
the checker list. Hence, ftp-master will run the checkers gpg and
checksum.
HOOKS
Hooks are pre- or post-uupload checks, They are pluggable components running before or after the upload of a package. Whether they run before or after the upload is determined by the JSON definition of a hook. That is an implementation detail the user typically does not need to worry about. Pre-Upload Hooks Pre-upload hooks are pluggable components which are designed to run before the upload actually happens. This typically involves consistency checks, sanity checks and similar tasks. The list of available pre-upload hooks can be obtained using dirt(1). The hooks invoked by default are determined on a per-profile basis by retrieving the setting of the hooks key. Hooks also run in simulation and check-only mode. It is easy to write your own hook extensions. Consult the manual for instructions. Post-Upload Hooks Processors are pluggable components which are designed to run after the upload actually happens. They cannot interrupt the upload, because they are invoked after a successful upload only. They do not run when dput was invoked with check-only or simulation mode. Such post-upload hooks may invoke post- processing tasks such as closing or filing bugs. The list of available processors can be obtained using dirt(1). The hooks invoked by default are determined on a per-profile basis by retrieving the setting of the hooks key and follow the same rules as pre-upload hooks. It is easy to write your own hook extensions. Consult the manual for instructions.
FILES
/usr/share/dput-ng/
/etc/dput.d/
~/.dput.d/
AUTHOR
dput-ng was originally written by Arno Tll <arno(a)debian.org> and Paul Richard I by the Grace of God of the United Kingdom of Debian and Ubuntu and of his other realms and territories King Head of the Fluxbox Window Manager Defender of the Faith Tagliamonte <paultag(a)debian.org>.
RESOURCES
RFC 4627, /usr/share/doc/dput-ng/html/reference/, dput(1), dcut(1), dcut(1) 11/27/2016 DPUT(5)
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
