Linux PV / HVM documentation

[desci]

Taking from #1175,

One of the first things I wanted to do on Qubes was to create VMs using Kali, Whonix and other similar distros. Actually, trying to have Kali and Tails on the same environment led me to the Whonix site, which in turn introduced the name "Qubes" for me to begin with.

The page on setting up a Windows 7 HVM was the first step I had to take when trying to figure out the proper path through the docs, until I finally found out the HVM Create page, which I originally expected was one of the first things on the main doc page.

Shouldn't similar newbie specific guides like this be available for Linux users as well? I don't think it is proper to assume that a Linux user has much more knowledge on the matter that a Windows user. I have background of administering Xen servers and I am learning from scratch how to deal with domU on Qubes, seems totally different to me.

My personal opinion is that stuff like Whonix should be in a Paravirtualized domain. However, I would like to use ElementaryOS, Kali and similar specific distros like a user would want to use Windows 7, for instance. So for the general purpose, one of the main things on the main doc page, in my opinion, should be something like "Installing and Using Linux-based PV/HVM AppVMs" or similar.

Edit: just went through the whole HVM Create page and figured out it basically teaches only Windows 7. There should be at least a "Tip: this also works for linux based isos!", or such. Mentioning Ubuntu in the meanwhile seem not enough, I had to go through many pages and now have to reverse read all doing s/Windows 7/Any OS/g inside my mind.

[andrewdavidwong]

Thank you for submitting this issue. However, your description is rather convoluted. I'll try to summarize, and you can tell me if I've understood you correctly or not.

1. Move the HVM Create page higher up on the main doc page.
2. Rewrite the HVM Create page so that it also applies to Linux.
3. Write a page explaining how to make PV domains for other Linux distros.

[andrewdavidwong]

Thank you for submitting this issue. However, your description is rather convoluted. I'll try to summarize, and you can tell me if I've understood you correctly or not.

1. Move the HVM Create page higher up on the main doc page.
2. Rewrite the HVM Create page so that it also applies to Linux.
3. Write a page explaining how to make PV domains for other Linux distros.

[desci]

The HVM Create page is labeled "Creating and Using HVM and Windows Domains (Qubes R2+)" on the main doc page (or ToC), that's why i missed it in the first place, I didn't understand its purpose, so I clicked on other links that seemed more like what I was trying to achieve.

So both your 1 and 2 really leads to:

1. Make it obvious for a lazy eye that Qubes can be used to install Linux distros.

And the number 3 would boil down to:

1. How? Here's How.

Which would lead to Paravirtualization with some kind of link in the beginning leading to HVM.

I should have brought this to the mailing list first 😛 if you help me, I may edit the original post.

[desci]

The HVM Create page is labeled "Creating and Using HVM and Windows Domains (Qubes R2+)" on the main doc page (or ToC), that's why i missed it in the first place, I didn't understand its purpose, so I clicked on other links that seemed more like what I was trying to achieve.

So both your 1 and 2 really leads to:

1. Make it obvious for a lazy eye that Qubes can be used to install Linux distros.

And the number 3 would boil down to:

1. How? Here's How.

Which would lead to Paravirtualization with some kind of link in the beginning leading to HVM.

I should have brought this to the mailing list first 😛 if you help me, I may edit the original post.

[andrewdavidwong]

1. Make it obvious for a lazy eye that Qubes can be used to install Linux distros.
2. How? Here's How.

It sounds like we can accomplish both tasks by creating a new page with the title "Installing other Linux distros" which contains the content you described. Agreed?

if you help me, I may edit the original post.

I'm not sure what you mean. Help you how?

[andrewdavidwong]

1. Make it obvious for a lazy eye that Qubes can be used to install Linux distros.
2. How? Here's How.

It sounds like we can accomplish both tasks by creating a new page with the title "Installing other Linux distros" which contains the content you described. Agreed?

if you help me, I may edit the original post.

I'm not sure what you mean. Help you how?

[adrelanos]

Few comments.

• Related: document TemplateBasedHVM domains #1341
• https://www.qubes-os.org/en/doc/hvm-create/ : Since #712 was implemented, no more command line use should be required to insert the installation CD? Is this worth a separate ticket or fine here?
• Any other uses of command line that is no longer necessary?
• https://www.qubes-os.org/en/doc/hvm-create/ could use a table of contents.

[adrelanos]

Few comments.

• Related: document TemplateBasedHVM domains #1341
• https://www.qubes-os.org/en/doc/hvm-create/ : Since #712 was implemented, no more command line use should be required to insert the installation CD? Is this worth a separate ticket or fine here?
• Any other uses of command line that is no longer necessary?
• https://www.qubes-os.org/en/doc/hvm-create/ could use a table of contents.

