Changeset 823 in code for trunk/doc/suika-bouncerserv.7


Ignore:
Timestamp:
Sep 15, 2023, 4:20:11 AM (21 months ago)
Author:
yakumo.izuru
Message:

Use asciidoctor for generating manpages.
Rename suikactl to suikadb.

Signed-off-by: Izuru Yakumo <yakumo.izuru@…>

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/suika-bouncerserv.7

    r817 r823  
    1 .Dd $Mdocdate$
    2 .Dt SUIKA-BOUNCERSERV 7
    3 .Os
    4 .Sh NAME
    5 .Nm suika-bouncerserv
    6 .Nd Service bot exposed by suika to control the bouncer
    7 .Sh DESCRIPTION
    8 suika exposes an IRC service called BouncerServ to manage the bouncer.
    9 Commands can be sent via regular private messages
    10 (/msg BouncerServ <command> [args...]). Commands may be written in full or
    11 abbreviated form, for instance network can be abbreviated as net or just
    12 n.
    13 .Ss COMMANDS
    14 .Bl -tag -width 11n
    15 .It help [command]
    16 Show a list of commands. If command is specified, show a help message for
    17 the command.
    18 .It network create -addr <addr> [options...]
    19 Connect to a new network at addr. -addr is mandatory.
    20 
     1'\" t
     2.\"     Title: suika-bouncerserv
     3.\"    Author: Simon Ser and contributors / Izuru Yakumo
     4.\" Generator: Asciidoctor 2.0.20
     5.\"      Date: 2023-09-15
     6.\"    Manual: Suika IRC Bouncer
     7.\"    Source: SUIKA-BOUNCERSERV
     8.\"  Language: English
     9.\"
     10.TH "SUIKA\-BOUNCERSERV" "7" "2023-09-15" "SUIKA\-BOUNCERSERV" "Suika IRC Bouncer"
     11.ie \n(.g .ds Aq \(aq
     12.el       .ds Aq '
     13.ss \n[.ss] 0
     14.nh
     15.ad l
     16.de URL
     17\fI\\$2\fP <\\$1>\\$3
     18..
     19.als MTO URL
     20.if \n[.g] \{\
     21.  mso www.tmac
     22.  am URL
     23.    ad l
     24.  .
     25.  am MTO
     26.    ad l
     27.  .
     28.  LINKSTYLE blue R < >
     29.\}
     30.SH "NAME"
     31suika-bouncerserv \- Service bot exposed by suika(1) to control the bouncer
     32.SH "DESCRIPTION"
     33.sp
     34suika(1) exposes an IRC service called BouncerServ to manage the bouncer.
     35Commands can be sent via regular private messages.
     36Commands may be written in full or abbreviated form, for instance network
     37can be abbreviated as net or just n.
     38.SH "COMMANDS"
     39.SS "help [command]"
     40.sp
     41Show a list of commands.
     42If command is specified, show a help message for the command.
     43.SS "network\-create \-addr <addr> [options...]"
     44.sp
     45Connect to a new network at addr.
     46The option \-addr is mandatory.
     47.sp
    2148addr supports several connection types:
    22 
    23 .Bl -tag -width 5n
    24 .It [ircs://]<host>[:port]
    25 connects with TLS over TCP
    26 .It irc+insecure://<host>[:port]
    27 connects with plain-text TCP
    28 .It irc+unix:///<path>
    29 connects to a Unix socket
    30 .El
    31 
     49* ircs://<host>:port \- connects with TLS over TCP
     50* irc+insecure://<host>:port \- connects with plain\-text over TCP
     51* irc+unix://<path> \- connects to a Unix domain socket
     52.sp
    3253Other options are:
    33 
    34 -name <name>
    35 Short network name. This will be used instead of addr to refer to the
    36 network.
    37 
    38 -username <username>
    39 Connect with the specified username. By default, the nickname is used.
    40 
    41 -pass <pass>
    42 Connect with the specified server password.
    43 
    44 -realname <realname>
    45 Connect with the specified real name. By default, the account's realname
    46 is used if set, otherwise the network's nickname is used.
    47 
    48 -nick <nickname>
    49 Connect with the specified nickname. By default, the account's username
    50 is used.
    51 
    52 -enabled true|false
    53 Enable or disable the network. If the network is disabled, the bouncer
    54 won't connect to it. By default, the network is enabled.
    55 
    56 -connect-command <command>
    57 Send the specified command as a raw IRC message right after connecting
    58 to the server. This can be used to identify to an account when the
    59 server doesn't support SASL.
    60 
    61 .It network update [name] [options...]
    62 Update an existing network. The options are the same as the
    63 network create command.
    64 
    65 When this command is executed, suika will disconnect and re-connect to the
    66 network.
    67 
     54.sp
     55.RS 4
     56.ie n \{\
     57\h'-04'\(bu\h'+03'\c
     58.\}
     59.el \{\
     60.  sp -1
     61.  IP \(bu 2.3
     62.\}
     63\-name <name>
     64Short network name, this will be used instead of addr to refer to the network
     65.RE
     66.sp
     67.RS 4
     68.ie n \{\
     69\h'-04'\(bu\h'+03'\c
     70.\}
     71.el \{\
     72.  sp -1
     73.  IP \(bu 2.3
     74.\}
     75\-username <username>
     76Connect with the specified username, by default, the nickname is used
     77.RE
     78.sp
     79.RS 4
     80.ie n \{\
     81\h'-04'\(bu\h'+03'\c
     82.\}
     83.el \{\
     84.  sp -1
     85.  IP \(bu 2.3
     86.\}
     87\-pass <pass>
     88Connect with the specified server password
     89.RE
     90.sp
     91.RS 4
     92.ie n \{\
     93\h'-04'\(bu\h'+03'\c
     94.\}
     95.el \{\
     96.  sp -1
     97.  IP \(bu 2.3
     98.\}
     99\-realname <realname>
     100Connect with the specified real name, by default, the account\(cqs realname is used if set, otherwise the network\(cqs nickname is used
     101.RE
     102.sp
     103.RS 4
     104.ie n \{\
     105\h'-04'\(bu\h'+03'\c
     106.\}
     107.el \{\
     108.  sp -1
     109.  IP \(bu 2.3
     110.\}
     111\-nick <nick>
     112Connect with the specified nickname, by default, the account\(cqs username is used
     113.RE
     114.sp
     115.RS 4
     116.ie n \{\
     117\h'-04'\(bu\h'+03'\c
     118.\}
     119.el \{\
     120.  sp -1
     121.  IP \(bu 2.3
     122.\}
     123\-enabled [bool]
     124Enable or disable the network, if the network is disabled, the bouncer won\(cqt connect to it, by default, the network is enabled
     125.RE
     126.sp
     127.RS 4
     128.ie n \{\
     129\h'-04'\(bu\h'+03'\c
     130.\}
     131.el \{\
     132.  sp -1
     133.  IP \(bu 2.3
     134.\}
     135\-connect\-command <command>
     136Send 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
     137.RE
     138.SS "network update [options...]"
     139.sp
     140Update an existing network. The options are the same as the network create command.
     141When this command is executed, suika(1) will disconnect and re\-connect to the network.
    68142If name is not specified, the current network is updated.
    69 
    70 .It network delete [name]
     143.SS "network delete [name]"
     144.sp
    71145Disconnect and delete a network.
    72 
    73146If name is not specified, the current network is deleted.
    74 
    75 .It network quote [name] <command>
    76 Send a raw IRC line as-is to a network.
    77 
     147.SS "network quote [name] <command>"
     148.sp
     149Send a raw IRC line as\-is to a network.
    78150If name is not specified, the command is sent to the current network.
    79 .It network status
     151.SS "network status"
     152.sp
    80153Show a list of saved networks and their current status.
    81 .It channel status [options...]
     154.SS "channel status [options...]"
     155.sp
    82156Show a list of saved channels and their current status.
    83157Options:
    84 
    85 -network <name>
    86 
     158.sp
     159.RS 4
     160.ie n \{\
     161\h'-04'\(bu\h'+03'\c
     162.\}
     163.el \{\
     164.  sp -1
     165.  IP \(bu 2.3
     166.\}
     167\-network <network>
    87168Only show channels for the specified network. By default, only the channels in the current network are displayed.
    88 channel update <name> [options...]
    89 
     169.RE
     170.SS "channel update <name> [options...]"
     171.sp
    90172Update the options of an existing channel.
    91173Options are:
    92 
    93 -detached true|false
    94 
     174.sp
     175\-detached [bool]
    95176Attach or detach this channel.
    96 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.
    97 
    98 -relay-detached <mode>
    99 
    100 Set when to relay messages from detached channels to the user with a BouncerServ NOTICE.
    101 Modes are:
    102 
    103 message
    104 
    105 Relay any message from this channel when detached.
    106 highlight
    107 
    108 Relay only messages mentioning you when detached.
    109 none
    110 
    111 Don't relay any messages from this channel when detached.
    112 default
    113 
    114 Currently same as highlight. This is the default behaviour.
    115 -reattach-on <mode>
    116 
    117 Set when to automatically reattach to detached channels.
    118 Modes are:
    119 
    120 message
    121 
    122 Reattach to this channel when any message is received.
    123 highlight
    124 
    125 Reattach to this channel when any message mentioning you is received.
    126 none
    127 
    128 Never automatically reattach to this channel.
    129 default
    130 
    131 Currently same as none. This is the default behaviour.
    132 -detach-after <duration>
    133 
    134 Automatically detach this channel after the specified duration has elapsed without receving any message corresponding to -detach-on.
    135 Example duration values: 1h30m, 30s, 2.5h.
    136 
    137 Setting this value to 0 will disable this behaviour, i.e. this channel will never be automatically detached. This is the default behaviour.
    138 
    139 -detach-on <mode>
    140 
    141 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.
    142 Modes are:
    143 
    144 message
    145 
    146 Receiving any message from this channel will reset the auto-detach timer.
    147 highlight
    148 
    149 Receiving any message mentioning you from this channel will reset the auto-detach timer.
    150 none
    151 
    152 Receiving messages from this channel will not reset the auto-detach timer. Sending messages or joining the channel will still reset the timer.
    153 default
    154 
    155 Currently same as message. This is the default behaviour.
    156 .It channel delete <name>
    157 Leave and forget a channel.
    158 .It certfp generate [options...]
    159 Generate self-signed certificate and use it for authentication (via SASL EXTERNAL).
    160 Generates a 3072-bit RSA private key by default.
    161 
    162 Options are:
    163 
    164 -network <name>
    165 
     177A detached channel is joined but is hidden by the bouncer.
     178This is useful to e.g. collect logs and highlights in low\-interest or high\-traffic channels.
     179.sp
     180\-relay\-detached [mode] \- Set when to relay messages from detached channels to the user with a BouncerServ NOTICE
     181* message \- Relay any message from this channel when detached.
     182* highlight \- Relay only messages mentioning you when detached.
     183* none \- Do not relay any messages from this channel when detached.
     184* default \- Currently same as highlight. This is the default behaviour.
     185.sp
     186\-reattach\-on [mode] \- Set when to automatically reattach to detached channels.
     187.sp
     188.RS 4
     189.ie n \{\
     190\h'-04'\(bu\h'+03'\c
     191.\}
     192.el \{\
     193.  sp -1
     194.  IP \(bu 2.3
     195.\}
     196message \- Reattach to this channel when any message is received.
     197.RE
     198.sp
     199.RS 4
     200.ie n \{\
     201\h'-04'\(bu\h'+03'\c
     202.\}
     203.el \{\
     204.  sp -1
     205.  IP \(bu 2.3
     206.\}
     207highlight \- Reattach to this channel when any message mentioning you is received.
     208.RE
     209.sp
     210.RS 4
     211.ie n \{\
     212\h'-04'\(bu\h'+03'\c
     213.\}
     214.el \{\
     215.  sp -1
     216.  IP \(bu 2.3
     217.\}
     218none \- Never automatically reattach to this channel.
     219.RE
     220.sp
     221.RS 4
     222.ie n \{\
     223\h'-04'\(bu\h'+03'\c
     224.\}
     225.el \{\
     226.  sp -1
     227.  IP \(bu 2.3
     228.\}
     229default \- Currently same as none. This is the default behaviour.
     230.RE
     231.sp
     232\-detach\-after [duration]
     233.sp
     234Automatically 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.
     235.sp
     236\-detach\-on [mode]
     237Set 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.
     238.sp
     239.RS 4
     240.ie n \{\
     241\h'-04'\(bu\h'+03'\c
     242.\}
     243.el \{\
     244.  sp -1
     245.  IP \(bu 2.3
     246.\}
     247message \- Receiving any message from this channel will reset the auto\-detach timer.
     248.RE
     249.sp
     250.RS 4
     251.ie n \{\
     252\h'-04'\(bu\h'+03'\c
     253.\}
     254.el \{\
     255.  sp -1
     256.  IP \(bu 2.3
     257.\}
     258highlight \- Receiving any message mentioning you from this channel will reset the auto\-detach timer.
     259.RE
     260.sp
     261.RS 4
     262.ie n \{\
     263\h'-04'\(bu\h'+03'\c
     264.\}
     265.el \{\
     266.  sp -1
     267.  IP \(bu 2.3
     268.\}
     269none \- Receiving messages from this channel will not reset the auto\-detach timer. Sending messages or joining the channel will still reset the timer.
     270.RE
     271.sp
     272.RS 4
     273.ie n \{\
     274\h'-04'\(bu\h'+03'\c
     275.\}
     276.el \{\
     277.  sp -1
     278.  IP \(bu 2.3
     279.\}
     280default \- Currently same as message. This is the default behaviour.
     281.RE
     282.SS "certfp generate [options...]"
     283.sp
     284Generate self\-signed certificate and use it for authentication (via SASL EXTERNAL). Generates a 3072\-bit RSA private key by default.
     285Options are:
     286.sp
     287.RS 4
     288.ie n \{\
     289\h'-04'\(bu\h'+03'\c
     290.\}
     291.el \{\
     292.  sp -1
     293.  IP \(bu 2.3
     294.\}
     295\-network <network>
    166296Select a network. By default, the current network is selected, if any.
    167 -key-type <type>
    168 
    169 Private key algorithm to use. Valid values are: rsa, ecdsa and ed25519. ecdsa uses the NIST P-521 curve.
    170 -bits <bits>
    171 
     297.RE
     298.sp
     299.RS 4
     300.ie n \{\
     301\h'-04'\(bu\h'+03'\c
     302.\}
     303.el \{\
     304.  sp -1
     305.  IP \(bu 2.3
     306.\}
     307\-key\-type <type>
     308Private key algorithm to use. Valid values are: rsa, ecdsa and ed25519. ecdsa uses the NIST P\-521 curve.
     309.RE
     310.sp
     311.RS 4
     312.ie n \{\
     313\h'-04'\(bu\h'+03'\c
     314.\}
     315.el \{\
     316.  sp -1
     317.  IP \(bu 2.3
     318.\}
     319\-bits <bits>
    172320Size of RSA key to generate. Ignored for other key types.
    173 certfp fingerprint [options...]
    174 
    175 Show SHA-1 and SHA-256 fingerprints for the certificate currently used with the network.
    176 Options are:
    177 
    178 -network <name>
    179 
     321.RE
     322.SS "certfp fingerprint [options...]"
     323.sp
     324Show SHA\-1 and SHA\-256 fingerprints for the certificate currently used with the network.
     325Options are:
     326.sp
     327.RS 4
     328.ie n \{\
     329\h'-04'\(bu\h'+03'\c
     330.\}
     331.el \{\
     332.  sp -1
     333.  IP \(bu 2.3
     334.\}
     335\-network <network>
    180336Select a network. By default, the current network is selected, if any.
    181 sasl status [options...]
    182 
     337.RE
     338.SS "sasl status [options...]"
     339.sp
    183340Show current SASL status.
    184341Options are:
    185 
    186 -network <name>
    187 
     342.sp
     343.RS 4
     344.ie n \{\
     345\h'-04'\(bu\h'+03'\c
     346.\}
     347.el \{\
     348.  sp -1
     349.  IP \(bu 2.3
     350.\}
     351\-network <network>
    188352Select a network. By default, the current network is selected, if any.
    189 .It sasl set-plain [options...] <username> <password>
     353.RE
     354.SS "sasl set\-plain [options...] <username> <password>"
     355.sp
    190356Set SASL PLAIN credentials.
    191357Options are:
    192 
    193 -network <name>
    194 
     358.sp
     359.RS 4
     360.ie n \{\
     361\h'-04'\(bu\h'+03'\c
     362.\}
     363.el \{\
     364.  sp -1
     365.  IP \(bu 2.3
     366.\}
     367\-network <network>
    195368Select a network. By default, the current network is selected, if any.
    196 .It sasl reset [options...]
     369.RE
     370.SS "sasl reset [options...]"
     371.sp
    197372Disable SASL authentication and remove stored credentials.
    198373Options are:
    199 
    200 -network <name>
    201 
     374.sp
     375.RS 4
     376.ie n \{\
     377\h'-04'\(bu\h'+03'\c
     378.\}
     379.el \{\
     380.  sp -1
     381.  IP \(bu 2.3
     382.\}
     383\-network <network>
    202384Select a network. By default, the current network is selected, if any.
    203 .It user status
     385.RE
     386.SS "user status"
     387.sp
    204388Show a list of users on this server. Only admins can query this information.
    205 user create -username <username> -password <password> [options...]
    206 
    207 Create a new suika user. Only admin users can create new accounts. The -username and -password flags are mandatory.
    208 Options are:
    209 
    210 -username <username>
    211 
    212 The bouncer username. This cannot be changed after the user has been created.
    213 -password <password>
    214 
    215 The bouncer password.
    216 -disable-password
    217 
    218 Disable password authentication. The user will be unable to login.
    219 -admin true|false
    220 
    221 Make the new user an administrator.
    222 -nick <nick>
    223 
    224 Set the user's nickname. This is used as a fallback if there is no nickname set for a network.
    225 -realname <realname>
    226 
    227 Set the user's realname. This is used as a fallback if there is no realname set for a network.
    228 -enabled true|false
    229 
    230 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.
    231 .It user update [username] [options...]
    232 Update a user. The options are the same as the user create command.
    233 If username is omitted, the current user is updated. Only admins can update other users.
    234 
     389.SS "user create \-username <username> \-password <password> [options...]"
     390.sp
     391Create a new suika user. Only admin users can create new accounts. The \-username and \-password flags are mandatory.
     392Options are:
     393.sp
     394.RS 4
     395.ie n \{\
     396\h'-04'\(bu\h'+03'\c
     397.\}
     398.el \{\
     399.  sp -1
     400.  IP \(bu 2.3
     401.\}
     402\-username <username> \- The bouncer username. This cannot be changed after the user has been created.
     403.RE
     404.sp
     405.RS 4
     406.ie n \{\
     407\h'-04'\(bu\h'+03'\c
     408.\}
     409.el \{\
     410.  sp -1
     411.  IP \(bu 2.3
     412.\}
     413\-password <password> \- The bouncer password.
     414.RE
     415.sp
     416.RS 4
     417.ie n \{\
     418\h'-04'\(bu\h'+03'\c
     419.\}
     420.el \{\
     421.  sp -1
     422.  IP \(bu 2.3
     423.\}
     424\-disable\-password \- Disable password authentication. The user will be unable to login.
     425.RE
     426.sp
     427.RS 4
     428.ie n \{\
     429\h'-04'\(bu\h'+03'\c
     430.\}
     431.el \{\
     432.  sp -1
     433.  IP \(bu 2.3
     434.\}
     435\-admin [bool] \- Make the new user an administrator.
     436.RE
     437.sp
     438.RS 4
     439.ie n \{\
     440\h'-04'\(bu\h'+03'\c
     441.\}
     442.el \{\
     443.  sp -1
     444.  IP \(bu 2.3
     445.\}
     446\-nick <nick> \- Set the user\(cqs nickname. This is used as a fallback if there is no nickname set for a network.
     447.RE
     448.sp
     449.RS 4
     450.ie n \{\
     451\h'-04'\(bu\h'+03'\c
     452.\}
     453.el \{\
     454.  sp -1
     455.  IP \(bu 2.3
     456.\}
     457\-realname <realname> \- Set the user\(cqs realname. This is used as a fallback if there is no realname set for a network.
     458.RE
     459.sp
     460.RS 4
     461.ie n \{\
     462\h'-04'\(bu\h'+03'\c
     463.\}
     464.el \{\
     465.  sp -1
     466.  IP \(bu 2.3
     467.\}
     468\-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.
     469.RE
     470.SS "user update [username] [options...]"
     471.sp
     472Update 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.
     473.sp
    235474Not all flags are valid in all contexts:
    236 
    237 •The -username flag is never valid, usernames are immutable.
    238 •The -nick and -realname flag are only valid when updating the current user.
    239 •The -admin and -enabled flags are only valid when updating another user.
    240 .It user delete <username> [confirmation token]
    241 Delete a suika user.
    242 Only admins can delete other users.
    243 .It user run <username> <command...>
    244 Execute a command as another user.
    245 Only admins can use this command.
    246 .It server status
     475.sp
     476.RS 4
     477.ie n \{\
     478\h'-04'\(bu\h'+03'\c
     479.\}
     480.el \{\
     481.  sp -1
     482.  IP \(bu 2.3
     483.\}
     484The \-username flag is never valid, usernames are immutable.
     485.RE
     486.sp
     487.RS 4
     488.ie n \{\
     489\h'-04'\(bu\h'+03'\c
     490.\}
     491.el \{\
     492.  sp -1
     493.  IP \(bu 2.3
     494.\}
     495The \-nick and \-realname flag are only valid when updating the current user.
     496.RE
     497.sp
     498.RS 4
     499.ie n \{\
     500\h'-04'\(bu\h'+03'\c
     501.\}
     502.el \{\
     503.  sp -1
     504.  IP \(bu 2.3
     505.\}
     506The \-admin and \-enabled flags are only valid when updating another user.
     507.RE
     508.SS "user delete <username> [confirmation token]"
     509.sp
     510Delete a suika user. Only admins can delete other users.
     511=== user run <username> <command...>
     512Execute a command as another user. Only admins can use this command.
     513=== server status
    247514Show some bouncer statistics. Only admins can query this information.
    248 .It server notice <message>
     515=== server notice <message>
    249516Broadcast a notice. All currently connected bouncer users will receive the message from the special BouncerServ service. Only admins can broadcast a notice.
    250 .El
    251 .Sh SEE ALSO
    252 .Xr suika 1
    253 .Xr suika-config 5
    254 .Sh AUTHORS
    255 .An Simon Ser and contributors
    256 .Lk https://emersion.fr
    257 .Pp
    258 .An Izuru Yakumo Aq Mt yakumo.izuru@chaotic.ninja
     517.SH "SEE ALSO"
     518.sp
     519suika(1)
     520suikadb(1)
     521suika\-znc\-import(1)
     522suika\-config(5)
     523.SH "AUTHOR"
     524.sp
     525Simon Ser and contributors / Izuru Yakumo
Note: See TracChangeset for help on using the changeset viewer.