Skip to content

Commit 1582fad

Browse files
nscuroCopilot
nscuro
and
Copilot
authored
Add upgrade notes for 5.0.0-rc.2 (#114)
* Add upgrade notes for 5.0.0-rc.2 Also updates references of renamed config properties. Signed-off-by: nscuro <nscuro@protonmail.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Niklas <nscuro@protonmail.com> * Fix property links Signed-off-by: nscuro <nscuro@protonmail.com> --------- Signed-off-by: nscuro <nscuro@protonmail.com> Signed-off-by: Niklas <nscuro@protonmail.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
1 parent af5e20d commit 1582fad

10 files changed

Lines changed: 269 additions & 112 deletions

File tree

‎docs/concepts/architecture/design/durable-execution.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -691,7 +691,7 @@ mechanism.
691691
### Maintenance
692692

693693
A leader-only maintenance worker periodically deletes terminal workflow runs older than
694-
[`dt.dex-engine.maintenance.run-retention-duration`](../../../reference/configuration/properties.md#dtdex-enginemaintenancerun-retention-duration).
694+
[`dt.dex-engine.maintenance.run-retention-ms`](../../../reference/configuration/properties.md#dtdex-enginemaintenancerun-retention-ms).
695695
Deletion happens in batches of [`dt.dex-engine.maintenance.run-deletion-batch-size`](../../../reference/configuration/properties.md#dtdex-enginemaintenancerun-deletion-batch-size)
696696
rows using `FOR NO KEY UPDATE SKIP LOCKED` to coexist with active workloads.
697697
Cascade foreign keys remove the associated history, inbox, and task rows in the same transaction.

‎docs/guides/administration/configuring-http-proxy.md‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -16,32 +16,32 @@ user's browser; any requests it appears to make actually originate from the brow
1616

1717
The API server reads proxy settings from two sources, in this order:
1818

19-
1. App properties (`dt.http.proxy.*`, `dt.no.proxy`).
19+
1. App properties (`dt.http.proxy.*`).
2020
2. The standard `HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY` environment variables.
2121

22-
If `dt.http.proxy.address` has a value, app properties win and the API server ignores the environment variables.
22+
If `dt.http.proxy.host` has a value, app properties win and the API server ignores the environment variables.
2323
Otherwise, the API server falls back to the environment.
2424

2525
## Configuring via app properties
2626

2727
Set the following properties (see [Application configuration](../../reference/configuration/application.md#environment-variable-mapping)
2828
for how property names map to environment variables):
2929

30-
- [`dt.http.proxy.address`](../../reference/configuration/properties.md#dthttpproxyaddress): proxy hostname or IP address.
30+
- [`dt.http.proxy.host`](../../reference/configuration/properties.md#dthttpproxyhost): proxy hostname or IP address.
3131
- [`dt.http.proxy.port`](../../reference/configuration/properties.md#dthttpproxyport): proxy port. Required when
32-
`dt.http.proxy.address` has a value.
33-
- [`dt.http.proxy.username`](../../reference/configuration/properties.md#dthttpproxyusername): optional, for
32+
`dt.http.proxy.host` has a value.
33+
- [`dt.http.proxy.auth.username`](../../reference/configuration/properties.md#dthttpproxyauthusername): optional, for
3434
authenticated proxies.
35-
- [`dt.http.proxy.password`](../../reference/configuration/properties.md#dthttpproxypassword): optional, for
35+
- [`dt.http.proxy.auth.password`](../../reference/configuration/properties.md#dthttpproxyauthpassword): optional, for
3636
authenticated proxies.
37-
- [`dt.no.proxy`](../../reference/configuration/properties.md#dtnoproxy): comma-separated bypass list.
37+
- [`dt.http.proxy.exclusions`](../../reference/configuration/properties.md#dthttpproxyexclusions): comma-separated bypass list.
3838

3939
Example:
4040

4141
```properties linenums="1"
42-
dt.http.proxy.address=proxy.example.com
42+
dt.http.proxy.host=proxy.example.com
4343
dt.http.proxy.port=8080
44-
dt.no.proxy=localhost,127.0.0.1,example.com
44+
dt.http.proxy.exclusions=localhost,127.0.0.1,example.com
4545
```
4646

4747
## Configuring via standard environment variables
@@ -62,7 +62,7 @@ The API server uses the same proxy for both HTTP and HTTPS upstream calls. URIs
6262

6363
## Bypass list
6464

65-
Both `dt.no.proxy` and `NO_PROXY` accept a comma-separated list of entries. Each entry takes the form of either a
65+
Both `dt.http.proxy.exclusions` and `NO_PROXY` accept a comma-separated list of entries. Each entry takes the form of either a
6666
hostname or IP address, optionally with `:port`. CIDR ranges, IP-address ranges, leading-dot notation, and protocol
6767
schemes are not supported.
6868

@@ -75,15 +75,15 @@ The matching rules are:
7575
- If an entry includes a port (`host:port`), the host must match (exact or subdomain) and the port must match exactly.
7676
- Only `http` and `https` URIs go through the proxy; other schemes always bypass it.
7777

78-
For example, given `dt.no.proxy=example.com,localhost:5432`:
78+
For example, given `dt.http.proxy.exclusions=example.com,localhost:5432`:
7979

8080
- `https://api.example.com/` bypasses the proxy (subdomain match).
8181
- `https://localhost:5432/` bypasses the proxy (host and port match).
8282
- `https://localhost:5433/` goes through the proxy (port mismatch).
8383

8484
## Authenticated proxies
8585

86-
For Basic-authenticated proxies, set `dt.http.proxy.username` and `dt.http.proxy.password`. Avoid placing the password
86+
For Basic-authenticated proxies, set `dt.http.proxy.auth.username` and `dt.http.proxy.auth.password`. Avoid placing the password
8787
in plain text; see [Loading values from files](../../reference/configuration/application.md#loading-values-from-files).
8888

8989
For NTLM-authenticated proxies, supply the username in `domain\username` form. The API server splits on the first

‎docs/guides/administration/configuring-ldap.md‎

Lines changed: 64 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -36,18 +36,18 @@ Enable LDAP and configure the server connection:
3636

3737
```properties linenums="1"
3838
dt.ldap.enabled=true
39-
dt.ldap.server.url=ldap://ldap.example.com:389
40-
dt.ldap.basedn=dc=example,dc=com
41-
dt.ldap.security.auth=simple
42-
dt.ldap.bind.username=cn=dt-service,dc=example,dc=com
43-
dt.ldap.bind.password=changeme
44-
dt.ldap.auth.username.format=uid={0},ou=users,dc=example,dc=com
45-
dt.ldap.attribute.name=cn
46-
dt.ldap.attribute.mail=mail
39+
dt.ldap.server-url=ldap://ldap.example.com:389
40+
dt.ldap.base-dn=dc=example,dc=com
41+
dt.ldap.security-auth=simple
42+
dt.ldap.bind-username=cn=dt-service,dc=example,dc=com
43+
dt.ldap.bind-password=changeme
44+
dt.ldap.username-format=uid={0},ou=users,dc=example,dc=com
45+
dt.ldap.name-attribute=cn
46+
dt.ldap.mail-attribute=mail
4747
```
4848

4949
!!! tip
50-
Dependency-Track substitutes the `{0}` placeholder in `dt.ldap.auth.username.format`
50+
Dependency-Track substitutes the `{0}` placeholder in `dt.ldap.username-format`
5151
with the username entered at login.
5252

5353
### User provisioning
@@ -57,7 +57,7 @@ user logs in. Otherwise, an administrator must create each account before its us
5757
log in.
5858

5959
```properties
60-
dt.ldap.user.provisioning=true
60+
dt.ldap.user-provisioning=true
6161
```
6262

6363
### Team synchronisation
@@ -66,11 +66,11 @@ When enabled, Dependency-Track keeps team membership in sync with LDAP group mem
6666
Map teams to LDAP groups under **Administration > Access Management > Teams**.
6767

6868
```properties
69-
dt.ldap.team.synchronization=true
70-
dt.ldap.groups.filter=(&(objectClass=groupOfUniqueNames))
71-
dt.ldap.user.groups.filter=(&(objectClass=groupOfUniqueNames)(uniqueMember={USER_DN}))
72-
dt.ldap.groups.search.filter=(&(objectClass=groupOfUniqueNames)(cn=*{SEARCH_TERM}*))
73-
dt.ldap.users.search.filter=(&(objectClass=inetOrgPerson)(cn=*{SEARCH_TERM}*))
69+
dt.ldap.team-synchronization=true
70+
dt.ldap.group-filter=(&(objectClass=groupOfUniqueNames))
71+
dt.ldap.user-groups-filter=(&(objectClass=groupOfUniqueNames)(uniqueMember={USER_DN}))
72+
dt.ldap.group-search-filter=(&(objectClass=groupOfUniqueNames)(cn=*{SEARCH_TERM}*))
73+
dt.ldap.user-search-filter=(&(objectClass=inetOrgPerson)(cn=*{SEARCH_TERM}*))
7474
```
7575

7676
!!! tip
@@ -91,18 +91,18 @@ Users typically authenticate with their User Principal Name (`user@domain.com`).
9191

9292
```properties linenums="1"
9393
dt.ldap.enabled=true
94-
dt.ldap.server.url=ldap://ldap.example.com:3268
95-
dt.ldap.basedn=dc=example,dc=com
96-
dt.ldap.security.auth=simple
97-
dt.ldap.bind.username=CN=DT Service Account,DC=example,DC=com
98-
dt.ldap.bind.password=changeme
99-
dt.ldap.auth.username.format={0}@example.com
100-
dt.ldap.attribute.name=userPrincipalName
101-
dt.ldap.attribute.mail=mail
102-
dt.ldap.groups.filter=(&(objectClass=group)(objectCategory=Group))
103-
dt.ldap.user.groups.filter=(&(objectClass=group)(objectCategory=Group)(member:1.2.840.113556.1.4.1941:={USER_DN}))
104-
dt.ldap.groups.search.filter=(&(objectClass=group)(objectCategory=Group)(cn=*{SEARCH_TERM}*))
105-
dt.ldap.users.search.filter=(&(objectClass=user)(objectCategory=Person)(cn=*{SEARCH_TERM}*))
94+
dt.ldap.server-url=ldap://ldap.example.com:3268
95+
dt.ldap.base-dn=dc=example,dc=com
96+
dt.ldap.security-auth=simple
97+
dt.ldap.bind-username=CN=DT Service Account,DC=example,DC=com
98+
dt.ldap.bind-password=changeme
99+
dt.ldap.username-format={0}@example.com
100+
dt.ldap.name-attribute=userPrincipalName
101+
dt.ldap.mail-attribute=mail
102+
dt.ldap.group-filter=(&(objectClass=group)(objectCategory=Group))
103+
dt.ldap.user-groups-filter=(&(objectClass=group)(objectCategory=Group)(member:1.2.840.113556.1.4.1941:={USER_DN}))
104+
dt.ldap.group-search-filter=(&(objectClass=group)(objectCategory=Group)(cn=*{SEARCH_TERM}*))
105+
dt.ldap.user-search-filter=(&(objectClass=user)(objectCategory=Person)(cn=*{SEARCH_TERM}*))
106106
```
107107

108108
!!! tip
@@ -113,43 +113,43 @@ dt.ldap.users.search.filter=(&(objectClass=user)(objectCategory=Person)(cn=*{SEA
113113
For LDAPS (recommended in production), change the port to `3269` and update the URL:
114114

115115
```properties
116-
dt.ldap.server.url=ldaps://ldap.example.com:3269
116+
dt.ldap.server-url=ldaps://ldap.example.com:3269
117117
```
118118

119119
### ApacheDS
120120

121121
```properties linenums="1"
122122
dt.ldap.enabled=true
123-
dt.ldap.server.url=ldap://ldap.example.com:389
124-
dt.ldap.basedn=dc=example,dc=com
125-
dt.ldap.security.auth=simple
126-
dt.ldap.bind.username=uid=admin,ou=system
127-
dt.ldap.bind.password=changeme
128-
dt.ldap.auth.username.format=uid={0},ou=users,dc=example,dc=com
129-
dt.ldap.attribute.name=cn
130-
dt.ldap.attribute.mail=mail
131-
dt.ldap.groups.filter=(&(objectClass=groupOfUniqueNames))
132-
dt.ldap.user.groups.filter=(&(objectClass=groupOfUniqueNames)(uniqueMember={USER_DN}))
133-
dt.ldap.groups.search.filter=(&(objectClass=groupOfUniqueNames)(cn=*{SEARCH_TERM}*))
134-
dt.ldap.users.search.filter=(&(objectClass=inetOrgPerson)(cn=*{SEARCH_TERM}*))
123+
dt.ldap.server-url=ldap://ldap.example.com:389
124+
dt.ldap.base-dn=dc=example,dc=com
125+
dt.ldap.security-auth=simple
126+
dt.ldap.bind-username=uid=admin,ou=system
127+
dt.ldap.bind-password=changeme
128+
dt.ldap.username-format=uid={0},ou=users,dc=example,dc=com
129+
dt.ldap.name-attribute=cn
130+
dt.ldap.mail-attribute=mail
131+
dt.ldap.group-filter=(&(objectClass=groupOfUniqueNames))
132+
dt.ldap.user-groups-filter=(&(objectClass=groupOfUniqueNames)(uniqueMember={USER_DN}))
133+
dt.ldap.group-search-filter=(&(objectClass=groupOfUniqueNames)(cn=*{SEARCH_TERM}*))
134+
dt.ldap.user-search-filter=(&(objectClass=inetOrgPerson)(cn=*{SEARCH_TERM}*))
135135
```
136136

137137
### Fedora 389 Directory Server
138138

139139
```properties linenums="1"
140140
dt.ldap.enabled=true
141-
dt.ldap.server.url=ldap://ldap.example.com:389
142-
dt.ldap.basedn=dc=example,dc=com
143-
dt.ldap.security.auth=simple
144-
dt.ldap.bind.username=cn=Directory Manager
145-
dt.ldap.bind.password=changeme
146-
dt.ldap.auth.username.format=uid={0},ou=people,dc=example,dc=com
147-
dt.ldap.attribute.name=uid
148-
dt.ldap.attribute.mail=mail
149-
dt.ldap.groups.filter=(&(objectClass=groupOfUniqueNames))
150-
dt.ldap.user.groups.filter=(&(objectClass=groupOfUniqueNames)(uniqueMember={USER_DN}))
151-
dt.ldap.groups.search.filter=(&(objectClass=groupOfUniqueNames)(cn=*{SEARCH_TERM}*))
152-
dt.ldap.users.search.filter=(&(objectClass=inetOrgPerson)(uid=*{SEARCH_TERM}*))
141+
dt.ldap.server-url=ldap://ldap.example.com:389
142+
dt.ldap.base-dn=dc=example,dc=com
143+
dt.ldap.security-auth=simple
144+
dt.ldap.bind-username=cn=Directory Manager
145+
dt.ldap.bind-password=changeme
146+
dt.ldap.username-format=uid={0},ou=people,dc=example,dc=com
147+
dt.ldap.name-attribute=uid
148+
dt.ldap.mail-attribute=mail
149+
dt.ldap.group-filter=(&(objectClass=groupOfUniqueNames))
150+
dt.ldap.user-groups-filter=(&(objectClass=groupOfUniqueNames)(uniqueMember={USER_DN}))
151+
dt.ldap.group-search-filter=(&(objectClass=groupOfUniqueNames)(cn=*{SEARCH_TERM}*))
152+
dt.ldap.user-search-filter=(&(objectClass=inetOrgPerson)(uid=*{SEARCH_TERM}*))
153153
```
154154

155155
### NetIQ / Novell eDirectory
@@ -158,18 +158,18 @@ eDirectory typically uses LDAPS on port 636 and an organisation-based DN structu
158158

159159
```properties linenums="1"
160160
dt.ldap.enabled=true
161-
dt.ldap.server.url=ldaps://ldap.example.com:636
162-
dt.ldap.basedn=o=example
163-
dt.ldap.security.auth=simple
164-
dt.ldap.bind.username=cn=admin,o=example
165-
dt.ldap.bind.password=changeme
166-
dt.ldap.auth.username.format=uid={0},ou=users,o=example
167-
dt.ldap.attribute.name=uid
168-
dt.ldap.attribute.mail=mail
169-
dt.ldap.groups.filter=(&(objectClass=groupOfUniqueNames))
170-
dt.ldap.user.groups.filter=(&(objectClass=groupOfUniqueNames)(uniqueMember={USER_DN}))
171-
dt.ldap.groups.search.filter=(&(objectClass=groupOfUniqueNames)(cn=*{SEARCH_TERM}*))
172-
dt.ldap.users.search.filter=(&(objectClass=inetOrgPerson)(uid=*{SEARCH_TERM}*))
161+
dt.ldap.server-url=ldaps://ldap.example.com:636
162+
dt.ldap.base-dn=o=example
163+
dt.ldap.security-auth=simple
164+
dt.ldap.bind-username=cn=admin,o=example
165+
dt.ldap.bind-password=changeme
166+
dt.ldap.username-format=uid={0},ou=users,o=example
167+
dt.ldap.name-attribute=uid
168+
dt.ldap.mail-attribute=mail
169+
dt.ldap.group-filter=(&(objectClass=groupOfUniqueNames))
170+
dt.ldap.user-groups-filter=(&(objectClass=groupOfUniqueNames)(uniqueMember={USER_DN}))
171+
dt.ldap.group-search-filter=(&(objectClass=groupOfUniqueNames)(cn=*{SEARCH_TERM}*))
172+
dt.ldap.user-search-filter=(&(objectClass=inetOrgPerson)(uid=*{SEARCH_TERM}*))
173173
```
174174

175175
---

‎docs/guides/administration/configuring-oidc.md‎

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -34,16 +34,16 @@ for how property names map to environment variables.
3434
```properties linenums="1"
3535
dt.oidc.enabled=true
3636
dt.oidc.issuer=https://idp.example.com
37-
dt.oidc.client.id=dependency-track
38-
dt.oidc.username.claim=preferred_username
37+
dt.oidc.client-id=dependency-track
38+
dt.oidc.username-claim=preferred_username
3939
```
4040

4141
### User provisioning
4242

4343
When enabled, Dependency-Track creates user accounts automatically on first login:
4444

4545
```properties
46-
dt.oidc.user.provisioning=true
46+
dt.oidc.user-provisioning=true
4747
```
4848

4949
### Team synchronisation
@@ -56,8 +56,8 @@ easiest to emit. Map teams to those group names under
5656
**Administration > Access Management > Teams**.
5757

5858
```properties
59-
dt.oidc.team.synchronization=true
60-
dt.oidc.teams.claim=groups
59+
dt.oidc.team-synchronization=true
60+
dt.oidc.teams-claim=groups
6161
```
6262

6363
## Frontend configuration
@@ -101,8 +101,8 @@ etc.) to match your environment.
101101

102102
```properties
103103
dt.oidc.issuer=https://keycloak.example.com/realms/your-realm
104-
dt.oidc.client.id=dependency-track
105-
dt.oidc.username.claim=preferred_username
104+
dt.oidc.client-id=dependency-track
105+
dt.oidc.username-claim=preferred_username
106106
```
107107

108108
### Microsoft Entra ID (Azure AD)
@@ -115,8 +115,8 @@ dt.oidc.username.claim=preferred_username
115115

116116
```properties
117117
dt.oidc.issuer=https://login.microsoftonline.com/<tenant-id>/v2.0
118-
dt.oidc.client.id=<application-client-id>
119-
dt.oidc.username.claim=preferred_username
118+
dt.oidc.client-id=<application-client-id>
119+
dt.oidc.username-claim=preferred_username
120120
```
121121

122122
!!! note
@@ -134,8 +134,8 @@ dt.oidc.username.claim=preferred_username
134134

135135
```properties
136136
dt.oidc.issuer=https://your-tenant.auth0.com/
137-
dt.oidc.client.id=<auth0-client-id>
138-
dt.oidc.username.claim=nickname
137+
dt.oidc.client-id=<auth0-client-id>
138+
dt.oidc.username-claim=nickname
139139
```
140140

141141
### GitLab
@@ -146,8 +146,8 @@ dt.oidc.username.claim=nickname
146146

147147
```properties
148148
dt.oidc.issuer=https://gitlab.com
149-
dt.oidc.client.id=<application-id>
150-
dt.oidc.username.claim=nickname
149+
dt.oidc.client-id=<application-id>
150+
dt.oidc.username-claim=nickname
151151
```
152152

153153
For self-hosted GitLab, replace `https://gitlab.com` with your GitLab instance URL.
@@ -160,8 +160,8 @@ For self-hosted GitLab, replace `https://gitlab.com` with your GitLab instance U
160160

161161
```properties
162162
dt.oidc.issuer=https://accounts.google.com
163-
dt.oidc.client.id=<client-id>.apps.googleusercontent.com
164-
dt.oidc.username.claim=email
163+
dt.oidc.client-id=<client-id>.apps.googleusercontent.com
164+
dt.oidc.username-claim=email
165165
```
166166

167167
!!! warning
@@ -188,8 +188,8 @@ dt.oidc.username.claim=email
188188

189189
```properties
190190
dt.oidc.issuer=https://your-subdomain.onelogin.com/oidc/2
191-
dt.oidc.client.id=<client-id>
192-
dt.oidc.username.claim=preferred_username
191+
dt.oidc.client-id=<client-id>
192+
dt.oidc.username-claim=preferred_username
193193
```
194194

195195
### AWS Cognito
@@ -203,8 +203,8 @@ dt.oidc.username.claim=preferred_username
203203

204204
```properties
205205
dt.oidc.issuer=https://cognito-idp.<region>.amazonaws.com/<user-pool-id>
206-
dt.oidc.client.id=<app-client-id>
207-
dt.oidc.username.claim=cognito:username
206+
dt.oidc.client-id=<app-client-id>
207+
dt.oidc.username-claim=cognito:username
208208
```
209209

210210
---

‎docs/guides/administration/configuring-vulnerability-sources.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -81,10 +81,14 @@ what each mirror is doing.
8181
Each source has its own cron property. Mirrors also run on instance startup. To change the schedule, set the
8282
corresponding property:
8383

84-
- NVD: [`dt.task.nist.mirror.cron`](../../reference/configuration/properties.md#dttasknistmirrorcron)
84+
- NVD: [`dt.task.nvd-vuln-data-source-mirror.cron`](../../reference/configuration/properties.md#dttasknvd-vuln-data-source-mirrorcron)
8585
- GitHub advisories:
86-
[`dt.task.git.hub.advisory.mirror.cron`](../../reference/configuration/properties.md#dttaskgithubadvisorymirrorcron)
87-
- OSV: [`dt.task.osv.mirror.cron`](../../reference/configuration/properties.md#dttaskosvmirrorcron)
86+
[`dt.task.github-advisory-vuln-data-source-mirror.cron`](../../reference/configuration/properties.md#dttaskgithub-advisory-vuln-data-source-mirrorcron)
87+
- OSV: [`dt.task.osv-vuln-data-source-mirror.cron`](../../reference/configuration/properties.md#dttaskosv-vuln-data-source-mirrorcron)
88+
89+
!!! note
90+
The `dt.vuln-analyzer.*` namespace (analyzer extension point) is unchanged.
91+
Only mirror task cron properties were renamed.
8892

8993
## Verifying findings
9094

‎docs/guides/upgrading/.pages‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
title: Upgrade guides
22
nav:
33
- index.md
4+
- v5.0.0-rc.2.md
45
- v5.0.0-rc.1.md
56
- v0.7.0-alpha.9.md
67
- v0.7.0-alpha.8.md

0 commit comments

Comments
 (0)