Provided by: dput-ng_1.39_all bug

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 dcuthooks/ 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 writes
           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).

           •   rsync:: Use rsync to upload files.

           •   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).

       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. $XDG_CONFIG_HOME/dput/dput.cf, or if that does not exist ~/.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 Töll <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)

                                            02/17/2024                                    DPUT(5)