source: code/trunk/doc/suika-bouncerserv.7@ 825

'\" t
.\"     Title: suika-bouncerserv
.\"    Author: Simon Ser and contributors / Izuru Yakumo
.\" Generator: Asciidoctor 2.0.20
.\"      Date: 2023-09-15
.\"    Manual: Suika IRC Bouncer
.\"    Source: SUIKA-BOUNCERSERV
.\"  Language: English
.\"
.TH "SUIKA\-BOUNCERSERV" "7" "2023-09-15" "SUIKA\-BOUNCERSERV" "Suika IRC Bouncer"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
suika-bouncerserv \- Service bot exposed by suika(1) to control the bouncer
.SH "DESCRIPTION"
.sp
suika(1) exposes an IRC service called BouncerServ to manage the bouncer.
Commands can be sent via regular private messages.
Commands may be written in full or abbreviated form, for instance network
can be abbreviated as net or just n.
.SH "COMMANDS"
.SS "help [command]"
.sp
Show a list of commands.
If command is specified, show a help message for the command.
.SS "network\-create \-addr <addr> [options...]"
.sp
Connect to a new network at addr.
The option \-addr is mandatory.
.sp
addr supports several connection types:
* ircs://<host>:port \- connects with TLS over TCP
* irc+insecure://<host>:port \- connects with plain\-text over TCP
* irc+unix://<path> \- connects to a Unix domain socket
.sp
Other options are:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\-name <name>
Short network name, this will be used instead of addr to refer to the network
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\-username <username>
Connect with the specified username, by default, the nickname is used
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\-pass <pass>
Connect with the specified server password
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\-realname <realname>
Connect with the specified real name, by default, the account\(cqs realname is used if set, otherwise the network\(cqs nickname is used
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\-nick <nick>
Connect with the specified nickname, by default, the account\(cqs username is used
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\-enabled [bool]
Enable or disable the network, if the network is disabled, the bouncer won\(cqt connect to it, by default, the network is enabled
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\-connect\-command <command>
Send the specified command as a raw IRC message right after connecting to the server, this can be used to identify to an account if a server does not support SASL
.RE
.SS "network update [options...]"
.sp
Update an existing network. The options are the same as the network create command.
When this command is executed, suika(1) will disconnect and re\-connect to the network.
If name is not specified, the current network is updated.
.SS "network delete [name]"
.sp
Disconnect and delete a network.
If name is not specified, the current network is deleted.
.SS "network quote [name] <command>"
.sp
Send a raw IRC line as\-is to a network.
If name is not specified, the command is sent to the current network.
.SS "network status"
.sp
Show a list of saved networks and their current status.
.SS "channel status [options...]"
.sp
Show a list of saved channels and their current status.
Options:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\-network <network>
Only show channels for the specified network. By default, only the channels in the current network are displayed.
.RE
.SS "channel update <name> [options...]"
.sp
Update the options of an existing channel.
Options are:
.sp
\-detached [bool]
Attach or detach this channel.
A detached channel is joined but is hidden by the bouncer.
This is useful to e.g. collect logs and highlights in low\-interest or high\-traffic channels.
.sp
\-relay\-detached [mode] \- Set when to relay messages from detached channels to the user with a BouncerServ NOTICE
* message \- Relay any message from this channel when detached.
* highlight \- Relay only messages mentioning you when detached.
* none \- Do not relay any messages from this channel when detached.
* default \- Currently same as highlight. This is the default behaviour.
.sp
\-reattach\-on [mode] \- Set when to automatically reattach to detached channels.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
message \- Reattach to this channel when any message is received.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
highlight \- Reattach to this channel when any message mentioning you is received.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
none \- Never automatically reattach to this channel.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
default \- Currently same as none. This is the default behaviour.
.RE
.sp
\-detach\-after [duration]
.sp
Automatically detach this channel after the specified duration has elapsed without receving any message corresponding to \-detach\-on. Example duration values: 1h30m, 30s, 2.5h. Setting this value to 0 will disable this behaviour, i.e. this channel will never be automatically detached. This is the default behaviour.
.sp
\-detach\-on [mode]
Set when to reset the auto\-detach timer used by \-detach\-after, causing it to wait again for the auto\-detach duration timer before detaching. Joining, reattaching, sending a message, or changing any channel option will reset the timer, in addition to the messages specified by the mode.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
message \- Receiving any message from this channel will reset the auto\-detach timer.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
highlight \- Receiving any message mentioning you from this channel will reset the auto\-detach timer.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
none \- Receiving messages from this channel will not reset the auto\-detach timer. Sending messages or joining the channel will still reset the timer.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
default \- Currently same as message. This is the default behaviour.
.RE
.SS "certfp generate [options...]"
.sp
Generate self\-signed certificate and use it for authentication (via SASL EXTERNAL). Generates a 3072\-bit RSA private key by default.
Options are:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\-network <network>
Select a network. By default, the current network is selected, if any.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\-key\-type <type>
Private key algorithm to use. Valid values are: rsa, ecdsa and ed25519. ecdsa uses the NIST P\-521 curve.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\-bits <bits>
Size of RSA key to generate. Ignored for other key types.
.RE
.SS "certfp fingerprint [options...]"
.sp
Show SHA\-1 and SHA\-256 fingerprints for the certificate currently used with the network.
Options are:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\-network <network>
Select a network. By default, the current network is selected, if any.
.RE
.SS "sasl status [options...]"
.sp
Show current SASL status.
Options are:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\-network <network>
Select a network. By default, the current network is selected, if any.
.RE
.SS "sasl set\-plain [options...] <username> <password>"
.sp
Set SASL PLAIN credentials.
Options are:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\-network <network>
Select a network. By default, the current network is selected, if any.
.RE
.SS "sasl reset [options...]"
.sp
Disable SASL authentication and remove stored credentials.
Options are:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\-network <network>
Select a network. By default, the current network is selected, if any.
.RE
.SS "user status"
.sp
Show a list of users on this server. Only admins can query this information.
.SS "user create \-username <username> \-password <password> [options...]"
.sp
Create a new suika user. Only admin users can create new accounts. The \-username and \-password flags are mandatory.
Options are:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\-username <username> \- The bouncer username. This cannot be changed after the user has been created.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\-password <password> \- The bouncer password.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\-disable\-password \- Disable password authentication. The user will be unable to login.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\-admin [bool] \- Make the new user an administrator.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\-nick <nick> \- Set the user\(cqs nickname. This is used as a fallback if there is no nickname set for a network.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\-realname <realname> \- Set the user\(cqs realname. This is used as a fallback if there is no realname set for a network.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\-enabled [bool] \- Enable or disable the user. If the user is disabled, the bouncer will not connect to any of their networks, and downstream connections will be immediately closed. By default, users are enabled.
.RE
.SS "user update [username] [options...]"
.sp
Update a user. The options are the same as the user create command. If username is omitted, the current user is updated. Only admins can update other users.
.sp
Not all flags are valid in all contexts:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
The \-username flag is never valid, usernames are immutable.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
The \-nick and \-realname flag are only valid when updating the current user.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
The \-admin and \-enabled flags are only valid when updating another user.
.RE
.SS "user delete <username> [confirmation token]"
.sp
Delete a suika user. Only admins can delete other users.
=== user run <username> <command...>
Execute a command as another user. Only admins can use this command.
=== server status
Show some bouncer statistics. Only admins can query this information.
=== server notice <message>
Broadcast a notice. All currently connected bouncer users will receive the message from the special BouncerServ service. Only admins can broadcast a notice.
.SH "SEE ALSO"
.sp
suika(1)
suikadb(1)
suika\-znc\-import(1)
suika\-config(5)
.SH "AUTHOR"
.sp
Simon Ser and contributors / Izuru Yakumo