/* doc/kline.txt - Overview of the remote kline system
 * 
 * Copyright (C) 2001-2002 Hybrid Development Team
 *
 * $Id: kline.txt,v 1.5 2002/05/02 16:58:11 leeh Exp $
 */


Introduction
------------

ircd-hybrid-7 will allow opers to add klines on multiple servers, an extension
and replacement of the old ircd-hybrid-6 method of sharing all klines between
servers.  Remote unkline is not currently supported, however an unofficial
patch to support this exists in contrib/.  Read contrib/README for more
information.

In this implementation, it is extended to be routable among servers which
understand the "KLN" capability. This allows us to continue to "talk"
to non remote kline capable servers without breaking anything.


Usage
-----

The old kline method has not been changed.  To place a kline it is still:

/quote kline <nick|user@host> :reason
/quote kline [tkline_duration] <nick|user@host> :reason



Scenario 1
----------

Oper wishes to kline user@host on server irc.xyz.net

/quote kline <nick|user@host> on irc.xyz.net :reason
/quote kline [duration] <nick|user@host> on irc.xyz.net :reason


Scenario 2
----------

Oper wishes to kline user@host on all servers named *.uk

/quote kline <nick|user@host> on *.uk :reason
/quote kline [duration] <nick|user@host> on *.uk :reason


Scenario 3
----------

Oper wishes to place a network wide kline on user@host

/quote kline <nick|user@host> on * :reason
/quote kline [duration] <nick|user@host> on * :reason


Authorisation
-------------

For the kline to be accepted by the remote server, the server must have
explicitly allowed klines from that user.  This is done via a shared {};
block in ircd.conf.

The shared block contains two settings, a user@host mask of the oper
who is allowed to kline, and a servername.

- If both of these options are present, klines will only be allowed 
  from that specific user@host on that specific server. 
- If only the servername is present, all klines from opers on that
  server will be accepted.
- If only the user@host is present, all klines from that user@host on
  any server will be accepted.
- If neither are present, the shared block is invalid.

shared {
	/* The name of the server we allow klines from */
	name = "this.server.net";

	/* the user@host allowed to kline */
	user = "user@host.com";
};


Server to Server Protocol
-------------------------

As mentioned above, each server capable of remote klines passes
the capability KLN along. No server will send a KLINE to a server
without a KLN capability.

Server to server messages are formatted like this:

  ":oper KLINE target.server duration user host :reason"
    
Note the difference between hybrid-6 GLINE which explicitly passed
the oper user@host and server along. This was originally done to handle
possible desync conditions, but is now shelved in favor of saving 
some bandwidth.

oper:		the nick of the oper performing the kline
target.server:	the server(s) this kline is destined for
duration:	the duration if a tkline, 0 if permanent.
user:		the 'user' portion of the kline
host:		the 'host' portion of the kline
reason:		the reason for the kline.
