Development

Shortcut: 7 steps for publishing a DLA

Debian Long Term Support Security Advisory (DLA)

HOWTO prepare a security update for LTS for casual contributor:

  1. Claim the issue in the security tracker (in dla-needed.txt)

  2. Prepare the update

  3. Test the update

  4. Upload the update

  5. Claim a DLA ID in DLA/list

  6. Announce the update

  7. Publish the Git repository and tags

Contributing to Debian Long Term Support

The Debian LTS team is always looking for more volunteers to do a better job. With more resources, we could for example:

  • support packages that are currently unsupported

  • take care of all Debian packages and not only the most popular ones

  • fix lower priority issues

If you want to get involved in the LTS team and help keep Debian packages secure for 5 years, have a look at this page. We assume that you are already familiar with the repository layout described in LTS/Using and that you are subscribed to the LTS mailing list: http://lists.debian.org/debian-lts/

You can help in many ways:

Test updated packages and report regressions

As a simple user, you can test packages that have been updated (or that are in the process of being updated). If you find a regression (i.e. something that used to work and that no longer works), then please report it to debian-lts@lists.debian.org and put the person who prepared the update in copy (in case they are not subscribed to the list).

Many LTS contributors are looking for testers for their updated packages. They send call for tests on the mailing list, so please subscribe to it and test the packages they provide when you can, and report back whether they work for you.

Prepare security updates for LTS

Caution

You must first get familiar with the Security Tracker before committing.

Claim the issue in the security tracker (in dla-needed.txt)

In order to prevent duplication of effort, make sure the issue is listed in the data/dla-needed.txt file from the security tracker and add your name to it. Normally, packages are triaged by Front Desk in dla-needed.txt first.

dla-needed.txt reflects LTS-specific information, such as who is working on a package, requests for help, or problems encountered.

Do not add packages to dla-needed.txt (bypass front desk by self-triaging) when you are not at front desk. The exception is when front desk is unresponsive (for more than 1-2 working days) or when the issue is really critical and timely release is important (e.g. embargoed issues). In that case, notify front desk about it, and document the bypass reason in the git commit message (for clarity to FD and other contributors).

As mentioned in the previous section, make sure to also review and update the relevant information in data/CVE/list when working on a package for LTS work.

You shall only claim it for the time you do active work. You are expected to actively handle the problem within 2-3 days and then you are expected to announce your intention to upload so others can test it for a few (3-4) more days. If you can not solve the problem within the 2-3 days, then please mention why it takes more time, how far you have gone, the preliminary results and/or free it for someone else to work on it. We do not want people to work on a package for a few hours, wait a few days, work again on it, wait more and so on.

Edit the data/dla-needed.txt file:

$ editor data/dla-needed.txt
$ git commit -m "Claim foo in dla-needed.txt" data/dla-needed.txt
$ git push

If the package you worked on got unclaimed by the coordinators after 2 weeks without new NOTEs, do not just re-claim it, but also add a NOTE about your progress and/or difficulties: add a new NOTE: line with the current date, and detail the progress status (e.g. waiting for feedback from maintainer or fixing multiple testsuite failures, not just WIP). That way the coordinators and other contributors can see whether you’re just working on a lengthy update, lacking time (and could hand over your work to another contributor), or could use additional help.

Claiming multiple packages: generally you’re expected to work sequentially one package after the other, so each update is published ASAP, and other contributors can work in parallel on other packages. If you are blocked waiting for a review (from the maintainer or another LTS contributor), or for long CI tests, you may claim another package. Do add a NOTE on the pending package stating why the work is currently blocked.

Do not claim multiple packages in advance, finish your current package first. If you claim more than 3 packages this will trigger a warning in the coordinators weekly e-mail. It is understood that some versioned packages (e.g. python3.5/.7/.9/.11) require claiming more, and it’s also expected that we keep a good team spirit.

Special case: can’t be fixed

If a CVE is too hard to fix, first unclaim the package in dla-needed.txt and leave a note describing the approach and difficulties.

