Table of Contents

# $EPIC: server_description.txt,v 1.4 2006/11/23 17:07:48 jnelson Exp $

Special Topic:

A server description is the way you give the client enough information about an irc server for it to be added to the server list and used.

Any place you are supposed to provide a “server”, you can provide either a server refnum, or the server description.

About server descriptions:

A server description is a colon-separated list of several data items that changes from time to time.

hostname The hostname or p-addr of the server
port The port the server is running on (default: 6667)
password The irc PASSword (if necessary) to log on with (default: none)
nickname The irc NICKname to log on with (default: global nickname)
group The server group this belongs to (default: no group)
type The protocol type to use, either IRC or IRC-SSL (default: IRC)
protocol The socket protocol to use, either “tcp4” or “tcp6” or “any”
vhost The local address (virtual host) to use for the connection

Only the hostname field is mandatory. If you want to use the default value in a field, you can leave it blank.

Because the server description is colon separated, IPv6 p-addrs have to be surrounded in square brackets such as [fe::00].

Server descriptions and skipping fields:

It can be confusing to keep track of which field you want to set, especially when you want to skip some of the middle fields. Each field has a name, which you can see in the above table. You can switch around to any field at any time by “assigning” to a field name:

irc.foobar.com:7002:type=IRC-SSL

and you can abbreviate a field name as long as it's not ambiguous:

irc.foobar.com:pr=tcp6

If you skip fields by doing an assignment, any following (unassigned) fields are in the same natural order as in the above table:

irc.foobar.com:group=efnet:IRC-SSL

(since 'type' follows 'group', the field after the 'group=' is 'type'.)

You don't have to skip fields in order, you can skip around and specify them however you want. If you happen to specify a field multiple times, the last one is the one that will be used.

About server refnums and the server list:

Any time you present a new server description to the client, it is added to the server list and is assigned a unique reference number. This is also called a “servref” or “refnum”. A server refnum is an internal number which is used to map windows, channels, timers, and other things to the appropriate server.

The hostname and port fields create the primary key for the server list. Two servers that have the same hostname and port are considered to be the same server.

Examples:

A server on irc.foobar.com, port 6667, where you use the nickname “JoeBob”:

    irc.foobar.com:::JoeBob

A server on irc.foo.com, port 6666, using nickname “blah”

    /server -add irc.foo.com:6666::blah

A server on irc.foo.com, port 8000, that uses SSL

   /server irc.foobar.com:8000::::IRC-SSL