man/prosodyctl.markdown

   1 ---
   2 author:
   3 - 'Dwayne Bent <dbb.1@liqd.org>'
   4 - Kim Alvefur
   5 date: '2017-09-02'
   6 section: 1
   7 title: PROSODYCTL
   8 ---
   9
  10 NAME
  11 ====
  12
  13 prosodyctl - Manage a Prosody XMPP server
  14
  15 SYNOPSIS
  16 ========
  17
  18     prosodyctl command [--help]
  19
  20 DESCRIPTION
  21 ===========
  22
  23 prosodyctl is the control tool for the Prosody XMPP server. It may be
  24 used to control the server daemon and manage users.
  25
  26 prosodyctl needs to be executed with sufficient privileges to perform
  27 its commands. This typically means executing prosodyctl as the root
  28 user. If a user named "prosody" is found then prosodyctl will change to
  29 that user before executing its commands.
  30
  31 COMMANDS
  32 ========
  33
  34 User Management
  35 ---------------
  36
  37 In the following commands users are identified by a Jabber ID, jid, of
  38 the usual form: user@domain.
  39
  40 adduser jid
  41 :   Adds a user with Jabber ID, jid, to the server. You will be prompted
  42     to enter the user's password.
  43
  44 passwd jid
  45 :   Changes the password of an existing user with Jabber ID, jid. You
  46     will be prompted to enter the user's new password.
  47
  48 deluser jid
  49 :   Deletes an existing user with Jabber ID, jid, from the server.
  50
  51 Daemon Management
  52 -----------------
  53
  54 Although prosodyctl has commands to manage the prosody daemon it is
  55 recommended that you utilize your distributions daemon management
  56 features if you attained Prosody through a package.
  57
  58 To perform daemon control commands prosodyctl needs a pidfile value
  59 specified in `/etc/prosody/prosody.cfg.lua`. Failure to do so will cause
  60 prosodyctl to complain.
  61
  62 start
  63 :   Starts the prosody server daemon. If run as root prosodyctl will
  64     attempt to change to a user named "prosody" before executing. This
  65     operation will block for up to five seconds to wait for the server
  66     to execute.
  67
  68 stop
  69 :   Stops the prosody server daemon. This operation will block for up to
  70     five seconds to wait for the server to stop executing.
  71
  72 restart
  73 :   Restarts the prosody server daemon. Equivalent to running prosodyctl
  74     stop followed by prosodyctl start.
  75
  76 reload
  77 :   Signals the prosody server daemon to reload configuration and reopen
  78     log files.
  79
  80 status
  81 :   Prints the current execution status of the prosody server daemon.
  82
  83 Certificates
  84 ------------
  85
  86 prosodyctl can create self-signed certificates, certificate requests and
  87 private keys for use with Prosody. Commands are of the form
  88 `prosodyctl cert subcommand`. Commands take a list of hosts to be
  89 included in the certificate.
  90
  91 `request hosts`
  92 :   Create a certificate request (CSR) file for submission to a
  93     certificate authority. Multiple hosts can be given, sub-domains are
  94     automatically included.
  95
  96 `generate hosts`
  97 :   Generate a self-signed certificate.
  98
  99 `key host [size]`
 100 :   Generate a private key of 'size' bits (defaults to 2048). Invoked
 101     automatically by 'request' and 'generate' if needed.
 102
 103 `config hosts`
 104 :   Produce a config file for the list of hosts. Invoked automatically
 105     by 'request' and 'generate' if needed.
 106
 107 `import hosts paths`
 108 :   Copy certificates for hosts into the certificate path and reload
 109     prosody.
 110
 111 Debugging
 112 ---------
 113
 114 prosodyctl can also show some information about the environment,
 115 dependencies and such to aid in debugging.
 116
 117 `about`
 118 :   Shows environment, various paths used by Prosody and installed
 119     dependencies.
 120
 121 `check [what]`
 122 :   Performs various sanity checks on the configuration, DNS setup and
 123     configured TLS certificates. `what` can be one of `config`, `dns`
 124     and `certs` to run only that check.
 125
 126 Ejabberd Compatibility
 127 ----------------------
 128
 129 ejabberd is another XMPP server which provides a comparable control
 130 tool, ejabberdctl, to control its server's operations. prosodyctl
 131 implements some commands which are compatible with ejabberdctl. For
 132 details of how these commands work you should see ejabberdctl(8).
 133
 134     register user server password
 135
 136     unregister user server
 137
 138 OPTIONS
 139 =======
 140
 141 `--config filename`
 142 :   Use the specified config file instead of the default.
 143
 144 `--root`
 145 :   Don't drop root privileges.
 146
 147 `--help`
 148 :   Display help text for the specified command.
 149
 150 FILES
 151 =====
 152
 153 `/etc/prosody/prosody.cfg.lua`
 154 :   The main prosody configuration file. prosodyctl reads this to
 155     determine the process ID file of the prosody server daemon and to
 156     determine if a host has been configured.
 157
 158 ONLINE
 159 ======
 160
 161 More information may be found online at: <https://prosody.im/>