Then, depending on the difficulties and issue severity, either:

  1. Leave the package for someone else to attempt.

  2. If severity is low, or a work-around exists, tag the issue <ignored> (cf. CVE status list for LTS) then drop the package from dla-needed.txt:

    [bullseye] - SRCPKG <ignored> (Minor issue; Easily worked around by ... hard to backport due to ...)

  3. If the issue is high-severity, a newer version of the package may need to be backported. Discuss this at debian-lts@lists.debian.org and open a backport proposal at lts-updates-tasks.

Prepare the update

Consistency with other Debian dists: to the best of our ability, we want to assist the Security Team and/or maintainers with preparing stable/oldstable updates, if not already done or underway. Sometimes it may make sense for an LTS contributor to update unstable too.

Updates to non-LTS-oldstable, stable and unstable must be coordinated appropriately, through the (O)SRMs, the Security Team, and/or the package maintainers. Ideally, updates will land first in unstable and then progressively in older releases. However, in the case of an SPU, which may be held for weeks until the next bimonthly stable point release, it’s appropriate to proceed with the LTS update once the SRMs validated the SPU.

If you are not able to get in touch with the maintainer, that the maintainer is not very responsive, or that there is some other extenuating circumstance (e.g. package was just recently updated and another update again would be too soon, or the package exists under a different name in newer releases, or that a full upstream point release update may be needed, etc.), then the best thing is to bring up the issue on the mailing list, with as much detail as you are able to provide. There the issue can be discussed among the team and we can come to a consensus on the best path forward.

Attention

Do not triage CVEs for releases managed by the Security Team (stable/non-LTS-oldstable), nor add entries to dSa-needed.txt.

Assess what needs to be fixed: properly and carefully assess the remaining open/untriaged CVEs, following CVE triage. Consider fixing any <no-dsa> or <postponed> issues for that package (unless that’s a lot of work, in which case leave the least severe ones for a next update). Issues marked as <ignored> shall generally be ignored as there are valid reasons not to fix the issue.

Git repository: your work should be published either in the package maintainers’ repository, or in a fork on Salsa. See Git workflow for details.

Backport the fixes to the version in LTS.

Make sure that each fix was approved by the upstream project (e.g. committed to their development repository), sometimes early patch proposals are erroneous or incomplete.

If there is no fix, it is fine to develop a new one: be a good citizen and propose the patch back upstream, open a BTS bug for the CVE if not already present, reference your patch in that report and link it in the security tracker.

(If the issue being addressed requires AddressSanitizer in order to reproduce the vulnerability and confirm the fix, then check Code Sanitizers).

If the fix comes with new binary files (e.g. test cases), they won’t be accepted by quilt, but you can reference them in debian/source/include-binaries and they’ll be included in the .debian.tar.xz file directly (discussion). When working with old (1.0) format, include-binaries is not supported, so either store a base64 version of the file that you’ll unpack on test or build, or try to make a patch with diff -a (not compatible with quilt refresh, but works with push/pop).

debian/changelog entry: initialize the entry with the text “Non-maintainer upload by the LTS Security Team.”, which you can do with dch --lts (since buster). Do not use -s and otherwise ensure it doesn’t look endorsed by the Debian Security Team.

Set the target distribution to “bullseye-security”.

The versioning follows the conventions already used at security.debian.org:

  • If a package already e.g. had a +deb11u1 update, use +deb11u2 for the next update.

  • If a package hasn’t seen an update, use +deb11u1 for the next update.

  • For the rare case where a new upstream version is introduced:

    • Make sure to use a lower version than in bookworm, such as -0+deb11u1 or ~deb11u1, see this discussion. Just don’t append +deb11uX as this will cause upgrade problems!

    • Reset to deb11u1, regardless how many uploads were previously done.

  • Note: historically codenames have been used as version suffixes (e.g. +squeezeX), but this was changed as dist versions can be sorted.

