From ac5c17a2fb1cc726af8411305167590209b60b79 Mon Sep 17 00:00:00 2001 From: Peter Krempa Date: Mon, 7 Mar 2022 14:39:24 +0100 Subject: [PATCH] docs: Convert 'bugs' page to rST MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Special care is given to preserve the 'quality' anchor in the 'bugs' page as we link to it directly from the gitlab issue template. Signed-off-by: Peter Krempa Reviewed-by: Ján Tomko --- docs/bugs.html.in | 161 ---------------------------------------------- docs/bugs.rst | 125 +++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 126 insertions(+), 162 deletions(-) delete mode 100644 docs/bugs.html.in create mode 100644 docs/bugs.rst diff --git a/docs/bugs.html.in b/docs/bugs.html.in deleted file mode 100644 index 400c423518..0000000000 --- a/docs/bugs.html.in +++ /dev/null @@ -1,161 +0,0 @@ - - - - - -

Bug reporting

- -
    - -

    Security Issues

    - -

    - If you think that an issue with libvirt may have security - implications, please do not publicly - report it in the bug tracker, mailing lists, or irc. Libvirt - has a dedicated process for handling (potential) security issues - that should be used instead. So if your issue has security - implications, ignore the rest of this page and follow the - security process instead. -

    - -

    Bug Tracking

    - -

    - If you are using libvirt binaries from a Linux distribution - check below for distribution specific bug reporting policies - first. -

    - -

    General libvirt bug reports

    - -

    - Bugs in upstream libvirt code should be reported as issues in the - appropriate project on GitLab. - Before submitting a ticket, check the existing tickets to see if - the bug/feature is already tracked. -

    -

    - It's always a good idea to file bug reports, as the process of - filing the report always makes it easier to describe the - problem, and the bug number provides a quick way of referring to - the problem. However, not everybody in the community pays frequent - attention to issues, so after you file a bug, asking questions - and submitting patches on the libvirt - mailing lists will increase your bug's visibility and - encourage people to think about your problem. Don't hesitate to - ask questions on the list, as others may know of existing - solutions or be interested in collaborating with you on finding - a solution. Patches are always appreciated, and it's likely - that someone else has the same problem you do! -

    -

    - If you decide to write code, though, before you begin please - read the contributor guidelines, - especially the first point: "Discuss any large changes on the - mailing list first. Post patches early and listen to feedback." - Few development experiences are more discouraging than spending - a bunch of time writing a patch only to have someone point out a - better approach on list. -

    - - - -

    - Note bugs in language bindings and other sub-projects should be - reported to their corresponding git repository rather than the - main libvirt.git linked above. -

    - -

    Linux Distribution specific bug reports

    -
      -
    • - If you are using binaries from Fedora, enter - tickets against the Fedora product and - the libvirt component. - -
      • -
    • -

      - If you are using binaries from Red Hat Enterprise - Linux, enter tickets against the Red Hat Enterprise - Linux product that you're using (e.g., Red Hat Enterprise - Linux 6) and the libvirt component. Red Hat - bugzilla has additional guidance about getting support if - you are a Red Hat customer. -

      -
      • -
    • -

      - If you are using binaries from another Linux distribution - first follow their own bug reporting guidelines. -

      -
      • -
    • -

      - Finally, if you are a contributor to another Linux - distribution and would like to have your procedure for - filing bugs mentioned here, please mail the libvirt - development list. -

      -
      • -
    - - -

    How to file high quality bug reports

    - -

    - To increase the likelihood of your bug report being addressed it is - important to provide as much information as possible. When filing - libvirt bugs use this checklist to see if you are providing enough - information: -

    - -
      -
    • The version number of the libvirt build, or SHA1 of the GIT - commit
      • -
    • The hardware architecture being used
      • -
    • The name of the hypervisor (Xen, QEMU, KVM)
      • -
    • The XML config of the guest domain if relevant
      • -
    • For Xen hypervisor, the domain logfiles from /var/log/xen and - /var/log/libvirt/libxl
      • -
    • For QEMU/KVM, the domain logfile from /var/log/libvirt/qemu
      • -
    - -

    - If the bug leads to a tool linked to libvirt crash, then the best - is to provide a backtrace along with the scenario used to get the - crash, the simplest is to run the program under gdb, reproduce the - steps leading to the crash and then issue a gdb "bt -a" command to - get the stack trace, attach it to the bug. Note that for the - data to be really useful libvirt debug information must be present - for example by installing libvirt debuginfo package on Fedora or - Red Hat Enterprise Linux (with debuginfo-install libvirt) prior - to running gdb.

    -

    - It may also happen that the libvirt daemon itself crashes or gets stuck, - in the first case run it (as root) under gdb, and reproduce the sequence - leading to the crash, similarly to a normal program provide the - "bt" backtrace information to where gdb will have stopped.
    - But if libvirtd gets stuck, for example seems to stop processing - commands, try to attach to the faulty daemon and issue a gdb command - "thread apply all bt" to show all the threads backtraces, as in:

    - 
     #  ps -o etime,pid `pgrep libvirt`
