# $EPIC: server_description.txt,v 1.4 2006/11/23 17:07:48 jnelson Exp $
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.
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].
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.
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.
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