| 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><ledctrl> 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: ledbot.html,v 1.2 2002-06-24 10:02:11 ijackson Exp $ |
| 288 | <A href="mailto:ircop@chiark.greenend.org.uk">ircop@chiark</A> |
| 289 | </address> |
| 290 | </body> |
| 291 | </html> |