~ubuntu-branches/ubuntu/oneiric/procserv/oneiric

.\"     Title: procserv

.\"    Author: 

.\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>

.\"      Date: 12/02/2009

.\"    Manual: procServ Manual

.\"    Source: procServ 2.5.0

.\"

.TH "PROCSERV" "1" "12/02/2009" "procServ 2\&.5\&.0" "procServ Manual"

.\" disable hyphenation

.nh

.\" disable justification (adjust text to left margin only)

.ad l

.SH "NAME"

procServ \- Process Server with Telnet Console and Log Access

.SH "SYNOPSIS"

\fBprocServ\fR [\fIOPTIONS\fR] \fIport\fR \fIcommand\fR \fIargs\&...\fR

.sp

.SH "DESCRIPTION"

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 console access (stdin/stdout) to the child process by offering a telnet connection at the specified port\&. For security reasons, access is restricted to connections from localhost (127\&.0\&.0\&.1), so that logging into a valid account on the host machine is required\&.

.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\&. To facilitate running under a central console access management (like conserver), the \fB\-l\fR (\fB\-\-logport\fR) option creates an additional telnet port, which is by default public (i\&.e\&. not restricted to localhost), and provides read\-only log access to the child\'s console\&. The \fB\-r\fR (\fB\-\-restrict\fR) option restricts the log port to localhost, similar to the access port\&.

.sp

Both access and log ports allow multiple connections, which are handled transparently: all input from access connections is forwarded to the child process, all output from the child is forwarded to all access and log connections (and written to the log file)\&. All diagnostic messages from the server process start with "@@@ " to be clearly distinguished 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 a child process when it dies\&. To avoid spinning, a minimum time between child process restarts is honoured (default: 15 seconds, can be changed using the \fB\-\-holdoff\fR option)\&. This behaviour 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 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 the telnet connection to issue a manual start command to create the child\&.

.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 console access port\&.

.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 standard PID file containing the PID of the server process\&.

.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\&.

.sp

.SH "OPTIONS"

.PP

\fB\-\-allow\fR

.RS 4

Allow control connections from anywhere\&. (Default: restrict control access to localhost\&.) Creates a serious security hole, as telnet clients from anywhere can connect to the child\'s stdin/stdout and 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 an access 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 child\&. This is done each time the child is started to make sure symbolic links are 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\-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 access 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

\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 an access 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=\fIport\fR

.RS 4

Provide read\-only access to the child\'s console on

\fIport\fR\&. By default all hosts can connect to

\fIport\fR, use the

\fB\-r\fR

(\fB\-\-restrict\fR) option to restrict access to localhost\&.

.RE

.PP

\fB\-L, \-\-logfile\fR=\fIfile\fR

.RS 4

Write a console log of all in\- and output to

\fIfile\fR\&.

.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\-p, \-\-pidfile\fR=\fIfile\fR

.RS 4

Write the PID of the server process into

\fIfile\fR

to facilitate integration into regular system service administration mechanisms\&.

.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 log connections to 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\&. Instead, wait for a telnet connection and a manual start command\&.

.RE

.SH "USAGE"

To start a soft IOC using procServ, change the directory into the IOC\'s boot directory\&. A typical command line would be

.sp

.sp

.RS 4

.nf

    procServ \-n "My SoftIOC" \-i ^D^C 20000 \&./st\&.cmd

.fi

.RE

To connect to the IOC, log into the soft IOC\'s host and connect to port 20000 using

.sp

.sp

.RS 4

.nf

    telnet localhost 20000

.fi

.RE

To connect from a remote machine, ssh to a user account on procservhost and connect to port 20000 using

.sp

.sp

.RS 4

.nf

    ssh \-t user@procservhost telnet localhost 20000

.fi

.RE

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

.sp

.RS 4

.nf

    > 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)

.fi

.RE

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 and quit to exit telnet (and ssh when you were connecting remotely)\&.

.sp

While procServ was originally intended to be an environment to run soft IOCs, any process might be started as child\&. It provides an environment for any program that requires access to its console and should be run in the background as a daemon\&. By writing a file log directly or through a console access and logging facility (such as conserver), the log of such a program\'s output can be used to correlate its messages to other events\&. E\&.g\&., in an EPICS environment, running casw (the beacon anomaly watcher) can provide useful log output to analyse and track down network issues (name resolution broadcast storms)\&.

.sp

.SH "ENVIRONMENT VARIABLES"

.PP

\fBPROCSERV_PID\fR

.RS 4

This 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"

None so far\&.

.sp

.SH "REPORTING BUGS"

Report bugs on the procServ Trac at http://sourceforge\&.net/apps/trac/procserv/ or to the authors\&.

.sp

.SH "AUTHORS"

Written by David H\&. Thompson <thompsondh@ornl\&.gov> and Ralph Lange <Ralph\&.Lange@bessy\&.de>\&.

.sp

.SH "RESOURCES"

SourceForge project: http://sourceforge\&.net/projects/procserv/

.sp

.SH "COPYING"

All copyrights reserved\&. Free use of this software is granted under the terms of the GNU General Public License (GPLv3)\&.

.sp

.SH "NOTES"

.IP " 1." 4

thompsondh@ornl.gov

.RS 4

\%mailto:thompsondh@ornl.gov

.RE

.IP " 2." 4

Ralph.Lange@bessy.de

.RS 4

\%mailto:Ralph.Lange@bessy.de

.RE