doc/api/jupe.txt

   1 Occasionally, a server will become incorrectly configured or will
   2 start behaving incorrectly.  Even more rarely, a server will be
   3 compromised, and a modified version of the server put in place to
   4 cause problems.  These cases are the reason for the _jupe_, a
   5 temporary server ban.  This is similar to the G-line, which is a
   6 temporary user ban, and indeed, the jupe API is very similar to the
   7 G-line API.
   8
   9 <macro>
  10 #define JUPE_MAX_EXPIRE 604800  /* max expire: 7 days */
  11
  12 This macro lists the maximum expire time a jupe is permitted to have.
  13 This value is limited to 7 days to prevent abuse of the system.
  14 </macro>
  15
  16 <macro>
  17 #define JUPE_ACTIVE     0x0001
  18
  19 This flag is used to indicate that a given jupe is globally active.
  20 </macro>
  21
  22 <macro>
  23 #define JUPE_LOCAL      0x0002
  24
  25 This flag is used to indicate that a given jupe is a local one.  Local
  26 jupes do not affect users on other servers.
  27 </macro>
  28
  29 <macro>
  30 #define JUPE_LDEACT     0x0004  /* locally deactivated */
  31
  32 This flag is set on global jupes that have been locally deactivated.
  33 This flag is maintained internally by the jupe subsystem.
  34 </macro>
  35
  36 <struct>
  37 struct Jupe;
  38
  39 The struct Jupe describes everything about a given jupe.  None of its
  40 fields may be directly accessed by the application; use the functions
  41 and macros described below instead.
  42 </struct>
  43
  44 <function>
  45 int JupeIsActive(struct Jupe* j);
  46
  47 This macro returns a non-zero value if the jupe is active, or 0
  48 otherwise.  If a jupe is locally deactivated, this macro will always
  49 return 0.
  50 </function>
  51
  52 <function>
  53 int JupeIsRemActive(struct Jupe* j);
  54
  55 This macro returns a non-zero value if the jupe is active, ignoring
  56 whether or not it is locally deactivated.
  57 </function>
  58
  59 <function>
  60 int JupeIsLocal(struct Jupe* j);
  61
  62 This macro returns a non-zero value if the jupe is local only.
  63 </function>
  64
  65 <function>
  66 char* JupeServer(struct Jupe* j);
  67
  68 This macro returns the server name associated with the jupe.
  69 </function>
  70
  71 <function>
  72 char* JupeReason(struct Jupe* j);
  73
  74 This macro returns the reason that was given when the jupe was set.
  75 </function>
  76
  77 <function>
  78 time_t JupeLastMod(struct Jupe* j);
  79
  80 Jupes have a modification time that must be monotonically increasing.
  81 This macro simply returns that modification time.
  82 </function>
  83
  84 <function>
  85 int jupe_add(struct Client *cptr, struct Client *sptr, char *server,
  86              char *reason, time_t expire, time_t lastmod, unsigned int flags);
  87
  88 This function simply adds a jupe, set by _sptr_ and with a _server_,
  89 _reason_, _expire_, and _lastmod_ as specified.  The _flags_ parameter
  90 is a bit mask consisting of the binary OR of JUPE_LOCAL and
  91 JUPE_ACTIVE, as appropriate.  The jupe_add() function will propagate
  92 the jupe to all servers (assuming JUPE_LOCAL was not passed), and will
  93 break its link to the server specified by _server_ (assuming that the
  94 JUPE_ACTIVE flag _was_ passed).
  95 </function>
  96
  97 <function>
  98 int jupe_activate(struct Client *cptr, struct Client *sptr, struct Jupe *jupe,
  99                   time_t lastmod, unsigned int flags);
 100
 101 This function activates the jupe specified by _jupe_, setting its
 102 _lastmod_ time as specified.  If _flags_ is JUPE_LOCAL and if the jupe
 103 is locally deactivated, this function will turn off the local
 104 deactivation flag, but will not modify _lastmod_.  If the jupe is
 105 globally deactivated, passing this function the JUPE_LOCAL flag will
 106 have no effect.
 107 </function>
 108
 109 <function>
 110 int jupe_deactivate(struct Client *cptr, struct Client *sptr,
 111                     struct Jupe *jupe, time_t lastmod, unsigned int flags);
 112
 113 This function is similar to jupe_activate() except that it deactivates
 114 the jupe.  If the given jupe is local, then the jupe is deleted from
 115 memory.  In all other cases, the jupe is simply deactivated, either
 116 locally (if JUPE_LOCAL was passed via _flags_) or globally.  Global
 117 deactivation will update the _lastmod_ time.
 118 </function>
 119
 120 <function>
 121 struct Jupe* jupe_find(char *server);
 122
 123 This function searches for a jupe matching the given _server_.
 124 </function>
 125
 126 <function>
 127 void jupe_free(struct Jupe *jupe);
 128
 129 This function releases all storage associated with a given jupe.
 130 </function>
 131
 132 <function>
 133 void jupe_burst(struct Client *cptr);
 134
 135 This function generates a burst of all existing global jupes and sends
 136 them to the server specified by _cptr_.
 137 </function>
 138
 139 <function>
 140 int jupe_resend(struct Client *cptr, struct Jupe *jupe);
 141
 142 This function resends the _jupe_ to a server specified by _cptr_.
 143 This may be used if, for instance, it is discovered that a server is
 144 not synchronized with respect to a particular jupe.
 145 </function>
 146
 147 <function>
 148 int jupe_list(struct Client *sptr, char *server);
 149
 150 This function sends the information about a jupe matching _server_ to
 151 the client specified by _sptr_.  If _server_ is a NULL pointer, a list
 152 of all jupes is sent.
 153 </function>
 154
 155 <authors>
 156 Kev <klmitch@mit.edu>
 157 </authors>
 158
 159 <changelog>
 160 [2001-6-15 Kev] Initial documentation of the jupe API.
 161 </changelog>