doc/api/gline.txt

   1 Some users can be very annoying, as any IRC operator can attest.  Some
   2 can in fact be downright abusive.  Sometimes the best way of dealing
   3 with these users is to ban them from the entire network.  The G-line
   4 system permits this.
   5
   6 G-lines are fairly complicated.  A G-line can be active or inactive,
   7 either locally or globally.  It can be a purely local G-line, or
   8 global.  It could be based on IP address or on host name.  In short,
   9 there are many variations on the basic G-line.  Worse, there is also
  10 the concept of a "bad channel," or BADCHAN, that has been tacked onto
  11 the G-line subsystem, when it should have been a separate command in
  12 the first place.
  13
  14 Different types of G-lines are differentiated from each other through
  15 the use of various flags.  Some of these flags are maintained solely
  16 by the G-line subsystem, where as others are passed to various
  17 functions in the API.
  18
  19 <macro>
  20 #define GLINE_MAX_EXPIRE 604800 /* max expire: 7 days */
  21
  22 This macro lists the maximum expire time a G-line is permitted to
  23 have.  This value is limited to 7 days to prevent abuse of the system.
  24 </macro>
  25
  26 <macro>
  27 #define GLINE_ACTIVE    0x0001
  28
  29 This flag is used to indicate that a given G-line is globally active.
  30 </macro>
  31
  32 <macro>
  33 #define GLINE_IPMASK    0x0002
  34
  35 This flag is used to indicate that a given G-line is an IP mask.  This
  36 flag is maintained internally by the G-line subsystem.
  37 </macro>
  38
  39 <macro>
  40 #define GLINE_BADCHAN   0x0004
  41
  42 This flag is used to indicate that a given G-line specifies a BADCHAN,
  43 a channel that users are not permitted to join.  This flag is
  44 maintained internally, but is also used in gline_find() to search for
  45 a BADCHAN for a particular channel.
  46 </macro>
  47
  48 <macro>
  49 #define GLINE_LOCAL     0x0008
  50
  51 This flag is used to indicate that a given G-line is a local G-line.
  52 Local G-lines do not affect users on other servers.
  53 </macro>
  54
  55 <macro>
  56 #define GLINE_ANY       0x0010
  57
  58 This flag is passed to gline_find() to signal that function to return
  59 any G-line or BADCHAN that matches the passed mask string.  It is
  60 never set on a real G-line.
  61 </macro>
  62
  63 <macro>
  64 #define GLINE_FORCE     0x0020
  65
  66 This flag is passed to gline_add() to force the server to accept an
  67 expire time that might be out of bounds.  It is never set on a real
  68 G-line.
  69 </macro>
  70
  71 <macro>
  72 #define GLINE_EXACT     0x0040
  73
  74 This flag is passed to gline_find() to signal that function to return
  75 only G-lines that exactly match the passed mask string.  That is, the
  76 ircd_strcmp() function is called to compare the G-line to the mask,
  77 rather than the match() function.  This flag is never set on a real
  78 G-line.
  79 </macro>
  80
  81 <macro>
  82 #define GLINE_LDEACT    0x0080  /* locally deactivated */
  83
  84 This flag is set on global G-lines that have been locally
  85 deactivated.  This flag is maintained internally by the G-line
  86 subsystem.
  87 </macro>
  88
  89 <macro>
  90 #define GLINE_GLOBAL    0x0100  /* find only global glines */
  91
  92 This flag is passed to gline_find() or gline_lookup() to specify that
  93 the caller is only interested in global G-lines.  This flag is never
  94 set on a real G-line.
  95 </macro>
  96
  97 <macro>
  98 #define GLINE_LASTMOD   0x0200  /* find only glines with non-zero lastmod */
  99
 100 This flag is passed to gline_find() or gline_lookup() to specify that
 101 the caller is only interested in G-lines with a non-zero lastmod time,
 102 that is, G-lines that were not set by a U-lined service.  This flag is
 103 never set on a real G-line.
 104 </macro>
 105
 106 <struct>
 107 struct Gline;
 108
 109 The struct Gline describes everything about a given G-line.  None of
 110 its fields may be directly accessed by the application; use the
 111 functions and macros described below instead.
 112 </struct>
 113
 114 <function>
 115 int GlineIsActive(struct Gline* g);
 116
 117 This macro returns a non-zero value if the G-line is active, or 0
 118 otherwise.  If a G-line is locally deactivated, this macro will always
 119 return 0.
 120 </function>
 121
 122 <function>
 123 int GlineIsRemActive(struct Gline* g);
 124
 125 This macro returns a non-zero value if the G-line is active, ignoring
 126 whether or not it is locally deactivated.
 127 </function>
 128
 129 <function>
 130 int GlineIsIpMask(struct Gline* g);
 131
 132 This macro returns a non-zero value if the G-line is an IP mask.
 133 </function>
 134
 135 <function>
 136 int GlineIsBadChan(struct Gline* g);
 137
 138 This macro returns a non-zero value if a G-line actually represents a
 139 BADCHAN.
 140 </function>
 141
 142 <function>
 143 int GlineIsLocal(struct Gline* g);
 144
 145 This macro returns a non-zero value if a G-line is local only.
 146 </function>
 147
 148 <function>
 149 char* GlineUser(struct Gline* g);
 150
 151 This macro returns the user name associated with the G-line.  If the
 152 G-line represents a BADCHAN, this will contain the channel name.
 153 </function>
 154
 155 <function>
 156 char* GlineHost(struct Gline* g);
 157
 158 This macro returns the host name associated with the G-line.  If the
 159 G-line represents a BADCHAN, this will be a NULL pointer.
 160 </function>
 161
 162 <function>
 163 char* GlineReason(struct Gline* g);
 164
 165 This macro returns the reason that was given when the G-line was set.
 166 </function>
 167
 168 <function>
 169 time_t GlineLastMod(struct Gline* g);
 170
 171 G-lines that were not set by a U-lined service have a modification
 172 time that must be monotonically increasing.  This macro simply returns
 173 that modification time.
 174 </function>
 175
 176 <function>
 177 int gline_propagate(struct Client *cptr, struct Client *sptr,
 178                     struct Gline *gline);
 179
 180 When a global G-line is set or modified, all other servers must be
 181 notified of the new G-line.  This function takes care of propagating
 182 the G-line specified by _gline_, originated by the client _sptr_, to
 183 all servers except _cptr_ (which may be a NULL pointer).
 184 </function>
 185
 186 <function>
 187 int gline_add(struct Client *cptr, struct Client *sptr, char *userhost,
 188               char *reason, time_t expire, time_t lastmod, unsigned int flags);
 189
 190 This function simply adds a G-line, set by _sptr_ and with a
 191 _userhost_, _reason_, _expire_, and _lastmod_ as specified.  The
 192 _flags_ parameter is a bit mask consisting of the binary OR of
 193 GLINE_FORCE, GLINE_LOCAL, or GLINE_ACTIVE, as appropriate.  The
 194 gline_add() function also calls gline_propagate() to propagate the
 195 G-line, and kills off any local users matching the G-line if it is
 196 active.
 197 </function>
 198
 199 <function>
 200 int gline_activate(struct Client *cptr, struct Client *sptr,
 201                    struct Gline *gline, time_t lastmod, unsigned int flags);
 202
 203 This function activates the G-line specified by _gline_, setting its
 204 _lastmod_ time as specified.  If _flags_ is GLINE_LOCAL and if the
 205 G-line is locally deactivated, this function will turn off the local
 206 deactivation flag, but will not modify _lastmod_.  If the G-line is
 207 globally deactivated, passing this function the GLINE_LOCAL flag will
 208 have no effect.
 209 </function>
 210
 211 <function>
 212 int gline_deactivate(struct Client *cptr, struct Client *sptr,
 213                      struct Gline *gline, time_t lastmod, unsigned int flags);
 214
 215 This function is similar to gline_activate() except that it
 216 deactivates the G-line.  If the given G-line is local, or if it was
 217 set by a U-lined service (and GLINE_LOCAL was not passed via _flags_),
 218 then the G-line is deleted from memory.  In all other cases, the
 219 G-line is simply deactivated, either locally (if GLINE_LOCAL was
 220 passed via _flags_) or globally.  Global deactivation will update the
 221 _lastmod_ time.
 222 </function>
 223
 224 <function>
 225 struct Gline *gline_find(char *userhost, unsigned int flags);
 226
 227 This function looks up a G-line matching the given _userhost_ value,
 228 under control of the _flags_ parameter.  Valid _flags_ that may be
 229 passed are: GLINE_BADCHAN, GLINE_ANY, GLINE_GLOBAL, GLINE_LASTMOD, or
 230 GLINE_EXACT, each described above.
 231 </function>
 232
 233 <function>
 234 struct Gline *gline_lookup(struct Client *cptr, unsigned int flags);
 235
 236 This function looks up a G-line matching the given client, specified
 237 by _cptr_, under the control of the _flags_.  Valid values for _flags_
 238 are GLINE_GLOBAL and GLINE_LASTMOD, as described above.
 239 </function>
 240
 241 <function>
 242 void gline_free(struct Gline *gline);
 243
 244 This function releases all storage associated with a given G-line.
 245 </function>
 246
 247 <function>
 248 void gline_burst(struct Client *cptr);
 249
 250 This function generates a burst of all existing global G-lines and
 251 BADCHANs and sends them to the server specified by _cptr_.
 252 </function>
 253
 254 <function>
 255 int gline_resend(struct Client *cptr, struct Gline *gline);
 256
 257 This function resends the _gline_ to a server specified by _cptr_.
 258 This may be used if, for instance, it is discovered that a server is
 259 not synchronized with respect to a particular G-line.
 260 </function>
 261
 262 <function>
 263 int gline_list(struct Client *sptr, char *userhost);
 264
 265 This function sends the information about a G-line matching _userhost_
 266 to the client specified by _sptr_.  If _userhost_ is a NULL pointer, a
 267 list of all G-lines is sent.
 268 </function>
 269
 270 <function>
 271 void gline_stats(struct Client *sptr);
 272
 273 This function generates a list of all G-lines, sending them to the
 274 user _sptr_ by a /STATS G response.
 275 </function>
 276
 277 <authors>
 278 Kev <klmitch@mit.edu>
 279 </authors>
 280
 281 <changelog>
 282 [2001-6-15 Kev] Initial documentation for the G-line API.
 283 </changelog>