Content-type: text/html Manpage of kibot-control

kibot-control

Section: (1)
Updated: 2003 Apr 6
Index Return to Main Contents

NAME

kibot-control - control a running kibot

SYNOPSIS

kibot-control [options]

DESCRIPTION

kibot-control is used to control a running kibot. This is mostly useful when starting an kibot for the first time.

Kibot requires that users have permissions to execute certain commands. In order to have such permissions, a human must first be known to the bot. Unfortunately, in order to introduce someone to the the bot (via the meet command), you must have the appropriate permissions. This little Catch-22 can be cleanly avoided using kibot-control, which allows you to give the bot commands effectively free of permissions checks.

kibot-control can also be useful in other situations, such as when you connect from a strange location and need to tell the bot to recognize you (although password authentication gets around this, too).

The primary mode of operation for kibot-control is to find and connect to the bot's direct connection (DC), which automatically grants full control over the bot. A direct connection acts very much like a private IRC chat with the bot, except that permissions checks are automatically passed.

OPTIONS

kibot-control takes all of the options that kibot does (although it ignores most of them) and a few more. The reason kibot-control takes the same options as kibot is so that you can call it in exactly the same way you started your bot in order to control that bot. That is, if you started your bot with

: kibot -C /foo/bar --dc-addr sockdir/socket

it might be hard to know where to find the socket file. It will be in the base dir, but the base dir might be set in the config file (/foo/bar) or it could be the directory from which kibot was called (the default base dir is "."). If you call kibot-control in exactly the same way:

: kibot-control -C /foo/bar --dc-addr sockdir/socket

from within the same directory, then kibot-control will parse the config file and determine correctly where the socket it.

-h, --help: Print a summary of command line options to STDOUT and exit.
-b VAL, --base-dir=VAL: The base directory where most other files are written or searched for. If other files are specified with relative paths, it will be interpreted as relative to the base dir. [files, base_dir] default: . (present working directory)
-C VAL, --conf=VAL: The location of the config file. Like other files, this is considered relative to the base directory if a relative path is give. default: kibot.conf --lockfile=VAL The file to use as a lockfile and to which the bot's pid is written. [admin, lockfile] default: kibot.pid
--dc-addr=VAL: The direct connection (DC) address to connect to. This can either be the address of a unix socket (basically, a file name), or it can be a host:port. This is the one deviation from the kibot options. This allows you run kibot-control on a different machine from kibot. If the host part is omitted (that is, if only a port is provided), then the host is assumed to be localhost. [admin, dc_addr] default: DC_SOCKET
--kill: Get the PID from the lockfile and then kill the bot. The bot is first sent SIGTERM, and if it does not terminate within 30 seconds, it is sent SIGKILL.
--reload: Send the bot SIGHUP, which causes it to reload its config. Note that it still uses the command line options that were passed in at startup, and they will still override config file options.
--pid: Print the process id of the bot to STDOUT and exit.
--signal=VAL: Send the signal VAL to the bot. VAL can be a number or name (as in SIGTERM or TERM). Note that there's little reason to do this with --kill and --reload available.

EXAMPLES

The most obvious example is when you first create a new bot. In that event, you should start the bot, (see kibot(1) ) start kibot-control in the same fashion, and do the following:

join #SOMECHANNEL
<in your IRC client, you also join #SOMECHANNEL>
meet YOURNICK with owner

At that point, you should be recognized as the bot's owner and should be able to do anything else you need to do from IRC.

AUTHORS

Michael Stenner <mstenner@phy.duke.edu>

BUGS

Due to the way python deals with signals, there is some possibility that "bad things" could happen if kibot receives a signal while it's in the process of executing a system call (mostly IO).

For now, send bugs to <mstenner@phy.duke.edu>. Documentation bugs and "this isn't clear"-reports are quite welcome as well.

This document was created by man2html, using the manual pages.
Time: 01:25:05 GMT, September 26, 2003

kibot-control