segv_handler/README

   1 segv_handler
   2 ============
   3
   4 Andrew Tridgell
   5 junkcode@tridgell.net
   6
   7
   8 This tool allows you to catch segmemtation faults globally on your
   9 system, giving a full backtrace for any program that dies with a
  10 segmemtation fault. This is done with zero overhead in the running
  11 program, so you can install it on production systems without
  12 interference.
  13
  14
  15 Building
  16 --------
  17
  18 Just type 'make'. If it fails to build then consult a systems
  19 programmer or local Linux oracle.
  20
  21
  22 Installing
  23 ----------
  24
  25 You need to install two files. The small shared library
  26 segv_handler.so can be put anywhere on the system, but somewhere like
  27 /usr/local/lib probably makes most sense.
  28
  29 The shell script 'backtrace' needs to be installed somewhere in the
  30 main system PATH, where all programs can see it. This usually means
  31 /usr/bin. It must be made executable using 'chmod +x backtrace'.
  32
  33 You may wish to edit the script to place the resulting backtraces in
  34 some other directory than /tmp, although you have to make sure the
  35 directory is writable by all programs that you wish to monitor.
  36
  37
  38 Testing
  39 -------
  40
  41 After installing try 'make test'. You should see something like this
  42 at the end of the output:
  43
  44   -rw-rw-r--    1 tridge   tridge        479 Sep 16 20:38 /tmp/segv_testprog.11817.out
  45
  46 look in that file. Notice that it contains a full backtrace of the
  47 program 'testprog' when it died.
  48
  49
  50 Usage Method 1 - per program
  51 ----------------------------
  52
  53 You can use segv_handler.so on a per program basis by setting the
  54 LD_PRELOAD environment variable before starting the program. For
  55 example you might start the 'winbindd' daemon from Samba in a script
  56 like this:
  57
  58    #!/bin/sh
  59
  60    export LD_PRELOAD=/usr/local/lib/segv_handler.so
  61    /usr/local/samba/sbin/winbindd
  62
  63 If you use the above script to start winbindd then if winbindd dies it
  64 will leave behind a file called /tmp/segv_winbindd.XXXX.out. That is
  65 the file that you would show to a programmer to find the bug.
  66
  67
  68 Usage Method 2 - entire system
  69 ------------------------------
  70
  71 Note! This method can be dangerous if you don't get it right. It is
  72 the way I usually use segv_handler as it provides a useful way to
  73 catch segmemtation faults across the entire system, but if you make a
  74 typo when installing then your system may become unbootable. Have a
  75 rescue disk handy.
  76
  77 To install globally you need to edit or create a file called
  78    /etc/ld.so.preload
  79 That file should contain the full path to where you installed
  80 segv_handler.so. It must be exactly the full path and nothing
  81 more. You must also be careful to remove /etc/ld.so.preload before
  82 removing or renaming segv_handler.so. If you leave a file in
  83 /etc/ld.so.preload that does not exist or is not an appropriate
  84 shared library then all programs on your system will fail to start.
  85
  86 That's it! After you create /etc/ld.so.preload any program that starts
  87 from then on will have the segmentation handler installed. If it dies
  88 with a segmentation fault then you will get a full backtrace in /tmp
  89