NetBSD/share/man/man4/ipkdb.4

.\"	$NetBSD: ipkdb.4,v 1.2 2000/11/07 06:43:26 lukem Exp $
.\"
.\"
.\" Copyright (C) 2000 Wolfgang Solfrank.
.\" Copyright (C) 2000 TooLs GmbH.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by TooLs GmbH.
.\" 4. The name of TooLs GmbH may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY TOOLS GMBH ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL TOOLS GMBH BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd March 27, 2000
.Dt IPKDB 4
.Os
.Sh NAME
.Nm ipkdb
.Nd IP-based kernel debugger
.Sh SYNOPSYS
.Cd options IPKDB
.Cd options IPKDBSECURE
.Cd options IPKDBKEY="\e"IPKDB key for remote debugging\e""
.Cd options IPKDB_NE_PCISLOT=x
.Sh DESCRIPTION
.Nm
is a kernel debugger that uses UDP and IP to communicate with
a remote debugger (normally
.Xr gdb 1 ).
.Pp
Since the debugger uses its own driver to talk to the networking hardware,
the number of supported network interfaces is a lot less than what is
supported by the kernel.
At the time of this writing, there is only support for a NE2000 compatible
card in a PCI slot.
In order for
.Nm
to find your card, you need to specify the slot the card is in via
the
.Li "options IPKDB_NE_PCISLOT" .
.Pp
To use
.Nm "" ,
you have to setup a DHCP server,
from which
.Nm
can get the IP address for the interface that is used for debugging.
.Pp
To enter
.Nm "" ,
the remote debugger has to send the protocol start packet.
E.g., gdb will do this on the command
.Dl target ipkdb debuggee IPKDB key for remote debugging
where
.Li debuggee
is the name of the machine to debug (which must resolve to the
IP address of the interface), and the rest of the line
corresponds to the definition of
.Dv IPKDBKEY
(see below).
For
.Nm
to actually see this packet, the interface which is used for
debugging has to be setup to actually receive packets,
i.e. it has to be up and running.
.Pp
To prevent messing around with a secured system,
.Nm
normally also checks the security level at which the kernel
is running.
.Nm
will only work with security levels less than 1,
unless the kernel is configured with
.Li "options IPKDBSECURE" .
.Pp
In addition, the debugger is forcedly entered on a panic,
as well as on intial startup, if you boot the kernel with the
.Fl d
option (note that this however is machine dependent).
On such a forced enter to
.Nm
there is no need for the interface in question to already
be up and running, since
.Nm
only needs to send/receive packets via its own driver.
.Pp
As some form of security against the occasional hacker,
.Nm
uses the definition of
.Li "options IPKDBKEY"
to compute a checksum on the data in every packet.
The remote debugger has to send this checksum,
based on the data it sends and the key, or
.Nm
ignores the packet.
This is also used in order to check against data errors
on the connection.
.Sh BUGS
Since the kernel includes the definition of IPKDBKEY,
anyone who can read the kernel can extract it and
use it to enter
.Nm "" .
.Pp
There is no support for
.Xr ip6 4 .
.Sh SEE ALSO
.Xr gdb 1 ,
.Xr ddb 4 ,
.Xr ip 4 ,
.Xr udp 4 ,
.Xr init 8
.Sh HISTORY
.Nm
appeared in
.Nx 1.3
for the first time.
It's configuration and setup changed quite a bit in
.Nx 1.5 .