Offline docs (switch to live docs)                         UI-only         CLI-only

How to report a bug

MAAS bugs are reported via Launchpad. We’ll provide the link in a moment, but first, some necessary prerequisites.

Filing a good bug report makes all the difference in how quickly we can triage and address your problem. This brief how-to guide will walk you through the steps of filing a bug. Some of these steps are necessary preparation, and the better you prepare before you file, the better the bug report.

NOTE: Note that in the examples that follow, a >> symbol indicates the newest line added to the draft report. It isn’t necessary for you to type these characters.

Step 1: Understand what’s required

You need to gather or prepare some information before you file your bug report. Here is the short list of pre-filing tasks that will smooth the process:

Open a text editor with a new file, so you can capture and refine this information in advance.

Prepare a concise summary

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

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

or

MAAS <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

Add this information to your text file.

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 list maas 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✓  -

We want the know the Version field; in this case, that’s 3.0.0~beta2-9796-g.2182ab55f. Add a line like this to your text file:

MAAS fails to PXE boot IBM LPAR machine as VM host

>>I'm using snap version/build 3.0.0~beta2-9796-g.2182ab55f.

If you’re using a debian package

If you’re using a deb, execute apt list maas at the command line, and enter whatever it returns into your text file, as in the snap example above, being sure to specify:

I'm using debian package version/build...

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:

MAAS fails to PXE boot IBM LPAR machine as VM host

I'm using snap version/build 3.0.0~beta2-9796-g.2182ab55f.

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

Explain what happens

Being as concise and specific as you can, explain what seemed to go wrong. For example:

MAAS fails to PXE boot IBM LPAR machine as VM host

I'm using snap version/build 3.0.0~beta2-9796-g.2182ab55f.

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

>>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.

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:

MAAS fails to PXE boot IBM LPAR machine as VM host

I'm using snap version/build 3.0.0~beta2-9796-g.2182ab55f.

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

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.

>>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’ll attach them later on in the process.

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:

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

How to compress these logfiles into a tar.gz file for efficient upload

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:

Step 2: Filing your bug

Have your prepared text file handy. In our example, it looks like this:

MAAS fails to PXE boot IBM LPAR machine as VM host

I'm using snap version/build 3.0.0~beta2-9796-g.2182ab55f.

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

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.

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).

To file a bug, go to the launchpad bug report page↗. You’ll see a screen similar to this one:

Enter your concise summary in the “Summary:” line:

Press enter to get to the next screen:

Paste the rest of your text file into the “Further information” box:

Attach your screenshots and logfiles by opening the “Extra options” section and browsing for your attachments. Ideally, you’d attach the files one at a time, with a comprehensible description.

When you’re done, simply choose “Submit Bug Report” and check your work on the screen that follows:

If you want, you can view a sample bug↗ with precisely these parameters.