diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/Makefile | 4 | ||||
| -rw-r--r-- | man/prosodyctl.man | 243 | ||||
| -rw-r--r-- | man/prosodyctl.markdown | 161 |
3 files changed, 339 insertions, 69 deletions
diff --git a/man/Makefile b/man/Makefile new file mode 100644 index 00000000..79bdd90a --- /dev/null +++ b/man/Makefile @@ -0,0 +1,4 @@ +all: prosodyctl.man + +%.man: %.markdown + pandoc -s -t man -o $@ $^ diff --git a/man/prosodyctl.man b/man/prosodyctl.man index 6dcb04cd..0d3cf5d6 100644 --- a/man/prosodyctl.man +++ b/man/prosodyctl.man @@ -1,83 +1,188 @@ -.TH PROSODYCTL 1 "2009-07-02" - +.\" Automatically generated by Pandoc 1.19.2.1 +.\" +.TH "PROSODYCTL" "1" "2017\-09\-02" "" "" +.hy .SH NAME +.PP prosodyctl \- Manage a Prosody XMPP server - .SH SYNOPSIS -\fBprosodyctl\fP \fIcommand\fP [\fI--help\fP] - +.IP +.nf +\f[C] +prosodyctl\ command\ [\-\-help] +\f[] +.fi .SH DESCRIPTION -\fBprosodyctl\fP is the control tool for the Prosody XMPP server. It may be -used to control the server daemon and manage users. - -\fBprosodyctl\fP needs to be executed with sufficient privileges to perform -its commands. This typically means executing \fBprosodyctl\fP as the root user. -If a user named "prosody" is found then \fBprosodyctl\fP will change to that +.PP +prosodyctl is the control tool for the Prosody XMPP server. +It may be used to control the server daemon and manage users. +.PP +prosodyctl needs to be executed with sufficient privileges to perform +its commands. +This typically means executing prosodyctl as the root user. +If a user named "prosody" is found then prosodyctl will change to that user before executing its commands. - .SH COMMANDS .SS User Management -In the following commands users are identified by a Jabber ID, \fIjid\fP, of the -usual form: user@domain. - -.IP "\fBadduser\fP \fIjid\fP" -Adds a user with Jabber ID, \fIjid\fP, to the server. You will be -prompted to enter the user's password. - -.IP "\fBpasswd\fP \fIjid\fP" -Changes the password of an existing user with Jabber ID, \fIjid\fP. You will be -prompted to enter the user's new password. - -.IP "\fBdeluser\fP \fIjid\fP" -Deletes an existing user with Jabber ID, \fIjid\fP, from the server. - +.PP +In the following commands users are identified by a Jabber ID, jid, of +the usual form: user\@domain. +.TP +.B adduser jid +Adds a user with Jabber ID, jid, to the server. +You will be prompted to enter the user\[aq]s password. +.RS +.RE +.TP +.B passwd jid +Changes the password of an existing user with Jabber ID, jid. +You will be prompted to enter the user\[aq]s new password. +.RS +.RE +.TP +.B deluser jid +Deletes an existing user with Jabber ID, jid, from the server. +.RS +.RE .SS Daemon Management -Although \fBprosodyctl\fP has commands to manage the \fBprosody\fP daemon it is -recommended that you utilize your distributions daemon management features if -you attained Prosody through a package. - -To perform daemon control commands \fBprosodyctl\fP needs a \fIpidfile\fP value -specified in \fI/etc/prosody/prosody.cfg.lua\fP. Failure to do so will cause -\fBprosodyctl\fP to complain. - -.IP \fBstart\fP -Starts the \fBprosody\fP server daemon. If run as root \fBprosodyctl\fP will -attempt to change to a user named "prosody" before executing. This operation -will block for up to five seconds to wait for the server to execute. - -.IP \fBstop\fP -Stops the \fBprosody\fP server daemon. This operation will block for up to five -seconds to wait for the server to stop executing. - -.IP \fBrestart\fP -Restarts the \fBprosody\fP server daemon. Equivalent to running \fBprosodyctl -stop\fP followed by \fBprosodyctl start\fP. - -.IP \fBstatus\fP -Prints the current execution status of the \fBprosody\fP server daemon. - +.PP +Although prosodyctl has commands to manage the prosody daemon it is +recommended that you utilize your distributions daemon management +features if you attained Prosody through a package. +.PP +To perform daemon control commands prosodyctl needs a pidfile value +specified in \f[C]/etc/prosody/prosody.cfg.lua\f[]. +Failure to do so will cause prosodyctl to complain. +.TP +.B start +Starts the prosody server daemon. +If run as root prosodyctl will attempt to change to a user named +"prosody" before executing. +This operation will block for up to five seconds to wait for the server +to execute. +.RS +.RE +.TP +.B stop +Stops the prosody server daemon. +This operation will block for up to five seconds to wait for the server +to stop executing. +.RS +.RE +.TP +.B restart +Restarts the prosody server daemon. +Equivalent to running prosodyctl stop followed by prosodyctl start. +.RS +.RE +.TP +.B reload +Signals the prosody server daemon to reload configuration and reopen log +files. +.RS +.RE +.TP +.B status +Prints the current execution status of the prosody server daemon. +.RS +.RE +.SS Certificates +.PP +prosodyctl can create self\-signed certificates, certificate requests +and private keys for use with Prosody. +Commands are of the form \f[C]prosodyctl\ cert\ subcommand\f[]. +Commands take a list of hosts to be included in the certificate. +.TP +.B \f[C]request\ hosts\f[] +Create a certificate request (CSR) file for submission to a certificate +authority. +Multiple hosts can be given, sub\-domains are automatically included. +.RS +.RE +.TP +.B \f[C]generate\ hosts\f[] +Generate a self\-signed certificate. +.RS +.RE +.TP +.B \f[C]key\ host\ [size]\f[] +Generate a private key of \[aq]size\[aq] bits (defaults to 2048). +Invoked automatically by \[aq]request\[aq] and \[aq]generate\[aq] if +needed. +.RS +.RE +.TP +.B \f[C]config\ hosts\f[] +Produce a config file for the list of hosts. +Invoked automatically by \[aq]request\[aq] and \[aq]generate\[aq] if +needed. +.RS +.RE +.TP +.B \f[C]import\ hosts\ paths\f[] +Copy certificates for hosts into the certificate path and reload +prosody. +.RS +.RE +.SS Debugging +.PP +prosodyctl can also show some information about the environment, +dependencies and such to aid in debugging. +.TP +.B \f[C]about\f[] +Shows environment, various paths used by Prosody and installed +dependencies. +.RS +.RE +.TP +.B \f[C]check\ [what]\f[] +Performs various sanity checks on the configuration, DNS setup and +configured TLS certificates. +\f[C]what\f[] can be one of \f[C]config\f[], \f[C]dns\f[] and +\f[C]certs\f[] to run only that check. +.RS +.RE .SS Ejabberd Compatibility -\fBejabberd\fP is another XMPP server which provides a comparable control tool, -\fBejabberdctl\fP, to control its server's operations. \fBprosodyctl\fP -implements some commands which are compatible with \fBejabberdctl\fP. For -details of how these commands work you should see -.BR ejabberdctl (8). - -.IP "\fBregister\fP \fIuser server password\fP" -.IP "\fBunregister\fP \fIuser server\fP" - +.PP +ejabberd is another XMPP server which provides a comparable control +tool, ejabberdctl, to control its server\[aq]s operations. +prosodyctl implements some commands which are compatible with +ejabberdctl. +For details of how these commands work you should see ejabberdctl(8). +.IP +.nf +\f[C] +register\ user\ server\ password + +unregister\ user\ server +\f[] +.fi .SH OPTIONS -.IP \fI--help\fP +.TP +.B \f[C]\-\-config\ filename\f[] +Use the specified config file instead of the default. +.RS +.RE +.TP +.B \f[C]\-\-root\f[] +Don\[aq]t drop root privileges. +.RS +.RE +.TP +.B \f[C]\-\-help\f[] Display help text for the specified command. - +.RS +.RE .SH FILES -.IP \fI/etc/prosody/prosody.cfg.lua\fP -The main \fBprosody\fP configuration file. \fBprosodyctl\fP reads this to -determine the process ID file of the \fBprosody\fP server daemon and to -determine if a host has been configured. - +.TP +.B \f[C]/etc/prosody/prosody.cfg.lua\f[] +The main prosody configuration file. +prosodyctl reads this to determine the process ID file of the prosody +server daemon and to determine if a host has been configured. +.RS +.RE .SH ONLINE -More information may be found online at: \fIhttp://prosody.im/\fP - +.PP +More information may be found online at: <https://prosody.im/> .SH AUTHORS -Dwayne Bent <dbb.1@liqd.org> +Dwayne Bent <dbb.1@liqd.org>; Kim Alvefur. diff --git a/man/prosodyctl.markdown b/man/prosodyctl.markdown new file mode 100644 index 00000000..121547fd --- /dev/null +++ b/man/prosodyctl.markdown @@ -0,0 +1,161 @@ +--- +author: +- 'Dwayne Bent <dbb.1@liqd.org>' +- Kim Alvefur +date: '2017-09-02' +section: 1 +title: PROSODYCTL +--- + +NAME +==== + +prosodyctl - Manage a Prosody XMPP server + +SYNOPSIS +======== + + prosodyctl command [--help] + +DESCRIPTION +=========== + +prosodyctl is the control tool for the Prosody XMPP server. It may be +used to control the server daemon and manage users. + +prosodyctl needs to be executed with sufficient privileges to perform +its commands. This typically means executing prosodyctl as the root +user. If a user named "prosody" is found then prosodyctl will change to +that user before executing its commands. + +COMMANDS +======== + +User Management +--------------- + +In the following commands users are identified by a Jabber ID, jid, of +the usual form: user@domain. + +adduser jid +: Adds a user with Jabber ID, jid, to the server. You will be prompted + to enter the user's password. + +passwd jid +: Changes the password of an existing user with Jabber ID, jid. You + will be prompted to enter the user's new password. + +deluser jid +: Deletes an existing user with Jabber ID, jid, from the server. + +Daemon Management +----------------- + +Although prosodyctl has commands to manage the prosody daemon it is +recommended that you utilize your distributions daemon management +features if you attained Prosody through a package. + +To perform daemon control commands prosodyctl needs a pidfile value +specified in `/etc/prosody/prosody.cfg.lua`. Failure to do so will cause +prosodyctl to complain. + +start +: Starts the prosody server daemon. If run as root prosodyctl will + attempt to change to a user named "prosody" before executing. This + operation will block for up to five seconds to wait for the server + to execute. + +stop +: Stops the prosody server daemon. This operation will block for up to + five seconds to wait for the server to stop executing. + +restart +: Restarts the prosody server daemon. Equivalent to running prosodyctl + stop followed by prosodyctl start. + +reload +: Signals the prosody server daemon to reload configuration and reopen + log files. + +status +: Prints the current execution status of the prosody server daemon. + +Certificates +------------ + +prosodyctl can create self-signed certificates, certificate requests and +private keys for use with Prosody. Commands are of the form +`prosodyctl cert subcommand`. Commands take a list of hosts to be +included in the certificate. + +`request hosts` +: Create a certificate request (CSR) file for submission to a + certificate authority. Multiple hosts can be given, sub-domains are + automatically included. + +`generate hosts` +: Generate a self-signed certificate. + +`key host [size]` +: Generate a private key of 'size' bits (defaults to 2048). Invoked + automatically by 'request' and 'generate' if needed. + +`config hosts` +: Produce a config file for the list of hosts. Invoked automatically + by 'request' and 'generate' if needed. + +`import hosts paths` +: Copy certificates for hosts into the certificate path and reload + prosody. + +Debugging +--------- + +prosodyctl can also show some information about the environment, +dependencies and such to aid in debugging. + +`about` +: Shows environment, various paths used by Prosody and installed + dependencies. + +`check [what]` +: Performs various sanity checks on the configuration, DNS setup and + configured TLS certificates. `what` can be one of `config`, `dns` + and `certs` to run only that check. + +Ejabberd Compatibility +---------------------- + +ejabberd is another XMPP server which provides a comparable control +tool, ejabberdctl, to control its server's operations. prosodyctl +implements some commands which are compatible with ejabberdctl. For +details of how these commands work you should see ejabberdctl(8). + + register user server password + + unregister user server + +OPTIONS +======= + +`--config filename` +: Use the specified config file instead of the default. + +`--root` +: Don't drop root privileges. + +`--help` +: Display help text for the specified command. + +FILES +===== + +`/etc/prosody/prosody.cfg.lua` +: The main prosody configuration file. prosodyctl reads this to + determine the process ID file of the prosody server daemon and to + determine if a host has been configured. + +ONLINE +====== + +More information may be found online at: <https://prosody.im/> |