[ircbot] / ledbot.html

<html>
  <head>
    <title>chiark ledctrl bot</title>
    <link rev="made" href="mailto:ircop@chiark.greenend.org.uk">
  </head>
  <body>
    <h1>chiark ledctrl bot</h1>

The ledctrl bot exists to allow users to have activity on channels
they're interested in reported on LEDs via the <a
href="http://www.chiark.greenend.org.uk/~ijackson/leds/">LED control
protocol</a>.

<h2>Privacy</h2>

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.

<p>

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.

<p>

If you want to know who is being told information about IRC activity,
say
<pre>
/msg ledctrl who
</pre>
and it will report something like this
<pre>
-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
</pre>
In this example, the channels <code>#starcraft</code> and <code>#test</code>
are being monitored on behalf of ijackson, who has chosen to name the
monitoring functions <code>ijackson:sc</code> and
<code>ijackson:#test</code>.  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.

<h2>Usage</h2>

If you want to use this facility:

<ol>

<li> Make sure that your LED server is operating properly, and that you
can use <code>remoteleds</code> on chiark to manipulate the relevant LEDs.

<li> If you're using a nonzero password (which is recommended, as
otherwise any other chiark user could interfere with your LEDs), copy
the <code>.led-client-pass</code> that you're using to
<code>~/.userv/irc-ledcontrol-passwords</code> (taking care to make
sure it's not world-readable).

<li> Write the configuration file saying which channels to monitor and
where to send the answers.  Put it in
<code>~/.userv/irc-ledcontrol-config</code>.  See below for the file
format.

<li> Join <code>#ledctrl</code>.  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
<code>/msg ledctrl reload <var>username</var></code>
where <var>username</var> is your own username.  If all is well it
should just say
<samp>&lt;ledctrl&gt; reloaded <var>username</var></samp>
and shortly afterwards your LEDs should be set.

<li> If you still can't get it to work, say
<code>/msg ledctrl debug <var>username</var></code>
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.

<li> If you decide you don't want to use ledctrl any more, delete
your config file and say <kbd>/msg ledctrl reload
<var>username</var></kbd>, which will cause ledctrl to forget about
your configuration (and any stored passwords).

</ol>

<h2>Configuration model</h2>

The file <code>~/.userv/irc-ledcontrol-config</code> 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.

<p>

The file may contain definitions of two kinds of objects:

<dl>

<dt>Monitors

<dd>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.

<p>

Monitors have names of the form
<code><var>username</var>:<var>suffix</var></code> where suffix is
chosen by the user who defines the monitor.

<dt>devicesets

<dd>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.

</dl>

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:

<ul>
<li><code>ijackson:#chiark</code>
<li><code>ijackson:#starcraft</code>
</ul>

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

<p>

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

<h2>Configuration syntax</h2>

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

<p>

<h3>Configuration directives</h3>

<dl>
<dt>
<code>monitor <var>monname</var> <var>#chan</var> [<var>#chan ...</var>]</code>
<dd><p>
Defines a monitor named <var>monname</var> which monitors the
specified channel(s).  <var>monname</var> must start with
<code><var>username</var>:</code> where <var>username</var> is the
username whose file the directive occurs in.

<dt>
<code>nick ignore [<var>glob-pattern</var> ...]</code>
<dd><p>
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.
<p>
Affects all monitors defined, until the next <code>nick ignore</code>.

<dt>
<code>nick nopresence [<var>glob-pattern</var> ...]</code>
<dd><p>
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.
<p>
Affects all monitors defined, until the next <code>nick nopresence</code>.

<dt>
<code>nick prefer [<var>glob-pattern</var> ...]</code>
<dd><p>
Defines a list of nick patterns to be extra interested in, when they
talk on channel.  See the <code>preftalk</code> and
<code>preftalknow</code> monitor state conditions in the
<code>leds</code> directive, below.

<p>
Affects all monitors defined, until the next <code>nick noprefer</code>.

<p>

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

<dt>
<code>times <var>talk-now-time</var> <var>talk-time</var></code>
<dd><p>
Specifies the times, in seconds, for which someone speaking in channel
will satisfy the <code>talknow</code> and <code>talk</code>
conditions, respectively.  <var>talk-now-time</var> should be no more
than <var>talk-time</var>.

<p> Affects all monitors defined, until the next <code>times</code>.
The initial values are 120 and 450.

<dt>
<code>leds <var>led-group</var> <var>monname</var> <var>state</var>=<var>value</var> ...</code>
<dd><p>
Defines an LED group, driven by <var>monname</var>.  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.
<p>

The state conditions are:
<dl>
<dt><code>talk</code>
<dd>Someone has spoken on channel since <var>talk-time</var> ago.

<dt><code>talknow</code>
<dd>Someone has spoken on channel since <var>talk-now-time</var> ago.

<dt><code>preftalk</code>
<dd>Someone matching <code>nick prefer</code> has spoken on channel
since <var>talk-time</var> ago.

<dt><code>preftalknow</code>
<dd>Someone matching <code>nick prefer</code> has spoken on channel
since <var>talk-now-time</var> ago.

<dt><code>present</code>
<dd>Someone (not matching <code>nick nopresence</code>) is present on
channel.  ledctrl itself does not count.

<dt><code>default</code>
<dd>Always true.  Put this at the end of the state list.

</dl>

<p>
<var>led-group</var> and each <var>value</var>
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.

<h2>userv</h2>

Actually, the configuration is all done with userv.  The system
supplies default implementations of the two services
<pre>
irc-ledcontrol-config
irc-ledcontrol-passwords
</pre>
which simply spit out the relevant files.

<p>

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

<p>

If <code>irc-ledcontrol-config</code> produces any output (even just
whitespace or comments) then <code>irc-ledcontrol-passwords</code>
must succeed, and produce a standard format LED password file.
(See the
<a
href="http://www.chiark.greenend.org.uk/~ijackson/leds/">LED
specification documents</a>.)

</dl>

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