From: ijackson Date: Mon, 10 Jun 2002 02:35:07 +0000 (+0000) Subject: Documentation. X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ijackson/git?a=commitdiff_plain;h=91a74043688b1887fab916caabc501ed84c0e2a1;p=ircbot.git Documentation. --- diff --git a/ledbot.html b/ledbot.html new file mode 100644 index 0000000..8965f98 --- /dev/null +++ b/ledbot.html @@ -0,0 +1,291 @@ + + + chiark ledctrl bot + + + +

chiark ledctrl bot

+ +The ledctrl bot exists to allow users to have activity on channels +they're interested in reported on LEDs via the LED control +protocol. + +

Privacy

+ +ledctrl does not make any information about content of IRC sessions +available to anyone, not even its operator (ijackson, acting as +ircop). It does look for activity on the channels it sits on and +report to its users whether there is activity, but the information +made available is not very much. + +

+ +It can watch preferentially for individual users, but this facility +should not be used without the prior consent of the target. ledctrl +will notify the target that they are being watched. + +

+ +If you want to know who is being told information about IRC activity, +say +

+/msg ledctrl who
+

+and it will report something like this +

+-ledctrl- monitoring #starcraft for ijackson:sc
+-ledctrl- monitoring #test for ijackson:#test
+-ledctrl- sending ijackson:sc to ijackson, davenant.relativity.greenend.org.uk:1447
+-ledctrl- sending ijackson:#test to ijackson, davenant.relativity.greenend.org.uk:1447
+

+In this example, the channels sc and #test +are being monitored on behalf of ijackson, who has chosen to name the +monitoring functions ijackson:sc and +ijackson:#test. The results are being sent only to the +LED server on port 1447 of davenant.relativity.greenend.org.uk:1447, +also on behalf of ijackson. + +

Usage

+ +If you want to use this facility: + +

