[crypto.git] / apps / irssi / docs / startup-HOWTO.txt

Startup HOWTO

  To new Irssi users (not to new IRC users ..)

   Copyright (c) 2000-2001 by Timo Sirainen

   Index with some FAQ questions that are answered in the chapter:
    1. For all the lazy people
    2. Basic user interface usage
    3. Server and channel automation
          + how do I automatically connect to servers at startup?
          + how do I automatically join to channels at startup?
    4. Setting up windows and automatically restoring them at startup
    5. Status and msgs windows & message levels
          + I want /WHOIS to print reply to current window
          + I want all messages to go to one window, not create new
            windows
    6. How support for multiple servers works in irssi
          + 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??
          + I want to have own status and/or msgs window for each servers
    7. /LASTLOG and jumping around in scrollback
          + How can I save all texts in a window to file?
    8. Logging
    9. Proxies and IRC bouncers
   10. Irssi's settings

  1. For all the lazy people

   These settings should give you pretty good defaults (the ones I use):

   I don't like automatic query windows, I don't like status window, I do
   like msgs window where all messages go:
     /SET autocreate_own_query OFF
     /SET autocreate_query_level DCCMSGS
     /SET use_status_window OFF
     /SET use_msgs_window ON

   Disable automatic window closing when /PARTing channel or /UNQUERYing
   query:
     /SET autoclose_windows OFF
     /SET reuse_unused_windows ON

   And example how to add servers:

   (openprojects network, identify with nickserv and wait for 2 seconds
   before joining channels)
     /IRCNET ADD -autosendcmd "/^msg nickserv ident pass;wait -opn 2000" opn

   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:
     /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

   Automatically join to channels after connected to server, send op
   request to bot after joined to efnet/#irssi:
     /CHANNEL ADD -auto #irssi ircnet
     /CHANNEL ADD -auto -bots *!*bot@host.org -botcmd "/^msg $0 op pass"
                  #irssi efnet

   If you want lines containing your nick to hilight:
     /HILIGHT nick

  2. Basic user interface usage

   Windows can be scrolled up/down with PgUp and PgDown keys. If they
   don't work for you, use Meta-p and Meta-n keys. For jumping to
   beginning or end of the buffer, use /SB HOME and /SB END commands.

   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:
     Meta-1, Meta-2, .. Meta-0 - Jump directly between windows 1-10
     Meta-q .. Meta-o          - Jump directly between windows 11-19
     /WINDOW <number>          - Jump to any window with specified number
     Ctrl-P, Ctrl-N            - Jump to previous / next window

   Clearly the easiest way is to use Meta-number keys. And what is the
   Meta key? For some terminals, it's the same as ALT. If you have
   Windows keyboard, it's probably the left Windows key. If they don't
   work directly, you'll need to set a few X resources (NOTE: these work
   with both xterm and rxvt):
     XTerm*eightBitInput:   false
     XTerm*metaSendsEscape: true

   With rxvt, you can also specify which key acts as Meta key. So if you
   want to use ALT instead of Windows key for it, use:
     rxvt*modifier: alt

   You could do this by changing the X key mappings:
    xmodmap -e "keysym Alt_L = Meta_L Alt_L"

   And how exactly do you set these X resources? For Debian, there's
   /etc/X11/Xresources/xterm file where you can put them and it's read
   automatically when X starts. ~/.Xresources and ~/.Xdefaults files
   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.

   Many windows SSH clients also don't allow usage of ALT. One excellent
   client that does allow is putty, you can download it from
   http://www.chiark.greenend.org.uk/~sgtatham/putty/.

   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:
     /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

   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:
     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

   When you are in win#1 and press ALT-6, irssi jumps to split window #3
   and moves the efnet/#channel2 the active window.

   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
     /SET autostick_split_windows OFF

   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
     /SET autocreate_windows OFF

   If you want to group only some channels or queries in one window, use
     /JOIN -window #channel
     /QUERY -window nick

  3. Server and channel automation

   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.

   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.

   After that you need to add your servers. For example:
     /SERVER ADD -auto -ircnet ircnet irc.kpnqwest.fi 6667
     /SERVER ADD -auto -ircnet worknet irc.mycompany.com 6667 password

   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.

   And finally channels:
     /CHANNEL ADD -auto -bots *!*bot@host.org -botcmd "/^msg $0 op pass"
                  #irssi efnet
     /CHANNEL ADD -auto #secret ircnet password

   -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.

  4. Setting up windows and automatically restoring them at startup

   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:
     /WINDOW MOVE LEFT/RIGHT/number    - move window elsewhere
     /WINDOW ITEM MOVE <number>|<name> - move channel/query to another window

   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.

   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.

  5. Status and msgs windows & message levels

   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
     /SET use_status_window OFF

   This doesn't have any effect until you restart irssi. If you want to
   remove it immediately, just /WINDOW CLOSE it.

   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:
     /SET use_msgs_window ON
     /SET autocreate_query_level DCCMSGS  (or if you don't want queries to
                                           dcc chats either, say NONE)

   use_msgs_window either doesn't have any effect until restarting irssi.
   To create it immediately say:
     /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

   Note that neither use_msgs_window nor use_status_window have any
   effect at all if /LAYOUT SAVE has been used.

   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
     /HELP levels

   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.

  6. How support for multiple servers works in irssi

   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:
     /CONNECT irc.server.org

   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:
     -!- IRCNet: irc.telia.fi:6667 (IRCNet)
     -!- OPN: tolkien.openprojects.net:6667 (OPN)
     -!- RECON-1: 192.168.0.1:6667 () (02:59 left before reconnecting)

   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.

   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.

   To disconnect one of the servers, or to stop irssi from reconnecting,
   use
     /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

   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
     /WINDOW SERVER tag    - set server "tag" active
     Ctrl-X                - set the next server in list active

   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.

   Several commands also accept -servertag option to specify which server
   it should use:
     /MSG -tag nick message
     /JOIN -tag #channel
     /QUERY -tag nick

   /MSG tab completion also automatically adds the -tag option when nick
   isn't in active server.

   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
     /WINDOW SERVER -sticky tag

   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)
     /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

  7. /LASTLOG and jumping around in scrollback

   /LASTLOG command can be used for searching texts in scrollback buffer.
   Simplest usages are
     /LASTLOG word     - print all lines with "word" in them
     /LASTLOG word 10  - print last 10 occurances of "word"
     /LASTLOG -topics  - print all topic changes

   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
     /LASTLOG -file ~/irc.log

   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.

   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.

  8. Logging

   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:
     /SET awaylog_level MSGS HILIGHT     - Specifies what messages to log
     /SET awaylog_file ~/.irssi/away.log - Specifies the file to use

   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
     /SET autolog ON

   By default it logs pretty much everything execept CTCPS or CRAP
   (/WHOIS requests, etc). You can specify the logging level yourself
   with
     /SET autolog_level ALL -CRAP -CLIENTCRAP -CTCPS (this is the default)

   By default irssi logs to ~/irclogs/<servertag>/<target>.log. You can
   change this with
     /SET autolog_path ~/irclogs/$tag/$0.log (this is the default)

   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
     /SET autolog_path ~/irclogs/%Y/$tag/$0.%m-%d.log

   For logging only some specific channels or nicks, see /HELP log

  9. Proxies and IRC bouncers

   Irssi supports connecting to IRC servers via a proxy. All proxies have
   these settings in common:
     /SET use_proxy ON
     /SET proxy_address <Proxy host address>
     /SET proxy_port <Proxy port>

   HTTP proxy

   Use these settings with HTTP proxies:
     /SET -clear proxy_password
     /EVAL SET proxy_string CONNECT %s:%d\n\n

   Irssi proxy

   Irssi contains it's own proxy which you can build giving --with-proxy
   option to configure. You'll still need to run irssi in a screen to use
   it though.

   Irssi proxy is a bit different than most proxies, normally proxies
   create a new connection to IRC server when you connect to it, but with
   irssi proxy all the clients use the same IRC server connection (a bit
   like how screen -x works).

   Irssi proxy supports sharing multiple server connections in different
   ports, like you can share ircnet in port 2777 and efnet in port 2778.

   Usage in proxy side:
     /LOAD irc_proxy (/LOAD proxy in irssi 0.7.98.3 and older)
     /SET irssiproxy_password <password>
     /SET irssiproxy_ports <ircnet>=<port> ... (eg. ircnet=2777 efnet=2778)

   NOTE: you MUST add all the servers you are using to server and ircnet
   lists with /SERVER ADD and /IRCNET ADD. ..Except if you really don't
   want to for some reason, and you only use one server connection, you
   may simply set:
     /SET irssiproxy_ports *=2777 (irssi 0.7.99 and later only)

   Usage in client side:

   Just connect to the irssi proxy like it is a normal server with
   password specified in /SET irssiproxy_password. For example:
     /SERVER ADD -ircnet ircnet my.irssi-proxy.org 2777 secret
     /SERVER ADD -ircnet efnet my.irssi-proxy.org 2778 secret

   Irssi proxy works fine with other IRC clients as well.

   SOCKS
   Irssi can be compiled with socks support (--with-socks option to
   configure), but I don't really know how it works, if at all. /SET
   proxy settings don't have anything to do with socks however.

   Others

   IRC bouncers usually work like IRC servers, and want a password. You
   can give it with:
     /SET proxy_password <password>

   Irssi's default for connect string is
     /SET proxy_string CONNECT %s %d

   which you can modify according to your bouncer's needs.

  10. Irssi's settings

   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):

   Queries

   /SET autocreate_own_query ON
          Should new query window be created when you send message to
          someone (with /msg).

   /SET autocreate_query_level MSGS
          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.

   /SET autoclose_query 0
          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.

   Windows

   /SET use_msgs_window OFF
          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).

   /SET use_status_window ON
          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).

   /SET autocreate_windows ON
          Should we create new windows for new window items or just place
          everything in one window

   /SET autoclose_windows ON
          Should window be automatically closed when the last item in
          them is removed (ie. /PART, /UNQUERY).

   /SET reuse_unused_windows OFF
          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.

   /SET window_auto_change OFF
          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.

   /SET print_active_channel OFF
          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.

   /SET window_history OFF
          Should command history be kept separate for each window.

   User information

   /SET nick
          Your nick name

   /SET alternate_nick
          Your alternate nick.

   /SET user_name
          Your username, if you have ident enabled this doesn't affect
          anything

   /SET real_name
          Your real name.

   Server information

   /SET skip_motd OFF
          Should we hide server's MOTD (Message Of The Day).

   /SET server_reconnect_time 300
          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.

   /SET lag_max_before_disconnect 300
          Maximum server lag in seconds before disconnecting and trying
          to reconnect. This happens mostly only when network breaks
          between you and IRC server.

   Appearance

   /SET timestamps ON
          Show timestamps before each message.

   /SET hide_text_style OFF
          Hide all bolds, underlines, MIRC colors, etc.

   /SET show_nickmode ON
          Show the nick's mode before nick in channels, ie. ops have
          <@nick>, voices <+nick> and others < nick>

   /SET show_nickmode_empty ON
          If the nick doesn't have a mode, use one space. ie. ON:
          < nick>, OFF: <nick>

   /SET show_quit_once OFF
          Show quit message only once in some of the channel windows the
          nick was in instead of in all windows.

   /SET topicbar ON
          Show the channel's topic in top of screen.

   /SET lag_min_show 100
          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).

   /SET indent 10
          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.

   /SET activity_hide_targets
          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.

   /SET mail_counter ON
          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.

   Nick completion

   /SET completion_auto OFF
          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 ;)

   /SET completion_char :
          Completion character to use.