~rjarry/dlrepo

dlrepo/docs/dlrepo-config.5.scdoc -rw-r--r-- 9.9 KiB
30793599Robin Jarry release v0.30 a month ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
dlrepo-config(5) "" "Configuration Manual"

# NAME

*dlrepo-config* -- artifact repository configuration

# DESCRIPTION

*dlrepo* is an artifact repository. It supports storing build artifacts (binary
packages, documentation, vm images, container images, etc.) in a structured
file system tree. It exposes an HTTP API to upload files, delete them, add
metadata, etc.

This manual describes how to configure the server.

# CONFIGURATION

The server is configured via environment variables. They should be set in
_/etc/default/dlrepo_ which is sourced by systemd in _dlrepo.service_ before
running the daemon process.

## core settings

*DLREPO_ROOT_DIR* (default: _/var/lib/dlrepo_)
	The root folder where the artifacts are stored. *dlrepo* does not use
	an external database and will only store data in that folder.

	The structure of that folder is described in detail in
	*dlrepo-layout*(8).

*DLREPO_CHUNK_SIZE* (default: _262144_)
	The maximum size in bytes of data chunks that are read from the client
	when receiving uploads.

*DLREPO_X_SENDFILE_HEADER*
	Instead of streaming the files directly from disk, dlrepo will return
	the filepath in an HTTP response header to be handled by a reverse
	proxy such as nginx or apache. This allows much better performance
	while preserving access control.

	Example: _X-Accel-Redirect_

*DLREPO_ORPHAN_BLOB_LIFETIME* (default: _600_)
	The minimum age in seconds after which an orphan blob may be deleted.

	Orphan blobs are files in _DLREPO_ROOT_DIR/.blobs_ that only have one
	hard link.

	The blobs will be deleted immediately when a tag is manually deleted
	via the *dlrepo-api*(7) if they are older than
	*DLREPO_ORPHAN_BLOB_LIFETIME*.

	Otherwise, the garbage collection task will delete them in a later time.

*DLREPO_TAG_CLEANUP_PERIOD* (default: _86400_)
	The period in seconds after which the cleanup coroutine will delete tags
	according to each branch cleanup policy, refresh each user quotas and
	finally perform garbage collection on the orphan blobs.

	This cleanup can also be triggered by sending the SIGUSR1 signal to the
	dlrepo process.

*DLREPO_LOG_LEVEL* (default: _WARNING_)
	Only events that are above that level are sent to the system logs.
	Valid values are _DEBUG_, _INFO_, _WARNING_ and _ERROR_.

*DLREPO_USER_QUOTA* (default: _10737418240_)
	The maximum disk usage in bytes per user repository. When the user quota
	is exceeded, new uploads are denied with an explicit error.

*DLREPO_POST_PROCESS_CMD* (optional)
	Command to execute when finalizing an artifact format. It may be used
	to perform sensible operations such as packages signing without
	exposing the private key to the build system.

	The finalization is done automatically when running the *dlrepo-cli*(1)
	*upload* command. Or, alternatively by performing a _PATCH_ request on
	an artifact format (see *dlrepo-api*(7)).

	This should be either the path to an executable or its name if it is in
	the system _PATH_. The command will be executed by the user running the
	dlrepo daemon process with the artifact format folder as its working
	directory and no arguments. Any output produced by the command will be
	sent to the system logs.

	If the command exits with a non-zero code, an error will be returned to
	the client.

	Example: _/etc/dlrepo/post-process.sh_

*DLREPO_POST_PROCESS_FILTER* (optional)
	Regular expression for selecting on which artifact formats
	_DLREPO_POST_PROCESS_CMD_ must be run. If set, the command is run if at
	least one file in the format folder matches the regular expression.
	If not set, _DLREPO_POST_PROCESS_CMD_ is run on all formats.

	Example: _'^(.+\\.rpm|Release)$'_

*DLREPO_PUBLIC_URL* (optional)
	If set, it will replace the default URL in the script contents that are
	returned from the _/cli_ URL.

## customization

*DLREPO_STATIC_DIR* (optional)
	Files present in that directory will be served under the _/static_ URL.
	The following special files may be added:

	_{product_name}.svg_
		When browsing the products tree, _/static/{product_name}.svg_
		images will be referenced. You may use this to provide SVG
		icons for products.

	You can also override the default style by adding the following files:

	_dlrepo.css_
		CSS stylesheet.
	_logo.svg_
		The main logo on the banner.
	_favicon.svg_
		The site icon.
	_locked.svg_
		Icon used for locked tags and versions.
	_released.svg_
		Icon used for released tags and versions.

	Example: _/etc/dlrepo/static_

*DLREPO_TEMPLATES_DIR* (default: _/etc/dlrepo/templates_)
	For extended customization, it is possible to override the builtin HTML
	templates. These templates use the Jinja2 syntax. You have two options:

	*1.* Completely redefine a template:
		Copy it from the default templates in the sources and adjust it
		to your needs.

	*2.* Extend a builtin template:
		Create an empty template with the same name than one of the
		builtins and add an _extends_ directive on top with the
		"templates/" prefix:

		```
		{% extends "templates/base.html" %}
		```

		Then, only redefine blocks that you want to change.

	Example: _/etc/dlrepo/static_

## authentication

*DLREPO_LDAP_URL* (if set, *DLREPO_AUTH_FILE* is ignored)
	URL to the LDAP server used to authenticate users and get their groups.

	If the URL starts with _ldap://_, Start TLS is implied unless
	*DLREPO_LDAP_START_TLS* is set to _0_.

	Example: _"ldap://ldap.foobar.org"_

