1DPUT(5)                                                                DPUT(5)
2
3
4

NAME

6       dput - configuration file format for dput-ng
7

DESCRIPTION

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

FILES AND FORMAT

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
26       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
30       dput reads, in order, these directories:
31
32        1. /usr/share/dput-ng/
33
34        2. /etc/dput.d/
35
36        3. ~/.dput.d/
37
38        4. The directory supplied via command line argument
39
40       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
48       Within each configuration directory, there may be another tier of
49       configuration directories. There, these actual configuration
50       directories may exist:
51
52metas/ 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
56profiles/ 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
60       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
65hooks/ define entry hooks to checker functions which are registered
66           for use with dput. See HOOKS below.
67
68commands/ define entry hooks to command functions which are
69           registered for use with dcut.
70
71interfaces/ 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
75       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

PROFILES

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
89       Following is an example configuration for a local upload profile, named
90       "localhost.json".
91
92           {
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
105       Supported keys are:
106
107       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
111       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
115       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
119       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
124       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
128       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
133       fqdn (string)
134           This is the fully qualified domain name that dput will connect to
135           as a target site.
136
137       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
142       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
147sha1: Perform validation of the SHA-1 hash (default when
148               omitted)
149
150sha256: Perform validation of the SHA-256 hash
151
152md5: Perform validation of the MD5 hash
153
154       hooks (list of string)
155           Defines a list of checkers which are running before or after the
156           upload. See HOOKS below.
157
158       interface (string)
159           Not supported yet. This is a known limitation.
160
161       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
167       method (string)
168           Use the specified method to upload your package. Currently these
169           alternatives are supported:
170
171ftp:: Use FTP to upload files
172
173http or https:: Use HTTP or HTTPS to upload files
174
175local:: Upload to a locally mounted location of the file
176               system. Internally this calls install(1).
177
178scp:: Use scp to upload files (requires python-paramiko).  This
179               method is deprecated, use sftp instead when possible.
180
181sftp:: Use the sftp protocol (a secured file transfer via SSH,
182               requires python-paramiko).
183
184dput-ng does not support rsync.
185
186       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
191       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
197       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
202       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
208       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
215       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

READING TRADITIONAL CONFIGURATION FILES

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
228       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
233        1. /etc/dput.d/profiles
234
235        2. /etc/dput.cf
236
237        3. ~/.dput.d/profiles
238
239        4. ~/.dput.cf
240
241       This means, old-style configuration files always take relative
242       precedence when installed. Use them with caution.
243

INHERITANCE OF KEYS

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
253       •   The = operator is the default operator when no operator was
254           explicitly provided. It overwrites any previous key.
255
256       •   The + operator is additive. When set, it merges the supplied
257           value(s) with any previous value
258
259       •   The - operator is subtractive. When set, it removes the supplied
260           value(s) from any previous value.
261
262   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
269       All keys and values can be set in the DEFAULT profile.
270
271   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
280       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
284       Meta profiles can in turn inherit itself values from other meta
285       profiles.
286
287   OVERRIDING SINGLE VALUES
288       Here’s an example stanza from a local dput config to remove an annoying
289       hook from being run:
290
291       ~/.dput.d/profiles/DEFAULT.json:
292
293           {
294               "hooks": [
295                   "gpg",
296                   "lintian"
297               ]
298           }
299
300       At this point, every profile will invoke the hooks gpg, lintian
301
302       ~/.dput.d/metas/my-defaults.json:
303
304           {
305               "hooks": [
306                   "checksum",
307               ]
308           }
309
310       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
314       ~/.dput.d/profiles/ftp-master.json:
315
316           {
317               "-hooks": [
318                   "lintian"
319               ]
320               "meta": [
321                       "my-defaults"
322               ]
323           }
324
325       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

HOOKS

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
337   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
345       It is easy to write your own hook extensions. Consult the manual for
346       instructions.
347
348   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
359       It is easy to write your own hook extensions. Consult the manual for
360       instructions.
361

FILES

363           /usr/share/dput-ng/
364           /etc/dput.d/
365           ~/.dput.d/
366

AUTHOR

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

RESOURCES

375       RFC 4627, /usr/share/doc/dput-ng/html/reference/, dput(1), dcut(1),
376       dcut(1)
377
378
379
380                                  07/21/2022                           DPUT(5)
Impressum