1I2M3806(1) GNU Info I2M3806(1)
2
6 miau.info - miau.info
7
9 This is edition 0.6.1 of the `miau Manual', last updated 7 January
10 2006.
11 * Menu:
13 Why you need an irc-bouncer and how it is used: see "Introduction"
15 How to install miau: see "Installation"
17 Invocation of miau: see "Command Line Options"
19 Commands while miau is running: see "miau Commands"
21 Statements in your miaurc: see "miaurc Commands"
23 1 What is an irc-bouncer?
25 A bouncer doesn't do anything else than diverting a network-connection.
27 In case of an irc-bouncer, connections from your irc-program (client)
29 are diverted by the bouncer to a irc-server.
30 "What is this good for?", you might ask.
32 Well, let's assume you've got a dialup-connection. If somebody per‐
34 forms a `/WHOIS' on you it shows something like "yournick is your‐
35 nick!yourident@dialup66-r-v.isp.at".
36 If you are vain you don't want people to see this stupid hostname. So
38 you get a account on a machine with a cool hostname (from now on ref‐
39 ered as middleman), get miau running there and a /whois on you will
40 show middleman's hostname, since the connection to the irc-server is
41 actually originating from middleman.
42 Another advantage is that network-attacks aren't really destinating to
44 YOUR computer but to middleman, which is in theory a machine that can't
45 be brought down.
46 2 What makes miau special over other bouncers?
48 **********************************************
49 miau is very straight and simple to set up and the probably most impor‐
51 tant and interesting feature is that miau keeps the middleman -> irc-
52 server connection up even after you disconnect with your client.
53 This means miau prevents people from using your nick (this is espe‐
55 cially handy on nets like IRCNet, since there are no services like on
56 dalnet etc) and tells people who message you that you're not here and
57 logs what these people said.
58 Upon your next connect to miau, it will let the channels you've been in
60 in your last session pop up, which means that you'll keep your status
61 in these channels.
62 Besides that miau's got a sophisticated flood-protection making it
64 (almost) impossible to disconnect miau.
65 3 Copyright ***********
67 miau has been written by Tommi Saviranta <wnd@iki.fi>. miau branched
69 from muh, see http://mind.riot.org/muh/. miau is licensed under the
70 GPL. See COPYING for details.
71 4 Command Line Options
73 `-f' Stay in foreground (don't fork)
75 `-d directory' Specifies a different directory than the default for
77 miaurc, messages and log
78 `-c' You will be prompted for a word to crypt. The output can be used
80 as `password' in miaurc if you don't wanna have the password stored in
81 clear text. Note that you'll still have to authorize with the unen‐
82 crypted password.
83 This option might not be compiled in.
85 5 miau Commands
87 miau accepts following commands to be issued by the client via `/MIAU
89 <command>'.
90 Note that some IRC-clients might require a prefix such as `/QUOTE' or
92 `/RAW' to send commands they don't know about.
93 `HELP' Display supported commands
95 `READ' Read received messages
97 `DEL' Delete all messages
99 `PRINT' Prints miau's server-list. Servers prefixed with '+' work,
101 those with '-' don't.
102 `JUMP [servernumber]' Jump to next server in serverlist. If `servernum‐
104 ber' (see `PRINT') is specified, miau will jump to this server (even if
105 marked as not working).
106 `REHASH' Reread config-file. Note that this can also be performed by
108 sending a `SIGHUP' to miau (see `kill(1)'). If `realname' or `username'
109 have been changed miau will reconnect to it's current server.
110 `DIE [reason]' Terminate miau. A quit reason can be given after com‐
112 mand.
113 `UPTIME' Prints uptime of miau.
115 This command might not be compiled in.
117 `PINGSTAT' Prints ping statistics.
119 This command might not be compiled in.
121 `DUMP' Prints some of miau's internal variables. Used for debugging.
123 This command might not be compiled in.
125 6 Installation
127 Create a `.miau/'-directory in your homedir and copy `miaurc' there (it
129 will probably reside in `/usr/share/miau', depending on your os/distri‐
130 bution).
131 Edit `miaurc', _make sure noone except you has read-access_ and launch
133 miau.
134 To make sure miau's running all day there is a script called `miau-
136 check' that came with miau. Edit it as well and make `crontab(5)' call
137 it periodically.
138 7 miaurc Commands
140 There are numerous commands with which you can extensively customize
142 miau's behaviour. The must be placed in the `miaurc' that miau reads on
143 startup, it is usually `$HOME/.miau/miaurc'.
144 8 Required settings *******************
146 `nicknames = { "nick" }' Your nickname (and secondary nicknames) on
148 IRC. If the primary nick (first nick on the list) is already on use,
149 miau will try the others on the list.
150 `realname = "realname"' Your "real" name (which will be shown by
152 `/WHOIS'-command) on IRC.
153 `username = "username"' Your ident (matters only if you don't have
155 `identd' running).
156 `password = "password"' The password miau will expect to receive from
158 client when it's registering with nick. If this is 13 characters long,
159 miau assumed it's crypted. miau can generate password-hashes with `-c'
160 -switch, if it is compiled with that feature.
161 `listenport = "port"' The port miau will wait for incoming connections.
163 This is the port you connect your IRC-client to.
164 `servers = { "server":"port":"password":"timeout" }' miau's
166 IRC-server-list. Each line represents one server, where timeout is
167 delay in seconds before connectiong attempt times out. Only `server'
168 parameter is required.
169 `connhosts = { "host":"permitted" }' List of hosts that are allowed (or
171 denied) to connect to miau. When `permitted' is left unset, it is
172 assumed to be `true'. This list will be processed as a chain which
173 means latter rules can override previous ones.
174 Note: You can define "your" hostname with `@@'. Only the _last_ occu‐
176 rance of `@@' will be translated.
177 9 Optional settings *******************
179 `statelog = "state"' Should miau write state log to `$MIAUDIR/log'?
181 When true, log will be written in this file. If set to false, the same
182 stuff is printed on `stdout' (on terminal).
183 `listenhost = "host"' Host miau uses to listen on. If you are compiled
185 with IPV6 and need this to listen on an IPV4 port, you must use an IP
186 in the form `::FFFF:127.0.0.1'.
187 `floodtimer = "number"' Time it takes to send one message. When config‐
189 uring flood-protection, this variable defined how fast you can send
190 messages; how many seconds sending one message takes. See also `burst‐
191 size'.
192 `burstsize = "number"' How many messages can be sent at once. When con‐
194 figuring flood-protection, this variable defined how many messages can
195 be sent at once (in a burst). See also `floodtimer'.
196 `jointries = "number"' Number of tries to join channel after dropping
198 from server etc. miau tries to join channels once a minute.
199 `bind = "host"' Host/IP miau uses for outgoing connections.
201 `maxclients = "number"' Maximum number of clients connected to miau
203 concurrently. Set to zero for unlimited clients.
204 `stonedtimeout = "seconds"' Time (in seconds) with no data from the
206 server before it is declared stoned and being disconnected. Although
207 minimum value is 30, this value has no upper limit. Watch out, though,
208 if this value is set too high, death of servers may stay undetected for
209 a very long time if you are idle.
210 `connecttimeout = "seconds"' Time (in seconds) before connection
212 attampt will time out. Note that while connecting to the server miau
213 will not respond to clients. Minimum value is 5, and many systems
214 define maximum value.
215 `channels = { "channel":"keyword" }' List of channels to join.
217 `rejoin = "state"' Rejoin channels after disconnecting from the server.
219 If `rejoin' is set to `true', channels defined in `channels'" are also
220 joined when client first time connects to miau.
221 `leave = "state"' Leave channels when all clients have detached from
223 miau. If `leave' is set to `false' and `rejoin' is set to `true',
224 channels defined at `channels' will be joined at miau startup. If both
225 `leave' and `rejoin' is set to `true', channels that are left at client
226 detach, are rejoined when client attached back to miau.
227 `leavemsg = "message"' Message miau will either use as PART-message or
229 as ACTION when all clients have detached from miau. If unset or set to
230 empty, no message will be shown. Note that many people dislike event-
231 based messages (which happens when `leave' is set to `false' and
232 `leavemsg' is set). Note that commenting this option out and rehashing
233 after `leavemsg' was set, this option is _not_ reverted. To disable
234 `leavemsg' afterwards you need to write an empty string here and
235 rehash. Also see `usequitmsg'.
236 `awaymsg = "message"' Text that will be set to miau's away-reason when
238 all clients have detached from miau. If unset or set to empty, AWAY-
239 status will be left untouched. When any client attaches back to miau,
240 AWAY-status will be reset. Note that is user sets him/herself away,
241 miau will _not_ touch away-status nor message neither when connecting
242 to or disconnected from miau. Also note that commenting this option out
243 and rehashing after `awaymsg' was set, this option is _not_ reverted.
244 To disable `awaymsg' afterwards you need to write an empty string here
245 and rehash. Also see `usequitmsg'.
246 `usequitmsg = "state"' Use last quit-reason as away-reason and/or
248 leave-message (if respective options are enabled) when all clients have
249 disconnected from miau. If quit-reason was empty, default values of
250 awaymsg and leavemsg will be used, otherwise most recent quit-message
251 overrides values in miaurc.
252 `autoaway = "mode"' miau can set user away automatically. This option
254 allows to define when to do that: `never' Never set user away automati‐
255 cally
256 `detach' Set user away when any of the clients disconnects
258 `noclients' Set user away when the last client disconnects If `use‐
260 quitmsg' is set, quit message will be used as a reason. If not,
261 `awaymsg' will be used.
262 `chandiscon = "mode"' When miau is disconnected from the server e.g.
264 because of network problem, miau can notify user about this in a couple
265 of ways. `nothing' Only print server notice
266 `notice' Send notice to each channel
268 `part' Part each channel. mIRC users probably don't want to use this.
270 `privmsg' Only send a private message to the user
272 `getnick = "selection"' miau can try to reclaim your primary nick when
274 it is lost. This option may be one of the following: `never' miau will
275 not try to get your nick back
276 `detached' miau will try to get your nick when no clients are attached
278 `attached' miau will try to get your nick when there are one or more
280 clients attached
281 `always' miau will try to get your nick Note: do _not_ use options
283 `attached' and `always' with clients (like irc-II EPIC) that automati‐
284 cally change your nick when they receive `ERR_NICKINUSE' from the
285 server - you might end up chaning your nick until server drops your
286 connection due excess (nick) flood.
287 `getnickinterval = "seconds"' Time between tries (in seconds) to obtain
289 currently (possibly) lost primary nick. Don't set it too low or you
290 might get kicked out the server due to excess flood.
291 `antiidle = "minutes"' Time between idle-timer resets in minutes. Set
293 to 0 to disable.
294 `qloglength = "minutes"' Age of oldest entry in quicklog in minutes.
296 Set to zero to disable quicklog.
297 Note: private messages get also logged into quicklog, but if `inbox' is
299 enabled, they are moved to messagelog instead of simply dropping of
300 from quicklog.
301 This option might not be compiled in.
303 `timestamp = "mode"' Location of timestamp in quicklog.
305 Available modes: `none' No timestamp
307 `beginning' Timestamp in beginning of line
309 `end' Timestamp at end of line
311 This options might not be compiled in.
313 `flushqlog = "state"' If set to `true', quicklog will be written only
315 when no clients are connected and quicklog will be erased when client
316 connects to miau. If you are running a single client, you probably want
317 to leave this to `false'.
318 This option might not be compiled in.
320 `inbox = "state"' Enables logging private messages when no clients are
322 connected to miau.
323 Note: if quicklog is enabled (see `qloglength'), private messages are
325 first stored in quicklog and moved to messagelog when they become too
326 old to be stored in quicklog.
327 This option might not be compiled in.
329 `nevergiveup = "state"' If set to `true', miau will reset "work‐
331 ing"-status of servers to working when all are set to dysfunctional.
332 Respectively, if set to `false', miau will quit when all servers on the
333 list have been set to dysfunctional.
334 `norestricted = "state"' If set to `true', miau will not stay on server
336 that forces user to have restricted-status (+r).
337 `reconnectdelay = "seconds"' Time (in seconds) between connection
339 attempts. Minumun value is set to 1.
340 `nickfillchar = "fill character"' Character used to modify your primary
342 nick when all defined nicks are already occupied. Note character is a
343 single octet (byte) and if longer string is fed, only the first charac‐
344 ter is used.
345 `maxnicklen = "length"' Maximum nick length, used with `nickfillchar'.
347 `usermode = "usermode(s)"' Usermode that miau will request (if no
349 clients are attached at the moment) from the server when connection to
350 the server is established. Leave unset or set to empty to disable this
351 feature.
352 `forwardmsg = "command"' miau can collect the (private) messages within
354 specified time (see `forwardtime') and pipe them into the program spec‐
355 ified. Leave this unset or set to empty to disable this feature.
356 `forwardtime = "seconds"' Time in seconds after first inserted line
358 into forwardmsg queue before piping the stuff out. Default is 180 sec‐
359 onds (or three mintues).
360 `ignore = { "mask":"ignored" }' List of users whose private messages
362 (PRIVMSG) and noticies (NOTICE) are ignored when no clients are
363 attached to miau. When `ignored' is left undefined, it is assumed to be
364 `true'. Setting `ignored' to `false' means that this user will _not_ be
365 ignored. This list is processed as a chain.
366 Note: You can define "your" hostname with @@. Only the _last_ occurance
368 of @@ will be translated.
369 `privlog = "mode"' Whatever private messages should be logged in nick-
371 specific files. Can be one of following: `never' never write private
372 message logs
373 `detached' write private message logs only when there are no clients
375 connected
376 `attached' write private logs only when there are clients connected
378 `always' always write private message logs
380 All logfiles are written into miau's log directory (`logs').
382 This option might not be compiled in.
384 `chanlog = { "channel(s)":"options":"logfile" }' List of channel log‐
386 files.
387 When channel is set to `*', line represents global log. When logging,
389 if channel doesn't have entry of it's own in this list, it will use
390 settings of global log and write log to it's own file. When defining
391 global log, `logfile' is ignored. Each line can have multiple channels
392 (like `#foobar,#miau').
393 If logfile is left undefined, logfile will be named after the channel
395 with possible suffix (see `logsuffix'). All filenames are relative and
396 are, by default, written in miau's log directory (`logs').
397 Options consist of abritary set of following possibilities: `j' log
399 joins
400 `e' log parts (exits)
402 `q' log quits
404 `m' log messages (privmsg/notice)
406 `c' log mode changes
408 `n' log nick changes
410 `o' log misc events (other)
412 `b' log messages from miau (bouncer)
414 `a' log all of above
416 `A' log when a client is attached
418 `D' log when a client is detached
420 `C' log continuously (status of clients doesn't matter)
422 Note that all channelless messages (such as QUIT) are logged on every
424 active channel. This is a feature, not a bug.
425 This option might not be compiled in.
427 `logsuffix = "suffix"' When writing log to undefined logfile, each log‐
429 file consists of channel name followed by suffix. Suffix can be defined
430 here.
431 `onconnect = { "mode":"target/data"(:"data") }' When miau connects and
433 registers user to server, miau can send pre-defined messages. User can
434 define miau to send normal messages (`PRIVMSG'), notices (`NOTICE') or
435 arbitrary messages.
436 Mode can be one of the following: `p' private message (`PRIVMSG').
438 `n' notice (`NOTICE'). Should be used with services and automatons,
440 but unfortunately some network services can't cope with notices.
441 `r' "raw" message. This means user must provide complete message to
443 send to the server. Using raw message user has complete control over
444 what is being sent. If you don't know what this is, you don't need
445 this. When using modes "`p'" or "`n'", user must provide both
446 message and target where as with raw messages only one parameter in
447 addition to type should be given.
448 This option might not be compiled in.
450 `automodes = { "mask":"privilegded" }' List of people who are automati‐
452 cally given certain privilege on channel. Mask is given in form of
453 `mode:nick!username@host/#channel' (where `mode' is a single character)
454 and list is processed as a chain.
455 Note: You can define "your" hostname with @@. Only the _last_ occurance
457 of @@ will be translated.
458 This option might not be compiled in.
460 `automodedelay = "seconds"' Time (in seconds) after first queued mode
462 change would take effect. During this period of time miau can collect
463 more than one mode change and commit up to three at a time. Other situ‐
464 ation reasonaly big value (like 30) here could prove useful is channel
465 where there are stupid "auto-oping" bots. (Stupid bots do mode changes
466 even if someone else did that already.)
467 This option might not be compiled in.
469 `cmdpasswd = "password"' Password for remote commands. If this is 13
471 characters long, miau assumes it's crypted. Comment this out or leave
472 it empty to disable remote commands. When sending miau a remote com‐
473 mand, password _always_ begins with column (':') (if `cmdpasswd' is set
474 to "foobar" (or hash of it), you need to send miau a message beginning
475 with `:foobar' to issue a remote command). miau can generate password-
476 hashes with `-c' -switch, if it is compiled with that feature.
477 This feature might not be compiled in.
479 `dccbounce = "state"' miau can bounce DCCs. Set to true to enable
481 bouncing. You probably don't need this.
482 This option might not be compiled in.
484 `dccbindhost = "host"' If miau has separate IPs for IRC-network and
486 clients, you should enter IP for clients here.
487 This option might not be compiled in.
489perl v5.8.8 2006-03-29 I2M3806(1)