[doldaconnect.git] / doc / server-address

		      Server address resolution

The libdcui library implements  a rather flexible scheme for resolving
the adress of the server to connect to. In order for you to be able to
create  the  setup  you  would  like best,  this  file  documents  the
scheme.  It is  worth noting  that it  is implemented  in  the library
itself,  and so  is  automatically  shared by  any  program using  it,
including  (but not  limited  to) dolcon,  autodl,  hubmgr, the  panel
applet, Pidgin plugin and others.

The server address  is specified as a single string.  If no server has
been  explicity specified,  the library  first checks  the environment
variable DCSERVER, and uses its value  if set. If it is unset as well,
the library attempts the following connections, in order:

 * The Unix socket /tmp/doldacond-$USERNAME
 * The Unix socket /var/run/doldacond.sock
 * TCP port 1500 on localhost
 * If compiled with DNS support and getdomainname(2) does not return
   `(none)' or nothing, the address indicated by the _dolcon._tcp SRV
   record on that domain, if one exists.

If a  server is  specified, either explicity  or through  the DCSERVER
environment variable, it is resolved as follows:

 * If the address contains a slash character, it is assumed to be the
   name of a Unix socket.
 * If the address does not contain a colon, and the library has been
   compiled with DNS support, and the address specifies a domain name
   with a _dolcon._tcp SRV record, the address of that SRV record is
   used.
 * If the address matches the regexp `^\[(.*)\]:([0-9]+)$', the string
   in the first subgroup is resolved by the system's getaddrinfo(3),
   and the port set to the second subgroup, and the result is
   connected to. This is mostly intended for connecting to literal
   IPv6 addresses.
 * If none of the above rules have been matched, the address
   specification is resolved using the system's getaddrinfo(3)
   implementation, and connected to. A port number can be specified by
   appending a colon and the port number to the address specification,
   such as in `localhost:1500'.
 * If none of the above rules are successful, the connection fails.


This document  was last updated 2008-02-14, reflecting  release 1.1 of
Dolda Connect.
Commit	Line	Data
d9476001 FT	1	Server address resolution
	2
	3	The libdcui library implements a rather flexible scheme for resolving
	4	the adress of the server to connect to. In order for you to be able to
	5	create the setup you would like best, this file documents the
	6	scheme. It is worth noting that it is implemented in the library
	7	itself, and so is automatically shared by any program using it,
	8	including (but not limited to) dolcon, autodl, hubmgr, the panel
	9	applet, Pidgin plugin and others.
	10
	11	The server address is specified as a single string. If no server has
	12	been explicity specified, the library first checks the environment
	13	variable DCSERVER, and uses its value if set. If it is unset as well,
	14	the library attempts the following connections, in order:
	15
	16	* The Unix socket /tmp/doldacond-$USERNAME
	17	* The Unix socket /var/run/doldacond.sock
	18	* TCP port 1500 on localhost
	19	* If compiled with DNS support and getdomainname(2) does not return
	20	`(none)' or nothing, the address indicated by the _dolcon._tcp SRV
	21	record on that domain, if one exists.
	22
	23	If a server is specified, either explicity or through the DCSERVER
	24	environment variable, it is resolved as follows:
	25
	26	* If the address contains a slash character, it is assumed to be the
	27	name of a Unix socket.
	28	* If the address does not contain a colon, and the library has been
	29	compiled with DNS support, and the address specifies a domain name
	30	with a _dolcon._tcp SRV record, the address of that SRV record is
	31	used.
	32	* If the address matches the regexp `^\[(.*)\]:([0-9]+)$', the string
	33	in the first subgroup is resolved by the system's getaddrinfo(3),
	34	and the port set to the second subgroup, and the result is
	35	connected to. This is mostly intended for connecting to literal
	36	IPv6 addresses.
	37	* If none of the above rules have been matched, the address
	38	specification is resolved using the system's getaddrinfo(3)
	39	implementation, and connected to. A port number can be specified by
	40	appending a colon and the port number to the address specification,
	41	such as in `localhost:1500'.
	42	* If none of the above rules are successful, the connection fails.
	43
	44
	45
	46	This document was last updated 2008-02-14, reflecting release 1.1 of
	47	Dolda Connect.