diff options
Diffstat (limited to 'docs/startup-HOWTO.html')
| -rw-r--r-- | docs/startup-HOWTO.html | 647 |
1 files changed, 647 insertions, 0 deletions
diff --git a/docs/startup-HOWTO.html b/docs/startup-HOWTO.html new file mode 100644 index 00000000..60aa9d75 --- /dev/null +++ b/docs/startup-HOWTO.html @@ -0,0 +1,647 @@ + <h2>Startup HOWTO</h2> + + <h3>To new Irssi users (not to new IRC users ..)</h3> + + <p>Copyright (c) 2000-2001 by Timo Sirainen</p> + + +<p>Index with some FAQ questions that are answered in the chapter:</p> + +<ol> +<li><a href="#c1">For all the lazy people</a></li> +<li><a href="#c2">Basic user interface usage</a></li> +<li><a href="#c3">Server and channel automation</a> + <ul> + <li>how do I automatically connect to servers at startup?</li> + <li>how do I automatically join to channels at startup?</li> + </ul></li> +<li><a href="#c4">Setting up windows and automatically restoring them + at startup</a></li> +<li><a href="#c5">Status and msgs windows & message levels</a> + <ul> + <li>I want /WHOIS to print reply to current window</li> + <li>I want all messages to go to one window, not create new windows</li> + </ul></li> +<li><a href="#c6">How support for multiple servers works in irssi</a> + <ul> + <li>I connected to some server that doesn't respond and now irssi + keeps trying to reconnect to it again and again, how can I stop + it??</li> + <li>I want to have own status and/or msgs window for each servers</li> + </ul></li> +<li><a href="#c7">/LASTLOG and jumping around in scrollback</a> + <ul> + <li>How can I save all texts in a window to file?</li> + </ul></li> +<li><a href="#c8">Logging</a></li> +<li><a href="#c9">Irssi's settings</a></li> +</ol> + +<h3><a id="c1">1. For all the lazy people</a></h3> + +<p>These settings should give you pretty good defaults (the ones I use):</p> + +<p>I don't like automatic query windows, I don't like status window, I do +like msgs window where all messages go:</p> + +<pre> + /SET autocreate_own_query OFF + /SET autocreate_query_level DCCMSGS + /SET use_status_window OFF + /SET use_msgs_window ON +</pre> + +<p>Disable automatic window closing when /PARTing channel or /UNQUERYing +query:</p> + +<pre> + /SET autoclose_windows OFF + /SET reuse_unused_windows ON +</pre> + +<p>And example how to add servers:</p> + +<p>(openprojects network, identify with nickserv and wait for 2 seconds before +joining channels)</p> + +<pre> + /IRCNET ADD -autosendcmd "/^msg nickserv ident pass;wait -opn 2000" opn +</pre> + +<p>Then add some servers to different networks (ircnet is already set up +for them), irc.kpnqwest.fi is used by default for IRCNet but if it fails, +irc.funet.fi is tried next:</p> + +<pre> + /SERVER ADD -auto -ircnet ircnet irc.kpnqwest.fi 6667 + /SERVER ADD -ircnet ircnet irc.funet.fi 6667 + /SERVER ADD -auto -ircnet efnet efnet.cs.hut.fi 6667 +</pre> + +<p>Automatically join to channels after connected to server, send op request +to bot after joined to efnet/#irssi:</p> + +<pre> + /CHANNEL ADD -auto #irssi ircnet + /CHANNEL ADD -auto -bots *!*@bot@host.org -botcmd "/^msg $0 op pass" + #irssi efnet +</pre> + +<h3><a id="c2">2. Basic user interface usage</a></h3> + +<p>By default, irssi uses "hidden windows" for everything. Hidden +window is created every time you /JOIN a channel or /QUERY someone. +There's several ways you can change between these windows:</p> + +<pre> + ALT-1, ALT-2, ... ALT-0 - Jump directly between windows 1-10 + ALT-q .. ALT-p - Jump directly between windows 11-20 + ESC-1 .. ESC-0 - ALT-keys don't work everywhere, but you can + use ESC-key instead of ALT. + /WINDOW <number> - Jump to any window with specified number + Ctrl-P, Ctrl-N - Jump to previous / next window +</pre> + +<p>Clearly the easiest way is to use ALT-number keys. Some terminals +just don't allow it, with xterm and rxvt you should be able to fix it +with changing X resources:</p> + +<pre> + XTerm*eightBitInput: false + XTerm*metaSendsEscape: true +</pre> + +<p>And how exactly does it happen? For Debian, there's +/etc/X11/Xresources/xterm file where you can put them and it's read +automatically when X starts. ~/.Xresources file might also work. If you +can't get anything else to work, just copy&paste those lines to +~/.Xresources and directly call "xrdb -merge ~/.Xresources" in some +xterm. The resources affect only the new xterms you start, not existing +ones.</p> + +<p>Many windows SSH clients also don't allow usage of ALT. One excellent +client that does allow is putty, you can download it from +<a href="http://www.chiark.greenend.org.uk/~sgtatham/putty/"> +http://www.chiark.greenend.org.uk/~sgtatham/putty/</a>.</p> + +<p>Irssi also supports split windows, they've had some problems in past +but I think they should work pretty well now :) Here's some commands +related to them:</p> + +<pre> + /WINDOW NEW - Create new split window + /WINDOW NEW HIDE - Create new hidden window + /WINDOW CLOSE - Close split or hidden window + + /WINDOW HIDE [<number>|<name>] - Make the split window hidden window + /WINDOW SHOW <number>|<name> - Make the hidden window a split window + + /WINDOW SHRINK [<lines>] - Shrink the split window + /WINDOW GROW [<lines>] - Grow the split window + /WINDOW BALANCE - Balance the sizes of all split windows +</pre> + +<p>By default, irssi uses "sticky windowing" for split windows. This means +that windows created inside one split window cannot be moved to another +split window without some effort. For example you could have following +window layout:</p> + +<pre> + Split window 1: win#1 - Status window, win#2 - Messages window + Split window 2: win#3 - ircnet/#channel1, win#4 - ircnet/#channel2 + Split window 3: win#5 - efnet/#channel1, win#6 - efnet/#channel2 +</pre> + +<p>When you are in win#1 and press ALT-6, irssi changes jumps to split +window #3 and moves the efnet/#channel2 the active window.</p> + +<p>With non-sticky windowing the windows don't have any relationship with +split windows, pressing ALT-6 in win#1 moves win#6 to split window 1 +and sets it active, except if win#6 was already visible in some other +split window irssi just changes to that split window. This it the way +windows work with ircii, if you prefer it you can set it with</p> + +<pre> + /SET autostick_split_windows OFF +</pre> + +<p>Each window can have multiple channels, queries and other "window +items" inside them. If you don't like windows at all, you disable +automatic creating of them with</p> + +<pre> + /SET autocreate_windows OFF +</pre> + +<p>If you want to group only some channels or queries in one window, +use</p> + +<pre> + /JOIN -window #channel + /QUERY -window nick +</pre> + +<h3><a id="c3">3. Server and channel automation</a></h3> + +<p>Irssi's multiple IRC network support is IMHO very good - at least +compared to other clients :) Even if you're only in one IRC network you +should group all your servers to be in the same IRC network as this +helps with reconnecting if your primary server breaks and is probably +useful in some other ways too :) For information how to actually use +irssi correctly with multiple servers see the chapter 6.</p> + +<p>First you need to have your IRC network set, use /IRCNET command to +see if it's already there. If it isn't, use /IRCNET ADD yourircnet. To +make Irssi work properly with different IRC networks, you might need to +give some special settings to /IRCNET ADD, see manual.txt for more +information about them. Irssi defaults to IRCNet's behaviour.</p> + +<p>After that you need to add your servers. For example:</p> + +<pre> + /SERVER ADD -auto -ircnet ircnet irc.kpnqwest.fi 6667 + /SERVER ADD -auto -ircnet worknet irc.mycompany.com 6667 password +</pre> + +<p>The -auto option specifies that this server is automatically connected +at startup. You don't need to make more than one server with -auto +option to one IRC network, other servers are automatically connected in +same network if the -auto server fails.</p> + +<p>And finally channels:</p> + +<pre> + /CHANNEL ADD -auto -bots *!*@bot@host.org -botcmd "/^msg $0 op pass" + #irssi efnet + /CHANNEL ADD -auto #secret ircnet password +</pre> + +<p>-bots and -botcmd should be the only ones needing a bit of +explaining. They're used to send commands automatically to bot when +channel is joined, usually to get ops automatically. You can specify +multiple bot masks with -bots option separated with spaces (and +remember to quote the string then). The $0 in -botcmd specifies the +first found bot in the list. If you don't need the bot masks (ie. the +bot is always with the same nick, like chanserv) you can give only the +-botcmd option and the command is always sent.</p> + + +<h3><a id="c4">4. Setting up windows and automatically restoring them at startup</a></h3> + +<p>First connect to all the servers, join the channels and create the +queries you want. If you want to move the windows or channels around +use commands:</p> + +<pre> + /WINDOW MOVE LEFT/RIGHT/number - move window elsewhere + /WINDOW ITEM MOVE <number>|<name> - move channel/query to another window +</pre> + +<p>When everything looks the way you like, use /LAYOUT SAVE command +(and /SAVE, if you don't have autosaving enabled) and when you start +irssi next time, irssi remembers the positions of the channels, queries +and everything. This "remembering" doesn't mean that simply using +/LAYOUT SAVE would automatically make irssi reconnect to all servers +and join all channels, you'll need the /SERVER ADD -auto and /CHANNEL +ADD -auto commands to do that.</p> + +<p>If you want to change the layout, you just rearrange the layout like +you want it and use /LAYOUT SAVE again. If you want to remove the +layout for some reason, use /LAYOUT RESET.</p> + + +<h3><a id="c5">5. Status and msgs windows & message levels</a></h3> + +<p>By default, all the "extra messages" go to status window. This means +pretty much all messages that don't clearly belong to some channel or +query. Some people like it, some don't. If you want to remove it, use</p> + +<pre> + /SET use_status_window OFF +</pre> + +<p>This doesn't have any effect until you restart irssi. If you want to +remove it immediately, just /WINDOW CLOSE it.</p> + +<p>Another common window is "messages window", where all private +messages go. By default it's disabled and query windows are created +instead. To make all private messages go to msgs window, say:</p> + +<pre> + /SET use_msgs_window ON + /SET autocreate_query_level DCCMSGS (or if you don't want queries to + dcc chats either, say NONE) +</pre> + +<p>use_msgs_window either doesn't have any effect until restarting +irssi. To create it immediately say:</p> + +<pre> + /WINDOW NEW HIDE - create the window + /WINDOW NAME (msgs) - name it to "(msgs)" + /WINDOW LEVEL MSGS - make all private messages go to this window + /WINDOW MOVE 1 - move it to first window +</pre> + +<p>Note that neither use_msgs_window nor use_status_window have any +effect at all if /LAYOUT SAVE has been used.</p> + +<p>This brings us to message levels.. What are they? All messages that +irssi prints have one or more "message levels". Most common are PUBLIC +for public messages in channels, MSGS for private messages and CRAP for +all sorts of messages with no real classification. You can get a whole +list of levels with</p> + +<pre> + /HELP levels +</pre> + +<p>Status window has message level "ALL -MSGS", meaning that all messages, +except private messages, without more specific place go to status +window. The -MSGS is there so it doesn't conflict with messages +window.</p> + + +<h3><a id="c6">6. How support for multiple servers works in irssi</a></h3> + +<p>ircii and several other clients support multiple servers by placing +the connection into some window. IRSSI DOES NOT. There is no required +relationship between window and server. You can connect to 10 servers +and manage them all in just one window, or join channel in each one of +them to one sigle window if you really want to. That being said, here's +how you do connect to new server without closing the old connection:</p> + +<pre> + /CONNECT irc.server.org +</pre> + +<p>Instead of the /SERVER which disconnects the existing connection. To +see list of all active connections, use /SERVER without any parameters. +You should see a list of something like:</p> + +<pre> + -!- IRCNet: irc.telia.fi:6667 (IRCNet) + -!- OPN: tolkien.openprojects.net:6667 (OPN) + -!- RECON-1: 192.168.0.1:6667 () (02:59 left before reconnecting) +</pre> + +<p>Here you see that we're connected to IRCNet and OPN networks. The +the IRCNet at the beginning is called the "server tag" while the +(IRCnet) at the end shows the IRC network. Server tag specifies unique +tag to refer to the server, usually it's the same as the IRC network. +When the IRC network isn't known it's some part of the server name. +When there's multiple connections to same IRC network or server, irssi +adds a number after the tag so there could be ircnet, ircnet2, ircnet3 +etc.</p> + +<p>Server tags beginning with RECON- mean server reconnections. Above we +see that connection to server at 192.168.0.1 wasn't successful and +irssi will try to connect it again in 3 minutes.</p> + +<p>To disconnect one of the servers, or to stop irssi from +reconnecting, use</p> + +<pre> + /DISCONNECT ircnet - disconnect server with tag "ircnet" + /DISCONNECT recon-1 - stop trying to reconnect to RECON-1 server + /RMRECONNS - stop all server reconnections + + /RECONNECT recon-1 - immediately try reconnecting back to RECON-1 + /RECONNECT ALL - immediately try reconnecting back to all + servers in reconnection queue +</pre> + +<p>Now that you're connected to all your servers, you'll have to know how +to specify which one of them you want to use. One way is to have an +empty window, like status or msgs window. In it, you can specify which +server to set active with</p> + +<pre> + /WINDOW SERVER tag - set server "tag" active + Ctrl-X - set the next server in list active +</pre> + +<p>When the server is active, you can use it normally. When there's +multiple connected servers, irssi adds [servertag] prefix to all +messages in non-channel/query messages so you'll know where it came +from.</p> + +<p>Several commands also accept -servertag option to specify which server +it should use:</p> + +<pre> + /MSG -tag nick message + /JOIN -tag #channel + /QUERY -tag nick +</pre> + +<p>/MSG tab completion also automatically adds the -tag option when +nick isn't in active server.</p> + +<p>Window's server can be made sticky. When sticky, it will never +automatically change to anything else, and if server gets disconnected, the +window won't have any active server. When the server gets connected again, +it is automatically set active in the window. To set the window's server +sticky use</p> + +<pre> + /WINDOW SERVER -sticky tag +</pre> + +<p>This is useful if you wish to have multiple status or msgs windows, one +for each server. Here's how to do them (repeat for each server)</p> + +<pre> + /WINDOW NEW HIDE + /WINDOW NAME (status) + /WINDOW LEVEL ALL -MSGS + /WINDOW SERVER -sticky ircnet + + /WINDOW NEW HIDE + /WINDOW NAME (msgs) + /WINDOW LEVEL MSGS + /WINDOW SERVER -sticky ircnet +</pre> + +<h3><a id="c7">7. /LASTLOG and jumping around in scrollback</a></h3> + +<p>/LASTLOG command can be used for searching texts in scrollback +buffer. Simplest usages are</p> + +<pre> + /LASTLOG word - print all lines with "word" in them + /LASTLOG word 10 - print last 10 occurances of "word" + /LASTLOG -topics - print all topic changes +</pre> + +<p>If there's more lines to be printed than 1000, irssi doesn't thinks +that you probably made some mistake and won't print them without -force +option. If you want to save the full lastlog to file, use</p> + +<pre> + /LASTLOG -file ~/irc.log +</pre> + +<p>With -file option you don't need -force even if there's more than 1000 +lines. /LASTLOG has a lot of other options too, see /HELP lastlog for +details.</p> + +<p>Once you've found the lines you were interested in, you might want +to check the discussion around them. Irssi has /SCROLLBACK (or alias +/SB) command for jumping around in scrollback buffer. Since /LASTLOG +prints the timestamp when the message was originally printed, you can +use /SB GOTO hh:mm to jump directly there. To get back to the bottom of +scrollback, use /SB END command.</p> + + +<h3><a id="c8">8. Logging</a></h3> + +<p>Irssi can automatically log important messages when you're set away +(/AWAY reason). When you set yourself unaway (/AWAY), the new messages +in away log are printed to screen. You can configure it with:</p> + +<pre> + /SET awaylog_level MSGS HILIGHT - Specifies what messages to log + /SET awaylog_file ~/.irssi/away.log - Specifies the file to use +</pre> + +<p>Easiest way to start logging with Irssi is to use autologging. With it +Irssi logs all channels and private messages to specified directory. +You can turn it on with</p> + +<pre> + /SET autolog ON +</pre> + +<p>By default it logs pretty much everything execept CTCPS or CRAP +(/WHOIS requests, etc). You can specify the logging level yourself with</p> + +<pre> + /SET autolog_level ALL -CRAP -CLIENTCRAP -CTCPS (this is the default) +</pre> + +<p>By default irssi logs to ~/irclogs/<servertag>/<target>.log. +You can change this with</p> + +<pre> + /SET autolog_path ~/irclogs/$tag/$0.log (this is the default) +</pre> + +<p>The path is automatically created if it doesn't exist. $0 specifies +the target (channel/nick). You can make irssi automatically rotate the +logs by adding date/time formats to the file name. The formats are in +"man strftime" format. For example</p> + +<pre> + /SET autolog_path = ~/irclogs/%Y/$tag/$0.%m-%d.log +</pre> + +<p>For logging only some specific channels or nicks, see /HELP log</p> + + +<h3><a id="c9">9. Irssi's settings</a></h3> + +<p>You probably don't like Irssi's default settings. I don't like them. +But I'm still convinced that they're pretty good defaults. Here's some +of them you might want to change (the default value is shown):</p> + +<p><strong>Queries</strong></p> + +<dl> +<dt>/SET autocreate_own_query ON</dt> + <dd>Should new query window be created when you send message to someone + (with /msg).</dd> + +<dt>/SET autocreate_query_level MSGS</dt> + <dd>New query window should be created when receiving messages with + this level. MSGS, DCCMSGS and NOTICES levels work currently. You can + disable this with /SET -clear autocrate_query_level.</dd> + +<dt>/SET autoclose_query 0</dt> + <dd>Query windows can be automatically closed after certain time of + inactivity. Queries with unread messages aren't closed and active + window is neither never closed. The value is given in seconds.</dd> +</dl> + +<p><strong>Windows</strong></p> + +<dl> +<dt>/SET use_msgs_window OFF</dt> + <dd>Create messages window at startup. All private messages go to this + window. This only makes sense if you've disabled automatic query + windows. Message window can also be created manually with /WINDOW LEVEL + MSGS, /WINDOW NAME (msgs).</dd> + +<dt>/SET use_status_window ON</dt> + <dd>Create status window at startup. All messages that don't really + have better place go here, like all /WHOIS replies etc. Status window + can also be created manually with /WINDOW LEVEL ALL -MSGS, /WINDOW NAME + (status).</dd> + +<dt>/SET autocreate_windows</dt> + <dd>Should we create new windows for new window items or just place + everything in one window</dd> + +<dt>/SET autoclose_windows OFF</dt> + <dd>Should window be automatically closed when the last item in them is + removed (ie. /PART, /UNQUERY).</dd> + +<dt>/SET reuse_unused_windows OFF</dt> + <dd>When finding where to place new window item (channel, query) Irssi + first tries to use already existing empty windows. If this is set ON, + new window will always be created for all window items. This setting is + ignored if autoclose_windows is set ON.</dd> + +<dt>/SET window_auto_change OFF</dt> + <dd>Should Irssi automatically change to automatically created windows + - usually queries when someone sends you a message. To prevent + accidentally sending text meant to some other channel/nick, Irssi + clears the input buffer when changing the window. The text is still in + scrollback buffer, you can get it back with pressing arrow up key.</dd> + +<dt>/SET print_active_channel OFF</dt> + <dd>When you keep more than one channel in same window, Irssi prints + the messages coming to active channel as "<nick> text" + and other channels as "<nick:channel> text". If this + setting is set ON, the messages to active channels are also printed in + the latter way.</dd> + +<dt>/SET window_history OFF</dt> + <dd>Should command history be kept separate for each window.</dd> +</dl> + + +<p><strong>User information</strong></p> + +<dl> +<dt>/SET nick</dt> + <dd>Your nick name</dd> + +<dt>/SET alternate_nick</dt> + <dd>Your alternate nick.</dd> + +<dt>/SET user_name</dt> + <dd>Your username, if you have ident enabled this doesn't affect + anything</dd> + +<dt>/SET real_name</dt> + <dd>Your real name.</dd> +</dl> + + +<p><strong>Server information</strong></p> + +<dl> +<dt>/SET skip_motd OFF</dt> + <dd>Should we hide server's MOTD (Message Of The Day).</dd> + +<dt>/SET server_reconnect_time 300</dt> + <dd>Seconds to wait before connecting to same server again. Don't set + this too low since it usually doesn't help at all - if the host is + down, the few extra minutes of waiting won't hurt much.</dd> + +<dt>/SET lag_max_before_disconnect 300</dt> + <dd>Maximum server lag in seconds before disconnecting and trying to + reconnect. This happens mostly only when network breaks between you and + IRC server.</dd> +</dl> + + +<p><strong>Appearance</strong></p> + +<dl> +<dt>/SET timestamps ON</dt> + <dd>Show timestamps before each message.</dd> + +<dt>/SET hide_text_style OFF</dt> + <dd>Hide all bolds, underlines, MIRC colors, etc.</dd> + +<dt>/SET show_nickmode ON</dt> + <dd>Show the nick's mode before nick in channels, ie. ops have + <@nick>, voices <+nick> and others < nick></dd> + +<dt>/SET show_quit_once OFF</dt> + <dd>Show quit message only once in some of the channel windows the + nick was in instead of in all windows.</dd> + +<dt>/SET topicbar ON</dt> + <dd>Show the channel's topic in top of screen.</dd> + +<dt>/SET lag_min_show 100</dt> + <dd>Show the server lag in status bar if it's bigger than this, the + unit is 1/100 of seconds (ie. the default value of 100 = 1 second).</dd> + +<dt>/SET indent 10</dt> + <dd>When lines are longer than screen width they have to be split to + multiple lines. This specifies how much space to put at the beginning + of the line before the text begins. This can be overridden in text + formats with %| format.</dd> + +<dt>/SET noact_channels</dt> + <dd>If you don't want to see window activity in some certain channels + or queries, list them here. For example "#boringchannel =bot1 =bot2". + If any highlighted text or message for you appears in that window, this + setting is ignored and the activity is shown.</dd> + +<dt>/SET mail_counter ON</dt> + <dd>Show the number of mails in your mbox in status + bar. The mbox file is taken from $MAIL environment setting. Only mbox + format works for now.</dd> + +<dt>/SET statusbar_xxx</dt> + <dd>Change these to change the colors of the statusbar. Type "/SET + statusbar" to see all the different settings.</dd> +</dl> + + +<p><strong>Nick completion</strong></p> + +<dl> +<dt>/SET completion_auto OFF</dt> + <dd>Automatically complete the nick if line begins with start of nick + and the completion character. Learn to use the tab-completion instead, + it's a lot better ;)</dd> + +<dt>/SET completion_char :</dt> + <dd>Completion character to use.</dd> +</dl> |