
What is lcrashd

  lcrashd is a daemon for accessing the lcrash tool remotely via TCP
  (e.g: with the tcpplugin of the new frontend qlcrash).
  For more information about lcrash and the LKCD project, please refer to
  http://lkcd.sourceforge.net

  lcrashd is distributed under the GNU public license. See COPYING for
  more information.

  lcrashd is (C) 2001 by Fritz Elfert <felfert@millenux.com>

Compiling/Installing lcrashd

  As with every automake-based package, it boils down to the well-known
  command sequence

    ./configure
    make
    su -c "make install"

  As usual, the default install prefix is /usr/local and you
  have to override that using configure's --prefix option if you
  want to have it installed elsewhere. There is currently one
  additional option:

  	--{en|dis}able-debug

  Explicitely enabling debug, produces a binary which prints lot of
  debug output. Explicitely disabling debug, produces a binary which
  does not print this debug output and is stripped. Ommitting this
  option, produces a binary which does not print debug output, but
  contains debugging symbols.

Using lcrashd

  lcrashd can be used in two modes of operation:

    1. Standalone daemon
    2. Started from inetd resp. xinetd

  The simplest way of running lcrashd is starting it manually from
  commandline. By default, lcrashd listens on any IP adress, port 8192.
  If you like a different default port, you can add an entry named
  "lcrashd" into your /etc/services file and specify the port there.
  E.g.:

  	lcrashd       8888/tcp

  makes 8888 the default port.

  You also can specify the port on the command line, using -p resp. --port.
  If your host has more than one IP adress, you probaly also want to
  bind lcrashd on a single IP adress. You can specify an adress on the
  command line, using -b resp. --bindto.

  If you frequently use lcrashd on a development machine, you probably
  want to run it from inetd. In that case, it has to be started, using
  the -i resp. --inetd option. A suitable entry for xinetd would look
  like this:

  	# default: on
	# description: lcrashd enables remote access to local lcrash
	service lcrashd
	{
		disable = no
		socket_type = stream
		flags = REUSE
		wait = no
		user = root
		server = /usr/local/sbin/lcrashd
		server_args = --inetd
		log_on_failure += USERID
	}
  
  For oldfashioned inetd, add a line like this in your /etc/inetd.conf

	lcrashd tcp stream nowait root /usr/local/sbin/lcrashd lcrashd --inetd

  Both inetd configuration examples also require you to add the above
  mentioned entry in /etc/services.

The protocol
  lcrashd uses a very simple protocol for communication with the client.
  There are four virtual communication channels which are multiplexed
  in the TCP stream:

  	- the control channel (used for starting/stopping lcrash and
	  similar maintenance.
	- the stdin channel for sending commands to lcrash.
	- the stdout channel for receiving lcrash's stdout.
	- the stderr channel for receiving lcrash's stderr.

  For multiplexing these channels in the single TCP stream, every message
  in the TCP stream is prefixed with a three byte header:

	Offset	Description
	0	A character, selecting the channel:
		  'C' for control channel
		  'I' for stdin channel
		  'O' for stdout channel
		  'E' for stderr channel
	1	An unsigned 16bit integer in network byte order,
		specifying the length of the following data.

  The data in the stdin, stdout and stderr channels is transferred
  to/from a running lcrash without any further modification.
  The data in the control channel is interpreted resp. generated
  within lcrashd. Every data portion of a control message is an
  ASCII string, ending with LF (linefeed), NOT null terminated
  (since the header already specifies the message length).
  The following control messages are defined:

    Direction lcrashd -> client:

  	A\n		Initially sent after connect.
	Dhhhhhhhh\n	Sent, if lcrash has terminated. hhhhhhhh
			is an 8-digit hexadecimal value, specifying
			the child exit status of lcrash in network
			byte order.
	Vb\n		Sent as reply on a validation inquiry.
			b is either '1' or '0', meaning lcrash binary
			is valid or not.
	Rb\n		Sent as reply on status inquiry.
			b is either '1' or '0', meaning lcrash is
			currently running or not.
	Kb\n		Sent as reply on a kill request.
			b is either '1' or '0', meaning signal
			has been successfully sent or not.
	Sb\n		Sent as reply on a start request.
			b is either '1' or '0', meaning lcrash has
			been started or could not be started.

    Direction client -> lcrashd:

    	valid? p\n	Validation inquiry. Check, if the binary
			specified in the path p is a valid executable.
	running?\n	Status inquiry. Check, if lcrash is
			currently running.
	kill! d\n	Kill request. Send signal number d to
			lcrash. The signal number is a decimal
			number string.
	start! l p a\n  Start request. l is a decimal number string,
	                specifying the length of p. p is the
			path of the binary, a is a string with
			additional arguments. The arguments are
			NOT shell-expanded. The only supported
			shell like interpretation is quoting with
			double quotes ("). Every whitespace, outside
			of quotes, leads to a separate element in
			lcrash's argument list.

Security
  lcrashd currently has no builtin security. All network traffic is
  unencrypted and no access authentication is performed. If you
  want to use lcrashd in a sensible environment, you should consider
  the following:

  Access authentication:
    If running from (x)inetd, use xinetd's access features or with
    inetd, use a tcp wrapper.
    
  Encryption:
    Running standalone, use the --bindto option for binding to
    127.0.0.1, then use ssh's port-forwarding mechanism for getting an
    encrypted connection.

Have fun!
 -Fritz
