.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "ERLSVC 1p"
.TH ERLSVC 1p "2017-07-02" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
erlsvc \- CLI to control My service
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBerlsvc\fR
[\fB\-C \f(BIconfig\fB\fR]
[\fB\-u \f(BIuser\fB\fR] [\fB\-g \f(BIgroup\fB\fR]
[\fB\-n \f(BInode\fB\fR]
[\fB\-h \f(BIhost\fB\fR]
[\fB\-c \f(BIcookie\fB\fR]
[\fB\-r \f(BIrelease\fB\fR]
[\fB\-d \f(BIreleases_dir\fB\fR]
[\fB\-E \f(BIerlang_root_dir\fB\fR]
[\fB\-L \f(BIerlang_libs_dir\fB\fR]
[\fB\-M \f(BImods_dir\fB\fR]
[\fB\-P \f(BIpipe_dir\fB\fR]]
[\fB\-O \f(BIlog_dir\fB\fR]]
[\fB\-V \f(BIcomponents\fB\fR] \fIcommand\fR [<command arguments>]
.PP
\&\fBerlsvc\fR help [\fIcommand\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBerlsvc\fR is the command line interface to manage the Erlang nodes
making My service. This includes bootstrapping a new node, starting and
stopping it or handling release upgrade.
.PP
Technically speaking, it starts a \*(L"controller\*(R" locally (an Erlang node).
This node may spawn a process on a running target node to execute the
command. This way, it's possible to manage a node on a remote host.
.PP
You can get a summary of the command line options and a list of
available commands by issueing the command \f(CW\*(C`erlsvc help\*(C'\fR.  To get a
help message for a specific command, use \f(CW\*(C`erlsvc help \f(CIcommand\f(CW\*(C'\fR.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-C\fR \fIconfig\fR or \fB\-\-config\fR \fIconfig\fR" 5
.IX Item "-C config or --config config"
This specifies the path to a configuration file.  See \*(L"\s-1CONFIGURATION\*(R"\s0
for more informations about the format of this file and the options
available.
.Sp
Command line options always override values from the configuration
file.
.Sp
By default, \fBerlsvc\fR looks for the following files:
.RS 5
.IP "1." 4
\&\fI\f(CI$HOME\fI/.config/erlsvc/config\-\fInode\fI@\fIhost\fI.yaml\fR
.IP "2." 4
\&\fI\f(CI$HOME\fI/.config/erlsvc/config\-\fInode\fI.yaml\fR
.IP "3." 4
\&\fI\f(CI$HOME\fI/.config/erlsvc/config.yaml\fR
.IP "4." 4
\&\fI/etc/wayne/erlsvc\-\fInode\fI@\fIhost\fI.yaml\fR
.IP "5." 4
\&\fI/etc/wayne/erlsvc\-\fInode\fI.yaml\fR
.IP "6." 4
\&\fI/etc/wayne/erlsvc.yaml\fR
.IP "7." 4
\&\fI/etc/default/erlsvc\fR
.RE
.RS 5
.RE
.IP "\fB\-u\fR \fIuser\fR or \fB\-\-user\fR \fIuser\fR" 5
.IX Item "-u user or --user user"
This specifies the user under which the service must run.  The target
node will first start with the caller's user \s-1ID \s0(eg. root) and will drop
to \fIuser\fR before starting the service.
.Sp
By default, the user is not changed.
.IP "\fB\-g\fR \fIgroup\fR or \fB\-\-group\fR \fIgroup\fR" 5
.IX Item "-g group or --group group"
This specified the group under which the service must run.  See the \fB\-u\fR
option above for an explanation.
.Sp
By default, the gorup is not changed.
.IP "\fB\-n\fR \fInode\fR or \fB\-\-node\fR \fInode\fR" 5
.IX Item "-n node or --node node"
This specifies the name of the target node to start or manage.
.Sp
The default is \*(L"myservice\*(R".
.IP "\fB\-h\fR \fIhost\fR or \fB\-\-host\fR \fIhost\fR" 5
.IX Item "-h host or --host host"
This specifies the hostname of the target node to manage.  The hostname
must be in a \*(L"short\*(R" form: only up-to the first dot, not a full
qualified domain name.
.Sp
The default is the local hostname.
.IP "\fB\-c\fR \fIcookie\fR or \fB\-\-cookie\fR \fIcookie\fR" 5
.IX Item "-c cookie or --cookie cookie"
This specifies the Erlang cookie to be used for inter-node
communication.  This cookie is also used as the starting target node's
cookie.
.Sp
By default, use whatever default cookie \fIerl\fR\|(1) would use.
.IP "\fB\-r\fR \fIrelease\fR or \fB\-\-release\fR \fIrelease\fR" 5
.IX Item "-r release or --release release"
This specifies the Erlang release to boot when starting the service.
.Sp
The default is the permanent release.
.IP "\fB\-d\fR \fIreleases_dir\fR or \fB\-\-releases\-dir\fR \fIreleases_dir\fR" 5
.IX Item "-d releases_dir or --releases-dir releases_dir"
This specifies the Erlang releases directory.
.Sp
The default is the system Erlang releases directory, ie. the \*(L"releases\*(R"
directory under the Erlang root directory.
.IP "\fB\-E\fR \fIerlang_root_dir\fR or \fB\-\-erlang\fR \fIerlang_root_dir\fR" 5
.IX Item "-E erlang_root_dir or --erlang erlang_root_dir"
This specifies the Erlang root directory.  This is useful when \fIerl\fR\|(1)
is not in the \s-1PATH\s0 or the one in the \s-1PATH\s0 is not to be used.
.Sp
By default, \fIerl\fR\|(1) in the \s-1PATH\s0 is used.
.IP "\fB\-L\fR \fIerlang_libs_dir\fR or \fB\-\-erllibs\-path\fR \fIerlang_libs_dir\fR" 5
.IX Item "-L erlang_libs_dir or --erllibs-path erlang_libs_dir"
This specifies additionnal directories where Erlang application may be
found.  This option may be specified multiple times to set several paths.
.Sp
By default, none.
.IP "\fB\-M\fR \fImods_dir\fR or \fB\-\-mods\-dir\fR \fImods_dir\fR" 5
.IX Item "-M mods_dir or --mods-dir mods_dir"
This specifies the directory where \fBerlsvc\fR's Erlang modules are.
.Sp
The default is the \fBerlsvc\fR's distribution-level shared data
directory as returned by \f(CW\*(C`dist_dir(\*(Aqerlsvc\*(Aq)\*(C'\fR from File::ShareDir.
.IP "\fB\-R\fR \fIpipe_dir\fR or \fB\-\-pipe\-dir\fR \fIpipe_dir\fR" 5
.IX Item "-R pipe_dir or --pipe-dir pipe_dir"
This specifies the directory where \fIrun_erl\fR\|(1) puts the named pipe
required by \fIto_erl\fR\|(1).
.Sp
The default is \fI/var/run/wayne\fR.
.IP "\fB\-O\fR \fIlog_dir\fR or \fB\-\-log\-dir\fR \fIlog_dir\fR" 5
.IX Item "-O log_dir or --log-dir log_dir"
This specifies the directory where \fIrun_erl\fR\|(1) puts its log files,
such as \fIrun_erl.log\fR or \fIerlang.log.*\fR.
.Sp
The default is \fI/var/log/wayne\fR.
.IP "\fB\-V\fR \fIcomponent\fR or \fB\-\-verbose\fR \fIcomponent\fR" 5
.IX Item "-V component or --verbose component"
This sets the verbosity per component or for all at once.  This option
may be specified multiple times to enable/disable several components.  To
specify all components, use \f(CW\*(C`ALL\*(C'\fR.  A component may be prefixed by '!'
to disable verbosity only for it.
.Sp
Available components are:
.RS 5
.IP "\(bu" 4
\&\f(CW\*(C`APP\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`ERLENV\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`ERLNODE\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`ERLSCRIPT\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`MNESIA\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`PROC\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`REL\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`SERV\*(C'\fR
.RE
.RS 5
.Sp
For instance, to enable verbosity for anything touching the service, use
\&\f(CW\*(C`\-V SERV\*(C'\fR.  To enable everything but the service's message, use \f(CW\*(C`\-V
ALL \-V !SERV\*(C'\fR (note that it may be necessary to escape the '!' character to
workaround shell interpretation).
.RE
.SH "COMMANDS"
.IX Header "COMMANDS"
.SS "Available commands"
.IX Subsection "Available commands"
Here is a list of available commands. Some commands don't have any
action; they rather provide sub-commands.
.IP "\fBbosh4yaws\fR" 5
.IX Item "bosh4yaws"
This command provides sub-commands to configure the bosh4yaws
application.
.IP "\fBejabberd\fR" 5
.IX Item "ejabberd"
This command provides sub-commands to configure the ejabberd
application.
.IP "\fBejabberd_client\fR" 5
.IX Item "ejabberd_client"
This command provides sub-commands to configure the ejabberd_client
application.
.IP "\fBephp4yaws\fR" 5
.IX Item "ephp4yaws"
This command provides sub-commands to configure the ephp4yaws
application.
.IP "\fBhelp\fR" 5
.IX Item "help"
This command display a generic help about \fBerlsvc\fR or a more detailed
help about a specified command.
.IP "\fBmnesia\fR" 5
.IX Item "mnesia"
This command provides sub-commands to handle the Mnesia database.
.IP "\fBphp\fR" 5
.IX Item "php"
This command provides sub-commands to handle the \s-1PHP\s0 interpreter.
.IP "\fBrelease\fR" 5
.IX Item "release"
This command provides sub-commands to handle the Erlang releases.
Especially, it's used during live upgrade.
.IP "\fBrestart\fR" 5
.IX Item "restart"
This command restarts the service.
.IP "\fBstart\fR" 5
.IX Item "start"
This command starts the service.
.IP "\fBstatus\fR" 5
.IX Item "status"
This command tells if the service is running.
.IP "\fBstop\fR" 5
.IX Item "stop"
This command stops the service.
.IP "\fBtarget\fR" 5
.IX Item "target"
This command provides sub-commands to manipulate a target system.
.IP "\fBtoken_bucket\fR" 5
.IX Item "token_bucket"
This command provides sub-commands to configure the token_bucket
application.
.IP "\fByaws\fR" 5
.IX Item "yaws"
This command provides sub-commands to configure the yaws application.
.SS "Detailed help about a command"
.IX Subsection "Detailed help about a command"
To obtain a more detailed help about a command, use the \*(L"help\*(R" command:
.PP
\&\fBerlsvc\fR help \fIcommand\fR
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
.SS "Configuration format"
.IX Subsection "Configuration format"
A configuration file can be specified using the \fB\-C\fR option.  The
file format conforms to \s-1YAML,\s0 or more exactly a subset of the \s-1YAML\s0
specification, as documented in YAML::Tiny.  This may still be
overrident by any command line option.
.PP
By default, \fBerlsvc\fR looks for the following files:
.IP "1." 4
\&\fI\f(CI$HOME\fI/.config/erlsvc/config\-\fInode\fI@\fIhost\fI.yaml\fR
.IP "2." 4
\&\fI\f(CI$HOME\fI/.config/erlsvc/config\-\fInode\fI.yaml\fR
.IP "3." 4
\&\fI\f(CI$HOME\fI/.config/erlsvc/config.yaml\fR
.IP "4." 4
\&\fI/etc/wayne/erlsvc\-\fInode\fI@\fIhost\fI.yaml\fR
.IP "5." 4
\&\fI/etc/wayne/erlsvc\-\fInode\fI.yaml\fR
.IP "6." 4
\&\fI/etc/wayne/erlsvc.yaml\fR
.IP "7." 4
\&\fI/etc/default/erlsvc\fR
.PP
The expected structure of the \s-1YAML\s0 document is a hash where the keys
are the long option names (with \*(L"\-\*(R" replaced by \*(L"_\*(R") and the value
are obviously the values for these options.  If an option may be given
multiple times to specify multiple values, the configuration entry will
have only one key pointing to a list of values.
.SS "Non-option variables"
.IX Subsection "Non-option variables"
Beside variables mapping the command line options, \fBerlsvc\fR supports
the following additional variables :
.IP "erlapp_args" 5
.IX Item "erlapp_args"
This specifies all the Erlang applications environment variable that
must be passed on the \fIerl\fR\|(1) command line.  The structure pointed by
the key must be a hash where the keys are the application names and the
values are a hash again, where the keys are the environment variable
name and the values, the variable's values.
.IP "extra_flags" 5
.IX Item "extra_flags"
This specifies extra command line flags to pass to \fIerl\fR\|(1).  The
structure pointed by the key must a list of strings.
.SS "Examples"
.IX Subsection "Examples"
Here is a configuration file setting the user and group for the target
node and enabling all debug messages.  It also shows how to specify
Mnesia's data directory and how to disable \s-1SMP\s0 in the Erlang emulator.
.PP
.Vb 3
\& # Set the service identity to wayne:wayne.
\& user: wayne
\& group: wayne
\& 
\& # Be verbose.
\& verbose:
\&   \- ALL
\&
\& # Set Mnesia\*(Aqs directory. Note how the quotes and double\-quotes are
\& # used so that Erlang interprets the string correctly.
\& erlapp_args:
\&   mnesia:
\&     dir: \*(Aq"/var/db/mnesia"\*(Aq
\& 
\& extra_flags:
\&   \- "\-smp"
\&   \- "disable"
.Ve