[andrewdavidwong]

• https://www.qubes-os.org/en/doc/hvm-create/ : Since #712 was implemented, no more command line use should be required to insert the installation CD? Is this worth a separate ticket or fine here?
• Any other uses of command line that is no longer necessary?

For better or worse, many of our docs use CLI commands instead of QVMM. In some cases, they were written before QVMM had the relevant functionality. In other cases, it's just easier to provide the CLI commands than to provide step-by-step screenshots of QVMM. It's also more precise to say qvm-create win7 --hvm --label green than just to say, "Create a green Windows 7 HVM." Of course, one could simply say both, or provide the CLI command and also say, "You can also do this in Qubes Manager."

[andrewdavidwong]

• https://www.qubes-os.org/en/doc/hvm-create/ : Since #712 was implemented, no more command line use should be required to insert the installation CD? Is this worth a separate ticket or fine here?
• Any other uses of command line that is no longer necessary?

For better or worse, many of our docs use CLI commands instead of QVMM. In some cases, they were written before QVMM had the relevant functionality. In other cases, it's just easier to provide the CLI commands than to provide step-by-step screenshots of QVMM. It's also more precise to say qvm-create win7 --hvm --label green than just to say, "Create a green Windows 7 HVM." Of course, one could simply say both, or provide the CLI command and also say, "You can also do this in Qubes Manager."

[mfc]

I think the CLI thread should be a separate ticket, as it is not specific to the PV / HVM documentation.

[mfc]

I think the CLI thread should be a separate ticket, as it is not specific to the PV / HVM documentation.

[andrewdavidwong]

@adrelanos:

https://www.qubes-os.org/en/doc/hvm-create/ could use a table of contents.

Done.

[andrewdavidwong]

@adrelanos:

https://www.qubes-os.org/en/doc/hvm-create/ could use a table of contents.

Done.

[adrelanos]

Did you consider using an automated TOC generator?

[adrelanos]

Did you consider using an automated TOC generator?

[andrewdavidwong]

Yes, that would be great! Can you point me in the right direction?

[andrewdavidwong]

Yes, that would be great! Can you point me in the right direction?

[adrelanos]

Axon:

Yes, that would be great! Can you point me in the right direction?

I am not experienced with jekyll.

From:
http://jekyllrb.com/docs/plugins/

Table of Content Generator: Generate the HTML code containing a table
of content (TOC), the TOC can be customized in many way, for example you
can decide which pages can be without TOC.

https://github.com/dafi/jekyll-toc-generator

[adrelanos]

Axon:

Yes, that would be great! Can you point me in the right direction?

I am not experienced with jekyll.

From:
http://jekyllrb.com/docs/plugins/

Table of Content Generator: Generate the HTML code containing a table
of content (TOC), the TOC can be customized in many way, for example you
can decide which pages can be without TOC.

https://github.com/dafi/jekyll-toc-generator

[andrewdavidwong]

Thanks, @adrelanos!

However:

Github pages can't use plugins
If you host your jekyll pages on github you can't run plugins, in this scenario you can use a full javascript solution using TOC Generator for Markdown

Looking into the latter now.

[andrewdavidwong]

Thanks, @adrelanos!

However:

Github pages can't use plugins
If you host your jekyll pages on github you can't run plugins, in this scenario you can use a full javascript solution using TOC Generator for Markdown

Looking into the latter now.

[andrewdavidwong]

Hm, can't seem to get this to work despite trying everything suggested in the README, on other guides online, and every other variation I could think of. Maybe our site handles scripts differently or something.

[andrewdavidwong]

Hm, can't seem to get this to work despite trying everything suggested in the README, on other guides online, and every other variation I could think of. Maybe our site handles scripts differently or something.

[desci]

@axon-qubes

---

It sounds like we can accomplish both tasks by creating a new page with the title "Installing other Linux distros" which contains the content you described. Agreed?

Indeed. And that's what I could help with, i think.

---

I'm not sure what you mean. Help you how?

I have no idea why I wrote that, in that way.

[desci]

@axon-qubes

---

It sounds like we can accomplish both tasks by creating a new page with the title "Installing other Linux distros" which contains the content you described. Agreed?

Indeed. And that's what I could help with, i think.

---

I'm not sure what you mean. Help you how?

I have no idea why I wrote that, in that way.

[kulinacs]

