1PROCSERV(1) procServ Manual PROCSERV(1)
2
6 procServ - Process Server with Telnet Console and Log Access
7
9 procServ [OPTIONS] -P endpoint... command args...
10 procServ [OPTIONS] endpoint command args...
12
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 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 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 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 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 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 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 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 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 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 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
86 Both control and log endpoints may be bound to either TCP or UNIX
87 sockets (where supported). Allowed endpoint specifications are:
88 <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 <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 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 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 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
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 --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 --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 -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 -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 -e, --exec=file
156 Run file as executable for child. Default is command.
157 -f, --foreground
159 Keep the server process in the foreground and connected to the
160 controlling terminal.
161 -h, --help
163 Print help message.
164 --holdoff=n
166 Wait at least n seconds between child restart attempts. (Default is
167 15 seconds.)
168 -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 *-I, --info-file <file>
177 Write instance information to this file.
178 -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 --killsig=signal
185 Kill the child using signal when receiving the kill command.
186 Default is 9 (SIGKILL).
187 -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 -L, --logfile=file
195 Write a console log of all in and output to file. - selects
196 stdout.
197 --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 -n, --name=title
204 In all server messages, use title instead of the full command line
205 to increase readability.
206 --noautorestart
208 Do not automatically restart child process on exit.
209 -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 -p, --pidfile=file
217 Write the PID of the server process into file.
218 --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 -q, --quiet
224 Do not write informational output (server). Avoids cluttering the
225 screen when run as part of a system script.
226 --restrict
228 Restrict TCP access (control and log) to connections from
229 localhost.
230 -V, --version
232 Print program version.
233 -w, --wait
235 Do not start the child immediately. Instead, wait for a control
236 connection and a manual start command.
237 -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
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 procServ -n "My SoftIOC" -i ^D^C 20000 ./st.cmd
247 To connect to the IOC, log into the soft IOC’s host and connect to port
249 20000 using
250 telnet localhost 20000
252 To connect from a remote machine, ssh to a user account on procservhost
254 and connect to port 20000 using
255 ssh -t user@procservhost telnet localhost 20000
257 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 > 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 Type the kill command character ^X to reboot the soft IOC and get
278 server messages about this action.
279 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 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
291 PROCSERV_PID
292 Sets the file name to write the PID of the server process into.
293 (See -p option.)
294 PROCSERV_DEBUG
296 If set, procServ starts in debug mode. (See -d option.)
297
299 None so far.
300
302 Please report bugs using the issue tracker at
303 https://github.com/ralphlange/procServ/issues.
304
306 Originally written by David H. Thompson (ORNL). Current author: Ralph
307 Lange <ralph.lange@gmx.de>.
308
310 GitHub project: https://github.com/ralphlange/procServ
311
313 All copyrights reserved. Free use of this software is granted under the
314 terms of the GNU General Public License (GPLv3).
315procServ 2.7.0 01/18/2017 PROCSERV(1)