*DLREPO_LDAP_START_TLS* (default: _1_)
	By default, when *DLREPO_LDAP_URL* starts with _ldap://_, a Start TLS
	request (RFC 2830) will be performed before attempting to authenticate
	the user with the provided login and password.

	Insecure connections can be allowed by setting this to _0_.

*DLREPO_LDAP_USER_FILTER* (mandatory if *DLREPO_LDAP_URL* is set)
	The LDAP filter used to determine a user DN from their login name.
	_{login}_ is replaced by the username received in the HTTP
	_Authorization_ header. The LDAP search is performed after an anonymous
	bind.

	Example: _"(&(uid={login})(objectClass=inetOrgPerson))"_

*DLREPO_LDAP_BASE_DN* (mandatory if *DLREPO_LDAP_URL* is set)
	The base DN used to lookup user groups.

	Example: _"dc=foobar,dc=org"_

*DLREPO_LDAP_GROUPS_FILTER* (mandatory if *DLREPO_LDAP_URL* is set)
	The LDAP filter used to search for the user groups. _{login}_ is
	replaced by the username provided in the HTTP _Authorization_ header.
	_{dn}_ is replaced by the resolved user DN. The LDAP search is
	performed after a successful bind with the provided login and password.
	If *DLREPO_IGNORE_PASSWORDS* is set to _1_, the groups are searched
	after an anonymous bind.

	Examples: _"(&(objectClass=posixGroup)(memberUid={login}))"_,
	_"(&(objectClass=groupOfNames)(member={dn}))"_

*DLREPO_LDAP_TIMEOUT* (default: _10_)
	Timeout in seconds for the LDAP server connection/requests.

*DLREPO_LDAP_MAX_CONNECTIONS* (default: _4_)
	Maximum number of concurrent LDAP server connections.

*DLREPO_AUTH_HTTP_LOGIN_HEADER*
	The HTTP header name where the server will find the user name. This
	should be used along with a proxy that sets the header value after
	a successful authentication. Only use this if the server is not
	directly accessible by users, but only via a reverse proxy that
	performs authentication checks.

	Example: X-Dlrepo-User

*DLREPO_AUTH_HTTP_GROUPS_HEADER*
	The HTTP header name where the server will find the user group names as
	comma separated values. This should be used along with a proxy that
	sets the header value after a successful authentication. Only use this
	if the server is not directly accessible by users, but only via
	a reverse proxy that performs authentication checks.

	Example: X-Dlrepo-Groups

*DLREPO_AUTH_FILE* (default: _/etc/dlrepo/auth_)
	File containing user passwords and groups. If *DLREPO_LDAP_URL* is not
	set, the username and password provided in the HTTP _Authorization_
	header are checked to determine the user groups.

	This file should have lines with the following format:

	```
	LOGIN:PASSWORD:GROUP1 GROUP2 GROUP3
	```

	This should only be used for small deployments or testing purposes. For
	production servers, you should use LDAP.

*DLREPO_AUTH_CACHE_SIZE* (default: _4096_)
	Maximum number of entries in the authentication cache. The cache is used
	to reduce the number of LDAP queries for repetitive connections with the
	same user.

*DLREPO_AUTH_CACHE_TTL* (default: _600_)
	Maximum age in seconds for entries in the authentication cache.

*DLREPO_ACLS_DIR* (default: _/etc/dlrepo/acls_)
	Local folder containing ACL files. See *dlrepo-acls*(5) for more
	details. If the file does not exist, a warning will be displayed on
	startup.

*DLREPO_AUTH_DISABLED* (default: _0_)
	Set to _1_ to completely disable authentication and permission
	checking. When authentication is disabled, anyone can read/write
	anything anonymously. The HTTP _Authorization_ header is ignored.

	_NEVER USE THIS ON A PRODUCTION SERVER! THIS IS ONLY FOR DEVELOPMENT._

*DLREPO_IGNORE_PASSWORDS* (default: _0_)
	Set to _1_ to disable password checking. When password check is
	disabled, the username provided in the HTTP _Authorization_ header is
	trusted without any verification/authentication. When *DLREPO_LDAP_URL*
	is set, the user groups are fetched from the LDAP server with an
	anonymous bind.

	_NEVER USE THIS ON A PRODUCTION SERVER! THIS IS ONLY FOR DEVELOPMENT._

## mirroring to another server

*DLREPO_PUBLISH_URL* (optional)
	URL to another dlrepo server on which to publish tags when they are
	released on this server.

	Example: _"https://dlrepo-public.foobar.org"_

*DLREPO_PUBLISH_AUTH* (optional)
	Path to a file containing the _LOGIN:PASSWORD_ to use for
	authenticating against *DLREPO_PUBLISH_URL*. This file should have
	restrictive permissions.

	Example: _/etc/dlrepo/publish_auth_

*DLREPO_PUBLISH_MAX_REQUESTS* (default: _1_)
	Maximum number of concurrent requests made to *DLREPO_PUBLISH_URL* when
	publishing tags.

# SEE ALSO

*dlrepo*(7),
*dlrepo-acls*(5),
*dlrepo-api*(1),
*dlrepo-cli*(1),
*dlrepo-layout*(7)

# AUTHORS

Created and maintained by Robin Jarry and Julien Floret. For more information,
development and bug reports, see _https://sr.ht/~rjarry/dlrepo/_.