path: root/doc/SERVICE.txt

  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.