When working on multiple dists, do not copy/paste the changelog date, as it sets SOURCE_DATE_EPOCH. This makes it more likely to ship files with the same date and the same size, but different content, across multiple dists. This needlessly confuses tools such as rsync. We suggest using dch -r/--release to finalize the changelogs and use a unique date.

BTS numbers can be referenced but are currently not processed.

Note that for non-native packages, first uploads to security-master need to include the source tarball (even if it’s already present in the distribution you’re uploading to) by using dpkg-buildpackage -sa; check at http://security.debian.org/pool/ or try rmadison -u qa PACKAGE.

See also Building the final .dsc to properly generate the *_source.changes to be uploaded.

Building: we want a clean and isolated build, close to the Debian buildd setup, to identify build issues before the upload.

See Technical workflows for technical setups.

Salsa: if you’re using salsa-ci and lts bullseye pipeline, Salsa can build your package for many architectures. It uses combined indep+arch though, unlike buildds, and can be hard to debug.

See also: Debian Developer’s Reference - Preparing packages to address security issues

Test the update

Salsa-CI can run many tests for you. Pros: this is automatic when working from Salsa Git. Cons: failures are hard to debug; some tests are currently (2025-02) run with unstable versions of the tools, rather than LTS’.

Don’t just run the automated tests. You should have an LTS VM to install the package in; perform at least basic (“smoke”) testing, make targetted testing for the features you patched, check for regression in reverse-dependencies.

See Test Suites for package-specific test instructions.

Test suites: if there’s a built-in test suite, make sure it runs fine at build-time in the LTS environment. It is acceptable to enable or even backport test suites from later releases if they are available. Conversely push your testsuite fixes and improvements to unstable or even stable.

DEP-8 tests in debian/tests/, if any, can be run and debugged manually with autopkgtest.

Reverse-dependencies: install some of the reverse dependencies, to test if you update didn’t break other packages. See reverse dependencies to identify them.

Running their own DEP-8 tests like ci.debian.net helps too. debusine.debian.net is working on this as well (2025-10). ci.freexian.com and debusine.freexian.com provide similar checks for ELTS.

Other architectures: it is worth testing with both a 32- and 64-bit architecture, see e.g. CVE-2019-14866.

To debug a build in an architecture you don’t have access to, you may use a porterbox, see PorterBoxHowToUse. Alternatively you may use debvm to easily create minimal test VMs, though they may be very slow as they won’t use KVM.

Source checks: inspect overall source changes since last release with debdiff, see manual CI tests.

Reviews: you’re encouraged to seek reviews from interested parties (such as upstream authors, Debian maintainers, security team, LTS team, etc.). When you do, please supply the following information:

  1. A generated debdiff against the previous version in LTS.

  2. A link to a test package that can be downloaded and tested.

For the LTS Team, you can use the lts-updates-tasks template.

It is common for LTS contributors to provide packages through Salsa artifacts, or to upload to a personal repository such as people.debian.org. A few guidelines for those temporary uploads:

  • sign the packages (using debsign, for example) so that users can verify package integrity

  • make sure to have the target distribution set to UNRELEASED so that nobody else can upload them before they are ready.

Upload the update

We recommend a 2-step upload:

  • debusine.debian.net for building and testing the package in a staging area, allowing you to address build and test failures before the official upload;

  • security-master to upload it to the official Debian archive.

For debusine, follow wiki:DebusineDebianNet:

dput debusine.debian.net hello_1.0-1+deb11u1_source.changes

If you’re satisfied with the build and tests, you can make debusine upload the package to security-master for you, or you can upload it directly:

dput security-master hello_1.0-1+deb11u1_source.changes

Attention

In both cases, uploads to Debian LTS at security-master do not wait for a DLA, CI checks or any other manual intervention before being installed into the Debian archive. In this regard, they are different from stable security uploads.

Once the upload is detected, an email will be sent to you and to the debian-lts-changes mailing list, confirming the update has been accepted. The BTS bot will also announce it in the #debian-devel-changes channel. (wait for ~30mn)

