Irssi 0.8 documentation - http://www.irssi.org/ Copyright(c) 2000 Timo Sirainen Index 0. Generic babbling 1. Command line parameters 2. Message levels 3. Flood protection 4. Configuration 5. Servers 6. Channels 7. IRC commands and features 8. Notify list 9. Text highlighting 10. Ignoring 11. Logging ( not written yet: ) 12. Aliases 13. Themes 14. Last log (currently text version only) 15. Nick and word completion 16. Translation tables 17. Windowing system (text version) 18. Keyboard (text version) 19. Perl scripting 0. Generic babbling 0.1 History Hello. I'm Timo Sirainen aka. cras, and I'm an IRC addict. :) I'm actually quite new in IRC, I got my first internet connection sometimes around fall 1997 and I started actively IRCing around christmas. I used EPIC and BitchX mostly at the start, but soon found some nice KDE IRC client which name I can't remember anymore. It's author however stopped developing it after I had been using it a few months. And since it had bugs and all, I wanted another nice GUI IRC client. I didn't find any. Since I've always been a coder and do-it-yourself guy (my own offline reader and BBS software in the BBS ages), I started my own IRC client at spring 1998. I called it yagIRC standing for "Yet another GTK IRC client". GTK was in around version 1.0 back then, and it had a lot of features/bugs which I found all the time as I tried to do some "different" things than other people. These sometimes prevented me of doing something some feature I wanted. So, in summer 1998 I went to army and I passed development of yagIRC to two guys, they did a few new features and released a version or two, but finally (in summer 1999?) they put a message to web page which told that they finally had stopped developing it entirely, also saying that my code was a total mess :) (yes, it was a mess) I got out of the army 1.1.1999. I promised to myself that I wouldn't do another IRC client, but after trying to use BitchX a while, I started dreaming about an IRC client which would have an excellent look and feel. After trying various things, I only came up with the GNOME panel applet which people still tell me that it's a great feature. I was more like thinking some pretty little icons in some corner telling me about new messages and other stuff.. I thought that I would keep Irssi a small project, just doing a few little features that *I* wanted, nothing for others. But after few versions and few interested people, I started coding it more and more generic.. Finally, after releasing version 0.6.0 (february, 1999) I realized that things were getting into a big mess again. I started a rewrite, I organized the code into irc-base, irc-extra, user interface and GUI directories, created the signalling system for letting them communicate themselves easily and released 0.7.0. This was the base for the rest of the 0.7.x releases, and it did work pretty well. The signalling system was excellent, for example creating text mode version was really easy and you didn't need tens of (empty) gui_xxx() functions like in the yagIRC days. Maintaining the text and GTK versions separately was really easy too. About a year later after releasing Irssi 0.7.0, I started having dreams about an IRC client that would be extremely modular, like you could upgrade the client to newer version ON THE FLY without needing to even disconnect from the servers. I started a project codenamed i2k, I took the code from Irssi, split it into more directories and changed quite a lot of the code to work a bit differently. I developed i2k quite a long, until I finally gave up with it since it could do only some basic things, and Irssi 0.7 really needed maintaining. After a while I got an idea, maybe I could merge the code from the i2k to Irssi more easily than rewriting the whole client. This was more easier than I thought. It's now been two months since I started it, and Irssi 0.8 is looking absolutely excellent. 0.2 Irssi 0.8 Irssi 0.8 is my fourth try to create the perfect IRC client. This time I'm concentrating to the code. I try to avoid kludges, I try to make as simple code as I can, and I try to provide enough easy to use functions so that extending Irssi is as simple as possible. I also try to keep the "bloat" features in scripts or modules instead of build-in. I think I'm succeeded with these goals pretty well, there's some small problems but everything in the big picture looks great. 0.3 Future What about Irssi 1.0, what will it look like? I was thinking about the Linux kernel versioning and keeping Irssi 0.8 a stable version all the time while developing new features only to Irssi 0.9. After 0.9 is finished, it will be called 0.10 or 1.0 depending if I think it's ready to be called 1.0. 1.0's goal is that it has all the possible features anyone will ever need. If not build-in, then in scripts or loadable modules. Not very small goal :) 0.4 This documentation Strange, I just created the index list and started writing this. I've never been too good at documentation and I usually don't like writing it, but after coding so much recently and seeing that the NEWS file was getting *SO* large, I thought that I had to put all these features down somewhere so people (and me!) would find them. 1. Command line parameters --connect -c Connect to server at startup --port -p - specify port --noconnect -! Don't autoconnect to any servers at startup --nick -n Specify what nick to use --hostname -h Specify what host name to use 2. Message levels Message levels (or in short, levels) are used almost everywhere. They describe what kind of messages we're dealing with. Here's a list of them all: CRAP - Can be almost anything MSGS - Private messages PUBLIC - Public messages in channel NOTICES - Notices SNOTES - Server notices CTCPS - CTCP messages ACTIONS - Actions (/me) - usually ORed with PUBLIC or MSGS JOINS - Someone joins a channel PARTS - Someone parts a channel QUITS - Someone quits IRC KICKS - Someone gets kicked from channel MODES - Channel mode is changed TOPICS - Channel topic is changed WALLOPS - Wallop is received INVITES - Invite is received NICKS - Someone changes nick DCC - DCC related messages DCCMSGS - DCC chat messages CLIENTNOTICES - Irssi's notices CLIENTERRORS - Irssi's error messages CLIENTCRAP - Some other messages from Irssi And a few special ones that could be included with the levels above: HILIGHT - Text is highlighted NOHILIGHT - Don't check highlighting for this message NO_ACT - Don't trigger channel activity when printing this message NEVER - Never ignore or log this message 3. Flood protection 3.1 Command flood protection Most (all?) IRC servers' flood protection works like this (from RFC 1459): -------- * check to see if client's `message timer' is less than current time (set to be equal if it is); * read any data present from the client; * while the timer is less than ten seconds ahead of the current time, parse any present messages and penalize the client by 2 seconds for each message; which in essence means that the client may send 1 message every 2 seconds without being adversely affected. -------- Irssi's flood protection works the same way, except it penalizes 2.2 seconds by default for each message (helps with some servers). You can change it with /SET cmd_queue_speed . You can also change the number of commands before flood protection activates (ie. the burst count) with /SET cmd_max_at_once . IRC servers also have an input buffer where the client's commands are saved before processed. It's size is server specific (can be as low as 1k!) If it gets full, the server kicks you out (the "Excess flood" quit message). Irssi's flood protecion protects this pretty well with small commands, but if you send many big commands (like >400 char long messages) fast, you could get easily kicked out. Normally this isn't problem, but if you have scripts sending long messages, you should remember this. I'm not sure how much you should wait between the long messages, but 2 seconds isn't enough. This protection is used with all commands sent to server, so you don't need to worry about it with your scripts. 3.2 CTCP flood protection Other people can pretty easily flood you with CTCP requests, and even if you wouldn't get kicked out from the server, they could easily grow your command queue. So, Irssi's CTCP flood protection works like this: First it checks how big the CTCP reply queue is, if it's longer than `max_ctcp_queue', the CTCP is ignored. You can change it with /SET max_ctcp_queue (default is 5). After this the CTCP reply is placed to server's "idle queue", so the reply is sent "when there's extra time", this means that if you are busy sending other commands, it might take a while before the reply is sent. 3.3 Detecting floods Irssi is all the time automatically checking different flooding, when flood is noticed, it sends "flood" signal. This can be easily used for example to create a script for kicking channel flooders. Autoignore uses this also, see section 10.2. Flood is detected when more than `flood_max_msgs' same kind of messages arrives in `flood_timecheck' seconds to same target (channel or private msg) so it isn't flooding if same user sends a message to 10 different channels you are on, but it is flooding if 10 messages are sent to same channel by the same user. Currently only messages, notices and ctcps are checked for flooding. /SET flood_max_msgs = , default is 4 /SET flood_timecheck = , default is 5 seconds If either of these is 0, the flood checking is disabled. 4. Configuration 4.1 Configuration files The configuration is saved to ~/.irssi/config file. You can edit it with text editor if you want, you can also add comments to it and they stay there even if /SAVE is used. Comments are the lines starting with # character. Any errors in config file are displayed at startup. Irssi uses it's own config library for handling the config file. The format is pretty much the same as in libPropList and should be easily understandable. You can reload the config file on the fly with /RELOAD command, you can also read a different config file with /RELOAD . If you change any settings, they aren't saved to file until you use /SAVE. You can save the config file to different place with /SAVE . 4.2 Settings You can view or change the settings with /SET command. /SET without any arguments displays all the settings. /SET displays settings which key (partly) matches /SET sets to Boolean settings accepts only values ON, OFF and TOGGLE. You can also use /TOGGLE command to change them, so /TOGGLE behaves like /SET TOGGLE. /TOGGLE also accepts arguments ON and OFF when /TOGGLE behaves exactly like /SET. Remember that changes are not saved until you use /SAVE! 5. Servers 5.1 Generic Irssi is multi-server friendly. You can be connected to multiple different servers, or the same server multiple times. Most of the settings that let you specify the channel, let you also specify IRC network. Servers are referenced by a "server tag". If the server is known to belong to some IRC network, the tag is the IRC network's name, like "IRCnet". If the IRC network is unknown, the tag is created from the server's name, like irc.funet.fi -> funet. If the tag already exists, a number is added to the end of it and raised until unused tag is found. Quit messages have a small problem if there's already a few commands in server's input command queue. If the server's socket is disconnected immediately after QUIT message is sent, it is possible that the server didn't yet process the quit command and your quit message will be "broken pipe" or something similiar. The right thing to do is to let the server disconnect you, but what if the connection to server is broken and the server never disconnects you? I solved the problem by waiting a few seconds to see if the server disconnects us. If it didn't, force the disconnect. This explains the (a bit annoying) "waiting for servers to close connections" message when quiting Irssi. Most IRC clients just ignore this whole problem, but I hate it if my quit message isn't displayed right. 5.2 IRC networks Different IRC networks behave a bit differently, and to be as efficient as possible, Irssi needs to know a few things about them or the safe defaults will be used. The default configuration file contains the settings for the biggest IRC networks. /NETWORK ADD [-kicks ] [-msgs ] [-modes ] [-whois ] [-cmdspeed ] [-cmdmax ] [-nick ] [-user ] [-realname ] [-host ] [-autosendcmd ] -kicks: Maximum number of nicks in one /KICK command -msgs: Maximum number of nicks in one /MSG command -modes: Maximum number of mode changes in one /MODE command -whois: Maximum number of nicks in one /WHOIS command -cmdspeed: Same as /SET cmd_queue_speed, see section 3.1 -cmdmax: Same as /SET cmd_max_at_once, see section 3.1 -nick, -user, -realname: Specify what nick/user/name to use -host: Specify what host name to use, if you have multiple -autosendcmd: Command to send after connecting to a server With -autosendcmd argument you can automatically run any commands after connecting to the network. This is useful for automatically identifying yourself to NickServ, for example /NETWORK ADD -autosendcmd "/msg NickServ identify secret" freenode /NETWORK REMOVE 5.3 Manually connecting and disconnecting To connect to a new server, use: /CONNECT [-network ] [-host ]
| [ [ []]] If there's no password, set it to -. You can directly connect to IRC server in specified address, or you can connect to some IRC network and Irssi will pick the server for you. You don't need to specify the IRC network, password, nick, etc. if you setup the server using /SERVER ADD (see next section). If the settings can't be found there either, Irssi will use the defaults: /SET default_nick = , defaults to user_name /SET alternate_nick = , defaults to _ /SET user_name = , defaults to your login name /SET real_name = , taken from /etc/passwd by default /SET hostname = , what host name to use when connecting /SET skip_motd ON|OFF|TOGGLE - Don't show server's MOTD NOTE: /CONNECT is also a command for IRC operators to connect IRC servers to other IRC servers. If you want to use it, use /SCONNECT instead. You can disconnect from the server with: /DISCONNECT *| [message] If message isn't given, Irssi will use the default quit message. You can set it with /SET quit_message , default is "leaving". /SERVER disconnects the server in active window and connects to new one. It will take the same arguments as /CONNECT. If you prefix the address with + character, Irssi won't disconnect the active server, and it will create a new window where the server is connected (ie. /window new hide;/connect address) /SERVER without any arguments displays list of connected servers. 5.4 Server settings /SERVER ADD [-auto | -noauto] [-network ] [-host ] [-cmdspeed ] [-cmdmax ] [-port ]
[ []] -auto: Automatically connect to server at startup -noauto: Don't connect to server at startup (default) -network: Specify what IRC network this server belongs to -ircnet: Same as -network. Deprecated. Do not use. -host: Specify what host name to use, if you have multiple -cmdspeed: Same as /SET cmd_queue_speed, see section 3.1 -cmdmax: Same as /SET cmd_max_at_once, see section 3.1 -port: This is pretty much like the port argument later, except this can be used to modify existing server's port. /SERVER REMOVE
[] /SERVER LIST Servers are identified by their name and port. You can have multiple entries for the same server name but in different ports. This is useful for IRC proxies, in one port you could have IRCNet proxy, another port would have EFNet, etc. If you wish to change existing server's port to something else, use -port command. For example if you had irc.server.org in port 6667 and you wanted to change it to port 6668, use command: /SERVER ADD -port 6668 irc.server.org 6667 If you want to remove some settings from existing server, for example hostname, just give -host "" parameters to it. After connected to server, Irssi can automatically change your user mode. You can set it with /SET usermode , default is +i. /SET resolve_prefer_ipv6 - If ON, prefer IPv6 for hosts that have both v4 and v6 addresses. 5.5 Automatic reconnecting If you get disconnected from server, Irssi will try to reconnect back to some of the servers in the same IRC network. To prevent flooding the server that doesn't let you in (and avoiding K-lines), Irssi won't try to reconnect to the same server more often than once in `server_reconnect_time' seconds. You can change it with /SET server_reconnect_time , default is 5 minutes. After reconnected to server, Irssi will re-set your user mode, away message and will join you back to the same channels where you were before the connection was lost. You can see list of the reconnections with /SERVER. The servers that have tag as RECON-n are the reconnections. You can remove them with /DISCONNECT , and you can reconnect to them immediately with /RECONNECT . /RECONNECT without any arguments will disconnect from the active server and reconnect back immediately. 5.6 Server redirections Getting replies matched to IRC commands can be quite complicated. Server redirection allow this in a relatively easy way. They are used internally and are available to scripts; see Server redirections in perl.txt for details. 5.7 Server idle command queue There's some situations when you want to ask something from the server which isn't really important. For example when connected to server and you didn't get your nick, Irssi asks with /WHOIS who has your nick and displays it. But if you already have a lot of commands in buffer, like you just autojoined to many channels, you'd rather first let the JOIN commands to be sent to server This is where server idle queue gets into picture. Commands in idle queue are sent to server when there's nothing else in the normal command queue. Idle queue works with server redirections, so you can ask something from server when it has time and your function is called when the reply is received. 5.8 Net splits Irssi keeps track of people who were lost in net splits. You can get a list of them with /NETSPLIT command. Another use for this is with bots. Channel master can op anyone in the channel and the bot happily accepts it. But if the opped user is lost behind a net split and in netjoin the server gives ops for the user, the bot should decide if the user (who isn't in bot's user database) is a malicious attacker who should be deopped, or if he/she/it is just some user that already had ops before the net split. /SET hide_netsplit_quits - If ON, hide all netsplit quit messages and display only "Netsplit host1 host2: nicks". /SET netsplit_max_nicks - If non-zero, limit the number of nicks printed in netsplit message and add "(+ more, use /NETSPLIT to show all of them)" text. 5.9 Lag checking Irssi will constantly check how big the lag to the server is. It is done by sending PING commands. Lag checking is disabled for broken servers that do not support PING. If the lag is too big, Irssi will reconnect to different IRC server. This is sometimes useful if the connection has been stuck for 30 minutes but it still hasn't been closed. /SET lag_check_time