1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289
|
<!doctype linuxdoc system>
<article>
<title>IRC Services
<author>Christophe Kalt
<date>$Id: SERVICE.sgml,v 1.9 2004/07/02 15:52:06 chopin Exp $
<abstract>
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.
</abstract>
<sect>A new type of connection
<p>
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.
<sect1>A bit client
<p>
services are similar to clients because they cannot:
<itemize>
<item> introduce other clients, services, or servers.
<item> change the global state of the net. (kill, squit..)
</itemize>
<sect1>A bit server
<p>
services are similar to servers because:
<itemize>
<item> they cannot join channels.
<item> they are not limited by flood control or penalty.
<item> they can see all users, servers, services.
<item> they can see all channel names.
<item> they cannot freely connect to a server.
<item> they may optionally receive a connection burst.
</itemize>
<sect1>Really unique
<p>
services are unique because:
<itemize>
<item> they are not subject to collisions.
<item> they can be local to one, or more servers, or global.
<item> they can only send notices, not private messages.
<item> they can only be contacted by the use of SQUERY.
</itemize>
<p>
Services are not meant to be used interactively, but provide
adequate support for automatons, statistic gathering,
monitoring.
<sect>What users see
<p>
This section covers the aspects visible to the users.
<sect1>&SERVICES
<p>
This is a special channel, similar to &SERVERS, on which
are sent notices when a service connects to or quit the net.
<sect1>SERVLIST
<p>
This new command gives the list of services currently
present on the IRC network. It can take two arguments.
<enum>
<item> a mask to limit the output to the services which
names matches the mask.
<item> a type to list only services of a specific type.
</enum>
It returns a list of servers using numeric 234, the
different fields are:
<itemize>
<item> The service name.
<item> The name of the server which introduced it on the
net.
<item> The <ref id="dist" name="distribution"> mask.
<item> The service <ref id="type" name="type">.
<item> The hop count between you and the service.
<item> A comment.
</itemize>
<sect1>SQUERY
<p>
This new command stands for ``Service Query''. The first
argument is the service name, and the second the text to be
sent to the service.
<sect>How to set up a service
<sect1>Compile time option for the server
<p>
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 ``<bf>USE_SERVICES</bf>'' defined in the
config.h file. To know if your server has been compiled
with this option, check the version:
<p>
351 Server irc.stealth.net: 2.9.3. AaCeEFiIkMu$_V1
<p>
351 Server irc.pvv.unit.no: 2.9.3. AaeEFHiKMp<bf>s</bf>tuYZ_V1
<p>
Here, only ``irc.pvv.unit.no'' was compiled with the
``USE_SERVICES'' defined as the lowercase ``s'' shows in the
version string.
<p>
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 lines
defines the name of the service, as well as the type.
<sect1>Glossary
<p>
Services have two main characteristics:
<descrip>
<label id="type">
<tag/Type/ 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:
<verb>
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 0x40000000 /* service wants to use TKLINE*/
</verb>
<label id="dist">
<tag/Distribution/ 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.
<p>
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.
<p>
Examples:
<descrip>
<tag/irc.funet.fi/Using a server name as distribution makes
the service local to the particular server.
<tag/*.fr/This would match any server in the toplevel ``fr''.
<tag/*/This is the distribution to be used to make the
service global.
</descrip>
<p>
It is important to note that the path between the service
and a server <bf>must</bf> be composed of servers which have
matching names:
<verb>
trondheim.irc.no <----> ircd.funet.fi <-----> oslo.irc.no
^ ^
| |
| +------> bergen.irc.no
|
+-------[MyService - Distribution *.no]
</verb>
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''.
<p>
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''.
</descrip>
<sect1>Signing on as a service
<p>
Once the S: line setup on the server, the service connects
by sending the password (PASS command), and then issuing a
``SERVICE'' command:
<p>
SERVICE servicename distribution servicetype :Information
<descrip>
<tag/servicename/ This is the name of the service as configured
by the S line.
<tag/distribution/ This is the distribution mask for this
connection.
<tag/servicetype/ This is the service type as configured by
the S line. (It must match)
<tag/Information/ This is any information. It will be sent
in ``SERVLIST'' replies and should be a short description of
the service.
</descrip>
<p>
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.
<sect1>Requesting data from the server
<p>
Once the connection is established, the service needs to
issue a ``SERVSET'' command to receive the data it wants:
<p>
SERVSET mask1 mask2
<descrip>
<tag/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.
<p>
This mask can also have the following bits set, regardless
of what the S line setting is:
<verb>
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 */
</verb>
<tag/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.
<tag/Note/The ``SERVSET'' command can only be issued once.
</descrip>
<sect>General notes for server and service administrators
<sect1>User privacy
<p>
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.
<p>
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). <bf>Administrators must remember that the privacy of
the users is at stake</bf>.
<sect1>Guidelines
<p>
To avoid confusion, it is a good idea to obey the following
simple rules:
<descrip>
<tag/Name/The name should be descriptive, and if possible
unique on the network.
<tag/Information/The service ``information'' should be short
and descriptive.
<tag/Mandatory queries/The service must reply to at least 2
queries:
<descrip>
<tag/ADMIN/Name and e-mail address of the administrator.
<tag/HELP/List of queries understood by the service. Each
query should also have an help.
</descrip>
<tag/Basic queries/These queries should also be understood
by the service:
<descrip>
<tag/INFO/This should be a short text explaining what the
service and its purpose are.
<tag/VERSION/The version of the running code.
</descrip>
</descrip>
<sect1>Flood control
<p>
Also, since services are not affected by flood control, they
can easily flood the IRC network with information. They
should be conceived so this does not happen.
<p>
Services should implement their own flood control (for
outgoing traffic) to be safe.
</article>
|