Chapril
/
xmpp.chapril.org-ejabberd
mirror of https://github.com/processone/ejabberd.git
24
1
Fork 0
Code Releases Activity

* src/ejabberdctl.template: Removed bashisms (EJAB-399). Set environment variables instead of passing parameters when calling erl (EJAB-421). 

* src/ejabberd_ctl.erl: Improvements in the help messages (EJAB-399).

* doc/guide.tex: Improvements in sections ejabberdctl, and Install from Source (EJAB-399).

SVN Revision: 978
This commit is contained in:
Badlop 2007-11-26 07:59:35 +00:00
parent a487652fe9
commit 399604e55d
4 changed files with 234 additions and 164 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
ChangeLog
View File

@ -1,3 +1,11 @@
2007-11-26 Badlop <badlop@process-one.net>
* src/ejabberdctl.template: Removed bashisms (EJAB-399). Set environment variables instead of passing parameters when calling erl (EJAB-421).
* src/ejabberd_ctl.erl: Improvements in the help messages (EJAB-399).
* doc/guide.tex: Improvements in sections ejabberdctl, and Install from Source (EJAB-399).
2007-11-25 Alexey Shchepin <alexey@process-one.net>
* src/ejabberd_router.erl: Bugfix

330
doc/guide.tex
View File

