'\" t
.\"     Title: procserv
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 06/28/2019
.\"    Manual: procServ Manual
.\"    Source: procServ 2.8.0
.\"  Language: English
.\"
.TH "PROCSERV" "1" "06/28/2019" "procServ 2\&.8\&.0" "procServ Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
procServ \- Process Server with Telnet Console and Log Access
.SH "SYNOPSIS"
.sp
\fBprocServ\fR [\fIOPTIONS\fR] \-P \fIendpoint\fR\&... \fIcommand\fR \fIargs\fR\&...
.sp
\fBprocServ\fR [\fIOPTIONS\fR] \fIendpoint\fR \fIcommand\fR \fIargs\fR\&...
.SH "DESCRIPTION"
.sp
procServ(1) creates a run time environment for a command (e\&.g\&. a soft IOC)\&. It forks a server run as a daemon into the background, which creates a child process running \fIcommand\fR with all remaining \fIargs\fR from the command line\&. The server provides control access (stdin/stdout) to the child process console by offering a telnet connection at the specified \fIendpoint\fR(s)\&.
.sp
An \fIendpoint\fR can either be a TCP server socket (specified by the port number) or a UNIX domain socket (where available)\&. See ENDPOINT SPECIFICATION below for details\&. For security reasons, control access is restricted to connections from localhost (127\&.0\&.0\&.1), so that a prior login in to the host machine is required\&. (See \fB\-\-allow\fR option\&.)
.sp
The first variant allows multiple \fIendpoint\fR declarations and treats all non\-option arguments as the command line for the child process\&. The second variant (provided for backward compatibility) declares one \fIendpoint\fR with its specification taken from the first non\-option argument\&.
.sp
procServ can be configured to write a console log of all in\- and output of the child process into a file using the \fB\-L\fR (\fB\-\-logfile\fR) option\&. Sending the signal SIGHUP to the server will make it reopen the log file\&.
.sp
To facilitate running under a central console access management (like conserver), the \fB\-l\fR (\fB\-\-logport\fR) option creates an additional endpoint, which is by default public (i\&.e\&. TCP access is not restricted to connections from localhost), and provides read\-only (log) access to the child\(cqs console\&. The \fB\-r\fR (\fB\-\-restrict\fR) option restricts both control and log access to connections from localhost\&.
.sp
Both control and log endpoints allow multiple connections, which are handled transparently: all input from control connections is forwarded to the child process, all output from the child is forwarded to all control and log connections (and written to the log file)\&. All diagnostic messages from the procServ server process start with "@@@" to be clearly distinguishable from child process messages\&. A name specified by the \fB\-n\fR (\fB\-\-name\fR) option will replace the command string in many messages for increased readability\&.
.sp
The server will by default automatically respawn the child process when it dies\&. To avoid spinning, a minimum time between child process restarts is honored (default: 15 seconds, can be changed using the \fB\-\-holdoff\fR option)\&. This behavior can be toggled online using the toggle command ^T, the default may be changed using the \fB\-\-noautorestart\fR option\&. You can restart a running child manually by sending a signal to the child process using the kill command ^X\&. With the child process being shut down, the server accepts two commands: ^R or ^X to restart the child, and ^Q to quit the server\&. The \fB\-w\fR (\fB\-\-wait\fR) option starts the server in this shut down mode, waiting for a control connection to issue a manual start command to spawn the child\&.
.sp
To facilitate running under system daemon management (systemd/supervisord), the \fB\-o\fR (\fB\-\-oneshot\fR) option will exit the procServ server after the child exits\&. In that mode, the system daemon must handle restarts (if required), and all clients will have to reconnect\&.
.sp
Any connection (control or log) can be disconnected using the client\(cqs disconnect sequence\&. Control connections can also be disconnected by sending the logout command character that can be specified using the \fB\-x\fR (\fB\-\-logoutcmd\fR) option\&.
.sp
To block input characters that are potentially dangerous to the child (e\&.g\&. ^D and ^C on soft IOCs), the \fB\-i\fR (\fB\-\-ignore\fR) option can be used to specify characters that are silently ignored when coming from a control connection\&.
.sp
To facilitate being started and stopped as a standard system service, the \fB\-p\fR (\fB\-\-pidfile\fR) option tells the server to create a PID file containing the PID of the server process\&. The \fB\-I\fR (\fB\-\-info\-file\fR) option writes a file listing the server PID and a list of all endpoints\&.
.sp
The \fB\-d\fR (\fB\-\-debug\fR) option runs the server in debug mode: the daemon process stays in the foreground, printing all regular log content plus additional debug messages to stdout\&.
.SH "ENDPOINT SPECIFICATION"
.sp
Both control and log endpoints may be bound to either TCP or UNIX sockets (where supported)\&. Allowed endpoint specifications are:
.PP
\fB<port>\fR
.RS 4
Bind to either 0\&.0\&.0\&.0:\fI<port>\fR
(any) or 127\&.0\&.0\&.1:\fI<port>\fR
(localhost) depending on the type of endpoint and the setting of
\fB\-r\fR
(\fB\-\-restrict\fR) and
\fB\-\-allow\fR
options\&.
.RE
.PP
\fB<ifaceaddr>:<port>\fR
.RS 4
Bind to the specified interface address and
\fI<port>\fR\&. The interface IP address
\fI<ifaceaddr>\fR
must be given in numeric form\&. Uses 127\&.0\&.0\&.1 (localhost) for security reasons unless the
\fB\-\-allow\fR
option is also used\&.
.RE
.PP
\fBunix:</path/to/socket>\fR
.RS 4
Bind to a named unix domain socket that will be created at the specified absolute or relative path\&. The server process must have permission to create files in the enclosing directory\&. The socket file will be owned by the uid and primary gid of the procServ server process with permissions 0666 (equivalent to a TCP socket bound to localhost)\&.
.RE
.PP
\fBunix:<user>:<group>:<perm>:</path/to/socket>\fR
.RS 4
Bind to a named unix domain socket that will be created at the specified absolute or relative path\&. The server process must have permission to create files in the enclosing directory\&. The socket file will be owned by the specified
\fI<user>\fR
and
\fI<group>\fR
with
\fI<perm>\fR
permissions\&. Any of
\fI<user>\fR,
\fI<group>\fR, and/or
\fI<perm>\fR
may be omitted\&. E\&.g\&. "\-P unix::grp:0660:/run/procServ/foo/control" will create the named socket with 0660 permissions and allow the "grp" group connect to it\&. This requires that procServ be run as root or a member of "grp"\&.
.RE
.PP
\fBunix:@</path/to/socket>\fR
.RS 4
Bind to an abstract unix domain socket (Linux specific)\&. Abstract sockets do not exist on the filesystem, and have no permissions checks\&. They are functionally similar to a TCP socket bound to localhost, but identified with a name string instead of a port number\&.
.RE
.SH "OPTIONS"
.PP
\fB\-\-allow\fR
.RS 4
Allow TCP control connections from anywhere\&. (Default: restrict control access to connections from localhost\&.) Creates a serious security hole, as telnet clients from anywhere can connect to the child\(cqs stdin/stdout and might execute arbitrary commands on the host if the child permits\&. Needs to be enabled at compile\-time (see Makefile)\&. Please do not enable and use this option unless you exactly know why and what you are doing\&.
.RE
.PP
\fB\-\-autorestartcmd\fR=\fIchar\fR
.RS 4
Toggle auto restart flag when
\fIchar\fR
is sent on a control connection\&. Use
^
to specify a control character,
""
to disable\&. Default is
^T\&.
.RE
.PP
\fB\-\-coresize\fR=\fIsize\fR
.RS 4
Set the maximum
\fIsize\fR
of core file\&. See getrlimit(2) documentation for details\&. Setting
\fIsize\fR
to 0 will keep child from creating core files\&.
.RE
.PP
\fB\-c, \-\-chdir\fR=\fIdir\fR
.RS 4
Change directory to
\fIdir\fR
before starting the child\&. This is done each time the child is started to make sure symbolic links are properly resolved on child restart\&.
.RE
.PP
\fB\-d, \-\-debug\fR
.RS 4
Enter debug mode\&. Debug mode will keep the server process in the foreground and enables diagnostic messages that will be sent to the controlling terminal\&.
.RE
.PP
\fB\-e, \-\-exec\fR=\fIfile\fR
.RS 4
Run
\fIfile\fR
as executable for child\&. Default is
\fIcommand\fR\&.
.RE
.PP
\fB\-f, \-\-foreground\fR
.RS 4
Keep the server process in the foreground and connected to the controlling terminal\&.
.RE
.PP
\fB\-h, \-\-help\fR
.RS 4
Print help message\&.
.RE
.PP
\fB\-\-holdoff\fR=\fIn\fR
.RS 4
Wait at least
\fIn\fR
seconds between child restart attempts\&. (Default is 15 seconds\&.)
.RE
.PP
\fB\-i, \-\-ignore\fR=\fIchars\fR
.RS 4
Ignore all characters in
\fIchars\fR
on control connections\&. This can be used to shield the child process from input characters that are potentially dangerous, e\&.g\&.
^D
and
^C
characters that would shut down a soft IOC\&. Use
^
to specify control characters,
^^
to specify a single
^
character\&.
.RE
.PP
*\-I, \-\-info\-file <file>
.RS 4
Write instance information to this file\&.
.RE
.PP
\fB\-k, \-\-killcmd\fR=\fIchar\fR
.RS 4
Kill the child process (child will be restarted automatically by default) when
\fIchar\fR
is sent on a control connection\&. Use
^
to specify a control character,
""
for no kill command\&. Default is
^X\&.
.RE
.PP
\fB\-\-killsig\fR=\fIsignal\fR
.RS 4
Kill the child using
\fIsignal\fR
when receiving the kill command\&. Default is 9 (SIGKILL)\&.
.RE
.PP
\fB\-l, \-\-logport\fR=\fIendpoint\fR
.RS 4
Provide read\-only log access to the child\(cqs console on
\fIendpoint\fR\&. See ENDPOINT SPECIFICATION above\&. By default, TCP log endpoints allow connections from anywhere\&. Use the
\fB\-r\fR
(\fB\-\-restrict\fR) option to restrict TCP access to local connections\&.
.RE
.PP
\fB\-L, \-\-logfile\fR=\fIfile\fR
.RS 4
Write a console log of all in and output to
\fIfile\fR\&.
\fI\-\fR
selects stdout\&.
.RE
.PP
\fB\-\-logstamp\fR[=\fIfmt\fR]
.RS 4
Prefix lines in logs with a time stamp, setting the time stamp format string to
\fIfmt\fR\&. Default is "[<timefmt>] "\&. (See
\fB\-\-timefmt\fR
option\&.)
.RE
.PP
\fB\-n, \-\-name\fR=\fItitle\fR
.RS 4
In all server messages, use
\fItitle\fR
instead of the full command line to increase readability\&.
.RE
.PP
\fB\-\-noautorestart\fR
.RS 4
Do not automatically restart child process on exit\&.
.RE
.PP
\fB\-o, \-\-oneshot\fR
.RS 4
Once the child process exits, also exit the server\&.
.RE
.PP
\fB\-P, \-\-port\fR=\fIendpoint\fR
.RS 4
Provide control access to the child\(cqs console on
\fIendpoint\fR\&. See ENDPOINT SPECIFICATION above\&. By default, TCP control endpoints are restricted to local connections\&. Use the
\fB\-\-allow\fR
option to allow TCP access from anywhere\&.
.RE
.PP
\fB\-p, \-\-pidfile\fR=\fIfile\fR
.RS 4
Write the PID of the server process into
\fIfile\fR\&.
.RE
.PP
\fB\-\-timefmt\fR=\fIfmt\fR
.RS 4
Set the format string used to print time stamps to
\fIfmt\fR\&. Default is "%c"\&. (See strftime(3) documentation for details\&.)
.RE
.PP
\fB\-q, \-\-quiet\fR
.RS 4
Do not write informational output (server)\&. Avoids cluttering the screen when run as part of a system script\&.
.RE
.PP
\fB\-\-restrict\fR
.RS 4
Restrict TCP access (control and log) to connections from localhost\&.
.RE
.PP
\fB\-V, \-\-version\fR
.RS 4
Print program version\&.
.RE
.PP
\fB\-w, \-\-wait\fR
.RS 4
Do not start the child immediately\&. Instead, wait for a control connection and a manual start command\&.
.RE
.PP
\fB\-x, \-\-logoutcmd\fR=\fIchar\fR
.RS 4
Log out (close client connection) when
\fIchar\fR
is sent on an control connection\&. Use
^
to specify a control character\&. Default is empty\&.
.RE
.SH "USAGE"
.sp
To start a soft IOC using procServ, change the directory into the IOC\(cqs boot directory\&. A typical command line would be
.sp
.if n \{\
.RS 4
.\}
.nf
    procServ \-n "My SoftIOC" \-i ^D^C 20000 \&./st\&.cmd
.fi
.if n \{\
.RE
.\}
.sp
To connect to the IOC, log into the soft IOC\(cqs host and connect to port 20000 using
.sp
.if n \{\
.RS 4
.\}
.nf
    telnet localhost 20000
.fi
.if n \{\
.RE
.\}
.sp
To connect from a remote machine, ssh to a user account on procservhost and connect to port 20000 using
.sp
.if n \{\
.RS 4
.\}
.nf
    ssh \-t user@procservhost telnet localhost 20000
.fi
.if n \{\
.RE
.\}
.sp
You will be connected to the soft IOCs console and receive an informative welcome message\&. All output from the procServ server will start with "@@@" to allow telling it apart from messages that your IOC sends\&.
.sp
.if n \{\
.RS 4
.\}
.nf
    > telnet localhost 20000
    Trying 127\&.0\&.0\&.1\&.\&.\&.
    Connected to localhost\&.
    Escape character is \*(Aq^]\*(Aq\&.
    @@@ Welcome to the procServ process server (procServ Version 2\&.1\&.0)
    @@@ Use ^X to kill the child, auto restart is ON, use ^T to toggle auto restart
    @@@ procServ server PID: 21413
    @@@ Startup directory: /projects/ctl/lange/epics/ioc/test314/iocBoot/iocexample
    @@@ Child "My SoftIOC" started as: \&./st\&.cmd
    @@@ Child "My SoftIOC" PID: 21414
    @@@ procServ server started at: Fri Apr 25 16:43:00 2008
    @@@ Child "My SoftIOC" started at: Fri Apr 25 16:43:00 2008
    @@@ 0 user(s) and 0 logger(s) connected (plus you)
.fi
.if n \{\
.RE
.\}
.sp
Type the kill command character ^X to reboot the soft IOC and get server messages about this action\&.
.sp
Type the telnet escape character ^] to get back to a telnet prompt then "quit" to exit telnet (and ssh when you were connecting remotely)\&.
.sp
Though procServ was originally intended to be an environment to run soft IOCs, an arbitrary process might be started as child\&. It provides an environment for any program that requires access to its console, while running in the background as a daemon, and keeping a log by writing a file or through a console access and logging facility (such as conserver)\&.
.SH "ENVIRONMENT VARIABLES"
.PP
\fBPROCSERV_PID\fR
.RS 4
Sets the file name to write the PID of the server process into\&. (See
\fB\-p\fR
option\&.)
.RE
.PP
\fBPROCSERV_DEBUG\fR
.RS 4
If set, procServ starts in debug mode\&. (See
\fB\-d\fR
option\&.)
.RE
.SH "KNOWN PROBLEMS"
.sp
None so far\&.
.SH "REPORTING BUGS"
.sp
Please report bugs using the issue tracker at https://github\&.com/ralphlange/procServ/issues\&.
.SH "AUTHORS"
.sp
Originally written by David H\&. Thompson (ORNL)\&. Current author: Ralph Lange <ralph\&.lange@gmx\&.de>\&.
.SH "RESOURCES"
.sp
GitHub project: https://github\&.com/ralphlange/procServ
.SH "COPYING"
.sp
All copyrights reserved\&. Free use of this software is granted under the terms of the GNU General Public License (GPLv3)\&.