doc/readme.gline

   1 GLINE documentation, last updated on 17 Mar 2007
   2
   3 For an ordinary user, the syntax is:
   4
   5   GLINE [<mask>]
   6
   7 If <mask> is given, and if a G-line for that server exists, all the
   8 information about that G-line is displayed.  If <mask> is not given,
   9 an error is returned.
  10
  11 For an operator, the syntax is:
  12
  13   GLINE [[!][+|-|>|<]<mask> [<target>] [<expiration> [:<reason>]]]
  14
  15 There are a total of 10 basic forms of the GLINE command.  If no
  16 arguments are given, all existing G-lines will be listed; if only
  17 <mask> is given, the behavior is the same as for an ordinary user.
  18 The remaining forms allow G-lines to be set, manipulated, or possibly
  19 destroyed.
  20
  21 * Local G-lines.
  22
  23 Opers may set or remove G-lines that only apply to a specific server.
  24 When the <target> parameter is not given, the specific server will be
  25 the local server; otherwise, it will be taken to be a remote server,
  26 and the G-line operations will take place there, if the oper has the
  27 GLINE privilege.  When <mask> is preceded with the '+' character, the
  28 G-line will be added, and <expiration> and <reason> are required; when
  29 <mask> is preceded with the '-' character, the G-line will be removed,
  30 and <expiration> and <reason> are not required.  The '<' and '>'
  31 character prefixes are not valid for local G-lines.
  32
  33 * Local modifications to global G-lines.
  34
  35 Opers may locally activate or deactivate global G-lines.  In this
  36 mode, <mask> is interpreted as referencing an existing G-line, and
  37 will be preceded by either '<' (to locally deactivate the G-line) or
  38 '>' (to locally activate the G-line).  This local state overrides the
  39 global state of the G-line, and persists until there is a global state
  40 change to the G-line, or until the G-line expires.  The <expiration>
  41 and <reason> arguments are not required, but <target> may be given if
  42 the oper desires to make the appropriate change on a remote
  43 server--note that the oper will need the GLINE privilege for this.
  44
  45 * Global G-lines.
  46
  47 Opers may, if they have the GLINE privilege, set and manipulate global
  48 G-lines on the network.  To create a new G-line, the oper must prefix
  49 the <mask> with either '+' (for globally activated G-lines) or '-'
  50 (for globally deactivated G-lines).  Additionally, <target> must be
  51 given as "*", and the <expiration> and <reason> parameters are
  52 required.  If the G-line already exists, it will be modified to match
  53 the new global status, <expiration>, and <reason>.
  54
  55 When the G-line already exists, an oper may activate or deactivate it
  56 simply by setting <target> to "*" and prefixing the <mask> with either
  57 "+" (to activate the G-line) or "-" (to deactivate it).  If it is
  58 desired to simply modify the expiration time or reason, without
  59 changing the activation status, specify <mask> without any prefix, set
  60 <target> to "*", and provide the updated <expire> and optionally an
  61 updated <reason>.
  62
  63 * Privilege notes.
  64
  65 Note that, for all locally-restricted G-line changes, such as locally
  66 activating a G-line or creating a local G-line, the oper must have the
  67 LOCAL_GLINE privilege.  For any other G-line change, including
  68 locally-restricted changes on remote servers, the server's
  69 CONFIG_OPERCMDS privilege must be enabled and the oper must have the
  70 GLINE privilege.  There are also restrictions to prevent an oper from
  71 setting a G-line that is too wide; in some cases, those restrictions
  72 may be overridden by prefixing the <mask> parameter with the "!"
  73 character, IF the operator has the WIDE_GLINE privilege.
  74
  75 For a server, the syntax is:
  76
  77   <prefix> GL <target> [!][+|-|>|<]<mask> [<expiration>] [<lastmod>]
  78         [<lifetime>] [:<reason>]
  79
  80 There are a total of 8 basic forms of the GL command.  The primary
  81 innovation is the addition of the <lifetime> parameter, which
  82 specifies a lifetime for the G-line record which may be longer than
  83 the expiration time.  <lifetime> will be monotonically increasing,
  84 enabling <expiration> to be modified in any way desirable.
  85
  86 * Local G-lines.
  87
  88 Remote servers, or opers on them, may remotely set local G-lines on
  89 the local server.  To create a local G-line, <target> will be set to
  90 the numeric of the local server, and <mask> must be preceded by '+'
  91 (optionally preceded by '!' if the origin desires to override some
  92 safety settings).  The <expiration> and <reason> parameters are
  93 required.  The <lastmod> and <lifetime> parameters will be ignored if
  94 present, allowing backwards compatibility with ircu2.10.12.10 and
  95 prior versions.  Removing local G-lines is similar--<mask> must be
  96 preceded by '-', and all other parameters are ignored to allow
  97 backwards compatibility.
  98
  99 * Local modifications to global G-lines.
 100
 101 Remote servers, or opers on them, may also locally activate or
 102 deactivate a global G-line on the local server.  The <target> must be
 103 set to the numeric of the local server, and <mask> must be preceded by
 104 either '<' (to locally deactivate the G-line) or '>' (to locally
 105 activate the G-line).  This local state overrides the global state of
 106 the G-line, and persists until there is a global state change to the
 107 G-line, or until the G-line expires.  No other parameters are
 108 necessary in this mode, and will be ignored if present.
 109
 110 * Global G-lines.
 111
 112 For creation and manipulation of global G-lines, the <target>
 113 parameter must be set to "*".  If the G-line does not exist, and if
 114 <expiration> is given, the G-line will be created with the specified
 115 expiration and <reason> (the latter defaulting to "No reason" if not
 116 present).  Otherwise, the G-line will be updated according to the
 117 available parameters.  The rules are similar to those for oper-issued
 118 global G-lines, with the addition of a <lastmod> parameter, which is a
 119 monotonically increasing serial number for the G-line, and an optional
 120 <lifetime> parameter that specifies a monotonically increasing
 121 lifetime for the G-line record.  Note that, for existing G-lines where
 122 only state changes (global activation or deactivation) are necessary,
 123 only <lastmod> is required; <expiration> must be specified for all
 124 other forms of the GL command.