I would like to work on this, but I would like to get some input before I rework everything.
Would it make more sense to have the "Creating and using HVM (fully virtualized) domains" rewritten to read more OS agnostic, to better convey that the installation process works with any ISO, not just Windows and Ubuntu. It could then link to the already Windows Specific page "Installing and using Windows-based AppVMs" which could be rebranded as "Windows in Qubes OS", with a Windows specific (pictures and all) example of installing it as an HVM, with a link back to the generalized documentation for clarity. This would leave room in the OS Agnostic Version of "Creating and using HVM (fully virtualized) domains" for multiple examples at the end, possibly Tails, Open/FreeBSD, etc. and allow the merging of Linux HVM tips that seems small and out of place by itself.

[kulinacs]

I would like to work on this, but I would like to get some input before I rework everything.
Would it make more sense to have the "Creating and using HVM (fully virtualized) domains" rewritten to read more OS agnostic, to better convey that the installation process works with any ISO, not just Windows and Ubuntu. It could then link to the already Windows Specific page "Installing and using Windows-based AppVMs" which could be rebranded as "Windows in Qubes OS", with a Windows specific (pictures and all) example of installing it as an HVM, with a link back to the generalized documentation for clarity. This would leave room in the OS Agnostic Version of "Creating and using HVM (fully virtualized) domains" for multiple examples at the end, possibly Tails, Open/FreeBSD, etc. and allow the merging of Linux HVM tips that seems small and out of place by itself.

[andrewdavidwong]

Would it make more sense to have the "Creating and using HVM (fully virtualized) domains" rewritten to read more OS agnostic, to better convey that the installation process works with any ISO, not just Windows and Ubuntu.

Yes, but I think it's already pretty close to that particular goal. There's still a lot of room for improvement for that page, however.

It could then link to the already Windows Specific page "Installing and using Windows-based AppVMs" which could be rebranded as "Windows in Qubes OS", with a Windows specific (pictures and all) example of installing it as an HVM, with a link back to the generalized documentation for clarity.

Do you mean the ability to install Windows as both an HVM and an HVM Template? Yes, I think it's important to clarify the difference there. But it also perhaps points to the need for more general documentation on HVM Templates.

This would leave room in the OS Agnostic Version of "Creating and using HVM (fully virtualized) domains" for multiple examples at the end, possibly Tails, Open/FreeBSD, etc. and allow the merging of Linux HVM tips that seems small and out of place by itself.

Sounds good.

[andrewdavidwong]

Would it make more sense to have the "Creating and using HVM (fully virtualized) domains" rewritten to read more OS agnostic, to better convey that the installation process works with any ISO, not just Windows and Ubuntu.

Yes, but I think it's already pretty close to that particular goal. There's still a lot of room for improvement for that page, however.

It could then link to the already Windows Specific page "Installing and using Windows-based AppVMs" which could be rebranded as "Windows in Qubes OS", with a Windows specific (pictures and all) example of installing it as an HVM, with a link back to the generalized documentation for clarity.

Do you mean the ability to install Windows as both an HVM and an HVM Template? Yes, I think it's important to clarify the difference there. But it also perhaps points to the need for more general documentation on HVM Templates.

This would leave room in the OS Agnostic Version of "Creating and using HVM (fully virtualized) domains" for multiple examples at the end, possibly Tails, Open/FreeBSD, etc. and allow the merging of Linux HVM tips that seems small and out of place by itself.

Sounds good.

[kulinacs]

To better clarify, this is what I'm planning:

Creating and using HVM (fully virtualized) domains

• Document HVM Templates, which addresses #1341
• Explicitly mention in the first section that it works with any ISO to avoid the confusion seen in the original issue
• Move "Installing Windows Tools" section into related links, seems out of place

Installing and using Windows-based AppVMs

• Clarify the difference between HVMs and HVM templates

Linux HVM Tips

(With further thought, I feel the documentation for general HVMs is already quite long, and adding to it may make it hard to use)

• Add sections for popular distros like Ubuntu, Arch
• Expand on Qubes HVM tools, pulling the mailing list information into the documentation

[kulinacs]

To better clarify, this is what I'm planning:

Creating and using HVM (fully virtualized) domains

• Document HVM Templates, which addresses #1341
• Explicitly mention in the first section that it works with any ISO to avoid the confusion seen in the original issue
• Move "Installing Windows Tools" section into related links, seems out of place

Installing and using Windows-based AppVMs

• Clarify the difference between HVMs and HVM templates

Linux HVM Tips

(With further thought, I feel the documentation for general HVMs is already quite long, and adding to it may make it hard to use)

• Add sections for popular distros like Ubuntu, Arch
• Expand on Qubes HVM tools, pulling the mailing list information into the documentation

[andrewdavidwong]

Sounds good to me.

[andrewdavidwong]

Sounds good to me.