Project

General

Profile

Bug #12474

Document troubleshooting tips for more failure scenarios throughout installation assistant

Added by Anonymous almost 3 years ago. Updated 6 months ago.

Status:
Rejected
Priority:
Normal
Assignee:
-
Category:
-
Target version:
-
Start date:
12/05/2017
Due date:
% Done:

100%

Feature Branch:
Type of work:
End-user documentation
Blueprint:
Starter:
Affected tool:

Subtasks

Bug #15016: Explain better how to disable Secure BootRejected


Related issues

Related to Tails - Feature #10286: Boot options documentation: more options could be added Rejected 09/27/2015
Related to Tails - Feature #12644: Allow remembering boot options Rejected 06/06/2017
Related to Tails - Bug #12613: Document Debian testing live image for debugging Resolved 05/29/2017
Related to Tails - Feature #15130: Restructure our support page and content Confirmed 09/28/2013
Related to Tails - Feature #14788: Add anchors to the troubleshooting parts of the installation doc In Progress 10/04/2017
Related to Tails - Feature #15128: Link to Mac known issues from troubleshooting Confirmed 12/27/2017

History

#1 Updated by emmapeel almost 3 years ago

There was a similar discussion a while ago, #10286

#2 Updated by sajolida almost 3 years ago

We had a section about this before removing I2P. See e9d02049b4.

But i2p was the only boot parameter in there.

Do you know of any other boot parameters that would be worth documenting?

#3 Updated by Anonymous almost 3 years ago

There are many others:

  • rootpw=something
  • debug
  • xorg-driver=intel

And I bet there are many others which I don't know about.

#4 Updated by Anonymous almost 3 years ago

As said by intrigeri on https://labs.riseup.net/code/issues/10286#note-1 these options are only useful for debugging and should be on a separate page.

I find this useful for sending the link to people asking for help on tails-support(-private). For example when X does not launch or they are stuck somewhere pre-greeter.

And I find this useful for myself, so it could also just go the contributor documentation.

But maybe it's not that relevant?

#5 Updated by intrigeri almost 3 years ago

  • Related to Feature #10286: Boot options documentation: more options could be added added

#6 Updated by intrigeri almost 3 years ago

  • Assignee set to Anonymous

there is no list of possible boot parameters.

I feel the need to define a narrower scope for this ticket.

Let me start with explicitly putting aside something that can't work, in order to make sure we're on the same page. An exhaustive list of possible boot parameters is:

  • very expensive to build and maintain: /proc/cmdline is world-readable, and many pieces of software we ship can, and do, read it to take into account whatever option they want, e.g. Linux, systemd, live-boot, live-config, Tails Greeter, and probably others I have no idea about. The total number of possible options is already somewhere in the hundreds at least, and it's constantly increasing; besides, we would need to filter the list to include only options we consider safe;
  • not very useful: the list would simply be too big, and too technical, to be actionable by most Tails users.

So I'll assume that this ticket is not about creating and maintaining such a list. Fair enough?

Now, I think there's clearly some room for improvement in the troubleshooting sections (Tails doesn't start at all / entirely) of the installation assistant, in our bug reporting doc, and in our known issues page. A number of these improvements will definitely require documenting some new kernel command-line options. We already do some of this work continuously as problems as discovered, and some of this work is formally on our Help Desk's plate; so IMO the process to document workarounds for very specific issues (e.g. hardware-specific options one has to pass to a kernel module on the boot command line) is rather well covered already.

So, once we've put aside the "exhaustive list" and "workarounds for very specific issues" topics, I think the remaining relevant part of this ticket is about generic debugging steps (sometimes involving boot parameters). Surely some more of these should be documented as part of the generic troubleshooting UX (as opposed to hardware-specific issues that are better suited for the "Known Issues" page). Shall we refocus this ticket this way, and brainstorm what we feel may be missing? I suggest we do this as we go, whenever we identify debugging steps we often guide users through on our support channels, and we can't point them to adequate documentation do to so.

#7 Updated by Anonymous almost 3 years ago

  • Subject changed from Consider documenting possible boot parameters to Improve documentation by providing generic debugging steps we can point users to

intrigeri wrote:

there is no list of possible boot parameters.

I feel the need to define a narrower scope for this ticket.

So I'll assume that this ticket is not about creating and maintaining such a list. Fair enough?

Absolutely. Thanks for making it clear. I was not suggesting to create such an extensive list.

So, once we've put aside the "exhaustive list" and "workarounds for very specific issues" topics, I think the remaining relevant part of this ticket is about generic debugging steps (sometimes involving boot parameters). Surely some more of these should be documented as part of the generic troubleshooting UX (as opposed to hardware-specific issues that are better suited for the "Known Issues" page). Shall we refocus this ticket this way, and brainstorm what we feel may be missing? I suggest we do this as we go, whenever we identify debugging steps we often guide users through on our support channels, and we can't point them to adequate documentation do to so.

