Big Sister - PROTOCOL

- The Big Sister Client/Server Protocol
- Commands

- join
- leave
- displayname
- status
- page
- savelogs
- sendlogs
- perf
- remove
- event

## 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