The package will then be re-built for all the supported architectures by the Debian buildds (even if it was already built by debusine). Monitor the build logs at:

Troubleshooting:

Built-Using refers to non-existing source package: if your package is rejected with this reason, open a bug against package ftp.debian.org requesting to add the missing package, see e.g. #974877 or #974954. For the same reason, the package may also be accepted but then unexplicably stalls in the “Uploaded” (not “Installed”) stage in the buildd status (#1033604).

Non-free packages: currently (2022-01-19) buildds won’t build source-only uploads to security-master (a bug, according to Aurélien Jarno), impacting packages such as amd64-microcode and firmware-linux-nonfree. Instead, upload the full “source-code” + the amd64 binary packages (build with -sa and upload the _amd64.changes file); then upload only the i386 binary packages (dpkg-buildpackage -b; or use changestool from reprepro to exclude unwanted files from the changes file).

Flaky build: see Requesting wanna-build actions if your package failed to build and you need a gb/giveback/give-back. Only do this if the build failure can’t actually be fixed cleanly.

Claim a DLA ID in DLA/list

Once your upload has been successfully re-built and published in the Debian archive, you can go ahead with the DLA.

Please make an effort to send out announcement for anything released via security.debian.org with not too much delay. There are all kinds of processes by people out there who react on those emails, and there are also people who get suspicious if an update is available without a corresponding announcement.

Run bin/gen-DLA in the top directory of the Git repository. It automatically generates an entry in data/DLA/list and asks you to commit the changes to ensure that no IDs are used twice. The following command would add an entry for src:hello fixing CVE-2014-0666 and creates an advisory template in the top directory of your security-tracker checkout.

$ DEBFULLNAME=xxx bin/gen-DLA --save hello CVE-2014-0666
# OR
$ DEBFULLNAME=xxx bin/gen-DLA --save .../hello_1.2-3+deb11u4_source.changes

That list of CVE will make sure that the security tracker is aware of the fix and mark the issues as resolved for that specific package.

gen-DLA will automatically remove prior suite triage for the fixed vulnerabilities (e.g. [bullseye] - package <postponed>). However, the DLA-XXXX-1 annotation will be added by the bi-daily cron, and the fixed version will be inferred automatically (don’t add it).

Announce the update

Only send the DLA to the mailing list when you have confirmed that the package was processed and built on all supported architectures.

Send mail to the debian-lts-announce mailing list. The mail needs to be signed by a GPG key in the debian or debian-maintainers keyring. Inline signatures always work (PGP/MIME check works with mutt but fails with Thunderbird).

The advisory template has been created by bin/gen-DLA (see before) and generally looks like this:

Subject: [SECURITY] [DLA $DLA-1] $SOURCEPACKAGENAME security update

Package        : $SOURCEPACKAGENAME
Version        : $LTS_VERSION
CVE ID         : CVE-2014-0001 CVE-2014-0002
Debian Bug     : 12345

DLA text goes here
[...]

In addition to describing the vulnerabilities, remember to add a short package description, so the audience can better understand the context and whether they are affected.

Please also don’t append your personal signatures to DLAs.

If you use mutt, a simple way to send it is to use

mutt -e "unset signature" -H DLA-123

Simple mail command works:

cat DLA-_BODY_.txt \
  | gpg --clearsign \
  | mail -s "[SECURITY] [DLA XXXX-X] $SOURCEPACKAGENAME security update" \
         -r "You <you@debian.org>" \
         debian-lts-announce@lists.debian.org
Official documentation:

When all this is done, you should remove the package from other locations it was uploaded to in the test section, if any.

Publish the Git repository and tags

Cf. Git workflow.

You may verify using the coordinator’s check:

$ bin/coordinator/check-advisories --lts --days 1 --check-git-tag

Prepare regression updates for LTS

If an upload introduces a regression, it needs to be fixed as soon as possible.

