1PROCSERV(1)                     procServ Manual                    PROCSERV(1)
2
3
4

NAME

6       procServ - Process Server with Telnet Console and Log Access
7

SYNOPSIS

9       procServ [OPTIONS] -P endpoint... command args...
10
11       procServ [OPTIONS] endpoint command args...
12

DESCRIPTION

14       procServ(1) creates a run time environment for a command (e.g. a soft
15       IOC). It forks a server run as a daemon into the background, which
16       creates a child process running command with all remaining args from
17       the command line. The server provides control access (stdin/stdout) to
18       the child process console by offering a telnet connection at the
19       specified endpoint(s).
20
21       An endpoint can either be a TCP server socket (specified by the port
22       number) or a UNIX domain socket (where available). See ENDPOINT
23       SPECIFICATION below for details. For security reasons, control access
24       is restricted to connections from localhost (127.0.0.1), so that a
25       prior login in to the host machine is required. (See --allow option.)
26
27       The first variant allows multiple endpoint declarations and treats all
28       non-option arguments as the command line for the child process. The
29       second variant (provided for backward compatibility) declares one
30       endpoint with its specification taken from the first non-option
31       argument.
32
33       procServ can be configured to write a console log of all in- and output
34       of the child process into a file using the -L (--logfile) option.
35       Sending the signal SIGHUP to the server will make it reopen the log
36       file.
37
38       To facilitate running under a central console access management (like
39       conserver), the -l (--logport) option creates an additional endpoint,
40       which is by default public (i.e. TCP access is not restricted to
41       connections from localhost), and provides read-only (log) access to the
42       child’s console. The -r (--restrict) option restricts both control and
43       log access to connections from localhost.
44
45       Both control and log endpoints allow multiple connections, which are
46       handled transparently: all input from control connections is forwarded
47       to the child process, all output from the child is forwarded to all
48       control and log connections (and written to the log file). All
49       diagnostic messages from the procServ server process start with "@@@"
50       to be clearly distinguishable from child process messages. A name
51       specified by the -n (--name) option will replace the command string in
52       many messages for increased readability.
53
54       The server will by default automatically respawn the child process when
55       it dies. To avoid spinning, a minimum time between child process
56       restarts is honored (default: 15 seconds, can be changed using the
57       --holdoff option). This behavior can be toggled online using the toggle
58       command ^T, the default may be changed using the --noautorestart
59       option. You can restart a running child manually by sending a signal to
60       the child process using the kill command ^X. With the child process
61       being shut down, the server accepts two commands: ^R or ^X to restart
62       the child, and ^Q to quit the server. The -w (--wait) option starts the
63       server in this shut down mode, waiting for a control connection to
64       issue a manual start command to spawn the child.
65
66       Any connection (control or log) can be disconnected using the client’s
67       disconnect sequence. Control connections can also be disconnected by
68       sending the logout command character that can be specified using the -x
69       (--logoutcmd) option.
70
71       To block input characters that are potentially dangerous to the child
72       (e.g. ^D and ^C on soft IOCs), the -i (--ignore) option can be used to
73       specify characters that are silently ignored when coming from a control
74       connection.
75
76       To facilitate being started and stopped as a standard system service,
77       the -p (--pidfile) option tells the server to create a PID file
78       containing the PID of the server process. The -I (--info-file) option
79       writes a file listing the server PID and a list of all endpoints.
80
81       The -d (--debug) option runs the server in debug mode: the daemon
82       process stays in the foreground, printing all regular log content plus
83       additional debug messages to stdout.
84

ENDPOINT SPECIFICATION

