Re: Resurrecting the Securing Debian Manual

["Dave P." <dprowseus@gmail.com>]

There is some good discussion here. I have some comments for those interested:

First, many thanks to Javier for building the Securing Debian Manual. That was a massive undertaking, and it is well-written and organized. I used it frequently between 2015 and 2017, and it helped me better secure some Dell R-series servers running Debian. It was invaluable. I haven't used it since 2020 or so, but it was a great help to me in the past.

Javier is the writer and the maintainer, and has put a lot of work into the manual and the repository at salsa.debian.org over the past decade.

When some people see the 2012 copyright notice at the beginning of the manual, they might think it is outdated/abandoned. Based on Salsa, and the response from Javier, it obviously is not abandoned. However, some of the content is outdated. A quick search will prove this to be true. For example, 4.11.2 Password security in PAM discusses SHA-512 (and Debian Squeeze).

Personally, I don't mind editing within a git-based repository, be it XML or whatever. (And now that I see the omission of yescrypt, I'll commit to 4.11.2.)

However, in my experience, people are more likely to contribute in WYSIWYG-based editors than in Git-based ones. It is most definitely easier to edit that way.

That said, it is possible to create a dedicated manual section in a Wiki-based site. However, I could imagine some structural/search difficulties. Also, reformatting the entire manual (and the entire process in general) could end up being more than a person bargains for. Anyone who has administered a Wiki in the past can attest to this.

Regardless of the updating method, I think the lack of updates in the manual is part of a trend. In my opinion, the entire Debian Wiki (and much of the community - myself included) is guilty of this; especially regarding Debian security. Simply compare the Debian Wiki to the Arch Wiki and you will see my point.

So, I agree that editing in a Wiki-based format is easier; however, it doesn't necessarily mean people will do it! 

Realizing all this, I resolve to commit/edit more. 😀

Ultimately, Javier is the writer and maintainer of this manual. It is GPL, which of course means that anyone could copy/modify/re-create/etc...
However, a word of caution: updating/recreating a manual of this proportion is a big proposition. Trust me on this - I know!

For now, I suggest the following:

- Get as many people on board as possible and commit to the current manual - but only important, Debian-related, security topics.

- Build a nice list of security items that are specifically Debian-centric. For example, the aforementioned yescrypt, nftables in Debian, sshd_config in Debian, etc... (many of these have been listed already in the thread). Divvy those topics up amongst those who wish to participate. This can help to organize the process.

- Consider some sort of search tool for the current manual. That is sorely missing.

- Create a test, dedicated manual section in the Debian Wiki (or any test Wiki), and convert a portion of the XML files into the Wiki - just to see what we would be up against. 😉

If, at the planning stage, it all appears to be a bit too much, then I think the community should simply consider building/updating specific Debian-centric, security-related topics within the main Debian Wiki. As mentioned, this is a sore spot in the Wiki and should probably be addressed regardless.

As I mentioned, I'm willing to invest some time into this, in whatever way Javier and the community decide to proceed. I think Debian and the Securing Debian Manual are worthwhile efforts. I've worked with boatloads of documentation in the past, and would love to help.

And thanks for reading my super-long email!

Dave

On Tue, Jun 10, 2025 at 5:52 PM Javier Fernandez-Sanguino <jfs@debian.org> wrote:

On Tue, 10 Jun 2025 at 22:57, Noah Meyerhans <noahm@debian.org> wrote:

On Tue, Jun 10, 2025 at 09:57:43PM +0200, Javier Fernandez-Sanguino wrote:
>    Moving the manual to a Wiki could be an option but I would rather first
>    have an updated version/content using the current package/toolset and then
>    consider moving it to a wiki.

The current format is arcane and presents a barrier to contributors.
I'm not sure that working within the existing structure (either markup
or content) is worthwhile at this point.

I'm not fully convinced that the current format is a barrier to contributors as the Debian website uses WML and this has not hindered contributions. When I've received snippets of text (even if unformatted form) I have gladly included them in the manual. The XML files available in Sala (https://salsa.debian.org/ddp-team/securing-debian-manual/-/tree/master/en-US?ref_type=heads) can be forked/edited quickly by anybody who has just a basic notion of HTML.  However, the BTS and merge requests in the last 10 years shows that the number of people willing to put the work and actually write / contribute is low.

I personally also see some advantages to the current format (including nice printable versions as well as easy translations via PO files) which would be lost if the content is moved to a Wiki format.

In any case, I would suggest that the best approach to improve the manual would be to first update the existing content in its current format, get it to a good enough shape that it can be shipped back into Debian proper and *then* consider moving it to Debian's Wiki.

 

>    Alternatively, somebody could start writing in the wiki different sections
>    related to hardening specific services and, once mature/finished, move it
>    to the manual.

Yeah, this may be reasonable.  Holger's example of the DebianEdu docs
might be a good one to follow.

I'm not aware of what was done in DebianEdu (any ponter's), but I'm open to trying alternative approaches.

>    Personally I think that the manual :
>
>    - Should not cover in details the principles you mention. There is enough
>    literature out there that it does not make sense to describe what other
>    sources (books / sites) provide better info on (it is manual, not a book!)

I understand your point.  However, as Schneier and others have observed,
security is a process, not a product (and not a checklist).  In order to
adapt to changes with security implications, an admin will need to
understant topics like threat modeling in order to react react
appropriately.  We don't want to provide a set of receipes/checklists
and leave the reader with a sense that they're done when they've
completed them.  I would expect to provide basic content on these
topics, but to link to external resources for further reading.  So I
think we probably agree; the question will be how to figure out how much
detail to include, and when to refer out to some other document.

I'm not opposed to having a section in chapter 2 (Before you begin) giving guidance to administrators on how to approach the problem. As you said, providing basic guidance and pointing to proper resources.

Actually, I think that this discussion on the potential approaches / rewrite and potential distribution of sections / workload could be well suited to be documented in a Wiki :)

 

>    - Should maybe focus only on specific use cases (eg setting up a server)
>    rather than trying to cover all potential use cases (eg desktop) unless
>    there are enough "hands" working on it

Broadly speaking, I'd say that the two most common use cases can be
classified as either "a system that's always online and offers network
services" and "a system that runs a web browser and other interactive
applications", and we should be able to cover those.  We can get more
granular or broaden the scope later, as needed.

Agreed. Although the current manual is more focused on the first use case in my opinion. It would require a mejor rewrite to fit multiple use cases.

 

>    Those thoughts aside I would be glad to help in pushing patches / new
>    versions of the manual to the archive if people start actively
>    contributing to it.

...this is exactly what I mean by centrally maintained. :)  The wiki
eliminates the need for merge requests, approvers, etc.

I was referring to the current status quo in which there is one package and a common repository (in salsa). If somebody wants to improve it *now* and help fix the issues raised in the BTS or add new content this would be the way to go about it.

Best regards

Javier