Steps for a regression update

  1. Fix the package.

  2. Do a test build and test installation. Verify the regression issue and also the original issue are really resolved now.

  3. Make sure you use a clean chroot for building. Using sbuild/pbuilder is recommended.

  4. Upload the fixed package to bullseye-security.

  5. Use gen-DLA script to add a DLA entry to data/DLA/list and to provide you with an announcement email template. Two possible options:

  1. The regression fixes the previous upload of the package:

$ bin/gen-DLA  --save $SOURCEPACKAGENAME regression

  1. The regression fixes an earlier than the previous upload of the package:

$ bin/gen-DLA  --save $PREVIOUS_DLA_ID $SOURCEPACKAGENAME regression
# /!\ $PREVIOUS_DLA_ID needs to be incremented (-1 -> -2)...

  1. If this is a security regression (e.g. incomplete or missing fix), reference the CVE ID in the data/DLA/list entry, otherwise (functional regression) do not reference it.

  2. Wait for the uploaded package to arrive in the bullseye-security repository.

  3. In the base folder of the security-tracker Git repository, you can find an auto-generated LTS announcement template file with name DLA-$DLA-{2,3,4...}. Use this file as the template for your regression fix announcement. Don’t commit this file to Git(!). Copy+paste the announcement template to your email application, complete/edit it manually and finally send the regression fix DLA email to debian-lts-announce@lists.debian.org.

  4. Note: if a DLA requires a fix in another package, use the same DLA major number (see this mail)

Switching to the next LTS release

  • Send a reminder to debian-lts-announce@lists.debian.org two months before the official support for the last LTS ends.

  • Contact the Teams/Publicity and draft an announcement that the old LTS release cycle has come to an end and a new one has started. Example, Example 2

  • Contact the Stable Release Managers for coordinating the date of the last point release (and so that they can clean up the proposed updates queues).

  • Ensure that the infrastructure is ready for the new LTS release: * Contact the FTP master team to ask them to open the oldstable-security upload queue when we take over from the Security Team.

  • Contact the FTP team and ask them to wait four weeks with archiving the old LTS release to give users a “grace period” to update their systems.

  • Contact the Buildd team to ask them to shutdown the build queues for the old LTS release.

  • Request from the Security Team a copy of the oldstable build logs, remove from them the logs of non-LTS architectures, and ask the Wanna-build team to make them (the LTS-related logs) public. (e-mail)

  • Update all relevant pages especially LTS/Using, LTS/Installing and this LTS/Development itself.

  • Check/update/merge security-support.debX in debian-security-support

    • Follow debian-security-support’s README.source

    • We shouldn’t just forward-port the EOL list, i.e. if the only reason to not support something is “we didn’t support it in previous releases”, then we should support it.

    • Also check for missing/pending EOLs announced in recent DSAs, e.g. grep 'discontinued' -r webwml/english/security/202*

    • Request team members / sponsors opinion, e.g. EOL candidates for security-support-ended.deb10

  • Update/verify the contents of data/packages/lts-do-call-me and data/packages/lts-do-not-call in the security tracker.

  • Reference pending proposed-updates in data/dla-needed.txt to prevent conflicts

Switching to the next Stable release

  • Update debian-archive-keyring for LTS (skipping one release during dist-upgrades is quite common); also needed as a work-around for #992966 (simple-cdd) at the moment.

Housekeeping Tasks

There are several tasks where we base our work on the work of the security team and where we can support them - especially when there are no open issues in dla-needed.txt. This will lead to more packages to fix:

  • Easy: Add bug references for issues unfixed in unstable. Check unreported issues in unstable, recheck them and file a bug if not already there. This makes sure we don’t regress in unstable with bugs fixed in stable, oldstable. You can use the bin/report-vuln script to generate a template report to be further edited with reportbug or a MUA. In case you don’t use reportbug to further submit the bugreport, please X-Debbugs-CC team@security.debian.org and secure-testing-team@lists.alioth.debian.org. This is done automatically if using reportbug.

  • Hard: Check TODO items from the tracker. Be sure to only mark items as NOT-FOR-US when you’re sure the software is not contained in Debian in any form.

Tips & tools