Commit | Line | Data |
---|---|---|
3e580664 IJ |
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> | |
5954eb58 | 42 | In this example, the channels <code>#starcraft</code> and <code>#test</code> |
3e580664 IJ |
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> | |
5954eb58 | 196 | Affects all monitors defined, until the next <code>nick noprefer</code>. |
3e580664 IJ |
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> | |
5954eb58 | 287 | $Id: ledbot.html,v 1.2 2002-06-24 10:02:11 ijackson Exp $ |
3e580664 IJ |
288 | <A href="mailto:ircop@chiark.greenend.org.uk">ircop@chiark</A> |
289 | </address> | |
290 | </body> | |
291 | </html> |