SHUN documentation, last updated on 22 Jun 2013

For an ordinary user, the syntax is:

  SHUN [<mask>]

If <mask> is given, and if a Shun for that server exists, all the
information about that Shun is displayed.  If <mask> is not given,
an error is returned.

For an operator, the syntax is:

  SHUN [[!][+|-|>|<]<mask> [<target>] [<expiration> [:<reason>]]]

There are a total of 10 basic forms of the SHUN command.  If no
arguments are given, all existing Shuns will be listed; if only
<mask> is given, the behavior is the same as for an ordinary user.
The remaining forms allow Shuns to be set, manipulated, or possibly
destroyed.

* Local Shuns.

Opers may set or remove Shuns that only apply to a specific server.
When the <target> parameter is not given, the specific server will be
the local server; otherwise, it will be taken to be a remote server,
and the Shun operations will take place there, if the oper has the
SHUN privilege.  When <mask> is preceded with the '+' character, the
Shun will be added, and <expiration> and <reason> are required; when
<mask> is preceded with the '-' character, the Shun will be removed,
and <expiration> and <reason> are not required.  The '<' and '>'
character prefixes are not valid for local Shuns.

* Local modifications to global Shuns.

Opers may locally activate or deactivate global Shuns.  In this
mode, <mask> is interpreted as referencing an existing Shun, and
will be preceded by either '<' (to locally deactivate the Shun) or
'>' (to locally activate the Shun).  This local state overrides the
global state of the Shun, and persists until there is a global state
change to the Shun, or until the Shun expires.  The <expiration>
and <reason> arguments are not required, but <target> may be given if
the oper desires to make the appropriate change on a remote
server--note that the oper will need the SHUN privilege for this.

* Global Shuns.

Opers may, if they have the SHUN privilege, set and manipulate global
Shuns on the network.  To create a new Shun, the oper must prefix
the <mask> with either '+' (for globally activated Shuns) or '-'
(for globally deactivated Shuns).  Additionally, <target> must be
given as "*", and the <expiration> and <reason> parameters are
required.  If the Shun already exists, it will be modified to match
the new global status, <expiration>, and <reason>.

When the Shun already exists, an oper may activate or deactivate it
simply by setting <target> to "*" and prefixing the <mask> with either
"+" (to activate the Shun) or "-" (to deactivate it).  If it is
desired to simply modify the expiration time or reason, without
changing the activation status, specify <mask> without any prefix, set
<target> to "*", and provide the updated <expire> and optionally an
updated <reason>.

* Privilege notes.

Note that, for all locally-restricted Shun changes, such as locally
activating a Shun or creating a local Shun, the oper must have the
LOCAL_SHUN privilege.  For any other Shun change, including
locally-restricted changes on remote servers, the server's
CONFIG_OPERCMDS privilege must be enabled and the oper must have the
SHUN privilege.  There are also restrictions to prevent an oper from
setting a Shun that is too wide; in some cases, those restrictions
may be overridden by prefixing the <mask> parameter with the "!"
character, IF the operator has the WIDE_SHUN privilege.

For a server, the syntax is:

  <prefix> SU <target> [!][+|-|>|<]<mask> [<expiration>] [<lastmod>]
	[<lifetime>] [:<reason>]

There are a total of 8 basic forms of the SU command.  The primary
innovation is the addition of the <lifetime> parameter, which
specifies a lifetime for the Shun record which may be longer than
the expiration time.  <lifetime> will be monotonically increasing,
enabling <expiration> to be modified in any way desirable.

* Local Shuns.

Remote servers, or opers on them, may remotely set local Shuns on
the local server.  To create a local Shun, <target> will be set to
the numeric of the local server, and <mask> must be preceded by '+'
(optionally preceded by '!' if the origin desires to override some
safety settings).  The <expiration> and <reason> parameters are
required.  The <lastmod> and <lifetime> parameters will be ignored if
present, allowing backwards compatibility with ircu2.10.12.10 and
prior versions.  Removing local Shuns is similar--<mask> must be
preceded by '-', and all other parameters are ignored to allow
backwards compatibility.

* Local modifications to global Shuns.

Remote servers, or opers on them, may also locally activate or
deactivate a global Shun on the local server.  The <target> must be
set to the numeric of the local server, and <mask> must be preceded by
either '<' (to locally deactivate the Shun) or '>' (to locally
activate the Shun).  This local state overrides the global state of
the Shun, and persists until there is a global state change to the
Shun, or until the Shun expires.  No other parameters are
necessary in this mode, and will be ignored if present.

* Global Shuns.

For creation and manipulation of global Shuns, the <target>
parameter must be set to "*".  If the Shun does not exist, and if
<expiration> is given, the Shun will be created with the specified
expiration and <reason> (the latter defaulting to "No reason" if not
present).  Otherwise, the Shun will be updated according to the
available parameters.  The rules are similar to those for oper-issued
global Shuns, with the addition of a <lastmod> parameter, which is a
monotonically increasing serial number for the Shun, and an optional
<lifetime> parameter that specifies a monotonically increasing
lifetime for the Shun record.  Note that, for existing Shuns where
only state changes (global activation or deactivation) are necessary,
only <lastmod> is required; <expiration> must be specified for all
other forms of the SU command.