Project

General

Profile

HowToReportABug » History » Revision 18

Revision 17 (gstrauss, 2021-07-15 01:25) → Revision 18/20 (gstrauss, 2021-07-15 01:33)

h1. How to report a bug 

 If you find a bug in lighttpd you can help alot to find a fix for it by following some simple steps: 
 * "Don't Panic":http://en.wikipedia.org/wiki/Don't_panic 
 * *For *for support questions question (How do I... ?) use the "Forums":https://redmine.lighttpd.net/projects/lighttpd/boards/2!* 
 * If lighttpd crashes, if it is a crash generate a backtrace Backtrace 
 * If lighttpd if it behaves in an a unexpected way, way prepare a strace 

 h2. Backtrace 

 A backtrace is a trace of the function which have been called before lighttpd died.  

 The best way to generate such a backtrace is using "valgrind":http://valgrind.kde.org/: 

 <pre> 
 valgrind --tool=memcheck -v --log-file=lighttpd --num-callers=8 lighttpd -D -f ./lighttpd.conf 
 </pre> 

 valgrind does many useful things while it waits for the server to crash: 
 * checks for uninitialized variables 
 * checks for out-of-bounds access  
 * and many more 

 valgrind does not normally produce large log files and does not seem to degrade lighttpd's throughput much. Meaning, it's a very good alternative when debugging on busy servers as compared to strace. 

 If you can't use valgrind there is another way to generate a backtrace: 

 <pre> 
 $ gdb lighttpd 
 (gdb) handle SIGPIPE pass nostop noprint 
 (gdb) r -D -f lighttpd.conf 
 ... 
 (gdb) bt 
 </pre> 

 h2. strace 

 strace is the name of the syscall-tracer on Linux. Every Unix-like OS provides a utility to collect information about system call like open, write, close and so on. 

 They have different names like  
 * strace 
 * truss 
 * ktrace (then kdump to get output) 

 If strace is available it is prefered as it provides the most useful information. Execute it like: 

 <pre> 
 strace -olighttpd.trace -tt -s 4000 lighttpd -D -f ./lighttpd.conf  
 </pre> 


 It will generate a file called lighttpd.trace. 

 If you have a running instance of lighttpd and want to see what lighttpd is doing you can attach strace to the process: 

 <pre> 
 strace -olighttpd.trace -tt -s 4000 -p $pidof-lighttpd 
 </pre> 

 Alternatively, if you want to debug a possible problem in lighttpd that is not related to networking and doing so on a busy server, try this: 

 <pre> 
 strace -tt -s 4000 -etrace='!open,epoll_wait,epoll_ctl,sendfile64,read,fcntl,write,fcntl64, 
 close,time,stat64,stat,writev,setsockopt,accept,getsockname,ioctl,socket,connect' \ 
  -p $pidof-lighttpd 
 </pre> 

 The above would tell strace to exclude the system calls listed from the trace, thus reducing the performance impact on lighttpd as well as producing much less output that may actually not be necessary in order to debug the problem at hand. 

 h2. ktrace  

 On all BSDs incl. MacOS X you can use ktrace as replacement for strace. The output not as informative as strace, but still very important for tracking down problems. 

 ktrace will, once enabled, trace data until the process exists or the trace point is cleared. A traced process can generate enormous amounts of log data quickly; it is strongly suggested that users memorize how to disable tracing before attempting to trace a process. The following command is sufficient to disable tracing on all user owned processes, and, if executed by root, all processes. 

 <pre> 
 ktrace -C 
 </pre> 

 To enable tracing run: 
 <pre> 
 ktrace -p <lighttpd pid> -f lighttpd.trace 
 </pre> 
 to attach to the process. 

 Use kdump to get useful data: 
 <pre> 
 kdump -f lighttpd.trace -T -m 4000 -d 
 </pre> 

 For more ways on limiting the output and such, see 
 http://www.openbsd.org/cgi-bin/man.cgi?query=ktrace and 
 http://www.openbsd.org/cgi-bin/man.cgi?query=kdump 

 h2. Memleaks 

 If you experience that lighttpd is using more than 1Gb of RAM you might have spotted a memleak. Valgrind, our valuable helper, can help you to provide the necessary information to fix it. 
 <pre> 
 valgrind --tool=memcheck -v --log-file=lighttpd --num-callers=8 \ 
   --leak-check=yes --show-reachable=yes \ 
   lighttpd -D -f ./lighttpd.conf 
 </pre> 

 Beware that this will use alot of memory and will slow down the process. You might not be able to run this on a production system with real load. 

 h2. Writing a bug report 

 If you have generated a backtrace or a syscall-trace please make sure that you can reproduce the problem. Otherwise it will be really hard for the developers to fix the problem for you. 

 If possible open a "new issue":http://redmine.lighttpd.net/projects/lighttpd/issues/new, but please check if someone else reported the problem before you. 

 If the report contains sensitive data you might also send it directly to security@lighttpd.net