Agreed. That is basically why I created this ticket. So let me rename it and find particular examples on what we feel is missing. Please don't hesitate adding your bits.

#8 Updated by Anonymous almost 3 years ago

After re-reading the known issues page, I believe I simply miss another approach to give users simple and readable information:

Basically, there are known issues for specific machines/graphic adapters/USB sticks, which is fine, but no generic information, ordered by problem type instead of hardware model, like:
- i can get until the greeter but can't login
- i end up at a black screen
- i end up at a blue screen after rebooting
- my screen is upside down
- etc.

I also think there is an english issue on the known issues page at several places I have "See troubleshooting section about Tails not starting entirely on PC or Mac." Not "starting entirely" means: "it starts partly", I believe. Maybe we can replace by "not starting at all". I've been fooled myself by this text and was looking for information of Tails getting stuck at the greeter and how I could debug what was going on.

#9 Updated by intrigeri almost 3 years ago

Basically, there are known issues for specific machines/graphic adapters/USB sticks,
which is fine, but no generic information, ordered by problem type instead of
hardware model, like:
- i can get until the greeter but can't login
- i end up at a black screen
- i end up at a blue screen after rebooting
- my screen is upside down
- etc.

I agree the page could be better structured, e.g. by re-using the structure we already have in the troubleshooting part of the installation assistant.
Let's keep in mind though that our Known Issues page is not the primary troubleshooting doc we have, it's rather a catalog of complementary information to the troubleshooting steps we document elsewhere.

#10 Updated by Anonymous over 2 years ago

  • Assignee changed from Anonymous to sajolida

Reassigning to our technical writer.

Please see in particular https://labs.riseup.net/code/issues/12474#note-8 - english issues.

And eventually comment on providing generic debugging steps.

#11 Updated by sajolida over 2 years ago

  • Subject changed from Improve documentation by providing generic debugging steps we can point users to to Document troubleshooting tips for more failure scenarios throughout installation assistant
  • Assignee changed from sajolida to Anonymous
  • QA Check set to Info Needed

I fully agree with intrigeri on #12474#note-6, also with u on #12474#note-8.

