1DPUT(5) DPUT(5)
2
6 dput - configuration file format for dput-ng
7
9 dput supports two configuration file formats. The old-style
10 configuration format was originally introduced by dput and is described
11 in dput.cf(5). This manpage describes new-style configuration files
12 only. All details are covered in in
13 </usr/share/doc/dput-ng/html/reference/configs.html> which is available
14 in the dput-ng-doc package.
15
17 Upload targets are configured using JSON as described in RFC 4627. In a
18 nutshell, dput configuration allows insignificant whitespace before or
19 after any type statement. Each upload profile is stored in its own file
20 and is represented as a pair of curly brackets surrounding name/value
21 pairs described below. Both, name and values are strings. A single
22 colon separates the name from the value. A string begins and ends with
23 quotation marks and may be escaped. Booleans are either true or false
24 (mind these are not surrounded by quotation marks).
25 Some keys names are accepting lists as possible value. A list is
27 represented as square brackets surrounding zero or more values,
28 separated by commas.
29 dput reads, in order, these directories:
31 1. /usr/share/dput-ng/
33 2. /etc/dput.d/
35 3. ~/.dput.d/
37 4. The directory supplied via command line argument
39 Moreover, old-style configuration files are parsed and read. See
41 READING TRADITIONAL CONFIGURATION FILES below. In general, packages are
42 installing pre-defined defaults for popular upload targets to
43 /usr/share/dput-ng/profiles/. System administrators who wish to
44 override or create a new system-wide and shared target for many users
45 may choose /etc/dput.d/profiles. Finally, local targets may be written
46 to ~/.dput.d/profiles for personal upload targets.
47 Within each configuration directory, there may be another tier of
49 configuration directories. There, these actual configuration
50 directories may exist:
51 • metas/ define super-classes of upload profiles. They can define any
53 name and value known to profiles (see below) which are shared
54 across profiles.
55 • profiles/ define upload profiles. Files therein are looked-up by
57 their name as HOST argument by dput. This is, where upload hosts
58 are defined.
59 Moreover, these directories can exist and are documented here for the
61 sake of completeness. However, users typically do not need to touch
62 these unless you are developing or customizing existing plug-ins to
63 dput or dcut
64 • hooks/ define entry hooks to checker functions which are registered
66 for use with dput. See HOOKS below.
67 • commands/ define entry hooks to command functions which are
69 registered for use with dcut.
70 • interfaces/ define entry hooks to user interface functions which
72 are registered for use with dput and dcut. They are responsible to
73 retrieve data from the user.
74 By default all configuration file locations are parsed, and overlaid in
76 a additive manner. This way both, entire profiles and actual settings
77 within a profile is inherited from any parent location defining a key
78 within the current scope. Details are explained in the INHERITANCE OF
79 KEYS section.
80
82 Profiles are indexed as <profile name>.json within the profiles/
83 configuration directory. Every profile may define these keys.
84 Optionally a profile called DEFAULT.json can be defined as a superset
85 of all existing profiles. Any other profile will inherit values from
86 this profile. For a finer grained control see meta keyword and
87 META-CLASSES below.
88 Following is an example configuration for a local upload profile, named
90 "localhost.json".
91 {
93 "+hooks": [
94 "lintian"
95 ],
96 "-hooks": [
97 "gpg"
98 ],
99 "incoming": "~/incoming",
100 "meta": "debian",
101 "method": "local",
102 "run_lintian": true
103 }
104 Supported keys are:
106 allow_dcut (boolean)
108 This defines if you are allowed to upload a dcut changes file to
109 the queue to remove or move files. See dcut(1).
110 allow_unsigned_uploads (boolean)
112 This defines if you are allowed to upload files without a GnuPG
113 signature to this host or not.
114 allowed_distributions (string)
116 A regular expression (of Python re module syntax) that the
117 distribution field must match or dput will refuse the upload.
118 default_host_main (string)
120 This defines the default host for packages that are allowed to be
121 uploaded to the main archive. This variable is used when guessing
122 the host to upload to.
123 default_keyid (string)
125 This defines the default GPG key ID to be used to sign dcut
126 commands. This option can be overridden by -k parameter.
127 full_upload_log (boolean)
129 This defines the verbosity of upload logs. When set to true, logs
130 will include more details. This setting might be overridden on the
131 command line and defaults to false.
132 fqdn (string)
134 This is the fully qualified domain name that dput will connect to
135 as a target site.
136 distributions (string)
138 This defines a comma-separated list of distributions that this host
139 accepts, used to guess the host to use when none is given on the
140 command line.
141 hash (string)
143 The hash algorithm that should be used in calculating the checksum
144 of the files before uploading them. Currently, dput accepts the
145 following values for hash:
146 • sha1: Perform validation of the SHA-1 hash (default when
148 omitted)
149 • sha256: Perform validation of the SHA-256 hash
151 • md5: Perform validation of the MD5 hash
153 hooks (list of string)
155 Defines a list of checkers which are running before or after the
156 upload. See HOOKS below.
157 interface (string)
159 Not supported yet. This is a known limitation.
160 incoming (string)
162 The directory that dput should upload files to. Most upload sites
163 do not allow writes in the log-in directory. Specify a path here,
164 to which dput should change the directory to, before starting to
165 write files.
166 method (string)
168 Use the specified method to upload your package. Currently these
169 alternatives are supported:
170 • ftp:: Use FTP to upload files
172 • http or https:: Use HTTP or HTTPS to upload files
174 • local:: Upload to a locally mounted location of the file
176 system. Internally this calls install(1).
177 • scp:: Use scp to upload files (requires python-paramiko). This
179 method is deprecated, use sftp instead when possible.
180 • sftp:: Use the sftp protocol (a secured file transfer via SSH,
182 requires python-paramiko).
183 • dput-ng does not support rsync.
185 login (string)
187 Your login on the machine named before. A single asterisk (*) will
188 cause the scp, sftp and uploaders to not supply a login name when
189 calling trying to authenticate.
190 meta (list of string)
192 Specify a list of super classes from which the profile should
193 inherit settings explicitly. This is different to the DEFAULT.json
194 profile in such that this defines settings conditionally, and not
195 for all profiles.
196 passive_ftp (boolean)
198 This option defines whether dput should use passive or active FTP
199 for uploading a package to one of the upload queues. This name is
200 only meaningful when method is set to ftp.
201 post_upload_command (string)
203 This option defines a command to be run by dput after a successful
204 upload. The command is invoked via the shell and does not get
205 passed any argument. See PROCESSORS for more sophisticated
206 approaches which are integrated in the upload process.
207 pre_upload_command (string)
209 This option defines a command to be run by dput before an upload.
210 The command is invoked via the shell and does not get passed any
211 argument. See HOOKS for more sophisticated approaches which are
212 integrated in the upload process and can gracefully interrupt the
213 upload process.
214 run_lintian (boolean)
216 This option defines if lintian should be run before the package
217 will be uploaded or not. This setting is deprecated but works as a
218 fallback to the corresponding HOOK. The Lintian hook allows much
219 more fine grained control over the Lintian invocation.
220
222 As outlined initially, dput reads and parses traditional INI style
223 configuration files. It’s format is documented in dput.cf(5). These
224 files are deprecated, but for the time being read and parsed. We
225 encourage the removal of these global and local configuration files
226 entirely.
227 Having that said, when in place old-style configuration files will
229 overrule new style files, to preserve a possibly modified legacy
230 behavior. That means, in order configuration values are inherited and
231 keys are successively overwritten in this order:
232 1. /etc/dput.d/profiles
234 2. /etc/dput.cf
236 3. ~/.dput.d/profiles
238 4. ~/.dput.cf
240 This means, old-style configuration files always take relative
242 precedence when installed. Use them with caution.
243
245 By default, keys will override any previously defined value. However,
246 as a special case, there are three operators (=, + and -) that may be
247 prefixed to names to merge with existing inherited values. This is
248 beneficial when a profile wishes to add or remove values from an
249 existing key which accepts lists of values. This is mostly useful to
250 hooks which may want to extend an existing profile key that is
251 inheriting values via it’s meta-class or parent.
252 • The = operator is the default operator when no operator was
254 explicitly provided. It overwrites any previous key.
255 • The + operator is additive. When set, it merges the supplied
257 value(s) with any previous value
258 • The - operator is subtractive. When set, it removes the supplied
260 value(s) from any previous value.
261 The DEFAULT Profile
263 There is a special profile called DEFAULT ("DEFAULT.json" in any
264 configuration location). This profile is the root profile. All profiles
265 are automatically inheriting values from this profile. Values set there
266 are global defaults. The profile itself is subject to the same
267 inheritance rules as any other profile itself as well.
268 All keys and values can be set in the DEFAULT profile.
270 META PROFILES
272 Configuration files may declare an optional meta key, who’s value is
273 the name of a meta-configuration to be placed under this configuration.
274 You can check for meta-configuration in /usr/share/dput-ng/metas,
275 /etc/dput.d/metas or ~/.dput.d/metas. This helps declare common
276 settings (such as general Debian archive configuration values (GPG
277 requirements, enforcing that binary files exist, etc) without having to
278 maintain may of the same values in many places).
279 They are different to the DEFAULT profile in such, that no profile
281 automatically inherits values from a meta profile, but only upon
282 explicit request.
283 Meta profiles can in turn inherit itself values from other meta
285 profiles.
286 OVERRIDING SINGLE VALUES
288 Here’s an example stanza from a local dput config to remove an annoying
289 hook from being run:
290 ~/.dput.d/profiles/DEFAULT.json:
292 {
294 "hooks": [
295 "gpg",
296 "lintian"
297 ]
298 }
299 At this point, every profile will invoke the hooks gpg, lintian
301 ~/.dput.d/metas/my-defaults.json:
303 {
305 "hooks": [
306 "checksum",
307 ]
308 }
309 This defines a meta profile named my-defaults, which will also invoke
311 the checksum hook. At this point this meta profile, inherits values
312 from DEFAULT and therefore invokes the hooks gpg, lintian and checksum.
313 ~/.dput.d/profiles/ftp-master.json:
315 {
317 "-hooks": [
318 "lintian"
319 ]
320 "meta": [
321 "my-defaults"
322 ]
323 }
324 At this point, the profile ftp-master will inherit values from DEFAULT
326 and my-defaults. However, the - operator prefix removes lintian from
327 the checker list. Hence, ftp-master will run the checkers gpg and
328 checksum.
329
331 Hooks are pre- or post-uupload checks, They are pluggable components
332 running before or after the upload of a package. Whether they run
333 before or after the upload is determined by the JSON definition of a
334 hook. That is an implementation detail the user typically does not need
335 to worry about.
336 Pre-Upload Hooks
338 Pre-upload hooks are pluggable components which are designed to run
339 before the upload actually happens. This typically involves consistency
340 checks, sanity checks and similar tasks. The list of available
341 pre-upload hooks can be obtained using dirt(1). The hooks invoked by
342 default are determined on a per-profile basis by retrieving the setting
343 of the hooks key. Hooks also run in simulation and check-only mode.
344 It is easy to write your own hook extensions. Consult the manual for
346 instructions.
347 Post-Upload Hooks
349 Processors are pluggable components which are designed to run after the
350 upload actually happens. They cannot interrupt the upload, because they
351 are invoked after a successful upload only. They do not run when dput
352 was invoked with check-only or simulation mode. Such post-upload hooks
353 may invoke post- processing tasks such as closing or filing bugs. The
354 list of available processors can be obtained using dirt(1). The hooks
355 invoked by default are determined on a per-profile basis by retrieving
356 the setting of the hooks key and follow the same rules as pre-upload
357 hooks.
358 It is easy to write your own hook extensions. Consult the manual for
360 instructions.
361
363 /usr/share/dput-ng/
364 /etc/dput.d/
365 ~/.dput.d/
366
368 dput-ng was originally written by Arno Töll <arno(a)debian.org> and
369 Paul Richard I by the Grace of God of the United Kingdom of Debian and
370 Ubuntu and of his other realms and territories King Head of the Fluxbox
371 Window Manager Defender of the Faith Tagliamonte
372 <paultag(a)debian.org>.
373
375 RFC 4627, /usr/share/doc/dput-ng/html/reference/, dput(1), dcut(1),
376 dcut(1)
377 07/19/2023 DPUT(5)