-
Notifications
You must be signed in to change notification settings - Fork 11
Services
The IRC protocol described in RFC 1459 defines two types of connections (client, and server). A third type was introduced with version 2.9 of the IRC software: service connections. This document describes what services are, and how to use them.
A service connection is something between a client and a server connection. It is not closer from any, as a matter of fact, the scope is pretty broad.
Services are similar to clients because they cannot:
-
introduce other clients, services, or servers.
-
change the global state of the net. (kill, squit..)
Services are similar to servers because:
-
they cannot join channels.
-
they are not limited by flood control or penalty.
-
they can see all users, servers, services.
-
they can see all channel names.
-
they cannot freely connect to a server.
-
they may optionally receive a connection burst.
Services are unique because:
-
they are not subject to collisions.
-
they can be local to one, or more servers, or global.
-
they can only send notices, not private messages.
-
they can only be contacted by the use of SQUERY.
Services are not meant to be used interactively, but provide adequate support for automatons, statistic gathering, monitoring.
This section covers the aspects visible to the users.
This is a special channel, similar to &SERVERS, on which are sent notices when a service connects to or quit the net.
This new command gives the list of services currently present on the IRC network. It can take two arguments.
-
a mask to limit the output to the services which names matches the mask.
-
a type to list only services of a specific type.
It returns a list of servers using numeric 234, the different fields are:
-
The service name.
-
The name of the server which introduced it on the net.
-
The
distributionmask. -
The service
type. -
The hop count between you and the service.
-
A comment.
First of all, it is important to note that in order to be able to connect a service to a server, this server must have been compiled with
USE_SERVICES defined in the config.h file. To know if your server has been compiled with this option, check the version:
351 Server irc.stealth.net: 2.9.3. AaCeEFiIkMu$_V1
351 Server irc.pvv.unit.no: 2.9.3. AaeEFHiKMpsstuYZ_V1
Here, only irc.pvv.unit.no was compiled with the USE_SERVICES defined as the lowercase s shows in the version string.
As they are special clients, services need to be allowed access to the server in the configuration file. Each service needs its own access to be setup. This is gone by adding an S: line to the configuration file. This line defines the name of the service, as well as the type.
Services have two main characteristics:
This is a misleading name. The type is actually a bit mask which defines what information the service can see. (With introduction of SERVICE_WANT_TKLINE it is even more misleading, as this does not define information, but rather access control.) The server configuration file limits the type allowed for a service. The meaning of the bits is defined in the service_def.h file coming with the IRC software:
SERVICE_WANT_SERVICE 0x00000001 /* other services signing on/off */ SERVICE_WANT_OPER 0x00000002 /* operators, included in umodes too */ SERVICE_WANT_UMODE 0x00000004 /* user modes, iow + local modes */ SERVICE_WANT_AWAY 0x00000008 /* away isn't propaged anymore.. */ SERVICE_WANT_KILL 0x00000010 /* KILLs */ SERVICE_WANT_NICK 0x00000020 /* all NICKs (new user, change) */ SERVICE_WANT_USER 0x00000040 /* USER signing on */ SERVICE_WANT_QUIT 0x00000080 /* all QUITs (users signing off) */ SERVICE_WANT_SERVER 0x00000100 /* servers signing on */ SERVICE_WANT_WALLOP 0x00000200 /* wallops */ SERVICE_WANT_SQUIT 0x00000400 /* servers signing off */ SERVICE_WANT_RQUIT 0x00000800 /* regular user QUITs (these which are also sent between servers) */ SERVICE_WANT_MODE 0x00001000 /* channel modes (not +ov) */ SERVICE_WANT_CHANNEL 0x00002000 /* channel creations/destructions */ SERVICE_WANT_VCHANNEL 0x00004000 /* channel joins/parts */ SERVICE_WANT_TOPIC 0x00008000 /* channel topics */
SERVICE_WANT_ERRORS 0x01000000 /* &ERRORS */ SERVICE_WANT_NOTICES 0x02000000 /* &NOTICES */ SERVICE_WANT_LOCAL 0x04000000 /* &LOCAL */ SERVICE_WANT_NUMERICS 0x08000000 /* &NUMERICS */
SERVICE_WANT_USERLOG 0x10000000 /* FNAME_USERLOG */ SERVICE_WANT_CONNLOG 0x20000000 /* FNAME_CONNLOG */
SERVICE_WANT_TKLINE 0x00100000 /* service wants to use TKLINE*/ SERVICE_WANT_KLINE 0x00200000 /* service wants to use KLINE*/
This controls the propagation of the service. The distribution is checked against server names, the service will only be on servers which names matches the distribution.
It also eventually limits the information received by the service (depending on the service type). A service will not have any information concerning users or services connected to a server which name does not match the distribution.
Examples:
irc.funet.fi Using a server name as distribution makes the service local to the particular server.
*.fr This would match any server in the toplevel `fr`.
* This is the distribution to be used to make the service global.
It is important to note that the path between the service and a server must be composed of servers which have matching names:
trondheim.irc.no <----> ircd.funet.fi <-----> oslo.irc.no
^ ^
| |
| +------> bergen.irc.no
|
+-------[MyService - Distribution *.no]
As shown above, if two `*.no` servers have a non `*.no` (for example here a `*.fi`) server connected between them, in this case the information related to `MyService` will not propagate to `oslo.irc.no`.
This means that the service will see information concerning the 3 *.no servers, but oslo.irc.no will have no knowledge of the
presence of MyService. Also, the service is unable to send anything thru ircd.funet.fi.
Once the S: line setup on the server, the service connects by sending the password (PASS command), and then issuing a SERVICE command:
SERVICE servicename distribution servicetype :Information
servicename This is the name of the service as configured by the S line.
distribution This is the distribution mask for this connection.
servicetype This is the service type as configured by the S line. (It must match)
Information This is any information. It will be sent in `SERVLIST` replies and should be a short description of the service.
A successfull registering of a service at the server will result in a RPL_YOURESERVICE (383) being sent back to the service. Any other reply as a result of sending service indicates an error has occured.
Once the connection is established, the service needs to issue a`SERVSET` command to receive the data it wants:
SERVSET mask1 mask2
mask1 It is a subset of the service type. It defines what the kind of information the service wants to receive for this particular connection.
This mask can also have the following bits set, regardless of what the S line setting is:
SERVICE_WANT_PREFIX 0x10000 /* to receive n!u@h instead of n */ SERVICE_WANT_TOKEN 0x20000 /* use server token instead of name */ SERVICE_WANT_EXTNICK 0x40000 /* user extended NICK syntax */ SERVICE_WANT_UID 0x80000 /* user extended UID syntax */
mask2 It is optional. It is a subset of mask1 that defines which information the service wants to receive in a `connection burst`. The information is similar to a server `connection burst`, it describe the current set of the network. The service can therefore store the information in memory and update it.
Note The `SERVSET` command can only be issued once.
Services can see almost as much information as a server. This means that granting a service connection should be considered with as much care as granting a server connection. In particular, the service type should be limited to the strict minimum needed for the service to be operational. In most cases, a service type of 0 is enough.
A great care should be taken to make sure that a service cannot be (ab)used to obtain information not normally accessible to users (such as showing invisible users). Administrators must remember that the privacy of the users is at stake.
To avoid confusion, it is a good idea to obey the following simple rules:
Name The name should be descriptive, and if possible unique on the network.
Information The service `information` should be short and descriptive.
Mandatory queries The service must reply to at least 2 queries:
ADMIN Name and e-mail address of the administrator.
HELP List of queries understood by the service. Each query should also have an help.
Basic queries These queries should also be understood by the service:
INFO This should be a short text explaining what the service and its purpose are.
VERSION The version of the running code.