https://wiki.archlinux.org/api.php?action=feedcontributions&user=Dbb&feedformat=atomArchWiki - User contributions [en]2024-03-29T11:51:24ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Kerbal_Space_Program&diff=350210Kerbal Space Program2014-12-16T01:23:00Z<p>Dbb: Removing because solution appeared to be a red herring, problem seems to occur sporadically and just so happened not to occur after installing lib, but subsequently happened again.</p>
<hr />
<div>[[Category:Gaming]]<br />
Since version 0.19, Kerbal Space Program includes a native Linux version. However, only Ubuntu 12.04 is officialy supported, so it may not work on Arch Linux out of the box.<br />
<br />
== Installation ==<br />
Install {{AUR|kerbalspaceprogram}} from the [[AUR]].<br />
<br />
== Known issues ==<br />
=== Game never progresses past initial loading ===<br />
To fix this, set:<br />
LC_ALL=C<br />
<br />
This is also relevant if you rocket's parts do not connect.<br />
<br />
=== No text display ===<br />
The game requires Arial and Arial Black fonts, provided in the {{AUR|ttf-ms-fonts}} [[AUR]] package.<br />
<br />
Another alternative is to try to use {{Pkg|ttf-freefont}}, from the [[official repositories]]. This worked using KSP 23.5 on x86_64 Arch Linux. YMMV<br />
<br />
=== Graphics flickering when using primusrun ===<br />
Run with PRIMUS_SYNC=2 (but you will get reduced frame rate this way)<br />
<br />
=== Game crashes when accessing settings or saves on 64 bit systems on Steam ===<br />
In the properties for Kerbal Space program, set a launch option of:<br />
LC_ALL=C %command%_64<br />
<br />
=== Game has garbled graphics when running on x86_64 with all lib32 drivers installed ===<br />
Steam launches the KSP.x86 executable vs the KSP.x86_64 executable. <br />
Navigate to <br />
/home/$USER/.local/share/Steam/SteamApps/common/Kerbal\ Space\ Program/ <br />
Launch with <br />
./KSP.x86_64<br />
Alternatively, to launch it from steam, set the following launch option:<br />
%command%_64<br />
<br />
=== No audio on 64-bit systems ===<br />
<br />
Run the 64-bit Executable.<br />
<br />
Steam launches the KSP.x86 executable vs the KSP.x86_64 executable. <br />
Navigate to <br />
/home/$USER/.local/share/Steam/SteamApps/common/Kerbal\ Space\ Program/ <br />
Launch with <br />
./KSP.x86_64<br />
<br />
Or you can simply right click on Kerbal Space Program on your game list, click on Properties, click on SET LAUNCH OPTIONS, then add this: <br />
LD_LIBRARY_PATH="/usr/lib:$LD_LIBRARY_PATH" LC_ALL=C %command%_64<br />
<br />
==See also==<br />
* http://forum.kerbalspaceprogram.com/showthread.php/24529-The-Linux-compatibility-thread!</div>Dbbhttps://wiki.archlinux.org/index.php?title=Kerbal_Space_Program&diff=350208Kerbal Space Program2014-12-16T00:24:53Z<p>Dbb: </p>
<hr />
<div>[[Category:Gaming]]<br />
Since version 0.19, Kerbal Space Program includes a native Linux version. However, only Ubuntu 12.04 is officialy supported, so it may not work on Arch Linux out of the box.<br />
<br />
== Installation ==<br />
Install {{AUR|kerbalspaceprogram}} from the [[AUR]].<br />
<br />
== Known issues ==<br />
=== Game never progresses past initial loading ===<br />
To fix this, set:<br />
LC_ALL=C<br />
<br />
This is also relevant if you rocket's parts do not connect.<br />
<br />
=== No text display ===<br />
The game requires Arial and Arial Black fonts, provided in the {{AUR|ttf-ms-fonts}} [[AUR]] package.<br />
<br />
Another alternative is to try to use {{Pkg|ttf-freefont}}, from the [[official repositories]]. This worked using KSP 23.5 on x86_64 Arch Linux. YMMV<br />
<br />
=== Graphics flickering when using primusrun ===<br />
Run with PRIMUS_SYNC=2 (but you will get reduced frame rate this way)<br />
<br />
=== Game crashes when accessing settings or saves on 64 bit systems on Steam ===<br />
In the properties for Kerbal Space program, set a launch option of:<br />
LC_ALL=C %command%_64<br />
<br />
=== Game has garbled graphics when running on x86_64 with all lib32 drivers installed ===<br />
Steam launches the KSP.x86 executable vs the KSP.x86_64 executable. <br />
Navigate to <br />
/home/$USER/.local/share/Steam/SteamApps/common/Kerbal\ Space\ Program/ <br />
Launch with <br />
./KSP.x86_64<br />
Alternatively, to launch it from steam, set the following launch option:<br />
%command%_64<br />
<br />
=== No audio on 64-bit systems ===<br />
<br />
Run the 64-bit Executable.<br />
<br />
Steam launches the KSP.x86 executable vs the KSP.x86_64 executable. <br />
Navigate to <br />
/home/$USER/.local/share/Steam/SteamApps/common/Kerbal\ Space\ Program/ <br />
Launch with <br />
./KSP.x86_64<br />
<br />
Or you can simply right click on Kerbal Space Program on your game list, click on Properties, click on SET LAUNCH OPTIONS, then add this: <br />
LD_LIBRARY_PATH="/usr/lib:$LD_LIBRARY_PATH" LC_ALL=C %command%_64<br />
<br />
=== Parts are missing textures ===<br />
If parts such as the Mk3 Cargo Bays introduced in v0.90 are pure white try installing {{Pkg|sdl2_image}}.<br />
<br />
==See also==<br />
* http://forum.kerbalspaceprogram.com/showthread.php/24529-The-Linux-compatibility-thread!</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=300247Prosody2014-02-23T14:08:16Z<p>Dbb: /* More Resources */</p>
<hr />
<div>[[Category:Internet Applications]]<br />
[[de:Prosody]]<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[Arch User Repository]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by {{Ic|$}} indicate that the command may be run as a regular user, while lines preceded by {{Ic|#}} indicate that the command must be run as {{Ic|root}}.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Ic|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [https://www.archlinux.org/packages/community/x86_64/lua51-sec/ lua51-sec] (Community)<br />
<br />
; Better Connection Scaling (Recommended)<br />
: Allow Prosody to use [http://www.monkey.org/~provos/libevent/ libevent] to handle a greater number of simultaneous connections.<br>''Requires:'' {{AUR|lua51-event}} (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [https://www.archlinux.org/packages/community/x86_64/lua51-zlib/ lua51-zlib] (Community)<br />
<br />
; Cyrus SASL Support<br />
: Allow Prosody to use the [http://asg.web.cmu.edu/sasl/sasl-library.html Cyrus SASL] library to provide authentication.<br>''Requires:'' {{AUR|lua-cyrussasl}} (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The {{Ic|posix}} module and {{Ic|pidfile}} setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{ic|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Ic|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to syslog. Thus, by default, Prosody log messages are available in the [[Systemd#Journal|systemd journal]].<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included Systemd script:<br />
<br />
{{Ic|# systemctl start prosody}}<br />
<br />
To automatically start Prosody at boot execute:<br />
<br />
{{Ic|# systemctl enable prosody}}<br />
<br />
Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the {{Ic|prosodyctl}} program. To add a user:<br />
<br />
{{Ic|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the {{Ic|admins}} list in the configuration file.}}<br />
<br />
Issue {{Ic|man prosodyctl}} to see the man page for {{Ic|prosodyctl}}.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the {{Ic|register}} module is enabled in the default configuration but {{Ic|allow_registration}} is set to {{Ic|false}}. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the {{Ic|watchregistrations}} and {{Ic|welcome}} modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). See the relevant sections of {{ic|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
===Listing Users===<br />
A simple way to see a list of the registered users is<br />
# ls -l /var/lib/prosody/*/accounts/*<br />
<br />
alternatively, you can download the module [http://prosody.im/files/mod_listusers.lua mod_listusers.lua], and use it as<br />
# prosodyctl mod_listusers<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Ic|# pacman -Rs prosody}}<br />
<br />
Check above for [[Prosody#Optional Dependencies|optional dependencies]] that may also be removed.<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you do not plan on reinstalling Prosody: {{ic|/etc/prosody}} and {{ic|/var/lib/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the {{Ic|VirtualHost}}s defined in {{Ic|prosody.cfg.lua}}. Attempting to host a component on the same hostname as a defined {{Ic|VirtualHost}} '''will''' result in errors.}}<br />
<br />
By default, Prosody will listen for external components. If you do not plan to use any external components with Prosody you can disable this behavior by adding the following your configuration:<br />
<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
component_ports = {}<br />
}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{hc|/etc/prosody/prosody.cfg.lua|<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host {{Ic|conference.example.com}}.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is {{Ic|[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]}}, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, {{Ic|httpserver}}).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Ic|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{ic|/usr/lib/prosody/modules}}. To enable the module add it to your {{Ic|modules_enabled}} list in your {{ic|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the {{Ic|pastebin}} module on a MUC component:<br />
<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named {{Ic|mod_''foo''.lua}} but simply enabled by adding {{Ic|''foo''}} to the {{Ic|modules_enabled}} list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the {{Ic|console}} module on a multi-user system.}}<br />
<br />
The {{Ic|console}} module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Ic|$ telnet localhost 5582}}<br />
<br />
You of course need the {{Ic|telnet}} program provided by the {{Ic|inetutils}} package. Use the {{Ic|help}} command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with {{Ic|>}}. For example to see if a client connection is compressed:<br />
<br />
{{Ic|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return {{Ic|true}} if the connection is compressed or {{Ic|nil}} if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Ic|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log'''<br>Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging.<br />
* '''Check permissions'''<br>The Prosody package should add a new {{Ic|prosody}} user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{ic|/etc/prosody}} and {{ic|/var/lib/prosody}} are owned by the {{Ic|prosody}} user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Ic|ss -tul}} and making sure that {{Ic|xmpp-client}} (port 5222) and {{Ic|xmpp-server}} (port 5269) are listed.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Ic|systemctl restart prosody}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: {{Ic|prosody@conference.prosody.im}}<br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [https://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
Two development packages are maintained for Prosody in the AUR, {{AUR|prosody-devel}} and {{AUR|prosody-hg]}}. {{Ic|prosody-devel}} tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. {{Ic|prosody-hg}} tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
==Communication==<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: {{Ic|prosody@conference.prosody.im}}<br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
== See also ==<br />
<br />
* [http://prosody.im/doc Official documentation]<br />
* [http://blog.prosody.im/ Prosodical Thoughts] (Blog)<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=300246Prosody2014-02-23T14:07:15Z<p>Dbb: /* More Resources */</p>
<hr />
<div>[[Category:Internet Applications]]<br />
[[de:Prosody]]<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[Arch User Repository]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by {{Ic|$}} indicate that the command may be run as a regular user, while lines preceded by {{Ic|#}} indicate that the command must be run as {{Ic|root}}.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Ic|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [https://www.archlinux.org/packages/community/x86_64/lua51-sec/ lua51-sec] (Community)<br />
<br />
; Better Connection Scaling (Recommended)<br />
: Allow Prosody to use [http://www.monkey.org/~provos/libevent/ libevent] to handle a greater number of simultaneous connections.<br>''Requires:'' {{AUR|lua51-event}} (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [https://www.archlinux.org/packages/community/x86_64/lua51-zlib/ lua51-zlib] (Community)<br />
<br />
; Cyrus SASL Support<br />
: Allow Prosody to use the [http://asg.web.cmu.edu/sasl/sasl-library.html Cyrus SASL] library to provide authentication.<br>''Requires:'' {{AUR|lua-cyrussasl}} (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The {{Ic|posix}} module and {{Ic|pidfile}} setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{ic|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Ic|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to syslog. Thus, by default, Prosody log messages are available in the [[Systemd#Journal|systemd journal]].<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included Systemd script:<br />
<br />
{{Ic|# systemctl start prosody}}<br />
<br />
To automatically start Prosody at boot execute:<br />
<br />
{{Ic|# systemctl enable prosody}}<br />
<br />
Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the {{Ic|prosodyctl}} program. To add a user:<br />
<br />
{{Ic|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the {{Ic|admins}} list in the configuration file.}}<br />
<br />
Issue {{Ic|man prosodyctl}} to see the man page for {{Ic|prosodyctl}}.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the {{Ic|register}} module is enabled in the default configuration but {{Ic|allow_registration}} is set to {{Ic|false}}. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the {{Ic|watchregistrations}} and {{Ic|welcome}} modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). See the relevant sections of {{ic|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
===Listing Users===<br />
A simple way to see a list of the registered users is<br />
# ls -l /var/lib/prosody/*/accounts/*<br />
<br />
alternatively, you can download the module [http://prosody.im/files/mod_listusers.lua mod_listusers.lua], and use it as<br />
# prosodyctl mod_listusers<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Ic|# pacman -Rs prosody}}<br />
<br />
Check above for [[Prosody#Optional Dependencies|optional dependencies]] that may also be removed.<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you do not plan on reinstalling Prosody: {{ic|/etc/prosody}} and {{ic|/var/lib/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the {{Ic|VirtualHost}}s defined in {{Ic|prosody.cfg.lua}}. Attempting to host a component on the same hostname as a defined {{Ic|VirtualHost}} '''will''' result in errors.}}<br />
<br />
By default, Prosody will listen for external components. If you do not plan to use any external components with Prosody you can disable this behavior by adding the following your configuration:<br />
<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
component_ports = {}<br />
}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{hc|/etc/prosody/prosody.cfg.lua|<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host {{Ic|conference.example.com}}.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is {{Ic|[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]}}, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, {{Ic|httpserver}}).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Ic|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{ic|/usr/lib/prosody/modules}}. To enable the module add it to your {{Ic|modules_enabled}} list in your {{ic|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the {{Ic|pastebin}} module on a MUC component:<br />
<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named {{Ic|mod_''foo''.lua}} but simply enabled by adding {{Ic|''foo''}} to the {{Ic|modules_enabled}} list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the {{Ic|console}} module on a multi-user system.}}<br />
<br />
The {{Ic|console}} module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Ic|$ telnet localhost 5582}}<br />
<br />
You of course need the {{Ic|telnet}} program provided by the {{Ic|inetutils}} package. Use the {{Ic|help}} command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with {{Ic|>}}. For example to see if a client connection is compressed:<br />
<br />
{{Ic|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return {{Ic|true}} if the connection is compressed or {{Ic|nil}} if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Ic|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log'''<br>Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging.<br />
* '''Check permissions'''<br>The Prosody package should add a new {{Ic|prosody}} user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{ic|/etc/prosody}} and {{ic|/var/lib/prosody}} are owned by the {{Ic|prosody}} user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Ic|ss -tul}} and making sure that {{Ic|xmpp-client}} (port 5222) and {{Ic|xmpp-server}} (port 5269) are listed.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Ic|systemctl restart prosody}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: {{Ic|prosody@conference.prosody.im}}<br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [https://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
Two development packages are maintained for Prosody in the AUR, {{AUR|prosody-devel}} and {{AUR|prosody-hg]}}. {{Ic|prosody-devel}} tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. {{Ic|prosody-hg}} tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://hg.prosody.im/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: {{Ic|prosody@conference.prosody.im}}<br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
== See also ==<br />
<br />
* [http://prosody.im/doc Official documentation]<br />
* [http://blog.prosody.im/ Prosodical Thoughts] (Blog)<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=300245Prosody2014-02-23T14:05:14Z<p>Dbb: /* Development */</p>
<hr />
<div>[[Category:Internet Applications]]<br />
[[de:Prosody]]<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[Arch User Repository]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by {{Ic|$}} indicate that the command may be run as a regular user, while lines preceded by {{Ic|#}} indicate that the command must be run as {{Ic|root}}.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Ic|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [https://www.archlinux.org/packages/community/x86_64/lua51-sec/ lua51-sec] (Community)<br />
<br />
; Better Connection Scaling (Recommended)<br />
: Allow Prosody to use [http://www.monkey.org/~provos/libevent/ libevent] to handle a greater number of simultaneous connections.<br>''Requires:'' {{AUR|lua51-event}} (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [https://www.archlinux.org/packages/community/x86_64/lua51-zlib/ lua51-zlib] (Community)<br />
<br />
; Cyrus SASL Support<br />
: Allow Prosody to use the [http://asg.web.cmu.edu/sasl/sasl-library.html Cyrus SASL] library to provide authentication.<br>''Requires:'' {{AUR|lua-cyrussasl}} (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The {{Ic|posix}} module and {{Ic|pidfile}} setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{ic|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Ic|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to syslog. Thus, by default, Prosody log messages are available in the [[Systemd#Journal|systemd journal]].<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included Systemd script:<br />
<br />
{{Ic|# systemctl start prosody}}<br />
<br />
To automatically start Prosody at boot execute:<br />
<br />
{{Ic|# systemctl enable prosody}}<br />
<br />
Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the {{Ic|prosodyctl}} program. To add a user:<br />
<br />
{{Ic|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the {{Ic|admins}} list in the configuration file.}}<br />
<br />
Issue {{Ic|man prosodyctl}} to see the man page for {{Ic|prosodyctl}}.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the {{Ic|register}} module is enabled in the default configuration but {{Ic|allow_registration}} is set to {{Ic|false}}. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the {{Ic|watchregistrations}} and {{Ic|welcome}} modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). See the relevant sections of {{ic|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
===Listing Users===<br />
A simple way to see a list of the registered users is<br />
# ls -l /var/lib/prosody/*/accounts/*<br />
<br />
alternatively, you can download the module [http://prosody.im/files/mod_listusers.lua mod_listusers.lua], and use it as<br />
# prosodyctl mod_listusers<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Ic|# pacman -Rs prosody}}<br />
<br />
Check above for [[Prosody#Optional Dependencies|optional dependencies]] that may also be removed.<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you do not plan on reinstalling Prosody: {{ic|/etc/prosody}} and {{ic|/var/lib/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the {{Ic|VirtualHost}}s defined in {{Ic|prosody.cfg.lua}}. Attempting to host a component on the same hostname as a defined {{Ic|VirtualHost}} '''will''' result in errors.}}<br />
<br />
By default, Prosody will listen for external components. If you do not plan to use any external components with Prosody you can disable this behavior by adding the following your configuration:<br />
<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
component_ports = {}<br />
}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{hc|/etc/prosody/prosody.cfg.lua|<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host {{Ic|conference.example.com}}.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is {{Ic|[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]}}, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, {{Ic|httpserver}}).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Ic|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{ic|/usr/lib/prosody/modules}}. To enable the module add it to your {{Ic|modules_enabled}} list in your {{ic|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the {{Ic|pastebin}} module on a MUC component:<br />
<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named {{Ic|mod_''foo''.lua}} but simply enabled by adding {{Ic|''foo''}} to the {{Ic|modules_enabled}} list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the {{Ic|console}} module on a multi-user system.}}<br />
<br />
The {{Ic|console}} module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Ic|$ telnet localhost 5582}}<br />
<br />
You of course need the {{Ic|telnet}} program provided by the {{Ic|inetutils}} package. Use the {{Ic|help}} command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with {{Ic|>}}. For example to see if a client connection is compressed:<br />
<br />
{{Ic|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return {{Ic|true}} if the connection is compressed or {{Ic|nil}} if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Ic|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log'''<br>Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging.<br />
* '''Check permissions'''<br>The Prosody package should add a new {{Ic|prosody}} user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{ic|/etc/prosody}} and {{ic|/var/lib/prosody}} are owned by the {{Ic|prosody}} user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Ic|ss -tul}} and making sure that {{Ic|xmpp-client}} (port 5222) and {{Ic|xmpp-server}} (port 5269) are listed.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Ic|systemctl restart prosody}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: {{Ic|prosody@conference.prosody.im}}<br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [https://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
Two development packages are maintained for Prosody in the AUR, {{AUR|prosody-devel}} and {{AUR|prosody-hg]}}. {{Ic|prosody-devel}} tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. {{Ic|prosody-hg}} tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: {{Ic|prosody@conference.prosody.im}}<br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]<br />
<br />
== See also ==<br />
<br />
* [http://prosody.im/doc Official documentation]<br />
* [http://blog.prosody.im/ Prosodical Thoughts] (Blog)<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=300244Prosody2014-02-23T14:04:26Z<p>Dbb: /* Troubleshooting */</p>
<hr />
<div>[[Category:Internet Applications]]<br />
[[de:Prosody]]<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[Arch User Repository]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by {{Ic|$}} indicate that the command may be run as a regular user, while lines preceded by {{Ic|#}} indicate that the command must be run as {{Ic|root}}.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Ic|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [https://www.archlinux.org/packages/community/x86_64/lua51-sec/ lua51-sec] (Community)<br />
<br />
; Better Connection Scaling (Recommended)<br />
: Allow Prosody to use [http://www.monkey.org/~provos/libevent/ libevent] to handle a greater number of simultaneous connections.<br>''Requires:'' {{AUR|lua51-event}} (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [https://www.archlinux.org/packages/community/x86_64/lua51-zlib/ lua51-zlib] (Community)<br />
<br />
; Cyrus SASL Support<br />
: Allow Prosody to use the [http://asg.web.cmu.edu/sasl/sasl-library.html Cyrus SASL] library to provide authentication.<br>''Requires:'' {{AUR|lua-cyrussasl}} (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The {{Ic|posix}} module and {{Ic|pidfile}} setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{ic|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Ic|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to syslog. Thus, by default, Prosody log messages are available in the [[Systemd#Journal|systemd journal]].<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included Systemd script:<br />
<br />
{{Ic|# systemctl start prosody}}<br />
<br />
To automatically start Prosody at boot execute:<br />
<br />
{{Ic|# systemctl enable prosody}}<br />
<br />
Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the {{Ic|prosodyctl}} program. To add a user:<br />
<br />
{{Ic|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the {{Ic|admins}} list in the configuration file.}}<br />
<br />
Issue {{Ic|man prosodyctl}} to see the man page for {{Ic|prosodyctl}}.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the {{Ic|register}} module is enabled in the default configuration but {{Ic|allow_registration}} is set to {{Ic|false}}. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the {{Ic|watchregistrations}} and {{Ic|welcome}} modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). See the relevant sections of {{ic|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
===Listing Users===<br />
A simple way to see a list of the registered users is<br />
# ls -l /var/lib/prosody/*/accounts/*<br />
<br />
alternatively, you can download the module [http://prosody.im/files/mod_listusers.lua mod_listusers.lua], and use it as<br />
# prosodyctl mod_listusers<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Ic|# pacman -Rs prosody}}<br />
<br />
Check above for [[Prosody#Optional Dependencies|optional dependencies]] that may also be removed.<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you do not plan on reinstalling Prosody: {{ic|/etc/prosody}} and {{ic|/var/lib/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the {{Ic|VirtualHost}}s defined in {{Ic|prosody.cfg.lua}}. Attempting to host a component on the same hostname as a defined {{Ic|VirtualHost}} '''will''' result in errors.}}<br />
<br />
By default, Prosody will listen for external components. If you do not plan to use any external components with Prosody you can disable this behavior by adding the following your configuration:<br />
<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
component_ports = {}<br />
}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{hc|/etc/prosody/prosody.cfg.lua|<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host {{Ic|conference.example.com}}.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is {{Ic|[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]}}, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, {{Ic|httpserver}}).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Ic|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{ic|/usr/lib/prosody/modules}}. To enable the module add it to your {{Ic|modules_enabled}} list in your {{ic|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the {{Ic|pastebin}} module on a MUC component:<br />
<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named {{Ic|mod_''foo''.lua}} but simply enabled by adding {{Ic|''foo''}} to the {{Ic|modules_enabled}} list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the {{Ic|console}} module on a multi-user system.}}<br />
<br />
The {{Ic|console}} module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Ic|$ telnet localhost 5582}}<br />
<br />
You of course need the {{Ic|telnet}} program provided by the {{Ic|inetutils}} package. Use the {{Ic|help}} command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with {{Ic|>}}. For example to see if a client connection is compressed:<br />
<br />
{{Ic|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return {{Ic|true}} if the connection is compressed or {{Ic|nil}} if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Ic|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log'''<br>Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging.<br />
* '''Check permissions'''<br>The Prosody package should add a new {{Ic|prosody}} user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{ic|/etc/prosody}} and {{ic|/var/lib/prosody}} are owned by the {{Ic|prosody}} user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Ic|ss -tul}} and making sure that {{Ic|xmpp-client}} (port 5222) and {{Ic|xmpp-server}} (port 5269) are listed.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Ic|systemctl restart prosody}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: {{Ic|prosody@conference.prosody.im}}<br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [https://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Ic|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, {{AUR|prosody-devel}} and {{AUR|prosody-hg]}}. {{Ic|prosody-devel}} tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. {{Ic|prosody-hg}} tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: {{Ic|prosody@conference.prosody.im}}<br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]<br />
<br />
== See also ==<br />
<br />
* [http://prosody.im/doc Official documentation]<br />
* [http://blog.prosody.im/ Prosodical Thoughts] (Blog)<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=300220Prosody2014-02-23T13:26:36Z<p>Dbb: /* Removal */</p>
<hr />
<div>[[Category:Internet Applications]]<br />
[[de:Prosody]]<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[Arch User Repository]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by {{Ic|$}} indicate that the command may be run as a regular user, while lines preceded by {{Ic|#}} indicate that the command must be run as {{Ic|root}}.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Ic|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [https://www.archlinux.org/packages/community/x86_64/lua51-sec/ lua51-sec] (Community)<br />
<br />
; Better Connection Scaling (Recommended)<br />
: Allow Prosody to use [http://www.monkey.org/~provos/libevent/ libevent] to handle a greater number of simultaneous connections.<br>''Requires:'' {{AUR|lua51-event}} (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [https://www.archlinux.org/packages/community/x86_64/lua51-zlib/ lua51-zlib] (Community)<br />
<br />
; Cyrus SASL Support<br />
: Allow Prosody to use the [http://asg.web.cmu.edu/sasl/sasl-library.html Cyrus SASL] library to provide authentication.<br>''Requires:'' {{AUR|lua-cyrussasl}} (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The {{Ic|posix}} module and {{Ic|pidfile}} setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{ic|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Ic|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to syslog. Thus, by default, Prosody log messages are available in the [[Systemd#Journal|systemd journal]].<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included Systemd script:<br />
<br />
{{Ic|# systemctl start prosody}}<br />
<br />
To automatically start Prosody at boot execute:<br />
<br />
{{Ic|# systemctl enable prosody}}<br />
<br />
Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the {{Ic|prosodyctl}} program. To add a user:<br />
<br />
{{Ic|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the {{Ic|admins}} list in the configuration file.}}<br />
<br />
Issue {{Ic|man prosodyctl}} to see the man page for {{Ic|prosodyctl}}.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the {{Ic|register}} module is enabled in the default configuration but {{Ic|allow_registration}} is set to {{Ic|false}}. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the {{Ic|watchregistrations}} and {{Ic|welcome}} modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). See the relevant sections of {{ic|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
===Listing Users===<br />
A simple way to see a list of the registered users is<br />
# ls -l /var/lib/prosody/*/accounts/*<br />
<br />
alternatively, you can download the module [http://prosody.im/files/mod_listusers.lua mod_listusers.lua], and use it as<br />
# prosodyctl mod_listusers<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Ic|# pacman -Rs prosody}}<br />
<br />
Check above for [[Prosody#Optional Dependencies|optional dependencies]] that may also be removed.<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you do not plan on reinstalling Prosody: {{ic|/etc/prosody}} and {{ic|/var/lib/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the {{Ic|VirtualHost}}s defined in {{Ic|prosody.cfg.lua}}. Attempting to host a component on the same hostname as a defined {{Ic|VirtualHost}} '''will''' result in errors.}}<br />
<br />
By default, Prosody will listen for external components. If you do not plan to use any external components with Prosody you can disable this behavior by adding the following your configuration:<br />
<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
component_ports = {}<br />
}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{hc|/etc/prosody/prosody.cfg.lua|<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host {{Ic|conference.example.com}}.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is {{Ic|[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]}}, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, {{Ic|httpserver}}).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Ic|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{ic|/usr/lib/prosody/modules}}. To enable the module add it to your {{Ic|modules_enabled}} list in your {{ic|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the {{Ic|pastebin}} module on a MUC component:<br />
<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named {{Ic|mod_''foo''.lua}} but simply enabled by adding {{Ic|''foo''}} to the {{Ic|modules_enabled}} list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the {{Ic|console}} module on a multi-user system.}}<br />
<br />
The {{Ic|console}} module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Ic|$ telnet localhost 5582}}<br />
<br />
You of course need the {{Ic|telnet}} program provided by the {{Ic|inetutils}} package. Use the {{Ic|help}} command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with {{Ic|>}}. For example to see if a client connection is compressed:<br />
<br />
{{Ic|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return {{Ic|true}} if the connection is compressed or {{Ic|nil}} if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Ic|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{ic|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{ic|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new {{Ic|prosody}} user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{ic|/etc/prosody}} and {{ic|/var/lib/prosody}} are owned by the {{Ic|prosody}} user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Ic|ss -tul}} and making sure that {{Ic|xmpp-client}} (port 5222) and {{Ic|xmpp-server}} (port 5269) are listed.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Ic|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: {{Ic|prosody@conference.prosody.im}}<br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [https://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Ic|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, {{AUR|prosody-devel}} and {{AUR|prosody-hg]}}. {{Ic|prosody-devel}} tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. {{Ic|prosody-hg}} tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: {{Ic|prosody@conference.prosody.im}}<br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]<br />
<br />
== See also ==<br />
<br />
* [http://prosody.im/doc Official documentation]<br />
* [http://blog.prosody.im/ Prosodical Thoughts] (Blog)<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=300219Prosody2014-02-23T13:18:10Z<p>Dbb: /* Configuration */</p>
<hr />
<div>[[Category:Internet Applications]]<br />
[[de:Prosody]]<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[Arch User Repository]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by {{Ic|$}} indicate that the command may be run as a regular user, while lines preceded by {{Ic|#}} indicate that the command must be run as {{Ic|root}}.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Ic|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [https://www.archlinux.org/packages/community/x86_64/lua51-sec/ lua51-sec] (Community)<br />
<br />
; Better Connection Scaling (Recommended)<br />
: Allow Prosody to use [http://www.monkey.org/~provos/libevent/ libevent] to handle a greater number of simultaneous connections.<br>''Requires:'' {{AUR|lua51-event}} (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [https://www.archlinux.org/packages/community/x86_64/lua51-zlib/ lua51-zlib] (Community)<br />
<br />
; Cyrus SASL Support<br />
: Allow Prosody to use the [http://asg.web.cmu.edu/sasl/sasl-library.html Cyrus SASL] library to provide authentication.<br>''Requires:'' {{AUR|lua-cyrussasl}} (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The {{Ic|posix}} module and {{Ic|pidfile}} setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{ic|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Ic|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to syslog. Thus, by default, Prosody log messages are available in the [[Systemd#Journal|systemd journal]].<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included Systemd script:<br />
<br />
{{Ic|# systemctl start prosody}}<br />
<br />
To automatically start Prosody at boot execute:<br />
<br />
{{Ic|# systemctl enable prosody}}<br />
<br />
Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the {{Ic|prosodyctl}} program. To add a user:<br />
<br />
{{Ic|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the {{Ic|admins}} list in the configuration file.}}<br />
<br />
Issue {{Ic|man prosodyctl}} to see the man page for {{Ic|prosodyctl}}.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the {{Ic|register}} module is enabled in the default configuration but {{Ic|allow_registration}} is set to {{Ic|false}}. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the {{Ic|watchregistrations}} and {{Ic|welcome}} modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). See the relevant sections of {{ic|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
===Listing Users===<br />
A simple way to see a list of the registered users is<br />
# ls -l /var/lib/prosody/*/accounts/*<br />
<br />
alternatively, you can download the module [http://prosody.im/files/mod_listusers.lua mod_listusers.lua], and use it as<br />
# prosodyctl mod_listusers<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Ic|# pacman -Rs prosody}}<br />
<br />
Check above for [[Prosody#Optional Dependencies|optional dependencies]] that may also be removed.<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you do not plan on reinstalling Prosody: {{ic|/etc/prosody}}, {{ic|/var/lib/prosody}}, {{ic|/var/log/prosody}}, and {{ic|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the {{Ic|VirtualHost}}s defined in {{Ic|prosody.cfg.lua}}. Attempting to host a component on the same hostname as a defined {{Ic|VirtualHost}} '''will''' result in errors.}}<br />
<br />
By default, Prosody will listen for external components. If you do not plan to use any external components with Prosody you can disable this behavior by adding the following your configuration:<br />
<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
component_ports = {}<br />
}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{hc|/etc/prosody/prosody.cfg.lua|<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host {{Ic|conference.example.com}}.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is {{Ic|[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]}}, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, {{Ic|httpserver}}).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Ic|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{ic|/usr/lib/prosody/modules}}. To enable the module add it to your {{Ic|modules_enabled}} list in your {{ic|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the {{Ic|pastebin}} module on a MUC component:<br />
<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named {{Ic|mod_''foo''.lua}} but simply enabled by adding {{Ic|''foo''}} to the {{Ic|modules_enabled}} list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the {{Ic|console}} module on a multi-user system.}}<br />
<br />
The {{Ic|console}} module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Ic|$ telnet localhost 5582}}<br />
<br />
You of course need the {{Ic|telnet}} program provided by the {{Ic|inetutils}} package. Use the {{Ic|help}} command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with {{Ic|>}}. For example to see if a client connection is compressed:<br />
<br />
{{Ic|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return {{Ic|true}} if the connection is compressed or {{Ic|nil}} if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Ic|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{ic|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{ic|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new {{Ic|prosody}} user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{ic|/etc/prosody}} and {{ic|/var/lib/prosody}} are owned by the {{Ic|prosody}} user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Ic|ss -tul}} and making sure that {{Ic|xmpp-client}} (port 5222) and {{Ic|xmpp-server}} (port 5269) are listed.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Ic|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: {{Ic|prosody@conference.prosody.im}}<br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [https://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Ic|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, {{AUR|prosody-devel}} and {{AUR|prosody-hg]}}. {{Ic|prosody-devel}} tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. {{Ic|prosody-hg}} tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: {{Ic|prosody@conference.prosody.im}}<br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]<br />
<br />
== See also ==<br />
<br />
* [http://prosody.im/doc Official documentation]<br />
* [http://blog.prosody.im/ Prosodical Thoughts] (Blog)<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=300218Prosody2014-02-23T13:12:51Z<p>Dbb: </p>
<hr />
<div>[[Category:Internet Applications]]<br />
[[de:Prosody]]<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[Arch User Repository]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by {{Ic|$}} indicate that the command may be run as a regular user, while lines preceded by {{Ic|#}} indicate that the command must be run as {{Ic|root}}.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Ic|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [https://www.archlinux.org/packages/community/x86_64/lua51-sec/ lua51-sec] (Community)<br />
<br />
; Better Connection Scaling (Recommended)<br />
: Allow Prosody to use [http://www.monkey.org/~provos/libevent/ libevent] to handle a greater number of simultaneous connections.<br>''Requires:'' {{AUR|lua51-event}} (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [https://www.archlinux.org/packages/community/x86_64/lua51-zlib/ lua51-zlib] (Community)<br />
<br />
; Cyrus SASL Support<br />
: Allow Prosody to use the [http://asg.web.cmu.edu/sasl/sasl-library.html Cyrus SASL] library to provide authentication.<br>''Requires:'' {{AUR|lua-cyrussasl}} (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The {{Ic|posix}} module and {{Ic|pidfile}} setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{ic|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Ic|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{ic|/var/log/prosody/prosody.err}} and {{ic|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{ic|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the {{Ic|olddir}} path for rotated log files in {{ic|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Ic|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the {{Ic|olddir}} line in {{ic|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included Systemd script:<br />
<br />
{{Ic|# systemctl start prosody}}<br />
<br />
To automatically start Prosody at boot execute:<br />
<br />
{{Ic|# systemctl enable prosody}}<br />
<br />
Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the {{Ic|prosodyctl}} program. To add a user:<br />
<br />
{{Ic|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the {{Ic|admins}} list in the configuration file.}}<br />
<br />
Issue {{Ic|man prosodyctl}} to see the man page for {{Ic|prosodyctl}}.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the {{Ic|register}} module is enabled in the default configuration but {{Ic|allow_registration}} is set to {{Ic|false}}. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the {{Ic|watchregistrations}} and {{Ic|welcome}} modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). See the relevant sections of {{ic|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
===Listing Users===<br />
A simple way to see a list of the registered users is<br />
# ls -l /var/lib/prosody/*/accounts/*<br />
<br />
alternatively, you can download the module [http://prosody.im/files/mod_listusers.lua mod_listusers.lua], and use it as<br />
# prosodyctl mod_listusers<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Ic|# pacman -Rs prosody}}<br />
<br />
Check above for [[Prosody#Optional Dependencies|optional dependencies]] that may also be removed.<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you do not plan on reinstalling Prosody: {{ic|/etc/prosody}}, {{ic|/var/lib/prosody}}, {{ic|/var/log/prosody}}, and {{ic|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the {{Ic|VirtualHost}}s defined in {{Ic|prosody.cfg.lua}}. Attempting to host a component on the same hostname as a defined {{Ic|VirtualHost}} '''will''' result in errors.}}<br />
<br />
By default, Prosody will listen for external components. If you do not plan to use any external components with Prosody you can disable this behavior by adding the following your configuration:<br />
<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
component_ports = {}<br />
}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{hc|/etc/prosody/prosody.cfg.lua|<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host {{Ic|conference.example.com}}.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is {{Ic|[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]}}, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, {{Ic|httpserver}}).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Ic|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{ic|/usr/lib/prosody/modules}}. To enable the module add it to your {{Ic|modules_enabled}} list in your {{ic|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the {{Ic|pastebin}} module on a MUC component:<br />
<br />
{{hc|/etc/prosody/prosody.cfg.lua|2=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named {{Ic|mod_''foo''.lua}} but simply enabled by adding {{Ic|''foo''}} to the {{Ic|modules_enabled}} list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the {{Ic|console}} module on a multi-user system.}}<br />
<br />
The {{Ic|console}} module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Ic|$ telnet localhost 5582}}<br />
<br />
You of course need the {{Ic|telnet}} program provided by the {{Ic|inetutils}} package. Use the {{Ic|help}} command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with {{Ic|>}}. For example to see if a client connection is compressed:<br />
<br />
{{Ic|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return {{Ic|true}} if the connection is compressed or {{Ic|nil}} if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Ic|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{ic|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{ic|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new {{Ic|prosody}} user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{ic|/etc/prosody}} and {{ic|/var/lib/prosody}} are owned by the {{Ic|prosody}} user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Ic|ss -tul}} and making sure that {{Ic|xmpp-client}} (port 5222) and {{Ic|xmpp-server}} (port 5269) are listed.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Ic|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: {{Ic|prosody@conference.prosody.im}}<br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [https://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Ic|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, {{AUR|prosody-devel}} and {{AUR|prosody-hg]}}. {{Ic|prosody-devel}} tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. {{Ic|prosody-hg}} tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: {{Ic|prosody@conference.prosody.im}}<br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]<br />
<br />
== See also ==<br />
<br />
* [http://prosody.im/doc Official documentation]<br />
* [http://blog.prosody.im/ Prosodical Thoughts] (Blog)<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=163252Prosody2011-10-02T01:52:01Z<p>Dbb: /* Optional Dependencies */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
{{i18n|Prosody}}<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by {{Codeline|$}} indicate that the command may be run as a regular user, while lines preceded by {{Codeline|#}} indicate that the command must be run as {{Codeline|root}}.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Codeline|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://www.archlinux.org/packages/community/x86_64/luasec/ luasec] (Community)<br />
<br />
; Better Connection Scaling (Recommended)<br />
: Allow Prosody to use [http://www.monkey.org/~provos/libevent/ libevent] to handle a greater number of simultaneous connections.<br>''Requires:'' {{Package AUR|luaevent}} (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [http://www.archlinux.org/packages/community/x86_64/lua-zlib/ lua-zlib] (Community)<br />
<br />
; Cyrus SASL Support<br />
: Allow Prosody to use the [http://asg.web.cmu.edu/sasl/sasl-library.html Cyrus SASL] library to provide authentication.<br>''Requires:'' {{Package AUR|lua-cyrussasl}} (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The {{Codeline|posix}} module and {{Codeline|pidfile}} setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the {{Codeline|olddir}} path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the {{Codeline|olddir}} line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add {{Codeline|prosody}} to your {{Codeline|DAEMONS}} array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the {{Codeline|prosodyctl}} program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the {{Codeline|admins}} list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for {{Codeline|prosodyctl}}.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the {{Codeline|register}} module is enabled in the default configuration but {{Codeline|allow_registration}} is set to {{Codeline|false}}. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the {{Codeline|watchregistrations}} and {{Codeline|welcome}} modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
Check above for [[Prosody#Optional Dependencies|optional dependencies]] that may also be removed.<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the {{Codeline|VirtualHost}}s defined in {{Codeline|prosody.cfg.lua}}. Attempting to host a component on the same hostname as a defined {{Codeline|VirtualHost}} '''will''' result in errors.}}<br />
<br />
By default, Prosody will listen for external components. If you do not plan to use any external components with Prosody you can disable this behavior by adding the following your configuration:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
component_ports = {}<br />
}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host {{Codeline|conference.example.com}}.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is {{Codeline|[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]}}, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, {{Codeline|httpserver}}).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your {{Codeline|modules_enabled}} list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the {{Codeline|pastebin}} module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named {{Codeline|mod_''foo''.lua}} but simply enabled by adding {{Codeline|''foo''}} to the {{Codeline|modules_enabled}} list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the {{Codeline|console}} module on a multi-user system.}}<br />
<br />
The {{Codeline|console}} module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the {{Codeline|telnet}} program provided by the {{Codeline|inetutils}} package. Use the {{Codeline|help}} command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with {{Codeline|>}}. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return {{Codeline|true}} if the connection is compressed or {{Codeline|nil}} if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new {{Codeline|prosody}} user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the {{Codeline|prosody}} user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that {{Codeline|xmpp-client}} (port 5222) and {{Codeline|xmpp-server}} (port 5269) are listed.<br>Note: the {{Codeline|netstat}} command is part of the {{Codeline|net-tools}} package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: {{Codeline|prosody@conference.prosody.im}}<br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, {{Package AUR|prosody-devel}} and {{Package AUR|prosody-hg]}}. {{Codeline|prosody-devel}} tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. {{Codeline|prosody-hg}} tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: {{Codeline|prosody@conference.prosody.im}}<br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=151777Prosody2011-08-13T13:43:49Z<p>Dbb: /* Components */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Codeline|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://www.archlinux.org/packages/community/x86_64/luasec/ luasec] (Community)<br />
<br />
; Better Connection Scaling (Recommended)<br />
: Allow Prosody to use [http://www.monkey.org/~provos/libevent/ libevent] to handle a greater number of simultaneous connections.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=49437 luaevent] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [http://www.archlinux.org/packages/community/x86_64/lua-zlib/ lua-zlib] (Community)<br />
<br />
; Cyrus SASL Support<br />
: Allow Prosody to use the [http://asg.web.cmu.edu/sasl/sasl-library.html Cyrus SASL] library to provide authentication.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34655 lua-cyrussasl-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
Check above for [[Prosody#Optional Dependencies|optional dependencies]] that may also be removed.<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>VirtualHost</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>VirtualHost</tt> '''will''' result in errors.}}<br />
<br />
By default, Prosody will listen for external components. If you do not plan to use any external components with Prosody you can disable this behavior by adding the following your configuration:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
component_ports = {}<br />
}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=151776Prosody2011-08-13T13:42:32Z<p>Dbb: /* Removal */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Codeline|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://www.archlinux.org/packages/community/x86_64/luasec/ luasec] (Community)<br />
<br />
; Better Connection Scaling (Recommended)<br />
: Allow Prosody to use [http://www.monkey.org/~provos/libevent/ libevent] to handle a greater number of simultaneous connections.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=49437 luaevent] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [http://www.archlinux.org/packages/community/x86_64/lua-zlib/ lua-zlib] (Community)<br />
<br />
; Cyrus SASL Support<br />
: Allow Prosody to use the [http://asg.web.cmu.edu/sasl/sasl-library.html Cyrus SASL] library to provide authentication.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34655 lua-cyrussasl-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
Check above for [[Prosody#Optional Dependencies|optional dependencies]] that may also be removed.<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
By default, Prosody will listen for external components. If you do not plan to use any external components with Prosody you can disable this behavior by adding the following your configuration:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
component_ports = {}<br />
}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=143166Prosody2011-05-30T00:07:14Z<p>Dbb: /* Optional Dependencies */ New package</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Codeline|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://www.archlinux.org/packages/community/x86_64/luasec/ luasec] (Community)<br />
<br />
; Better Connection Scaling (Recommended)<br />
: Allow Prosody to use [http://www.monkey.org/~provos/libevent/ libevent] to handle a greater number of simultaneous connections.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=49437 luaevent] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [http://www.archlinux.org/packages/community/x86_64/lua-zlib/ lua-zlib] (Community)<br />
<br />
; Cyrus SASL Support<br />
: Allow Prosody to use the [http://asg.web.cmu.edu/sasl/sasl-library.html Cyrus SASL] library to provide authentication.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34655 lua-cyrussasl-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib-git lua-cyrussasl-git}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
By default, Prosody will listen for external components. If you do not plan to use any external components with Prosody you can disable this behavior by adding the following your configuration:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
component_ports = {}<br />
}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=109280Prosody2010-06-21T23:45:08Z<p>Dbb: /* Optional Dependencies */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Codeline|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://www.archlinux.org/packages/community/x86_64/luasec/ luasec] (Community)<br />
<br />
; Better Connection Scaling (Recommended)<br />
: Allow Prosody to use [http://www.monkey.org/~provos/libevent/ libevent] to handle a greater number of simultaneous connections.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34658 luaevent-prosody] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [http://www.archlinux.org/packages/community/x86_64/lua-zlib/ lua-zlib] (Community)<br />
<br />
; Cyrus SASL Support<br />
: Allow Prosody to use the [http://asg.web.cmu.edu/sasl/sasl-library.html Cyrus SASL] library to provide authentication.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34655 lua-cryussasl-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib-git lua-cyrussasl-git}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
By default, Prosody will listen for external components. If you do not plan to use any external components with Prosody you can disable this behavior by adding the following your configuration:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
component_ports = {}<br />
}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=109279Prosody2010-06-21T23:44:40Z<p>Dbb: /* Optional Dependencies */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Codeline|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://www.archlinux.org/packages/community/x86_64/luasec/ luasec] (Community)<br />
<br />
; Better Connection Scaling (Recommended)<br />
: Allow Prosody to use [http://www.monkey.org/~provos/libevent/ libevent] to handle a greater number of simultaneous connections.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34658 luaevent-prosody] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [http://www.archlinux.org/packages/community/x86_64/lua-zlib/ lua-zlib-git] (Community)<br />
<br />
; Cyrus SASL Support<br />
: Allow Prosody to use the [http://asg.web.cmu.edu/sasl/sasl-library.html Cyrus SASL] library to provide authentication.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34655 lua-cryussasl-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib-git lua-cyrussasl-git}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
By default, Prosody will listen for external components. If you do not plan to use any external components with Prosody you can disable this behavior by adding the following your configuration:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
component_ports = {}<br />
}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=107573Prosody2010-05-29T13:35:05Z<p>Dbb: /* Optional Dependencies */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Codeline|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Better Connection Scaling (Recommended)<br />
: Allow Prosody to use [http://www.monkey.org/~provos/libevent/ libevent] to handle a greater number of simultaneous connections.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34658 luaevent-prosody] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34654 lua-zlib-git] (AUR)<br />
<br />
; Cyrus SASL Support<br />
: Allow Prosody to use the [http://asg.web.cmu.edu/sasl/sasl-library.html Cyrus SASL] library to provide authentication.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34655 lua-cryussasl-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib-git lua-cyrussasl-git}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
By default, Prosody will listen for external components. If you do not plan to use any external components with Prosody you can disable this behavior by adding the following your configuration:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
component_ports = {}<br />
}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=105263Prosody2010-05-02T20:51:07Z<p>Dbb: /* Source */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Codeline|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34654 lua-zlib-git] (AUR)<br />
<br />
; Cyrus SASL Support<br />
: Allow Prosody to use the [http://asg.web.cmu.edu/sasl/sasl-library.html Cyrus SASL] library to provide authentication.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34655 lua-cryussasl-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib-git lua-cyrussasl-git}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
By default, Prosody will listen for external components. If you do not plan to use any external components with Prosody you can disable this behavior by adding the following your configuration:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
component_ports = {}<br />
}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=105262Prosody2010-05-02T20:50:01Z<p>Dbb: /* Components */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Codeline|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34654 lua-zlib-git] (AUR)<br />
<br />
; Cyrus SASL Support<br />
: Allow Prosody to use the [http://asg.web.cmu.edu/sasl/sasl-library.html Cyrus SASL] library to provide authentication.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34655 lua-cryussasl-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib-git lua-cyrussasl-git}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
By default, Prosody will listen for external components. If you do not plan to use any external components with Prosody you can disable this behavior by adding the following your configuration:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
component_ports = {}<br />
}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=105261Prosody2010-05-02T20:49:52Z<p>Dbb: /* Components */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Codeline|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34654 lua-zlib-git] (AUR)<br />
<br />
; Cyrus SASL Support<br />
: Allow Prosody to use the [http://asg.web.cmu.edu/sasl/sasl-library.html Cyrus SASL] library to provide authentication.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34655 lua-cryussasl-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib-git lua-cyrussasl-git}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
By default Prosody will listen for external components. If you do not plan to use any external components with Prosody you can disable this behavior by adding the following your configuration:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
component_ports = {}<br />
}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=105260Prosody2010-05-02T20:49:38Z<p>Dbb: /* Components */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Codeline|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34654 lua-zlib-git] (AUR)<br />
<br />
; Cyrus SASL Support<br />
: Allow Prosody to use the [http://asg.web.cmu.edu/sasl/sasl-library.html Cyrus SASL] library to provide authentication.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34655 lua-cryussasl-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib-git lua-cyrussasl-git}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
By default Prosody will listen or external components. If you do not plan to use any external components with Prosody you can disable this behavior by adding the following your configuration:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
component_ports = {}<br />
}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=105259Prosody2010-05-02T20:46:47Z<p>Dbb: /* Removal */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Codeline|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34654 lua-zlib-git] (AUR)<br />
<br />
; Cyrus SASL Support<br />
: Allow Prosody to use the [http://asg.web.cmu.edu/sasl/sasl-library.html Cyrus SASL] library to provide authentication.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34655 lua-cryussasl-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib-git lua-cyrussasl-git}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=105258Prosody2010-05-02T20:46:17Z<p>Dbb: /* Stream Encryption */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Codeline|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34654 lua-zlib-git] (AUR)<br />
<br />
; Cyrus SASL Support<br />
: Allow Prosody to use the [http://asg.web.cmu.edu/sasl/sasl-library.html Cyrus SASL] library to provide authentication.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34655 lua-cryussasl-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib-git}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=105257Prosody2010-05-02T20:45:55Z<p>Dbb: /* Stream Encryption */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Codeline|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34654 lua-zlib-git] (AUR)<br />
<br />
; Cyrus SASL Support<br />
: Allow Prosody to use the [http://asg.web.cmu.edu/sasl/sasl-library.html Cyrus SASL] library to provide authentication.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34655 lua-cryussasl-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib-git}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=105256Prosody2010-05-02T20:43:52Z<p>Dbb: </p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Codeline|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34654 lua-zlib-git] (AUR)<br />
<br />
; Cyrus SASL Support<br />
: Allow Prosody to use the [http://asg.web.cmu.edu/sasl/sasl-library.html Cyrus SASL] library to provide authentication.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34655 lua-cryussasl-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib-git}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=105255Prosody2010-05-02T20:42:21Z<p>Dbb: /* Optional Dependencies */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Codeline|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34654 lua-zlib-git] (AUR)<br />
<br />
; Cyrus SASL Support<br />
: Allow Prosody to use the Cyrus SASL library to provide authentication.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34655 lua-cryussasl-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib-git}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=105254Prosody2010-05-02T20:39:29Z<p>Dbb: /* Installation */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
<br />
{{Codeline|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34654 lua-zlib-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib-git}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=105253Prosody2010-05-02T20:39:14Z<p>Dbb: /* Installation */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Prosody is available in the Community repository, and is straightforward to install via pacman:<br />
{{Codeline|# pacman -S prosody}}<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR. If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34654 lua-zlib-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib-git}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=105252Prosody2010-05-02T20:36:32Z<p>Dbb: </p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies available from the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Installation of Prosody on Arch Linux requires building Prosody and one of its dependencies, [http://aur.archlinux.org/packages.php?ID=13509 luaexpat], from the AUR (the remaining required dependencies are available in the main Arch Linux repositories). Use whatever method (yaourt, aurbuild, etc.) you prefer to download, build, and install luaexpat and Prosody from the AUR.<br />
<br />
If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR.<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34654 lua-zlib-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib-git}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=105251Prosody2010-05-02T20:36:08Z<p>Dbb: </p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux in the Community repository with some optional dependencies packages found in the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Installation of Prosody on Arch Linux requires building Prosody and one of its dependencies, [http://aur.archlinux.org/packages.php?ID=13509 luaexpat], from the AUR (the remaining required dependencies are available in the main Arch Linux repositories). Use whatever method (yaourt, aurbuild, etc.) you prefer to download, build, and install luaexpat and Prosody from the AUR.<br />
<br />
If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR.<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34654 lua-zlib-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib-git}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=99723Prosody2010-03-12T00:10:56Z<p>Dbb: /* Removal */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux from packages found in the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Installation of Prosody on Arch Linux requires building Prosody and one of its dependencies, [http://aur.archlinux.org/packages.php?ID=13509 luaexpat], from the AUR (the remaining required dependencies are available in the main Arch Linux repositories). Use whatever method (yaourt, aurbuild, etc.) you prefer to download, build, and install luaexpat and Prosody from the AUR.<br />
<br />
If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR.<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34654 lua-zlib-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib-git}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=99722Prosody2010-03-12T00:09:48Z<p>Dbb: /* Stream Encryption */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux from packages found in the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Installation of Prosody on Arch Linux requires building Prosody and one of its dependencies, [http://aur.archlinux.org/packages.php?ID=13509 luaexpat], from the AUR (the remaining required dependencies are available in the main Arch Linux repositories). Use whatever method (yaourt, aurbuild, etc.) you prefer to download, build, and install luaexpat and Prosody from the AUR.<br />
<br />
If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR.<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34654 lua-zlib-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper [[#Optional_Dependencies|dependencies]] are installed). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=99721Prosody2010-03-12T00:07:42Z<p>Dbb: /* Optional Dependencies */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux from packages found in the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Installation of Prosody on Arch Linux requires building Prosody and one of its dependencies, [http://aur.archlinux.org/packages.php?ID=13509 luaexpat], from the AUR (the remaining required dependencies are available in the main Arch Linux repositories). Use whatever method (yaourt, aurbuild, etc.) you prefer to download, build, and install luaexpat and Prosody from the AUR.<br />
<br />
If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR.<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatible clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34654 lua-zlib-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper dependencies are installed, see [[#Optional_Dependencies|above]]). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=98417Prosody2010-02-27T15:28:37Z<p>Dbb: /* Components */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux from packages found in the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Installation of Prosody on Arch Linux requires building Prosody and one of its dependencies, [http://aur.archlinux.org/packages.php?ID=13509 luaexpat], from the AUR (the remaining required dependencies are available in the main Arch Linux repositories). Use whatever method (yaourt, aurbuild, etc.) you prefer to download, build, and install luaexpat and Prosody from the AUR.<br />
<br />
If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR.<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatbile clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34654 lua-zlib-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper dependencies are installed, see [[#Optional_Dependencies|above]]). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules or externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=97041Prosody2010-02-15T22:28:32Z<p>Dbb: /* Optional Dependencies */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux from packages found in the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Installation of Prosody on Arch Linux requires building Prosody and one of its dependencies, [http://aur.archlinux.org/packages.php?ID=13509 luaexpat], from the AUR (the remaining required dependencies are available in the main Arch Linux repositories). Use whatever method (yaourt, aurbuild, etc.) you prefer to download, build, and install luaexpat and Prosody from the AUR.<br />
<br />
If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR.<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatbile clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=34654 lua-zlib-git] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper dependencies are installed, see [[#Optional_Dependencies|above]]). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules are externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=97040Prosody2010-02-15T22:25:53Z<p>Dbb: /* Components */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux from packages found in the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Installation of Prosody on Arch Linux requires building Prosody and one of its dependencies, [http://aur.archlinux.org/packages.php?ID=13509 luaexpat], from the AUR (the remaining required dependencies are available in the main Arch Linux repositories). Use whatever method (yaourt, aurbuild, etc.) you prefer to download, build, and install luaexpat and Prosody from the AUR.<br />
<br />
If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR.<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatbile clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=32246 lua-zlib] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper dependencies are installed, see [[#Optional_Dependencies|above]]). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules are externally using the protocol specified in [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=97039Prosody2010-02-15T22:25:29Z<p>Dbb: /* Tips & Tricks */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux from packages found in the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Installation of Prosody on Arch Linux requires building Prosody and one of its dependencies, [http://aur.archlinux.org/packages.php?ID=13509 luaexpat], from the AUR (the remaining required dependencies are available in the main Arch Linux repositories). Use whatever method (yaourt, aurbuild, etc.) you prefer to download, build, and install luaexpat and Prosody from the AUR.<br />
<br />
If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR.<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatbile clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=32246 lua-zlib] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper dependencies are installed, see [[#Optional_Dependencies|above]]). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Components===<br />
Prosody supports XMPP components, which provide extra services to clients. Components are either provided internally by special Prosody modules are externally using the protocol specified [http://xmpp.org/extensions/xep-0114.html XEP-0114].<br />
<br />
{{Note|Components must use a different hostname from the <tt>Host</tt>s defined in <tt>prosody.cfg.lua</tt>. Attempting to host a component on the same hostname as a defined <tt>Host</tt> '''will''' result in errors.}}<br />
<br />
====Multi-User Chat====<br />
A common component used with XMPP servers is Multi-User Chat (MUC), which allows conferences between multiple users. MUC is provided as an internal component with Prosody. To enable MUC add the following to your configuration file:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
}}<br />
<br />
This will enable the MUC component on host <tt>conference.example.com</tt>.<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=97017Prosody2010-02-15T18:08:26Z<p>Dbb: /* Troubleshooting */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux from packages found in the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Installation of Prosody on Arch Linux requires building Prosody and one of its dependencies, [http://aur.archlinux.org/packages.php?ID=13509 luaexpat], from the AUR (the remaining required dependencies are available in the main Arch Linux repositories). Use whatever method (yaourt, aurbuild, etc.) you prefer to download, build, and install luaexpat and Prosody from the AUR.<br />
<br />
If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR.<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatbile clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=32246 lua-zlib] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper dependencies are installed, see [[#Optional_Dependencies|above]]). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by running {{Codeline|netstat -tul}} and making sure that <tt>xmpp-client</tt> (port 5222) and <tt>xmpp-server</tt> (port 5269) are listed.<br>Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=90731Prosody2010-01-02T18:14:11Z<p>Dbb: /* Tips & Tricks */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux from packages found in the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Installation of Prosody on Arch Linux requires building Prosody and one of its dependencies, [http://aur.archlinux.org/packages.php?ID=13509 luaexpat], from the AUR (the remaining required dependencies are available in the main Arch Linux repositories). Use whatever method (yaourt, aurbuild, etc.) you prefer to download, build, and install luaexpat and Prosody from the AUR.<br />
<br />
If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR.<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatbile clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=32246 lua-zlib] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper dependencies are installed, see [[#Optional_Dependencies|above]]). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by issuing the following command and checking that the output matches your own:{{Command|name=netstat -tul|output=<br />
Proto Recv-Q Send-Q Local Address Foreign Address State<br />
tcp 0 0 *:xmpp-client *:* LISTEN<br />
tcp 0 0 *:xmpp-server *:* LISTEN<br />
}} Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=89190Prosody2009-12-28T22:17:12Z<p>Dbb: /* Optional Dependencies */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux from packages found in the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Installation of Prosody on Arch Linux requires building Prosody and one of its dependencies, [http://aur.archlinux.org/packages.php?ID=13509 luaexpat], from the AUR (the remaining required dependencies are available in the main Arch Linux repositories). Use whatever method (yaourt, aurbuild, etc.) you prefer to download, build, and install luaexpat and Prosody from the AUR.<br />
<br />
If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR.<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression<br />
: Allow Prosody to compress client-to-server streams for compatbile clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=32246 lua-zlib] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper dependencies are installed, see [[#Optional_Dependencies|above]]). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
{{Tip|If you like Prosody remember to show your support and vote for the package in the AUR.}}<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by issuing the following command and checking that the output matches your own:{{Command|name=netstat -tul|output=<br />
Proto Recv-Q Send-Q Local Address Foreign Address State<br />
tcp 0 0 *:xmpp-client *:* LISTEN<br />
tcp 0 0 *:xmpp-server *:* LISTEN<br />
}} Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=85407Prosody2009-11-26T18:18:04Z<p>Dbb: </p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. It covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux from packages found in the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Installation of Prosody on Arch Linux requires building Prosody and one of its dependencies, [http://aur.archlinux.org/packages.php?ID=13509 luaexpat], from the AUR (the remaining required dependencies are available in the main Arch Linux repositories). Use whatever method (yaourt, aurbuild, etc.) you prefer to download, build, and install luaexpat and Prosody from the AUR.<br />
<br />
If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR.<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression (Recommended)<br />
: Allow Prosody to compress client-to-server streams for compatbile clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=32246 lua-zlib] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper dependencies are installed, see [[#Optional_Dependencies|above]]). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
{{Tip|If you like Prosody remember to show your support and vote for the package in the AUR.}}<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by issuing the following command and checking that the output matches your own:{{Command|name=netstat -tul|output=<br />
Proto Recv-Q Send-Q Local Address Foreign Address State<br />
tcp 0 0 *:xmpp-client *:* LISTEN<br />
tcp 0 0 *:xmpp-server *:* LISTEN<br />
}} Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=85389Prosody2009-11-26T17:22:40Z<p>Dbb: /* Source */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. This article covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux from packages found in the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Installation of Prosody on Arch Linux requires building Prosody and one of its dependencies, [http://aur.archlinux.org/packages.php?ID=13509 luaexpat], from the AUR (the remaining required dependencies are available in the main Arch Linux repositories). Use whatever method (yaourt, aurbuild, etc.) you prefer to download, build, and install luaexpat and Prosody from the AUR.<br />
<br />
If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR.<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression (Recommended)<br />
: Allow Prosody to compress client-to-server streams for compatbile clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=32246 lua-zlib] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper dependencies are installed, see [[#Optional_Dependencies|above]]). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
{{Tip|If you like Prosody remember to show your support and vote for the package in the AUR.}}<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by issuing the following command and checking that the output matches your own:{{Command|name=netstat -tul|output=<br />
Proto Recv-Q Send-Q Local Address Foreign Address State<br />
tcp 0 0 *:xmpp-client *:* LISTEN<br />
tcp 0 0 *:xmpp-server *:* LISTEN<br />
}} Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
{{Codeline|$ hg clone http://code.liqd.org/packages/prosody/}}<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=85388Prosody2009-11-26T17:22:18Z<p>Dbb: /* Change Log */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. This article covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux from packages found in the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Installation of Prosody on Arch Linux requires building Prosody and one of its dependencies, [http://aur.archlinux.org/packages.php?ID=13509 luaexpat], from the AUR (the remaining required dependencies are available in the main Arch Linux repositories). Use whatever method (yaourt, aurbuild, etc.) you prefer to download, build, and install luaexpat and Prosody from the AUR.<br />
<br />
If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR.<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression (Recommended)<br />
: Allow Prosody to compress client-to-server streams for compatbile clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=32246 lua-zlib] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper dependencies are installed, see [[#Optional_Dependencies|above]]). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
{{Tip|If you like Prosody remember to show your support and vote for the package in the AUR.}}<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by issuing the following command and checking that the output matches your own:{{Command|name=netstat -tul|output=<br />
Proto Recv-Q Send-Q Local Address Foreign Address State<br />
tcp 0 0 *:xmpp-client *:* LISTEN<br />
tcp 0 0 *:xmpp-server *:* LISTEN<br />
}} Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
{{Codeline|$ pacman -Qc prosody}}<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
$ hg clone http://code.liqd.org/packages/prosody/<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=85387Prosody2009-11-26T17:21:21Z<p>Dbb: /* Troubleshooting */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. This article covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux from packages found in the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Installation of Prosody on Arch Linux requires building Prosody and one of its dependencies, [http://aur.archlinux.org/packages.php?ID=13509 luaexpat], from the AUR (the remaining required dependencies are available in the main Arch Linux repositories). Use whatever method (yaourt, aurbuild, etc.) you prefer to download, build, and install luaexpat and Prosody from the AUR.<br />
<br />
If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR.<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression (Recommended)<br />
: Allow Prosody to compress client-to-server streams for compatbile clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=32246 lua-zlib] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper dependencies are installed, see [[#Optional_Dependencies|above]]). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
{{Tip|If you like Prosody remember to show your support and vote for the package in the AUR.}}<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by issuing the following command and checking that the output matches your own:{{Command|name=netstat -tul|output=<br />
Proto Recv-Q Send-Q Local Address Foreign Address State<br />
tcp 0 0 *:xmpp-client *:* LISTEN<br />
tcp 0 0 *:xmpp-server *:* LISTEN<br />
}} Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
$ pacman -Qc prosody<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
$ hg clone http://code.liqd.org/packages/prosody/<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=85386Prosody2009-11-26T17:20:28Z<p>Dbb: /* Troubleshooting */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. This article covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux from packages found in the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Installation of Prosody on Arch Linux requires building Prosody and one of its dependencies, [http://aur.archlinux.org/packages.php?ID=13509 luaexpat], from the AUR (the remaining required dependencies are available in the main Arch Linux repositories). Use whatever method (yaourt, aurbuild, etc.) you prefer to download, build, and install luaexpat and Prosody from the AUR.<br />
<br />
If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR.<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression (Recommended)<br />
: Allow Prosody to compress client-to-server streams for compatbile clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=32246 lua-zlib] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper dependencies are installed, see [[#Optional_Dependencies|above]]). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
{{Tip|If you like Prosody remember to show your support and vote for the package in the AUR.}}<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by issuing the following command:{{Command|name=netstat -tul|output=<br />
Proto Recv-Q Send-Q Local Address Foreign Address State<br />
tcp 0 0 *:xmpp-client *:* LISTEN<br />
tcp 0 0 *:xmpp-server *:* LISTEN<br />
}} Check that your output matches the above. Note: the <tt>netstat</tt> command is part of the <tt>net-tools</tt> package.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
$ pacman -Qc prosody<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
$ hg clone http://code.liqd.org/packages/prosody/<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=85382Prosody2009-11-26T17:16:12Z<p>Dbb: /* Troubleshooting */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. This article covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux from packages found in the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Installation of Prosody on Arch Linux requires building Prosody and one of its dependencies, [http://aur.archlinux.org/packages.php?ID=13509 luaexpat], from the AUR (the remaining required dependencies are available in the main Arch Linux repositories). Use whatever method (yaourt, aurbuild, etc.) you prefer to download, build, and install luaexpat and Prosody from the AUR.<br />
<br />
If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR.<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression (Recommended)<br />
: Allow Prosody to compress client-to-server streams for compatbile clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=32246 lua-zlib] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper dependencies are installed, see [[#Optional_Dependencies|above]]). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
{{Tip|If you like Prosody remember to show your support and vote for the package in the AUR.}}<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run {{Codeline|luac -p /etc/prosody/prosody.cfg.lua}} to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in {{Filename|/var/log/prosody}}. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to {{Filename|prosody.debug}}.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that {{Filename|/etc/prosody}} and {{Filename|/var/lib/prosody}} are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by issuing {{Codeline|netstat -tul}} to list all ports on which your server is listening (The <tt>netstat</tt> command is part of the <tt>net-tools</tt> package). If Prosody is listening on the default ports you should see <tt>*:xmpp-client</tt> and <tt>*:xmpp-server</tt> among the local addresses your server is listening on.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody ({{Codeline|/etc/rc.d/prosody restart}}) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
$ pacman -Qc prosody<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
$ hg clone http://code.liqd.org/packages/prosody/<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=85378Prosody2009-11-26T17:13:55Z<p>Dbb: /* Console */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. This article covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux from packages found in the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Installation of Prosody on Arch Linux requires building Prosody and one of its dependencies, [http://aur.archlinux.org/packages.php?ID=13509 luaexpat], from the AUR (the remaining required dependencies are available in the main Arch Linux repositories). Use whatever method (yaourt, aurbuild, etc.) you prefer to download, build, and install luaexpat and Prosody from the AUR.<br />
<br />
If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR.<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression (Recommended)<br />
: Allow Prosody to compress client-to-server streams for compatbile clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=32246 lua-zlib] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper dependencies are installed, see [[#Optional_Dependencies|above]]). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
{{Tip|If you like Prosody remember to show your support and vote for the package in the AUR.}}<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run <tt>luac -p /etc/prosody/prosody.cfg.lua</tt> to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in <tt>/var/log/prosody</tt>. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to <tt>prosody.debug</tt>.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that <tt>/etc/prosody</tt> and <tt>/var/lib/prosody</tt> are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by issuing <tt>netstat -tul</tt> to list all ports on which your server is listening (The <tt>netstat</tt> command is part of the <tt>net-tools</tt> package). If Prosody is listening on the default ports you should see <tt>*:xmpp-client</tt> and <tt>*:xmpp-server</tt> among the local addresses your server is listening on.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody (<tt>/etc/rc.d/prosody restart</tt>) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
$ pacman -Qc prosody<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
$ hg clone http://code.liqd.org/packages/prosody/<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=85377Prosody2009-11-26T17:13:44Z<p>Dbb: /* Console */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. This article covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux from packages found in the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Installation of Prosody on Arch Linux requires building Prosody and one of its dependencies, [http://aur.archlinux.org/packages.php?ID=13509 luaexpat], from the AUR (the remaining required dependencies are available in the main Arch Linux repositories). Use whatever method (yaourt, aurbuild, etc.) you prefer to download, build, and install luaexpat and Prosody from the AUR.<br />
<br />
If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR.<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression (Recommended)<br />
: Allow Prosody to compress client-to-server streams for compatbile clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=32246 lua-zlib] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper dependencies are installed, see [[#Optional_Dependencies|above]]). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
{{Tip|If you like Prosody remember to show your support and vote for the package in the AUR.}}<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
{{Codeline|$ telnet localhost 5582}}<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
{{Codeline}|> full_sessions["romeo@montague.lit/Resource"].compressed}}<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run <tt>luac -p /etc/prosody/prosody.cfg.lua</tt> to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in <tt>/var/log/prosody</tt>. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to <tt>prosody.debug</tt>.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that <tt>/etc/prosody</tt> and <tt>/var/lib/prosody</tt> are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by issuing <tt>netstat -tul</tt> to list all ports on which your server is listening (The <tt>netstat</tt> command is part of the <tt>net-tools</tt> package). If Prosody is listening on the default ports you should see <tt>*:xmpp-client</tt> and <tt>*:xmpp-server</tt> among the local addresses your server is listening on.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody (<tt>/etc/rc.d/prosody restart</tt>) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
$ pacman -Qc prosody<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
$ hg clone http://code.liqd.org/packages/prosody/<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=85373Prosody2009-11-26T17:11:28Z<p>Dbb: /* Prosody Modules */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. This article covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux from packages found in the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Installation of Prosody on Arch Linux requires building Prosody and one of its dependencies, [http://aur.archlinux.org/packages.php?ID=13509 luaexpat], from the AUR (the remaining required dependencies are available in the main Arch Linux repositories). Use whatever method (yaourt, aurbuild, etc.) you prefer to download, build, and install luaexpat and Prosody from the AUR.<br />
<br />
If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR.<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression (Recommended)<br />
: Allow Prosody to compress client-to-server streams for compatbile clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=32246 lua-zlib] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper dependencies are installed, see [[#Optional_Dependencies|above]]). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
{{Tip|If you like Prosody remember to show your support and vote for the package in the AUR.}}<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your {{Filename|prosody.cfg.lua}} for the host or component you wish to use it for. For example, to use the <tt>pastebin</tt> module on a MUC component:<br />
<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Component "conference.example.com" "muc"<br />
modules_enabled = { "pastebin" }<br />
}}<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
$ telnet localhost 5582<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
> full_sessions["romeo@montague.lit/Resource"].compressed<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run <tt>luac -p /etc/prosody/prosody.cfg.lua</tt> to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in <tt>/var/log/prosody</tt>. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to <tt>prosody.debug</tt>.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that <tt>/etc/prosody</tt> and <tt>/var/lib/prosody</tt> are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by issuing <tt>netstat -tul</tt> to list all ports on which your server is listening (The <tt>netstat</tt> command is part of the <tt>net-tools</tt> package). If Prosody is listening on the default ports you should see <tt>*:xmpp-client</tt> and <tt>*:xmpp-server</tt> among the local addresses your server is listening on.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody (<tt>/etc/rc.d/prosody restart</tt>) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
$ pacman -Qc prosody<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
$ hg clone http://code.liqd.org/packages/prosody/<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=85371Prosody2009-11-26T17:09:01Z<p>Dbb: /* Prosody Modules */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. This article covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux from packages found in the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Installation of Prosody on Arch Linux requires building Prosody and one of its dependencies, [http://aur.archlinux.org/packages.php?ID=13509 luaexpat], from the AUR (the remaining required dependencies are available in the main Arch Linux repositories). Use whatever method (yaourt, aurbuild, etc.) you prefer to download, build, and install luaexpat and Prosody from the AUR.<br />
<br />
If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR.<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression (Recommended)<br />
: Allow Prosody to compress client-to-server streams for compatbile clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=32246 lua-zlib] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper dependencies are installed, see [[#Optional_Dependencies|above]]). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
{{Tip|If you like Prosody remember to show your support and vote for the package in the AUR.}}<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
{{Codeline|$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules}}<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at {{Filename|/usr/lib/prosody/modules}}. To enable the module add it to your <tt>modules_enabled</tt> list in your <tt>prosody.cfg.lua</tt>.<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
$ telnet localhost 5582<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
> full_sessions["romeo@montague.lit/Resource"].compressed<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run <tt>luac -p /etc/prosody/prosody.cfg.lua</tt> to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in <tt>/var/log/prosody</tt>. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to <tt>prosody.debug</tt>.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that <tt>/etc/prosody</tt> and <tt>/var/lib/prosody</tt> are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by issuing <tt>netstat -tul</tt> to list all ports on which your server is listening (The <tt>netstat</tt> command is part of the <tt>net-tools</tt> package). If Prosody is listening on the default ports you should see <tt>*:xmpp-client</tt> and <tt>*:xmpp-server</tt> among the local addresses your server is listening on.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody (<tt>/etc/rc.d/prosody restart</tt>) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
$ pacman -Qc prosody<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
$ hg clone http://code.liqd.org/packages/prosody/<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbbhttps://wiki.archlinux.org/index.php?title=Prosody&diff=85370Prosody2009-11-26T17:08:21Z<p>Dbb: /* Removal */</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|This article discusses how to setup and use Prosody, a lightweight XMPP server. This article covers installation, configuration, operation, and removal of Prosody.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Prosody}}<br />
{{Article summary heading|Important Links}}<br />
{{Article summary link|Prosody.im|http://prosody.im/}}<br />
{{Article summary link|Documentation|http://prosody.im/doc}}<br />
{{Article summary text|[http://blog.prosody.im/ Prosodical Thoughts] (Blog)}}<br />
{{Article summary link|Issue Tracker|http://code.google.com/p/lxmppd/issues/list}}<br />
{{Article summary text|[http://prosody.im/source/browse/ Prosody Modules] (Extra Modules)}}<br />
{{Article summary end}}<br />
<br />
[http://prosody.im/ Prosody] (pronunciation: [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod05.wav=prosody%27 1], [http://www.merriam-webster.com/cgi-bin/audio.pl?prosod04.wav=prosody%27 2]) is an [http://xmpp.org/ XMPP] server written in the [http://www.lua.org/ Lua] programming language. Prosody is designed to be lightweight and highly extensible. It is licensed under a permissive [http://prosody.im/source/mit MIT license]. Prosody is available for Arch Linux from packages found in the [[AUR]].<br />
<br />
Previous experience with building and installing packages from the AUR and basic knowledge of XMPP will be very helpful when following the guide. As per usual, when command line commands are provided, lines preceded by <tt>$</tt> indicate that the command may be run as a regular user, while lines preceded by <tt>#</tt> indicate that the command must be run as <tt>root</tt>.<br />
<br />
==Installation==<br />
<br />
Installation of Prosody on Arch Linux requires building Prosody and one of its dependencies, [http://aur.archlinux.org/packages.php?ID=13509 luaexpat], from the AUR (the remaining required dependencies are available in the main Arch Linux repositories). Use whatever method (yaourt, aurbuild, etc.) you prefer to download, build, and install luaexpat and Prosody from the AUR.<br />
<br />
If you are unfamiliar with how to build and install packages from the AUR please see this [[AUR_User_Guidelines#Installing_Packages_from_the_AUR|tutorial]].<br />
<br />
===Optional Dependencies===<br />
Prosody has optional depedencies that although not strictly required for its operation, provide useful features. These dependencies may also have to be built and installed from the AUR.<br />
<br />
; TLS/SSL Support (Recommended)<br />
: Allow Prosody to encrypt streams to prevent eavesdropping.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=21919 luasec] (AUR)<br />
<br />
; Stream Compression (Recommended)<br />
: Allow Prosody to compress client-to-server streams for compatbile clients to save bandwidth.<br>''Requires:'' [http://aur.archlinux.org/packages.php?ID=32246 lua-zlib] (AUR)<br />
<br />
==Configuration==<br />
<br />
{{Note|The <tt>posix</tt> module and <tt>pidfile</tt> setting contained in the default configuration file are required for Prosody's proper operation on Arch Linux. Please do not disable or alter them.}}<br />
<br />
The main configuration file is located at {{Filename|/etc/prosody/prosody.cfg.lua}}, information on how to configure Prosody can be found in Prosody's [http://prosody.im/doc/configure documentation]. The syntax of the configuration file can be checked after any changes are made by running: <br />
<br />
{{Codeline|$ luac -p /etc/prosody/prosody.cfg.lua}}<br />
<br />
No output means the syntax is correct.<br />
<br />
===Logging===<br />
The Arch Linux Prosody package is pre-configured to log to {{Filename|/var/log/prosody/prosody.err}} and {{Filename|/var/log/prosody/prosody.log}}. The Arch Linux package also includes a logrotate script in {{Filename|/etc/logrotate.d/prosody}}, configure it to suit your needs. If you enabled the <tt>olddir</tt> path for rotated log files in {{Filename|/etc/logrotate.conf}} you will likely want to move old prosody log files. First create the directory:<br />
<br />
{{Codeline|# mkdir /var/log/old/prosody}}<br />
<br />
Then uncomment the <tt>olddir</tt> line in {{Filename|/etc/logrotate.d/prosody}}.<br />
<br />
==Operation==<br />
<br />
You can start Prosody through the included rc.d script:<br />
<br />
{{Codeline|# /etc/rc.d/prosody start}}<br />
<br />
Of course you can add <tt>prosody</tt> to your <tt>DAEMONS</tt> array in your {{Filename|/etc/rc.conf}} file to have it automatically started at boot. Prosody uses the default XMPP ports, 5222 and 5269, for client-to-server and server-to-server communications respectively. Configure your firewall as necessary.<br />
<br />
You can manipulate Prosody users by using the <tt>prosodyctl</tt> program. To add a user:<br />
<br />
{{Codeline|# prosodyctl adduser <JID>}}<br />
<br />
{{Tip|You will likely want to make at least one user an administrator by adding their Jabber ID to the <tt>admins</tt> list in the configuration file.}}<br />
<br />
Issue {{Codeline|man prosodyctl}} to see the man page for <tt>prosodyctl</tt>.<br />
<br />
===Security===<br />
====User Registration====<br />
Prosody supports XMPP's in-band registration [http://xmpp.org/extensions/xep-0077.html standard], which allows users to register with an XMPP client from within their client and change their passwords. While this is convenient for users it does not allow administrators to moderate the registration of new users. As such, the <tt>register</tt> module is enabled in the default configuration but <tt>allow_registration</tt> is set to <tt>false</tt>. This allows existing users to change their passwords from within their client but does not allow new users to register themselves.<br />
<br />
{{Tip|If you do decide to support new in-band registrations, you will likely find the <tt>watchregistrations</tt> and <tt>welcome</tt> modules useful.}}<br />
<br />
====Stream Encryption====<br />
Prosody can utilize TLS certificates to encrypt client-to-server communications (if the proper dependencies are installed, see [[#Optional_Dependencies|above]]). If you intend to have a publicly accessible server, you can get a TLS certificate from the [http://xmpp.org/ca/ XMPP Standards Foundation]. See the relevant sections of {{Filename|prosody.cfg.lua}} to configure Prosody to utilize these certificates.<br />
<br />
To require encryption for client-to-server communications add the following to your configuration file:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
c2s_require_encryption = true<br />
}}<br />
<br />
<br />
Similarly, for server-to-server communications you may do:<br />
{{File|name=/etc/prosody/prosody.cfg.lua|content=<br />
Host "*"<br />
<br />
s2s_require_encryption = true<br />
}}<br />
<br />
{{Note|As of v0.6.1, <tt>s2s_require_encryption</tt> does not actually enforce server-to-server encryption, but simply announces that it is required.}}<br />
<br />
While requiring client-to-server encryption is generally a good idea, please keep in mind that some popular XMPP services such as Google Talk/Gmail do not support server-to-server encryption.<br />
<br />
==Removal==<br />
<br />
Prosody and all its (required) dependencies can be removed using pacman:<br />
<br />
{{Codeline|# pacman -Rs prosody}}<br />
<br />
To remove Prosody's optional dependencies:<br />
<br />
{{Codeline|# pacman -Rs luasec lua-zlib}}<br />
<br />
Prosody may leave the following directories on your filesystem that you may want to remove if you don't plan on reinstalling Prosody: {{Filename|/etc/prosody}}, {{Filename|/var/lib/prosody}}, {{Filename|/var/log/prosody}}, and {{Filename|/var/log/old/prosody}}.<br />
<br />
==Tips & Tricks==<br />
{{Tip|If you like Prosody remember to show your support and vote for the package in the AUR.}}<br />
<br />
===Prosody Modules===<br />
[http://code.google.com/p/prosody-modules/ Prosody Modules] is a collection of extra modules not distributed with Prosody. These modules are in various states of development from highly experimental to relatively stable. You should consult a given module's wiki page for more information. An example of an extra module is <tt>[http://code.google.com/p/prosody-modules/wiki/mod_pastebin pastebin]</tt>, which when loaded will intercept long messages (for example, log file output) and replace them with a link to a pastebin hosted using Prosody's internal HTTP server (provided by the core module, <tt>httpserver</tt>).<br />
<br />
To use an extra module download its raw file(s) from the source browser (when viewing a file, search for the link "View raw file"). Alternatively and likely easier, use Mercurial to clone the entire repository:<br />
<br />
$ hg clone https://prosody-modules.googlecode.com/hg/ prosody-modules<br />
<br />
Now you can copy the module (and any additional files it needs) to Prosody's module directory at <tt>/usr/lib/prosody/modules</tt>. To enable the module add it to your <tt>modules_enabled</tt> list in your <tt>prosody.cfg.lua</tt>.<br />
<br />
{{Note|An enforced Prosody convention is that modules are named <tt>mod_''foo''.lua</tt> but simply enabled by adding <tt>''foo''</tt> to the <tt>modules_enabled</tt> list.}}<br />
<br />
===Console===<br />
{{Warning|The console does not require any authentication so any user on a multi-user system can connect and issue commands on the console. Therefore it is '''not''' recommended to enable the <tt>console</tt> module on a multi-user system.}}<br />
<br />
The <tt>console</tt> module provides a telnet console from which administrative operations and queries can be performed. You can connect to the console by issuing:<br />
<br />
$ telnet localhost 5582<br />
<br />
You of course need the <tt>telnet</tt> program provided by the <tt>inetutils</tt> package. Use the <tt>help</tt> command in the console to get usage help.<br />
<br />
The console even allows you to execute Lua commands directly on the server by preceding a command with <tt>></tt>. For example to see if a client connection is compressed:<br />
<br />
> full_sessions["romeo@montague.lit/Resource"].compressed<br />
<br />
Will return <tt>true</tt> if the connection is compressed or <tt>nil</tt> if it is not.<br />
<br />
==Troubleshooting==<br />
One of Prosody's primary design principles is to be simple to use and configure. However, issues can still arise (and likely will as is the case with any complex software). If you encounter a problem there are a variety of steps you can take to narrow down the cause:<br />
<br />
* '''Check for known issues'''<br>Look at the [http://prosody.im/doc/release release notes] for your Prosody version to see if your issue is listed as a known issue. Also check the [http://code.google.com/p/lxmppd/issues/list issue tracker] to see if your issue has already been reported.<br />
* '''Check configuration syntax'''<br>Run <tt>luac -p /etc/prosody/prosody.cfg.lua</tt> to check for any syntax errors in your configuration file. If there is no output your syntax is fine.<br />
* '''Check the log files'''<br>Log files are located in <tt>/var/log/prosody</tt>. Errors are only logged if there is a critical problem so always address those issues. If you think you have a very low level issue (like protocol compatibility between clients and servers with Prosody) then you can enable the very verbose debug level logging. The default configuration file has commented out lines to log debug messages to <tt>prosody.debug</tt>.<br />
* '''Check permissions'''<br>The Prosody package should add a new <tt>prosody</tt> user and group to your system and set appropriate permissions, but it is always good to double check. Ensure that <tt>/etc/prosody</tt> and <tt>/var/lib/prosody</tt> are owned by the <tt>prosody</tt> user and that the user has appropriate permissions to read and write to those paths and all contained files.<br />
* '''Check listening ports'''<br>When troubleshooting connection issues make sure that Prosody is actually listening for connections. You may do so by issuing <tt>netstat -tul</tt> to list all ports on which your server is listening (The <tt>netstat</tt> command is part of the <tt>net-tools</tt> package). If Prosody is listening on the default ports you should see <tt>*:xmpp-client</tt> and <tt>*:xmpp-server</tt> among the local addresses your server is listening on.<br />
* '''Restart'''<br>Like most things, it doesn't hurt to restart Prosody (<tt>/etc/rc.d/prosody restart</tt>) to see if it resolves an issue.<br />
<br />
If you're unable to resolve your issue yourself there are a variety of resources you can use to seek help. In order of immediacy with which you'll likely receive help:<br />
<br />
# XMPP Conference: <tt>prosody@conference.prosody.im</tt><br />
# Mailing List: [http://groups.google.co.uk/group/prosody-users Web Interface], [mailto:prosody-users@googlegroups.com Email]<br />
# [http://bbs.archlinux.org/viewforum.php?id=4 Arch Forums] (for package issues)<br />
<br />
==Development==<br />
<br />
===Change Log===<br />
You may view the change log of the Prosody package by issuing the following command:<br />
<br />
$ pacman -Qc prosody<br />
<br />
===Packages===<br />
Two development packages are maintained for Prosody in the AUR, <tt>[http://aur.archlinux.org/packages.php?ID=28165 prosody-devel]</tt> and <tt>[http://aur.archlinux.org/packages.php?ID=28217 prosody-hg]</tt>. <tt>prosody-devel</tt> tracks the latest source release of a development version (alpha, beta, release candidate) and will actually be behind the stable version if a final version of the development version is released. <tt>prosody-hg</tt> tracks the [http://www.selenic.com/mercurial/wiki/ Mercurial] repository tip for Prosody and will always contain the latest code as it is checked in. Both packages are built similarly to the stable package.<br />
<br />
===Source===<br />
The Prosody package is maintained in a Mercurial repository available [http://code.liqd.org/packages/prosody/ here]. If you have Mercurial installed you may issue the following command to clone the repository:<br />
<br />
$ hg clone http://code.liqd.org/packages/prosody/<br />
<br />
==More Resources==<br />
===Development===<br />
* [http://code.google.com/p/lxmppd/issues/list Issue Tracker]<br />
* [http://prosody.im/source/browse/ Source Repository]<br />
* [http://code.google.com/p/prosody-modules/ Prosody Modules] (Non-Core Modules)<br />
<br />
===Documentation===<br />
* [http://prosody.im/doc/faq Frequently Asked Questions]<br />
* [http://prosody.im/doc/troubleshooting Troubleshooting Guide]<br />
* [http://prosody.im/doc/xeplist XEP Support List]<br />
* [http://prosody.im/doc/modules Module List]<br />
<br />
===Communication===<br />
* Mailing Lists: [http://groups.google.co.uk/group/prosody-dev prosody-dev], [http://groups.google.co.uk/group/prosody-users prosody-users]<br />
* Conference: <tt>prosody@conference.prosody.im</tt><br />
* Blog: [http://blog.prosody.im/ Prosodical Thoughts]<br />
<br />
===Social===<br />
* [http://freshmeat.net/projects/prosody Freshmeat]<br />
* [http://identi.ca/group/prosody Identi.ca]<br />
* [http://www.ohloh.net/p/prosody Ohloh]</div>Dbb