86       Both control and log endpoints may be bound to either TCP or UNIX
87       sockets (where supported). Allowed endpoint specifications are:
88
89       <port>
90           Bind to either 0.0.0.0:<port> (any) or 127.0.0.1:<port> (localhost)
91           depending on the type of endpoint and the setting of -r
92           (--restrict) and --allow options.
93
94       <ifaceaddr>:<port>
95           Bind to the specified interface address and <port>. The interface
96           IP address <ifaceaddr> must be given in numeric form. Uses
97           127.0.0.1 (localhost) for security reasons unless the --allow
98           option is also used.
99
100       unix:</path/to/socket>
101           Bind to a named unix domain socket that will be created at the
102           specified absolute or relative path. The server process must have
103           permission to create files in the enclosing directory. The socket
104           file will be owned by the uid and primary gid of the procServ
105           server process with permissions 0666 (equivalent to a TCP socket
106           bound to localhost).
107
108       unix:<user>:<group>:<perm>:</path/to/socket>
109           Bind to a named unix domain socket that will be created at the
110           specified absolute or relative path. The server process must have
111           permission to create files in the enclosing directory. The socket
112           file will be owned by the specified <user> and <group> with <perm>
113           permissions. Any of <user>, <group>, and/or <perm> may be omitted.
114           E.g. "-P unix::grp:0660:/run/procServ/foo/control" will create the
115           named socket with 0660 permissions and allow the "grp" group
116           connect to it. This requires that procServ be run as root or a
117           member of "grp".
118
119       unix:@</path/to/socket>
120           Bind to an abstract unix domain socket (Linux specific). Abstract
121           sockets do not exist on the filesystem, and have no permissions
122           checks. They are functionally similar to a TCP socket bound to
123           localhost, but identified with a name string instead of a port
124           number.
125

OPTIONS

127       --allow
128           Allow TCP control connections from anywhere. (Default: restrict
129           control access to connections from localhost.) Creates a serious
130           security hole, as telnet clients from anywhere can connect to the
131           child’s stdin/stdout and might execute arbitrary commands on the
132           host if the child permits. Needs to be enabled at compile-time (see
133           Makefile). Please do not enable and use this option unless you
134           exactly know why and what you are doing.
135
136       --autorestartcmd=char
137           Toggle auto restart flag when char is sent on a control connection.
138           Use ^ to specify a control character, "" to disable. Default is ^T.
139
140       --coresize=size
141           Set the maximum size of core file. See getrlimit(2) documentation
142           for details. Setting size to 0 will keep child from creating core
143           files.
144
145       -c, --chdir=dir
146           Change directory to dir before starting the child. This is done
147           each time the child is started to make sure symbolic links are
148           properly resolved on child restart.
149
150       -d, --debug
151           Enter debug mode. Debug mode will keep the server process in the
152           foreground and enables diagnostic messages that will be sent to the
153           controlling terminal.
154
155       -e, --exec=file
156           Run file as executable for child. Default is command.
157
158       -f, --foreground
159           Keep the server process in the foreground and connected to the
160           controlling terminal.
161
162       -h, --help
163           Print help message.
164
165       --holdoff=n
166           Wait at least n seconds between child restart attempts. (Default is
167           15 seconds.)
168
169       -i, --ignore=chars
170           Ignore all characters in chars on control connections. This can be
171           used to shield the child process from input characters that are
172           potentially dangerous, e.g.  ^D and ^C characters that would shut
173           down a soft IOC. Use ^ to specify control characters, ^^ to specify
174           a single ^ character.
175
176       *-I, --info-file <file>
177           Write instance information to this file.
178
179       -k, --killcmd=char
180           Kill the child process (child will be restarted automatically by
181           default) when char is sent on a control connection. Use ^ to
182           specify a control character, "" for no kill command. Default is ^X.
183
184       --killsig=signal
185           Kill the child using signal when receiving the kill command.
186           Default is 9 (SIGKILL).
187
188       -l, --logport=endpoint
189           Provide read-only log access to the child’s console on endpoint.
190           See ENDPOINT SPECIFICATION above. By default, TCP log endpoints
191           allow connections from anywhere. Use the -r (--restrict) option to
192           restrict TCP access to local connections.
193
194       -L, --logfile=file
195           Write a console log of all in and output to file.  - selects
196           stdout.
197
198       --logstamp[=fmt]
199           Prefix lines in logs with a time stamp, setting the time stamp
200           format string to fmt. Default is "[<timefmt>] ". (See --timefmt
201           option.)
202
203       -n, --name=title
204           In all server messages, use title instead of the full command line
205           to increase readability.
206
207       --noautorestart
208           Do not automatically restart child process on exit.
209
210       -P, --port=endpoint
211           Provide control access to the child’s console on endpoint. See
212           ENDPOINT SPECIFICATION above. By default, TCP control endpoints are
213           restricted to local connections. Use the --allow option to allow
214           TCP access from anywhere.
215
216       -p, --pidfile=file
217           Write the PID of the server process into file.
218
219       --timefmt=fmt
220           Set the format string used to print time stamps to fmt. Default is
221           "%c". (See strftime(3) documentation for details.)
222
223       -q, --quiet
224           Do not write informational output (server). Avoids cluttering the
225           screen when run as part of a system script.
226
227       --restrict
228           Restrict TCP access (control and log) to connections from
229           localhost.
230
231       -V, --version
232           Print program version.
233
234       -w, --wait
235           Do not start the child immediately. Instead, wait for a control
236           connection and a manual start command.
237
238       -x, --logoutcmd=char
239           Log out (close client connection) when char is sent on an control
240           connection. Use ^ to specify a control character. Default is empty.
241