Make sure that your LED server is operating properly, and that you +can use remoteleds on chiark to manipulate the relevant LEDs. + +
If you're using a nonzero password (which is recommended, as +otherwise any other chiark user could interfere with your LEDs), copy +the .led-client-pass that you're using to +~/.userv/irc-ledcontrol-passwords (taking care to make +sure it's not world-readable). + +
Write the configuration file saying which channels to monitor and +where to send the answers. Put it in +~/.userv/irc-ledcontrol-config. See below for the file +format. + +
Join #ledctrl. This is where the debug and +diagnostic output goes. You should also look here if it seems not to +be working at some later point. When you think everything is right, say +/msg ledctrl reload username +where username is your own username. If all is well it +should just say +<ledctrl> reloaded username +and shortly afterwards your LEDs should be set. + +
If you still can't get it to work, say +/msg ledctrl debug username +and see if you can make any sense of the output. NB that this +produces lots of output in the channel, which will disrupt other +people's use of it, and cause ledctrl to become lagged, so please +don't leave the debug enabled. It will turn itself off after a while +anyway. + +
If you decide you don't want to use ledctrl any more, delete +your config file and say /msg ledctrl reload +username, which will cause ledctrl to forget about +your configuration (and any stored passwords). + +

+ +

Configuration model

+ +The file ~/.userv/irc-ledcontrol-config contains the +configuration file for your ledctrl settings. If this file doesn't +exist, ledctrl will assume you don't want it to run on your behalf. + +

+ +The file may contain definitions of two kinds of objects: + +

Monitors + +: These are specifications of channels to monitor, activity +timeouts, and nicks to ignore, etc. Each monitor at any particular +time has a particular result state which depends only on its +configuration and activity on the channel. + +
+ +Monitors have names of the form +username:suffix where suffix is +chosen by the user who defines the monitor. + +
devicesets + +: These are LED groups; each deviceset must be tied to exactly one +monitor; the configuration specifies a mapping from monitor result +states to LED values. + +Devicesets are not explicitly named, but when ledctrl needs to refer +to them it may do so by the username who defined them and the line +number in their configuration, or sometimes by the destination host(s) +and port(s) in the specified LED group. + +

+ +Note that you can refer in your configuration to another users' +monitors. This allows you to share monitor configuration. There are +two monitors provided as a general service by the system +administration, currently via the user ijackson: + +

ijackson:#chiark +
ijackson:#starcraft +

+ +Consult ~ijackson/.userv/irc-ledcontrol-config for exact +details. To suggest changes to this configuration, consult +ircop@chiark. + +

+ +If you define a deviceset which refers to a nonexistent monitor, it +will be silently ignored. + +

Configuration syntax

+ +The configuration file is line-based. Leading and trailing whitespace +on each line is ignored. Comment lines (starting with #) +and blank lines are ignored. Lines (including comment lines) may be +continued using \. + +

+ +

Configuration directives

+ +

+monitor monname #chan [#chan ...] +

+Defines a monitor named monname which monitors the +specified channel(s). monname must start with +username: where username is the +username whose file the directive occurs in. + +

+nick ignore [glob-pattern ...] +

+Defines a list of nick patterns to completely ignore. No activity on +the part of nicks matching any of the patterns will have any effect. +

+Affects all monitors defined, until the next nick ignore. + +

+nick nopresence [glob-pattern ...] +

+Defines a list of nick patterns to ignore when deciding whether anyone +is present. If the affected nicks speak in channel they will still +count. +

+Affects all monitors defined, until the next nick nopresence. + +

+nick prefer [glob-pattern ...] +

+Defines a list of nick patterns to be extra interested in, when they +talk on channel. See the preftalk and +preftalknow monitor state conditions in the +leds directive, below. + +

+Affects all monitors defined, until the next nick nopresence. + +

+ +Important: Use of this directive can amount to fairly +intrusive monitoring of the activity of the affected nicks. +Ask permission from the target before using this +directive on a real person. ledctrl will inform the target of the +surveillance. + +

+times talk-now-time talk-time +

+Specifies the times, in seconds, for which someone speaking in channel +will satisfy the talknow and talk +conditions, respectively. talk-now-time should be no more +than talk-time. + +

Affects all monitors defined, until the next times. +The initial values are 120 and 450. + +

+leds led-group monname state=value ... +

+Defines an LED group, driven by monname. Each time the +monitor's state changes, the list of states will be searched, and the +first which is true for the monitor's new state will take effect. If +none of the states apply then the LEDs are left unchanged. +

+ +The state conditions are: +

talk +: Someone has spoken on channel since talk-time ago. + +
talknow +: Someone has spoken on channel since talk-now-time ago. + +
preftalk +: Someone matching nick prefer has spoken on channel +since talk-time ago. + +
preftalknow +: Someone matching nick prefer has spoken on channel +since talk-now-time ago. + +
present +: Someone (not matching nick nopresence) is present on +channel. ledctrl itself does not count. + +
default +: Always true. Put this at the end of the state list. + +

+ +

+led-group and each value +should be as specified in the LED protocol document. The LED group +will be accessed in an exclusive manner and should not be accessed by +any other LED clients. + +

userv

+ +Actually, the configuration is all done with userv. The system +supplies default implementations of the two services +

+irc-ledcontrol-config
+irc-ledcontrol-passwords
+

+which simply spit out the relevant files. + +

+ +The irc-ledcontrol-config service must succeed; +if you do not want ledctrl configuration it should exit zero without +printing any output at all. + +

+ +If irc-ledcontrol-config produces any output (even just +whitespace or comments) then irc-ledcontrol-passwords +must succeed, and produce a standard format LED password file. +(See the +LED +specification documents.) + +

+ +

+ $Id$ + ircop@chiark +

+ + diff --git a/ledhelp b/ledhelp index e94f74d..567c6f9 100644 --- a/ledhelp +++ b/ledhelp @@ -5,8 +5,8 @@ Commands: debug ... turn on debugging (causes lag!) nodebug turn off debugging help display this help -See - http://... for full information +For full information, see: + http://cabal.greenend.org.uk/chiark-info/irc-ledctrl.html # Local variables: # fill-column: 69 diff --git a/ledmodule.tcl b/ledmodule.tcl index f3231de..e07b046 100644 --- a/ledmodule.tcl +++ b/ledmodule.tcl @@ -1,36 +1,5 @@ -# maintains local list of users to userv-slurp config from -# each user provides list of -# monitors -# devicesets -# -# a monitor specifies -# name -# IRC channel(s) -# nicks ignore totally -# nicks ignore presence -# nicks prefer speech -# time for `a while ago' -# time for `very-recently' -# syntax -# nick ignore|nopresence|prefer [...] -# times

(default 120 450) -# (affect subsequent `monitor' directives) -# monitor <#chan>[,<#chan>...] -# must start with : -# -# a deviceset specifies -# monitor -# led-group -# led states -# syntax -# leds = -# where state is one of -# [pref]talk[now] any non-ignored (with `pref', only any preferred) -# nick(s) spoke at least somewhat recently -# (with `now', only if they spoke very recently) -# present at least some non-nopresence nicks present -# default always matches -# where the first matching state wins; if none, no LEDs are set +# see ledbot.html +# $Id$ set helpfile ledhelp