For accomplishing certain adminsdrative tasks, sending commands to the server through the agent- server- protocol can come in very helpful. Please read the Server Command Reference for a complete list of commands implemented in the Big Sister serverprotocol.
Commands can be sent by establishing a telnet session to the tcp- server port and typing the desired command plus required arguments:
[root@proxy /root]# telnet [bigsister-server] 1984 Trying 192.168.170.13... Connected to bigsister.joerg.cc. Escape character is '^]'. [TYPE YOUR COMMANDS HERE]
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.
bsadmin
is commandline based tool wich comes with Big Sister and offers a more comfortable way of sending server commands than the telnet client. It basically takes the same commands and arguments than the telnet client.
Example 3.3. Getting rid of unwanted status lights ("purples")
Whenever an agent stops reporting status messages for a certain host/check the Big Sister display server will still remember this host/check and display a purple ("no report") status light. This is the indended behaviour since by this means you notice which checks are currently not working (e.g. due to a connection loss with the respective agent).
However sometimes you will remove or rename a host/check and want those purples to just disappear. Big Sister 0.96 introduces a "remove" command for exactly this purpose. Agents now can send a "remove host.check" to the display server and the respective status light will disappear. The required procedure is actually a good example on how to send server commands using the telnet client or bsadmin.
Table 3.5. Accepted keywords and function
Function | Using bsadmin | Using the telnet client |
---|---|---|
remove a single check | bsadmin -d servername remove hostname.checkname | telnet servername port remove hostname.checkname |
remove all checks of a host | bsadmin -d servername remove hostname.* | telnet servername port remove hostname.* |
remove a host completely | bsadmin -d servername leave hostname * | telnet servername port leave hostname * |
In Big Sister versions prior to rev. 0.96, the remove command has not been implemented in the server protocol. Big Sister Version 0.96 to 0.98 need an additional remove hostname.*
command for removing a host completely.
Never forget to limit access to this removal command (see Server access: /etc/bigsister/permissions)