3 <h3>To new Irssi users (not to new IRC users ..)</h3>
5 <p>Copyright (c) 2000-2001 by Timo Sirainen</p>
8 <p>Index with some FAQ questions that are answered in the chapter:</p>
11 <li><a href="#c1">For all the lazy people</a></li>
12 <li><a href="#c2">Basic user interface usage</a></li>
13 <li><a href="#c3">Server and channel automation</a>
15 <li>how do I automatically connect to servers at startup?</li>
16 <li>how do I automatically join to channels at startup?</li>
18 <li><a href="#c4">Setting up windows and automatically restoring them
20 <li><a href="#c5">Status and msgs windows & message levels</a>
22 <li>I want /WHOIS to print reply to current window</li>
23 <li>I want all messages to go to one window, not create new windows</li>
25 <li><a href="#c6">How support for multiple servers works in irssi</a>
27 <li>I connected to some server that doesn't respond and now irssi
28 keeps trying to reconnect to it again and again, how can I stop
30 <li>I want to have own status and/or msgs window for each servers</li>
32 <li><a href="#c7">/LASTLOG and jumping around in scrollback</a>
34 <li>How can I save all texts in a window to file?</li>
36 <li><a href="#c8">Logging</a></li>
37 <li><a href="#c9">Irssi's settings</a></li>
40 <h3><a id="c1">1. For all the lazy people</a></h3>
42 <p>These settings should give you pretty good defaults (the ones I use):</p>
44 <p>I don't like automatic query windows, I don't like status window, I do
45 like msgs window where all messages go:</p>
48 /SET autocreate_own_query OFF
49 /SET autocreate_query_level DCCMSGS
50 /SET use_status_window OFF
51 /SET use_msgs_window ON
54 <p>Disable automatic window closing when /PARTing channel or /UNQUERYing
58 /SET autoclose_windows OFF
59 /SET reuse_unused_windows ON
62 <p>And example how to add servers:</p>
64 <p>(openprojects network, identify with nickserv and wait for 2 seconds before
68 /IRCNET ADD -autosendcmd "/^msg nickserv ident pass;wait -opn 2000" opn
71 <p>Then add some servers to different networks (ircnet is already set up
72 for them), irc.kpnqwest.fi is used by default for IRCNet but if it fails,
73 irc.funet.fi is tried next:</p>
76 /SERVER ADD -auto -ircnet ircnet irc.kpnqwest.fi 6667
77 /SERVER ADD -ircnet ircnet irc.funet.fi 6667
78 /SERVER ADD -auto -ircnet efnet efnet.cs.hut.fi 6667
81 <p>Automatically join to channels after connected to server, send op request
82 to bot after joined to efnet/#irssi:</p>
85 /CHANNEL ADD -auto #irssi ircnet
86 /CHANNEL ADD -auto -bots *!*@bot@host.org -botcmd "/^msg $0 op pass"
90 <h3><a id="c2">2. Basic user interface usage</a></h3>
92 <p>By default, irssi uses "hidden windows" for everything. Hidden
93 window is created every time you /JOIN a channel or /QUERY someone.
94 There's several ways you can change between these windows:</p>
97 Meta-1, Meta-2, .. Meta-0 - Jump directly between windows 1-10
98 Meta-q .. Meta-p - Jump directly between windows 11-20
99 /WINDOW <number> - Jump to any window with specified number
100 Ctrl-P, Ctrl-N - Jump to previous / next window
103 <p>Clearly the easiest way is to use Meta-number keys. And what is the Meta
104 key? For some terminals, it's the same as ALT. If you have Windows keyboard,
105 it's probably the left Windows key. If they don't work directly, you'll need
106 to set a few X resources (NOTE: these work with both xterm and rxvt):</p>
109 XTerm*eightBitInput: false
110 XTerm*metaSendsEscape: true
113 <p>With rxvt, you can also specify which key acts as Meta key. So if you
114 want to use ALT instead of Windows key for it, use:</p>
120 <p>And how exactly do you set these X resources? For Debian, there's
121 /etc/X11/Xresources/xterm file where you can put them and it's read
122 automatically when X starts. ~/.Xresources and ~/.Xdefaults files might also
123 work. If you can't get anything else to work, just copy&paste those lines to
124 ~/.Xresources and directly call "xrdb -merge ~/.Xresources" in some xterm.
125 The resources affect only the new xterms you start, not existing ones.</p>
127 <p>Many windows SSH clients also don't allow usage of ALT. One excellent
128 client that does allow is putty, you can download it from
129 <a href="http://www.chiark.greenend.org.uk/~sgtatham/putty/">
130 http://www.chiark.greenend.org.uk/~sgtatham/putty/</a>.</p>
132 <p>Irssi also supports split windows, they've had some problems in past
133 but I think they should work pretty well now :) Here's some commands
137 /WINDOW NEW - Create new split window
138 /WINDOW NEW HIDE - Create new hidden window
139 /WINDOW CLOSE - Close split or hidden window
141 /WINDOW HIDE [<number>|<name>] - Make the split window hidden window
142 /WINDOW SHOW <number>|<name> - Make the hidden window a split window
144 /WINDOW SHRINK [<lines>] - Shrink the split window
145 /WINDOW GROW [<lines>] - Grow the split window
146 /WINDOW BALANCE - Balance the sizes of all split windows
149 <p>By default, irssi uses "sticky windowing" for split windows. This means
150 that windows created inside one split window cannot be moved to another
151 split window without some effort. For example you could have following
155 Split window 1: win#1 - Status window, win#2 - Messages window
156 Split window 2: win#3 - ircnet/#channel1, win#4 - ircnet/#channel2
157 Split window 3: win#5 - efnet/#channel1, win#6 - efnet/#channel2
160 <p>When you are in win#1 and press ALT-6, irssi jumps to split window
161 #3 and moves the efnet/#channel2 the active window.</p>
163 <p>With non-sticky windowing the windows don't have any relationship with
164 split windows, pressing ALT-6 in win#1 moves win#6 to split window 1
165 and sets it active, except if win#6 was already visible in some other
166 split window irssi just changes to that split window. This it the way
167 windows work with ircii, if you prefer it you can set it with</p>
170 /SET autostick_split_windows OFF
173 <p>Each window can have multiple channels, queries and other "window
174 items" inside them. If you don't like windows at all, you disable
175 automatic creating of them with</p>
178 /SET autocreate_windows OFF
181 <p>If you want to group only some channels or queries in one window,
185 /JOIN -window #channel
189 <h3><a id="c3">3. Server and channel automation</a></h3>
191 <p>Irssi's multiple IRC network support is IMHO very good - at least
192 compared to other clients :) Even if you're only in one IRC network you
193 should group all your servers to be in the same IRC network as this
194 helps with reconnecting if your primary server breaks and is probably
195 useful in some other ways too :) For information how to actually use
196 irssi correctly with multiple servers see the chapter 6.</p>
198 <p>First you need to have your IRC network set, use /IRCNET command to
199 see if it's already there. If it isn't, use /IRCNET ADD yourircnet. To
200 make Irssi work properly with different IRC networks, you might need to
201 give some special settings to /IRCNET ADD, see manual.txt for more
202 information about them. Irssi defaults to IRCNet's behaviour.</p>
204 <p>After that you need to add your servers. For example:</p>
207 /SERVER ADD -auto -ircnet ircnet irc.kpnqwest.fi 6667
208 /SERVER ADD -auto -ircnet worknet irc.mycompany.com 6667 password
211 <p>The -auto option specifies that this server is automatically connected
212 at startup. You don't need to make more than one server with -auto
213 option to one IRC network, other servers are automatically connected in
214 same network if the -auto server fails.</p>
216 <p>And finally channels:</p>
219 /CHANNEL ADD -auto -bots *!*@bot@host.org -botcmd "/^msg $0 op pass"
221 /CHANNEL ADD -auto #secret ircnet password
224 <p>-bots and -botcmd should be the only ones needing a bit of
225 explaining. They're used to send commands automatically to bot when
226 channel is joined, usually to get ops automatically. You can specify
227 multiple bot masks with -bots option separated with spaces (and
228 remember to quote the string then). The $0 in -botcmd specifies the
229 first found bot in the list. If you don't need the bot masks (ie. the
230 bot is always with the same nick, like chanserv) you can give only the
231 -botcmd option and the command is always sent.</p>
234 <h3><a id="c4">4. Setting up windows and automatically restoring them at startup</a></h3>
236 <p>First connect to all the servers, join the channels and create the
237 queries you want. If you want to move the windows or channels around
241 /WINDOW MOVE LEFT/RIGHT/number - move window elsewhere
242 /WINDOW ITEM MOVE <number>|<name> - move channel/query to another window
245 <p>When everything looks the way you like, use /LAYOUT SAVE command
246 (and /SAVE, if you don't have autosaving enabled) and when you start
247 irssi next time, irssi remembers the positions of the channels, queries
248 and everything. This "remembering" doesn't mean that simply using
249 /LAYOUT SAVE would automatically make irssi reconnect to all servers
250 and join all channels, you'll need the /SERVER ADD -auto and /CHANNEL
251 ADD -auto commands to do that.</p>
253 <p>If you want to change the layout, you just rearrange the layout like
254 you want it and use /LAYOUT SAVE again. If you want to remove the
255 layout for some reason, use /LAYOUT RESET.</p>
258 <h3><a id="c5">5. Status and msgs windows & message levels</a></h3>
260 <p>By default, all the "extra messages" go to status window. This means
261 pretty much all messages that don't clearly belong to some channel or
262 query. Some people like it, some don't. If you want to remove it, use</p>
265 /SET use_status_window OFF
268 <p>This doesn't have any effect until you restart irssi. If you want to
269 remove it immediately, just /WINDOW CLOSE it.</p>
271 <p>Another common window is "messages window", where all private
272 messages go. By default it's disabled and query windows are created
273 instead. To make all private messages go to msgs window, say:</p>
276 /SET use_msgs_window ON
277 /SET autocreate_query_level DCCMSGS (or if you don't want queries to
278 dcc chats either, say NONE)
281 <p>use_msgs_window either doesn't have any effect until restarting
282 irssi. To create it immediately say:</p>
285 /WINDOW NEW HIDE - create the window
286 /WINDOW NAME (msgs) - name it to "(msgs)"
287 /WINDOW LEVEL MSGS - make all private messages go to this window
288 /WINDOW MOVE 1 - move it to first window
291 <p>Note that neither use_msgs_window nor use_status_window have any
292 effect at all if /LAYOUT SAVE has been used.</p>
294 <p>This brings us to message levels.. What are they? All messages that
295 irssi prints have one or more "message levels". Most common are PUBLIC
296 for public messages in channels, MSGS for private messages and CRAP for
297 all sorts of messages with no real classification. You can get a whole
298 list of levels with</p>
304 <p>Status window has message level "ALL -MSGS", meaning that all messages,
305 except private messages, without more specific place go to status
306 window. The -MSGS is there so it doesn't conflict with messages
310 <h3><a id="c6">6. How support for multiple servers works in irssi</a></h3>
312 <p>ircii and several other clients support multiple servers by placing
313 the connection into some window. IRSSI DOES NOT. There is no required
314 relationship between window and server. You can connect to 10 servers
315 and manage them all in just one window, or join channel in each one of
316 them to one sigle window if you really want to. That being said, here's
317 how you do connect to new server without closing the old connection:</p>
320 /CONNECT irc.server.org
323 <p>Instead of the /SERVER which disconnects the existing connection. To
324 see list of all active connections, use /SERVER without any parameters.
325 You should see a list of something like:</p>
328 -!- IRCNet: irc.telia.fi:6667 (IRCNet)
329 -!- OPN: tolkien.openprojects.net:6667 (OPN)
330 -!- RECON-1: 192.168.0.1:6667 () (02:59 left before reconnecting)
333 <p>Here you see that we're connected to IRCNet and OPN networks. The
334 the IRCNet at the beginning is called the "server tag" while the
335 (IRCnet) at the end shows the IRC network. Server tag specifies unique
336 tag to refer to the server, usually it's the same as the IRC network.
337 When the IRC network isn't known it's some part of the server name.
338 When there's multiple connections to same IRC network or server, irssi
339 adds a number after the tag so there could be ircnet, ircnet2, ircnet3
342 <p>Server tags beginning with RECON- mean server reconnections. Above we
343 see that connection to server at 192.168.0.1 wasn't successful and
344 irssi will try to connect it again in 3 minutes.</p>
346 <p>To disconnect one of the servers, or to stop irssi from
347 reconnecting, use</p>
350 /DISCONNECT ircnet - disconnect server with tag "ircnet"
351 /DISCONNECT recon-1 - stop trying to reconnect to RECON-1 server
352 /RMRECONNS - stop all server reconnections
354 /RECONNECT recon-1 - immediately try reconnecting back to RECON-1
355 /RECONNECT ALL - immediately try reconnecting back to all
356 servers in reconnection queue
359 <p>Now that you're connected to all your servers, you'll have to know how
360 to specify which one of them you want to use. One way is to have an
361 empty window, like status or msgs window. In it, you can specify which
362 server to set active with</p>
365 /WINDOW SERVER tag - set server "tag" active
366 Ctrl-X - set the next server in list active
369 <p>When the server is active, you can use it normally. When there's
370 multiple connected servers, irssi adds [servertag] prefix to all
371 messages in non-channel/query messages so you'll know where it came
374 <p>Several commands also accept -servertag option to specify which server
378 /MSG -tag nick message
383 <p>/MSG tab completion also automatically adds the -tag option when
384 nick isn't in active server.</p>
386 <p>Window's server can be made sticky. When sticky, it will never
387 automatically change to anything else, and if server gets disconnected, the
388 window won't have any active server. When the server gets connected again,
389 it is automatically set active in the window. To set the window's server
393 /WINDOW SERVER -sticky tag
396 <p>This is useful if you wish to have multiple status or msgs windows, one
397 for each server. Here's how to do them (repeat for each server)</p>
401 /WINDOW NAME (status)
402 /WINDOW LEVEL ALL -MSGS
403 /WINDOW SERVER -sticky ircnet
408 /WINDOW SERVER -sticky ircnet
411 <h3><a id="c7">7. /LASTLOG and jumping around in scrollback</a></h3>
413 <p>/LASTLOG command can be used for searching texts in scrollback
414 buffer. Simplest usages are</p>
417 /LASTLOG word - print all lines with "word" in them
418 /LASTLOG word 10 - print last 10 occurances of "word"
419 /LASTLOG -topics - print all topic changes
422 <p>If there's more lines to be printed than 1000, irssi doesn't thinks
423 that you probably made some mistake and won't print them without -force
424 option. If you want to save the full lastlog to file, use</p>
427 /LASTLOG -file ~/irc.log
430 <p>With -file option you don't need -force even if there's more than 1000
431 lines. /LASTLOG has a lot of other options too, see /HELP lastlog for
434 <p>Once you've found the lines you were interested in, you might want
435 to check the discussion around them. Irssi has /SCROLLBACK (or alias
436 /SB) command for jumping around in scrollback buffer. Since /LASTLOG
437 prints the timestamp when the message was originally printed, you can
438 use /SB GOTO hh:mm to jump directly there. To get back to the bottom of
439 scrollback, use /SB END command.</p>
442 <h3><a id="c8">8. Logging</a></h3>
444 <p>Irssi can automatically log important messages when you're set away
445 (/AWAY reason). When you set yourself unaway (/AWAY), the new messages
446 in away log are printed to screen. You can configure it with:</p>
449 /SET awaylog_level MSGS HILIGHT - Specifies what messages to log
450 /SET awaylog_file ~/.irssi/away.log - Specifies the file to use
453 <p>Easiest way to start logging with Irssi is to use autologging. With it
454 Irssi logs all channels and private messages to specified directory.
455 You can turn it on with</p>
461 <p>By default it logs pretty much everything execept CTCPS or CRAP
462 (/WHOIS requests, etc). You can specify the logging level yourself with</p>
465 /SET autolog_level ALL -CRAP -CLIENTCRAP -CTCPS (this is the default)
468 <p>By default irssi logs to ~/irclogs/<servertag>/<target>.log.
469 You can change this with</p>
472 /SET autolog_path ~/irclogs/$tag/$0.log (this is the default)
475 <p>The path is automatically created if it doesn't exist. $0 specifies
476 the target (channel/nick). You can make irssi automatically rotate the
477 logs by adding date/time formats to the file name. The formats are in
478 "man strftime" format. For example</p>
481 /SET autolog_path = ~/irclogs/%Y/$tag/$0.%m-%d.log
484 <p>For logging only some specific channels or nicks, see /HELP log</p>
487 <h3><a id="c9">9. Irssi's settings</a></h3>
489 <p>You probably don't like Irssi's default settings. I don't like them.
490 But I'm still convinced that they're pretty good defaults. Here's some
491 of them you might want to change (the default value is shown):</p>
493 <p><strong>Queries</strong></p>
496 <dt>/SET autocreate_own_query ON</dt>
497 <dd>Should new query window be created when you send message to someone
500 <dt>/SET autocreate_query_level MSGS</dt>
501 <dd>New query window should be created when receiving messages with
502 this level. MSGS, DCCMSGS and NOTICES levels work currently. You can
503 disable this with /SET -clear autocrate_query_level.</dd>
505 <dt>/SET autoclose_query 0</dt>
506 <dd>Query windows can be automatically closed after certain time of
507 inactivity. Queries with unread messages aren't closed and active
508 window is neither never closed. The value is given in seconds.</dd>
511 <p><strong>Windows</strong></p>
514 <dt>/SET use_msgs_window OFF</dt>
515 <dd>Create messages window at startup. All private messages go to this
516 window. This only makes sense if you've disabled automatic query
517 windows. Message window can also be created manually with /WINDOW LEVEL
518 MSGS, /WINDOW NAME (msgs).</dd>
520 <dt>/SET use_status_window ON</dt>
521 <dd>Create status window at startup. All messages that don't really
522 have better place go here, like all /WHOIS replies etc. Status window
523 can also be created manually with /WINDOW LEVEL ALL -MSGS, /WINDOW NAME
526 <dt>/SET autocreate_windows ON</dt>
527 <dd>Should we create new windows for new window items or just place
528 everything in one window</dd>
530 <dt>/SET autoclose_windows ON</dt>
531 <dd>Should window be automatically closed when the last item in them is
532 removed (ie. /PART, /UNQUERY).</dd>
534 <dt>/SET reuse_unused_windows OFF</dt>
535 <dd>When finding where to place new window item (channel, query) Irssi
536 first tries to use already existing empty windows. If this is set ON,
537 new window will always be created for all window items. This setting is
538 ignored if autoclose_windows is set ON.</dd>
540 <dt>/SET window_auto_change OFF</dt>
541 <dd>Should Irssi automatically change to automatically created windows
542 - usually queries when someone sends you a message. To prevent
543 accidentally sending text meant to some other channel/nick, Irssi
544 clears the input buffer when changing the window. The text is still in
545 scrollback buffer, you can get it back with pressing arrow up key.</dd>
547 <dt>/SET print_active_channel OFF</dt>
548 <dd>When you keep more than one channel in same window, Irssi prints
549 the messages coming to active channel as "<nick> text"
550 and other channels as "<nick:channel> text". If this
551 setting is set ON, the messages to active channels are also printed in
554 <dt>/SET window_history OFF</dt>
555 <dd>Should command history be kept separate for each window.</dd>
559 <p><strong>User information</strong></p>
563 <dd>Your nick name</dd>
565 <dt>/SET alternate_nick</dt>
566 <dd>Your alternate nick.</dd>
568 <dt>/SET user_name</dt>
569 <dd>Your username, if you have ident enabled this doesn't affect
572 <dt>/SET real_name</dt>
573 <dd>Your real name.</dd>
577 <p><strong>Server information</strong></p>
580 <dt>/SET skip_motd OFF</dt>
581 <dd>Should we hide server's MOTD (Message Of The Day).</dd>
583 <dt>/SET server_reconnect_time 300</dt>
584 <dd>Seconds to wait before connecting to same server again. Don't set
585 this too low since it usually doesn't help at all - if the host is
586 down, the few extra minutes of waiting won't hurt much.</dd>
588 <dt>/SET lag_max_before_disconnect 300</dt>
589 <dd>Maximum server lag in seconds before disconnecting and trying to
590 reconnect. This happens mostly only when network breaks between you and
595 <p><strong>Appearance</strong></p>
598 <dt>/SET timestamps ON</dt>
599 <dd>Show timestamps before each message.</dd>
601 <dt>/SET hide_text_style OFF</dt>
602 <dd>Hide all bolds, underlines, MIRC colors, etc.</dd>
604 <dt>/SET show_nickmode ON</dt>
605 <dd>Show the nick's mode before nick in channels, ie. ops have
606 <@nick>, voices <+nick> and others < nick></dd>
608 <dt>/SET show_quit_once OFF</dt>
609 <dd>Show quit message only once in some of the channel windows the
610 nick was in instead of in all windows.</dd>
612 <dt>/SET topicbar ON</dt>
613 <dd>Show the channel's topic in top of screen.</dd>
615 <dt>/SET lag_min_show 100</dt>
616 <dd>Show the server lag in status bar if it's bigger than this, the
617 unit is 1/100 of seconds (ie. the default value of 100 = 1 second).</dd>
619 <dt>/SET indent 10</dt>
620 <dd>When lines are longer than screen width they have to be split to
621 multiple lines. This specifies how much space to put at the beginning
622 of the line before the text begins. This can be overridden in text
623 formats with %| format.</dd>
625 <dt>/SET activity_hide_targets</dt>
626 <dd>If you don't want to see window activity in some certain channels
627 or queries, list them here. For example "#boringchannel =bot1 =bot2".
628 If any highlighted text or message for you appears in that window, this
629 setting is ignored and the activity is shown.</dd>
631 <dt>/SET mail_counter ON</dt>
632 <dd>Show the number of mails in your mbox in status
633 bar. The mbox file is taken from $MAIL environment setting. Only mbox
634 format works for now.</dd>
637 <p><strong>Nick completion</strong></p>
640 <dt>/SET completion_auto OFF</dt>
641 <dd>Automatically complete the nick if line begins with start of nick
642 and the completion character. Learn to use the tab-completion instead,
643 it's a lot better ;)</dd>
645 <dt>/SET completion_char :</dt>
646 <dd>Completion character to use.</dd>