How to help us help you

Users
1

We are happy to try to help with Discourse requests. We get all kinds of different questions, all the time.

That said, giving us enough information makes all the difference in how quickly we can respond. This brief how-to guide will walk you through the steps of giving us the information we need.

Step 1: Understand what’s required

It helps to prepare some information before you post your question on discourse. Here is the short list of things that will smooth the process:

We’d like to recommend that you start a discourse post, with this page open in another window, and start adding the information below:

Prepare a concise summary

Keep your title short and concise. We recommend something of the form:

<something specific happens> with MAAS <involved feature(s)> on <some version>

or

MAAS <some version> <behaves some unexpected way> when I <try to use a particular feature>

For example:

MAAS fails to PXE boot IBM LPAR machines as KVM hosts on MAAS 3.2

Identify your version and build

We need to know the version and build (and packaging format) that you’re running.

If you're using a snap

If you’re using a snap, execute snap listmaas at the command line, which will return some lines like this:

Name  Version                       Rev    Tracking     Publisher   Notes
maas  3.0.0~beta2-9796-g.2182ab55f  13292  latest/edge  canonical✓  -

Add this output to your budding discourse post.

If you're using a debian package

If you’re using a deb, execute apt list maas at the command line, and add whatever you get back to the discourse post you’re building.

Using CLI, UI, or API?

Next, you’ll need to specify which interface you’re using, and generally what command(s) you were attempting. For example:

I tried to create a VM host using a previously discovered IBM LPAR machine,
via the MAAS UI.

Explain what happens

Being as concise and specific as you can, explain what seemed to go wrong, being sure to add your specific question at the end of the narrative. For example:

I was able to select the machine under "Add KVM," define its parameters,
and select a project.  I was also able to push "Authenticate," and the
expected commissioning process began.  After the machine powered on, though,
the commissioning process timed out trying to PXE boot the machine.  Looking
at the machine, it had indeed been powered on, but nothing happened after that.  What am I doing wrong, if anything?

Explain how to reproduce your issue

In addition to the explanation above, you should create a step-by-step list of what you did to reproduce the problem. For example:

Steps to reproduce:

1. Confirm that at least one IBM LPAR 700 model is discovered and in the
Ready state (see screenshot-1).

2. Select the KVM tab (see screenshot-2).

3. Press the "Add KVM" button.

4. Select the KVM host type according to your network (I selected "<selection>").

5. Enter a name for the KVM host (I entered "<entered-name>").

6. Enter a bridge address to reach the KVM host (I entered "<power-address>").

7. Enter the appropriate password.

8. Press the "Authenticate" button.

9. On the project screen which pops up, select the "default" project.

10. Press the "Add KVM" button.

11. Return to the machine list and find the machine you just added as a KVM.
It should show "Powering on."

12. Watch until the machine enters the "Performing PXE boot" stage.

13. Wait for the machine to time out without reaching "Loading ephemeral"
stage, as normal.

14. Examine the logfiles (see attached logfiles).

Take relevant screenshots

If you think it will help – especially when using the UI – try and capture screenshots of any unexpected results or ambiguous actions. Your goal isn’t to document your experience in pictures, but to provide a visual reference where verbal descriptions fall short. Name these so you can sync them with your explanation (e.g., “screenshot-1”). You can imbed them directly in your discourse post by pasting them there.

[note]
Give them a minute to load after you paste them.
[/note][tabs]

This text will be hidden

[/tabs]

Locate and capture logfiles

If at all possible, capture at least the following logfiles, for the time period surrounding your error situation:

  1. maas.log
  2. regiond.log
  3. rackd.log
  4. the rsyslog file of the affected machine(s), if it exists.

On snap, these files are located as follows:

  • /var/snap/maas/common/log/maas.log
  • /var/snap/maas/common/log/regiond.log
  • /var/snap/maas/common/log/rackd.log
  • /var/snap/maas/common/log/rsyslog/$MACHINE_NAME/$RELEVANT_DATE/messages

If you’re using packages, you’ll find the files in these locations:

  • /var/log/maas/maas.log
  • /var/log/maas/regiond.log
  • /var/log/maas/rackd.log
  • /var/log/maas/rsyslog/$MACHINE_NAME/$RELEVANT_DATE/messages

You may be able to paste these directly into the discourse post (use the “preformatted” tool, or use a form like this one:

 ```
 the text you want to paste.
 ```

You can also paste these into a pastebin (don’t forget to link it), or request a canonical e-mail address from one of the moderators to transmit the logs.

If you want to e-mail them, please compress the logfiles into a tar.gz file for efficient upload transmission. The following animation shows a recommended process for creating a tar.gz file. The mistakes are intentional, so that you’ll know what to do if you forget an option now and then, or forget to use sudo in a step or two:

That’s all there is to it! Be aware that without some of this info, we’ll probably have to ask you for it before we can try to answer you.