share/man/man4/ipkdb.4

   1 .\"     $NetBSD: ipkdb.4,v 1.6 2003/02/25 10:35:14 wiz Exp $
   2 .\"
   3 .\"
   4 .\" Copyright (C) 2000 Wolfgang Solfrank.
   5 .\" Copyright (C) 2000 TooLs GmbH.
   6 .\" All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed by TooLs GmbH.
  19 .\" 4. The name of TooLs GmbH may not be used to endorse or promote products
  20 .\"    derived from this software without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY TOOLS GMBH ``AS IS'' AND ANY EXPRESS OR
  23 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  24 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  25 .\" IN NO EVENT SHALL TOOLS GMBH BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  27 .\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  28 .\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  29 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  30 .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  31 .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32 .\"
  33 .Dd March 27, 2000
  34 .Dt IPKDB 4
  35 .Os
  36 .Sh NAME
  37 .Nm ipkdb
  38 .Nd IP-based kernel debugger
  39 .Sh SYNOPSIS
  40 .Cd options IPKDB
  41 .Cd options IPKDBSECURE
  42 .Cd options IPKDBKEY="\e"IPKDB key for remote debugging\e""
  43 .Cd options IPKDB_NE_PCISLOT=x
  44 .Sh DESCRIPTION
  45 .Nm
  46 is a kernel debugger that uses UDP and IP to communicate with
  47 a remote debugger (normally
  48 .Xr gdb 1 ) .
  49 .Pp
  50 Since the debugger uses its own driver to talk to the networking hardware,
  51 the number of supported network interfaces is a lot less than what is
  52 supported by the kernel.
  53 At the time of this writing, there is only support for a NE2000 compatible
  54 card in a PCI slot.
  55 In order for
  56 .Nm
  57 to find your card, you need to specify the slot the card is in via
  58 the
  59 .Li "options IPKDB_NE_PCISLOT" .
  60 .Pp
  61 To use
  62 .Nm ,
  63 you have to set up a DHCP server,
  64 from which
  65 .Nm
  66 can get the IP address for the interface that is used for debugging.
  67 .Pp
  68 To enter
  69 .Nm ,
  70 the remote debugger has to send the protocol start packet.
  71 E.g., gdb will do this on the command
  72 .Dl target ipkdb debuggee IPKDB key for remote debugging
  73 where
  74 .Li debuggee
  75 is the name of the machine to debug (which must resolve to the
  76 IP address of the interface), and the rest of the line
  77 corresponds to the definition of
  78 .Dv IPKDBKEY
  79 (see below).
  80 For
  81 .Nm
  82 to actually see this packet, the interface which is used for
  83 debugging has to be set up to actually receive packets,
  84 i.e. it has to be up and running.
  85 .Pp
  86 To prevent messing around with a secured system,
  87 .Nm
  88 normally also checks the security level at which the kernel
  89 is running.
  90 .Nm
  91 will only work with security levels less than 1,
  92 unless the kernel is configured with
  93 .Li "options IPKDBSECURE" .
  94 .Pp
  95 In addition, the debugger is forcedly entered on a panic,
  96 as well as on initial startup, if you boot the kernel with the
  97 .Fl d
  98 option (note that this however is machine dependent).
  99 On such a forced enter to
 100 .Nm
 101 there is no need for the interface in question to already
 102 be up and running, since
 103 .Nm
 104 only needs to send/receive packets via its own driver.
 105 .Pp
 106 As some form of security against the occasional hacker,
 107 .Nm
 108 uses the definition of
 109 .Li "options IPKDBKEY"
 110 to compute a checksum on the data in every packet.
 111 The remote debugger has to send this checksum,
 112 based on the data it sends and the key, or
 113 .Nm
 114 ignores the packet.
 115 This is also used in order to check against data errors
 116 on the connection.
 117 .Sh SEE ALSO
 118 .Xr gdb 1 ,
 119 .Xr ddb 4 ,
 120 .Xr ip 4 ,
 121 .Xr udp 4 ,
 122 .Xr init 8
 123 .Sh HISTORY
 124 .Nm
 125 appeared in
 126 .Nx 1.3
 127 for the first time.
 128 Its configuration and setup changed quite a bit in
 129 .Nx 1.5 .
 130 .Sh BUGS
 131 Since the kernel includes the definition of IPKDBKEY,
 132 anyone who can read the kernel can extract it and
 133 use it to enter
 134 .Nm .
 135 .Pp
 136 There is no support for
 137 .Xr ip6 4 .