USAGE

243       To start a soft IOC using procServ, change the directory into the IOC’s
244       boot directory. A typical command line would be
245
246               procServ -n "My SoftIOC" -i ^D^C 20000 ./st.cmd
247
248       To connect to the IOC, log into the soft IOC’s host and connect to port
249       20000 using
250
251               telnet localhost 20000
252
253       To connect from a remote machine, ssh to a user account on procservhost
254       and connect to port 20000 using
255
256               ssh -t user@procservhost telnet localhost 20000
257
258       You will be connected to the soft IOCs console and receive an
259       informative welcome message. All output from the procServ server will
260       start with "@@@" to allow telling it apart from messages that your IOC
261       sends.
262
263               > telnet localhost 20000
264               Trying 127.0.0.1...
265               Connected to localhost.
266               Escape character is '^]'.
267               @@@ Welcome to the procServ process server (procServ Version 2.1.0)
268               @@@ Use ^X to kill the child, auto restart is ON, use ^T to toggle auto restart
269               @@@ procServ server PID: 21413
270               @@@ Startup directory: /projects/ctl/lange/epics/ioc/test314/iocBoot/iocexample
271               @@@ Child "My SoftIOC" started as: ./st.cmd
272               @@@ Child "My SoftIOC" PID: 21414
273               @@@ procServ server started at: Fri Apr 25 16:43:00 2008
274               @@@ Child "My SoftIOC" started at: Fri Apr 25 16:43:00 2008
275               @@@ 0 user(s) and 0 logger(s) connected (plus you)
276
277       Type the kill command character ^X to reboot the soft IOC and get
278       server messages about this action.
279
280       Type the telnet escape character ^] to get back to a telnet prompt then
281       "quit" to exit telnet (and ssh when you were connecting remotely).
282
283       Though procServ was originally intended to be an environment to run
284       soft IOCs, an arbitrary process might be started as child. It provides
285       an environment for any program that requires access to its console,
286       while running in the background as a daemon, and keeping a log by
287       writing a file or through a console access and logging facility (such
288       as conserver).
289

ENVIRONMENT VARIABLES

291       PROCSERV_PID
292           Sets the file name to write the PID of the server process into.
293           (See -p option.)
294
295       PROCSERV_DEBUG
296           If set, procServ starts in debug mode. (See -d option.)
297

KNOWN PROBLEMS

299       None so far.
300

REPORTING BUGS

302       Please report bugs using the issue tracker at
303       https://github.com/ralphlange/procServ/issues.
304

AUTHORS

306       Originally written by David H. Thompson (ORNL). Current author: Ralph
307       Lange <ralph.lange@gmx.de>.
308

RESOURCES

310       GitHub project: https://github.com/ralphlange/procServ
311

COPYING

313       All copyrights reserved. Free use of this software is granted under the
314       terms of the GNU General Public License (GPLv3).
315
316
317
318procServ 2.7.0                    01/18/2017                       PROCSERV(1)
Impressum