3 To new Irssi users (not to new IRC users ..)
5 Copyright (c) 2000-2002 by Timo Sirainen
7 Index with some FAQ questions that are answered in the chapter:
8 1. For all the lazy people
9 2. Basic user interface usage
10 + Split windows work in weird way
11 3. Server and channel automation
12 + How do I automatically connect to servers at startup?
13 + How do I automatically join to channels at startup?
14 4. Setting up windows and automatically restoring them at startup
15 5. Status and msgs windows & message levels
16 + I want /WHOIS to print reply to current window
17 + I want all messages to go to one window, not create new
19 6. How support for multiple servers works in irssi
20 + I connected to some server that doesn't respond and now irssi
21 keeps trying to reconnect to it again and again, how can I
23 + I want to have own status and/or msgs window for each servers
24 7. /LASTLOG and jumping around in scrollback
25 + How can I save all texts in a window to file?
27 9. Changing keyboard bindings
28 + How do I make F1 key do something?
29 10. Proxies and IRC bouncers
32 1. For all the lazy people
34 These settings should give you pretty good defaults (the ones I use):
36 I don't like automatic query windows, I don't like status window, I do
37 like msgs window where all messages go:
38 /SET autocreate_own_query OFF
39 /SET autocreate_query_level DCCMSGS
40 /SET use_status_window OFF
41 /SET use_msgs_window ON
43 Disable automatic window closing when /PARTing channel or /UNQUERYing
45 /SET autoclose_windows OFF
46 /SET reuse_unused_windows ON
48 And example how to add servers:
50 (openprojects network, identify with nickserv and wait for 2 seconds
51 before joining channels)
52 /IRCNET ADD -autosendcmd "/^msg nickserv ident pass;wait -opn 2000" opn
54 Then add some servers to different networks (ircnet is already set up
55 for them), irc.kpnqwest.fi is used by default for IRCNet but if it
56 fails, irc.funet.fi is tried next:
57 /SERVER ADD -auto -ircnet ircnet irc.kpnqwest.fi 6667
58 /SERVER ADD -ircnet ircnet irc.funet.fi 6667
59 /SERVER ADD -auto -ircnet efnet efnet.cs.hut.fi 6667
61 Automatically join to channels after connected to server, send op
62 request to bot after joined to efnet/#irssi:
63 /CHANNEL ADD -auto #irssi ircnet
64 /CHANNEL ADD -auto -bots *!*bot@host.org -botcmd "/^msg $0 op pass"
67 If you want lines containing your nick to hilight:
70 2. Basic user interface usage
72 Windows can be scrolled up/down with PgUp and PgDown keys. If they
73 don't work for you, use Meta-p and Meta-n keys. For jumping to
74 beginning or end of the buffer, use /SB HOME and /SB END commands.
76 By default, irssi uses "hidden windows" for everything. Hidden window
77 is created every time you /JOIN a channel or /QUERY someone. There's
78 several ways you can change between these windows:
79 Meta-1, Meta-2, .. Meta-0 - Jump directly between windows 1-10
80 Meta-q .. Meta-o - Jump directly between windows 11-19
81 /WINDOW <number> - Jump to any window with specified number
82 Ctrl-P, Ctrl-N - Jump to previous / next window
84 Clearly the easiest way is to use Meta-number keys. And what is the
85 Meta key? For some terminals, it's the same as ALT. If you have
86 Windows keyboard, it's probably the left Windows key. If they don't
87 work directly, you'll need to set a few X resources (NOTE: these work
88 with both xterm and rxvt):
89 XTerm*eightBitInput: false
90 XTerm*metaSendsEscape: true
92 With rxvt, you can also specify which key acts as Meta key. So if you
93 want to use ALT instead of Windows key for it, use:
96 You could do this by changing the X key mappings:
97 xmodmap -e "keysym Alt_L = Meta_L Alt_L"
99 And how exactly do you set these X resources? For Debian, there's
100 /etc/X11/Xresources/xterm file where you can put them and it's read
101 automatically when X starts. ~/.Xresources and ~/.Xdefaults files
102 might also work. If you can't get anything else to work, just
103 copy&paste those lines to ~/.Xresources and directly call "xrdb -merge
104 ~/.Xresources" in some xterm. The resources affect only the new xterms
105 you start, not existing ones.
107 Many windows SSH clients also don't allow usage of ALT. One excellent
108 client that does allow is putty, you can download it from
109 http://www.chiark.greenend.org.uk/~sgtatham/putty/.
111 Irssi also supports split windows, they've had some problems in past
112 but I think they should work pretty well now :) Here's some commands
114 /WINDOW NEW - Create new split window
115 /WINDOW NEW HIDE - Create new hidden window
116 /WINDOW CLOSE - Close split or hidden window
118 /WINDOW HIDE [<number>|<name>] - Make the split window hidden window
119 /WINDOW SHOW <number>|<name> - Make the hidden window a split window
121 /WINDOW SHRINK [<lines>] - Shrink the split window
122 /WINDOW GROW [<lines>] - Grow the split window
123 /WINDOW BALANCE - Balance the sizes of all split windows
125 By default, irssi uses "sticky windowing" for split windows. This
126 means that windows created inside one split window cannot be moved to
127 another split window without some effort. For example you could have
128 following window layout:
129 Split window 1: win#1 - Status window, win#2 - Messages window
130 Split window 2: win#3 - ircnet/#channel1, win#4 - ircnet/#channel2
131 Split window 3: win#5 - efnet/#channel1, win#6 - efnet/#channel2
133 When you are in win#1 and press ALT-6, irssi jumps to split window #3
134 and moves the efnet/#channel2 the active window.
136 With non-sticky windowing the windows don't have any relationship with
137 split windows, pressing ALT-6 in win#1 moves win#6 to split window 1
138 and sets it active, except if win#6 was already visible in some other
139 split window irssi just changes to that split window. This it the way
140 windows work with ircii, if you prefer it you can set it with
141 /SET autostick_split_windows OFF
143 Each window can have multiple channels, queries and other "window
144 items" inside them. If you don't like windows at all, you disable
145 automatic creating of them with
146 /SET autocreate_windows OFF
148 If you want to group only some channels or queries in one window, use
149 /JOIN -window #channel
152 3. Server and channel automation
154 Irssi's multiple IRC network support is IMHO very good - at least
155 compared to other clients :) Even if you're only in one IRC network
156 you should group all your servers to be in the same IRC network as
157 this helps with reconnecting if your primary server breaks and is
158 probably useful in some other ways too :) For information how to
159 actually use irssi correctly with multiple servers see the chapter 6.
161 First you need to have your IRC network set, use /IRCNET command to
162 see if it's already there. If it isn't, use /IRCNET ADD yourircnet. To
163 make Irssi work properly with different IRC networks, you might need
164 to give some special settings to /IRCNET ADD, see manual.txt for more
165 information about them. Irssi defaults to IRCNet's behaviour.
167 After that you need to add your servers. For example:
168 /SERVER ADD -auto -ircnet ircnet irc.kpnqwest.fi 6667
169 /SERVER ADD -auto -ircnet worknet irc.mycompany.com 6667 password
171 The -auto option specifies that this server is automatically connected
172 at startup. You don't need to make more than one server with -auto
173 option to one IRC network, other servers are automatically connected
174 in same network if the -auto server fails.
176 And finally channels:
177 /CHANNEL ADD -auto -bots *!*bot@host.org -botcmd "/^msg $0 op pass"
179 /CHANNEL ADD -auto #secret ircnet password
181 -bots and -botcmd should be the only ones needing a bit of explaining.
182 They're used to send commands automatically to bot when channel is
183 joined, usually to get ops automatically. You can specify multiple bot
184 masks with -bots option separated with spaces (and remember to quote
185 the string then). The $0 in -botcmd specifies the first found bot in
186 the list. If you don't need the bot masks (ie. the bot is always with
187 the same nick, like chanserv) you can give only the -botcmd option and
188 the command is always sent.
190 4. Setting up windows and automatically restoring them at startup
192 First connect to all the servers, join the channels and create the
193 queries you want. If you want to move the windows or channels around
195 /WINDOW MOVE LEFT/RIGHT/number - move window elsewhere
196 /WINDOW ITEM MOVE <number>|<name> - move channel/query to another window
198 When everything looks the way you like, use /LAYOUT SAVE command (and
199 /SAVE, if you don't have autosaving enabled) and when you start irssi
200 next time, irssi remembers the positions of the channels, queries and
201 everything. This "remembering" doesn't mean that simply using /LAYOUT
202 SAVE would automatically make irssi reconnect to all servers and join
203 all channels, you'll need the /SERVER ADD -auto and /CHANNEL ADD -auto
206 If you want to change the layout, you just rearrange the layout like
207 you want it and use /LAYOUT SAVE again. If you want to remove the
208 layout for some reason, use /LAYOUT RESET.
210 5. Status and msgs windows & message levels
212 By default, all the "extra messages" go to status window. This means
213 pretty much all messages that don't clearly belong to some channel or
214 query. Some people like it, some don't. If you want to remove it, use
215 /SET use_status_window OFF
217 This doesn't have any effect until you restart irssi. If you want to
218 remove it immediately, just /WINDOW CLOSE it.
220 Another common window is "messages window", where all private messages
221 go. By default it's disabled and query windows are created instead. To
222 make all private messages go to msgs window, say:
223 /SET use_msgs_window ON
224 /SET autocreate_query_level DCCMSGS (or if you don't want queries to
225 dcc chats either, say NONE)
227 use_msgs_window either doesn't have any effect until restarting irssi.
228 To create it immediately say:
229 /WINDOW NEW HIDE - create the window
230 /WINDOW NAME (msgs) - name it to "(msgs)"
231 /WINDOW LEVEL MSGS - make all private messages go to this window
232 /WINDOW MOVE 1 - move it to first window
234 Note that neither use_msgs_window nor use_status_window have any
235 effect at all if /LAYOUT SAVE has been used.
237 This brings us to message levels.. What are they? All messages that
238 irssi prints have one or more "message levels". Most common are PUBLIC
239 for public messages in channels, MSGS for private messages and CRAP
240 for all sorts of messages with no real classification. You can get a
241 whole list of levels with
244 Status window has message level "ALL -MSGS", meaning that all
245 messages, except private messages, without more specific place go to
246 status window. The -MSGS is there so it doesn't conflict with messages
249 6. How support for multiple servers works in irssi
251 ircii and several other clients support multiple servers by placing
252 the connection into some window. IRSSI DOES NOT. There is no required
253 relationship between window and server. You can connect to 10 servers
254 and manage them all in just one window, or join channel in each one of
255 them to one sigle window if you really want to. That being said,
256 here's how you do connect to new server without closing the old
258 /CONNECT irc.server.org
260 Instead of the /SERVER which disconnects the existing connection. To
261 see list of all active connections, use /SERVER without any
262 parameters. You should see a list of something like:
263 -!- IRCNet: irc.song.fi:6667 (IRCNet)
264 -!- OPN: tolkien.openprojects.net:6667 (OPN)
265 -!- RECON-1: 192.168.0.1:6667 () (02:59 left before reconnecting)
267 Here you see that we're connected to IRCNet and OPN networks. The the
268 IRCNet at the beginning is called the "server tag" while the (IRCnet)
269 at the end shows the IRC network. Server tag specifies unique tag to
270 refer to the server, usually it's the same as the IRC network. When
271 the IRC network isn't known it's some part of the server name. When
272 there's multiple connections to same IRC network or server, irssi adds
273 a number after the tag so there could be ircnet, ircnet2, ircnet3 etc.
275 Server tags beginning with RECON- mean server reconnections. Above we
276 see that connection to server at 192.168.0.1 wasn't successful and
277 irssi will try to connect it again in 3 minutes.
279 To disconnect one of the servers, or to stop irssi from reconnecting,
281 /DISCONNECT ircnet - disconnect server with tag "ircnet"
282 /DISCONNECT recon-1 - stop trying to reconnect to RECON-1 server
283 /RMRECONNS - stop all server reconnections
285 /RECONNECT recon-1 - immediately try reconnecting back to RECON-1
286 /RECONNECT ALL - immediately try reconnecting back to all
287 servers in reconnection queue
289 Now that you're connected to all your servers, you'll have to know how
290 to specify which one of them you want to use. One way is to have an
291 empty window, like status or msgs window. In it, you can specify which
292 server to set active with
293 /WINDOW SERVER tag - set server "tag" active
294 Ctrl-X - set the next server in list active
296 When the server is active, you can use it normally. When there's
297 multiple connected servers, irssi adds [servertag] prefix to all
298 messages in non-channel/query messages so you'll know where it came
301 Several commands also accept -servertag option to specify which server
303 /MSG -tag nick message
307 /MSG tab completion also automatically adds the -tag option when nick
308 isn't in active server.
310 Window's server can be made sticky. When sticky, it will never
311 automatically change to anything else, and if server gets
312 disconnected, the window won't have any active server. When the server
313 gets connected again, it is automatically set active in the window. To
314 set the window's server sticky use
315 /WINDOW SERVER -sticky tag
317 This is useful if you wish to have multiple status or msgs windows,
318 one for each server. Here's how to do them (repeat for each server)
320 /WINDOW NAME (status)
321 /WINDOW LEVEL ALL -MSGS
322 /WINDOW SERVER -sticky ircnet
327 /WINDOW SERVER -sticky ircnet
329 7. /LASTLOG and jumping around in scrollback
331 /LASTLOG command can be used for searching texts in scrollback buffer.
333 /LASTLOG word - print all lines with "word" in them
334 /LASTLOG word 10 - print last 10 occurances of "word"
335 /LASTLOG -topics - print all topic changes
337 If there's more than 1000 lines to be printed, irssi thinks that you
338 probably made some mistake and won't print them without -force option.
339 If you want to save the full lastlog to file, use
340 /LASTLOG -file ~/irc.log
342 With -file option you don't need -force even if there's more than 1000
343 lines. /LASTLOG has a lot of other options too, see /HELP lastlog for
346 Once you've found the lines you were interested in, you might want to
347 check the discussion around them. Irssi has /SCROLLBACK (or alias /SB)
348 command for jumping around in scrollback buffer. Since /LASTLOG prints
349 the timestamp when the message was originally printed, you can use /SB
350 GOTO hh:mm to jump directly there. To get back to the bottom of
351 scrollback, use /SB END command.
355 Irssi can automatically log important messages when you're set away
356 (/AWAY reason). When you set yourself unaway (/AWAY), the new messages
357 in away log are printed to screen. You can configure it with:
358 /SET awaylog_level MSGS HILIGHT - Specifies what messages to log
359 /SET awaylog_file ~/.irssi/away.log - Specifies the file to use
361 Easiest way to start logging with Irssi is to use autologging. With it
362 Irssi logs all channels and private messages to specified directory.
363 You can turn it on with
366 By default it logs pretty much everything execept CTCPS or CRAP
367 (/WHOIS requests, etc). You can specify the logging level yourself
369 /SET autolog_level ALL -CRAP -CLIENTCRAP -CTCPS (this is the default)
371 By default irssi logs to ~/irclogs/<servertag>/<target>.log. You can
373 /SET autolog_path ~/irclogs/$tag/$0.log (this is the default)
375 The path is automatically created if it doesn't exist. $0 specifies
376 the target (channel/nick). You can make irssi automatically rotate the
377 logs by adding date/time formats to the file name. The formats are in
378 "man strftime" format. For example
379 /SET autolog_path ~/irclogs/%Y/$tag/$0.%m-%d.log
381 For logging only some specific channels or nicks, see /HELP log
383 9. Changing keyboard bindings
385 You can change any keyboard binding that terminal lets irssi know
386 about. It doesn't let irssi know everything, so for example
387 shift-backspace can't be bound unless you modify xterm resources
390 /HELP bind tells pretty much everything there is to know about
391 keyboard bindings. However, there's the problem of how to bind some
392 non-standard keys. They might differ a bit with each terminal, so
393 you'll need to find out what exactly the keypress produces. Easiest
394 way to check that would be to see what it prints in "cat". Here's an
395 example for pressing F1 key:
399 So in irssi you would use /BIND ^[OP /ECHO F1 pressed. If you use
400 multiple terminals which have different bindings for the key, it would
401 be better to use eg.:
404 /BIND F1 /ECHO F1 pressed.
406 10. Proxies and IRC bouncers
408 Irssi supports connecting to IRC servers via a proxy. All proxies have
409 these settings in common:
411 /SET proxy_address <Proxy host address>
412 /SET proxy_port <Proxy port>
416 Use these settings with HTTP proxies:
417 /SET -clear proxy_password
418 /EVAL SET proxy_string CONNECT %s:%d\n\n
421 /SET proxy_password your_pass
422 /SET -clear proxy_string
423 /SET proxy_string conn %s %d
427 dircproxy separates the server connections by passwords. So, if you
428 for example have ircnet connection with password ircpass and
429 openprojects connection with opnpass, you would do something like
431 /SET -clear proxy_password
432 /SET -clear proxy_string
434 /SERVER ADD -auto -ircnet ircnet fake.ircnet 6667 ircpass
435 /SERVER ADD -auto -ircnet opn fake.opn 6667 opnpass
437 The server name and port you give isn't used anywhere, so you can put
438 anything you want in there.
442 Irssi contains it's own proxy which you can build giving --with-proxy
443 option to configure. You'll still need to run irssi in a screen to use
446 Irssi proxy is a bit different than most proxies, normally proxies
447 create a new connection to IRC server when you connect to it, but with
448 irssi proxy all the clients use the same IRC server connection (a bit
449 like how screen -x works).
451 Irssi proxy supports sharing multiple server connections in different
452 ports, like you can share ircnet in port 2777 and efnet in port 2778.
456 /SET irssiproxy_password <password>
457 /SET irssiproxy_ports <ircnet>=<port> ... (eg. ircnet=2777 efnet=2778)
459 NOTE: you MUST add all the servers you are using to server and ircnet
460 lists with /SERVER ADD and /IRCNET ADD. ..Except if you really don't
461 want to for some reason, and you only use one server connection, you
463 /SET irssiproxy_ports *=2777
465 Usage in client side:
467 Just connect to the irssi proxy like it is a normal server with
468 password specified in /SET irssiproxy_password. For example:
469 /SERVER ADD -ircnet ircnet my.irssi-proxy.org 2777 secret
470 /SERVER ADD -ircnet efnet my.irssi-proxy.org 2778 secret
472 Irssi proxy works fine with other IRC clients as well.
475 Irssi can be compiled with socks support (--with-socks option to
476 configure), but I don't really know how it works, if at all. /SET
477 proxy settings don't have anything to do with socks however.
481 IRC bouncers usually work like IRC servers, and want a password. You
483 /SET proxy_password <password>
485 Irssi's defaults for connect strings are
486 /SET proxy_string CONNECT %s %d
487 /SET proxy_string_after
489 The proxy_string is sent before NICK/USER commands, the
490 proxy_string_after is sent after them. %s and %d can be used with both
495 You probably don't like Irssi's default settings. I don't like them.
496 But I'm still convinced that they're pretty good defaults. Here's some
497 of them you might want to change (the default value is shown):
501 /SET autocreate_own_query ON
502 Should new query window be created when you send message to
505 /SET autocreate_query_level MSGS
506 New query window should be created when receiving messages with
507 this level. MSGS, DCCMSGS and NOTICES levels work currently.
508 You can disable this with /SET -clear autocrate_query_level.
510 /SET autoclose_query 0
511 Query windows can be automatically closed after certain time of
512 inactivity. Queries with unread messages aren't closed and
513 active window is neither never closed. The value is given in
518 /SET use_msgs_window OFF
519 Create messages window at startup. All private messages go to
520 this window. This only makes sense if you've disabled automatic
521 query windows. Message window can also be created manually with
522 /WINDOW LEVEL MSGS, /WINDOW NAME (msgs).
524 /SET use_status_window ON
525 Create status window at startup. All messages that don't really
526 have better place go here, like all /WHOIS replies etc. Status
527 window can also be created manually with /WINDOW LEVEL ALL
528 -MSGS, /WINDOW NAME (status).
530 /SET autocreate_windows ON
531 Should we create new windows for new window items or just place
532 everything in one window
534 /SET autoclose_windows ON
535 Should window be automatically closed when the last item in
536 them is removed (ie. /PART, /UNQUERY).
538 /SET reuse_unused_windows OFF
539 When finding where to place new window item (channel, query)
540 Irssi first tries to use already existing empty windows. If
541 this is set ON, new window will always be created for all
542 window items. This setting is ignored if autoclose_windows is
545 /SET window_auto_change OFF
546 Should Irssi automatically change to automatically created
547 windows - usually queries when someone sends you a message. To
548 prevent accidentally sending text meant to some other
549 channel/nick, Irssi clears the input buffer when changing the
550 window. The text is still in scrollback buffer, you can get it
551 back with pressing arrow up key.
553 /SET print_active_channel OFF
554 When you keep more than one channel in same window, Irssi
555 prints the messages coming to active channel as "<nick> text"
556 and other channels as "<nick:channel> text". If this setting is
557 set ON, the messages to active channels are also printed in the
560 /SET window_history OFF
561 Should command history be kept separate for each window.
572 Your username, if you have ident enabled this doesn't affect
581 Should we hide server's MOTD (Message Of The Day).
583 /SET server_reconnect_time 300
584 Seconds to wait before connecting to same server again. Don't
585 set this too low since it usually doesn't help at all - if the
586 host is down, the few extra minutes of waiting won't hurt much.
588 /SET lag_max_before_disconnect 300
589 Maximum server lag in seconds before disconnecting and trying
590 to reconnect. This happens mostly only when network breaks
591 between you and IRC server.
596 Show timestamps before each message.
598 /SET hide_text_style OFF
599 Hide all bolds, underlines, MIRC colors, etc.
601 /SET show_nickmode ON
602 Show the nick's mode before nick in channels, ie. ops have
603 <@nick>, voices <+nick> and others < nick>
605 /SET show_nickmode_empty ON
606 If the nick doesn't have a mode, use one space. ie. ON:
609 /SET show_quit_once OFF
610 Show quit message only once in some of the channel windows the
611 nick was in instead of in all windows.
613 /SET lag_min_show 100
614 Show the server lag in status bar if it's bigger than this, the
615 unit is 1/100 of seconds (ie. the default value of 100 = 1
619 When lines are longer than screen width they have to be split
620 to multiple lines. This specifies how much space to put at the
621 beginning of the line before the text begins. This can be
622 overridden in text formats with %| format.
624 /SET activity_hide_targets
625 If you don't want to see window activity in some certain
626 channels or queries, list them here. For example
627 "#boringchannel =bot1 =bot2". If any highlighted text or
628 message for you appears in that window, this setting is ignored
629 and the activity is shown.
633 /SET completion_auto OFF
634 Automatically complete the nick if line begins with start
635 of nick and the completion character. Learn to use the
636 tab-completion instead, it's a lot better ;)
638 /SET completion_char :
639 Completion character to use.