-... note the process id from the output
-# gdb /usr/sbin/libvirtd
-.... some information about gdb and loading debug data
-(gdb) attach $the_daemon_process_id
-....
-(gdb) thread apply all bt
-.... information to attach to the bug
-(gdb)
-
    - - - diff --git a/docs/bugs.rst b/docs/bugs.rst new file mode 100644 index 0000000000..152d734592 --- /dev/null +++ b/docs/bugs.rst @@ -0,0 +1,125 @@ +.. role:: anchor(raw) + :format: html + +============= +Bug reporting +============= + +.. contents:: + +Security Issues +--------------- + +If you think that an issue with libvirt may have security implications, **please +do not** publicly report it in the bug tracker, mailing lists, or irc. Libvirt +has `a dedicated process for handling (potential) security +issues `__ that should be used instead. So if your issue +has security implications, ignore the rest of this page and follow the `security +process `__ instead. + +Bug Tracking +------------ + +If you are using libvirt binaries from a Linux distribution check below for +distribution specific bug reporting policies first. + +General libvirt bug reports +--------------------------- + +Bugs in upstream libvirt code should be reported as issues in the appropriate +`project on GitLab. `__ Before submitting a ticket, +check the existing tickets to see if the bug/feature is already tracked. + +It's always a good idea to file bug reports, as the process of filing the report +always makes it easier to describe the problem, and the bug number provides a +quick way of referring to the problem. However, not everybody in the community +pays frequent attention to issues, so after you file a bug, asking questions and +submitting patches on `the libvirt mailing lists `__ will increase +your bug's visibility and encourage people to think about your problem. Don't +hesitate to ask questions on the list, as others may know of existing solutions +or be interested in collaborating with you on finding a solution. Patches are +always appreciated, and it's likely that someone else has the same problem you +do! + +If you decide to write code, though, before you begin please read the +`contributor guidelines `__, especially the first point: "Discuss +any large changes on the mailing list first. Post patches early and listen to +feedback." Few development experiences are more discouraging than spending a +bunch of time writing a patch only to have someone point out a better approach +on list. + +- `View libvirt.git tickets `__ +- `New libvirt.git ticket `__ + +Note bugs in language bindings and other sub-projects should be reported to +their corresponding git repository rather than the main libvirt.git linked +above. + +Linux Distribution specific bug reports +--------------------------------------- + +- If you are using binaries from **Fedora**, enter tickets against the + ``Fedora`` product and the ``libvirt`` component. + + - `View Fedora libvirt + tickets `__ + - `New Fedora libvirt + ticket `__ + +- If you are using binaries from **Red Hat Enterprise Linux**, enter tickets + against the Red Hat Enterprise Linux product that you're using (e.g., Red Hat + Enterprise Linux 6) and the ``libvirt`` component. Red Hat bugzilla has + `additional guidance `__ about getting support + if you are a Red Hat customer. + +- If you are using binaries from another Linux distribution first follow their + own bug reporting guidelines. + +- Finally, if you are a contributor to another Linux distribution and would + like to have your procedure for filing bugs mentioned here, please mail the + libvirt development list. + +:anchor:`` + +How to file high quality bug reports +------------------------------------ + +To increase the likelihood of your bug report being addressed it is important to +provide as much information as possible. When filing libvirt bugs use this +checklist to see if you are providing enough information: + +- The version number of the libvirt build, or SHA1 of the GIT commit +- The hardware architecture being used +- The name of the hypervisor (Xen, QEMU, KVM) +- The XML config of the guest domain if relevant +- For Xen hypervisor, the domain logfiles from /var/log/xen and + /var/log/libvirt/libxl +- For QEMU/KVM, the domain logfile from /var/log/libvirt/qemu + +If the bug leads to a tool linked to libvirt crash, then the best is to provide +a backtrace along with the scenario used to get the crash, the simplest is to +run the program under gdb, reproduce the steps leading to the crash and then +issue a gdb "bt -a" command to get the stack trace, attach it to the bug. Note +that for the data to be really useful libvirt debug information must be present +for example by installing libvirt debuginfo package on Fedora or Red Hat +Enterprise Linux (with debuginfo-install libvirt) prior to running gdb. + +| It may also happen that the libvirt daemon itself crashes or gets stuck, in + the first case run it (as root) under gdb, and reproduce the sequence leading + to the crash, similarly to a normal program provide the "bt" backtrace + information to where gdb will have stopped. +| But if libvirtd gets stuck, for example seems to stop processing commands, try + to attach to the faulty daemon and issue a gdb command "thread apply all bt" + to show all the threads backtraces, as in: + +:: + + # ps -o etime,pid `pgrep libvirt` + ... note the process id from the output + # gdb /usr/sbin/libvirtd + .... some information about gdb and loading debug data + (gdb) attach $the_daemon_process_id + .... + (gdb) thread apply all bt + .... information to attach to the bug + (gdb) diff --git a/docs/meson.build b/docs/meson.build index bee7b3e6fc..e92ce6bd9e 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -19,7 +19,6 @@ docs_assets = [ docs_html_in_files = [ '404', - 'bugs', 'cgroups', 'contact', 'csharp', @@ -84,6 +83,7 @@ docs_rst_files = [ 'auth', 'bindings', 'best-practices', + 'bugs', 'ci', 'coding-style', 'committer-guidelines',