1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>PROCSERV(1)</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /></head><body><div xml:lang="en" class="article" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="idm1"></a>PROCSERV(1)</h2></div><div><div class="revhistory"><table style="border-style:solid; width:100%;" summary="Revision History"><tr><th align="left" valign="top" colspan="2"><strong>Revision History</strong></th></tr><tr><td align="left">Revision 2.8.0</td><td align="left">06/28/2019</td></tr></table></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="#_name">1. NAME</a></span></dt><dt><span class="section"><a href="#_synopsis">2. SYNOPSIS</a></span></dt><dt><span class="section"><a href="#_description">3. DESCRIPTION</a></span></dt><dt><span class="section"><a href="#_endpoint_specification">4. ENDPOINT SPECIFICATION</a></span></dt><dt><span class="section"><a href="#_options">5. OPTIONS</a></span></dt><dt><span class="section"><a href="#_usage">6. USAGE</a></span></dt><dt><span class="section"><a href="#_environment_variables">7. ENVIRONMENT VARIABLES</a></span></dt><dt><span class="section"><a href="#_known_problems">8. KNOWN PROBLEMS</a></span></dt><dt><span class="section"><a href="#_reporting_bugs">9. REPORTING BUGS</a></span></dt><dt><span class="section"><a href="#_authors">10. AUTHORS</a></span></dt><dt><span class="section"><a href="#_resources">11. RESOURCES</a></span></dt><dt><span class="section"><a href="#_copying">12. COPYING</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_name"></a>1. NAME</h2></div></div></div><p>procServ - Process Server with Telnet Console and Log Access</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_synopsis"></a>2. SYNOPSIS</h2></div></div></div><p><span class="strong"><strong>procServ</strong></span> [<span class="emphasis"><em>OPTIONS</em></span>] -P <span class="emphasis"><em>endpoint</em></span>… <span class="emphasis"><em>command</em></span> <span class="emphasis"><em>args</em></span>…</p><p><span class="strong"><strong>procServ</strong></span> [<span class="emphasis"><em>OPTIONS</em></span>] <span class="emphasis"><em>endpoint</em></span> <span class="emphasis"><em>command</em></span> <span class="emphasis"><em>args</em></span>…</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_description"></a>3. DESCRIPTION</h2></div></div></div><p>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 <span class="emphasis"><em>command</em></span> with all remaining <span class="emphasis"><em>args</em></span> from the command line.
The server provides control access (stdin/stdout) to the child process
console by offering a telnet connection at the specified <span class="emphasis"><em>endpoint</em></span>(s).</p><p>An <span class="emphasis"><em>endpoint</em></span> 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 <span class="strong"><strong>--allow</strong></span> option.)</p><p>The first variant allows multiple <span class="emphasis"><em>endpoint</em></span> declarations and treats all
non-option arguments as the command line for the child process.
The second variant (provided for backward compatibility) declares one
<span class="emphasis"><em>endpoint</em></span> with its specification taken from the first non-option argument.</p><p>procServ can be configured to write a console log of all in- and output of
the child process into a file using the <span class="strong"><strong>-L</strong></span> (<span class="strong"><strong>--logfile</strong></span>) option.
Sending the signal SIGHUP to the server will make it reopen the log file.</p><p>To facilitate running under a central console access management (like
conserver), the <span class="strong"><strong>-l</strong></span> (<span class="strong"><strong>--logport</strong></span>) 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’s console.
The <span class="strong"><strong>-r</strong></span> (<span class="strong"><strong>--restrict</strong></span>) option restricts both control and log access to
connections from localhost.</p><p>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 "<code class="literal">@@@</code>"
to be clearly distinguishable from child process messages.
A name specified by the <span class="strong"><strong>-n</strong></span> (<span class="strong"><strong>--name</strong></span>) option will replace the command
string in many messages for increased readability.</p><p>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 <span class="strong"><strong>--holdoff</strong></span> option).
This behavior can be toggled online using the toggle command <code class="literal">^T</code>, the
default may be changed using the <span class="strong"><strong>--noautorestart</strong></span> option.
You can restart a running child manually by sending a signal to the child
process using the kill command <code class="literal">^X</code>.
With the child process being shut down, the server accepts two commands: <code class="literal">^R</code>
or <code class="literal">^X</code> to restart the child, and <code class="literal">^Q</code> to quit the server.
The <span class="strong"><strong>-w</strong></span> (<span class="strong"><strong>--wait</strong></span>) option starts the server in this shut down mode, waiting
for a control connection to issue a manual start command to spawn the child.</p><p>To facilitate running under system daemon management (systemd/supervisord),
the <span class="strong"><strong>-o</strong></span> (<span class="strong"><strong>--oneshot</strong></span>) 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.</p><p>Any connection (control or log) can be disconnected using the client’s
disconnect sequence. Control connections can also be disconnected by sending
the logout command character that can be specified using the <span class="strong"><strong>-x</strong></span>
(<span class="strong"><strong>--logoutcmd</strong></span>) option.</p><p>To block input characters that are potentially dangerous to the child (e.g.
<code class="literal">^D</code> and <code class="literal">^C</code> on soft IOCs), the <span class="strong"><strong>-i</strong></span> (<span class="strong"><strong>--ignore</strong></span>) option can be used to
specify characters that are silently ignored when coming from a control
connection.</p><p>To facilitate being started and stopped as a standard system service, the
<span class="strong"><strong>-p</strong></span> (<span class="strong"><strong>--pidfile</strong></span>) option tells the server to create a PID file containing
the PID of the server process. The <span class="strong"><strong>-I</strong></span> (<span class="strong"><strong>--info-file</strong></span>) option
writes a file listing the server PID and a list of all endpoints.</p><p>The <span class="strong"><strong>-d</strong></span> (<span class="strong"><strong>--debug</strong></span>) 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.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_endpoint_specification"></a>4. ENDPOINT SPECIFICATION</h2></div></div></div><p>Both control and log endpoints may be bound to either TCP or UNIX sockets
(where supported).
Allowed endpoint specifications are:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<span class="strong"><strong><port></strong></span>
</span></dt><dd>
Bind to either 0.0.0.0:<span class="emphasis"><em><port></em></span> (any) or 127.0.0.1:<span class="emphasis"><em><port></em></span>
(localhost) depending on the type of endpoint and the setting of <span class="strong"><strong>-r</strong></span>
(<span class="strong"><strong>--restrict</strong></span>) and <span class="strong"><strong>--allow</strong></span> options.
</dd><dt><span class="term">
<span class="strong"><strong><ifaceaddr>:<port></strong></span>
</span></dt><dd>
Bind to the specified interface address and <span class="emphasis"><em><port></em></span>. The interface
IP address <span class="emphasis"><em><ifaceaddr></em></span> must be given in numeric form.
Uses 127.0.0.1 (localhost) for security reasons unless the <span class="strong"><strong>--allow</strong></span>
option is also used.
</dd><dt><span class="term">
<span class="strong"><strong>unix:</path/to/socket></strong></span>
</span></dt><dd>
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).
</dd><dt><span class="term">
<span class="strong"><strong>unix:<user>:<group>:<perm>:</path/to/socket></strong></span>
</span></dt><dd>
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 <span class="emphasis"><em><user></em></span> and <span class="emphasis"><em><group></em></span>
with <span class="emphasis"><em><perm></em></span> permissions.
Any of <span class="emphasis"><em><user></em></span>, <span class="emphasis"><em><group></em></span>, and/or <span class="emphasis"><em><perm></em></span> 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".
</dd><dt><span class="term">
<span class="strong"><strong>unix:@</path/to/socket></strong></span>
</span></dt><dd>
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.
</dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_options"></a>5. OPTIONS</h2></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<span class="strong"><strong>--allow</strong></span>
</span></dt><dd>
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’s 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.
</dd><dt><span class="term">
<span class="strong"><strong>--autorestartcmd</strong></span>=<span class="emphasis"><em>char</em></span>
</span></dt><dd>
Toggle auto restart flag when <span class="emphasis"><em>char</em></span> is sent on a control connection.
Use <code class="literal">^</code> to specify a control character, <code class="literal">""</code> to disable. Default is <code class="literal">^T</code>.
</dd><dt><span class="term">
<span class="strong"><strong>--coresize</strong></span>=<span class="emphasis"><em>size</em></span>
</span></dt><dd>
Set the maximum <span class="emphasis"><em>size</em></span> of core file. See getrlimit(2) documentation for
details. Setting <span class="emphasis"><em>size</em></span> to 0 will keep child from creating core files.
</dd><dt><span class="term">
<span class="strong"><strong>-c, --chdir</strong></span>=<span class="emphasis"><em>dir</em></span>
</span></dt><dd>
Change directory to <span class="emphasis"><em>dir</em></span> before starting the child. This is done each
time the child is started to make sure symbolic links are properly
resolved on child restart.
</dd><dt><span class="term">
<span class="strong"><strong>-d, --debug</strong></span>
</span></dt><dd>
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.
</dd><dt><span class="term">
<span class="strong"><strong>-e, --exec</strong></span>=<span class="emphasis"><em>file</em></span>
</span></dt><dd>
Run <span class="emphasis"><em>file</em></span> as executable for child. Default is <span class="emphasis"><em>command</em></span>.
</dd><dt><span class="term">
<span class="strong"><strong>-f, --foreground</strong></span>
</span></dt><dd>
Keep the server process in the foreground and connected to the
controlling terminal.
</dd><dt><span class="term">
<span class="strong"><strong>-h, --help</strong></span>
</span></dt><dd>
Print help message.
</dd><dt><span class="term">
<span class="strong"><strong>--holdoff</strong></span>=<span class="emphasis"><em>n</em></span>
</span></dt><dd>
Wait at least <span class="emphasis"><em>n</em></span> seconds between child restart attempts.
(Default is 15 seconds.)
</dd><dt><span class="term">
<span class="strong"><strong>-i, --ignore</strong></span>=<span class="emphasis"><em>chars</em></span>
</span></dt><dd>
Ignore all characters in <span class="emphasis"><em>chars</em></span> on control connections. This can be used
to shield the child process from input characters that are potentially
dangerous, e.g. <code class="literal">^D</code> and <code class="literal">^C</code> characters that would shut down a soft IOC.
Use <code class="literal">^</code> to specify control characters, <code class="literal">^^</code> to specify a single <code class="literal">^</code>
character.
</dd><dt><span class="term">
*-I, --info-file <file>
</span></dt><dd>
Write instance information to this file.
</dd><dt><span class="term">
<span class="strong"><strong>-k, --killcmd</strong></span>=<span class="emphasis"><em>char</em></span>
</span></dt><dd>
Kill the child process (child will be restarted automatically by default)
when <span class="emphasis"><em>char</em></span> is sent on a control connection. Use <code class="literal">^</code> to specify a control
character, <code class="literal">""</code> for no kill command. Default is <code class="literal">^X</code>.
</dd><dt><span class="term">
<span class="strong"><strong>--killsig</strong></span>=<span class="emphasis"><em>signal</em></span>
</span></dt><dd>
Kill the child using <span class="emphasis"><em>signal</em></span> when receiving the kill command. Default is
9 (SIGKILL).
</dd><dt><span class="term">
<span class="strong"><strong>-l, --logport</strong></span>=<span class="emphasis"><em>endpoint</em></span>
</span></dt><dd>
Provide read-only log access to the child’s console on <span class="emphasis"><em>endpoint</em></span>.
See ENDPOINT SPECIFICATION above.
By default, TCP log endpoints allow connections from anywhere. Use the
<span class="strong"><strong>-r</strong></span> (<span class="strong"><strong>--restrict</strong></span>) option to restrict TCP access to local connections.
</dd><dt><span class="term">
<span class="strong"><strong>-L, --logfile</strong></span>=<span class="emphasis"><em>file</em></span>
</span></dt><dd>
Write a console log of all in and output to <span class="emphasis"><em>file</em></span>. <span class="emphasis"><em>-</em></span> selects stdout.
</dd><dt><span class="term">
<span class="strong"><strong>--logstamp</strong></span>[=<span class="emphasis"><em>fmt</em></span>]
</span></dt><dd>
Prefix lines in logs with a time stamp, setting the time stamp format
string to <span class="emphasis"><em>fmt</em></span>. Default is "[<timefmt>] ". (See <span class="strong"><strong>--timefmt</strong></span> option.)
</dd><dt><span class="term">
<span class="strong"><strong>-n, --name</strong></span>=<span class="emphasis"><em>title</em></span>
</span></dt><dd>
In all server messages, use <span class="emphasis"><em>title</em></span> instead of the full command line to
increase readability.
</dd><dt><span class="term">
<span class="strong"><strong>--noautorestart</strong></span>
</span></dt><dd>
Do not automatically restart child process on exit.
</dd><dt><span class="term">
<span class="strong"><strong>-o, --oneshot</strong></span>
</span></dt><dd>
Once the child process exits, also exit the server.
</dd><dt><span class="term">
<span class="strong"><strong>-P, --port</strong></span>=<span class="emphasis"><em>endpoint</em></span>
</span></dt><dd>
Provide control access to the child’s console on <span class="emphasis"><em>endpoint</em></span>.
See ENDPOINT SPECIFICATION above.
By default, TCP control endpoints are restricted to local connections.
Use the <span class="strong"><strong>--allow</strong></span> option to allow TCP access from anywhere.
</dd><dt><span class="term">
<span class="strong"><strong>-p, --pidfile</strong></span>=<span class="emphasis"><em>file</em></span>
</span></dt><dd>
Write the PID of the server process into <span class="emphasis"><em>file</em></span>.
</dd><dt><span class="term">
<span class="strong"><strong>--timefmt</strong></span>=<span class="emphasis"><em>fmt</em></span>
</span></dt><dd>
Set the format string used to print time stamps to <span class="emphasis"><em>fmt</em></span>. Default is
"%c". (See strftime(3) documentation for details.)
</dd><dt><span class="term">
<span class="strong"><strong>-q, --quiet</strong></span>
</span></dt><dd>
Do not write informational output (server). Avoids cluttering the screen
when run as part of a system script.
</dd><dt><span class="term">
<span class="strong"><strong>--restrict</strong></span>
</span></dt><dd>
Restrict TCP access (control and log) to connections from localhost.
</dd><dt><span class="term">
<span class="strong"><strong>-V, --version</strong></span>
</span></dt><dd>
Print program version.
</dd><dt><span class="term">
<span class="strong"><strong>-w, --wait</strong></span>
</span></dt><dd>
Do not start the child immediately. Instead, wait for a control connection
and a manual start command.
</dd><dt><span class="term">
<span class="strong"><strong>-x, --logoutcmd</strong></span>=<span class="emphasis"><em>char</em></span>
</span></dt><dd>
Log out (close client connection) when <span class="emphasis"><em>char</em></span> is sent on an control
connection. Use <code class="literal">^</code> to specify a control character. Default is empty.
</dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_usage"></a>6. USAGE</h2></div></div></div><p>To start a soft IOC using procServ, change the directory into the IOC’s boot
directory. A typical command line would be</p><pre class="screen"> procServ -n "My SoftIOC" -i ^D^C 20000 ./st.cmd</pre><p>To connect to the IOC, log into the soft IOC’s host and connect to port 20000
using</p><pre class="screen"> telnet localhost 20000</pre><p>To connect from a remote machine, ssh to a user account on procservhost and
connect to port 20000 using</p><pre class="screen"> ssh -t user@procservhost telnet localhost 20000</pre><p>You will be connected to the soft IOCs console and receive an informative
welcome message. All output from the procServ server will start with "<code class="literal">@@@</code>"
to allow telling it apart from messages that your IOC sends.</p><pre class="screen"> > telnet localhost 20000
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
@@@ 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)</pre><p>Type the kill command character <code class="literal">^X</code> to reboot the soft IOC and get server
messages about this action.</p><p>Type the telnet escape character <code class="literal">^]</code> to get back to a telnet prompt then
"<code class="literal">quit</code>" to exit telnet (and ssh when you were connecting remotely).</p><p>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
<code class="literal">conserver</code>).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_environment_variables"></a>7. ENVIRONMENT VARIABLES</h2></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<span class="strong"><strong>PROCSERV_PID</strong></span>
</span></dt><dd>
Sets the file name to write the PID of the server process into.
(See <span class="strong"><strong>-p</strong></span> option.)
</dd><dt><span class="term">
<span class="strong"><strong>PROCSERV_DEBUG</strong></span>
</span></dt><dd>
If set, procServ starts in debug mode. (See <span class="strong"><strong>-d</strong></span> option.)
</dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_known_problems"></a>8. KNOWN PROBLEMS</h2></div></div></div><p>None so far.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_reporting_bugs"></a>9. REPORTING BUGS</h2></div></div></div><p>Please report bugs using the issue tracker at
<a class="ulink" href="https://github.com/ralphlange/procServ/issues" target="_top">https://github.com/ralphlange/procServ/issues</a>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_authors"></a>10. AUTHORS</h2></div></div></div><p>Originally written by David H. Thompson (ORNL).
Current author: Ralph Lange <<a class="ulink" href="mailto:ralph.lange@gmx.de" target="_top">ralph.lange@gmx.de</a>>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_resources"></a>11. RESOURCES</h2></div></div></div><p>GitHub project: <a class="ulink" href="https://github.com/ralphlange/procServ" target="_top">https://github.com/ralphlange/procServ</a></p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_copying"></a>12. COPYING</h2></div></div></div><p>All copyrights reserved.
Free use of this software is granted under the terms of the GNU General
Public License (GPLv3).</p></div></div></body></html>
|
