diff options
Diffstat (limited to 'doc/SERVICE.txt')
| -rw-r--r-- | doc/SERVICE.txt | 330 |
1 files changed, 330 insertions, 0 deletions
diff --git a/doc/SERVICE.txt b/doc/SERVICE.txt new file mode 100644 index 0000000..fa07c3a --- /dev/null +++ b/doc/SERVICE.txt @@ -0,0 +1,330 @@ + IRC Services + Christophe Kalt + $Id: SERVICE.txt,v 1.7 1999/04/15 21:56:53 kalt Exp $ + + The IRC protocol described in RFC 1459 defines two types of connec- + tions (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. + + 11.. AA nneeww ttyyppee ooff ccoonnnneeccttiioonn + + 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. + + 11..11.. AA bbiitt cclliieenntt + + services are similar to clients because they cannot: + + +o introduce other clients, services, or servers. + + +o change the global state of the net. (kill, squit..) + + 11..22.. AA bbiitt sseerrvveerr + + services are similar to servers because: + + +o they cannot join channels. + + +o they are not limited by flood control or penalty. + + +o they can see all users, servers, services. + + +o they can see all channel names. + + +o they cannot freely connect to a server. + + +o they may optionally receive a connection burst. + + 11..33.. RReeaallllyy uunniiqquuee + + services are unique because: + + +o they are not subject to collisions. + + +o they can be local to one, or more servers, or global. + + +o they can only send notices, not private messages. + + +o 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. + + + 22.. WWhhaatt uusseerrss sseeee + + This section covers the aspects visible to the users. + + 22..11.. &&SSEERRVVIICCEESS + + This is a special channel, similar to &SERVERS, on which are sent + notices when a service connects to or quit the net. + + + + 22..22.. SSEERRVVLLIISSTT + + This new command gives the list of services currently present on the + IRC network. It can take two arguments. + + 1. a mask to limit the output to the services which names matches the + mask. + + 2. a type to list only services of a specific type. + + It returns a list of servers using numeric 234, the different + fields are: + + +o The service name. + + +o The name of the server which introduced it on the net. + + +o The ``distribution'' mask. + + +o The service ``type''. + + +o The hop count between you and the service. + + +o A comment. + + 22..33.. SSQQUUEERRYY + + 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. + + + 33.. HHooww ttoo sseett uupp aa sseerrvviiccee + + 33..11.. CCoommppiillee ttiimmee ooppttiioonn ffoorr tthhee sseerrvveerr + + 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 ``UUSSEE__SSEERRVVIICCEESS'' 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 lines defines the name of the service, as well as the + type. + + 33..22.. GGlloossssaarryy + + Services have two main characteristics: + + + TTyyppee + This is a misleading name. The type is actually a bit mask + which defines what information the service can see. The server + configuration file limits the type allowed for a service. The + meaning of the bits is defined in the service.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 */ + + + + DDiissttrriibbuuttiioonn + 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: + + iirrcc..ffuunneett..ffii + Using a server name as distribution makes the service local + to the particular server. + + **..ffrr + 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 mmuusstt 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''. + + 33..33.. SSiiggnniinngg oonn aass aa sseerrvviiccee + + 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 servername distribution servicetype 0 :Information + + sseerrvviicceennaammee + This is the name of the service as configured by the S line. + + sseerrvveerrnnaammee + This is ignored by the server. + + ddiissttrriibbuuttiioonn + This is the distribution mask for this connection. + + sseerrvviicceettyyppee + This is the service type as configured by the S line. (It must + match) + + IInnffoorrmmaattiioonn + 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. + + 33..44.. RReeqquueessttiinngg ddaattaa ffrroomm tthhee sseerrvveerr + + Once the connection is established, the service needs to issue a + ``SERVSET'' command to receive the data it wants: + + SERVSET mask1 mask2 + + mmaasskk11 + 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 */ + + + + mmaasskk22 + 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. + + NNoottee + The ``SERVSET'' command can only be issued once. + + + 44.. GGeenneerraall nnootteess ffoorr sseerrvveerr aanndd sseerrvviiccee aaddmmiinniissttrraattoorrss + + 44..11.. UUsseerr pprriivvaaccyy + + 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). AAddmmiinniissttrraattoorrss mmuusstt rreemmeemmbbeerr tthhaatt tthhee + pprriivvaaccyy ooff tthhee uusseerrss iiss aatt ssttaakkee. + + 44..22.. GGuuiiddeelliinneess + + To avoid confusion, it is a good idea to obey the following simple + rules: + + NNaammee + The name should be descriptive, and if possible unique on the + network. + + IInnffoorrmmaattiioonn + The service ``information'' should be short and descriptive. + + MMaannddaattoorryy qquueerriieess + The service must reply to at least 2 queries: + + AADDMMIINN + Name and e-mail address of the administrator. + + HHEELLPP + List of queries understood by the service. Each query should + also have an help. + + BBaassiicc qquueerriieess + These queries should also be understood by the service: + + IINNFFOO + This should be a short text explaining what the service and + its purpose are. + + VVEERRSSIIOONN + The version of the running code. + + 44..33.. FFlloooodd ccoonnttrrooll + + 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. + + Services should implement their own flood control (for outgoing + traffic) to be safe. + + + + + + + + + + + |