@ -198,17 +198,14 @@ The binaries are available for many different system architectures, so this is a
alternative to the binary installer and Operating System's ejabberd packages.
\section{Installation from Source}
\label{installsource}
\ind{installation}
\section{Installing ejabberd from Source Code}
\label{installation}
\ind{install}
\subsection{Installation Requirements}
\subsection{Requirements}
\label{installreq}
\ind{installation!requirements}
\subsubsection{`Unix-like' operating systems}
\label{installrequnix}
To compile \ejabberd{} on a `Unix-like' operating system, you need:
\begin{itemize}
\item GNU Make
@ -220,10 +217,157 @@ To compile \ejabberd{} on a `Unix-like' operating system, you need:
\item GNU Iconv 1.8 or higher (optional, not needed on systems with GNU libc)
\end{itemize}
\subsubsection{Windows}
\label{installreqwin}
\subsection{Download Source Sode}
\label{download}
\ind{install!download}
To compile \ejabberd{} on a Windows flavour, you need:
Released versions of \ejabberd{} can be obtained from \\
\ahrefurl{http://www.process-one.net/en/ejabberd/download.html}
\ind{Subversion repository}
The latest development version can be retrieved from the Subversion repository using this command:
\begin{verbatim}
svn co http://svn.process-one.net/ejabberd/trunk ejabberd
\end{verbatim}
\subsection{Compile}
\label{compile}
\ind{install!compile}
To compile \ejabberd{} execute the commands:
\begin{verbatim}
./configure
make
\end{verbatim}
The compilation process may report several warnings related to unusued variables.
This is common, and is not a problem.
The build configuration script provides several parameters.
To get the full list run the command:
\begin{verbatim}
./configure --help
\end{verbatim}
Some options that you may be interested in modifying:
\begin{description}
\titem{--prefix=/}
Specify the path prefix where the files will be copied when running the make install command.
\titem{--enable-pam}
Enable the PAM authentication method.
\titem{--enable-odbc or --enable-mssql}
Required if you want to use an external database.
See section~\ref{database} for more information.
\titem{--enable-full-xml}
Enable the use of XML based optimisations.
It will for example use CDATA to escape characters in the XMPP stream.
Use this option only if you are sure your Jabber clients include a fully compliant XML parser.
\titem{--disable-transient-supervisors}
Disable the use of Erlang/OTP supervision for transient processes.
\end{description}
\subsection{Install}
\label{install}
\ind{install!install}
To install ejabberd in the destination directories, run the command:
\begin{verbatim}
make install
\end{verbatim}
Note that you may need to have administrative privileges in the system.
The files and directories created are, by default:
\begin{description}
\titem{/etc/ejabberd/} Configuration files:
\begin{description}
\titem{ejabberd.cfg} ejabberd configuration file
\titem{ejabberd.inetrc} Network DNS configuration
\titem{ejabberdctl.cfg} Configuration file of the administration script
\end{description}
\titem{/sbin/ejabberdctl} Administration script
\titem{/var/lib/ejabberd/}
\begin{description}
\titem{.erlang.cookie} Erlang cookie file
\titem{db} Database spool files
\titem{ebin} Binary Erlang files (*.beam)
\titem{priv}
\begin{description}
\titem{lib} Binary system libraries (*.so)
\titem{msgs} Translated strings (*.msgs)
\end{description}
\end{description}
\titem{/var/log/ejabberd/} Log files:
\begin{description}
\titem{ejabberd.log} Messages reported by ejabberd code
\titem{sasl.log} Messages reported by Erlang/OTP
\end{description}
\end{description}
\subsection{Start}
\label{start}
\ind{install!start}
You can use the ejabberdctl command line administration script to start and stop ejabberd.
Please refer to the section~\ref{ejabberdctl} for details about ejabberdctl.
The command line parameters used by the ejabberdctl administration script
when starting the Erlang/OTP virtual machine are:
\begin{description}
\titem{-pa /var/lib/ejabberd/ebin}
Specify the directory where Erlang binary files (*.beam) are located.
\titem{-sname ejabberd}
The Erlang node will be identified using only the first part
of the host name, i.\,e. other Erlang nodes outside this domain cannot contact
this node. This is the preferable option in most cases.
\titem{-name ejabberd}
The Erlang node will be fully identified.
This is only useful if you plan to setup an ejabberd cluster with nodes in different networks.
\titem{-s ejabberd}
This paramaters tells the Erlang machine to start the ejabberd application
\titem{-mnesia dir "/var/lib/ejabberd/spool"}
Specify the Mnesia database directory.
\titem{-ejabberd config "/etc/ejabberd/ejabberd.cfg"}
Specify the ejabberd configuration file.
\titem{-ejabberd log\_path "/var/log/ejabberd/ejabberd.log"}
Specify the directory for the ejabberd.log file.
\titem{-sasl sasl\_error\_logger \{file,\"/var/log/ejabberd/sasl.log"\}}
Specify the directory for the sasl.log file.
\titem{-env ERL\_MAX\_PORTS=32000}
Allow up to 32000 connections. The default limit is just 1024.
With this value, \ejabberd{} will use more memory (approximately 6 MB more).
\titem{-env ERL\_FULLSWEEP\_AFTER=0}
May reduce memory usage, but \ejabberd{} may consume more processor.
\end{description}
Note that some characters need to be escaped when used in shell scripts, for instance \verb|"| and \verb|{}|.
You can find other options in the Erlang manual page (\shell{erl -man erl}).
\subsection{Specific Notes for BSD}
\label{bsd}
\ind{install!bsd}
The command to compile ejabberd in BSD systems is:
\begin{verbatim}
gmake
\end{verbatim}
\subsection{Specific Notes for Microsoft Windows}
\label{windows}
\ind{install!windows}
\subsubsection{Requirements}
\label{windowsreq}
To compile \ejabberd{} on a Microsoft Windows system, you need:
\begin{itemize}
\item MS Visual C++ 6.0 Compiler
\item \footahref{http://erlang.org/download.html}{Erlang/OTP R9C-2 or higher}
@ -236,60 +380,11 @@ To compile \ejabberd{} on a Windows flavour, you need:
\item \footahref{http://www.zlib.net/}{Zlib 1.2.3 or higher}
\end{itemize}
\subsection{Obtaining \ejabberd{}}
\label{obtaining}
\ind{download}
Released versions of \ejabberd{} can be obtained from \\
\ahrefurl{http://www.process-one.net/en/projects/ejabberd/download.html}.
\subsubsection{Compilation}
\label{windowscom}
\ind{Subversion repository}
The latest development version can be retrieved from the Subversion repository\@.
\begin{verbatim}
svn co http://svn.process-one.net/ejabberd/trunk ejabberd
\end{verbatim}
\subsection{Compilation}
\label{compile}
\ind{installation!compilation}
\subsubsection{`Unix-like' operating systems}
\label{compileunix}
Compile \ejabberd{} on a `Unix-like' operating system by executing:
\begin{verbatim}
./configure
make
su
make install
\end{verbatim}
These commands will:
\begin{itemize}
\item install \ejabberd{} into the directory \verb|/var/lib/ejabberd|,
\item install the configuration file into \verb|/etc/ejabberd|,
\item create a directory called \verb|/var/log/ejabberd| to store log files.
\end{itemize}
\subsubsection{Build options}
If you want to enable the use of XML based optimisations, you can use
the option \term{--enable-full-xml} when running the \term{configure}
command. It will for example use CDATA to escape characters in the
XMPP stream. Do not use this option if all your clients are not using
a fully compliant XML parser.
In some case, you might want to disable the use of Erlang OTP supervision for transient processes. In this case, you can \term{configure} ejabberd with the option \term{--disable-transient-supervisors}.
If you want to use an external database, you need to execute the configure
script with the option(s) \term{--enable-odbc} or \term{--enable-odbc
--enable-mssql}. See section~\ref{database} for more information.
\subsubsection{Windows}
\label{compilewin}
\begin{itemize}
\begin{enumerate}
\item Install Erlang emulator (for example, into \verb|C:\Program Files\erl5.3|).
\item Install Expat library into \verb|C:\Program Files\Expat-1.95.7|
directory.
@ -318,60 +413,10 @@ nmake -f Makefile.win32
\begin{verbatim}
werl -s ejabberd -name ejabberd
\end{verbatim}
\end{itemize}
\end{enumerate}
%TODO: how to compile database support on windows?
\subsection{Starting}
\label{start}
\ind{starting}
%TODO: update when the ejabberdctl script is made more userfriendly
Execute the following command to start \ejabberd{}:
\begin{verbatim}
erl -pa /var/lib/ejabberd/ebin -name ejabberd -s ejabberd
\end{verbatim}
or
\begin{verbatim}
erl -pa /var/lib/ejabberd/ebin -sname ejabberd -s ejabberd
\end{verbatim}
In the latter case the Erlang node will be identified using only the first part
of the host name, i.\,e. other Erlang nodes outside this domain cannot contact
this node.
Note that when using the above command, \ejabberd{} will search for the
configuration file in the current directory and will use the current directory
for storing its user database and for logging.
To specify the path to the configuration file, the log files and the Mnesia
database directory, you may use the following command:
\begin{verbatim}
erl -pa /var/lib/ejabberd/ebin \
-sname ejabberd \
-s ejabberd \
-ejabberd config \"/etc/ejabberd/ejabberd.cfg\" \
log_path \"/var/log/ejabberd/ejabberd.log\" \
-sasl sasl_error_logger \{file,\"/var/log/ejabberd/sasl.log\"\} \
-mnesia dir \"/var/lib/ejabberd/spool\"
\end{verbatim}
You can find other useful options in the Erlang manual page
(\shell{erl -man erl}).
To use more than 1024 connections, you should set the environment variable
\verb|ERL_MAX_PORTS|:
\begin{verbatim}
export ERL_MAX_PORTS=32000
\end{verbatim}
Note that with this value, \ejabberd{} will use more memory (approximately 6\,MB
more).
To reduce memory usage, you may set the environment variable
\verb|ERL_FULLSWEEP_AFTER|:
\begin{verbatim}
export ERL_FULLSWEEP_AFTER=0
\end{verbatim}
But in this case \ejabberd{} can start to work slower.
\section{Creating an Initial Administrator}
\label{initialadmin}
@ -381,7 +426,7 @@ account with administrator rights is needed on your \ejabberd{} deployment.
Instructions to create an initial administrator account:
\begin{enumerate}
\item Register an account on your \ejabberd{} deployment. An account can be
\item Register a Jabber account on your \ejabberd{} server. An account can be
created in two ways:
\begin{enumerate}
\item Using the tool \term{ejabberdctl}\ind{ejabberdctl} (see
@ -3191,41 +3236,29 @@ Examples:
\end{verbatim}
\end{itemize}
\subsection{\term{ejabberdctl}}
\label{ejabberdctl}
%TODO: update when the ejabberdctl script is made more userfriendly
It is possible to do some administration operations using the command
line tool \term{ejabberdctl}. You can list all available options by
running \term{ejabberdctl} without arguments:
\begin{verbatim}
% ejabberdctl
Usage: ejabberdctl node command
The \term{ejabberdctl} command line script allows to start, stop and perform
many other administrative tasks in a local or remote ejabberd server.
Available commands:
status get ejabberd status
stop stop ejabberd
restart restart ejabberd
reopen-log reopen log file
register user server password register a user
unregister user server unregister a user
backup file store a database backup to file
restore file restore a database backup from file
install-fallback file install a database fallback from file
dump file dump a database to a text file
load file restore a database from a text file
import-file file import user data from jabberd 1.4 spool file
import-dir dir import user data from jabberd 1.4 spool directory
registered-users list all registered users
delete-expired-messages delete expired offline messages from database
Example:
ejabberdctl ejabberd@host restart
\end{verbatim}
Additional information:
When \term{ejabberdctl} is executed without any parameter,
it displays the available options. If there isn't an ejabberd server running,
the available parameters are:
\begin{description}
\titem{reopen-log } If you use a tool to rotate logs, you have to configure it
\titem{start} Start ejabberd in background mode. This is the default method.
\titem{debug} Attach an Erlang shell to an already existing ejabberd server. This allows to execute commands interactively in the ejabberd server.
\titem{live} Start ejabberd in live mode: the shell keeps attached to the started server, showing log messages and allowing to execute interactive commands.
\end{description}
If there is an ejabberd server running in the system,
\term{ejabberdctl} shows all the available commands in that server.
The more interesting ones are:
\begin{description}
\titem{status} Check the status of the ejabberd server.
\titem{stop} Stop the ejabberd server which is running in the machine.
\titem{reopen-log} If you use a tool to rotate logs, you have to configure it
so that this command is executed after each rotation.
\titem {backup, restore, install-fallback, dump, load} You can use these
commands to create and restore backups.
@ -3233,12 +3266,19 @@ Additional information:
%% be found in section~\ref{backup}.
\titem{import-file, import-dir} \ind{migration from other software}
These options can be used to migrate from other \Jabber{}/XMPP servers. There
exist tutorials to \footahref{http://ejabberd.jabber.ru/migrate-to-ejabberd}{migrate from other software to ejabberd}.
exist tutorials to \footahref{http://www.ejabberd.im/migrate-to-ejabberd}{migrate from other software to ejabberd}.
\titem{delete-expired-messages} This option can be used to delete old messages
in offline storage. This might be useful when the number of offline messages
is very high.
\end{description}
The \term{ejabberdctl} script also allows the argument \term{--node NODENAME}.
This allows to administer a remote node.
The \term{ejabberdctl} administration script can be configured in the file ejabberdctl.cfg.
This file provides detailed information about each configurable option.
\chapter{Securing ejabberd}
\section{Firewall Settings}
\label{firewall}

32
src/ejabberd_ctl.erl
View File

@ -24,7 +24,21 @@
start() ->
case init:get_plain_arguments() of
[SNode | Args] ->
Node = list_to_atom(SNode),
SNode1 = case string:tokens(SNode, "@") of
[_Node, _Server] ->
SNode;
_ ->
case net_kernel:longnames() of
true ->
SNode ++ "@" ++ inet_db:gethostname() ++
"." ++ inet_db:res_option(domain);
false ->
SNode ++ "@" ++ inet_db:gethostname();
_ ->
SNode
end
end,
Node = list_to_atom(SNode1),
Status = case rpc:call(Node, ?MODULE, process, [Args]) of
{badrpc, Reason} ->
io:format("RPC failed on the node ~p: ~p~n",
@ -248,13 +262,15 @@ print_usage() ->
Desc, NewLine]
end, CmdDescs),
io:format(
"Usage: ejabberdctl node command~n"
"Usage: ejabberdctl [--node nodename] command [options]~n"
"~n"
"Available commands:~n"
"Available commands in this ejabberd node:~n"
++ FmtCmdDescs ++
"~n"
"Example:~n"
" ejabberdctl ejabberd@host restart~n"
"Examples:~n"
" ejabberdctl restart~n"
" ejabberdctl --node ejabberd@host restart~n"
" ejabberdctl vhost jabber.example.org ...~n"
).
print_vhost_usage(Host) ->
@ -279,11 +295,13 @@ print_vhost_usage(Host) ->
Desc, NewLine]
end, CmdDescs),
io:format(
"Usage: ejabberdctl node vhost host command~n"
"Usage: ejabberdctl [--node nodename] vhost hostname command [options]~n"
"~n"
"Available commands:~n"
"Available commands in this ejabberd node and this vhost:~n"
++ FmtCmdDescs ++
"~n"
"Examples:~n"
" ejabberdctl vhost "++Host++" registered-users~n"
).
register_commands(CmdDescs, Module, Function) ->

28
src/ejabberdctl.template
View File

@ -6,7 +6,8 @@ ERLANG_NODE=$NODE@$HOST
# Define ejabberd environment
ROOTDIR=@rootdir@
EJABBERD_CFG=$ROOTDIR/etc/ejabberd/ejabberd.cfg
EJABBERD_CONFIG_PATH=$ROOTDIR/etc/ejabberd/ejabberd.cfg
export EJABBERD_CONFIG_PATH
EJABBERDCTL_CFG=$ROOTDIR/etc/ejabberd/ejabberdctl.cfg
EJABBERD_INETRC=$ROOTDIR/etc/ejabberd/ejabberd.inetrc
EJABBERD_EBIN=$ROOTDIR/var/lib/ejabberd/ebin
@ -14,6 +15,7 @@ EJABBERD_DB=$ROOTDIR/var/lib/ejabberd/db/$NODE
EJABBERD_MSGS_PATH=$ROOTDIR/var/lib/ejabberd/priv/msgs
EJABBERD_SO_PATH=$ROOTDIR/var/lib/ejabberd/priv/lib
EJABBERD_LOG_PATH=$ROOTDIR/var/log/ejabberd/ejabberd.log
export EJABBERD_LOG_PATH
SASL_LOG_PATH=$ROOTDIR/var/log/ejabberd/sasl.log
[ -d $EJABBERD_DB ] || mkdir -p $EJABBERD_DB
@ -35,9 +37,12 @@ else
SNAME=-name
fi
# Compatibility in ZSH
#setopt shwordsplit 2>/dev/null
ERLANG_OPTS="$POLL $PROCESSES $ERL_MAX_ETS_TABLES"
function start
start ()
{
erl \
$SNAME $ERLANG_NODE \
@ -46,12 +51,10 @@ function start
-pa $EJABBERD_EBIN \
-mnesia dir "\"$EJABBERD_DB\"" \
-s ejabberd \
-ejabberd config \"$EJABBERD_CFG\" \
log_path \"$EJABBERD_LOG_PATH\" \
-sasl sasl_error_logger \{file,\"$SASL_LOG_PATH\"\}
}
function debug
debug ()
{
echo "--------------------------------------------------------------------"
echo ""
@ -66,14 +69,15 @@ function debug
echo " control+c, control+c"
echo ""
echo "--------------------------------------------------------------------"
read -p "Press any key to continue"
echo "Press any key to continue"
read foo
echo ""
erl \
$SNAME debug \
-remsh $ERLANG_NODE
}
function live
live ()
{
echo "--------------------------------------------------------------------"
echo ""
@ -87,18 +91,18 @@ function live
echo " q(). and press the Enter key"
echo ""
echo "--------------------------------------------------------------------"
read -p "Press any key to continue"
echo "Press any key to continue"
read foo
echo ""
erl \
$SNAME $ERLANG_NODE \
$ERLANG_OPTS \
-pa $EJABBERD_EBIN \
-mnesia dir "\"$EJABBERD_DB\"" \
-ejabberd config \"$EJABBERD_CFG\" \
-s ejabberd
}
function ctl
ctl ()
{
erl \
$SNAME ejabberdctl \
@ -111,13 +115,13 @@ function ctl
esac
}
function usage
usage ()
{
ctl
exit
}
function help_start
help_start ()
{
echo ""
echo "Commands to start an ejabberd node:"