ledbot.html

   1 <html>
   2   <head>
   3     <title>chiark ledctrl bot</title>
   4     <link rev="made" href="mailto:ircop@chiark.greenend.org.uk">
   5   </head>
   6   <body>
   7     <h1>chiark ledctrl bot</h1>
   8
   9 The ledctrl bot exists to allow users to have activity on channels
  10 they're interested in reported on LEDs via the <a
  11 href="http://www.chiark.greenend.org.uk/~ijackson/leds/">LED control
  12 protocol</a>.
  13
  14 <h2>Privacy</h2>
  15
  16 ledctrl does not make any information about content of IRC sessions
  17 available to anyone, not even its operator (ijackson, acting as
  18 ircop).  It does look for activity on the channels it sits on and
  19 report to its users whether there is activity, but the information
  20 made available is not very much.
  21
  22 <p>
  23
  24 It can watch preferentially for individual users, but this facility
  25 should not be used without the prior consent of the target.  ledctrl
  26 will notify the target that they are being watched.
  27
  28 <p>
  29
  30 If you want to know who is being told information about IRC activity,
  31 say
  32 <pre>
  33 /msg ledctrl who
  34 </pre>
  35 and it will report something like this
  36 <pre>
  37 -ledctrl- monitoring #starcraft for ijackson:sc
  38 -ledctrl- monitoring #test for ijackson:#test
  39 -ledctrl- sending ijackson:sc to ijackson, davenant.relativity.greenend.org.uk:1447
  40 -ledctrl- sending ijackson:#test to ijackson, davenant.relativity.greenend.org.uk:1447
  41 </pre>
  42 In this example, the channels <code>#starcraft</code> and <code>#test</code>
  43 are being monitored on behalf of ijackson, who has chosen to name the
  44 monitoring functions <code>ijackson:sc</code> and
  45 <code>ijackson:#test</code>.  The results are being sent only to the
  46 LED server on port 1447 of davenant.relativity.greenend.org.uk:1447,
  47 also on behalf of ijackson.
  48
  49 <h2>Usage</h2>
  50
  51 If you want to use this facility:
  52
  53 <ol>
  54
  55 <li> Make sure that your LED server is operating properly, and that you
  56 can use <code>remoteleds</code> on chiark to manipulate the relevant LEDs.
  57
  58 <li> If you're using a nonzero password (which is recommended, as
  59 otherwise any other chiark user could interfere with your LEDs), copy
  60 the <code>.led-client-pass</code> that you're using to
  61 <code>~/.userv/irc-ledcontrol-passwords</code> (taking care to make
  62 sure it's not world-readable).
  63
  64 <li> Write the configuration file saying which channels to monitor and
  65 where to send the answers.  Put it in
  66 <code>~/.userv/irc-ledcontrol-config</code>.  See below for the file
  67 format.
  68
  69 <li> Join <code>#ledctrl</code>.  This is where the debug and
  70 diagnostic output goes.  You should also look here if it seems not to
  71 be working at some later point.  When you think everything is right, say
  72 <code>/msg ledctrl reload <var>username</var></code>
  73 where <var>username</var> is your own username.  If all is well it
  74 should just say
  75 <samp>&lt;ledctrl&gt; reloaded <var>username</var></samp>
  76 and shortly afterwards your LEDs should be set.
  77
  78 <li> If you still can't get it to work, say
  79 <code>/msg ledctrl debug <var>username</var></code>
  80 and see if you can make any sense of the output.  NB that this
  81 produces lots of output in the channel, which will disrupt other
  82 people's use of it, and cause ledctrl to become lagged, so please
  83 don't leave the debug enabled.  It will turn itself off after a while
  84 anyway.
  85
  86 <li> If you decide you don't want to use ledctrl any more, delete
  87 your config file and say <kbd>/msg ledctrl reload
  88 <var>username</var></kbd>, which will cause ledctrl to forget about
  89 your configuration (and any stored passwords).
  90
  91 </ol>
  92
  93 <h2>Configuration model</h2>
  94
  95 The file <code>~/.userv/irc-ledcontrol-config</code> contains the
  96 configuration file for your ledctrl settings.  If this file doesn't
  97 exist, ledctrl will assume you don't want it to run on your behalf.
  98
  99 <p>
 100
 101 The file may contain definitions of two kinds of objects:
 102
 103 <dl>
 104
 105 <dt>Monitors
 106
 107 <dd>These are specifications of channels to monitor, activity
 108 timeouts, and nicks to ignore, etc.  Each monitor at any particular
 109 time has a particular result state which depends only on its
 110 configuration and activity on the channel.
 111
 112 <p>
 113
 114 Monitors have names of the form
 115 <code><var>username</var>:<var>suffix</var></code> where suffix is
 116 chosen by the user who defines the monitor.
 117
 118 <dt>devicesets
 119
 120 <dd>These are LED groups; each deviceset must be tied to exactly one
 121 monitor; the configuration specifies a mapping from monitor result
 122 states to LED values.
 123
 124 Devicesets are not explicitly named, but when ledctrl needs to refer
 125 to them it may do so by the username who defined them and the line
 126 number in their configuration, or sometimes by the destination host(s)
 127 and port(s) in the specified LED group.
 128
 129 </dl>
 130
 131 Note that you can refer in your configuration to another users'
 132 monitors.  This allows you to share monitor configuration.  There are
 133 two monitors provided as a general service by the system
 134 administration, currently via the user ijackson:
 135
 136 <ul>
 137 <li><code>ijackson:#chiark</code>
 138 <li><code>ijackson:#starcraft</code>
 139 </ul>
 140
 141 Consult <code>~ijackson/.userv/irc-ledcontrol-config</code> for exact
 142 details.  To suggest changes to this configuration, consult
 143 ircop@chiark.
 144
 145 <p>
 146
 147 If you define a deviceset which refers to a nonexistent monitor, it
 148 will be silently ignored.
 149
 150 <h2>Configuration syntax</h2>
 151
 152 The configuration file is line-based.  Leading and trailing whitespace
 153 on each line is ignored.  Comment lines (starting with <code>#</code>)
 154 and blank lines are ignored.  Lines (including comment lines) may be
 155 continued using <code>\</code>.
 156
 157 <p>
 158
 159 <h3>Configuration directives</h3>
 160
 161 <dl>
 162 <dt>
 163 <code>monitor <var>monname</var> <var>#chan</var> [<var>#chan ...</var>]</code>
 164 <dd><p>
 165 Defines a monitor named <var>monname</var> which monitors the
 166 specified channel(s).  <var>monname</var> must start with
 167 <code><var>username</var>:</code> where <var>username</var> is the
 168 username whose file the directive occurs in.
 169
 170 <dt>
 171 <code>nick ignore [<var>glob-pattern</var> ...]</code>
 172 <dd><p>
 173 Defines a list of nick patterns to completely ignore.  No activity on
 174 the part of nicks matching any of the patterns will have any effect.
 175 <p>
 176 Affects all monitors defined, until the next <code>nick ignore</code>.
 177
 178 <dt>
 179 <code>nick nopresence [<var>glob-pattern</var> ...]</code>
 180 <dd><p>
 181 Defines a list of nick patterns to ignore when deciding whether anyone
 182 is present.  If the affected nicks speak in channel they will still
 183 count.
 184 <p>
 185 Affects all monitors defined, until the next <code>nick nopresence</code>.
 186
 187 <dt>
 188 <code>nick prefer [<var>glob-pattern</var> ...]</code>
 189 <dd><p>
 190 Defines a list of nick patterns to be extra interested in, when they
 191 talk on channel.  See the <code>preftalk</code> and
 192 <code>preftalknow</code> monitor state conditions in the
 193 <code>leds</code> directive, below.
 194
 195 <p>
 196 Affects all monitors defined, until the next <code>nick noprefer</code>.
 197
 198 <p>
 199
 200 <strong>Important</strong>: Use of this directive can amount to fairly
 201 intrusive monitoring of the activity of the affected nicks.
 202 <strong>Ask permission</strong> from the target before using this
 203 directive on a real person.  ledctrl will inform the target of the
 204 surveillance.
 205
 206 <dt>
 207 <code>times <var>talk-now-time</var> <var>talk-time</var></code>
 208 <dd><p>
 209 Specifies the times, in seconds, for which someone speaking in channel
 210 will satisfy the <code>talknow</code> and <code>talk</code>
 211 conditions, respectively.  <var>talk-now-time</var> should be no more
 212 than <var>talk-time</var>.
 213
 214 <p> Affects all monitors defined, until the next <code>times</code>.
 215 The initial values are 120 and 450.
 216
 217 <dt>
 218 <code>leds <var>led-group</var> <var>monname</var> <var>state</var>=<var>value</var> ...</code>
 219 <dd><p>
 220 Defines an LED group, driven by <var>monname</var>.  Each time the
 221 monitor's state changes, the list of states will be searched, and the
 222 first which is true for the monitor's new state will take effect.  If
 223 none of the states apply then the LEDs are left unchanged.
 224 <p>
 225
 226 The state conditions are:
 227 <dl>
 228 <dt><code>talk</code>
 229 <dd>Someone has spoken on channel since <var>talk-time</var> ago.
 230
 231 <dt><code>talknow</code>
 232 <dd>Someone has spoken on channel since <var>talk-now-time</var> ago.
 233
 234 <dt><code>preftalk</code>
 235 <dd>Someone matching <code>nick prefer</code> has spoken on channel
 236 since <var>talk-time</var> ago.
 237
 238 <dt><code>preftalknow</code>
 239 <dd>Someone matching <code>nick prefer</code> has spoken on channel
 240 since <var>talk-now-time</var> ago.
 241
 242 <dt><code>present</code>
 243 <dd>Someone (not matching <code>nick nopresence</code>) is present on
 244 channel.  ledctrl itself does not count.
 245
 246 <dt><code>default</code>
 247 <dd>Always true.  Put this at the end of the state list.
 248
 249 </dl>
 250
 251 <p>
 252 <var>led-group</var> and each <var>value</var>
 253 should be as specified in the LED protocol document.  The LED group
 254 will be accessed in an exclusive manner and should not be accessed by
 255 any other LED clients.
 256
 257 <h2>userv</h2>
 258
 259 Actually, the configuration is all done with userv.  The system
 260 supplies default implementations of the two services
 261 <pre>
 262 irc-ledcontrol-config
 263 irc-ledcontrol-passwords
 264 </pre>
 265 which simply spit out the relevant files.
 266
 267 <p>
 268
 269 The <code>irc-ledcontrol-config</code> service <em>must</em> succeed;
 270 if you do not want ledctrl configuration it should exit zero without
 271 printing any output at all.
 272
 273 <p>
 274
 275 If <code>irc-ledcontrol-config</code> produces any output (even just
 276 whitespace or comments) then <code>irc-ledcontrol-passwords</code>
 277 must succeed, and produce a standard format LED password file.
 278 (See the
 279 <a
 280 href="http://www.chiark.greenend.org.uk/~ijackson/leds/">LED
 281 specification documents</a>.)
 282
 283 </dl>
 284
 285   <hr>
 286   <address>
 287     $Id$
 288     <A href="mailto:ircop@chiark.greenend.org.uk">ircop@chiark</A>
 289   </address>
 290   </body>
 291 </html>