[HOME] [DOWNLOAD] [DOCS] [BLOG] [SUPPORT] [TIPS] [ISSUES] [Priority Support]

Offline Documentation Discussion


#40

No changes. Now it worked. Created a ~ 14 MB file with 1499 pages pdf file that works.


#41

What’s next @HulaHoop?

I guess the current solution does not fulfill the original requirement. It’s generated on the server so you have to trust the server to not create a malicious pdf.

You could replicate whonix.org ( https://www.whonix.org/wiki/Dev/Replicating_whonix.org ) then have your local machine do that. But the replication itself does not give you the same level of security. Or usability. Complicated setup. Checking the code of checking the code against upstreams. Sometimes no gpg signed code etc.

We have markdown wiki backups also. ( https://github.com/Whonix/whonix-wiki-backup )
But these probably are not easily converted into pdf. It’s not a simple markdown to pdf. Due to the wiki templates that we are using. I would wonder if the converter is clever enough to resolve them.


#42

I guess the current solution does not fulfill the original requirement. It’s generated on the server so you have to trust the server to not create a malicious pdf.

True but this PDF is no worse than things now where a malicious server can infect visitors. IMO a static file is a bit better protection.

To reduce risk the PDF can be converted to a simple text file still though I’m not sure how it will look.

But these probably are not easily converted into pdf. It’s not a simple markdown to pdf. Due to the wiki templates that we are using. I would wonder if the converter is clever enough to resolve them.

Have you tried converting with pandoc? If it works then its simple as downloading markup locally, extracting and running the archive thru pandoc.


#43

HulaHoop:

Have you tried converting with pandoc? If it works then its simple as downloading markup locally, extracting and running the archive in pandoc.

pandoc just does simple conversion. Does not understand template and
perhaps other stuff. Just half baked solution.


#44

Then I don’t think the goal of buildable documentation is possible with the current setup like TAILS does unless we imitate their documentation setup - which we don’t do for valid reasons.

A PDF should is easy to inspect for foul play. The situation is no worse with a PDF than it is now.

How reproducible is a file generated from a snapshot of mediawiki pages? Do multiple files have the same hash?


#45

HulaHoop:

A PDF should is easy to inspect for foul play.

Who would look through the giant pdf source file to check it does not
include some weird exploitation code?

How reproducible is a file generated from a snapshot of mediawiki pages? Do multiple files have the same hash?

Just try downloading it multiple times and check. Since we don’t have
minutely edits chances are great no one made an edit between your tries.


#46

I mean when you generate a PDF on the server from a set of pages is the output identical every time?

Who would look through the giant pdf source file to check it does not include some weird exploitation code?

Couldn’t the same be said about the mediawiki source pages?


#47

HulaHoop:

I mean when you generate a PDF on the server from a set of pages is the output identical every time?

How could I run it on the server? Install a browser on the server and
remote VNC (over ssh etc…) to it?

Who would look through the giant pdf source file to check it does not include some weird exploitation code?

Couldn’t the same be said about the mediawiki source pages?

Mediawiki markup is easily readable. At least Whonix maintainers can
keep up reading latest changes and would easily spot exploitation code
within.

Mediawiki html output is not so easily readable. I sometimes look into
parts of it to figure out various stuff and might accidentally spot if
something is very wrong but generally finding malware on a compromised
server is hard.


#48

How could I run it on the server? Install a browser on the server and remote VNC (over ssh etc…) to it?

A few posts back you and fortrasse were testing the pdf plugin on the mediawiki server if I’m not mistaken.


#49

You are mistaken. Installed on the server, yes. But tested just as normal through whonix.org web download.


#50

The print PDF button gives an identical file for the same version of a current page. The next step would be to test if an offline wiki with the PDF plugin gives a file with the same hash for the same page. That would be as close to reproducible as we can get.

So for a given version of the Whonix manual a user would download a snapshot of the wiki tarball (when it was used to generate the official PDF) and setup an offline mediaiwiki and generate a PDF and see if the file matches with the (signed) official one provided.

At the moment Whonix and TAILS are at the same level on this. They just use ikiwiki instead and commits are made via git pull requests instead of the easier mediawiki editing but they don’t have an easy to read file thats reproducible for offline use.

If you think this is too much work forget it.


#51

Subgraph handbook uses:

pandoc / po4a. Text in markdown, build produces multiple formats, translations, etc. Check out the Makefile in the repo.


#52

The PdfBook extension (already installed) supports creating a PDF of all pages in a category that includes documentation. So this can be considered solved.

PdfBook help docs:

https://www.mediawiki.org/wiki/Extension:PdfBook#Usage

Example I followed:

http://www.foo.bar/wiki/index.php?title=Category:foo&action=pdfbook

It works! and gives a 16.6MB pdf. The result OK but needs some cleanup. Translated pages are included sometimes in broken gibberish characters. I would suggest moving each set of translated pages under their own superset categories for example Documentation-DE and so on.

https://www.whonix.org/w/index.php?title=Category:Documentation&action=pdfbook

Up to you if you want to convert the PDF into a simpler format for distribution in Whonix but I wouldn’t bother.


#53

It still needs to be documented. Otherwise no one can know about it.

Would be a break of the security model. I consider pdf a binary format. All binaries for now have been produced locally from source code on my developer hardware. (Except for binary Debian packages which are installed inside VM images as is from Debian repository.) Adding a binary file (the pdf) that I generated from the Whonix web server would break that model.

Also build script and instructions shouldn’t include “go to whonix.org webserver, click there”, to be professional, it needs all to be automated, scripted and from source code.


Maintainer for Whonix Welcome Page
#54

OK lets forget about shipping it with Whonix for now. Where can I add this as optional instructions on the wiki?


#55

It fits nowhere. New page Offline_Documentation?


#56

Done. I suggest linking it under the "Other Whonix Resources " section.


#57

Yes, please do.


#58

Instead of sacrificing ease of contribution or offline documentation quality I propose migrating to Dokuwiki.

Advantages: supports most mediawiki features while being much lighter, allows conversion from mediawiki to their format, databaseless meaning it shouldn’t be a PITA for inclusion in whonix for users to use offline.

Disadvantage: included in every Debian version but stretch though pinning can solve this. I don’t know if its a deal breaker but a php supporting webserver is required. In this case nginx the most minimal, popular and actively developed solution can do.


#59

Not an easy migration. A ton of work.

https://www.whonix.org/wiki/Dev/About_Infrastructure#Whonix_homepage_backend