My conclusion is that we could add more troubleshooting tips (and maybe sections) to the installation assistant (see https://tails.boum.org/install/win/usb/ and search "Troubleshooting") to cover some of the scenarios pointed out by u in #12474#note-6. Also note that we already have notes about additional kernel command line options in the section "Tails does not start entirely". Maybe we should add more.

Now, I genuinely don't know what are the hot topics that should be put there because I haven't done use support in several years now (partly in an attempt to not be everywhere possible in this project). I also understand that these issues change over time as our graphical stack evolves for example (while the things that we are documenting so far are more static).

In my opinion, providing the relevant information and keeping it up-to-date is the duty of our help desk (see "do whatever small tasks will make the frontdesk job's easier in the future" in https://tails.boum.org/contribute/working_together/roles/front_desk/).

And yes, it should be my duty to structure, format, and integrate this information in the current documentation (outside of Known issues). But we already have some structure to do that and I think we should build upon it.

Still, at this point I can't really work on that until I'm provided with at least a bunch of relevant options or troubleshooting steps to document. Note that debug for example is already documented in "Tails does not start entirely").

→ Trying to rename this ticket accordingly.

NB: In the Installation Assistant I use "_Tails not starting at all_" for "_not getting the Boot Loader Menu_" and "_Tails does not start entirely_" for "_not getting Tails Greeter_" while I understand that you were proposing to use the same phrasing for both in #12474#note-7. I'm happy to discuss this terminology futher if you find it confusing but first I want to make sure that we understand the current state of things in the same way.

#12 Updated by intrigeri over 2 years ago

Still, at this point I can't really work on that until I'm provided with at least a bunch of relevant options or troubleshooting steps to document.

Indeed. With my Foundations Team hat on, I try to let our frontdesk know what the user should try and when, but I'm not in a good position to compile this info.

#13 Updated by sajolida over 2 years ago

#14 Updated by Anonymous over 2 years ago

  • Assignee changed from Anonymous to goupille

So I think we agree that we could improve our troubleshooting documentation.

Dear frontdesk, the next step for this ticket would be to compile the questions that front desk receives most often, in such a manner:

- i can get until the greeter but can't login
- i end up at a black screen
- i end up at a blue screen after rebooting
- my screen is upside down
- etc.

For each topic, we would need a question and basic steps to solve the problem.

It would be sufficient to just copy paste something here and the technical writers can then take care of putting this into shape I believe. So when you're done with compiling some hot topics, please reassign to me or sajolida.

Thanks!

#15 Updated by Anonymous over 2 years ago

  • Related to Bug #12613: Document Debian testing live image for debugging added

#16 Updated by mercedes508 about 2 years ago

  • Status changed from New to Confirmed

#17 Updated by sajolida about 2 years ago

  • Related to Feature #15130: Restructure our support page and content added

#18 Updated by sajolida about 2 years ago

  • Related to Feature #14788: Add anchors to the troubleshooting parts of the installation doc added

#19 Updated by sajolida about 2 years ago

  • Related to Feature #15128: Link to Mac known issues from troubleshooting added

#20 Updated by Anonymous over 1 year ago

@frontdesk: please see my request on https://labs.riseup.net/code/issues/12474#note-14

#21 Updated by Anonymous 12 months ago

@emmapeel, @goupille @mercedes508

Do you think you could reply to my question from one year ago, please? Here it is again:

We agree that we could improve our troubleshooting documentation.

Dear frontdesk, the next step for this ticket would be to compile the questions that front desk receives most often, in such a manner:

- i can get until the greeter but can't login
- i end up at a black screen
- i end up at a blue screen after rebooting
- my screen is upside down
- etc.

For each topic, we would need a question and basic steps to solve the problem.

It would be sufficient to just copy paste something here and the technical writers can then take care of putting this into shape I believe. So when you're done with compiling some hot topics, please reassign to me or sajolida.

Thanks!

#22 Updated by mercedes508 12 months ago

Hey, we've been discusisng this internally but somehow it got lost, so I pinged the team internally to move it forward.

Thanks for the ping.

#23 Updated by goupille 12 months ago

  • Assignee changed from goupille to Anonymous
  • Tails doesn't boot at all / Computer boots on the main OS

    → might be related to secure boot (kind of addressed in the installation troubleshooting notes (although #14788)

  • Tails doesn't get to Greeter / everything is too small on my screen

    → related to GPU error (adressed with the related known issues page)

#24 Updated by Anonymous 12 months ago

goupille wrote:

  • Tails doesn't boot at all / Computer boots on the main OS

→ might be related to secure boot (kind of addressed in the installation troubleshooting notes (although #14788)

→ I've also noticed this often happens on Apfelcomputers and is often due to a stick that has not been correctly installed.
  • Tails doesn't get to Greeter / everything is too small on my screen

→ related to GPU error (adressed with the related known issues page)

→ but a user who has never used Tails does not know what the greeter is I suspect. So their way of seeing this issue is a black screen with text, right?

#25 Updated by Anonymous 12 months ago

  • Description updated (diff)

We now have https://tails.boum.org/support/known_issues that orders problems by hardware used. From https://tails.boum.org/support/ there is no way to get to some information like "My Tails does not start". This information seems to be available only in the installation assistant → where I personally would only look if i did install Tails myself, which might not be the case of many people.

#26 Updated by Anonymous 12 months ago

  • Assignee changed from Anonymous to goupille

@goupille @emmapeel @mercedes508 I think we still lack information from you:

sajolida said:
"At this point I can't really work on that until I'm provided with at least a bunch of relevant options or troubleshooting steps to document."

Could you please also send us the troubleshooting steps for the two items in https://redmine.tails.boum.org/code/issues/12474#note-23 that you send to users?

#27 Updated by goupille 12 months ago

  • Assignee changed from goupille to Anonymous

sorry if that wasn't clear enough... we only thought about those two situations.

About the secure boot one, the doc is already there, probably not read by people that are too quick to reboot, or that do not have a handheld device or another computer to read the doc while rebooting, so I don't see what we can do about that. however, when then come to us, it is painpul to point them to that particular part of the doc because there are no anchors. there is a ticket about that (#14788) that would really ease our job... it could probably be duplicated or linked in /support as well...

About the other one, the gpu issues, when gdm fails, people are displayed with a screen that states their gpu and point them to tails.boum.org/gdm, but a lot of users are not going to this webpage and come to tails-bugs instead, with concerns that are mostly already answered there, so we basically point them to it again. I don't see what to do about it, since, iirc, the number of characters to be displayed is limitated.

if it is another gpu issue (like a display issue), it is usually because their gpu wasn't working in normal mode (so back to the tails.boum.org/gdm case) and the generic driver of the troubleshooting mode is not working well with their gpu. if there are workaround on t.b.o/gdm for that model, I redirect them to it, if not, I try to gather more info (test with debian), open a ticket and assign FT.

#28 Updated by Anonymous 12 months ago

  • Assignee changed from Anonymous to sajolida

@goupille Thanks! I handle that ticket over to @sajolida now, to see if he can do something useful with this information.

#29 Updated by emmapeel 12 months ago

goupille wrote:

→ might be related to secure boot (kind of addressed in the installation troubleshooting notes (although #14788)

Related to secure boot, I opened #15016 a while ago

#30 Updated by sajolida 11 months ago

  • Status changed from Confirmed to Rejected
  • Assignee deleted (sajolida)
  • QA Check deleted (Info Needed)
  • For secure boot, we already have #15016 and Cody is working on it.
  • For graphics cards, we already have a not at the right time in the installation instructions (search for "Error starting GDM with your graphics card").

Sorry but I don't think that this ticket is bring new actionable ideas so I'm rejecting it.

Also available in: Atom PDF