Topic: FAQ - How to report issues effectively

[ReetP]

Reporting Issues

Intro

Koozali SME Server is open source. That means you can take the code and use and modify it any way you want. But it has no warranty.

That means you do not get guaranteed support, instantly or otherwise, do not have permission to abuse developers and helpers because things don't work the way you want, and cannot demand a fix or feature.

Everything is provided on a best effort basis.

You will also find that if you get involved and help you will learn more, and get more help from more experienced users.

Be prepared

If you are reporting issues please take some time to prepare a well documented question. Please think carefully about what you say and how you say it, particularly if you are using translations.

It will save everyone a lot of time and energy and will help both you and us.

Please remember that you are the one with the problem, so help those people who are trying to help you. Don't abuse them or you will find yourself at best ignored by the very people with the knowledge to help you, or banned altogether.

Answer their questions accurately. The questions might seem strange to you, but they know what they are doing, and you are one who is stuck and asking for help.

Remember they are also blind. They cannot see your screen, they cannot read your mind, and they have not seen what you have been doing to get yourself in this position. Document everything. Take written notes as you go.

• YOU are the one with the problem. You would not be here otherwise
• The developers build SME in their spare time and do not get paid for their work. Respect them
• Volunteers who help here do it in their spare time and are not getting paid for this. Respect them
• You are entitled to exactly the level of support that you paid for...........
• Just because it is urgent for you does not mean that it is urgent for them
• Your time might be valuable. Theirs is invaluable
• They have jobs to do and mouths to feed. Don't waste their time

Backups

You do have backups in case things go wrong? More than one, in different places, and you have tested your restore procedures?

Good.


RTFM

We spend a lot of time on documentation. It is isn't perfect but it does contain a lot of answer and help.

https://wiki.koozali.org/SME_Server:Documentation
https://wiki.koozali.org/SME_Server:Documentation:FAQ
https://wiki.koozali.org/Category:Howto


Searching for an answer

Have you actually tried searching for your issue?

Frequently the issue will have been answered before, often several times. The first thing that most helpers do is have a read - they may either have read about it before (because they track issues closely) or try to find extra material.

Search the forums, the wiki and the bug tracker. Then search the interwebs in general. Try some different search terms. Use advanced search options eg the bug tracker won't show closed bugs by default so you need to edit the options.

Next do some more reading. These are some bibles on issue reporting.

Tell us about your problem, not your attempts at a solution:
https://xyproblem.info/

How to report bugs effective:
https://www.chiark.greenend.org.uk/~sgtatham/bugs.html

How to ask a smart question that will attract attention:
http://www.catb.org/esr/faqs/smart-questions.html


The start

Always go back to the beginning and give us a bit of history of your server and the journey to your current predicament. Often issues are caused by a long chain of slightly unusual events - see the XY Problem above.

A real world anecdotal example. A client brought in a car with an issue with the rear washer pump.

I traced it back to an issue with the front washer pump. Confusingly it was still working, though a bit low on pressure. The pump was partly blocked and that melted the feed wire. They had used thicker wire to repair it, which blew the fuse. They wrapped the fuse with silver foil, which melted part of the fuse box. And that stopped the rear washer pump working......

"But I just thought the rear pump was broken"

Nope, and a new fusebox is going to cost you a lot of money.


Let's go.


Documenting things

Was it a clean install, upgrade, how?

What sort of internet connection? DHCP , static, Adsl or whatever? Other routers, local network setup etc?

Have a look in your server manager lower left in Miscellaneous for "Report a bug" and then do "Create configuration report" and post us some of the network details, less things like passwords.

Also run these and post the output:

Code: [Select]

/sbin/e-smith/audittools/newrpms
/sbin/e-smith/audittools/templates
Can you repeat the issue so that we can repeat it and be able to look for it on a test machine?


Logs

Stephdl wrote some nice one liners to assist

https://wiki.koozali.org/User_talk:Stephdl#Log

Quick Parse of Log

a quick parse of your log, but you should read the entire log

Code: [Select]

less  /var/log/messages| grep -iE "uninitialized|WARNING|ERROR"

Deep parse Log to find errors

When you want to test the SME Product it can be useful to see what it occurs This CL can help you, but you should read the entire log

Code: [Select]

less  /var/log/messages| grep -iE "useless|uninitialized|warn|fail|error|disable|unable|exit"
Of course this is for the /var/log/messages  but you can use it on other logs.

Parse all Logs to find errors

Parse all logs and write (under /root) the output to a text file named with the date of day. For example log012214:

Code: [Select]

find /var/log/ -mtime -2 -print -exec sh -c 'cat "{}" | tai64nlocal | egrep -i "useless|warn|fail|error|disable|remov|unable|exit"' \; > "log$(date +'%m%d%y')" 2>&1
Then:

Code: [Select]

cd /root
less log012214
Or this one is lighter

Code: [Select]

find /var/log/ -mtime -2 -print -exec sh -c 'cat "{}" | tai64nlocal | egrep -i "uninitialized|WARNING|ERROR"' \; > "log$(date +'%m%d%y')" 2>&1

Using journalctl

Print in reverse order

Code: [Select]

journalctl -r
Tail a log file

Code: [Select]

journalctl -f
View a specific service

Code: [Select]

journalctl -u sshd.service
See errors

Code: [Select]

journalctl -xe

Unit files/services

Remember that Koozali SME uses systemd to manager services. It also has some bespoke code to enable management of these services via commands so some 'normal' systemd commands may not work as expected.

Using Koozali SME specific controls via the server-manager or via the command line eg signal-event some-command is always preferable as this should mange all the relevant templates and services for you

Some systemd specific commands

Code: [Select]

systemctl list-units --all

Code: [Select]

systemctl list-unit-files --type=service

Code: [Select]

systemctl list-unit-files --type=service --state=enabled

Code: [Select]

systemctl list-unit-files --type=service --state=enabled,disabled

Final thoughts

E&OE

Most issues are not really issues. They are often bad installation/configuration caused by a lack of understanding of the hardware or the software.

We try to make Koozali as foolproof as we can but it does not excuse you from the responsibility of understanding and managing a server.

If you have any ideas or comments on this post then let us know and we can add or mend as appropriate.

Thank you for using Koozali SME Server

We are totally dependent on donations to run the hardware that builds Koozali SME so please help maintenance.

https://forums.contribs.org/index.php?action=profile;area=subscriptions

[15/12/21 Edited some parts]

[ReetP]

I forgot I had this post!!

I have started a wiki page here:

https://wiki.koozali.org/How_to_report_a_problem

I'll update accordingly.

[bunkobugsy]

wrong thread