Tutorial: connect to a Wi-Fi access point

parulin · February 16, 2026, 10:03pm

After spending some time trying to figure out how to write a proper tutorial for Qubes, I ended up with this:

user/tutorials/connect-to-wifi.rst

tutorials

====================================
Tutorial: connect to a Wi-Fi hotspot
====================================

.. TODO: remove the following admonition

.. warning:: This tutorial is only about Qubes 4.3

Right after installing Qubes OS, connecting to a Wi-Fi hotspot might be the first thing you want to do. Even if you don't want to browse the internet, this would allow you to update the system.

.. note:: **If you use another type of connection** (i.e.: ethernet), you can still follow this tutorial.

First Qubes OS boot
-------------------

In order to start, **let's power on the device where Qubes OS is installed**. A succession of screens are presented to you:

1. **the firmware** of your computer might use the :program:`BIOS` or the :program:`UEFI`), a software independent from Qubes OS. How the screen renders is dependent on your hardware.

2. then another screen provides a list of options. The first one is :guilabel:`Qubes, with Xen hypervisor`. If you do nothing, this option is automatically selected. This software is a **bootloader** and that specific bootloader is called :program:`GRUB`:

This file has been truncated. show original

The HTML output is visible here:

If anyone would like to review it, I would appreciate it. I wrote this text with the idea to contribute to the official docs but I’m not sure if it would be appropriate. For sure, there are a lot of mistakes in it. I’m open to any suggestion, even if someone wants to nitpick. The things that must be wrong are:

the grammar, etc.
the description of the First Qubes OS boot section
Why do we need sys-net? section
the screenshots
the instructions

About the screenshots, I tried to use openQA screenshots, with a custom script, to be able to update and correct them easily. Feel free to suggest anything about them, it should not be difficult if it is a fullscreen screenshot.

Right now, I spent too much time rereading and retrying my own instructions to be able to accurately spot my own mistakes. Feel free to discuss the method, anything.

solene · February 16, 2026, 10:25pm

That’s good work, but it might be surprising coming from me, who is the audience of this? Is there any specific challenge connecting to WiFi? Who is going to follow it from how to not touch grub to boot up to how to connect to a WiFi network?

The content is good, I quickly read it, we could reuse it but I don’t really see a point focusing on how to connect to a WiFi network.

parulin · February 17, 2026, 7:56am

The audience is absolute beginners. I would like this tutorial to be followed by people with no previous Linux knowledge.

Thanks for your comment, you are right : there is absolutely no challenge. The idea is not to achieve something difficult, it’s to learn by doing something. By using this (too) simple task, we can show a beginner how the qubes are isolated, what is dom0, how to create a qube, getting familiar with parts of Qube Manager, etc.

I may be wrong but doing something more useful, while trying to teach something about Qubes OS would be too difficult. There might be a better way, but I have not been able to find it…

I don’t see much relevant part that could be reused outside this tutorial, so I’m curious?

Zrubi · February 17, 2026, 9:59am

It’s more like a getting started with Qubes OS, than ‘just’ connect to a WiFi hotspot.
And Wifi hotspot is a different thing, you just connected to your wifi AP in this guide.

Hotspot is usually found in public places like a Hotel, Airport, and in such places there is some additional steps you might need to do before you can actually reach the internet…

OvalZero · February 17, 2026, 10:03am

I’d change the title as well, good point.

parulin · February 17, 2026, 10:21am

Thanks, I updated the “hotspot” occurrences.

zzy · March 15, 2026, 4:17pm

It’s great that you’ve taken the time to write this tutorial!
I would suggest to rethink the title altogether. This is (as I see it) more like a basic getting started tutorial for Qubes, the part talking about getting connected to a wifi network is just a few paragraphs long in the middle of this tutorial, which can be confusing for users, who are really just keen on seeing how they can connect to a network.
Also, have you considered building on the already existing “Getting started” guide (Getting started — Qubes OS Documentation) where a lot of the basics are covered already? Maybe it would be good to streamline the content and use this merging process to get rid of redundant topics between the linked getting started guide and the one written by you. In my opinion it would be a good investment of your energy to make that more “beginner friendly” if that is the goal here (although honestly I don’t see where the referenced official one would fall short in explaining the concepts of Qubes to users who are new to the platform)

parulin · March 15, 2026, 7:10pm

Thanks for your review.

Why not? But I need to find something more appropriate…

Yes, I have considered this but the Getting started page is more like an overview. With the tutorial I want to teach the user what Qubes OS is by making them do something. I don’t think it fits the Getting started page where you just learn something.