The Big Sister Client/Server Protocol
=====================================

Clients communicate with the Big Sister Status Collector 
via a TCP based protocol. Whenever a client needs to send
status/group updates it connects to a dedicated port (defaults
to 1984), sends one or more commands and then disconnects.
The server will never acknowledge client commands, the protocol
(currently) is one-way only.

Commands are text based. Each command starts with a keyword
followed by the command arguments followed by a newline.
Both "network" (CR/LF) and "unix" (LF) newlines are accepted.
Newlines in a command argument must be replaced by the string
"|>" before transmission. There is one exception to this: For
compatibility reasons with Big Brother "status" and "page" 
commands may be multi-lined. The text beginning at a status 
command up to the next line looking like a valid command is 
treated as one single command. Do not use this feature!

Usually the client disconnects after successfully sending its
commands. The Big Sister server does terminate a connection if 
one of the following conditions are met:

	- an invalid command was sent
	- a timeout ocurred (no data received for a limited time)
	- the client is not allowed to send a command

Whenever hostnames are fully qualified (domain name included)
"." characters must be replaced by "_" or "," before transmission.

By convention hostnames are written in lowercase letters while
group names are written in uppercase letters.

Clients running in Big Brother compatibility mode should never
send more than one command without closing/re-opening the TCP
connection.


Commands
========

    join
    ====

    Syntax: join group group1 ... groupn

    The host or group called group joins the groups group1 through groupn.
    Non-existant groups are automatically set up when the first member
    joins them.

    NOTE: If the %Autojoin feature of bbd is active, any host appearing
	  automatically joins one or more groups.


    leave
    =====

    Syntax: leave group group1 ... groupn

    The host or group called group leaves the groups group1 through groupn

    Alternate Syntax: leave group *

    The host or group called group leaves any group it was in, any cached
    information for this host is deleted.

    Groups are dropped when their last member leaves.


    displayname
    ===========

    Syntax: displayname group text

    Set the Text appearing on the Web pages for the host or group
    called group to text. All the text up to the end of the line
    is treated as one argument - the text may contain spaces.


    status
    ======

    Syntax: status hostname.check color comment

    Set the status of the check called check of the host called
    hostname to color. Allowed colors are red, yellow, purple and
    green. The comment may be an arbitrary (multi-lined) text. By
    convention it starts with

	(seconds since January 1 1970) time-and-date-in-human-readable-format

    though. A valid status command therefore is for instance:

	status myhost.bak red (926008681) Thu May  6 18:38:01 1999 backup failed

    Status messages exchanged between Big Sister status collectors
    usually will have "(proxy delay: XXs)" added after the human
    readable time, e.g.

	status myhost.bak red (926008681) Thu May  6 18:38:01 1999 (proxy delay: 126s) backup failed


    page
    ====

    NOTE: this command is only implemented for backwards compatibility
	  whith Big Brother!

    Syntax: page text

    Send a paged alarm.


    savelogs
    ========

    Syntax: savelogs
	    savelogs tag

    Rotates Big Sister log files. The optional tag (alphanumeric string)
    does associate an identifier with savelogs e.g. used with sendlogs.
    Savelogs will not be executed if savelogs has already been executed
    for this tag.


    sendlogs
    ========

    Syntax: sendlogs tag

    Sends the history log file called "tag" to the client. The
    transmission ends with a line containing only "--END". If
    the tag is not known (savelogs must have been executed for
    this tag) no file transmission will take place.

    This command is mainly used in "bsadmin archivelogs" (see HOWTO).


    perf
    ====

    Syntax: perf time host:variable value

    Log performance data. The sample for host 'host', variable
    'variable' at time 'time' was of value 'value'.


    remove
    ======

    Syntax: remove host.check

    Discards in-memory tracks of host.check on the server. The
    status light for host.check disappears.


    event
    =====

    Syntax: event time host.item priority text

